@anzusystems/common-admin 1.47.0-beta.dev-1782077999 → 1.47.0-beta.dev-1782079999

package/dist/labs.d.ts

@@ -10,6 +10,7 @@ import { MaybeRefOrGetter } from 'vue';
 import { Method } from 'axios';
 import { PublicProps } from 'vue';
 import { Ref } from 'vue';
+import { ShallowRef } from 'vue';
 import { ShallowUnwrapRef } from 'vue';
 import { UseDebounceFnReturn } from '@vueuse/shared';
 import { VNode } from 'vue';
@@ -907,6 +908,14 @@ export declare function createFilter<F extends readonly MakeFilterOption<string>
 
 export declare function createFilterStore<F extends readonly MakeFilterOption<string>[]>(filterFields: F): FilterData<F>;
 
+/**
+ * Create a scope. The internal `effectScope` is NOT detached: it attaches to whatever scope creates
+ * it — the providing editor's component scope (so everything stops on its unmount) or a persisted
+ * ENTRY's scope (so a nested editor's own row scope outlives the editor exactly as its controller
+ * does).
+ */
+export declare function createListEditorStateScope(): ListEditorStateScope;
+
 declare interface DatatableColumnsConfigMoreOptions {
     storeColumnsLocalStorage: string | boolean;
     disableActions: boolean;
@@ -1238,6 +1247,60 @@ export declare interface ListEditorHandle<TItem extends Record<string, any>> {
 
 export declare type ListEditorKey = DocId | IntegerId | string;
 
+/**
+ * The instance-bound controller options an editor re-supplies on EVERY (re)mount. `get`/`set` close
+ * over the editor instance's `modelValue`/`emit`, and `factory`/`validate`/`dirtyExclude` over its
+ * props — a remounted editor is a NEW instance, so a persisted controller must read all of them
+ * through the live binding (see `useListEditorStateEntry`), never through the closures of the dead
+ * instance that happened to create it.
+ */
+export declare type ListEditorStateBindings<TItem extends Record<string, any>> = Pick<UseListEditorControllerOptions<TItem>, 'get' | 'set' | 'factory' | 'getKey' | 'position' | 'dirtyExclude' | 'validate'>;
+
+/** What a `state-key`'d editor gets back: its persisted handle + the scope to hand to ITS own rows. */
+export declare interface ListEditorStateEntry<THandle> {
+    handle: THandle;
+    /** Scope for this editor's `#item` slot subtree — persisted alongside the entry, so a
+     *  grand-nested `state-key`'d editor survives this editor's unmount too. */
+    childScope: ListEditorStateScope | null;
+}
+
+/**
+ * A keyed registry of list-editor state controllers, owned by an ANCESTOR (the editor that provides
+ * it for its `#item` slot subtree) and living in that ancestor's `effectScope` — NOT in the scope of
+ * the transient editor component that resolves it. That is the whole point: a nested editor's `#item`
+ * slot is behind a `v-if`, so collapsing a row UNMOUNTS the nested editor; a component-owned
+ * controller dies with it and a brand-new one re-baselines the already-edited data on re-expand,
+ * losing amber / movedKeys / editedKeys / tombstones / the submitted (red-rail) flag.
+ */
+export declare interface ListEditorStateScope {
+    /** Unique per scope instance; namespaces the row prefixes this scope mints (and can prune). */
+    readonly id: string;
+    /**
+     * First call for `key` CREATES the controller inside this scope (via `create`, from the calling
+     * editor's own bindings) and registers it. Every later call REBINDS the registered controller to
+     * the (new) calling instance's bindings and returns it — state intact.
+     */
+    resolve<TBindings extends object, THandle>(key: string, bindings: TBindings, create: (live: ShallowRef<TBindings>) => THandle, uid?: number | null): THandle;
+    /**
+     * The editor bound to `key` is unmounting: park the entry — its model accessors are swapped for a
+     * frozen read + a no-op write so the orphaned controller can never read or write through the dead
+     * instance's `modelValue`/`emit`. No-op when another instance has already rebound (mount-before-
+     * unmount ordering), which is why the caller passes its uid.
+     */
+    release<TBindings extends object>(key: string, uid: number | null, park: (bindings: TBindings) => TBindings): void;
+    /** Child scope of a registered entry (created lazily inside the entry's effect scope). */
+    childScope(key: string): ListEditorStateScope | null;
+    /** The state-key prefix for a row — hosts thread it down and suffix it per nested list. */
+    prefixFor(rowKey: ListEditorKey): string;
+    /** Dispose the entries of rows that no longer exist (keys minted from `prefixFor` only). */
+    retainOwners(liveRowKeys: Iterable<ListEditorKey>): void;
+    has(key: string): boolean;
+    size(): number;
+    dispose(): void;
+}
+
+export declare const ListEditorStateScopeKey: InjectionKey<ListEditorStateScope>;
+
 /** Per-row validity. `true` (or `{ valid: true }`) = VALID. Only `valid: false` blocks save. */
 export declare type ListEditorValidationResult = boolean | {
     valid: boolean;
@@ -1376,6 +1439,8 @@ export declare interface NestedListEditorHandle<TItem extends Record<string, any
     calculateSubtreeDepth: (node: NestedTreeNode<TItem>) => number;
 }
 
+export declare type NestedListEditorStateBindings<TItem extends Record<string, any>> = Pick<UseNestedListEditorControllerOptions<TItem>, 'get' | 'set' | 'factory' | 'getKey' | 'position' | 'parentField' | 'maxDepth' | 'dirtyExclude' | 'validate'>;
+
 export declare interface NestedPositionHint {
     parentId?: ListEditorKey | null;
     afterId?: ListEditorKey;
@@ -1502,6 +1567,18 @@ declare interface Props<TItem extends Record<string, any>> {
      * internally. Either way the `ListEditorHandle` is reachable via `useTemplateRef`.
      */
     editor?: ListEditorHandle<TItem>;
+    /**
+     * Persist this editor's controller in the nearest ANCESTOR editor's row-state scope under this
+     * key, instead of owning it. Use it for an editor rendered in another editor's `#item` slot: that
+     * slot is behind a `v-if`, so collapsing the row unmounts this editor and a component-owned
+     * controller would re-baseline the already-edited data on re-expand (losing amber, tombstones and
+     * the red rail). Derive the key from the row slot's `stateKeyPrefix`, e.g.
+     * `:state-key="`${stateKeyPrefix}:adverts`"`. Options stay declared here, on this tag: the
+     * controller is built from THIS editor's `factory`/`get-key`/`position`/`dirty-exclude`/`validate`
+     * and rebound to each new instance's model on remount. Ignored when `:editor` is passed, and a
+     * no-op without an ancestor scope.
+     */
+    stateKey?: string;
     readonly?: boolean;
     disabled?: boolean;
     loading?: boolean;
@@ -1591,6 +1668,18 @@ declare interface Props_2<TItem extends Record<string, any>> {
      * relocation). When omitted the editor owns an internal controller.
      */
     editor?: ListEditorHandle<TItem>;
+    /**
+     * Persist this editor's controller in the nearest ANCESTOR editor's row-state scope under this
+     * key, instead of owning it. Use it for an editor rendered in another editor's `#item` slot: that
+     * slot is behind a `v-if`, so collapsing the row unmounts this editor and a component-owned
+     * controller would re-baseline the already-edited data on re-expand (losing amber, moved rows,
+     * tombstones and the red rail). Derive the key from the row slot's `stateKeyPrefix`, e.g.
+     * `:state-key="`${stateKeyPrefix}:answers`"`. Options stay declared here, on this tag: the
+     * controller is built from THIS editor's `factory`/`get-key`/`position`/`dirty-exclude`/`validate`
+     * and rebound to each new instance's model on remount. Ignored when `:editor` is passed, and a
+     * no-op without an ancestor scope.
+     */
+    stateKey?: string;
     readonly?: boolean;
     disabled?: boolean;
     loading?: boolean;
@@ -1689,6 +1778,15 @@ declare interface Props_3<TItem extends Record<string, any>> {
      * reachable via `useTemplateRef`.
      */
     editor?: NestedListEditorHandle<TItem>;
+    /**
+     * Persist this editor's controller in the nearest ANCESTOR editor's row-state scope under this
+     * key, instead of owning it. Use it for an editor rendered in another editor's `#item` slot (that
+     * slot is behind a `v-if`, so collapsing the row unmounts this editor and a component-owned
+     * controller would re-baseline the already-edited tree on re-expand). Derive the key from the row
+     * slot's `stateKeyPrefix`. Options stay declared here, on this tag. Ignored when `:editor` is
+     * passed, and a no-op without an ancestor scope.
+     */
+    stateKey?: string;
     readonly?: boolean;
     disabled?: boolean;
     loading?: boolean;
@@ -1741,6 +1839,13 @@ declare interface Props_4 {
     dirtyLabels?: string[];
 }
 
+/**
+ * Provide the row-state scope for an editor's `#item` slot subtree. A `state-key`'d editor passes
+ * the `childScope` of its own persisted entry (so the chain survives at any depth); a plain editor
+ * creates a component-owned scope that dies with it.
+ */
+export declare function provideListEditorStateScope(inherited: ListEditorStateScope | null): ListEditorStateScope;
+
 /**
  * Non-mutating renumber to sequential positions matching array order — the same
  * renumbering the editors apply on commit. Unchanged items stay reference-equal.
@@ -1838,6 +1943,13 @@ declare interface RowSlotProps<TItem extends Record<string, any>> {
     /** Aliases `dirty` here (no reorder mode → no `moved` to OR). Same field name as on sortable/nested variants. */
     unsaved: boolean;
     touch: boolean;
+    /**
+     * Row-scoped `state-key` prefix. Thread it down to any list editor rendered in this slot and set
+     * its `:state-key="`${stateKeyPrefix}:someList`"` — that editor's controller then lives in THIS
+     * editor's scope and survives the row collapsing (which unmounts the whole slot subtree). Entries
+     * under this prefix are disposed when the row is removed.
+     */
+    stateKeyPrefix: string;
     actions: RowActions<TItem>;
 }
 
@@ -1857,6 +1969,13 @@ declare interface RowSlotProps_2<TItem extends Record<string, any>> {
     canMoveUp: boolean;
     canMoveDown: boolean;
     touch: boolean;
+    /**
+     * Row-scoped `state-key` prefix. Thread it down to any list editor rendered in this slot and set
+     * its `:state-key="`${stateKeyPrefix}:someList`"` — that editor's controller then lives in THIS
+     * editor's scope and survives the row collapsing (which unmounts the whole slot subtree). Entries
+     * under this prefix are disposed when the row is removed.
+     */
+    stateKeyPrefix: string;
     actions: RowActions_2<TItem>;
 }
 
@@ -1890,6 +2009,13 @@ declare interface RowSlotProps_3<TItem extends Record<string, any>> {
     canOutdent: boolean;
     canAddChild: boolean;
     touch: boolean;
+    /**
+     * Row-scoped `state-key` prefix. Thread it down to any list editor rendered in this slot and set
+     * its `:state-key="`${stateKeyPrefix}:someList`"` — that editor's controller then lives in THIS
+     * editor's scope and survives the row collapsing (which unmounts the whole slot subtree). Entries
+     * under this prefix are disposed when the row is removed.
+     */
+    stateKeyPrefix: string;
     actions: RowActions_3<TItem>;
 }
 
@@ -2198,6 +2324,18 @@ export declare interface UseListEditorOptions {
     updatePosition?: boolean;
 }
 
+/**
+ * Resolve this editor's controller from the nearest ancestor scope under `stateKey` (or `null` when
+ * the editor has no `state-key`, or no ancestor provides a scope → today's component-owned
+ * controller, unchanged).
+ *
+ * The controller is built from the FIRST mounting instance's own props, but every instance-bound
+ * option is read through `live` — the shallowRef the scope swaps on each (re)mount. `getKey` and
+ * `position` are static per tag, so the controller reads them once (it derives its key field at
+ * construction); everything else is indirected.
+ */
+export declare function useListEditorStateEntry<TItem extends Record<string, any>>(stateKey: string | undefined, bindings: ListEditorStateBindings<TItem>): ListEditorStateEntry<ListEditorHandle<TItem>> | null;
+
 /**
  * Nested list editor core. Pure data behavior shared by ANestedSortableListEditor.
  * Works on a tree of `{ data, children, meta }` nodes — shape-compatible with the
@@ -2257,6 +2395,9 @@ declare interface UseNestedListEditorOptions {
     expandedKeys?: Ref<Set<ListEditorKey>>;
 }
 
+/** Tree-shaped twin of `useListEditorStateEntry` for ANestedSortableListEditor. */
+export declare function useNestedListEditorStateEntry<TItem extends Record<string, any>>(stateKey: string | undefined, bindings: NestedListEditorStateBindings<TItem>): ListEditorStateEntry<NestedListEditorHandle<TItem>> | null;
+
 /**
  * Aggregates per-parent child-editor unsaved-keys into one prefix-merged set.
  * Used by stacked editors (e.g. quiz: questions → answers) so the outer