biggus-dickus/docs/superpowers/specs/2026-06-04-frontend-spa-milestone-3-design.md

# Frontend SPA — Milestone 3 (Publishing Workflow) — Design

**Date:** 2026-06-04
**Status:** Approved (brainstorming) — ready for implementation planning.

## Context

Milestones 1–2 (merged to `main` at `bb05331`) delivered the SPA foundation, the
read-only two-pane Objects screen, and full object authoring (create/edit/delete +
the dynamic flexible-field form). Milestone 3 adds the **publishing workflow** — driving
a record through the stepwise `Draft → Internal → Public` visibility pipeline.

This is **pure frontend**: the backend `POST /api/admin/objects/{id}/visibility`
endpoint and the stepwise state machine already exist (the publish gate was added under
issue #16).

Milestone roadmap: M1 foundation → M2 authoring → **M3 publish workflow (this)** → M4
vocabulary/authority management → M5 search.

## Decisions (settled during brainstorming)

- **Publish control = a segmented stepper** (Draft → Internal → Public) on the object
  **detail read view**, with the current stage highlighted; it offers only **legal
  one-step** moves (forward/back).
- **Confirm only on → Public** (an `AlertDialog`, reusing the M2 shadcn one), since
  publishing makes the record externally visible; all other steps fire immediately.
- The **422 publish-gate** failure shows a generic inline message + an Edit link (the
  backend 422 is bare; per-field detail is deferred to issue #28).
- Keep the existing `VisibilityBadge` in the detail header alongside the new stepper.

## Backend contract (already shipped — verify against `web/src/api/schema.d.ts`)

- `POST /api/admin/objects/{id}/visibility` body `VisibilityRequest { visibility }` →
  `204` on success; `404` if the object is missing; `409` on an illegal transition
  (skipping a step); `422` if publishing to Public with required fields missing (the
  publish gate). The 422 body is **bare** (no per-field detail).
- **State machine** (`domain::Visibility::can_transition_to`): legal moves are
  `Draft↔Internal` and `Internal↔Public` (one step each). `Draft→Public` and
  `Public→Draft` are illegal. Setting to the current value is a no-op (allowed).
- The publish **gate** (422) fires only on a transition **into Public**
  (`Internal → Public`). Backward/internal moves have no gate.

## Scope (YAGNI)

**In:** the `PublishControl` stepper on the object detail; `useSetVisibility` mutation;
the `adjacentTransitions` helper; confirm-on-→Public; inline surfacing of the 422 gate
(with an Edit link) and the 409 illegal-transition (defensive); cache invalidation so
the badge/stepper refresh after a transition.

**Out:** per-field gate detail (bare 422 → generic message, tracked by #28); visibility
controls in the edit form (visibility stays separate from core/flexible editing, per
the M2 design); vocabulary/authority management (M4); search (M5).

## Architecture

### Transition adjacency (pure helper)

`web/src/objects/transitions.ts`:

```ts
export type Visibility = "draft" | "internal" | "public";

/** The legal one-step moves from a given visibility, per the backend state machine. */
export function adjacentTransitions(v: Visibility): { forward?: Visibility; back?: Visibility } {
  switch (v) {
    case "draft":    return { forward: "internal" };
    case "internal": return { forward: "public", back: "draft" };
    case "public":   return { back: "internal" };
  }
}
```

- `forward` to `public` is the only move that is gated + confirmed.
- Unit-tested in isolation (all three states).

### Data layer

`web/src/api/queries.ts` + `useSetVisibility`:

- `POST /api/admin/objects/{id}/visibility` with `{ visibility }`.
- On non-`204`, throw an error that carries the **status** so the UI can distinguish:
  `409` (illegal), `422` (gate), other. (e.g. `throw Object.assign(new Error("visibility"), { status })`, or a small typed error class.)
- `onSuccess`: invalidate `["object", id]` and `["objects"]`.

### Component — `web/src/objects/publish-control.tsx`

`PublishControl({ object })`:

- Reads `object.visibility` and computes `adjacentTransitions`.
- Renders a **3-segment stepper** (Draft / Internal / Public): segments before the
  current = "done", current = highlighted, after = pending.
- Renders the legal step buttons with contextual labels:
  - forward to Internal → "Advance to internal" (or "→ Internal")
  - forward to Public → "Publish →" (opens the confirm dialog)
  - back to Draft → "← Back to draft"
  - back to Internal → "Unpublish to internal"
- **Confirm on → Public:** clicking "Publish →" opens an `AlertDialog`
  ("This will make the record publicly visible…") with Cancel + a confirm Action that
  fires `useSetVisibility.mutate({ id, visibility: "public" })`. All other buttons fire
  the mutation immediately.
- **Mutation states:** while pending, disable the buttons. On error, branch on
  `error.status`:
  - `422` → inline message "Can't publish — required fields are missing." + a
    `<Link to={/objects/:id/edit}>` Edit link.
  - `409` → inline "That visibility change isn't allowed." (defensive; the UI only
    offers legal steps).
  - other → the generic `form.rejected` message.
- On success, query invalidation refreshes the object → the stepper + the header
  `VisibilityBadge` reflect the new state automatically.

Rendered in `object-detail.tsx` as a new section below the header. The existing
`VisibilityBadge` remains in the header.

## Error handling

| Outcome | UI |
|---|---|
| `204` | invalidate → stepper + badge update to the new state |
| `422` (gate, only on →Public) | inline error + Edit link; state unchanged |
| `409` (illegal) | inline error (defensive) |
| pending | step buttons disabled |
| `404` | (object already absent) generic error; the detail itself would 404 on reload |

## Testing (Vitest + RTL + MSW)

- `transitions.test.ts` — `adjacentTransitions` for draft/internal/public.
- `publish-control.test.tsx`:
  - Stepper renders the current stage highlighted.
  - Draft → only a forward (Internal) button, no back.
  - Internal → forward (Publish) + back (Draft) buttons.
  - Public → only a back (Internal) button.
  - Draft → Internal: clicking forward POSTs `visibility=internal` (204) — assert the
    request body; success path.
  - Internal → Public: clicking "Publish →" opens the confirm dialog; confirming POSTs
    `visibility=public`.
  - **Gate:** POST `visibility=public` → `422` → inline gate error + Edit link visible;
    no navigation.
  - Public → Internal: clicking back POSTs `visibility=internal` immediately (no
    confirm dialog).
- MSW: a configurable `POST /api/admin/objects/:id/visibility` handler (default 204;
  per-test overrides for 422/409).

## Acceptance criteria (Milestone 3 "done")

1. The object detail shows a Draft→Internal→Public stepper with the current stage
   highlighted and only legal one-step buttons.
2. Advancing/retracting a step (except →Public) immediately POSTs the new visibility and
   the badge/stepper update.
3. Publishing to Public requires a confirmation; confirming POSTs `visibility=public`.
4. A publish-gate failure (422) shows an inline "required fields missing" message + an
   Edit link, leaving the record unchanged.
5. The UI never offers an illegal (skip) transition; a 409 is handled defensively.
6. Web CI green (typecheck, lint, tests, build, bundle ≤150 KB gz).

## Out of scope / follow-ups

- Per-field publish-gate detail requires the backend 422 to carry field info (#28).
- Audit/history view of visibility changes (a later milestone; the backend already
  audits transitions).
- A public-facing collection site is post-MVP (the public read API exists; no UI here).