@proveanything/smartlinks-utils-ui 0.10.7 → 0.10.9

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

@@ -1,6 +1,6 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { ComponentType, ReactNode } from 'react';
-import { FacetRule, MatchedAt, RecordTarget, AppRecord, MatchResult, ResolveAllEntry } from '@proveanything/smartlinks/dist/types/appObjects';
+import { FacetRule, MatchedAt, AppRecord, RecordTarget, MatchResult, ResolveAllEntry } from '@proveanything/smartlinks/dist/types/appObjects';
+import { ReactNode, ComponentType } from 'react';
 import { LucideIcon } from 'lucide-react';
 import * as _tanstack_query_core from '@tanstack/query-core';
 import * as _proveanything_smartlinks from '@proveanything/smartlinks';
@@ -93,6 +93,21 @@ interface RecordSummary<TData = unknown> {
      * browser uses this to render a friendly rule summary as the row subtitle.
      */
     facetRule?: FacetRule | null;
+    /**
+     * Optional visual hint for the leading status icon on the default row
+     * renderer. When set, takes precedence over the status-derived icon
+     * (configured / inherited / empty). Used by lifecycle rail buckets
+     * (success/warning/etc) and any host that wants per-row iconography
+     * without supplying a full `renderListRow`.
+     */
+    iconHint?: ReactNode;
+    /**
+     * Optional semantic tone for the leading status icon. Drives the icon
+     * colour via `ra-status-icon--<tone>` CSS classes. Has no effect unless
+     * `iconHint` is also set (or the tone is one that maps to a built-in
+     * default icon).
+     */
+    toneHint?: 'success' | 'warning' | 'danger' | 'muted' | 'info' | 'default';
 }
 interface ResolvedRecord<TData = unknown> {
     data: TData | null;
@@ -962,7 +977,35 @@ interface RailConfig<TData = unknown> {
         key: string;
         label: string;
         icon?: ReactNode;
+        /**
+         * Whether this bucket should be expanded by default (records-driven
+         * accordion mode). Last-write-wins per key. Has no effect in the
+         * collection-cardinality lifecycle-rail mode where buckets are flat
+         * selectable rows rather than accordion sections.
+         */
+        defaultOpen?: boolean;
+        /**
+         * Semantic tone for the bucket — drives a CSS data attribute on the
+         * lifecycle bucket row (`data-tone="success" | "warning" | "muted"`).
+         * Apps style via `[data-tone="…"]` selectors against existing
+         * semantic tokens.
+         */
+        tone?: 'default' | 'success' | 'warning' | 'muted' | 'danger';
     } | null;
+    /**
+     * Initial bucket key to select on first mount of the lifecycle rail
+     * (collection cardinality + `'all'` / `'global'` scope + `groupBy`).
+     * Ignored when a deep-link state restores a different selection. Pass
+     * the same key shape your `groupBy` returns (e.g. `"1-open"`).
+     */
+    defaultGroupKey?: string;
+    /**
+     * EXPERIMENTAL — invoked the first time a lifecycle bucket is selected
+     * (collection-cardinality lifecycle rail). Hosts can use this to trigger
+     * supplemental fetches before the bucket-filtered table renders. May be
+     * called more than once per key. API may change before stabilising.
+     */
+    onGroupExpanded?: (key: string) => void;
     /** Visual density. Default `comfortable`. */
     density?: 'comfortable' | 'compact';
 }
