@funstack/ui 0.1.0-alpha.2 → 0.1.0-alpha.4

package/dist/field/field-control.mjs

@@ -0,0 +1,68 @@
+"use client";
+import { useRender } from "../internal/use-render.mjs";
+import { useFieldContext } from "../internal/field-context.mjs";
+import { useFieldControl, useMergedRef } from "../internal/use-field-control.mjs";
+import { fieldDataAttributes } from "./field-root.mjs";
+import { useCallback, useRef } from "react";
+//#region src/field/field-control.tsx
+const isDev = process.env.NODE_ENV !== "production";
+const CONTROL_TAGS = /* @__PURE__ */ new Set([
+	"INPUT",
+	"TEXTAREA",
+	"SELECT"
+]);
+/**
+* The field's native control: an `<input>` (or a `<textarea>` / `<select>` through `render`)
+* wired to the Field: `id` for the Label, `aria-describedby` (the consumer's tokens, the
+* description, the error while shown), an explicit `aria-invalid`, and `name` / `disabled` /
+* `required` from the Field unless given. Everything else passes through, including `onChange`
+* / `value` for a controlled input; the Field's listeners are native and run independently.
+*
+* Owned keys (conventions 1.2): `id`, `name`, `disabled`, `required`, `aria-invalid`,
+* `aria-describedby` (token-merged), `data-invalid`, `data-disabled`, `data-required`,
+* `data-pending`.
+*/
+function FieldControl({ name, disabled, required, className, style, render, ...rest }) {
+	const ctx = useFieldContext("Field.Control");
+	const { id: consumerId, ...props } = rest;
+	const field = useFieldControl({
+		labelable: true,
+		name,
+		disabled,
+		required,
+		id: consumerId,
+		component: "Field.Control"
+	});
+	const warned = useRef(false);
+	const checkElement = useCallback((el) => {
+		if (isDev && !warned.current && !CONTROL_TAGS.has(el.tagName)) {
+			warned.current = true;
+			console.error(`Field.Control: expected to render an <input>, <textarea> or <select> but got <${el.tagName.toLowerCase()}>. Validation, labelling and form participation need a native form control.`);
+		}
+		return () => {};
+	}, []);
+	const ref = useMergedRef(checkElement, field.ref);
+	return useRender({
+		defaultElement: "input",
+		render,
+		state: ctx.state,
+		className,
+		style,
+		children: void 0,
+		props,
+		libraryProps: {
+			id: field.id,
+			name: field.name,
+			disabled: field.disabled,
+			required: field.required,
+			...field.attributes,
+			...fieldDataAttributes(ctx.state)
+		},
+		ref
+	});
+}
+FieldControl.displayName = "FieldControl";
+//#endregion
+export { FieldControl };
+
+//# sourceMappingURL=field-control.mjs.map

