@tristan2828/ui-foundation 4.39.0 → 4.41.0

package/conventions/docs/cell-patterns.md

@@ -26,14 +26,14 @@
   - [A variant: a pressed icon inside another value's cell](#a-variant-a-pressed-icon-inside-another-values-cell) · lines 564–647
 - [16. Title linking to the record's view](#16-title-linking-to-the-records-view) · lines 649–684
 - [17. Quick action on the view](#17-quick-action-on-the-view) · lines 686–759
-- [18. Editable value](#18-editable-value) · lines 761–1176
-  - [A list of sub-items](#a-list-of-sub-items) · lines 1020–1077
-  - [In a table's rows](#in-a-tables-rows) · lines 1079–1164
-  - [A table of a few short columns: `width="content"`](#a-table-of-a-few-short-columns-widthcontent) · lines 1166–1176
-- [19. Stage circle for an ordered status](#19-stage-circle-for-an-ordered-status) · lines 1178–1244
-- [20. Count linking to the related records](#20-count-linking-to-the-related-records) · lines 1246–1310
-- [21. Rows grouped under headings, and a pill filter](#21-rows-grouped-under-headings-and-a-pill-filter) · lines 1312–1377
-- [22. A highlighted row, and rows that are done](#22-a-highlighted-row-and-rows-that-are-done) · lines 1379–1407
+- [18. Editable value](#18-editable-value) · lines 761–1207
+  - [A list of sub-items](#a-list-of-sub-items) · lines 1023–1108
+  - [In a table's rows](#in-a-tables-rows) · lines 1110–1195
+  - [A table of a few short columns: `width="content"`](#a-table-of-a-few-short-columns-widthcontent) · lines 1197–1207
+- [19. Stage circle for an ordered status](#19-stage-circle-for-an-ordered-status) · lines 1209–1275
+- [20. Count linking to the related records](#20-count-linking-to-the-related-records) · lines 1277–1341
+- [21. Rows grouped under headings, and a pill filter](#21-rows-grouped-under-headings-and-a-pill-filter) · lines 1343–1408
+- [22. A highlighted row, and rows that are done](#22-a-highlighted-row-and-rows-that-are-done) · lines 1410–1438
 
 <!-- /index -->
 
@@ -781,8 +781,11 @@ the form stay.
 **At rest: says it's editable without shouting.** The value reads as it
 always did. Hover tints it (`bg-muted`) and shows a pencil; the pencil is
 a real button ("Edit <label>"), so Tab reaches it and Enter opens the
-field, and its focus ring tints the value too. On a touch screen the
-pencil always shows. A click anywhere on the value opens it, except on a
+field, and its focus ring tints the value too. Muted text inside it (the
+view's "Not set", a "No caption", a done item) turns `text-foreground`
+on that tint, since muted on `bg-muted` is under 4.5:1; the package does
+it, so an app just uses `text-muted-foreground` as anywhere else. On a
+touch screen the pencil always shows. A click anywhere on the value opens it, except on a
 link inside it (a reference to a record with a view, a link in the
 notes), which still navigates.
 
@@ -1056,6 +1059,14 @@ Checklist is the reference (`checklist` in `widgetEdits`). It's built on
   option is still inside the row, and Enter in the row's text box or
   leaving the row saves the item, ids only on the wire. A new item starts
   with no pick, which the list's schema refuses on that row.
+- **Items that come from elsewhere** (a record's files, added by upload):
+  `add` in place of `newItem` and `addLabel`. It renders the app's own
+  control (an "Add files" button over a hidden file input) and is given
+  `add(items)`, which saves them at the end through `save`, as a move is
+  ("Saving…", a refusal under the list, the caret back on the control),
+  plus `items` (to stop at a limit), `disabled` (a change is saving) and
+  `onProblem(message)` (an upload refused, under the list). Each item
+  then reads, edits, moves and removes like a checklist's.
 
 ```tsx
 const checklist = editInPlace<ChecklistItem>({
@@ -1076,6 +1087,26 @@ 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.
 
+A list added by upload:
+
+```tsx
+const files = editInPlace<Attachment>({
+  kind: 'list',
+  value: record.attachments,
+  save: (change) => editField.mutateAsync((current) => ({ attachments: change(current.attachments) })),
+  itemName: (index) => record.attachments[index]?.name ?? `file ${index + 1}`,
+  add: ({ add, items, disabled, onProblem }) => (
+    <UploadButton                                           // the app's: a button over <input type="file" hidden>
+      disabled={disabled || items.length >= MAX}
+      onUploaded={(stored) => add(stored.map(toAttachment))}
+      onRefused={(error) => onProblem(error.message)}
+    />
+  ),
+  renderShown: (file) => <FileRow file={file} />,           // its thumbnail, name and caption
+  renderItem: (props) => <CaptionInput {...props} />,       // what edits on a click: the caption
+})
+```
+
 ### In a table's rows
 
 For a **small entity edited in its table** (a name and a few fields,

package/conventions/docs/design-language.md

@@ -3,20 +3,21 @@
 <!-- index: written by `npm run docs:index` in the package from the headings below; never edit it by hand -->
 ## Index
 
-- [Semantic tones](#semantic-tones) · lines 29–57
-- [The three badge styles](#the-three-badge-styles) · lines 59–76
-- [Mapping an enum to tones](#mapping-an-enum-to-tones) · lines 78–107
-- [Glyphs and icons: 3:1](#glyphs-and-icons-31) · lines 109–122
-- [Logos and brand marks](#logos-and-brand-marks) · lines 124–168
-- [Categorical colour](#categorical-colour) · lines 170–240
-- [Typography](#typography) · lines 242–324
-  - [Written text (notes)](#written-text-notes) · lines 273–324
-- [Density](#density) · lines 326–383
-- [Widget cards (hub pages)](#widget-cards-hub-pages) · lines 385–463
-- [Module cards (a hub's places)](#module-cards-a-hubs-places) · lines 465–523
-- [Notices](#notices) · lines 525–553
-- [A value over time](#a-value-over-time) · lines 555–588
-- [A list as a board](#a-list-as-a-board) · lines 590–641
+- [Semantic tones](#semantic-tones) · lines 30–58
+- [The three badge styles](#the-three-badge-styles) · lines 60–77
+- [Mapping an enum to tones](#mapping-an-enum-to-tones) · lines 79–108
+- [Glyphs and icons: 3:1](#glyphs-and-icons-31) · lines 110–123
+- [Logos and brand marks](#logos-and-brand-marks) · lines 125–169
+- [Categorical colour](#categorical-colour) · lines 171–241
+- [Typography](#typography) · lines 243–325
+  - [Written text (notes)](#written-text-notes) · lines 274–325
+- [Density](#density) · lines 327–384
+- [Widget cards (hub pages)](#widget-cards-hub-pages) · lines 386–464
+- [Module cards (a hub's places)](#module-cards-a-hubs-places) · lines 466–524
+- [Notices](#notices) · lines 526–554
+- [A value over time](#a-value-over-time) · lines 556–589
+- [A list as a board](#a-list-as-a-board) · lines 591–642
+- [A list as cards](#a-list-as-cards) · lines 644–690
 
 <!-- /index -->
 
@@ -639,3 +640,51 @@ the table's.
   columns share the width, at least 16rem each, and scroll sideways with
   snap points; a phone shows one column at a time, with the edge of the
   next one showing.
+
+## A list as cards
+
+`DataTable`'s `layouts` (4.39) draw the same rows as cards beside the
+table: a thumbnail grid for a feed, covers for a collection, a dense line
+each for clearing a backlog. They are layouts of one list, not other
+pages: the toolbar, filters, saved views, paging and `groupBy` headings
+are the table's in every one, and so are its loading, empty and error
+states.
+
+```tsx
+const { layout, setLayout } = useTableLayout({
+  layouts: ['table', 'covers'],
+  defaultLayout: 'covers',
+  storageKey: 'my-app:books:layout',
+})
+
+<DataTable
+  {...tableProps}
+  layouts={[{ id: 'covers', label: 'Covers', icon: LayoutGridIcon, size: 'sm', aspect: '2:3', renderCard: (book) => <BookCard book={book} /> }]}
+  layout={layout}
+  onLayoutChange={setLayout}
+/>
+```
+
+- **The switch** sits at the end of the toolbar, the table first (rename
+  it with `tableLayout`, "Rows" for a list-like table with no header).
+  The pick is in the URL (`?layout=`) and remembered per table on the
+  device, so name the `storageKey` for the list. A list opens on the
+  layout it is read in most: covers for something browsed by its art, the
+  table for something compared by its columns.
+- **A grid's sizes** are the package's: `sm` for covers (three across on
+  a phone), `md` for thumbnails (two), `lg` for big ones (one). `list`
+  is one card per line in a bordered box, divided like rows.
+- **The picture** is `Artwork`: a fixed shape (2:3 posters and books,
+  1:1 square art, 16:9 video), the record's image or a neutral
+  placeholder (the list's icon, and the title where most records have no
+  picture), so the grid's rows stay even. Its corners hold an
+  `ArtworkTag` (a length, "Live") and an `ArtworkToggle`, a round button
+  that marks the record (Read, Owned): dark on the picture while off,
+  success's fill while on.
+- **The card holds what the row does**: the title as the link to the
+  record (cell pattern 16), the list's key line in muted text, then its
+  status, rating or quality as the table's own cells draw them, and the
+  same actions. A card leaves an empty value out rather than showing a
+  dash. Never an action only one layout has.
+- `totals` and `highlightRow` are the table's alone. Sorting is the
+  toolbar's in a card layout (there is no header to click).

package/dist/components/app/artwork.d.ts

@@ -0,0 +1,43 @@
+import { type ReactNode } from 'react';
+import type { IconComponent } from './icon-component.js';
+export type ArtworkAspect = '2:3' | '1:1' | '16:9';
+export type ArtworkProps = {
+    /** The image's URL; null or undefined for the placeholder. */
+    src?: string | null;
+    alt?: string;
+    aspect: ArtworkAspect;
+    /** The placeholder's icon (the list's own: a book, a die); a picture icon when left out. */
+    placeholderIcon?: IconComponent;
+    /** Words under the placeholder's icon, often the title, for a grid where most records have no picture. */
+    placeholderLabel?: ReactNode;
+    topStart?: ReactNode;
+    topEnd?: ReactNode;
+    bottomStart?: ReactNode;
+    bottomEnd?: ReactNode;
+    /** Dims the picture (a watched video), never its overlays. */
+    dimmed?: boolean;
+    className?: string;
+};
+export declare function Artwork({ src, alt, aspect, placeholderIcon: PlaceholderIcon, placeholderLabel, topStart, topEnd, bottomStart, bottomEnd, dimmed, className, }: ArtworkProps): import("react").JSX.Element;
+/**
+ * A small label on a picture (a length, "Live", "Short"): the page's
+ * foreground as its background, so it reads on any image in either theme.
+ */
+export declare function ArtworkTag({ children, className }: {
+    children: ReactNode;
+    className?: string;
+}): import("react").JSX.Element;
+export type ArtworkToggleProps = {
+    /** What it marks, with the record ("Read: Saga"), for a screen reader and the tooltip. */
+    label: string;
+    pressed: boolean;
+    onPressedChange: (pressed: boolean) => void;
+    icon: IconComponent;
+    disabled?: boolean;
+};
+/**
+ * A round button on a picture that marks the record (Read, Owned): dark
+ * on the picture while off, success's solid fill while on, so it reads on
+ * any image. Goes in one of Artwork's corners.
+ */
+export declare function ArtworkToggle({ label, pressed, onPressedChange, icon: Icon, disabled }: ArtworkToggleProps): import("react").JSX.Element;

package/dist/components/app/artwork.js

@@ -0,0 +1,43 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// A card's picture (DataTable's card layouts): a box of a fixed shape, a
+// poster's 2:3, a square cover's 1:1 or a video's 16:9, holding the
+// record's image, or a neutral placeholder when it has none (or it fails
+// to load), so a grid of cards keeps its rows even. Overlays sit on top:
+// `topStart`/`topEnd`/`bottomStart`/`bottomEnd` corners for a badge, a
+// length, or a round button such as Read or Owned.
+//
+// The image is decorative by default (`alt=""`): the card's title, beside
+// it, already names the record. Give `alt` only when the picture says
+// something the card doesn't.
+import { useState } from 'react';
+import { ImageIcon } from 'lucide-react';
+import { cn } from 'cn';
+const ASPECT_CLASS = {
+    '2:3': 'aspect-[2/3]',
+    '1:1': 'aspect-square',
+    '16:9': 'aspect-video',
+};
+const CORNER_CLASS = 'absolute z-10 flex items-center gap-1';
+export function Artwork({ src, alt = '', aspect, placeholderIcon: PlaceholderIcon = ImageIcon, placeholderLabel, topStart, topEnd, bottomStart, bottomEnd, dimmed, className, }) {
+    // The src that failed, so a new one gets its own try.
+    const [failed, setFailed] = useState(null);
+    const showImage = Boolean(src) && failed !== src;
+    return (_jsxs("div", { "data-slot": "artwork", "data-aspect": aspect, className: cn('relative w-full overflow-hidden rounded-md bg-muted', ASPECT_CLASS[aspect], className), children: [showImage ? (_jsx("img", { src: src ?? undefined, alt: alt, loading: "lazy", decoding: "async", onError: () => setFailed(src ?? null), className: cn('size-full object-cover', dimmed && 'opacity-55') })) : (_jsxs("div", { "data-slot": "artwork-placeholder", className: cn('flex size-full flex-col items-center justify-center gap-2 p-3 text-center text-muted-foreground', dimmed && 'opacity-55'), children: [_jsx(PlaceholderIcon, { "aria-hidden": "true", className: "size-6 shrink-0" }), placeholderLabel && (_jsx("span", { className: "type-caption line-clamp-3 text-balance text-foreground", children: placeholderLabel }))] })), topStart && _jsx("div", { className: cn(CORNER_CLASS, 'top-1.5 left-1.5'), children: topStart }), topEnd && _jsx("div", { className: cn(CORNER_CLASS, 'top-1.5 right-1.5'), children: topEnd }), bottomStart && _jsx("div", { className: cn(CORNER_CLASS, 'bottom-1.5 left-1.5'), children: bottomStart }), bottomEnd && _jsx("div", { className: cn(CORNER_CLASS, 'right-1.5 bottom-1.5'), children: bottomEnd })] }));
+}
+/**
+ * A small label on a picture (a length, "Live", "Short"): the page's
+ * foreground as its background, so it reads on any image in either theme.
+ */
+export function ArtworkTag({ children, className }) {
+    return (_jsx("span", { "data-slot": "artwork-tag", className: cn('rounded-sm bg-foreground/85 px-1 font-mono text-[0.6875rem] leading-4 font-medium text-background tabular-nums', className), children: children }));
+}
+/**
+ * A round button on a picture that marks the record (Read, Owned): dark
+ * on the picture while off, success's solid fill while on, so it reads on
+ * any image. Goes in one of Artwork's corners.
+ */
+export function ArtworkToggle({ label, pressed, onPressedChange, icon: Icon, disabled }) {
+    return (_jsx("button", { type: "button", "aria-pressed": pressed, "aria-label": label, title: label, disabled: disabled, onClick: () => onPressedChange(!pressed), className: cn('grid size-8 place-items-center rounded-full outline-none focus-visible:ring-3 focus-visible:ring-ring/50', 'disabled:pointer-events-none disabled:opacity-50', pressed
+            ? 'bg-success text-success-foreground hover:bg-success/90'
+            : 'bg-foreground/85 text-background hover:bg-foreground'), children: _jsx(Icon, { "aria-hidden": "true", className: "size-4" }) }));
+}

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

@@ -2,6 +2,8 @@ import { type ReactNode } from 'react';
 import type { CellData, RowData, TableFeatures } from '@tanstack/react-table';
 import { type LegacyColumnDef } from '@tanstack/react-table/legacy';
 import type { AppError } from '../../api/contracts.js';
+import type { ArtworkAspect } from './artwork.js';
+import type { IconComponent } from './icon-component.js';
 import { type RowGroup } from './table-groups.js';
 export type SortingState = {
     id: string;
@@ -107,6 +109,52 @@ export type DataTableProps<TData extends Record<string, unknown>> = {
      * has come) for no row.
      */
     totals?: DataTableTotals | null;
+    /**
+     * Card layouts besides the table (a thumbnail grid, covers, one line
+     * each), and a switch between them at the end of the toolbar, the table
+     * first. Each draws a row with its own `renderCard`; paging, `groupBy`
+     * headings and the loading, empty and error states hold in every one.
+     * The columns still define the table, and sorting is the toolbar's in a
+     * card layout. `totals` and `highlightRow` are the table's alone.
+     */
+    layouts?: readonly DataTableCardLayout<TData>[];
+    /**
+     * The layout showing: `'table'` or a card layout's id, from
+     * useTableLayout (the URL's `?layout=`, then the one remembered for this
+     * table, then its default). An id the table doesn't have shows the table.
+     * Left out, the switch keeps its own state, starting on the table.
+     */
+    layout?: string;
+    onLayoutChange?: (layout: string) => void;
+    /** The table's own entry in the switch: "Table" with a table icon unless set ("Rows", for a list-like table). */
+    tableLayout?: {
+        label?: string;
+        icon?: IconComponent;
+    };
+};
+/** One of DataTable's card layouts (`layouts`). */
+export type DataTableCardLayout<TData> = {
+    /** In the URL (`?layout=covers`) and remembered, so keep it short and stable. */
+    id: string;
+    /** The switch's word for it ("Covers"); its accessible name on a phone, where only the icon shows. */
+    label: string;
+    icon: IconComponent;
+    /** A row as a card. Everything it holds is the app's: the picture (Artwork), the title link, the actions. */
+    renderCard: (row: TData) => ReactNode;
+    /**
+     * `grid` (the default): cards side by side, as many across as fit, the
+     * package's sizing from the table's width; `list`: one card per line,
+     * divided like rows, for a dense one-line-each layout.
+     */
+    arrange?: 'grid' | 'list';
+    /**
+     * A grid card's width: `sm` covers (about 8.5rem, three across on a
+     * phone), `md` (the default) thumbnails (11rem, two on a phone), `lg`
+     * big thumbnails (14rem, one on a phone).
+     */
+    size?: 'sm' | 'md' | 'lg';
+    /** The picture's shape, for the loading skeleton's cards: 16:9 unless set. */
+    aspect?: ArtworkAspect;
 };
 export type DataTableWidth = 'full' | 'content';
 export type DataTableTotals = {
@@ -119,4 +167,4 @@ export type DataTableTotals = {
      */
     cells?: Partial<Record<string, ReactNode>>;
 };
-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, groupBy, groupSummary, header: showHeader, highlightRow, totals, }: DataTableProps<TData>): import("react").JSX.Element;
+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, groupBy, groupSummary, header: showHeader, highlightRow, totals, layouts, layout: layoutProp, onLayoutChange, tableLayout, }: DataTableProps<TData>): import("react").JSX.Element;

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

@@ -14,11 +14,12 @@ import { useEffect, useLayoutEffect, useRef, useState, useSyncExternalStore } fr
 import { flexRender } from '@tanstack/react-table';
 import { cn } from 'cn';
 import { getCoreRowModel, useLegacyTable } from '@tanstack/react-table/legacy';
-import { ArrowDownIcon, ArrowUpIcon, ArrowUpDownIcon, ChevronLeftIcon, ChevronRightIcon } from 'lucide-react';
+import { ArrowDownIcon, ArrowUpIcon, ArrowUpDownIcon, ChevronLeftIcon, ChevronRightIcon, TableIcon } from 'lucide-react';
 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 { ToggleGroup, ToggleGroupItem } from '../ui/toggle-group.js';
 import { EditInPlaceContext } from './edit-in-place.js';
 import { EditInPlaceStore } from './edit-in-place-store.js';
 import { LeaveGuard } from './editable-value.js';
@@ -38,6 +39,41 @@ function leafColumnIds(columns) {
         return id === undefined ? [] : [id];
     });
 }
+// A card grid's columns: as many of the size as the table's width holds,
+// and a fixed count on a phone-width table (`@container/data-table-cards`,
+// under 28rem), where minimum widths would leave one lonely column.
+const CARD_GRID_CLASS = {
+    sm: 'grid-cols-[repeat(auto-fill,minmax(8.5rem,1fr))] @max-md/data-table-cards:grid-cols-3',
+    md: 'grid-cols-[repeat(auto-fill,minmax(11rem,1fr))] @max-md/data-table-cards:grid-cols-2',
+    lg: 'grid-cols-[repeat(auto-fill,minmax(14rem,1fr))] @max-md/data-table-cards:grid-cols-1',
+};
+const CARD_GRID_GAP_CLASS = 'gap-x-4 gap-y-6 @max-md/data-table-cards:gap-x-2.5 @max-md/data-table-cards:gap-y-4';
+// A `list` layout: rows in a bordered box, divided as the table's are.
+const CARD_LIST_CLASS = 'divide-y divide-border overflow-hidden rounded-lg border border-border';
+const SKELETON_ASPECT_CLASS = {
+    '2:3': 'aspect-[2/3]',
+    '1:1': 'aspect-square',
+    '16:9': 'aspect-video',
+};
+function CardsSkeleton({ layout }) {
+    if (layout.arrange === 'list') {
+        return (_jsx("div", { className: cn(CARD_LIST_CLASS, 'flex flex-col'), "data-state": "loading", children: Array.from({ length: 6 }, (_, index) => (_jsxs("div", { className: "flex items-center gap-3 px-3 py-2", children: [_jsx(Skeleton, { className: "size-6 shrink-0 rounded-full" }), _jsx(Skeleton, { className: "h-4 flex-1" })] }, index))) }));
+    }
+    return (_jsx("div", { className: "@container/data-table-cards", "data-state": "loading", children: _jsx("div", { className: cn('grid', CARD_GRID_CLASS[layout.size ?? 'md'], CARD_GRID_GAP_CLASS), children: Array.from({ length: 8 }, (_, index) => (_jsxs("div", { className: "flex flex-col gap-2", children: [_jsx(Skeleton, { className: cn('w-full rounded-md', SKELETON_ASPECT_CLASS[layout.aspect ?? '16:9']) }), _jsx(Skeleton, { className: "h-4 w-4/5" }), _jsx(Skeleton, { className: "h-3 w-1/2" })] }, index))) }) }));
+}
+// The layout switch: a toggle group (one tab stop, the arrow keys along
+// it), the pressed one in the muted fill with the foreground's colour and
+// medium weight, the others in muted text, so the difference isn't the
+// fill alone. On a phone only the icons show; the label stays their name.
+const LAYOUT_ITEM_CLASS = 'gap-1.5 text-muted-foreground aria-pressed:bg-muted aria-pressed:font-medium aria-pressed:text-foreground';
+function LayoutSwitch({ options, value, onValueChange, }) {
+    return (_jsx(ToggleGroup, { "aria-label": "Layout", variant: "outline", size: "sm", spacing: 0, "data-slot": "data-table-layout-switch", value: [value], onValueChange: (next) => {
+            // [] is the pressed one pressed again: it stays on.
+            const chosen = next[0];
+            if (chosen !== undefined && chosen !== value)
+                onValueChange(chosen);
+        }, children: options.map(({ id, label, icon: Icon }) => (_jsxs(ToggleGroupItem, { value: id, className: LAYOUT_ITEM_CLASS, title: label, children: [_jsx(Icon, { "aria-hidden": "true", className: "size-4" }), _jsx("span", { className: "max-sm:sr-only", children: label })] }, id))) }));
+}
 function TableSkeleton({ columnCount }) {
     return (_jsx("div", { className: "flex flex-col gap-2 p-2", "data-state": "loading", children: Array.from({ length: 5 }, (_, row) => (_jsx("div", { className: "flex gap-4", children: Array.from({ length: columnCount }, (_, col) => (_jsx(Skeleton, { className: "h-8 flex-1" }, col))) }, row))) }));
 }
@@ -172,7 +208,17 @@ 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, width = 'full', groupBy, groupSummary, header: showHeader = true, highlightRow, totals, }) {
+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', groupBy, groupSummary, header: showHeader = true, highlightRow, totals, layouts, layout: layoutProp, onLayoutChange, tableLayout, }) {
+    // The switch's own state, for a table that doesn't pass `layout`.
+    const [ownLayout, setOwnLayout] = useState('table');
+    const requestedLayout = layoutProp ?? ownLayout;
+    const cardLayout = layouts?.find((candidate) => candidate.id === requestedLayout);
+    const currentLayout = cardLayout?.id ?? 'table';
+    const setLayout = (next) => {
+        if (layoutProp === undefined)
+            setOwnLayout(next);
+        onLayoutChange?.(next);
+    };
     // 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
@@ -229,15 +275,18 @@ export function DataTable({ columns, data, total, page, pageSize, onPageChange,
         return () => observer.disconnect();
     }, [width, isSuccessView]);
     const containerRef = useRef(null);
-    const { barRef, isOverflowing, scrollWidth } = useBottomScrollbar(containerRef, Boolean(pinFirstColumn) && isSuccessView);
+    const { barRef, isOverflowing, scrollWidth } = useBottomScrollbar(containerRef, Boolean(pinFirstColumn) && isSuccessView && !cardLayout);
     const rows = table.getRowModel().rows;
     const visibleLeafColumns = table.getVisibleLeafColumns();
     const visibleColumnCount = visibleLeafColumns.length;
     // One body row, the same in a plain table and a grouped one.
     const renderRow = (row) => (_jsx(TableRow, { "data-highlighted": highlightRow?.(row.original) || undefined, className: cn(pinFirstColumn && ROW_GROUP_CLASS, highlightRow?.(row.original) && HIGHLIGHTED_ROW_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, alignClass(cell.column.columnDef.meta?.align)), 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));
-    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
+    const content = (_jsxs("div", { ref: root, className: cn('flex flex-col gap-4', width === 'content' && CONTENT_WIDTH_CLASS), "data-width": width, "data-layout": layouts?.length ? currentLayout : undefined, 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, 
+            : undefined, children: [layouts?.length ? (_jsxs("div", { className: "flex flex-wrap items-end gap-x-4 gap-y-2", children: [_jsx("div", { className: "min-w-0 flex-1", children: toolbar }), _jsx(LayoutSwitch, { options: [
+                            { id: 'table', label: tableLayout?.label ?? 'Table', icon: tableLayout?.icon ?? TableIcon },
+                            ...layouts,
+                        ], value: currentLayout, onValueChange: setLayout })] })) : (toolbar), error ? (_jsx(ErrorState, { error: error, onRetry: onRetry })) : isLoading || isPastLastPage ? (cardLayout ? (_jsx(CardsSkeleton, { layout: cardLayout })) : (_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: [cardLayout ? (_jsx(Cards, { layout: cardLayout, rows: rows, groupBy: groupBy, groupSummary: groupSummary })) : (_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
@@ -269,6 +318,15 @@ export function DataTable({ columns, data, total, page, pageSize, onPageChange,
                                     }) }, headerGroup.id))) }), groupBy ? (groupRuns(rows, (row) => groupBy(row.original)).map((run, runIndex) => (_jsxs(TableBody, { "data-slot": "table-group", children: [_jsx(TableRow, { "data-slot": "table-group-heading", className: "hover:bg-transparent", children: _jsx(TableHead, { scope: "rowgroup", colSpan: visibleColumnCount, className: GROUP_HEADING_CLASS, children: _jsxs("span", { className: "sticky left-(--table-cell-px) inline-flex items-baseline gap-2", children: [_jsx("span", { className: "type-label text-foreground", children: run.label }), groupSummary && (_jsx("span", { className: "type-caption text-muted-foreground tabular-nums", children: groupSummary(run.rows.map((row) => row.original)) }))] }) }) }), _jsx("tr", { hidden: true, "aria-hidden": "true", "data-slot": "table-group-stripe-offset" }), run.rows.map(renderRow)] }, `${runIndex}:${run.key}`)))) : (_jsx(TableBody, { children: rows.map(renderRow) })), totals && (_jsx(TableFooter, { className: TOTALS_FOOTER_CLASS, children: _jsx(TableRow, { "data-slot": "table-totals", className: "hover:bg-transparent", children: visibleLeafColumns.map((column, index) => {
                                         const className = cn(pinFirstColumn && index === 0 && PINNED_TOTALS_LABEL_CLASS, pinLastColumn && index === visibleColumnCount - 1 && PINNED_LAST_COLUMN_CLASS, alignClass(column.columnDef.meta?.align));
                                         return index === 0 ? (_jsx(TableHead, { scope: "row", className: cn(TOTALS_LABEL_CLASS, className), children: pinFirstColumn ? (_jsx("div", { className: PINNED_FIRST_CONTENT_CLASS, children: totals.label })) : (totals.label) }, column.id)) : (_jsx(TableCell, { className: className, children: totals.cells?.[column.id] }, column.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, {}) })] })] })] }))] }));
+                                    }) }) }))] })), pinFirstColumn && isOverflowing && !cardLayout && (_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: [editing && _jsx(LeaveGuard, { store: store }), width === 'content' ? _jsx("div", { className: "@container/data-table", children: content }) : content] }));
 }
+// A card layout's success view: the rows as cards in a grid or a list,
+// each run of one group (`groupBy`) under its own heading, as the table's
+// heading rows are, with the same label and summary.
+function Cards({ layout, rows, groupBy, groupSummary, }) {
+    const list = (items) => (_jsx("ul", { role: "list", className: cn(layout.arrange === 'list' ? CARD_LIST_CLASS : ['grid', CARD_GRID_CLASS[layout.size ?? 'md'], CARD_GRID_GAP_CLASS]), children: items.map((row) => (_jsx("li", { "data-slot": "data-table-card", className: "min-w-0", children: layout.renderCard(row.original) }, row.id))) }));
+    return (_jsx("div", { className: "@container/data-table-cards flex flex-col gap-6", "data-state": "success", "data-slot": "data-table-cards", children: groupBy
+            ? groupRuns(rows, (row) => groupBy(row.original)).map((run, runIndex) => (_jsxs("section", { "data-slot": "table-group", className: "flex flex-col gap-3", children: [_jsxs("h2", { "data-slot": "table-group-heading", className: "flex items-baseline gap-2 border-b border-border pb-1.5", children: [_jsx("span", { className: "type-label text-foreground", children: run.label }), groupSummary && (_jsx("span", { className: "type-caption text-muted-foreground tabular-nums", children: groupSummary(run.rows.map((row) => row.original)) }))] }), list(run.rows)] }, `${runIndex}:${run.key}`)))
+            : list(rows) }));
+}

package/dist/components/app/edit-in-place.d.ts

@@ -123,14 +123,31 @@ export type EditListItemProps<TItem> = EditControlProps<TItem> & {
     /** The item being added at the end, not one already in the list. */
     isNew: boolean;
 };
+/** What a list's own `add` is given: how to put new items at the end, saved as the list's other changes are. */
+export type EditListAddProps<TItem> = {
+    /**
+     * Saves these items at the end of the list, through the list's `save`
+     * (built on its latest list, after whatever is open and whatever is
+     * still saving). "Saving…" and a refusal show under the list, as for a
+     * move. Resolves once it's done: `true` saved, `false` refused.
+     */
+    add: (items: TItem[]) => Promise<boolean>;
+    /** The list as saved: to stop adding at a limit (`items.length >= max`). */
+    items: readonly TItem[];
+    /** A change is saving: the list's buttons wait, and so should this one. */
+    disabled: boolean;
+    /** Why the add can't happen (an upload refused), under the list where a refused save shows; `null` clears it. */
+    onProblem: (message: string | null) => void;
+};
 /**
- * A list of sub-items edited in place (a checklist, a list of links), on
- * a `content` section of EntityView. Make one with `editInPlace({ kind:
- * 'list', ... })`. Every item reads as `renderShown` (a quick action, such
- * as its done box, still works there); clicking it or its pencil turns it
- * into `renderItem`, the form's own row. "Add" at the end opens a new item;
- * move up, move down and remove are ListEditor's buttons. Each change is one
- * save of the whole list.
+ * A list of sub-items edited in place (a checklist, a list of links, a
+ * record's files), on a `content` section of EntityView. Make one with
+ * `editInPlace({ kind: 'list', ... })`. Every item reads as `renderShown`
+ * (a quick action, such as its done box, still works there); clicking it
+ * or its pencil turns it into `renderItem`, the form's own row. "Add" at
+ * the end opens a new item (`newItem`), or the app's own `add` puts items
+ * there (an upload); move up, move down and remove are ListEditor's
+ * buttons. Each change is one save of the whole list.
  */
 export type EditInPlaceListOptions<TItem> = {
     kind: 'list';
@@ -145,12 +162,19 @@ export type EditInPlaceListOptions<TItem> = {
     renderItem: (props: EditListItemProps<TItem>) => ReactNode;
     /** How the item reads when it isn't being edited. Its own controls (a done box) keep working. */
     renderShown: (item: TItem, index: number) => ReactNode;
-    /** A blank item, what "Add" starts from. */
-    newItem: () => TItem;
+    /** A blank item, what "Add" starts from. Not needed with `add`; one or the other is. */
+    newItem?: () => TItem;
+    /**
+     * In place of "Add" and its blank item: what adds items, such as a file
+     * upload or a picker, e.g. a button that uploads, then calls
+     * `props.add(stored.map(toItem))`. The items save at the end of the list
+     * through `save`, so they read, move and save like any other.
+     */
+    add?: (props: EditListAddProps<TItem>) => ReactNode;
     /** How the buttons name an item, as on the form: (i) => `item ${i + 1}` gives "Move item 2 up". */
     itemName: (index: number) => string;
-    /** The Add button's text, e.g. "Add item". */
-    addLabel: string;
+    /** The Add button's text, e.g. "Add item". Not needed with `add`, whose control has its own. */
+    addLabel?: string;
     /**
      * The form's schema for the whole list (`widgetFormSchema.shape.checklist`).
      * Each change is checked as the list it would make; a message about an
@@ -169,7 +193,8 @@ export type EditInPlaceListOptions<TItem> = {
     save: (change: (current: TItem[]) => TItem[]) => Promise<unknown>;
 };
 /** A list marked editable in place. Make one with `editInPlace({ kind: 'list', ... })`. */
-export type EditInPlaceList = Omit<EditInPlaceListOptions<unknown>, 'renderItem' | 'renderShown' | 'schema' | 'save'> & {
+export type EditInPlaceList = Omit<EditInPlaceListOptions<unknown>, 'renderItem' | 'renderShown' | 'schema' | 'save' | 'add'> & {
+    add?: (props: EditListAddProps<unknown>) => ReactNode;
     renderItem: (props: EditListItemProps<unknown>) => ReactNode;
     renderShown: (item: unknown, index: number) => ReactNode;
     schema?: {

package/dist/components/app/editable-list.js

@@ -9,7 +9,8 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 //   form's row (`renderItem`), an EditableValue like any field: leaving or
 //   Enter saves, Esc gives up, one field open at a time.
 // - "Add" at the end opens a new item the same way. Enter saves it and
-//   opens the next, so a run of items goes in from the keyboard.
+//   opens the next, so a run of items goes in from the keyboard. Or the
+//   app's own `add` (an upload) puts items at the end, saved as a move is.
 // - Move and remove save at once. Whatever is open is saved first; while
 //   the change saves, the buttons wait, "Saving…" shows under the list,
 //   and a refusal leaves the list as it was with the reason under it.
@@ -56,16 +57,22 @@ function checkItem(edit, items, index, draft) {
     const issue = issues.find(({ path }) => path?.[0] === index) ?? issues.find(({ path }) => !path?.length) ?? issues[0];
     return { success: false, error: { issues: issue ? [issue] : [] } };
 }
+// The app's own add, as a component of its own: it renders the app's
+// control with what it's given, and holds nothing.
+function ListAdd({ render, ...props }) {
+    return _jsx("div", { "data-list-add-slot": "", children: render(props) });
+}
 export function EditableList({ label, edit, emptyLabel }) {
     const store = useContext(EditInPlaceContext);
     if (!store)
         throw new Error('A list edited in place works inside an <EntityView>, which runs editing in place.');
     const items = edit.value;
     const statusId = useId();
-    const [status, setStatus] = useState({ saving: false, error: null });
+    const [status, setStatus] = useState({ saving: false, inFlight: 0, error: null });
     // The buttons are disabled while a change saves, which drops the caret.
     // Once the list shows the outcome it goes to the first of these buttons
-    // (by name) that's there and enabled, else to Add.
+    // (by name) that's there and enabled, else to Add (or the app's add's
+    // first button).
     const root = useRef(null);
     const focusNext = useRef(null);
     useEffect(() => {
@@ -75,26 +82,30 @@ export function EditableList({ label, edit, emptyLabel }) {
         focusNext.current = null;
         const buttons = [...(root.current?.querySelectorAll('button:not(:disabled)') ?? [])];
         const target = names.map((name) => buttons.find((button) => button.getAttribute('aria-label') === name)).find(Boolean);
-        (target ?? root.current?.querySelector('[data-list-add]:not(:disabled)'))?.focus();
+        (target ?? root.current?.querySelector('[data-list-add]:not(:disabled), [data-list-add-slot] button:not(:disabled)'))?.focus();
     }, [items, status.saving]);
-    // Move and remove: save the open field first (if it can't save, it stays
-    // and nothing else happens), then the change.
-    const act = async (change, focusAfter, focusIfRefused) => {
-        if (status.saving)
-            return;
+    // Move, remove and the app's own add: save the open field first (if it
+    // can't save, it stays and nothing else happens), then the change. An
+    // add that lands while a change saves (an upload finishing) still goes:
+    // `save` builds on the latest list, and "Saving…" stays until both are done.
+    const act = async (change, focusAfter, focusIfRefused, waits = true) => {
+        if (waits && status.saving)
+            return false;
         const open = store.open;
         if (open !== null && !(await store.commit(open)))
-            return;
-        setStatus({ saving: true, error: null });
+            return false;
+        setStatus((now) => ({ saving: true, inFlight: now.inFlight + 1, error: null }));
+        let error = null;
         try {
             await edit.save(change);
             focusNext.current = focusAfter;
-            setStatus({ saving: false, error: null });
         }
-        catch (error) {
+        catch (refused) {
             focusNext.current = focusIfRefused;
-            setStatus({ saving: false, error: messageOf(error) });
+            error = messageOf(refused);
         }
+        setStatus((now) => ({ saving: now.inFlight > 1, inFlight: now.inFlight - 1, error: error ?? now.error }));
+        return error === null;
     };
     const move = (from, to) => {
         const direction = to < from ? 'up' : 'down';
@@ -124,13 +135,19 @@ export function EditableList({ label, edit, emptyLabel }) {
             return current.map((other, i) => (i === at ? item : other));
         }),
     });
+    // The app's own add: its items saved at the end, the caret back on it.
+    const addItems = (added) => added.length === 0 ? Promise.resolve(true) : act((current) => [...current, ...added], [], [], false);
+    const onProblem = (message) => setStatus((now) => ({ ...now, error: message }));
     // The item being added, at the end.
+    const newItem = edit.newItem;
+    if (!newItem && !edit.add)
+        throw new Error('A list edited in place needs `newItem` (a blank item to add) or `add` (its own control).');
     const addEdit = {
         kind: 'text',
-        value: edit.newItem(),
+        value: newItem?.(),
         control: (props) => _jsx(ItemRow, { children: edit.renderItem({ ...props, index: items.length, isNew: true }) }),
         schema: { safeParse: (draft) => checkItem(edit, items, items.length, draft) },
         save: (item) => edit.save((current) => [...current, item]),
     };
-    return (_jsxs("div", { ref: root, className: "flex flex-col gap-2", "data-slot": "editable-list", children: [_jsx(ListEditor, { "aria-label": label, items: items.map((_, index) => ({ id: String(index) })), itemName: edit.itemName, addLabel: edit.addLabel, emptyText: emptyLabel, disabled: status.saving, onRemove: remove, onMove: move, renderItem: (index) => (_jsx(EditableField, { label: edit.itemName(index), edit: itemEdit(index), children: edit.renderShown(items[index], index) })), add: _jsx(EditableField, { label: edit.itemName(items.length), edit: addEdit, reopenAfterKeyboardSave: true, children: null, trigger: (start) => (_jsx("div", { children: _jsxs(Button, { "data-list-add": "", type: "button", variant: "outline", size: "sm", disabled: status.saving, onClick: start, children: [_jsx(PlusIcon, {}), edit.addLabel] }) })) }) }), _jsx("span", { id: statusId, className: "type-body", children: status.saving ? (_jsxs("span", { role: "status", className: "inline-flex items-center gap-1.5 type-caption text-muted-foreground", children: [_jsx(Spinner, { "aria-hidden": "true", className: "size-3.5" }), "Saving\u2026"] })) : (status.error && _jsx(FieldError, { className: "type-caption", children: status.error })) })] }));
+    return (_jsxs("div", { ref: root, className: "flex flex-col gap-2", "data-slot": "editable-list", children: [_jsx(ListEditor, { "aria-label": label, items: items.map((_, index) => ({ id: String(index) })), itemName: edit.itemName, addLabel: edit.addLabel ?? '', emptyText: emptyLabel, disabled: status.saving, onRemove: remove, onMove: move, renderItem: (index) => (_jsx(EditableField, { label: edit.itemName(index), edit: itemEdit(index), children: edit.renderShown(items[index], index) })), add: edit.add ? (_jsx(ListAdd, { render: edit.add, add: addItems, items: items, disabled: status.saving, onProblem: onProblem })) : (_jsx(EditableField, { label: edit.itemName(items.length), edit: addEdit, reopenAfterKeyboardSave: true, children: null, trigger: (start) => (_jsx("div", { children: _jsxs(Button, { "data-list-add": "", type: "button", variant: "outline", size: "sm", disabled: status.saving, onClick: start, children: [_jsx(PlusIcon, {}), edit.addLabel] }) })) })) }), _jsx("span", { id: statusId, className: "type-body", children: status.saving ? (_jsxs("span", { role: "status", className: "inline-flex items-center gap-1.5 type-caption text-muted-foreground", children: [_jsx(Spinner, { "aria-hidden": "true", className: "size-3.5" }), "Saving\u2026"] })) : (status.error && _jsx(FieldError, { className: "type-caption", children: status.error })) })] }));
 }

package/dist/components/app/editable-value.js

@@ -206,7 +206,7 @@ export function EditableField({ label, edit, children, layout = 'block', classNa
     if (state.status === 'closed' && !always) {
         if (trigger)
             return (_jsx("span", { ref: triggerBox, className: "contents", children: trigger(start) }));
-        return (_jsxs("span", { "data-slot": "editable-value", onClick: onShownClick, className: cn('group/editable relative -mx-1.5 cursor-text items-start gap-1 rounded-md px-1.5 transition-colors hover:bg-muted has-[[data-edit]:focus-visible]:bg-muted', layout === 'block' ? 'flex w-full' : 'inline-flex max-w-full align-top', className), children: [_jsx("span", { className: "min-w-0 flex-1", children: children }), _jsx(Button, { ref: editButton, "data-edit": "", type: "button", variant: "ghost", size: "icon-xs", "aria-label": `Edit ${label}`, onClick: start, className: "shrink-0 text-muted-foreground opacity-0 group-hover/editable:opacity-100 focus-visible:opacity-100 pointer-coarse:opacity-100", children: _jsx(PencilIcon, {}) })] }));
+        return (_jsxs("span", { "data-slot": "editable-value", onClick: onShownClick, className: cn('group/editable relative -mx-1.5 cursor-text items-start gap-1 rounded-md px-1.5 transition-colors hover:bg-muted has-[[data-edit]:focus-visible]:bg-muted', layout === 'block' ? 'flex w-full' : 'inline-flex max-w-full align-top', className), children: [_jsx("span", { className: "min-w-0 flex-1 group-hover/editable:[&_.text-muted-foreground]:text-foreground group-has-[[data-edit]:focus-visible]/editable:[&_.text-muted-foreground]:text-foreground", children: children }), _jsx(Button, { ref: editButton, "data-edit": "", type: "button", variant: "ghost", size: "icon-xs", "aria-label": `Edit ${label}`, onClick: start, className: "shrink-0 text-muted-foreground opacity-0 group-hover/editable:opacity-100 focus-visible:opacity-100 pointer-coarse:opacity-100", children: _jsx(PencilIcon, {}) })] }));
     }
     // Always editable, before the store has it (the first render): the saved value.
     const open = state.status === 'closed' ? { status: 'open', draft: edit.value, error: null, autosave: undefined, revision: 0 } : state;

package/dist/hooks/use-table-layout.d.ts

@@ -0,0 +1,31 @@
+type StorageLike = Pick<Storage, 'getItem' | 'setItem'>;
+export type LayoutStore = {
+    get: (key: string) => string | null;
+    set: (key: string, value: string) => void;
+    subscribe: (key: string, listener: () => void) => () => void;
+};
+export declare function createLayoutStore(getStorage: () => StorageLike | undefined): LayoutStore;
+/** The layout to show: the URL's if the table has it, then the remembered one, then the default. */
+export declare function resolveLayout(layouts: readonly string[], fromUrl: string | null, remembered: string | null, defaultLayout: string): string;
+export type TableLayoutOptions = {
+    /** Every layout id the table has, the table's own `'table'` among them. */
+    layouts: readonly string[];
+    /** The one shown until another is picked; `'table'` when left out. */
+    defaultLayout?: string;
+    /**
+     * Where the pick is remembered on this device, one key per table: name it
+     * for the app and the list (`"my-app:comics:layout"`). Without one the
+     * pick lives only in the URL.
+     */
+    storageKey?: string;
+};
+/**
+ * `{ layout, setLayout }` for DataTable's `layout` and `onLayoutChange`.
+ * Setting one writes `?layout=` (replacing the history entry, as a filter
+ * does) and remembers it under `storageKey`.
+ */
+export declare function useTableLayout({ layouts, defaultLayout, storageKey }: TableLayoutOptions): {
+    layout: string;
+    setLayout: (next: string) => void;
+};
+export {};

package/dist/hooks/use-table-layout.js

@@ -0,0 +1,67 @@
+import { useCallback, useSyncExternalStore } from 'react';
+import { useSearchParams } from 'react-router';
+export function createLayoutStore(getStorage) {
+    const memory = new Map();
+    const listeners = new Map();
+    return {
+        get(key) {
+            const kept = memory.get(key);
+            if (kept !== undefined)
+                return kept;
+            try {
+                return getStorage()?.getItem(key) ?? null;
+            }
+            catch {
+                return null;
+            }
+        },
+        set(key, value) {
+            memory.set(key, value);
+            try {
+                getStorage()?.setItem(key, value);
+            }
+            catch {
+                // Storage blocked or full: remembered in memory for this page only.
+            }
+            for (const listener of listeners.get(key) ?? [])
+                listener();
+        },
+        subscribe(key, listener) {
+            let set = listeners.get(key);
+            if (!set)
+                listeners.set(key, (set = new Set()));
+            set.add(listener);
+            return () => set.delete(listener);
+        },
+    };
+}
+/** The layout to show: the URL's if the table has it, then the remembered one, then the default. */
+export function resolveLayout(layouts, fromUrl, remembered, defaultLayout) {
+    if (fromUrl !== null && layouts.includes(fromUrl))
+        return fromUrl;
+    if (remembered !== null && layouts.includes(remembered))
+        return remembered;
+    return defaultLayout;
+}
+const browserStore = createLayoutStore(() => (typeof window === 'undefined' ? undefined : window.localStorage));
+/**
+ * `{ layout, setLayout }` for DataTable's `layout` and `onLayoutChange`.
+ * Setting one writes `?layout=` (replacing the history entry, as a filter
+ * does) and remembers it under `storageKey`.
+ */
+export function useTableLayout({ layouts, defaultLayout = 'table', storageKey }) {
+    const [params, setParams] = useSearchParams();
+    const subscribe = useCallback((listener) => (storageKey === undefined ? () => { } : browserStore.subscribe(storageKey, listener)), [storageKey]);
+    const remembered = useSyncExternalStore(subscribe, () => (storageKey === undefined ? null : browserStore.get(storageKey)), () => null);
+    const layout = resolveLayout(layouts, params.get('layout'), remembered, defaultLayout);
+    const setLayout = useCallback((next) => {
+        if (storageKey !== undefined)
+            browserStore.set(storageKey, next);
+        setParams((previous) => {
+            const updated = new URLSearchParams(previous);
+            updated.set('layout', next);
+            return updated;
+        }, { replace: true });
+    }, [setParams, storageKey]);
+    return { layout, setLayout };
+}

package/dist/index.d.ts

@@ -1,13 +1,14 @@
 export { AppShell, type AppShellProps, type AppShellVersion, type BottomBarItem, type NavEntry, type NavItem, type NavSection, } from './components/app/app-shell.js';
 export type { IconComponent } from './components/app/icon-component.js';
 export { Board, type BoardColumn, type BoardMoveTarget, type BoardProps } from './components/app/board.js';
+export { Artwork, ArtworkTag, ArtworkToggle, type ArtworkAspect, type ArtworkProps, type ArtworkToggleProps, } from './components/app/artwork.js';
 export { CountLink, type CountLinkProps } from './components/app/count-link.js';
-export { DataTable, type DataTableProps, type DataTableTotals, type DataTableWidth, type SortingState, } from './components/app/data-table.js';
+export { DataTable, type DataTableCardLayout, type DataTableProps, type DataTableTotals, type DataTableWidth, type SortingState, } from './components/app/data-table.js';
 export { type RowGroup } from './components/app/table-groups.js';
 export { byDay, type ByDayOptions } from './lib/group-by-day.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 { editInPlace, type EditControlProps, type EditInPlace, type EditInPlaceList, type EditInPlaceListOptions, type EditInPlaceOptions, type EditKind, type EditListAddProps, 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';
@@ -51,6 +52,7 @@ export type { AppError, Page, QuerySpec } from './api/contracts.js';
 export type { ErrorReportingOptions } from './error-reporting/reporter.js';
 export { createQueryClient } from './api/query-client.js';
 export { useTableUrlState } from './hooks/use-table-url-state.js';
+export { useTableLayout, type TableLayoutOptions } from './hooks/use-table-layout.js';
 export type { TableView, UrlChanges } from './hooks/table-url-changes.js';
 export { useDebouncedValue } from './hooks/use-debounced-value.js';
 export { useDocumentTitle } from './hooks/use-document-title.js';

package/dist/index.js

@@ -5,6 +5,7 @@
 // Composites
 export { AppShell, } from './components/app/app-shell.js';
 export { Board } from './components/app/board.js';
+export { Artwork, ArtworkTag, ArtworkToggle, } from './components/app/artwork.js';
 export { CountLink } from './components/app/count-link.js';
 export { DataTable, } from './components/app/data-table.js';
 export {} from './components/app/table-groups.js';
@@ -54,6 +55,7 @@ export { AuthProvider, useAuth } from './auth/use-auth.js';
 export { createQueryClient } from './api/query-client.js';
 // Hooks
 export { useTableUrlState } from './hooks/use-table-url-state.js';
+export { useTableLayout } from './hooks/use-table-layout.js';
 export { useDebouncedValue } from './hooks/use-debounced-value.js';
 export { useDocumentTitle } from './hooks/use-document-title.js';
 export { useRecordUpdate, } from './hooks/use-record-update.js';

package/package.json

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