@@ -1020,6 +1063,20 @@ interface ItemsConfig<TData = unknown> {
     cardSize?: 'sm' | 'md' | 'lg';
     /** What the rail shows once an item is open. Default `'siblings'`. */
     railMode?: CollectionRailMode;
+    /**
+     * Optional projector that derives `label` / `subtitle` / `thumbnail`
+     * (and any other `RecordSummary` fields) from a raw record. Runs for
+     * every item in the collection-cardinality right-pane list. The
+     * shell's default tries common keys (`title`, `name`, `label`,
+     * `question`, …) — supply this when your record shape doesn't match
+     * those, or when you want the global / all-items list to read from a
+     * different field.
+     *
+     * `base` already carries the framework-derived fields (id, scope,
+     * status, etc.); return a merged `RecordSummary` (e.g.
+     * `{ ...base, label: rec.data?.headline ?? base.label }`).
+     */
+    toSummary?: (rec: AppRecord, base: RecordSummary<TData>) => RecordSummary<TData>;
 }
 interface UnsavedConfig<TData = unknown> {
     /**
@@ -1135,6 +1192,8 @@ interface Props$f {
 declare const StatusDot: ({ source, status, className }: Props$f) => react_jsx_runtime.JSX.Element;
 
 type StatusTone = 'own' | 'shared' | 'missing';
+/** Semantic tones used by host-driven iconography (e.g. lifecycle buckets). */
+type SemanticTone = 'success' | 'warning' | 'danger' | 'muted' | 'info' | 'default';
 interface Props$e {
     source?: RecordSource;
     status?: RecordStatus;
@@ -1143,8 +1202,21 @@ interface Props$e {
     size?: string;
     /** Optional accessible label — defaults to the tone name. */
     label?: string;
+    /**
+     * Host-supplied icon override. Either a React element (rendered as-is)
+     * or any ReactNode. When set, takes precedence over the status-derived
+     * icon. Pair with `semanticTone` to drive colour.
+     */
+    iconHint?: ReactNode;
+    /**
+     * Host-supplied semantic tone (success/warning/danger/muted/info). When
+     * set, drives the icon colour AND — if no `iconHint` is supplied —
+     * picks a sensible default lucide icon per tone (CheckCircle2 / Alert /
+     * XCircle / MinusCircle / Info).
+     */
+    semanticTone?: SemanticTone;
 }
-declare const StatusIcon: ({ source, status, className, size, label }: Props$e) => react_jsx_runtime.JSX.Element;
+declare const StatusIcon: ({ source, status, className, size, label, iconHint, semanticTone, }: Props$e) => react_jsx_runtime.JSX.Element;
 /** Short label rendered next to / under the row title. */
 declare const statusToneLabel: (tone: StatusTone) => string;
 
@@ -1696,7 +1768,7 @@ declare const useRecordList: (args: UseRecordListArgs) => {
     };
     isLoading: boolean;
     error: Error | null;
-    refetch: () => void;
+    refetch: () => Promise<void>;
     hasNextPage: boolean;
     isFetchingNextPage: boolean;
     fetchNextPage: (options?: _tanstack_query_core.FetchNextPageOptions) => Promise<_tanstack_query_core.InfiniteQueryObserverResult<_tanstack_query_core.InfiniteData<{
@@ -1841,7 +1913,7 @@ declare function useCollectionItems<T = unknown>(args: UseCollectionItemsArgs):
         hasMore: boolean;
         nextOffset: number;
     }, unknown>, Error>>;
-    refetch: () => void;
+    refetch: () => Promise<void>;
 };
 
 /**

package/dist/components/RecordsAdmin/index.js

@@ -1,3 +1,4 @@
+import { AdminPageHeader } from '../../chunk-2MW54ZVG.js';
 import { assertComponentStylesLoaded } from '../../chunk-OLYC54YT.js';
 import '../../chunk-5UQQYXCX.js';
 import { FacetRuleEditor } from '../../chunk-JMCV6FOW.js';
@@ -5,8 +6,8 @@ import { useFacets } from '../../chunk-4LHF5JB7.js';
 import { cn } from '../../chunk-L7FQ52F5.js';
 import { parsedRefToTarget, parsedRefToScope, matchRecords, scopesEqual, getRecordById, listRecords, upsertRecord, updateRecord, createRecord, removeRecord } from '../../chunk-KA4MKRHL.js';
 export { bulkDelete, bulkUpsert, createRecord, getRecordById, listRecords, matchRecords, parsedRefToScope, parsedRefToTarget, removeRecord, restoreRecord, scopesEqual, upsertRecord } from '../../chunk-KA4MKRHL.js';
-import { createContext, useState, useEffect, useCallback, useMemo, useRef, useContext, useSyncExternalStore, useLayoutEffect, createElement, useId } from 'react';
-import { ChevronDown, Database, Lightbulb, SearchX, Inbox, LayoutGrid, Eye, MoreHorizontal, Download, Upload, Trash2, Copy, Pencil, Plus, CircleDashed, ArrowDownLeft, CheckCircle2, List, SlidersHorizontal, Globe, Tag, Boxes, Layers, Package, Target, Rows3, ChevronRight, Eraser, ClipboardPaste, Box, X, Search, Image, Table, ArrowLeft, ChevronLeft, AlertTriangle, Info, HelpCircle, CornerDownLeft, Circle, CopyPlus, AlertCircle, Undo2, Save, Loader2, XCircle, ArrowRight, BookOpen, Globe2, Check, Settings2 } from 'lucide-react';
+import { createContext, useState, useEffect, useCallback, useMemo, useRef, isValidElement, useContext, useSyncExternalStore, useLayoutEffect, createElement } from 'react';
+import { ChevronDown, Database, Lightbulb, SearchX, Inbox, LayoutGrid, Eye, MoreHorizontal, Download, Upload, Trash2, Copy, Pencil, Plus, CircleDashed, ArrowDownLeft, CheckCircle2, List, SlidersHorizontal, Globe, Tag, Boxes, Layers, Package, Target, Rows3, ChevronRight, Eraser, ClipboardPaste, Box, X, Search, Image, Table, ArrowLeft, ChevronLeft, AlertTriangle, Info, HelpCircle, CornerDownLeft, Circle, MinusCircle, XCircle, CopyPlus, AlertCircle, Undo2, Save, Loader2, ArrowRight, Globe2, Check, Settings2 } from 'lucide-react';
 import { useQuery, useQueryClient, useInfiniteQuery } from '@tanstack/react-query';
 import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
 import { createPortal } from 'react-dom';
@@ -690,9 +691,9 @@ var useRecordList = (args) => {
     partial: items.filter((r) => r.status === "partial").length,
     empty: items.filter((r) => r.status === "empty").length
   }), [items]);
-  const refetch = useCallback(() => {
-    queryClient.invalidateQueries({ queryKey: [...QK_BASE2, ctx.collectionId, ctx.appId, ctx.recordType] });
-  }, [queryClient, ctx.collectionId, ctx.appId, ctx.recordType]);
+  const refetch = useCallback(() => queryClient.refetchQueries({
+    queryKey: [...QK_BASE2, ctx.collectionId, ctx.appId, ctx.recordType]
+  }), [queryClient, ctx.collectionId, ctx.appId, ctx.recordType]);
   const total = query.data?.pages[query.data.pages.length - 1]?.total ?? items.length;
   return {
     allItems: items,
@@ -3125,9 +3126,11 @@ var useShellSelection = (args) => {
   }, [contextScope?.batchId]);
   const [selectedItemId, setSelectedItemId] = useState(null);
   const skipNextItemResetRef = useRef(false);
+  const [selectedLifecycleKey, setSelectedLifecycleKey] = useState(null);
   useEffect(() => {
     setSelectedRecordId(null);
     setDraftKind(null);
+    setSelectedLifecycleKey(null);
   }, [activeScope]);
   return {
     activeScope,
@@ -3150,6 +3153,8 @@ var useShellSelection = (args) => {
     setSelectedBatchId,
     selectedItemId,
     setSelectedItemId,
+    selectedLifecycleKey,
+    setSelectedLifecycleKey,
     skipNextItemResetRef
   };
 };
@@ -3245,7 +3250,43 @@ var resolveTone = (source, status) => {
   if (source === "inherited" || status === "partial") return "shared";
   return "missing";
 };
-var StatusIcon = ({ source, status, className, size = "1.05rem", label }) => {
+var SEMANTIC_DEFAULT_ICONS = {
+  success: CheckCircle2,
+  warning: AlertTriangle,
+  danger: XCircle,
+  muted: MinusCircle,
+  info: Info
+};
+var StatusIcon = ({
+  source,
+  status,
+  className,
+  size = "1.05rem",
+  label,
+  iconHint,
+  semanticTone
+}) => {
+  if (semanticTone || iconHint) {
+    const toneClass = semanticTone && semanticTone !== "default" ? `ra-status-icon--${semanticTone}` : "ra-status-icon--muted";
+    let content;
+    if (iconHint) {
+      content = isValidElement(iconHint) ? iconHint : /* @__PURE__ */ jsx(Fragment, { children: iconHint });
+    } else {
+      const Icon2 = semanticTone && semanticTone !== "default" ? SEMANTIC_DEFAULT_ICONS[semanticTone] : MinusCircle;
+      content = /* @__PURE__ */ jsx(Icon2, { className: "w-full h-full" });
+    }
+    return /* @__PURE__ */ jsx(
+      "span",
+      {
+        className: cn("ra-status-icon", toneClass, className),
+        style: { width: size, height: size },
+        role: label ? "img" : void 0,
+        "aria-label": label,
+        "aria-hidden": label ? void 0 : "true",
+        children: content
+      }
+    );
+  }
   const tone = resolveTone(source, status);
   const Icon = DEFAULT_ICONS.status[tone === "own" ? "own" : tone === "shared" ? "inherited" : "missing"];
   return /* @__PURE__ */ jsx(
@@ -3478,7 +3519,9 @@ var DefaultRecordRow = ({ record, ctx, compact = false }) => {
             StatusIcon,
             {
               status: record.status,
-              label: statusToneLabel(tone)
+              label: statusToneLabel(tone),
+              iconHint: record.iconHint,
+              semanticTone: record.toneHint
             }
           ) }),
           /* @__PURE__ */ jsxs("div", { className: "ra-row-body", children: [
@@ -4086,9 +4129,7 @@ function useCollectionItems(args) {
       return toSummary2(rec, base);
     }).filter((x) => x !== null);
   }, [query.data, toSummary2, scope, ruleSignature, includeAll]);
