@anzusystems/common-admin 1.47.0-beta.dev-1778754008 → 1.47.0-beta.dev-1782072279

package/dist/labs.d.ts

@@ -6,6 +6,7 @@ import { ComponentProvideOptions } from 'vue';
 import { ComputedRef } from 'vue';
 import { DefineComponent } from 'vue';
 import { InjectionKey } from 'vue';
+import { MaybeRefOrGetter } from 'vue';
 import { Method } from 'axios';
 import { PublicProps } from 'vue';
 import { Ref } from 'vue';
@@ -278,35 +279,17 @@ declare const __VLS_export_16: <TItem>(__VLS_props: NonNullable<Awaited<typeof _
 declare const __VLS_export_17: <TItem extends Record<string, any>>(__VLS_props: NonNullable<Awaited<typeof __VLS_setup>>["props"], __VLS_ctx?: __VLS_PrettifyLocal_4<Pick<NonNullable<Awaited<typeof __VLS_setup>>, "attrs" | "emit" | "slots">>, __VLS_exposed?: NonNullable<Awaited<typeof __VLS_setup>>["expose"], __VLS_setup?: Promise<{
     props: PublicProps & __VLS_PrettifyLocal_4<(Props<TItem> & {
         modelValue: TItem[];
-        unsavedKeys?: Set<ListEditorKey>;
     }) & {
         onDeleted?: ((item: ListViewItem<TItem>) => any) | undefined;
         onClose?: ((item: ListViewItem<TItem>) => any) | undefined;
         onEdit?: ((item: ListViewItem<TItem>) => any) | undefined;
-        onAdd?: ((positionHint: PositionHint | undefined) => any) | undefined;
         "onUpdate:modelValue"?: ((value: TItem[]) => any) | undefined;
-        onAdded?: ((payload: {
-            item: TItem;
-            index: number;
-        }) => any) | undefined;
         "onItem-saved"?: ((item: ListViewItem<TItem>) => any) | undefined;
         "onItem-expand"?: ((item: ListViewItem<TItem>, expanded: boolean) => any) | undefined;
-        "onUpdate:unsavedKeys"?: ((value: Set<ListEditorKey>) => any) | undefined;
     }> & (typeof globalThis extends {
         __VLS_PROPS_FALLBACK: infer P;
     } ? P : {});
-    expose: (exposed: ShallowUnwrapRef<{
-        addItem: (data: TItem, positionHint?: PositionHint) => TItem[];
-        deleteItem: (idOrItem: ListEditorKey | TItem) => TItem[];
-        updateItem: (idOrItem: ListEditorKey | TItem, data: TItem) => TItem[];
-        moveItem: (fromIndex: number, toIndex: number) => TItem[];
-        recalculatePositions: (items: TItem[]) => TItem[];
-        viewItems: ComputedRef<ListViewItem<TItem>[]>;
-        resetDirtyBaseline: () => void;
-        hasUnsavedChanges: ComputedRef<boolean>;
-        unsavedCount: ComputedRef<number>;
-        clearUnsavedState: (key?: ListEditorKey) => void;
-    }>) => void;
+    expose: (exposed: ShallowUnwrapRef<ListEditorHandle<TItem>>) => void;
     attrs: any;
     slots: {
         header?: (props: HeaderSlotProps) => unknown;
@@ -321,10 +304,7 @@ declare const __VLS_export_17: <TItem extends Record<string, any>>(__VLS_props:
         'before-item'?: (props: RowSlotProps<TItem>) => unknown;
         'after-item'?: (props: RowSlotProps<TItem>) => unknown;
     };
-    emit: (((evt: "deleted", item: ListViewItem<TItem>) => void) & ((evt: "close", item: ListViewItem<TItem>) => void) & ((evt: "edit", item: ListViewItem<TItem>) => void) & ((evt: "add", positionHint: PositionHint | undefined) => void) & ((evt: "added", payload: {
-        item: TItem;
-        index: number;
-    }) => void) & ((evt: "item-saved", item: ListViewItem<TItem>) => void) & ((evt: "item-expand", item: ListViewItem<TItem>, expanded: boolean) => void)) & (((event: "update:modelValue", value: TItem[]) => void) & ((event: "update:unsavedKeys", value: Set<ListEditorKey>) => void));
+    emit: (((evt: "deleted", item: ListViewItem<TItem>) => void) & ((evt: "close", item: ListViewItem<TItem>) => void) & ((evt: "edit", item: ListViewItem<TItem>) => void) & ((evt: "item-saved", item: ListViewItem<TItem>) => void) & ((evt: "item-expand", item: ListViewItem<TItem>, expanded: boolean) => void)) & ((event: "update:modelValue", value: TItem[]) => void);
 }>) => VNode & {
     __ctx?: Awaited<typeof __VLS_setup>;
 };
@@ -333,18 +313,12 @@ declare const __VLS_export_18: <TItem extends Record<string, any>>(__VLS_props:
     props: PublicProps & __VLS_PrettifyLocal_5<(Props_2<TItem> & {
         modelValue: TItem[];
         mode?: ReorderMode;
-        unsavedKeys?: Set<ListEditorKey>;
     }) & {
         onDeleted?: ((item: ListViewItem<TItem>) => any) | undefined;
         onClose?: ((item: ListViewItem<TItem>) => any) | undefined;
         onEdit?: ((item: ListViewItem<TItem>) => any) | undefined;
-        onAdd?: ((positionHint: PositionHint | undefined) => any) | undefined;
         "onUpdate:modelValue"?: ((value: TItem[]) => any) | undefined;
         "onUpdate:mode"?: ((value: ReorderMode) => any) | undefined;
-        onAdded?: ((payload: {
-            item: TItem;
-            index: number;
-        }) => any) | undefined;
         "onItem-saved"?: ((item: ListViewItem<TItem>) => any) | undefined;
         "onItem-expand"?: ((item: ListViewItem<TItem>, expanded: boolean) => any) | undefined;
         "onReorder-start"?: (() => any) | undefined;
@@ -352,21 +326,10 @@ declare const __VLS_export_18: <TItem extends Record<string, any>>(__VLS_props:
         "onReorder-applied"?: ((items: TItem[]) => any) | undefined;
         "onReorder-apply-error"?: ((error: unknown) => any) | undefined;
         "onReorder-end"?: (() => any) | undefined;
-        "onUpdate:unsavedKeys"?: ((value: Set<ListEditorKey>) => any) | undefined;
     }> & (typeof globalThis extends {
         __VLS_PROPS_FALLBACK: infer P;
     } ? P : {});
-    expose: (exposed: ShallowUnwrapRef<{
-        addItem: (data: TItem, positionHint?: PositionHint) => TItem[];
-        deleteItem: (idOrItem: ListEditorKey | TItem) => TItem[];
-        updateItem: (idOrItem: ListEditorKey | TItem, data: TItem) => TItem[];
-        moveItem: (fromIndex: number, toIndex: number) => TItem[];
-        recalculatePositions: (items: TItem[]) => TItem[];
-        viewItems: ComputedRef<ListViewItem<TItem>[]>;
-        resetDirtyBaseline: () => void;
-        hasUnsavedChanges: ComputedRef<boolean>;
-        unsavedCount: ComputedRef<number>;
-        clearUnsavedState: (key?: ListEditorKey) => void;
+    expose: (exposed: ShallowUnwrapRef<ListEditorHandle<TItem> & {
         enterReorderMode: () => void;
         cancelReorderMode: () => void;
         applyReorder: () => Promise<void>;
@@ -388,10 +351,7 @@ declare const __VLS_export_18: <TItem extends Record<string, any>>(__VLS_props:
         'before-item'?: (props: RowSlotProps_2<TItem>) => unknown;
         'after-item'?: (props: RowSlotProps_2<TItem>) => unknown;
     };
-    emit: (((evt: "deleted", item: ListViewItem<TItem>) => void) & ((evt: "close", item: ListViewItem<TItem>) => void) & ((evt: "edit", item: ListViewItem<TItem>) => void) & ((evt: "add", positionHint: PositionHint | undefined) => void) & ((evt: "added", payload: {
-        item: TItem;
-        index: number;
-    }) => void) & ((evt: "item-saved", item: ListViewItem<TItem>) => void) & ((evt: "item-expand", item: ListViewItem<TItem>, expanded: boolean) => void) & ((evt: "reorder-start") => void) & ((evt: "reorder-cancel") => void) & ((evt: "reorder-applied", items: TItem[]) => void) & ((evt: "reorder-apply-error", error: unknown) => void) & ((evt: "reorder-end") => void)) & (((event: "update:modelValue", value: TItem[]) => void) & ((event: "update:mode", value: ReorderMode) => void) & ((event: "update:unsavedKeys", value: Set<ListEditorKey>) => void));
+    emit: (((evt: "deleted", item: ListViewItem<TItem>) => void) & ((evt: "close", item: ListViewItem<TItem>) => void) & ((evt: "edit", item: ListViewItem<TItem>) => void) & ((evt: "item-saved", item: ListViewItem<TItem>) => void) & ((evt: "item-expand", item: ListViewItem<TItem>, expanded: boolean) => void) & ((evt: "reorder-start") => void) & ((evt: "reorder-cancel") => void) & ((evt: "reorder-applied", items: TItem[]) => void) & ((evt: "reorder-apply-error", error: unknown) => void) & ((evt: "reorder-end") => void)) & (((event: "update:modelValue", value: TItem[]) => void) & ((event: "update:mode", value: ReorderMode) => void));
 }>) => VNode & {
     __ctx?: Awaited<typeof __VLS_setup>;
 };
@@ -400,7 +360,6 @@ declare const __VLS_export_19: <TItem extends Record<string, any>>(__VLS_props:
     props: PublicProps & __VLS_PrettifyLocal_6<(Props_3<TItem> & {
         modelValue: NestedTree<TItem>;
         mode?: ReorderMode_2;
-        unsavedKeys?: Set<ListEditorKey>;
     }) & {
         onDeleted?: ((item: NestedViewItem<TItem>) => any) | undefined;
         onClose?: ((item: NestedViewItem<TItem>) => any) | undefined;
@@ -417,44 +376,27 @@ declare const __VLS_export_19: <TItem extends Record<string, any>>(__VLS_props:
         "onReorder-applied"?: ((tree: NestedTree<TItem>) => any) | undefined;
         "onReorder-apply-error"?: ((error: unknown) => any) | undefined;
         "onReorder-end"?: (() => any) | undefined;
-        "onUpdate:unsavedKeys"?: ((value: Set<ListEditorKey>) => any) | undefined;
         "onAdd-child"?: ((parent: NestedViewItem<TItem>) => any) | undefined;
     }> & (typeof globalThis extends {
         __VLS_PROPS_FALLBACK: infer P;
     } ? P : {});
-    expose: (exposed: ShallowUnwrapRef<{
-        addItem: (data: TItem, hint?: PositionHint & {
-            parentId?: ListEditorKey | null;
-            asFirstChild?: boolean;
-            childrenAllowed?: boolean;
-        }) => NestedTree<TItem>;
+    expose: (exposed: ShallowUnwrapRef<NestedListEditorHandle<TItem> & {
         addAfterId: (targetId: ListEditorKey | null, data: TItem, childrenAllowed: boolean) => NestedTree<TItem>;
         addChildToId: (targetId: ListEditorKey, data: TItem, childrenAllowed: boolean) => NestedTree<TItem>;
         removeById: (id: ListEditorKey) => void;
         updateData: (id: ListEditorKey, data: TItem, _children?: unknown, _position?: unknown, _markUnsaved?: unknown) => void;
-        updateItem: (id: ListEditorKey, data: TItem, markDirty?: boolean) => NestedTree<TItem>;
-        deleteItem: (id: ListEditorKey) => NestedTree<TItem>;
-        moveUp: (id: ListEditorKey) => NestedTree<TItem> | null;
-        moveDown: (id: ListEditorKey) => NestedTree<TItem> | null;
-        moveTop: (id: ListEditorKey) => NestedTree<TItem> | null;
-        moveBottom: (id: ListEditorKey) => NestedTree<TItem> | null;
-        indent: (id: ListEditorKey) => NestedTree<TItem> | null;
-        outdent: (id: ListEditorKey) => NestedTree<TItem> | null;
-        moveTo: (id: ListEditorKey, targetParentId: ListEditorKey | null, targetIndex: number) => NestedTree<TItem> | null;
-        recalculatePositions: (model: NestedTree<TItem>) => NestedTree<TItem>;
-        viewItems: ComputedRef<NestedViewItem<TItem>[]>;
         resetDirtyBaseline: () => void;
         hasUnsavedChanges: ComputedRef<boolean>;
         unsavedCount: ComputedRef<number>;
-        clearUnsavedState: (key?: ListEditorKey) => void;
+        clearUnsavedState: () => void;
         enterReorderMode: () => void;
         cancelReorderMode: () => void;
         applyReorder: () => Promise<void>;
-        expand: (id: ListEditorKey) => Set<ListEditorKey> & Omit<Set<ListEditorKey>, keyof Set<any>>;
-        collapse: (id: ListEditorKey) => boolean;
+        expand: (id: ListEditorKey) => void;
+        collapse: (id: ListEditorKey) => void;
         toggleExpand: (id: ListEditorKey) => void;
-        expandDetail: (id: ListEditorKey) => Set<ListEditorKey> & Omit<Set<ListEditorKey>, keyof Set<any>>;
-        collapseDetail: (id: ListEditorKey) => boolean;
+        expandDetail: (id: ListEditorKey) => void;
+        collapseDetail: (id: ListEditorKey) => void;
     }>) => void;
     attrs: any;
     slots: {
@@ -472,7 +414,7 @@ declare const __VLS_export_19: <TItem extends Record<string, any>>(__VLS_props:
         'before-item'?: (props: RowSlotProps_3<TItem>) => unknown;
         'after-item'?: (props: RowSlotProps_3<TItem>) => unknown;
     };
-    emit: (((evt: "deleted", item: NestedViewItem<TItem>) => void) & ((evt: "close", item: NestedViewItem<TItem>) => void) & ((evt: "edit", item: NestedViewItem<TItem>) => void) & ((evt: "add", hint: NestedPositionHint | undefined) => void) & ((evt: "indent", item: NestedViewItem<TItem>) => void) & ((evt: "outdent", item: NestedViewItem<TItem>) => void) & ((evt: "item-saved", item: NestedViewItem<TItem>) => void) & ((evt: "item-expand", item: NestedViewItem<TItem>, expanded: boolean) => void) & ((evt: "reorder-start") => void) & ((evt: "reorder-cancel") => void) & ((evt: "reorder-applied", tree: NestedTree<TItem>) => void) & ((evt: "reorder-apply-error", error: unknown) => void) & ((evt: "reorder-end") => void) & ((evt: "add-child", parent: NestedViewItem<TItem>) => void)) & (((event: "update:modelValue", value: NestedTree<TItem>) => void) & ((event: "update:mode", value: ReorderMode_2) => void) & ((event: "update:unsavedKeys", value: Set<ListEditorKey>) => void));
+    emit: (((evt: "deleted", item: NestedViewItem<TItem>) => void) & ((evt: "close", item: NestedViewItem<TItem>) => void) & ((evt: "edit", item: NestedViewItem<TItem>) => void) & ((evt: "add", hint: NestedPositionHint | undefined) => void) & ((evt: "indent", item: NestedViewItem<TItem>) => void) & ((evt: "outdent", item: NestedViewItem<TItem>) => void) & ((evt: "item-saved", item: NestedViewItem<TItem>) => void) & ((evt: "item-expand", item: NestedViewItem<TItem>, expanded: boolean) => void) & ((evt: "reorder-start") => void) & ((evt: "reorder-cancel") => void) & ((evt: "reorder-applied", tree: NestedTree<TItem>) => void) & ((evt: "reorder-apply-error", error: unknown) => void) & ((evt: "reorder-end") => void) & ((evt: "add-child", parent: NestedViewItem<TItem>) => void)) & (((event: "update:modelValue", value: NestedTree<TItem>) => void) & ((event: "update:mode", value: ReorderMode_2) => void));
 }>) => VNode & {
     __ctx?: Awaited<typeof __VLS_setup>;
 };
@@ -1011,6 +953,8 @@ declare interface DecoratedViewItem<T> extends ListViewItem<T> {
     expanded: boolean;
     loading: boolean;
     dirty: boolean;
+    unsaved: boolean;
+    validationState: ListEditorValidationState;
 }
 
 declare interface DecoratedViewItem_2<T> extends ListViewItem<T> {
@@ -1020,6 +964,7 @@ declare interface DecoratedViewItem_2<T> extends ListViewItem<T> {
     dirty: boolean;
     moved: boolean;
     unsaved: boolean;
+    validationState: ListEditorValidationState;
     canMoveUp: boolean;
     canMoveDown: boolean;
 }
@@ -1161,6 +1106,8 @@ declare interface GeneralFilterOptions {
 
 export declare const generateListQuery: (pagination: Ref<Pagination>, filterData: FilterData<any>, filterConfig: FilterConfig<any>) => string;
 
+export declare type GetKey<TItem> = keyof TItem | ((item: TItem) => ListEditorKey);
+
 declare interface HeaderSlotProps {
     title: string | null;
 }
@@ -1220,6 +1167,41 @@ export declare interface ListEditorApi<TItem> {
     recalculatePositions: (items: TItem[]) => TItem[];
 }
 
+export declare interface ListEditorChanges<TItem> {
+    added: TItem[];
+    updated: TItem[];
+    moved: TItem[];
+    deleted: TItem[];
+    reparented: TItem[];
+}
+
+export declare interface ListEditorHandle<TItem extends Record<string, any>> {
+    items: ComputedRef<TItem[]>;
+    hasUnsaved: ComputedRef<boolean>;
+    hasErrors: ComputedRef<boolean>;
+    invalidKeys: ComputedRef<Set<ListEditorKey>>;
+    /** Amber: is this row added / edited / moved since the last commit? */
+    isUnsaved: (key: ListEditorKey) => boolean;
+    /** Red rail (gated): 'invalid' only once the row is unsaved or `validateAll()` ran. */
+    rowState: (item: TItem, key: ListEditorKey) => ListEditorValidationState;
+    /** Force-show all invalid rows + return whether the list is valid. The save guard. */
+    validateAll: () => boolean;
+    /** Normalized ordered array for a full-DTO save. */
+    getPayload: () => TItem[];
+    /** Change-set for partial-save endpoints. */
+    getChanges: () => ListEditorChanges<TItem>;
+    /** Adopt saved rows as the new baseline; backfill keys; clear unsaved/submitted. */
+    commit: (savedItems?: TItem[]) => void;
+    /** Discard unsaved edits back to the last committed baseline (or given items). */
+    reset: (items?: TItem[]) => void;
+    addItem: (item?: TItem, hint?: PositionHint) => void;
+    updateItem: (key: ListEditorKey, next: TItem | Partial<TItem> | ((current: TItem) => TItem)) => void;
+    deleteItem: (key: ListEditorKey) => void;
+    moveItem: (fromIndex: number, toIndex: number) => 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>;
@@ -1229,6 +1211,13 @@ export declare interface ListEditorValidationRegistry {
     unregister: (key: ListEditorKey) => void;
 }
 
+/** Per-row validity. `true` (or `{ valid: true }`) = VALID. Only `valid: false` blocks save. */
+export declare type ListEditorValidationResult = boolean | {
+    valid: boolean;
+    state?: 'invalid' | 'warning';
+    message?: string;
+};
+
 export declare type ListEditorValidationState = 'valid' | 'invalid' | 'warning' | null;
 
 export declare interface ListViewItem<TItem> {
@@ -1281,6 +1270,71 @@ export declare interface NestedListEditorApi<TItem extends Record<string, any>>
     calculateSubtreeDepth: (node: NestedTreeNode<TItem>) => number;
 }
 
+/** Flattened ordered row carrying its resolved key (for change-sets + payload). */
+export declare interface NestedListEditorChanges<TItem> {
+    added: TItem[];
+    updated: TItem[];
+    moved: TItem[];
+    deleted: TItem[];
+    /**
+     * Rows whose parent changed since the last commit (BUG-13 — persisted even
+     * when the position number is unchanged).
+     */
+    reparented: TItem[];
+}
+
+/**
+ * Tree-shaped state controller for the nested list editor (v2). A superset of
+ * the flat `ListEditorHandle`: same dirty/validate/commit/reset semantics, but
+ * the row set is a flattened ordered projection of a `NestedTree` and the
+ * mutators are tree ops (indent / outdent / moveTo / addChild …) delegated to
+ * `useNestedListEditor`. Each flattened payload row carries its resolved
+ * `position` and parent key written onto it.
+ */
+export declare interface NestedListEditorHandle<TItem extends Record<string, any>> {
+    /** Flattened ordered rows (depth-first), matching the rendered order. */
+    items: ComputedRef<TItem[]>;
+    /** Tree view rows (key/index/raw/depth/parent…), as consumed by the renderer. */
+    viewItems: ComputedRef<NestedViewItem<TItem>[]>;
+    hasUnsaved: ComputedRef<boolean>;
+    hasErrors: ComputedRef<boolean>;
+    invalidKeys: ComputedRef<Set<ListEditorKey>>;
+    /** Amber: is this row added / edited / moved / reparented since the last commit? */
+    isUnsaved: (key: ListEditorKey) => boolean;
+    /** Red rail (gated): 'invalid' only once the row is unsaved or `validateAll()` ran. */
+    rowState: (item: TItem, key: ListEditorKey) => ListEditorValidationState;
+    /** Force-show all invalid rows + return whether the tree is valid. The save guard. */
+    validateAll: () => boolean;
+    /** Flattened ordered array (each row carrying its resolved position + parent key) for a full-DTO save. */
+    getPayload: () => TItem[];
+    /** Change-set for partial-save endpoints (added/updated/moved/deleted/reparented), keyed. */
+    getChanges: () => NestedListEditorChanges<TItem>;
+    /** Adopt the saved tree as the new baseline; backfill keys; clear dirty/submitted. */
+    commit: (saved?: NestedTree<TItem>) => void;
+    /** Discard unsaved edits back to the last committed baseline (or a given tree). */
+    reset: (tree?: NestedTree<TItem>) => void;
+    addItem: (item?: TItem, hint?: NestedPositionHint) => void;
+    addAfter: (afterKey: ListEditorKey, item?: TItem, childrenAllowed?: boolean) => void;
+    addChild: (parentKey: ListEditorKey, item?: TItem, childrenAllowed?: boolean) => void;
+    updateItem: (key: ListEditorKey, data: TItem, markDirty?: boolean) => void;
+    deleteItem: (key: ListEditorKey) => void;
+    moveUp: (key: ListEditorKey) => boolean;
+    moveDown: (key: ListEditorKey) => boolean;
+    moveTop: (key: ListEditorKey) => boolean;
+    moveBottom: (key: ListEditorKey) => boolean;
+    indent: (key: ListEditorKey) => boolean;
+    outdent: (key: ListEditorKey) => boolean;
+    moveTo: (key: ListEditorKey, targetParentKey: ListEditorKey | null, targetIndex: number) => boolean;
+    recalculatePositions: () => void;
+    /** Escape hatch: a row form (e.g. vuelidate) reports its own validity instead of `validate`. */
+    registerValidity: (key: ListEditorKey, isValid: () => boolean) => () => void;
+    findNode: (key: ListEditorKey) => {
+        node: NestedTreeNode<TItem> | null;
+        parent: NestedTreeNode<TItem> | null;
+    };
+    calculateSubtreeDepth: (node: NestedTreeNode<TItem>) => number;
+}
+
 export declare interface NestedPositionHint {
     parentId?: ListEditorKey | null;
     afterId?: ListEditorKey;
@@ -1360,11 +1414,46 @@ export declare interface PositionHint {
     index?: number;
 }
 
+export declare type PositionOption<TItem> = false | keyof TItem | {
+    field: keyof TItem;
+    multiplier?: number;
+};
+
 declare interface Props<TItem extends Record<string, any>> {
-    keyField?: string;
-    positionField?: string;
-    positionMultiplier?: number;
-    updatePosition?: boolean;
+    /**
+     * New-row factory. Add / "add after" insert `factory()` through the controller
+     * (positions renumbered) — no consumer `@add` push handler is needed.
+     */
+    factory?: () => TItem;
+    /**
+     * Stable row identity. Default `'id'`; never the position field. Typed `string`
+     * not `keyof TItem` because the latter compiles to a Boolean-only runtime prop
+     * type that silently coerces `get-key="id"` to `true`.
+     */
+    getKey?: string | ((item: TItem) => ListEditorKey);
+    /**
+     * Managed order field. Default `'position'`; `false` opts out. `string` must be
+     * listed before `false` (and not be `keyof TItem`): otherwise Vue's runtime
+     * type goes Boolean-first and coerces `position="position"` to `true`.
+     */
+    position?: string | false | {
+        field: string;
+        multiplier?: number;
+    };
+    /**
+     * Extra fields to drop from the dirty content-hash (position is always dropped).
+     * Use when a SEPARATE nested editor already tracks a child collection, so editing
+     * a child doesn't flip the parent row amber. Still saved; only the diff ignores it.
+     */
+    dirtyExclude?: string[];
+    /** Per-row validity — `true` (or `{ valid: true }`) = VALID. Drives the red rail + save guard. */
+    validate?: (item: TItem) => ListEditorValidationResult;
+    /**
+     * Opt-in lifted controller from `useListEditorController()` — pass it so editor
+     * state survives this component's unmount/remount. Omitted: the editor owns one
+     * internally. Either way the `ListEditorHandle` is reachable via `useTemplateRef`.
+     */
+    editor?: ListEditorHandle<TItem>;
     readonly?: boolean;
     disabled?: boolean;
     loading?: boolean;
@@ -1382,49 +1471,64 @@ declare interface Props<TItem extends Record<string, any>> {
     emptyTitle?: string | null;
     disableRowClick?: boolean;
     disableDeleteConfirm?: boolean;
-    /** Disable unsaved-state tracking — no dirty markers, never feeds `unsaved-keys`. */
+    /** Disable unsaved-state tracking — no dirty markers, never reads as unsaved. */
     disableUnsaved?: boolean;
     deleteConfirmTitle?: string | null;
     deleteConfirmText?: string | null;
     closeVariant?: 'auto' | 'icon' | 'labeled';
     /**
-     * Render every row's `#item` slot expanded by default — no edit pencil, no
-     * inline Save/Cancel footer, no row-click toggle. Use when the editor has
-     * no reorder affordance and the consumer wants all forms visible at once
-     * (e.g. ThirdPartyTracker, bookmarks dialog).
+     * Render every `#item` slot expanded — no edit pencil, inline footer, or row-click
+     * toggle. Use when all forms should be visible at once (e.g. ThirdPartyTracker).
      */
     defaultExpanded?: boolean;
     loadingKeys?: Set<ListEditorKey> | null;
-    getValidationState?: (item: TItem, key: ListEditorKey, index: number) => ListEditorValidationState;
     onDeleteConfirm?: (item: TItem) => Promise<boolean> | boolean;
     onDelete?: (item: TItem) => Promise<void> | void;
     onItemSave?: (item: TItem) => Promise<void> | void;
     /**
-     * Editor-managed add: the add button and "add after this item" insert
-     * `itemFactory()` into the model directly (positions renumbered when
-     * `update-position` is on) and emit `added` — the `add` event does NOT fire,
-     * so no consumer push handler is needed.
-     */
-    itemFactory?: () => TItem;
-    /**
-     * Editor-managed delete: a confirmed delete removes the row from the model
-     * itself. `deleted` still fires as a notification — consumers keep side
-     * effects but must not splice the model themselves.
-     */
-    manageDelete?: boolean;
-    /**
-     * Registers this editor as a named unsaved-changes section under the given
-     * (already translated) label — replaces the per-consumer `useUnsavedSection`
-     * call for the common one-editor case.
+     * Registers this editor as a named unsaved-changes section under this (already
+     * translated) label — replaces a per-consumer `useUnsavedSection` call.
      */
     unsavedSectionLabel?: string;
 }
 
 declare interface Props_2<TItem extends Record<string, any>> {
-    keyField?: string;
-    positionField?: string;
-    positionMultiplier?: number;
-    updatePosition?: boolean;
+    /**
+     * New-row factory (required). The add button + "add after this item" insert
+     * `factory()` into the model directly through the controller (positions
+     * renumbered) — no consumer `@add` push handler is needed.
+     */
+    factory?: () => TItem;
+    /**
+     * Stable row identity. Default `'id'`. Never point this at the position field.
+     * Typed `string` (not `keyof TItem`): a bare `keyof TItem` on a generic
+     * component compiles to a Boolean-only runtime type that coerces `get-key="id"` to `true`.
+     */
+    getKey?: string | ((item: TItem) => ListEditorKey);
+    /**
+     * Managed order field. Default `'position'`. `false` opts out. Typed `string`
+     * before `false` so the runtime prop type is `[String, Boolean, Object]`:
+     * `keyof TItem` would be Boolean-only, and `false` listed first would coerce
+     * `position="position"` (value == prop name) to `true`.
+     */
+    position?: string | false | {
+        field: string;
+        multiplier?: number;
+    };
+    /**
+     * Extra fields to drop from the dirty content-hash (position is always
+     * dropped). Use when a SEPARATE nested editor tracks a row's child collection,
+     * so editing a child doesn't flip the parent amber. The field is still saved.
+     */
+    dirtyExclude?: string[];
+    /** Per-row validity — `true` (or `{ valid: true }`) = VALID. Drives the red rail + save guard. */
+    validate?: (item: TItem) => ListEditorValidationResult;
+    /**
+     * Opt-in lifted state controller (from consumer's `useListEditorController()`)
+     * so editor state survives this component's unmount/remount (pinned-widget
+     * relocation). When omitted the editor owns an internal controller.
+     */
+    editor?: ListEditorHandle<TItem>;
     readonly?: boolean;
     disabled?: boolean;
     loading?: boolean;
@@ -1449,61 +1553,67 @@ declare interface Props_2<TItem extends Record<string, any>> {
     showReorderToggle?: boolean;
     disableReorder?: boolean;
     disableDrag?: boolean;
-    /** Disable unsaved-state tracking — no dirty/moved markers, never feeds `unsaved-keys`. */
-    disableUnsaved?: boolean;
     showMoveToPosition?: boolean;
     /**
-     * Embedded mode — this editor is nested inside another editor's `#item`
-     * slot and follows a shared `v-model:mode` from the outer editor. When
-     * set, the editor:
-     *   - hides its own Reorder button + Cancel/Apply toolbar
-     *   - skips the snapshot/restore (the outer editor's deep snapshot covers
-     *     nested data, so cancel at the top reverts everything)
-     *   - paints lighter chrome so it visually reads as part of the parent row
-     * Pair with `v-model:mode` bound to the same ref the outer editor uses.
+     * Embedded mode — nested inside another editor's `#item` slot, following a
+     * shared `v-model:mode`. Hides own Reorder button + toolbar, skips the
+     * snapshot/restore (the outer editor's deep snapshot covers nested data), and
+     * paints lighter chrome. Pair with `v-model:mode` bound to the outer ref.
      */
     embedded?: boolean;
     /**
-     * Allow rows to remain inline-editable while the editor is in reorder
-     * mode. By default, entering reorder closes any open inline edit and the
-     * `#item` slot body is hidden — this keeps the visual focus on dragging.
-     * Set this when the open row's body needs to render in reorder mode (e.g.
-     * the parent editor of a shared-reorder pair, where the open question
-     * exposes its embedded answers list for dragging).
+     * Keep rows inline-editable in reorder mode. By default entering reorder
+     * closes any open edit and hides the `#item` body to focus on dragging. Set
+     * for a shared-reorder pair's parent, where the open row exposes its embedded
+     * answers list for dragging.
      */
     allowEditInReorder?: boolean;
-    getValidationState?: (item: TItem, key: ListEditorKey, index: number) => ListEditorValidationState;
     onDeleteConfirm?: (item: TItem) => Promise<boolean> | boolean;
     onDelete?: (item: TItem) => Promise<void> | void;
     onItemSave?: (item: TItem) => Promise<void> | void;
     onReorderApply?: (items: TItem[]) => Promise<void> | void;
+    /** Register as a named unsaved-changes section under this (translated) label. */
+    unsavedSectionLabel?: string;
+}
+
+declare interface Props_3<TItem extends Record<string, any>> {
+    maxDepth: number;
     /**
-     * Editor-managed add: the add button and "add after this item" insert
-     * `itemFactory()` into the model directly (positions renumbered when
-     * `update-position` is on) and emit `added` — the `add` event does NOT fire,
-     * so no consumer push handler is needed.
+     * New-row factory; if set, add/add-after/add-inside insert through the
+     * controller (no `@add` handler needed). Optional for read-only trees.
      */
-    itemFactory?: () => TItem;
+    factory?: () => TItem;
     /**
-     * Editor-managed delete: a confirmed delete removes the row from the model
-     * itself. `deleted` still fires as a notification — consumers keep side
-     * effects but must not splice the model themselves.
+     * Stable row identity. Default `'id'`. Never point at the position field.
+     * Typed `string` (not `keyof TItem`): a bare keyof compiles to a Boolean-only
+     * runtime type that silently coerces `get-key="id"` to `true`.
      */
-    manageDelete?: boolean;
+    getKey?: string | ((item: TItem) => ListEditorKey);
     /**
-     * Registers this editor as a named unsaved-changes section under the given
-     * (already translated) label — replaces the per-consumer `useUnsavedSection`
-     * call for the common one-editor case.
+     * Managed order field. Default `'position'`; `false` opts out. Typed
+     * `[String, Boolean, Object]` with `string` before `false`: a bare keyof
+     * compiles Boolean-only, and `false`-first would coerce `position="position"`
+     * (value == prop name) to `true`. Object form folds in `{ field, multiplier }`.
      */
-    unsavedSectionLabel?: string;
-}
-
-declare interface Props_3<TItem extends Record<string, any>> {
-    maxDepth: number;
-    keyField?: string;
-    positionField?: string;
+    position?: string | false | {
+        field: string;
+        multiplier?: number;
+    };
+    /** Parent-key field written onto reparented rows. Default `'parent'`. */
     parentField?: string;
-    positionMultiplier?: number;
+    /**
+     * Extra fields dropped from the dirty content-hash (position + parent always
+     * dropped), e.g. a child collection tracked by a separate editor.
+     */
+    dirtyExclude?: string[];
+    /** Per-row validity — `true` (or `{ valid: true }`) = VALID. Drives the red rail + save guard. */
+    validate?: (item: TItem) => ListEditorValidationResult;
+    /**
+     * Opt-in lifted controller (`useNestedListEditorController()`) so state
+     * survives unmount/remount; omitted = internal controller. Same handle
+     * reachable via `useTemplateRef`.
+     */
+    editor?: NestedListEditorHandle<TItem>;
     readonly?: boolean;
     disabled?: boolean;
     loading?: boolean;
@@ -1519,7 +1629,6 @@ declare interface Props_3<TItem extends Record<string, any>> {
     showMoveToPosition?: boolean;
     showChangeParent?: boolean;
     showExpandToggle?: boolean;
-    getValidationState?: (item: TItem, key: ListEditorKey, index: number) => ListEditorValidationState;
     addLabel?: string | null;
     emptyTitle?: string | null;
     disableRowClick?: boolean;
@@ -1531,17 +1640,11 @@ declare interface Props_3<TItem extends Record<string, any>> {
     showReorderToggle?: boolean;
     disableReorder?: boolean;
     disableDrag?: boolean;
-    /** Disable unsaved-state tracking — no dirty/moved markers, never feeds `unsaved-keys`. */
-    disableUnsaved?: boolean;
     onDeleteConfirm?: (item: TItem) => Promise<boolean> | boolean;
     onDelete?: (item: TItem) => Promise<void> | void;
     onItemSave?: (item: TItem) => Promise<void> | void;
     onReorderApply?: (tree: NestedTree<TItem>) => Promise<void> | void;
-    /**
-     * Registers this editor as a named unsaved-changes section under the given
-     * (already translated) label — replaces the per-consumer `useUnsavedSection`
-     * call for the common one-editor case.
-     */
+    /** Registers this editor as a named unsaved-changes section under the given (translated) label. */
     unsavedSectionLabel?: string;
 }
 
@@ -1557,6 +1660,10 @@ declare interface Props_4 {
     dirtyLabels?: string[];
 }
 
+/**
+ * Non-mutating renumber to sequential positions matching array order — the same
+ * renumbering the editors apply on commit. Unchanged items stay reference-equal.
+ */
 export declare const renumberPositions: <TItem extends Record<string, any>>(items: TItem[], options?: RenumberPositionsOptions) => TItem[];
 
 export declare interface RenumberPositionsOptions {
@@ -1600,7 +1707,7 @@ declare interface RowActions<TItem> {
     delete: () => Promise<void>;
     addAfter: () => void;
     toggleExpand: () => void;
-    update: (data: TItem) => TItem[];
+    update: (next: TItem | Partial<TItem> | ((current: TItem) => TItem)) => void;
 }
 
 declare interface RowActions_2<TItem> {
@@ -1615,7 +1722,7 @@ declare interface RowActions_2<TItem> {
     moveDown: () => void;
     moveTop: () => void;
     moveBottom: () => void;
-    update: (data: TItem) => TItem[];
+    update: (next: TItem | Partial<TItem> | ((current: TItem) => TItem)) => void;
 }
 
 declare interface RowActions_3<TItem> {
@@ -1634,13 +1741,11 @@ declare interface RowActions_3<TItem> {
     moveBottom: () => void;
     indent: () => void;
     outdent: () => void;
-    update: (data: TItem) => NestedTree<TItem>;
+    update: (data: TItem) => void;
 }
 
 declare interface RowSlotProps<TItem extends Record<string, any>> {
-    item: DecoratedViewItem<TItem> & {
-        validationState: ListEditorValidationState;
-    };
+    item: DecoratedViewItem<TItem>;
     raw: TItem;
     index: number;
     key: ListEditorKey;
@@ -1656,9 +1761,7 @@ declare interface RowSlotProps<TItem extends Record<string, any>> {
 }
 
 declare interface RowSlotProps_2<TItem extends Record<string, any>> {
-    item: DecoratedViewItem_2<TItem> & {
-        validationState: ListEditorValidationState;
-    };
+    item: DecoratedViewItem_2<TItem>;
     raw: TItem;
     index: number;
     key: ListEditorKey;
@@ -1742,13 +1845,7 @@ export declare interface SortableNestedItem<TData extends SortableItemWithParent
     };
 }
 
-/**
- * Returns a copy of the list ordered by ascending `position`. Use after
- * fetching/saving collections whose backend returns rows in storage order —
- * a shared, non-mutating alternative to scattered
- * `items.sort((a, b) => a.position - b.position)` calls (in-place `sort`
- * mutates the source and can trigger unintended reactivity).
- */
+/** Non-mutating sort by ascending `position` (in-place `sort` would trigger reactivity). */
 export declare const sortByPosition: <TItem extends {
     position: number;
 }>(items: TItem[]) => TItem[];
@@ -1939,6 +2036,45 @@ export declare function useJobApi<JobType extends JobBase = JobBase>(client: ()
  */
 export declare function useListEditor<TItem extends Record<string, any>>(model: Ref<TItem[]>, options?: UseListEditorOptions): ListEditorApi<TItem>;
 
+/**
+ * Component-owned state controller for the list editors (v2). Owns row keys,
+ * declared dirty tracking (no fragile whole-list JSON diff on volatile fields),
+ * validation summary, position renumbering, and the save lifecycle — exposed as
+ * a `ListEditorHandle`. Created internally by an editor (default) or lifted by a
+ * consumer via `useListEditor()` + `:editor` so the state survives unmount/remount.
+ */
+export declare function useListEditorController<TItem extends Record<string, any>>(options: UseListEditorControllerOptions<TItem>): ListEditorHandle<TItem>;
+
+export declare interface UseListEditorControllerOptions<TItem extends Record<string, any>> {
+    /** Read the live list (the editor's v-model, or a consumer store getter). */
+    get: () => TItem[];
+    /** Write the list back. */
+    set: (items: TItem[]) => void;
+    /** New-row factory. Optional for read-only / no-add lists. Should mint a stable temp id. */
+    factory?: () => TItem;
+    /** Stable row identity. Default `'id'`. Never point this at the position field. */
+    getKey?: GetKey<TItem>;
+    /** Managed order field. Default `'position'`. `false` opts out of position management. */
+    position?: PositionOption<TItem>;
+    /**
+     * Extra top-level fields to drop from the dirty content-hash (position is
+     * always dropped). For a child collection a separate nested editor already
+     * tracks, so editing a child doesn't flip the parent row amber. Still in the
+     * payload — only the dirty comparison ignores it. Reactive (accepts a getter/ref).
+     */
+    dirtyExclude?: MaybeRefOrGetter<string[]>;
+    /** Per-row validity — `true` = valid. Drives the red rail + `hasErrors`. */
+    validate?: (item: TItem) => ListEditorValidationResult;
+    /** Custom dirty predicate (override the default content-diff). */
+    isDirty?: (current: TItem, saved: TItem | undefined) => boolean;
+    /** Custom save payload (overrides `getPayload`). */
+    payload?: (items: TItem[]) => TItem[];
+    /** Resolve a saved row's key on commit (default: existing key, else mint a temp id). */
+    commitKey?: (saved: TItem, previous: TItem | undefined) => ListEditorKey;
+    /** Normalize server rows before they become the new baseline on commit. */
+    normalizeSaved?: (savedItems: TItem[]) => TItem[];
+}
+
 export declare function useListEditorItemValidation(options: UseListEditorItemValidationOptions): void;
 
 declare interface UseListEditorItemValidationOptions {
@@ -2006,8 +2142,50 @@ export declare function useListEditorVuelidateSentinel(v$: Ref<VuelidateSentinel
  */
 export declare function useNestedListEditor<TItem extends Record<string, any>>(model: Ref<NestedTree<TItem>>, options: UseNestedListEditorOptions): NestedListEditorApi<TItem>;
 
+export declare function useNestedListEditorController<TItem extends Record<string, any>>(options: UseNestedListEditorControllerOptions<TItem>): NestedListEditorHandle<TItem>;
+
+export declare interface UseNestedListEditorControllerOptions<TItem extends Record<string, any>> {
+    /** Read the live tree (the editor's v-model, or a consumer store getter). */
+    get: () => NestedTree<TItem>;
+    /** Write the tree back. */
+    set: (tree: NestedTree<TItem>) => void;
+    /** New-row factory. Optional for read-only / no-add trees. Should mint a stable temp id. */
+    factory?: () => TItem;
+    /** Stable row identity. Default `'id'`. Never point this at the position field. */
+    getKey?: GetKey<TItem>;
+    /** Managed order field. Default `'position'`. `false` opts out of position management. */
+    position?: PositionOption<TItem>;
+    /** Parent-key field written onto reparented rows. Default `'parent'`. */
+    parentField?: string;
+    /** Maximum nesting depth (1-based). Enforced by indent/outdent/moveTo. */
+    maxDepth: number;
+    /**
+     * Extra top-level fields to drop from the dirty content-hash (position +
+     * parent are always dropped). Same purpose as the flat controller — a child
+     * collection tracked by a separate editor shouldn't flip its owner amber.
+     * Accepts a getter/ref so a `computed` set is honoured reactively.
+     */
+    dirtyExclude?: MaybeRefOrGetter<string[]>;
+    /** Per-row validity — `true` = valid. Drives the red rail + `hasErrors`. */
+    validate?: (item: TItem) => ListEditorValidationResult;
+    /** Custom dirty predicate (override the default `meta.dirty ∪ content-diff`). */
+    isDirty?: (current: TItem, saved: TItem | undefined) => boolean;
+    /** Custom save payload (overrides `getPayload`). Receives the flattened ordered rows. */
+    payload?: (items: TItem[]) => TItem[];
+    /** Resolve a saved row's key on commit (default: existing key, else mint a temp id). */
+    commitKey?: (saved: TItem, previous: TItem | undefined) => ListEditorKey;
+    /** Normalize the server tree before it becomes the new baseline on commit. */
+    normalizeSaved?: (saved: NestedTree<TItem>) => NestedTree<TItem>;
+}
+
 declare interface UseNestedListEditorOptions {
     keyField?: string;
+    /**
+     * Resolve a row's key; takes precedence over `keyField`. Pass the controller's
+     * `keyOf` so tree ops key rows the same way as dirty/validity tracking — incl.
+     * a FUNCTION get-key, which `keyField` lookup would miss.
+     */
+    getKey?: (data: any) => ListEditorKey;
     positionField?: string;
     parentField?: string;
     positionMultiplier?: number;