@antelopejs/dms 0.9.8 → 0.10.0

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/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/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);
 }

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

@@ -0,0 +1,65 @@
+import type {
+  DataType,
+  DataTypeSelectSource,
+} from "#dms-core/app/composables/data-types/useDataType";
+import type { RenderableColumn } from "../data-types/useColumnValueRenderer";
+
+/** A column of a read-only list: a field of its rows. */
+export interface RepeaterTableColumn {
+  id: string;
+  label?: string;
+  type?: string;
+  component: ComponentInfo;
+}
+
+/** Where a relation column reads the rows its values name. */
+export interface RelationLabelSource extends DataTypeSelectSource {
+  multiple: boolean;
+}
+
+/**
+ * The column as the grid's cell renderer reads it: its data type, with the
+ * options of its control (a select's items, a relation's key mapping).
+ */
+export function renderableColumn(
+  column: RepeaterTableColumn,
+): RenderableColumn {
+  const type: DataTypeConfig = {
+    id: column.type ?? "",
+    compareModes: [],
+    filterComponents: {},
+    // The column came from the form's JSON: its options are JSON values.
+    inputComponent: column.component as ComponentInfo<ComponentOptionsData>,
+  };
+  return { id: column.id, type };
+}
+
+/**
+ * The rows a relation column names its values from, if its data type reads
+ * its labels from a `select` route ({@link DataType.selectSource}).
+ */
+export function relationLabelSource(
+  column: RepeaterTableColumn,
+  dataType: Pick<DataType, "selectSource"> | undefined,
+): RelationLabelSource | undefined {
+  const options = column.component.options as
+    | { multiple?: unknown }
+    | undefined;
+  const source = dataType?.selectSource?.(options);
+  return source ? { ...source, multiple: !!options?.multiple } : undefined;
+}
+
+/**
+ * A relation value as its formatter draws it: the related row in place of
+ * each id it holds. An id no row matches (a deleted one) stays as it is; a
+ * value the server already joined is kept.
+ */
+export function joinRelationValue(
+  value: unknown,
+  rowsByValue: ReadonlyMap<unknown, Record<string, unknown>>,
+  multiple: boolean,
+): unknown {
+  const join = (item: unknown) => rowsByValue.get(item) ?? item;
+  if (multiple && Array.isArray(value)) return value.map(join);
+  return join(value);
+}

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

@@ -0,0 +1,49 @@
+/**
+ * A server error as UForm holds it once placed: on the field, or on the part
+ * of it the error names (`address.street`).
+ */
+export interface PlacedServerError {
+  name?: string;
+  message: string;
+}
+
+/** A refused submit's errors a field shows, and the value they were raised against. */
+export interface KeptServerError {
+  /** The field's value when the server refused it, as JSON. */
+  value: string;
+  errors: PlacedServerError[];
+}
+
+/** The value of a field as a kept error compares it. */
+export function serverErrorValue(value: unknown): string {
+  return JSON.stringify(value) ?? "";
+}
+
+/** The fields whose value moved off the one their kept error was raised against. */
+export function changedServerErrorFields(
+  kept: ReadonlyMap<string, KeptServerError>,
+  state: Readonly<Record<string, unknown>>,
+): string[] {
+  return [...kept]
+    .filter(([name, entry]) => serverErrorValue(state[name]) !== entry.value)
+    .map(([name]) => name);
+}
+
+/**
+ * The kept server errors, as UForm's `validate` answers them. UForm runs it
+ * with its schema on every validation and replaces a field's errors with what
+ * both answer: a number input commits its value as it loses focus, and the
+ * input event, landing 300 ms later, re-validates the field after a refused
+ * submit placed its error. A field still holding the refused value keeps it.
+ * A submit validates without them: the server judges the values again.
+ */
+export function keptServerErrors(
+  kept: ReadonlyMap<string, KeptServerError>,
+  state: Readonly<Record<string, unknown>>,
+  isSubmitting: boolean,
+): PlacedServerError[] {
+  if (isSubmitting) return [];
+  return [...kept]
+    .filter(([name, entry]) => serverErrorValue(state[name]) === entry.value)
+    .flatMap(([, entry]) => entry.errors);
+}