@anzusystems/common-admin 1.47.0-beta.dev-1782075999 → 1.47.0-beta.dev-1782078999

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;
@@ -1006,6 +1015,29 @@ declare type ExecuteRequestParams<T> = {
     object?: T;
 };
 
+/**
+ * The shape a CONSUMER sees when it reads a list-editor handle through a template/function ref.
+ * Vue's `expose` proxy unwraps every exposed ref, so the reactive fields (`hasUnsaved`, `hasErrors`,
+ * `unsavedCount`, …) arrive as plain VALUES here, not `Ref`s: read `handle.hasUnsaved` (a boolean),
+ * never `handle.hasUnsaved.value` (that is `undefined`). Type your `useTemplateRef` / collected-ref
+ * maps with this so a stray `.value` is a compile error instead of a silently-dead guard/save-gate.
+ */
+export declare type ExposedListEditorHandle<TItem extends Record<string, any>> = ShallowUnwrapRef<ListEditorHandle<TItem>>;
+
+/**
+ * Consumer-facing shape of a nested-list-editor handle read through a template/function ref — Vue's
+ * `expose` proxy unwraps the exposed refs, so read `handle.hasUnsaved` (a boolean), not
+ * `handle.hasUnsaved.value`. See {@link ExposedListEditorHandle}.
+ *
+ * The `ANestedSortableListEditor` component also exposes `hasUnsavedChanges` (a legacy alias of
+ * `hasUnsaved`, likewise a ComputedRef → unwrapped to a boolean here) — included so it can't be
+ * `.value`-read by accident. Its imperative-only extras (addAfterId / resetDirtyBaseline / expand /
+ * reorder / …) are not refs and carry no unwrap hazard; intersect them in the consumer if you call them.
+ */
+export declare type ExposedNestedListEditorHandle<TItem extends Record<string, any>> = ShallowUnwrapRef<NestedListEditorHandle<TItem>> & {
+    hasUnsavedChanges: boolean;
+};
+
 declare type FetchByIdsParams = {
     urlTemplate?: string;
     urlParams?: UrlParams;
@@ -1207,19 +1239,68 @@ export declare interface ListEditorHandle<TItem extends Record<string, any>> {
     /** Clear a deferred-deletion tombstone (the caller re-inserts the row, e.g. reorder Cancel). */
     restoreDeleted: (key: ListEditorKey) => void;
     moveItem: (fromIndex: number, toIndex: number) => void;
+    /** Drop the "moved" flag for the given keys (or all) without touching edits/adds — e.g. reorder Cancel. */
+    clearMoved: (keys?: Iterable<ListEditorKey>) => void;
     /** Escape hatch: a row form (e.g. vuelidate) reports its own validity instead of `validate`. */
     registerValidity: (key: ListEditorKey, isValid: () => boolean) => () => void;
 }
 
 export declare type ListEditorKey = DocId | IntegerId | string;
 
-export declare const ListEditorValidationKey: InjectionKey<ListEditorValidationRegistry>;
+/**
+ * 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'>;
 
-export declare interface ListEditorValidationRegistry {
-    register: (key: ListEditorKey, state: Ref<ListEditorValidationState> | ComputedRef<ListEditorValidationState>) => void;
-    unregister: (key: ListEditorKey) => void;
+/** 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;
@@ -1358,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;
@@ -1484,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;
@@ -1573,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;
@@ -1671,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;
@@ -1723,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.
@@ -1820,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>;
 }
 
@@ -1839,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>;
 }
 
@@ -1872,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>;
 }
 
@@ -2107,9 +2251,14 @@ export declare function useFilterHelpers<F extends readonly MakeFilterOption<str
  * the view on an already-deleted entity (system error). This acknowledges the guard right before the
  * delete so the follow-up navigation proceeds without prompting. (QA 85050 batch 7 — BUG-08)
  *
+ * If `onDelete` REJECTS (the delete failed and never navigated), the acknowledgement is undone
+ * immediately (`unacknowledge()`) so a subsequently-dirtied navigation is still guarded (M1) — the
+ * error is re-thrown so the caller's own handling runs. For this to catch failures, `onDelete` must
+ * let its error propagate (don't swallow it in the action's try/catch).
+ *
  * Usage: `@delete-record="guardedDelete(() => onDelete(id))"` or wrap the handler once.
  */
-export declare function useGuardedDelete<A extends unknown[], R>(guard: Pick<UseUnsavedChangesGuardApi, 'acknowledge'>, onDelete: (...args: A) => R): (...args: A) => R;
+export declare function useGuardedDelete<A extends unknown[], R>(guard: Pick<UseUnsavedChangesGuardApi, 'acknowledge' | 'unacknowledge'>, onDelete: (...args: A) => R): (...args: A) => R | Promise<Awaited<R>>;
 
 export declare function useJobApi<JobType extends JobBase = JobBase>(client: () => AxiosInstance, system: string): {
     useFetchJobList: () => UseApiFetchListReturnType<JobType[]>;
@@ -2168,39 +2317,6 @@ export declare interface UseListEditorControllerOptions<TItem extends Record<str
     normalizeSaved?: (savedItems: TItem[]) => TItem[];
 }
 
-export declare function useListEditorItemValidation(options: UseListEditorItemValidationOptions): void;
-
-declare interface UseListEditorItemValidationOptions {
-    /**
-     * Stable identity of the row in the editor's v-model. Pass a getter so the
-     * composable can re-register if the key ever swaps.
-     */
-    key: () => ListEditorKey;
-    /**
-     * Reactive validation state. Common shape: a computed reading vuelidate's
-     * `v$.$dirty && v$.$invalid` and returning 'invalid' or null.
-     *
-     * Prefer `invalid` (+ optional `dirty`) below: it lets the editor surface the
-     * error once the row is unsaved without relying on mount-relative `$anyDirty`.
-     * `state` is kept for callers that report 'valid'/'warning' or custom logic.
-     */
-    state?: Ref<ListEditorValidationState> | ComputedRef<ListEditorValidationState> | (() => ListEditorValidationState);
-    /**
-     * Whether the row's data fails validation right now (e.g. `() => v$.value.$invalid`).
-     * When provided, the row is flagged 'invalid' as soon as it is invalid AND the
-     * user has had a chance to fix it — i.e. the row is unsaved (added / modified)
-     * or `dirty` below is true. Untouched rows on initial load stay clear so a
-     * persisted-but-invalid record does not light up red before any interaction.
-     */
-    invalid?: () => boolean;
-    /**
-     * Optional extra "has been interacted with" signal OR-ed with the editor's
-     * unsaved tracking (e.g. `() => v$.value.$anyDirty`). Useful when unsaved
-     * tracking is disabled on the editor.
-     */
-    dirty?: () => boolean;
-}
-
 export declare interface UseListEditorOptions {
     keyField?: string;
     positionField?: string;
@@ -2209,23 +2325,16 @@ export declare interface UseListEditorOptions {
 }
 
 /**
- * Registers a row's vuelidate state with the surrounding list editor so the
- * row shows the red invalid rail (invalid + unsaved/dirty) instead of amber.
- *
- * This is the one blessed shape for row validity sentinels — domain sentinels
- * call their validation composable and delegate here:
+ * 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).
  *
- * ```ts
- * const item = computed(() => props.modelValue)
- * const { v$ } = useReviewListItemValidation(item)
- * useListEditorVuelidateSentinel(v$, () => item.value.id ?? item.value.position)
- * ```
- *
- * `key` must return the same key the editor resolves for the row
- * (its `key-field`) or the item's own id/position — the editor's validation
- * registry accepts either.
+ * 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 useListEditorVuelidateSentinel(v$: Ref<VuelidateSentinelSource>, key: () => ListEditorKey): void;
+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.
@@ -2286,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
@@ -2429,8 +2541,19 @@ declare interface UseUnsavedChangesGuardApi {
      * route/dialog/unload attempt proceeds without prompting. Useful right
      * before a programmatic navigation that the consumer has already
      * confirmed.
+     *
+     * The acknowledgement AUTO-EXPIRES after a few seconds if nothing consumes it
+     * (see `ACKNOWLEDGE_TTL_MS`): a delete that acknowledges up-front but then FAILS
+     * (throws, never navigates) must not leave the guard silently disarmed for the
+     * next unrelated navigation. Consuming it (a real leave) clears the timer.
      */
     acknowledge: () => void;
+    /**
+     * Cancel a pending `acknowledge()` (disarm). Call from a delete's failure path
+     * so a failed/aborted delete restores the guard immediately instead of waiting
+     * for the TTL. No-op if nothing is acknowledged.
+     */
+    unacknowledge: () => void;
 }
 
 declare interface UseUnsavedChangesGuardOptions {
@@ -2505,15 +2628,6 @@ declare interface ViewBodySlotProps<TItem extends Record<string, any>> {
     };
 }
 
-/**
- * Minimal surface of a vuelidate instance the sentinel reads — any
- * `useVuelidate()` return value is structurally assignable.
- */
-export declare interface VuelidateSentinelSource {
-    $invalid: boolean;
-    $anyDirty: boolean;
-}
-
 export { }
 
 declare global {