@proveanything/smartlinks-utils-ui 0.8.2 → 0.9.0

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

@@ -658,286 +658,211 @@ interface RecordsAdminShellProps<TData = unknown> {
         variantId?: string;
         batchId?: string;
     };
-    renderEditor: (ctx: EditorContext<TData>) => ReactNode;
-    /**
-     * Render the preview surface. Receives the editor's current value so the
-     * preview tracks unsaved edits. When `previewScope` differs from the
-     * editing scope (because the user picked something in `<PreviewScopePicker>`),
-     * `previewScope` reflects the chosen target — apps can use it to load
-     * resolved/collected/merged data for that scope instead of `resolved`.
-     */
-    renderPreview?: (ctx: {
-        resolved: TData | null;
-        previewScope: ParsedRef;
-    }) => ReactNode;
-    /**
-     * How the preview surface attaches to the editor pane.
-     * - `inline` (default): rendered below the form (current behaviour).
-     * - `side`:   resizable right pane next to the editor.
-     * - `tab`:    Editor / Preview siblings inside the right pane.
-     * - `drawer`: slide-out from the right, toggled by a button.
-     */
-    previewMode?: 'inline' | 'side' | 'tab' | 'drawer';
-    /**
-     * When true, render a `<PreviewScopePicker>` in the preview chrome so admins
-     * can preview as a different product/variant/batch than they're editing.
-     * Default false.
-     */
-    previewScopePicker?: boolean;
-    /**
-     * Editor tab strip behaviour. See {@link RecordsAdminEditorTabsMode}.
-     * Default `'off'` — the redundant single-tab strip is hidden when the
-     * product has no variants/batches.
-     */
-    editorTabs?: RecordsAdminEditorTabsMode;
-    /**
-     * How to handle unsaved edits when the user navigates to a different
-     * record/scope/tab.
-     * - `prompt` (default): show a confirm dialog (Discard / Cancel / Save).
-     * - `autosave`: silently save before navigating away.
-     * - `keep`: hold edits in memory keyed by ref; coming back restores them.
-     */
-    dirtyStrategy?: 'prompt' | 'autosave' | 'keep';
-    /**
-     * Pre-delete hook. Return `false` to abort. Lets apps run app-specific
-     * confirms (e.g. "this batch has 12k linked proofs"). When omitted the
-     * inline two-step confirm is the only safeguard.
-     */
-    onBeforeDelete?: (scope: ParsedRef) => boolean | Promise<boolean>;
     /**
-     * Disable the browser-level `beforeunload` prompt. Default false.
-     * Set true when the host platform handles unload guarding itself.
+     * How the rail should react when `contextScope.productId` is pinned.
+     *
+     * - `'strict'` (default) — the host has scoped this mount to one product.
+     *   The rail hides `'collection'` (Global) and `'rule'` tabs entirely
+     *   (they're collection-wide concerns the product inherits) and the
+     *   product list collapses to that single product. When the product has
+     *   no variants and no batches available for drill-down AND no other
+     *   top-level scopes survive, the rail itself is hidden and the editor
+     *   takes the whole pane.
+     * - `'expand'` — legacy behaviour. The full rail renders; pinning only
+     *   biases the default tab + selected product.
+     *
+     * Has no effect when `contextScope.productId` is not set.
      */
-    disableBeforeUnload?: boolean;
-    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;
-    };
+    contextScopeMode?: 'strict' | 'expand';
+    renderEditor: (ctx: EditorContext<TData>) => ReactNode;
     csvSchema?: CsvSchema<TData>;
     classify?: (record: RecordSummary<TData>) => RecordStatus;
     defaultData?: () => TData;
     /**
-     * Optional derivation for the label that represents an in-flight draft
-     * in the unsaved-changes tray. Receives the editor's current value and
-     * its scope; return a short, human-readable title (or `undefined` to
-     * defer to the built-in heuristic). Useful when your record shape nests
-     * the title under a custom key the heuristic doesn't know about.
-     */
-    deriveDraftLabel?: (value: TData, scope: ParsedRef) => string | undefined;
-    /**
-     * Which layouts the rail offers. Default `['list']`. When more than one is
-     * supplied, a switcher appears above the list and the choice persists
-     * per-app/recordType.
+     * Header card configuration. The card is off by default; set `show: true`
+     * (or pass any of `title` / `subtitle` / `icon` / `actions` / `stats`) to
+     * opt in.
      */
