@tristan2828/ui-foundation 4.45.0 → 4.47.0

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

@@ -7,3 +7,15 @@ export type GroupRun<T> = RowGroup & {
     rows: T[];
 };
 export declare function groupRuns<T>(rows: readonly T[], groupOf: (row: T) => RowGroup): GroupRun<T>[];
+/**
+ * Rows grouped by a choice field's value (DataTable's `groupings`): one
+ * group per option, in the options' order, then any value the options
+ * don't name (in the order first met), then the rows with none under
+ * `emptyLabel`. A multi-value field (an array) puts the row under each of
+ * its values. Rows keep the server's order inside a group, and a group
+ * with no rows on this page never exists.
+ */
+export declare function groupByValues<T>(rows: readonly T[], valueOf: (row: T) => string | readonly string[] | null | undefined, options: readonly {
+    value: string;
+    label: string;
+}[], emptyLabel: string): GroupRun<T>[];

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

@@ -16,3 +16,40 @@ export function groupRuns(rows, groupOf) {
     }
     return runs;
 }
+/**
+ * Rows grouped by a choice field's value (DataTable's `groupings`): one
+ * group per option, in the options' order, then any value the options
+ * don't name (in the order first met), then the rows with none under
+ * `emptyLabel`. A multi-value field (an array) puts the row under each of
+ * its values. Rows keep the server's order inside a group, and a group
+ * with no rows on this page never exists.
+ */
+export function groupByValues(rows, valueOf, options, emptyLabel) {
+    const byKey = new Map();
+    const unknown = [];
+    const known = new Set(options.map((option) => option.value));
+    // The empty group's key can't collide with a value: values are non-empty.
+    const EMPTY = '';
+    for (const row of rows) {
+        const raw = valueOf(row);
+        const values = [...new Set((typeof raw === 'string' ? [raw] : (raw ?? [])).filter((value) => value !== ''))];
+        for (const value of values.length > 0 ? values : [EMPTY]) {
+            if (value !== EMPTY && !known.has(value) && !byKey.has(value))
+                unknown.push(value);
+            const group = byKey.get(value);
+            if (group)
+                group.push(row);
+            else
+                byKey.set(value, [row]);
+        }
+    }
+    const run = (key, label) => {
+        const groupRows = byKey.get(key);
+        return groupRows ? [{ key, label, rows: groupRows }] : [];
+    };
+    return [
+        ...options.flatMap((option) => run(option.value, option.label)),
+        ...unknown.flatMap((value) => run(value, value)),
+        ...run(EMPTY, emptyLabel),
+    ];
+}

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/index.d.ts

@@ -6,11 +6,12 @@ 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 { EntityView, type EntityViewField, type EntityViewLayout, type EntityViewPlacement, type EntityViewProps, type EntityViewSection, } from './components/app/entity-view.js';
+export { KeyStats, type KeyStat, type KeyStatsProps } from './components/app/key-stats.js';
+export { EntityView, type EntityViewField, type EntityViewLayout, type EntityViewMobileOrder, 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';
 export { EditableValue, type EditableValueProps } from './components/app/editable-value.js';
@@ -43,7 +44,7 @@ export { ImageField, type ImageFieldProps } from './components/app/image-field.j
 export { DEFAULT_IMAGE_TYPES, type ImageUpload, type ImageUploadResult } from './lib/image-file.js';
 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 { ModuleCard, ModuleStrip, type CategorySlot, type ModuleCardLink, type ModuleCardPlace, type ModuleCardProps, type ModuleStripMobile, type ModuleStripProps, } from './components/app/module-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';
@@ -55,7 +56,7 @@ 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';

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';

package/package.json

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