From dbf99b5a7ea6e71250035721b7446fa335b35ebc Mon Sep 17 00:00:00 2001
From: Alex Kanitz <alexanderkanitz@gmail.com>
Date: Fri, 13 Nov 2026 08:05:28 +0100
Subject: [PATCH 01/11] feat(design): add error states to form controls

Input, textarea, checkbox, select and multi-select get the properties
invalid and error. error shows a message under the control (part
"error", announced with aria-live="polite") and marks the control as
invalid: red border, aria-invalid and aria-describedby. The select
triggers take the state from their select and keep a screen reader
copy of the message, as aria-describedby can't cross shadow roots.

Refs #535

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../src/components/checkbox/checkbox.ts       |  26 ++-
 .../src/components/input/input.ts             |  23 ++-
 .../components/multi-select/multi-select.ts   |  33 +++-
 .../src/components/select/select.ts           |  34 +++-
 .../src/components/textarea/textarea.ts       |  23 ++-
 .../src/form-controls.test.ts                 | 157 ++++++++++++++++++
 6 files changed, 290 insertions(+), 6 deletions(-)
 create mode 100644 packages/ecc-utils-design/src/form-controls.test.ts

diff --git a/packages/ecc-utils-design/src/components/checkbox/checkbox.ts b/packages/ecc-utils-design/src/components/checkbox/checkbox.ts
index 8351f498..249de286 100644
--- a/packages/ecc-utils-design/src/components/checkbox/checkbox.ts
+++ b/packages/ecc-utils-design/src/components/checkbox/checkbox.ts
@@ -1,5 +1,6 @@
 import { LitElement, html, css } from "lit";
 import { property, state } from "lit/decorators.js";
+import { ifDefined } from "lit/directives/if-defined.js";
 import { ComponentStyles as TailwindStyles } from "./tw-styles.js";
 import { GlobalStyles } from "../../global.js";
 
