@stridge/noctis 1.0.0-beta.0

package/dist/components/dialog/dialog.props.js

@@ -0,0 +1,75 @@
+import { DIALOG_SLOTS } from "./dialog.slots.js";
+//#region src/components/dialog/dialog.props.ts
+/**
+* The D12 unified variant contract for Dialog — each compound part exposes a `props(...)` builder
+* returning a **spreadable data-attribute prop bag** of the form
+* `{ "data-slot": "noctis-dialog-<part>", ...dataAttrs }`, derived from the part's variant inputs.
+*
+* Under the single-`data-slot` anchor model the `data-slot` (plus `data-size` on the popup) is the only
+* styling hook needed — `dialog.css` keys every rule off it — so spreading a part's `props()` onto a
+* *foreign* element styles it as that part:
+*
+*     <div {...Dialog.Popup.props({ size: "lg" })} />
+*     // → <div data-slot="noctis-dialog-popup" data-size="lg">
+*
+* The escape hatch carries no className (styling is attribute-driven); an optional `className`
+* passthrough is accepted and forwarded verbatim. The same variant→data-attribute→values mapping is
+* emitted as data from the token graph (`generated/declarations.json` → `variantSchema`) so non-React /
+* agent consumers can hand-write the markup from the docs.
+*/
+const withClassName = (bag, className) => className === void 0 ? bag : {
+	...bag,
+	className
+};
+/** Trigger prop bag: just the slot anchor. */
+function triggerProps({ className } = {}) {
+	return withClassName({ "data-slot": DIALOG_SLOTS.trigger }, className);
+}
+/** Backdrop prop bag: just the slot anchor (the scrim's paint flows from `dialog.css`). */
+function backdropProps({ className } = {}) {
+	return withClassName({ "data-slot": DIALOG_SLOTS.backdrop }, className);
+}
+/** Viewport prop bag: just the slot anchor (the overlay-level scroll container for `scroll="viewport"`). */
+function viewportProps({ className } = {}) {
+	return withClassName({ "data-slot": DIALOG_SLOTS.viewport }, className);
+}
+/** Popup prop bag: slot anchor plus the `data-size` the popup width rule reads. */
+function popupProps({ size = "md", className } = {}) {
+	return withClassName({
+		"data-slot": DIALOG_SLOTS.popup,
+		"data-size": size
+	}, className);
+}
+/** Close prop bag: just the slot anchor (it carries no paint of its own — it composes with a Button). */
+function closeProps({ className } = {}) {
+	return withClassName({ "data-slot": DIALOG_SLOTS.close }, className);
+}
+/**
+* CloseButton prop bag: the same `noctis-dialog-close` slot the convenience corner button reuses, so a
+* hand-built close affordance and `Dialog.CloseButton` anchor on the identical selector.
+*/
+function closeButtonProps({ className } = {}) {
+	return withClassName({ "data-slot": DIALOG_SLOTS.close }, className);
+}
+/** Header prop bag: just the slot anchor. */
+function headerProps({ className } = {}) {
+	return withClassName({ "data-slot": DIALOG_SLOTS.header }, className);
+}
+/** Body prop bag: just the slot anchor. */
+function bodyProps({ className } = {}) {
+	return withClassName({ "data-slot": DIALOG_SLOTS.body }, className);
+}
+/** Footer prop bag: just the slot anchor. */
+function footerProps({ className } = {}) {
+	return withClassName({ "data-slot": DIALOG_SLOTS.footer }, className);
+}
+/** Title prop bag: just the slot anchor. */
+function titleProps({ className } = {}) {
+	return withClassName({ "data-slot": DIALOG_SLOTS.title }, className);
+}
+/** Description prop bag: just the slot anchor. */
+function descriptionProps({ className } = {}) {
+	return withClassName({ "data-slot": DIALOG_SLOTS.description }, className);
+}
+//#endregion
+export { backdropProps, bodyProps, closeButtonProps, closeProps, descriptionProps, footerProps, headerProps, popupProps, titleProps, triggerProps, viewportProps };

package/dist/components/dialog/dialog.slots.d.ts

