fluid-primitives 0.19.1 → 1.0.0-beta.1

package/dist/dialog.js

@@ -1,30 +1,29 @@
-import { a as Machine, p as Component, r as normalizeProps } from "./Client-C51NSHxg.js";
+import { a as normalizeProps, at as Machine, rt as Component } from "./Client-HrMIqv7d.js";
 import * as dialog from "@zag-js/dialog";
 
 //#region Resources/Private/Primitives/Dialog/Dialog.ts
 var Dialog = class extends Component {
-	static name = "dialog";
+	static componentName = "dialog";
 	initMachine(props) {
-		return new Machine(dialog.machine, props);
+		const [machineProps] = dialog.splitProps(props);
+		return new Machine(dialog.machine, machineProps);
 	}
 	initApi() {
 		return dialog.connect(this.machine.service, normalizeProps);
 	}
 	render() {
-		this.getElements("trigger").forEach((trigger) => {
-			this.spreadProps(trigger, this.api.getTriggerProps());
-		});
-		const backdropEl = this.getElement("backdrop");
+		this.spreadPropsByOptionalValue("trigger", ({ value }) => this.api.getTriggerProps({ value }));
+		const backdropEl = this.hydrator.query("backdrop");
 		if (backdropEl) this.spreadProps(backdropEl, this.api.getBackdropProps());
-		const positionerEl = this.getElement("positioner");
+		const positionerEl = this.hydrator.query("positioner");
 		if (positionerEl) this.spreadProps(positionerEl, this.api.getPositionerProps());
-		const contentEl = this.getElement("content");
+		const contentEl = this.hydrator.query("content");
 		if (contentEl) this.spreadProps(contentEl, this.api.getContentProps());
-		const titleEl = this.getElement("title");
+		const titleEl = this.hydrator.query("title");
 		if (titleEl) this.spreadProps(titleEl, this.api.getTitleProps());
-		const descriptionEl = this.getElement("description");
+		const descriptionEl = this.hydrator.query("description");
 		if (descriptionEl) this.spreadProps(descriptionEl, this.api.getDescriptionProps());
-		this.getElements("close-trigger").forEach((trigger) => {
+		this.hydrator.queryAll("closeTrigger").forEach((trigger) => {
 			this.spreadProps(trigger, this.api.getCloseTriggerProps());
 		});
 	}

package/dist/field-array.d.ts

@@ -0,0 +1,97 @@
+import { C as FieldValue, c as Machine$1, z as Component } from "./index-B06gIN_k.js";
+import { EventObject } from "@zag-js/core";
+import { PropTypes } from "@zag-js/types";
+//#region Resources/Private/Primitives/FieldArray/src/field-array.types.d.ts
+/**
+ * What a `translations.rowAdded` or `rowRemoved` callback receives, to build an announcement from the
+ * data of the row, e.g. "Person Ada Lovelace was removed" instead of the generic default.
+ */
+interface FieldArrayAnnounceInfo {
+  /** The index of the row. */
+  index: number;
+  /**
+   * The element of the row, for anything `getFieldValue` doesn't cover. For `rowRemoved` it is
+   * already detached from the document, but still readable.
+   */
+  rowEl: HTMLElement;
+  /** Reads the value of a field in this row by its bare name, `'firstName'` and not `people[2][firstName]`. */
+  getFieldValue: (name: string) => FieldValue;
+}
+/** A screen reader announcement: a string, `false` to stay silent, or a callback that builds one from the row. */
+type FieldArrayAnnounceTranslation = string | false | ((info: FieldArrayAnnounceInfo) => string | false);
+interface FieldArrayProps {
+  /** The unique identifier of the field array. */
+  id: string;
+  /** The name the rows are nested under, e.g. `people` for `people[0][firstName]`. */
+  name: string;
+  /**
+   * The number of rows the server rendered. It sets the state of the triggers before hydration,
+   * once the client runs it counts the rows in the DOM instead.
+   */
+  itemCount?: number;
+  /**
+   * The fewest rows allowed. At this many, `remove()` and the remove triggers do nothing and the
+   * remove triggers are disabled.
+   * @default 0
+   */
+  minItems?: number;
+  /**
+   * The most rows allowed. At this many, `append()` and the add trigger do nothing and the add
+   * trigger is disabled.
+   */
+  maxItems?: number;
+  /**
+   * The screen reader announcements of an added and a removed row. In a string, `%number%` is
+   * replaced with the 1-based position of the row, e.g. `Row %number% removed.`. A callback builds
+   * the message from the data of the row, and may use `%number%` in what it returns.
+   */
+  translations?: {
+    rowAdded?: FieldArrayAnnounceTranslation;
+    rowRemoved?: FieldArrayAnnounceTranslation;
+  };
+  /**
+   * Called after a row was added by the add trigger, with its index and the client names of the
+   * components inside it, e.g. `['field', 'input']`. Call their `mountAll()` here: the field
+   * array doesn't know what the template of a row contains.
+   */
+  onItemAdded?: (detail: {
+    index: number;
+    componentNames: string[];
+  }) => void;
+  /**
+   * Called after a row was removed by its remove trigger, with the index it had. The later rows
+   * have already moved up by then.
+   */
+  onItemRemoved?: (detail: {
+    index: number;
+  }) => void;
+}
+interface FieldArrayApiActions {
+  /** The rows that currently exist, by index. */
+  getRows(): {
+    index: number;
+  }[];
+  /** Whether `append()` would currently add a row, i.e. `maxItems` hasn't been reached. */
+  canAppend(): boolean;
+  /** Whether `remove()` would currently remove a row, i.e. more than `minItems` remain. */
+  canRemove(): boolean;
+  /** Adds a row, if `maxItems` allows it. */
+  append(): void;
+  /** Removes the row at `index`, if `minItems` allows it. */
+  remove(index: number): void;
+}
+interface FieldArrayApiProps {
+  getAddTriggerProps(): PropTypes['button'];
+  getRemoveTriggerProps(index: number): PropTypes['button'];
+}
+interface FieldArrayApi extends FieldArrayApiActions, FieldArrayApiProps {}
+//#endregion
+//#region Resources/Private/Primitives/FieldArray/FieldArray.d.ts
+declare class FieldArray extends Component<FieldArrayProps, FieldArrayApi> {
+  static componentName: string;
+  initMachine(props: FieldArrayProps): Machine$1<any>;
+  initApi(): FieldArrayApi;
+  render(): void;
+}
+//#endregion
+export { FieldArray, type FieldArrayAnnounceInfo, type FieldArrayAnnounceTranslation, type FieldArrayApi, type FieldArrayProps };

package/dist/field-array.js

@@ -0,0 +1,223 @@
+import { B as stringifyFieldPathAsBrackets, F as renameFieldMachineForForm, J as destroyComponentsWithin, R as parseFieldPath, a as normalizeProps, at as Machine$1, g as getFieldValueFromContainer, n as Template, rt as Component } from "./Client-HrMIqv7d.js";
+import { nextTick } from "@zag-js/dom-query";
+import { createSplitProps } from "@zag-js/utils";
+import { createAnatomy } from "@zag-js/anatomy";
+import { createMachine } from "@zag-js/core";
+import { createProps } from "@zag-js/types";
+import { createLiveRegion } from "@zag-js/live-region";
+
+//#region Resources/Private/Primitives/FieldArray/src/field-array.anatomy.ts
+const anatomy = createAnatomy("field-array").parts("addTrigger", "removeTrigger");
+const parts = anatomy.build();
+
+//#endregion
+//#region Resources/Private/Primitives/FieldArray/src/field-array.connect.ts
+/**
+* Builds `FieldArray`'s API. Deliberately takes the `Component` instance itself, not a Zag
+* `service` the way `Field`/`Form`'s own `connect()` do - their API is "read context, return a
+* plain object", but `append`/`remove` here are DOM mutations over an open-ended row collection,
+* which needs `Component`-level helpers (`hydrator`/`refresh`) that a
+* Zag service's `context`/`scope` alone don't provide. Still takes `normalize` like every other
+* `connect()` though, so `getAddTriggerProps`/`getRemoveTriggerProps` stay framework-portable and
+* carry the same anatomy attrs every other primitive's parts do.
+*/
+function connect(component, normalize) {
+	const actions = {
+		getRows: () => getRows(component),
+		canAppend: () => canAppend(component),
+		canRemove: () => canRemove(component),
+		append: () => append(component),
+		remove: (index) => remove(component, index)
+	};
+	const props = {
+		getAddTriggerProps: () => {
+			const disabled = !actions.canAppend();
+			return normalize.button({
+				...parts.addTrigger.attrs(component.machine.scope.id),
+				onClick: () => actions.append(),
+				"aria-disabled": disabled ? true : void 0,
+				"data-disabled": disabled ? true : void 0
+			});
+		},
+		getRemoveTriggerProps: (index) => {
+			const disabled = !actions.canRemove();
+			return normalize.button({
+				...parts.removeTrigger.attrs(component.machine.scope.id),
+				onClick: () => actions.remove(index),
+				"aria-disabled": disabled ? true : void 0,
+				"data-disabled": disabled ? true : void 0,
+				/** The index of the row the trigger removes. */
+				"data-value": index
+			});
+		}
+	};
+	return {
+		...actions,
+		...props
+	};
+}
+function getRows(component) {
+	return component.hydrator.queryAll("item").map((el) => ({ index: Number(el.dataset.value) })).filter(({ index }) => !Number.isNaN(index)).sort((a, b) => a.index - b.index);
+}
+function canAppend(component) {
+	const maxItems = component.machine.prop("maxItems");
+	return maxItems == null || getRows(component).length < maxItems;
+}
+function canRemove(component) {
+	const minItems = component.machine.prop("minItems") ?? 0;
+	return getRows(component).length > minItems;
+}
+/**
+* Clones the `itemTemplate` stencil for a new row and appends it to `itemGroup` - `Template`'s own
+* `{value}` option (via `ComponentHydrator.restampValue`) prepares any nested root components the
+* row happens to compose (Field/Input/...) too, but doesn't construct them (see `restampValue`'s
+* own docblock for why that step can't happen here) - `onItemAdded` carries `clone.componentNames`,
+* so consumer code can call `mountAll()` again for each of them.
+*/
+function append(component) {
+	if (!canAppend(component)) return;
+	const itemGroupEl = component.hydrator.query("itemGroup");
+	if (!itemGroupEl) return;
+	const index = nextIndex(component);
+	const clone = new Template(component.hydrator, "itemTemplate", { value: String(index) });
+	itemGroupEl.appendChild(clone);
+	component.machine.prop("onItemAdded")?.({
+		index,
+		componentNames: clone.componentNames
+	});
+	announce(component, "rowAdded", index, clone.root);
+	component.refresh();
+}
+/**
+* Removes a row and shifts every later row's index (and its nested fields' `name`s) down by
+* one, via `renameFieldMachineForForm` - the same mechanism `Form.api.renameField` itself uses,
+* which keeps recurring-field rows contiguously indexed without touching any field's value/
+* touched/dirty/error state.
+*/
+function remove(component, index) {
+	if (!canRemove(component)) return;
+	const rowEl = component.hydrator.queryAll("item").find((el) => el.dataset.value === String(index));
+	if (!rowEl) return;
+	const focusTargetEl = findFocusTargetAfterRemoval(component, rowEl);
+	announce(component, "rowRemoved", index, rowEl);
+	destroyComponentsWithin(rowEl);
+	rowEl.remove();
+	reindexRowsAfter(component, index);
+	component.machine.prop("onItemRemoved")?.({ index });
+	component.refresh();
+	nextTick(() => focusTargetEl?.focus());
+}
+/**
+* Resolves what should receive focus once `rowEl` is gone, so keyboard/screen-reader users
+* don't lose focus to `<body>` when the element they were just interacting with (its own
+* `removeTrigger`) disappears: the next row's `removeTrigger`, or the previous row's if the
+* removed row was last, or `addTrigger` if no rows remain. Resolved to a real element
+* *before* removal, so the reference stays valid through the DOM mutation and reindexing that
+* follow - `queryAll('item')` already reflects visual/DOM order, so this doesn't need to
+* reason about numeric row indices at all.
+*/
+function findFocusTargetAfterRemoval(component, rowEl) {
+	const rows = component.hydrator.queryAll("item");
+	const removedPosition = rows.indexOf(rowEl);
+	const siblingRowEl = rows[removedPosition + 1] ?? rows[removedPosition - 1];
+	return siblingRowEl && component.hydrator.query("removeTrigger", siblingRowEl) || component.hydrator.query("addTrigger");
+}
+function nextIndex(component) {
+	const rows = getRows(component);
+	return rows.length > 0 ? Math.max(...rows.map((row) => row.index)) + 1 : 0;
+}
+function reindexRowsAfter(component, removedIndex) {
+	const rowsToShift = getRows(component).filter(({ index }) => index > removedIndex);
+	for (const { index } of rowsToShift) {
+		const rowEl = component.hydrator.queryAll("item").find((el) => el.dataset.value === String(index));
+		if (!rowEl) continue;
+		const newIndex = index - 1;
+		rowEl.querySelectorAll("[data-field-root]").forEach((fieldRootEl) => {
+			const oldName = fieldRootEl.dataset.name;
+			if (!oldName) return;
+			renameFieldMachineForForm(fieldRootEl, oldName, oldName.replace(`[${index}]`, `[${newIndex}]`));
+		});
+		component.hydrator.renameValue(rowEl, String(newIndex));
+	}
+}
+function announce(component, translationKey, index, rowEl) {
+	const entry = component.machine.prop("translations")?.[translationKey];
+	const text = typeof entry === "function" ? entry({
+		index,
+		rowEl,
+		getFieldValue: (name) => getRowFieldValue(component, rowEl, index, name)
+	}) : entry;
+	if (typeof text !== "string" || text === "") return;
+	component.machine.refs.get("liveRegion")?.announce(text.replaceAll("%number%", String(index + 1)));
+}
+function getRowFieldValue(component, rowEl, index, name) {
+	return getFieldValueFromContainer(rowEl, stringifyFieldPathAsBrackets([
+		component.machine.prop("name"),
+		index,
+		...parseFieldPath(name)
+	]));
+}
+
+//#endregion
+//#region Resources/Private/Primitives/FieldArray/src/field-array.machine.ts
+const machine = createMachine({
+	initialState() {
+		return "idle";
+	},
+	context() {
+		return {};
+	},
+	refs() {
+		return { liveRegion: null };
+	},
+	effects: ["manageLiveRegion"],
+	states: { idle: {} },
+	implementations: { effects: { manageLiveRegion({ refs }) {
+		const liveRegion = createLiveRegion({ level: "polite" });
+		refs.set("liveRegion", liveRegion);
+		return () => {
+			liveRegion.destroy();
+		};
+	} } }
+});
+
+//#endregion
+//#region Resources/Private/Primitives/FieldArray/src/field-array.props.ts
+const props = createProps()([
+	"id",
+	"name",
+	"itemCount",
+	"minItems",
+	"maxItems",
+	"translations",
+	"onItemAdded",
+	"onItemRemoved"
+]);
+const splitProps = createSplitProps(props);
+
+//#endregion
+//#region Resources/Private/Primitives/FieldArray/FieldArray.ts
+var FieldArray = class extends Component {
+	static componentName = "fieldArray";
+	initMachine(props) {
+		const [machineProps] = splitProps(props);
+		return new Machine$1(machine, machineProps);
+	}
+	initApi() {
+		return connect(this, normalizeProps);
+	}
+	render() {
+		const addTriggerEl = this.hydrator.query("addTrigger");
+		if (addTriggerEl) this.spreadProps(addTriggerEl, this.api.getAddTriggerProps());
+		for (const removeTriggerEl of this.hydrator.queryAll("removeTrigger")) {
+			const index = Number(removeTriggerEl.dataset.value);
+			if (Number.isNaN(index)) continue;
+			this.spreadProps(removeTriggerEl, this.api.getRemoveTriggerProps(index));
+		}
+		const emptyStateEl = this.hydrator.query("emptyState");
+		if (emptyStateEl) emptyStateEl.hidden = this.hydrator.queryAll("item").length > 0;
+	}
+};
+
+//#endregion
+export { FieldArray };

package/dist/field.d.ts

@@ -1,60 +1,36 @@
-import { a as Machine, f as Component } from "./index-B8JCdyld.js";
-import { n as FormMachine } from "./form.registry-Cb8Pvoe8.js";
-import { EventObject } from "@zag-js/core";
-import { PropTypes } from "@zag-js/types";
+import { C as FieldValue, F as FieldSchema, P as FieldProps, S as FieldHandle, b as FieldClientApi, c as Machine, x as FieldDependencyChangeDetail, z as Component } from "./index-B06gIN_k.js";
 
-//#region Resources/Private/Primitives/Field/src/field.types.d.ts
-interface FieldProps {
-  id: string;
-  name: string;
-  invalid?: boolean;
-  required?: boolean;
-  disabled?: boolean;
-  readOnly?: boolean;
-}
-interface FieldSchema {
-  props: FieldProps;
-  context: {
-    invalid: boolean;
-    required: boolean;
-    disabled: boolean;
-    readOnly: boolean;
-    formMachine: FormMachine | null;
-    describeIds: string | undefined;
-    hasDescription: boolean;
-  };
-  computed: {
-    errors: string[];
-  };
-  state: 'ready';
-  event: EventObject;
-  action: string;
-  effect: string;
-}
-interface FieldApi {
-  getFormMachine(): FieldSchema['context']['formMachine'];
-  invalid: boolean;
-  errors: string[];
-  name: string;
-  disabled: boolean;
-  required: boolean;
-  readOnly: boolean;
-  getRootProps(): PropTypes['element'];
-  getLabelProps(): PropTypes['label'];
-  getControlProps(): PropTypes['element'];
-  getErrorProps(): PropTypes['element'];
-  getDescriptionProps(): PropTypes['element'];
-  getErrorText(): string | null;
-}
-//#endregion
 //#region Resources/Private/Primitives/Field/Field.d.ts
-declare class Field extends Component<FieldProps, FieldApi> {
-  static name: string;
-  private subscribedToForm;
+declare class Field extends Component<FieldProps, FieldClientApi> {
+  static componentName: string;
+  /** The `validate` a consumer set; the machine itself runs {@link validate}, which adds the form's. */
+  private ownValidate;
+  private cleanups;
+  private cancelDeferredRender;
+  /** The base class types its machine as `Machine<any>`. */
+  private get fieldMachine();
   initMachine(props: FieldProps): Machine<FieldSchema>;
-  initApi(): FieldApi;
-  subscribeToFormMachine(): void;
+  initApi(): FieldClientApi;
+  init(): void;
+  updateProps(newProps: Partial<FieldProps>): void;
   render(): void;
+  destroy(): void;
+  /**
+   * Zag's props differ per element only in `readOnly`, and the control part is the one place a
+   * bare native element is wired up by the field itself (primitives bring their own control).
+   */
+  private getControlProps;
+  /** What the machine validates with: the form's messages for this field, then the consumer's own. */
+  private validate;
+  /**
+   * `listenTo`: when a named sibling field in the same form changes value, this field announces
+   * `fluid-primitives:field:dependencychange` for consumer DOM reactions and treats it like a
+   * change of its own, so it revalidates under the same rules as when its user types.
+   *
+   * A sibling's registration may come later than this field's (the form can hydrate after its
+   * fields), so subscribing is retried whenever a form registers, until every name resolved.
+   */
+  private listenToDependencies;
 }
 //#endregion
-export { Field };
+export { Field, type FieldClientApi, type FieldDependencyChangeDetail, type FieldHandle, type FieldProps, type FieldValue };