@antelopejs/dms 0.5.6 → 0.6.0

package/frontend-vue/tests/form-required-validation.test.ts

@@ -0,0 +1,407 @@
+import { describe, expect, it } from "vitest";
+import { z } from "zod";
+import { zodToJsonSchema } from "zod-to-json-schema";
+import { jsonSchemaToZod, type JsonSchema } from "json-schema-to-zod";
+import {
+  formIssueMessage,
+  isBlankValue,
+  REQUIRED_MESSAGE,
+} from "../layers/dms-core/app/composables/useFormValidation";
+import {
+  type FormValidationField,
+  type FormValidationIssue,
+  unwrapUnionIssue,
+  validateFormState,
+} from "../layers/dms-ui/app/build/composables/form/formValidation";
+
+// The client rebuilds the schema the backend serializes (see useForm's
+// createBaseValidationSchema): the same round trip here, so each case reads
+// what the form really validates with.
+function roundTrip(
+  shape: Record<string, z.ZodTypeAny>,
+): z.ZodObject<Record<string, z.ZodTypeAny>> {
+  const json = zodToJsonSchema(z.object(shape)) as unknown as JsonSchema;
+  const code = jsonSchemaToZod(json, { module: "none" }).replace(
+    /\.strict\(\)$/,
+    ".passthrough()",
+  );
+  return new Function("z", `"use strict"; return (${code})`)(z);
+}
+
+// The backend's adaptFieldValidationSchema: optional is nullable+optional,
+// required makes a text or a list non-empty.
+function optional(schema: z.ZodTypeAny): z.ZodTypeAny {
+  return schema.nullable().optional();
+}
+
+// DefaultDataTypes.DateType: an ISO date string or a Date.
+function date(): z.ZodTypeAny {
+  return z
+    .union([
+      z.string().regex(/^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(\.\d{3})?Z?)?$/),
+      z.date(),
+    ])
+    .transform((value) =>
+      typeof value === "string" ? new Date(value) : value,
+    );
+}
+
+function dateRange(): z.ZodTypeAny {
+  return z.union([z.array(date()), z.object({ start: date(), end: date() })]);
+}
+
+// DefaultDataTypes.AddressType.
+function address(): z.ZodTypeAny {
+  return z.object({
+    streetName: z.string().min(1),
+    houseNumber: z.string().optional(),
+    postalCode: z.string().min(1),
+    city: z.string().min(1),
+    countryCode: z.string().length(2),
+  });
+}
+
+const REQUIRED = "This field is required.";
+// What the form's error map does with a blank part: the required wording.
+const errorMap: z.ZodErrorMap = (issue, context) => ({
+  message:
+    formIssueMessage(issue, context.data) === REQUIRED_MESSAGE
+      ? REQUIRED
+      : (issue.message ?? context.defaultError),
+});
+
+async function issuesOf(
+  shape: Record<string, z.ZodTypeAny>,
+  fields: FormValidationField[],
+  state: Record<string, unknown>,
+): Promise<FormValidationIssue[]> {
+  const result = await validateFormState(roundTrip(shape), state, {
+    fields,
+    requiredMessage: REQUIRED,
+    locale: "en",
+    parseParams: { errorMap },
+  });
+  return "issues" in result ? result.issues : [];
+}
+
+async function valueOf(
+  shape: Record<string, z.ZodTypeAny>,
+  fields: FormValidationField[],
+  state: Record<string, unknown>,
+): Promise<Record<string, unknown> | undefined> {
+  const result = await validateFormState(roundTrip(shape), state, {
+    fields,
+    requiredMessage: REQUIRED,
+    locale: "en",
+    parseParams: { errorMap },
+  });
+  return "value" in result ? result.value : undefined;
+}
+
+const required = (id: string, type?: string): FormValidationField => ({
+  id,
+  type,
+  required: true,
+});
+
+describe("isBlankValue: what counts as empty, per type", () => {
+  it.each([
+    ["nothing", undefined, undefined],
+    ["null", null, undefined],
+    ["a blank text", "  ", undefined],
+    ["no item", [], undefined],
+    ["a cleared number", Number.NaN, undefined],
+    ["an unpicked range", { start: undefined, end: undefined }, "date"],
+    ["a range list of nothing", [undefined, undefined], "date"],
+    ["an empty rich-text document", "<p></p>", "rich_text"],
+    [
+      "a rich-text document of spaces",
+      "<p>&nbsp; </p><p><br></p>",
+      "rich_text",
+    ],
+    [
+      "an address of empty parts",
+      { streetName: "", postalCode: "", city: "", countryCode: "" },
+      "address",
+    ],
+    [
+      "an image without a file",
+      { key: "", alt: "", principal: false },
+      "image",
+    ],
+    ["translations all blank", { en: "", fr: " " }, "string"],
+  ])("%s is empty", (_label, value, type) => {
+    expect(isBlankValue(value, type)).toBe(true);
+  });
+
+  it.each([
+    ["zero", 0, "number"],
+    ["false", false, "boolean"],
+    ["a rich-text document with text", "<p>Hi</p>", "rich_text"],
+    [
+      "a rich-text document with only an image",
+      '<p><img src="a"></p>',
+      "rich_text",
+    ],
+    ["an address with a street", { streetName: "Rue", city: "" }, "address"],
+    ["a picked date", "2026-10-02", "date"],
+  ])("%s is a value", (_label, value, type) => {
+    expect(isBlankValue(value, type)).toBe(false);
+  });
+});
+
+describe("validateFormState: a required field left empty", () => {
+  it("flags an unpicked date as required, not as an invalid value", async () => {
+    const issues = await issuesOf(
+      { due: date() },
+      [required("due", "date")],
+      {},
+    );
+    expect(issues).toEqual([{ message: REQUIRED, path: ["due"] }]);
+  });
+
+  it.each([
+    ["a date", "date", date(), null],
+    ["a date range", "date", dateRange(), { start: undefined, end: undefined }],
+    ["a list of dates", "date", z.array(date()).min(1), []],
+    ["a rich text", "rich_text", z.string().min(1), "<p></p>"],
+    ["a number cleared to text", "number", z.number(), ""],
+    ["a number cleared", "number", z.number(), Number.NaN],
+    ["a select", "select", z.enum(["a", "b"]), undefined],
+    ["a file", "file", z.string().min(1), ""],
+    ["a gallery", "image", z.array(z.object({ key: z.string() })).min(1), []],
+    ["a time", "string_time", z.number(), null],
+  ])("flags %s as required", async (_label, type, schema, value) => {
+    const issues = await issuesOf(
+      { field: schema },
+      [required("field", type)],
+      { field: value },
+    );
+    expect(issues).toEqual([{ message: REQUIRED, path: ["field"] }]);
+  });
+
+  it("gives an empty address one required issue, not one per part", async () => {
+    const issues = await issuesOf(
+      { address: address() },
+      [required("address", "address")],
+      {
+        address: { streetName: "", postalCode: "", city: "", countryCode: "" },
+      },
+    );
+    expect(issues).toEqual([{ message: REQUIRED, path: ["address"] }]);
+  });
+
+  it("puts the error of a localized field on the language it shows", async () => {
+    const issues = await issuesOf(
+      { title: z.record(z.string(), z.string()) },
+      [{ id: "title", type: "string", localized: true, required: true }],
+      { title: { en: "", fr: "" } },
+    );
+    expect(issues).toEqual([{ message: REQUIRED, path: ["title", "en"] }]);
+  });
+
+  it("takes 0 as a value", async () => {
+    const value = await valueOf(
+      { count: z.number() },
+      [required("count", "number")],
+      { count: 0 },
+    );
+    expect(value).toEqual({ count: 0 });
+  });
+
+  it("lists the issues in the order of the fields", async () => {
+    const issues = await issuesOf(
+      { email: z.string().email(), due: date(), name: z.string().min(1) },
+      [required("name"), required("email", "email"), required("due", "date")],
+      { email: "nope" },
+    );
+    expect(issues.map((issue) => issue.path[0])).toEqual([
+      "name",
+      "email",
+      "due",
+    ]);
+  });
+});
+
+describe("validateFormState: other errors", () => {
+  it("names the missing part of a partly filled address", async () => {
+    const issues = await issuesOf(
+      { address: address() },
+      [required("address", "address")],
+      {
+        address: {
+          streetName: "Rue Neuve",
+          postalCode: "",
+          city: "Brussels",
+          countryCode: "",
+        },
+      },
+    );
+    expect(issues).toEqual([
+      { message: REQUIRED, path: ["address", "postalCode"] },
+      { message: REQUIRED, path: ["address", "countryCode"] },
+    ]);
+  });
+
+  it("names the missing end of a half-picked range", async () => {
+    const issues = await issuesOf(
+      { vacation: dateRange() },
+      [required("vacation", "date")],
+      { vacation: { start: "2026-10-01" } },
+    );
+    expect(issues).toEqual([{ message: REQUIRED, path: ["vacation", "end"] }]);
+  });
+
+  it("accepts a range as { start, end } or as a list", async () => {
+    const fields = [required("vacation", "date")];
+    for (const vacation of [
+      { start: "2026-10-01", end: "2026-10-05" },
+      ["2026-10-01", "2026-10-05"],
+    ]) {
+      expect(
+        await issuesOf({ vacation: dateRange() }, fields, { vacation }),
+      ).toEqual([]);
+    }
+  });
+
+  it("keeps a type error once the field holds something", async () => {
+    const issues = await issuesOf(
+      { email: z.string().email() },
+      [required("email", "email")],
+      { email: "nope" },
+    );
+    expect(issues).toHaveLength(1);
+    expect(issues[0]!.path).toEqual(["email"]);
+    expect(issues[0]!.message).not.toBe(REQUIRED);
+  });
+});
+
+describe("validateFormState: an optional field left empty", () => {
+  const optionalField = (id: string, type?: string): FormValidationField => ({
+    id,
+    type,
+    required: false,
+  });
+
+  it("submits a cleared optional email as null instead of refusing it", async () => {
+    const value = await valueOf(
+      { email: optional(z.string().email()) },
+      [optionalField("email", "email")],
+      { email: "" },
+    );
+    expect(value).toEqual({ email: null });
+  });
+
+  it("submits an optional address of empty parts as null", async () => {
+    const value = await valueOf(
+      { address: optional(address()) },
+      [optionalField("address", "address")],
+      {
+        address: { streetName: "", postalCode: "", city: "", countryCode: "" },
+      },
+    );
+    expect(value).toEqual({ address: null });
+  });
+
+  it("keeps a blank optional text as it is when its type takes it", async () => {
+    const value = await valueOf(
+      { notes: optional(z.string()) },
+      [optionalField("notes", "string")],
+      { notes: "" },
+    );
+    expect(value).toEqual({ notes: "" });
+  });
+
+  it("reads a switch never touched as off", async () => {
+    const value = await valueOf(
+      { done: z.boolean() },
+      [optionalField("done", "boolean")],
+      {},
+    );
+    expect(value).toEqual({ done: false });
+  });
+
+  it("names the missing part of a partly filled optional address", async () => {
+    const issues = await issuesOf(
+      { address: optional(address()) },
+      [optionalField("address", "address")],
+      {
+        address: {
+          streetName: "Rue Neuve",
+          postalCode: "1000",
+          city: "",
+          countryCode: "BE",
+        },
+      },
+    );
+    expect(issues).toEqual([{ message: REQUIRED, path: ["address", "city"] }]);
+  });
+});
+
+describe("unwrapUnionIssue", () => {
+  it("keeps a union issue when several branches are of the value's type", () => {
+    const schema = z.union([z.string().email(), z.string().url()]);
+    const result = schema.safeParse("nope");
+    expect(result.success).toBe(false);
+    const [issue] = result.error!.issues;
+    expect(unwrapUnionIssue(issue!)).toEqual([issue]);
+  });
+
+  it("takes the issues of the one branch of the value's type", () => {
+    const schema = z.union([z.object({ a: z.string() }), z.null()]);
+    const result = schema.safeParse({});
+    const issues = result.error!.issues.flatMap(unwrapUnionIssue);
+    expect(issues.map((issue) => issue.path)).toEqual([["a"]]);
+  });
+});
+
+describe("validateFormState: errors a control reports", () => {
+  const DURATION = "Enter a duration such as 1h30m or 01:30.";
+
+  it("refuses the field with the control's message, before required", async () => {
+    const result = await validateFormState(
+      roundTrip({ duration: z.number(), name: optional(z.string()) }),
+      { duration: null },
+      {
+        fields: [
+          required("duration", "string_time"),
+          { id: "name", required: false },
+        ],
+        requiredMessage: REQUIRED,
+        controlErrors: new Map([["duration", DURATION]]),
+      },
+    );
+    expect("issues" in result && result.issues).toEqual([
+      { message: DURATION, path: ["duration"] },
+    ]);
+  });
+
+  it("leaves a field without one to the schema", async () => {
+    const result = await validateFormState(
+      roundTrip({ duration: optional(z.number()) }),
+      { duration: 5 },
+      {
+        fields: [{ id: "duration", required: false }],
+        requiredMessage: REQUIRED,
+        controlErrors: new Map(),
+      },
+    );
+    expect(result).toEqual({ value: { duration: 5 } });
+  });
+});
+
+describe("validateFormState: a box to tick", () => {
+  it("is missing until ticked when required", async () => {
+    const shape = { terms: z.literal(true) };
+    const field = { ...required("terms", "boolean"), acceptance: true };
+    expect(await issuesOf(shape, [field], { terms: false })).toEqual([
+      { message: REQUIRED, path: ["terms"] },
+    ]);
+    expect(await issuesOf(shape, [field], {})).toEqual([
+      { message: REQUIRED, path: ["terms"] },
+    ]);
+    expect(await valueOf(shape, [field], { terms: true })).toEqual({
+      terms: true,
+    });
+  });
+});