-  const refetch = useCallback(() => {
-    queryClient.invalidateQueries({ queryKey });
-  }, [queryClient, queryKey]);
+  const refetch = useCallback(() => queryClient.refetchQueries({ queryKey }), [queryClient, queryKey]);
   return {
     items,
     total: query.data?.pages[query.data.pages.length - 1]?.total ?? items.length,
@@ -6193,89 +6234,6 @@ var UtilityRow = ({ label, customLabel, introHidden, onShowIntro }) => {
     }
   );
 };
-var TONE_ICON2 = {
-  info: Lightbulb,
-  success: CheckCircle2,
-  warning: AlertTriangle
-};
-function AdminPageHeader({
-  title,
-  subtitle,
-  icon,
-  helpUrl,
-  helpLabel,
-  actions,
-  aside,
-  intro,
-  className
-}) {
-  const titleId = useId();
-  const resolvedHelpLabel = helpLabel ?? "Help & documentation";
-  const resolvedReopenLabel = intro?.reopenLabel ?? "How it works";
-  const showReopen = !!intro && intro.dismissed && !!intro.onReopen;
-  const showIntro = !!intro && !intro.dismissed;
-  return /* @__PURE__ */ jsxs("header", { className: `sl-aph${className ? ` ${className}` : ""}`, "aria-labelledby": titleId, children: [
-    /* @__PURE__ */ jsxs("div", { className: "sl-aph__row", children: [
-      /* @__PURE__ */ jsx("div", { className: "sl-aph__main", children: /* @__PURE__ */ jsxs("div", { className: "sl-aph__text", children: [
-        /* @__PURE__ */ jsxs("h1", { className: "sl-aph__title", id: titleId, children: [
-          icon ? /* @__PURE__ */ jsx("span", { className: "sl-aph__icon", "aria-hidden": "true", children: icon }) : null,
-          /* @__PURE__ */ jsx("span", { children: title })
-        ] }),
-        subtitle ? /* @__PURE__ */ jsx("p", { className: "sl-aph__subtitle", children: subtitle }) : null
-      ] }) }),
-      actions || aside || helpUrl || showReopen ? /* @__PURE__ */ jsxs("div", { className: "sl-aph__aside", children: [
-        actions,
-        aside,
-        helpUrl ? /* @__PURE__ */ jsx(
-          "a",
-          {
-            href: helpUrl,
-            target: "_blank",
-            rel: "noopener noreferrer",
-            className: "sl-aph__icon-btn",
-            "aria-label": resolvedHelpLabel,
-            title: resolvedHelpLabel,
-            children: /* @__PURE__ */ jsx(BookOpen, { "aria-hidden": "true" })
-          }
-        ) : null,
-        showReopen ? /* @__PURE__ */ jsx(
-          "button",
-          {
-            type: "button",
-            onClick: intro.onReopen,
-            className: "sl-aph__icon-btn",
-            "aria-label": resolvedReopenLabel,
-            title: resolvedReopenLabel,
-            children: /* @__PURE__ */ jsx(HelpCircle, { "aria-hidden": "true" })
-          }
-        ) : null
-      ] }) : null
-    ] }),
-    showIntro ? /* @__PURE__ */ jsx(AdminPageHeaderIntroCard, { intro }) : null
-  ] });
-}
-function AdminPageHeaderIntroCard({ intro }) {
-  const tone = intro.tone ?? "info";
-  const Icon = TONE_ICON2[tone] ?? Info;
-  return /* @__PURE__ */ jsxs("div", { className: "sl-aph__intro", "data-tone": tone, role: "note", children: [
-    /* @__PURE__ */ jsx("div", { className: "sl-aph__intro-icon", children: /* @__PURE__ */ jsx(Icon, { "aria-hidden": "true", style: { width: "0.95rem", height: "0.95rem" } }) }),
-    /* @__PURE__ */ jsxs("div", { className: "sl-aph__intro-body", children: [
-      /* @__PURE__ */ jsx("h4", { className: "sl-aph__intro-title", children: intro.title }),
-      /* @__PURE__ */ jsx("span", { className: "sl-aph__intro-text", children: intro.body }),
-      intro.action ? /* @__PURE__ */ jsx("span", { className: "sl-aph__intro-action", children: intro.action }) : null
-    ] }),
-    /* @__PURE__ */ jsx(
-      "button",
-      {
-        type: "button",
-        onClick: intro.onDismiss,
-        "aria-label": "Dismiss",
-        className: "sl-aph__intro-dismiss",
-        children: /* @__PURE__ */ jsx(X, { "aria-hidden": "true", style: { width: "0.875rem", height: "0.875rem" } })
-      }
-    )
-  ] });
-}
 function ShellHeader({
   title,
   subtitle,
@@ -7452,6 +7410,8 @@ function RecordsAdminShellInner(props) {
     renderListRow,
     renderEmpty: renderEmptyState,
     groupBy,
+    defaultGroupKey,
+    onGroupExpanded,
     density = "comfortable"
   } = rail ?? {};
   const {
@@ -7474,7 +7434,8 @@ function RecordsAdminShellInner(props) {
     renderCard: renderItemCard,
     renderEmpty: renderItemEmpty,
     cardSize: itemCardSize = "md",
-    railMode: collectionRailMode = "siblings"
+    railMode: collectionRailMode = "siblings",
+    toSummary: itemToSummary
   } = items ?? {};
   const {
     strategy: dirtyStrategy = "keep",
@@ -7592,8 +7553,11 @@ function RecordsAdminShellInner(props) {
     setSelectedBatchId,
     selectedItemId,
     setSelectedItemId,
+    selectedLifecycleKey,
+    setSelectedLifecycleKey,
     skipNextItemResetRef
   } = selection;
+  const [isReconcilingRecordSelection, setIsReconcilingRecordSelection] = useState(false);
   const { dismissed, dismiss, undismiss } = useIntroDismissed(SL, collectionId, appId, recordType);
   const headerWillRender = useMemo(() => {
     const headerCustomised = !!title || !!subtitle || !!headerIcon || !!headerActions || showStats || !!statsItems || !!statsTitle || !!statsIcon || !!helpUrl;
@@ -7654,6 +7618,7 @@ function RecordsAdminShellInner(props) {
   useEffect(() => {
     if (activeScope !== "rule" && activeScope !== "collection" && activeScope !== "all") return;
     if (selectedRecordId !== null) return;
+    if (isReconcilingRecordSelection) return;
     if (ruleWizardStep !== null) return;
     if (draftKind !== null) return;
     if (activeScope === "collection" && cardinality === "collection") {
@@ -7664,7 +7629,7 @@ function RecordsAdminShellInner(props) {
     }
     const first = recordList.items[0];
     if (first?.id) setSelectedRecordId(first.id);
-  }, [activeScope, selectedRecordId, recordList.items, cardinality, ruleWizardStep, draftKind]);
+  }, [activeScope, selectedRecordId, recordList.items, cardinality, ruleWizardStep, draftKind, isReconcilingRecordSelection]);
   const editingScopes = useEditingScope({
     activeScope,
     cardinality,
@@ -7692,7 +7657,8 @@ function RecordsAdminShellInner(props) {
     // record across the whole collection (anchored, ruled, global) so
     // host-supplied lifecycle grouping has the full picture.
     includeAll: isCollection && activeScope === "all",
-    enabled: isCollection
+    enabled: isCollection,
+    toSummary: itemToSummary
   });
   useEffect(() => {
     if (skipNextItemResetRef.current) {
@@ -7761,10 +7727,15 @@ function RecordsAdminShellInner(props) {
     supportedScopes: supportedForResolution,
     enabled: !!editingTargetScope
   });
-  const refetchAll = useCallback(() => {
-    recordList.refetch();
-    if (isCollection) collectionItems.refetch();
-  }, [recordList, isCollection, collectionItems]);
+  const refetchAll = useCallback(async () => {
+    await Promise.all([
+      recordList.refetch(),
+      isCollection ? collectionItems.refetch() : Promise.resolve(),
+      queryClient.refetchQueries({
+        queryKey: scopeCountsQueryKey(ctx.collectionId, ctx.appId, ctx.recordType)
+      })
+    ]);
+  }, [recordList, isCollection, collectionItems, queryClient, ctx.collectionId, ctx.appId, ctx.recordType]);
   const { editorCtx } = useShellEditorTarget({
     editingTargetScope,
     isCollection,
@@ -7783,7 +7754,7 @@ function RecordsAdminShellInner(props) {
     },
     defaultData,
     deriveDraftLabel,
-    onSaved: (isCreate, savedRecordId) => {
+    onSaved: async (isCreate, savedRecordId) => {
       onTelemetry?.({ type: "record.save", recordType, ref: editingTargetScope?.raw ?? "", isCreate });
       if (ruleWizardStep !== null) {
         setRuleWizardStep(null);
@@ -7791,15 +7762,20 @@ function RecordsAdminShellInner(props) {
         setDraftKind(null);
       }
       if (isCreate && selectedRecordId === DRAFT_ID3) {
-        setSelectedRecordId(savedRecordId ?? null);
+        setIsReconcilingRecordSelection(true);
+        setSelectedRecordId(null);
         setDraftKind(null);
       }
       if (isCreate && isCollection && savedRecordId && isDraftId3(selectedItemId)) {
         setSelectedItemId(savedRecordId);
       }
-      refetchAll();
+      await refetchAll();
+      if (!isCollection && isCreate && activeScope === "collection") {
+        setSelectedRecordId(savedRecordId ?? null);
+      }
+      setIsReconcilingRecordSelection(false);
     },
-    onDeleted: () => {
+    onDeleted: async () => {
       onTelemetry?.({ type: "record.delete", recordType, ref: editingTargetScope?.raw ?? "" });
       if (isCollection && selectedItemId) {
         setSelectedItemId(null);
@@ -7808,10 +7784,12 @@ function RecordsAdminShellInner(props) {
       } else if (drillTab === "batch") {
         setSelectedBatchId(void 0);
       } else if (selectedRecordId) {
+        setIsReconcilingRecordSelection(true);
         setSelectedRecordId(null);
         setDraftKind(null);
       }
-      refetchAll();
+      await refetchAll();
+      setIsReconcilingRecordSelection(false);
     }
   });
   useUnsavedGuard({
@@ -8426,17 +8404,96 @@ function RecordsAdminShellInner(props) {
     }),
     [i18n.itemsAllLabel, collectionItems.items.length, itemNoun]
   );
+  const isLifecycleRail = (isAllTab || isGlobalTab) && isCollection && !!groupBy;
+  const lifecycleBuckets = useMemo(() => {
+    if (!isLifecycleRail || !groupBy) return [];
+    const map = /* @__PURE__ */ new Map();
+    const order = [];
+    for (const item of collectionItems.items) {
+      const g = groupBy(item) ?? { key: "__other", label: "Other" };
+      let bucket = map.get(g.key);
+      if (!bucket) {
+        bucket = { key: g.key, label: g.label, icon: g.icon, tone: g.tone, items: [] };
+        map.set(g.key, bucket);
+        order.push(g.key);
+      }
+      bucket.items.push(item);
+    }
+    return order.sort().map((k) => map.get(k));
+  }, [isLifecycleRail, groupBy, collectionItems.items]);
+  const LIFECYCLE_PREFIX = "lifecycle:";
+  const lifecycleRows = useMemo(() => {
+    if (!isLifecycleRail) return [];
+    const rows = [
+      {
+        id: `${LIFECYCLE_PREFIX}__all`,
+        ref: "",
+        scope: parseRef(""),
+        data: null,
+        status: collectionItems.items.length ? "configured" : "empty",
+        label: i18n.itemsAllLabel,
+        subtitle: collectionItems.items.length ? `${collectionItems.items.length} ${itemNoun}${collectionItems.items.length === 1 ? "" : "s"}` : void 0
+      }
+    ];
+    for (const b of lifecycleBuckets) {
+      rows.push({
+        id: `${LIFECYCLE_PREFIX}${b.key}`,
+        ref: "",
+        scope: parseRef(""),
+        data: null,
+        status: b.items.length ? "configured" : "empty",
+        label: b.label,
+        subtitle: `${b.items.length} ${itemNoun}${b.items.length === 1 ? "" : "s"}`,
+        // Tone + icon drive the row's leading status icon (replacing the
+        // generic green tick / dotted circle for these synthetic rows).
+        // Hosts can override the icon entirely via `groupBy(...).icon`.
+        iconHint: b.icon,
+        toneHint: b.tone
+      });
+    }
+    return rows;
+  }, [isLifecycleRail, lifecycleBuckets, collectionItems.items.length, i18n.itemsAllLabel, itemNoun]);
+  const lifecycleSeededRef = useRef(false);
+  useEffect(() => {
+    if (!isLifecycleRail) {
+      lifecycleSeededRef.current = false;
+      return;
+    }
+    if (lifecycleSeededRef.current) return;
+    if (selectedLifecycleKey !== null) {
+      lifecycleSeededRef.current = true;
+      return;
+    }
+    if (!defaultGroupKey) return;
+    if (!lifecycleBuckets.some((b) => b.key === defaultGroupKey)) return;
+    setSelectedLifecycleKey(defaultGroupKey);
+    lifecycleSeededRef.current = true;
+  }, [isLifecycleRail, defaultGroupKey, lifecycleBuckets, selectedLifecycleKey, setSelectedLifecycleKey]);
+  const filteredCollectionItems = useMemo(() => {
+    if (!isLifecycleRail || !selectedLifecycleKey || !groupBy) return collectionItems.items;
+    return collectionItems.items.filter((it) => {
+      const g = groupBy(it) ?? { key: "__other" };
+      return g.key === selectedLifecycleKey;
+    });
+  }, [isLifecycleRail, selectedLifecycleKey, groupBy, collectionItems.items]);
   const leftItems = isProductTab ? productListItems : isRuleTab ? applyFacetBrowseFilter(
     isCollection ? collectionRuleRailItems : filteredRuleItems
-  ) : (isGlobalTab || isAllTab) && isCollection ? [collectionGlobalAllRow] : isRecordsTab ? applyFacetBrowseFilter(recordList.items) : [];
+  ) : isLifecycleRail ? lifecycleRows : (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;
+  const leftSelectedId = isProductTab ? void 0 : isLifecycleRail ? `${LIFECYCLE_PREFIX}${selectedLifecycleKey ?? "__all"}` : selectedRecordId && selectedRecordId !== DRAFT_ID3 ? selectedRecordId : void 0;
   const leftSelectedAnchorKey = isProductTab ? selectedProductId ? buildRef({ productId: selectedProductId }) : void 0 : void 0;
   const dirtyId = !editorCtx.isDirty ? void 0 : selectedRecordId && selectedRecordId !== DRAFT_ID3 ? selectedRecordId : void 0;
   const dirtyAnchorKey = !editorCtx.isDirty ? void 0 : isProductTab ? editingScope?.raw : void 0;
   const onLeftSelect = (item) => {
     void runWithGuard(() => {
+      if (isLifecycleRail && typeof item.id === "string" && item.id.startsWith(LIFECYCLE_PREFIX)) {
+        const key = item.id.slice(LIFECYCLE_PREFIX.length);
+        const next = key === "__all" ? null : key;
+        setSelectedLifecycleKey(next);
+        if (next && onGroupExpanded) onGroupExpanded(next);
+        return;
+      }
       if (isProductTab) {
         setSelectedProductId(item.scope.productId);
         setSelectedVariantId(void 0);
@@ -8794,7 +8851,7 @@ function RecordsAdminShellInner(props) {
                           // navigational anchor, not a real record — applying the
                           // host's groupBy bucketed it under "Other" (its
                           // data is null). Skip grouping for that single-row rail.
-                          (isGlobalTab || isAllTab) && isCollection ? void 0 : effectiveGroupBy
+                          (isGlobalTab || isAllTab) && isCollection || isLifecycleRail ? void 0 : effectiveGroupBy
                         ),
                         renderGroupActions: renderRuleGroupActions,
                         rowClipboard,
@@ -8883,7 +8940,7 @@ function RecordsAdminShellInner(props) {
                 ruleWizardStep === null && isCollection && editingScope && !selectedItemId && /* @__PURE__ */ jsx(
                   ItemListView,
                   {
-                    items: collectionItems.items,
+                    items: filteredCollectionItems,
                     isLoading: collectionItems.isLoading,
                     error: collectionItems.error,
                     ctx: itemViewCtx,