@tristan2828/ui-foundation 3.25.0 → 3.27.0

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

@@ -61,6 +61,18 @@ is a filled-in example while the Widgets demo is still here).
   written before the view existed has neither: ask the developer whether
   to add them before step 1. The reference files build the table *with* a
   view, where Edit and Delete live, so the table has no row actions.
+- **`Screens: list, edited in the row`** is a small entity with no view
+  and no form: build the contract, gateway, mocks and table as below, but
+  no view, form or `/new`, `/:id`, `/:id/edit` routes. Its table follows
+  cell pattern 18, "In a table's rows": each field's cell an
+  `EditableValue` over the shared control from `<entity>-fields.tsx` and
+  `useEdit<Entity>Field`, `InlineCreate` in the toolbar for create, a
+  delete row action with its confirm dialog, and `width="content"` if the
+  plan's List screen says so. There's no reference file in the template
+  for this shape; the pattern's code is the reference. Its specs: each
+  cell kind saves, a refusal stays in its cell, one cell at a time, the
+  leave prompt, create (Enter, a blank name, a taken one), delete, and
+  the in-place a11y states for a cell open and refused, in both themes.
 
 1. **Add `<Entity>` to `openapi.yaml`** — schema, list, get, create, update,
    delete — exactly as the plan specifies: its fields, types, required
@@ -490,6 +502,8 @@ is a filled-in example while the Widgets demo is still here).
   the in-place a11y block unless the plan has an `Edit in place` line,
   and then only for the fields it names.
 
+- `width="content"` on `DataTable` unless the plan's List screen says
+  `Width: content` (the Widgets table is wide and leaves it out).
 - The saved-views row in `widgets-table.tsx` (`VIEWS`, the "Saved views"
   button group and `visibleColumns`) unless the plan's List screen lists
   saved views. When it does, copy it: `useTableUrlState`'s third argument

package/conventions/docs/cell-patterns.md

@@ -819,6 +819,88 @@ The row's fields are one component shared with the form
 (`WidgetChecklistItemFields` in `widget-fields.tsx`), each field named by
 position ("Item 2 text") as the row buttons name the item.
 
