@antelopejs/dms 0.11.1 → 0.12.1

package/frontend-vue/layers/dms-ui/app/build/composables/form/useFormModel.ts

@@ -0,0 +1,431 @@
+import { z } from "zod";
+import { onMounted, unref } from "vue";
+import { jsonSchemaToZod } from "json-schema-to-zod";
+import type { FormProps } from "../../../composables/form/types";
+import { FormEvents } from "../../../composables/form/types/events";
+import type {
+  FormData,
+  FormFieldValue,
+} from "../../../composables/form/types/value";
+import type {
+  FieldCondition,
+  FormField,
+  FormFieldOrGroup,
+} from "../../../composables/form/types/field";
+import { isFieldGroup } from "../../../composables/form/types/field";
+import type {
+  DataType,
+  DataTypeValueComparer,
+} from "#dms-core/app/composables/data-types/useDataType";
+import type { useWatch } from "#dms-core/app/composables/watch/useWatch";
+import type { useComponentEvent } from "#dms-core/app/composables/components/useComponentEvent";
+import { resolveFieldErrors } from "#dms-core/app/composables/useFieldErrors";
+import { isBlankValue } from "#dms-core/app/composables/useFormValidation";
+import { isObject, isString } from "#dms-core/app/utils/type-check";
+import { isPlainObject, sameFormValue } from "../unsaved-changes/formValue";
+import { createStartingValueTracker } from "./fieldValueRule";
+import {
+  type ReplaceUrlVariablesContext,
+  hasUrlVariables,
+  resolveTextVariables,
+  resolveUrlVariables,
+} from "../../utils/urlVariables";
+
+type FormState = ReturnType<typeof useWatch>["state"]["value"];
+type ResetStateValues = Record<string, FormFieldValue | undefined>;
+
+const INTERNAL_STATE_KEYS = new Set([
+  "disabledFields",
+  "hiddenFields",
+  "requiredFields",
+]);
+
+export function cloneFormValue(
+  value: FormFieldValue | undefined,
+): FormFieldValue | undefined {
+  if (value === undefined) return undefined;
+  return JSON.parse(JSON.stringify(value));
+}
+
+/** Whether a form has somewhere to save and an editable field, or is an action. */
+export function formShowsActions(
+  options: Pick<FormProps, "saveMode" | "submitUrl" | "kind">,
+  fields: ReadonlyArray<{ disabled?: boolean }>,
+): boolean {
+  return (
+    options.saveMode !== "none" &&
+    !!options.submitUrl &&
+    (options.kind === "action" || !fields.every((field) => field.disabled))
+  );
+}
+
+export function computeResetState(state: FormState, initialValues: FormData) {
+  const result: ResetStateValues = {};
+  for (const key of Object.keys(state)) {
+    if (INTERNAL_STATE_KEYS.has(key)) continue;
+    result[key] = cloneFormValue(initialValues[key]);
+  }
+  return result;
+}
+
+export function snapshotFormState(state: FormState): FormData {
+  // oxlint-disable-next-line anti-slop/require-safety-comment-for-type-assertion -- Watch state is deliberately open to plugin values and undefined entries. Snapshotting clones them without validation, preserving the existing FormData API.
+  return computeResetState(state, state as FormData) as FormData;
+}
+
+export function flattenFields(items: FormFieldOrGroup[]): FormField[] {
+  const result: FormField[] = [];
+  for (const item of items) {
+    if (isFieldGroup(item)) result.push(...item.fields);
+    else result.push(item);
+  }
+  return result;
+}
+
+export function createBaseValidationSchema(
+  schema: FormProps["schema"],
+): z.ZodObject<Record<string, z.ZodTypeAny>> {
+  if (!schema) return z.object({});
+  try {
+    const zodCode = jsonSchemaToZod(schema, { module: "none" }).replace(
+      /\.strict\(\)$/,
+      ".passthrough()",
+    );
+    return new Function("z", `"use strict"; return (${zodCode})`)(z);
+  } catch {
+    return z.object({});
+  }
+}
+
+/** Where a submit goes, or what it lacks to go anywhere. */
+export type SubmitTarget = { url: string } | { missing: "url" | "token" };
+
+/** Resolves a submit URL without sending unresolved route tokens. */
+export function resolveSubmitTarget(
+  submitUrl: string | undefined,
+  context: ReplaceUrlVariablesContext,
+): SubmitTarget {
+  if (!submitUrl) return { missing: "url" };
+  const url = resolveUrlVariables(submitUrl, context);
+  return url === undefined ? { missing: "token" } : { url };
+}
+
+export function processBeforeStateMappers(
+  data: FormData,
+  fields: FormFieldOrGroup[],
+  getDataType: (type: string) => DataType | undefined,
+): FormData {
+  const result = { ...data };
+  const flatFields = flattenFields(fields);
+  for (const field of flatFields) {
+    if (!field.type || result[field.id] === undefined) continue;
+    const dataType = getDataType(field.type);
+    if (!dataType?.beforeStateMapper) continue;
+    // oxlint-disable-next-line anti-slop/require-safety-comment-for-type-assertion -- Plugin mappers return arbitrary values. Preserve them unchanged rather than imposing FormFieldValue validation at this existing unchecked boundary.
+    result[field.id] = dataType.beforeStateMapper(
+      result[field.id],
+      field.component.options,
+    ) as FormFieldValue;
+  }
+  return result;
+}
+
+/** A cleared list submits an empty list; other cleared fields submit null. */
+export function clearedFieldValue(
+  initial: Parameters<typeof isBlankValue>[0],
+): FormFieldValue {
+  return Array.isArray(initial) ? [] : null;
+}
+
+/** Blank controls are cleared, but arrays and non-Date instances are not. */
+export function isClearedFieldValue(
+  value: Parameters<typeof isBlankValue>[0],
+  type?: string,
+): boolean {
+  if (Array.isArray(value)) return false;
+  const isInstance =
+    isObject(value) &&
+    value !== null &&
+    !(value instanceof Date) &&
+    !isPlainObject(value);
+  return !isInstance && isBlankValue(value, type);
+}
+
+/** Normalizes blank languages while passing through non-localized values. */
+export function localizedSubmitValue(
+  value: Parameters<typeof isBlankValue>[0],
+  type?: string,
+) {
+  if (!isPlainObject(value)) return value;
+  return Object.fromEntries(
+    Object.entries(value).map(([locale, text]) => [
+      locale,
+      isString(text) && isBlankValue(text, type) ? "" : text,
+    ]),
+  );
+}
+
+function isClearedField(
+  field: SubmitField,
+  value: Parameters<typeof isBlankValue>[0],
+): boolean {
+  if (field.localized) return value === undefined;
+  return isClearedFieldValue(value, field.type);
+}
+
+function submittedFieldValue(
+  field: SubmitField,
+  value: Parameters<typeof localizedSubmitValue>[0],
+) {
+  return field.localized ? localizedSubmitValue(value, field.type) : value;
+}
+
+/** A field as collectSubmitData reads it. */
+export type SubmitField = Pick<
+  FormField,
+  "id" | "type" | "disabled" | "localized"
+> &
+  Partial<Pick<FormField, "component">>;
+
+/** Compares field values under the data-type plugin's open value contract. */
+export type FieldValueComparer = (
+  field: SubmitField,
+  left: Parameters<DataTypeValueComparer>[0],
+  right: Parameters<DataTypeValueComparer>[1],
+) => boolean;
+
+/** Uses the field's data-type comparator or a deep value comparison. */
+export function createFieldValueComparer(
+  getDataType: (type: string) => DataType | undefined,
+): FieldValueComparer {
+  return (field, left, right) => {
+    const compare = field.type
+      ? getDataType(field.type)?.isSameValue
+      : undefined;
+    return compare
+      ? compare(left, right, field.component?.options)
+      : sameFormValue(left, right);
+  };
+}
+
+const defaultFieldValueComparer: FieldValueComparer = (_field, left, right) =>
+  sameFormValue(left, right);
+
+/** The form context for collecting a submit body. */
+export interface SubmitDataContext {
+  /** Loaded values, last saved values, or field defaults. */
+  initialValues?: FormState;
+  /** Values submitted even when they have no rendered field. */
+  submitDefaults?: FormProps["submitDefaults"];
+  /** Fields disabled by watch actions. */
+  disabled?: Set<string>;
+  /** Leaves unchanged fields out of a record update. */
+  onlyChanged?: boolean;
+  /** The field's comparator, or deep comparison by default. */
+  isSameValue?: FieldValueComparer;
+}
+
+/** Collects populated fields and explicit clears, omitting untouched empty fields. */
+export function collectSubmitData(
+  data: FormState,
+  fields: ReadonlyArray<SubmitField>,
+  context: SubmitDataContext = {},
+): FormData {
+  const fieldData: FormData = {};
+  const isSameValue = context.isSameValue ?? defaultFieldValueComparer;
+  for (const field of fields) {
+    const value = unref(data[field.id]);
+    const initial = context.initialValues?.[field.id];
+    if (context.onlyChanged && isSameValue(field, value, initial)) continue;
+    if (!isClearedField(field, value)) {
+      // oxlint-disable-next-line anti-slop/require-safety-comment-for-type-assertion -- Submission intentionally passes arbitrary populated plugin values through; validating against FormFieldValue would change accepted payloads.
+      fieldData[field.id] = submittedFieldValue(field, value) as FormFieldValue;
+      continue;
+    }
+    if (field.disabled || context.disabled?.has(field.id)) continue;
+    if (isBlankValue(initial, field.type)) continue;
+    fieldData[field.id] = clearedFieldValue(initial);
+  }
+  return {
+    // oxlint-disable-next-line anti-slop/require-safety-comment-for-type-assertion -- Submit defaults are an open prop contract and are merged without validation, including malformed runtime values.
+    ...(context.submitDefaults as FormData | undefined),
+    ...fieldData,
+  };
+}
+
+export function resolveSubmitDefaults(
+  submitDefaults: FormProps["submitDefaults"],
+  context: ReplaceUrlVariablesContext,
+): FormProps["submitDefaults"] {
+  if (!submitDefaults) return undefined;
+  const resolved: NonNullable<FormProps["submitDefaults"]> = {};
+  for (const [key, value] of Object.entries(submitDefaults)) {
+    if (isString(value) && hasUrlVariables(value)) {
+      const replaced = resolveTextVariables(value, context);
+      if (replaced === undefined) continue;
+      resolved[key] = replaced;
+    } else resolved[key] = value;
+  }
+  return Object.keys(resolved).length > 0 ? resolved : undefined;
+}
+
+/** Initializes fields found among submit defaults, leaving extra defaults submit-only. */
+export function fieldValuesOfSubmitDefaults(
+  fields: ReadonlyArray<{ id: string }>,
+  submitDefaults: FormProps["submitDefaults"],
+): FormData {
+  const values: FormData = {};
+  if (!submitDefaults) return values;
+  for (const { id } of fields) {
+    if (id in submitDefaults) {
+      // oxlint-disable-next-line anti-slop/require-safety-comment-for-type-assertion -- The open submit-default prop is copied unchanged into fields, including values outside the nominal FormFieldValue union.
+      values[id] = submitDefaults[id] as FormFieldValue;
+    }
+  }
+  return values;
+}
+
+export function makeFieldSchemaRequired(schema: z.ZodTypeAny): z.ZodTypeAny {
+  if (schema instanceof z.ZodOptional || schema instanceof z.ZodNullable)
+    return makeFieldSchemaRequired(schema.unwrap());
+  if (schema instanceof z.ZodDefault)
+    return makeFieldSchemaRequired(schema.removeDefault());
+  if (schema instanceof z.ZodUnion) {
+    const nonNullOptions = schema.options.filter(
+      (option: z.ZodTypeAny) => !(option instanceof z.ZodNull),
+    );
+    if (nonNullOptions.length === 1)
+      return makeFieldSchemaRequired(nonNullOptions[0]);
+    return schema;
+  }
+  if (schema instanceof z.ZodString || schema instanceof z.ZodArray)
+    return schema.min(1);
+  return schema;
+}
+
+export function buildValidationSchema(
+  baseSchema: z.ZodObject<Record<string, z.ZodTypeAny>>,
+  disabled: Set<string> | undefined,
+  hidden: Set<string> | undefined,
+  required: Set<string> | undefined,
+): z.ZodObject<Record<string, z.ZodTypeAny>> {
+  const hasInactive =
+    (disabled && disabled.size > 0) || (hidden && hidden.size > 0);
+  const hasRequired = required && required.size > 0;
+  if (!hasInactive && !hasRequired) return baseSchema;
+  const fieldSchemas: Record<string, z.ZodTypeAny> = {};
+  for (const [key, fieldSchema] of Object.entries(baseSchema.shape)) {
+    const isInactive = disabled?.has(key) || hidden?.has(key);
+    if (isInactive) fieldSchemas[key] = fieldSchema.optional().nullable();
+    else if (required?.has(key))
+      fieldSchemas[key] = makeFieldSchemaRequired(fieldSchema);
+    else fieldSchemas[key] = fieldSchema;
+  }
+  return z.object(fieldSchemas).passthrough();
+}
+
+const ALWAYS_FILLED_FIELD_TYPES = new Set(["boolean"]);
+const ACCEPTANCE_COMPONENTS = new Set(["dms-checkbox"]);
+
+/** Whether a field is a required checkbox that only true fills. */
+export function isAcceptanceField(
+  field: Pick<FormField, "type"> & Partial<Pick<FormField, "component">>,
+): boolean {
+  return (
+    !!field.type &&
+    ALWAYS_FILLED_FIELD_TYPES.has(field.type) &&
+    ACCEPTANCE_COMPONENTS.has(field.component?.componentName ?? "")
+  );
+}
+
+/** Whether an active, editable field carries its required marker. */
+export function isFieldMarkedRequired(
+  field: Pick<FormField, "id" | "required" | "disabled" | "type"> &
+    Partial<Pick<FormField, "component" | "readonly">>,
+  disabled: Set<string> | undefined,
+  hidden: Set<string> | undefined,
+  required: Set<string> | undefined,
+): boolean {
+  if (field.disabled || field.readonly) return false;
+  if (disabled?.has(field.id) || hidden?.has(field.id)) return false;
+  const isAlwaysFilled =
+    !!field.type && ALWAYS_FILLED_FIELD_TYPES.has(field.type);
+  if (isAlwaysFilled && !isAcceptanceField(field)) return false;
+  return !!field.required || (required?.has(field.id) ?? false);
+}
+
+const meetsCondition = (
+  condition: FieldCondition,
+  values: FormState,
+): boolean => condition.in.includes(values[condition.field] ?? null);
+
+/** Combines watch-driven inactive fields with the conditions on current values. */
+export function withConditionFields(
+  fields: ReadonlyArray<Pick<FormField, "id" | "visibleWhen" | "disabledWhen">>,
+  values: FormState,
+  watched: { disabled?: Set<string>; hidden?: Set<string> },
+) {
+  const disabled = new Set(watched.disabled);
+  const hidden = new Set(watched.hidden);
+  for (const field of fields) {
+    if (field.visibleWhen && !meetsCondition(field.visibleWhen, values))
+      hidden.add(field.id);
+    if (field.disabledWhen && meetsCondition(field.disabledWhen, values))
+      disabled.add(field.id);
+  }
+  return { disabled, hidden };
+}
+
+export function watchFieldChanges(
+  state: Ref<FormState>,
+  componentId: string | undefined,
+  sendComponentEvent: ReturnType<
+    typeof useComponentEvent
+  >["sendComponentEvent"],
+  isStartingValue: Parameters<typeof createStartingValueTracker>[0],
+): void {
+  if (!componentId) return;
+  const id = componentId;
+  const previousValuesJson: Record<string, string> = {};
+  const isInitial = createStartingValueTracker(isStartingValue);
+  onMounted(() => {
+    watch(() => state.value, sendChanges, { deep: true, immediate: true });
+  });
+  function sendChanges(newState: FormState): void {
+    for (const fieldId of Object.keys(newState)) {
+      if (INTERNAL_STATE_KEYS.has(fieldId)) continue;
+      let newJson: string;
+      try {
+        newJson = JSON.stringify(newState[fieldId]);
+      } catch {
+        newJson = String(newState[fieldId]);
+      }
+      if (newJson !== previousValuesJson[fieldId]) {
+        sendComponentEvent(FormEvents.FIELD_CHANGE, id, {
+          fieldId,
+          value: newState[fieldId],
+          formValues: newState,
+          initial: isInitial(fieldId, newState[fieldId]),
+        });
+        previousValuesJson[fieldId] = newJson;
+      }
+    }
+  }
+}
+
+/** Keeps refused-submit field errors only for active rendered fields. */
+export function resolveFormFieldErrors(
+  error: Parameters<typeof resolveFieldErrors>[0],
+  fields: ReadonlyArray<Pick<FormField, "id" | "disabled">>,
+  inactive: { disabled?: Set<string>; hidden?: Set<string> } = {},
+) {
+  const shown = fields
+    .filter(
+      (field) =>
+        !field.disabled &&
+        !inactive.disabled?.has(field.id) &&
+        !inactive.hidden?.has(field.id),
+    )
+    .map((field) => field.id);
+  return resolveFieldErrors(error, { fields: shown }).fields;
+}

