@proveanything/smartlinks-utils-ui 0.8.3 → 0.9.1

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

@@ -19,8 +19,15 @@ import { InfiniteData } from '@tanstack/react-query';
  * - `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:`.
+ * - `all`        — synthetic UI scope: opt-in flat-list view of every record
+ *                  in the collection (global + ruled + pinned). Skips the
+ *                  framework's scope-as-axis grouping entirely so hosts can
+ *                  drive the rail with their own `rail.groupBy` (e.g.
+ *                  open / upcoming / closed for time-bound records like
+ *                  votes or competitions). Off by default — add `'all'` to
+ *                  the host's `scopes` array to enable.
  */
-type ScopeKind = 'collection' | 'product' | 'facet' | 'variant' | 'batch' | 'rule';
+type ScopeKind = 'collection' | 'product' | 'facet' | 'variant' | 'batch' | 'rule' | 'all';
 /** Parsed `ref` string — see `data/refs.ts`. Format: `kind:id` or chain. */
 interface ParsedRef {
     /** Most-specific scope this ref points at. */
@@ -407,6 +414,16 @@ interface RecordsAdminI18n {
     subtitleEmpty: string;
     subtitleConfigured: string;
     subtitleInherited: string;
+    /**
+     * Hover tooltip on the "Rules" scope tab. The label itself stays short
+     * for navigation density; this longer string surfaces the audience /
+     * targeting vocabulary that explains the feature without needing docs.
+     * Apps can override per-domain (e.g. "Show this FAQ to a targeted
+     * audience").
+     */
+    rulesTabTooltip: string;
+    /** Empty-state body shown inside the Rules tab when no rules exist yet. */
+    rulesEmptyBody: string;
 }
 declare const DEFAULT_I18N: RecordsAdminI18n;
 
@@ -675,285 +692,194 @@ interface RecordsAdminShellProps<TData = unknown> {
      */
     contextScopeMode?: 'strict' | 'expand';
     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.
-     */
-    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;
-    };
     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.
-     */
-    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`).
+     * Header card configuration. The card is off by default; set `show: true`
+     * (or pass any of `title` / `subtitle` / `icon` / `actions` / `stats`) to
+     * opt in.
      */
-    renderListRow?: (record: RecordSummary<TData>, ctx: RecordSlotContext) => ReactNode;
+    header?: HeaderConfig;
     /**
-     * Optional custom empty-state renderer for the rail. If omitted the shell
-     * uses the default `<EmptyState>` with `i18n.emptyTitle` / `i18n.emptyBody`.
+     * 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).
      */
-    renderEmpty?: (ctx: {
-        scope: ParsedRef | null;
-    }) => ReactNode;
+    intro?: IntroConfig;
+    rail?: RailConfig<TData>;
+    editor?: EditorConfig<TData>;
+    items?: ItemsConfig<TData>;
+    unsaved?: UnsavedConfig<TData>;
+    clipboard?: ClipboardConfig<TData>;
+    actions?: ActionsConfig;
     /**
-     * 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`).
+     * Mirror the shell's runtime state into URL params. Off by default. The
+     * shell only owns `item`, `scope`, `view` — host platform params are
+     * untouched.
      */
-    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;
-    /**
-     * 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.
-     */
-    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. */
-    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;
@@ -961,21 +887,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
@@ -1031,10 +948,17 @@ interface Props$g {
     loading?: boolean;
     /** Optional per-scope counts displayed as tiny badges. */
     counts?: Partial<Record<ScopeKind, number>>;
+    /**
+     * Optional per-scope hover tooltip (rendered as native `title`). Used by
+     * the shell to surface marketing-friendly explanations on tabs whose
+     * one-word label benefits from a longer gloss — primarily "Rules"
+     * ("Use rules to scope records to a targeted audience…").
+     */
+    tooltips?: Partial<Record<ScopeKind, string>>;
     /** Override icons used per scope. Falls back to DEFAULT_ICONS.scope. */
     icons?: RecordsAdminIcons['scope'];
 }