+### In a table's rows
+
+For a **small entity edited in its table** (a name and a few fields,
+with no view page and no form: the plan's `Screens: list, edited in the
+row`), every editable cell is an editable value, exactly as on a view.
+`DataTable` runs it: one cell open at a time, the leave-page prompt while
+one is open, "Saving…" and a refusal in the cell. There's no pencil
+column and no edit route.
+
+- **A cell** is `<EditableValue label="<Column> of <name>" layout="inline"
+  edit={editInPlace({ ... })}>`, its shown value the cell as it always
+  was. The label names the column and the row, so its pencil reads "Edit
+  Colour of Work" and its control "Colour of Work". The kinds are the
+  same: `text` (Enter saves), `choice` (the list opens with it, non-modal,
+  a pick saves), `multi`.
+- **A cell is a component** (`<Entity><Field>Cell`) that calls
+  `useEdit<Entity>Field(row.id)` for its save, the view's single-field
+  save. A hook can't be called inside a column definition.
+- **Stable columns and row ids.** Make the column definitions once
+  (at module level, or `useMemo`) and give
+  `DataTable` a `getRowId`: new definitions every render, or rows keyed
+  by position, remount an open cell and lose what's typed.
+- **Create is `InlineCreate`** in the toolbar: the new record's name, Enter
+  or Add. It's created with every other field at its default (say which in
+  the plan) and appears as a row, edited like the others; the box empties
+  and keeps the caret for the next one. The name's rule is the form's
+  (`schema`), and a refusal (a taken name's 422) shows under the box.
+- **Delete** stays a row action: a trash button in a pinned last column
+  (`pinLastColumn`), with its confirm dialog.
+- **Few short columns?** `width="content"` (below) keeps the row's cells
+  and its delete together on a wide screen.
+
+```tsx
+// A cell is its own component, so it can call the record's save hook.
+function CategoryColourCell({ category }: { category: Category }) {
+  const editField = useEditCategoryField(category.id)       // optimistic: false, toastOnError: false
+  return (
+    <EditableValue label={`Colour of ${category.name}`} layout="inline"
+      edit={editInPlace({
+        kind: 'choice',
+        value: category.colour,
+        schema: categoryFormSchema.shape.colour,
+        save: (colour) => editField.mutateAsync({ colour }),
+        control: (props) => (
+          <CategoryColourSelect id={props.id} value={props.value} onChange={(colour) => props.commit(colour)}
+            readOnly={props.disabled} defaultOpen modal={false} onOpenChange={(open) => !open && props.cancel()}
+            aria-label={props.label} aria-describedby={props.describedBy} />
+        ),
+      })}>
+      <ColourSwatch colour={category.colour} />
+    </EditableValue>
+  )
+}
+
+// Made once: the cells read the row they're given.
+const CATEGORY_COLUMNS: LegacyColumnDef<Category, unknown>[] = [
+  { id: 'name', header: 'Name', cell: ({ row }) => <CategoryNameCell category={row.original} /> },
+  { id: 'colour', header: 'Colour', cell: ({ row }) => <CategoryColourCell category={row.original} /> },
+  { id: 'actions', header: () => <span className="sr-only">Actions</span>, cell: ({ row }) => <DeleteCategoryAction category={row.original} /> },
+]
+
+<DataTable columns={CATEGORY_COLUMNS} getRowId={(row) => String(row.id)} width="content" pinFirstColumn pinLastColumn
+  toolbar={<InlineCreate label="New category's name" schema={categoryFormSchema.shape.name}
+    create={(name) => createCategory.mutateAsync({ name, colour: 'blue', icon: 'house' })} />} … />
+```
+
+The worked example is the package's Storybook story `app/DataTable`
+"Edit in the rows" (`data-table.stories.tsx`); the template has no small
+entity yet.
+
+### A table of a few short columns: `width="content"`
+
+On a wide screen a table of three to five short columns (a name, a
+colour, a count, its delete) spreads them across the page, and the
+row's actions end up far from its name. `width="content"` sizes such a
+table to its columns once its area is 80rem or wider, never under 36rem,
+with the toolbar and pagination at the same width. Below 80rem, and on a
+phone, it's the full width as always. While it's loading, empty or
+failed after a load, it keeps the width it last had, so paging and
+filtering don't move it; only the first load can. A table that grows
+wide (many columns) has no reason to opt in.
+
 ## 19. Stage circle for an ordered status
 
 A status that's an ordered lifecycle (each record moves through the same

package/conventions/docs/design-language.md

@@ -125,30 +125,38 @@ that lets people pick a colour stores the slot's name (an enum of
 `category-1` … `category-12` in its contract, with a CHECK on the column)
 and maps each to its whole class the same way.
 
-| Slots | What they are | Near info's blue |
-|---|---|---|
-| 1–8 | eight hues, about 25° apart | 1, 6, 8 |
-| 9–12 | deeper shades of four of those hues: 9 teal (4's), 10 plum (5's), 11 olive (3's), 12 violet (2's) | none |
+| Slot | Colour | Slot | Colour |
+|---|---|---|---|
+| 1 | blue (near info) | 7 | teal |
+| 2 | orange | 8 | red |
+| 3 | green | 9 | gold |
+| 4 | purple | 10 | navy |
+| 5 | pink | 11 | lime |
+| 6 | brown | 12 | magenta |
+
+Every slot is a colour with its own name: no two blues, no two teals. So
+in a picker, label each with its name ("Orange"), not its number.
 
 Five things about them:
 
-- **The hues avoid red, green and amber**, which the tones already spend. A
-  category drawn in red reads as "this one is bad" even when nothing is
-  wrong. Info's blue came later, and slots 1, 6 and 8 sit near it: a table
-  that shows an info badge keeps its categories off those three, so a blue
-  genre isn't read as "notice this". That still leaves nine.
-- **They are ordered by distinctness, not by hue angle.** An app using
-  three categories gets three obviously different colours. Past about five,
-  hue alone stops separating them — slots 3 and 7 are both yellow-greens —
-  so the glyph has to carry the meaning and the colour only reinforces it.
-- **Past eight, it's lightness, not hue.** The hues left between the tones
-  are spent, so slots 9–12 are darker shades of four of the first eight, in
-  both themes. Each is at least as far from every other slot as the first
-  eight are from each other (a unit test holds every pair to it), but a
-  deep shade beside its own hue is told apart by how dark it is, which
-  reads less readily than a hue. Use them for a set that really has more
-  than eight values, and keep a shade away from its own hue where you can
-  choose (10 isn't 5's neighbour in a list).
+- **Chosen to be told apart, not spaced by hue.** They use the whole hue
+  circle and vary lightness and chroma as well, so a light lime sits next
+  to a deep navy rather than two mid-tone hues 25° apart. Every pair is at
+  least 17.9 apart in CIEDE2000 ΔE (the perceived difference; 10 and up
+  reads as a different colour), in both themes. A unit test holds every
+  pair to 15.
+- **A category is not a tone.** Red, orange, brown and green are slots
+  because a category is a tinted glyph beside its name, never a status
+  badge, and doesn't read as good or bad there. Where it still could, keep
+  them apart: a column that shows tone badges doesn't tint its categories
+  in the same column, and a table that shows an info badge keeps its
+  categories off slot 1, the one near info's blue.
+- **They are ordered for small sets.** An app using the first few gets the
+  most separable few, for everyone: the first six also stay apart (ΔE 10
+  or more, tested) for readers with deuteranopia or protanopia, the common
+  red-green deficiencies. Past six, some pairs merge for those readers
+  (gold and lime are nearly one colour), so the glyph and the name carry
+  the meaning and the colour only reinforces it.
 - **Tint the glyph, never fill behind text.** The label stays
   `text-foreground`, so readability never depends on the hue. A slot used
   as a background needs its own contrast check, which nothing here does
@@ -157,12 +165,13 @@ Five things about them:
   non-text minimum in both themes, on the page and on a card (recorded in
   `theme.css`). axe checks text contrast, not icon contrast, so the
   package's Storybook glyph check draws an icon in each slot on both
-  surfaces (`patterns/CategoricalColour`, which also shows them side by
-  side) and fails a change that takes one below 3:1.
+  surfaces (`patterns/CategoricalColour`) and fails a change that takes
+  one below 3:1. Its `SideBySide` story shows both themes at once, under
+  normal vision and simulated deuteranopia and protanopia.
 
 If you find yourself wanting a thirteenth, that is a sign the column should
 be showing a shape or a label rather than more colours: there is no more
-room in hue or lightness that stays readable.
+room that stays readable.
 
 ## Typography
 

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

@@ -111,6 +111,9 @@ per list; delete the section if there are none.
 | All tasks | none | dueDate asc | |
 | Bugs | kind = bug | dueDate asc | title, severity, assignee, dueDate |
 
+- Width (optional): `content` for a table of a few short columns, so on a
+  wide screen it takes the width they need rather than the whole page
+  (cell pattern 18, "`width="content"`"). Leave it out for the full width.
 - Anything else the table must show or do:
 
 ## View screen
@@ -176,7 +179,12 @@ except the quick actions, if any.
 ## Screens and access
 
 - Screens: list, view, create, edit, delete (the shape the playbook
-  builds).
+  builds). Or, for a small entity (a name and a few fields, no page of
+  its own): `list, edited in the row`, with no View screen section. Every
+  field the table shows is edited in its cell, a new record is created
+  from its name in the table's toolbar (say what every other field
+  starts as), and delete is a row action (cell pattern 18, "In a table's
+  rows").
 - Ownership: **shared** (every signed-in user sees every record) or
   **per-user** (each user sees only their own).
 

package/dist/components/app/data-table.d.ts

@@ -60,5 +60,16 @@ export type DataTableProps<TData extends Record<string, unknown>> = {
      * view is active, which can leave out a column only one view shows.
      */
     visibleColumns?: readonly string[];
+    /**
+     * `full` (the default): the table, its toolbar and its pagination take
+     * the whole width. `content`, for a table of a few short columns: on a
+     * wide screen (a table area of 80rem or more) they take the width the
+     * columns need, never under 36rem, with the row actions right after the
+     * last column. Below that, as `full`. While loading, empty or failed
+     * after a load, it keeps the width it last had, so paging and filtering
+     * don't move it (only the first load can).
+     */
+    width?: DataTableWidth;
 };
-export declare function DataTable<TData extends Record<string, unknown>>({ columns, data, total, page, pageSize, onPageChange, sorting, onSortingChange, isLoading, error, onRetry, emptyTitle, emptyDescription, emptyAction, toolbar, getRowId, pinFirstColumn, pinLastColumn, enableSortingRemoval, visibleColumns, }: DataTableProps<TData>): import("react").JSX.Element;
+export type DataTableWidth = 'full' | 'content';
+export declare function DataTable<TData extends Record<string, unknown>>({ columns, data, total, page, pageSize, onPageChange, sorting, onSortingChange, isLoading, error, onRetry, emptyTitle, emptyDescription, emptyAction, toolbar, getRowId, pinFirstColumn, pinLastColumn, enableSortingRemoval, visibleColumns, width, }: DataTableProps<TData>): import("react").JSX.Element;

package/dist/components/app/data-table.js

@@ -10,7 +10,7 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
 // pagination tree-shakeable and independently swappable, which buys nothing
 // here: every row model is manual (the server sorts and pages), so this
 // table never uses TanStack's own sorted/paginated row models at all.
-import { useEffect, useRef, useState } from 'react';
+import { useEffect, useLayoutEffect, useRef, useState, useSyncExternalStore } from 'react';
 import { flexRender } from '@tanstack/react-table';
 import { cn } from 'cn';
 import { getCoreRowModel, useLegacyTable } from '@tanstack/react-table/legacy';
@@ -19,6 +19,9 @@ import { ErrorState } from './error-state.js';
 import { Button } from '../ui/button.js';
 import { Empty, EmptyDescription, EmptyHeader, EmptyTitle } from '../ui/empty.js';
 import { Skeleton } from '../ui/skeleton.js';
+import { EditInPlaceContext } from './edit-in-place.js';
+import { EditInPlaceStore } from './edit-in-place-store.js';
+import { LeaveGuard } from './editable-value.js';
 import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow, } from '../ui/table.js';
 // A column def's id as TanStack resolves it (constructColumn): `id`, then
 // `accessorKey` with dots as underscores, then a string header. Group
@@ -71,6 +74,12 @@ const PINNED_FIRST_CONTENT_CLASS = 'max-md:max-w-[45cqw] max-md:whitespace-norma
 // background so it reads identically on striped and unstriped rows, and it
 // stays on screen when the table is scrolled right.
 const ROW_GROUP_CLASS = 'group/row hover:bg-transparent';
+// `width="content"`: from a table area 80rem wide, as wide as the columns
+// need (`w-fit` over the table's own `w-full`), at least 36rem, or the
+// width it last had loaded while it shows another state
+// (--data-table-last-width), at most the area. Narrower, no change.
+const CONTENT_WIDTH_CLASS = '@7xl/data-table:w-fit @7xl/data-table:max-w-full ' +
+    '@7xl/data-table:min-w-[max(36rem,var(--data-table-last-width,0px))]';
 // A second horizontal scrollbar, stuck to the viewport's bottom edge. The
 // real one sits directly under the last row, which on a full page is
 // off-screen until you have already scrolled past every row. Only rendered
@@ -133,7 +142,13 @@ function useBottomScrollbar(containerRef, isSuccessView) {
     }, [containerRef, isSuccessView, isOverflowing]);
     return { barRef, isOverflowing, scrollWidth };
 }
-export function DataTable({ columns, data, total, page, pageSize, onPageChange, sorting, onSortingChange, isLoading, error, onRetry, emptyTitle, emptyDescription, emptyAction, toolbar, getRowId, pinFirstColumn, pinLastColumn, enableSortingRemoval, visibleColumns, }) {
+export function DataTable({ columns, data, total, page, pageSize, onPageChange, sorting, onSortingChange, isLoading, error, onRetry, emptyTitle, emptyDescription, emptyAction, toolbar, getRowId, pinFirstColumn, pinLastColumn, enableSortingRemoval, visibleColumns, width = 'full', }) {
+    // Editing in place in the rows (cell pattern 18, "In a table's rows"):
+    // a cell that renders an <EditableValue> edits where it's shown, one at
+    // a time, with the leave-page prompt while one is open, the same rules
+    // as a record's view.
+    const [store] = useState(() => new EditInPlaceStore());
+    const openField = useSyncExternalStore(store.subscribe, () => store.open, () => store.open);
     const pageCount = Math.max(1, Math.ceil(total / pageSize));
     // TanStack treats a column missing from this map as visible, so every
     // column gets an entry once a list is given.
@@ -171,15 +186,34 @@ export function DataTable({ columns, data, total, page, pageSize, onPageChange,
     }, [isPastLastPage, pageCount, onPageChange]);
     const isEmpty = !isLoading && !error && data.length === 0 && !isPastLastPage;
     const isSuccessView = !error && !isLoading && !isPastLastPage && !isEmpty;
+    // `width="content"`: the width the table last had loaded, kept while it
+    // shows another state.
+    const root = useRef(null);
+    const [lastWidth, setLastWidth] = useState(null);
+    useLayoutEffect(() => {
+        const element = root.current;
+        if (width !== 'content' || !isSuccessView || !element)
+            return;
+        const observer = new ResizeObserver(() => setLastWidth(Math.round(element.getBoundingClientRect().width)));
+        observer.observe(element);
+        return () => observer.disconnect();
+    }, [width, isSuccessView]);
     const containerRef = useRef(null);
     const { barRef, isOverflowing, scrollWidth } = useBottomScrollbar(containerRef, Boolean(pinFirstColumn) && isSuccessView);
-    return (_jsxs("div", { className: "flex flex-col gap-4", children: [toolbar, error ? (_jsx(ErrorState, { error: error, onRetry: onRetry })) : isLoading || isPastLastPage ? (_jsx(TableSkeleton, { columnCount: table.getVisibleLeafColumns().length })) : isEmpty ? (_jsxs(Empty, { "data-state": "empty", children: [_jsxs(EmptyHeader, { children: [_jsx(EmptyTitle, { children: emptyTitle }), emptyDescription && _jsx(EmptyDescription, { children: emptyDescription })] }), emptyAction] })) : (_jsxs(_Fragment, { children: [_jsxs(Table, { "data-state": "success", containerRef: containerRef, 
+    const content = (_jsxs("div", { ref: root, className: cn('flex flex-col gap-4', width === 'content' && CONTENT_WIDTH_CLASS), "data-width": width, style: width === 'content' && !isSuccessView && lastWidth !== null
+            ? { '--data-table-last-width': `${lastWidth}px` }
+            : undefined, children: [toolbar, error ? (_jsx(ErrorState, { error: error, onRetry: onRetry })) : isLoading || isPastLastPage ? (_jsx(TableSkeleton, { columnCount: table.getVisibleLeafColumns().length })) : isEmpty ? (_jsxs(Empty, { "data-state": "empty", children: [_jsxs(EmptyHeader, { children: [_jsx(EmptyTitle, { children: emptyTitle }), emptyDescription && _jsx(EmptyDescription, { children: emptyDescription })] }), emptyAction] })) : (_jsxs(_Fragment, { children: [_jsxs(Table, { "data-state": "success", containerRef: containerRef, 
                         // With the sticky bar below as the visible scrollbar, hide the
                         // container's own. It stays overflow-x-auto and fully
                         // scrollable (wheel, trackpad, drag, and the sync effect); it
                         // just no longer draws a bar directly under the last row.
                         containerClassName: cn(pinFirstColumn &&
-                            '@container [scrollbar-width:none] [&::-webkit-scrollbar]:hidden'), children: [_jsx(TableHeader, { children: table.getHeaderGroups().map((headerGroup) => (_jsx(TableRow, { children: headerGroup.headers.map((header, index) => {
+                            '@container [scrollbar-width:none] [&::-webkit-scrollbar]:hidden', 
+                        // A size container has no width of its own to give, so
+                        // `width="content"` couldn't fit the table. Its query only
+                        // serves a phone-width rule, and an 80rem table area never
+                        // is one.
+                        width === 'content' && '@7xl/data-table:[container-type:normal]'), children: [_jsx(TableHeader, { children: table.getHeaderGroups().map((headerGroup) => (_jsx(TableRow, { children: headerGroup.headers.map((header, index) => {
                                         const canSort = header.column.getCanSort();
                                         const sortDirection = header.column.getIsSorted();
                                         const content = header.isPlaceholder ? null : canSort ? (_jsxs("button", { type: "button", className: cn('flex items-center gap-1 text-foreground', header.column.columnDef.meta?.align === 'center' && 'w-full justify-center'), onClick: header.column.getToggleSortingHandler(), children: [flexRender(header.column.columnDef.header, header.getContext()), sortDirection === 'asc' ? (_jsx(ArrowUpIcon, { className: "size-3.5 text-muted-foreground" })) : sortDirection === 'desc' ? (_jsx(ArrowDownIcon, { className: "size-3.5 text-muted-foreground" })) : (_jsx(ArrowUpDownIcon, { className: "size-3.5 text-muted-foreground/50" }))] })) : (flexRender(header.column.columnDef.header, header.getContext()));
@@ -195,4 +229,5 @@ export function DataTable({ columns, data, total, page, pageSize, onPageChange,
                                     }) }, headerGroup.id))) }), _jsx(TableBody, { children: table.getRowModel().rows.map((row) => (_jsx(TableRow, { className: cn(pinFirstColumn && ROW_GROUP_CLASS), children: row.getVisibleCells().map((cell, index) => (_jsx(TableCell, { className: cn(pinFirstColumn && index === 0 && PINNED_COLUMN_CLASS, pinLastColumn &&
                                             index === row.getVisibleCells().length - 1 &&
                                             PINNED_LAST_COLUMN_CLASS, cell.column.columnDef.meta?.align === 'center' && 'text-center'), children: pinFirstColumn && index === 0 ? (_jsx("div", { className: PINNED_FIRST_CONTENT_CLASS, children: flexRender(cell.column.columnDef.cell, cell.getContext()) })) : (flexRender(cell.column.columnDef.cell, cell.getContext())) }, cell.id))) }, row.id))) })] }), pinFirstColumn && isOverflowing && (_jsx("div", { ref: barRef, "aria-hidden": "true", tabIndex: -1, "data-slot": "bottom-scrollbar", className: "sticky bottom-0 z-20 h-4 overflow-x-auto border-t border-border bg-background", children: _jsx("div", { style: { width: scrollWidth, height: 1 } }) })), _jsxs("div", { className: "flex items-center justify-between", children: [_jsxs("p", { className: "type-body text-muted-foreground", children: [total === 0 ? 0 : (page - 1) * pageSize + 1, '–', Math.min(page * pageSize, total), " of ", total] }), _jsxs("div", { className: "flex items-center gap-2", children: [_jsx(Button, { variant: "outline", size: "icon-sm", "aria-label": "Previous page", disabled: page <= 1, onClick: () => onPageChange(page - 1), children: _jsx(ChevronLeftIcon, {}) }), _jsxs("span", { className: "type-body text-muted-foreground", children: ["Page ", page, " of ", pageCount] }), _jsx(Button, { variant: "outline", size: "icon-sm", "aria-label": "Next page", disabled: page >= pageCount, onClick: () => onPageChange(page + 1), children: _jsx(ChevronRightIcon, {}) })] })] })] }))] }));
+    return (_jsxs(EditInPlaceContext.Provider, { value: store, children: [openField !== null && _jsx(LeaveGuard, { store: store }), width === 'content' ? _jsx("div", { className: "@container/data-table", children: content }) : content] }));
 }

package/dist/components/app/inline-create.d.ts

@@ -0,0 +1,30 @@
+type SafeParse = (value: unknown) => {
+    success: true;
+    data: unknown;
+} | {
+    success: false;
+    error: {
+        issues: readonly {
+            message: string;
+        }[];
+    };
+};
+export type InlineCreateProps = {
+    /** What the box is for, e.g. "New category's name": its accessible name and placeholder. */
+    label: string;
+    /** The button's text. Defaults to "Add". */
+    addLabel?: string;
+    /** The form's rule for the field (`<entity>FormSchema.shape.name`). Its output is what `create` gets. */
+    schema?: {
+        safeParse: SafeParse;
+    };
+    /**
+     * Creates the record from the name: the entity's create mutation's
+     * `mutateAsync`, with the other fields at their defaults. Rejects with the
+     * AppError; a 422's field error shows under the box.
+     */
+    create: (value: string) => Promise<unknown>;
+    className?: string;
+};
+export declare function InlineCreate({ label, addLabel, schema, create, className }: InlineCreateProps): import("react").JSX.Element;
+export {};

package/dist/components/app/inline-create.js

@@ -0,0 +1,54 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// Creates a record from its name, in a table's toolbar: the way in for a
+// small entity edited in its rows (cell pattern 18, "In a table's rows").
+// The rest of the new record's fields start at their defaults and are
+// edited in its row like any other.
+//
+// - Enter or Add creates it. While it saves the box is read-only and Add
+//   shows a spinner; then the box empties and keeps the caret, so a run of
+//   records goes in from the keyboard, and a status line says what was added.
+// - A name the form's schema refuses is never sent; a refusal from the
+//   server (a 422's field error, word for word) shows under the box with
+//   what was typed kept.
+import { PlusIcon } from 'lucide-react';
+import { useId, useRef, useState } from 'react';
+import { cn } from 'cn';
+import { Button } from '../ui/button.js';
+import { Field, FieldError } from '../ui/field.js';
+import { Input } from '../ui/input.js';
+import { Spinner } from '../ui/spinner.js';
+import { messageOf } from './edit-in-place-store.js';
+export function InlineCreate({ label, addLabel = 'Add', schema, create, className }) {
+    const id = useId();
+    const input = useRef(null);
+    const [value, setValue] = useState('');
+    const [error, setError] = useState(null);
+    const [saving, setSaving] = useState(false);
+    const [added, setAdded] = useState('');
+    const submit = async (event) => {
+        event.preventDefault();
+        if (saving)
+            return;
+        const parsed = schema ? schema.safeParse(value) : { success: true, data: value.trim() };
+        if (!parsed.success) {
+            setError(parsed.error.issues[0]?.message ?? 'Check this value.');
+            return;
+        }
+        const name = String(parsed.data);
+        setSaving(true);
+        setError(null);
+        try {
+            await create(name);
+            setValue('');
+            setAdded(`Added ${name}`);
+        }
+        catch (refusal) {
+            setError(messageOf(refusal));
+        }
+        finally {
+            setSaving(false);
+            input.current?.focus();
+        }
+    };
+    return (_jsxs("form", { onSubmit: submit, noValidate: true, className: cn('flex items-start gap-2', className), "data-slot": "inline-create", children: [_jsxs(Field, { "data-invalid": error !== null, className: "w-72 max-w-full", children: [_jsx(Input, { ref: input, value: value, readOnly: saving, placeholder: label, "aria-label": label, "aria-invalid": error !== null, "aria-describedby": error !== null ? `${id}-error` : undefined, onChange: (event) => setValue(event.target.value) }), error !== null && (_jsx(FieldError, { id: `${id}-error`, className: "type-caption", children: error }))] }), _jsxs(Button, { type: "submit", variant: "outline", disabled: saving, children: [saving ? _jsx(Spinner, { "aria-hidden": "true", className: "size-4" }) : _jsx(PlusIcon, {}), addLabel] }), _jsx("span", { role: "status", className: "sr-only", children: saving ? 'Adding…' : added })] }));
+}

package/dist/index.d.ts

@@ -1,12 +1,13 @@
 export { AppShell, type AppShellProps, type NavItem } from './components/app/app-shell.js';
 export { CountLink, type CountLinkProps } from './components/app/count-link.js';
-export { DataTable, type DataTableProps, type SortingState } from './components/app/data-table.js';
+export { DataTable, type DataTableProps, type DataTableWidth, type SortingState } from './components/app/data-table.js';
 export { EntityForm, type EntityFormProps } from './components/app/entity-form.js';
 export { EntityView, type EntityViewField, type EntityViewLayout, type EntityViewPlacement, type EntityViewProps, type EntityViewSection, } from './components/app/entity-view.js';
 export { editInPlace, type EditControlProps, type EditInPlace, type EditInPlaceList, type EditInPlaceListOptions, type EditInPlaceOptions, type EditKind, type EditListItemProps, } from './components/app/edit-in-place.js';
 export { DataEnvironmentBanner } from './components/app/data-environment-banner.js';
 export { EditableValue, type EditableValueProps } from './components/app/editable-value.js';
 export { ErrorState } from './components/app/error-state.js';
+export { InlineCreate, type InlineCreateProps } from './components/app/inline-create.js';
 export { FoundationProviders } from './components/app/foundation-providers.js';
 export { Markdown, type MarkdownProps } from './components/app/markdown.js';
 export { MockModeBanner } from './components/app/mock-mode-banner.js';

package/dist/index.js

@@ -12,6 +12,7 @@ export { editInPlace, } from './components/app/edit-in-place.js';
 export { DataEnvironmentBanner } from './components/app/data-environment-banner.js';
 export { EditableValue } from './components/app/editable-value.js';
 export { ErrorState } from './components/app/error-state.js';
+export { InlineCreate } from './components/app/inline-create.js';
 export { FoundationProviders } from './components/app/foundation-providers.js';
 export { Markdown } from './components/app/markdown.js';
 export { MockModeBanner } from './components/app/mock-mode-banner.js';

package/package.json

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

package/styles/theme.css

@@ -66,54 +66,50 @@
    * to a slot in its own columns file, so a new enum value costs a line
    * there rather than three tokens here.
    *
-   * Hues avoid the red and green bands that destructive/success already
-   * spend, and the amber that warning does — a category drawn in red reads
-   * as "bad". The blue slots (1, 6, 8) sit near info's hue, which came
-   * later: a table using info keeps its categories off those three. They are ordered by distinctness, not by hue angle, so an app
-   * using only the first three gets three obviously different colours.
-   * Past about five, hue alone stops separating them and the glyph has to
-   * carry the meaning; see docs/design-language.md. Twelve slots in all.
+   * Chosen to be told apart (#108), not spaced by hue: twelve colours a
+   * person names differently, from the whole hue circle, with lightness and
+   * chroma varied per slot as well as hue. Red, orange, brown and green are
+   * in: a category is a tinted glyph beside its name, never a status badge,
+   * so it doesn't read as a tone (design-language.md says where that still
+   * matters). Slot 1 (blue) sits near info's hue; a table using info keeps
+   * its categories off it.
    *
-   * Ratios are against the page, measured (WCAG 2.x, sRGB), and all clear
-   * the 3:1 non-text minimum in both themes with room to spare (4.5:1 at
-   * the least, slots 9-12 on the dark card). axe does NOT check icon
-   * contrast; the Storybook glyph check re-measures every slot on the
-   * page and on a card (design-language/CategoricalColour).
-   */
-  --category-1-700: oklch(0.5 0.15 240);
-  --category-1-400: oklch(0.78 0.12 240);
-  --category-2-700: oklch(0.5 0.15 300);
-  --category-2-400: oklch(0.78 0.12 300);
-  --category-3-700: oklch(0.5 0.15 95);
-  --category-3-400: oklch(0.78 0.12 95);
-  --category-4-700: oklch(0.5 0.15 190);
-  --category-4-400: oklch(0.78 0.12 190);
-  --category-5-700: oklch(0.5 0.15 330);
-  --category-5-400: oklch(0.78 0.12 330);
-  --category-6-700: oklch(0.5 0.15 265);
-  --category-6-400: oklch(0.78 0.12 265);
-  --category-7-700: oklch(0.5 0.15 120);
-  --category-7-400: oklch(0.78 0.12 120);
-  --category-8-700: oklch(0.5 0.15 215);
-  --category-8-400: oklch(0.78 0.12 215);
-  /*
-   * Slots 9-12 are a second channel, not new hues: the hues left between
-   * the tones' are already spent ~25 degrees apart, so these are deeper
-   * shades of the four that sit furthest from info (teal, plum, olive,
-   * violet), darker than their slot in both themes. Each is at least as
-   * far from its nearest slot (OKLab distance) as slots 1-8 are from each
-   * other; tests/category-slots.test.ts holds every pair to that. A deep
-   * shade of the blues or the yellow-green fell to half that distance, so
-   * twelve is where it stops. Chroma is the most each holds in sRGB.
+   * Every pair is at least 17.9 apart in CIEDE2000 ΔE in both themes (the
+   * hue-spaced slots before them got to 8.8); tests/category-slots.test.ts
+   * holds every pair to 15. They are ordered so the first few stay apart
+   * under deuteranopia and protanopia too (the first six are 12 apart);
+   * past that, the glyph has to carry the meaning for those readers.
+   *
+   * Ratios are against the page, measured (WCAG 2.x, sRGB): all clear the
+   * 3:1 non-text minimum in both themes (3.75:1 at the least, orange and
+   * teal on white). axe does NOT check icon contrast; the Storybook glyph
+   * check re-measures every slot on the page and on a card
+   * (patterns/CategoricalColour).
    */
-  --category-9-700: oklch(0.36 0.06 190);
-  --category-9-400: oklch(0.62 0.1 190);
-  --category-10-700: oklch(0.36 0.12 330);
-  --category-10-400: oklch(0.62 0.15 330);
-  --category-11-700: oklch(0.36 0.07 95);
-  --category-11-400: oklch(0.62 0.12 95);
-  --category-12-700: oklch(0.36 0.14 300);
-  --category-12-400: oklch(0.62 0.17 300);
+  --category-1-700: oklch(0.44 0.11 245); /* blue */
+  --category-1-400: oklch(0.626 0.156 245);
+  --category-2-700: oklch(0.627 0.161 52); /* orange */
+  --category-2-400: oklch(0.722 0.16 52);
+  --category-3-700: oklch(0.492 0.105 152); /* green */
+  --category-3-400: oklch(0.763 0.17 152);
+  --category-4-700: oklch(0.55 0.254 305); /* purple */
+  --category-4-400: oklch(0.772 0.116 305);
+  --category-5-700: oklch(0.615 0.144 7); /* pink */
+  --category-5-400: oklch(0.812 0.102 7);
+  --category-6-700: oklch(0.445 0.1 56); /* brown */
+  --category-6-400: oklch(0.602 0.054 56);
+  --category-7-700: oklch(0.599 0.104 183); /* teal */
+  --category-7-400: oklch(0.849 0.139 183);
+  --category-8-700: oklch(0.503 0.176 27); /* red */
+  --category-8-400: oklch(0.646 0.152 27);
+  --category-9-700: oklch(0.573 0.115 84); /* gold */
+  --category-9-400: oklch(0.87 0.136 84);
+  --category-10-700: oklch(0.362 0.203 279); /* navy */
+  --category-10-400: oklch(0.601 0.164 279);
+  --category-11-700: oklch(0.593 0.121 119); /* lime */
+  --category-11-400: oklch(0.823 0.163 119);
+  --category-12-700: oklch(0.423 0.181 337); /* magenta */
+  --category-12-400: oklch(0.648 0.232 337);
   --blue-500: oklch(0.488 0.243 264.376);
 
   --radius-base: 0.625rem;