package/dist/field/field-control.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"field-control.mjs","names":[],"sources":["../../src/field/field-control.tsx"],"sourcesContent":["\"use client\";\nimport { useCallback, useRef } from \"react\";\nimport type { ComponentPropsWithRef, CSSProperties } from \"react\";\nimport { useFieldContext } from \"../internal/field-context.js\";\nimport type { FieldState } from \"../internal/field-context.js\";\nimport type { RenderProp, StateValue } from \"../internal/types.js\";\nimport { useFieldControl, useMergedRef } from \"../internal/use-field-control.js\";\nimport { useRender } from \"../internal/use-render.js\";\nimport { fieldDataAttributes } from \"./field-root.js\";\n\nconst isDev = process.env.NODE_ENV !== \"production\";\n\nexport interface FieldControlProps extends Omit<\n  ComponentPropsWithRef<\"input\">,\n  \"id\" | \"aria-invalid\" | \"className\" | \"style\" | \"children\"\n> {\n  /** Native `name`; defaults to the Field's `name`. */\n  name?: string;\n  /** Native `disabled`; the Field's `disabled` also disables the control. Owned. */\n  disabled?: boolean;\n  /** Native `required`; the Field's `required` also requires the control. Owned. */\n  required?: boolean;\n  className?: StateValue<string | undefined, FieldState>;\n  style?: StateValue<CSSProperties | undefined, FieldState>;\n  /** Must render an `<input>`, `<textarea>` or `<select>`: `render={<textarea rows={3} />}`. */\n  render?: RenderProp<ComponentPropsWithRef<\"input\">, FieldState>;\n}\n\nconst CONTROL_TAGS = new Set([\"INPUT\", \"TEXTAREA\", \"SELECT\"]);\n\n/**\n * The field's native control: an `<input>` (or a `<textarea>` / `<select>` through `render`)\n * wired to the Field: `id` for the Label, `aria-describedby` (the consumer's tokens, the\n * description, the error while shown), an explicit `aria-invalid`, and `name` / `disabled` /\n * `required` from the Field unless given. Everything else passes through, including `onChange`\n * / `value` for a controlled input; the Field's listeners are native and run independently.\n *\n * Owned keys (conventions 1.2): `id`, `name`, `disabled`, `required`, `aria-invalid`,\n * `aria-describedby` (token-merged), `data-invalid`, `data-disabled`, `data-required`,\n * `data-pending`.\n */\nexport function FieldControl({\n  name,\n  disabled,\n  required,\n  className,\n  style,\n  render,\n  ...rest\n}: FieldControlProps) {\n  const ctx = useFieldContext(\"Field.Control\");\n  // `id` is not in the props type (the Field owns it); a JS caller's is ignored with a warning.\n  const { id: consumerId, ...props } = rest as typeof rest & { id?: string };\n  const field = useFieldControl({\n    labelable: true,\n    name,\n    disabled,\n    required,\n    id: consumerId,\n    component: \"Field.Control\",\n  });\n  const warned = useRef(false);\n  const checkElement = useCallback((el: HTMLElement) => {\n    if (isDev && !warned.current && !CONTROL_TAGS.has(el.tagName)) {\n      warned.current = true;\n      console.error(\n        \"Field.Control: expected to render an <input>, <textarea> or <select> but got \" +\n          `<${el.tagName.toLowerCase()}>. Validation, labelling and form participation need a ` +\n          \"native form control.\",\n      );\n    }\n    // A cleanup, so the merged ref never calls this with `null`.\n    return () => {};\n  }, []);\n  const ref = useMergedRef<HTMLElement>(checkElement, field.ref);\n\n  return useRender<ComponentPropsWithRef<\"input\">, FieldState>({\n    defaultElement: \"input\",\n    render,\n    state: ctx.state,\n    className,\n    style,\n    children: undefined,\n    props,\n    libraryProps: {\n      id: field.id,\n      name: field.name,\n      disabled: field.disabled,\n      required: field.required,\n      ...field.attributes,\n      ...fieldDataAttributes(ctx.state),\n    },\n    ref,\n  });\n}\n\nFieldControl.displayName = \"FieldControl\";\n"],"mappings":";;;;;;;AAUA,MAAM,QAAQ,QAAQ,IAAI,aAAa;AAkBvC,MAAM,+BAAe,IAAI,IAAI;CAAC;CAAS;CAAY;AAAQ,CAAC;;;;;;;;;;;;AAa5D,SAAgB,aAAa,EAC3B,MACA,UACA,UACA,WACA,OACA,QACA,GAAG,QACiB;CACpB,MAAM,MAAM,gBAAgB,eAAe;CAE3C,MAAM,EAAE,IAAI,YAAY,GAAG,UAAU;CACrC,MAAM,QAAQ,gBAAgB;EAC5B,WAAW;EACX;EACA;EACA;EACA,IAAI;EACJ,WAAW;CACb,CAAC;CACD,MAAM,SAAS,OAAO,KAAK;CAC3B,MAAM,eAAe,aAAa,OAAoB;EACpD,IAAI,SAAS,CAAC,OAAO,WAAW,CAAC,aAAa,IAAI,GAAG,OAAO,GAAG;GAC7D,OAAO,UAAU;GACjB,QAAQ,MACN,iFACM,GAAG,QAAQ,YAAY,EAAE,4EAEjC;EACF;EAEA,aAAa,CAAC;CAChB,GAAG,CAAC,CAAC;CACL,MAAM,MAAM,aAA0B,cAAc,MAAM,GAAG;CAE7D,OAAO,UAAsD;EAC3D,gBAAgB;EAChB;EACA,OAAO,IAAI;EACX;EACA;EACA,UAAU,KAAA;EACV;EACA,cAAc;GACZ,IAAI,MAAM;GACV,MAAM,MAAM;GACZ,UAAU,MAAM;GAChB,UAAU,MAAM;GAChB,GAAG,MAAM;GACT,GAAG,oBAAoB,IAAI,KAAK;EAClC;EACA;CACF,CAAC;AACH;AAEA,aAAa,cAAc"}

