@tristan2828/ui-foundation 4.44.0 → 4.46.0

package/dist/components/app/widget-card.js

@@ -1,4 +1,4 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 // A small titled card on a hub page (issue #121): a few rows from one part
 // of the app, loaded on their own. It owns the four required states the
 // way DataTable and EntityView do, so every widget on a page skeletons,
@@ -24,6 +24,21 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 // where that's blocked). The body is hidden, not unmounted, so whatever
 // the app keeps in it stays put.
 //
+// `summary` (#263) is one short value a folded card shows in its header
+// ("3", "Due today"), so a hub of folded cards still reads at a glance.
+// It follows the card's state: a small skeleton while loading, a muted
+// dash ("Couldn't load" to a screen reader) on an error, `emptySummary`
+// (or nothing) when empty. Opened, the summary goes and the body shows,
+// the error in it as before. The chevron is described by it.
+//
+// WidgetCardGroup (#263) makes its cards an accordion: every card in it
+// folds, opening one folds the others, and a click anywhere on a header
+// (not on its link or another control) toggles it; the chevron stays the
+// keyboard's way in. `accordion="mobile"` does that only below the
+// sidebar's breakpoint (useIsMobile), so a desktop hub keeps each card's
+// own `collapsible`. While the accordion is on it owns the folding and a
+// card's `storageKey` is left alone.
+//
 // The header's link is an app route (`to`) or, for a widget about a
 // service outside the app, its address (`href`, #248): that one opens in a
 // new tab, with the outside-link mark and a screen reader's "(opens in a
@@ -39,7 +54,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 // a row's to 4px, for a dense hub; text stays at type-body. On a phone a
 // compact row is 44px tall and its link fills that height, so it stays a
 // finger's target.
-import { useId } from 'react';
+import { createContext, useContext, useId, useState } from 'react';
 import { Link } from 'react-router';
 import { ChevronDownIcon, ExternalLinkIcon } from 'lucide-react';
 import { cn } from 'cn';
@@ -47,21 +62,62 @@ import { ErrorState } from './error-state.js';
 import { Button } from '../ui/button.js';
 import { Card, CardContent, CardHeader } from '../ui/card.js';
 import { Skeleton } from '../ui/skeleton.js';
+import { useIsMobile } from '../../hooks/use-mobile.js';
 import { useRememberedFlag } from '../../hooks/use-remembered-flag.js';
 const HEADER_LINK_CLASS = 'shrink-0 rounded-sm type-label text-foreground underline underline-offset-4 outline-none ' +
     'hover:decoration-2 focus-visible:ring-3 focus-visible:ring-ring/50';
