@anzusystems/common-admin 1.49.0 → 2.0.0-rc.2

package/dist/domains/listEditor/composables/useListEditorController.d.ts

@@ -0,0 +1,124 @@
+import { ComputedRef, MaybeRefOrGetter, ShallowUnwrapRef } from 'vue';
+import { ListEditorKey, ListEditorValidationState, PositionHint } from '../types/listEditorTypes';
+/** Per-row validity. `true` (or `{ valid: true }`) = VALID. Only `valid: false` blocks save. */
+export type ListEditorValidationResult = boolean | {
+    valid: boolean;
+    state?: 'invalid' | 'warning';
+    message?: string;
+};
+export type GetKey<TItem> = keyof TItem | ((item: TItem) => ListEditorKey);
+/**
+ * How the managed order field is maintained.
+ * - `renumber` (default) — positions are opaque ordinals: every write rewrites them to a clean
+ *   `(index + 1) * multiplier` series.
+ * - `preserve-values` — positions are meaningful ABSOLUTE numbers (e.g. a CMS page interleaves its
+ *   rows with another collection on the same numeric scale, so rewriting 10/310 to 100/200 would
+ *   move unrelated items). A REORDER then only swaps rows through the EXISTING slots: the set of
+ *   values is kept and reassigned, ascending, to the new row order. It is a reorder policy, not a
+ *   normalization policy — `add` keeps the position the factory/consumer supplied, `delete` leaves
+ *   holes rather than compacting.
+ *
+ * Per-action exceptions go through `strategyOverrides` (e.g. base `preserve-values` +
+ * `{ remove: 'renumber' }` to keep absolute values on reorder/save but still close the gap on delete).
+ */
+export type PositionStrategy = 'renumber' | 'preserve-values';
+/** Which mutation is asking for positions to be (re)assigned. */
+export type PositionAction = 'add' | 'update' | 'remove' | 'move' | 'payload';
+export type PositionOption<TItem> = false | keyof TItem | {
+    field: keyof TItem;
+    multiplier?: number;
+    strategy?: PositionStrategy;
+    /**
+     * Per-action override of `strategy`. Each entry replaces the base strategy for that one
+     * action only; omitted actions inherit `strategy`. This is what lets a consumer mix policies
+     * without a bespoke preset — the behaviour is visible at the call site, one action per key.
+     */
+    strategyOverrides?: Partial<Record<PositionAction, PositionStrategy>>;
+};
+export interface ListEditorChanges<TItem> {
+    added: TItem[];
+    updated: TItem[];
+    moved: TItem[];
+    deleted: TItem[];
+    reparented: TItem[];
+}
+export 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 interface ListEditorHandle<TItem extends Record<string, any>> {
+    items: ComputedRef<TItem[]>;
+    hasUnsaved: ComputedRef<boolean>;
+    /** Count of distinct unconfirmed changes (added/edited/moved rows + deferred-deletion tombstones). */
+    unsavedCount: ComputedRef<number>;
+    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, editing?: boolean) => 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) => ListEditorKey | undefined;
+    updateItem: (key: ListEditorKey, next: TItem | Partial<TItem> | ((current: TItem) => TItem)) => void;
+    /** Remove a row. `trackDeleted: false` (immediate mode) skips the deferred-deletion tombstone. */
+    deleteItem: (key: ListEditorKey, opts?: {
+        trackDeleted?: boolean;
+    }) => void;
+    /** 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;
+}
+/**
+ * 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 type ExposedListEditorHandle<TItem extends Record<string, any>> = ShallowUnwrapRef<ListEditorHandle<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 by a consumer
+ * that passes it in as `:editor`, so the state survives unmount/remount.
+ */
+export declare function useListEditorController<TItem extends Record<string, any>>(options: UseListEditorControllerOptions<TItem>): ListEditorHandle<TItem>;

package/dist/domains/listEditor/composables/useListEditorController.js