package/frontend-vue/tests/form-sections.test.ts

@@ -0,0 +1,94 @@
+import { describe, expect, it } from "vitest";
+import {
+  errorFieldId,
+  invalidFieldIds,
+  layoutSections,
+  resolveSectionNav,
+  sectionState,
+} from "../layers/dms-ui/app/build/composables/form/formSections";
+import type { FormFieldOrGroup } from "../layers/dms-ui/app/composables/form/types/field";
+
+const field = (id: string, label?: string) => ({
+  id,
+  label,
+  component: { componentName: "dms-input-text" },
+});
+
+const ENTRIES: FormFieldOrGroup[] = [
+  field("intro"),
+  field("name", "Name"),
+  { id: "contact", label: "Contact", fields: [field("email"), field("phone")] },
+  field("notes", "Notes"),
+];
+
+const SECTIONS = [
+  { id: "general", label: "General", fieldIds: ["name", "contact"] },
+  { id: "advanced", label: "Advanced", fieldIds: ["notes"] },
+];
+
+describe("form sections", () => {
+  it("lists the sections beside them from three sections, none below", () => {
+    expect(resolveSectionNav(undefined, 2)).toBe("none");
+    expect(resolveSectionNav(undefined, 3)).toBe("side");
+    expect(resolveSectionNav("jump", 5)).toBe("jump");
+    expect(resolveSectionNav("side", 1)).toBe("side");
+  });
+
+  it("puts each entry in its section, the others first", () => {
+    const layout = layoutSections(ENTRIES, SECTIONS);
+    expect(layout.lead.map((entry) => entry.id)).toEqual(["intro"]);
+    expect(
+      layout.sections.map((section) => [
+        section.id,
+        section.entries.map((entry) => entry.id),
+        section.fieldIds,
+      ]),
+    ).toEqual([
+      ["general", ["name", "contact"], ["name", "email", "phone"]],
+      ["advanced", ["notes"], ["notes"]],
+    ]);
+  });
+
+  it("skips a section entry the form does not hold", () => {
+    const layout = layoutSections(ENTRIES, [
+      { id: "s", label: "S", fieldIds: ["gone", "notes"] },
+    ]);
+    expect(layout.sections[0]?.entries.map((entry) => entry.id)).toEqual([
+      "notes",
+    ]);
+  });
+
+  it("gives an error to the field it names, or whose part it names", () => {
+    const ids = ["address", "title", "title2"];
+    expect(errorFieldId("address", ids)).toBe("address");
+    expect(errorFieldId("address.streetName", ids)).toBe("address");
+    expect(errorFieldId("title2.en", ids)).toBe("title2");
+    expect(errorFieldId("other", ids)).toBeUndefined();
+    expect(errorFieldId(undefined, ids)).toBeUndefined();
+  });
+
+  it("lists the invalid fields once each, in the form's order", () => {
+    const errors = [
+      { name: "notes" },
+      { name: "email.domain" },
+      { name: "notes" },
+      { name: "unknown" },
+      { name: "email" },
+    ];
+    expect(invalidFieldIds(errors, ["name", "email", "notes"])).toEqual([
+      "email",
+      "notes",
+    ]);
+  });
+
+  it("marks a section changed or invalid from its fields", () => {
+    const [general] = layoutSections(ENTRIES, SECTIONS).sections;
+    expect(sectionState(general!, new Set(["phone"]), new Set())).toEqual({
+      dirty: true,
+      invalidCount: 0,
+    });
+    expect(
+      sectionState(general!, new Set(), new Set(["name", "email", "notes"])),
+    ).toEqual({ dirty: false, invalidCount: 2 });
+  });
+});

