@tristan2828/ui-foundation 3.3.0 → 3.5.0

package/README.md

@@ -18,8 +18,8 @@ than installing this by hand:
 
 | Import | What |
 |---|---|
-| `@tristan2828/ui-foundation` | `AppShell`, `DataTable`, `EntityForm`, `ErrorState`, `MultiChoice`, `PasswordInput`, `RouteErrorBoundary`, `FoundationProviders`, `LoginRoute`, `RegisterRoute`, `useAuth`, `useTableUrlState`, `useDebouncedValue`, `createQueryClient`, `cn`; types `Page`, `AppError`, `QuerySpec` |
-| `@tristan2828/ui-foundation/ui/<name>` | shadcn primitives: badge, button, calendar, card, combobox, dialog, empty, field, input, input-group, label, popover, select, separator, sheet, sidebar, skeleton, sonner, spinner, table, textarea, tooltip |
+| `@tristan2828/ui-foundation` | `AppShell`, `DataTable`, `EntityForm`, `ErrorState`, `MultiChoice`, `MultiReference`, `PasswordInput`, `RouteErrorBoundary`, `FoundationProviders`, `LoginRoute`, `RegisterRoute`, `useAuth`, `useTableUrlState`, `useDebouncedValue`, `createQueryClient`, `cn`; types `Page`, `AppError`, `QuerySpec` |
+| `@tristan2828/ui-foundation/ui/<name>` | shadcn primitives: badge, button, calendar, card, combobox, dialog, empty, field, input, input-group, label, popover, select, separator, sheet, sidebar, skeleton, sonner, spinner, switch, table, textarea, tooltip |
 | `@tristan2828/ui-foundation/gateway` | `safeFetch`, `toAppError`, `networkError` — for an app's `src/api/gateway/` only |
 | `@tristan2828/ui-foundation/mocks` | MSW: `authHandlers`, `resetMockAuth`, `getMockCurrentUser`, `MOCK_USER`, `exposeMswForE2E` |
 | `@tristan2828/ui-foundation/testing` | Playwright: `defineA11ySuite`, `defineMockModeBannerSuite`, `forceMswOverride`, `forceLoggedOut`, `waitForMswReady` |

package/conventions/docs/add-an-entity.md

@@ -76,11 +76,26 @@ is a filled-in example while the Widgets demo is still here).
    and labels from its field table, and field types by pattern (a
    `reference` field copies Category's searchable combobox, a
    `single choice` copies Status's select, a `date-time` copies
-   Available From's date picker, a `multi choice` copies Tags — the
+   Available From's date picker, a `yes/no` copies In Stock — a `Switch`
+   (`@tristan2828/ui-foundation/ui/switch`) in a horizontal `Field` with
+   its label beside it on the form, cell pattern 12 (the word Yes/No) in
+   the table, and a three-way toolbar `Select` (either / yes / no) whose URL
+   value is `'true'`/`'false'` and whose `filters` value is a real boolean,
+   so `false` reaches the wire — and a `multi choice` copies Tags — the
    `<MultiChoice>` control from the foundation on the
    form and as a toolbar filter via `useTableUrlState`'s multi filters,
    badges in the table, and a `filters` array the gateway sends as a
-   repeated parameter):
+   repeated parameter — and a `multi reference` copies Extra Categories:
+   the `<MultiReference>` control on the form and as a toolbar filter, an
+   array of ids on the wire, a repeated any-of list filter, and names from
+   a **lookup by id** on the referenced entity
+   (`GET /categories?ids=1&ids=3`, `getCategoriesByIds`,
+   `useCategoriesByIdsQuery`). Add that `ids` parameter to the referenced
+   entity's list endpoint if it lacks one. Never name a picked id from
+   search results alone: a saved pick the current search doesn't return
+   would show without a name. The table looks up every id on its page in
+   one request; the backend rejects an unknown id as a 422 on the field,
+   never a foreign-key 500):
    - `src/routes/widgets/use-widgets.ts`, `use-categories.ts` →
      `src/routes/<entity>/use-<entity>.ts` (TanStack Query hooks over the
      new gateway module)

package/conventions/docs/cell-patterns.md

@@ -7,7 +7,9 @@ per-entity, and only the shape is reusable. Copy the markup into your
 
 Patterns 1–10 were each chosen for a real column, from a page of
 alternatives ([`column-options.md`](column-options.md)), not designed in the abstract.
-Patterns from 11 on are marked **Unproven**: written ahead of a real
+Pattern 12 (boolean) is the template's own reference: Widget's In Stock
+column renders it and its specs pin it. The other patterns from 11 on are
+marked **Unproven**: written ahead of a real
 column, so no app has tested them on real data yet. Prefer a proven
 pattern when one fits. When you use an unproven one, say so in the
 entity's plan, and raise what you learned for the foundation, so the
