@marktiderman/genesis-ui 1.3.0 → 2.1.0

package/dist/components/data/index.d.ts

@@ -1,84 +1,25 @@
-import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as React from 'react';
 import { ReactNode, RefObject } from 'react';
+import { c as PageHeaderOptions, A as AppShell$1, P as PageHeader$1 } from '../../AppShell-sQT0UbXg.js';
+export { a as AppShellOptions, b as AppShellProps, N as NavItem, d as PageHeaderProps } from '../../AppShell-sQT0UbXg.js';
+import { V as ViewMode } from '../../view-toggle-CahQ87PW.js';
+export { a as ViewToggle } from '../../view-toggle-CahQ87PW.js';
 import { LucideIcon } from 'lucide-react';
-import { V as ViewMode } from '../../ViewToggle-DDe_Luj2.js';
-export { a as ViewToggle } from '../../ViewToggle-DDe_Luj2.js';
 import { Density } from '../../hooks/use-view-settings.js';
-import { a as ResourceColumnDef } from '../../use-resource-page-BXBv_Xah.js';
-export { D as DataTable, c as DataTableColumn, d as DataTableProps, L as LinkCell, R as ResourceActions, T as ThumbnailCell } from '../../use-resource-page-BXBv_Xah.js';
+import { R as ResourceActions, a as ResourceColumnDef } from '../../use-resource-page-DTQS011Q.js';
+export { D as DataTable, c as DataTableColumn, d as DataTableProps, L as LinkCell, T as ThumbnailCell } from '../../use-resource-page-DTQS011Q.js';
+export { EmptyState } from '../patterns/empty-state.js';
+export { V as ViewSettings } from '../../view-settings-kHKCHMjj.js';
 import { L as LinkComponent, N as NavigateFn } from '../../navigation-CpOEyUSb.js';
 export { D as DefaultLink, G as GenesisLinkProps, d as defaultNavigate, i as isPathActive } from '../../navigation-CpOEyUSb.js';
 import { UseFormReturn, Control, FieldErrors } from 'react-hook-form';
 import { WizardStep, UseResourceOptions } from '@marktiderman/genesis-core/hooks';
-import { FilterParam } from '@marktiderman/genesis-core/provider';
+import { FilterParam, SortParam, BaseRecord, Identifier } from '@marktiderman/genesis-core/provider';
 import { ResourceFormFieldDef } from '@marktiderman/genesis-core';
 export { FieldType, ResourceFormFieldDef, SelectOption } from '@marktiderman/genesis-core';
 export { CommandPalette, CommandPaletteItem, CommandPaletteProps, useCommandPaletteHotkey } from '../ui/command-palette.js';
 export { UseSavedViewsReturn, useSavedViews } from '../../hooks/use-saved-views.js';
 