package/dist/field/field-description.d.mts

@@ -0,0 +1,24 @@
+import { RenderProp, StateValue } from "../internal/types.mjs";
+import { FieldState } from "../internal/field-context.mjs";
+import { CSSProperties, ComponentPropsWithRef, ReactNode } from "react";
+//#region src/field/field-description.d.ts
+export interface FieldDescriptionProps extends Omit<ComponentPropsWithRef<"p">, "id" | "className" | "style" | "children"> {
+  className?: StateValue<string | undefined, FieldState>;
+  style?: StateValue<CSSProperties | undefined, FieldState>;
+  children?: StateValue<ReactNode, FieldState>;
+  render?: RenderProp<ComponentPropsWithRef<"p">, FieldState>;
+}
+/**
+ * Help text for the field: a `<p>` whose id the control always lists in `aria-describedby`
+ * (a dangling reference when no Description is rendered is skipped by assistive technology, so
+ * nothing registers and the server HTML is exact).
+ *
+ * Owned keys (conventions 1.2): `id`, `data-invalid`, `data-disabled`, `data-required`,
+ * `data-pending`.
+ */
+export declare function FieldDescription({ className, style, children, render, ...rest }: FieldDescriptionProps): ReactNode;
+export declare namespace FieldDescription {
+  var displayName: string;
+}
+//#endregion
+//# sourceMappingURL=field-description.d.mts.map

package/dist/field/field-description.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"field-description.d.mts","names":[],"sources":["../../src/field/field-description.tsx"],"mappings":";;;;iBAQiB,8BAA8B,KAC7C;EAGA,YAAY,+BAA+B;EAC3C,QAAQ,WAAW,2BAA2B;EAC9C,WAAW,WAAW,WAAW;EACjC,SAAS,WAAW,4BAA4B;;;;;;;;;;wBAWlC,mBACd,WACA,OACA,UACA,WACG,QACF,wBAAqB;yBANR"}

package/dist/field/field-description.mjs

@@ -0,0 +1,34 @@
+"use client";
+import { useRender } from "../internal/use-render.mjs";
+import { useFieldContext } from "../internal/field-context.mjs";
+import { fieldDataAttributes } from "./field-root.mjs";
+//#region src/field/field-description.tsx
+/**
+* Help text for the field: a `<p>` whose id the control always lists in `aria-describedby`
+* (a dangling reference when no Description is rendered is skipped by assistive technology, so
+* nothing registers and the server HTML is exact).
+*
+* Owned keys (conventions 1.2): `id`, `data-invalid`, `data-disabled`, `data-required`,
+* `data-pending`.
+*/
+function FieldDescription({ className, style, children, render, ...rest }) {
+	const ctx = useFieldContext("Field.Description");
+	return useRender({
+		defaultElement: "p",
+		render,
+		state: ctx.state,
+		className,
+		style,
+		children,
+		props: rest,
+		libraryProps: {
+			id: ctx.ids.description,
+			...fieldDataAttributes(ctx.state)
+		}
+	});
+}
+FieldDescription.displayName = "FieldDescription";
+//#endregion
+export { FieldDescription };
+
+//# sourceMappingURL=field-description.mjs.map

