@tristan2828/ui-foundation 4.44.0 → 4.45.0

package/conventions/AGENTS.md

@@ -87,7 +87,8 @@ Every data view handles: loading, empty, error, and success. Use
 `<Skeleton>`, `<Empty>`, and the error boundary — `DataTable` already does,
 and `EntityView` (one record) adds not found: a plain 404, never a retry.
 A small widget on a hub page is a `WidgetCard`, which holds all four for
-its own data, its error inside the card; a hub's place (a module, with
+its own data, its error inside the card (folded, its `summary` follows
+the same states); a hub's place (a module, with
 one live number) is a `ModuleCard` in a `ModuleStrip`, the same way.
 Every screen has one Playwright test per state, forced via MSW overrides
 (`@tristan2828/ui-foundation/testing`).

package/conventions/docs/design-language.md

@@ -12,14 +12,14 @@
 - [Typography](#typography) · lines 245–327
   - [Written text (notes)](#written-text-notes) · lines 276–327
 - [Density](#density) · lines 329–386
-- [Widget cards (hub pages)](#widget-cards-hub-pages) · lines 388–466
-- [Module cards (a hub's places)](#module-cards-a-hubs-places) · lines 468–526
-- [Notices](#notices) · lines 528–556
-- [A value over time](#a-value-over-time) · lines 558–591
-- [A list as a board](#a-list-as-a-board) · lines 593–644
-- [A list as cards](#a-list-as-cards) · lines 646–692
-- [Picking at random](#picking-at-random) · lines 694–725
-- [Filling in what's missing](#filling-in-whats-missing) · lines 727–777
+- [Widget cards (hub pages)](#widget-cards-hub-pages) · lines 388–502
+- [Module cards (a hub's places)](#module-cards-a-hubs-places) · lines 504–562
+- [Notices](#notices) · lines 564–592
+- [A value over time](#a-value-over-time) · lines 594–627
+- [A list as a board](#a-list-as-a-board) · lines 629–680
+- [A list as cards](#a-list-as-cards) · lines 682–728
+- [Picking at random](#picking-at-random) · lines 730–761
+- [Filling in what's missing](#filling-in-whats-missing) · lines 763–813
 
 <!-- /index -->
 
@@ -446,7 +446,42 @@ const { data, isLoading, error, refetch } = useReadyTasksQuery() // one page of
   (`"<app>:hub.<widget>"`) so a card folded stays folded on that device,
   and `defaultCollapsed` for one that should start folded. The chevron
   at the header's end is named by the title; the header's link stays
-  while folded.
+  while folded. Give a card that folds a `summary`: one short value its
+  header shows while folded (`summary={data?.total}`, `"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 on an error
+  (the error itself is in the body, opened), and `emptySummary`
+  (`"None"`) or nothing when empty.
+- **One open at a time on a phone:** put the cards in a
+  `WidgetCardGroup accordion="mobile"` (its `className` is the grid),
+  give each an `id`, and name the one to start open in `defaultOpen`.
+  Below the sidebar's breakpoint every card folds, opening one folds the
+  others, and a tap anywhere on a header (not its link) toggles it; on a
+  desktop the cards keep their own `collapsible`. `accordion` alone does
+  it at every width.
+- **Letting someone order the cards:** keep the order in
+  `useWidgetLayout('<app>:hub', ids)` (every card's id, in the default
+  order), render `layout.visible`, and put a `WidgetLayoutSheet` (its
+  Customize button) beside the page's title, with each card's title by id.
+  Its rows have Up, Down and a Show switch, with Reset: the same on a
+  phone, a desktop and a keyboard (the focus stays on the button
+  pressed). The order is kept on the device; a removed id drops out and
+  a new one falls in at its default place. To follow the person between
+  devices, pass `{ store }`, a `WidgetLayoutStore` over the app's
+  backend.
+
+```tsx
+const HUB_CARDS = { ready: 'Ready to start', waiting: 'Waiting on', links: 'Saved links' }
+const layout = useWidgetLayout('my-app:hub', Object.keys(HUB_CARDS))
+
+<div className="flex items-center justify-between gap-3">
+  <h1 className="type-page-title text-foreground">Home</h1>
+  <WidgetLayoutSheet layout={layout} titles={HUB_CARDS} />
+</div>
+<WidgetCardGroup accordion="mobile" defaultOpen="ready" className="grid … gap-4">
+  {layout.visible.map((id) => <HubCard key={id} id={id} />)}
+</WidgetCardGroup>
+```
 - **A row is one line:** its text is a link (`to` for a route in the
   app, `href` for an external address, which opens in a new tab with the
   external-link mark) or plain text, cut with an ellipsis, the whole of
@@ -462,7 +497,8 @@ const { data, isLoading, error, refetch } = useReadyTasksQuery() // one page of
   many 288px-or-wider columns as fit). Each card is as tall as its rows;
   it doesn't stretch to its tallest neighbour.
 - Storybook's `app/WidgetCard` shows three widgets on a page and every
-  one in each state; its checks run axe and the token and glyph checks in
+  one in each state, a folded summary in each state and an accordion,
+  and `app/WidgetLayoutSheet` a hub with its Customize sheet; its checks run axe and the token and glyph checks in
   both themes and at `large`.
 
 ## Module cards (a hub's places)

package/dist/components/app/widget-card.d.ts

@@ -4,6 +4,11 @@ import type { AppError } from '../../api/contracts.js';
 import type { IconComponent } from './icon-component.js';
 export interface WidgetCardProps {
     title: string;
+    /**
+     * The card's id, on its region: the one WidgetCardGroup's `defaultOpen`
+     * names and useWidgetLayout orders (`"ready"`). Unique on the page.
+     */
+    id?: string;
     /**
      * An icon shown before the title: a Lucide icon, or an app's own mark (an
      * outside service's logo on a card about that service). Decorative: the
@@ -39,6 +44,14 @@ export interface WidgetCardProps {
      * Left out, it starts at `defaultCollapsed` on every visit.
      */
     storageKey?: string;
+    /**
+     * One short value shown in the header while the card is folded: a count
+     * (`3`), or a word or two (`"Due today"`). A skeleton while loading, a
+     * muted dash on an error. Ignored while open.
+     */
+    summary?: ReactNode;
+    /** What a folded card's summary says when it's empty (`"None"`); nothing when left out. */
+    emptySummary?: ReactNode;
     children?: ReactNode;
     className?: string;
 }
@@ -51,7 +64,22 @@ export type WidgetCardLink = {
     label: string;
     to?: never;
 };
-export declare function WidgetCard({ title, icon: Icon, headingLevel, link, isLoading, error, onRetry, isEmpty, emptyMessage, skeletonRows, collapsible, defaultCollapsed, storageKey, children, className, }: WidgetCardProps): import("react").JSX.Element;
+export declare function WidgetCard({ id, title, icon: Icon, headingLevel, link, isLoading, error, onRetry, isEmpty, emptyMessage, skeletonRows, collapsible, defaultCollapsed, storageKey, summary, emptySummary, children, className, }: WidgetCardProps): import("react").JSX.Element;
+export interface WidgetCardGroupProps {
+    /**
+     * One card open at a time: `true` always, `"mobile"` only below the
+     * sidebar's breakpoint (a desktop hub keeps each card's own
+     * `collapsible`), `false` never (the group is a plain wrapper).
+     */
+    accordion?: boolean | 'mobile';
+    /** The `id` of the card open at first; all folded (showing their summaries) when left out. */
+    defaultOpen?: string | null;
+    children: ReactNode;
+    /** The wrapper's classes: the hub's grid of cards, usually. */
+    className?: string;
+}
+/** Wraps a hub's WidgetCards so that opening one folds the others (on a phone only, with `accordion="mobile"`). */
+export declare function WidgetCardGroup({ accordion, defaultOpen, children, className }: WidgetCardGroupProps): import("react").JSX.Element;
 /** The rows of a WidgetCard: a list with a divider between rows. */
 export declare function WidgetList({ children, className }: {
     children: ReactNode;

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/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

@@ -44,7 +44,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';
@@ -56,6 +57,7 @@ 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 { 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

@@ -47,7 +47,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 +60,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.45.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": {