-/**
- * Declarative chrome for PageHeader — developer defaults + optional
- * in-header user toggles (Notion/Linear “customize view” pattern).
- *
- * @stability Beta
- */
-interface PageHeaderOptions {
-    showIcon?: boolean;
-    showSubtitle?: boolean;
-    showCount?: boolean;
-    showViewToggle?: boolean;
-    showViewSettings?: boolean;
-    showCreate?: boolean;
-    /** Ghost ListFilter control in the actions cluster */
-    showDetailsToggle?: boolean;
-    /** Quiet hint beside actions while details are collapsed */
-    showDetailsHint?: boolean;
-    /** Move subtitle into the details panel (default true when details exist) */
-    subtitleInDetails?: boolean;
-    defaultDetailsOpen?: boolean;
-    detailsLabel?: string;
-    /**
-     * Show the in-header Header options popover so users can customize chrome.
-     * Default true when the header has more than one chrome affordance.
-     */
-    configurable?: boolean;
-}
-interface PageHeaderProps {
-    title: string;
-    subtitle?: string;
-    icon?: LucideIcon;
-    /**
-     * Header chrome config (developer defaults). Merged under user picks from
-     * the in-header options menu when `options.configurable` / storage is on.
-     */
-    options?: PageHeaderOptions;
-    /** Persist user header-option overrides (localStorage) */
-    optionsStorageKey?: string;
-    /** Extra trailing actions (after create); prefer first-class slots below */
-    actions?: ReactNode;
-    /** Collapsible details region below the title row */
-    details?: ReactNode;
-    detailsOpen?: boolean;
-    onDetailsOpenChange?: (open: boolean) => void;
-    detailsActive?: boolean;
-    detailsHint?: ReactNode;
-    /** Count badge */
-    count?: number;
-    totalCount?: number;
-    /** Singular entity for “N rows” copy when unfiltered */
-    entityName?: string;
-    countActive?: boolean;
-    viewMode?: ViewMode;
-    onViewModeChange?: (mode: ViewMode) => void;
-    pageSize?: number;
-    onPageSizeChange?: (size: number) => void;
-    density?: Density;
-    onDensityChange?: (density: Density) => void;
-    createAction?: ReactNode;
-}
-declare function PageHeader({ title, subtitle, icon: Icon, options: optionsProp, optionsStorageKey, actions, details, detailsOpen, onDetailsOpenChange, detailsActive, detailsHint, count, totalCount, entityName, countActive, viewMode, onViewModeChange, pageSize, onPageSizeChange, density, onDensityChange, createAction, }: PageHeaderProps): react_jsx_runtime.JSX.Element;
-
 interface DataPageShellProps {
     /** Display title for the page */
     title: string;
@@ -132,7 +73,7 @@ interface DataPageShellProps {
     headerOptionsStorageKey?: string;
     children: ReactNode;
 }
-declare function DataPageShell({ title, icon, entityName, subtitle, createAction, isLoading, isEmpty, emptyIcon, emptyMessage, emptyAction, hasError, errorMessage, onRetry, count, totalCount, viewMode, onViewModeChange, pageSize, onPageSizeChange, density, onDensityChange, filters, hasActiveFilters, onClearFilters, filtersCollapsible, defaultFiltersOpen, filtersOpen, onFiltersOpenChange, filtersLabel, filtersHint, headerOptions, headerOptionsStorageKey, children, }: DataPageShellProps): react_jsx_runtime.JSX.Element;
+declare function DataPageShell({ title, icon, entityName, subtitle, createAction, isLoading, isEmpty, emptyIcon, emptyMessage, emptyAction, hasError, errorMessage, onRetry, count, totalCount, viewMode, onViewModeChange, pageSize, onPageSizeChange, density, onDensityChange, filters, hasActiveFilters, onClearFilters, filtersCollapsible, defaultFiltersOpen, filtersOpen, onFiltersOpenChange, filtersLabel, filtersHint, headerOptions, headerOptionsStorageKey, children, }: DataPageShellProps): React.JSX.Element;
 
 interface FilterOption {
     value: string;
@@ -150,7 +91,7 @@ interface FilterComboboxProps {
     /** Optional map of value -> display label */
     labelMap?: Record<string, string>;
 }
-declare function FilterCombobox({ label, icon: Icon, options, selected, onChange, searchPlaceholder, allLabel, labelMap, }: FilterComboboxProps): react_jsx_runtime.JSX.Element;
+declare function FilterCombobox({ label, icon: Icon, options, selected, onChange, searchPlaceholder, allLabel, labelMap, }: FilterComboboxProps): React.JSX.Element;
 
 interface DataFilterConfig {
     key: string;
@@ -200,7 +141,7 @@ interface DataFiltersProps {
     /** Expose the search input ref for keyboard nav "/" shortcut */
     searchInputRef?: React.RefObject<HTMLInputElement | null>;
 }
-declare function DataFilters({ search, onSearchChange, searchPlaceholder, sort, onSortChange, sortOptions, filters, statusChips, savedViews, onLoadView, onSaveView, onDeleteView, canSaveViews, onViewSaved, onClearAll, searchInputRef, }: DataFiltersProps): react_jsx_runtime.JSX.Element;
+declare function DataFilters({ search, onSearchChange, searchPlaceholder, sort, onSortChange, sortOptions, filters, statusChips, savedViews, onLoadView, onSaveView, onDeleteView, canSaveViews, onViewSaved, onClearAll, searchInputRef, }: DataFiltersProps): React.JSX.Element;
 
 interface DataGridProps<T> {
     items: T[];
@@ -224,7 +165,7 @@ interface DataGridProps<T> {
     /** Keyboard navigation: container ref for scroll management */
     keyboardContainerRef?: RefObject<HTMLDivElement | null>;
 }
-declare function DataGrid<T>({ items, viewMode, batchSize, gridCols, renderCard, renderTable, renderListItem, staggerAnimation, getKey, focusedIndex, keyboardContainerRef, }: DataGridProps<T>): react_jsx_runtime.JSX.Element;
+declare function DataGrid<T>({ items, viewMode, batchSize, gridCols, renderCard, renderTable, renderListItem, staggerAnimation, getKey, focusedIndex, keyboardContainerRef, }: DataGridProps<T>): React.JSX.Element;
 
 interface BulkAction {
     label: string;
@@ -239,7 +180,7 @@ interface DataBulkBarProps {
     onClearSelection: () => void;
     actions: BulkAction[];
 }
-declare function DataBulkBar({ selected, totalCount, onToggleAll, onClearSelection, actions, }: DataBulkBarProps): react_jsx_runtime.JSX.Element | null;
+declare function DataBulkBar({ selected, totalCount, onToggleAll, onClearSelection, actions, }: DataBulkBarProps): React.JSX.Element | null;
 
 /**
  * DateCell -- shows relative date by default, formatted date otherwise.
@@ -260,25 +201,7 @@ declare function CurrencyCell(currency?: string, locale?: string): (_item: unkno
 /**
  * BadgeCell -- status badge with configurable color map.
  */
-declare function BadgeCell(colorMap?: Record<string, "default" | "secondary" | "destructive" | "outline" | "success" | "warning" | "info" | "muted">): (_item: unknown, value: unknown) => react_jsx_runtime.JSX.Element | "—";
-
-interface EmptyStateProps {
-    icon?: LucideIcon;
-    message?: string;
-    action?: ReactNode;
-    /** If true, shows a "no results" message with clear button */
-    hasFilters?: boolean;
-    onClearFilters?: () => void;
-}
-declare function EmptyState({ icon: Icon, message, action, hasFilters, onClearFilters, }: EmptyStateProps): react_jsx_runtime.JSX.Element;
-
-interface ViewSettingsProps {
-    pageSize: number;
-    onPageSizeChange: (size: number) => void;
-    density: Density;
-    onDensityChange: (density: Density) => void;
-}
-declare function ViewSettings({ pageSize, onPageSizeChange, density, onDensityChange, }: ViewSettingsProps): react_jsx_runtime.JSX.Element;
+declare function BadgeCell(colorMap?: Record<string, "default" | "secondary" | "destructive" | "outline" | "success" | "warning" | "info" | "muted">): (_item: unknown, value: unknown) => React.JSX.Element | "—";
 
 type StatCardColor = "primary" | "success" | "warning" | "info" | "destructive" | "muted";
 interface StatCardProps {
@@ -300,7 +223,7 @@ interface StatCardProps {
     };
     className?: string;
 }
-declare function StatCard({ label, value, icon: Icon, color, href, linkComponent: Link, trend, className, }: StatCardProps): react_jsx_runtime.JSX.Element;
+declare function StatCard({ label, value, icon: Icon, color, href, linkComponent: Link, trend, className, }: StatCardProps): React.JSX.Element;
 
 type ColumnStatus = "neutral" | "warning" | "success" | "info" | "destructive" | "primary";
 interface KanbanColumn<T> {
@@ -320,7 +243,7 @@ interface KanbanBoardProps<T> {
     emptyMessage?: string;
     className?: string;
 }
-declare function KanbanBoard<T>({ columns, renderCard, emptyMessage, className, }: KanbanBoardProps<T>): react_jsx_runtime.JSX.Element;
+declare function KanbanBoard<T>({ columns, renderCard, emptyMessage, className, }: KanbanBoardProps<T>): React.JSX.Element;
 
 interface DataListProps<T> {
     items: T[];
@@ -328,8 +251,15 @@ interface DataListProps<T> {
     emptyMessage?: string;
     className?: string;
 }
-declare function DataList<T>({ items, renderItem, emptyMessage, className, }: DataListProps<T>): react_jsx_runtime.JSX.Element;
+declare function DataList<T>({ items, renderItem, emptyMessage, className, }: DataListProps<T>): React.JSX.Element;
 
+/**
+ * Props for {@link DetailPanel} — a shell-agnostic record detail view.
+ * `layout` selects only the surrounding shell (inline / dialog / sheet);
+ * the header and content below it render identically across all three.
+ *
+ * @stability Beta
+ */
 interface DetailPanelProps<T> {
     /** The record to display */
     item: T | null;
@@ -353,17 +283,93 @@ interface DetailPanelProps<T> {
         label: string;
         render?: (value: unknown, item: T) => ReactNode;
     }>;
-    /** Panel width */
+    /**
+     * Panel width. For `"sheet"` / `"inline"` this is a fixed pixel width
+     * (matching this component's original, pre-`layout` sizing exactly). For
+     * `"dialog"` it maps to Tailwind's modal max-width scale instead, since a
+     * centered modal has a different sizing idiom than an edge-anchored panel.
+     */
     width?: "sm" | "md" | "lg";
+    /**
+     * Rendering shell for the header + content below.
+     * - `"sheet"` (default): fixed, right-anchored slide-in panel, composed
+     *   from the shared `Sheet` primitive. Matches this component's original
+     *   (pre-`layout`-prop) behavior — existing consumers that don't pass
+     *   `layout` see no change, other than an overlay now present at all
+     *   breakpoints (previously mobile-only) since it's a real `Sheet`.
+     * - `"dialog"`: centered modal overlay, composed from the shared `Dialog`
+     *   primitive.
+     * - `"inline"`: plain in-flow panel — no overlay, backdrop, or fixed
+     *   positioning — for master-detail / split-pane layouts.
+     */
+    layout?: "inline" | "dialog" | "sheet";
 }
-declare function DetailPanel<T extends Record<string, unknown>>({ item, open, onClose, title, subtitle, onEdit, onDelete, children, fields, width, }: DetailPanelProps<T>): react_jsx_runtime.JSX.Element | null;
+declare function DetailPanel<T extends Record<string, unknown>>({ item, open, onClose, title, subtitle, onEdit, onDelete, children, fields, width, layout, }: DetailPanelProps<T>): React.JSX.Element | null;
 
+/**
+ * Row-bound actions handed to `renderCard`, on top of the resource-wide
+ * `ResourceActions`. `open` is per-row, which is why it lives here rather
+ * than on `ResourceActions` — that object is built once and shared by every
+ * row and column, so it cannot carry a row-specific callback.
+ *
+ * @stability Beta
+ */
+interface ResourceCardActions<T> extends ResourceActions<T> {
+    /**
+     * Activate this row — opens the configured detail panel / modal / route,
+     * exactly as clicking the built-in card does. Wire it to your card's
+     * `onClick` (and call `stopPropagation` on any nested control that should
+     * not also activate the row).
+     */
+    open: () => void;
+}
+/**
+ * Config-driven resource page: wires data-fetching (or a pre-fetched `data`
+ * array), search/filter/sort, table/grid/list views, and a detail
+ * panel/modal/route around a `DataProvider` resource — the CRUD page most
+ * apps hand-roll, expressed as one component tree. `renderCard` lets a
+ * consumer fully own item presentation while ResourcePage keeps handling
+ * data-fetching, filtering, and layout; see also the built-in
+ * `useKeyboardNavigation` wiring (`keyboardNavigation` prop) and `gridCols`.
+ *
+ * Three levels of control, and each option is available at all three:
+ *
+ * 1. **The primitive offers it** — table / grid / list views, search, sort,
+ *    status chips, column visibility and resizing, density, page size,
+ *    detail panel / modal / route, built-in create and edit forms.
+ * 2. **The instance turns it on or off** — every one of those is a prop, so
+ *    a given page decides which affordances it offers at all.
+ * 3. **The end user picks their own, and it sticks** — for the options left
+ *    on at level 2, the user's choice persists to their own storage:
+ *    `viewSettingsKey` for page size and density, `columnVisibilityKey` and
+ *    `resizeKey` for column layout, `savedViews` (pair with `useSavedViews`)
+ *    for named filter sets. Persistence needs a key; without one the choice
+ *    lasts only for the session.
+ *
+ * A server-paginated list drives the same component through the controlled
+ * props (`page`, `perPage`, `onPageChange`, `onSortChange`, `onSearchChange`
+ * and friends) — supplying any of them stops ResourcePage from searching,
+ * sorting or paging the `data` a second time. See that block in
+ * {@link ResourcePageProps}.
+ *
+ * @stability Beta
+ */
 interface ResourcePageProps<T extends Record<string, unknown> = Record<string, unknown>> {
     /** Client-side mode: resource name passed to useResource / DataProvider. */
     resource?: string;
     /** Server-data mode: pre-fetched data array. */
     data?: T[];
-    /** Server-data mode: total record count (before client-side filtering). */
+    /**
+     * Server-data mode: total record count (before client-side filtering).
+     *
+     * Required whenever `onPageChange` is supplied. It cannot be derived from
+     * `data`, which holds only the current page. Omitted, `displayTotal` falls
+     * back to `0`, so the range span reads "No records" and `Next` stays
+     * disabled while the rows render directly below it. Rather than show a
+     * pager that contradicts the list, the component refuses to render the
+     * pager and shows an error instead. See {@link perPage} and
+     * {@link onPageChange}.
+     */
     total?: number;
     title: string;
     /** Page subtitle shown below the title. */
@@ -381,6 +387,16 @@ interface ResourcePageProps<T extends Record<string, unknown> = Record<string, u
         label: string;
         render?: (value: unknown, item: T) => ReactNode;
     }>;
+    /**
+     * Adds a status-chip filter. There is no dedicated status-change
+     * callback: chip clicks update the same filter state that already
+     * reports through `onFiltersChange`, whether or not the page is in
+     * server-controlled mode. A caller combining `statusFilter` with server
+     * pagination (`onPageChange` et al.) must supply `onFiltersChange` — see
+     * that prop — or status changes will update the chip UI without ever
+     * reaching the server. In server-controlled mode a status change also
+     * resets to page 1 via `onPageChange(1)` — see {@link onPageChange}.
+     */
     statusFilter?: string | {
         field: string;
         options?: string[];
@@ -389,6 +405,74 @@ interface ResourcePageProps<T extends Record<string, unknown> = Record<string, u
     searchPlaceholder?: string;
     initialFilters?: FilterParam[];
     onFiltersChange?: (filters: FilterParam[]) => void;
+    /** Current page, 1-based. Server-controlled mode only. */
+    page?: number;
+    /**
+     * Rows per page the server was asked for. Required whenever
+     * `onPageChange` is supplied: pager math (total pages, range start, Next)
+     * cannot be inferred from `data.length`, because a short final page is
+     * smaller than the real page size. Wins over the per-user page size
+     * persisted by `viewSettingsKey` — an explicit prop always beats a stored
+     * preference.
+     *
+     * Required whenever `onPageChange` is supplied. A short final page (the
+     * server's last page returning fewer rows than its page size) is
+     * indistinguishable from a small page size — there is no correct way to
+     * infer the divisor from the rows handed back. Rather than guess and
+     * render a wrong range or a stuck Next button, the component refuses to
+     * render the pager and shows an error instead when `onPageChange` is
+     * present without `perPage`.
+     *
+     * `total` is required on the same terms — see {@link total}. The error
+     * names every missing prop, not just the first.
+     */
+    perPage?: number;
+    /**
+     * Called with the next 1-based page number. The pager only renders when
+     * this is supplied AND both `perPage` and `total` are supplied — see
+     * {@link perPage} and {@link total}. Supplying this without either one
+     * renders an error naming the missing props instead of a pager.
+     *
+     * Status changes reach the server through `onFiltersChange` — not a
+     * dedicated callback here — because `statusFilter` state is tracked by
+     * the same filter machinery that already calls `onFiltersChange`
+     * regardless of controlled mode (see {@link statusFilter}). In
+     * server-controlled mode a status change also calls `onPageChange(1)`
+     * directly, since the previous page number is meaningless against a new
+     * filtered result set.
+     */
+    onPageChange?: (page: number) => void;
+    /** Called when the user picks a different page size in the header's view settings. */
+    onPerPageChange?: (perPage: number) => void;
+    /** Called when the user changes the sort, with `null` when the sort is cleared. */
+    onSortChange?: (sort: SortParam | null) => void;
+    /** Called when the user changes the search text (including clearing it). */
+    onSearchChange?: (search: string) => void;
+    /** Saved filter views to offer. Pair with `useSavedViews` for per-user storage. */
+    savedViews?: SavedViewItem[];
+    onLoadView?: (filters: Record<string, unknown>) => void;
+    onSaveView?: (name: string) => void;
+    onDeleteView?: (id: string) => void;
+    /** Show the "save current view" affordance. */
+    canSaveViews?: boolean;
+    /** Show the column-visibility dropdown. DataTable's default is `true`. */
+    columnVisibility?: boolean;
+    /** Persist key for the user's column-visibility picks. */
+    columnVisibilityKey?: string;
+    /** Allow drag-resizing columns. DataTable's default is `true`. */
+    resizableColumns?: boolean;
+    /** Persist key for the user's column widths. */
+    resizeKey?: string;
+    /** Keep the table header visible while scrolling. DataTable's default is `true`. */
+    stickyHeader?: boolean;
+    /** Keep the first column visible while scrolling horizontally. */
+    stickyFirstColumn?: boolean;
+    /**
+     * Page-size choices offered by `DataTable`'s own pager. Client-side mode
+     * only — server-controlled mode switches that pager off. (The header's
+     * view-settings popover has its own fixed 10/25/50/100 list.)
+     */
+    pageSizeOptions?: number[];
     onCreate?: () => void;
     onEdit?: (item: T) => void;
     onDelete?: (item: T) => void;
@@ -413,6 +497,46 @@ interface ResourcePageProps<T extends Record<string, unknown> = Record<string, u
         variant?: "default" | "destructive";
         onAction: (ids: string[]) => void | Promise<void>;
     }>;
+    /**
+     * Override the default card renderer used for grid view (and, absent a
+     * dedicated list layout, list view too — DataGrid falls back to the same
+     * renderer there). ResourcePage still owns data-fetching, filtering,
+     * sorting, and layout (grid columns, infinite-scroll batching, stagger
+     * animation) — this only swaps what's rendered inside each item slot.
+     *
+     * Receives `ResourceCardActions`: the row's `update`/`remove`/`refetch`
+     * plus `open()` to activate the row (opening the configured detail
+     * panel/modal/route). Row activation is *not* applied automatically to a
+     * custom card — wrapping it would double-fire against cards that bring
+     * their own click handling and would hijack clicks on nested buttons — so
+     * call `actions.open()` from wherever your card should activate.
+     */
+    renderCard?: (item: T, index: number, actions: ResourceCardActions<T>) => ReactNode;
+    /**
+     * Tailwind grid-column classes for the card grid, passed through to
+     * `DataGrid`'s `gridCols` — e.g. `"grid-cols-1 sm:grid-cols-2 lg:grid-cols-3"`.
+     * Defaults to DataGrid's own responsive 1/2/3/4-column ramp.
+     */
+    gridCols?: string;
+    /**
+     * Built-in list keyboard navigation via `useKeyboardNavigation`: j/k (or
+     * Arrow Up/Down) move a focus cursor, Enter opens the focused item,
+     * Backspace (⌫) closes an open detail view, and x toggles the focused
+     * item's selection when `bulkActions` are configured. Set to `false` to
+     * opt out.
+     *
+     * Default-on, and scoped so that being on by default stays safe:
+     * - Only while the grid or list view is showing. Table view keeps its own
+     *   independent sort/pagination, so a flat focus index can't reliably map
+     *   onto its visible rows.
+     * - Cursor keys suspend while a detail panel/modal or the built-in form
+     *   is open, so they can't drive the list behind the overlay; ⌫ stays
+     *   live there so it can close it.
+     * - Backspace is only intercepted while there's an open detail to close.
+     * - Modified chords (Ctrl/Cmd/Alt) are never captured, so an app's
+     *   Cmd+K-style shortcuts keep working.
+     */
+    keyboardNavigation?: boolean;
     toolbar?: ReactNode;
     emptyState?: ReactNode;
     /**
@@ -430,7 +554,86 @@ interface ResourcePageProps<T extends Record<string, unknown> = Record<string, u
      */
     viewSettingsKey?: string;
 }
-declare function ResourcePage<T extends Record<string, unknown> = Record<string, unknown>>(props: ResourcePageProps<T>): react_jsx_runtime.JSX.Element;
+declare function ResourcePage<T extends Record<string, unknown> = Record<string, unknown>>(props: ResourcePageProps<T>): React.JSX.Element;
+
+interface ResourceDetailPageProps<T extends BaseRecord = BaseRecord> {
+    /** Resource name, resolved through the mounted `DataProvider`. */
+    resource: string;
+    /**
+     * Record id. Nullish means "not resolved yet" — no request goes out and the
+     * page shows its loading state, which is what a route param that hasn't
+     * arrived should look like. It is deliberately NOT the not-found state:
+     * nothing has been asked, so nothing is missing.
+     */
+    id: Identifier | undefined | null;
+    /**
+     * Field used as the page title. Defaults to `name`, then `title`, then the
+     * id — the same fallback chain `ResourcePage` uses for a row's label.
+     */
+    titleField?: string;
+    /** Field used as the line under the title. */
+    subtitleField?: string;
+    /** Provider select/join syntax, e.g. `"*, owner:profiles(name)"`. */
+    select?: string;
+    /** Slot above the title: a `Breadcrumb`, a back link, a `StatusBadge`. */
+    breadcrumb?: ReactNode;
+    /** Record-scoped controls, built from the loaded record. */
+    actions?: (record: T) => ReactNode;
+    /** Metadata column, built from the loaded record. */
+    sidebar?: (record: T) => ReactNode;
+    /** The primary content region. */
+    children: (record: T) => ReactNode;
+    className?: string;
+    /** Stable test/automation selector (emitted as `data-testid`). */
+    testID?: string;
+}
+/**
+ * ResourceDetailPage — `DetailPage` with a record bound to it: fetches one
+ * record by id through the mounted `DataProvider` and hands it to the title,
+ * the actions, the sidebar and the content.
+ *
+ * ```tsx
+ * <ResourceDetailPage
+ *   resource="people"
+ *   id={params.id}
+ *   subtitleField="role"
+ *   actions={(person) => <Button testID="edit">Edit {person.name}</Button>}
+ *   sidebar={(person) => <StatCard label="Sessions" value={person.session_count} />}
+ * >
+ *   {(person) => <Section title="Timeline"><Timeline personId={person.id} /></Section>}
+ * </ResourceDetailPage>
+ * ```
+ *
+ * This is the detail-route counterpart to `ResourcePage`, which is the list
+ * one. Both are **data-bound**, not layouts: they need a resource contract
+ * to be useful, which is the layers table's admission test for this tier.
+ * The structure they render is a layout and lives one layer down —
+ * `DetailPage` in `@marktiderman/genesis-ui/layout` — so an app with its own
+ * fetching keeps the page shape without inheriting the provider. That
+ * layout/data-bound pairing is the same one `AppShell` and `ResourcePage`
+ * already have.
+ *
+ * The three non-record states are rendered here rather than left to the
+ * caller, because a per-app "loading…" is exactly the hand-written code a
+ * template exists to remove:
+ * - loading, or no id yet -> `PageLoading`
+ * - absent -> `EmptyState` saying so, distinct from the error state, since a
+ *   deleted record and a broken query need different words. Every provider
+ *   Genesis ships signals "no such row" by throwing rather than by resolving
+ *   empty, so this state is reached by classifying the error (see
+ *   `isNotFoundError`) as well as by a falsy `data`
+ * - any other failure -> `EmptyState` carrying the provider's message, which
+ *   is kept verbatim: an error state that hides what went wrong is the one
+ *   nobody can act on
+ *
+ * `titleField` is exact: name a field and you get that field, empty string
+ * included. The `name` -> `title` -> id chain is the DEFAULT, not a fallback
+ * layered under an explicit choice — a page silently titled by a different
+ * column than the one asked for is worse than a blank one.
+ *
+ * @stability Beta
+ */
+declare function ResourceDetailPage<T extends BaseRecord = BaseRecord>({ resource, id, titleField, subtitleField, select, breadcrumb, actions, sidebar, children, className, testID, }: ResourceDetailPageProps<T>): React.JSX.Element;
 
 interface ResourceFormProps {
     resource: string;
@@ -454,7 +657,7 @@ interface ResourceFormProps {
     /** Number of columns for the form layout. Default 1. */
     columns?: 1 | 2;
 }
-declare function ResourceForm(props: ResourceFormProps): react_jsx_runtime.JSX.Element | null;
+declare function ResourceForm(props: ResourceFormProps): React.JSX.Element | null;
 
 interface RelationFieldProps {
     field: ResourceFormFieldDef;
@@ -462,7 +665,7 @@ interface RelationFieldProps {
     onChange: (value: string) => void;
     disabled?: boolean;
 }
-declare function RelationField({ field, value, onChange, disabled, }: RelationFieldProps): react_jsx_runtime.JSX.Element;
+declare function RelationField({ field, value, onChange, disabled, }: RelationFieldProps): React.JSX.Element;
 
 interface FileUploadFieldProps {
     field: ResourceFormFieldDef;
@@ -470,14 +673,14 @@ interface FileUploadFieldProps {
     onChange: (value: File | File[] | null) => void;
     disabled?: boolean;
 }
-declare function FileUploadField({ field, value, onChange, disabled, }: FileUploadFieldProps): react_jsx_runtime.JSX.Element;
+declare function FileUploadField({ field, value, onChange, disabled, }: FileUploadFieldProps): React.JSX.Element;
 
 declare function FieldArrayRenderer({ field, control, action, watchedValues, }: {
     field: ResourceFormFieldDef;
     control: Control<Record<string, unknown>>;
     action: "create" | "edit";
     watchedValues?: Record<string, unknown>;
-}): react_jsx_runtime.JSX.Element;
+}): React.JSX.Element;
 
 interface WizardFormProps {
     steps: WizardStep[];
@@ -489,134 +692,21 @@ interface WizardFormProps {
     action: "create" | "edit";
     onInvalid?: (errors: FieldErrors) => void;
 }
-declare function WizardForm({ steps, form, fields, onSubmit, isSaving, renderField, action, onInvalid, }: WizardFormProps): react_jsx_runtime.JSX.Element;
+declare function WizardForm({ steps, form, fields, onSubmit, isSaving, renderField, action, onInvalid, }: WizardFormProps): React.JSX.Element;
 
-interface NavItem {
-    to: string;
-    icon: LucideIcon;
-    label: string;
-    /** Nested items — rendered as a collapsible group when the rail is expanded */
-    children?: NavItem[];
-    badge?: string | number;
-    disabled?: boolean;
-    /** Exact-match active state (e.g. overview `/`) */
-    end?: boolean;
-}
 /**
- * Declarative chrome for AppShell — developer defaults + optional
- * in-sidebar user toggles (Notion/Linear “customize chrome” pattern).
- *
- * @stability Beta
+ * @deprecated Import `AppShell` from `@marktiderman/genesis-ui/layout` instead.
+ * `AppShell` is a layout, not a data-bound component. This `/data` alias is
+ * removed in the next major — see docs/FRAMEWORK.md rule 5.
+ * @stability Deprecated
  */
-interface AppShellOptions {
-    showLogo?: boolean;
-    showAppName?: boolean;
-    showThemeToggle?: boolean;
-    /** Desktop rail collapse control */
-    showCollapse?: boolean;
-    showUserSlot?: boolean;
-    showFooter?: boolean;
-    showSecondaryNav?: boolean;
-    /** Mobile fixed bottom tab bar */
-    showMobileBottomNav?: boolean;
-    defaultCollapsed?: boolean;
-    /**
-     * Show the in-sidebar Sidebar options popover so users can customize chrome.
-     * Default true when collapse / secondary / theme / slots are available.
-     */
-    configurable?: boolean;
-    /**
-     * Toggle keys the developer has decided on and users may not override —
-     * e.g. hiding `showThemeToggle` for a brand that manages theme elsewhere.
-     * Locked keys are dropped from the options popover and any stored user
-     * override for them is ignored on resolve.
-     */
-    lockedOptions?: (keyof AppShellOptions)[];
-    /** Comfortable (default) vs compact row padding */
-    density?: "comfortable" | "compact";
-    /** Expanded rail width in rem-ish tokens: narrow ≈ 13rem, wide ≈ 16rem */
-    railWidth?: "narrow" | "wide";
-    /**
-     * Where page content scrolls.
-     * - `container` (default): main panel scrolls — classic app-shell chrome.
-     * - `window`: document/window scrolls with a sticky rail so React Router
-     *   `ScrollRestoration` keeps working (dashboard dogfood).
-     */
-    scrollRoot?: "container" | "window";
-}
+declare const AppShell: typeof AppShell$1;
 /**
- * @stability Beta
+ * @deprecated Import `PageHeader` from `@marktiderman/genesis-ui/layout`
+ * instead. `PageHeader` is a layout, not a data-bound component. This `/data`
+ * alias is removed in the next major — see docs/FRAMEWORK.md rule 5.
+ * @stability Deprecated
  */
-interface AppShellProps {
-    /** App name shown in sidebar header */
-    appName: string;
-    /** App logo letter or short text (ignored when `logo` is set) */
-    appLogo?: string;
-    /** Custom logo node — preferred over `appLogo` letter tile */
-    logo?: ReactNode;
-    /** Primary navigation items */
-    navItems: NavItem[];
-    /** Secondary nav (e.g. “More”) — rendered below a divider when shown */
-    secondaryNavItems?: NavItem[];
-    /** Label above secondary nav (default “More”) */
-    secondaryNavLabel?: string;
-    /**
-     * Items for the mobile bottom tab bar. Defaults to top-level `navItems`
-     * (no children). Pass a short list for apps with large sidebars; pass `[]`
-     * and set `options.showMobileBottomNav: false` to hide.
-     */
-    mobileNavItems?: NavItem[];
-    /** Slot below the logo row (product switcher, workspace picker, …) */
-    headerSlot?: ReactNode;
-    /**
-     * Compact slot shown in the **collapsed** desktop rail, where `headerSlot`
-     * is hidden for space. Use it to keep a core affordance reachable without
-     * expanding — e.g. an icon-only product switcher. Omit to hide the header
-     * region entirely while collapsed.
-     */
-    collapsedHeaderSlot?: ReactNode;
-    /** Footer region above the user slot (version, links) */
-    footer?: ReactNode;
-    /**
-     * User / account block at the bottom of the sidebar. When the rail is
-     * collapsed, AppShell hides any descendant carrying the
-     * `data-shell-user-detail` attribute (e.g. name/email text) so only a
-     * compact element (avatar, initial) remains — tag the detail wrapper you
-     * want hidden in the collapsed rail with that attribute.
-     */
-    userSlot?: ReactNode;
-    /** Page content */
-    children: ReactNode;
-    /**
-     * @deprecated Prefer `options.showThemeToggle`. Kept for sample-app
-     * back-compat; merges into resolved options when `options` omits it.
-     */
-    showThemeToggle?: boolean;
-    /** Chrome config (developer defaults + optional in-sidebar menu) */
-    options?: AppShellOptions;
-    /** Persist user sidebar-option overrides + collapse state (localStorage) */
-    optionsStorageKey?: string;
-    /** Controlled collapse (desktop rail) */
-    collapsed?: boolean;
-    onCollapsedChange?: (collapsed: boolean) => void;
-    /**
-     * Injectable link component. Defaults to a plain `<a>` (no router). Pass a
-     * router adapter — e.g. React Router `({ href, ...p }) => <Link to={href} {...p} />`
-     * or Next.js `next/link` — to get client-side navigation.
-     */
-    linkComponent?: LinkComponent;
-    /**
-     * Current path used to highlight the active nav item. Router consumers pass
-     * `useLocation().pathname` (RR) or `usePathname()` (Next). Omit to disable
-     * active highlighting.
-     */
-    activePath?: string;
-    /**
-     * Optional custom active-state matcher. Defaults to a prefix match (with `/`
-     * treated as exact), mirroring React Router `NavLink`.
-     */
-    isActive?: (to: string, activePath?: string) => boolean;
-}
-declare function AppShell({ appName, appLogo, logo, navItems, secondaryNavItems, secondaryNavLabel, mobileNavItems, headerSlot, collapsedHeaderSlot, footer, userSlot, children, showThemeToggle: showThemeToggleProp, options: optionsProp, optionsStorageKey, collapsed: collapsedProp, onCollapsedChange, linkComponent, activePath, isActive, }: AppShellProps): react_jsx_runtime.JSX.Element;
+declare const PageHeader: typeof PageHeader$1;
 
-export { AppShell, type AppShellOptions, type AppShellProps, BadgeCell, type BulkAction, type ColumnStatus, CurrencyCell, DataBulkBar, type DataFilterConfig, DataFilters, DataGrid, DataList, type DataListProps, DataPageShell, type DataPageShellProps, DateCell, Density, DetailPanel, type DetailPanelProps, EmptyState, FieldArrayRenderer, FileUploadField, FilterCombobox, type FilterOption, KanbanBoard, type KanbanBoardProps, type KanbanColumn, LinkComponent, type NavItem, NavigateFn, NumberCell, PageHeader, type PageHeaderOptions, type PageHeaderProps, RelationField, ResourceColumnDef, ResourceForm, type ResourceFormProps, ResourcePage, type ResourcePageProps, type SavedViewItem, StatCard, type StatCardColor, type StatCardProps, ViewMode, ViewSettings, WizardForm };
+export { AppShell, BadgeCell, type BulkAction, type ColumnStatus, CurrencyCell, DataBulkBar, type DataFilterConfig, DataFilters, DataGrid, DataList, type DataListProps, DataPageShell, type DataPageShellProps, DateCell, Density, DetailPanel, type DetailPanelProps, FieldArrayRenderer, FileUploadField, FilterCombobox, type FilterOption, KanbanBoard, type KanbanBoardProps, type KanbanColumn, LinkComponent, NavigateFn, NumberCell, PageHeader, PageHeaderOptions, RelationField, ResourceActions, type ResourceCardActions, ResourceColumnDef, ResourceDetailPage, type ResourceDetailPageProps, ResourceForm, type ResourceFormProps, ResourcePage, type ResourcePageProps, type SavedViewItem, StatCard, type StatCardColor, type StatCardProps, ViewMode, WizardForm };