@proveanything/smartlinks-utils-ui 0.9.1 → 0.9.3

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

@@ -424,6 +424,14 @@ interface RecordsAdminI18n {
     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;
 
@@ -485,7 +493,17 @@ interface DeepLinkAdapter {
     subscribe(listener: () => void): () => void;
 }
 interface DeepLinkOptions {
-    /** Master switch — default `false` (opt in per app). */
+    /**
+     * Master switch. **Default `true` as of v0.10.** Most hosts want URL
+     * round-tripping (refresh / share-link restores the open record), so the
+     * shell installs a default adapter automatically — `window.location` +
+     * `window.history` for standalone hosts, or a postMessage relay when
+     * mounted inside a SmartLinks iframe.
+     *
+     * Set to `false` to run an isolated shell whose state never touches the
+     * URL. Useful for embedded previews, modal pickers, or hosts that own
+     * a more opinionated URL scheme they don't want the shell to touch.
+     */
     enabled?: boolean;
     /** Push/replace strategy. Default `'smart'`. */
     history?: DeepLinkHistoryMode;
@@ -555,6 +573,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` /
@@ -714,6 +780,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
@@ -1311,13 +1386,19 @@ interface PreviewScopePickerProps {
     /** Are variants/batches available for drill-down. */
     showVariants: boolean;
     showBatches: boolean;
+    /** Active rail tab. The picker hides itself on product/variant/batch
+     *  tabs because the editing scope already pins a product there. */
+    activeScope?: ScopeKind;
     /** i18n strings (uses defaults if omitted). */
     i18n?: {
         previewAs?: string;
         previewAsDefault?: string;
+        change?: string;
+        searchProducts?: string;
+        close?: string;
     };
 }
-declare const PreviewScopePicker: ({ SL, collectionId, editingScope, value, onChange, showVariants, showBatches, i18n, }: PreviewScopePickerProps) => react_jsx_runtime.JSX.Element | null;
+declare const PreviewScopePicker: ({ SL, collectionId, editingScope, value, onChange, showVariants, showBatches, activeScope, i18n, }: PreviewScopePickerProps) => react_jsx_runtime.JSX.Element | null;
 
 declare const ScopeBreadcrumb: ({ scope }: {
     scope: ParsedRef;
@@ -2134,6 +2215,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;
@@ -2145,7 +2232,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[];