schema-components 1.29.0 → 2.0.0

package/dist/react/a11y.d.mts

@@ -1,21 +1,88 @@
-import { j as WalkedField } from "../types-C2Ay1FEh.mjs";
+import { j as WalkedField } from "../types-BrYbjC7_.mjs";
+import { AllConstraints } from "../core/renderer.mjs";
 
 //#region src/react/a11y.d.ts
 /**
  * Build the ARIA attribute bundle for a renderer.
  *
  * - `aria-required="true"` whenever the field is non-optional.
+ * - `aria-describedby=<hint-id>` whenever a constraint hint applies.
  * - `aria-label=<description>` when a non-empty description is supplied.
  *
  * Returns a plain `Record<string, string>` (rather than a typed
  * attribute interface) so callers can spread the result into any JSX
  * element type without per-element TypeScript widening.
  *
- * Each helper from `html/a11y.ts` returns its corresponding fragment
- * separately. The React renderers merge them into a single object
- * here because the headless renderers compose one attribute bag per
- * `<input>` element rather than threading multiple bags through `h()`.
+ * `inputId` and `constraints` together control whether
+ * `aria-describedby` is emitted. Pass `undefined` for `constraints`
+ * when the renderer never emits a constraint hint (e.g. boolean
+ * checkboxes); the helper then skips the attribute entirely. When the
+ * caller does emit a hint via `buildHint(...)`, the `aria-describedby`
+ * id matches `hintIdFor(inputId)` so the wire-up holds end-to-end.
  */
-declare function buildAriaAttrs(tree: WalkedField, description?: unknown): Record<string, string>;
+declare function buildAriaAttrs(tree: WalkedField, description?: unknown, inputId?: string, constraints?: AllConstraints): Record<string, string>;
+/**
+ * Description for a constraint hint emitted alongside an input.
+ *
+ * Returned by {@link constraintHint} when the field carries one or
+ * more constraint keywords the user should be told about (min/max,
+ * pattern, item count, …). Theme adapters render this as a `<small>`
+ * element wired to the input via `aria-describedby`.
+ */
+interface Hint {
+  /** DOM id matching {@link hintIdFor}(inputId) on the host input. */
+  readonly id: string;
+  /** Human-readable hint text. */
+  readonly text: string;
+}
+/**
+ * Derive the constraint-hint descriptor for a field at `inputId`. Returns
+ * `undefined` when the field has no constraint worth announcing — callers
+ * skip rendering the `<small>` element entirely rather than emitting an
+ * empty node.
+ *
+ * Shares its text builder with `html/a11y.ts` so the two renderers
+ * always announce the same constraint copy for the same schema field.
+ */
+declare function constraintHint(inputId: string, constraints: AllConstraints): Hint | undefined;
+/**
+ * True when the supplied field is non-optional and therefore deserves
+ * a visual required indicator alongside its label.
+ *
+ * Exposed as a predicate rather than a JSX element so theme adapters
+ * can render the indicator in whatever element type matches their
+ * design language (`<span>`, `<sup>`, an icon component, …).
+ */
+declare function isFieldRequired(tree: WalkedField): boolean;
+/**
+ * Narrow `meta.description` (typed `unknown`) to a string value safe to
+ * pass into JSX `aria-label`. Returns `undefined` for non-string or
+ * empty-string descriptions so React drops the attribute rather than
+ * stringifying e.g. `{}` to `"[object Object]"`.
+ */
+declare function ariaLabel(description: unknown): string | undefined;
+/**
+ * Structured constraint-hint data for the React renderers.
+ *
+ * The HTML pipeline emits an inline `<small class="sc-hint">` element
+ * next to each input and references it through `aria-describedby`. The
+ * React pipeline mirrors that contract: the input takes the
+ * `ariaDescribedBy` id, the renderer emits a sibling `<small id={...}>`
+ * whose text is `hint`. Returns `undefined` when the field has no
+ * advertise-able constraints (`constraintHint` returns `undefined`) so
+ * callers can skip both the attribute and the element cleanly.
+ */
+interface HintInfo {
+  readonly id: string;
+  readonly hint: string;
+  readonly ariaDescribedBy: string;
+}
+/**
+ * Build {@link HintInfo} for a field at `inputId` given its declared
+ * constraints. Returns `undefined` when no constraint message would be
+ * produced — the React renderers then skip emitting the hint element
+ * entirely so consumers don't see an empty `<small>`.
+ */
+declare function buildHintInfo(inputId: string, constraints: AllConstraints): HintInfo | undefined;
 //#endregion