package/dist/field/field-description.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"field-description.mjs","names":[],"sources":["../../src/field/field-description.tsx"],"sourcesContent":["\"use client\";\nimport type { ComponentPropsWithRef, CSSProperties, ReactNode } from \"react\";\nimport { useFieldContext } from \"../internal/field-context.js\";\nimport type { FieldState } from \"../internal/field-context.js\";\nimport type { RenderProp, StateValue } from \"../internal/types.js\";\nimport { useRender } from \"../internal/use-render.js\";\nimport { fieldDataAttributes } from \"./field-root.js\";\n\nexport interface FieldDescriptionProps extends Omit<\n  ComponentPropsWithRef<\"p\">,\n  \"id\" | \"className\" | \"style\" | \"children\"\n> {\n  className?: StateValue<string | undefined, FieldState>;\n  style?: StateValue<CSSProperties | undefined, FieldState>;\n  children?: StateValue<ReactNode, FieldState>;\n  render?: RenderProp<ComponentPropsWithRef<\"p\">, FieldState>;\n}\n\n/**\n * Help text for the field: a `<p>` whose id the control always lists in `aria-describedby`\n * (a dangling reference when no Description is rendered is skipped by assistive technology, so\n * nothing registers and the server HTML is exact).\n *\n * Owned keys (conventions 1.2): `id`, `data-invalid`, `data-disabled`, `data-required`,\n * `data-pending`.\n */\nexport function FieldDescription({\n  className,\n  style,\n  children,\n  render,\n  ...rest\n}: FieldDescriptionProps) {\n  const ctx = useFieldContext(\"Field.Description\");\n  return useRender<ComponentPropsWithRef<\"p\">, FieldState>({\n    defaultElement: \"p\",\n    render,\n    state: ctx.state,\n    className,\n    style,\n    children,\n    props: rest,\n    libraryProps: { id: ctx.ids.description, ...fieldDataAttributes(ctx.state) },\n  });\n}\n\nFieldDescription.displayName = \"FieldDescription\";\n"],"mappings":";;;;;;;;;;;;;AA0BA,SAAgB,iBAAiB,EAC/B,WACA,OACA,UACA,QACA,GAAG,QACqB;CACxB,MAAM,MAAM,gBAAgB,mBAAmB;CAC/C,OAAO,UAAkD;EACvD,gBAAgB;EAChB;EACA,OAAO,IAAI;EACX;EACA;EACA;EACA,OAAO;EACP,cAAc;GAAE,IAAI,IAAI,IAAI;GAAa,GAAG,oBAAoB,IAAI,KAAK;EAAE;CAC7E,CAAC;AACH;AAEA,iBAAiB,cAAc"}

package/dist/field/field-error.d.mts

@@ -0,0 +1,30 @@
+import { RenderProp, StateValue } from "../internal/types.mjs";
+import { FieldState } from "../internal/field-context.mjs";
+import { CSSProperties, ComponentPropsWithRef, ReactNode } from "react";
+//#region src/field/field-error.d.ts
+export interface FieldErrorProps extends Omit<ComponentPropsWithRef<"div">, "id" | "className" | "style" | "children"> {
+  className?: StateValue<string | undefined, FieldState>;
+  style?: StateValue<CSSProperties | undefined, FieldState>;
+  /**
+   * Rendered only while `state.invalid`. Default: `state.messages` joined by a space. A function
+   * gets the state: `({ validity, messages }) => validity.valueMissing ? "Enter your email" : messages.join(" ")`.
+   * Must not suspend (urgent render, design 2.4).
+   */
+  children?: StateValue<ReactNode, FieldState>;
+  render?: RenderProp<ComponentPropsWithRef<"div">, FieldState>;
+}
+/**
+ * The field's error message: a `div` rendered only while an error is shown, whose id the control
+ * then lists in `aria-describedby`. No role and no live region: the library focuses the first
+ * invalid control after a submission attempt, and focus reads the description (design 4.2).
+ * Its presence lets the Field cancel the platform's validation bubble.
+ *
+ * Owned keys (conventions 1.2): `id`, `data-invalid`, `data-disabled`, `data-required`,
+ * `data-pending`.
+ */
+export declare function FieldError({ className, style, children, render, ...rest }: FieldErrorProps): ReactNode;
+export declare namespace FieldError {
+  var displayName: string;
+}
+//#endregion
+//# sourceMappingURL=field-error.d.mts.map

package/dist/field/field-error.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"field-error.d.mts","names":[],"sources":["../../src/field/field-error.tsx"],"mappings":";;;;iBASiB,wBAAwB,KACvC;EAGA,YAAY,+BAA+B;EAC3C,QAAQ,WAAW,2BAA2B;;;;;;EAM9C,WAAW,WAAW,WAAW;EACjC,SAAS,WAAW,8BAA8B;;;;;;;;;;;wBAgBpC,aACd,WACA,OACA,UACA,WACG,QACF,kBAAe;yBANF"}

package/dist/field/field-error.mjs