@@ -0,0 +1,26 @@
+//#region src/components/dialog/dialog.slots.d.ts
+/**
+ * The `data-*` attributes the rendered `Dialog` parts carry, beyond `data-slot`. Each member's value is
+ * the attribute name; its JSDoc is the description docgen renders into the attributes table. The state
+ * attributes come from Base UI's Dialog parts; `data-size` is stamped by the popup.
+ */
+declare enum DialogDataAttributes {
+  /** The stable, prefixed styling/testing hook on every rendered part. */
+  slot = "data-slot",
+  /** Present on the popup: the cross-axis cap (`sm` / `md` / `lg` / `full`) the width rules key off. */
+  size = "data-size",
+  /** Present on the popup, backdrop, and trigger while the dialog is open. */
+  open = "data-open",
+  /** Present on the popup, backdrop, and trigger while the dialog is closed. */
+  closed = "data-closed",
+  /** Present on the popup and backdrop during the enter transition's first frame. */
+  startingStyle = "data-starting-style",
+  /** Present on the popup and backdrop during the exit transition. */
+  endingStyle = "data-ending-style",
+  /** Present on the popup when it is nested inside another dialog. */
+  nested = "data-nested",
+  /** Present on the popup when it has a nested dialog open on top of it. */
+  nestedDialogOpen = "data-nested-dialog-open"
+}
+//#endregion
+export { DialogDataAttributes };

package/dist/components/dialog/dialog.slots.js

@@ -0,0 +1,46 @@
+//#region src/components/dialog/dialog.slots.ts
+/**
+* The slot vocabulary every `Dialog` part stamps as its `data-slot`. The authored source the
+* orchestration file reads from, kebab-cased `{component}-{part}`; SLOTS.md still generates from the
+* token-graph declarations. `Dialog.Root` wraps Base UI's `Dialog.Root` without rendering an element of
+* its own, and `Dialog.Content` composes the portal/backdrop/(viewport/)popup without stamping a slot —
+* so neither appears here, keeping the const parity-true to the rendered DOM.
+*/
+const DIALOG_SLOTS = {
+	trigger: "noctis-dialog-trigger",
+	backdrop: "noctis-dialog-backdrop",
+	viewport: "noctis-dialog-viewport",
+	popup: "noctis-dialog-popup",
+	close: "noctis-dialog-close",
+	header: "noctis-dialog-header",
+	body: "noctis-dialog-body",
+	footer: "noctis-dialog-footer",
+	title: "noctis-dialog-title",
+	description: "noctis-dialog-description"
+};
+/**
+* The `data-*` attributes the rendered `Dialog` parts carry, beyond `data-slot`. Each member's value is
+* the attribute name; its JSDoc is the description docgen renders into the attributes table. The state
+* attributes come from Base UI's Dialog parts; `data-size` is stamped by the popup.
+*/
+let DialogDataAttributes = /* @__PURE__ */ function(DialogDataAttributes) {
+	/** The stable, prefixed styling/testing hook on every rendered part. */
+	DialogDataAttributes["slot"] = "data-slot";
+	/** Present on the popup: the cross-axis cap (`sm` / `md` / `lg` / `full`) the width rules key off. */
+	DialogDataAttributes["size"] = "data-size";
+	/** Present on the popup, backdrop, and trigger while the dialog is open. */
+	DialogDataAttributes["open"] = "data-open";
+	/** Present on the popup, backdrop, and trigger while the dialog is closed. */
+	DialogDataAttributes["closed"] = "data-closed";
+	/** Present on the popup and backdrop during the enter transition's first frame. */
+	DialogDataAttributes["startingStyle"] = "data-starting-style";
+	/** Present on the popup and backdrop during the exit transition. */
+	DialogDataAttributes["endingStyle"] = "data-ending-style";
+	/** Present on the popup when it is nested inside another dialog. */
+	DialogDataAttributes["nested"] = "data-nested";
+	/** Present on the popup when it has a nested dialog open on top of it. */
+	DialogDataAttributes["nestedDialogOpen"] = "data-nested-dialog-open";
+	return DialogDataAttributes;
+}({});
+//#endregion
+export { DIALOG_SLOTS, DialogDataAttributes };

