From 900fba5af6eb1b62e447ad379e7e7bdc7503b174 Mon Sep 17 00:00:00 2001
From: hsiegeln <37154749+hsiegeln@users.noreply.github.com>
Date: Thu, 23 Apr 2026 15:36:57 +0200
Subject: [PATCH] docs(spec): deployment page polish (upload-in-button,
 sort/refresh, collapsible checkpoints, DS Select, tab reorder)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 ...026-04-23-deployment-page-polish-design.md | 190 ++++++++++++++++++
 1 file changed, 190 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-04-23-deployment-page-polish-design.md

diff --git a/docs/superpowers/specs/2026-04-23-deployment-page-polish-design.md b/docs/superpowers/specs/2026-04-23-deployment-page-polish-design.md
new file mode 100644
index 00000000..daec6c16
--- /dev/null
+++ b/docs/superpowers/specs/2026-04-23-deployment-page-polish-design.md
@@ -0,0 +1,190 @@
+# Deployment page polish — design
+
+**Date:** 2026-04-23
+**Scope:** six targeted UX improvements on the unified deployment page (`ui/src/pages/AppsTab/AppDeploymentPage/*`)
+**Status:** Draft — pending user review
+
+## 1. Motivation
+
+The unified deployment page landed recently. Exercising it surfaced six rough edges:
+
+1. No feedback during JAR upload — user clicks `Save` or `Redeploy`, the button spins, nothing happens visually until the upload finishes. On large JARs this feels broken.
+2. Startup logs are fixed ascending with no way to see the newest line first and no manual refresh between polls.
+3. The checkpoints table is always visible, pushing the config tabs far down even when the user doesn't care about history right now.
+4. The replica dropdown in the checkpoint drawer uses a raw `<select>`, visually out of place vs. the rest of the design system.
+5. The drawer opens on `Logs` — but `Config` is the restore-decision content. Users currently always click over.
+6. (Shipped as `b3d1dd37`.) The "No past deployments yet." empty-state hint was noise — removed.
+
+This spec covers changes 1–5. #6 is listed for completeness only.
+
+## 2. Design
+
+### 2.1 Upload progress inside the primary action button
+
+**Rationale.** Putting upload progress inside the button the user just clicked keeps all state-machine feedback in a single locus. The button already advertises the active action (`Save` → `Redeploy` → `Deploying…`); adding `Uploading…` is a natural extension.
+
+**State machine.**
+
+```
+PrimaryActionMode: 'save' | 'redeploy' | 'uploading' | 'deploying'
+```
+
+- `save` — config dirty, no active deploy, no active upload
+- `redeploy` — server dirty against last deploy, no active upload, no active deploy
+- `uploading` — a JAR upload is in flight (applies during both Save and Redeploy paths)
+- `deploying` — a deployment row exists with status `STARTING`
+
+**Progress propagation.**
+
+- `useUploadJar` switches from `fetch()` to `XMLHttpRequest`. Fetch gives no upload-progress events; XHR's `upload.onprogress` does.
+- `useUploadJar` mutation args gain `onProgress?: (pct: number) => void`.
+- `AppDeploymentPage` holds `const [uploadPct, setUploadPct] = useState<number | null>(null)`. `handleSave` and `handleRedeploy` pass `onProgress: setUploadPct` into the mutation and clear to `null` in a `finally` block.
+- `computeMode` learns a new input `uploading: boolean` (derived from `uploadPct !== null`). Order: `deploying` > `uploading` > `save|redeploy` choice.
+- `PrimaryActionButton` gains an optional `progress?: number` prop and renders a progress overlay when `mode === 'uploading'`.
+
+**Button visual during `uploading`.**
+
+- Label: `Uploading… 42%` (rounded integer).
+- Disabled (same UX as `deploying`).
+- A tinted-primary fill grows from left to right behind the label. Implementation: wrap the DS `Button` children in a positioned container with an inner `<div>` whose `width: ${pct}%` and background is a translucent primary tint (via `color-mix(in srgb, var(--primary) 30%, transparent)` or equivalent CSS variable). Keeps DS `Button` unmodified.
+
+**Edge cases.**
+
+- Upload fails → `onProgress` stops, the XHR error rejects the mutation, existing `catch` block surfaces the toast, `uploadPct` is cleared in `finally`, button returns to whichever mode `computeMode` picks.
+- User navigates away mid-upload → the unsaved-changes blocker already exists and challenges the navigation. Cancellation semantics (whether to `xhr.abort()` when the mutation is superseded) are handled by the mutation's own lifecycle — out of scope for this change.
+- No staged JAR (redeploy-only) → `uploadPct` stays `null`, mode goes `redeploy` → `deploying` with no `uploading` in between (unchanged from today).
+
+### 2.2 Startup log panel — sort + manual refresh
+
+**Layout.** Mirror the Application Log panel in `AgentHealth.tsx:899-917`:
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│ STARTUP LOGS  ● live  polling every 3s    42 entries  ↓  ↻   │
+└──────────────────────────────────────────────────────────────┘
+│ <LogViewer entries...>                                        │
+└──────────────────────────────────────────────────────────────┘
+```
+
+- Reuse `ui/src/styles/log-panel.module.css` (`logCard`, `logHeader`, `headerActions`).
+- Sort toggle: DS `Button variant="ghost" size="sm"` with unicode arrow (`↓` desc / `↑` asc). `title` prop: `"Newest first"` / `"Oldest first"`.
+- Refresh: DS `Button variant="ghost" size="sm"` wrapping `<RefreshCw size={14} />` from `lucide-react`. `title="Refresh"`.
+
+**Sort semantics.**
+
+- Default sort is **desc** (newest first). User's pain point is that the interesting lines are the most recent ones.
+- `useStartupLogs` signature extends to:
+  ```ts
+  useStartupLogs(application, environment, deployCreatedAt, isStarting, sort: 'asc' | 'desc')
+  ```
+- `sort` is passed straight into `LogSearchParams` so the **backend** fetch respects it. Limit remains 500. The 500-line cap applies from the sort direction, so desc gets the latest 500 and asc gets the oldest 500. (Pre-existing limitation; not addressed here.)
+- Display direction matches fetch direction — `LogViewer` is passed whatever order the server returns.
+
+**Refresh behavior.**
+
+- Calls the TanStack Query `refetch()`.
+- After the refetch resolves, scroll the panel's content container to the "latest" edge:
+  - `sort === 'asc'` → scroll to bottom (newest is at the bottom).
+  - `sort === 'desc'` → scroll to top (newest is at the top).
+- Requires a `useRef<HTMLDivElement>` on a new scroll wrapper around `LogViewer` inside `StartupLogPanel`. `LogViewer` itself does not forward a scroll ref — confirmed in DS `index.es.d.ts` — so we add a wrapping `<div ref={scrollRef} className={...}>` with `overflow: auto` and call `scrollRef.current.scrollTo({ top, behavior: 'smooth' })` after the refetch resolves.
+
+**Polling behavior unchanged.** 3-second polling while `isStarting` still happens via `refetchInterval`. Manual refresh is orthogonal.
+
+### 2.3 Checkpoints table collapsible, default collapsed
+
+**Rationale.** Deployments happen infrequently; when the user is on this page, they're usually tuning *current* config, not reviewing history. Collapsing by default reclaims vertical space for the config tabs.
+
+**Behavior.**
+
+- `CheckpointsTable` renders a clickable header row **above** the table body:
+  ```
+  ▸ Checkpoints (7)        ← collapsed (default)
+  ▾ Checkpoints (7)        ← expanded
+  ```
+- Chevron and label are part of the same `<button>` (keyboard-accessible). No separate icon component needed — unicode `▸`/`▾` match the existing codebase style.
+- Local component state: `const [open, setOpen] = useState(false)`.
+- When `open === false`, the `<table>` and the "Show older" expander are not rendered — only the header row.
+- The existing "no checkpoints" early-return (`null`) is preserved — no header row at all when there's nothing to show.
+
+**Styling.** New `.checkpointsHeader` class in `AppDeploymentPage.module.css`:
+- Same horizontal padding as the table cells, small gap between chevron and label, subdued color on hover.
+- Muted count `(N)` in `var(--text-muted)`.
+
+### 2.4 Replica dropdown uses DS Select
+
+**Change.** In `CheckpointDetailDrawer/LogsPanel.tsx:36-47`, replace the native `<select>` with `Select` from `@cameleer/design-system`.
+
+```tsx
+<Select
+  value={String(replicaFilter)}
+  onChange={(e) => {
+    const v = e.target.value;
+    setReplicaFilter(v === 'all' ? 'all' : Number(v));
+  }}
+  options={[
+    { value: 'all', label: `all (${deployment.replicaStates.length})` },
+    ...deployment.replicaStates.map((_, i) => ({ value: String(i), label: String(i) })),
+  ]}
+/>
+```
+
+- Label stays `Replica:` as a sibling element (DS `Select` doesn't include an inline label slot).
+- No behavior change beyond styling.
+
+### 2.5 Drawer tabs — Config first, default Config
+
+**Change.** In `CheckpointDetailDrawer/index.tsx`:
+
+- Reverse the `tabs` array in the `<Tabs>` call so `Config` precedes `Logs`.
+- Change the initial tab state from `useState<TabId>('logs')` to `useState<TabId>('config')`.
+
+Rationale: `Config` is the restore-decision content (what variables, what resources, what monitoring settings did this checkpoint have). `Logs` is supporting/post-mortem material. The first tab should be the one users land on for the default question.
+
+## 3. Files to touch
+
+| File | Change |
+|------|--------|
+| `ui/src/pages/AppsTab/AppDeploymentPage/PrimaryActionButton.tsx` | Add `'uploading'` mode + `progress` prop; `computeMode` takes `uploading` input |
+| `ui/src/pages/AppsTab/AppDeploymentPage/AppDeploymentPage.module.css` | `.checkpointsHeader`; progress-overlay styles for the primary button |
+| `ui/src/pages/AppsTab/AppDeploymentPage/index.tsx` | `uploadPct` state; pass `onProgress` into both upload call sites |
+| `ui/src/api/queries/admin/apps.ts` | `useUploadJar` → XHR; `onProgress` mutation arg |
+| `ui/src/components/StartupLogPanel.tsx` | Header layout rewrite; sort state; refresh handler; scroll ref |
+| `ui/src/components/StartupLogPanel.module.css` | Header-action styles if not covered by shared `log-panel.module.css` |
+| `ui/src/api/queries/logs.ts` | `useStartupLogs` adds `sort` parameter |
+| `ui/src/pages/AppsTab/AppDeploymentPage/CheckpointsTable.tsx` | Collapse state + header row |
+| `ui/src/pages/AppsTab/AppDeploymentPage/CheckpointDetailDrawer/LogsPanel.tsx` | DS `Select` for replica filter |
+| `ui/src/pages/AppsTab/AppDeploymentPage/CheckpointDetailDrawer/index.tsx` | Tab reorder + default `'config'` |
+
+## 4. Testing
+
+**Unit.**
+
+- `useUploadJar` — mock XHR, assert `onProgress` fires during `upload.onprogress`, resolves on 2xx, rejects on non-2xx and on `xhr.onerror`.
+- `CheckpointsTable` — collapse toggle: header-only when collapsed, full table visible when open; count in header matches `checkpoints.length`.
+- `StartupLogPanel` — sort toggle flips the query sort parameter; refresh calls `refetch` and calls `scrollTo` on the right end per sort direction.
+
+**Component rendering.**
+
+- `PrimaryActionButton` — renders `Uploading… 42%` in `'uploading'` mode with the overlay element width bound to `progress`.
+
+**Manual smoke.**
+
+- Save-with-JAR: button transitions `Save` → `Uploading…` → back to whatever the post-save mode is.
+- Redeploy-with-JAR: button transitions `Redeploy` → `Uploading…` → `Deploying…`.
+- Redeploy-only (no staged JAR): button transitions `Redeploy` → `Deploying…` (no `Uploading…`).
+- Upload fails (simulate 500 from backend): button returns to pre-click mode; error toast shown.
+- Startup logs: flip sort; refresh; confirm latest line is visible in each direction.
+- Checkpoints: collapsed on load; expanding shows the 10-row table + "Show older" expander if applicable.
+- Drawer: open it → lands on `Config`; switching to `Logs` works; replica filter looks like DS components.
+
+## 5. Non-goals
+
+- No change to the startup-logs backend endpoint; the 500-line cap and 3s polling stay.
+- No change to the checkpoint drawer's footer (`Restore` button), header, or meta line.
+- No change to deployment creation, stop, or delete flows.
+- No new test-infra scaffolding (XHR mocking uses what's already in Vitest).
+- Already-shipped: the empty-checkpoints `null` return (commit `b3d1dd37`) — not touched again.
+
+## 6. Open questions
+
+None — all decisions resolved during brainstorming.