-declare const ScopeTabs: ({ scopes, active, onChange, loading, counts, icons, }: Props$g) => react_jsx_runtime.JSX.Element;
+declare const ScopeTabs: ({ scopes, active, onChange, loading, counts, tooltips, icons, }: Props$g) => react_jsx_runtime.JSX.Element;
 
 interface Props$f {
     source?: RecordSource;
@@ -1088,6 +1012,8 @@ interface Props$c {
      * Anchor-based highlight fallback for tabs whose rail rows are not backed
      * by AppRecords (Products, Facets). Compared against `RecordSummary.ref`
      * which for those tabs is a synthesised display-only anchor string.
+     * NOTE: framework-owned. Built via `anchorKey(scope)` — does NOT come from
+     * the host's `record.ref` field (which the framework deliberately ignores).
      */
     selectedAnchorKey?: string;
     onSelect: (item: RecordSummary) => void;
@@ -1114,6 +1040,18 @@ interface Props$c {
         label: string;
         icon?: ReactNode;
     } | null;
+    /**
+     * Optional per-group action slot rendered to the right of the group
+     * header label/count. Used by the shell to surface a "Edit rule for all"
+     * affordance on Rules-tab groups (each group is one shared rule). The
+     * callback receives the group's key + the records in that group so the
+     * caller can target them. Returning `null` hides the slot.
+     */
+    renderGroupActions?: (group: {
+        key: string;
+        label: string;
+        items: RecordSummary[];
+    }) => ReactNode;
     /**
      * Optional clipboard wiring per row. When provided the shell's Copy /
      * Paste affordance appears in each row's context menu. Returning `null`
@@ -1129,11 +1067,11 @@ interface Props$c {
     /** Resolved i18n strings — used by default row/card renderers. */
     i18n?: RecordsAdminI18n;
 }
-declare const RecordList: ({ items, selectedId, selectedAnchorKey, onSelect, dirtyId, dirtyAnchorKey, dirtyKeys, errorKeys, presentation, renderListRow, groupBy, rowClipboard, i18n, }: Props$c) => react_jsx_runtime.JSX.Element;
-declare const ProductList: ({ items, selectedId, selectedAnchorKey, onSelect, dirtyId, dirtyAnchorKey, dirtyKeys, errorKeys, presentation, renderListRow, groupBy, rowClipboard, i18n, }: Props$c) => react_jsx_runtime.JSX.Element;
-declare const FacetList: ({ items, selectedId, selectedAnchorKey, onSelect, dirtyId, dirtyAnchorKey, dirtyKeys, errorKeys, presentation, renderListRow, groupBy, rowClipboard, i18n, }: Props$c) => react_jsx_runtime.JSX.Element;
-declare const VariantList: ({ items, selectedId, selectedAnchorKey, onSelect, dirtyId, dirtyAnchorKey, dirtyKeys, errorKeys, presentation, renderListRow, groupBy, rowClipboard, i18n, }: Props$c) => react_jsx_runtime.JSX.Element;
-declare const BatchList: ({ items, selectedId, selectedAnchorKey, onSelect, dirtyId, dirtyAnchorKey, dirtyKeys, errorKeys, presentation, renderListRow, groupBy, rowClipboard, i18n, }: Props$c) => react_jsx_runtime.JSX.Element;
+declare const RecordList: ({ items, selectedId, selectedAnchorKey, onSelect, dirtyId, dirtyAnchorKey, dirtyKeys, errorKeys, presentation, renderListRow, groupBy, renderGroupActions, rowClipboard, i18n, }: Props$c) => react_jsx_runtime.JSX.Element;
+declare const ProductList: ({ items, selectedId, selectedAnchorKey, onSelect, dirtyId, dirtyAnchorKey, dirtyKeys, errorKeys, presentation, renderListRow, groupBy, renderGroupActions, rowClipboard, i18n, }: Props$c) => react_jsx_runtime.JSX.Element;
+declare const FacetList: ({ items, selectedId, selectedAnchorKey, onSelect, dirtyId, dirtyAnchorKey, dirtyKeys, errorKeys, presentation, renderListRow, groupBy, renderGroupActions, rowClipboard, i18n, }: Props$c) => react_jsx_runtime.JSX.Element;
+declare const VariantList: ({ items, selectedId, selectedAnchorKey, onSelect, dirtyId, dirtyAnchorKey, dirtyKeys, errorKeys, presentation, renderListRow, groupBy, renderGroupActions, rowClipboard, i18n, }: Props$c) => react_jsx_runtime.JSX.Element;
+declare const BatchList: ({ items, selectedId, selectedAnchorKey, onSelect, dirtyId, dirtyAnchorKey, dirtyKeys, errorKeys, presentation, renderListRow, groupBy, renderGroupActions, rowClipboard, i18n, }: Props$c) => react_jsx_runtime.JSX.Element;
 
 interface DefaultRecordRowProps {
     record: RecordSummary;
@@ -1197,6 +1135,13 @@ interface Props$a<T> {
      * leave it `undefined` and nothing renders.
      */
     targeting?: ReactNode;
+    /**
+     * Optional small control rendered in the header's right cluster (next to
+     * the bulk-actions menu). Used for the per-record `TargetingPopover` so
+     * admins can flip between Global / a preset rule / a custom rule from
+     * the editor header without scrolling to the Targeting section.
+     */
+    targetingControl?: ReactNode;
     bulkActions?: React.ComponentProps<typeof BulkActionsMenu>;
     /** Extra slot rendered in the footer between the danger actions and Save. */
     footerExtra?: ReactNode;
@@ -1235,7 +1180,7 @@ interface Props$a<T> {
     /** Host-provided icons rendered before save / discard / delete labels. */
     actionIcons?: Partial<Record<RecordsAdminActionKey, RecordsAdminActionIcon>>;
 }
-declare function RecordEditor<T>({ ctx, i18n, children, preview, targeting, bulkActions, footerExtra, onBeforeDelete, headerLabel, headerSubtitle, headerMeta, clipboard, actionLabels, actionIcons, }: Props$a<T>): react_jsx_runtime.JSX.Element;
+declare function RecordEditor<T>({ ctx, i18n, children, preview, targeting, targetingControl, bulkActions, footerExtra, onBeforeDelete, headerLabel, headerSubtitle, headerMeta, clipboard, actionLabels, actionIcons, }: Props$a<T>): react_jsx_runtime.JSX.Element;
 
 interface InheritanceCtx {
     parentValue?: Record<string, unknown> | null;
@@ -1677,6 +1622,14 @@ interface UseCollectionItemsArgs {
      * are skipped, since they belong on the Rules tab).
      */
     facetRule?: FacetRule | null;
+    /**
+     * When true, return every item-cardinality record across the whole
+     * collection — anchor-pinned, ruled, and global. Used by the 'all' top-
+     * level scope which intentionally bypasses scope-as-axis grouping so
+     * hosts can drive the rail with their own `groupBy` (e.g. lifecycle).
+     * `scope` and `facetRule` are ignored when this is set.
+     */
+    includeAll?: boolean;
     /** Per-page size requested from the SDK (default 100). */
     pageSize?: number;
     /**
@@ -1834,6 +1787,32 @@ declare const useScopeProbe: ({ SL, collectionId, admin, enabled }: UseScopeProb
     error: Error | null;
 };
 
+interface UseScopeCountsArgs {
+    ctx: RecordsCtx;
+    /** Disable the query (e.g. before SL/collection is ready). */
+    enabled?: boolean;
+    /**
+     * Hard cap on records scanned for counts. Above this we return a
+     * lower-bound count and set `truncated: true`. Default 500.
+     */
+    maxRecords?: number;
+    /** Page size used for the underlying SDK list calls. Default 100. */
+    pageSize?: number;
+}
+interface ScopeCounts extends Partial<Record<ScopeKind, number>> {
+}
+interface UseScopeCountsResult {
+    counts: ScopeCounts;
+    total: number;
+    isLoading: boolean;
+    error: Error | null;
+    /** True when we hit `maxRecords` and stopped paginating. */
+    truncated: boolean;
+}
+declare const useScopeCounts: (args: UseScopeCountsArgs) => UseScopeCountsResult;
+/** React Query key factory for cache invalidation from save/delete sites. */
+declare const scopeCountsQueryKey: (collectionId: string, appId: string, recordType?: string) => (string | null)[];
+
 declare const useIntroDismissed: (SL: SmartLinksSDK, collectionId: string, appId: string, recordType?: string) => {
     dismissed: boolean;
     dismiss: () => Promise<void>;
@@ -2334,6 +2313,31 @@ interface ResolveArgs {
 }
 declare const resolveRecord: <T>(args: ResolveArgs) => Promise<ResolvedRecord<T>>;
 
+interface NormalisedRule {
+    all: Array<{
+        facetKey: string;
+        anyOf: string[];
+    }>;
+}
+/**
+ * Canonicalise a FacetRule so semantically identical rules produce identical
+ * strings. Returns `null` for empty/missing rules so callers can distinguish
+ * "no rule" from "the rule that matches everything".
+ */
+declare const normaliseRule: (rule: FacetRule | null | undefined) => NormalisedRule | null;
+/**
+ * Stable content-addressed hash of a FacetRule. `null`/empty rules return
+ * `null` so the caller can route them to a separate "no rule" bucket.
+ */
+declare const ruleHash: (rule: FacetRule | null | undefined) => string | null;
+/**
+ * Human-readable single-line summary of a rule, used for group headers.
+ * Compact ("country=DE,FR · tier=premium") so it fits a rail-width header.
+ */
+declare const summariseRule: (rule: FacetRule | null | undefined) => string;
+/** Comparator: are two rules semantically identical? */
+declare const rulesEqual: (a: FacetRule | null | undefined, b: FacetRule | null | undefined) => boolean;
+
 interface ImportReport {
     total: number;
     saved: number;
@@ -2349,4 +2353,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_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 DirtyDraft, DirtyDraftProvider, type DirtyDraftStatus, type DirtyDraftStore, 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, buildDraftKey, buildRef, bulkDelete, bulkUpsert, checkPasteCompatibility, cloneValue, createDefaultDeepLinkAdapter, createPostMessageDeepLinkAdapter, createRecord, downloadBlob, exportCsv, getRecordById, importCsv, isInSmartLinksIframe, listRecords, matchRecords, mergeIcons, parseRef, parsedRefToScope, parsedRefToTarget, pickHeaderIcon, removeRecord, resolutionChain, resolveRecord, restoreRecord, scopesEqual, statusToneLabel, upsertRecord, useCollectedRecords, useCollectionItems, useDeepLinkState, useDirtyDraft, useDirtyDraftActions, useDirtyDraftStore, useDirtyDrafts, useDirtyNavigation, useFacetBrowse, useIntroDismissed, useItemViewPref, 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 DirtyDraft, DirtyDraftProvider, type DirtyDraftStatus, type DirtyDraftStore, 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 NormalisedRule, 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 ScopeCounts, 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, type UseScopeCountsArgs, type UseScopeCountsResult, UtilityRow, VariantList, buildDraftKey, buildRef, bulkDelete, bulkUpsert, checkPasteCompatibility, cloneValue, createDefaultDeepLinkAdapter, createPostMessageDeepLinkAdapter, createRecord, downloadBlob, exportCsv, getRecordById, importCsv, isInSmartLinksIframe, listRecords, matchRecords, mergeIcons, normaliseRule, parseRef, parsedRefToScope, parsedRefToTarget, pickHeaderIcon, removeRecord, resolutionChain, resolveRecord, restoreRecord, ruleHash, rulesEqual, scopeCountsQueryKey, scopesEqual, statusToneLabel, summariseRule, upsertRecord, useCollectedRecords, useCollectionItems, useDeepLinkState, useDirtyDraft, useDirtyDraftActions, useDirtyDraftStore, useDirtyDrafts, useDirtyNavigation, useFacetBrowse, useIntroDismissed, useItemViewPref, useMergedRecord, usePresentationPref, useProductBrowse, useProductChildren, useRecordClipboard, useRecordEditor, useRecordList, useResolveAllRecords, useResolvedRecord, useRulePreview, useScopeCounts, useScopeProbe, useUnsavedGuard };