@proveanything/smartlinks-utils-ui 0.9.1 → 0.9.2

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;
 
@@ -555,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` /
@@ -714,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
@@ -2134,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;
@@ -2145,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[];

package/dist/components/RecordsAdmin/index.js

@@ -146,7 +146,11 @@ var DEFAULT_I18N = {
   subtitleConfigured: "Configured",
   subtitleInherited: "Inherited",
   rulesTabTooltip: "Use rules to scope records to a targeted audience or a subset of products.",
-  rulesEmptyBody: "Create a rule to target a subset of products or a specific audience \u2014 for example, \u201Conly premium tier customers in Germany\u201D."
+  rulesEmptyBody: "Create a rule to target a subset of products or a specific audience \u2014 for example, \u201Conly premium tier customers in Germany\u201D.",
+  hookBeforeSaveFailed: "Couldn't save: {message}",
+  hookAfterSaveFailed: "Saved, but a follow-up step failed: {message}",
+  hookBeforeDeleteFailed: "Couldn't delete: {message}",
+  hookAfterDeleteFailed: "Deleted, but a follow-up step failed: {message}"
 };
 
 // src/components/RecordsAdmin/types/presentation.ts
@@ -1819,7 +1823,8 @@ function useShellNavigation(args) {
     deepLinkState,
     onTelemetry,
     onBeforeDelete,
-    generateItemId
+    generateItemId,
+    hooks
   } = args;
   const buildItemUrlValue = useCallback((id) => {
     if (!baseScopeRef && id.startsWith("item:")) return id;
@@ -1904,6 +1909,34 @@ function useShellNavigation(args) {
       const ok = await onBeforeDelete(editingScope ?? parseRef(""));
       if (!ok) return;
     }
+    const row = collectionItems.items.find(
+      (it) => it.itemId === itemId || it.id === itemId
+    );
+    const hookCtxBase = {
+      collectionId: ctx.collectionId,
+      appId: ctx.appId,
+      recordType: ctx.recordType,
+      scope: editingScope?.kind ?? "collection",
+      targetRef: editingScope?.raw || void 0,
+      admin: true
+    };
+    const recordSummary = row ?? {
+      id: itemId,
+      ref: editingScope?.raw ?? "",
+      scope: editingScope ?? parseRef(""),
+      data: null,
+      status: "configured",
+      label: itemId
+    };
+    if (hooks?.beforeDelete) {
+      try {
+        const result = await hooks.beforeDelete({ ...hookCtxBase, record: recordSummary });
+        if (result === false) return;
+      } catch (err) {
+        console.warn("[RecordsAdmin] item beforeDelete hook cancelled delete", err);
+        return;
+      }
+    }
     try {
       const { removeRecord: removeRecord2 } = await import('../../records-AYYQSP7E.js');
       await removeRecord2(ctx, itemId);
@@ -1911,6 +1944,13 @@ function useShellNavigation(args) {
       if (selectedItemId === itemId) setSelectedItemId(null);
       if (selectedItemId === itemId) deepLinkState.emit({ recordId: null }, "record.close");
       collectionItems.refetch();
+      if (hooks?.afterDelete) {
+        try {
+          await hooks.afterDelete({ ...hookCtxBase, record: recordSummary });
+        } catch (err) {
+          console.warn("[RecordsAdmin] item afterDelete hook failed", err);
+        }
+      }
     } catch (err) {
       console.error("[RecordsAdminShell] item delete failed", err);
     }
@@ -1925,7 +1965,8 @@ function useShellNavigation(args) {
     collectionItems,
     deepLinkState,
     editingScope,
-    setSelectedItemId
+    setSelectedItemId,
+    hooks
   ]);
   const itemViewCtx = useMemo(() => ({
     onOpen: onItemOpen,
@@ -2231,6 +2272,25 @@ var createEditorStore = () => {
   const listeners = /* @__PURE__ */ new Set();
   let cachedList = [];
   let nextOrder = 0;
+  let hooksBundle = null;
+  let notifier = null;
+  const buildRecordSummary = (entry, value) => ({
+    id: entry.recordId ?? null,
+    ref: entry.spec.scope.raw,
+    scope: entry.spec.scope,
+    label: entry.label,
+    status: "configured",
+    data: value,
+    facetRule: entry.facetRule
+  });
+  const buildHookCtxBase = (entry) => ({
+    collectionId: entry.saveSpec.ctx.collectionId,
+    appId: entry.saveSpec.ctx.appId,
+    recordType: entry.saveSpec.ctx.recordType,
+    scope: entry.spec.scope.kind,
+    targetRef: entry.spec.scope.raw || void 0,
+    admin: true
+  });
   const recompute = () => {
     cachedList = Array.from(map.values()).sort((a, b) => a.order - b.order);
   };
@@ -2384,10 +2444,35 @@ var createEditorStore = () => {
       const entry = map.get(editorId);
       if (!entry) return;
       if (entry.status !== "dirty" && entry.status !== "error") return;
-      const persistedValue = entry.value;
+      let persistedValue = entry.value;
       const persistedFacetRule = entry.facetRule;
       const { ctx, anchors } = entry.saveSpec;
       const spec = entry.spec;
+      const isCreate = !(entry.recordId && entry.source === "self") || !!spec.createMode;
+      if (hooksBundle?.beforeSave) {
+        try {
+          const hookCtx = {
+            ...buildHookCtxBase(entry),
+            isCreate,
+            record: buildRecordSummary(entry, persistedValue),
+            before: !isCreate ? buildRecordSummary(entry, entry.baseline) : void 0
+          };
+          const result = await hooksBundle.beforeSave(hookCtx);
+          if (result === false) {
+            return;
+          }
+          if (result && typeof result === "object") {
+            persistedValue = persistedValue && typeof persistedValue === "object" ? { ...persistedValue, ...result } : result;
+          }
+        } catch (err) {
+          notifier?.({ kind: "hook-before-save", error: err, recordLabel: entry.label });
+          update(editorId, (e) => {
+            e.status = "error";
+            e.error = err;
+          });
+          return;
+        }
+      }
       update(editorId, (e) => {
         e.status = "saving";
         e.error = void 0;
@@ -2424,6 +2509,9 @@ var createEditorStore = () => {
           nextRecordId = upserted.record?.id ?? nextRecordId;
         }
         update(editorId, (e) => {
+          if (persistedValue !== entry.value) {
+            e.value = cloneDeep(persistedValue);
+          }
           e.baseline = cloneDeep(e.value);
           e.baselineFacetRule = e.facetRule;
           e.recordId = nextRecordId;
@@ -2431,6 +2519,21 @@ var createEditorStore = () => {
           e.status = "saved";
           e.error = void 0;
         });
+        if (hooksBundle?.afterSave) {
+          const refreshed = map.get(editorId);
+          const hookCtx = {
+            ...buildHookCtxBase(refreshed ?? entry),
+            isCreate,
+            record: buildRecordSummary(refreshed ?? entry, persistedValue),
+            before: !isCreate ? buildRecordSummary(entry, entry.baseline) : void 0
+          };
+          try {
+            await hooksBundle.afterSave(hookCtx);
+          } catch (err) {
+            notifier?.({ kind: "hook-after-save", error: err, recordLabel: entry.label });
+            console.warn("[RecordsAdmin] afterSave hook failed", err);
+          }
+        }
       } catch (err) {
         update(editorId, (e) => {
           e.status = "error";
@@ -2452,9 +2555,35 @@ var createEditorStore = () => {
       if (!entry) return;
       if (entry.source !== "self") return;
       if (!entry.recordId) return;
+      if (hooksBundle?.beforeDelete) {
+        try {
+          const hookCtx = {
+            ...buildHookCtxBase(entry),
+            record: buildRecordSummary(entry, entry.value)
+          };
+          const result = await hooksBundle.beforeDelete(hookCtx);
+          if (result === false) return;
+        } catch (err) {
+          notifier?.({ kind: "hook-before-delete", error: err, recordLabel: entry.label });
+          console.warn("[RecordsAdmin] beforeDelete hook cancelled delete", err);
+          return;
+        }
+      }
+      const deletedSnapshot = hooksBundle?.afterDelete ? {
+        ...buildHookCtxBase(entry),
+        record: buildRecordSummary(entry, entry.value)
+      } : null;
       await removeRecord(entry.saveSpec.ctx, entry.recordId);
       map.delete(editorId);
       emit();
+      if (hooksBundle?.afterDelete && deletedSnapshot) {
+        try {
+          await hooksBundle.afterDelete(deletedSnapshot);
+        } catch (err) {
+          notifier?.({ kind: "hook-after-delete", error: err, recordLabel: entry.label });
+          console.warn("[RecordsAdmin] afterDelete hook failed", err);
+        }
+      }
     },
     enforcePoolLimit(max, exceptEditorId) {
       const alive = Array.from(map.values());
@@ -2475,6 +2604,12 @@ var createEditorStore = () => {
       return () => {
         listeners.delete(listener);
       };
+    },
+    setHooks(hooks) {
+      hooksBundle = hooks ?? null;
+    },
+    setNotifier(notify2) {
+      notifier = notify2 ?? null;
     }
   };
 };
@@ -2496,10 +2631,14 @@ var EditorSessionProvider = ({
   ctx,
   children,
   maxOpenEditors = 8,
-  defaultValueFactory
+  defaultValueFactory,
+  hooks,
+  onHookNotice
 }) => {
   const storeRef = useRef(null);
   if (!storeRef.current) storeRef.current = createEditorStore();
+  storeRef.current.setHooks(hooks ?? null);
+  storeRef.current.setNotifier(onHookNotice ?? null);
   const currentRef = useRef(void 0);
   const listenersRef = useRef(/* @__PURE__ */ new Set());
   const subscribeCurrent = useCallback((cb) => {
@@ -4100,8 +4239,15 @@ function RecordEditor({
   const DeleteIcon = actionIcons?.delete;
   const showInherited = ctx.source === "inherited";
   const showEmpty = ctx.source === "empty";
+  const hasBreadcrumb = (() => {
+    const s = ctx.scope;
+    return Boolean(s?.facetId || s?.productId || s?.variantId || s?.batchId);
+  })();
+  const hasLeftContent = Boolean(headerLabel) || hasBreadcrumb;
+  const hasRightContent = showInherited || showEmpty || Boolean(headerMeta) || Boolean(bulkActions) || Boolean(targetingControl);
+  const showHeader = hasLeftContent || hasRightContent;
   return /* @__PURE__ */ jsxs("div", { className: "flex flex-col h-full", children: [
-    /* @__PURE__ */ jsxs(
+    showHeader && /* @__PURE__ */ jsxs(
       "header",
       {
         className: "sticky top-0 z-40 px-5 py-3 border-b flex items-start justify-between gap-3",
@@ -5309,6 +5455,7 @@ function ItemListView({
   error,
   ctx,
   itemNoun,
+  ruleSummary,
   view,
   views,
   onViewChange,
@@ -5406,6 +5553,27 @@ function ItemListView({
   }
   return /* @__PURE__ */ jsxs("div", { className: "ra-item-list", children: [
     toolbar,
+    ruleSummary ? /* @__PURE__ */ jsxs(
+      "div",
+      {
+        className: "ra-item-rule-summary",
+        style: {
+          padding: "6px 12px",
+          fontSize: "11px",
+          color: "hsl(var(--ra-muted-text))",
+          borderBottom: "1px solid hsl(var(--ra-border))",
+          background: "hsl(var(--ra-muted) / 0.4)",
+          display: "flex",
+          alignItems: "center",
+          gap: "6px"
+        },
+        children: [
+          /* @__PURE__ */ jsx("span", { style: { fontWeight: 500, color: "hsl(var(--ra-text))" }, children: "Rule" }),
+          /* @__PURE__ */ jsx("span", { "aria-hidden": "true", children: "\xB7" }),
+          /* @__PURE__ */ jsx("span", { children: ruleSummary })
+        ]
+      }
+    ) : null,
     /* @__PURE__ */ jsx("div", { className: "ra-item-list-body", children: body })
   ] });
 }
@@ -6730,6 +6898,19 @@ function RecordsAdminShell(props) {
     {
       ctx,
       defaultValueFactory: props.defaultData,
+      hooks: props.hooks,
+      onHookNotice: (notice) => {
+        console.warn(`[RecordsAdmin] ${notice.kind} hook failed`, notice.error);
+        try {
+          props.onTelemetry?.({
+            type: "record.hook.error",
+            recordType: props.recordType,
+            kind: notice.kind,
+            message: notice.error instanceof Error ? notice.error.message : String(notice.error)
+          });
+        } catch {
+        }
+      },
       children: /* @__PURE__ */ jsx(RecordsAdminShellInner, { ...props })
     }
   );
@@ -7290,7 +7471,8 @@ function RecordsAdminShellInner(props) {
     deepLinkState,
     onTelemetry,
     onBeforeDelete,
-    generateItemId
+    generateItemId,
+    hooks: props.hooks
   });
   const renderEditorWithPreview = () => {
     if (!editingTargetScope) return null;
@@ -7497,12 +7679,13 @@ function RecordsAdminShellInner(props) {
     if (groupBy) return groupBy;
     if (isAllTab) return void 0;
     if (!isRuleTab) return void 0;
+    if (isCollection) return void 0;
     return (record) => {
       const hash = ruleHash(record.facetRule);
       if (!hash) return null;
       return { key: `rule:${hash}`, label: summariseRule(record.facetRule) };
     };
-  }, [groupBy, isRuleTab, isAllTab]);
+  }, [groupBy, isRuleTab, isAllTab, isCollection]);
   const [bulkRuleEditTarget, setBulkRuleEditTarget] = useState(null);
   const ruleCatalogue = useMemo(() => {
     const buckets = /* @__PURE__ */ new Map();
@@ -7601,6 +7784,32 @@ function RecordsAdminShellInner(props) {
     () => isRuleTab ? applyRuleFilters(recordList.items, ruleFilters) : recordList.items,
     [isRuleTab, recordList.items, ruleFilters]
   );
+  const collectionRuleRailItems = useMemo(() => {
+    if (!isRuleTab || !isCollection) return filteredRuleItems;
+    const buckets = /* @__PURE__ */ new Map();
+    for (const item of filteredRuleItems) {
+      const hash = ruleHash(item.facetRule);
+      if (!hash) continue;
+      const existing = buckets.get(hash);
+      if (existing) {
+        existing.count += 1;
+      } else {
+        buckets.set(hash, { rep: item, count: 1 });
+      }
+    }
+    return Array.from(buckets.values()).map(({ rep, count }) => ({
+      ...rep,
+      label: summariseRule(rep.facetRule),
+      subtitle: `${count} ${itemNoun}${count === 1 ? "" : "s"}`
+    }));
+  }, [isRuleTab, isCollection, filteredRuleItems, itemNoun]);
+  const activeRuleSummary = useMemo(() => {
+    if (!isRuleTab || !isCollection) return null;
+    if (!selectedRecordId || isDraftId3(selectedRecordId)) return null;
+    const hit = recordList.items.find((it) => it.id === selectedRecordId);
+    if (!hit?.facetRule) return null;
+    return summariseRule(hit.facetRule);
+  }, [isRuleTab, isCollection, selectedRecordId, recordList.items]);
   const applyFacetBrowseFilter = useCallback(
     (items2) => {
       if (!facetBrowseFilter) return items2;
@@ -7648,7 +7857,9 @@ function RecordsAdminShellInner(props) {
     }),
     [i18n.itemsAllLabel, collectionItems.items.length, itemNoun]
   );
-  const leftItems = isProductTab ? productListItems : isRuleTab ? applyFacetBrowseFilter(filteredRuleItems) : (isGlobalTab || isAllTab) && isCollection ? [collectionGlobalAllRow] : isRecordsTab ? applyFacetBrowseFilter(recordList.items) : [];
+  const leftItems = isProductTab ? productListItems : isRuleTab ? applyFacetBrowseFilter(
+    isCollection ? collectionRuleRailItems : filteredRuleItems
+  ) : (isGlobalTab || isAllTab) && isCollection ? [collectionGlobalAllRow] : isRecordsTab ? applyFacetBrowseFilter(recordList.items) : [];
   const leftLoading = isProductTab ? !productPinned && productBrowse.isLoading : isRecordsTab ? recordList.isLoading || probe.isLoading : false;
   const leftError = isProductTab ? productBrowse.error : isRecordsTab ? recordList.error : null;
   const leftSelectedId = isProductTab ? void 0 : selectedRecordId && selectedRecordId !== DRAFT_ID3 ? selectedRecordId : void 0;
@@ -8089,6 +8300,7 @@ function RecordsAdminShellInner(props) {
                     renderItemEmpty,
                     itemColumns,
                     cardSize: itemCardSize,
+                    ruleSummary: activeRuleSummary,
                     i18n
                   }
                 ),