package/dist/components/dialog/dialog.types.d.ts

@@ -0,0 +1,16 @@
+//#region src/components/dialog/dialog.types.d.ts
+/**
+ * The size and scroll vocabularies `Dialog` carries — the authored source of truth since styling lives
+ * in precompiled `dialog.css`. Types-only: no runtime code, so they never participate in the styling
+ * layer.
+ */
+/** The dialog's cross-axis extent — its maximum width. `full` lifts the cap for a near-fullscreen panel. */
+type DialogSize = "sm" | "md" | "lg" | "full";
+/**
+ * How a tall dialog scrolls. `body` (default) scrolls the inner body region so the header and footer
+ * stay pinned; `viewport` scrolls the whole panel inside an overlay-level scroll container, so the
+ * dialog stays centered when it fits and grows past the viewport without the page scrolling.
+ */
+type DialogScroll = "body" | "viewport";
+//#endregion
+export { DialogScroll, DialogSize };

package/dist/components/dialog/index.d.ts

@@ -0,0 +1,3 @@
+import { DialogScroll, DialogSize } from "./dialog.types.js";
+import { Dialog } from "./dialog.js";
+import { DialogDataAttributes } from "./dialog.slots.js";

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

@@ -0,0 +1,221 @@
+import { field_d_exports } from "../../primitives/field.js";
+import { fieldset_d_exports } from "../../primitives/fieldset.js";
+import { form_d_exports } from "../../primitives/form.js";
+import { FieldActionSide } from "./field.types.js";
+import { FieldPartProps, actionProps, controlProps, countProps, descriptionProps, errorProps, fieldsetProps, formProps, labelProps, legendProps, rootProps } from "./field.props.js";
+import { ComponentPropsWithRef, ReactElement } from "react";
+
+//#region src/components/field/field.d.ts
+/**
+ * Groups one field's label, control, description, and error so assistive tech reads them together.
+ * Base UI manages the `aria-labelledby`/`aria-describedby` wiring and the live validity state
+ * (`data-invalid`, `data-touched`, `data-dirty`, …) it stamps on each part. Set `name` to identify the
+ * field on submit, `validate` for custom validation, and `disabled` to opt the whole field out of
+ * interaction. Drop a styled control (`Input`, `Textarea`, …) inside it directly — they auto-wire.
+ */
+declare function FieldRoot({
+  className,
+  ...props
+}: Field.Root.Props): ReactElement;
+/**
+ * The field's label, automatically associated with its control — clicking it focuses the control. Set
+ * `nativeLabel={false}` when rendering the label onto a non-`<label>` element (e.g. labelling a button
+ * trigger) so it doesn't inherit `<label>` click/hover behaviour.
+ */
+declare function FieldLabel({
+  className,
+  ...props
+}: Field.Label.Props): ReactElement;
+/**
+ * The form control to label and validate. Renders a native `<input>` by default — the no-chrome path;
+ * pass `render` to use a different element. For a styled field, omit this and place a control shell
+ * (`Input`/`Textarea`) inside `Field.Root` instead: its control auto-wires to the field.
+ */
+declare function FieldControl({
+  className,
+  ...props
+}: Field.Control.Props): ReactElement;
+/** Supporting text describing the field, wired to the control via `aria-describedby`. */
+declare function FieldDescription({
+  className,
+  ...props
+}: Field.Description.Props): ReactElement;
+/**
+ * The validation error message, shown only while the field is invalid. Pass `match` to tie it to a
+ * specific `ValidityState` key (e.g. `valueMissing`) so each rule gets its own message, or `match` as a
+ * boolean to let an external form library control visibility.
+ */
+declare function FieldError({
+  className,
+  ...props
+}: Field.Error.Props): ReactElement;
+/**
+ * The shared interactive in-field affordance — the substrate for clear, password-reveal, and shortcut
+ * buttons across the field family (exposed as `Field.Action`, and aliased as `Input.Action`,
+ * `Textarea.Action`, …). Renders a real `<button>` with the system's ghost-control discipline: a neutral
+ * rest, a neutral `control-ghost-hover` fill (never an accent), and its own `:focus-visible` ring. It is
+ * a compact square — the host field's glyph size plus a tight inset — centred against the field. Set
+ * `side` to `end` (trailing, default) or `start`. **Icon-only actions require an `aria-label`** (or a
+ * `VisuallyHidden` child); a toggle such as password-reveal should keep a static label and flip
+ * `aria-pressed` rather than swap its name. Defaults to `type="button"`; add `data-reveal="filled"` to
+ * show it only while the host field's control holds a value (driven by the host's CSS `:has()`).
+ */
+declare function FieldAction({
+  side,
+  type,
+  className,
+  children,
+  ...props
+}: FieldAction.Props): ReactElement;
+declare namespace FieldAction {
+  type Props = ComponentPropsWithRef<"button"> & {
+    /**
+     * Which edge the action sits on — leading (`start`) or trailing (`end`).
+     * @default "end"
+     */
+    side?: FieldActionSide;
+  };
+}
+/**
+ * The shared quiet character-count readout for a field's trailing edge (exposed as `Field.Count`, and
+ * aliased as `Input.Count`, `Textarea.Count`, …). Pass the control's current `value` and a `max`; it
+ * shows `length / max`, escalates `muted` → `warning` → `danger` as the value nears and then passes the
+ * limit, and announces the remaining count through a polite, atomic live region (empty on first paint,
+ * and only once near the limit). Give it an `id` and point the control's `aria-describedby` at it so the
+ * count is also read as the field's description. With no `max` it simply shows the current length.
+ */
+declare function FieldCount({
+  value,
+  max,
+  className,
+  ...props
+}: FieldCount.Props): ReactElement;
+declare namespace FieldCount {
+  type Props = Omit<ComponentPropsWithRef<"span">, "children"> & {
+    /**
+     * The control's current value; its length is counted against `max`.
+     * @default ""
+     */
+    value?: string; /** The character limit. Omit it to show only the current length. */
+    max?: number;
+  };
+}
+/**
+ * The field layer: the wiring that ties a label, control, description, and error together for one input
+ * (with the aria wiring and validity state managed for you), plus the shared in-field affordances every
+ * control reuses. Drop a styled control (`Input`/`Textarea`) inside `Field.Root` — it auto-wires — or use
+ * the bare `Field.Control` for a no-chrome input.
+ */
+declare const Field: {
+  /** The field container. `Field.Root.props()` → its spreadable prop bag. */Root: typeof FieldRoot & {
+    props: typeof rootProps;
+  }; /** The associated label. `Field.Label.props()` → its spreadable prop bag. */
+  Label: typeof FieldLabel & {
+    props: typeof labelProps;
+  }; /** The form control (bare-input seam; styled controls drop in directly). `Field.Control.props()` → its prop bag. */
+  Control: typeof FieldControl & {
+    props: typeof controlProps;
+  }; /** Supporting description text. `Field.Description.props()` → its spreadable prop bag. */
+  Description: typeof FieldDescription & {
+    props: typeof descriptionProps;
+  }; /** The validation error message. `Field.Error.props()` → its spreadable prop bag. */
+  Error: typeof FieldError & {
+    props: typeof errorProps;
+  }; /** The shared in-field action button. `Field.Action.props({ side })` → its spreadable prop bag. */
+  Action: typeof FieldAction & {
+    props: typeof actionProps;
+  }; /** The shared character-count readout. `Field.Count.props()` → its spreadable prop bag. */
+  Count: typeof FieldCount & {
+    props: typeof countProps;
+  };
+};
+/**
+ * Per-part prop and state types, mirroring Base UI's `Component.Part.Props` convention. Types-only — it
+ * merges with the `Field` object above, so `Field.Control` is the component value while
+ * `Field.Control.Props` is its prop type.
+ */
+declare namespace Field {
+  /** The spreadable data-attribute prop bag every field `*.props()` returns (D12). */
+  type PartProps = FieldPartProps;
+  namespace Root {
+    type Props = field_d_exports.Field.Root.Props;
+    type State = field_d_exports.Field.Root.State;
+    type Actions = field_d_exports.Field.Root.Actions;
+  }
+  namespace Label {
+    type Props = field_d_exports.Field.Label.Props;
+    type State = field_d_exports.Field.Label.State;
+  }
+  namespace Control {
+    type Props = field_d_exports.Field.Control.Props;
+    type State = field_d_exports.Field.Control.State;
+  }
+  namespace Description {
+    type Props = field_d_exports.Field.Description.Props;
+    type State = field_d_exports.Field.Description.State;
+  }
+  namespace Error {
+    type Props = field_d_exports.Field.Error.Props;
+    type State = field_d_exports.Field.Error.State;
+  }
+  /** The shared in-field action button — see {@link FieldAction}. */
+  namespace Action {
+    type Props = FieldAction.Props;
+  }
+  /** The shared character-count readout — see {@link FieldCount}. */
+  namespace Count {
+    type Props = FieldCount.Props;
+  }
+}
+/** Groups related fields under a shared legend, so a screen reader announces the group on each control. */
+declare function FieldsetRoot({
+  className,
+  ...props
+}: Fieldset.Root.Props): ReactElement;
+/** The fieldset's accessible label, automatically associated with the group. */
+declare function FieldsetLegend({
+  className,
+  ...props
+}: Fieldset.Legend.Props): ReactElement;
+/** Groups related fields under one legend — the wiring layer's section header. */
+declare const Fieldset: {
+  /** The fieldset container. `Fieldset.Root.props()` → its spreadable prop bag. */Root: typeof FieldsetRoot & {
+    props: typeof fieldsetProps;
+  }; /** The group legend. `Fieldset.Legend.props()` → its spreadable prop bag. */
+  Legend: typeof FieldsetLegend & {
+    props: typeof legendProps;
+  };
+};
+/** Per-part prop and state types for `Fieldset`. Types-only; merges with the object above. */
+declare namespace Fieldset {
+  namespace Root {
+    type Props = fieldset_d_exports.Fieldset.Root.Props;
+    type State = fieldset_d_exports.Fieldset.Root.State;
+  }
+  namespace Legend {
+    type Props = fieldset_d_exports.Fieldset.Legend.Props;
+    type State = fieldset_d_exports.Fieldset.Legend.State;
+  }
+}
+/**
+ * A native `<form>` with consolidated error handling. Validates its fields together, reports external
+ * `errors` keyed by field `name`, and calls `onFormSubmit` with the collected values once valid. Stacks
+ * its fields and fieldsets with a shared vertical rhythm.
+ */
+declare function FormImpl({
+  className,
+  ...props
+}: Form.Props): ReactElement;
+/** The form wrapper: a native `<form>` with consolidated validation and error reporting. */
+declare const Form: typeof FormImpl & {
+  props: typeof formProps;
+};
+/** Prop and state types for `Form`. Types-only; merges with the function above. */
+declare namespace Form {
+  type Props = form_d_exports.Form.Props;
+  type State = form_d_exports.Form.State;
+  type Actions = form_d_exports.Form.Actions;
+  type ValidationMode = form_d_exports.Form.ValidationMode;
+}
+//#endregion
+export { Field, FieldAction, FieldCount, Fieldset, Form };