package/frontend-vue/tests/form-server-field-errors.test.ts

@@ -0,0 +1,187 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { computed, effectScope, ref, watch, type EffectScope } from "vue";
+import {
+  type FormServerFieldError,
+  resolveFormFieldErrors,
+  useForm,
+} from "../layers/dms-ui/app/composables/form/useForm";
+
+const authFetch = vi.fn();
+const addToast = vi.fn();
+const showFieldErrors = vi.fn<(errors: FormServerFieldError[]) => boolean>();
+const hiddenFields = new Set<string>();
+let scope: EffectScope;
+
+const FIELDS = [
+  { id: "name", label: "Name", component: { componentName: "DmsInputText" } },
+  { id: "email", label: "Email", component: { componentName: "DmsInputText" } },
+  {
+    id: "code",
+    label: "Code",
+    disabled: true,
+    component: { componentName: "DmsInputText" },
+  },
+];
+
+/** What `assertValidation` answers: the ZodError's issues, as plain text. */
+const zodRefusal = (issues: unknown[]) => ({
+  statusCode: 400,
+  data: JSON.stringify(issues, null, 2),
+});
+
+function setupForm() {
+  return scope.run(() =>
+    useForm(
+      {
+        componentId: "form-1",
+        pageId: "page-1",
+        fields: FIELDS,
+        submitUrl: "/api/things/new",
+      } as never,
+      { showFieldErrors },
+    ),
+  )!;
+}
+
+const submit = (form: ReturnType<typeof setupForm>) =>
+  form.onSubmit({ data: { name: "", email: "taken@test.local" } } as never);
+
+beforeEach(() => {
+  scope = effectScope();
+  hiddenFields.clear();
+  showFieldErrors.mockReturnValue(true);
+  vi.stubGlobal("computed", computed);
+  vi.stubGlobal("ref", ref);
+  vi.stubGlobal("watch", watch);
+  vi.stubGlobal("isString", (value: unknown) => typeof value === "string");
+  vi.stubGlobal("Color", {
+    error: "error",
+    success: "success",
+    info: "info",
+  });
+  vi.stubGlobal("CONTENT_LANGUAGE_HEADER", "Content-Language");
+  vi.stubGlobal("useToast", () => ({ add: addToast }));
+  vi.stubGlobal("useAuthFetch", () => ({ $authFetch: authFetch }));
+  vi.stubGlobal("useDataTypes", () => ({ getDataType: () => undefined }));
+  vi.stubGlobal("useTranslation", () => ({
+    processI18n: (key: string) => key,
+    processApiMessage: (message: string) => `t(${message})`,
+  }));
+  vi.stubGlobal("useI18n", () => ({
+    t: (key: string, named?: Record<string, unknown>) =>
+      named ? `${key} ${JSON.stringify(named)}` : key,
+  }));
+  vi.stubGlobal("useDmsRoute", () => ({ query: {} }));
+  vi.stubGlobal("useComponentEvent", () => ({ sendComponentEvent: vi.fn() }));
+  vi.stubGlobal("useEventedAction", () => ({
+    execute: (action: () => Promise<unknown>) => action(),
+  }));
+  vi.stubGlobal(
+    "useWatch",
+    (_actions: unknown, _id: unknown, initial: Record<string, unknown>) => ({
+      isLoading: ref(false),
+      state: ref({ ...initial, hiddenFields }),
+    }),
+  );
+  vi.stubGlobal("navigateDms", vi.fn());
+});
+
+afterEach(() => {
+  scope.stop();
+  vi.unstubAllGlobals();
+  vi.resetAllMocks();
+});
+
+describe("DMS form server errors", () => {
+  it("puts a refused value under its field, without a toast", async () => {
+    authFetch.mockRejectedValue(
+      zodRefusal([
+        {
+          code: "too_small",
+          minimum: 1,
+          type: "string",
+          message: "String must contain at least 1 character(s)",
+          path: ["name"],
+        },
+      ]),
+    );
+    await submit(setupForm());
+
+    expect(showFieldErrors).toHaveBeenCalledExactlyOnceWith([
+      { name: "name", message: "t($dms.field_errors.required)" },
+    ]);
+    expect(addToast).not.toHaveBeenCalled();
+  });
+
+  it("names the values a refusal lists under the field", async () => {
+    authFetch.mockRejectedValue({
+      statusCode: 409,
+      data: {
+        message: "$taken",
+        field: "email",
+        values: ["taken@test.local"],
+      },
+    });
+    await submit(setupForm());
+
+    expect(showFieldErrors).toHaveBeenCalledExactlyOnceWith([
+      {
+        name: "email",
+        message: `dms.field_errors.with_values ${JSON.stringify({
+          message: "t($taken)",
+          values: "taken@test.local",
+        })}`,
+        values: ["taken@test.local"],
+      },
+    ]);
+    expect(addToast).not.toHaveBeenCalled();
+  });
+
+  it("keeps a failure tied to no field as a toast", async () => {
+    authFetch.mockRejectedValue({ statusCode: 500, data: "error.unexpected" });
+    await submit(setupForm());
+
+    expect(showFieldErrors).not.toHaveBeenCalled();
+    expect(addToast).toHaveBeenCalledExactlyOnceWith({
+      title: "$dms.form.error_title",
+      description: "t(error.unexpected)",
+      color: "error",
+    });
+  });
+
+  it("toasts a field error no rendered field could show", async () => {
+    showFieldErrors.mockReturnValue(false);
+    authFetch.mockRejectedValue({
+      statusCode: 400,
+      data: "Missing mandatory fields: name",
+    });
+    await submit(setupForm());
+
+    expect(showFieldErrors).toHaveBeenCalledOnce();
+    expect(addToast).toHaveBeenCalledOnce();
+  });
+
+  it("toasts an error on a hidden or disabled field", async () => {
+    hiddenFields.add("name");
+    authFetch.mockRejectedValue({
+      statusCode: 400,
+      data: "Missing mandatory fields: name, code",
+    });
+    await submit(setupForm());
+
+    expect(showFieldErrors).not.toHaveBeenCalled();
+    expect(addToast).toHaveBeenCalledOnce();
+  });
+});
+
+describe("resolveFormFieldErrors", () => {
+  it("only resolves to the fields the form shows", () => {
+    const error = {
+      statusCode: 400,
+      data: "Missing mandatory fields: name, email, code",
+    };
+    expect(
+      resolveFormFieldErrors(error, FIELDS, { hidden: new Set(["email"]) }),
+    ).toEqual([{ field: "name", message: "$dms.field_errors.required" }]);
+  });
+});