@igne-agency/react-web-ui 0.2.1 → 0.3.0

package/README.md

@@ -184,6 +184,45 @@ const SignUp = () => {
 };
 ```
 
+Related fields, such as the parts of an address, share one legend and one error in a field group, which lines them up side by side. Register `TSFFieldGroup` as a form component and name the fields whose errors it shows:
+
+```ts
+import { TSFFieldGroup } from "@igne-agency/react-web-ui/fieldset";
+import { TSFTextField } from "@igne-agency/react-web-ui/text-field";
+
+export const { useAppForm, withForm, withFieldGroup } =
+	createAppForm(
+		{ TextField: TSFTextField },
+		{ FieldGroup: TSFFieldGroup },
+	);
+```
+
+```tsx
+<form.FieldGroup
+	legend="Address"
+	optionalLabel="optional"
+	names={["postalCode", "houseNumber"]}>
+	<form.AppField name="postalCode">
+		{field => (
+			<field.TextField
+				label="Postal code"
+				requiredness="required"
+				optionalLabel="optional"
+			/>
+		)}
+	</form.AppField>
+	<form.AppField name="houseNumber">
+		{field => (
+			<field.TextField
+				label="House number"
+				requiredness="required"
+				optionalLabel="optional"
+			/>
+		)}
+	</form.AppField>
+</form.FieldGroup>
+```
+
 Every field takes `requiredness` (`"required"`, `"optional"`, or left out to show neither mark) and `errors`, which accepts strings and anything with a string `message`, such as Standard Schema issues. Validation is the app's own, through Standard Schema; the kit ships no validators.
 
 `Form.Root` reports unsaved changes to the page's leave guards (`useLeaveGuard`, or `useRouterLeaveGuard` from `./unsaved-changes/tanstack-router`) while its `leaveGuard` policy returns true for the form's live state. The default, `whenDirty`, guards while the values differ from their defaults and no submit is in flight. Pass `never` for a form whose edits need not survive leaving, or any `(state) => boolean`:

package/dist/components/checkbox-field/tsf-checkbox-field.js

@@ -14,7 +14,7 @@ import { jsx } from "react/jsx-runtime";
 */
 var TSFCheckboxField = (props) => {
 	const $ = c(7);
-	const { field, props: connected } = useConnectedField();
+	const { field, props: connected } = useConnectedField(props.label);
 	let t0;
 	if ($[0] !== field) {
 		t0 = (checked) => field.handleChange(checked);

package/dist/components/checkbox-group-field/checkbox-group.d.ts

@@ -3,7 +3,7 @@ import { Field as BaseField } from "@base-ui/react/field";
 import type { ReactNode } from "react";
 import { Checkbox } from "../checkbox-field/index.ts";
 import { Field } from "../field/index.ts";
-import { FieldsetLegend, FieldsetRoot, type FieldsetRootProps } from "../field/fieldset.tsx";
+import { FieldsetLegend, FieldsetRoot, type FieldsetRootProps } from "../fieldset/fieldset-root.tsx";
 export type CheckboxGroupRootProps = FieldsetRootProps;
 declare const CheckboxGroupGroup: ({ className, ...props }: BaseCheckboxGroup.Props) => ReactNode;
 declare const CheckboxGroupItem: ({ className, ...props }: BaseField.Item.Props) => ReactNode;

package/dist/components/checkbox-group-field/checkbox-group.js

@@ -1,6 +1,6 @@
 import { Checkbox } from "../checkbox-field/checkbox.js";
 import { Field as Field$1 } from "../field/field.js";
-import { FieldsetLegend, FieldsetRoot } from "../field/fieldset.js";
+import { FieldsetLegend, FieldsetRoot } from "../fieldset/fieldset-root.js";
 import checkbox_group_module_default from "./checkbox-group.module.js";
 import { c } from "react/compiler-runtime";
 import { jsx } from "react/jsx-runtime";

package/dist/components/checkbox-group-field/tsf-checkbox-group-field.js

@@ -15,7 +15,7 @@ import { jsx } from "react/jsx-runtime";
 */
 var TSFCheckboxGroupField = (props) => {
 	const $ = c(7);
-	const { field, props: connected } = useConnectedField();
+	const { field, props: connected } = useConnectedField(props.label);
 	let t0;
 	if ($[0] !== field) {
 		t0 = (value) => field.handleChange(value);

package/dist/components/combobox-field/tsf-combobox-field.js

@@ -6,7 +6,7 @@ import { jsx } from "react/jsx-runtime";
 var SingleField = (t0) => {
 	const $ = c(7);
 	const { props } = t0;
-	const { field, props: connected } = useConnectedField();
+	const { field, props: connected } = useConnectedField(props.label);
 	let t1;
 	if ($[0] !== field) {
 		t1 = (next) => field.handleChange(next);
@@ -32,7 +32,7 @@ var SingleField = (t0) => {
 var MultipleField = (t0) => {
 	const $ = c(7);
 	const { props } = t0;
-	const { field, props: connected } = useConnectedField();
+	const { field, props: connected } = useConnectedField(props.label);
 	let t1;
 	if ($[0] !== field) {
 		t1 = (next) => field.handleChange(next);

package/dist/components/date-field/tsf-date-field.js

@@ -14,7 +14,7 @@ import { jsx } from "react/jsx-runtime";
 */
 var TSFDateField = (props) => {
 	const $ = c(7);
-	const { field, props: connected } = useConnectedField();
+	const { field, props: connected } = useConnectedField(props.label);
 	let t0;
 	if ($[0] !== field) {
 		t0 = (next) => field.handleChange(next);

package/dist/components/date-range-field/tsf-date-range-field.js

@@ -15,7 +15,7 @@ import { jsx } from "react/jsx-runtime";
 */
 var TSFDateRangeField = (props) => {
 	const $ = c(12);
-	const { field, props: t0 } = useConnectedField();
+	const { field, props: t0 } = useConnectedField(props.label);
 	let connected;
 	let name;
 	if ($[0] !== t0) {

package/dist/components/field/field-group-context.d.ts

@@ -0,0 +1,21 @@
+import { type Context } from "react";
+/** What a field group tells the fields it collects the errors of. */
+export type FieldGroupContextValue = Readonly<{
+    /** The ids of the lines a field's errors show as in the group's error, or `undefined` for a field the group does not collect. */
+    lineIds: (name: string) => readonly string[] | undefined;
+    /** Tells the group a field's label, until the returned function takes it back. */
+    registerLabel: (name: string, label: string) => () => void;
+}>;
+/** The field group the fields inside it report to. */
+export declare const FieldGroupContext: Context<FieldGroupContextValue | null>;
+/** Whether a field root sits directly in a field group's row of fields. */
+export declare const FieldRowContext: Context<boolean>;
+/**
+ * The ids of the lines the enclosing field group shows this field's errors as,
+ * or `undefined` when no group collects it. A field is matched by the name of
+ * the TanStack Form field it renders in.
+ *
+ * @example
+ * const lineIds = useFieldGroupLineIds(); // ["«r3»line0"]
+ */
+export declare const useFieldGroupLineIds: () => readonly string[] | undefined;

package/dist/components/field/field-group-context.js

@@ -0,0 +1,38 @@
+import { fieldContext } from "../../lib/forms/context.js";
+import { c } from "react/compiler-runtime";
+import { createContext, useContext } from "react";
+// src/components/field/field-group-context.ts
+/** The field group the fields inside it report to. */
+var FieldGroupContext = createContext(null);
+/** Whether a field root sits directly in a field group's row of fields. */
+var FieldRowContext = createContext(false);
+/**
+* The ids of the lines `group` shows the errors of `field` as, where there are
+* both.
+*
+* @example
+* groupLineIds(group, field); // ["«r3»line0"]
+*/
+var groupLineIds = (group, field) => group === null || field === null ? void 0 : group.lineIds(field.name);
+/**
+* The ids of the lines the enclosing field group shows this field's errors as,
+* or `undefined` when no group collects it. A field is matched by the name of
+* the TanStack Form field it renders in.
+*
+* @example
+* const lineIds = useFieldGroupLineIds(); // ["«r3»line0"]
+*/
+var useFieldGroupLineIds = () => {
+	const $ = c(3);
+	const t0 = useContext(FieldGroupContext);
+	const t1 = useContext(fieldContext);
+	let t2;
+	if ($[0] !== t0 || $[1] !== t1) {
+		t2 = groupLineIds(t0, t1);
+		$[0] = t0;
+		$[1] = t1;
+		$[2] = t2;
+	} else t2 = $[2];
+	return t2;
+};
+export { FieldGroupContext, FieldRowContext, useFieldGroupLineIds };

package/dist/components/field/field.css

@@ -1,29 +1,48 @@
 @layer kit.reset, kit.base, kit.components;
 @layer kit.components {
-  ._field_14ydh_3 {
+  ._field_dzutr_3 {
     display: flex;
     flex-direction: column;
     gap: var(--field-gap, var(--sys-unit-4));
     inline-size: 100%;
   }
-  ._label_14ydh_9 {
+  ._field_dzutr_3[data-field-group-member] > * {
+    grid-row: extra;
+    margin-block-start: var(--field-gap, var(--sys-unit-4));
+  }
+  ._field_dzutr_3[data-field-group-member] > ._label_dzutr_13 {
+    grid-row: label;
+    margin-block: 0 var(--field-gap, var(--sys-unit-4));
+  }
+  ._field_dzutr_3[data-field-group-member] > :first-child:not(._label_dzutr_13),
+  ._field_dzutr_3[data-field-group-member] > ._label_dzutr_13 + * {
+    grid-row: control;
+    margin-block-start: 0;
+  }
+  ._field_dzutr_3[data-field-group-member] > ._description_dzutr_22 {
+    grid-row: description;
+  }
+  ._field_dzutr_3[data-field-group-member] > ._error_dzutr_25 {
+    grid-row: error;
+  }
+  ._label_dzutr_13 {
     color: var(--sys-color-text);
     font: var(--sys-font-label-medium);
     cursor: default;
   }
-  ._optional_14ydh_14 {
+  ._optional_dzutr_33 {
     vertical-align: middle;
     color: var(--sys-color-text-muted);
     font: var(--sys-font-body-small);
     font-size: 0.75rem;
   }
-  ._inlineText_14ydh_20 {
+  ._inlineText_dzutr_39 {
     grid-area: text;
   }
-  ._inlineOptional_14ydh_23 {
+  ._inlineOptional_dzutr_42 {
     grid-area: optional;
   }
-  ._required_14ydh_26 {
+  ._required_dzutr_45 {
     display: inline-block;
     vertical-align: middle;
     translate: 0 -1px;
@@ -32,11 +51,11 @@
     background-color: var(--field-required-fg, var(--sys-color-primary));
     mask: url("data:image/svg+xml,%3csvg%20xmlns='http://www.w3.org/2000/svg'%20viewBox='16%2016%2032%2032'%20fill='currentColor'%3e%3cpath%20d='M45.475%2036.291c.377.162.549.477.523.943-.027.469-.35%201.223-.967%202.264-.617%201.072-1.121%201.725-1.51%201.967-.389.24-.744.24-1.066%200l-8.574-6.215%201.129%2010.508c.078.398-.096.707-.525.92-.428.215-1.262.322-2.495.322-1.236%200-2.066-.107-2.496-.322-.43-.213-.604-.521-.523-.92l1.127-10.508-8.533%206.215c-.322.24-.686.24-1.088%200-.402-.242-.912-.895-1.529-1.967-.617-1.041-.934-1.795-.945-2.264-.016-.467.168-.781.543-.943l9.701-4.29-9.701-4.252c-.375-.188-.559-.516-.543-.984.012-.467.328-1.223.945-2.264.617-1.045%201.127-1.686%201.529-1.926s.766-.24%201.088%200l8.533%206.176-1.127-10.467c-.08-.428.094-.748.523-.963s1.26-.321%202.496-.321c1.232%200%202.066.107%202.494.322.43.215.604.535.525.963l-1.129%2010.467%208.574-6.176c.322-.24.678-.24%201.066%200s.893.896%201.51%201.965c.617%201.018.939%201.758.967%202.225.025.469-.146.797-.523.984l-9.701%204.252%209.702%204.289'/%3e%3c/svg%3e") center/contain no-repeat;
   }
-  ._description_14ydh_35 {
+  ._description_dzutr_22 {
     color: var(--field-description-fg, var(--sys-color-text-muted));
     font: var(--field-description-font, var(--sys-font-body-medium));
   }
-  ._pending_14ydh_39 {
+  ._pending_dzutr_58 {
     display: inline-flex;
     flex: none;
     align-items: center;

package/dist/components/field/field.d.ts

@@ -72,11 +72,12 @@ export type FieldRootProps = BaseField.Root.Props & Readonly<{
 }>;
 /**
  * The field frame: label, control, description and error stacked full width.
+ * In a field group's row its parts share the row's tracks with its neighbours.
  *
  * @example
  * <Field.Root name="email" invalid={invalid}>…</Field.Root>
  */
-declare const FieldRoot: ({ className, ...props }: FieldRootProps) => ReactNode;
+declare const FieldRoot: ({ className, children, ...props }: FieldRootProps) => ReactNode;
 export type FieldLabelProps = Omit<BaseField.Label.Props, "className"> & RequirednessProps & Readonly<{
     className?: string;
 }>;
@@ -113,7 +114,9 @@ export type FieldErrorProps = Omit<BaseField.Error.Props, "match" | "render" | "
  * The one error part every control renders, after the description. Normalises
  * its errors to lines with `normalizeFieldErrors` and renders nothing when
  * there are none. It is the field's only live region, so a control must not
- * announce the same message a second time.
+ * announce the same message a second time. In a field group that collects
+ * the field, the group's error shows the lines instead, and the control is
+ * described by them.
  *
  * @example
  * <Field.Error>{errors}</Field.Error>
@@ -139,7 +142,7 @@ export type FieldIds = Readonly<{
     errorId: string;
     /** A stable id and name for the control. */
     controlId: string;
-    /** The control's `aria-describedby`: the description and the error that are shown. */
+    /** The control's `aria-describedby`: the description and the error that are shown, or the field's lines in a field group that collects it. */
     describedBy: (hasDescription: boolean, invalid: boolean) => string | undefined;
 }>;
 /**

package/dist/components/field/field.js

@@ -1,9 +1,10 @@
 import { normalizeFieldErrors } from "../../lib/forms/errors.js";
 import { ErrorText } from "../error-text/error-text.js";
 import { Spinner } from "../spinner/spinner.js";
+import { FieldRowContext, useFieldGroupLineIds } from "./field-group-context.js";
 import field_module_default from "./field.module.js";
 import { c } from "react/compiler-runtime";
-import { useId } from "react";
+import { useContext, useId } from "react";
 import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
 import { clsx } from "clsx";
 import { Field } from "@base-ui/react/field";
@@ -104,40 +105,59 @@ var InlineLabelText = (t0) => {
 };
 /**
 * The field frame: label, control, description and error stacked full width.
+* In a field group's row its parts share the row's tracks with its neighbours.
 *
 * @example
 * <Field.Root name="email" invalid={invalid}>…</Field.Root>
 */
 var FieldRoot = (t0) => {
-	const $ = c(8);
+	const $ = c(13);
+	let children;
 	let className;
 	let props;
 	if ($[0] !== t0) {
-		({className, ...props} = t0);
+		({className, children, ...props} = t0);
 		$[0] = t0;
-		$[1] = className;
-		$[2] = props;
+		$[1] = children;
+		$[2] = className;
+		$[3] = props;
 	} else {
-		className = $[1];
-		props = $[2];
+		children = $[1];
+		className = $[2];
+		props = $[3];
 	}
+	const inRow = useContext(FieldRowContext);
 	let t1;
-	if ($[3] !== className) {
+	if ($[4] !== className) {
 		t1 = clsx(field_module_default.field, className);
-		$[3] = className;
-		$[4] = t1;
-	} else t1 = $[4];
-	let t2;
-	if ($[5] !== props || $[6] !== t1) {
-		t2 = /* @__PURE__ */ jsx(Field.Root, {
+		$[4] = className;
+		$[5] = t1;
+	} else t1 = $[5];
+	const t2 = inRow ? "" : void 0;
+	let t3;
+	if ($[6] !== children) {
+		t3 = /* @__PURE__ */ jsx(FieldRowContext, {
+			value: false,
+			children
+		});
+		$[6] = children;
+		$[7] = t3;
+	} else t3 = $[7];
+	let t4;
+	if ($[8] !== props || $[9] !== t1 || $[10] !== t2 || $[11] !== t3) {
+		t4 = /* @__PURE__ */ jsx(Field.Root, {
 			className: t1,
-			...props
+			"data-field-group-member": t2,
+			...props,
+			children: t3
 		});
-		$[5] = props;
-		$[6] = t1;
-		$[7] = t2;
-	} else t2 = $[7];
-	return t2;
+		$[8] = props;
+		$[9] = t1;
+		$[10] = t2;
+		$[11] = t3;
+		$[12] = t4;
+	} else t4 = $[12];
+	return t4;
 };
 /**
 * The label above a control, trailing its requiredness. Renders nothing without
@@ -280,17 +300,20 @@ var FieldDescription = (t0) => {
 	} else t1 = $[7];
 	return t1;
 };
+var Unrendered = () => null;
 /**
 * The one error part every control renders, after the description. Normalises
 * its errors to lines with `normalizeFieldErrors` and renders nothing when
 * there are none. It is the field's only live region, so a control must not
-* announce the same message a second time.
+* announce the same message a second time. In a field group that collects
+* the field, the group's error shows the lines instead, and the control is
+* described by them.
 *
 * @example
 * <Field.Error>{errors}</Field.Error>
 */
 var FieldError = (t0) => {
-	const $ = c(8);
+	const $ = c(10);
 	let errors;
 	let props;
 	if ($[0] !== t0) {
@@ -302,15 +325,25 @@ var FieldError = (t0) => {
 		errors = $[1];
 		props = $[2];
 	}
+	const groupLineIds = useFieldGroupLineIds();
+	if (groupLineIds !== void 0) {
+		let t1;
+		if ($[3] !== groupLineIds) {
+			t1 = groupLineIds.map(_temp);
+			$[3] = groupLineIds;
+			$[4] = t1;
+		} else t1 = $[4];
+		return t1;
+	}
 	let t1;
-	if ($[3] !== errors) {
+	if ($[5] !== errors) {
 		t1 = normalizeFieldErrors(errors);
-		$[3] = errors;
-		$[4] = t1;
-	} else t1 = $[4];
+		$[5] = errors;
+		$[6] = t1;
+	} else t1 = $[6];
 	const messages = t1;
 	let t2;
-	if ($[5] !== messages || $[6] !== props) {
+	if ($[7] !== messages || $[8] !== props) {
 		t2 = messages.length === 0 ? null : /* @__PURE__ */ jsx(Field.Error, {
 			match: true,
 			...props,
@@ -318,13 +351,14 @@ var FieldError = (t0) => {
 				el: "span",
 				role: "alert",
 				...renderProps,
+				className: clsx(field_module_default.error, renderProps.className),
 				children: messages
 			})
 		});
-		$[5] = messages;
-		$[6] = props;
-		$[7] = t2;
-	} else t2 = $[7];
+		$[7] = messages;
+		$[8] = props;
+		$[9] = t2;
+	} else t2 = $[9];
 	return t2;
 };
 /**
@@ -369,21 +403,23 @@ var FieldPending = (t0) => {
 * const { labelId, errorId } = useFieldIds();
 */
 var useFieldIds = () => {
-	const $ = c(9);
+	const $ = c(10);
 	const id = useId();
+	const groupLineIds = useFieldGroupLineIds();
 	const descriptionId = `${id}description`;
 	const errorId = `${id}error`;
 	const t0 = `${id}label`;
 	const t1 = `${id}control`;
 	let t2;
-	if ($[0] !== descriptionId || $[1] !== errorId) {
-		t2 = (hasDescription, invalid) => [hasDescription ? descriptionId : "", invalid ? errorId : ""].filter(_temp).join(" ") || void 0;
+	if ($[0] !== descriptionId || $[1] !== errorId || $[2] !== groupLineIds) {
+		t2 = (hasDescription, invalid) => [hasDescription ? descriptionId : "", ...groupLineIds ?? [invalid ? errorId : ""]].filter(_temp2).join(" ") || void 0;
 		$[0] = descriptionId;
 		$[1] = errorId;
-		$[2] = t2;
-	} else t2 = $[2];
+		$[2] = groupLineIds;
+		$[3] = t2;
+	} else t2 = $[3];
 	let t3;
-	if ($[3] !== descriptionId || $[4] !== errorId || $[5] !== t0 || $[6] !== t1 || $[7] !== t2) {
+	if ($[4] !== descriptionId || $[5] !== errorId || $[6] !== t0 || $[7] !== t1 || $[8] !== t2) {
 		t3 = {
 			labelId: t0,
 			descriptionId,
@@ -391,13 +427,13 @@ var useFieldIds = () => {
 			controlId: t1,
 			describedBy: t2
 		};
-		$[3] = descriptionId;
-		$[4] = errorId;
-		$[5] = t0;
-		$[6] = t1;
-		$[7] = t2;
-		$[8] = t3;
-	} else t3 = $[8];
+		$[4] = descriptionId;
+		$[5] = errorId;
+		$[6] = t0;
+		$[7] = t1;
+		$[8] = t2;
+		$[9] = t3;
+	} else t3 = $[9];
 	return t3;
 };
 /**
@@ -428,7 +464,14 @@ var Field$1 = {
 	InlineLabelText,
 	useIds: useFieldIds
 };
-function _temp(part) {
+function _temp(lineId) {
+	return /* @__PURE__ */ jsx(Field.Error, {
+		match: true,
+		id: lineId,
+		render: /* @__PURE__ */ jsx(Unrendered, {})
+	}, lineId);
+}
+function _temp2(part) {
 	return part !== "";
 }
 export { Field$1 as Field, useFieldIds };

package/dist/components/field/field.module.js

@@ -1,20 +1,22 @@
 import './field.css';// src/components/field/field.module.scss
-var field = "_field_14ydh_3";
-var label = "_label_14ydh_9";
-var optional = "_optional_14ydh_14";
-var inlineText = "_inlineText_14ydh_20";
-var inlineOptional = "_inlineOptional_14ydh_23";
-var required = "_required_14ydh_26";
-var description = "_description_14ydh_35";
-var pending = "_pending_14ydh_39";
+var field = "_field_dzutr_3";
+var label = "_label_dzutr_13";
+var description = "_description_dzutr_22";
+var error = "_error_dzutr_25";
+var optional = "_optional_dzutr_33";
+var inlineText = "_inlineText_dzutr_39";
+var inlineOptional = "_inlineOptional_dzutr_42";
+var required = "_required_dzutr_45";
+var pending = "_pending_dzutr_58";
 var field_module_default = {
 	field,
 	label,
+	description,
+	error,
 	optional,
 	inlineText,
 	inlineOptional,
 	required,
-	description,
 	pending
 };
-export { field_module_default as default, description, field, inlineOptional, inlineText, label, optional, pending, required };
+export { field_module_default as default, description, error, field, inlineOptional, inlineText, label, optional, pending, required };

package/dist/components/fieldset/field-group.d.ts

@@ -0,0 +1,31 @@
+import { type ReactNode } from "react";
+import type { FieldProps } from "../field/index.ts";
+import type { FieldsetErrorFormat, FieldsetMember } from "./fieldset-root.tsx";
+export type FieldGroupProps = Pick<FieldProps, "requiredness" | "optionalLabel"> & Readonly<{
+    /** The visible name of the group, such as "Address". */
+    legend: string;
+    /** Help about the group as a whole, under its legend. */
+    description?: ReactNode;
+    /** Errors about the group as a whole, such as a failed address lookup, in any shape `normalizeFieldErrors` accepts. */
+    errors?: unknown;
+    /** The fields whose errors the group shows in its own error instead of under each field. */
+    members?: readonly FieldsetMember[];
+    /** Turns a member's message into its line. Left out, the line is the message. */
+    formatError?: FieldsetErrorFormat;
+    className?: string;
+    /** The fields, laid out side by side. */
+    children: ReactNode;
+}>;
+/**
+ * Related fields side by side under one legend, with one error for all of
+ * them: the lines of its `members`, each tied to its field's control, then its
+ * own `errors`. Every field's label, control, description and error line up
+ * with its neighbours'. The `--field-group-columns` knob sets the columns.
+ *
+ * @example
+ * <FieldGroup legend="Address" optionalLabel="optional" members={members}>
+ * 	<TextField label="Postal code" … />
+ * 	<TextField label="House number" … />
+ * </FieldGroup>
+ */
+export declare const FieldGroup: ({ legend, description, errors, requiredness, optionalLabel, members, formatError, className, children, }: FieldGroupProps) => ReactNode;