@@ -0,0 +1,42 @@
+"use client";
+import { useRender } from "../internal/use-render.mjs";
+import { useFieldContext } from "../internal/field-context.mjs";
+import { fieldDataAttributes } from "./field-root.mjs";
+import { useLayoutEffect } from "react";
+//#region src/field/field-error.tsx
+function defaultChildren(state) {
+	return state.messages.join(" ");
+}
+/**
+* The field's error message: a `div` rendered only while an error is shown, whose id the control
+* then lists in `aria-describedby`. No role and no live region: the library focuses the first
+* invalid control after a submission attempt, and focus reads the description (design 4.2).
+* Its presence lets the Field cancel the platform's validation bubble.
+*
+* Owned keys (conventions 1.2): `id`, `data-invalid`, `data-disabled`, `data-required`,
+* `data-pending`.
+*/
+function FieldError({ className, style, children = defaultChildren, render, ...rest }) {
+	const ctx = useFieldContext("Field.Error");
+	const { registerError } = ctx;
+	useLayoutEffect(registerError, [registerError]);
+	const element = useRender({
+		defaultElement: "div",
+		render,
+		state: ctx.state,
+		className,
+		style,
+		children,
+		props: rest,
+		libraryProps: {
+			id: ctx.ids.error,
+			...fieldDataAttributes(ctx.state)
+		}
+	});
+	return ctx.state.invalid ? element : null;
+}
+FieldError.displayName = "FieldError";
+//#endregion
+export { FieldError };
+
+//# sourceMappingURL=field-error.mjs.map

package/dist/field/field-error.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"field-error.mjs","names":[],"sources":["../../src/field/field-error.tsx"],"sourcesContent":["\"use client\";\nimport { useLayoutEffect } from \"react\";\nimport type { ComponentPropsWithRef, CSSProperties, ReactNode } from \"react\";\nimport { useFieldContext } from \"../internal/field-context.js\";\nimport type { FieldState } from \"../internal/field-context.js\";\nimport type { RenderProp, StateValue } from \"../internal/types.js\";\nimport { useRender } from \"../internal/use-render.js\";\nimport { fieldDataAttributes } from \"./field-root.js\";\n\nexport interface FieldErrorProps extends Omit<\n  ComponentPropsWithRef<\"div\">,\n  \"id\" | \"className\" | \"style\" | \"children\"\n> {\n  className?: StateValue<string | undefined, FieldState>;\n  style?: StateValue<CSSProperties | undefined, FieldState>;\n  /**\n   * Rendered only while `state.invalid`. Default: `state.messages` joined by a space. A function\n   * gets the state: `({ validity, messages }) => validity.valueMissing ? \"Enter your email\" : messages.join(\" \")`.\n   * Must not suspend (urgent render, design 2.4).\n   */\n  children?: StateValue<ReactNode, FieldState>;\n  render?: RenderProp<ComponentPropsWithRef<\"div\">, FieldState>;\n}\n\nfunction defaultChildren(state: FieldState): ReactNode {\n  return state.messages.join(\" \");\n}\n\n/**\n * The field's error message: a `div` rendered only while an error is shown, whose id the control\n * then lists in `aria-describedby`. No role and no live region: the library focuses the first\n * invalid control after a submission attempt, and focus reads the description (design 4.2).\n * Its presence lets the Field cancel the platform's validation bubble.\n *\n * Owned keys (conventions 1.2): `id`, `data-invalid`, `data-disabled`, `data-required`,\n * `data-pending`.\n */\nexport function FieldError({\n  className,\n  style,\n  children = defaultChildren,\n  render,\n  ...rest\n}: FieldErrorProps) {\n  const ctx = useFieldContext(\"Field.Error\");\n  const { registerError } = ctx;\n  useLayoutEffect(registerError, [registerError]);\n  const element = useRender<ComponentPropsWithRef<\"div\">, FieldState>({\n    defaultElement: \"div\",\n    render,\n    state: ctx.state,\n    className,\n    style,\n    children,\n    props: rest,\n    libraryProps: { id: ctx.ids.error, ...fieldDataAttributes(ctx.state) },\n  });\n  return ctx.state.invalid ? element : null;\n}\n\nFieldError.displayName = \"FieldError\";\n"],"mappings":";;;;;;AAwBA,SAAS,gBAAgB,OAA8B;CACrD,OAAO,MAAM,SAAS,KAAK,GAAG;AAChC;;;;;;;;;;AAWA,SAAgB,WAAW,EACzB,WACA,OACA,WAAW,iBACX,QACA,GAAG,QACe;CAClB,MAAM,MAAM,gBAAgB,aAAa;CACzC,MAAM,EAAE,kBAAkB;CAC1B,gBAAgB,eAAe,CAAC,aAAa,CAAC;CAC9C,MAAM,UAAU,UAAoD;EAClE,gBAAgB;EAChB;EACA,OAAO,IAAI;EACX;EACA;EACA;EACA,OAAO;EACP,cAAc;GAAE,IAAI,IAAI,IAAI;GAAO,GAAG,oBAAoB,IAAI,KAAK;EAAE;CACvE,CAAC;CACD,OAAO,IAAI,MAAM,UAAU,UAAU;AACvC;AAEA,WAAW,cAAc"}