-export { buildAriaAttrs };
+export { Hint, HintInfo, ariaLabel, buildAriaAttrs, buildHintInfo, constraintHint, isFieldRequired };

package/dist/react/a11y.mjs

@@ -1,24 +1,85 @@
+import { constraintHint as constraintHint$1 } from "../core/constraintHint.mjs";
+import { hintIdFor } from "../core/idPath.mjs";
 //#region src/react/a11y.ts
 /**
 * Build the ARIA attribute bundle for a renderer.
 *
 * - `aria-required="true"` whenever the field is non-optional.
+* - `aria-describedby=<hint-id>` whenever a constraint hint applies.
 * - `aria-label=<description>` when a non-empty description is supplied.
 *
 * Returns a plain `Record<string, string>` (rather than a typed
 * attribute interface) so callers can spread the result into any JSX
 * element type without per-element TypeScript widening.
 *
-* Each helper from `html/a11y.ts` returns its corresponding fragment
-* separately. The React renderers merge them into a single object
-* here because the headless renderers compose one attribute bag per
-* `<input>` element rather than threading multiple bags through `h()`.
+* `inputId` and `constraints` together control whether
+* `aria-describedby` is emitted. Pass `undefined` for `constraints`
+* when the renderer never emits a constraint hint (e.g. boolean
+* checkboxes); the helper then skips the attribute entirely. When the
+* caller does emit a hint via `buildHint(...)`, the `aria-describedby`
+* id matches `hintIdFor(inputId)` so the wire-up holds end-to-end.
 */