@@ -0,0 +1,193 @@
+import { cloneDeep as e } from "../../../shared/utils/common.js";
+import { preservePositionValues as t, renumberPositions as n } from "../utils/positions.js";
+import { nextListEditorTempId as r } from "../utils/tempId.js";
+import { computed as i, reactive as a, ref as o, toValue as s, watch as c } from "vue";
+//#region src/domains/listEditor/composables/useListEditorController.ts
+function l(l) {
+	let u = typeof l.getKey == "function" ? null : l.getKey ?? "id", d = (e) => typeof l.getKey == "function" ? l.getKey(e) : e[u], f = l.position ?? "position", p = f !== !1, m = typeof f == "object" ? f.field : f === !1 ? "position" : f, h = typeof f == "object" && f.multiplier ? f.multiplier : 1, g = typeof f == "object" && f.strategy || "renumber", _ = typeof f == "object" && f.strategyOverrides || {}, v = i(() => l.get()), y = i(() => s(l.dirtyExclude) ?? []), b = (e, t) => e === "id" && typeof t == "number" && t < 0 ? void 0 : t, x = (e) => {
+		let t = { ...e };
+		p && delete t[m];
+		for (let e of y.value) delete t[e];
+		return JSON.stringify(t, b);
+	}, S = o(/* @__PURE__ */ new Map()), C = o([]), w = (t) => {
+		let n = /* @__PURE__ */ new Map();
+		for (let e of t) n.set(d(e), x(e));
+		S.value = n, C.value = t.map((t) => e(t));
+	};
+	c(y, () => {
+		let e = /* @__PURE__ */ new Map();
+		for (let t of C.value) e.set(d(t), x(t));
+		S.value = e;
+	}, { flush: "sync" });
+	let T = ((e) => {
+		if (!u) return {
+			rows: e,
+			changed: !1
+		};
+		let t = !1;
+		return {
+			rows: e.map((e) => d(e) == null ? (t = !0, {
+				...e,
+				[u]: r()
+			}) : e),
+			changed: t
+		};
+	})(l.get());
+	T.changed && l.set(T.rows), w(T.rows);
+	let E = o(/* @__PURE__ */ new Set()), D = o([]), O = o(!1), k = a(/* @__PURE__ */ new Map()), A = (e, t) => {
+		if (l.isDirty) {
+			let n = C.value.find((e) => d(e) === t);
+			return l.isDirty(e, n);
+		}
+		let n = S.value.get(t);
+		return n === void 0 || n !== x(e) || E.value.has(t);
+	}, j = o(/* @__PURE__ */ new Map()), M = o(/* @__PURE__ */ new Set());
+	c(v, (e) => {
+		let t = /* @__PURE__ */ new Set();
+		for (let n of e) {
+			let e = d(n);
+			if (t.add(e), !S.value.has(e) && !j.value.has(e) && j.value.set(e, x(n)), !M.value.has(e)) {
+				let t = S.value.get(e) ?? j.value.get(e);
+				t !== void 0 && t !== x(n) && M.value.add(e);
+			}
+		}
+		let n = [];
+		for (let e of j.value.keys()) t.has(e) || n.push(e);
+		for (let e of n) j.value.delete(e);
+		D.value.some((e) => t.has(d(e))) && (D.value = D.value.filter((e) => !t.has(d(e))));
+	}, {
+		immediate: !0,
+		deep: !0
+	});
+	let N = (e) => M.value.has(e), P = i(() => {
+		let e = /* @__PURE__ */ new Set();
+		for (let t of l.get()) {
+			let n = d(t);
+			A(t, n) && e.add(n);
+		}
+		return e;
+	}), F = (e) => P.value.has(e), I = i(() => P.value.size > 0 || D.value.length > 0), L = i(() => {
+		let e = new Set(P.value);
+		for (let t of D.value) e.add(d(t));
+		return e.size;
+	}), R = (e, t) => {
+		let n = k.get(t);
+		if (n) return {
+			invalid: !n(),
+			warning: !1
+		};
+		if (!l.validate) return {
+			invalid: !1,
+			warning: !1
+		};
+		let r = l.validate(e);
+		return typeof r == "boolean" ? {
+			invalid: !r,
+			warning: !1
+		} : {
+			invalid: !r.valid,
+			warning: r.valid && r.state === "warning"
+		};
+	}, z = i(() => {
+		let e = /* @__PURE__ */ new Set();
+		for (let t of l.get()) {
+			let n = d(t);
+			R(t, n).invalid && e.add(n);
+		}
+		return e;
+	}), B = i(() => z.value.size > 0), V = (e, t, n = !1) => {
+		let { invalid: r, warning: i } = R(e, t);
+		return r ? O.value ? "invalid" : n ? null : N(t) || F(t) ? "invalid" : null : i ? "warning" : null;
+	}, H = () => (O.value = !0, z.value.size === 0), U = (e, r) => p ? (_[r] ?? g) === "preserve-values" ? r === "move" ? t(e, { positionField: m }) : e : n(e, {
+		positionField: m,
+		positionMultiplier: h
+	}) : e, W = (e, t) => l.set(U(e, t)), G = () => l.payload ? l.payload(l.get()) : U(l.get(), "payload"), K = () => {
+		let e = [], t = [], n = [];
+		for (let r of l.get()) {
+			let i = d(r), a = S.value.get(i);
+			a === void 0 ? e.push(r) : a !== x(r) && t.push(r), E.value.has(i) && n.push(r);
+		}
+		return {
+			added: e,
+			updated: t,
+			moved: n,
+			deleted: [...D.value],
+			reparented: []
+		};
+	}, q = (e) => {
+		let t = e ?? l.get(), n = (l.normalizeSaved ? l.normalizeSaved(t) : t).map((e) => (l.commitKey ? l.commitKey(e, C.value.find((t) => d(t) === d(e))) : d(e)) == null && u ? {
+			...e,
+			[u]: r()
+		} : e);
+		l.set(n), w(n), E.value = /* @__PURE__ */ new Set(), D.value = [], j.value = /* @__PURE__ */ new Map(), M.value = /* @__PURE__ */ new Set(), O.value = !1;
+	}, J = (t) => {
+		l.set(t ?? C.value.map((t) => e(t))), E.value = /* @__PURE__ */ new Set(), D.value = [], j.value = /* @__PURE__ */ new Map(), M.value = /* @__PURE__ */ new Set(), O.value = !1;
+	}, Y = (e, t) => e.findIndex((e) => d(e) === t);
+	return {
+		items: v,
+		hasUnsaved: I,
+		unsavedCount: L,
+		hasErrors: B,
+		invalidKeys: z,
+		isUnsaved: F,
+		rowState: V,
+		validateAll: H,
+		getPayload: G,
+		getChanges: K,
+		commit: q,
+		reset: J,
+		addItem: (e, t) => {
+			let n = e ?? l.factory?.();
+			if (n === void 0) return;
+			let r = [...l.get()], i = r.length;
+			if (t?.afterId !== void 0) {
+				let e = Y(r, t.afterId);
+				i = e === -1 ? r.length : e + 1;
+			} else t?.index !== void 0 && (i = Math.max(0, Math.min(t.index, r.length)));
+			return r.splice(i, 0, n), W(r, "add"), d(n);
+		},
+		updateItem: (e, t) => {
+			let n = [...l.get()], r = Y(n, e);
+			if (r === -1) return;
+			let i = n[r];
+			n[r] = typeof t == "function" ? t(i) : {
+				...i,
+				...t
+			}, W(n, "update");
+		},
+		deleteItem: (e, t) => {
+			let n = [...l.get()], r = Y(n, e);
+			if (r === -1) return;
+			let i = n.splice(r, 1)[0];
+			if (S.value.has(e) && t?.trackDeleted !== !1) D.value = [...D.value, i];
+			else if (S.value.has(e)) {
+				let t = new Map(S.value);
+				t.delete(e), S.value = t, C.value = C.value.filter((t) => d(t) !== e);
+			}
+			E.value.delete(e), W(n, "remove");
+		},
+		restoreDeleted: (e) => {
+			D.value = D.value.filter((t) => d(t) !== e);
+		},
+		moveItem: (e, t) => {
+			let n = [...l.get()];
+			if (e < 0 || e >= n.length || t < 0 || t >= n.length || e === t) return;
+			let r = n.splice(e, 1)[0];
+			n.splice(t, 0, r), E.value.add(d(r)), W(n, "move");
+		},
+		clearMoved: (e) => {
+			if (e === void 0) {
+				E.value = /* @__PURE__ */ new Set();
+				return;
+			}
+			let t = new Set(E.value);
+			for (let n of e) t.delete(n);
+			E.value = t;
+		},
+		registerValidity: (e, t) => (k.set(e, t), () => k.delete(e))
+	};
+}
+//#endregion
+export { l as useListEditorController };
+
+//# sourceMappingURL=useListEditorController.js.map