package/dist/field/field-label.d.mts

@@ -0,0 +1,25 @@
+import { RenderProp, StateValue } from "../internal/types.mjs";
+import { FieldState } from "../internal/field-context.mjs";
+import { CSSProperties, ComponentPropsWithRef, ReactNode } from "react";
+//#region src/field/field-label.d.ts
+export interface FieldLabelProps extends Omit<ComponentPropsWithRef<"label">, "htmlFor" | "id" | "className" | "style" | "children"> {
+  className?: StateValue<string | undefined, FieldState>;
+  style?: StateValue<CSSProperties | undefined, FieldState>;
+  children?: StateValue<ReactNode, FieldState>;
+  /** Must render a `<label>`. */
+  render?: RenderProp<ComponentPropsWithRef<"label">, FieldState>;
+}
+/**
+ * The field's visible name: `<label for>` pointing at the control. For a group control (a
+ * RadioGroup or CheckboxGroup `<fieldset>`) it renders no `for` once the group registered, and
+ * the group names itself with `aria-labelledby` → this id (design 4.2).
+ *
+ * Owned keys (conventions 1.2): `id`, `htmlFor`, `data-invalid`, `data-disabled`,
+ * `data-required`, `data-pending`.
+ */
+export declare function FieldLabel({ className, style, children, render, ...rest }: FieldLabelProps): ReactNode;
+export declare namespace FieldLabel {
+  var displayName: string;
+}
+//#endregion
+//# sourceMappingURL=field-label.d.mts.map

package/dist/field/field-label.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"field-label.d.mts","names":[],"sources":["../../src/field/field-label.tsx"],"mappings":";;;;iBAWiB,wBAAwB,KACvC;EAGA,YAAY,+BAA+B;EAC3C,QAAQ,WAAW,2BAA2B;EAC9C,WAAW,WAAW,WAAW;;EAEjC,SAAS,WAAW,gCAAgC;;;;;;;;;;wBAWtC,aAAa,WAAW,OAAO,UAAU,WAAW,QAAQ,kBAAe;yBAA3E"}

package/dist/field/field-label.mjs

@@ -0,0 +1,46 @@
+"use client";
+import { useRender } from "../internal/use-render.mjs";
+import { useFieldContext } from "../internal/field-context.mjs";
+import { fieldDataAttributes } from "./field-root.mjs";
+import { useCallback, useRef } from "react";
+//#region src/field/field-label.tsx
+const isDev = process.env.NODE_ENV !== "production";
+/**
+* The field's visible name: `<label for>` pointing at the control. For a group control (a
+* RadioGroup or CheckboxGroup `<fieldset>`) it renders no `for` once the group registered, and
+* the group names itself with `aria-labelledby` → this id (design 4.2).
+*
+* Owned keys (conventions 1.2): `id`, `htmlFor`, `data-invalid`, `data-disabled`,
+* `data-required`, `data-pending`.
+*/
+function FieldLabel({ className, style, children, render, ...rest }) {
+	const ctx = useFieldContext("Field.Label");
+	const warned = useRef(false);
+	const ref = useCallback((el) => {
+		if (isDev && !warned.current && el.tagName !== "LABEL") {
+			warned.current = true;
+			console.error(`Field.Label: expected to render a <label> element but got <${el.tagName.toLowerCase()}>. Label activation and the control's accessible name need a real <label>.`);
+		}
+		return () => {};
+	}, []);
+	return useRender({
+		defaultElement: "label",
+		render,
+		state: ctx.state,
+		className,
+		style,
+		children,
+		props: rest,
+		libraryProps: {
+			id: ctx.ids.label,
+			htmlFor: ctx.labelable ? ctx.ids.control : void 0,
+			...fieldDataAttributes(ctx.state)
+		},
+		ref
+	});
+}
+FieldLabel.displayName = "FieldLabel";
+//#endregion
+export { FieldLabel };
+
+//# sourceMappingURL=field-label.mjs.map