-function buildAriaAttrs(tree, description) {
+function buildAriaAttrs(tree, description, inputId, constraints) {
 	const attrs = {};
 	if (tree.isOptional === false) attrs["aria-required"] = "true";
+	if (inputId !== void 0 && constraints !== void 0 && constraintHint$1(constraints) !== void 0) attrs["aria-describedby"] = hintIdFor(inputId);
 	if (typeof description === "string" && description.length > 0) attrs["aria-label"] = description;
 	return attrs;
 }
+/**
+* Derive the constraint-hint descriptor for a field at `inputId`. Returns
+* `undefined` when the field has no constraint worth announcing — callers
+* skip rendering the `<small>` element entirely rather than emitting an
+* empty node.
+*
+* Shares its text builder with `html/a11y.ts` so the two renderers
+* always announce the same constraint copy for the same schema field.
+*/
+function constraintHint(inputId, constraints) {
+	const text = constraintHint$1(constraints);
+	if (text === void 0) return void 0;
+	return {
+		id: hintIdFor(inputId),
+		text
+	};
+}
+/**
+* True when the supplied field is non-optional and therefore deserves
+* a visual required indicator alongside its label.
+*
+* Exposed as a predicate rather than a JSX element so theme adapters
+* can render the indicator in whatever element type matches their
+* design language (`<span>`, `<sup>`, an icon component, …).
+*/
+function isFieldRequired(tree) {
+	return tree.isOptional === false;
+}
+/**
+* Narrow `meta.description` (typed `unknown`) to a string value safe to
+* pass into JSX `aria-label`. Returns `undefined` for non-string or
+* empty-string descriptions so React drops the attribute rather than
+* stringifying e.g. `{}` to `"[object Object]"`.
+*/
+function ariaLabel(description) {
+	if (typeof description !== "string") return void 0;
+	if (description.length === 0) return void 0;
+	return description;
+}
+/**
+* Build {@link HintInfo} for a field at `inputId` given its declared
+* constraints. Returns `undefined` when no constraint message would be
+* produced — the React renderers then skip emitting the hint element
+* entirely so consumers don't see an empty `<small>`.
+*/
+function buildHintInfo(inputId, constraints) {
+	const hint = constraintHint$1(constraints);
+	if (hint === void 0) return void 0;
+	const id = hintIdFor(inputId);
+	return {
+		id,
+		hint,
+		ariaDescribedBy: id
+	};
+}
 //#endregion
-export { buildAriaAttrs };
+export { ariaLabel, buildAriaAttrs, buildHintInfo, constraintHint, isFieldRequired };

package/dist/react/fieldPath.d.mts

@@ -1,4 +1,4 @@
-import { j as WalkedField } from "../types-C2Ay1FEh.mjs";
+import { j as WalkedField } from "../types-BrYbjC7_.mjs";
 
 //#region src/react/fieldPath.d.ts
 /**
@@ -9,11 +9,26 @@ declare function resolvePath(tree: WalkedField, path: string): WalkedField | und
 /**
  * Resolve a dot-separated path through a data value.
  * Supports array index notation: `field[0]`.
+ *
+ * Path segments naming a prototype-polluting property (`__proto__`,
+ * `constructor`, `prototype`) refuse to resolve and return `undefined`.
+ * Without the refusal, an attacker-supplied path would read
+ * `Object.prototype` (or similar) and surface fields injected into the
+ * runtime prototype chain as if they belonged to the user's data.
  */
 declare function resolveValue(root: unknown, path: string): unknown;
 /**
  * Set a value at a dot-separated path, producing a new root object.
  * Does not mutate the input — returns a shallow-updated copy at each level.
+ *
+ * Refuses paths whose segments name a prototype-polluting property
+ * (`__proto__`, `constructor`, `prototype`). Such a path could otherwise
+ * mutate `Object.prototype` (or similar) through the assignment, planting
+ * fields visible to every plain object in the runtime. The input `root`
+ * is returned unchanged so the caller's onChange handler treats the
+ * write as a no-op rather than propagating a poisoned state. This
+ * matches the silent-refusal semantics of `dereference` in `core/ref.ts`
+ * when a JSON Pointer segment names a prototype-polluting key.
  */
 declare function setNestedValue(root: unknown, path: string, leafValue: unknown): unknown;
 //#endregion

package/dist/react/fieldPath.mjs

@@ -1,4 +1,5 @@
 import { isObject } from "../core/guards.mjs";
+import { isPrototypePollutingKey } from "../core/uri.mjs";
 //#region src/react/fieldPath.ts
 /**
 * Resolve a dot-separated path through a WalkedField tree.
@@ -26,6 +27,12 @@ function resolvePath(tree, path) {
 /**
 * Resolve a dot-separated path through a data value.
 * Supports array index notation: `field[0]`.
+*
+* Path segments naming a prototype-polluting property (`__proto__`,
+* `constructor`, `prototype`) refuse to resolve and return `undefined`.
+* Without the refusal, an attacker-supplied path would read
+* `Object.prototype` (or similar) and surface fields injected into the
+* runtime prototype chain as if they belonged to the user's data.
 */
 function resolveValue(root, path) {
 	if (path.length === 0) return root;
@@ -36,21 +43,38 @@ function resolveValue(root, path) {
 		const bracketMatch = /^(.+)\[(\d+)\]$/.exec(part);
 		if (bracketMatch?.[1] !== void 0 && bracketMatch[2] !== void 0) {
 			const key = bracketMatch[1];
+			if (isPrototypePollutingKey(key)) return void 0;
 			const index = Number(bracketMatch[2]);
 			const arr = current[key];
 			if (Array.isArray(arr)) current = arr[index];
 			else return;
-		} else current = current[part];
+		} else {
+			if (isPrototypePollutingKey(part)) return void 0;
+			current = current[part];
+		}
 	}
 	return current;
 }
 /**
 * Set a value at a dot-separated path, producing a new root object.
 * Does not mutate the input — returns a shallow-updated copy at each level.
+*
+* Refuses paths whose segments name a prototype-polluting property
+* (`__proto__`, `constructor`, `prototype`). Such a path could otherwise
+* mutate `Object.prototype` (or similar) through the assignment, planting
+* fields visible to every plain object in the runtime. The input `root`
+* is returned unchanged so the caller's onChange handler treats the
+* write as a no-op rather than propagating a poisoned state. This
+* matches the silent-refusal semantics of `dereference` in `core/ref.ts`
+* when a JSON Pointer segment names a prototype-polluting key.
 */
 function setNestedValue(root, path, leafValue) {
 	if (path.length === 0) return leafValue;
 	const parts = path.split(".");
+	for (const part of parts) {
+		const bracketMatch = /^(.+)\[(\d+)\]$/.exec(part);
+		if (isPrototypePollutingKey(bracketMatch?.[1] !== void 0 && bracketMatch[2] !== void 0 ? bracketMatch[1] : part)) return root;
+	}
 	const result = isObject(root) ? { ...root } : {};
 	let current = result;
 	for (let i = 0; i < parts.length; i++) {

package/dist/react/fieldShell.d.mts

@@ -0,0 +1,49 @@
+import { RenderProps } from "../core/renderer.mjs";
+import { ReactNode } from "react";
+
+//#region src/react/fieldShell.d.ts
+/**
+ * Render-time inputs to {@link FieldShell}. The shell does not depend
+ * on a theme; it consumes only the field metadata the walker has
+ * already produced.
+ */
+interface FieldShellProps {
+  /** The walked field props passed to the theme's render function. */
+  readonly props: RenderProps;
+  /** Stable DOM id for the host input. */
+  readonly inputId: string;
+  /**
+   * Children-as-function. Receives the ARIA attribute bundle so the
+   * caller can spread the attributes onto whatever element it
+   * produces; the shell does not inject them because the spread
+   * point varies between libraries (`inputProps`, top-level, slot
+   * props, …).
+   */
+  readonly children: (ariaAttrs: Record<string, string>) => ReactNode;
+  /**
+   * Optional override for the label text. Defaults to
+   * `props.meta.description` when undefined.
+   */
+  readonly label?: string;
+  /**
+   * When true, suppress the wrapping `<label>` element. Useful for
+   * adapters whose host primitive (e.g. MUI's `TextField`) already
+   * renders its own label.
+   */
+  readonly hideLabel?: boolean;
+}
+/**
+ * Compose label, host primitive, and constraint hint around a render
+ * function supplied by the theme adapter. Returns plain JSX — no
+ * theme-specific element types — so the same shell works under
+ * shadcn, MUI, Mantine, Radix, or any custom theme.
+ */
+declare function FieldShell({
+  props,
+  inputId,
+  children,
+  label,
+  hideLabel
+}: FieldShellProps): ReactNode;
+//#endregion
+export { FieldShell, FieldShellProps };

package/dist/react/fieldShell.mjs

@@ -0,0 +1,37 @@
+import { buildAriaAttrs, constraintHint, isFieldRequired } from "./a11y.mjs";
+import { jsx, jsxs } from "react/jsx-runtime";
+//#region src/react/fieldShell.tsx
+/**
+* Compose label, host primitive, and constraint hint around a render
+* function supplied by the theme adapter. Returns plain JSX — no
+* theme-specific element types — so the same shell works under
+* shadcn, MUI, Mantine, Radix, or any custom theme.
+*/
+function FieldShell({ props, inputId, children, label, hideLabel }) {
+	const description = typeof label === "string" ? label : typeof props.meta.description === "string" ? props.meta.description : void 0;
+	const required = isFieldRequired(props.tree);
+	const hint = constraintHint(inputId, props.constraints);
+	const ariaAttrs = buildAriaAttrs(props.tree, description, inputId, props.constraints);
+	return /* @__PURE__ */ jsxs("div", {
+		className: "sc-field",
+		children: [
+			hideLabel !== true && description !== void 0 && /* @__PURE__ */ jsxs("label", {
+				htmlFor: inputId,
+				children: [description, required && /* @__PURE__ */ jsxs("span", {
+					"aria-hidden": "true",
+					className: "sc-required",
+					style: { color: "#dc2626" },
+					children: [" ", "*"]
+				})]
+			}),
+			children(ariaAttrs),
+			hint !== void 0 && /* @__PURE__ */ jsx("small", {
+				className: "sc-hint",
+				id: hint.id,
+				children: hint.text
+			})
+		]
+	});
+}
+//#endregion
+export { FieldShell };

package/dist/react/headless.d.mts

@@ -1,4 +1,4 @@
-import { r as ComponentResolver } from "../renderer-OaOz-n6-.mjs";
+import { ComponentResolver } from "../core/renderer.mjs";
 
 //#region src/react/headless.d.ts
 /**

package/dist/react/headlessRenderers.d.mts

@@ -1,5 +1,5 @@
-import { j as WalkedField } from "../types-C2Ay1FEh.mjs";
-import { l as RenderProps } from "../renderer-OaOz-n6-.mjs";
+import { j as WalkedField } from "../types-BrYbjC7_.mjs";
+import { RenderProps } from "../core/renderer.mjs";
 import { ReactNode } from "react";
 
 //#region src/react/headlessRenderers.d.ts