133 lines
9.1 KiB
Markdown
133 lines
9.1 KiB
Markdown
# Token-Styled Select — Design
|
|
|
|
**Date:** 2026-06-08
|
|
**Status:** Approved (brainstorming) — ready for implementation planning.
|
|
**Issue:** #51.
|
|
|
|
## Context
|
|
|
|
Four raw `<select>` elements (`field-form.tsx:120` data_type, `:138` vocabulary, `:158`
|
|
authority_kind; `object-form.tsx:148` visibility) are styled `w-full rounded border px-2 py-1 text-sm`
|
|
— different radius/border/padding/height from the sibling `ui/Input` (`h-8 rounded-lg border-input …
|
|
focus-visible:ring-3 ring-ring/50`), and crucially they have **no focus ring** (keyboard users get no
|
|
focus affordance). This milestone adds a token-styled `ui/Select` (Base UI Select) matching `Input`
|
|
and replaces all four. (Decision: all four → `ui/Select`; making the vocabulary picker a searchable
|
|
combobox is a deferred follow-up — keeps the working object-editing combobox untouched.)
|
|
|
|
**Facts:** Base UI Select is `import { Select as SelectPrimitive } from "@base-ui/react/select"`
|
|
(namespace; parts Root/Trigger/Value/Icon/Portal/Positioner/Popup/List/Item/ItemIndicator/ItemText) —
|
|
no new dependency. `object-form` is react-hook-form (visibility is `register`'d); `field-form` is
|
|
useState-controlled (all three selects), with `data_type`/`vocabulary_id`/`authority_kind` `disabled`
|
|
on edit. `ui/menu.tsx` + `ui/combobox.tsx` are the established Base UI wrapper patterns. The Input
|
|
className to match is in `ui/input.tsx`. Base UI Select is NOT a native `<select>`, so existing tests
|
|
using `userEvent.selectOptions` / `HTMLSelectElement` must be rewritten to click interaction.
|
|
|
|
### Decisions (from brainstorming)
|
|
1. **All four selects → `ui/Select`** (uniform token styling + focus ring; lowest risk).
|
|
2. New `ui/select.tsx` wraps Base UI Select; **validated by running** (novel primitive).
|
|
3. Tests rewritten to Base UI Select interaction (open trigger → click item).
|
|
|
|
## Components
|
|
|
|
### `web/src/components/ui/select.tsx` (new)
|
|
Wrap Base UI Select in the `ui/*` style (`data-slot`, `cn`, no semicolons), mirroring
|
|
`ui/combobox.tsx`/`ui/menu.tsx`. Exports (names final after validate-by-running):
|
|
- `Select` — `SelectPrimitive.Root` (generic value; `value`/`onValueChange`/`defaultValue`/`disabled`/`name`).
|
|
- `SelectTrigger` — `SelectPrimitive.Trigger` styled to **match Input**: `h-8 w-full rounded-lg border
|
|
border-input bg-transparent px-2.5 py-1 text-sm inline-flex items-center justify-between
|
|
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 dark:bg-input/30` + a
|
|
trailing chevron (`SelectPrimitive.Icon` with a lucide `ChevronDown`, `aria-hidden`) and a
|
|
`SelectValue` (`SelectPrimitive.Value`) showing the chosen item (with `placeholder`).
|
|
- `SelectContent` — `SelectPrimitive.Portal` + `SelectPrimitive.Positioner` (`sideOffset`, `z-50`) +
|
|
`SelectPrimitive.Popup` styled as a card (`min-w-[var(--anchor-width)]` if supported, else
|
|
`min-w-32`; `rounded-md border bg-popover p-1 text-popover-foreground shadow-md outline-none` +
|
|
open/close animation data-attrs).
|
|
- `SelectItem` — `SelectPrimitive.Item` row (`flex items-center gap-2 rounded-sm px-2 py-1.5 text-sm
|
|
outline-none select-none data-[highlighted]:bg-accent data-[highlighted]:text-accent-foreground`) +
|
|
a `SelectPrimitive.ItemIndicator` (lucide `Check`) and `SelectPrimitive.ItemText`.
|
|
- Token classes only (no raw palette). The exact part tree + props (`SelectValue` placeholder,
|
|
positioner anchoring, item `value`) **must be confirmed by running the story** (Base UI Select is
|
|
novel here), as combobox/menu/toast were.
|
|
|
|
**Accessibility:** `SelectTrigger` accepts `id` so the existing `<Label htmlFor={id}>` associates →
|
|
`getByLabelText`/`getByRole("combobox", { name })` keeps working in tests. (Base UI Select trigger has
|
|
role `combobox`; confirm the accessible-name wiring when validating.)
|
|
|
|
### `web/src/components/ui/select.stories.tsx` (new)
|
|
A `Select` with a few `SelectItem`s; a `play` test that opens the trigger and selects an item, asserting
|
|
the value/label updates (portal content queried via `within(document.body)`, like the menu story). This
|
|
is the validation.
|
|
|
|
### Replacements
|
|
|
|
**`object-form.tsx` visibility** (create-mode only): Base UI Select isn't a native input, so replace
|
|
the `register("visibility")` `<select>` with a **`Controller`** (`control={form.control}
|
|
name="visibility"`) rendering `<Select value={field.value} onValueChange={field.onChange}>` with items
|
|
`draft`/`internal` (labels `form.draft`/`form.internal`). Keep `<Label htmlFor="visibility">` → trigger
|
|
`id="visibility"`. Default stays `"draft"` (the form's defaultValues already set it).
|
|
|
|
**`field-form.tsx`** (useState — pass `value`/`onValueChange` directly, no Controller):
|
|
- **data_type:** `<Select value={dataType} onValueChange={setDataType} disabled={isEdit}>`, items from
|
|
`TYPES` (labels `fields.types.${type}`). `id="field-type"`.
|
|
- **vocabulary_id** (when `dataType==="term"`): `<Select value={vocabularyId} onValueChange={setVocabularyId}
|
|
disabled={isEdit}>` with a placeholder (`form.selectPlaceholder`) and items from `vocabularies` (value
|
|
`vocab.id`, label `vocab.key`). `id="field-vocab"`. The empty/placeholder state: Base UI Select shows
|
|
the `SelectValue` placeholder when value is `""`; keep `vocabularyId=""` as the unselected state (the
|
|
existing required-check `!vocabularyId` still works).
|
|
- **authority_kind** (when `dataType==="authority"`): `<Select value={authorityKind}
|
|
onValueChange={setAuthorityKind} disabled={isEdit}>` with an "Any" item (value `""`, label
|
|
`fields.anyKind`) + `KINDS` items (labels `authorities.${kind}`). `id="field-kind"`.
|
|
|
|
No change to submit logic, validation, or the disabled-on-edit behavior — only the control swaps.
|
|
|
|
## Data flow
|
|
Unchanged: the same state/`register`/`Controller` value drives the same submit payloads. Only the
|
|
rendered control (native `<select>` → Base UI Select) and its styling change.
|
|
|
|
## Error handling / edges
|
|
- Base UI Select `value=""` must render the placeholder (vocabulary) or the "Any" item (authority_kind)
|
|
— verify when running. The authority_kind "Any" is a real selectable item with value `""`.
|
|
- `disabled={isEdit}` must visually + functionally disable the trigger (the styling includes
|
|
`disabled:` classes).
|
|
- The visibility `Controller` default must remain `"draft"` (no regression to the create payload).
|
|
- Keyboard: Base UI Select is fully keyboard-operable (the focus ring is the headline fix).
|
|
|
|
## Testing
|
|
- **`select.stories.tsx`** validates the primitive by running (open + select).
|
|
- **`object-form.test.tsx`** rewrite the visibility assertions:
|
|
- "shows visibility (draft/internal only, not public)": open the Select trigger, assert items `Draft`
|
|
+ `Internal` are present and `Public` is absent (query the portal list); select `Internal` and
|
|
assert it's reflected. (Replaces `HTMLSelectElement.options` inspection.)
|
|
- "edit mode: no visibility control": keep — query by the visibility Label name returns null.
|
|
- **`fields.test.tsx`** rewrite the select flows to click interaction:
|
|
- data_type → open, click `Authority` → the kind picker appears → open, click `Person` → assert
|
|
`authority_kind: "person"` in the create payload.
|
|
- data_type → open, click `Term` → the vocabulary picker appears → submit blocked until a vocab is
|
|
chosen → open, click the vocab → assert the create payload. Keep the same payload assertions.
|
|
- "creates a text field" (default type) — unaffected or minimal change.
|
|
- Keep all payload/mutation assertions identical (don't weaken); only the interaction changes.
|
|
- Gate: `typecheck`/`lint`/`test`/`build`/`check:size`/`check:colors`; en/sv parity (no new keys
|
|
expected); no codename. **`check:size`:** Base UI Select adds to the always-loaded form chunk —
|
|
report the value (budget 250 KB gz; flag if it exceeds rather than silently raising).
|
|
|
|
## Acceptance criteria
|
|
1. A `ui/Select` (Base UI Select) exists, styled to match `Input` (h-8, rounded-lg, border-input,
|
|
focus-visible ring, disabled/aria-invalid states), with a Storybook story validated by running.
|
|
2. All four raw `<select>` elements (object-form visibility; field-form data_type / vocabulary /
|
|
authority_kind) are replaced by `ui/Select`; they share Input's tokens and have a visible focus ring.
|
|
3. Behavior preserved: same values/payloads, disabled-on-edit, create-mode-only visibility, term/authority
|
|
conditional pickers, the required-vocabulary check, and the create-form reset.
|
|
4. Tests rewritten to Base UI Select interaction (no native `selectOptions`); all payload assertions
|
|
unchanged; suite green.
|
|
5. `typecheck`/`lint`/`test`/`build`/`check:colors` green; `check:size` reported (within budget or
|
|
flagged); en/sv parity; no codename; no new npm dependency.
|
|
|
|
## Out of scope → follow-ups
|
|
- Making the vocabulary picker a **searchable combobox** (generalizing `OptionsCombobox` to `{id,label}`)
|
|
— deferred; revisit if vocabulary lists grow large.
|
|
- Replacing any other native form controls; a lint guard banning raw `<select>` outside `components/ui/`.
|
|
- The `visibility` select gaining a `public` option (intentionally absent — publishing is via
|
|
`publish-control`).
|