@tristan2828/ui-foundation 3.4.0 → 3.5.0

package/README.md

@@ -18,7 +18,7 @@ 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` | `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` |

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

@@ -85,7 +85,17 @@ is a filled-in example while the Widgets demo is still here).
    `<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/entity-plan-template.md

@@ -30,7 +30,10 @@ One or two sentences: what one record is, and who uses the screens.
     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).

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/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.4.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": {