From e54ea89b1ef201fad63468de57a8a3c8bc54ce61 Mon Sep 17 00:00:00 2001
From: Anders Olsson <anders.e.olsson@gmail.com>
Date: Mon, 8 Jun 2026 05:50:00 +0200
Subject: [PATCH] =?UTF-8?q?docs(plans):=20token-styled=20select=20?=
 =?UTF-8?q?=E2=80=94=203-task=20plan=20(#51)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../plans/2026-06-08-token-select.md          | 288 ++++++++++++++++++
 1 file changed, 288 insertions(+)
 create mode 100644 docs/superpowers/plans/2026-06-08-token-select.md

diff --git a/docs/superpowers/plans/2026-06-08-token-select.md b/docs/superpowers/plans/2026-06-08-token-select.md
new file mode 100644
index 0000000..d552464
--- /dev/null
+++ b/docs/superpowers/plans/2026-06-08-token-select.md
@@ -0,0 +1,288 @@
+# Token-Styled Select Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Replace the four raw `<select>` elements with a token-styled `ui/Select` (Base UI Select) that matches `ui/Input` and has a visible focus ring.
+
+**Architecture:** A new `ui/select.tsx` wraps Base UI Select (Portal+Positioner+Popup) styled like Input. `object-form` visibility moves to a react-hook-form `Controller`; `field-form`'s three selects use `value`/`onValueChange` directly. Base UI Select is not a native `<select>`, so the affected tests are rewritten from `userEvent.selectOptions` to open-trigger + click-option.
+
+**Tech Stack:** React 19 + TS + pnpm, Base UI (`@base-ui/react/select`, namespace `Select`), react-hook-form (object-form), lucide-react (Chevron/Check), Vitest + RTL + Storybook. Test runner: `pnpm test` (single pass).
+
+**Conventions:** pnpm; **no `any`/`eslint-disable`/`@ts-ignore`**; no codename; en/sv parity (no new keys expected); **ui/ files = no-semicolon** (match `ui/combobox.tsx`/`ui/menu.tsx`); app source = double-quote+semicolon; stories single-quote/no-semicolon; token classes only; this repo enforces `react-hooks/refs` + `react-refresh/only-export-components` — refactor cleanly, never disable.
+
+**Spec:** `docs/superpowers/specs/2026-06-08-token-select-design.md`
+
+**Key facts:**
+- Base UI: `import { Select as SelectPrimitive } from "@base-ui/react/select"` — parts `Root, Trigger, Value, Icon, Portal, Positioner, Popup, List, Item, ItemIndicator, ItemText`. Mirror `ui/combobox.tsx`/`ui/menu.tsx` wrapper style. **Novel → validate by running.**
+- Input className to match (`ui/input.tsx`): `h-8 w-full min-w-0 rounded-lg border border-input bg-transparent px-2.5 py-1 … focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-ring/50 disabled:… aria-invalid:border-destructive dark:bg-input/30`.
+- `object-form.tsx`: visibility `<select {...register("visibility")}>` (create-mode only), `<Label htmlFor="visibility">`, options draft/internal, default "draft".
+- `field-form.tsx`: useState selects — `dataType` (`id="field-type"`, TYPES, disabled on edit), `vocabularyId` (`id="field-vocab"`, when term, placeholder + `useVocabularies()` `{id,key}`, disabled on edit, required), `authorityKind` (`id="field-kind"`, when authority, "Any"=`""` + KINDS, disabled on edit).
+- Tests: `object-form.test.tsx` (visibility options + edit-mode-absent) and `fields.test.tsx` (selectOptions for type/kind/vocab) — must be rewritten.
+
+---
+
+# Task 1: `ui/select.tsx` + story (validate by running)
+
+**Files:** `web/src/components/ui/select.tsx` (new), `web/src/components/ui/select.stories.tsx` (new).
+
+- [ ] **Step 1: Study the references.** Read `web/src/components/ui/combobox.tsx` and `web/src/components/ui/menu.tsx` for the exact house pattern (namespace import, `data-slot`, `cn()`, NO semicolons, Portal+Positioner+Popup, token classes). Read `web/src/components/ui/input.tsx` for the trigger className to match. **Confirm the real Base UI Select part names/props by inspecting `web/node_modules/@base-ui/react/select/` types** — especially `Trigger`, `Value` (placeholder prop), `Positioner` (sideOffset/anchor), `Item` (`value` prop), `ItemIndicator`, `ItemText`.
+
+- [ ] **Step 2: Implement `web/src/components/ui/select.tsx`** (no-semicolon). Export `Select`, `SelectTrigger`, `SelectValue`, `SelectContent`, `SelectItem`. Skeleton — adapt every prop/part to what the installed Base UI actually exposes (validate in Step 4):
+```tsx
+import { Select as SelectPrimitive } from "@base-ui/react/select"
+import { Check, ChevronDown } from "lucide-react"
+
+import { cn } from "@/lib/utils"
+
+function Select<Value>(props: SelectPrimitive.Root.Props<Value>) {
+  return <SelectPrimitive.Root {...props} />
+}
+
+function SelectTrigger({ className, children, ...props }: SelectPrimitive.Trigger.Props) {
+  return (
+    <SelectPrimitive.Trigger
+      data-slot="select-trigger"
+      className={cn(
+        "flex h-8 w-full min-w-0 items-center justify-between gap-2 rounded-lg border border-input bg-transparent px-2.5 py-1 text-sm transition-colors outline-none",
+        "focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-ring/50",
+        "disabled:pointer-events-none disabled:cursor-not-allowed disabled:bg-input/50 disabled:opacity-50",
+        "aria-invalid:border-destructive aria-invalid:ring-3 aria-invalid:ring-destructive/20",
+        "dark:bg-input/30 data-[popup-open]:border-ring",
+        className
+      )}
+      {...props}
+    >
+      {children}
+      <SelectPrimitive.Icon className="text-muted-foreground">
+        <ChevronDown className="h-4 w-4" aria-hidden />
+      </SelectPrimitive.Icon>
+    </SelectPrimitive.Trigger>
+  )
+}
+
+function SelectValue({ className, ...props }: SelectPrimitive.Value.Props) {
+  return <SelectPrimitive.Value data-slot="select-value" className={cn("truncate", className)} {...props} />
+}
+
+function SelectContent({ className, sideOffset = 6, ...props }: SelectPrimitive.Popup.Props & { sideOffset?: number }) {
+  return (
+    <SelectPrimitive.Portal>
+      <SelectPrimitive.Positioner sideOffset={sideOffset} className="z-50" alignItemWithTrigger={false}>
+        <SelectPrimitive.Popup
+          data-slot="select-content"
+          className={cn(
+            "max-h-[min(24rem,var(--available-height))] min-w-[var(--anchor-width)] overflow-y-auto rounded-md border bg-popover p-1 text-popover-foreground shadow-md outline-none",
+            "data-open:animate-in data-open:fade-in-0 data-closed:animate-out data-closed:fade-out-0",
+            className
+          )}
+          {...props}
+        />
+      </SelectPrimitive.Positioner>
+    </SelectPrimitive.Portal>
+  )
+}
+
+function SelectItem({ className, children, ...props }: SelectPrimitive.Item.Props) {
+  return (
+    <SelectPrimitive.Item
+      data-slot="select-item"
+      className={cn(
+        "flex cursor-default items-center justify-between gap-2 rounded-sm px-2 py-1.5 text-sm outline-none select-none",
+        "data-[highlighted]:bg-accent data-[highlighted]:text-accent-foreground",
+        className
+      )}
+      {...props}
+    >
+      <SelectPrimitive.ItemText>{children}</SelectPrimitive.ItemText>
+      <SelectPrimitive.ItemIndicator>
+        <Check className="h-4 w-4" aria-hidden />
+      </SelectPrimitive.ItemIndicator>
+    </SelectPrimitive.Item>
+  )
+}
+
+export { Select, SelectTrigger, SelectValue, SelectContent, SelectItem }
+```
+IMPORTANT: `--anchor-width`/`--available-height`, `alignItemWithTrigger`, `data-[popup-open]`, the `Value` placeholder API, and whether `Trigger` is generic — all MUST be confirmed against the installed types/runtime. If a class/prop doesn't exist, drop/replace it. Token classes only (no raw palette). The STORY passing is the proof.
+
+- [ ] **Step 3: Story `web/src/components/ui/select.stories.tsx`** (single-quote, no-semicolon; match `menu.stories.tsx`). A controlled `Select` with a `SelectTrigger`(+`SelectValue placeholder`) and a `SelectContent` of 3 `SelectItem`s; a `play` test that clicks the trigger, clicks an option (queried via `within(document.body)` — Base UI Select options render in a portal with role `option`), and asserts the trigger now shows the chosen label.
+```tsx
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { useState } from 'react'
+import { expect, within } from 'storybook/test'
+
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from './select'
+
+function Controlled() {
+  const [value, setValue] = useState('')
+  return (
+    <Select value={value} onValueChange={setValue}>
+      <SelectTrigger aria-label="Fruit"><SelectValue placeholder="Pick one" /></SelectTrigger>
+      <SelectContent>
+        <SelectItem value="apple">Apple</SelectItem>
+        <SelectItem value="pear">Pear</SelectItem>
+        <SelectItem value="plum">Plum</SelectItem>
+      </SelectContent>
+    </Select>
+  )
+}
+
+const meta = { component: Select, tags: ['ai-generated'], render: () => <Controlled /> } satisfies Meta<typeof Select>
+export default meta
+type Story = StoryObj<typeof meta>
+
+export const Default: Story = {
+  play: async ({ canvas, userEvent }) => {
+    await userEvent.click(canvas.getByRole('combobox', { name: 'Fruit' }))
+    await userEvent.click(await within(document.body).findByRole('option', { name: 'Pear' }))
+    await expect(canvas.getByRole('combobox', { name: 'Fruit' })).toHaveTextContent('Pear')
+  },
+}
+```
+(If the Base UI Select trigger isn't role `combobox`, adjust the query to what it actually is — discover by running. If `onValueChange`/`value` prop names differ, fix. The story passing IS the validation; report the final working API.)
+
+- [ ] **Step 4: Validate by running (vitest ONCE):**
+  `cd web && pnpm vitest run src/components/ui/select.stories.tsx && pnpm typecheck && pnpm lint`
+  Iterate the wrapper until the story play test passes. Report the FINAL working API (exports, the trigger role/accessible-name mechanism, value/onValueChange names, placeholder mechanism) — Tasks 2/3 depend on it.
+
+- [ ] **Step 5: Commit**
+```bash
+git add web/src/components/ui/select.tsx web/src/components/ui/select.stories.tsx
+git commit -m "feat(web): ui/select Base UI Select wrapper matching Input + story (#51)"
+```
+
+---
+
+# Task 2: object-form visibility → ui/Select
+
+**Files:** `web/src/objects/object-form.tsx`, `web/src/objects/object-form.test.tsx`.
+
+- [ ] **Step 1: Replace the visibility `<select>`** (create-mode block). Add imports: `import { Controller } from "react-hook-form";` (if not present) and `import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "@/components/ui/select";`. Replace:
+```tsx
+{mode === "create" && (
+  <div className="space-y-1">
+    <Label htmlFor="visibility">{t("form.visibility")}</Label>
+    <Controller
+      control={form.control}
+      name="visibility"
+      render={({ field }) => (
+        <Select value={field.value} onValueChange={field.onChange}>
+          <SelectTrigger id="visibility">
+            <SelectValue />
+          </SelectTrigger>
+          <SelectContent>
+            <SelectItem value="draft">{t("form.draft")}</SelectItem>
+            <SelectItem value="internal">{t("form.internal")}</SelectItem>
+          </SelectContent>
+        </Select>
+      )}
+    />
+  </div>
+)}
+```
+(Use the exact value/onValueChange/trigger-id API confirmed in Task 1. `form.control` is available from `useForm`; destructure `control` or use `form.control`. The default value stays `"draft"` from `defaultValues`.) Keep `<Label htmlFor="visibility">` so the trigger is labelled (the trigger carries `id="visibility"`).
+
+- [ ] **Step 2: Rewrite the visibility test** in `object-form.test.tsx` (the first test, lines 8–26). Replace the `HTMLSelectElement.options` inspection with open-and-assert:
+```tsx
+// after typing object number/name/inscription:
+await userEvent.click(screen.getByLabelText(/visibility/i)); // opens the Select
+expect(await within(document.body).findByRole("option", { name: /draft/i })).toBeInTheDocument();
+expect(within(document.body).getByRole("option", { name: /internal/i })).toBeInTheDocument();
+expect(within(document.body).queryByRole("option", { name: /public/i })).not.toBeInTheDocument();
+// close without changing (Escape) so default "draft" stays, then submit:
+await userEvent.keyboard("{Escape}");
+await userEvent.click(screen.getByRole("button", { name: /create object/i }));
+await waitFor(() => expect(onSubmit).toHaveBeenCalledOnce());
+const values = onSubmit.mock.calls[0][0];
+expect(values.core.object_number).toBe("A-9");
+expect(values.visibility).toBe("draft");
+expect(values.fields.inscription).toBe("To the gods");
+```
+Add `within` to the testing-library import. NOTE: `screen.getByLabelText(/visibility/i)` must resolve the Select trigger — if the Label→trigger association doesn't make `getByLabelText` work (Task 1 should ensure it via `id`), fall back to `screen.getByRole("combobox", { name: /visibility/i })`; use whichever the Task-1 validation showed works, consistently. Do NOT weaken the draft/internal/not-public assertions.
+
+- [ ] **Step 3: Confirm the "edit mode: no visibility control" test (lines 68–82) still passes** — it queries `queryByLabelText(/visibility/i)` which returns null in edit mode (the block isn't rendered). Should pass unchanged. If the query mechanism changed in Step 2, mirror it here (e.g. `queryByRole("combobox", { name: /visibility/i })`).
+
+- [ ] **Step 4: Verify (vitest ONCE):** `cd web && pnpm vitest run src/objects/object-form.test.tsx && pnpm typecheck && pnpm lint`. PASS (the other object-form tests — Cmd+Enter, required, minCount, edit, pruneFields — must stay green).
+
+- [ ] **Step 5: Commit**
+```bash
+git add web/src/objects/object-form.tsx web/src/objects/object-form.test.tsx
+git commit -m "feat(web): object-form visibility uses ui/Select (#51)"
+```
+
+---
+
+# Task 3: field-form's three selects → ui/Select + gate
+
+**Files:** `web/src/fields/field-form.tsx`, `web/src/fields/fields.test.tsx`.
+
+- [ ] **Step 1: Replace the three `<select>`s** in `field-form.tsx`. Add `import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "@/components/ui/select";`.
+  - **data_type** (lines 118–133):
+```tsx
+<div className="space-y-1">
+  <Label htmlFor="field-type">{t("fields.type")}</Label>
+  <Select value={dataType} onValueChange={setDataType} disabled={isEdit}>
+    <SelectTrigger id="field-type"><SelectValue /></SelectTrigger>
+    <SelectContent>
+      {TYPES.map((type) => (
+        <SelectItem key={type} value={type}>{t(`fields.types.${type}`)}</SelectItem>
+      ))}
+    </SelectContent>
+  </Select>
+</div>
+```
+  - **vocabulary** (the `dataType === "term"` block): `<Select value={vocabularyId} onValueChange={setVocabularyId} disabled={isEdit}>` with `<SelectTrigger id="field-vocab"><SelectValue placeholder={t("form.selectPlaceholder")} /></SelectTrigger>` and `SelectItem`s from `vocabularies?.map((v) => <SelectItem key={v.id} value={v.id}>{v.key}</SelectItem>)`. (No empty `""` item — the placeholder shows when `vocabularyId===""`; the required check `!vocabularyId` still blocks submit.)
+  - **authority_kind** (the `dataType === "authority"` block): `<Select value={authorityKind} onValueChange={setAuthorityKind} disabled={isEdit}>` with `<SelectTrigger id="field-kind"><SelectValue /></SelectTrigger>`, an `<SelectItem value="">{t("fields.anyKind")}</SelectItem>` then `KINDS.map((k) => <SelectItem key={k} value={k}>{t(`authorities.${k}`)}</SelectItem>)`.
+  Keep every `<Label htmlFor>` and the surrounding `div.space-y-1`. No change to submit/validation/reset logic.
+  - NOTE on Base UI Select value `""`: confirm the authority_kind `""` "Any" item selects/displays correctly, and that vocabulary's `""` shows the placeholder (Task 1 validated the placeholder). If Base UI Select disallows an empty-string item value, use a sentinel (e.g. `"__any__"`) mapped to `""`/`null` at submit — but prefer `""` if it works; verify by running the test.
+
+- [ ] **Step 2: Rewrite `fields.test.tsx`** select interactions (a small helper keeps it readable). Add `within` to the import. Replace `userEvent.selectOptions(...)` with open+click:
+  - A helper:
+```tsx
+async function choose(triggerName: RegExp, optionName: RegExp) {
+  await userEvent.click(screen.getByLabelText(triggerName));
+  await userEvent.click(await within(document.body).findByRole("option", { name: optionName }));
+}
+```
+  - "selecting Authority…": `await choose(/^type$/i, /authority/i);` then `const kind = await screen.findByLabelText(/authority kind/i);` (now a Select trigger) → `await choose(/authority kind/i, /^person$/i);` → create → assert `body.authority_kind === "person"`.
+  - "selecting Term…": `await choose(/^type$/i, /term/i);` then assert the vocabulary trigger appears (`await screen.findByLabelText(/^vocabulary$/i)`); click create → expect the `role="alert"` (blocked, `posted===false`); then `await choose(/^vocabulary$/i, /material/i)` (the seeded vocab `v-material` shows its `key` — match its label; check the MSW vocab fixture for the displayed `key` text and match it) → create → `posted===true`.
+  - "creates a text field" + "lists field definitions…" — default type is text; the type Select isn't opened, so these should pass unchanged (the create posts `data_type: "text"`). Verify.
+  - If `getByLabelText(triggerName)` doesn't resolve the Select trigger, use `getByRole("combobox", { name: triggerName })` (whatever Task 1 validated) — consistently. Keep all `body`/`posted` assertions identical.
+  - IMPORTANT: confirm the vocab option label — the test selected `"v-material"` (the option *value*); with Select the user clicks the visible **label** (the vocab `key`). Read the vocab MSW fixture (`web/src/test/handlers.ts`) to find the `key` displayed for id `v-material` and match the option name to that text.
+
+- [ ] **Step 3: FULL GATE (run tests EXACTLY ONCE):**
+```bash
+cd web && pnpm typecheck && pnpm lint && pnpm test && pnpm build && pnpm check:size && pnpm check:colors
+```
+All green. Report test totals, largest chunk (KB gz; Select adds to the bundle — report and flag if >250), check:colors line.
+
+- [ ] **Step 4: Codename + status:**
+```bash
+cd /Users/olsson/Laboratory/biggus-dickus
+git grep -in 'biggus\|dickus' -- web/src; echo "codename-exit=$?"
+git status --short
+```
+
+- [ ] **Step 5: Manual smoke (recommended).** `pnpm dev`: each select now matches Input (height/radius/border) and shows a focus ring on keyboard focus; data_type/vocab/kind disabled on edit; visibility still defaults to draft and submits correctly; term/authority conditional pickers work.
+
+- [ ] **Step 6: Commit**
+```bash
+git add web/src/fields/field-form.tsx web/src/fields/fields.test.tsx
+git commit -m "feat(web): field-form selects use ui/Select; rewrite select tests (#51)"
+```
+
+---
+
+## Self-Review (completed)
+
+**Spec coverage:** ui/Select matching Input + story-validated (T1); visibility via Controller (T2); data_type/vocabulary/authority_kind via value/onValueChange + disabled-on-edit (T3); behavior preserved (placeholder, "Any"=`""`, required-vocab check, reset); tests rewritten to click interaction with identical payload assertions (T2/T3); gate + check:size report (T3). Acceptance criteria 1–5 mapped. ✓
+
+**Placeholder scan:** the Base UI Select part tree/props are "confirm by running" (novel primitive) with a concrete skeleton + the validation step — not a TODO. The `""`-value caveat (authority "Any") has an explicit fallback (sentinel). The vocab option label is "read the fixture and match" with the file named. No vague steps. ✓
+
+**Type/consistency:** exports `Select/SelectTrigger/SelectValue/SelectContent/SelectItem` defined in T1, consumed identically in T2/T3; the trigger query mechanism (getByLabelText vs getByRole combobox) is chosen once in T1 and used consistently. value/onValueChange contract uniform. ✓
+
+## Notes
+- No new dependency (Base UI + lucide already present); no new i18n keys.
+- `check:size` is the one budget risk (Select in the form chunks) — measured + flagged in T3, not silently bumped.
+- Validate-by-running (T1) is mandatory for the novel Base UI Select, per the repo pattern (combobox/menu/toast).
+- Deferred: searchable vocabulary combobox; a raw-`<select>` lint guard.