package/dist/components/field/field.js

@@ -0,0 +1,192 @@
+"use client";
+import { useNoctisStringFormatter } from "../../core/use-injected-labels.js";
+import { VisuallyHidden } from "../../core/visually-hidden/visually-hidden.js";
+import { field_exports } from "../../primitives/field.js";
+import { fieldset_exports } from "../../primitives/fieldset.js";
+import { form_exports } from "../../primitives/form.js";
+import { FIELD_SLOTS } from "./field.slots.js";
+import { actionProps, controlProps, countProps, descriptionProps, errorProps, fieldsetProps, formProps, labelProps, legendProps, rootProps } from "./field.props.js";
+import { useEffect, useRef } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+//#region src/components/field/field.tsx
+/** How near the limit (in remaining characters) the count escalates to its warning colour and starts announcing. */
+const COUNT_WARN_RATIO = .1;
+/**
+* Groups one field's label, control, description, and error so assistive tech reads them together.
+* Base UI manages the `aria-labelledby`/`aria-describedby` wiring and the live validity state
+* (`data-invalid`, `data-touched`, `data-dirty`, …) it stamps on each part. Set `name` to identify the
+* field on submit, `validate` for custom validation, and `disabled` to opt the whole field out of
+* interaction. Drop a styled control (`Input`, `Textarea`, …) inside it directly — they auto-wire.
+*/
+function FieldRoot({ className, ...props }) {
+	return /* @__PURE__ */ jsx(field_exports.Field.Root, {
+		"data-slot": FIELD_SLOTS.root,
+		className,
+		...props
+	});
+}
+/**
+* The field's label, automatically associated with its control — clicking it focuses the control. Set
+* `nativeLabel={false}` when rendering the label onto a non-`<label>` element (e.g. labelling a button
+* trigger) so it doesn't inherit `<label>` click/hover behaviour.
+*/
+function FieldLabel({ className, ...props }) {
+	return /* @__PURE__ */ jsx(field_exports.Field.Label, {
+		"data-slot": FIELD_SLOTS.label,
+		className,
+		...props
+	});
+}
+/**
+* The form control to label and validate. Renders a native `<input>` by default — the no-chrome path;
+* pass `render` to use a different element. For a styled field, omit this and place a control shell
+* (`Input`/`Textarea`) inside `Field.Root` instead: its control auto-wires to the field.
+*/
+function FieldControl({ className, ...props }) {
+	return /* @__PURE__ */ jsx(field_exports.Field.Control, {
+		"data-slot": FIELD_SLOTS.control,
+		className,
+		...props
+	});
+}
+/** Supporting text describing the field, wired to the control via `aria-describedby`. */
+function FieldDescription({ className, ...props }) {
+	return /* @__PURE__ */ jsx(field_exports.Field.Description, {
+		"data-slot": FIELD_SLOTS.description,
+		className,
+		...props
+	});
+}
+/**
+* The validation error message, shown only while the field is invalid. Pass `match` to tie it to a
+* specific `ValidityState` key (e.g. `valueMissing`) so each rule gets its own message, or `match` as a
+* boolean to let an external form library control visibility.
+*/
+function FieldError({ className, ...props }) {
+	return /* @__PURE__ */ jsx(field_exports.Field.Error, {
+		"data-slot": FIELD_SLOTS.error,
+		className,
+		...props
+	});
+}
+/**
+* The shared interactive in-field affordance — the substrate for clear, password-reveal, and shortcut
+* buttons across the field family (exposed as `Field.Action`, and aliased as `Input.Action`,
+* `Textarea.Action`, …). Renders a real `<button>` with the system's ghost-control discipline: a neutral
+* rest, a neutral `control-ghost-hover` fill (never an accent), and its own `:focus-visible` ring. It is
+* a compact square — the host field's glyph size plus a tight inset — centred against the field. Set
+* `side` to `end` (trailing, default) or `start`. **Icon-only actions require an `aria-label`** (or a
+* `VisuallyHidden` child); a toggle such as password-reveal should keep a static label and flip
+* `aria-pressed` rather than swap its name. Defaults to `type="button"`; add `data-reveal="filled"` to
+* show it only while the host field's control holds a value (driven by the host's CSS `:has()`).
+*/
+function FieldAction({ side = "end", type, className, children, ...props }) {
+	const { className: _omit, ...recipe } = actionProps({ side });
+	return /* @__PURE__ */ jsx("button", {
+		type: type ?? "button",
+		...recipe,
+		"data-slot": FIELD_SLOTS.action,
+		className,
+		...props,
+		children
+	});
+}
+/**
+* The shared quiet character-count readout for a field's trailing edge (exposed as `Field.Count`, and
+* aliased as `Input.Count`, `Textarea.Count`, …). Pass the control's current `value` and a `max`; it
+* shows `length / max`, escalates `muted` → `warning` → `danger` as the value nears and then passes the
+* limit, and announces the remaining count through a polite, atomic live region (empty on first paint,
+* and only once near the limit). Give it an `id` and point the control's `aria-describedby` at it so the
+* count is also read as the field's description. With no `max` it simply shows the current length.
+*/
+function FieldCount({ value = "", max, className, ...props }) {
+	const { className: _omit, ...recipe } = countProps();
+	const formatter = useNoctisStringFormatter();
+	const announced = useRef(false);
+	useEffect(() => {
+		announced.current = true;
+	}, []);
+	const length = value.length;
+	const hasMax = max !== void 0;
+	const remaining = hasMax ? max - length : 0;
+	const over = hasMax && remaining < 0;
+	const near = hasMax && !over && remaining <= Math.ceil(max * COUNT_WARN_RATIO);
+	const liveText = announced.current && (near || over) ? formatter.format("field.charactersRemaining", { count: Math.max(0, remaining) }) : "";
+	return /* @__PURE__ */ jsxs("span", {
+		...recipe,
+		"data-slot": FIELD_SLOTS.count,
+		"data-near": near ? "" : void 0,
+		"data-over": over ? "" : void 0,
+		className,
+		...props,
+		children: [/* @__PURE__ */ jsx("span", {
+			"aria-hidden": "true",
+			children: hasMax ? `${length}/${max}` : length
+		}), /* @__PURE__ */ jsx(VisuallyHidden, {
+			"aria-live": "polite",
+			"aria-atomic": "true",
+			children: liveText
+		})]
+	});
+}
+/**
+* The field layer: the wiring that ties a label, control, description, and error together for one input
+* (with the aria wiring and validity state managed for you), plus the shared in-field affordances every
+* control reuses. Drop a styled control (`Input`/`Textarea`) inside `Field.Root` — it auto-wires — or use
+* the bare `Field.Control` for a no-chrome input.
+*/
+const Field = {
+	/** The field container. `Field.Root.props()` → its spreadable prop bag. */
+	Root: Object.assign(FieldRoot, { props: rootProps }),
+	/** The associated label. `Field.Label.props()` → its spreadable prop bag. */
+	Label: Object.assign(FieldLabel, { props: labelProps }),
+	/** The form control (bare-input seam; styled controls drop in directly). `Field.Control.props()` → its prop bag. */
+	Control: Object.assign(FieldControl, { props: controlProps }),
+	/** Supporting description text. `Field.Description.props()` → its spreadable prop bag. */
+	Description: Object.assign(FieldDescription, { props: descriptionProps }),
+	/** The validation error message. `Field.Error.props()` → its spreadable prop bag. */
+	Error: Object.assign(FieldError, { props: errorProps }),
+	/** The shared in-field action button. `Field.Action.props({ side })` → its spreadable prop bag. */
+	Action: Object.assign(FieldAction, { props: actionProps }),
+	/** The shared character-count readout. `Field.Count.props()` → its spreadable prop bag. */
+	Count: Object.assign(FieldCount, { props: countProps })
+};
+/** Groups related fields under a shared legend, so a screen reader announces the group on each control. */
+function FieldsetRoot({ className, ...props }) {
+	return /* @__PURE__ */ jsx(fieldset_exports.Fieldset.Root, {
+		"data-slot": FIELD_SLOTS.fieldset,
+		className,
+		...props
+	});
+}
+/** The fieldset's accessible label, automatically associated with the group. */
+function FieldsetLegend({ className, ...props }) {
+	return /* @__PURE__ */ jsx(fieldset_exports.Fieldset.Legend, {
+		"data-slot": FIELD_SLOTS.fieldsetLegend,
+		className,
+		...props
+	});
+}
+/** Groups related fields under one legend — the wiring layer's section header. */
+const Fieldset = {
+	/** The fieldset container. `Fieldset.Root.props()` → its spreadable prop bag. */
+	Root: Object.assign(FieldsetRoot, { props: fieldsetProps }),
+	/** The group legend. `Fieldset.Legend.props()` → its spreadable prop bag. */
+	Legend: Object.assign(FieldsetLegend, { props: legendProps })
+};
+/**
+* A native `<form>` with consolidated error handling. Validates its fields together, reports external
+* `errors` keyed by field `name`, and calls `onFormSubmit` with the collected values once valid. Stacks
+* its fields and fieldsets with a shared vertical rhythm.
+*/
+function FormImpl({ className, ...props }) {
+	return /* @__PURE__ */ jsx(form_exports.Form, {
+		"data-slot": FIELD_SLOTS.form,
+		className,
+		...props
+	});
+}
+/** The form wrapper: a native `<form>` with consolidated validation and error reporting. */
+const Form = Object.assign(FormImpl, { props: formProps });
+//#endregion
+export { Field, FieldAction, FieldCount, Fieldset, Form };

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