-export function WidgetCard({ title, icon: Icon, headingLevel = 2, link, isLoading, error, onRetry, isEmpty, emptyMessage, skeletonRows = 3, collapsible = false, defaultCollapsed = false, storageKey, children, className, }) {
+export function WidgetCard({ id, title, icon: Icon, headingLevel = 2, link, isLoading, error, onRetry, isEmpty, emptyMessage, skeletonRows = 3, collapsible = false, defaultCollapsed = false, storageKey, summary, emptySummary, children, className, }) {
     const headingId = useId();
     const contentId = useId();
+    const summaryId = useId();
+    const ownId = useId();
+    const cardId = id ?? ownId;
+    const group = useContext(GroupContext);
+    const inAccordion = group !== null && group.active;
     const Heading = `h${headingLevel}`;
     const state = error ? 'error' : isLoading ? 'loading' : isEmpty ? 'empty' : 'success';
     const [folded, setFolded] = useRememberedFlag(collapsible && storageKey !== undefined ? `${storageKey}:collapsed` : undefined, defaultCollapsed);
-    const collapsed = collapsible && folded;
-    return (_jsx("section", { "aria-labelledby": headingId, "data-slot": "widget-card", "data-state": state, "data-collapsed": collapsed || undefined, className: cn('min-w-0 self-start', className), children: _jsxs(Card, { className: "density-compact:[--card-spacing:--spacing(3)]", children: [_jsxs(CardHeader, { className: "flex items-center justify-between gap-3", children: [_jsxs(Heading, { id: headingId, className: "flex min-w-0 items-center gap-2 type-section-title text-foreground", children: [Icon && _jsx(Icon, { "aria-hidden": "true", className: "size-4 shrink-0 text-muted-foreground" }), _jsx("span", { className: "truncate", children: title })] }), (link || collapsible) && (_jsxs("div", { className: "flex shrink-0 items-center gap-1", children: [link?.href !== undefined ? (_jsxs("a", { href: link.href, target: "_blank", rel: "noreferrer", "aria-describedby": headingId, className: cn(HEADER_LINK_CLASS, 'inline-flex items-center gap-1'), children: [link.label, _jsx(ExternalLinkIcon, { "aria-hidden": "true", className: "size-3 shrink-0 text-muted-foreground" }), _jsx("span", { className: "sr-only", children: " (opens in a new tab)" })] })) : (link && (_jsx(Link, { to: link.to, "aria-describedby": headingId, className: HEADER_LINK_CLASS, children: link.label }))), collapsible && (_jsx(Button, { variant: "ghost", size: "icon-sm", "aria-labelledby": headingId, "aria-expanded": !collapsed, "aria-controls": contentId, onClick: () => setFolded(!collapsed), 
+    const collapsed = inAccordion ? group.openId !== cardId : collapsible && folded;
+    const foldable = inAccordion || collapsible;
+    const toggle = () => (inAccordion ? group.setOpenId(collapsed ? cardId : null) : setFolded(!collapsed));
+    const summaryShown = collapsed && (summary !== undefined || emptySummary !== undefined);
+    // In an accordion the whole header toggles, except where the click lands
+    // on its link or another control (the chevron toggles on its own).
+    const onHeaderClick = (event) => {
+        if (!inAccordion)
+            return;
+        if (event.target.closest('a, button, input, select, textarea, [role="switch"]'))
+            return;
+        toggle();
+    };
+    return (_jsx("section", { id: id, "aria-labelledby": headingId, "data-slot": "widget-card", "data-state": state, "data-collapsed": collapsed || undefined, className: cn('min-w-0 self-start', className), children: _jsxs(Card, { className: "density-compact:[--card-spacing:--spacing(3)]", children: [_jsxs(CardHeader, { onClick: onHeaderClick, className: cn('flex items-center justify-between gap-3', inAccordion && 'cursor-pointer select-none'), children: [_jsxs(Heading, { id: headingId, className: "flex min-w-0 items-center gap-2 type-section-title text-foreground", children: [Icon && _jsx(Icon, { "aria-hidden": "true", className: "size-4 shrink-0 text-muted-foreground" }), _jsx("span", { className: "truncate", children: title })] }), (link || foldable || summaryShown) && (_jsxs("div", { className: "flex shrink-0 items-center gap-1", children: [summaryShown && (_jsx("span", { id: summaryId, "data-slot": "widget-card-summary", className: "mr-2 flex items-center", children: _jsx(WidgetCardSummary, { state: state, summary: summary, emptySummary: emptySummary }) })), link?.href !== undefined ? (_jsxs("a", { href: link.href, target: "_blank", rel: "noreferrer", "aria-describedby": headingId, className: cn(HEADER_LINK_CLASS, 'inline-flex items-center gap-1'), children: [link.label, _jsx(ExternalLinkIcon, { "aria-hidden": "true", className: "size-3 shrink-0 text-muted-foreground" }), _jsx("span", { className: "sr-only", children: " (opens in a new tab)" })] })) : (link && (_jsx(Link, { to: link.to, "aria-describedby": headingId, className: HEADER_LINK_CLASS, children: link.label }))), foldable && (_jsx(Button, { variant: "ghost", size: "icon-sm", "aria-labelledby": headingId, "aria-describedby": summaryShown ? summaryId : undefined, "aria-expanded": !collapsed, "aria-controls": contentId, onClick: toggle, 
                                     // The button's own open look (a filled background) would
                                     // read as pressed: the chevron says it.
                                     className: "-my-1 -mr-1.5 aria-expanded:not-hover:bg-transparent", children: _jsx(ChevronDownIcon, { "aria-hidden": "true", className: cn('transition-transform', collapsed && '-rotate-90') }) }))] }))] }), _jsx(CardContent, { id: contentId, hidden: collapsed, "aria-busy": state === 'loading' || undefined, children: error ? (_jsx(ErrorState, { error: error, onRetry: onRetry, size: "compact" })) : state === 'loading' ? (_jsx(WidgetListSkeleton, { rows: skeletonRows })) : state === 'empty' ? (_jsx("p", { "data-state": "empty", className: "py-2 type-body text-muted-foreground", children: emptyMessage })) : (children) })] }) }));
 }
+// A folded card's one value, by state. Loading's skeleton is about one
+// number wide; an error's dash says "Couldn't load" to a screen reader,
+// the error itself waiting in the body.
+function WidgetCardSummary({ state, summary, emptySummary, }) {
+    if (state === 'loading') {
+        return (_jsxs(_Fragment, { children: [_jsx(Skeleton, { "data-state": "loading", className: "h-4 w-8" }), _jsx("span", { className: "sr-only", children: "Loading" })] }));
+    }
+    if (state === 'error') {
+        return (_jsxs("span", { "data-state": "error", className: "type-label text-muted-foreground", children: [_jsx("span", { "aria-hidden": "true", children: "\u2014" }), _jsx("span", { className: "sr-only", children: "Couldn't load" })] }));
+    }
+    if (state === 'empty') {
+        return emptySummary === undefined ? null : (_jsx("span", { "data-state": "empty", className: "type-label text-muted-foreground", children: emptySummary }));
+    }
+    return _jsx("span", { className: "type-label tabular-nums text-foreground", children: summary });
+}
+const GroupContext = createContext(null);
+/** Wraps a hub's WidgetCards so that opening one folds the others (on a phone only, with `accordion="mobile"`). */
+export function WidgetCardGroup({ accordion = true, defaultOpen = null, children, className }) {
+    const isMobile = useIsMobile();
+    const [openId, setOpenId] = useState(defaultOpen);
+    const active = accordion === 'mobile' ? isMobile : accordion;
+    return (_jsx(GroupContext.Provider, { value: { active, openId, setOpenId }, children: _jsx("div", { "data-slot": "widget-card-group", "data-accordion": active || undefined, className: className, children: children }) }));
+}
 // One row's height, shared by the skeleton and the list so the card doesn't
 // jump: py-2 around one line of type-body (or a small control). Compact
 // is 32px (6px around the line); on a phone it's 44px, the link's own

package/dist/components/app/widget-layout-sheet.d.ts

@@ -0,0 +1,25 @@
+import { type ReactNode } from 'react';
+import type { WidgetLayout } from '../../hooks/use-widget-layout.js';
+export interface WidgetLayoutSheetProps {
+    /** The page's layout, from useWidgetLayout. */
+    layout: WidgetLayout;
+    /** Each card's title by its id: the row's name. An id without one shows as the id. */
+    titles: Readonly<Record<string, string>>;
+    /** The sheet's heading. */
+    title?: string;
+    /** A line under the heading. */
+    description?: ReactNode;
+    /** The trigger button's label. */
+    triggerLabel?: string;
+    /** Opens and closes the sheet from outside (then the trigger can be left out with `trigger={false}`). */
+    open?: boolean;
+    /** Whether the sheet starts open, when `open` isn't given. */
+    defaultOpen?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    /** Show the Customize button; `false` when the app opens the sheet itself. */
+    trigger?: boolean;
+    /** Which side the sheet comes from: the right on a desktop, `bottom` suits a phone. */
+    side?: 'right' | 'bottom';
+    className?: string;
+}
+export declare function WidgetLayoutSheet({ layout, titles, title, description, triggerLabel, open, defaultOpen, onOpenChange, trigger, side, className, }: WidgetLayoutSheetProps): import("react").JSX.Element;

package/dist/components/app/widget-layout-sheet.js

@@ -0,0 +1,55 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// A hub page's Customize sheet (#263): every card the page has, in the
+// person's order, each row with Up and Down buttons and a Show switch,
+// and Reset at the foot. It edits a useWidgetLayout, which keeps the
+// order (on this device by default) and which the page renders its cards
+// by (`layout.visible`).
+//
+// It's the same on a phone, a desktop and a keyboard: no dragging. Up and
+// Down keep the focus on the button pressed, so pressing it again moves
+// the card on. At either end the button is `aria-disabled`, not
+// `disabled`, so the focus stays on it there too, and a polite live region
+// says where the card went ("Saved links, 1 of 3").
+//
+// The trigger is a Customize button for the page's header; pass `open`
+// and `onOpenChange` to open it from elsewhere instead.
+import { useLayoutEffect, useRef, useState } from 'react';
+import { ArrowDownIcon, ArrowUpIcon, SlidersHorizontalIcon } from 'lucide-react';
+import { cn } from 'cn';
+import { Button } from '../ui/button.js';
+import { Sheet, SheetContent, SheetDescription, SheetFooter, SheetHeader, SheetTitle, SheetTrigger, } from '../ui/sheet.js';
+import { Switch } from '../ui/switch.js';
+export function WidgetLayoutSheet({ layout, titles, title = 'Customize this page', description = 'Order the cards, and hide the ones you don’t need.', triggerLabel = 'Customize', open, defaultOpen, onOpenChange, trigger = true, side = 'right', className, }) {
+    const listRef = useRef(null);
+    const [moved, setMoved] = useState(null);
+    const [announcement, setAnnouncement] = useState('');
+    const { order, hidden } = layout;
+    const nameOf = (id) => titles[id] ?? id;
+    // Moving a row re-orders the list, which can take the focus off the
+    // button that moved it: put it back.
+    useLayoutEffect(() => {
+        if (moved === null)
+            return;
+        const button = listRef.current?.querySelector(`[data-widget-id="${CSS.escape(moved.id)}"] [data-move="${moved.by}"]`);
+        if (button && document.activeElement !== button)
+            button.focus();
+    }, [moved, order]);
+    const move = (id, by) => {
+        const from = order.indexOf(id);
+        const to = from + by;
+        if (from === -1 || to < 0 || to >= order.length)
+            return;
+        layout.move(id, by);
+        setMoved({ id, by });
+        setAnnouncement(`${nameOf(id)}, ${to + 1} of ${order.length}`);
+    };
+    return (_jsxs(Sheet, { open: open, defaultOpen: defaultOpen, onOpenChange: onOpenChange ? (next) => onOpenChange(next) : undefined, children: [trigger && (_jsxs(SheetTrigger, { render: _jsx(Button, { variant: "outline", size: "sm" }), children: [_jsx(SlidersHorizontalIcon, { "aria-hidden": "true" }), triggerLabel] })), _jsxs(SheetContent, { side: side, className: cn(side === 'bottom' && 'max-h-[85dvh]', className), children: [_jsxs(SheetHeader, { children: [_jsx(SheetTitle, { children: title }), description && _jsx(SheetDescription, { children: description })] }), _jsx("ol", { ref: listRef, "data-slot": "widget-layout-list", className: "flex flex-col divide-y divide-border overflow-y-auto px-4", children: order.map((id, index) => (_jsx(WidgetLayoutRow, { id: id, name: nameOf(id), shown: !hidden.includes(id), first: index === 0, last: index === order.length - 1, onMove: (by) => move(id, by), onToggle: () => layout.toggle(id) }, id))) }), _jsx("div", { "aria-live": "polite", className: "sr-only", children: announcement }), _jsx(SheetFooter, { children: _jsx(Button, { variant: "outline", "aria-disabled": layout.isDefault || undefined, onClick: () => {
+                                if (layout.isDefault)
+                                    return;
+                                layout.reset();
+                                setAnnouncement('Back to the default order');
+                            }, className: "aria-disabled:opacity-50", children: "Reset" }) })] })] }));
+}
+function WidgetLayoutRow({ id, name, shown, first, last, onMove, onToggle, }) {
+    return (_jsxs("li", { "data-widget-id": id, "data-hidden": !shown || undefined, className: "flex min-h-12 items-center gap-2 py-2", children: [_jsx("span", { className: cn('min-w-0 flex-1 truncate type-body', shown ? 'text-foreground' : 'text-muted-foreground'), children: name }), _jsx(Button, { variant: "ghost", size: "icon-sm", "data-move": "-1", "aria-label": `Move ${name} up`, "aria-disabled": first || undefined, onClick: () => onMove(-1), className: "aria-disabled:opacity-50", children: _jsx(ArrowUpIcon, { "aria-hidden": "true" }) }), _jsx(Button, { variant: "ghost", size: "icon-sm", "data-move": "1", "aria-label": `Move ${name} down`, "aria-disabled": last || undefined, onClick: () => onMove(1), className: "aria-disabled:opacity-50", children: _jsx(ArrowDownIcon, { "aria-hidden": "true" }) }), _jsx(Switch, { "aria-label": `Show ${name}`, checked: shown, onCheckedChange: onToggle, className: "ml-2" })] }));
+}

package/dist/hooks/table-url-changes.d.ts

@@ -13,6 +13,13 @@ export type TableView<F extends string, M extends string> = {
      * Applies only while the view is active (see activeViewOf).
      */
     columns?: readonly string[];
+    /**
+     * The grouping this view turns on, for DataTable's `grouping`: a
+     * grouping's id, or '' for None. Pressing the view sets it; a view that
+     * leaves it out keeps whatever grouping is on, since a grouping is how
+     * the rows are read, not which rows they are.
+     */
+    group?: string;
 };
 export declare function serializeSort(next: Sort): string | null;
 export declare function applyUrlChanges(previous: URLSearchParams, changes: UrlChanges): URLSearchParams;

package/dist/hooks/table-url-changes.js

@@ -27,6 +27,7 @@ export function viewToUrlChanges(filterNames, multiFilterNames, view) {
         ...Object.fromEntries(filterNames.map((name) => [name, view.filters?.[name] ?? ''])),
         ...Object.fromEntries(multiFilterNames.map((name) => [name, view.multiFilters?.[name] ?? []])),
         sort: view.sort ? serializeSort(view.sort) : null,
+        ...(view.group === undefined ? {} : { group: view.group || null }),
         page: null,
     };
 }

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

@@ -7,6 +7,7 @@ export type LayoutStore = {
 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 declare const browserStore: LayoutStore;
 export type TableLayoutOptions = {
     /** Every layout id the table has, the table's own `'table'` among them. */
     layouts: readonly string[];

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

@@ -43,7 +43,8 @@ export function resolveLayout(layouts, fromUrl, remembered, defaultLayout) {
         return remembered;
     return defaultLayout;
 }
-const browserStore = createLayoutStore(() => (typeof window === 'undefined' ? undefined : window.localStorage));
+// This device's remembered picks, shared with useTableUrlState's grouping.
+export 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

package/dist/hooks/use-table-url-state.d.ts

@@ -1,11 +1,21 @@
 import type { SortingState } from '../components/app/data-table.js';
 import { type TableView } from './table-url-changes.js';
-export declare function useTableUrlState<F extends string, M extends string = never, V extends string = never>(filterNames: readonly F[], multiFilterNames?: readonly M[], views?: Readonly<Record<V, TableView<NoInfer<F>, NoInfer<M>>>>): {
+export type TableUrlStateOptions = {
+    /**
+     * Where the table's grouping (DataTable's `grouping`) is remembered on
+     * this device, one key per table (`"my-app:tasks:group"`), the way
+     * useTableLayout remembers a layout. Without one it lives only in the URL.
+     */
+    groupStorageKey?: string;
+};
+export declare function useTableUrlState<F extends string, M extends string = never, V extends string = never>(filterNames: readonly F[], multiFilterNames?: readonly M[], views?: Readonly<Record<V, TableView<NoInfer<F>, NoInfer<M>>>>, { groupStorageKey }?: TableUrlStateOptions): {
     page: number;
     sorting: SortingState;
     filters: Record<F, string>;
     multiFilters: Record<M, string[]>;
     activeView: V | null;
+    grouping: string;
+    setGrouping: (next: string) => void;
     setPage: (next: number) => void;
     setSorting: (next: SortingState) => void;
     setFilter: (name: F, value: string) => void;

package/dist/hooks/use-table-url-state.js

@@ -1,5 +1,7 @@
+import { useCallback, useSyncExternalStore } from 'react';
 import { useSearchParams } from 'react-router';
 import { activeViewOf, applyUrlChanges, serializeSort, viewToUrlChanges, } from './table-url-changes.js';
+import { browserStore } from './use-table-layout.js';
 // A table's page, sort and filters, kept in the URL query string
 // (`?page=2&sort=name:asc&search=mouse&tags=fragile&tags=bulky`) instead of
 // component state, so they survive going to the edit form and back, a
@@ -15,9 +17,22 @@ import { activeViewOf, applyUrlChanges, serializeSort, viewToUrlChanges, } from
 // counts as active); pass that view's `columns` to DataTable. A view is
 // pressed with applyView().
 //
+// `grouping` is DataTable's: a grouping's id, or '' for None. It's
+// `?group=` in the URL, then the one remembered under `groupStorageKey`,
+// then None. Like the sort it doesn't change which rows are shown, so it
+// keeps the page and doesn't count toward the active view; a view that
+// names a `group` sets it when pressed.
+//
 // Every setter is one update(), and must stay one: see setFilters.
-export function useTableUrlState(filterNames, multiFilterNames = [], views = {}) {
+export function useTableUrlState(filterNames, multiFilterNames = [], views = {}, { groupStorageKey } = {}) {
     const [params, setParams] = useSearchParams();
+    const subscribe = useCallback((listener) => (groupStorageKey === undefined ? () => { } : browserStore.subscribe(groupStorageKey, listener)), [groupStorageKey]);
+    const rememberedGrouping = useSyncExternalStore(subscribe, () => (groupStorageKey === undefined ? null : browserStore.get(groupStorageKey)), () => null);
+    const grouping = params.get('group') ?? rememberedGrouping ?? '';
+    const rememberGrouping = (next) => {
+        if (groupStorageKey !== undefined)
+            browserStore.set(groupStorageKey, next);
+    };
     const page = Math.max(1, Math.floor(Number(params.get('page'))) || 1);
     const [sortField, sortDir] = (params.get('sort') ?? '').split(':');
     const sorting = sortField ? [{ id: sortField, desc: sortDir === 'desc' }] : [];
@@ -33,6 +48,11 @@ export function useTableUrlState(filterNames, multiFilterNames = [], views = {})
         filters,
         multiFilters,
         activeView,
+        grouping,
+        setGrouping: (next) => {
+            rememberGrouping(next);
+            update({ group: next || null });
+        },
         setPage: (next) => update({ page: next > 1 ? String(next) : null }),
         setSorting: (next) => update({ sort: serializeSort(next), page: null }),
         setFilter: (name, value) => update({ [name]: value, page: null }),
@@ -46,6 +66,10 @@ export function useTableUrlState(filterNames, multiFilterNames = [], views = {})
         setMultiFilter: (name, values) => update({ [name]: values, page: null }),
         // Replaces the whole filter + sort state at once — a saved view. See
         // viewToUrlChanges() for why anything the view doesn't set is cleared.
-        applyView: (view) => update(viewToUrlChanges(filterNames, multiFilterNames, view)),
+        applyView: (view) => {
+            if (view.group !== undefined)
+                rememberGrouping(view.group);
+            update(viewToUrlChanges(filterNames, multiFilterNames, view));
+        },
     };
 }

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

@@ -0,0 +1,45 @@
+/** What's kept for a page: the ids in the person's order, and the hidden ones. */
+export type SavedWidgetLayout = {
+    order: readonly string[];
+    hidden: readonly string[];
+};
+export type WidgetLayoutStore = {
+    /** What's saved under `key`, or null. The same object until it changes. */
+    get: (key: string) => SavedWidgetLayout | null;
+    /** Saves `layout` under `key`; null forgets it (a reset). */
+    set: (key: string, layout: SavedWidgetLayout | null) => void;
+    subscribe: (key: string, listener: () => void) => () => void;
+};
+type StorageLike = Pick<Storage, 'getItem' | 'setItem' | 'removeItem'>;
+export declare function createWidgetLayoutStore(getStorage: () => StorageLike | undefined): WidgetLayoutStore;
+/** The order and hidden ids to show: `saved` merged with the app's `defaultIds`. */
+export declare function mergeWidgetLayout(defaultIds: readonly string[], saved: SavedWidgetLayout | null): SavedWidgetLayout;
+/** `order` with `id` one place earlier (`-1`) or later (`1`); unchanged at either end. */
+export declare function moveWidget(order: readonly string[], id: string, by: -1 | 1): string[];
+export type WidgetLayoutOptions = {
+    /** Where the layout is kept; this device's localStorage when left out. */
+    store?: WidgetLayoutStore;
+};
+export type WidgetLayout = {
+    /** Every card's id, in the person's order. */
+    order: readonly string[];
+    /** The ids the person hid. */
+    hidden: readonly string[];
+    /** `order` without the hidden ones: the cards to render. */
+    visible: readonly string[];
+    /** Moves a card one place up (`-1`) or down (`1`). */
+    move: (id: string, by: -1 | 1) => void;
+    /** Hides a shown card, or shows a hidden one. */
+    toggle: (id: string) => void;
+    /** Back to the default order, everything shown. */
+    reset: () => void;
+    /** True while the layout is the default one. */
+    isDefault: boolean;
+};
+/**
+ * The order of a page's cards and which are hidden, remembered under
+ * `pageKey` (name it for the app and the page: `"my-app:hub"`).
+ * `defaultIds` is every card the page has, in its default order.
+ */
+export declare function useWidgetLayout(pageKey: string, defaultIds: readonly string[], { store }?: WidgetLayoutOptions): WidgetLayout;
+export {};

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

@@ -0,0 +1,128 @@
+import { useCallback, useMemo, useSyncExternalStore } from 'react';
+function parse(raw) {
+    if (raw === null)
+        return null;
+    try {
+        const value = JSON.parse(raw);
+        if (typeof value !== 'object' || value === null)
+            return null;
+        const { order, hidden } = value;
+        const strings = (list) => (Array.isArray(list) ? list.filter((id) => typeof id === 'string') : []);
+        return { order: strings(order), hidden: strings(hidden) };
+    }
+    catch {
+        return null;
+    }
+}
+export function createWidgetLayoutStore(getStorage) {
+    // Layouts this page set, for when storage refuses them (null: a reset).
+    const memory = new Map();
+    // The last string read per key and what it parsed to, so `get` hands
+    // back the same object until the stored string changes.
+    const parsed = new Map();
+    const listeners = new Map();
+    return {
+        get(key) {
+            if (memory.has(key))
+                return memory.get(key) ?? null;
+            let raw = null;
+            try {
+                raw = getStorage()?.getItem(key) ?? null;
+            }
+            catch {
+                // Storage blocked: nothing saved.
+            }
+            const cached = parsed.get(key);
+            if (cached && cached.raw === raw)
+                return cached.layout;
+            const layout = parse(raw);
+            parsed.set(key, { raw, layout });
+            return layout;
+        },
+        set(key, layout) {
+            memory.set(key, layout);
+            try {
+                const storage = getStorage();
+                if (layout === null)
+                    storage?.removeItem(key);
+                else
+                    storage?.setItem(key, JSON.stringify(layout));
+            }
+            catch {
+                // Storage blocked or full: kept 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 order and hidden ids to show: `saved` merged with the app's `defaultIds`. */
+export function mergeWidgetLayout(defaultIds, saved) {
+    if (saved === null)
+        return { order: [...defaultIds], hidden: [] };
+    const known = new Set(defaultIds);
+    const order = [];
+    for (const id of saved.order)
+        if (known.has(id) && !order.includes(id))
+            order.push(id);
+    defaultIds.forEach((id, index) => {
+        if (order.includes(id))
+            return;
+        // After the nearest card before it in the default order.
+        let at = 0;
+        for (let before = index - 1; before >= 0; before--) {
+            const placed = order.indexOf(defaultIds[before]);
+            if (placed !== -1) {
+                at = placed + 1;
+                break;
+            }
+        }
+        order.splice(at, 0, id);
+    });
+    const hidden = order.filter((id) => saved.hidden.includes(id));
+    return { order, hidden };
+}
+/** `order` with `id` one place earlier (`-1`) or later (`1`); unchanged at either end. */
+export function moveWidget(order, id, by) {
+    const next = [...order];
+    const from = next.indexOf(id);
+    const to = from + by;
+    if (from === -1 || to < 0 || to >= next.length)
+        return next;
+    [next[from], next[to]] = [next[to], next[from]];
+    return next;
+}
+const browserStore = createWidgetLayoutStore(() => (typeof window === 'undefined' ? undefined : window.localStorage));
+/**
+ * The order of a page's cards and which are hidden, remembered under
+ * `pageKey` (name it for the app and the page: `"my-app:hub"`).
+ * `defaultIds` is every card the page has, in its default order.
+ */
+export function useWidgetLayout(pageKey, defaultIds, { store = browserStore } = {}) {
+    const key = `${pageKey}:widgets`;
+    const subscribe = useCallback((listener) => store.subscribe(key, listener), [store, key]);
+    const saved = useSyncExternalStore(subscribe, () => store.get(key), () => null);
+    // The ids as a string, so a new array with the same ids each render doesn't re-merge.
+    const idsKey = defaultIds.join('\u0000');
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- idsKey stands for defaultIds
+    const { order, hidden } = useMemo(() => mergeWidgetLayout(defaultIds, saved), [idsKey, saved]);
+    const move = useCallback((id, by) => store.set(key, { order: moveWidget(order, id, by), hidden }), [store, key, order, hidden]);
+    const toggle = useCallback((id) => store.set(key, { order, hidden: hidden.includes(id) ? hidden.filter((other) => other !== id) : [...hidden, id] }), [store, key, order, hidden]);
+    const reset = useCallback(() => store.set(key, null), [store, key]);
+    return {
+        order,
+        hidden,
+        visible: order.filter((id) => !hidden.includes(id)),
+        move,
+        toggle,
+        reset,
+        isDefault: hidden.length === 0 && order.every((id, index) => id === defaultIds[index]),
+    };
+}

package/dist/index.d.ts

@@ -6,10 +6,11 @@ export { pickSpinWheelIndex, type SpinWheelItem } from './components/app/spin-wh
 export { FillInChoice, FillInQueue, type FillInChoiceProps, type FillInQueueProgress, type FillInQueueProps, } from './components/app/fill-in-queue.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 DataTableCardLayout, type DataTableProps, type DataTableTotals, type DataTableWidth, type SortingState, } from './components/app/data-table.js';
+export { DataTable, type DataTableCardLayout, type DataTableGrouping, 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 { KeyStats, type KeyStat, type KeyStatsProps } from './components/app/key-stats.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 EditListAddProps, type EditListItemProps, } from './components/app/edit-in-place.js';
 export { DataEnvironmentBanner } from './components/app/data-environment-banner.js';
@@ -44,7 +45,8 @@ export { DEFAULT_IMAGE_TYPES, type ImageUpload, type ImageUploadResult } from '.
 export { formatPlainDate, type PlainDate } from './lib/plain-date.js';
 export { ChoiceCell, LinkCell, NameCell, type ChoiceCellProps, type LinkCellProps, type NameCellProps, } from './components/app/row-edit-cells.js';
 export { ModuleCard, ModuleStrip, type CategorySlot, type ModuleCardLink, type ModuleCardPlace, type ModuleCardProps, type ModuleStripProps, } from './components/app/module-card.js';
-export { WidgetCard, WidgetList, WidgetListItem, type WidgetCardLink, type WidgetCardProps, type WidgetListItemProps, } from './components/app/widget-card.js';
+export { WidgetCard, WidgetCardGroup, WidgetList, WidgetListItem, type WidgetCardGroupProps, type WidgetCardLink, type WidgetCardProps, type WidgetListItemProps, } from './components/app/widget-card.js';
+export { WidgetLayoutSheet, type WidgetLayoutSheetProps } from './components/app/widget-layout-sheet.js';
 export { ThemeProvider } from './components/theme-provider.js';
 export { LoginRoute, type LoginRouteProps } from './routes/login.js';
 export { RegisterRoute } from './routes/register.js';
@@ -54,8 +56,9 @@ export type { AuthContextValue, AuthStatus, AuthUser, SignInResult } from './aut
 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 { useTableUrlState, type TableUrlStateOptions } from './hooks/use-table-url-state.js';
 export { useTableLayout, type TableLayoutOptions } from './hooks/use-table-layout.js';
+export { useWidgetLayout, createWidgetLayoutStore, mergeWidgetLayout, type SavedWidgetLayout, type WidgetLayout, type WidgetLayoutOptions, type WidgetLayoutStore, } from './hooks/use-widget-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

@@ -14,6 +14,7 @@ export { DataTable, } from './components/app/data-table.js';
 export {} from './components/app/table-groups.js';
 export { byDay } from './lib/group-by-day.js';
 export { EntityForm } from './components/app/entity-form.js';
+export { KeyStats } from './components/app/key-stats.js';
 export { EntityView, } from './components/app/entity-view.js';
 export { editInPlace, } from './components/app/edit-in-place.js';
 export { DataEnvironmentBanner } from './components/app/data-environment-banner.js';
@@ -47,7 +48,8 @@ export { DEFAULT_IMAGE_TYPES } from './lib/image-file.js';
 export { formatPlainDate } from './lib/plain-date.js';
 export { ChoiceCell, LinkCell, NameCell, } from './components/app/row-edit-cells.js';
 export { ModuleCard, ModuleStrip, } from './components/app/module-card.js';
-export { WidgetCard, WidgetList, WidgetListItem, } from './components/app/widget-card.js';
+export { WidgetCard, WidgetCardGroup, WidgetList, WidgetListItem, } from './components/app/widget-card.js';
+export { WidgetLayoutSheet } from './components/app/widget-layout-sheet.js';
 export { ThemeProvider } from './components/theme-provider.js';
 // Screens outside the app shell
 export { LoginRoute } from './routes/login.js';
@@ -59,6 +61,7 @@ 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 { useWidgetLayout, createWidgetLayoutStore, mergeWidgetLayout, } from './hooks/use-widget-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.44.0",
+  "version": "4.46.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": {