-    presentations?: RecordPresentation[];
-    /** Initial presentation when nothing is persisted. Default first of `presentations`. */
-    defaultPresentation?: RecordPresentation;
-    /**
-     * 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;
-    /**
-     * Optional custom empty-state renderer for the rail. If omitted the shell
-     * uses the default `<EmptyState>` with `i18n.emptyTitle` / `i18n.emptyBody`.
-     */
-    renderEmpty?: (ctx: {
-        scope: ParsedRef | null;
-    }) => ReactNode;
-    /**
-     * 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: 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'`). */
-    itemNoun?: string;
-    /**
-     * Generate a host-local handle for a brand-new collection item draft when
-     * "+ New" is clicked. The shell prefixes non-draft values so they remain
-     * recognisably unsaved (`draft:…`) until the first save returns a real
-     * record UUID. Use this when the host wants stable local draft identities
-     * for analytics/UI bookkeeping — not to predeclare the eventual server id.
-     */
-    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;
+    header?: HeaderConfig;
     /**
-     * Visual density of the built-in `cards` / `gallery` item views.
-     * - `'sm'` — tight: ~180px (cards) / ~240px (gallery) min column width.
-     * - `'md'` *(default)* — comfortable: ~240px / ~320px.
-     * - `'lg'` — spacious: ~320px / ~420px, suits hero-style imagery.
-     *
-     * Hosts that need exact pixel control can override the underlying
-     * `--ra-item-card-min` / `--ra-item-gallery-min` CSS custom properties
-     * on `.ra-shell` instead.
-     */
-    itemCardSize?: 'sm' | 'md' | 'lg';
-    /**
-     * Custom empty state when a scope has no items yet. Falls back to a
-     * styled built-in empty state with a "+ New {noun}" CTA.
+     * Dismissable intro / "How it works" card shown above the rail+editor split.
+     * Only renders when supplied. The reopen affordance defaults to a small
+     * icon-button inside the header (auto-falls back to the utility row when
+     * no header is rendered).
      */
-    renderItemEmpty?: (ctx: ItemViewContext) => ReactNode;
+    intro?: IntroConfig;
+    rail?: RailConfig<TData>;
+    editor?: EditorConfig<TData>;
+    items?: ItemsConfig<TData>;
+    unsaved?: UnsavedConfig<TData>;
+    clipboard?: ClipboardConfig<TData>;
+    actions?: ActionsConfig;
     /**
-     * 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).
+     * Mirror the shell's runtime state into URL params. Off by default. The
+     * shell only owns `item`, `scope`, `view` — host platform params are
+     * untouched.
      */
