@proveanything/smartlinks-utils-ui 0.3.9 → 0.3.12

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

@@ -1,12 +1,26 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { ComponentType, ReactNode } from 'react';
+import { ReactNode, ComponentType } from 'react';
 import * as _proveanything_smartlinks_dist_types_appObjects from '@proveanything/smartlinks/dist/types/appObjects';
-import { MatchedAt, FacetRule, RecordScope, AppRecord, RecordTarget, MatchResult, MatchEntry } from '@proveanything/smartlinks/dist/types/appObjects';
+import { FacetRule, MatchedAt, RecordScope, AppRecord, RecordTarget, MatchResult, MatchEntry } from '@proveanything/smartlinks/dist/types/appObjects';
 import { LucideIcon } from 'lucide-react';
 import * as _tanstack_query_core from '@tanstack/query-core';
 import { InfiniteData } from '@tanstack/react-query';
 
-type ScopeKind = 'product' | 'facet' | 'variant' | 'batch';
+/**
+ * Where a record is anchored in the inheritance chain.
+ *
+ * - `collection` — terminal rung (collection-wide default). Inherited by every
+ *   product/facet/variant/batch when nothing more specific exists. Most useful
+ *   for collection-cardinality records (a global pool of FAQs / recipes / SOPs).
+ * - `facet`      — anchored to a facet value (e.g. `bagel-type=white`).
+ * - `product`    — anchored to a product.
+ * - `variant`    — anchored to a product variant.
+ * - `batch`      — anchored to a product batch.
+ * - `rule`       — synthetic UI scope: records that target via a `facetRule`
+ *                  (AND-of-OR over facets) rather than being pinned to a
+ *                  specific node in the chain. Their refs start with `rule:`.
+ */
+type ScopeKind = 'collection' | 'product' | 'facet' | 'variant' | 'batch' | 'rule';
 /** Parsed `ref` string — see `data/refs.ts`. Format: `kind:id` or chain. */
 interface ParsedRef {
     /** Most-specific scope this ref points at. */
@@ -20,6 +34,19 @@ interface ParsedRef {
     variantId?: string;
     batchId?: string;
     proofId?: string;
+    /**
+     * Opaque id of a rule-targeted record (ref starts with `rule:`). Set when
+     * `kind === 'rule'`. The actual rule lives on the record's `facetRule`
+     * field — this is just the addressing handle used by the URL/refs layer.
+     */
+    ruleId?: string;
+    /**
+     * For `collection` cardinality records: the per-item identifier within the
+     * scope. Singleton records leave this undefined. The full ref is
+     * `{scopeRef}/item:{itemId}`, or just `item:{itemId}` for collection-rooted
+     * items.
+     */
+    itemId?: string;
 }
 
 type RecordSource = 'self' | 'inherited' | 'empty';
@@ -54,6 +81,13 @@ interface RecordSummary<TData = unknown> {
      * leave this undefined.
      */
     itemId?: string;
+    /**
+     * For rule-targeted records (ref begins `rule:`). The AND-of-OR clauses
+     * the server uses to match this record against a product's facets.
+     * `null` for non-rule records. The browser uses this to render a friendly
+     * rule summary as the row subtitle.
+     */
+    facetRule?: FacetRule | null;
 }
 interface ResolvedRecord<TData = unknown> {
     data: TData | null;
@@ -104,14 +138,27 @@ interface CsvSchema<TData> {
 }
 
 /**
- * How records are laid out in the browse rail / panel.
- * - `list`     → dense rows with status dot + label + subtitle (default).
- * - `grid`     → square cards with thumbnail + label.
- * - `gallery`  → larger 16:9 cards with thumbnail + label + subtitle.
- * - `compact`  → minimal one-line rows (no subtitle, no status dot).
+ * How records are laid out in the **left rail** (the navigator).
+ *
+ * The rail is intentionally a dense tree/list — cards or galleries belong on
+ * the right pane, not in a 260px column. Only the row densities are offered:
+ *
+ * - `list`    → dense rows with status dot + label + subtitle (default).
+ * - `compact` → minimal one-line rows (no subtitle, no status dot).
  */
-type RecordPresentation = 'list' | 'grid' | 'gallery' | 'compact';
+type RecordPresentation = 'list' | 'compact';
 declare const ALL_PRESENTATIONS: RecordPresentation[];
+/**
+ * How a multi-item collection is rendered in the **right pane** when a scope
+ * is selected and no item is open. Right-pane only — cards and galleries
+ * have the room to breathe here.
+ *
+ * - `table`   → declarative columns (built-in default with `itemColumns`).
+ * - `cards`   → square cards with thumbnail + label.
+ * - `gallery` → larger 16:9 cards with thumbnail + label + subtitle.
+ */
+type ItemView = 'table' | 'cards' | 'gallery';
+declare const ALL_ITEM_VIEWS: ItemView[];
 /**
  * Whether each scope holds at most one record of this type, or many.
  * - `singleton`  → one record per scope (e.g. washing instructions). Default.
@@ -131,6 +178,17 @@ type CollectedSort = {
     field: string;
     direction?: 'asc' | 'desc';
 };
+/**
+ * What the left rail shows once an item is open in the editor (collection
+ * cardinality only):
+ *
+ * - `siblings` *(default)* — rail flips to the list of items in the current
+ *   scope. Click any sibling to switch instantly. A pinned `← All scopes`
+ *   link returns to scope navigation.
+ * - `scopes` — rail keeps showing scopes. Switching items requires going
+ *   back to the right-pane list first.
+ */
+type CollectionRailMode = 'siblings' | 'scopes';
 
 type TelemetryEvent = {
     type: 'record.save';
@@ -171,6 +229,22 @@ type TelemetryEvent = {
     type: 'item.create';
     recordType?: string;
     scopeRef: string;
+} | {
+    type: 'item.open';
+    recordType?: string;
+    scopeRef: string;
+    itemId: string;
+} | {
+    type: 'item.delete';
+    recordType?: string;
+    scopeRef: string;
+    itemId: string;
+} | {
+    type: 'item.view.change';
+    recordType?: string;
+    scopeRef: string;
+    from: string;
+    to: string;
 } | {
     type: 'clipboard.copy';
     recordType?: string;
@@ -228,13 +302,30 @@ interface RecordsAdminI18n {
     unsavedBannerBody: string;
     /** Presentation mode switcher labels. */
     presentationList: string;
-    presentationGrid: string;
-    presentationGallery: string;
     presentationCompact: string;
+    /** Right-pane item view (collection cardinality) switcher labels. */
+    itemViewTable: string;
+    itemViewCards: string;
+    itemViewGallery: string;
     /** Collection cardinality affordances. */
     newItem: string;
     noItemsTitle: string;
     noItemsBody: string;
+    /**
+     * Right-pane multi-item flow strings (collection cardinality).
+     * `{noun}` is replaced with `itemNoun` (e.g. "recipe", "FAQ").
+     */
+    backToList: string;
+    prevItem: string;
+    nextItem: string;
+    itemListTitle: string;
+    /** Friendly singular for table column header in built-in default. */
+    itemColumnLabel: string;
+    itemColumnUpdated: string;
+    itemActions: string;
+    /** Sibling rail (rail flips to items when one is open). */
+    backToScopes: string;
+    siblingsHeading: string;
     /**
      * Empty-state copy for the LEFT browse rail (the list itself is empty).
      * Defaults to a friendly "no records exist yet" message — distinct from
@@ -261,6 +352,88 @@ interface RecordsAdminI18n {
 }
 declare const DEFAULT_I18N: RecordsAdminI18n;
 
+/**
+ * How URL changes are pushed onto the browser history.
+ *
+ * - `push`     — every change adds a history entry (rich back stack).
+ * - `replace`  — every change replaces the current entry (no history bloat).
+ * - `smart`    — meaningful navigation (open item, change scope) pushes;
+ *                cosmetic changes (toggle view, prev/next sibling) replace.
+ *                Default.
+ */
+type DeepLinkHistoryMode = 'push' | 'replace' | 'smart';
+/**
+ * Customise the URL parameter names the shell reads / writes. Useful when
+ * a host already uses one of these keys for something else.
+ */
+interface DeepLinkParamNames {
+    /** Default `'item'`. */
+    item?: string;
+    /** Default `'scope'`. */
+    scope?: string;
+    /** Default `'view'`. */
+    view?: string;
+}
+/**
+ * The shell-owned deep-link state. All fields are optional — `null` /
+ * `undefined` means "absent from the URL".
+ */
+interface DeepLinkState {
+    /** Item id when an item is open in the editor. */
+    item?: string | null;
+    /** Scope ref when no item is open and the user is browsing a list. */
+    scope?: string | null;
+    /** Right-pane view choice (`table` / `cards` / `gallery`). */
+    view?: string | null;
+}
+/**
+ * Pluggable bridge between the shell and the host's URL. Hosts can supply
+ * their own adapter to integrate with React Router, hash routing, the
+ * SmartLinks `persistentQueryParams` helper, etc. When omitted the shell
+ * falls back to a plain `window.location` + `window.history` adapter.
+ */
+interface DeepLinkAdapter {
+    /** Read the current values for the shell-owned params. */
+    read(): DeepLinkState;
+    /**
+     * Write a partial state update. `mode` is the resolved push/replace hint
+     * (the shell already mapped `'smart'` to one of the two before calling).
+     * Hosts should preserve every other URL parameter — only the keys
+     * supplied here may be touched.
+     */
+    write(partial: DeepLinkState, mode: 'push' | 'replace'): void;
+    /**
+     * Subscribe to external URL changes (back/forward, host-driven nav).
+     * Should fire whenever the params the shell cares about may have
+     * changed. Returns an unsubscribe function.
+     */
+    subscribe(listener: () => void): () => void;
+}
+interface DeepLinkOptions {
+    /** Master switch — default `false` (opt in per app). */
+    enabled?: boolean;
+    /** Push/replace strategy. Default `'smart'`. */
+    history?: DeepLinkHistoryMode;
+    /** Override the default param key names. */
+    paramNames?: DeepLinkParamNames;
+    /**
+     * Pluggable URL bridge. Defaults to `window.location` + `window.history`
+     * with a `popstate` subscription. Provide one when the host owns routing
+     * (React Router, hash router, iframe postMessage relay, etc.).
+     */
+    adapter?: DeepLinkAdapter;
+}
+/**
+ * Resolved param names — everywhere outside the public surface uses these
+ * to avoid the optional-key ceremony.
+ */
+interface ResolvedDeepLinkParamNames {
+    item: string;
+    scope: string;
+    view: string;
+}
+declare const DEFAULT_DEEP_LINK_PARAM_NAMES: ResolvedDeepLinkParamNames;
+
 interface RecordsAdminIcons {
     scope: Record<ScopeKind | 'universal', LucideIcon>;
     status: {
@@ -348,6 +521,46 @@ interface RecordSlotContext {
     /** Friendly label for "Paste from {sourceLabel}" in row menus. */
     clipboardSourceLabel?: string;
 }
+/**
+ * Declarative column definition for the built-in default item table.
+ * Supply `itemColumns` for the lazy path; supply `renderItemList` /
+ * `renderItemCard` for full control.
+ */
+interface ItemColumn<TData = unknown> {
+    /** Stable key — used for React keys and per-column persistence. */
+    key: string;
+    /** Column header label. */
+    header: string;
+    /**
+     * Render the cell content. Receives the record summary plus the typed
+     * `data` for convenience.
+     */
+    render: (record: RecordSummary<TData>) => ReactNode;
+    /** CSS width hint applied to the `<th>` (and matching `<td>`). */
+    width?: string;
+    /** Right-align the cell (numeric columns). */
+    align?: 'left' | 'right' | 'center';
+}
+/**
+ * Context passed to right-pane item-view slot renderers.
+ */
+interface ItemViewContext {
+    /** Open the item in the editor. */
+    onOpen: (itemId: string) => void;
+    /** Create a new item in the current scope. */
+    onCreate: () => void;
+    /** Delete an item by id. */
+    onDelete: (itemId: string) => void;
+    /** The scope the items belong to. */
+    scope: ParsedRef;
+    /** Item id currently open in the editor (when applicable). */
+    selectedId?: string;
+    /** True while the items are loading. */
+    isLoading: boolean;
+}
+interface ItemSlotContext extends ItemViewContext {
+    selected: boolean;
+}
 interface RecordsAdminShellProps<TData = unknown> {
     SL: SmartLinksSDK;
     appId: string;
@@ -426,6 +639,24 @@ interface RecordsAdminShellProps<TData = unknown> {
     intro?: {
         title: string;
         body: ReactNode;
+        /**
+         * Where to surface the "show again" affordance after the user dismisses
+         * the intro banner.
+         *
+         * - `'header'` *(default)* — small ghost icon-button (`?`) inline inside
+         *   the `ShellHeader`, right-aligned next to `headerActions`. Zero
+         *   vertical footprint. Auto-falls back to `'footer'` when no header
+         *   card is rendered (host hasn't enabled it).
+         * - `'footer'` — render the `?` button in the quiet utility row that
+         *   sits above the rail/editor split.
+         * - `'inline'` — legacy behaviour: full-width strip with a "How it
+         *   works" pill on the right.
+         * - `'hidden'` — once dismissed, do not offer a way to bring it back
+         *   from this surface. The host can still re-enable via state reset.
+         */
+        reopenAffordance?: 'header' | 'footer' | 'inline' | 'hidden';
+        /** Override the default "How it works" label / tooltip. */
+        reopenLabel?: string;
     };
     csvSchema?: CsvSchema<TData>;
     classify?: (record: RecordSummary<TData>) => RecordStatus;
@@ -439,13 +670,9 @@ interface RecordsAdminShellProps<TData = unknown> {
     /** Initial presentation when nothing is persisted. Default first of `presentations`. */
     defaultPresentation?: RecordPresentation;
     /**
-     * Optional custom card renderer used by `grid` / `gallery` presentations.
-     * If omitted the shell uses `<DefaultRecordCard>`.
-     */
-    renderCard?: (record: RecordSummary<TData>, ctx: RecordSlotContext) => ReactNode;
-    /**
-     * Optional custom list-row renderer used by `list` / `compact` presentations.
-     * If omitted the shell uses `<DefaultRecordRow>`.
+     * Optional custom row renderer for the rail. Applied to both `list` and
+     * `compact` densities. Cards/galleries are not supported in the rail —
+     * they belong on the right pane (see `renderItemList` / `itemView`).
      */
     renderListRow?: (record: RecordSummary<TData>, ctx: RecordSlotContext) => ReactNode;
     /**
@@ -458,8 +685,11 @@ interface RecordsAdminShellProps<TData = unknown> {
     /**
      * Whether each scope holds at most one record (`singleton`, default) or
      * many (`collection`, e.g. FAQs / recipes / SOPs). In collection mode the
-     * shell treats scopes as folders containing items, exposes a "+ New" action,
-     * and the `RecordEditor` works on individual items via `itemId`-suffixed refs.
+     * shell treats scopes as folders containing items: when a scope is selected
+     * with no item open, the right pane shows the multi-item view (default
+     * table, or `renderItemList` / `itemView` overrides). Clicking an item
+     * opens it in the editor with Back / prev / next nav, and the rail flips
+     * to siblings (see `collectionRailMode`).
      */
     cardinality?: RecordCardinality;
     /** Display name for an item in collection mode (defaults to `'item'`). */
@@ -469,6 +699,47 @@ interface RecordsAdminShellProps<TData = unknown> {
      * timestamp+random string.
      */
     generateItemId?: () => string;
+    /**
+     * Which built-in item views the right pane offers when a scope is selected
+     * and no item is open. Default `['table']`. When more than one is supplied,
+     * a switcher appears above the item view and the choice persists per
+     * `appId` + `recordType`.
+     *
+     * Ignored when `renderItemList` is supplied (the host owns the entire view).
+     */
+    itemViews?: ItemView[];
+    /** Initial item view when nothing is persisted. Default first of `itemViews`. */
+    defaultItemView?: ItemView;
+    /**
+     * Declarative columns for the built-in default `table` view. The shell
+     * renders a styled table — most apps with a few well-defined fields
+     * (FAQ question + last-updated, recipe name + cuisine + servings) want
+     * this rather than a custom renderer.
+     */
+    itemColumns?: ItemColumn<TData>[];
+    /**
+     * Full custom item-view renderer. When supplied, replaces the built-in
+     * table / cards / gallery entirely — `itemViews`, `itemColumns`, and
+     * `renderItemCard` are ignored.
+     */
+    renderItemList?: (items: RecordSummary<TData>[], ctx: ItemViewContext) => ReactNode;
+    /**
+     * Custom card renderer for the `cards` and `gallery` item views. Falls
+     * back to a styled built-in card when omitted.
+     */
+    renderItemCard?: (record: RecordSummary<TData>, ctx: ItemSlotContext) => ReactNode;
+    /**
+     * Custom empty state when a scope has no items yet. Falls back to a
+     * styled built-in empty state with a "+ New {noun}" CTA.
+     */
+    renderItemEmpty?: (ctx: ItemViewContext) => ReactNode;
+    /**
+     * What the rail shows once an item is open (collection cardinality only).
+     * Default `'siblings'` — the rail flips to the items in the current scope
+     * with a pinned `← All scopes` link. Set to `'scopes'` to keep the rail
+     * on scope navigation (admin must use Back / prev / next instead).
+     */
+    collectionRailMode?: CollectionRailMode;
     /** Display title shown in the header card. Falls back to `label`, then `recordType`. */
     title?: string;
     /** Single-line muted subtitle under the header title. */
@@ -570,6 +841,21 @@ interface RecordsAdminShellProps<TData = unknown> {
         scope: ParsedRef;
         currentValue: TData | null;
     }) => TData | null;
+    /**
+     * Mirror the shell's runtime state (current scope, open item, right-pane
+     * view) into URL parameters so links open to the right place and the
+     * browser back/forward buttons feel native.
+     *
+     * Off by default. The shell only owns the params it knows about
+     * (`item`, `scope`, `view`); platform context like `appId` /
+     * `collectionId` lives in the host's URL and stays untouched.
+     *
+     * Pass an `adapter` to integrate with a host router (React Router,
+     * SmartLinks `persistentQueryParams`, etc.) — without one the shell
+     * uses a default `window.location` + `window.history` adapter that
+     * also handles hash routing.
+     */
+    deepLink?: DeepLinkOptions;
 }
 /**
  * Controls the small tab strip that appears above the editor body inside the
@@ -616,7 +902,7 @@ interface RecordBrowserProps {
 }
 declare const RecordBrowser: ({ scopes, activeScope, onActiveScopeChange, selectedRef, onSelectRef, items, counts, isLoading, error, filter, onFilterChange, search, onSearchChange, hasNextPage, isFetchingNextPage, onLoadMore, scopesLoading, i18n, }: RecordBrowserProps) => react_jsx_runtime.JSX.Element;
 
-interface Props$9 {
+interface Props$g {
     scopes: ScopeKind[];
     active: ScopeKind;
     onChange: (s: ScopeKind) => void;
@@ -627,17 +913,31 @@ interface Props$9 {
     /** Override icons used per scope. Falls back to DEFAULT_ICONS.scope. */
     icons?: RecordsAdminIcons['scope'];
 }
-declare const ScopeTabs: ({ scopes, active, onChange, loading, counts, icons, }: Props$9) => react_jsx_runtime.JSX.Element;
+declare const ScopeTabs: ({ scopes, active, onChange, loading, counts, icons, }: Props$g) => react_jsx_runtime.JSX.Element;
 
-interface Props$8 {
+interface Props$f {
     source?: RecordSource;
     status?: RecordStatus;
     className?: string;
 }
 /** Emerald = own data, amber = inherited, muted = empty */
-declare const StatusDot: ({ source, status, className }: Props$8) => react_jsx_runtime.JSX.Element;
+declare const StatusDot: ({ source, status, className }: Props$f) => react_jsx_runtime.JSX.Element;
 
-interface Props$7 {
+type StatusTone = 'own' | 'shared' | 'missing';
+interface Props$e {
+    source?: RecordSource;
+    status?: RecordStatus;
+    className?: string;
+    /** Override icon size (default 1.05rem). */
+    size?: string;
+    /** Optional accessible label — defaults to the tone name. */
+    label?: string;
+}
+declare const StatusIcon: ({ source, status, className, size, label }: Props$e) => react_jsx_runtime.JSX.Element;
+/** Short label rendered next to / under the row title. */
+declare const statusToneLabel: (tone: StatusTone) => string;
+
+interface Props$d {
     value: 'all' | RecordStatus;
     onChange: (v: 'all' | RecordStatus) => void;
     counts: {
@@ -652,20 +952,18 @@ interface Props$7 {
      *  active filter is always rendered so users never lose context. */
     hideZero?: Array<'all' | RecordStatus>;
 }
-declare const StatusFilterPills: ({ value, onChange, counts, i18n, hideZero }: Props$7) => react_jsx_runtime.JSX.Element;
+declare const StatusFilterPills: ({ value, onChange, counts, i18n, hideZero }: Props$d) => react_jsx_runtime.JSX.Element;
 
-interface Props$6 {
+interface Props$c {
     items: RecordSummary[];
     selectedRef?: string;
     onSelect: (item: RecordSummary) => void;
     /** When set, the matching row gets a small "unsaved" indicator. */
     dirtyRef?: string;
-    /** Layout. Defaults to `list` for full back-compat. */
+    /** Rail row density. Defaults to `list`. */
     presentation?: RecordPresentation;
-    /** Optional override for `list` / `compact` rows. */
+    /** Optional custom row renderer (still dense — applied to both densities). */
     renderListRow?: (record: RecordSummary, ctx: RecordSlotContext) => ReactNode;
-    /** Optional override for `grid` / `gallery` cards. */
-    renderCard?: (record: RecordSummary, ctx: RecordSlotContext) => ReactNode;
     /** Optional grouping function. Returning null buckets the row under "Other". */
     groupBy?: (record: RecordSummary) => {
         key: string;
@@ -685,11 +983,11 @@ interface Props$6 {
         clipboardSourceLabel?: string;
     } | null;
 }
-declare const RecordList: ({ items, selectedRef, onSelect, dirtyRef, presentation, renderListRow, renderCard, groupBy, rowClipboard, }: Props$6) => react_jsx_runtime.JSX.Element;
-declare const ProductList: ({ items, selectedRef, onSelect, dirtyRef, presentation, renderListRow, renderCard, groupBy, rowClipboard, }: Props$6) => react_jsx_runtime.JSX.Element;
-declare const FacetList: ({ items, selectedRef, onSelect, dirtyRef, presentation, renderListRow, renderCard, groupBy, rowClipboard, }: Props$6) => react_jsx_runtime.JSX.Element;
-declare const VariantList: ({ items, selectedRef, onSelect, dirtyRef, presentation, renderListRow, renderCard, groupBy, rowClipboard, }: Props$6) => react_jsx_runtime.JSX.Element;
-declare const BatchList: ({ items, selectedRef, onSelect, dirtyRef, presentation, renderListRow, renderCard, groupBy, rowClipboard, }: Props$6) => react_jsx_runtime.JSX.Element;
+declare const RecordList: ({ items, selectedRef, onSelect, dirtyRef, presentation, renderListRow, groupBy, rowClipboard, }: Props$c) => react_jsx_runtime.JSX.Element;
+declare const ProductList: ({ items, selectedRef, onSelect, dirtyRef, presentation, renderListRow, groupBy, rowClipboard, }: Props$c) => react_jsx_runtime.JSX.Element;
+declare const FacetList: ({ items, selectedRef, onSelect, dirtyRef, presentation, renderListRow, groupBy, rowClipboard, }: Props$c) => react_jsx_runtime.JSX.Element;
+declare const VariantList: ({ items, selectedRef, onSelect, dirtyRef, presentation, renderListRow, groupBy, rowClipboard, }: Props$c) => react_jsx_runtime.JSX.Element;
+declare const BatchList: ({ items, selectedRef, onSelect, dirtyRef, presentation, renderListRow, groupBy, rowClipboard, }: Props$c) => react_jsx_runtime.JSX.Element;
 
 interface DefaultRecordRowProps {
     record: RecordSummary;
@@ -731,7 +1029,7 @@ declare const ErrorState: ({ error }: {
     error: Error;
 }) => react_jsx_runtime.JSX.Element;
 
-interface Props$5 {
+interface Props$b {
     i18n: RecordsAdminI18n;
     onApplyToMany?: () => void;
     onCopyFrom?: () => void;
@@ -739,9 +1037,9 @@ interface Props$5 {
     onImportCsv?: () => void;
     onExportCsv?: () => void;
 }
-declare const BulkActionsMenu: ({ i18n, onApplyToMany, onCopyFrom, onClearMany, onImportCsv, onExportCsv, }: Props$5) => react_jsx_runtime.JSX.Element | null;
+declare const BulkActionsMenu: ({ i18n, onApplyToMany, onCopyFrom, onClearMany, onImportCsv, onExportCsv, }: Props$b) => react_jsx_runtime.JSX.Element | null;
 
-interface Props$4<T> {
+interface Props$a<T> {
     ctx: EditorContext<T>;
     i18n: RecordsAdminI18n;
     children: ReactNode;
@@ -784,7 +1082,7 @@ interface Props$4<T> {
     /** Host-provided icons rendered before save / discard / delete labels. */
     actionIcons?: Partial<Record<RecordsAdminActionKey, RecordsAdminActionIcon>>;
 }
-declare function RecordEditor<T>({ ctx, i18n, children, preview, bulkActions, footerExtra, onBeforeDelete, headerLabel, headerSubtitle, headerMeta, clipboard, actionLabels, actionIcons, }: Props$4<T>): react_jsx_runtime.JSX.Element;
+declare function RecordEditor<T>({ ctx, i18n, children, preview, bulkActions, footerExtra, onBeforeDelete, headerLabel, headerSubtitle, headerMeta, clipboard, actionLabels, actionIcons, }: Props$a<T>): react_jsx_runtime.JSX.Element;
 
 interface InheritanceCtx {
     parentValue?: Record<string, unknown> | null;
@@ -802,10 +1100,10 @@ interface MarkerProps {
 }
 declare const InheritanceMarker: ({ field, inheritedValue, value, children }: MarkerProps) => react_jsx_runtime.JSX.Element;
 
-interface Props$3 {
+interface Props$9 {
     children: ReactNode;
 }
-declare const ResolvedPreview: ({ children }: Props$3) => react_jsx_runtime.JSX.Element;
+declare const ResolvedPreview: ({ children }: Props$9) => react_jsx_runtime.JSX.Element;
 
 interface ProductChildItem {
     /** Variant or batch id (the `<id>` part of `variant:<id>` / `batch:<id>`). */
@@ -836,7 +1134,7 @@ declare const useProductChildren: (args: UseProductChildrenArgs) => {
 };
 
 type DrillTab = 'product' | 'variant' | 'batch';
-interface Props$2 {
+interface Props$8 {
     productLabel: string;
     /** Which child types are available on the collection. */
     showVariants: boolean;
@@ -861,7 +1159,7 @@ interface Props$2 {
      */
     hideSingleTab?: boolean;
 }
-declare const ProductDrillDown: ({ productLabel, showVariants, showBatches, active, onChange, selectedChildId, onSelectChild, variants, batches, variantsLoading, batchesLoading, children, hideSingleTab, }: Props$2) => react_jsx_runtime.JSX.Element;
+declare const ProductDrillDown: ({ productLabel, showVariants, showBatches, active, onChange, selectedChildId, onSelectChild, variants, batches, variantsLoading, batchesLoading, children, hideSingleTab, }: Props$8) => react_jsx_runtime.JSX.Element;
 
 type PreviewMode = 'inline' | 'side' | 'tab' | 'drawer';
 interface CommonProps {
@@ -928,7 +1226,7 @@ declare const ScopeBreadcrumb: ({ scope }: {
 }) => react_jsx_runtime.JSX.Element | null;
 
 type IntroTone = 'info' | 'success' | 'warning';
-interface Props$1 {
+interface Props$7 {
     title: string;
     body: ReactNode;
     onDismiss: () => void;
@@ -937,14 +1235,16 @@ interface Props$1 {
     /** Optional "Learn more" link or button rendered inline after the body. */
     action?: ReactNode;
 }
-declare const IntroCard: ({ title, body, onDismiss, tone, action }: Props$1) => react_jsx_runtime.JSX.Element;
+declare const IntroCard: ({ title, body, onDismiss, tone, action }: Props$7) => react_jsx_runtime.JSX.Element;
 
-interface Props {
+interface Props$6 {
     label: string;
+    /** Optional override for the button label. When set, takes precedence over `label`. */
+    customLabel?: string;
     introHidden: boolean;
     onShowIntro?: () => void;
 }
-declare const UtilityRow: ({ label, introHidden, onShowIntro }: Props) => react_jsx_runtime.JSX.Element | null;
+declare const UtilityRow: ({ label, customLabel, introHidden, onShowIntro }: Props$6) => react_jsx_runtime.JSX.Element | null;
 
 interface RecordsCtx {
     SL: SmartLinksSDK;
@@ -1121,6 +1421,68 @@ declare function useResolvedRecord<T = unknown>(args: UseResolvedRecordArgs): {
     matchedRule?: _proveanything_smartlinks_dist_types_appObjects.FacetRule;
 };
 
+interface UseCollectionItemsArgs {
+    ctx: RecordsCtx;
+    /**
+     * Scope the items live under. Items at the collection root pass an empty
+     * `scope.raw` (the hook then uses `refPrefix: 'item:'`). Pass `null` to
+     * keep the query disabled.
+     */
+    scope: ParsedRef | null;
+    /** Per-page size requested from the SDK (default 100). */
+    pageSize?: number;
+    /**
+     * Optional projector that derives the row label / subtitle / thumbnail
+     * from a record's `data`. Falls back to the itemId.
+     */
+    toSummary?: (rec: AppRecord, base: RecordSummary) => RecordSummary;
+    /** When false, the query is paused (used while the host is still booting). */
+    enabled?: boolean;
+}
+/**
+ * The shell's `useRecordList` filters by *scope kind*, which doesn't
+ * differentiate items from singletons. This hook intentionally bypasses
+ * that filter and asks for refs under a precise prefix.
+ */
+declare function useCollectionItems<T = unknown>(args: UseCollectionItemsArgs): {
+    items: RecordSummary<T>[];
+    total: number;
+    isLoading: boolean;
+    error: Error | null;
+    hasNextPage: boolean;
+    isFetchingNextPage: boolean;
+    fetchNextPage: (options?: _tanstack_query_core.FetchNextPageOptions) => Promise<_tanstack_query_core.InfiniteQueryObserverResult<_tanstack_query_core.InfiniteData<{
+        data: AppRecord[];
+        total: number;
+        hasMore: boolean;
+        nextOffset: number;
+    }, unknown>, Error>>;
+    refetch: () => void;
+};
+
+/**
+ * Which logical changes are "meaningful navigation" (push) vs "cosmetic /
+ * incremental" (replace) under `'smart'` history mode. The shell tags each
+ * emit with one of these.
+ */
+type DeepLinkChangeKind = 'item.open' | 'item.close' | 'item.step' | 'scope' | 'view';
+interface UseDeepLinkStateResult {
+    /** Latest snapshot read from the adapter. */
+    urlState: DeepLinkState;
+    /**
+     * Push a partial update through the adapter. `kind` informs the
+     * push-vs-replace decision under `'smart'` mode.
+     */
+    emit: (partial: DeepLinkState, kind: DeepLinkChangeKind) => void;
+    /** Resolved param names for callers that need them. */
+    paramNames: ResolvedDeepLinkParamNames;
+    /** True when deep linking is active (host opted in + we have an adapter). */
+    enabled: boolean;
+}
+declare function useDeepLinkState(options: DeepLinkOptions | undefined): UseDeepLinkStateResult;
+
+declare const createDefaultDeepLinkAdapter: (paramNames: ResolvedDeepLinkParamNames) => DeepLinkAdapter;
+
 interface UseResolveAllRecordsArgs {
     SL: SmartLinksSDK;
     collectionId: string;
@@ -1434,6 +1796,88 @@ declare function usePresentationPref(args: {
     options: RecordPresentation[];
     defaultValue: RecordPresentation;
 }): [RecordPresentation, (next: RecordPresentation) => void];
+/**
+ * Twin of `usePresentationPref` for the right-pane item view (collection
+ * cardinality only). Stored under a distinct key so toggling the rail
+ * presentation never clobbers the table/cards/gallery preference.
+ */
+declare function useItemViewPref(args: {
+    appId: string;
+    recordType?: string;
+    options: ItemView[];
+    defaultValue: ItemView;
+}): [ItemView, (next: ItemView) => void];
+
+interface Props$5<T> {
+    items: RecordSummary<T>[];
+    isLoading: boolean;
+    error: Error | null;
+    ctx: ItemViewContext;
+    itemNoun: string;
+    view: ItemView;
+    views: ItemView[];
+    onViewChange: (view: ItemView) => void;
+    renderItemList?: (items: RecordSummary<T>[], ctx: ItemViewContext) => ReactNode;
+    renderItemCard?: (record: RecordSummary<T>, ctx: ItemSlotContext) => ReactNode;
+    renderItemEmpty?: (ctx: ItemViewContext) => ReactNode;
+    itemColumns?: ItemColumn<T>[];
+    i18n: RecordsAdminI18n;
+}
+declare function ItemListView<T>({ items, isLoading, error, ctx, itemNoun, view, views, onViewChange, renderItemList, renderItemCard, renderItemEmpty, itemColumns, i18n, }: Props$5<T>): react_jsx_runtime.JSX.Element;
+
+interface Props$4 {
+    options: ItemView[];
+    value: ItemView;
+    onChange: (next: ItemView) => void;
+    i18n: Pick<RecordsAdminI18n, 'itemViewTable' | 'itemViewCards' | 'itemViewGallery'>;
+}
+declare const ItemViewSwitcher: ({ options, value, onChange, i18n }: Props$4) => react_jsx_runtime.JSX.Element | null;
+
+interface Props$3<T> {
+    items: RecordSummary<T>[];
+    columns?: ItemColumn<T>[];
+    selectedId?: string;
+    onOpen: (itemId: string) => void;
+    onDelete: (itemId: string) => void;
+    i18n: Pick<RecordsAdminI18n, 'itemColumnLabel' | 'itemColumnUpdated' | 'itemActions' | 'delete'>;
+}
+declare function DefaultItemTable<T>({ items, columns, selectedId, onOpen, onDelete, i18n, }: Props$3<T>): react_jsx_runtime.JSX.Element;
+
+interface Props$2<T> {
+    items: RecordSummary<T>[];
+    variant: 'cards' | 'gallery';
+    selectedId?: string;
+    ctx: ItemViewContext;
+    renderCard?: (record: RecordSummary<T>, slotCtx: ItemSlotContext) => ReactNode;
+    i18n: Pick<RecordsAdminI18n, 'delete'>;
+}
+declare function DefaultItemCards<T>({ items, variant, selectedId, ctx, renderCard, i18n, }: Props$2<T>): react_jsx_runtime.JSX.Element;
+
+interface Props$1 {
+    /** Friendly name of the item being edited (mostly for screen readers). */
+    label?: string;
+    /** 1-based position within the current sibling list. */
+    position?: number;
+    total?: number;
+    onBack: () => void;
+    onPrev?: () => void;
+    onNext?: () => void;
+    canPrev: boolean;
+    canNext: boolean;
+    i18n: Pick<RecordsAdminI18n, 'backToList' | 'prevItem' | 'nextItem'>;
+}
+declare const EditorItemNav: ({ label, position, total, onBack, onPrev, onNext, canPrev, canNext, i18n, }: Props$1) => react_jsx_runtime.JSX.Element;
+
+interface Props<T> {
+    items: RecordSummary<T>[];
+    selectedItemId?: string;
+    isLoading: boolean;
+    error: Error | null;
+    onBack: () => void;
+    onSelect: (itemId: string) => void;
+    i18n: Pick<RecordsAdminI18n, 'backToScopes' | 'siblingsHeading' | 'noItemsTitle' | 'noItemsBody'>;
+}
+declare function SiblingRail<T>({ items, selectedItemId, isLoading, error, onBack, onSelect, i18n, }: Props<T>): react_jsx_runtime.JSX.Element;
 
 interface ClipboardEntry<T = unknown> {
     value: T;
@@ -1504,6 +1948,7 @@ interface BuildRefArgs {
     variantId?: string;
     batchId?: string;
     proofId?: string;
+    itemId?: string;
 }
 declare const buildRef: (a: BuildRefArgs) => string;
 /**
@@ -1511,6 +1956,17 @@ declare const buildRef: (a: BuildRefArgs) => string;
  * `supportedScopes` prunes scopes the app doesn't care about.
  */
 declare const resolutionChain: (target: ParsedRef, supportedScopes: ScopeKind[]) => string[];
+/**
+ * Strip the trailing `/item:{id}` (or leading `item:{id}`) from a ref and
+ * return both halves. For singleton refs `itemId` is `undefined` and
+ * `scopeRef` equals the input.
+ */
+declare const splitItemRef: (raw: string) => {
+    scopeRef: string;
+    itemId?: string;
+};
+/** Concatenate a scope ref (possibly empty for collection) and an itemId. */
+declare const buildItemRef: (scopeRef: string, itemId: string) => string;
 
 interface ResolveArgs {
     ctx: RecordsCtx;
@@ -1550,4 +2006,4 @@ declare const exportCsv: <T>(records: RecordSummary<T>[], schema: CsvSchema<T>)
 declare const importCsv: <T>(file: File, schema: CsvSchema<T>, ctx: RecordsCtx) => Promise<ImportReport>;
 declare const downloadBlob: (blob: Blob, filename: string) => void;
 
-export { ALL_PRESENTATIONS, BatchList, BulkActionsMenu, type ClipboardEntry, type CollectedRecord, type CollectedSort, type CsvSchema, type CsvSchemaColumn, DEFAULT_I18N, DEFAULT_ICONS, DefaultRecordCard, DefaultRecordRow, DeleteButton, type DirtyStrategy, DrawerPreview, type EditorContext, EmptyState, ErrorState, FacetList, InheritanceMarker, InheritanceProvider, InlinePreview, IntroCard, LoadingState, type MergeStrategy, type MergedRecord, type NavConfirmI18n, type ParsedRef, type PasteCompatibility, type PasteCompatibilityResult, PresentationSwitcher, type PreviewMode, PreviewScopePicker, PreviewToggleButton, type ProductBrowseItem, type ProductChildItem, ProductDrillDown, ProductList, type RecordBadge, RecordBrowser, type RecordCardinality, RecordEditor, RecordList, type RecordPresentation, type RecordSlotContext, type RecordSource, type RecordStatus, type RecordSummary, type RecordsAdminI18n, type RecordsAdminIcons, RecordsAdminShell, type RecordsAdminShellProps, ResolvedPreview, type ResolvedRecord, ScopeBreadcrumb, type ScopeKind, ScopeTabs, SidePreview, type SmartLinksSDK, StatusDot, StatusFilterPills, TabbedPreview, type TelemetryEvent, type UseRecordClipboardArgs, type UseRecordClipboardReturn, type UseResolveAllRecordsArgs, type UseResolveAllResult, type UseRulePreviewArgs, type UseRulePreviewResult, UtilityRow, VariantList, buildRef, bulkDelete, bulkUpsert, checkPasteCompatibility, cloneValue, deleteRecord, downloadBlob, exportCsv, getRecordByRef, importCsv, listRecords, matchRecords, mergeIcons, parseRef, parsedRefToScope, parsedRefToTarget, pickHeaderIcon, resolutionChain, resolveRecord, restoreRecord, scopesEqual, upsertRecord, useCollectedRecords, useDirtyNavigation, useFacetBrowse, useIntroDismissed, useMergedRecord, usePresentationPref, useProductBrowse, useProductChildren, useRecordClipboard, useRecordEditor, useRecordList, useResolveAllRecords, useResolvedRecord, useRulePreview, useScopeProbe, useUnsavedGuard };
+export { ALL_ITEM_VIEWS, ALL_PRESENTATIONS, BatchList, BulkActionsMenu, type ClipboardEntry, type CollectedRecord, type CollectedSort, type CollectionRailMode, type CsvSchema, type CsvSchemaColumn, DEFAULT_DEEP_LINK_PARAM_NAMES, DEFAULT_I18N, DEFAULT_ICONS, type DeepLinkAdapter, type DeepLinkChangeKind, type DeepLinkHistoryMode, type DeepLinkOptions, type DeepLinkParamNames, type DeepLinkState, DefaultItemCards, DefaultItemTable, DefaultRecordCard, DefaultRecordRow, DeleteButton, type DirtyStrategy, DrawerPreview, type EditorContext, EditorItemNav, EmptyState, ErrorState, FacetList, InheritanceMarker, InheritanceProvider, InlinePreview, IntroCard, type ItemColumn, ItemListView, type ItemSlotContext, type ItemView, type ItemViewContext, ItemViewSwitcher, LoadingState, type MergeStrategy, type MergedRecord, type NavConfirmI18n, type ParsedRef, type PasteCompatibility, type PasteCompatibilityResult, PresentationSwitcher, type PreviewMode, PreviewScopePicker, PreviewToggleButton, type ProductBrowseItem, type ProductChildItem, ProductDrillDown, ProductList, type RecordBadge, RecordBrowser, type RecordCardinality, RecordEditor, RecordList, type RecordPresentation, type RecordSlotContext, type RecordSource, type RecordStatus, type RecordSummary, type RecordsAdminI18n, type RecordsAdminIcons, RecordsAdminShell, type RecordsAdminShellProps, type ResolvedDeepLinkParamNames, ResolvedPreview, type ResolvedRecord, ScopeBreadcrumb, type ScopeKind, ScopeTabs, SiblingRail, SidePreview, type SmartLinksSDK, StatusDot, StatusFilterPills, StatusIcon, type StatusTone, TabbedPreview, type TelemetryEvent, type UseCollectionItemsArgs, type UseRecordClipboardArgs, type UseRecordClipboardReturn, type UseResolveAllRecordsArgs, type UseResolveAllResult, type UseRulePreviewArgs, type UseRulePreviewResult, UtilityRow, VariantList, buildItemRef, buildRef, bulkDelete, bulkUpsert, checkPasteCompatibility, cloneValue, createDefaultDeepLinkAdapter, deleteRecord, downloadBlob, exportCsv, getRecordByRef, importCsv, listRecords, matchRecords, mergeIcons, parseRef, parsedRefToScope, parsedRefToTarget, pickHeaderIcon, resolutionChain, resolveRecord, restoreRecord, scopesEqual, splitItemRef, statusToneLabel, upsertRecord, useCollectedRecords, useCollectionItems, useDeepLinkState, useDirtyNavigation, useFacetBrowse, useIntroDismissed, useItemViewPref, useMergedRecord, usePresentationPref, useProductBrowse, useProductChildren, useRecordClipboard, useRecordEditor, useRecordList, useResolveAllRecords, useResolvedRecord, useRulePreview, useScopeProbe, useUnsavedGuard };