@antelopejs/dms 0.9.8 → 0.11.0

package/frontend-vue/layers/dms-ui/app/build/composables/data-types/relationValue.ts

@@ -64,3 +64,42 @@ export function sameRelationValue(
   };
   return sameFormValue(comparable(left), comparable(right));
 }
+
+/**
+ * What a relation field asks its target's `select` route for to label the
+ * ids it holds: those rows alone, matched on the field's value key (the
+ * route falls back to the row id when none is mapped).
+ */
+export interface RelationIdsQuery {
+  ids: string[];
+  idKey?: string;
+  limit: number;
+}
+
+const isIdValue = (value: unknown): value is string | number =>
+  (typeof value === "string" && value !== "") || typeof value === "number";
+
+/**
+ * The ids a relation value holds that no known row labels yet — a form whose
+ * read answers the id (`"u-5"`) rather than the joined row. A joined row
+ * labels itself, so only plain ids are returned, each once.
+ */
+export function unlabeledRelationIds(
+  value: unknown,
+  labeledIds: ReadonlySet<string>,
+): string[] {
+  const ids = [value].flat().filter(isIdValue).map(String);
+  return [...new Set(ids)].filter((id) => !labeledIds.has(id));
+}
+
+/** The `select` query answering the rows of `ids`. */
+export function relationIdsQuery(
+  ids: string[],
+  keyMapping?: RelationKeyMapping,
+): RelationIdsQuery {
+  return {
+    ids,
+    ...(keyMapping?.value ? { idKey: keyMapping.value } : {}),
+    limit: ids.length,
+  };
+}

package/frontend-vue/layers/dms-ui/app/build/composables/data-types/twoLineCell.ts

@@ -1,6 +1,6 @@
 import { h, type VNodeChild } from "vue";
 import type { DataType } from "#dms-core/app/composables/data-types/useDataType";