package/dist/domains/listEditor/composables/useListEditorController.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useListEditorController.js","names":["useListEditorController","keyField","options","keyOf","item","positionOpt","managedPosition","positionField","positionMultiplier","positionStrategy","positionOverrides","items","computed","dirtyExclude","toValue","stripTempIds","_k","v","normalize","copy","f","baselineHashes","ref","baselineRows","captureBaseline","map","r","rows","cloneDeep","seeded","changed","nextListEditorTempId","movedKeys","deletedRows","submitted","registeredValidity","reactive","isItemDirty","saved","key","baseHash","addedBaseline","editedKeys","live","base","stale","isRowEdited","unsavedKeys","out","isUnsaved","hasUnsaved","unsavedCount","keys","resolveValidity","registered","invalidKeys","hasErrors","rowState","invalid","editing","warning","validateAll","renumber","action","preservePositionValues","arr","renumberPositions","write","getPayload","getChanges","added","updated","moved","commit","source","savedItems","next","reset","indexOfKey","x","row","at","hint","i","current","removed","opts","hashes","fromIndex","toIndex","el","isValid"],"sources":["../../../../src/domains/listEditor/composables/useListEditorController.ts"],"sourcesContent":["import {\n  computed,\n  reactive,\n  ref,\n  toValue,\n  watch,\n  type ComputedRef,\n  type MaybeRefOrGetter,\n  type Ref,\n  type ShallowUnwrapRef,\n} from 'vue'\nimport type { ListEditorKey, ListEditorValidationState, PositionHint } from '@/domains/listEditor/types/listEditorTypes'\nimport { preservePositionValues, renumberPositions } from '@/domains/listEditor/utils/positions'\nimport { nextListEditorTempId } from '@/domains/listEditor/utils/tempId'\nimport { cloneDeep } from '@/shared/utils/common'\n\n/** Per-row validity. `true` (or `{ valid: true }`) = VALID. Only `valid: false` blocks save. */\nexport type ListEditorValidationResult = boolean | { valid: boolean; state?: 'invalid' | 'warning'; message?: string }\n\nexport type GetKey<TItem> = keyof TItem | ((item: TItem) => ListEditorKey)\n/**\n * How the managed order field is maintained.\n * - `renumber` (default) — positions are opaque ordinals: every write rewrites them to a clean\n *   `(index + 1) * multiplier` series.\n * - `preserve-values` — positions are meaningful ABSOLUTE numbers (e.g. a CMS page interleaves its\n *   rows with another collection on the same numeric scale, so rewriting 10/310 to 100/200 would\n *   move unrelated items). A REORDER then only swaps rows through the EXISTING slots: the set of\n *   values is kept and reassigned, ascending, to the new row order. It is a reorder policy, not a\n *   normalization policy — `add` keeps the position the factory/consumer supplied, `delete` leaves\n *   holes rather than compacting.\n *\n * Per-action exceptions go through `strategyOverrides` (e.g. base `preserve-values` +\n * `{ remove: 'renumber' }` to keep absolute values on reorder/save but still close the gap on delete).\n */\nexport type PositionStrategy = 'renumber' | 'preserve-values'\n\n/** Which mutation is asking for positions to be (re)assigned. */\nexport type PositionAction = 'add' | 'update' | 'remove' | 'move' | 'payload'\n\nexport type PositionOption<TItem> =\n  | false\n  | keyof TItem\n  | {\n      field: keyof TItem\n      multiplier?: number\n      strategy?: PositionStrategy\n      /**\n       * Per-action override of `strategy`. Each entry replaces the base strategy for that one\n       * action only; omitted actions inherit `strategy`. This is what lets a consumer mix policies\n       * without a bespoke preset — the behaviour is visible at the call site, one action per key.\n       */\n      strategyOverrides?: Partial<Record<PositionAction, PositionStrategy>>\n    }\n\nexport interface ListEditorChanges<TItem> {\n  added: TItem[]\n  updated: TItem[]\n  moved: TItem[]\n  deleted: TItem[]\n  reparented: TItem[]\n}\n\nexport interface UseListEditorControllerOptions<TItem extends Record<string, any>> {\n  /** Read the live list (the editor's v-model, or a consumer store getter). */\n  get: () => TItem[]\n  /** Write the list back. */\n  set: (items: TItem[]) => void\n  /** New-row factory. Optional for read-only / no-add lists. Should mint a stable temp id. */\n  factory?: () => TItem\n  /** Stable row identity. Default `'id'`. Never point this at the position field. */\n  getKey?: GetKey<TItem>\n  /** Managed order field. Default `'position'`. `false` opts out of position management. */\n  position?: PositionOption<TItem>\n  /**\n   * Extra top-level fields to drop from the dirty content-hash (position is\n   * always dropped). For a child collection a separate nested editor already\n   * tracks, so editing a child doesn't flip the parent row amber. Still in the\n   * payload — only the dirty comparison ignores it. Reactive (accepts a getter/ref).\n   */\n  dirtyExclude?: MaybeRefOrGetter<string[]>\n  /** Per-row validity — `true` = valid. Drives the red rail + `hasErrors`. */\n  validate?: (item: TItem) => ListEditorValidationResult\n  /** Custom dirty predicate (override the default content-diff). */\n  isDirty?: (current: TItem, saved: TItem | undefined) => boolean\n  /** Custom save payload (overrides `getPayload`). */\n  payload?: (items: TItem[]) => TItem[]\n  /** Resolve a saved row's key on commit (default: existing key, else mint a temp id). */\n  commitKey?: (saved: TItem, previous: TItem | undefined) => ListEditorKey\n  /** Normalize server rows before they become the new baseline on commit. */\n  normalizeSaved?: (savedItems: TItem[]) => TItem[]\n}\n\nexport interface ListEditorHandle<TItem extends Record<string, any>> {\n  items: ComputedRef<TItem[]>\n  hasUnsaved: ComputedRef<boolean>\n  /** Count of distinct unconfirmed changes (added/edited/moved rows + deferred-deletion tombstones). */\n  unsavedCount: ComputedRef<number>\n  hasErrors: ComputedRef<boolean>\n  invalidKeys: ComputedRef<Set<ListEditorKey>>\n  /** Amber: is this row added / edited / moved since the last commit? */\n  isUnsaved: (key: ListEditorKey) => boolean\n  /** Red rail (gated): 'invalid' only once the row is unsaved or `validateAll()` ran. */\n  rowState: (item: TItem, key: ListEditorKey, editing?: boolean) => ListEditorValidationState\n  /** Force-show all invalid rows + return whether the list is valid. The save guard. */\n  validateAll: () => boolean\n  /** Normalized ordered array for a full-DTO save. */\n  getPayload: () => TItem[]\n  /** Change-set for partial-save endpoints. */\n  getChanges: () => ListEditorChanges<TItem>\n  /** Adopt saved rows as the new baseline; backfill keys; clear unsaved/submitted. */\n  commit: (savedItems?: TItem[]) => void\n  /** Discard unsaved edits back to the last committed baseline (or given items). */\n  reset: (items?: TItem[]) => void\n  addItem: (item?: TItem, hint?: PositionHint) => ListEditorKey | undefined\n  updateItem: (key: ListEditorKey, next: TItem | Partial<TItem> | ((current: TItem) => TItem)) => void\n  /** Remove a row. `trackDeleted: false` (immediate mode) skips the deferred-deletion tombstone. */\n  deleteItem: (key: ListEditorKey, opts?: { trackDeleted?: boolean }) => void\n  /** Clear a deferred-deletion tombstone (the caller re-inserts the row, e.g. reorder Cancel). */\n  restoreDeleted: (key: ListEditorKey) => void\n  moveItem: (fromIndex: number, toIndex: number) => void\n  /** Drop the \"moved\" flag for the given keys (or all) without touching edits/adds — e.g. reorder Cancel. */\n  clearMoved: (keys?: Iterable<ListEditorKey>) => void\n  /** Escape hatch: a row form (e.g. vuelidate) reports its own validity instead of `validate`. */\n  registerValidity: (key: ListEditorKey, isValid: () => boolean) => () => void\n}\n\n/**\n * The shape a CONSUMER sees when it reads a list-editor handle through a template/function ref.\n * Vue's `expose` proxy unwraps every exposed ref, so the reactive fields (`hasUnsaved`, `hasErrors`,\n * `unsavedCount`, …) arrive as plain VALUES here, not `Ref`s: read `handle.hasUnsaved` (a boolean),\n * never `handle.hasUnsaved.value` (that is `undefined`). Type your `useTemplateRef` / collected-ref\n * maps with this so a stray `.value` is a compile error instead of a silently-dead guard/save-gate.\n */\nexport type ExposedListEditorHandle<TItem extends Record<string, any>> = ShallowUnwrapRef<ListEditorHandle<TItem>>\n\n/**\n * Component-owned state controller for the list editors (v2). Owns row keys,\n * declared dirty tracking (no fragile whole-list JSON diff on volatile fields),\n * validation summary, position renumbering, and the save lifecycle — exposed as\n * a `ListEditorHandle`. Created internally by an editor (default) or by a consumer\n * that passes it in as `:editor`, so the state survives unmount/remount.\n */\nexport function useListEditorController<TItem extends Record<string, any>>(\n  options: UseListEditorControllerOptions<TItem>\n): ListEditorHandle<TItem> {\n  const keyField = (typeof options.getKey === 'function' ? null : (options.getKey ?? 'id')) as keyof TItem | null\n  const keyOf = (item: TItem): ListEditorKey =>\n    typeof options.getKey === 'function' ? options.getKey(item) : (item[keyField as keyof TItem] as ListEditorKey)\n\n  const positionOpt = options.position ?? 'position'\n  const managedPosition = positionOpt !== false\n  const positionField = (\n    typeof positionOpt === 'object' ? positionOpt.field : positionOpt === false ? 'position' : positionOpt\n  ) as string\n  const positionMultiplier = typeof positionOpt === 'object' && positionOpt.multiplier ? positionOpt.multiplier : 1\n  const positionStrategy: PositionStrategy = (typeof positionOpt === 'object' && positionOpt.strategy) || 'renumber'\n  const positionOverrides: Partial<Record<PositionAction, PositionStrategy>> =\n    (typeof positionOpt === 'object' && positionOpt.strategyOverrides) || {}\n\n  const items = computed<TItem[]>(() => options.get())\n\n  // Baseline = last committed snapshot. `hashes` powers content-diff dirty\n  // (position excluded so a reorder never marks a row dirty); `rows` powers `reset`.\n  const dirtyExclude = computed<string[]>(() => toValue(options.dirtyExclude) ?? [])\n  // Temp ids are client identity bookkeeping, never content. `ensureKeys` mints one INTO the model\n  // for rows the server returns without a key — and for a NESTED editor that write happens on mount,\n  // i.e. when a parent row is merely expanded to be read. The parent hashes the whole row, so without\n  // this the seed would retroactively invalidate the parent's baseline and expanding a row to LOOK at\n  // it would mark it unsaved (QA 85050 batch 10 BUG-02). Only negative NUMBERS are stripped —\n  // persisted ids are positive (see `nextListEditorTempId`), so real ids still count as content, and\n  // a genuinely added row still differs by its other fields.\n  const stripTempIds = (_k: string, v: unknown): unknown =>\n    _k === 'id' && typeof v === 'number' && v < 0 ? undefined : v\n  const normalize = (item: TItem): string => {\n    const copy = { ...item } as Record<string, unknown>\n    if (managedPosition) delete copy[positionField]\n    for (const f of dirtyExclude.value) delete copy[f]\n    return JSON.stringify(copy, stripTempIds)\n  }\n  const baselineHashes = ref(new Map<ListEditorKey, string>()) as Ref<Map<ListEditorKey, string>>\n  const baselineRows = ref<TItem[]>([]) as Ref<TItem[]>\n  const captureBaseline = (rows: TItem[]) => {\n    const map = new Map<ListEditorKey, string>()\n    for (const r of rows) map.set(keyOf(r), normalize(r))\n    baselineHashes.value = map\n    // Deep clone: a shallow `{...r}` shares nested refs with the live row, so an\n    // in-place mutation would drift the baseline (reset/re-hash read stale data).\n    baselineRows.value = rows.map((r) => cloneDeep(r))\n  }\n  // Re-hash when the excluded-field set changes. `sync` so baseline + live\n  // normalize() never disagree mid-flush (which would flash every row amber).\n  watch(\n    dirtyExclude,\n    () => {\n      const map = new Map<ListEditorKey, string>()\n      for (const r of baselineRows.value) map.set(keyOf(r), normalize(r))\n      baselineHashes.value = map\n    },\n    { flush: 'sync' }\n  )\n  // Ensure every row has a resolvable, UNIQUE key before the first baseline\n  // capture. Server rows lacking the key field (e.g. no `id` and no custom\n  // get-key → keyOf() is undefined for ALL of them) would collapse to a single\n  // baseline entry and read as perpetually unsaved even on a clean load\n  // (QA 85050 BUG-03). Mint a temp id for those rows — exactly what commit()\n  // already does on save (line ~299). Rows that DO resolve a key (the common\n  // case) are untouched, so id-backed editors are unaffected.\n  const ensureKeys = (rows: TItem[]): { rows: TItem[]; changed: boolean } => {\n    if (!keyField) return { rows, changed: false }\n    let changed = false\n    const next = rows.map((item) => {\n      const k = keyOf(item)\n      if (k === undefined || k === null) {\n        changed = true\n        return { ...item, [keyField]: nextListEditorTempId() } as TItem\n      }\n      return item\n    })\n    return { rows: next, changed }\n  }\n  const seeded = ensureKeys(options.get())\n  if (seeded.changed) options.set(seeded.rows)\n  // Capture from the seeded array directly (not a re-read of options.get()): when\n  // set() emits through v-model the prop update is async, so options.get() would\n  // still return the pre-mint colliding rows here. Mirrors commit()'s pattern.\n  captureBaseline(seeded.rows)\n\n  // Declared structural state the content-diff can't see.\n  const movedKeys = ref(new Set<ListEditorKey>()) as Ref<Set<ListEditorKey>>\n  const deletedRows = ref<TItem[]>([]) as Ref<TItem[]>\n  const submitted = ref(false)\n  // Reactive so a row form (re)registering its validity re-runs `invalidKeys`/`rowState`.\n  const registeredValidity = reactive(new Map<ListEditorKey, () => boolean>())\n\n  const isItemDirty = (item: TItem, key: ListEditorKey): boolean => {\n    if (options.isDirty) {\n      const saved = baselineRows.value.find((r) => keyOf(r) === key)\n      return options.isDirty(item, saved)\n    }\n    const baseHash = baselineHashes.value.get(key)\n    if (baseHash === undefined) return true // added\n    if (baseHash !== normalize(item)) return true // edited\n    return movedKeys.value.has(key) // moved (content-invisible)\n  }\n\n  // Gate the validation rail on \"has this row actually been edited\" rather than just \"is it\n  // unsaved\", so a freshly added still-untouched row is amber but not yet red. `addedBaseline` =\n  // first-seen content hash of each ADDED row; `editedKeys` = STICKY set of rows whose content has\n  // since diverged from that first-seen / committed baseline. Sticky like vuelidate `$dirty`: once\n  // edited a row stays dirty until commit/reset, so clearing a field back to empty keeps the rail\n  // consistent with the field's own error state. Position / `dirtyExclude` are normalized out, so a\n  // reorder never counts as an edit.\n  const addedBaseline = ref(new Map<ListEditorKey, string>()) as Ref<Map<ListEditorKey, string>>\n  const editedKeys = ref(new Set<ListEditorKey>()) as Ref<Set<ListEditorKey>>\n  watch(\n    items,\n    (rows) => {\n      const live = new Set<ListEditorKey>()\n      for (const r of rows) {\n        const key = keyOf(r)\n        live.add(key)\n        if (!baselineHashes.value.has(key) && !addedBaseline.value.has(key)) {\n          addedBaseline.value.set(key, normalize(r))\n        }\n        if (!editedKeys.value.has(key)) {\n          const base = baselineHashes.value.get(key) ?? addedBaseline.value.get(key)\n          if (base !== undefined && base !== normalize(r)) editedKeys.value.add(key)\n        }\n      }\n      const stale: ListEditorKey[] = []\n      for (const key of addedBaseline.value.keys()) if (!live.has(key)) stale.push(key)\n      for (const key of stale) addedBaseline.value.delete(key)\n      // A deferred-deleted key that becomes live again (re-add before save) must drop its tombstone —\n      // otherwise it would both render and still count/report as deleted.\n      if (deletedRows.value.some((r) => live.has(keyOf(r)))) {\n        deletedRows.value = deletedRows.value.filter((r) => !live.has(keyOf(r)))\n      }\n    },\n    { immediate: true, deep: true }\n  )\n\n  const isRowEdited = (key: ListEditorKey): boolean => editedKeys.value.has(key)\n\n  const unsavedKeys = computed<Set<ListEditorKey>>(() => {\n    const out = new Set<ListEditorKey>()\n    for (const item of options.get()) {\n      const key = keyOf(item)\n      if (isItemDirty(item, key)) out.add(key)\n    }\n    return out\n  })\n\n  const isUnsaved = (key: ListEditorKey): boolean => unsavedKeys.value.has(key)\n  const hasUnsaved = computed<boolean>(() => unsavedKeys.value.size > 0 || deletedRows.value.length > 0)\n\n  // Count of DISTINCT unconfirmed changes = union of live dirty keys (added / edited / moved) and\n  // deferred-deletion tombstones. A key that is both live and tombstoned (delete-then-re-add) counts\n  // once; a deleted row (no longer live) adds one. Drives the \"N unconfirmed changes\" indicator, so a\n  // delete lights up as a change even though the row itself is gone.\n  const unsavedCount = computed<number>(() => {\n    const keys = new Set<ListEditorKey>(unsavedKeys.value)\n    for (const r of deletedRows.value) keys.add(keyOf(r))\n    return keys.size\n  })\n\n  const resolveValidity = (item: TItem, key: ListEditorKey): { invalid: boolean; warning: boolean } => {\n    const registered = registeredValidity.get(key)\n    if (registered) return { invalid: !registered(), warning: false }\n    if (!options.validate) return { invalid: false, warning: false }\n    const r = options.validate(item)\n    if (typeof r === 'boolean') return { invalid: !r, warning: false }\n    return { invalid: !r.valid, warning: r.valid && r.state === 'warning' }\n  }\n\n  const invalidKeys = computed<Set<ListEditorKey>>(() => {\n    const out = new Set<ListEditorKey>()\n    for (const item of options.get()) {\n      const key = keyOf(item)\n      if (resolveValidity(item, key).invalid) out.add(key)\n    }\n    return out\n  })\n  const hasErrors = computed<boolean>(() => invalidKeys.value.size > 0)\n\n  // Red rail gated behind \"row has been edited\" (content changed since add/baseline — mirrors the\n  // field's vuelidate `$dirty`) or an explicit validateAll() — so a freshly added still-untouched\n  // row stays amber (not red) and a loaded-but-invalid row doesn't light up before interaction,\n  // while a save attempt reveals every offender (mounted or collapsed).\n  const rowState = (item: TItem, key: ListEditorKey, editing = false): ListEditorValidationState => {\n    const { invalid, warning } = resolveValidity(item, key)\n    // Red rail for an invalid row that is edited, unsaved (added), or after a save attempt. A row being\n    // filled in reads amber (not red) and goes red once collapsed — but a save attempt (`submitted`,\n    // which also reveals collapsed offenders) always reds it, even while open. (QA 85050 batch 7)\n    if (invalid) {\n      if (submitted.value) return 'invalid'\n      if (editing) return null\n      return isRowEdited(key) || isUnsaved(key) ? 'invalid' : null\n    }\n    if (warning) return 'warning'\n    return null\n  }\n\n  const validateAll = (): boolean => {\n    submitted.value = true\n    return invalidKeys.value.size === 0\n  }\n\n  // Resolve the policy for THIS action: a per-action override wins, else the base strategy.\n  // Under 'preserve-values' only a move reassigns (through the existing kept slots); every other\n  // action leaves positions as-is (add keeps the handed value, delete leaves a hole, update/payload\n  // never touch them). Under 'renumber' every action rewrites to a clean `(index+1)*multiplier`.\n  const renumber = (arr: TItem[], action: PositionAction): TItem[] => {\n    if (!managedPosition) return arr\n    const strategy = positionOverrides[action] ?? positionStrategy\n    if (strategy === 'preserve-values') {\n      return action === 'move' ? preservePositionValues(arr, { positionField }) : arr\n    }\n    return renumberPositions(arr, { positionField, positionMultiplier })\n  }\n\n  const write = (arr: TItem[], action: PositionAction) => options.set(renumber(arr, action))\n\n  const getPayload = (): TItem[] =>\n    options.payload ? options.payload(options.get()) : renumber(options.get(), 'payload')\n\n  const getChanges = (): ListEditorChanges<TItem> => {\n    const added: TItem[] = []\n    const updated: TItem[] = []\n    const moved: TItem[] = []\n    for (const item of options.get()) {\n      const key = keyOf(item)\n      const baseHash = baselineHashes.value.get(key)\n      if (baseHash === undefined) added.push(item)\n      else if (baseHash !== normalize(item)) updated.push(item)\n      if (movedKeys.value.has(key)) moved.push(item)\n    }\n    return { added, updated, moved, deleted: [...deletedRows.value], reparented: [] }\n  }\n\n  const commit = (savedItems?: TItem[]): void => {\n    const source = savedItems ?? options.get()\n    const normalized = options.normalizeSaved ? options.normalizeSaved(source) : source\n    const next = normalized.map((item) => {\n      const key = options.commitKey\n        ? options.commitKey(\n            item,\n            baselineRows.value.find((r) => keyOf(r) === keyOf(item))\n          )\n        : keyOf(item)\n      if (key === undefined || key === null) {\n        return keyField ? ({ ...item, [keyField]: nextListEditorTempId() } as TItem) : item\n      }\n      return item\n    })\n    options.set(next)\n    captureBaseline(next)\n    movedKeys.value = new Set()\n    deletedRows.value = []\n    addedBaseline.value = new Map()\n    editedKeys.value = new Set()\n    submitted.value = false\n  }\n\n  const reset = (rows?: TItem[]): void => {\n    options.set(rows ?? baselineRows.value.map((r) => cloneDeep(r)))\n    movedKeys.value = new Set()\n    deletedRows.value = []\n    addedBaseline.value = new Map()\n    editedKeys.value = new Set()\n    submitted.value = false\n  }\n\n  const indexOfKey = (arr: TItem[], key: ListEditorKey): number => arr.findIndex((x) => keyOf(x) === key)\n\n  const addItem = (item?: TItem, hint?: PositionHint): ListEditorKey | undefined => {\n    const row = item ?? options.factory?.()\n    if (row === undefined) return undefined // no item + no factory (read-only list) → no-op\n    const arr = [...options.get()]\n    let at = arr.length\n    if (hint?.afterId !== undefined) {\n      const i = indexOfKey(arr, hint.afterId)\n      at = i === -1 ? arr.length : i + 1\n    } else if (hint?.index !== undefined) {\n      at = Math.max(0, Math.min(hint.index, arr.length))\n    }\n    arr.splice(at, 0, row)\n    write(arr, 'add')\n    return keyOf(row)\n  }\n\n  const updateItem = (key: ListEditorKey, next: TItem | Partial<TItem> | ((current: TItem) => TItem)): void => {\n    const arr = [...options.get()]\n    const i = indexOfKey(arr, key)\n    if (i === -1) return\n    const current = arr[i]!\n    const resolved =\n      typeof next === 'function'\n        ? (next as (c: TItem) => TItem)(current)\n        : ({ ...current, ...(next as Partial<TItem>) } as TItem)\n    arr[i] = resolved\n    write(arr, 'update')\n  }\n\n  const deleteItem = (key: ListEditorKey, opts?: { trackDeleted?: boolean }): void => {\n    const arr = [...options.get()]\n    const i = indexOfKey(arr, key)\n    if (i === -1) return\n    const removed = arr.splice(i, 1)[0]!\n    // A previously-saved row that's removed is a DEFERRED deletion: reported in the change-set and\n    // counted as one unconfirmed change (`unsavedCount`) until save. `trackDeleted: false` (immediate\n    // mode — the row is already deleted on the backend) skips the tombstone so it does NOT read as\n    // unsaved. An unsaved temp row just vanishes either way.\n    if (baselineHashes.value.has(key) && opts?.trackDeleted !== false) {\n      deletedRows.value = [...deletedRows.value, removed]\n    } else if (baselineHashes.value.has(key)) {\n      // Deleted on the backend: no longer part of the saved rows `reset()` returns to.\n      const hashes = new Map(baselineHashes.value)\n      hashes.delete(key)\n      baselineHashes.value = hashes\n      baselineRows.value = baselineRows.value.filter((r) => keyOf(r) !== key)\n    }\n    movedKeys.value.delete(key)\n    write(arr, 'remove')\n  }\n\n  // Un-tombstone a deferred-deleted row. Re-inserting the row into the model is the caller's job\n  // (e.g. reorder Cancel restoring the pre-session snapshot); this only clears the deletion record so\n  // `deletedRows` / `unsavedCount` / `getChanges().deleted` stay consistent.\n  const restoreDeleted = (key: ListEditorKey): void => {\n    deletedRows.value = deletedRows.value.filter((r) => keyOf(r) !== key)\n  }\n\n  const moveItem = (fromIndex: number, toIndex: number): void => {\n    const arr = [...options.get()]\n    if (fromIndex < 0 || fromIndex >= arr.length || toIndex < 0 || toIndex >= arr.length) return\n    if (fromIndex === toIndex) return\n    const el = arr.splice(fromIndex, 1)[0]!\n    arr.splice(toIndex, 0, el)\n    movedKeys.value.add(keyOf(el))\n    write(arr, 'move')\n  }\n\n  // Reorder Cancel restores the pre-session order, so the moves are undone — drop\n  // just those keys' \"moved\" flag (edits/adds stay dirty). No arg = clear all.\n  const clearMoved = (keys?: Iterable<ListEditorKey>): void => {\n    if (keys === undefined) {\n      movedKeys.value = new Set()\n      return\n    }\n    const next = new Set(movedKeys.value)\n    for (const key of keys) next.delete(key)\n    movedKeys.value = next\n  }\n\n  const registerValidity = (key: ListEditorKey, isValid: () => boolean): (() => void) => {\n    registeredValidity.set(key, isValid)\n    return () => registeredValidity.delete(key)\n  }\n\n  return {\n    items,\n    hasUnsaved,\n    unsavedCount,\n    hasErrors,\n    invalidKeys,\n    isUnsaved,\n    rowState,\n    validateAll,\n    getPayload,\n    getChanges,\n    commit,\n    reset,\n    addItem,\n    updateItem,\n    deleteItem,\n    restoreDeleted,\n    moveItem,\n    clearMoved,\n    registerValidity,\n  }\n}\n"],"mappings":"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"}

package/dist/domains/listEditor/composables/useListEditorScopeValidity.d.ts

@@ -0,0 +1,39 @@
+import { ComputedRef } from 'vue';
+import { ListEditorValidationScope } from '../types/listEditorTypes';
+export interface UseListEditorScopeValidityOptions {
+    /**
+     * The editor's aggregate validity — the controller's `hasErrors`, a computed over ALL raw rows
+     * via the `:validate` predicate (so it reflects collapsed/unmounted rows too).
+     */
+    hasErrors: ComputedRef<boolean>;
+    /**
+     * The consumer's vuelidate `$scope`. `undefined` = not wired (no-op, legacy behavior);
+     * `false` = explicit opt-out (the save flow calls the editor `validateAll()` itself).
+     */
+    validationScope: ListEditorValidationScope | false | undefined;
+    /**
+     * Reveal every invalid row (open it + show the red rail) — pass the editor's own
+     * `validateAllAndReveal` routine so nested editors also expand ancestors.
+     */
+    reveal: () => void;
+    /**
+     * Whether the editor got a `:validate` predicate. `hasErrors` is driven solely by it
+     * (row-form vuelidate feeds a separate display registry, not `hasErrors`), so a scope
+     * wired WITHOUT `:validate` yields `hasErrors === false` forever — a silently-dead gate.
+     * Passed so this composable can warn (dev) instead of failing open.
+     */
+    validateProvided: boolean;
+}
+/**
+ * Bridges the editor's aggregate row validity into the consumer's vuelidate scope collector, so a
+ * plain `v$.value.$touch(); if (v$.value.$invalid) return` save gate BLOCKS (and reveals) even a
+ * COLLAPSED invalid row — whose own row-form vuelidate has unmounted and deregistered.
+ *
+ * The editor is always mounted and `hasErrors` scans all raw rows, so the collector sees rows
+ * regardless of expand state. `$invalid` reflects validity immediately (no touch needed → the save
+ * blocks synchronously); the `$dirty` watch mirrors the collector's `$touch()` to open the offenders.
+ *
+ * Opt-in: a no-op unless `validationScope` is a real scope, so an editor without the prop behaves
+ * exactly as before.
+ */
+export declare function useListEditorScopeValidity(options: UseListEditorScopeValidityOptions): void;

package/dist/domains/listEditor/composables/useListEditorScopeValidity.js

@@ -0,0 +1,16 @@
+import { watch as e } from "vue";
+import t from "@vuelidate/core";
+//#region src/domains/listEditor/composables/useListEditorScopeValidity.ts
+function n(n) {
+	let { hasErrors: r, validationScope: i, reveal: a, validateProvided: o } = n;
+	if (i === void 0 || i === !1) return;
+	i === !0 && console.warn("[list-editor] `:validation-scope=\"true\"` uses vuelidate’s GLOBAL scope. If your save gate collects a NAMED scope (useVuelidate({ $scope: someSymbol })), this editor’s validity is NOT collected by it and the gate won’t block. Pass the SAME scope value your collector uses."), o || console.warn("[list-editor] `:validation-scope` is set but `:validate` is missing. The scope save-gate bridges the editor’s aggregate `hasErrors`, which is driven only by `:validate`; without it the gate never blocks (hasErrors stays false). Pass `:validate` so collapsed/invalid rows block the consumer save, or drop `:validation-scope` if you gate validity yourself.");
+	let s = t({ listEditor: { valid: () => !r.value } }, { listEditor: r }, { $scope: i });
+	e(() => s.value.$dirty, (e) => {
+		e && r.value && a();
+	});
+}
+//#endregion
+export { n as useListEditorScopeValidity };
+
+//# sourceMappingURL=useListEditorScopeValidity.js.map

package/dist/domains/listEditor/composables/useListEditorScopeValidity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useListEditorScopeValidity.js","names":["useVuelidate","useListEditorScopeValidity","options","validationScope","validateProvided","v$","hasErrors","dirty","reveal"],"sources":["../../../../src/domains/listEditor/composables/useListEditorScopeValidity.ts"],"sourcesContent":["import { watch, type ComputedRef } from 'vue'\nimport useVuelidate from '@vuelidate/core'\nimport type { ListEditorValidationScope } from '@/domains/listEditor/types/listEditorTypes'\n\nexport interface UseListEditorScopeValidityOptions {\n  /**\n   * The editor's aggregate validity — the controller's `hasErrors`, a computed over ALL raw rows\n   * via the `:validate` predicate (so it reflects collapsed/unmounted rows too).\n   */\n  hasErrors: ComputedRef<boolean>\n  /**\n   * The consumer's vuelidate `$scope`. `undefined` = not wired (no-op, legacy behavior);\n   * `false` = explicit opt-out (the save flow calls the editor `validateAll()` itself).\n   */\n  validationScope: ListEditorValidationScope | false | undefined\n  /**\n   * Reveal every invalid row (open it + show the red rail) — pass the editor's own\n   * `validateAllAndReveal` routine so nested editors also expand ancestors.\n   */\n  reveal: () => void\n  /**\n   * Whether the editor got a `:validate` predicate. `hasErrors` is driven solely by it\n   * (row-form vuelidate feeds a separate display registry, not `hasErrors`), so a scope\n   * wired WITHOUT `:validate` yields `hasErrors === false` forever — a silently-dead gate.\n   * Passed so this composable can warn (dev) instead of failing open.\n   */\n  validateProvided: boolean\n}\n\n/**\n * Bridges the editor's aggregate row validity into the consumer's vuelidate scope collector, so a\n * plain `v$.value.$touch(); if (v$.value.$invalid) return` save gate BLOCKS (and reveals) even a\n * COLLAPSED invalid row — whose own row-form vuelidate has unmounted and deregistered.\n *\n * The editor is always mounted and `hasErrors` scans all raw rows, so the collector sees rows\n * regardless of expand state. `$invalid` reflects validity immediately (no touch needed → the save\n * blocks synchronously); the `$dirty` watch mirrors the collector's `$touch()` to open the offenders.\n *\n * Opt-in: a no-op unless `validationScope` is a real scope, so an editor without the prop behaves\n * exactly as before.\n */\nexport function useListEditorScopeValidity(options: UseListEditorScopeValidityOptions): void {\n  const { hasErrors, validationScope, reveal, validateProvided } = options\n  if (validationScope === undefined || validationScope === false) return\n\n  // `true` = vuelidate's GLOBAL scope. A globally-scoped child is NOT collected by a parent that\n  // uses a NAMED ($scope: Symbol) collector — so under the typical named save gate the bridge is\n  // silently dropped. Warn: the consumer almost always wants their collector's exact scope value.\n  if (validationScope === true) {\n    console.warn(\n      '[list-editor] `:validation-scope=\"true\"` uses vuelidate’s GLOBAL scope. If your save gate ' +\n        'collects a NAMED scope (useVuelidate({ $scope: someSymbol })), this editor’s validity is ' +\n        'NOT collected by it and the gate won’t block. Pass the SAME scope value your collector uses.'\n    )\n  }\n\n  // A scope with no `:validate` bridges an always-false `hasErrors` — the gate never blocks. Warn\n  // (dev) so the misconfiguration is visible instead of silently letting invalid rows through save.\n  if (!validateProvided) {\n    console.warn(\n      '[list-editor] `:validation-scope` is set but `:validate` is missing. The scope save-gate ' +\n        'bridges the editor’s aggregate `hasErrors`, which is driven only by `:validate`; without ' +\n        'it the gate never blocks (hasErrors stays false). Pass `:validate` so collapsed/invalid ' +\n        'rows block the consumer save, or drop `:validation-scope` if you gate validity yourself.'\n    )\n  }\n\n  // One editor-level child registered under the consumer's scope. The validator reads `hasErrors`\n  // reactively (vuelidate's sync `$invalid` is a computed that runs it), so the collector's\n  // `$invalid` tracks it. State is `hasErrors` only to give the field a (reactive) value.\n  const v$ = useVuelidate(\n    { listEditor: { valid: () => !hasErrors.value } },\n    { listEditor: hasErrors },\n    { $scope: validationScope }\n  )\n\n  // On save the consumer's collector `$touch()` propagates to this child (`$dirty` → true); mirror\n  // the editor's `validateAll()` reveal so the blocked save opens WHICH rows are wrong.\n  watch(\n    () => v$.value.$dirty,\n    (dirty) => {\n      if (dirty && hasErrors.value) reveal()\n    }\n  )\n}\n"],"mappings":";;;AAyCA,SAAgBC,EAA2B,GAAkD;CAC3F,IAAM,EAAE,cAAW,oBAAiB,WAAQ,wBAAqBC;CACjE,IAAIC,MAAoB,KAAA,KAAaA,MAAoB,IAAO;CAehE,AAVIA,MAAoB,MACtB,QAAQ,KACN,mRAGF,GAKGC,KACH,QAAQ,KACN,oWAIF;CAMF,IAAMC,IAAKL,EACT,EAAE,YAAY,EAAE,aAAa,CAACM,EAAU,MAAM,EAAE,GAChD,EAAE,YAAYA,EAAU,GACxB,EAAE,QAAQH,EAAgB,CAC5B;CAIA,QACQE,EAAG,MAAM,SACd,MAAU;EACT,AAAIE,KAASD,EAAU,SAAOE,EAAO;CACvC,CACF;AACF"}

package/dist/domains/listEditor/composables/useListEditorStateScope.d.ts

@@ -0,0 +1,81 @@
+import { InjectionKey, ShallowRef } from 'vue';
+import { ListEditorKey } from '../types/listEditorTypes';
+import { ListEditorHandle, UseListEditorControllerOptions } from './useListEditorController';
+import { NestedListEditorHandle, UseNestedListEditorControllerOptions } from './useNestedListEditorController';
+/**
+ * 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 type ListEditorStateBindings<TItem extends Record<string, any>> = Pick<UseListEditorControllerOptions<TItem>, 'get' | 'set' | 'factory' | 'getKey' | 'position' | 'dirtyExclude' | 'validate'>;
+export type NestedListEditorStateBindings<TItem extends Record<string, any>> = Pick<UseNestedListEditorControllerOptions<TItem>, 'get' | 'set' | 'factory' | 'getKey' | 'position' | 'parentField' | 'maxDepth' | 'dirtyExclude' | 'validate'>;
+/** What a `state-key`'d editor gets back: its persisted handle + the scope to hand to ITS own rows. */
+export 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 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>;
+/**
+ * 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;
+/**
+ * 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;
+/**
+ * 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;
+/** 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;