package/dist/field/field-label.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"field-label.mjs","names":[],"sources":["../../src/field/field-label.tsx"],"sourcesContent":["\"use client\";\nimport { useCallback, useRef } from \"react\";\nimport type { ComponentPropsWithRef, CSSProperties, ReactNode } from \"react\";\nimport { useFieldContext } from \"../internal/field-context.js\";\nimport type { FieldState } from \"../internal/field-context.js\";\nimport type { RenderProp, StateValue } from \"../internal/types.js\";\nimport { useRender } from \"../internal/use-render.js\";\nimport { fieldDataAttributes } from \"./field-root.js\";\n\nconst isDev = process.env.NODE_ENV !== \"production\";\n\nexport interface FieldLabelProps extends Omit<\n  ComponentPropsWithRef<\"label\">,\n  \"htmlFor\" | \"id\" | \"className\" | \"style\" | \"children\"\n> {\n  className?: StateValue<string | undefined, FieldState>;\n  style?: StateValue<CSSProperties | undefined, FieldState>;\n  children?: StateValue<ReactNode, FieldState>;\n  /** Must render a `<label>`. */\n  render?: RenderProp<ComponentPropsWithRef<\"label\">, FieldState>;\n}\n\n/**\n * The field's visible name: `<label for>` pointing at the control. For a group control (a\n * RadioGroup or CheckboxGroup `<fieldset>`) it renders no `for` once the group registered, and\n * the group names itself with `aria-labelledby` → this id (design 4.2).\n *\n * Owned keys (conventions 1.2): `id`, `htmlFor`, `data-invalid`, `data-disabled`,\n * `data-required`, `data-pending`.\n */\nexport function FieldLabel({ className, style, children, render, ...rest }: FieldLabelProps) {\n  const ctx = useFieldContext(\"Field.Label\");\n  const warned = useRef(false);\n  const ref = useCallback((el: HTMLElement) => {\n    if (isDev && !warned.current && el.tagName !== \"LABEL\") {\n      warned.current = true;\n      console.error(\n        `Field.Label: expected to render a <label> element but got <${el.tagName.toLowerCase()}>. ` +\n          \"Label activation and the control's accessible name need a real <label>.\",\n      );\n    }\n    // A cleanup, so the merged ref never calls this with `null`.\n    return () => {};\n  }, []);\n  return useRender<ComponentPropsWithRef<\"label\">, FieldState>({\n    defaultElement: \"label\",\n    render,\n    state: ctx.state,\n    className,\n    style,\n    children,\n    props: rest,\n    libraryProps: {\n      id: ctx.ids.label,\n      htmlFor: ctx.labelable ? ctx.ids.control : undefined,\n      ...fieldDataAttributes(ctx.state),\n    },\n    ref,\n  });\n}\n\nFieldLabel.displayName = \"FieldLabel\";\n"],"mappings":";;;;;;AASA,MAAM,QAAQ,QAAQ,IAAI,aAAa;;;;;;;;;AAqBvC,SAAgB,WAAW,EAAE,WAAW,OAAO,UAAU,QAAQ,GAAG,QAAyB;CAC3F,MAAM,MAAM,gBAAgB,aAAa;CACzC,MAAM,SAAS,OAAO,KAAK;CAC3B,MAAM,MAAM,aAAa,OAAoB;EAC3C,IAAI,SAAS,CAAC,OAAO,WAAW,GAAG,YAAY,SAAS;GACtD,OAAO,UAAU;GACjB,QAAQ,MACN,8DAA8D,GAAG,QAAQ,YAAY,EAAE,2EAEzF;EACF;EAEA,aAAa,CAAC;CAChB,GAAG,CAAC,CAAC;CACL,OAAO,UAAsD;EAC3D,gBAAgB;EAChB;EACA,OAAO,IAAI;EACX;EACA;EACA;EACA,OAAO;EACP,cAAc;GACZ,IAAI,IAAI,IAAI;GACZ,SAAS,IAAI,YAAY,IAAI,IAAI,UAAU,KAAA;GAC3C,GAAG,oBAAoB,IAAI,KAAK;EAClC;EACA;CACF,CAAC;AACH;AAEA,WAAW,cAAc"}