-import { useComposedText } from "../../../../../dms-core/app/composables/translation/useComposedText";
+import { getAppComposedText } from "../../../../../dms-core/app/composables/translation/useComposedText";
 import {
   type ComposableText,
   isComposedText,
@@ -53,7 +53,7 @@ function readPrimary(
   opts: TwoLineOptions,
   row: Row,
 ): VNodeChild | undefined {
-  const { processText } = useComposedText();
+  const { processText } = getAppComposedText();
   if (opts.primaryField) {
     const text = processText(
       readRowField(row, opts.primaryField) as ComposableText,
@@ -76,7 +76,7 @@ function renderTwoLine(
   options: unknown,
   row: Row,
 ) {
-  const { processText } = useComposedText();
+  const { processText } = getAppComposedText();
   const opts = (options ?? {}) as TwoLineOptions;
   const primary = readPrimary(value, locale, opts, row);
   const sub = readSubline(readRowField(row, opts.subField), {

package/frontend-vue/layers/dms-ui/app/build/composables/data-types/useColumnValueRenderer.ts

@@ -20,12 +20,14 @@ export interface RenderableColumn {
 }
 
 // v2 cell anatomy: amounts are right-aligned mono figures in the ink color,
-// dates 12px muted mono. A data type can give cells a shorter rendering
+// dates 12px muted mono. Where a record is read (the detail surface), amounts
+// keep the form's own font with tabular figures, as its read-only values do. A data type can give cells a shorter rendering
 // through a `cell` formatter (the date type does); others use `default`.
 export const NUMERIC_TYPE_IDS = new Set(["number", "price", "percentage"]);
 const DATE_TYPE_IDS = new Set(["date"]);
 const NUMERIC_CELL_CLASS =
   "block text-right font-mono tabular-nums text-highlighted";
+const DETAIL_NUMERIC_CELL_CLASS = "block text-right tabular-nums";
 const NUMERIC_EMPTY_CELL_CLASS = "block text-right text-dimmed";
 const DATE_CELL_CLASS = "font-mono text-xs text-muted tabular-nums";
 const DEFAULT_FALLBACK = "-";
@@ -101,7 +103,9 @@ export function useColumnValueRenderer() {
       return formatted as VNodeChild;
     }
     if (isNumeric) {
-      return h("span", { class: NUMERIC_CELL_CLASS }, String(formatted));
+      const numericClass =
+        surface === "detail" ? DETAIL_NUMERIC_CELL_CLASS : NUMERIC_CELL_CLASS;
+      return h("span", { class: numericClass }, String(formatted));
     }
     if (!column.display && typeId && DATE_TYPE_IDS.has(typeId)) {
       return h("span", { class: DATE_CELL_CLASS }, String(formatted));

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

@@ -0,0 +1,15 @@
+import type { FormField } from "../../../composables/form/types/field";
+import { isEmptyFormValue } from "../unsaved-changes/formValue";
+
+/**
+ * Whether a form creating a record leaves a field out: a read-only one that
+ * holds nothing yet (a number, a date, a total the server sets once the
+ * record exists) would only read "—". It shows once it holds a value (a
+ * default, one a rule computed), and a field declaring `showEmptyOnCreate`
+ * keeps its place regardless.
+ */
+export function isHiddenOnCreate(field: FormField, value: unknown): boolean {
+  if (field.showEmptyOnCreate) return false;
+  if (!field.disabled && !field.readonly) return false;
+  return isEmptyFormValue(value);
+}

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

@@ -0,0 +1,40 @@
+import type { Ref } from "vue";
+import type { MarkFieldSaved } from "../../../composables/form/types/field-saved";
+import type {
+  FormData,
+  FormFieldValue,
+} from "../../../composables/form/types/value";
+import { cloneFormValue } from "../../../composables/form/useForm";
+import type { UseFormDirtyReturn } from "../../../composables/unsaved-changes/useFormDirty";
+import type { InstantForm } from "./useInstantForm";
+
+type FormValues = Record<string, unknown>;
+
+/** What a field the server saved on its own updates in its form. */
+export interface FieldSavedTargets {
+  /** Whether the form has the field: another control's id is left alone. */
+  hasField: (id: string) => boolean;
+  /** The values "Discard" puts back. */
+  initialValues: Ref<FormData>;
+  /** The values the form reads as unchanged. */
+  dirty: Pick<UseFormDirtyReturn<FormValues>, "baseline" | "markClean">;
+  /** The instant save of a form saving as it goes. */
+  instantSave?: Pick<InstantForm, "confirmField">;
+}
+
+/**
+ * The form's answer to a field whose value the server stored on its own (a
+ * rotated secret): that value becomes the one the field is compared with and
+ * the one "Discard" puts back, and an instant form does not save it again.
+ */
+export function fieldSavedMarker(targets: FieldSavedTargets): MarkFieldSaved {
+  return (id, value) => {
+    if (!targets.hasField(id)) return;
+    targets.initialValues.value = {
+      ...targets.initialValues.value,
+      [id]: cloneFormValue(value as FormFieldValue) as FormFieldValue,
+    };
+    targets.dirty.markClean({ ...targets.dirty.baseline.value, [id]: value });
+    targets.instantSave?.confirmField(id, value);
+  };
+}

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

@@ -0,0 +1,62 @@
+/** What a `SetFieldValue` watch writes, and where. */
+export interface SetFieldValueParams {
+  targetField: string;
+  value?: unknown;
+  valueMap?: Record<string, unknown>;
+}
+
+/** The payload of a form's `FieldChange` event. */
+export interface FieldChangePayload {
+  fieldId?: string;
+  value?: unknown;
+  /** The field still holds the value the form started from. */
+  initial?: boolean;
+}
+
+/** A value to write, or nothing to write. */
+export type FieldValueWrite = { value: unknown } | undefined;
+
+type MapKey = string | number | boolean;
+
+function isMapKey(value: unknown): value is MapKey {
+  return ["string", "number", "boolean"].includes(typeof value);
+}
+
+/**
+ * What a `SetFieldValue` watch writes for a field change: its `value`, or the
+ * entry of its `valueMap` named by the changed field's value. Nothing on a
+ * value the form started from — the record keeps what it stored — nor for a
+ * value the map has no entry for.
+ */
+export function resolveFieldValueWrite(
+  params: SetFieldValueParams,
+  payload: FieldChangePayload | undefined,
+): FieldValueWrite {
+  if (payload?.initial) return undefined;
+  if (params.valueMap) {
+    const key = payload?.value;
+    if (!isMapKey(key) || !Object.hasOwn(params.valueMap, String(key))) {
+      return undefined;
+    }
+    return { value: params.valueMap[String(key)] };
+  }
+  if (!Object.hasOwn(params, "value")) return undefined;
+  return { value: params.value };
+}
+
+/**
+ * Tells, for each `FieldChange` a form sends, whether the field still holds
+ * the value it started from and never held another: once a field changed,
+ * coming back to that value is a change too.
+ */
+export function createStartingValueTracker(
+  isStartingValue: (fieldId: string, value: unknown) => boolean,
+): (fieldId: string, value: unknown) => boolean {
+  const changedFieldIds = new Set<string>();
+  return (fieldId, value) => {
+    if (changedFieldIds.has(fieldId)) return false;
+    if (isStartingValue(fieldId, value)) return true;
+    changedFieldIds.add(fieldId);
+    return false;
+  };
+}

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

@@ -20,6 +20,11 @@ export interface FormEntryContext {
   isFieldHidden: (field: FormField) => boolean;
   isFieldDisabled: (field: FormField) => boolean;
   isFieldRequired: (field: FormField) => boolean;
+  /**
+   * Whether nothing in the form can be changed (a record's details): its
+   * rows show values without the descriptions that tell how to fill them.
+   */
+  isReadOnly: Readonly<Ref<boolean>>;
   /**
    * Whether a field points out a change waiting to be saved: not in an
    * instant form (nothing waits) nor in an action form (nothing was saved).

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

@@ -3,15 +3,19 @@
  *
  * - `record` (default): a record, a settings page, a table view's form. It
  *   keeps its values once saved; Cancel while there is nothing to save when
- *   it has somewhere to go back to, then "Unsaved changes" with Discard and
- *   Save.
+ *   it has somewhere to go back to, then "Unsaved changes" with Save and,
+ *   beside it, Cancel again (discard and leave) or, with nowhere to go back
+ *   to, Discard.
+ * - `create`: a form that makes a new record (a table view's add form, the
+ *   duplicate it opens). Its submit from the start, no "Unsaved changes"
+ *   list, since all it holds is new.
  * - `action`: a form that does something each time (send a notification,
  *   invite someone, run a job). Its own submit label, always ready: what it
  *   holds untouched, its defaults included, is a payload too. Beside it,
  *   Reset once a value changed, Cancel before that in a drawer or a modal.
  *   It empties after a successful submit.
  */
-export type FormKind = "record" | "action";
+export type FormKind = "record" | "create" | "action";
 
 /** How a form offers to save (interface-dms `FormSaveMode`). */
 export type FormSaveMode = "bar" | "footer" | "none" | "instant";
@@ -39,7 +43,10 @@ export interface SaveBarContext {
   resettable: boolean;
 }
 
-/** The button beside the submit: Discard / Reset, or Cancel. */
+/**
+ * The button beside the submit: Discard / Reset (values back, the form
+ * stays), or Cancel (values back, the form is left).
+ */
 export type SaveBarSecondary = "discard" | "cancel";
 
 /** What a form's save bar shows. */
@@ -67,11 +74,20 @@ const HIDDEN_BAR: SaveBarState = {
 };
 
 /**
- * A record form's bar: "Unsaved changes" with Discard and Save once a value
- * changed, Cancel before that when it has somewhere to go back to.
+ * A record form's bar: "Unsaved changes" and Save once a value changed, Cancel
+ * before that when it has somewhere to go back to. Beside Save, a form with
+ * somewhere to go back to keeps Cancel, which drops the changes and leaves,
+ * the same as before any change: one click, never a reverted form left open.
+ * A form with nowhere to go back to offers Discard.
  */
 function recordSaveBar(context: SaveBarContext): SaveBarState {
-  if (context.dirty) return { ...HIDDEN_BAR, isHidden: false };
+  if (context.dirty) {
+    return {
+      ...HIDDEN_BAR,
+      secondary: context.cancellable ? "cancel" : "discard",
+      isHidden: false,
+    };
+  }
   if (!context.cancellable) return HIDDEN_BAR;
   return {
     showsStatus: false,
@@ -82,6 +98,24 @@ function recordSaveBar(context: SaveBarContext): SaveBarState {
   };
 }
 
+/**
+ * A create form's bar: its submit from the start, since a duplicate (or a
+ * row its defaults fill) is saved as it is, with no "Unsaved changes" list,
+ * since all it holds is new. Beside it, Cancel when it has somewhere to go
+ * back to, Discard once a value changed otherwise.
+ */
+function createSaveBar(context: SaveBarContext): SaveBarState {
+  const bar: SaveBarState = {
+    showsStatus: false,
+    showsSubmit: true,
+    isSubmitHeld: false,
+    isHidden: false,
+  };
+  if (context.cancellable) return { ...bar, secondary: "cancel" };
+  if (context.dirty) return { ...bar, secondary: "discard" };
+  return bar;
+}
+
 /**
  * An action form's bar: its submit, never held, so a pre-filled form sends as
  * it is. Beside it, Reset once a value changed; before that, Cancel in a
@@ -106,6 +140,7 @@ function actionSaveBar(context: SaveBarContext): SaveBarState {
 
 const SAVE_BARS: Record<FormKind, (context: SaveBarContext) => SaveBarState> = {
   record: recordSaveBar,
+  create: createSaveBar,
   action: actionSaveBar,
 };
 

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

@@ -2,6 +2,11 @@ import type {
   FieldRowLayout,
   FieldRowSpacing,
 } from "../../../components/field-row/FieldRow.vue";
+import {
+  type FormField,
+  type FormFieldOrGroup,
+  isFieldGroup,
+} from "../../../composables/form/types/field";
 
 export type FormOrientation = "horizontal" | "vertical";
 export type FormSurface = "card" | "container" | "section" | "sections";
@@ -41,6 +46,25 @@ export const FORM_LAYOUT_CLASSES: Record<FormOrientation, FormLayoutClasses> = {
   },
 };
 
+// A form in a drawer or a modal: the same rows on a tighter rhythm, the
+// container's width being scarcer than a page's. A row with one line of
+// value is 57px beside its label; stacked (a phone, a narrow drawer) the
+// label sits 6px above its control. Read-only details and editable forms
+// share the rows, so both read alike.
+export const CONTAINER_LAYOUT_CLASSES: Record<
+  FormOrientation,
+  FormLayoutClasses
+> = {
+  horizontal: {
+    rows: "flex flex-col",
+    row: { layout: "form", inset: false, spacing: "dense" },
+  },
+  vertical: {
+    rows: "flex flex-col gap-3 py-3",
+    row: { layout: "stack", inset: false, spacing: "list" },
+  },
+};
+
 // A card form draws its own head band and sticky footer band; inside a
 // modal or drawer the container is the surface and already pads the body.
 // The footer sticks to the bottom of the scroll area while the form runs
@@ -82,10 +106,88 @@ export const SECTION_LAYOUT_CLASSES: FormLayoutClasses = {
   row: { layout: "form", inset: true, spacing: "row" },
 };
 
-// Grouped controls sit side by side once the row is wide enough for its
-// label column (FieldRow's 560px container step), whatever the viewport: a
-// narrow modal or drawer form stacks them.
+// Grouped controls share the row while each keeps a usable width (11rem: a
+// date, a select showing its value), and wrap onto the next line once they
+// would shrink below it, so a group of five in a modal, a drawer or on a
+// phone wraps instead of drawing its controls over one another. A member
+// alone on its line takes the whole width; `min(100%, ...)` keeps a row
+// narrower than the minimum from overflowing.
 export const GROUP_FIELDS_CLASSES: Record<FormOrientation, string> = {
-  horizontal: "flex flex-col gap-2.5 @min-[560px]:flex-row",
+  horizontal:
+    "grid grid-cols-[repeat(auto-fit,minmax(min(100%,11rem),1fr))] gap-x-3 gap-y-2.5",
   vertical: "flex flex-col gap-2.5",
 };
+
+// Fields whose value is a block of its own (a table of rows, pairs, code,
+// formatted text, a gallery): beside a 240px label they get what is left of
+// a drawer, where a repeater falls into its stacked cards. They take the
+// row's full width under their label instead, whatever the form's layout.
+const WIDE_FIELD_COMPONENTS: ReadonlySet<string> = new Set([
+  "dms-repeater",
+  "dms-key-value",
+  "dms-input-code",
+  "dms-rich-text",
+]);
+// The same values shown read-only, drawn from the field's type.
+const WIDE_FIELD_TYPES: ReadonlySet<string> = new Set([
+  "array",
+  "key_value",
+  "code",
+  "rich_text",
+]);
+// Files and images drop their list or gallery under the control when
+// several are allowed.
+const MULTIPLE_FILE_COMPONENTS: ReadonlySet<string> = new Set([
+  "dms-file",
+  "dms-image",
+]);
+// A textarea taller than the browser's three rows is a long text.
+const SHORT_TEXTAREA_ROWS = 3;
+
+/** The options of a field's control that make it wide. */
+interface WideFieldOptions {
+  multiple?: boolean;
+  rows?: number;
+}
+
+/** Whether a field takes the row's full width, its label above it. */
+export function isWideField(field: FormField): boolean {
+  if (field.type && WIDE_FIELD_TYPES.has(field.type)) return true;
+  const name = field.component.componentName ?? "";
+  if (WIDE_FIELD_COMPONENTS.has(name)) return true;
+  const options: WideFieldOptions = field.component.options ?? {};
+  if (MULTIPLE_FILE_COMPONENTS.has(name)) return options.multiple === true;
+  if (name !== "dms-textarea") return false;
+  return (options.rows ?? 0) > SHORT_TEXTAREA_ROWS;
+}
+
+/**
+ * How a form row is drawn: a wide field, or a group holding one, stacks its
+ * label above it where the form would set it beside.
+ */
+export function entryRowLayout(
+  row: FormRowLayout,
+  fields: readonly FormField[],
+): FormRowLayout {
+  if (row.layout !== "form" || !fields.some(isWideField)) return row;
+  return { ...row, layout: "stack" };
+}
+
+/** The fields a form entry draws: its own, or its group's. */
+export function entryFields(entry: FormFieldOrGroup): FormField[] {
+  return isFieldGroup(entry) ? entry.fields : [entry];
+}
+
+/** Classes of a grouped field: its own label above its control. */
+export interface GroupMemberClasses {
+  root: string;
+  label: string;
+}
+
+// A member's label is a step below the group's (FieldRow's 13px semibold
+// label), which heads the cluster.
+export const GROUP_MEMBER_CLASSES: GroupMemberClasses = {
+  root: "grid min-w-0 flex-1 content-start gap-1.5",
+  label:
+    "flex flex-wrap items-center gap-1 text-[12.5px] font-medium text-toned",
+};

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

@@ -1,15 +1,19 @@
 import { type Ref, ref, watch } from "vue";
 import { apiErrorStatus } from "#dms-core/app/composables/useFieldErrors";
-import { HTTP_FORBIDDEN } from "#dms-core/app/utils/http-status";
+import {
+  HTTP_FORBIDDEN,
+  HTTP_NOT_FOUND,
+} from "#dms-core/app/utils/http-status";
 
 /**
  * Why a form could not load the record it edits: `forbidden` when the server
  * refused the caller the read (a role that may edit rows but not view them),
  * `missing` when its address lacks the record's id (a page reached without
- * its `?id=`), `error` for anything else (a network failure, a server error,
- * a row gone).
+ * its `?id=`), `not_found` when the server answered 404 (the record was
+ * deleted, or never existed), `error` for anything else (a network failure,
+ * a server error).
  */
-export type FormLoadFailure = "forbidden" | "missing" | "error";
+export type FormLoadFailure = "forbidden" | "missing" | "not_found" | "error";
 
 /** What a form knows of the record it is about, as far as `missing` goes. */
 export interface FormRecordAddress {
@@ -51,7 +55,9 @@ export interface FormRecordLoad {
 /** The failure a load error stands for; `null` when there is none. */
 export function formLoadFailure(error: unknown): FormLoadFailure | null {
   if (!error) return null;
-  return apiErrorStatus(error) === HTTP_FORBIDDEN ? "forbidden" : "error";
+  const status = apiErrorStatus(error);
+  if (status === HTTP_FORBIDDEN) return "forbidden";
+  return status === HTTP_NOT_FOUND ? "not_found" : "error";
 }
 
 /** How a form takes the answers of its record's later reads. */

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

@@ -133,3 +133,35 @@ export function sectionState(
     invalidCount: section.fieldIds.filter((id) => invalid.has(id)).length,
   };
 }
+
+/** Where a section's card starts, from the top of the visible area. */
+export interface SectionOffset {
+  id: string;
+  top: number;
+}
+
+/** What the side list reads to tell which section is being read. */
+export interface SectionSpyView {
+  /** The sections, in order. */
+  sections: SectionOffset[];
+  /** Offset of the reading line from the top of the visible area. */
+  readingLine: number;
+  /** Scrolled to the end: nothing below can rise to the reading line. */
+  isAtEnd: boolean;
+}
+
+/**
+ * The section being read: the last one whose top has passed the reading
+ * line, the first before any has, and the last once the form is scrolled to
+ * its end — the sections at the bottom of a long form never rise that far,
+ * and would otherwise never be current. One section at a time.
+ */
+export function currentSectionId(view: SectionSpyView): string | undefined {
+  if (view.isAtEnd) return view.sections.at(-1)?.id;
+  let current = view.sections[0]?.id;
+  for (const section of view.sections) {
+    if (section.top > view.readingLine) break;
+    current = section.id;
+  }
+  return current;
+}

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

@@ -22,6 +22,11 @@ export interface FormValidationField {
   type?: string;
   /** Holds one value per content language. */
   localized?: boolean;
+  /**
+   * The language a localized field falls back to: required as soon as the
+   * field holds any language, and where its required error goes.
+   */
+  fallbackLocale?: string;
   /** A box to tick: unticked, it is missing. */
   acceptance?: boolean;
   /**
@@ -63,6 +68,32 @@ function issueField(issue: { path: PropertyKey[] }): PropertyKey | undefined {
   return issue.path[0];
 }
 
+/** Whether a localized value fills some language but not its fallback one. */
+function lacksFallbackLocale(
+  field: FormValidationField,
+  value: unknown,
+): boolean {
+  if (!field.localized || !field.fallbackLocale) return false;
+  if (typeof value !== "object" || value === null) return false;
+  const languages = value as Record<string, unknown>;
+  const isAnyFilled = Object.values(languages).some(
+    (text) => !isBlankValue(text, field.type),
+  );
+  return (
+    isAnyFilled && isBlankValue(languages[field.fallbackLocale], field.type)
+  );
+}
+
+/** Where a localized field's required error goes: the language to fill. */
+function requiredPath(
+  field: FormValidationField,
+  locale: string | undefined,
+): PropertyKey[] {
+  if (!field.localized) return [field.id];
+  const language = field.fallbackLocale ?? locale;
+  return language ? [field.id, language] : [field.id];
+}
+
 /** An issue saying the value is not of a branch's type at all. */
 function isTypeMismatch(issue: z.ZodIssue, path: PropertyKey[]): boolean {
   return issue.code === "invalid_type" && issue.path.length === path.length;
@@ -117,6 +148,10 @@ export async function validateFormState(
   for (const field of context.fields) {
     const value = state[field.id];
     if (reported.has(field.id)) continue;
+    if (lacksFallbackLocale(field, value)) {
+      missing.add(field.id);
+      continue;
+    }
     const isBlank = field.acceptance
       ? value !== true
       : isBlankValue(value, field.type);
@@ -159,10 +194,7 @@ export async function validateFormState(
     if (!missing.has(field.id)) continue;
     issues.push({
       message: context.requiredMessage,
-      path:
-        field.localized && context.locale
-          ? [field.id, context.locale]
-          : [field.id],
+      path: requiredPath(field, context.locale),
     });
   }
 

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

@@ -0,0 +1,19 @@
+import type { DataType } from "#dms-core/app/composables/data-types/useDataType";
+
+/**
+ * What a read-only field shows: for a type whose form state is mapped from
+ * the value the server sent (a relation loaded as its row, held as its id),
+ * that value while the state still references it, so the field reads as the
+ * table cell does — the row's label and avatar rather than its id. Any other
+ * value, or one the form changed, is shown as the state holds it.
+ */
+export function readonlyFieldValue(
+  value: unknown,
+  loaded: unknown,
+  dataType: DataType | undefined,
+  options?: unknown,
+): unknown {
+  if (!dataType?.beforeStateMapper || !dataType.isSameValue) return value;
+  if (loaded === undefined || loaded === null) return value;
+  return dataType.isSameValue(value, loaded, options) ? loaded : value;
+}

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

@@ -1,3 +1,9 @@
+import {
+  type FieldChangePayload,
+  type SetFieldValueParams,
+  resolveFieldValueWrite,
+} from "./fieldValueRule";
+
 type FieldSetStateKey = "disabledFields" | "hiddenFields" | "requiredFields";
 
 function createFieldSetMutator(stateKey: FieldSetStateKey, flagKey: string) {
@@ -23,6 +29,25 @@ function createFieldSetMutator(stateKey: FieldSetStateKey, flagKey: string) {
   };
 }
 
+function setFieldValue(
+  action: WatchAction,
+  eventData: ComponentEventData,
+  componentState: Ref<Record<string, unknown>>,
+) {
+  const params = action.params as unknown as SetFieldValueParams;
+  const write = resolveFieldValueWrite(
+    params,
+    eventData.data as FieldChangePayload | undefined,
+  );
+  if (!write) return;
+  // A copy: a map entry holding a list or an object is shared by every write
+  // (and may reach here as a reactive proxy, which structuredClone refuses).
+  componentState.value[params.targetField] =
+    write.value === undefined
+      ? undefined
+      : JSON.parse(JSON.stringify(write.value));
+}
+
 export function registerFormFunctions() {
   const { registerFunction } = useDefinedFunctions();
 
@@ -40,4 +65,6 @@ export function registerFormFunctions() {
     FormFunctions.SET_FIELD_REQUIRED,
     createFieldSetMutator("requiredFields", "setRequired"),
   );
+
+  registerFunction(FormFunctions.SET_FIELD_VALUE, setFieldValue);
 }