@@ -0,0 +1,66 @@
+import { FieldActionSide } from "./field.types.js";
+
+//#region src/components/field/field.props.d.ts
+/** A spreadable data-attribute prop bag — the shape every field `*.props()` returns. */
+type FieldPartProps = {
+  /** The slot value the matching `field.css` rules anchor on. */"data-slot": string; /** Forwarded verbatim — styling is attribute-driven, so this is an optional consumer passthrough. */
+  className?: string; /** A data-attribute present (empty string) or absent (`undefined`); never `false`. */
+  [attr: `data-${string}`]: string | undefined;
+};
+/** Common shape: every part's `.props()` accepts an optional `className` passthrough. */
+interface BasePropsArgs {
+  /** Forwarded verbatim onto the returned prop bag. */
+  className?: string;
+}
+/** Argument to a stateless field part's `.props(...)` — no variants/state of its own. */
+type FieldPartPropsArgs = BasePropsArgs;
+/** Argument to `actionProps(...)` — which edge the in-field action button sits on. */
+interface FieldActionPropsArgs extends BasePropsArgs {
+  /** Which edge the action sits on — leading (`start`) or trailing (`end`). @default "end" */
+  side?: FieldActionSide;
+}
+/** Argument to `countProps(...)` — the counter carries no variants; its escalation is value-driven at runtime. */
+type FieldCountPropsArgs = BasePropsArgs;
+/** Root prop bag: just the slot anchor. */
+declare function rootProps({
+  className
+}?: FieldPartPropsArgs): FieldPartProps;
+/** Label prop bag: just the slot anchor. */
+declare function labelProps({
+  className
+}?: FieldPartPropsArgs): FieldPartProps;
+/** Control prop bag: just the slot anchor. */
+declare function controlProps({
+  className
+}?: FieldPartPropsArgs): FieldPartProps;
+/** Description prop bag: just the slot anchor. */
+declare function descriptionProps({
+  className
+}?: FieldPartPropsArgs): FieldPartProps;
+/** Error prop bag: just the slot anchor. */
+declare function errorProps({
+  className
+}?: FieldPartPropsArgs): FieldPartProps;
+/** Fieldset prop bag: just the slot anchor. */
+declare function fieldsetProps({
+  className
+}?: FieldPartPropsArgs): FieldPartProps;
+/** Fieldset legend prop bag: just the slot anchor. */
+declare function legendProps({
+  className
+}?: FieldPartPropsArgs): FieldPartProps;
+/** Form prop bag: just the slot anchor. */
+declare function formProps({
+  className
+}?: FieldPartPropsArgs): FieldPartProps;
+/** Action prop bag: slot anchor plus the `data-side` edge (the in-field ghost button). */
+declare function actionProps({
+  side,
+  className
+}?: FieldActionPropsArgs): FieldPartProps;
+/** Count prop bag: just the slot anchor (the character-count readout; escalation is value-driven). */
+declare function countProps({
+  className
+}?: FieldCountPropsArgs): FieldPartProps;
+//#endregion
+export { FieldActionPropsArgs, FieldCountPropsArgs, FieldPartProps, actionProps, controlProps, countProps, descriptionProps, errorProps, fieldsetProps, formProps, labelProps, legendProps, rootProps };