@proveanything/smartlinks-utils-ui 0.9.0 → 0.9.2

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,24 @@ 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;
+    /**
+     * Lifecycle-hook failure toasts. `{message}` is replaced with the
+     * thrown error's message (or a generic fallback when none is provided).
+     */
+    hookBeforeSaveFailed: string;
+    hookAfterSaveFailed: string;
+    hookBeforeDeleteFailed: string;
+    hookAfterDeleteFailed: string;
 }
 declare const DEFAULT_I18N: RecordsAdminI18n;
 
@@ -538,6 +563,54 @@ declare function mergeIcons(override?: Partial<RecordsAdminIcons>): RecordsAdmin
  *  explicit `headerIcon` > `icons.header.byRecordType[type]` > `icons.header.default`. */
 declare function pickHeaderIcon(icons: RecordsAdminIcons, recordType?: string): LucideIcon;
 
+/** Common context fields passed to every lifecycle hook. */
+interface RecordHookCtx {
+    collectionId: string;
+    appId: string;
+    recordType?: string;
+    /** Editing scope kind (`'global' | 'rule' | 'product' | …`). */
+    scope: ScopeKind;
+    /** Resolved scope ref string when available (e.g. `product:abc`). Most
+     *  hosts ignore this; provided for parity with non-shell callers. */
+    targetRef?: string;
+    /** Always `true` from inside the shell; included for symmetry with
+     *  future non-shell callers. */
+    admin: true;
+}
+interface SaveHookCtx<T = unknown> extends RecordHookCtx {
+    isCreate: boolean;
+    /** Record as it WILL be (in `beforeSave`) or HAS been (in `afterSave`)
+     *  written. `id` is the resolved UUID when known, otherwise undefined. */
+    record: RecordSummary<T>;
+    /** Snapshot of the record's previous server state. Undefined on create. */
+    before?: RecordSummary<T>;
+}
+interface DeleteHookCtx<T = unknown> extends RecordHookCtx {
+    /** Snapshot of the record taken immediately before deletion. */
+    record: RecordSummary<T>;
+}
+/**
+ * Opt-in lifecycle hooks for `RecordsAdminShell`. All four are awaited.
+ *
+ * - `beforeSave` — return `false` (or throw) to cancel the write. Return
+ *   a `Partial<T>` to merge into the record's `data` payload before it
+ *   hits the server (e.g. inject computed `status`, normalised dates).
+ * - `afterSave` — runs after a successful write. Throwing surfaces a
+ *   toast but does NOT roll back the server state.
+ * - `beforeDelete` — return `false` (or throw) to cancel the delete.
+ * - `afterDelete` — runs after a successful delete. Throwing surfaces a
+ *   toast; the record is already gone.
+ *
+ * `data` is the only host-shaped portion of the payload — anchors and
+ * `facetRule` are owned by the shell, so `beforeSave` returns a partial
+ * of the typed `data` shape, not of the full SDK record input.
+ */
+interface RecordsAdminShellHooks<T = unknown> {
+    beforeSave?: (ctx: SaveHookCtx<T>) => Promise<Partial<T> | false | void> | Partial<T> | false | void;
+    afterSave?: (ctx: SaveHookCtx<T>) => Promise<void> | void;
+    beforeDelete?: (ctx: DeleteHookCtx<T>) => Promise<false | void> | false | void;
+    afterDelete?: (ctx: DeleteHookCtx<T>) => Promise<void> | void;
+}
 /**
  * Footer / banner action keys whose label and icon can be customised by
  * the host. `save`, `discard`, `delete` are wired today. `saveAll` /
@@ -697,6 +770,15 @@ interface RecordsAdminShellProps<TData = unknown> {
     unsaved?: UnsavedConfig<TData>;
     clipboard?: ClipboardConfig<TData>;
     actions?: ActionsConfig;
+    /**
+     * Opt-in awaited callbacks fired around record save/delete. See
+     * {@link RecordsAdminShellHooks} for the contract.
+     *
+     * Today these fire on the single-record paths (editor footer Save/Delete
+     * and the right-pane item-list trash). Bulk paths (CSV import, paste,
+     * Save-all) do NOT fire hooks yet — tracked as a follow-up.
+     */
+    hooks?: RecordsAdminShellHooks<TData>;
     /**
      * Mirror the shell's runtime state into URL params. Off by default. The
      * shell only owns `item`, `scope`, `view` — host platform params are
@@ -931,10 +1013,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;
@@ -988,6 +1077,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;
@@ -1014,6 +1105,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`
@@ -1029,11 +1132,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;
@@ -1097,6 +1200,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;
@@ -1135,7 +1245,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;
@@ -1577,6 +1687,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;
     /**
@@ -1734,6 +1852,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>;
@@ -2055,6 +2199,12 @@ interface Props$5<T> {
     error: Error | null;
     ctx: ItemViewContext;
     itemNoun: string;
+    /**
+     * Optional one-line rule summary shown beneath the toolbar — used in
+     * collection-mode when an item list is scoped to a specific rule, so the
+     * admin sees which rule's items they're viewing without leaving the pane.
+     */
+    ruleSummary?: string | null;
     view: ItemView;
     views: ItemView[];
     onViewChange: (view: ItemView) => void;
@@ -2066,7 +2216,7 @@ interface Props$5<T> {
     cardSize?: 'sm' | 'md' | 'lg';
     i18n: RecordsAdminI18n;
 }
-declare function ItemListView<T>({ items, isLoading, error, ctx, itemNoun, view, views, onViewChange, renderItemList, renderItemCard, renderItemEmpty, itemColumns, cardSize, i18n, }: Props$5<T>): react_jsx_runtime.JSX.Element;
+declare function ItemListView<T>({ items, isLoading, error, ctx, itemNoun, ruleSummary, view, views, onViewChange, renderItemList, renderItemCard, renderItemEmpty, itemColumns, cardSize, i18n, }: Props$5<T>): react_jsx_runtime.JSX.Element;
 
 interface Props$4 {
     options: ItemView[];
@@ -2234,6 +2384,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;
@@ -2249,4 +2424,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 };