@@ -257,9 +259,11 @@ cell: ({ getValue }) => {
   template's `USD` is the demo's.
 - **Cost:** none to speak of. It's the plain-text pattern with formatting.
 
-## 12. Boolean — *Unproven*
+## 12. Boolean
 
-A yes/no field.
+A yes/no field. Widget's In Stock column (`src/routes/widgets/widgets-columns.tsx`)
+is the reference; its value is never null, so it drops the `emptyCell`
+branch below.
 
 ```tsx
 cell: ({ getValue }) => {

package/conventions/docs/entity-plan-template.md

@@ -24,15 +24,21 @@ One or two sentences: what one record is, and who uses the screens.
 - **Type** — what the foundation supports today:
   - *Demonstrated by the Widget reference* (copied directly): `text` (one
     line), `long text`, `decimal` (fixed places — say how many),
-    `date-time`, `email`, `single choice` (list the options, in display
+    `date-time`, `email`, `yes/no` (a boolean that is always yes or no:
+    say its default and the filter's three labels, e.g. Any stock /
+    In stock / Out of stock), `single choice` (list the options, in display
     order; see the note below if it is *optional*), `multi choice` (list
     the options; any number can be picked —
     chips on the form, badges in the table, an any-of filter), `reference`
-    (to another entity — name it; a searchable combobox).
+    (to another entity — name it; a searchable combobox), `multi reference`
+    (to any number of records of another entity — name it; chips with a
+    searchable dropdown, names as badges in the table, an any-of filter;
+    the other entity's list endpoint must also accept `ids`).
   - *Close variants* (built by a small, stated change to the nearest
     pattern): `integer` (from decimal), `url` (from email — a format
     check), `date` (from date-time — no time part).
-  - *Not supported yet:* boolean, file, and anything else.
+  - *Not supported yet:* a yes/no that can also be unset (three states),
+    file, and anything else.
     Write it anyway with a note; the playbook will stop and raise it
     rather than improvise.
 - **Required**: `yes`, or `no` (then say whether empty means "unknown").

package/dist/components/app/multi-reference.d.ts

@@ -0,0 +1,27 @@
+import * as React from 'react';
+export declare function MultiReference<Id extends string | number>({ options, value, onValueChange, getLabel, onSearchChange, id, placeholder, emptyText, 'aria-label': ariaLabel, 'aria-invalid': ariaInvalid, className, }: {
+    /** The records the current search returned, in display order. */
+    options: readonly {
+        id: Id;
+        label: string;
+    }[];
+    /** The picked ids. */
+    value: Id[];
+    onValueChange: (value: Id[]) => void;
+    /**
+     * The name of any id: a picked one (from the app's lookup by ids) or an
+     * option. `undefined` while it's still loading.
+     */
+    getLabel: (id: Id) => string | undefined;
+    /** Called with the typed text; the app feeds it to its search query. */
+    onSearchChange: (search: string) => void;
+    /** Id for the text input, so a <FieldLabel htmlFor> labels it. */
+    id?: string;
+    placeholder?: string;
+    /** Shown in the dropdown when the search matches nothing. */
+    emptyText?: string;
+    /** For use without a visible label (e.g. a table toolbar filter). */
+    'aria-label'?: string;
+    'aria-invalid'?: boolean;
+    className?: string;
+}): React.JSX.Element;

package/dist/components/app/multi-reference.js

@@ -0,0 +1,27 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// A multi-reference picker: links to several records of another entity,
+// shown as removable chips, with the rest found by typing. The one control
+// for every "multi reference" field (conventions/docs/entity-plan-template.md),
+// on a form (Widget Extra Categories) and as a table filter.
+//
+// MultiChoice's sibling, for values that are record ids rather than enum
+// strings. Two differences follow from that:
+// - A chip needs a *name* for an id the current search may not include
+//   (editing a saved record, a filter from a shared link). The app fetches
+//   names for exactly the picked ids (Widget: GET /categories?ids=...) and
+//   passes `getLabel`; this component never guesses one.
+// - Matching happens on the server: `onSearchChange` reports what was typed
+//   and `options` is whatever the app's search query returned, so nothing
+//   is filtered here (filter={null}).
+import * as React from 'react';
+import { Combobox, ComboboxChip, ComboboxChips, ComboboxChipsInput, ComboboxContent, ComboboxEmpty, ComboboxItem, ComboboxList, ComboboxValue, useComboboxAnchor, } from '../ui/combobox.js';
+/** Shown on a chip whose name hasn't loaded yet, instead of a bare id. */
+const PENDING_LABEL = '…';
+export function MultiReference({ options, value, onValueChange, getLabel, onSearchChange, id, placeholder, emptyText = 'No matches.', 'aria-label': ariaLabel, 'aria-invalid': ariaInvalid, className, }) {
+    const anchor = useComboboxAnchor();
+    const label = (option) => getLabel(option) ?? PENDING_LABEL;
+    return (_jsxs(Combobox, { multiple: true, autoHighlight: true, 
+        // Ids, not {id,label} objects: Base UI compares items to the value
+        // with Object.is, so the items must have the value's own shape.
+        items: options.map((option) => option.id), value: value, onValueChange: (next) => onValueChange(next), onInputValueChange: onSearchChange, itemToStringLabel: label, filter: null, children: [_jsx(ComboboxChips, { ref: anchor, className: className, children: _jsx(ComboboxValue, { children: (selected) => (_jsxs(React.Fragment, { children: [selected.map((option) => (_jsx(ComboboxChip, { children: label(option) }, option))), _jsx(ComboboxChipsInput, { id: id, "aria-label": ariaLabel, "aria-invalid": ariaInvalid, placeholder: selected.length === 0 ? placeholder : undefined })] })) }) }), _jsxs(ComboboxContent, { anchor: anchor, children: [_jsx(ComboboxEmpty, { children: emptyText }), _jsx(ComboboxList, { children: (option) => (_jsx(ComboboxItem, { value: option, children: label(option) }, option)) })] })] }));
+}

package/dist/components/ui/switch.d.ts

@@ -0,0 +1,5 @@
+import { Switch as SwitchPrimitive } from "@base-ui/react/switch";
+declare function Switch({ className, size, ...props }: SwitchPrimitive.Root.Props & {
+    size?: "sm" | "default";
+}): import("react").JSX.Element;
+export { Switch };

package/dist/components/ui/switch.js

@@ -0,0 +1,7 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Switch as SwitchPrimitive } from "@base-ui/react/switch";
+import { cn } from "cn";
+function Switch({ className, size = "default", ...props }) {
+    return (_jsx(SwitchPrimitive.Root, { "data-slot": "switch", "data-size": size, className: cn("peer group/switch relative inline-flex shrink-0 items-center rounded-full border border-transparent transition-all outline-none group-has-[:focus-visible]/field-label:border-transparent group-has-[:focus-visible]/field-label:ring-0 after:absolute after:-inset-x-3 after:-inset-y-2 focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-ring/50 aria-invalid:border-destructive aria-invalid:ring-3 aria-invalid:ring-destructive/20 data-[size=default]:h-[18.4px] data-[size=default]:w-[32px] data-[size=sm]:h-[14px] data-[size=sm]:w-[24px] dark:aria-invalid:border-destructive/50 dark:aria-invalid:ring-destructive/40 data-checked:bg-primary data-unchecked:bg-input dark:data-unchecked:bg-input/80 data-disabled:cursor-not-allowed data-disabled:opacity-50", className), ...props, children: _jsx(SwitchPrimitive.Thumb, { "data-slot": "switch-thumb", className: "pointer-events-none block rounded-full bg-background ring-0 transition-transform group-data-[size=default]/switch:size-4 group-data-[size=sm]/switch:size-3 group-data-[size=default]/switch:data-checked:translate-x-[calc(100%-2px)] group-data-[size=sm]/switch:data-checked:translate-x-[calc(100%-2px)] dark:data-checked:bg-primary-foreground group-data-[size=default]/switch:data-unchecked:translate-x-0 group-data-[size=sm]/switch:data-unchecked:translate-x-0 dark:data-unchecked:bg-foreground" }) }));
+}
+export { Switch };

package/dist/index.d.ts

@@ -5,6 +5,7 @@ export { ErrorState } from './components/app/error-state.js';
 export { FoundationProviders } from './components/app/foundation-providers.js';
 export { MockModeBanner } from './components/app/mock-mode-banner.js';
 export { MultiChoice } from './components/app/multi-choice.js';
+export { MultiReference } from './components/app/multi-reference.js';
 export { PasswordInput } from './components/app/password-input.js';
 export { RouteErrorBoundary } from './components/app/route-error-boundary.js';
 export { ThemeProvider } from './components/theme-provider.js';

package/dist/index.js

@@ -10,6 +10,7 @@ export { ErrorState } from './components/app/error-state.js';
 export { FoundationProviders } from './components/app/foundation-providers.js';
 export { MockModeBanner } from './components/app/mock-mode-banner.js';
 export { MultiChoice } from './components/app/multi-choice.js';
+export { MultiReference } from './components/app/multi-reference.js';
 export { PasswordInput } from './components/app/password-input.js';
 export { RouteErrorBoundary } from './components/app/route-error-boundary.js';
 export { ThemeProvider } from './components/theme-provider.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tristan2828/ui-foundation",
-  "version": "3.3.0",
+  "version": "3.5.0",
   "description": "Shared UI foundation for contract-first, database-backed React apps: shadcn primitives, DataTable/EntityForm composites, auth, the gateway error seam, design tokens, lint rules and the AI playbook.",
   "license": "MIT",
   "repository": {