@tristan2828/ui-foundation 3.19.0 → 3.20.1

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

@@ -125,7 +125,9 @@ is a filled-in example while the Widgets demo is still here).
    array of ids on the wire, a repeated any-of list filter, and names from
    a **lookup by id** on the referenced entity
    (`GET /widget-categories?ids=1&ids=3`, `getWidgetCategoriesByIds`,
-   `useWidgetCategoriesByIdsQuery`). Add that `ids` parameter to the referenced
+   `useWidgetCategoriesByIdsQuery`), and `searching` from the search
+   query's `isPlaceholderData` so Enter waits for the results that match
+   what was typed. 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

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

@@ -1,5 +1,5 @@
 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, 'aria-describedby': ariaDescribedBy, readOnly, className, }: {
+export declare function MultiReference<Id extends string | number>({ options, value, onValueChange, getLabel, onSearchChange, id, placeholder, emptyText, 'aria-label': ariaLabel, 'aria-invalid': ariaInvalid, 'aria-describedby': ariaDescribedBy, readOnly, searching, className, }: {
     /** The records the current search returned, in display order. */
     options: readonly {
         id: Id;
@@ -27,5 +27,13 @@ export declare function MultiReference<Id extends string | number>({ options, va
     'aria-describedby'?: string;
     /** Shown, not changeable: editing in place, while the save is in flight. */
     readOnly?: boolean;
+    /**
+     * The options don't answer what's typed yet: the app's search for it is
+     * in flight and the list still shows the last one's results (TanStack
+     * Query with `placeholderData: (previous) => previous`:
+     * `isPlaceholderData`). Enter does nothing until it answers; a click
+     * still picks. The list is `aria-busy` meanwhile.
+     */
+    searching?: boolean;
     className?: string;
 }): React.JSX.Element;

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

@@ -13,15 +13,24 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 // - 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}).
+// - Until that search answers, the list still holds the last one's
+//   results, its first still highlighted. `searching` says so: Enter
+//   waits rather than picking from the old list (where it could even
+//   remove a pick: the highlighted item may be one already picked).
 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, 'aria-describedby': ariaDescribedBy, readOnly = false, className, }) {
+export function MultiReference({ options, value, onValueChange, getLabel, onSearchChange, id, placeholder, emptyText = 'No matches.', 'aria-label': ariaLabel, 'aria-invalid': ariaInvalid, 'aria-describedby': ariaDescribedBy, readOnly = false, searching = false, 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, readOnly: readOnly, 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, "aria-describedby": ariaDescribedBy, 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)) })] })] }));
+        items: options.map((option) => option.id), value: value, onValueChange: (next) => onValueChange(next), onInputValueChange: onSearchChange, itemToStringLabel: label, filter: null, readOnly: readOnly, 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, onKeyDown: (event) => {
+                                    if (searching && event.key === 'Enter') {
+                                        event.preventDefault();
+                                        event.preventBaseUIHandler();
+                                    }
+                                }, "aria-label": ariaLabel, "aria-invalid": ariaInvalid, "aria-describedby": ariaDescribedBy, placeholder: selected.length === 0 ? placeholder : undefined })] })) }) }), _jsxs(ComboboxContent, { anchor: anchor, children: [_jsx(ComboboxEmpty, { children: emptyText }), _jsx(ComboboxList, { "aria-busy": searching || undefined, children: (option) => (_jsx(ComboboxItem, { value: option, children: label(option) }, option)) })] })] }));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tristan2828/ui-foundation",
-  "version": "3.19.0",
+  "version": "3.20.1",
   "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": {