docs(plans): token-styled select — 3-task plan (#51)
This commit is contained in:
@@ -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.
|
||||
Reference in New Issue
Block a user