package/frontend-vue/layers/dms-ui/app/build/composables/form/useInstantForm.ts

@@ -1,6 +1,7 @@
 import { type ComputedRef, type Ref, watch } from "vue";
 import type { FormField } from "../../../composables/form/types/field";
 import type { FormFieldValue } from "../../../composables/form/types/value";
+import type { validateFormState } from "./formValidation";
 import { cloneFormValue } from "../../../composables/form/useForm";
 import { sameFormValue } from "../unsaved-changes/formValue";
 import {
@@ -8,11 +9,8 @@ import {
   useInstantSave,
 } from "../instant-save/useInstantSave";
 
-type FormValues = Record<string, unknown>;
+type FormValues = Parameters<typeof validateFormState>[1];
 
-// Fields typed in rather than picked: they save once typing pauses, a pick
-// (a select, a switch, a date) at once. A field without a type is a text;
-// so is a field made of typed parts (an address, the rows of a repeater).
 const TYPED_FIELD_TYPES = new Set([
   "string",
   "address",
@@ -48,6 +46,7 @@ export interface InstantFormOptions {
   /** Sends the changed fields, alone (a partial submit). */
   submit: (changes: FormValues) => Promise<void>;
   /** Says why a save was refused, once its values are put back. */
+  // oxlint-disable-next-line anti-slop/no-unknown-parameters -- JavaScript promises can reject with any value; the adapter forwards it without narrowing the public callback.
   onRefused: (error: unknown) => void;
 }
 
@@ -58,10 +57,11 @@ export interface InstantForm extends InstantSave<FormValues> {
    * A field the server stored on its own (a rotated secret): its value is the
    * confirmed one, not a change to save again.
    */
-  confirmField: (id: string, value: unknown) => void;
+  confirmField: (id: string, value: FormValues[string]) => void;
 }
 
-const clone = (value: unknown): unknown =>
+const clone = (value: FormValues[string]): FormValues[string] =>
+  // oxlint-disable-next-line anti-slop/require-safety-comment-for-type-assertion -- Form state accepts arbitrary compound values; preserve the unchecked clone adapter without claiming FormFieldValue validation.
   cloneFormValue(value as FormFieldValue | undefined);
 
 /**
@@ -71,10 +71,8 @@ const clone = (value: unknown): unknown =>
  * server last confirmed when refused.
  */
 export function useInstantForm(options: InstantFormOptions): InstantForm {
-  // The value each field shows as far as the save knows: a value put back
-  // after a refusal is not a change of the user's.
   const shown = new Map<string, unknown>();
-  // The latest check of each field: an older one ending late is dropped.
+
   const checks = new Map<string, number>();
 
   const instant = useInstantSave<FormValues>({
@@ -97,13 +95,16 @@ export function useInstantForm(options: InstantFormOptions): InstantForm {
     instant.confirm(values);
   }
 
-  function confirmField(id: string, value: unknown): void {
+  function confirmField(id: string, value: FormValues[string]): void {
     const confirmed = clone(value);
     shown.set(id, confirmed);
     instant.confirm({ [id]: confirmed });
   }
 
-  async function saveField(field: FormField, value: unknown): Promise<void> {
+  async function saveField(
+    field: FormField,
+    value: FormValues[string],
+  ): Promise<void> {
     const check = (checks.get(field.id) ?? 0) + 1;
     checks.set(field.id, check);
     const isValid = await options.isFieldValid(field);

package/frontend-vue/layers/dms-ui/app/build/composables/global/searchShortcuts.ts

@@ -1,5 +1,5 @@
-// The page search keys are public (`composables/global/searchShortcuts`):
-// re-exported for the layer's own callers.
+import type { buildPageSearchShortcuts } from "../../../composables/global/searchShortcuts";
+
 export {
   buildPageSearchShortcuts,
   PAGE_SEARCH_SHORTCUTS,
@@ -27,7 +27,7 @@ export function pageSearchAriaKeyshortcuts(macOS: boolean): string {
 /** `defineShortcuts` map focusing the navigation search on "/". */
 export function buildNavSearchShortcuts(
   focus: () => void,
-): Record<string, () => void> {
+): ReturnType<typeof buildPageSearchShortcuts> {
   return { [NAV_SEARCH_SHORTCUT]: focus };
 }
 

package/frontend-vue/layers/dms-ui/app/build/composables/instant-save/useInstantSave.ts

@@ -7,7 +7,7 @@ import {
   type Ref,
 } from "vue";
 import type { SaveStatusState } from "../../../components/save-bar/SaveStatus.vue";
-import { combineSaveStates } from "#dms-layout/app/composables/layout/useInstantSaveHeader";
+import { combineSaveStates } from "#dms-ui/app/composables/layout/useInstantSaveHeader";
 import { sameFormValue } from "../unsaved-changes/formValue";
 
 /** How long typing pauses before a text saves. */
@@ -30,6 +30,7 @@ export interface InstantSaveSource<V extends object> {
   /** Keeps the changed keys; rejects when they are refused. */
   save: (changes: Partial<V>) => Promise<void>;
   /** Called after a refused save is put back (field errors, a toast). */
+  // oxlint-disable-next-line anti-slop/no-unknown-parameters -- A rejected save can throw any JavaScript value; Promise<void> has no rejection type to derive for this callback contract.
   onError?: (error: unknown, changes: Partial<V>) => void;
 }
 
@@ -71,14 +72,24 @@ export interface InstantSave<V extends object> {
 
 type Timer = ReturnType<typeof setTimeout>;
 
+function saveKeys<V extends object>(values: Partial<V>): InstantSaveKey<V>[] {
+  // oxlint-disable-next-line anti-slop/require-safety-comment-for-type-assertion -- Partial<V> does not guarantee exact string keys at runtime; retain the unchecked Object.keys projection.
+  return Object.keys(values) as InstantSaveKey<V>[];
+}
+
 /** The saves of one page: what waits, what runs, what the server holds. */
 class InstantSaveQueue<V extends object> {
-  readonly states = reactive({}) as Partial<
-    Record<InstantSaveKey<V>, SaveStatusState>
-  >;
-  readonly failed = ref<Partial<V> | null>(null) as Ref<Partial<V> | null>;
-  private readonly confirmed = new Map<InstantSaveKey<V>, unknown>();
-  private readonly pending = new Map<InstantSaveKey<V>, unknown>();
+  readonly states: Partial<Record<InstantSaveKey<V>, SaveStatusState>> =
+    reactive({});
+  readonly failed: Ref<Partial<V> | null> = ref(null);
+  private readonly confirmed = new Map<
+    InstantSaveKey<V>,
+    V[InstantSaveKey<V>] | undefined
+  >();
+  private readonly pending = new Map<
+    InstantSaveKey<V>,
+    V[InstantSaveKey<V>] | undefined
+  >();
   private readonly inFlight = new Set<InstantSaveKey<V>>();
   private readonly debounceTimers = new Map<InstantSaveKey<V>, Timer>();
   private readonly savedTimers = new Map<InstantSaveKey<V>, Timer>();
@@ -93,18 +104,22 @@ class InstantSaveQueue<V extends object> {
   }
 
   confirm(values: Partial<V>): void {
-    for (const [key, value] of Object.entries(values)) {
-      this.confirmed.set(key as InstantSaveKey<V>, value);
+    for (const key of saveKeys(values)) {
+      this.confirmed.set(key, values[key]);
     }
   }
 
   /** A change to send with the next save of its key. */
-  put(key: InstantSaveKey<V>, value: unknown): void {
+  put<K extends InstantSaveKey<V>>(key: K, value: V[K] | undefined): void {
     clearTimeout(this.debounceTimers.get(key));
     this.pending.set(key, value);
   }
 
-  wait(key: InstantSaveKey<V>, value: unknown, debounce: boolean): void {
+  wait<K extends InstantSaveKey<V>>(
+    key: K,
+    value: V[K],
+    debounce: boolean,
+  ): void {
     this.put(key, value);
     if (!debounce) {
       void this.send([key]);
@@ -150,6 +165,7 @@ class InstantSaveQueue<V extends object> {
 
   /** Moves the waiting changes of these keys to a running save. */
   private take(keys: InstantSaveKey<V>[]): Partial<V> {
+    // SAFETY: pending stores only V[K] or undefined for a key K; ready contains only keys in pending. Partial<V> permits those supplied values, while Object.fromEntries loses their per-key relationship.
     const changes = Object.fromEntries(
       keys.map((key) => [key, this.pending.get(key)]),
     ) as Partial<V>;
@@ -162,20 +178,23 @@ class InstantSaveQueue<V extends object> {
   }
 
   private onSaved(changes: Partial<V>): void {
-    for (const key of Object.keys(changes) as InstantSaveKey<V>[]) {
+    for (const key of saveKeys(changes)) {
       this.confirmed.set(key, changes[key]);
       this.setState(key, "saved");
     }
     this.settleFailed(changes, false);
   }
 
-  private onRefused(error: unknown, changes: Partial<V>): void {
-    for (const key of Object.keys(changes) as InstantSaveKey<V>[]) {
-      // A newer value picked meanwhile stays on screen: its own save follows.
+  private onRefused(
+    error: Parameters<NonNullable<InstantSaveSource<V>["onError"]>>[0],
+    changes: Partial<V>,
+  ): void {
+    for (const key of saveKeys(changes)) {
       const isShown =
         !this.pending.has(key) &&
         sameFormValue(this.source.read(key), changes[key]);
       if (isShown) {
+        // oxlint-disable-next-line anti-slop/require-safety-comment-for-type-assertion -- The queue API does not require a remembered value; preserve the unchecked rollback lookup.
         this.source.write(key, this.confirmed.get(key) as V[typeof key]);
       }
       this.setState(key, "error");
@@ -185,10 +204,10 @@ class InstantSaveQueue<V extends object> {
   }
 
   private settleFailed(changes: Partial<V>, isRefused: boolean): void {
-    const rest = { ...this.failed.value } as Record<string, unknown>;
-    for (const key of Object.keys(changes)) delete rest[key];
+    const rest: Partial<V> = { ...this.failed.value };
+    for (const key of saveKeys(changes)) delete rest[key];
     const next = isRefused ? { ...rest, ...changes } : rest;
-    this.failed.value = Object.keys(next).length ? (next as Partial<V>) : null;
+    this.failed.value = Object.keys(next).length ? next : null;
   }
 
   private setState(key: InstantSaveKey<V>, state: SaveStatusState): void {
@@ -224,9 +243,10 @@ export function useInstantSave<V extends object>(
   };
 
   const changeMany: InstantSave<V>["changeMany"] = (changes) => {
-    const keys = Object.keys(changes) as InstantSaveKey<V>[];
+    const keys = saveKeys(changes);
     for (const key of keys) {
       saves.remember(key);
+      // oxlint-disable-next-line anti-slop/require-safety-comment-for-type-assertion -- Partial changes may contain undefined for required source fields; retain the unchecked write-through.
       source.write(key, changes[key] as V[typeof key]);
       saves.put(key, changes[key]);
     }
@@ -239,7 +259,6 @@ export function useInstantSave<V extends object>(
     if (changes) changeMany(changes);
   };
 
-  // A text still waiting for typing to pause is saved when the page goes.
   onScopeDispose(() => {
     saves.dispose();
     void saves.flush();

package/frontend-vue/layers/{dms-layout → dms-ui}/app/build/composables/layout/rowSidePanel.ts

@@ -53,6 +53,7 @@ export interface RowSidePanelContent {
   positionLabel?: string;
   component: Component;
   /** Props of the component besides `rowData` and `navigation`. */
+  // oxlint-disable-next-line anti-slop/no-unsafe-dictionary-type -- The selected module component owns these arbitrary props; Vue Component is an open union and cannot derive one shared prop schema without excluding existing component options.
   componentOptions: Record<string, unknown>;
   row?: Data;
   /** Id of `row`: the key the component is mounted under, the row the table highlights. */
@@ -65,9 +66,6 @@ export interface RowSidePanelContent {
   onClose?: () => void;
 }
 
-// Written on the client only (a click, a table mounting on a deep link), never
-// while the server renders a request, so a module-level ref is safe here. It
-// holds a component and callbacks, which no shared state may serialize.
 const content = shallowRef<RowSidePanelContent | null>(null);
 
 /**