dev(core): align form components

Author: karim-semmoud

CONTRIBUTING.md

@@ -85,7 +85,8 @@ Generates apps with `corex.new` and asserts install paths. Requires `mix archive
 | `lib/components/` | Phoenix components (`Corex.*`), moduledoc, `attr` / `slot` |
 | `lib/components/<name>/` | Connect, anatomy, translation modules |
 | `assets/hooks/` | LiveView hooks (TypeScript, Zag.js) |
-| `assets/lib/` | Shared TS helpers (`util`, `respond-to`, `read-props`, …); tests in `assets/lib/*.test.ts` |
+| `assets/lib/` | Shared TS helpers (`util`, `respond-to`, `read-props`, …) |
+| `assets/test/lib/` | Unit tests for `assets/lib/` helpers |
 | `assets/components/` | Zag `Component` subclasses; colocated `*.test.ts` per module (helpers + smoke); all modules in `components-contract.test.ts` and `components-smoke.test.ts` |
 | `assets/hooks/` | LiveView hooks; hook-specific logic in `hooks/<name>.ts` + `hooks/<name>.test.ts`; wiring in `hooks-wiring.test.ts` |
 | `priv/design/corex/` | Corex Design tokens and component CSS (source of truth in the package) |
@@ -120,12 +121,12 @@ We use [Conventional Commits](https://www.conventionalcommits.org/) style when i
 
 | Path | Expectation |
 | ---- | ----------- |
-| `assets/lib/*.ts` | Colocated `assets/lib/<name>.test.ts` for every module except `core.ts` (abstract base) |
+| `assets/lib/*.ts` | `assets/test/lib/<name>.test.ts` for every module except `core.ts` (abstract base) |
 | `assets/components/*.ts` | Tests under `assets/test/component/` (per-module + `components-contract.test.ts` + `components-smoke.test.ts`) |
 | `assets/hooks/*.ts` | Tests under `assets/test/hooks/` (per-hook lifecycle + parser tests + `hooks-contract.test.ts`) |
 | `assets/test/helpers/` | Shared DOM fixtures (`dom.ts`, `component-fixture.ts`, `component-smoke.ts`, `mock-live-socket.ts`, `expect-hook.ts`) |
 
-New shared helper → `assets/lib/<name>.test.ts`. New component or hook tests → `assets/test/component/<name>.test.ts` or `assets/test/hooks/<name>.test.ts`. Export small pure functions from hooks when logic is not otherwise testable.
+New shared helper → `assets/test/lib/<name>.test.ts`. New component or hook tests → `assets/test/component/<name>.test.ts` or `assets/test/hooks/<name>.test.ts`. Export small pure functions from hooks when logic is not otherwise testable.
 | Design CSS | `mix assets.build`, visual check in e2e styling pages |
 | Moduledoc only | `mix docs` (fix any warnings) |
 | Installer | `cd installer && mix test` |

assets/components/angle-slider.ts

@@ -1,6 +1,7 @@
 import { connect, machine, type Props, type Api } from "@zag-js/angle-slider";
 import { VanillaMachine } from "@zag-js/vanilla";
 import { Component } from "../lib/core";
+import { syncHiddenInputValue } from "../lib/value-form-sync";
 
 export class AngleSlider extends Component<Props, Api> {
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -26,7 +27,15 @@ export class AngleSlider extends Component<Props, Api> {
     const hiddenInputEl = this.el.querySelector<HTMLElement>(
       '[data-scope="angle-slider"][data-part="hidden-input"]'
     );
-    if (hiddenInputEl) this.spreadProps(hiddenInputEl, this.api.getHiddenInputProps());
+    if (hiddenInputEl instanceof HTMLInputElement) {
+      syncHiddenInputValue(
+        hiddenInputEl,
+        this.el,
+        String(this.api.value),
+        (el, props) => this.spreadProps(el, props),
+        this.api.getHiddenInputProps() as Record<string, unknown>
+      );
+    }
 
     const controlEl = this.el.querySelector<HTMLElement>(
       '[data-scope="angle-slider"][data-part="control"]'

assets/components/checkbox.ts

@@ -1,6 +1,7 @@
 import { connect, machine, type Props, type Api } from "@zag-js/checkbox";
 import { VanillaMachine } from "@zag-js/vanilla";
 import { Component } from "../lib/core";
+import { syncCheckableHiddenInput } from "../lib/checkable-form-sync";
 
 export class Checkbox extends Component<Props, Api> {
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -20,8 +21,14 @@ export class Checkbox extends Component<Props, Api> {
     const inputEl = rootEl.querySelector<HTMLElement>(
       ':scope > [data-scope="checkbox"][data-part="hidden-input"]'
     );
-    if (inputEl) {
-      this.spreadProps(inputEl, this.api.getHiddenInputProps());
+    if (inputEl instanceof HTMLInputElement) {
+      syncCheckableHiddenInput(
+        inputEl,
+        this.el,
+        this.api.checked === true,
+        (el, props) => this.spreadProps(el, props),
+        this.api.getHiddenInputProps() as Record<string, unknown>
+      );
     }
 
     const labelEl = rootEl.querySelector<HTMLElement>(

assets/components/color-picker.ts

@@ -1,6 +1,7 @@
 import { connect, machine, parse, type Props, type Api } from "@zag-js/color-picker";
 import { VanillaMachine } from "@zag-js/vanilla";
 import { Component } from "../lib/core";
+import { syncHiddenInputValue } from "../lib/value-form-sync";
 
 export class ColorPicker extends Component<Props, Api> {
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -20,7 +21,15 @@ export class ColorPicker extends Component<Props, Api> {
     if (labelEl) this.spreadProps(labelEl, this.api.getLabelProps());
 
     const hiddenInputEl = this.el.querySelector<HTMLInputElement>('[data-part="hidden-input"]');
-    if (hiddenInputEl) this.spreadProps(hiddenInputEl, this.api.getHiddenInputProps());
+    if (hiddenInputEl) {
+      syncHiddenInputValue(
+        hiddenInputEl,
+        this.el,
+        this.api.valueAsString ?? "",
+        (el, props) => this.spreadProps(el, props),
+        this.api.getHiddenInputProps() as Record<string, unknown>
+      );
+    }
 
     const controlEl = this.el.querySelector<HTMLElement>('[data-part="control"]');
     if (controlEl) this.spreadProps(controlEl, this.api.getControlProps());

assets/components/combobox.ts

@@ -9,6 +9,8 @@ import {
 } from "@zag-js/combobox";
 import { VanillaMachine } from "@zag-js/vanilla";
 import { Component } from "../lib/core";
+import { stripZagSubmitNames } from "../lib/form-field-array-submit";
+import { getString } from "../lib/util";
 import { itemValue, zagListCollectionConfig } from "../lib/list-collection";
 import { templatesContentRoot } from "../lib/util";
 
@@ -299,8 +301,14 @@ export class Combobox extends Component<Props, Api> {
     if (hiddenInput) {
       const valueStr = this.hiddenInputValue();
       if (hiddenInput.value !== valueStr) hiddenInput.value = valueStr;
+      if (getString(this.el, "submitName")) {
+        hiddenInput.removeAttribute("name");
+        hiddenInput.removeAttribute("form");
+      }
     }
 
+    stripZagSubmitNames(this.el, "combobox", ["hidden-input", "input"]);
+
     [
       "label",
       "control",

assets/components/file-upload.ts

@@ -29,6 +29,28 @@ export function fileKeyFor(file: File): string {
   return zagFileId(`${file.name}-${file.size}`);
 }
 
+export function labelFieldNameFor(fieldName: string): string {
+  if (fieldName.includes("[")) {
+    return fieldName.replace(/\[([^\]]+)\]$/, "[$1_label]");
+  }
+
+  return `${fieldName}_label`;
+}
+
+function setInputFiles(inputEl: HTMLInputElement, files: File[]): void {
+  try {
+    if (typeof window.DataTransfer !== "undefined") {
+      const dataTransfer = new window.DataTransfer();
+      for (const file of files) {
+        dataTransfer.items.add(file);
+      }
+      inputEl.files = dataTransfer.files;
+    }
+  } catch {
+    // ignore unsupported environments
+  }
+}
+
 export class FileUpload extends Component<Props, Api> {
   private previewCleanup = new Map<HTMLElement, VoidFunction>();
   private sentinelSnapshot = "";
@@ -159,9 +181,82 @@ export class FileUpload extends Component<Props, Api> {
       }
     }
 
+    this.syncFormSubmitInputs();
     this.touchSentinel();
   }
 
+  syncFormSubmitInputs(): void {
+    const fileInput = this.el.querySelector<HTMLInputElement>(
+      '[data-scope="file-upload"][data-part="hidden-input"]'
+    );
+    const sentinel = this.el.querySelector<HTMLInputElement>('[data-part="hidden-input-sentinel"]');
+    const files = this.api.acceptedFiles;
+    const name = this.el.dataset.name;
+
+    if (fileInput) {
+      setInputFiles(fileInput, files);
+    }
+
+    this.syncAcceptedNamesHidden(name, files);
+
+    if (!sentinel) return;
+
+    if (files.length > 0) {
+      sentinel.disabled = true;
+      sentinel.removeAttribute("name");
+      return;
+    }
+
+    sentinel.disabled = false;
+    if (name) {
+      sentinel.setAttribute("name", name);
+    }
+  }
+
+  private syncAcceptedNamesHidden(fieldName: string | undefined, files: File[]): void {
+    if (!fieldName) return;
+
+    const labelFieldName = labelFieldNameFor(fieldName);
+
+    const region =
+      this.el.querySelector<HTMLElement>('[data-scope="file-upload"][data-part="region"]') ??
+      this.el;
+
+    let labelInput = region.querySelector<HTMLInputElement>(
+      '[data-scope="file-upload"][data-part="accepted-names-hidden"]'
+    );
+
+    if (!labelInput) {
+      labelInput = document.createElement("input");
+      labelInput.type = "hidden";
+      labelInput.setAttribute("data-scope", "file-upload");
+      labelInput.setAttribute("data-part", "accepted-names-hidden");
+      region.appendChild(labelInput);
+    }
+
+    const names = files
+      .map((file) => file.name)
+      .filter(Boolean)
+      .join(", ");
+
+    if (names === "") {
+      labelInput.disabled = true;
+      labelInput.removeAttribute("name");
+      labelInput.value = "";
+      return;
+    }
+
+    labelInput.disabled = false;
+    labelInput.name = labelFieldName;
+    labelInput.value = names;
+    const formId = this.el.dataset.form;
+    if (formId) {
+      labelInput.setAttribute("form", formId);
+    } else {
+      labelInput.removeAttribute("form");
+    }
+  }
+
   private touchSentinel(): void {
     const sentinel = this.el.querySelector<HTMLInputElement>('[data-part="hidden-input-sentinel"]');
     if (!sentinel) return;

assets/components/number-input.ts

@@ -1,6 +1,8 @@
 import { connect, machine, type Props, type Api } from "@zag-js/number-input";
 import { VanillaMachine } from "@zag-js/vanilla";
 import { Component } from "../lib/core";
+import { getString } from "../lib/util";
+import { syncHiddenInputValue } from "../lib/value-form-sync";
 
 export class NumberInput extends Component<Props, Api> {
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -36,7 +38,12 @@ export class NumberInput extends Component<Props, Api> {
     const inputEl = this.el.querySelector<HTMLElement>(
       '[data-scope="number-input"][data-part="input"]'
     );
-    if (inputEl) this.spreadProps(inputEl, this.api.getInputProps());
+    if (inputEl) {
+      const visibleProps = { ...(this.api.getInputProps() as Record<string, unknown>) };
+      delete visibleProps.name;
+      delete visibleProps.form;
+      this.spreadProps(inputEl, visibleProps);
+    }
 
     const decrementEl = this.el.querySelector<HTMLElement>(
       '[data-scope="number-input"][data-part="decrement-trigger"]'
@@ -47,5 +54,19 @@ export class NumberInput extends Component<Props, Api> {
       '[data-scope="number-input"][data-part="increment-trigger"]'
     );
     if (incrementEl) this.spreadProps(incrementEl, this.api.getIncrementTriggerProps());
+
+    const valueInputEl = this.el.querySelector<HTMLElement>(
+      '[data-scope="number-input"][data-part="value-input"]'
+    );
+    if (valueInputEl instanceof HTMLInputElement) {
+      const value = this.api.value || getString(this.el, "defaultValue") || "";
+      syncHiddenInputValue(
+        valueInputEl,
+        this.el,
+        value,
+        (el, props) => this.spreadProps(el, props),
+        {}
+      );
+    }
   }
 }

assets/components/pin-input.ts

@@ -1,6 +1,9 @@
 import { connect, machine, type Props, type Api } from "@zag-js/pin-input";
 import { VanillaMachine } from "@zag-js/vanilla";
 import { Component } from "../lib/core";
+import { stripZagSubmitNames } from "../lib/form-field-array-submit";
+import { getString } from "../lib/util";
+import { syncHiddenInputValue } from "../lib/value-form-sync";
 
 export class PinInput extends Component<Props, Api> {
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -25,7 +28,21 @@ export class PinInput extends Component<Props, Api> {
     const hiddenInputEl = this.el.querySelector<HTMLElement>(
       '[data-scope="pin-input"][data-part="hidden-input"]'
     );
-    if (hiddenInputEl) this.spreadProps(hiddenInputEl, this.api.getHiddenInputProps());
+    if (hiddenInputEl instanceof HTMLInputElement) {
+      syncHiddenInputValue(
+        hiddenInputEl,
+        this.el,
+        this.api.valueAsString ?? "",
+        (el, props) => this.spreadProps(el, props),
+        this.api.getHiddenInputProps() as Record<string, unknown>
+      );
+      if (getString(this.el, "submitName")) {
+        hiddenInputEl.removeAttribute("name");
+        hiddenInputEl.removeAttribute("form");
+      }
+    }
+
+    stripZagSubmitNames(this.el, "pin-input");
 
     const controlEl = this.el.querySelector<HTMLElement>(
       '[data-scope="pin-input"][data-part="control"]'

assets/components/radio-group.ts

@@ -2,6 +2,8 @@ import { connect, machine, type Props, type Api } from "@zag-js/radio-group";
 import type { ItemProps } from "@zag-js/radio-group";
 import { VanillaMachine } from "@zag-js/vanilla";
 import { Component } from "../lib/core";
+import { hiddenInputPropsWithoutChecked } from "../lib/checkable-form-sync";
+import { syncInputFormAssociation } from "../lib/util";
 
 export class RadioGroup extends Component<Props, Api> {
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -59,15 +61,20 @@ export class RadioGroup extends Component<Props, Api> {
         const hiddenInputEl = itemEl.querySelector<HTMLElement>(
           '[data-scope="radio-group"][data-part="item-hidden-input"]'
         );
-        if (hiddenInputEl)
+        if (hiddenInputEl instanceof HTMLInputElement) {
           this.spreadProps(
             hiddenInputEl,
-            this.api.getItemHiddenInputProps({
-              value,
-              disabled,
-              invalid,
-            } as ItemProps)
+            hiddenInputPropsWithoutChecked(
+              this.api.getItemHiddenInputProps({
+                value,
+                disabled,
+                invalid,
+              } as ItemProps) as Record<string, unknown>
+            )
           );
+          hiddenInputEl.checked = this.api.value === value;
+          syncInputFormAssociation(hiddenInputEl, this.el);
+        }
       });
   }
 }

assets/components/signature-pad.ts

@@ -1,6 +1,8 @@
 import { connect, machine, type Props, type Api } from "@zag-js/signature-pad";
 import { VanillaMachine } from "@zag-js/vanilla";
 import { Component } from "../lib/core";
+import { stripZagSubmitNames } from "../lib/form-field-array-submit";
+import { getString } from "../lib/util";
 
 export class SignaturePad extends Component<Props, Api> {
   imageURL: string = "";
@@ -109,8 +111,14 @@ export class SignaturePad extends Component<Props, Api> {
           value: this.api.paths.length > 0 ? this.api.paths.join("\n") : "",
         })
       );
+      if (getString(this.el, "submitName")) {
+        hiddenInput.removeAttribute("name");
+        hiddenInput.removeAttribute("form");
+      }
     }
 
+    stripZagSubmitNames(this.el, "signature-pad");
+
     this.syncPaths();
   }
 }