@@ -21,13 +22,24 @@ export class EccUtilsDesignCheckbox extends LitElement {
   @property({ type: Boolean, reflect: true }) disabled = false;
   @property({ type: String }) name = "";
   @property({ type: String }) value = "";
+  /**
+   * Whether the value is invalid; also implied by a non-empty `error`.
+   */
+  @property({ type: Boolean, reflect: true }) invalid = false;
+  /** Error message shown under the checkbox, e.g. one returned by an API. */
+  @property({ type: String }) error = "";
   @state() private _focused = false;
 
   render() {
+    const isInvalid = this.invalid || !!this.error;
     const checkboxClasses = cn(
-      "peer h-4 w-4 shrink-0 rounded-[4px] border border-primary shadow focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:cursor-not-allowed disabled:opacity-50",
+      "peer h-4 w-4 shrink-0 rounded-[4px] border shadow focus-visible:outline-none focus-visible:ring-1 disabled:cursor-not-allowed disabled:opacity-50",
+      isInvalid
+        ? "border-destructive focus-visible:ring-destructive"
+        : "border-primary focus-visible:ring-ring",
       this.checked && "bg-primary text-primary-foreground",
-      this._focused && "ring-1 ring-ring"
+      this._focused &&
+        (isInvalid ? "ring-1 ring-destructive" : "ring-1 ring-ring")
     );
 
     const indicatorClasses = cn(
@@ -42,6 +54,8 @@ export class EccUtilsDesignCheckbox extends LitElement {
         role="checkbox"
         aria-checked=${this.checked ? "true" : "false"}
         aria-disabled=${this.disabled ? "true" : "false"}
+        aria-invalid=${ifDefined(isInvalid ? "true" : undefined)}
+        aria-describedby=${ifDefined(this.error ? "error" : undefined)}
         tabindex=${this.disabled ? "-1" : "0"}
         @click=${this._handleClick}
         @keydown=${this._handleKeydown}
@@ -63,6 +77,14 @@ export class EccUtilsDesignCheckbox extends LitElement {
           </svg>
         </div>
       </div>
+      <p
+        id="error"
+        part="error"
+        class=${cn("text-sm text-destructive", !!this.error && "mt-1.5")}
+        aria-live="polite"
+      >
+        ${this.error}
+      </p>
     `;
   }
 
diff --git a/packages/ecc-utils-design/src/components/input/input.ts b/packages/ecc-utils-design/src/components/input/input.ts
index 0d282ca1..e187afec 100644
--- a/packages/ecc-utils-design/src/components/input/input.ts
+++ b/packages/ecc-utils-design/src/components/input/input.ts
@@ -1,5 +1,6 @@
 import { LitElement, html, css } from "lit";
 import { property } from "lit/decorators.js";
+import { ifDefined } from "lit/directives/if-defined.js";
 import { ComponentStyles as TailwindStyles } from "./tw-styles.js";
 import { GlobalStyles } from "../../global.js";
 
@@ -38,10 +39,20 @@ export class EccUtilsDesignInput extends LitElement {
   @property({ type: String }) placeholder = "";
   @property({ type: String }) value = "";
   @property({ type: Boolean, reflect: true }) disabled = false;
+  /**
+   * Whether the value is invalid; also implied by a non-empty `error`.
+   */
+  @property({ type: Boolean, reflect: true }) invalid = false;
+  /** Error message shown under the field, e.g. one returned by an API. */
+  @property({ type: String }) error = "";
 
   render() {
+    const isInvalid = this.invalid || !!this.error;
     const classes = cn(
-      "flex h-9 w-full rounded-md border border-input bg-transparent px-3 py-1 text-base shadow-sm transition-colors file:border-0 file:bg-transparent file:text-sm file:font-medium file:text-foreground placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:cursor-not-allowed disabled:opacity-50 md:text-sm"
+      "flex h-9 w-full rounded-md border bg-transparent px-3 py-1 text-base shadow-sm transition-colors file:border-0 file:bg-transparent file:text-sm file:font-medium file:text-foreground placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-1 disabled:cursor-not-allowed disabled:opacity-50 md:text-sm",
+      isInvalid
+        ? "border-destructive focus-visible:ring-destructive"
+        : "border-input focus-visible:ring-ring"
     );
 
     return html`
@@ -52,8 +63,18 @@ export class EccUtilsDesignInput extends LitElement {
         placeholder=${this.placeholder}
         .value=${this.value}
         ?disabled=${this.disabled}
+        aria-invalid=${ifDefined(isInvalid ? "true" : undefined)}
+        aria-describedby=${ifDefined(this.error ? "error" : undefined)}
         @input=${this._handleInput}
       />
+      <p
+        id="error"
+        part="error"
+        class=${cn("text-sm text-destructive", !!this.error && "mt-1.5")}
+        aria-live="polite"
+      >
+        ${this.error}
+      </p>
     `;
   }
 
diff --git a/packages/ecc-utils-design/src/components/multi-select/multi-select.ts b/packages/ecc-utils-design/src/components/multi-select/multi-select.ts
index 2f8b228d..2101c63e 100644
--- a/packages/ecc-utils-design/src/components/multi-select/multi-select.ts
+++ b/packages/ecc-utils-design/src/components/multi-select/multi-select.ts
@@ -1,5 +1,6 @@
 import { LitElement, html, css, PropertyValues } from "lit";
 import { property, state } from "lit/decorators.js";
+import { ifDefined } from "lit/directives/if-defined.js";
 import { ComponentStyles as TailwindStyles } from "./tw-styles.js";
 import { GlobalStyles } from "../../global.js";
 import "../checkbox/index.js";
@@ -47,6 +48,12 @@ export class EccUtilsDesignMultiSelect extends LitElement {
   @property({ type: Array }) value: string[] = [];
   @property({ type: String }) placeholder = "Select options...";
   @property({ type: Boolean }) disabled = false;
+  /**
+   * Whether the value is invalid; also implied by a non-empty `error`.
+   */
+  @property({ type: Boolean, reflect: true }) invalid = false;
+  /** Error message shown under the select, e.g. one returned by an API. */
+  @property({ type: String }) error = "";
   @property({ type: String }) name = "";
 
   @state() private isOpen = false;
@@ -70,6 +77,12 @@ export class EccUtilsDesignMultiSelect extends LitElement {
   }
 
   updated(changedProperties: PropertyValues) {
+    if (changedProperties.has("invalid") || changedProperties.has("error")) {
+      // The trigger shows the invalid state of the select
+      this.querySelectorAll("ecc-utils-design-multi-select-trigger").forEach(
+        (trigger) => trigger.requestUpdate()
+      );
+    }
     if (changedProperties.has("value") || changedProperties.has("isOpen")) {
       multiSelectState.set(this.selectId, {
         ...multiSelectState.get(this.selectId)!,
@@ -134,6 +147,14 @@ export class EccUtilsDesignMultiSelect extends LitElement {
       >
         <slot></slot>
       </div>
+      <p
+        id="error"
+        part="error"
+        class=${cn("text-sm text-destructive", !!this.error && "mt-1.5")}
+        aria-live="polite"
+      >
+        ${this.error}
+      </p>
     `;
   }
 }
@@ -227,20 +248,30 @@ export class EccUtilsDesignMultiSelectTrigger extends LitElement {
   render() {
     const select = this._getParentSelect();
     const placeholder = select?.placeholder || "Select options...";
+    const error = select?.error ?? "";
+    const isInvalid = !!select && (select.invalid || !!error);
 
     const classes = cn(
-      "flex h-9 w-full items-center justify-between whitespace-nowrap rounded-md border border-input bg-transparent px-3 py-2 text-sm shadow-sm ring-offset-background focus:outline-none focus:ring-1 focus:ring-ring disabled:cursor-not-allowed disabled:opacity-50",
+      "flex h-9 w-full items-center justify-between whitespace-nowrap rounded-md border bg-transparent px-3 py-2 text-sm shadow-sm ring-offset-background focus:outline-none focus:ring-1 disabled:cursor-not-allowed disabled:opacity-50",
+      isInvalid
+        ? "border-destructive focus:ring-destructive"
+        : "border-input focus:ring-ring",
       this.disabled && "opacity-50 cursor-not-allowed"
     );
 
     const hasSelection = this.selectedValues.length > 0;
 
+    // The multi-select shows the error; the trigger has a copy for screen
+    // readers, as `aria-describedby` can't refer to another shadow root
     return html`
+      <span id="error" class="sr-only">${error}</span>
       <button
         part="base"
         type="button"
         class=${classes}
         ?disabled=${this.disabled}
+        aria-invalid=${ifDefined(isInvalid ? "true" : undefined)}
+        aria-describedby=${ifDefined(error ? "error" : undefined)}
         data-state=${this.isOpen ? "open" : "closed"}
         @click=${this._handleClick}
       >
diff --git a/packages/ecc-utils-design/src/components/select/select.ts b/packages/ecc-utils-design/src/components/select/select.ts
index e716770a..a109e6b3 100644
--- a/packages/ecc-utils-design/src/components/select/select.ts
+++ b/packages/ecc-utils-design/src/components/select/select.ts
@@ -1,5 +1,6 @@
 import { LitElement, html, css, PropertyValues } from "lit";
 import { property, state } from "lit/decorators.js";
+import { ifDefined } from "lit/directives/if-defined.js";
 import { ComponentStyles as TailwindStyles } from "./tw-styles.js";
 import { GlobalStyles } from "../../global.js";
 
@@ -36,6 +37,12 @@ export class EccUtilsDesignSelect extends LitElement {
 
   @property({ type: String }) value = "";
   @property({ type: Boolean }) disabled = false;
+  /**
+   * Whether the value is invalid; also implied by a non-empty `error`.
+   */
+  @property({ type: Boolean, reflect: true }) invalid = false;
+  /** Error message shown under the select, e.g. one returned by an API. */
+  @property({ type: String }) error = "";
 
   @state() private isOpen = false;
 
@@ -58,6 +65,12 @@ export class EccUtilsDesignSelect extends LitElement {
   }
 
   updated(changedProperties: PropertyValues) {
+    if (changedProperties.has("invalid") || changedProperties.has("error")) {
+      // The trigger shows the invalid state of the select
+      this.querySelectorAll("ecc-utils-design-select-trigger").forEach(
+        (trigger) => trigger.requestUpdate()
+      );
+    }
     if (changedProperties.has("value") || changedProperties.has("isOpen")) {
       selectState.set(this.selectId, {
         ...selectState.get(this.selectId)!,
@@ -114,6 +127,14 @@ export class EccUtilsDesignSelect extends LitElement {
       >
         <slot></slot>
       </div>
+      <p
+        id="error"
+        part="error"
+        class=${cn("text-sm text-destructive", !!this.error && "mt-1.5")}
+        aria-live="polite"
+      >
+        ${this.error}
+      </p>
     `;
   }
 }
@@ -147,17 +168,28 @@ export class EccUtilsDesignSelectTrigger extends LitElement {
   }
 
   render() {
+    const select = this._getParentSelect();
+    const error = select?.error ?? "";
+    const isInvalid = !!select && (select.invalid || !!error);
     const classes = cn(
-      "flex h-9 w-full items-center justify-between whitespace-nowrap rounded-md border border-input bg-transparent px-3 py-2 text-sm shadow-sm ring-offset-background focus:outline-none focus:ring-1 focus:ring-ring disabled:cursor-not-allowed disabled:opacity-50 [&>span]:line-clamp-1",
+      "flex h-9 w-full items-center justify-between whitespace-nowrap rounded-md border bg-transparent px-3 py-2 text-sm shadow-sm ring-offset-background focus:outline-none focus:ring-1 disabled:cursor-not-allowed disabled:opacity-50 [&>span]:line-clamp-1",
+      isInvalid
+        ? "border-destructive focus:ring-destructive"
+        : "border-input focus:ring-ring",
       this.disabled && "opacity-50 cursor-not-allowed"
     );
 
+    // The select shows the error; the trigger has a copy for screen
+    // readers, as `aria-describedby` can't refer to another shadow root
     return html`
+      <span id="error" class="sr-only">${error}</span>
       <button
         part="base"
         type="button"
         class=${classes}
         ?disabled=${this.disabled}
+        aria-invalid=${ifDefined(isInvalid ? "true" : undefined)}
+        aria-describedby=${ifDefined(error ? "error" : undefined)}
         data-state=${this.isOpen ? "open" : "closed"}
         @click=${this._handleClick}
       >
diff --git a/packages/ecc-utils-design/src/components/textarea/textarea.ts b/packages/ecc-utils-design/src/components/textarea/textarea.ts
index a56bd7e4..c15ac59c 100644
--- a/packages/ecc-utils-design/src/components/textarea/textarea.ts
+++ b/packages/ecc-utils-design/src/components/textarea/textarea.ts
@@ -1,5 +1,6 @@
 import { LitElement, html, css } from "lit";
 import { property } from "lit/decorators.js";
+import { ifDefined } from "lit/directives/if-defined.js";
 import { ComponentStyles as TailwindStyles } from "./tw-styles.js";
 import { GlobalStyles } from "../../global.js";
 
@@ -20,12 +21,22 @@ export class EccUtilsDesignTextarea extends LitElement {
   @property({ type: String }) placeholder = "";
   @property({ type: String }) value = "";
   @property({ type: Boolean, reflect: true }) disabled = false;
+  /**
+   * Whether the value is invalid; also implied by a non-empty `error`.
+   */
+  @property({ type: Boolean, reflect: true }) invalid = false;
+  /** Error message shown under the field, e.g. one returned by an API. */
+  @property({ type: String }) error = "";
   @property({ type: Number }) rows = 3;
   @property({ type: Number }) cols?: number;
 
   render() {
+    const isInvalid = this.invalid || !!this.error;
     const classes = cn(
-      "flex min-h-[60px] w-full rounded-md border border-input bg-transparent px-3 py-2 text-base shadow-sm placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:cursor-not-allowed disabled:opacity-50 md:text-sm"
+      "flex min-h-[60px] w-full rounded-md border bg-transparent px-3 py-2 text-base shadow-sm placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-1 disabled:cursor-not-allowed disabled:opacity-50 md:text-sm",
+      isInvalid
+        ? "border-destructive focus-visible:ring-destructive"
+        : "border-input focus-visible:ring-ring"
     );
 
     return html`
@@ -35,10 +46,20 @@ export class EccUtilsDesignTextarea extends LitElement {
         placeholder=${this.placeholder}
         .value=${this.value}
         ?disabled=${this.disabled}
+        aria-invalid=${ifDefined(isInvalid ? "true" : undefined)}
+        aria-describedby=${ifDefined(this.error ? "error" : undefined)}
         rows=${this.rows}
         cols=${this.cols || ""}
         @input=${this._handleInput}
       ></textarea>
+      <p
+        id="error"
+        part="error"
+        class=${cn("text-sm text-destructive", !!this.error && "mt-1.5")}
+        aria-live="polite"
+      >
+        ${this.error}
+      </p>
     `;
   }
 
diff --git a/packages/ecc-utils-design/src/form-controls.test.ts b/packages/ecc-utils-design/src/form-controls.test.ts
new file mode 100644
index 00000000..2a0487e8
--- /dev/null
+++ b/packages/ecc-utils-design/src/form-controls.test.ts
@@ -0,0 +1,157 @@
+/* eslint-disable import/no-extraneous-dependencies */
+import { expect, fixture, html } from "@open-wc/testing";
+import type { LitElement } from "lit";
+import "./components/input/index.js";
+import "./components/textarea/index.js";
+import "./components/checkbox/index.js";
+import "./components/select/index.js";
+import "./components/multi-select/index.js";
+import type { EccUtilsDesignSelect } from "./components/select/index.js";
+import type { EccUtilsDesignMultiSelect } from "./components/multi-select/index.js";
+
+type FormControl = LitElement & { invalid: boolean; error: string };
+
+// The element that gets `aria-invalid` and `aria-describedby`
+const controls: [string, () => Promise<FormControl>, string][] = [
+  [
+    "input",
+    () => fixture(html`<ecc-utils-design-input></ecc-utils-design-input>`),
+    "input",
+  ],
+  [
+    "textarea",
+    () =>
+      fixture(html`<ecc-utils-design-textarea></ecc-utils-design-textarea>`),
+    "textarea",
+  ],
+  [
+    "checkbox",
+    () =>
+      fixture(html`<ecc-utils-design-checkbox></ecc-utils-design-checkbox>`),
+    "[role=checkbox]",
+  ],
+];
+
+function errorElement(el: LitElement): HTMLElement {
+  return el.shadowRoot!.querySelector("[part=error]") as HTMLElement;
+}
+
+describe("form controls: invalid state and error message", () => {
+  controls.forEach(([name, create, selector]) => {
+    describe(name, () => {
+      it("is valid by default, with an empty live region", async () => {
+        const el = await create();
+        const control = el.shadowRoot!.querySelector(selector)!;
+        expect(control.hasAttribute("aria-invalid")).to.equal(false);
+        expect(control.hasAttribute("aria-describedby")).to.equal(false);
+        expect(errorElement(el).textContent?.trim()).to.equal("");
+        expect(errorElement(el).getAttribute("aria-live")).to.equal("polite");
+      });
+
+      it("shows the error under the control", async () => {
+        const el = await create();
+        el.error = "Must be a valid URI.";
+        await el.updateComplete;
+        const control = el.shadowRoot!.querySelector(selector)!;
+        const message = errorElement(el);
+        expect(message.textContent?.trim()).to.equal("Must be a valid URI.");
+        expect(control.getAttribute("aria-invalid")).to.equal("true");
+        expect(control.getAttribute("aria-describedby")).to.equal(message.id);
+        expect(control.className).to.contain("border-destructive");
+      });
+
+      it("can be invalid without a message", async () => {
+        const el = await create();
+        el.invalid = true;
+        await el.updateComplete;
+        const control = el.shadowRoot!.querySelector(selector)!;
+        expect(el.hasAttribute("invalid")).to.equal(true);
+        expect(control.getAttribute("aria-invalid")).to.equal("true");
+        expect(control.hasAttribute("aria-describedby")).to.equal(false);
+        expect(control.className).to.contain("border-destructive");
+      });
+
+      it("clears the error", async () => {
+        const el = await create();
+        el.error = "Is required.";
+        await el.updateComplete;
+        el.error = "";
+        await el.updateComplete;
+        const control = el.shadowRoot!.querySelector(selector)!;
+        expect(control.hasAttribute("aria-invalid")).to.equal(false);
+        expect(errorElement(el).textContent?.trim()).to.equal("");
+        expect(control.className).to.not.contain("border-destructive");
+      });
+    });
+  });
+
+  it("takes the error from the attribute", async () => {
+    const el = await fixture<FormControl>(
+      html`<ecc-utils-design-input
+        error="Is required."
+      ></ecc-utils-design-input>`
+    );
+    expect(errorElement(el).textContent?.trim()).to.equal("Is required.");
+  });
+
+  const selects: [string, () => Promise<FormControl>, string][] = [
+    [
+      "select",
+      () =>
+        fixture<EccUtilsDesignSelect>(html`
+          <ecc-utils-design-select>
+            <ecc-utils-design-select-trigger>
+              <ecc-utils-design-select-value></ecc-utils-design-select-value>
+            </ecc-utils-design-select-trigger>
+          </ecc-utils-design-select>
+        `),
+      "ecc-utils-design-select-trigger",
+    ],
+    [
+      "multi-select",
+      () =>
+        fixture<EccUtilsDesignMultiSelect>(html`
+          <ecc-utils-design-multi-select>
+            <ecc-utils-design-multi-select-trigger></ecc-utils-design-multi-select-trigger>
+          </ecc-utils-design-multi-select>
+        `),
+      "ecc-utils-design-multi-select-trigger",
+    ],
+  ];
+
+  selects.forEach(([name, create, triggerTag]) => {
+    describe(name, () => {
+      it("shows the error and marks the trigger invalid", async () => {
+        const el = await create();
+        const trigger = el.querySelector(triggerTag) as LitElement;
+        const button = () => trigger.shadowRoot!.querySelector("button")!;
+        expect(button().hasAttribute("aria-invalid")).to.equal(false);
+
+        el.error = "Must be one of: a, b.";
+        await el.updateComplete;
+        await trigger.updateComplete;
+        expect(errorElement(el).textContent?.trim()).to.equal(
+          "Must be one of: a, b."
+        );
+        expect(button().getAttribute("aria-invalid")).to.equal("true");
+        const describedBy = button().getAttribute("aria-describedby")!;
+        expect(
+          trigger.shadowRoot!.getElementById(describedBy)!.textContent?.trim()
+        ).to.equal("Must be one of: a, b.");
+        expect(button().className).to.contain("border-destructive");
+
+        el.error = "";
+        await el.updateComplete;
+        await trigger.updateComplete;
+        expect(button().hasAttribute("aria-invalid")).to.equal(false);
+        expect(button().className).to.not.contain("border-destructive");
+
+        el.invalid = true;
+        await el.updateComplete;
+        await trigger.updateComplete;
+        expect(button().getAttribute("aria-invalid")).to.equal("true");
+        expect(button().hasAttribute("aria-describedby")).to.equal(false);
+      });
+    });
+  });
+});

From 3aee48853278897a2774ce0d8e96889f62992381 Mon Sep 17 00:00:00 2001
From: Alex Kanitz <alexanderkanitz@gmail.com>
Date: Fri, 13 Nov 2026 08:10:47 +0100
Subject: [PATCH 02/11] feat(design): map problem details to form fields

Add server-agnostic utilities for RFC 9457 problem details:
readProblemDetails() and parseProblemDetails() read the standard
members, the field errors (errors[] with detail and pointer, as in the
RFC's example; plain pointers and parameter accepted) and the extension
members; mapFieldErrors() maps the errors to a component's fields by
pointer or parameter (closest containing field otherwise) and gives a
general error for the rest, for problem details without errors and for
other responses.

Refs #535

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 packages/ecc-utils-design/src/index.ts        |   1 +
 packages/ecc-utils-design/src/utils/index.ts  |   1 +
 .../src/utils/problem-details.test.ts         | 283 ++++++++++++++++
 .../src/utils/problem-details.ts              | 319 ++++++++++++++++++
 4 files changed, 604 insertions(+)
 create mode 100644 packages/ecc-utils-design/src/utils/index.ts
 create mode 100644 packages/ecc-utils-design/src/utils/problem-details.test.ts
 create mode 100644 packages/ecc-utils-design/src/utils/problem-details.ts

diff --git a/packages/ecc-utils-design/src/index.ts b/packages/ecc-utils-design/src/index.ts
index 96a7338f..7682ecb1 100644
--- a/packages/ecc-utils-design/src/index.ts
+++ b/packages/ecc-utils-design/src/index.ts
@@ -2,3 +2,4 @@ import "./components/index.js";
 import "./events/index.js";
 
 export * from "./components/index.js";
+export * from "./utils/index.js";
diff --git a/packages/ecc-utils-design/src/utils/index.ts b/packages/ecc-utils-design/src/utils/index.ts
new file mode 100644
index 00000000..d508a2cc
--- /dev/null
+++ b/packages/ecc-utils-design/src/utils/index.ts
@@ -0,0 +1 @@
+export * from "./problem-details.js";
diff --git a/packages/ecc-utils-design/src/utils/problem-details.test.ts b/packages/ecc-utils-design/src/utils/problem-details.test.ts
new file mode 100644
index 00000000..912aae4f
--- /dev/null
+++ b/packages/ecc-utils-design/src/utils/problem-details.test.ts
@@ -0,0 +1,283 @@
+/* eslint-disable import/no-extraneous-dependencies */
+import { expect } from "@open-wc/testing";
+import {
+  mapFieldErrors,
+  normalizePointer,
+  parseProblemDetails,
+  readProblemDetails,
+} from "./index.js";
+
+// The example of RFC 9457, section 3, with FOCA's `code` members
+const RFC_EXAMPLE = {
+  type: "https://example.net/validation-error",
+  title: "Your request is not valid.",
+  status: 400,
+  code: "invalid-request",
+  errors: [
+    {
+      detail: "must be a positive integer",
+      pointer: "#/age",
+      code: "too-small",
+    },
+    {
+      detail: "must be 'green', 'red' or 'blue'",
+      pointer: "#/profile/color",
+    },
+  ],
+};
+
+describe("normalizePointer()", () => {
+  it("accepts URI fragments and plain pointers", () => {
+    expect(normalizePointer("#/organization/url")).to.equal(
+      "/organization/url"
+    );
+    expect(normalizePointer("/organization/url")).to.equal("/organization/url");
+    expect(normalizePointer("#")).to.equal("");
+    expect(normalizePointer("")).to.equal("");
+  });
+
+  it("decodes percent-encoded fragments and keeps RFC 6901 escapes", () => {
+    expect(normalizePointer("#/a%20b/c~1d")).to.equal("/a b/c~1d");
+  });
+
+  it("rejects what isn't a pointer", () => {
+    expect(normalizePointer("organization/url")).to.equal(undefined);
+    expect(normalizePointer("#organization")).to.equal(undefined);
+    expect(normalizePointer("#/%E0%A4%A")).to.equal(undefined);
+  });
+});
+
+describe("parseProblemDetails()", () => {
+  it("parses the standard members, errors and extensions", () => {
+    const problem = parseProblemDetails({
+      ...RFC_EXAMPLE,
+      detail: "Invalid fields",
+      instance: "/requests/1",
+    });
+    expect(problem).to.deep.include({
+      type: RFC_EXAMPLE.type,
+      title: RFC_EXAMPLE.title,
+      status: 400,
+      detail: "Invalid fields",
+      instance: "/requests/1",
+      extensions: { code: "invalid-request" },
+    });
+    expect(
+      problem?.errors.map(({ detail, pointer, code }) => ({
+        detail,
+        pointer,
+        code,
+      }))
+    ).to.deep.equal([
+      {
+        detail: "must be a positive integer",
+        pointer: "/age",
+        code: "too-small",
+      },
+      {
+        detail: "must be 'green', 'red' or 'blue'",
+        pointer: "/profile/color",
+        code: undefined,
+      },
+    ]);
+    expect(problem?.errors[0].raw).to.equal(RFC_EXAMPLE.errors[0]);
+  });
+
+  it("accepts parameters and plain pointers", () => {
+    const problem = parseProblemDetails({
+      status: 400,
+      errors: [
+        { detail: "Must be at most 10.", parameter: "limit" },
+        { detail: "Is required.", pointer: "/url" },
+      ],
+    });
+    expect(problem?.errors[0].parameter).to.equal("limit");
+    expect(problem?.errors[0].pointer).to.equal(undefined);
+    expect(problem?.errors[1].pointer).to.equal("/url");
+  });
+
+  it("defaults the type and ignores members of the wrong type", () => {
+    const problem = parseProblemDetails({
+      title: 1,
+      status: "400",
+      detail: "Bad",
+      errors: "none",
+    });
+    expect(problem).to.deep.include({
+      type: "about:blank",
+      title: undefined,
+      status: undefined,
+      detail: "Bad",
+      errors: [],
+    });
+  });
+
+  it("skips entries without a readable detail", () => {
+    const problem = parseProblemDetails({
+      errors: [null, "x", { pointer: "#/a" }, { detail: "", pointer: "#/a" }],
+    });
+    expect(problem?.errors).to.deep.equal([]);
+  });
+
+  it("keeps entries with an invalid pointer, without a location", () => {
+    const problem = parseProblemDetails({
+      errors: [{ detail: "Bad.", pointer: "a" }],
+    });
+    expect(problem?.errors[0].pointer).to.equal(undefined);
+    expect(problem?.errors[0].parameter).to.equal(undefined);
+  });
+
+  it("returns undefined for bodies that aren't problem details", () => {
+    expect(parseProblemDetails(undefined)).to.equal(undefined);
+    expect(parseProblemDetails("Bad Request")).to.equal(undefined);
+    expect(parseProblemDetails([RFC_EXAMPLE])).to.equal(undefined);
+    expect(parseProblemDetails({ message: "Bad" })).to.equal(undefined);
+  });
+});
+
+describe("readProblemDetails()", () => {
+  const response = (body: string, contentType: string) =>
+    new Response(body, {
+      status: 400,
+      headers: { "Content-Type": contentType },
+    });
+
+  it("reads problem+json and JSON bodies", async () => {
+    const body = JSON.stringify(RFC_EXAMPLE);
+    const problem = await readProblemDetails(
+      response(body, "application/problem+json; charset=utf-8")
+    );
+    expect(problem?.errors).to.have.length(2);
+    expect(
+      await readProblemDetails(response(body, "application/json"))
+    ).to.not.equal(undefined);
+  });
+
+  it("returns undefined for other bodies", async () => {
+    expect(
+      await readProblemDetails(response("Bad Request", "text/plain"))
+    ).to.equal(undefined);
+    expect(
+      await readProblemDetails(response("{not json", "application/json"))
+    ).to.equal(undefined);
+  });
+});
+
+describe("mapFieldErrors()", () => {
+  const fields = {
+    age: "#/age",
+    color: "/profile/color",
+    tags: "/tags",
+    limit: { parameter: "limit" },
+    url: { pointer: "#/url" },
+  };
+
+  it("maps errors to fields by pointer", () => {
+    const mapped = mapFieldErrors(RFC_EXAMPLE, fields);
+    expect(mapped.fieldErrors).to.deep.equal({
+      age: "must be a positive integer",
+      color: "must be 'green', 'red' or 'blue'",
+    });
+    expect(mapped.unmatched).to.deep.equal([]);
+    expect(mapped.generalError).to.equal(undefined);
+    expect(mapped.problem?.extensions.code).to.equal("invalid-request");
+  });
+
+  it("maps parameters, object locations and contained fields", () => {
+    const mapped = mapFieldErrors(
+      {
+        errors: [
+          { detail: "Too large.", parameter: "limit" },
+          { detail: "Is required.", pointer: "#/url" },
+          { detail: "Too long.", pointer: "#/tags/0" },
+          { detail: "Duplicate.", pointer: "#/tags/1" },
+        ],
+      },
+      fields
+    );
+    expect(mapped.fieldErrors).to.deep.equal({
+      limit: "Too large.",
+      url: "Is required.",
+      tags: "Too long. Duplicate.",
+    });
+    expect(mapped.generalError).to.equal(undefined);
+  });
+
+  it("prefers the closest containing field", () => {
+    const mapped = mapFieldErrors(
+      { errors: [{ detail: "Bad.", pointer: "#/a/b/c" }] },
+      { a: "/a", ab: "/a/b", abc2: "/a/bc" }
+    );
+    expect(mapped.fieldErrors).to.deep.equal({ ab: "Bad." });
+  });
+
+  it("reports unknown pointers and parameters as a general error", () => {
+    const mapped = mapFieldErrors(
+      {
+        detail: "Invalid fields",
+        errors: [
+          { detail: "Is required.", pointer: "#/age" },
+          { detail: "Unknown.", pointer: "#/organization/url" },
+          { detail: "Unknown parameter.", parameter: "page" },
+          { detail: "Not an object.", pointer: "#" },
+          { detail: "Somewhere.", pointer: "nowhere" },
+        ],
+      },
+      fields
+    );
+    expect(mapped.fieldErrors).to.deep.equal({ age: "Is required." });
+    expect(mapped.unmatched).to.have.length(4);
+    expect(mapped.generalError).to.equal(
+      "organization/url: Unknown. page: Unknown parameter. Not an object. Somewhere."
+    );
+  });
+
+  it("doesn't map body errors to parameters or vice versa", () => {
+    const mapped = mapFieldErrors(
+      {
+        errors: [
+          { detail: "A.", pointer: "#/limit" },
+          { detail: "B.", parameter: "age" },
+        ],
+      },
+      fields
+    );
+    expect(mapped.fieldErrors).to.deep.equal({});
+    expect(mapped.unmatched).to.have.length(2);
+  });
+
+  it("ignores fields with invalid locations", () => {
+    const mapped = mapFieldErrors(
+      { errors: [{ detail: "A.", pointer: "#/age" }] },
+      { age: "age", other: { pointer: "x" } }
+    );
+    expect(mapped.fieldErrors).to.deep.equal({});
+    expect(mapped.generalError).to.equal("age: A.");
+  });
+
+  it("falls back to detail, title or the fallback without errors", () => {
+    expect(
+      mapFieldErrors({ title: "Bad Request", detail: "No." }, fields)
+        .generalError
+    ).to.equal("No.");
+    expect(
+      mapFieldErrors({ title: "Bad Request", errors: [] }, fields).generalError
+    ).to.equal("Bad Request");
+    expect(mapFieldErrors({ status: 500 }, fields).generalError).to.equal(
+      "The request failed."
+    );
+    const notProblem = mapFieldErrors("Internal Server Error", fields, "Oops.");
+    expect(notProblem.problem).to.equal(undefined);
+    expect(notProblem.generalError).to.equal("Oops.");
+    expect(mapFieldErrors(undefined, fields).generalError).to.equal(
+      "The request failed."
+    );
+  });
+
+  it("accepts problem details parsed already", () => {
+    const problem = parseProblemDetails(RFC_EXAMPLE);
+    const mapped = mapFieldErrors(problem, fields);
+    expect(mapped.problem).to.equal(problem);
+    expect(mapped.fieldErrors.age).to.equal("must be a positive integer");
+  });
+});
diff --git a/packages/ecc-utils-design/src/utils/problem-details.ts b/packages/ecc-utils-design/src/utils/problem-details.ts
new file mode 100644
index 00000000..22cc68b0
--- /dev/null
+++ b/packages/ecc-utils-design/src/utils/problem-details.ts
@@ -0,0 +1,319 @@
+/**
+ * Problem details (RFC 9457, `application/problem+json`) and their field
+ * errors, for components that submit data to an API and show its errors at
+ * their form fields.
+ *
+ * Nothing here is specific to a server: field errors are read in the form of
+ * the example of RFC 9457, section 3 (`errors[]` with `detail` and
+ * `pointer`, a JSON Pointer in URI fragment form like `#/organization/url`),
+ * with plain JSON Pointers like `/organization/url` and `parameter` (the
+ * name of a query, path, header or cookie parameter) accepted too.
+ */
+
+/** A field error: one entry of the `errors` member of problem details. */
+export interface ProblemFieldError {
+  /** Readable message, e.g. `Must be a valid URI.` */
+  detail: string;
+  /**
+   * The field in the request body as a plain JSON Pointer (RFC 6901), e.g.
+   * `/organization/url`, decoded from the URI fragment form (`""` for the
+   * whole body). Absent for parameters and entries without a location.
+   */
+  pointer?: string;
+  /** Name of the request parameter, e.g. `limit`. */
+  parameter?: string;
+  /** Machine-readable code of what is wrong, e.g. `too-long`, if any. */
+  code?: string;
+  /** All members of the entry as received, including extension members. */
+  raw: Record<string, unknown>;
+}
+
+/** Problem details (RFC 9457), with their field errors. */
+export interface ProblemDetails {
+  /** Problem type URI; `about:blank` if absent, as per RFC 9457. */
+  type: string;
+  /** Short summary of the problem type. */
+  title?: string;
+  /** HTTP status code. */
+  status?: number;
+  /** Explanation of this occurrence of the problem. */
+  detail?: string;
+  /** URI of this occurrence of the problem. */
+  instance?: string;
+  /** Field errors with a readable `detail`; empty if there are none. */
+  errors: ProblemFieldError[];
+  /**
+   * Extension members, e.g. `code`, as received (all members but `type`,
+   * `title`, `status`, `detail`, `instance` and `errors`).
+   */
+  extensions: Record<string, unknown>;
+}
+
+/**
+ * Location of a form field in a request: a JSON Pointer to it in the request
+ * body (plain, e.g. `/organization/url`, or in URI fragment form, e.g.
+ * `#/organization/url`), or `{ parameter: "<name>" }` for a request
+ * parameter.
+ */
+export type FieldLocation =
+  | string
+  | { pointer: string }
+  | { parameter: string };
+
+/** Problem details mapped to the fields of a form. */
+export interface MappedFieldErrors {
+  /** The parsed problem details; `undefined` if the body isn't any. */
+  problem: ProblemDetails | undefined;
+  /**
+   * Message per field key (the keys of the `fields` passed), for fields with
+   * errors only. Several messages for the same field are joined by a space.
+   */
+  fieldErrors: Record<string, string>;
+  /** Field errors that match no field. */
+  unmatched: ProblemFieldError[];
+  /**
+   * Message to show as a general error, or `undefined` if every error is
+   * shown at a field: the `detail` (or else the `title`) of problem details
+   * without field errors, or the fallback for responses that aren't problem
+   * details; otherwise the field errors that match no field, each with its
+   * location (e.g. `organization/url: Is required.`).
+   */
+  generalError: string | undefined;
+}
+
+// Problem details returned by `parseProblemDetails()`, so that
+// `mapFieldErrors()` can tell them from response bodies
+const parsedProblems = new WeakSet<object>();
+
+function isParsedProblem(value: unknown): value is ProblemDetails {
+  return (
+    typeof value === "object" && value !== null && parsedProblems.has(value)
+  );
+}
+
+const STANDARD_MEMBERS = new Set([
+  "type",
+  "title",
+  "status",
+  "detail",
+  "instance",
+  "errors",
+]);
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function optionalString(value: unknown): string | undefined {
+  return typeof value === "string" ? value : undefined;
+}
+
+/**
+ * Normalize a JSON Pointer to its plain form (RFC 6901).
+ *
+ * @param pointer - Pointer in plain form (`/a/b`, `""` for the whole
+ *   document) or in URI fragment form (`#/a/b`, `#` for the whole document;
+ *   percent-encoded characters are decoded).
+ * @returns The plain pointer, or `undefined` if `pointer` is neither.
+ */
+export function normalizePointer(pointer: string): string | undefined {
+  let plain = pointer;
+  if (pointer.startsWith("#")) {
+    try {
+      plain = decodeURIComponent(pointer.slice(1));
+    } catch {
+      return undefined;
+    }
+  }
+  if (plain !== "" && !plain.startsWith("/")) return undefined;
+  return plain;
+}
+
+function parseFieldError(entry: unknown): ProblemFieldError | undefined {
+  if (!isObject(entry)) return undefined;
+  const detail = optionalString(entry.detail);
+  if (!detail) return undefined;
+  const fieldError: ProblemFieldError = { detail, raw: entry };
+  const pointer =
+    typeof entry.pointer === "string"
+      ? normalizePointer(entry.pointer)
+      : undefined;
+  const parameter = optionalString(entry.parameter);
+  if (pointer !== undefined) fieldError.pointer = pointer;
+  else if (parameter) fieldError.parameter = parameter;
+  const code = optionalString(entry.code);
+  if (code) fieldError.code = code;
+  return fieldError;
+}
+
+/**
+ * Parse a response body as problem details (RFC 9457).
+ *
+ * Members of the wrong type are ignored, as the RFC requires; so are entries
+ * of `errors` without a readable `detail`.
+ *
+ * @param body - The parsed JSON body of a response.
+ * @returns The problem details, or `undefined` if `body` isn't a JSON object
+ *   or has none of the members `type`, `title`, `status`, `detail` and
+ *   `errors`.
+ */
+export function parseProblemDetails(body: unknown): ProblemDetails | undefined {
+  if (!isObject(body)) return undefined;
+  if (!["type", "title", "status", "detail", "errors"].some((m) => m in body))
+    return undefined;
+  const extensions: Record<string, unknown> = {};
+  Object.keys(body).forEach((key) => {
+    if (!STANDARD_MEMBERS.has(key)) extensions[key] = body[key];
+  });
+  const errors = Array.isArray(body.errors)
+    ? body.errors
+        .map(parseFieldError)
+        .filter((e): e is ProblemFieldError => e !== undefined)
+    : [];
+  const problem: ProblemDetails = {
+    type: optionalString(body.type) ?? "about:blank",
+    title: optionalString(body.title),
+    status: typeof body.status === "number" ? body.status : undefined,
+    detail: optionalString(body.detail),
+    instance: optionalString(body.instance),
+    errors,
+    extensions,
+  };
+  parsedProblems.add(problem);
+  return problem;
+}
+
+/**
+ * Read the problem details of a `fetch` response.
+ *
+ * The body is read only if the response is JSON (`application/problem+json`,
+ * `application/json` or another `+json` type); reading it consumes it.
+ *
+ * @param response - The response, e.g. of a request that failed.
+ * @returns The problem details, or `undefined` if the body isn't JSON or
+ *   isn't problem details.
+ */
+export async function readProblemDetails(
+  response: Response
+): Promise<ProblemDetails | undefined> {
+  const mediaType = (response.headers.get("content-type") ?? "")
+    .split(";")[0]
+    .trim()
+    .toLowerCase();
+  if (mediaType !== "application/json" && !mediaType.endsWith("+json"))
+    return undefined;
+  try {
+    return parseProblemDetails(await response.json());
+  } catch {
+    return undefined;
+  }
+}
+
+type NormalizedLocation = { pointer: string } | { parameter: string };
+
+function normalizeLocation(
+  location: FieldLocation
+): NormalizedLocation | undefined {
+  if (typeof location === "string") {
+    const pointer = normalizePointer(location);
+    return pointer === undefined ? undefined : { pointer };
+  }
+  if ("parameter" in location) return { parameter: location.parameter };
+  const pointer = normalizePointer(location.pointer);
+  return pointer === undefined ? undefined : { pointer };
+}
+
+function isAncestor(ancestor: string, pointer: string): boolean {
+  return ancestor !== "" && pointer.startsWith(`${ancestor}/`);
+}
+
+function findField(
+  error: ProblemFieldError,
+  locations: [string, NormalizedLocation][]
+): string | undefined {
+  if (error.parameter !== undefined) {
+    return locations.find(
+      ([, loc]) => "parameter" in loc && loc.parameter === error.parameter
+    )?.[0];
+  }
+  if (error.pointer === undefined) return undefined;
+  const { pointer } = error;
+  const exact = locations.find(
+    ([, loc]) => "pointer" in loc && loc.pointer === pointer
+  );
+  if (exact) return exact[0];
+  // Else the closest containing field, e.g. `/tags` for `/tags/0`
+  let best: [string, string] | undefined;
+  locations.forEach(([key, loc]) => {
+    if (
+      "pointer" in loc &&
+      isAncestor(loc.pointer, pointer) &&
+      (!best || loc.pointer.length > best[1].length)
+    ) {
+      best = [key, loc.pointer];
+    }
+  });
+  return best?.[0];
+}
+
+function describeUnmatched(error: ProblemFieldError): string {
+  const location = error.parameter ?? error.pointer?.slice(1);
+  return location ? `${location}: ${error.detail}` : error.detail;
+}
+
+/**
+ * Map the field errors of problem details to the fields of a form.
+ *
+ * A field error belongs to the field with the same pointer or parameter or,
+ * failing that, to the closest field that contains it (e.g. an error at
+ * `/tags/0` to a field at `/tags`). Errors that match no field, problem
+ * details without field errors and responses that aren't problem details
+ * give a general error instead.
+ *
+ * @param body - The parsed JSON body of the response, or problem details
+ *   parsed already (e.g. by `readProblemDetails()`); `undefined` if there is
+ *   no body.
+ * @param fields - The form's fields: their keys (e.g. the names the
+ *   component uses for them) and their locations in the request.
+ * @param fallback - General error for responses that aren't problem details
+ *   or have neither `detail` nor `title`.
+ * @returns The messages per field and the general error.
+ */
+export function mapFieldErrors(
+  body: unknown,
+  fields: Record<string, FieldLocation>,
+  fallback = "The request failed."
+): MappedFieldErrors {
+  const problem = isParsedProblem(body) ? body : parseProblemDetails(body);
+  const fieldErrors: Record<string, string> = {};
+  const unmatched: ProblemFieldError[] = [];
+  if (!problem || problem.errors.length === 0) {
+    return {
+      problem,
+      fieldErrors,
+      unmatched,
+      generalError: problem?.detail || problem?.title || fallback,
+    };
+  }
+  const locations: [string, NormalizedLocation][] = [];
+  Object.entries(fields).forEach(([key, location]) => {
+    const normalized = normalizeLocation(location);
+    if (normalized) locations.push([key, normalized]);
+  });
+  problem.errors.forEach((error) => {
+    const key = findField(error, locations);
+    if (key === undefined) unmatched.push(error);
+    else
+      fieldErrors[key] = fieldErrors[key]
+        ? `${fieldErrors[key]} ${error.detail}`
+        : error.detail;
+  });
+  return {
+    problem,
+    fieldErrors,
+    unmatched,
+    generalError: unmatched.length
+      ? unmatched.map(describeUnmatched).join(" ")
+      : undefined,
+  };
+}

From 3550162f76cb714030364001121b7876157cbc8d Mon Sep 17 00:00:00 2001
From: Alex Kanitz <alexanderkanitz@gmail.com>
Date: Fri, 13 Nov 2026 08:13:07 +0100
Subject: [PATCH 03/11] docs(design): document field errors from APIs

Add a Field errors page (response format, utilities, example) and the
invalid and error properties to the pages of the form controls.

Refs #535

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../pages/docs/design/_meta.json              |   3 +-
 .../pages/docs/design/components/checkbox.mdx |  18 +++
 .../pages/docs/design/components/input.mdx    |  18 +++
 .../docs/design/components/multi-select.mdx   |  22 +++
 .../pages/docs/design/components/select.mdx   |  22 +++
 .../pages/docs/design/components/textarea.mdx |  18 +++
 .../pages/docs/design/field-errors.mdx        | 143 ++++++++++++++++++
 7 files changed, 243 insertions(+), 1 deletion(-)
 create mode 100644 apps/documentation/pages/docs/design/field-errors.mdx

diff --git a/apps/documentation/pages/docs/design/_meta.json b/apps/documentation/pages/docs/design/_meta.json
index 22cfc8b2..bc577822 100644
--- a/apps/documentation/pages/docs/design/_meta.json
+++ b/apps/documentation/pages/docs/design/_meta.json
@@ -1,5 +1,6 @@
 {
   "introduction": "Introduction",
   "architecture": "Architecture",
-  "components": "Components"
+  "components": "Components",
+  "field-errors": "Field errors"
 }
diff --git a/apps/documentation/pages/docs/design/components/checkbox.mdx b/apps/documentation/pages/docs/design/components/checkbox.mdx
index 35594170..0e09ec4a 100644
--- a/apps/documentation/pages/docs/design/components/checkbox.mdx
+++ b/apps/documentation/pages/docs/design/components/checkbox.mdx
@@ -127,6 +127,8 @@ This example shows a checkbox in a disabled state.
 | `disabled` | `boolean` | `false` | When `true`, disables the checkbox.       |
 | `name`     | `string`  | `""`    | The name of the checkbox for form submission. |
 | `value`    | `string`  | `""`    | The value of the checkbox for form submission. |
+| `invalid` | `boolean` | `false` | When `true`, marks the checkbox as invalid (also implied by `error`). |
+| `error`   | `string`  | `""`    | Error message shown under the checkbox, e.g. from an API. |
 
 ### `checked`
 Controls the checked state of the checkbox.
@@ -192,6 +194,22 @@ The value attribute, used when submitting the checkbox as part of a form.
   </Tabs.Tab>
 </Tabs>
 
+### `invalid` and `error`
+`error` shows a message under the checkbox, e.g. one that an API returned for this field (see [Field errors](/docs/design/field-errors)), and marks the checkbox as invalid: it gets a red border, `aria-invalid="true"` and `aria-describedby` pointing to the message, and screen readers announce the message (`aria-live="polite"`). `invalid` marks the checkbox as invalid without a message, e.g. when the message is shown elsewhere. Clear both when the user changes the value or submits again. The message has the part `error` for styling (`ecc-utils-design-checkbox::part(error)`).
+
+<Tabs items={['React', 'HTML']}>
+  <Tabs.Tab>
+    ```tsx copy
+    <EccUtilsDesignCheckbox error="Is required." />
+    ```
+  </Tabs.Tab>
+  <Tabs.Tab>
+    ```html copy
+    <ecc-utils-design-checkbox error="Is required."></ecc-utils-design-checkbox>
+    ```
+  </Tabs.Tab>
+</Tabs>
+
 ## Events
 
 | Event Name          | React Event Name     | Detail Type                      | Description                                    |
diff --git a/apps/documentation/pages/docs/design/components/input.mdx b/apps/documentation/pages/docs/design/components/input.mdx
index 45ef5f3b..c0d809f3 100644
--- a/apps/documentation/pages/docs/design/components/input.mdx
+++ b/apps/documentation/pages/docs/design/components/input.mdx
@@ -116,6 +116,8 @@ This example shows an input field associated with a label.
 | `placeholder` | `string`   | `""`     | Placeholder text for the input.            |
 | `value`       | `string`   | `""`     | The current value of the input.            |
 | `disabled`    | `boolean`  | `false`  | When `true`, disables the input.           |
+| `invalid` | `boolean` | `false` | When `true`, marks the input as invalid (also implied by `error`). |
+| `error`   | `string`  | `""`    | Error message shown under the input, e.g. from an API. |
 
 ### `type`
 Specifies the input type, determining the data format and keyboard layout on mobile devices.
@@ -181,6 +183,22 @@ When `true`, the input is non-interactive and visually de-emphasized.
   </Tabs.Tab>
 </Tabs>
 
+### `invalid` and `error`
+`error` shows a message under the input, e.g. one that an API returned for this field (see [Field errors](/docs/design/field-errors)), and marks the input as invalid: it gets a red border, `aria-invalid="true"` and `aria-describedby` pointing to the message, and screen readers announce the message (`aria-live="polite"`). `invalid` marks the input as invalid without a message, e.g. when the message is shown elsewhere. Clear both when the user changes the value or submits again. The message has the part `error` for styling (`ecc-utils-design-input::part(error)`).
+
+<Tabs items={['React', 'HTML']}>
+  <Tabs.Tab>
+    ```tsx copy
+    <EccUtilsDesignInput error="Must be a valid URI." />
+    ```
+  </Tabs.Tab>
+  <Tabs.Tab>
+    ```html copy
+    <ecc-utils-design-input error="Must be a valid URI."></ecc-utils-design-input>
+    ```
+  </Tabs.Tab>
+</Tabs>
+
 ## Events
 
 | Event Name          | React Event Name     | Detail Type             | Description                                    |
diff --git a/apps/documentation/pages/docs/design/components/multi-select.mdx b/apps/documentation/pages/docs/design/components/multi-select.mdx
index e957fefa..36d332c5 100644
--- a/apps/documentation/pages/docs/design/components/multi-select.mdx
+++ b/apps/documentation/pages/docs/design/components/multi-select.mdx
@@ -191,6 +191,8 @@ This example shows a multi-select with some values pre-selected.
 | `placeholder` | `string`   | `"Select options..."` | Placeholder text when no options are selected.    |
 | `disabled`    | `boolean`  | `false`              | When `true`, disables the multi-select.           |
 | `name`        | `string`   | `""`                 | The name attribute for form submissions.          |
+| `invalid` | `boolean` | `false` | When `true`, marks the multi-select as invalid (also implied by `error`). |
+| `error`   | `string`  | `""`    | Error message shown under the multi-select, e.g. from an API. |
 
 #### `value`
 Controls the selected values in the multi-select. This should be an array of strings matching the values of selected items.
@@ -274,6 +276,26 @@ The name attribute used when submitting the multi-select as part of a form.
   </Tabs.Tab>
 </Tabs>
 
+#### `invalid` and `error`
+`error` shows a message under the multi-select, e.g. one that an API returned for this field (see [Field errors](/docs/design/field-errors)), and marks the multi-select as invalid: its trigger gets a red border, `aria-invalid="true"` and `aria-describedby` pointing to the message, and screen readers announce the message (`aria-live="polite"`). `invalid` marks the multi-select as invalid without a message, e.g. when the message is shown elsewhere. Clear both when the user changes the value or submits again. The message has the part `error` for styling (`ecc-utils-design-multi-select::part(error)`).
+
+<Tabs items={['React', 'HTML']}>
+  <Tabs.Tab>
+    ```tsx copy
+    <EccUtilsDesignMultiSelect error="Must have at least 1 item.">
+      ...
+    </EccUtilsDesignMultiSelect>
+    ```
+  </Tabs.Tab>
+  <Tabs.Tab>
+    ```html copy
+    <ecc-utils-design-multi-select error="Must have at least 1 item.">
+      ...
+    </ecc-utils-design-multi-select>
+    ```
+  </Tabs.Tab>
+</Tabs>
+
 ### `EccUtilsDesignMultiSelectTrigger`
 
 | Property    | Type      | Default | Description                                        |
diff --git a/apps/documentation/pages/docs/design/components/select.mdx b/apps/documentation/pages/docs/design/components/select.mdx
index 6a49435c..5d8a181a 100644
--- a/apps/documentation/pages/docs/design/components/select.mdx
+++ b/apps/documentation/pages/docs/design/components/select.mdx
@@ -219,6 +219,8 @@ The `Select` is built by combining these components:
 |-------------|-----------|---------|-------------------------------------------|
 | `value`     | `string`  | `""`    | The value of the currently selected option. |
 | `disabled`  | `boolean` | `false` | When `true`, disables the select.         |
+| `invalid` | `boolean` | `false` | When `true`, marks the select as invalid (also implied by `error`). |
+| `error`   | `string`  | `""`    | Error message shown under the select, e.g. from an API. |
 
 #### `value`
 Controls the currently selected option. Should match the `value` of one of the SelectItem components.
@@ -260,6 +262,26 @@ When `true`, disables the entire select, preventing user interaction.
   </Tabs.Tab>
 </Tabs>
 
+#### `invalid` and `error`
+`error` shows a message under the select, e.g. one that an API returned for this field (see [Field errors](/docs/design/field-errors)), and marks the select as invalid: its trigger gets a red border, `aria-invalid="true"` and `aria-describedby` pointing to the message, and screen readers announce the message (`aria-live="polite"`). `invalid` marks the select as invalid without a message, e.g. when the message is shown elsewhere. Clear both when the user changes the value or submits again. The message has the part `error` for styling (`ecc-utils-design-select::part(error)`).
+
+<Tabs items={['React', 'HTML']}>
+  <Tabs.Tab>
+    ```tsx copy
+    <EccUtilsDesignSelect error="Must be one of: a, b.">
+      ...
+    </EccUtilsDesignSelect>
+    ```
+  </Tabs.Tab>
+  <Tabs.Tab>
+    ```html copy
+    <ecc-utils-design-select error="Must be one of: a, b.">
+      ...
+    </ecc-utils-design-select>
+    ```
+  </Tabs.Tab>
+</Tabs>
+
 ### `EccUtilsDesignSelectItem`
 
 | Property    | Type      | Default | Description                               |
diff --git a/apps/documentation/pages/docs/design/components/textarea.mdx b/apps/documentation/pages/docs/design/components/textarea.mdx
index 0f028c03..b9141a02 100644
--- a/apps/documentation/pages/docs/design/components/textarea.mdx
+++ b/apps/documentation/pages/docs/design/components/textarea.mdx
@@ -115,6 +115,8 @@ This example shows a textarea with a corresponding label.
 | `placeholder` | `string`  | `""`    | Placeholder text for the textarea.        |
 | `value`       | `string`  | `""`    | The current value of the textarea.        |
 | `disabled`    | `boolean` | `false` | When `true`, disables the textarea.       |
+| `invalid` | `boolean` | `false` | When `true`, marks the textarea as invalid (also implied by `error`). |
+| `error`   | `string`  | `""`    | Error message shown under the textarea, e.g. from an API. |
 | `rows`        | `number`  | `3`     | The number of visible text lines.         |
 | `cols`        | `number`  | `undefined` | The visible width of the text control.  |
 
@@ -198,6 +200,22 @@ Specifies the visible width of the textarea in average character widths.
   </Tabs.Tab>
 </Tabs>
 
+### `invalid` and `error`
+`error` shows a message under the textarea, e.g. one that an API returned for this field (see [Field errors](/docs/design/field-errors)), and marks the textarea as invalid: it gets a red border, `aria-invalid="true"` and `aria-describedby` pointing to the message, and screen readers announce the message (`aria-live="polite"`). `invalid` marks the textarea as invalid without a message, e.g. when the message is shown elsewhere. Clear both when the user changes the value or submits again. The message has the part `error` for styling (`ecc-utils-design-textarea::part(error)`).
+
+<Tabs items={['React', 'HTML']}>
+  <Tabs.Tab>
+    ```tsx copy
+    <EccUtilsDesignTextarea error="Must be at most 300 characters long." />
+    ```
+  </Tabs.Tab>
+  <Tabs.Tab>
+    ```html copy
+    <ecc-utils-design-textarea error="Must be at most 300 characters long."></ecc-utils-design-textarea>
+    ```
+  </Tabs.Tab>
+</Tabs>
+
 ## Events
 
 | Event Name          | React Event Name     | Detail Type             | Description                                  |
diff --git a/apps/documentation/pages/docs/design/field-errors.mdx b/apps/documentation/pages/docs/design/field-errors.mdx
new file mode 100644
index 00000000..b37ef30f
--- /dev/null
+++ b/apps/documentation/pages/docs/design/field-errors.mdx
@@ -0,0 +1,143 @@
+import { Callout } from 'nextra/components'
+
+# Field errors
+
+When an API rejects a request, components that submit data can show its
+messages at the fields they belong to, instead of one general error. The
+design package has the two parts for this:
+
+- The form controls ([input](/docs/design/components/input),
+  [textarea](/docs/design/components/textarea),
+  [checkbox](/docs/design/components/checkbox),
+  [select](/docs/design/components/select) and
+  [multi-select](/docs/design/components/multi-select)) have the properties
+  `error` and `invalid`: `error` shows a message under the control and marks it
+  as invalid (red border, `aria-invalid`, `aria-describedby`, announced to
+  screen readers), `invalid` marks it as invalid without a message.
+- Utilities that read the errors of a response in the standard format,
+  problem details ([RFC 9457](https://www.rfc-editor.org/rfc/rfc9457),
+  `application/problem+json`), and map them to the component's fields.
+
+Components don't need validation rules of their own: the API keeps the final
+say, and the components show what it says.
+
+## Response format
+
+Field errors are read in the form of the example of
+[RFC 9457, section 3](https://www.rfc-editor.org/rfc/rfc9457#section-3): an
+extension member `errors`, each entry with a readable `detail` and the
+location of the field, a JSON Pointer
+([RFC 6901](https://www.rfc-editor.org/rfc/rfc6901)) to the field in the
+request body (`pointer`, e.g. `#/organization/url`) or the name of a request
+parameter (`parameter`, e.g. `limit`):
+
+```json
+{
+  "type": "https://foca.readthedocs.io/en/latest/problems/invalid-request/",
+  "title": "Bad Request",
+  "status": 400,
+  "detail": "Invalid fields: #/name (too-long); #/organization/url (invalid-format)",
+  "code": "invalid-request",
+  "errors": [
+    { "detail": "Must be at most 3 characters long.", "pointer": "#/name", "code": "too-long" },
+    { "detail": "Must be a valid URI.", "pointer": "#/organization/url", "code": "invalid-format" }
+  ]
+}
+```
+
+Pointers in URI fragment form (`#/organization/url`, percent-encoded) and plain
+pointers (`/organization/url`) are both accepted. Nothing is specific to one
+server: [FOCA](https://github.com/elixir-cloud-aai/foca)-based APIs, such as
+Cloud Registry, respond in this format, and so can any other API.
+
+## Utilities
+
+All are exported by `@elixir-cloud/design`:
+
+| Function | Description |
+|----------|-------------|
+| `readProblemDetails(response)` | Reads the problem details of a `fetch` response (JSON bodies only; consumes the body). Returns `undefined` if the body isn't problem details. |
+| `parseProblemDetails(body)` | Parses a JSON body that was read already. Returns the standard members (`type`, `title`, `status`, `detail`, `instance`), the field errors (`errors`, each with `detail`, `pointer` or `parameter`, `code` and the entry as received in `raw`) and the other members in `extensions` (e.g. `code`), or `undefined` if the body isn't problem details. |
+| `mapFieldErrors(body, fields, fallback?)` | Maps the field errors to the component's fields. `body` is a JSON body or parsed problem details. `fields` maps the component's keys for its fields to their locations: a pointer (`"/organization/url"` or `"#/organization/url"`) or `{ parameter: "limit" }`. Returns `fieldErrors` (a message per key), `unmatched` (the errors that match no field), `generalError` and `problem`. |
+| `normalizePointer(pointer)` | Converts a pointer in URI fragment form to a plain pointer. |
+
+A field error belongs to the field with the same pointer or parameter or,
+failing that, to the closest field that contains it (e.g. an error at
+`/tags/0` to a field at `/tags`). Several messages for the same field are
+joined.
+
+`generalError` is the message to show above or below the form, or `undefined`
+if every error is shown at a field:
+
+- errors that match no field, each with its location (e.g.
+  `organization/url: Must be a valid URI.`);
+- for problem details without field errors, their `detail`, or else their
+  `title`;
+- for responses that aren't problem details, the `fallback`
+  (default: `The request failed.`).
+
+## Example
+
+A component that registers a service shows the errors of a rejected request
+at its fields:
+
+```ts copy filename="service-form.ts"
+import { html, LitElement } from "lit";
+import { state } from "lit/decorators.js";
+import { mapFieldErrors, readProblemDetails } from "@elixir-cloud/design";
+
+// The component's fields and their locations in the request body
+const FIELDS = {
+  name: "/name",
+  url: "/url",
+  organizationUrl: "/organization/url",
+};
+
+export class ServiceForm extends LitElement {
+  @state() private fieldErrors: Record<string, string> = {};
+  @state() private generalError = "";
+
+  private async submit(body: unknown) {
+    this.fieldErrors = {};
+    this.generalError = "";
+    const response = await fetch("/ga4gh/registry/v1/services", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body),
+    });
+    if (response.ok) return;
+    const mapped = mapFieldErrors(
+      await readProblemDetails(response),
+      FIELDS,
+      `The service could not be registered (${response.status}).`
+    );
+    this.fieldErrors = mapped.fieldErrors;
+    this.generalError = mapped.generalError ?? "";
+  }
+
+  render() {
+    return html`
+      <ecc-utils-design-input
+        .error=${this.fieldErrors.name ?? ""}
+      ></ecc-utils-design-input>
+      <ecc-utils-design-input
+        type="url"
+        .error=${this.fieldErrors.url ?? ""}
+      ></ecc-utils-design-input>
+      <ecc-utils-design-input
+        type="url"
+        .error=${this.fieldErrors.organizationUrl ?? ""}
+      ></ecc-utils-design-input>
+      ${this.generalError
+        ? html`<p role="alert">${this.generalError}</p>`
+        : ""}
+    `;
+  }
+}
+```
+
+<Callout type="info">
+  Components that call their API through a provider can read the problem
+  details there, e.g. with `readProblemDetails()`, and pass them on, e.g. in
+  the error they throw, so that the component can call `mapFieldErrors()`.
+</Callout>

From 30ddb1de3ca00530863c430bb9ae7c7b0ea95fc7 Mon Sep 17 00:00:00 2001
From: Alex Kanitz <alexanderkanitz@gmail.com>
Date: Fri, 13 Nov 2026 09:28:54 +0100
Subject: [PATCH 04/11] fix(design): address review of field errors

- mapFieldErrors() takes parsed problem details only, instead of
  telling them from bodies by a hidden registry of parsed objects.
- Field keys that are names of object members (e.g. toString) map
  correctly; locations in the general error have their keys
  unescaped (RFC 6901).
- The checkbox message no longer widens or shifts the box next to its
  label; the select triggers' copy for aria-describedby is hidden, so
  screen readers don't read the message twice.
- Docs: errors aren't passed down to contained fields; the example
  handles network errors; FOCA's problem type linked.
- More tests for the select controls.

Refs #535

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../pages/docs/design/components/checkbox.mdx |  2 +-
 .../pages/docs/design/field-errors.mdx        | 82 ++++++++++---------
 .../src/components/checkbox/checkbox.ts       | 77 +++++++++--------
 .../components/multi-select/multi-select.ts   |  6 +-
 .../src/components/select/select.ts           |  6 +-
 .../src/form-controls.test.ts                 | 20 +++++
 .../src/utils/problem-details.test.ts         | 54 +++++++++---
 .../src/utils/problem-details.ts              | 34 ++++----
 8 files changed, 169 insertions(+), 112 deletions(-)

diff --git a/apps/documentation/pages/docs/design/components/checkbox.mdx b/apps/documentation/pages/docs/design/components/checkbox.mdx
index 0e09ec4a..ec0b241d 100644
--- a/apps/documentation/pages/docs/design/components/checkbox.mdx
+++ b/apps/documentation/pages/docs/design/components/checkbox.mdx
@@ -195,7 +195,7 @@ The value attribute, used when submitting the checkbox as part of a form.
 </Tabs>
 
 ### `invalid` and `error`
-`error` shows a message under the checkbox, e.g. one that an API returned for this field (see [Field errors](/docs/design/field-errors)), and marks the checkbox as invalid: it gets a red border, `aria-invalid="true"` and `aria-describedby` pointing to the message, and screen readers announce the message (`aria-live="polite"`). `invalid` marks the checkbox as invalid without a message, e.g. when the message is shown elsewhere. Clear both when the user changes the value or submits again. The message has the part `error` for styling (`ecc-utils-design-checkbox::part(error)`).
+`error` shows a message under the checkbox, e.g. one that an API returned for this field (see [Field errors](/docs/design/field-errors)), and marks the checkbox as invalid: it gets a red border, `aria-invalid="true"` and `aria-describedby` pointing to the message, and screen readers announce the message (`aria-live="polite"`). `invalid` marks the checkbox as invalid without a message, e.g. when the message is shown elsewhere. Clear both when the user changes the value or submits again. The message has the part `error` for styling (`ecc-utils-design-checkbox::part(error)`). Unlike the other controls' messages, it is positioned under the box without taking space (so that it doesn't widen or shift the box next to its label): leave room below the checkbox, e.g. with a margin.
 
 <Tabs items={['React', 'HTML']}>
   <Tabs.Tab>
diff --git a/apps/documentation/pages/docs/design/field-errors.mdx b/apps/documentation/pages/docs/design/field-errors.mdx
index b37ef30f..2c3da397 100644
--- a/apps/documentation/pages/docs/design/field-errors.mdx
+++ b/apps/documentation/pages/docs/design/field-errors.mdx
@@ -1,4 +1,4 @@
-import { Callout } from 'nextra/components'
+import { Callout } from 'nextra/components';
 
 # Field errors
 
@@ -47,24 +47,30 @@ parameter (`parameter`, e.g. `limit`):
 
 Pointers in URI fragment form (`#/organization/url`, percent-encoded) and plain
 pointers (`/organization/url`) are both accepted. Nothing is specific to one
-server: [FOCA](https://github.com/elixir-cloud-aai/foca)-based APIs, such as
-Cloud Registry, respond in this format, and so can any other API.
+server: the example is the response of an API built with
+[FOCA](https://github.com/elixir-cloud-aai/foca), which reports invalid
+fields in this format (see FOCA's
+[invalid request](https://foca.readthedocs.io/en/latest/problems/invalid-request/)
+problem type), and any other API can respond the same way.
 
 ## Utilities
 
 All are exported by `@elixir-cloud/design`:
 
-| Function | Description |
-|----------|-------------|
-| `readProblemDetails(response)` | Reads the problem details of a `fetch` response (JSON bodies only; consumes the body). Returns `undefined` if the body isn't problem details. |
-| `parseProblemDetails(body)` | Parses a JSON body that was read already. Returns the standard members (`type`, `title`, `status`, `detail`, `instance`), the field errors (`errors`, each with `detail`, `pointer` or `parameter`, `code` and the entry as received in `raw`) and the other members in `extensions` (e.g. `code`), or `undefined` if the body isn't problem details. |
-| `mapFieldErrors(body, fields, fallback?)` | Maps the field errors to the component's fields. `body` is a JSON body or parsed problem details. `fields` maps the component's keys for its fields to their locations: a pointer (`"/organization/url"` or `"#/organization/url"`) or `{ parameter: "limit" }`. Returns `fieldErrors` (a message per key), `unmatched` (the errors that match no field), `generalError` and `problem`. |
-| `normalizePointer(pointer)` | Converts a pointer in URI fragment form to a plain pointer. |
+| Function                                     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `readProblemDetails(response)`               | Reads the problem details of a `fetch` response (JSON bodies only; consumes the body). Returns `undefined` if the body isn't problem details.                                                                                                                                                                                                                                                                                                                            |
+| `parseProblemDetails(body)`                  | Parses a JSON body that was read already. Returns the standard members (`type`, `title`, `status`, `detail`, `instance`), the field errors (`errors`, each with `detail`, `pointer` or `parameter`, `code` and the entry as received in `raw`) and the other members in `extensions` (e.g. `code`), or `undefined` if the body isn't problem details.                                                                                                                    |
+| `mapFieldErrors(problem, fields, fallback?)` | Maps the field errors to the component's fields. `problem` is the result of `readProblemDetails()` or `parseProblemDetails()` (`undefined` for responses without problem details). `fields` maps the component's keys for its fields to their locations: a pointer (`"/organization/url"` or `"#/organization/url"`) or `{ parameter: "limit" }`. Returns `fieldErrors` (a message per key), `unmatched` (the errors that match no field), `generalError` and `problem`. |
+| `normalizePointer(pointer)`                  | Converts a pointer in URI fragment form to a plain pointer.                                                                                                                                                                                                                                                                                                                                                                                                              |
 
 A field error belongs to the field with the same pointer or parameter or,
 failing that, to the closest field that contains it (e.g. an error at
 `/tags/0` to a field at `/tags`). Several messages for the same field are
-joined.
+joined. Errors are not passed down: an error at an object (e.g.
+`#/organization`, "Is required.") doesn't mark the fields inside it (e.g.
+`/organization/url`); give the object a field key of its own to show it
+somewhere, or it becomes part of the general error.
 
 `generalError` is the message to show above or below the form, or `undefined`
 if every error is shown at a field:
@@ -82,62 +88,64 @@ A component that registers a service shows the errors of a rejected request
 at its fields:
 
 ```ts copy filename="service-form.ts"
-import { html, LitElement } from "lit";
-import { state } from "lit/decorators.js";
-import { mapFieldErrors, readProblemDetails } from "@elixir-cloud/design";
+import { html, LitElement } from 'lit';
+import { state } from 'lit/decorators.js';
+import { mapFieldErrors, readProblemDetails } from '@elixir-cloud/design';
 
 // The component's fields and their locations in the request body
 const FIELDS = {
-  name: "/name",
-  url: "/url",
-  organizationUrl: "/organization/url",
+  name: '/name',
+  url: '/url',
+  organizationUrl: '/organization/url',
 };
 
 export class ServiceForm extends LitElement {
   @state() private fieldErrors: Record<string, string> = {};
-  @state() private generalError = "";
+  @state() private generalError = '';
 
   private async submit(body: unknown) {
     this.fieldErrors = {};
-    this.generalError = "";
-    const response = await fetch("/ga4gh/registry/v1/services", {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify(body),
-    });
+    this.generalError = '';
+    let response: Response;
+    try {
+      response = await fetch('/ga4gh/registry/v1/services', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(body),
+      });
+    } catch {
+      this.generalError = 'The registry could not be reached.';
+      return;
+    }
     if (response.ok) return;
     const mapped = mapFieldErrors(
       await readProblemDetails(response),
       FIELDS,
-      `The service could not be registered (${response.status}).`
+      `The service could not be registered (${response.status}).`,
     );
     this.fieldErrors = mapped.fieldErrors;
-    this.generalError = mapped.generalError ?? "";
+    this.generalError = mapped.generalError ?? '';
   }
 
   render() {
     return html`
-      <ecc-utils-design-input
-        .error=${this.fieldErrors.name ?? ""}
-      ></ecc-utils-design-input>
+      <ecc-utils-design-input .error=${this.fieldErrors.name ?? ''}></ecc-utils-design-input>
       <ecc-utils-design-input
         type="url"
-        .error=${this.fieldErrors.url ?? ""}
+        .error=${this.fieldErrors.url ?? ''}
       ></ecc-utils-design-input>
       <ecc-utils-design-input
         type="url"
-        .error=${this.fieldErrors.organizationUrl ?? ""}
+        .error=${this.fieldErrors.organizationUrl ?? ''}
       ></ecc-utils-design-input>
-      ${this.generalError
-        ? html`<p role="alert">${this.generalError}</p>`
-        : ""}
+      ${this.generalError ? html`<p role="alert">${this.generalError}</p>` : ''}
     `;
   }
 }
 ```
 
-<Callout type="info">
-  Components that call their API through a provider can read the problem
-  details there, e.g. with `readProblemDetails()`, and pass them on, e.g. in
-  the error they throw, so that the component can call `mapFieldErrors()`.
+<Callout type='info'>
+  Components that call their API through a provider can read the problem details there, e.g. with
+  `readProblemDetails()`, and pass them on, e.g. in the error they throw, so that the component can
+  call `mapFieldErrors()`.
 </Callout>
diff --git a/packages/ecc-utils-design/src/components/checkbox/checkbox.ts b/packages/ecc-utils-design/src/components/checkbox/checkbox.ts
index 249de286..ff938b23 100644
--- a/packages/ecc-utils-design/src/components/checkbox/checkbox.ts
+++ b/packages/ecc-utils-design/src/components/checkbox/checkbox.ts
@@ -47,44 +47,51 @@ export class EccUtilsDesignCheckbox extends LitElement {
       !this.checked && "opacity-0"
     );
 
+    // The message is positioned under the box without taking space, so
+    // that it neither widens nor shifts the box next to its label
     return html`
-      <div
-        part="base"
-        class=${checkboxClasses}
-        role="checkbox"
-        aria-checked=${this.checked ? "true" : "false"}
-        aria-disabled=${this.disabled ? "true" : "false"}
-        aria-invalid=${ifDefined(isInvalid ? "true" : undefined)}
-        aria-describedby=${ifDefined(this.error ? "error" : undefined)}
-        tabindex=${this.disabled ? "-1" : "0"}
-        @click=${this._handleClick}
-        @keydown=${this._handleKeydown}
-        @focus=${this._handleFocus}
-        @blur=${this._handleBlur}
-      >
-        <div class=${indicatorClasses}>
-          <svg
-            xmlns="http://www.w3.org/2000/svg"
-            viewBox="0 0 24 24"
-            fill="none"
-            stroke="currentColor"
-            stroke-width="2"
-            stroke-linecap="round"
-            stroke-linejoin="round"
-            class="h-4 w-4"
-          >
-            <path d="M20 6 9 17l-5-5" />
-          </svg>
+      <div class="relative">
+        <div
+          part="base"
+          class=${checkboxClasses}
+          role="checkbox"
+          aria-checked=${this.checked ? "true" : "false"}
+          aria-disabled=${this.disabled ? "true" : "false"}
+          aria-invalid=${ifDefined(isInvalid ? "true" : undefined)}
+          aria-describedby=${ifDefined(this.error ? "error" : undefined)}
+          tabindex=${this.disabled ? "-1" : "0"}
+          @click=${this._handleClick}
+          @keydown=${this._handleKeydown}
+          @focus=${this._handleFocus}
+          @blur=${this._handleBlur}
+        >
+          <div class=${indicatorClasses}>
+            <svg
+              xmlns="http://www.w3.org/2000/svg"
+              viewBox="0 0 24 24"
+              fill="none"
+              stroke="currentColor"
+              stroke-width="2"
+              stroke-linecap="round"
+              stroke-linejoin="round"
+              class="h-4 w-4"
+            >
+              <path d="M20 6 9 17l-5-5" />
+            </svg>
+          </div>
         </div>
+        <p
+          id="error"
+          part="error"
+          class=${cn(
+            "absolute left-0 top-full whitespace-nowrap text-sm text-destructive",
+            !!this.error && "mt-1.5"
+          )}
+          aria-live="polite"
+        >
+          ${this.error}
+        </p>
       </div>
-      <p
-        id="error"
-        part="error"
-        class=${cn("text-sm text-destructive", !!this.error && "mt-1.5")}
-        aria-live="polite"
-      >
-        ${this.error}
-      </p>
     `;
   }
 
diff --git a/packages/ecc-utils-design/src/components/multi-select/multi-select.ts b/packages/ecc-utils-design/src/components/multi-select/multi-select.ts
index 2101c63e..aab77a5c 100644
--- a/packages/ecc-utils-design/src/components/multi-select/multi-select.ts
+++ b/packages/ecc-utils-design/src/components/multi-select/multi-select.ts
@@ -261,10 +261,10 @@ export class EccUtilsDesignMultiSelectTrigger extends LitElement {
 
     const hasSelection = this.selectedValues.length > 0;
 
-    // The multi-select shows the error; the trigger has a copy for screen
-    // readers, as `aria-describedby` can't refer to another shadow root
+    // The multi-select shows the error; the trigger has a hidden copy for
+    // `aria-describedby`, which can't refer to another shadow root
     return html`
-      <span id="error" class="sr-only">${error}</span>
+      <span id="error" hidden>${error}</span>
       <button
         part="base"
         type="button"
diff --git a/packages/ecc-utils-design/src/components/select/select.ts b/packages/ecc-utils-design/src/components/select/select.ts
index a109e6b3..4861f5c2 100644
--- a/packages/ecc-utils-design/src/components/select/select.ts
+++ b/packages/ecc-utils-design/src/components/select/select.ts
@@ -179,10 +179,10 @@ export class EccUtilsDesignSelectTrigger extends LitElement {
       this.disabled && "opacity-50 cursor-not-allowed"
     );
 
-    // The select shows the error; the trigger has a copy for screen
-    // readers, as `aria-describedby` can't refer to another shadow root
+    // The select shows the error; the trigger has a hidden copy for
+    // `aria-describedby`, which can't refer to another shadow root
     return html`
-      <span id="error" class="sr-only">${error}</span>
+      <span id="error" hidden>${error}</span>
       <button
         part="base"
         type="button"
diff --git a/packages/ecc-utils-design/src/form-controls.test.ts b/packages/ecc-utils-design/src/form-controls.test.ts
index 2a0487e8..e62b2dd5 100644
--- a/packages/ecc-utils-design/src/form-controls.test.ts
+++ b/packages/ecc-utils-design/src/form-controls.test.ts
@@ -126,9 +126,12 @@ describe("form controls: invalid state and error message", () => {
         const trigger = el.querySelector(triggerTag) as LitElement;
         const button = () => trigger.shadowRoot!.querySelector("button")!;
         expect(button().hasAttribute("aria-invalid")).to.equal(false);
+        expect(errorElement(el).textContent?.trim()).to.equal("");
+        expect(errorElement(el).getAttribute("aria-live")).to.equal("polite");
 
         el.error = "Must be one of: a, b.";
         await el.updateComplete;
+        expect(el.hasAttribute("invalid")).to.equal(false);
         await trigger.updateComplete;
         expect(errorElement(el).textContent?.trim()).to.equal(
           "Must be one of: a, b."
@@ -149,9 +152,26 @@ describe("form controls: invalid state and error message", () => {
         el.invalid = true;
         await el.updateComplete;
         await trigger.updateComplete;
+        expect(el.hasAttribute("invalid")).to.equal(true);
         expect(button().getAttribute("aria-invalid")).to.equal("true");
         expect(button().hasAttribute("aria-describedby")).to.equal(false);
       });
+
+      it("takes the error from the attribute", async () => {
+        const el = await create();
+        el.setAttribute("error", "Is required.");
+        await el.updateComplete;
+        expect(errorElement(el).textContent?.trim()).to.equal("Is required.");
+      });
+
+      it("has a valid trigger without a select", async () => {
+        const trigger = await fixture<LitElement>(
+          `<${triggerTag}></${triggerTag}>`
+        );
+        const button = trigger.shadowRoot!.querySelector("button")!;
+        expect(button.hasAttribute("aria-invalid")).to.equal(false);
+        expect(button.className).to.contain("border-input");
+      });
     });
   });
 });
diff --git a/packages/ecc-utils-design/src/utils/problem-details.test.ts b/packages/ecc-utils-design/src/utils/problem-details.test.ts
index 912aae4f..1ab34692 100644
--- a/packages/ecc-utils-design/src/utils/problem-details.test.ts
+++ b/packages/ecc-utils-design/src/utils/problem-details.test.ts
@@ -164,6 +164,13 @@ describe("readProblemDetails()", () => {
 });
 
 describe("mapFieldErrors()", () => {
+  // Maps a response body, parsed as the docs show
+  const mapBody = (
+    body: unknown,
+    fieldsOfForm: Parameters<typeof mapFieldErrors>[1],
+    fallback?: string
+  ) => mapFieldErrors(parseProblemDetails(body), fieldsOfForm, fallback);
+
   const fields = {
     age: "#/age",
     color: "/profile/color",
@@ -173,7 +180,7 @@ describe("mapFieldErrors()", () => {
   };
 
   it("maps errors to fields by pointer", () => {
-    const mapped = mapFieldErrors(RFC_EXAMPLE, fields);
+    const mapped = mapBody(RFC_EXAMPLE, fields);
     expect(mapped.fieldErrors).to.deep.equal({
       age: "must be a positive integer",
       color: "must be 'green', 'red' or 'blue'",
@@ -184,7 +191,7 @@ describe("mapFieldErrors()", () => {
   });
 
   it("maps parameters, object locations and contained fields", () => {
-    const mapped = mapFieldErrors(
+    const mapped = mapBody(
       {
         errors: [
           { detail: "Too large.", parameter: "limit" },
@@ -204,7 +211,7 @@ describe("mapFieldErrors()", () => {
   });
 
   it("prefers the closest containing field", () => {
-    const mapped = mapFieldErrors(
+    const mapped = mapBody(
       { errors: [{ detail: "Bad.", pointer: "#/a/b/c" }] },
       { a: "/a", ab: "/a/b", abc2: "/a/bc" }
     );
@@ -212,7 +219,7 @@ describe("mapFieldErrors()", () => {
   });
 
   it("reports unknown pointers and parameters as a general error", () => {
-    const mapped = mapFieldErrors(
+    const mapped = mapBody(
       {
         detail: "Invalid fields",
         errors: [
@@ -233,7 +240,7 @@ describe("mapFieldErrors()", () => {
   });
 
   it("doesn't map body errors to parameters or vice versa", () => {
-    const mapped = mapFieldErrors(
+    const mapped = mapBody(
       {
         errors: [
           { detail: "A.", pointer: "#/limit" },
@@ -247,7 +254,7 @@ describe("mapFieldErrors()", () => {
   });
 
   it("ignores fields with invalid locations", () => {
-    const mapped = mapFieldErrors(
+    const mapped = mapBody(
       { errors: [{ detail: "A.", pointer: "#/age" }] },
       { age: "age", other: { pointer: "x" } }
     );
@@ -257,24 +264,45 @@ describe("mapFieldErrors()", () => {
 
   it("falls back to detail, title or the fallback without errors", () => {
     expect(
-      mapFieldErrors({ title: "Bad Request", detail: "No." }, fields)
-        .generalError
+      mapBody({ title: "Bad Request", detail: "No." }, fields).generalError
     ).to.equal("No.");
     expect(
-      mapFieldErrors({ title: "Bad Request", errors: [] }, fields).generalError
+      mapBody({ title: "Bad Request", errors: [] }, fields).generalError
     ).to.equal("Bad Request");
-    expect(mapFieldErrors({ status: 500 }, fields).generalError).to.equal(
+    expect(mapBody({ status: 500 }, fields).generalError).to.equal(
       "The request failed."
     );
-    const notProblem = mapFieldErrors("Internal Server Error", fields, "Oops.");
+    const notProblem = mapBody("Internal Server Error", fields, "Oops.");
     expect(notProblem.problem).to.equal(undefined);
     expect(notProblem.generalError).to.equal("Oops.");
-    expect(mapFieldErrors(undefined, fields).generalError).to.equal(
+    expect(mapBody(undefined, fields).generalError).to.equal(
       "The request failed."
     );
   });
 
-  it("accepts problem details parsed already", () => {
+  it("unescapes keys in the locations of the general error", () => {
+    const mapped = mapBody(
+      { errors: [{ detail: "F.", pointer: "#/a~1b/c~0d" }] },
+      fields
+    );
+    expect(mapped.generalError).to.equal("a/b/c~d: F.");
+  });
+
+  it("handles field keys that are names of object members", () => {
+    const mapped = mapBody(
+      {
+        errors: [
+          { detail: "A.", pointer: "#/toString" },
+          { detail: "B.", pointer: "#/constructor" },
+        ],
+      },
+      { toString: "/toString", constructor: "/constructor" }
+    );
+    expect(mapped.fieldErrors.toString).to.equal("A.");
+    expect(mapped.fieldErrors.constructor).to.equal("B.");
+  });
+
+  it("returns the problem details it was given", () => {
     const problem = parseProblemDetails(RFC_EXAMPLE);
     const mapped = mapFieldErrors(problem, fields);
     expect(mapped.problem).to.equal(problem);
diff --git a/packages/ecc-utils-design/src/utils/problem-details.ts b/packages/ecc-utils-design/src/utils/problem-details.ts
index 22cc68b0..dcf2cced 100644
--- a/packages/ecc-utils-design/src/utils/problem-details.ts
+++ b/packages/ecc-utils-design/src/utils/problem-details.ts
@@ -81,16 +81,6 @@ export interface MappedFieldErrors {
   generalError: string | undefined;
 }
 
-// Problem details returned by `parseProblemDetails()`, so that
-// `mapFieldErrors()` can tell them from response bodies
-const parsedProblems = new WeakSet<object>();
-
-function isParsedProblem(value: unknown): value is ProblemDetails {
-  return (
-    typeof value === "object" && value !== null && parsedProblems.has(value)
-  );
-}
-
 const STANDARD_MEMBERS = new Set([
   "type",
   "title",
@@ -179,7 +169,6 @@ export function parseProblemDetails(body: unknown): ProblemDetails | undefined {
     errors,
     extensions,
   };
-  parsedProblems.add(problem);
   return problem;
 }
 
@@ -257,7 +246,14 @@ function findField(
 }
 
 function describeUnmatched(error: ProblemFieldError): string {
-  const location = error.parameter ?? error.pointer?.slice(1);
+  // E.g. `organization/url`, with keys unescaped (RFC 6901)
+  const location =
+    error.parameter ??
+    error.pointer
+      ?.slice(1)
+      .split("/")
+      .map((key) => key.replace(/~1/g, "/").replace(/~0/g, "~"))
+      .join("/");
   return location ? `${location}: ${error.detail}` : error.detail;
 }
 
@@ -270,21 +266,19 @@ function describeUnmatched(error: ProblemFieldError): string {
  * details without field errors and responses that aren't problem details
  * give a general error instead.
  *
- * @param body - The parsed JSON body of the response, or problem details
- *   parsed already (e.g. by `readProblemDetails()`); `undefined` if there is
- *   no body.
+ * @param problem - Problem details, as returned by `readProblemDetails()` or
+ *   `parseProblemDetails()`; `undefined` if the response has none.
  * @param fields - The form's fields: their keys (e.g. the names the
  *   component uses for them) and their locations in the request.
- * @param fallback - General error for responses that aren't problem details
- *   or have neither `detail` nor `title`.
+ * @param fallback - General error for responses without problem details or
+ *   with neither `detail` nor `title`.
  * @returns The messages per field and the general error.
  */
 export function mapFieldErrors(
-  body: unknown,
+  problem: ProblemDetails | undefined,
   fields: Record<string, FieldLocation>,
   fallback = "The request failed."
 ): MappedFieldErrors {
-  const problem = isParsedProblem(body) ? body : parseProblemDetails(body);
   const fieldErrors: Record<string, string> = {};
   const unmatched: ProblemFieldError[] = [];
   if (!problem || problem.errors.length === 0) {
@@ -304,7 +298,7 @@ export function mapFieldErrors(
     const key = findField(error, locations);
     if (key === undefined) unmatched.push(error);
     else
-      fieldErrors[key] = fieldErrors[key]
+      fieldErrors[key] = Object.prototype.hasOwnProperty.call(fieldErrors, key)
         ? `${fieldErrors[key]} ${error.detail}`
         : error.detail;
   });

From 93ffcdd0db95b1e72268dbf2b15c5196e08ea135 Mon Sep 17 00:00:00 2001
From: Alex Kanitz <alexanderkanitz@gmail.com>
Date: Fri, 13 Nov 2026 09:54:16 +0100
Subject: [PATCH 05/11] fix(design): harden checkbox message and mapping

The checkbox message no longer catches clicks meant for content below
it, and the docs say that long messages don't wrap. mapFieldErrors()
gives a general error for problem details without an errors array
instead of throwing, e.g. for untyped callers.

Refs #535

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 apps/documentation/pages/docs/design/components/checkbox.mdx  | 2 +-
 packages/ecc-utils-design/src/components/checkbox/checkbox.ts | 2 +-
 packages/ecc-utils-design/src/utils/problem-details.ts        | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/apps/documentation/pages/docs/design/components/checkbox.mdx b/apps/documentation/pages/docs/design/components/checkbox.mdx
index ec0b241d..0097d36d 100644
--- a/apps/documentation/pages/docs/design/components/checkbox.mdx
+++ b/apps/documentation/pages/docs/design/components/checkbox.mdx
@@ -195,7 +195,7 @@ The value attribute, used when submitting the checkbox as part of a form.
 </Tabs>
 
 ### `invalid` and `error`
-`error` shows a message under the checkbox, e.g. one that an API returned for this field (see [Field errors](/docs/design/field-errors)), and marks the checkbox as invalid: it gets a red border, `aria-invalid="true"` and `aria-describedby` pointing to the message, and screen readers announce the message (`aria-live="polite"`). `invalid` marks the checkbox as invalid without a message, e.g. when the message is shown elsewhere. Clear both when the user changes the value or submits again. The message has the part `error` for styling (`ecc-utils-design-checkbox::part(error)`). Unlike the other controls' messages, it is positioned under the box without taking space (so that it doesn't widen or shift the box next to its label): leave room below the checkbox, e.g. with a margin.
+`error` shows a message under the checkbox, e.g. one that an API returned for this field (see [Field errors](/docs/design/field-errors)), and marks the checkbox as invalid: it gets a red border, `aria-invalid="true"` and `aria-describedby` pointing to the message, and screen readers announce the message (`aria-live="polite"`). `invalid` marks the checkbox as invalid without a message, e.g. when the message is shown elsewhere. Clear both when the user changes the value or submits again. The message has the part `error` for styling (`ecc-utils-design-checkbox::part(error)`). Unlike the other controls' messages, it is positioned under the box without taking space (so that it doesn't widen or shift the box next to its label): leave room below the checkbox, e.g. with a margin. Long messages don't wrap.
 
 <Tabs items={['React', 'HTML']}>
   <Tabs.Tab>
diff --git a/packages/ecc-utils-design/src/components/checkbox/checkbox.ts b/packages/ecc-utils-design/src/components/checkbox/checkbox.ts
index ff938b23..71ae018d 100644
--- a/packages/ecc-utils-design/src/components/checkbox/checkbox.ts
+++ b/packages/ecc-utils-design/src/components/checkbox/checkbox.ts
@@ -84,7 +84,7 @@ export class EccUtilsDesignCheckbox extends LitElement {
           id="error"
           part="error"
           class=${cn(
-            "absolute left-0 top-full whitespace-nowrap text-sm text-destructive",
+            "pointer-events-none absolute left-0 top-full whitespace-nowrap text-sm text-destructive",
             !!this.error && "mt-1.5"
           )}
           aria-live="polite"
diff --git a/packages/ecc-utils-design/src/utils/problem-details.ts b/packages/ecc-utils-design/src/utils/problem-details.ts
index dcf2cced..42bfcc1f 100644
--- a/packages/ecc-utils-design/src/utils/problem-details.ts
+++ b/packages/ecc-utils-design/src/utils/problem-details.ts
@@ -281,7 +281,7 @@ export function mapFieldErrors(
 ): MappedFieldErrors {
   const fieldErrors: Record<string, string> = {};
   const unmatched: ProblemFieldError[] = [];
-  if (!problem || problem.errors.length === 0) {
+  if (!problem || !Array.isArray(problem.errors) || !problem.errors.length) {
     return {
       problem,
       fieldErrors,

From dbc8e90a0088b66596b1038cce8962aa401486dd Mon Sep 17 00:00:00 2001
From: Alex Kanitz <alexanderkanitz@gmail.com>
Date: Fri, 13 Nov 2026 12:00:50 +0100
Subject: [PATCH 06/11] fix(design): address automated review

- Extension members and field keys named __proto__ are kept as own
  data instead of changing prototypes.
- Pointers with invalid ~ escapes are rejected (RFC 6901).
- Bodies with only instance are recognized as problem details.
- The general error names the member with the empty key (/).
- Docs example: only the latest submission shows its errors.
- Tests check that described-by copies are hidden, that
  aria-describedby is removed with the error, and the parsed JSON.

Refs #535

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../pages/docs/design/field-errors.mdx        | 13 ++++-
 .../src/form-controls.test.ts                 |  6 +++
 .../src/utils/problem-details.test.ts         | 47 +++++++++++++++--
 .../src/utils/problem-details.ts              | 50 +++++++++++++------
 4 files changed, 95 insertions(+), 21 deletions(-)

diff --git a/apps/documentation/pages/docs/design/field-errors.mdx b/apps/documentation/pages/docs/design/field-errors.mdx
index 2c3da397..94e4f430 100644
--- a/apps/documentation/pages/docs/design/field-errors.mdx
+++ b/apps/documentation/pages/docs/design/field-errors.mdx
@@ -103,7 +103,12 @@ export class ServiceForm extends LitElement {
   @state() private fieldErrors: Record<string, string> = {};
   @state() private generalError = '';
 
+  // Only the latest submission shows its errors
+  private submission = 0;
+
   private async submit(body: unknown) {
+    this.submission += 1;
+    const submission = this.submission;
     this.fieldErrors = {};
     this.generalError = '';
     let response: Response;
@@ -114,12 +119,16 @@ export class ServiceForm extends LitElement {
         body: JSON.stringify(body),
       });
     } catch {
-      this.generalError = 'The registry could not be reached.';
+      if (submission === this.submission) {
+        this.generalError = 'The registry could not be reached.';
+      }
       return;
     }
     if (response.ok) return;
+    const problem = await readProblemDetails(response);
+    if (submission !== this.submission) return;
     const mapped = mapFieldErrors(
-      await readProblemDetails(response),
+      problem,
       FIELDS,
       `The service could not be registered (${response.status}).`,
     );
diff --git a/packages/ecc-utils-design/src/form-controls.test.ts b/packages/ecc-utils-design/src/form-controls.test.ts
index e62b2dd5..e5a07399 100644
--- a/packages/ecc-utils-design/src/form-controls.test.ts
+++ b/packages/ecc-utils-design/src/form-controls.test.ts
@@ -79,6 +79,7 @@ describe("form controls: invalid state and error message", () => {
         await el.updateComplete;
         const control = el.shadowRoot!.querySelector(selector)!;
         expect(control.hasAttribute("aria-invalid")).to.equal(false);
+        expect(control.hasAttribute("aria-describedby")).to.equal(false);
         expect(errorElement(el).textContent?.trim()).to.equal("");
         expect(control.className).to.not.contain("border-destructive");
       });
@@ -138,6 +139,10 @@ describe("form controls: invalid state and error message", () => {
         );
         expect(button().getAttribute("aria-invalid")).to.equal("true");
         const describedBy = button().getAttribute("aria-describedby")!;
+        // Hidden, so that the message isn't read twice
+        expect(
+          trigger.shadowRoot!.getElementById(describedBy)!.hidden
+        ).to.equal(true);
         expect(
           trigger.shadowRoot!.getElementById(describedBy)!.textContent?.trim()
         ).to.equal("Must be one of: a, b.");
@@ -147,6 +152,7 @@ describe("form controls: invalid state and error message", () => {
         await el.updateComplete;
         await trigger.updateComplete;
         expect(button().hasAttribute("aria-invalid")).to.equal(false);
+        expect(button().hasAttribute("aria-describedby")).to.equal(false);
         expect(button().className).to.not.contain("border-destructive");
 
         el.invalid = true;
diff --git a/packages/ecc-utils-design/src/utils/problem-details.test.ts b/packages/ecc-utils-design/src/utils/problem-details.test.ts
index 1ab34692..a20a58a6 100644
--- a/packages/ecc-utils-design/src/utils/problem-details.test.ts
+++ b/packages/ecc-utils-design/src/utils/problem-details.test.ts
@@ -44,6 +44,8 @@ describe("normalizePointer()", () => {
     expect(normalizePointer("organization/url")).to.equal(undefined);
     expect(normalizePointer("#organization")).to.equal(undefined);
     expect(normalizePointer("#/%E0%A4%A")).to.equal(undefined);
+    expect(normalizePointer("/a~2b")).to.equal(undefined);
+    expect(normalizePointer("/a~")).to.equal(undefined);
   });
 });
 
@@ -96,6 +98,12 @@ describe("parseProblemDetails()", () => {
     expect(problem?.errors[1].pointer).to.equal("/url");
   });
 
+  it("recognizes problem details by any standard member", () => {
+    expect(parseProblemDetails({ instance: "/requests/1" })?.instance).to.equal(
+      "/requests/1"
+    );
+  });
+
   it("defaults the type and ignores members of the wrong type", () => {
     const problem = parseProblemDetails({
       title: 1,
@@ -148,9 +156,12 @@ describe("readProblemDetails()", () => {
       response(body, "application/problem+json; charset=utf-8")
     );
     expect(problem?.errors).to.have.length(2);
-    expect(
-      await readProblemDetails(response(body, "application/json"))
-    ).to.not.equal(undefined);
+    const json = await readProblemDetails(response(body, "application/json"));
+    expect(json?.title).to.equal(RFC_EXAMPLE.title);
+    expect(json?.errors.map((e) => e.pointer)).to.deep.equal([
+      "/age",
+      "/profile/color",
+    ]);
   });
 
   it("returns undefined for other bodies", async () => {
@@ -302,6 +313,36 @@ describe("mapFieldErrors()", () => {
     expect(mapped.fieldErrors.constructor).to.equal("B.");
   });
 
+  it("names the member with the empty key", () => {
+    const mapped = mapBody(
+      { errors: [{ detail: "E.", pointer: "#/" }] },
+      fields
+    );
+    expect(mapped.generalError).to.equal("/: E.");
+  });
+
+  it("keeps __proto__ as data", () => {
+    const problem = parseProblemDetails(
+      JSON.parse(
+        '{"title": "T", "__proto__": {"polluted": 1}, ' +
+          '"errors": [{"detail": "P.", "pointer": "#/__proto__"}]}'
+      )
+    );
+    expect(Object.getPrototypeOf(problem?.extensions)).to.equal(
+      Object.prototype
+    );
+    expect(Object.keys(problem!.extensions)).to.deep.equal(["__proto__"]);
+    // A field key `__proto__` (from JSON, as an own member)
+    const fieldsOfForm = JSON.parse('{"__proto__": "/__proto__"}');
+    const mapped = mapFieldErrors(problem, fieldsOfForm);
+    expect(
+      Object.getOwnPropertyDescriptor(mapped.fieldErrors, "__proto__")?.value
+    ).to.equal("P.");
+    expect(Object.getPrototypeOf(mapped.fieldErrors)).to.equal(
+      Object.prototype
+    );
+  });
+
   it("returns the problem details it was given", () => {
     const problem = parseProblemDetails(RFC_EXAMPLE);
     const mapped = mapFieldErrors(problem, fields);
diff --git a/packages/ecc-utils-design/src/utils/problem-details.ts b/packages/ecc-utils-design/src/utils/problem-details.ts
index 42bfcc1f..f3f8a988 100644
--- a/packages/ecc-utils-design/src/utils/problem-details.ts
+++ b/packages/ecc-utils-design/src/utils/problem-details.ts
@@ -81,14 +81,15 @@ export interface MappedFieldErrors {
   generalError: string | undefined;
 }
 
-const STANDARD_MEMBERS = new Set([
+const STANDARD_MEMBERS_LIST = [
   "type",
   "title",
   "status",
   "detail",
   "instance",
   "errors",
-]);
+];
+const STANDARD_MEMBERS = new Set(STANDARD_MEMBERS_LIST);
 
 function isObject(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -116,9 +117,21 @@ export function normalizePointer(pointer: string): string | undefined {
     }
   }
   if (plain !== "" && !plain.startsWith("/")) return undefined;
+  // `~` only as `~0` or `~1` (RFC 6901)
+  if (/~(?![01])/.test(plain)) return undefined;
   return plain;
 }
 
+// Set a member as own data, also for keys like `__proto__`
+function setOwn(target: Record<string, unknown>, key: string, value: unknown) {
+  Object.defineProperty(target, key, {
+    value,
+    enumerable: true,
+    writable: true,
+    configurable: true,
+  });
+}
+
 function parseFieldError(entry: unknown): ProblemFieldError | undefined {
   if (!isObject(entry)) return undefined;
   const detail = optionalString(entry.detail);
@@ -149,11 +162,10 @@ function parseFieldError(entry: unknown): ProblemFieldError | undefined {
  */
 export function parseProblemDetails(body: unknown): ProblemDetails | undefined {
   if (!isObject(body)) return undefined;
-  if (!["type", "title", "status", "detail", "errors"].some((m) => m in body))
-    return undefined;
+  if (!STANDARD_MEMBERS_LIST.some((member) => member in body)) return undefined;
   const extensions: Record<string, unknown> = {};
   Object.keys(body).forEach((key) => {
-    if (!STANDARD_MEMBERS.has(key)) extensions[key] = body[key];
+    if (!STANDARD_MEMBERS.has(key)) setOwn(extensions, key, body[key]);
   });
   const errors = Array.isArray(body.errors)
     ? body.errors
@@ -247,14 +259,16 @@ function findField(
 
 function describeUnmatched(error: ProblemFieldError): string {
   // E.g. `organization/url`, with keys unescaped (RFC 6901)
-  const location =
-    error.parameter ??
-    error.pointer
-      ?.slice(1)
-      .split("/")
-      .map((key) => key.replace(/~1/g, "/").replace(/~0/g, "~"))
-      .join("/");
-  return location ? `${location}: ${error.detail}` : error.detail;
+  if (error.parameter) return `${error.parameter}: ${error.detail}`;
+  // No location for the whole body (`""`)
+  if (!error.pointer) return error.detail;
+  const location = error.pointer
+    .slice(1)
+    .split("/")
+    .map((key) => key.replace(/~1/g, "/").replace(/~0/g, "~"))
+    .join("/");
+  // `/` points to the member with the empty key
+  return `${location || error.pointer}: ${error.detail}`;
 }
 
 /**
@@ -298,9 +312,13 @@ export function mapFieldErrors(
     const key = findField(error, locations);
     if (key === undefined) unmatched.push(error);
     else
-      fieldErrors[key] = Object.prototype.hasOwnProperty.call(fieldErrors, key)
-        ? `${fieldErrors[key]} ${error.detail}`
-        : error.detail;
+      setOwn(
+        fieldErrors,
+        key,
+        Object.prototype.hasOwnProperty.call(fieldErrors, key)
+          ? `${fieldErrors[key]} ${error.detail}`
+          : error.detail
+      );
   });
   return {
     problem,

From 2f14e7e3aef356da6da0e8c9cc09c2b9c5557e0d Mon Sep 17 00:00:00 2001
From: Alex Kanitz <alexanderkanitz@gmail.com>
Date: Sat, 14 Nov 2026 19:13:25 +0100
Subject: [PATCH 07/11] feat(design): export utils from a subpath

Add the subpath export @elixir-cloud/design/utils and build
src/utils/index.ts as a tsup entry, so that apps can import the
problem details utilities without registering every component
(including the Ace-based code editor), as the package root does.

The build entries move to getBuildEntries() in scripts/utils.js,
with tests. The Field errors page imports from the subpath.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../pages/docs/design/field-errors.mdx        | 17 +++-
 packages/ecc-utils-design/package.json        |  4 +
 .../ecc-utils-design/src/utils/index.test.ts  | 22 ++++++
 scripts/build.js                              | 14 +---
 scripts/utils.js                              | 20 +++++
 scripts/utils.test.js                         | 79 ++++++++++++++++++-
 6 files changed, 139 insertions(+), 17 deletions(-)
 create mode 100644 packages/ecc-utils-design/src/utils/index.test.ts

diff --git a/apps/documentation/pages/docs/design/field-errors.mdx b/apps/documentation/pages/docs/design/field-errors.mdx
index 94e4f430..dbbf256e 100644
--- a/apps/documentation/pages/docs/design/field-errors.mdx
+++ b/apps/documentation/pages/docs/design/field-errors.mdx
@@ -8,12 +8,14 @@ design package has the two parts for this:
 
 - The form controls ([input](/docs/design/components/input),
   [textarea](/docs/design/components/textarea),
-  [checkbox](/docs/design/components/checkbox),
   [select](/docs/design/components/select) and
   [multi-select](/docs/design/components/multi-select)) have the properties
   `error` and `invalid`: `error` shows a message under the control and marks it
   as invalid (red border, `aria-invalid`, `aria-describedby`, announced to
-  screen readers), `invalid` marks it as invalid without a message.
+  screen readers), `invalid` marks it as invalid without a message. The
+  [checkbox](/docs/design/components/checkbox) has only `invalid`, as a
+  message under the box wouldn't wrap next to its label: show the checkbox's
+  message elsewhere, e.g. with the general error.
 - Utilities that read the errors of a response in the standard format,
   problem details ([RFC 9457](https://www.rfc-editor.org/rfc/rfc9457),
   `application/problem+json`), and map them to the component's fields.
@@ -55,7 +57,13 @@ problem type), and any other API can respond the same way.
 
 ## Utilities
 
-All are exported by `@elixir-cloud/design`:
+Import them from `@elixir-cloud/design/utils`, which loads only the
+utilities. The package root (`@elixir-cloud/design`) exports them too, but
+importing it registers every component (including the code editor):
+
+```ts
+import { mapFieldErrors, readProblemDetails } from '@elixir-cloud/design/utils';
+```
 
 | Function                                     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
 | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
@@ -90,7 +98,8 @@ at its fields:
 ```ts copy filename="service-form.ts"
 import { html, LitElement } from 'lit';
 import { state } from 'lit/decorators.js';
-import { mapFieldErrors, readProblemDetails } from '@elixir-cloud/design';
+import { mapFieldErrors, readProblemDetails } from '@elixir-cloud/design/utils';
+import '@elixir-cloud/design/components/input/index.js';
 
 // The component's fields and their locations in the request body
 const FIELDS = {
diff --git a/packages/ecc-utils-design/package.json b/packages/ecc-utils-design/package.json
index 4de95ebd..b242ec0d 100644
--- a/packages/ecc-utils-design/package.json
+++ b/packages/ecc-utils-design/package.json
@@ -16,6 +16,10 @@
     "./components/*": "./dist/components/*",
     "./react": "./dist/react/index.js",
     "./react/*": "./dist/react/*",
+    "./utils": {
+      "types": "./dist/utils/index.d.ts",
+      "import": "./dist/utils/index.js"
+    },
     "./events": "./dist/events/index.js",
     "./events/*": "./dist/events/*"
   },
diff --git a/packages/ecc-utils-design/src/utils/index.test.ts b/packages/ecc-utils-design/src/utils/index.test.ts
new file mode 100644
index 00000000..5e3a85bf
--- /dev/null
+++ b/packages/ecc-utils-design/src/utils/index.test.ts
@@ -0,0 +1,22 @@
+/* eslint-disable import/no-extraneous-dependencies */
+import { expect } from "@open-wc/testing";
+import * as utils from "./index.js";
+
+// The `./utils` subpath export of the package; test files run in pages of
+// their own, so nothing else registers components here
+describe("utils entry point", () => {
+  it("exports the problem details utilities", () => {
+    expect(utils.readProblemDetails).to.be.a("function");
+    expect(utils.parseProblemDetails).to.be.a("function");
+    expect(utils.mapFieldErrors).to.be.a("function");
+    expect(utils.normalizePointer).to.be.a("function");
+  });
+
+  it("registers no components", () => {
+    ["input", "checkbox", "code", "select"].forEach((name) => {
+      expect(customElements.get(`ecc-utils-design-${name}`)).to.equal(
+        undefined
+      );
+    });
+  });
+});
diff --git a/scripts/build.js b/scripts/build.js
index bbe82ff0..5de60abe 100644
--- a/scripts/build.js
+++ b/scripts/build.js
@@ -5,12 +5,11 @@
 // TODO
 // Add cleanup function for when an errror is encountered or user terminates process
 const { cwd } = require("process");
-const fg = require("fast-glob");
 const tsup = require("tsup");
 const { program } = require("commander");
 const { execFileSync } = require("child_process");
 const fs = require("fs");
-const { npmDir, normalizePath } = require("./utils.js");
+const { npmDir, getBuildEntries } = require("./utils.js");
 const path = require("path");
 const { reactDir } = require("./utils.js");
 
@@ -119,16 +118,7 @@ nextTask("Building source", async () => {
     format: "esm",
     target: "es2017",
     platform: "browser",
-    entry: [
-      normalizePath(`${sourceDir}/index.ts`),
-      ...(await fg(normalizePath(`${sourceDir}/components/**/!(*.(test)).ts`), {
-        ignore: ["**/tests/**"],
-      })),
-      ...(await fg(normalizePath(`${sourceDir}/providers/**/*.ts`), {
-        ignore: ["**/tests/**"],
-      })),
-      ...(await fg(normalizePath(`${sourceDir}/react/**/*.ts`))),
-    ],
+    entry: getBuildEntries(sourceDir),
     splitting: true,
     treeshake: true,
     bundle: true,
diff --git a/scripts/utils.js b/scripts/utils.js
index cddae9cb..bf167612 100644
--- a/scripts/utils.js
+++ b/scripts/utils.js
@@ -1,4 +1,5 @@
 const path = require("path");
+const fg = require("fast-glob");
 const cwd = require("process").cwd;
 
 const componentsPrefix = "ecc-utils-design-";
@@ -50,8 +51,27 @@ function escapeTemplateLiteral(text) {
     .replaceAll("${", "\\${");
 }
 
+// The entry points that tsup builds from a package's source directory: the
+// root, every component, provider and React wrapper, and the utilities
+// (`utils/index.ts`, if any), which a package exports as a subpath of its
+// own, so that apps can import them without registering the components
+function getBuildEntries(sourceDir) {
+  // fast-glob takes forward slashes only
+  const dir = normalizePath(sourceDir);
+  return [
+    `${dir}/index.ts`,
+    ...fg.sync(`${dir}/components/**/!(*.(test)).ts`, {
+      ignore: ["**/tests/**"],
+    }),
+    ...fg.sync(`${dir}/providers/**/*.ts`, { ignore: ["**/tests/**"] }),
+    ...fg.sync(`${dir}/react/**/*.ts`),
+    ...fg.sync(`${dir}/utils/index.ts`),
+  ];
+}
+
 module.exports = {
   componentsPrefix,
+  getBuildEntries,
   npmDir,
   getAllComponents,
   pascalCase,
diff --git a/scripts/utils.test.js b/scripts/utils.test.js
index 805526c4..d4b3a6cf 100644
--- a/scripts/utils.test.js
+++ b/scripts/utils.test.js
@@ -1,9 +1,12 @@
 // Tests for scripts/utils.js; run with `node --test scripts/utils.test.js`
 
 const assert = require("assert");
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
 const { test } = require("node:test");
 
-const { escapeTemplateLiteral } = require("./utils.js");
+const { escapeTemplateLiteral, getBuildEntries } = require("./utils.js");
 
 // What a template literal with the escaped text in it evaluates to
 const evaluate = (escaped) =>
@@ -32,3 +35,77 @@ test("backslashes are escaped before backticks", () => {
   assert.strictEqual(escapeTemplateLiteral("\\"), "\\\\");
   assert.strictEqual(escapeTemplateLiteral("\\`"), "\\\\\\`");
 });
+
+// A source directory with the given (empty) files, paths relative to it
+function makeSourceDir(files) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "build-entries-"));
+  files.forEach((file) => {
+    fs.mkdirSync(path.dirname(path.join(dir, file)), { recursive: true });
+    fs.writeFileSync(path.join(dir, file), "");
+  });
+  return dir;
+}
+
+// The build entries of a source directory, relative to it and sorted
+function relativeEntries(dir) {
+  return getBuildEntries(dir)
+    .map((entry) => path.relative(dir, entry).split(path.sep).join("/"))
+    .sort();
+}
+
+test("build entries: root, components, providers, react and utils", () => {
+  const dir = makeSourceDir([
+    "index.ts",
+    "components/input/index.ts",
+    "components/input/input.ts",
+    "components/input/input.test.ts",
+    "components/input/tests/helper.ts",
+    "providers/api.ts",
+    "providers/tests/mock.ts",
+    "react/input.ts",
+    "utils/index.ts",
+    "utils/problem-details.ts",
+    "utils/problem-details.test.ts",
+  ]);
+  try {
+    assert.deepStrictEqual(relativeEntries(dir), [
+      "components/input/index.ts",
+      "components/input/input.ts",
+      "index.ts",
+      "providers/api.ts",
+      "react/input.ts",
+      "utils/index.ts",
+    ]);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("build entries: no utils entry without utils/index.ts", () => {
+  const dir = makeSourceDir(["index.ts", "components/a/index.ts"]);
+  try {
+    assert.deepStrictEqual(relativeEntries(dir), [
+      "components/a/index.ts",
+      "index.ts",
+    ]);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+// Apps import the utilities from `@elixir-cloud/design/utils` without
+// registering the components
+test("design package exports ./utils", () => {
+  const packageJson = path.join(
+    __dirname,
+    "..",
+    "packages",
+    "ecc-utils-design",
+    "package.json"
+  );
+  const { exports } = JSON.parse(fs.readFileSync(packageJson, "utf-8"));
+  assert.deepStrictEqual(exports["./utils"], {
+    types: "./dist/utils/index.d.ts",
+    import: "./dist/utils/index.js",
+  });
+});

From fa175ee89b5e53b444c095be5be02669e2367673 Mon Sep 17 00:00:00 2001
From: Alex Kanitz <alexanderkanitz@gmail.com>
Date: Sat, 14 Nov 2026 19:17:48 +0100
Subject: [PATCH 08/11] refactor(design): drop error from the checkbox

Keep only invalid on the checkbox: its message didn't wrap and
overflowed when the checkbox is at the end of a row, as in the TES
run-create form. Docs and changeset say to show the message
elsewhere.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .changeset/design-field-errors.md             |  2 +-
 .../pages/docs/design/components/checkbox.mdx | 11 ++-
 .../src/components/checkbox/checkbox.ts       | 79 ++++++++-----------
 .../src/form-controls.test.ts                 | 56 +++++++++++--
 4 files changed, 87 insertions(+), 61 deletions(-)

diff --git a/.changeset/design-field-errors.md b/.changeset/design-field-errors.md
index 270822f6..c3c54e5f 100644
--- a/.changeset/design-field-errors.md
+++ b/.changeset/design-field-errors.md
@@ -2,4 +2,4 @@
 "@elixir-cloud/design": minor
 ---
 
-Show field errors returned by APIs: the form controls (input, textarea, checkbox, select, multi-select) get the properties `invalid` and `error` (message under the control, `aria-invalid`, `aria-describedby`, announced with `aria-live`), and new utilities read RFC 9457 problem details (`readProblemDetails()`, `parseProblemDetails()`) and map their field errors to a component's fields (`mapFieldErrors()`).
+Show field errors returned by APIs: the form controls (input, textarea, select, multi-select) get the properties `invalid` and `error` (message under the control, `aria-invalid`, `aria-describedby`, announced with `aria-live`), the checkbox gets `invalid`, and new utilities read RFC 9457 problem details (`readProblemDetails()`, `parseProblemDetails()`) and map their field errors to a component's fields (`mapFieldErrors()`). The utilities are exported from the new subpath `@elixir-cloud/design/utils`, which registers no components, and from the package root.
diff --git a/apps/documentation/pages/docs/design/components/checkbox.mdx b/apps/documentation/pages/docs/design/components/checkbox.mdx
index 0097d36d..f7b7bad9 100644
--- a/apps/documentation/pages/docs/design/components/checkbox.mdx
+++ b/apps/documentation/pages/docs/design/components/checkbox.mdx
@@ -127,8 +127,7 @@ This example shows a checkbox in a disabled state.
 | `disabled` | `boolean` | `false` | When `true`, disables the checkbox.       |
 | `name`     | `string`  | `""`    | The name of the checkbox for form submission. |
 | `value`    | `string`  | `""`    | The value of the checkbox for form submission. |
-| `invalid` | `boolean` | `false` | When `true`, marks the checkbox as invalid (also implied by `error`). |
-| `error`   | `string`  | `""`    | Error message shown under the checkbox, e.g. from an API. |
+| `invalid` | `boolean` | `false` | When `true`, marks the checkbox as invalid, e.g. after an API rejected its value. |
 
 ### `checked`
 Controls the checked state of the checkbox.
@@ -194,18 +193,18 @@ The value attribute, used when submitting the checkbox as part of a form.
   </Tabs.Tab>
 </Tabs>
 
-### `invalid` and `error`
-`error` shows a message under the checkbox, e.g. one that an API returned for this field (see [Field errors](/docs/design/field-errors)), and marks the checkbox as invalid: it gets a red border, `aria-invalid="true"` and `aria-describedby` pointing to the message, and screen readers announce the message (`aria-live="polite"`). `invalid` marks the checkbox as invalid without a message, e.g. when the message is shown elsewhere. Clear both when the user changes the value or submits again. The message has the part `error` for styling (`ecc-utils-design-checkbox::part(error)`). Unlike the other controls' messages, it is positioned under the box without taking space (so that it doesn't widen or shift the box next to its label): leave room below the checkbox, e.g. with a margin. Long messages don't wrap.
+### `invalid`
+Marks the checkbox as invalid, e.g. when an API rejected its value (see [Field errors](/docs/design/field-errors)): it gets a red border and `aria-invalid="true"`. Clear it when the user changes the value or submits again. Unlike the other form controls, the checkbox has no `error` property: a message under the box wouldn't wrap next to its label, e.g. when the checkbox is at the end of a row. Show the message elsewhere, e.g. with the form's general error or next to the label.
 
 <Tabs items={['React', 'HTML']}>
   <Tabs.Tab>
     ```tsx copy
-    <EccUtilsDesignCheckbox error="Is required." />
+    <EccUtilsDesignCheckbox invalid={true} />
     ```
   </Tabs.Tab>
   <Tabs.Tab>
     ```html copy
-    <ecc-utils-design-checkbox error="Is required."></ecc-utils-design-checkbox>
+    <ecc-utils-design-checkbox invalid></ecc-utils-design-checkbox>
     ```
   </Tabs.Tab>
 </Tabs>
diff --git a/packages/ecc-utils-design/src/components/checkbox/checkbox.ts b/packages/ecc-utils-design/src/components/checkbox/checkbox.ts
index 71ae018d..0c2d4ad4 100644
--- a/packages/ecc-utils-design/src/components/checkbox/checkbox.ts
+++ b/packages/ecc-utils-design/src/components/checkbox/checkbox.ts
@@ -23,23 +23,22 @@ export class EccUtilsDesignCheckbox extends LitElement {
   @property({ type: String }) name = "";
   @property({ type: String }) value = "";
   /**
-   * Whether the value is invalid; also implied by a non-empty `error`.
+   * Whether the value is invalid, e.g. after an API rejected it. Unlike the
+   * other form controls, the checkbox has no `error` message: it wouldn't
+   * wrap next to the box's label, so show the message elsewhere.
    */
   @property({ type: Boolean, reflect: true }) invalid = false;
-  /** Error message shown under the checkbox, e.g. one returned by an API. */
-  @property({ type: String }) error = "";
   @state() private _focused = false;
 
   render() {
-    const isInvalid = this.invalid || !!this.error;
     const checkboxClasses = cn(
       "peer h-4 w-4 shrink-0 rounded-[4px] border shadow focus-visible:outline-none focus-visible:ring-1 disabled:cursor-not-allowed disabled:opacity-50",
-      isInvalid
+      this.invalid
         ? "border-destructive focus-visible:ring-destructive"
         : "border-primary focus-visible:ring-ring",
       this.checked && "bg-primary text-primary-foreground",
       this._focused &&
-        (isInvalid ? "ring-1 ring-destructive" : "ring-1 ring-ring")
+        (this.invalid ? "ring-1 ring-destructive" : "ring-1 ring-ring")
     );
 
     const indicatorClasses = cn(
@@ -47,50 +46,34 @@ export class EccUtilsDesignCheckbox extends LitElement {
       !this.checked && "opacity-0"
     );
 
-    // The message is positioned under the box without taking space, so
-    // that it neither widens nor shifts the box next to its label
     return html`
-      <div class="relative">
-        <div
-          part="base"
-          class=${checkboxClasses}
-          role="checkbox"
-          aria-checked=${this.checked ? "true" : "false"}
-          aria-disabled=${this.disabled ? "true" : "false"}
-          aria-invalid=${ifDefined(isInvalid ? "true" : undefined)}
-          aria-describedby=${ifDefined(this.error ? "error" : undefined)}
-          tabindex=${this.disabled ? "-1" : "0"}
-          @click=${this._handleClick}
-          @keydown=${this._handleKeydown}
-          @focus=${this._handleFocus}
-          @blur=${this._handleBlur}
-        >
-          <div class=${indicatorClasses}>
-            <svg
-              xmlns="http://www.w3.org/2000/svg"
-              viewBox="0 0 24 24"
-              fill="none"
-              stroke="currentColor"
-              stroke-width="2"
-              stroke-linecap="round"
-              stroke-linejoin="round"
-              class="h-4 w-4"
-            >
-              <path d="M20 6 9 17l-5-5" />
-            </svg>
-          </div>
+      <div
+        part="base"
+        class=${checkboxClasses}
+        role="checkbox"
+        aria-checked=${this.checked ? "true" : "false"}
+        aria-disabled=${this.disabled ? "true" : "false"}
+        aria-invalid=${ifDefined(this.invalid ? "true" : undefined)}
+        tabindex=${this.disabled ? "-1" : "0"}
+        @click=${this._handleClick}
+        @keydown=${this._handleKeydown}
+        @focus=${this._handleFocus}
+        @blur=${this._handleBlur}
+      >
+        <div class=${indicatorClasses}>
+          <svg
+            xmlns="http://www.w3.org/2000/svg"
+            viewBox="0 0 24 24"
+            fill="none"
+            stroke="currentColor"
+            stroke-width="2"
+            stroke-linecap="round"
+            stroke-linejoin="round"
+            class="h-4 w-4"
+          >
+            <path d="M20 6 9 17l-5-5" />
+          </svg>
         </div>
-        <p
-          id="error"
-          part="error"
-          class=${cn(
-            "pointer-events-none absolute left-0 top-full whitespace-nowrap text-sm text-destructive",
-            !!this.error && "mt-1.5"
-          )}
-          aria-live="polite"
-        >
-          ${this.error}
-        </p>
       </div>
     `;
   }
diff --git a/packages/ecc-utils-design/src/form-controls.test.ts b/packages/ecc-utils-design/src/form-controls.test.ts
index e5a07399..11fe89fa 100644
--- a/packages/ecc-utils-design/src/form-controls.test.ts
+++ b/packages/ecc-utils-design/src/form-controls.test.ts
@@ -24,12 +24,6 @@ const controls: [string, () => Promise<FormControl>, string][] = [
       fixture(html`<ecc-utils-design-textarea></ecc-utils-design-textarea>`),
     "textarea",
   ],
-  [
-    "checkbox",
-    () =>
-      fixture(html`<ecc-utils-design-checkbox></ecc-utils-design-checkbox>`),
-    "[role=checkbox]",
-  ],
 ];
 
 function errorElement(el: LitElement): HTMLElement {
@@ -86,6 +80,56 @@ describe("form controls: invalid state and error message", () => {
     });
   });
 
+  // Only `invalid`: a message wouldn't wrap next to the box's label
+  describe("checkbox", () => {
+    const create = () =>
+      fixture<FormControl>(
+        html`<ecc-utils-design-checkbox></ecc-utils-design-checkbox>`
+      );
+    const box = (el: LitElement) =>
+      el.shadowRoot!.querySelector("[role=checkbox]")!;
+
+    it("is valid by default", async () => {
+      const el = await create();
+      expect(box(el).hasAttribute("aria-invalid")).to.equal(false);
+      expect(box(el).className).to.contain("border-primary");
+    });
+
+    it("can be marked invalid and valid again", async () => {
+      const el = await create();
+      el.invalid = true;
+      await el.updateComplete;
+      expect(el.hasAttribute("invalid")).to.equal(true);
+      expect(box(el).getAttribute("aria-invalid")).to.equal("true");
+      expect(box(el).className).to.contain("border-destructive");
+
+      el.invalid = false;
+      await el.updateComplete;
+      expect(box(el).hasAttribute("aria-invalid")).to.equal(false);
+      expect(box(el).className).to.not.contain("border-destructive");
+    });
+
+    it("takes the invalid state from the attribute", async () => {
+      const el = await fixture<FormControl>(
+        html`<ecc-utils-design-checkbox invalid></ecc-utils-design-checkbox>`
+      );
+      expect(box(el).getAttribute("aria-invalid")).to.equal("true");
+    });
+
+    it("shows no error message", async () => {
+      const el = await fixture<LitElement>(
+        html`<ecc-utils-design-checkbox
+          error="Is required."
+        ></ecc-utils-design-checkbox>`
+      );
+      expect(el.shadowRoot!.querySelector("[part=error]") === null).to.equal(
+        true
+      );
+      expect(box(el).hasAttribute("aria-invalid")).to.equal(false);
+      expect(box(el).hasAttribute("aria-describedby")).to.equal(false);
+    });
+  });
+
   it("takes the error from the attribute", async () => {
     const el = await fixture<FormControl>(
       html`<ecc-utils-design-input

From 9a7a8971d176400ef71f298b1eefe3f2ba0d89cf Mon Sep 17 00:00:00 2001
From: Alex Kanitz <alexanderkanitz@gmail.com>
Date: Sat, 14 Nov 2026 19:50:00 +0100
Subject: [PATCH 09/11] test: check the built design utils subpath

Add scripts/check-design-utils.mjs, run in CI after the build: the
built @elixir-cloud/design/utils subpath must export the utilities
and load neither Lit nor components. The build entry tests now clean
up with t.after() and check the design package's real entries.
Document the utils entry convention in the contributing guide and
split the changeset into bullets.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .changeset/design-field-errors.md             |  6 +-
 .github/workflows/ci.yml                      |  4 ++
 .../documentation/pages/docs/contributing.mdx | 12 +++-
 scripts/check-design-utils.mjs                | 23 +++++++
 scripts/utils.test.js                         | 64 +++++++++----------
 5 files changed, 72 insertions(+), 37 deletions(-)
 create mode 100644 scripts/check-design-utils.mjs

diff --git a/.changeset/design-field-errors.md b/.changeset/design-field-errors.md
index c3c54e5f..550a7918 100644
--- a/.changeset/design-field-errors.md
+++ b/.changeset/design-field-errors.md
@@ -2,4 +2,8 @@
 "@elixir-cloud/design": minor
 ---
 
-Show field errors returned by APIs: the form controls (input, textarea, select, multi-select) get the properties `invalid` and `error` (message under the control, `aria-invalid`, `aria-describedby`, announced with `aria-live`), the checkbox gets `invalid`, and new utilities read RFC 9457 problem details (`readProblemDetails()`, `parseProblemDetails()`) and map their field errors to a component's fields (`mapFieldErrors()`). The utilities are exported from the new subpath `@elixir-cloud/design/utils`, which registers no components, and from the package root.
+Show field errors returned by APIs.
+
+- Input, textarea, select and multi-select get the properties `invalid` and `error`: `error` shows a message under the control (`aria-invalid`, `aria-describedby`, announced with `aria-live`), `invalid` marks the control as invalid without a message.
+- The checkbox gets `invalid` only; show its message elsewhere.
+- New utilities read RFC 9457 problem details (`readProblemDetails()`, `parseProblemDetails()`) and map their field errors to a component's fields (`mapFieldErrors()`). Import them from the new subpath `@elixir-cloud/design/utils`, which registers no components; the package root exports them too.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 4f29a5e3..869ebb45 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -160,6 +160,10 @@ jobs:
       - name: Build
         run: npm run build
 
+      # The design package's `./utils` subpath must load without components
+      - name: Check design utils entry
+        run: node scripts/check-design-utils.mjs
+
       # With coverage (in Chromium, in `coverage/lcov.info` of each package
       # with tests; see `web-test.runner-config.mjs`) for the uploaded run
       - name: Run tests
diff --git a/apps/documentation/pages/docs/contributing.mdx b/apps/documentation/pages/docs/contributing.mdx
index 9129da88..6ace6c70 100644
--- a/apps/documentation/pages/docs/contributing.mdx
+++ b/apps/documentation/pages/docs/contributing.mdx
@@ -12,7 +12,8 @@ Keep the checks green: `CI passed` sums up the PR title, linting, tests
 (Node.js 22 and 24) and the other CI jobs. Run `npm run lint`,
 `npm run build` and `npm test` (and
 `node --test scripts/release.test.js` after changes to
-`scripts/release.js`) locally before you push. CI runs the tests with
+`scripts/release.js`, `node --test scripts/utils.test.js` after changes to
+`scripts/utils.js` or `scripts/build.js`) locally before you push. CI runs the tests with
 coverage (`npm run test -- -- --coverage`, which passes `--coverage`
 through npm and turbo to the test runner; Chromium only; each package's
 report is in its `coverage/` folder) and reports it to
@@ -20,6 +21,15 @@ report is in its `coverage/` folder) and reports it to
 coverage of the packages with tests must not drop by more than 1 %
 (`codecov.yml`).
 
+`scripts/build.js` builds every package from the entries that
+`getBuildEntries()` in `scripts/utils.js` lists: `src/index.ts`, the
+components, providers and React wrappers, and `src/utils/index.ts` if a
+package has one. That file is the entry of the package's `./utils` subpath
+(add it to the `exports` of the package's `package.json`): utilities that
+apps can import without registering the components, so it must not import
+them. For the design package, CI checks this after the build
+(`node scripts/check-design-utils.mjs`).
+
 Changesets are not used; versions are set in the version bump pull
 request of each release (see "Releases").
 
diff --git a/scripts/check-design-utils.mjs b/scripts/check-design-utils.mjs
new file mode 100644
index 00000000..c4d276b1
--- /dev/null
+++ b/scripts/check-design-utils.mjs
@@ -0,0 +1,23 @@
+// Checks the built `@elixir-cloud/design/utils` subpath (run after the
+// build): it exports the utilities and loads neither Lit nor any component.
+// Lit's Node build installs a `customElements` shim when it loads, so the
+// global stays undefined only if nothing imported Lit.
+
+const utils = await import("@elixir-cloud/design/utils");
+
+const expected = [
+  "mapFieldErrors",
+  "normalizePointer",
+  "parseProblemDetails",
+  "readProblemDetails",
+];
+const missing = expected.filter((name) => typeof utils[name] !== "function");
+if (missing.length > 0) {
+  console.error(`@elixir-cloud/design/utils lacks: ${missing.join(", ")}`);
+  process.exit(1);
+}
+if (globalThis.customElements !== undefined) {
+  console.error("@elixir-cloud/design/utils loads Lit or components");
+  process.exit(1);
+}
+console.log("@elixir-cloud/design/utils: ok");
diff --git a/scripts/utils.test.js b/scripts/utils.test.js
index d4b3a6cf..813446e3 100644
--- a/scripts/utils.test.js
+++ b/scripts/utils.test.js
@@ -36,9 +36,11 @@ test("backslashes are escaped before backticks", () => {
   assert.strictEqual(escapeTemplateLiteral("\\`"), "\\\\\\`");
 });
 
-// A source directory with the given (empty) files, paths relative to it
-function makeSourceDir(files) {
+// A source directory with the given (empty) files, paths relative to it,
+// removed after the test
+function makeSourceDir(t, files) {
   const dir = fs.mkdtempSync(path.join(os.tmpdir(), "build-entries-"));
+  t.after(() => fs.rmSync(dir, { recursive: true, force: true }));
   files.forEach((file) => {
     fs.mkdirSync(path.dirname(path.join(dir, file)), { recursive: true });
     fs.writeFileSync(path.join(dir, file), "");
@@ -53,8 +55,8 @@ function relativeEntries(dir) {
     .sort();
 }
 
-test("build entries: root, components, providers, react and utils", () => {
-  const dir = makeSourceDir([
+test("build entries: root, components, providers, react and utils", (t) => {
+  const dir = makeSourceDir(t, [
     "index.ts",
     "components/input/index.ts",
     "components/input/input.ts",
@@ -67,43 +69,35 @@ test("build entries: root, components, providers, react and utils", () => {
     "utils/problem-details.ts",
     "utils/problem-details.test.ts",
   ]);
-  try {
-    assert.deepStrictEqual(relativeEntries(dir), [
-      "components/input/index.ts",
-      "components/input/input.ts",
-      "index.ts",
-      "providers/api.ts",
-      "react/input.ts",
-      "utils/index.ts",
-    ]);
-  } finally {
-    fs.rmSync(dir, { recursive: true, force: true });
-  }
+  assert.deepStrictEqual(relativeEntries(dir), [
+    "components/input/index.ts",
+    "components/input/input.ts",
+    "index.ts",
+    "providers/api.ts",
+    "react/input.ts",
+    "utils/index.ts",
+  ]);
 });
 
-test("build entries: no utils entry without utils/index.ts", () => {
-  const dir = makeSourceDir(["index.ts", "components/a/index.ts"]);
-  try {
-    assert.deepStrictEqual(relativeEntries(dir), [
-      "components/a/index.ts",
-      "index.ts",
-    ]);
-  } finally {
-    fs.rmSync(dir, { recursive: true, force: true });
-  }
+test("build entries: no utils entry without utils/index.ts", (t) => {
+  const dir = makeSourceDir(t, ["index.ts", "components/a/index.ts"]);
+  assert.deepStrictEqual(relativeEntries(dir), [
+    "components/a/index.ts",
+    "index.ts",
+  ]);
 });
 
 // Apps import the utilities from `@elixir-cloud/design/utils` without
-// registering the components
-test("design package exports ./utils", () => {
-  const packageJson = path.join(
-    __dirname,
-    "..",
-    "packages",
-    "ecc-utils-design",
-    "package.json"
+// registering the components; CI checks the built subpath after the build
+// (`scripts/check-design-utils.mjs`)
+test("design package builds and exports ./utils", () => {
+  const packageDir = path.join(__dirname, "..", "packages", "ecc-utils-design");
+  assert.ok(
+    relativeEntries(path.join(packageDir, "src")).includes("utils/index.ts")
+  );
+  const { exports } = JSON.parse(
+    fs.readFileSync(path.join(packageDir, "package.json"), "utf-8")
   );
-  const { exports } = JSON.parse(fs.readFileSync(packageJson, "utf-8"));
   assert.deepStrictEqual(exports["./utils"], {
     types: "./dist/utils/index.d.ts",
     import: "./dist/utils/index.js",

From ed72f5ac6c105ce7c5308ee060c4d5be94c2027f Mon Sep 17 00:00:00 2001
From: Alex Kanitz <alexanderkanitz@gmail.com>
Date: Sat, 14 Nov 2026 20:17:30 +0100
Subject: [PATCH 10/11] fix(design): resolve utils types with node10

Add typesVersions for the utils subpath, so that TypeScript projects
with moduleResolution node, which ignores exports, find its types.
Say in the docs how to show a checkbox's field error: its message
is in fieldErrors, not in generalError.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 apps/documentation/pages/docs/contributing.mdx             | 3 ++-
 .../pages/docs/design/components/checkbox.mdx              | 2 +-
 apps/documentation/pages/docs/design/field-errors.mdx      | 5 +++--
 packages/ecc-utils-design/package.json                     | 7 +++++++
 scripts/utils.test.js                                      | 4 +++-
 5 files changed, 16 insertions(+), 5 deletions(-)

diff --git a/apps/documentation/pages/docs/contributing.mdx b/apps/documentation/pages/docs/contributing.mdx
index 6ace6c70..ce2dec88 100644
--- a/apps/documentation/pages/docs/contributing.mdx
+++ b/apps/documentation/pages/docs/contributing.mdx
@@ -25,7 +25,8 @@ coverage of the packages with tests must not drop by more than 1 %
 `getBuildEntries()` in `scripts/utils.js` lists: `src/index.ts`, the
 components, providers and React wrappers, and `src/utils/index.ts` if a
 package has one. That file is the entry of the package's `./utils` subpath
-(add it to the `exports` of the package's `package.json`): utilities that
+(add it to `exports` and, for TypeScript's `node` module resolution, to
+`typesVersions` in the package's `package.json`): utilities that
 apps can import without registering the components, so it must not import
 them. For the design package, CI checks this after the build
 (`node scripts/check-design-utils.mjs`).
diff --git a/apps/documentation/pages/docs/design/components/checkbox.mdx b/apps/documentation/pages/docs/design/components/checkbox.mdx
index f7b7bad9..494fd435 100644
--- a/apps/documentation/pages/docs/design/components/checkbox.mdx
+++ b/apps/documentation/pages/docs/design/components/checkbox.mdx
@@ -194,7 +194,7 @@ The value attribute, used when submitting the checkbox as part of a form.
 </Tabs>
 
 ### `invalid`
-Marks the checkbox as invalid, e.g. when an API rejected its value (see [Field errors](/docs/design/field-errors)): it gets a red border and `aria-invalid="true"`. Clear it when the user changes the value or submits again. Unlike the other form controls, the checkbox has no `error` property: a message under the box wouldn't wrap next to its label, e.g. when the checkbox is at the end of a row. Show the message elsewhere, e.g. with the form's general error or next to the label.
+Marks the checkbox as invalid, e.g. when an API rejected its value (see [Field errors](/docs/design/field-errors)): it gets a red border and `aria-invalid="true"`. Clear it when the user changes the value or submits again. Unlike the other form controls, the checkbox has no `error` property: a message under the box wouldn't wrap next to its label, e.g. when the checkbox is at the end of a row. Render the message yourself, e.g. next to the label or above the form: with `mapFieldErrors()`, set `invalid` when `fieldErrors` has a message for the checkbox's field key, and show that message (it is not part of `generalError`, which holds only the errors that match no field).
 
 <Tabs items={['React', 'HTML']}>
   <Tabs.Tab>
diff --git a/apps/documentation/pages/docs/design/field-errors.mdx b/apps/documentation/pages/docs/design/field-errors.mdx
index dbbf256e..a00538ff 100644
--- a/apps/documentation/pages/docs/design/field-errors.mdx
+++ b/apps/documentation/pages/docs/design/field-errors.mdx
@@ -14,8 +14,9 @@ design package has the two parts for this:
   as invalid (red border, `aria-invalid`, `aria-describedby`, announced to
   screen readers), `invalid` marks it as invalid without a message. The
   [checkbox](/docs/design/components/checkbox) has only `invalid`, as a
-  message under the box wouldn't wrap next to its label: show the checkbox's
-  message elsewhere, e.g. with the general error.
+  message under the box wouldn't wrap next to its label: give the checkbox a
+  field key, set `invalid` when `fieldErrors` has a message for it, and render
+  that message yourself, e.g. next to the label or above the form.
 - Utilities that read the errors of a response in the standard format,
   problem details ([RFC 9457](https://www.rfc-editor.org/rfc/rfc9457),
   `application/problem+json`), and map them to the component's fields.
diff --git a/packages/ecc-utils-design/package.json b/packages/ecc-utils-design/package.json
index b242ec0d..cdc6374c 100644
--- a/packages/ecc-utils-design/package.json
+++ b/packages/ecc-utils-design/package.json
@@ -23,6 +23,13 @@
     "./events": "./dist/events/index.js",
     "./events/*": "./dist/events/*"
   },
+  "typesVersions": {
+    "*": {
+      "utils": [
+        "./dist/utils/index.d.ts"
+      ]
+    }
+  },
   "repository": {
     "type": "git",
     "url": "https://github.com/elixir-cloud-aai/cloud-components.git"
diff --git a/scripts/utils.test.js b/scripts/utils.test.js
index 813446e3..8c017358 100644
--- a/scripts/utils.test.js
+++ b/scripts/utils.test.js
@@ -95,11 +95,13 @@ test("design package builds and exports ./utils", () => {
   assert.ok(
     relativeEntries(path.join(packageDir, "src")).includes("utils/index.ts")
   );
-  const { exports } = JSON.parse(
+  const { exports, typesVersions } = JSON.parse(
     fs.readFileSync(path.join(packageDir, "package.json"), "utf-8")
   );
   assert.deepStrictEqual(exports["./utils"], {
     types: "./dist/utils/index.d.ts",
     import: "./dist/utils/index.js",
   });
+  // For TypeScript's `node` module resolution, which ignores `exports`
+  assert.deepStrictEqual(typesVersions["*"].utils, ["./dist/utils/index.d.ts"]);
 });

From 29d109738d20295217a14bc97f04522039fe7a9b Mon Sep 17 00:00:00 2001
From: Alex Kanitz <alexanderkanitz@gmail.com>
Date: Sat, 14 Nov 2026 20:34:19 +0100
Subject: [PATCH 11/11] docs: split the local script test instructions

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 apps/documentation/pages/docs/contributing.mdx | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/apps/documentation/pages/docs/contributing.mdx b/apps/documentation/pages/docs/contributing.mdx
index ce2dec88..53be10af 100644
--- a/apps/documentation/pages/docs/contributing.mdx
+++ b/apps/documentation/pages/docs/contributing.mdx
@@ -10,10 +10,10 @@ This page covers what is specific to this repository.
 
 Keep the checks green: `CI passed` sums up the PR title, linting, tests
 (Node.js 22 and 24) and the other CI jobs. Run `npm run lint`,
-`npm run build` and `npm test` (and
-`node --test scripts/release.test.js` after changes to
-`scripts/release.js`, `node --test scripts/utils.test.js` after changes to
-`scripts/utils.js` or `scripts/build.js`) locally before you push. CI runs the tests with
+`npm run build` and `npm test` locally before you push. After changes to
+`scripts/release.js`, also run `node --test scripts/release.test.js`; after
+changes to `scripts/utils.js` or `scripts/build.js`, also run
+`node --test scripts/utils.test.js`. CI runs the tests with
 coverage (`npm run test -- -- --coverage`, which passes `--coverage`
 through npm and turbo to the test runner; Chromium only; each package's
 report is in its `coverage/` folder) and reports it to