package/dist/field/field-root.d.mts

@@ -0,0 +1,53 @@
+import { RenderProp, StateValue } from "../internal/types.mjs";
+import { FieldErrorValue, FieldValidity } from "../internal/validity.mjs";
+import { FieldState } from "../internal/field-context.mjs";
+import { CSSProperties, ComponentPropsWithRef, ReactNode } from "react";
+//#region src/field/field-root.d.ts
+/**
+ * A custom constraint: receives the field's submitted value (`formData.get(name)` as a string,
+ * `""` when absent) and the whole form's `FormData`. Return a message (or several) for an error,
+ * `null` / `undefined` / `""` for none.
+ */
+export type FieldValidate = (value: string, formData: FormData) => FieldErrorValue;
+export interface FieldRootProps extends Omit<ComponentPropsWithRef<"div">, "className" | "style" | "children"> {
+  /** Form field name: the control's default `name`, the key in `Form.Root errors`, and the entry `validate` reads. */
+  name?: string;
+  /** Disables the control (native `disabled`) and marks every part `data-disabled`. */
+  disabled?: boolean;
+  /** Makes the control `required` (native) and marks every part `data-required`. */
+  required?: boolean;
+  /**
+   * A custom constraint, written into the control with `setCustomValidity`. Sync. Receives the
+   * field's submitted value (`formData.get(name)` as a string, `""` when absent) and the whole
+   * form's `FormData`, so a cross-field rule can read the other field. Runs at mount, on every
+   * `input` / `change` in the form (and a FUNSTACK control's value change), on blur, after a
+   * reset, on a submission attempt, and in every commit in which this prop changed identity, so
+   * a rule that reads outside state (a list that loads, a sibling value in React state) updates
+   * on render. An inline function therefore re-runs on every render of the Field; wrap it in
+   * `useCallback` to re-run only when its inputs change. Return a string
+   * or strings for an error, `null` / `undefined` / `""` for none. Shown when the platform's
+   * `:user-invalid` heuristic says so, like a native constraint. Not serialisable: a Field with
+   * `validate` is rendered from a client component.
+   */
+  validate?: FieldValidate;
+  className?: StateValue<string | undefined, FieldState>;
+  style?: StateValue<CSSProperties | undefined, FieldState>;
+  children?: StateValue<ReactNode, FieldState>;
+  render?: RenderProp<ComponentPropsWithRef<"div">, FieldState>;
+}
+/**
+ * The field: a `div` that owns the ids, the urgent validity mirror, the custom-validity slot
+ * (`validate` and the server error), the control registration and the native listeners
+ * (design/components/field-form.md 2, 14). `data-pending` is the enclosing form's submission
+ * (`useFormStatus`), the one part that folds the form channel into its own state, because a
+ * Field has no action of its own.
+ *
+ * Owned keys (conventions 1.2): `data-invalid`, `data-disabled`, `data-required`, `data-pending`.
+ */
+export declare function FieldRoot({ name, disabled, required, validate, className, style, children, render, ...rest }: FieldRootProps): import("react").JSX.Element;
+export declare namespace FieldRoot {
+  var displayName: string;
+}
+//#endregion
+export type { FieldState, FieldValidity };
+//# sourceMappingURL=field-root.d.mts.map

package/dist/field/field-root.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"field-root.d.mts","names":[],"sources":["../../src/field/field-root.tsx"],"mappings":";;;;;;;;;;YAiDY,iBAAiB,eAAe,UAAU,aAAa;iBAElD,uBAAuB,KACtC;;EAIA;;EAEA;;EAEA;;;;;;;;;;;;;;EAcA,WAAW;EACX,YAAY,+BAA+B;EAC3C,QAAQ,WAAW,2BAA2B;EAC9C,WAAW,WAAW,WAAW;EACjC,SAAS,WAAW,8BAA8B;;;;;;;;;;;wBA0CpC,YACd,MACA,UACA,UACA,UACA,WACA,OACA,UACA,WACG,QACF,iCAAc,IAAA;yBAVD"}