-    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. */
-    subtitle?: string;
-    /**
-     * Render the branded header card above the rail. Off by default — most apps
-     * don't need it (the surrounding host typically already shows a title). Set
-     * `true` to opt in, or simply pass any of the header-customising props
-     * (`title`, `subtitle`, `headerIcon`, `headerActions`, `showStats`,
-     * `statsItems`) and the header will auto-show.
-     */
-    showHeader?: boolean;
-    /** Icon shown in the header card. Falls back to `icons.header.byRecordType[recordType]`
-     *  or `icons.header.default`. Pass a Lucide icon component or any ReactNode. */
-    headerIcon?: ReactNode;
-    /** Right-aligned header content — typically a primary "+ New" button + secondary controls. */
-    headerActions?: ReactNode;
-    /** Show a counts strip in the header (e.g. Shared · Products). Off by default —
-     *  most apps don't need it. When `true`, the shell renders built-in counts unless
-     *  `statsItems` is also provided. */
-    showStats?: boolean;
-    /** Show the contextual icon to the left of the header title. Default true.
-     *  Set to `false` if the recordType icon (database, etc.) feels off-brand. */
-    showHeaderIcon?: boolean;
-    /** Fully custom stats strip content. When provided, replaces the built-in
-     *  Shared/Products counts. Each item renders as a value + uppercase label. */
-    statsItems?: Array<{
+    deepLink?: DeepLinkOptions;
+    /** Override the default Lucide icons used by the shell. Deep-merged onto
+     *  `DEFAULT_ICONS`. */
+    icons?: Partial<RecordsAdminIcons>;
+    i18n?: Partial<RecordsAdminI18n>;
+    onTelemetry?: (event: TelemetryEvent) => void;
+    className?: string;
+}
+interface HeaderStatsConfig {
+    /** Show a counts strip in the header. */
+    show?: boolean;
+    /** Fully custom stats items. When provided, replaces built-in counts. */
+    items?: Array<{
         label: string;
         value: string | number;
     }>;
     /** Optional title rendered above the stats strip (e.g. "At a glance"). */
-    statsTitle?: string;
-    /** Optional icon rendered next to `statsTitle`. Pass a Lucide icon element
-     *  or any ReactNode. */
-    statsIcon?: ReactNode;
-    /**
-     * External help / documentation link for this admin surface. When set, the
-     * shell renders a small icon-button in the header (right side) that opens
-     * the URL in a new tab. Use this to point at an app-specific help doc in
-     * your shared docs site.
-     */
+    title?: string;
+    /** Optional icon rendered next to the stats title. */
+    icon?: ReactNode;
+}
+interface HeaderConfig {
+    /** Render the branded header card above the rail. Auto-true when any other
+     *  header field is set. */
+    show?: boolean;
+    /** Display title shown in the header card. Falls back to `label`, then
+     *  `recordType`. */
+    title?: string;
+    /** Single-line muted subtitle under the title. */
+    subtitle?: string;
+    /** Icon shown to the left of the header title. Falls back to
+     *  `icons.header.byRecordType[recordType]` or `icons.header.default`. */
+    icon?: ReactNode;
+    /** Show the contextual icon. Default true. */
+    showIcon?: boolean;
+    /** Right-aligned header content — typically a primary "+ New" button. */
+    actions?: ReactNode;
+    /** External help / documentation link rendered as a small icon-button. */
     helpUrl?: string;
-    /** Tooltip / aria-label for the help link. Defaults to "Help & documentation". */
+    /** Tooltip / aria-label for the help link. Defaults to
+     *  "Help & documentation". */
     helpLabel?: string;
-    /** Override the default Lucide icons used by the shell (scope tabs, statuses,
-     *  empty states, action menus, etc.). Deep-merged onto `DEFAULT_ICONS`. */
-    icons?: Partial<RecordsAdminIcons>;
-    /** When supplied, the records list is rendered as accordion-style groups.
-     *  Return `null` to put a record in the default "Other" bucket. */
+    /** Counts strip configuration. */
+    stats?: HeaderStatsConfig;
+}
+interface IntroConfig {
+    title: string;
+    body: ReactNode;
+    /**
+     * Where to surface the "show again" affordance after dismissal.
+     * Defaults to `'header'` (auto-falls back to `'footer'` when no header
+     * card is rendered).
+     */
+    reopenAffordance?: 'header' | 'footer' | 'inline' | 'hidden';
+    /** Override the default "How it works" label / tooltip. */
+    reopenLabel?: string;
+}
+interface RailConfig<TData = unknown> {
+    /** Which layouts the rail offers. Default `['list']`. */
+    presentations?: RecordPresentation[];
+    /** Initial presentation when nothing is persisted. */
+    defaultPresentation?: RecordPresentation;
+    /** Custom row renderer for `list` / `compact` densities. */
+    renderListRow?: (record: RecordSummary<TData>, ctx: RecordSlotContext) => ReactNode;
+    /**
+     * Custom empty-state renderer for the records rail. Receives the active
+     * scope (kind only). Falls back to the styled built-in empty state.
+     */
+    renderEmpty?: (ctx: {
+        scope: ScopeKind;
+    }) => ReactNode;
+    /** Group rail records into accordion-style buckets. Return `null` to put
+     *  a record in the default "Other" bucket. */
     groupBy?: (record: RecordSummary) => {
         key: string;
         label: string;
         icon?: ReactNode;
     } | null;
-    /** Custom empty-state renderer for the records rail. Falls back to the styled
-     *  built-in empty state (icon + title + body + optional CTAs). */
-    renderEmptyState?: (ctx: {
-        scope: ScopeKind;
-    }) => ReactNode;
     /** Visual density. Default `comfortable`. */
     density?: 'comfortable' | 'compact';
-    i18n?: Partial<RecordsAdminI18n>;
-    onTelemetry?: (event: TelemetryEvent) => void;
-    className?: string;
+}
+interface EditorPreviewConfig<TData = unknown> {
     /**
-     * Override the resting label for footer / banner actions. When a key is
-     * omitted the shell falls back to the i18n default ("Save", "Discard",
-     * "Delete"). Loading / disabled states (e.g. "Saving…") remain owned by
-     * the shell — only the resting label is customisable here.
-     *
-     * Hosts that need translated labels should pass already-translated
-     * strings; the shell stays locale-agnostic.
+     * Render the preview surface. Receives the editor's current value so the
+     * preview tracks unsaved edits, plus the chosen `previewScope` (which can
+     * differ from the editing scope when `<PreviewScopePicker>` is used).
      */
-    actionLabels?: Partial<Record<RecordsAdminActionKey, string>>;
+    render?: (ctx: {
+        resolved: TData | null;
+        previewScope: ParsedRef;
+    }) => ReactNode;
     /**
-     * Optional icon component rendered before each action label (sized
-     * `h-4 w-4`). Omit a key to preserve current look — the editor footer
-     * renders Save/Discard without icons by default. Delete retains its
-     * built-in `Trash2` unless overridden here.
+     * How the preview surface attaches to the editor pane.
+     * - `inline` (default): rendered below the form.
+     * - `side`:   resizable right pane next to the editor.
+     * - `tab`:    Editor / Preview siblings inside the right pane.
+     * - `drawer`: slide-out from the right, toggled by a button.
      */
-    actionIcons?: Partial<Record<RecordsAdminActionKey, RecordsAdminActionIcon>>;
+    mode?: 'inline' | 'side' | 'tab' | 'drawer';
+    /** Render a `<PreviewScopePicker>` so admins can preview as a different
+     *  product/variant/batch than they're editing. Default false. */
+    scopePicker?: boolean;
+}
+interface EditorConfig<TData = unknown> {
+    /** Editor tab strip behaviour. See {@link RecordsAdminEditorTabsMode}. */
+    tabs?: RecordsAdminEditorTabsMode;
+    /** Preview pane configuration. */
+    preview?: EditorPreviewConfig<TData>;
+}
+interface ItemsConfig<TData = unknown> {
     /**
-     * Enable in-shell Copy / Paste between scopes for the current `recordType`.
-     * Default `true`. The clipboard is scoped per `(appId, recordType)` and
-     * persists in `sessionStorage` so it survives host route changes.
+     * Whether each scope holds at most one record (`singleton`, default) or
+     * many (`collection`).
      */
-    enableClipboard?: boolean;
+    cardinality?: RecordCardinality;
+    /** Display name for an item in collection mode. Default `'item'`. */
+    noun?: string;
+    /** Generate a host-local handle for a brand-new draft. */
+    generateId?: () => string;
+    /** Which built-in item views the right pane offers. Default `['table']`. */
+    views?: ItemView[];
+    /** Initial item view when nothing is persisted. */
+    defaultView?: ItemView;
+    /** Declarative columns for the built-in `table` view. */
+    columns?: ItemColumn<TData>[];
+    /** Card renderer for `cards` / `gallery` views. */
+    renderCard?: (record: RecordSummary<TData>, ctx: ItemSlotContext) => ReactNode;
+    /** Full custom item-view renderer. Replaces built-in views entirely. */
+    renderList?: (items: RecordSummary<TData>[], ctx: ItemViewContext) => ReactNode;
+    /** Custom empty-state when a scope has no items yet. */
+    renderEmpty?: (ctx: ItemViewContext) => ReactNode;
+    /** Visual density of `cards` / `gallery` views. Default `'md'`. */
+    cardSize?: 'sm' | 'md' | 'lg';
+    /** What the rail shows once an item is open. Default `'siblings'`. */
+    railMode?: CollectionRailMode;
+}
+interface UnsavedConfig<TData = unknown> {
     /**
-     * Optional transform on Copy. Receives the resolved value at the source
-     * scope and returns what should be stored in the clipboard. Use this to
-     * strip per-scope-only fields (e.g. country of origin) that shouldn't
-     * propagate. Defaults to a deep clone of the resolved value.
+     * How to handle unsaved edits when navigating away.
+     * - `keep` (default): hold edits per editor mount; surface via the
+     *   inline UnsavedBanner.
+     * - `prompt`: show a confirm dialog on navigation.
+     * - `autosave`: silently save before navigating.
      */
+    strategy?: 'prompt' | 'autosave' | 'keep';
+    /** Disable the browser-level `beforeunload` prompt. Default false. */
+    disableBeforeUnload?: boolean;
+    /** Pre-delete hook. Return `false` to abort. */
+    onBeforeDelete?: (scope: ParsedRef) => boolean | Promise<boolean>;
+    /** Derive a label for an in-flight draft in the unsaved-changes tray. */
+    deriveDraftLabel?: (value: TData, scope: ParsedRef) => string | undefined;
+}
+interface ClipboardConfig<TData = unknown> {
+    /** Enable in-shell Copy / Paste. Default `true`. */
+    enabled?: boolean;
+    /** Optional transform on Copy. Defaults to a deep clone. */
     onCopy?: (source: {
         value: TData;
         scope: ParsedRef;
     }) => TData;
-    /**
-     * Optional transform on Paste. Receives the clipboard payload and the
-     * destination scope/current value. Return the value to apply, or `null`
-     * to abort the paste. Defaults to replacing the destination's value with
-     * the clipboard's.
-     */
+    /** Optional transform on Paste. Return `null` to abort. */
     onPaste?: (clipboard: {
         value: TData;
         sourceScope: ParsedRef;
@@ -945,21 +870,12 @@ 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;
+}
+interface ActionsConfig {
+    /** Override resting labels for `save` / `discard` / `delete` (etc.). */
+    labels?: Partial<Record<RecordsAdminActionKey, string>>;
+    /** Optional icon component rendered before each action label. */
+    icons?: Partial<Record<RecordsAdminActionKey, RecordsAdminActionIcon>>;
 }
 /**
  * Controls the small tab strip that appears above the editor body inside the
@@ -1651,6 +1567,16 @@ interface UseCollectionItemsArgs {
      * the query disabled.
      */
     scope: ParsedRef | null;
+    /**
+     * When the scope is a rule (kind === 'rule'), pass the rule's `facetRule`
+     * here. Items belonging to a rule are records that carry the *same*
+     * facetRule — they share anchors only by coincidence (typically empty),
+     * so anchor equality alone isn't enough to identify them. When this is
+     * provided we match rule records by facetRule equality and ignore
+     * anchors. When absent, anchor-based matching applies (and rule records
+     * are skipped, since they belong on the Rules tab).
+     */
+    facetRule?: FacetRule | null;
     /** Per-page size requested from the SDK (default 100). */
     pageSize?: number;
     /**