@vtex/faststore 0.0.5 → 0.0.6

package/dist/matter/client-profile-form/client-profile-fieldset.js

@@ -0,0 +1,488 @@
+"use client";
+import { defineComponent } from "../../core/dist/define-component.js";
+import "../../core/dist/index.js";
+import { Field, FieldBinding, FieldsetFieldContext, useFieldsetField, useFieldsetFieldNames, useNoAncestorFieldset } from "../../particles/field/field.js";
+import { useActionsOverride } from "../../sdk/actions/actions-override-context.js";
+import { useDataOverride } from "../../sdk/data/data-override-context.js";
+import { useSession } from "../session/session.js";
+import { Fieldset } from "../../particles/fieldset/fieldset.js";
+import { DOCUMENTS, DocumentField, isSupportedDocumentType } from "../../particles/document-field/document-field.js";
+import { useFormRegistry } from "../../particles/form/form.js";
+import { useEntityDataResolved } from "../../sdk/data/entity-resolution-context.js";
+import { useReactiveDataSettled } from "../../sdk/data/use-reactive-data-settled.js";
+import { PhoneField, toE164 } from "../../particles/phone-field/phone-field.js";
+import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState } from "react";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { useFormContext } from "react-hook-form";
+//#region src/matter/client-profile-form/client-profile-fieldset.tsx
+/**
+* `ClientProfileFieldset` — the composable, one-Save write of the `ClientProfile` sibling entity
+* (RFC: Composable Entity Forms, `Proposal > Design > The fieldset`). It registers itself with the
+* enclosing `FormRoot` under the `clientProfile` namespace and dispatches
+* `$actions.identity.clientProfileUpdate` for its own submit slot; it renders no `<form>` of its own.
+*
+* The four controls below are the smallest placeable unit: each calls `useFieldsetField` for its full
+* field name, renders a `FieldBinding` carrying the field's static facts, and — inside it — either the
+* default anatomy or the author's own children. No control's field contract carries a blocking
+* `RegisterOptions` key (no `required`, `min`, `max`, `minLength`, `maxLength`, `pattern`); requiredness
+* on the phone control rides on its own `requirement` prop instead, which only ever gates required
+* validation — a field the store does not want is omitted from the page, not switched off by a prop.
+*
+* The fieldset's context name is `client-profile-fieldset`, not `client-profile`: the shipped
+* `ClientProfilePhoneControl` (`matter/client-profile/client-profile.tsx`) already requires
+* `client-profile` and writes on blur, so reusing that name here would let an on-blur control compile
+* inside this batched fieldset and write immediately. `ClientProfileFieldsetPhoneControl` carries the
+* same container prefix as the context it requires, naming the collision rather than hiding it.
+*/
+const fragment = `
+  fragment ClientProfileFieldsetData on Query {
+    clientProfile {
+      __typename
+      id
+      firstName
+      lastName
+      phone
+      document
+    }
+  }
+`;
+/** No control publishes a rule today — a blocking `RegisterOptions` key would reopen the same submit
+* block for a read-only session (Decision 6): `readOnly` disables a control's rendered `<input>` via a
+* plain HTML attribute, never react-hook-form's own `disabled` registration option (`field.tsx`'s
+* `useController` call takes no `disabled`), so a required field would stay fully registered and
+* validated while the shopper has no way to focus or edit it. Kept as a stable empty object so the
+* context value's identity does not churn on every render. */
+const NO_RULES = {};
+/**
+* Rows `ClientProfileFieldsetSkeleton` draws when nobody says otherwise: one per control in the full
+* anatomy — first name, last name, phone, document. It is a default and not a derivation, because
+* the composed children are opaque here. A page that composes fewer sets `skeletonCount` to what it
+* composed, or the form jumps by the difference when the controls take the skeleton's place.
+*/
+const CLIENT_PROFILE_SKELETON_ROWS = 4;
+const CLIENT_PROFILE_FIELDSET_UNSET = Symbol("ClientProfileFieldsetContextUnset");
+const ClientProfileFieldsetContext = createContext(CLIENT_PROFILE_FIELDSET_UNSET);
+function useClientProfileFieldsetContext() {
+	const ctx = useContext(ClientProfileFieldsetContext);
+	if (ctx === CLIENT_PROFILE_FIELDSET_UNSET) throw new Error("ClientProfileFieldset controls must be used inside ClientProfileFieldset.");
+	return ctx;
+}
+const ClientProfileFieldsetDefinition = defineComponent({
+	name: "ClientProfileFieldset",
+	importPath: "@vtex/faststore/components",
+	component: ClientProfileFieldset,
+	fragment,
+	fetchStrategy: "reactive",
+	skeleton: ClientProfileFieldsetSkeleton,
+	requiresContext: ["form", "session"],
+	providesContext: "client-profile-fieldset",
+	actions: { identity: ["clientProfileUpdate"] },
+	editor: {
+		label: "Client Profile Fieldset",
+		category: "identity"
+	},
+	schema: {
+		country: {
+			type: "string",
+			default: "US",
+			label: "Phone country (US or BR)"
+		},
+		documentType: {
+			type: "string",
+			label: "Document type (e.g. CPF)"
+		},
+		skeletonCount: {
+			type: "number",
+			default: 4,
+			label: "Skeleton rows"
+		},
+		loadingLabel: {
+			type: "string",
+			default: "Loading your details",
+			label: "Loading announcement"
+		},
+		loadedLabel: {
+			type: "string",
+			default: "Your details are ready",
+			label: "Loaded announcement"
+		},
+		groupLabel: {
+			type: "string",
+			default: "Your details",
+			label: "Accessible group name"
+		}
+	},
+	guideline: "Registers a batched write of the ClientProfile entity with the enclosing FormRoot; renders one Fieldset.Root and no <form>. Must be inside a FormRoot with a SessionRoot ancestor. Compose ClientProfileFirstNameControl / ClientProfileLastNameControl / ClientProfileFieldsetPhoneControl / ClientProfileDocumentControl as children, in any order. The controls mount only once the profile has resolved, with skeletonCount placeholder rows in their place until then — set it to the number of controls composed, or the form jumps by the difference. Style the announcement sr-only. Dispatches only the fields the shopper changed. groupLabel names the group as its accessible name; blank emits no aria-label, and a composed FieldsetLegend wins over it."
+});
+const ClientProfileFirstNameControlDefinition = defineComponent({
+	name: "ClientProfileFirstNameControl",
+	importPath: "@vtex/faststore/components",
+	component: ClientProfileFirstNameControl,
+	requiresContext: "client-profile-fieldset",
+	providesContext: "field",
+	editor: {
+		label: "Client Profile First Name Control",
+		category: "identity"
+	},
+	schema: {
+		label: {
+			type: "string",
+			label: "Label"
+		},
+		placeholder: {
+			type: "string",
+			label: "Placeholder"
+		}
+	},
+	guideline: "The bound first-name control; must be a descendant of ClientProfileFieldset. Renders Field.Root > Field.Label + Field.Control + Field.Error by default, or the composed children in the author's own order."
+});
+const ClientProfileLastNameControlDefinition = defineComponent({
+	name: "ClientProfileLastNameControl",
+	importPath: "@vtex/faststore/components",
+	component: ClientProfileLastNameControl,
+	requiresContext: "client-profile-fieldset",
+	providesContext: "field",
+	editor: {
+		label: "Client Profile Last Name Control",
+		category: "identity"
+	},
+	schema: {
+		label: {
+			type: "string",
+			label: "Label"
+		},
+		placeholder: {
+			type: "string",
+			label: "Placeholder"
+		}
+	},
+	guideline: "The bound last-name control; must be a descendant of ClientProfileFieldset. Renders Field.Root > Field.Label + Field.Control + Field.Error by default, or the composed children in the author's own order."
+});
+const ClientProfileFieldsetPhoneControlDefinition = defineComponent({
+	name: "ClientProfileFieldsetPhoneControl",
+	importPath: "@vtex/faststore/components",
+	component: ClientProfileFieldsetPhoneControl,
+	requiresContext: "client-profile-fieldset",
+	providesContext: ["field", "phone-field"],
+	editor: {
+		label: "Client Profile Fieldset Phone Control",
+		category: "identity"
+	},
+	schema: {
+		label: {
+			type: "string",
+			label: "Label"
+		},
+		placeholder: {
+			type: "string",
+			label: "Placeholder"
+		},
+		requirement: {
+			type: ["mandatory", "optional"],
+			label: "Requirement"
+		},
+		errorInvalid: {
+			type: "string",
+			label: "Invalid error message"
+		},
+		errorRequired: {
+			type: "string",
+			label: "Required error message"
+		}
+	},
+	guideline: "The bound phone control; must be a descendant of ClientProfileFieldset. Distinct from ClientProfilePhoneControl (matter/client-profile), which writes on blur and requires the client-profile context — the two cannot compile into each other's container. Composes the PhoneField particle: recomposable (RFC:503) — given children, they replace PhoneField's default Field.Label + PhoneFieldInput + Field.Error anatomy, in any order; childless keeps today's order. Its className styles PhoneField's own root, the node that lays out label, input and error — not the wrapper, which carries only the data-fs-client-profile-fieldset-field=\"phone\" styling hook. A store that does not want a phone field omits this element from the page: requirement only governs required validation, never visibility."
+});
+const ClientProfileDocumentControlDefinition = defineComponent({
+	name: "ClientProfileDocumentControl",
+	importPath: "@vtex/faststore/components",
+	component: ClientProfileDocumentControl,
+	requiresContext: "client-profile-fieldset",
+	providesContext: ["field", "document-field"],
+	editor: {
+		label: "Client Profile Document Control",
+		category: "identity"
+	},
+	schema: {
+		label: {
+			type: "string",
+			label: "Label"
+		},
+		placeholder: {
+			type: "string",
+			label: "Placeholder"
+		},
+		errorMessage: {
+			type: "string",
+			label: "Error message"
+		}
+	},
+	guideline: "The bound tax-document control; must be a descendant of ClientProfileFieldset. Renders nothing, and registers no field name, when the fieldset's documentType is unsupported. Composes the DocumentField particle: recomposable (RFC:503) — given children, they replace DocumentField's default Field.Label + DocumentFieldInput + Field.Error anatomy, in any order; childless keeps today's order."
+});
+/**
+* Registers a batched write of the `ClientProfile` entity with the enclosing `FormRoot`
+* (`registerFieldset`, namespace `clientProfile`) on mount, unconditionally — so this fieldset keeps its
+* original dispatch slot even while its own query is still resolving. Its children — the seed values and
+* the field-name registry its controls need — render only once the entity has resolved; until then the
+* `Fieldset.Root` carries `-pending` and renders `ClientProfileFieldsetSkeleton` (Decision 5).
+* `dispatch` and `toPayload` are `useCallback([])`-stable and read `$actions`/`country`/`documentType`
+* through a ref, so the registration effect runs exactly once per mount regardless of how often the
+* parent re-renders.
+*
+* "Resolved" is two conditions, because `$data` alone cannot answer it. Under the reactive runtime the
+* slice is defined from the first render — `useReactiveEntity` hands down `fallbackData` while the cache
+* read is incomplete — so an empty server answer looks exactly like a resolved one, and the controls
+* would mount and seed `''` before the shopper's real profile arrives. `useSeedAdoption` re-seeds a
+* clean field with `defaultValue` on every render, but once the field turns dirty no later seed
+* ever reaches it again: a shopper who starts typing before the real profile arrives locks that
+* empty seed in for good, and even a shopper who does not type sees the field flash from `''` to
+* the real data. `useReactiveDataSettled` supplies the missing half: the page query's own
+* in-flight state, latched so it only ever goes pending → settled. The `$data === undefined` half still
+* carries trees with no reactive root above them, where the slice arrives as a plain prop.
+*
+* Both ends of that wait are spoken: the fieldset carries `aria-busy` while it lasts and holds a polite
+* live region that announces `loadingLabel` and then `loadedLabel`. Style the region `sr-only` — it is
+* text meant for a screen reader, not for the page.
+*/
+function ClientProfileFieldset({ country = "US", documentType, skeletonCount = CLIENT_PROFILE_SKELETON_ROWS, loadingLabel = "Loading your details", loadedLabel = "Your details are ready", groupLabel = "Your details", className, children, $data: $dataProp, $actions: $actionsProp }) {
+	useNoAncestorFieldset("ClientProfileFieldset");
+	const $data = useDataOverride($dataProp);
+	const $actions = useActionsOverride($actionsProp);
+	const settled = useReactiveDataSettled();
+	const sliceResolved = useEntityDataResolved();
+	const resolved = settled && sliceResolved && $data !== void 0;
+	const { canEditData } = useSession();
+	const readOnly = !canEditData;
+	const { registerFieldset } = useFormRegistry();
+	const { getFieldState } = useFormContext();
+	const latest = useRef({
+		$actions,
+		country,
+		documentType,
+		readOnly,
+		getFieldState
+	});
+	useEffect(() => {
+		latest.current = {
+			$actions,
+			country,
+			documentType,
+			readOnly,
+			getFieldState
+		};
+	}, [
+		$actions,
+		country,
+		documentType,
+		readOnly,
+		getFieldState
+	]);
+	const { registry: fieldsetRegistry, getFieldNames } = useFieldsetFieldNames("clientProfile");
+	const dispatch = useCallback(async (payload) => {
+		if (latest.current.readOnly) throw new Error("ClientProfileFieldset cannot dispatch while the session is read-only.");
+		const update = latest.current.$actions?.identity?.clientProfileUpdate;
+		if (!update) throw new Error("ClientProfileFieldset requires $actions.identity.clientProfileUpdate.");
+		return update(payload);
+	}, []);
+	const toPayload = useCallback((values) => {
+		const { country: activeCountry, getFieldState } = latest.current;
+		const isDirty = (key) => getFieldState(`clientProfile.${key}`).isDirty;
+		const payload = {};
+		if ("firstName" in values && isDirty("firstName")) payload.firstName = String(values.firstName ?? "").trim();
+		if ("lastName" in values && isDirty("lastName")) payload.lastName = String(values.lastName ?? "").trim();
+		if ("phone" in values && isDirty("phone")) {
+			const raw = String(values.phone ?? "").trim();
+			payload.phone = raw ? toE164(raw, activeCountry) : "";
+		}
+		if ("document" in values && isDirty("document")) payload.document = String(values.document ?? "").replace(/\D/g, "");
+		return payload;
+	}, []);
+	useEffect(() => registerFieldset({
+		namespace: "clientProfile",
+		getFieldNames,
+		dispatch,
+		toPayload,
+		label: "client-profile"
+	}), [
+		registerFieldset,
+		getFieldNames,
+		dispatch,
+		toPayload
+	]);
+	const saved = useMemo(() => ({
+		firstName: $data?.firstName ?? "",
+		lastName: $data?.lastName ?? "",
+		phone: $data?.phone ?? "",
+		document: $data?.document ?? ""
+	}), [$data]);
+	const contextValue = useMemo(() => ({
+		namespace: "clientProfile",
+		saved,
+		readOnly,
+		country,
+		documentType,
+		rules: NO_RULES
+	}), [
+		saved,
+		readOnly,
+		country,
+		documentType
+	]);
+	const [announcement, setAnnouncement] = useState("");
+	const announced = resolved ? loadedLabel : loadingLabel;
+	useEffect(() => {
+		setAnnouncement(announced);
+	}, [announced]);
+	return /* @__PURE__ */ jsxs(Fieldset.Root, {
+		className,
+		disabled: readOnly,
+		"aria-busy": resolved ? void 0 : true,
+		...groupLabel?.trim() ? { "aria-label": groupLabel } : {},
+		"data-fs-client-profile-fieldset": "",
+		...resolved ? {} : { "data-fs-client-profile-fieldset-pending": "" },
+		...readOnly ? { "data-fs-client-profile-fieldset-readonly": "" } : {},
+		children: [resolved ? /* @__PURE__ */ jsx(FieldsetFieldContext.Provider, {
+			value: fieldsetRegistry,
+			children: /* @__PURE__ */ jsx(ClientProfileFieldsetContext.Provider, {
+				value: contextValue,
+				children
+			})
+		}) : /* @__PURE__ */ jsx(ClientProfileFieldsetSkeleton, { count: skeletonCount }), /* @__PURE__ */ jsx("output", {
+			"aria-live": "polite",
+			"data-fs-client-profile-fieldset-announcement": "",
+			children: announcement
+		})]
+	});
+}
+/**
+* The loading state of the fieldset, rendered in place of the controls until the entity resolves and
+* declared as the definition's `skeleton`. Purely visual: the wait is spoken by the fieldset's own live
+* region, so this is hidden from assistive technology rather than announced twice.
+*/
+function ClientProfileFieldsetSkeleton({ count = CLIENT_PROFILE_SKELETON_ROWS, className, ...props }) {
+	return /* @__PURE__ */ jsx("div", {
+		...props,
+		className,
+		"data-fs-client-profile-fieldset-skeleton": "",
+		"aria-hidden": "true",
+		children: Array.from({ length: count }, (_, i) => /* @__PURE__ */ jsx("span", { "data-fs-client-profile-fieldset-skeleton-field": "" }, i))
+	});
+}
+ClientProfileFieldset.Skeleton = ClientProfileFieldsetSkeleton;
+function ProfileTextControl({ fieldKey, attr, autoComplete, defaultLabel, label, placeholder, className, children }) {
+	const { namespace, saved, readOnly, rules } = useClientProfileFieldsetContext();
+	const name = useFieldsetField(namespace, fieldKey);
+	return /* @__PURE__ */ jsx(FieldBinding, {
+		name,
+		label: label ?? defaultLabel,
+		placeholder,
+		defaultValue: saved[fieldKey],
+		rule: rules[fieldKey],
+		disabled: readOnly,
+		autoComplete,
+		children: /* @__PURE__ */ jsx(Field.Root, {
+			className,
+			"data-fs-client-profile-fieldset-field": attr,
+			children: children ?? /* @__PURE__ */ jsxs(Fragment, { children: [
+				/* @__PURE__ */ jsx(Field.Label, {}),
+				/* @__PURE__ */ jsx(Field.Control, {}),
+				/* @__PURE__ */ jsx(Field.Error, {})
+			] })
+		})
+	});
+}
+function ClientProfileFirstNameControl({ label, placeholder, className, children }) {
+	return /* @__PURE__ */ jsx(ProfileTextControl, {
+		fieldKey: "firstName",
+		attr: "first-name",
+		autoComplete: "given-name",
+		defaultLabel: "First name",
+		label,
+		placeholder,
+		className,
+		children
+	});
+}
+function ClientProfileLastNameControl({ label, placeholder, className, children }) {
+	return /* @__PURE__ */ jsx(ProfileTextControl, {
+		fieldKey: "lastName",
+		attr: "last-name",
+		autoComplete: "family-name",
+		defaultLabel: "Last name",
+		label,
+		placeholder,
+		className,
+		children
+	});
+}
+/**
+* Composes `PhoneField` inside a `FieldBinding`, wrapped in a `data-fs-client-profile-fieldset-field="phone"`
+* node — the same styling hook attribute the text controls carry on their own `Field.Root`.
+* `useFieldsetField` runs unconditionally, before `requirement` is even read — there is no suppressed
+* state for this control to second-guess; `requirement` only ever raises the field to required,
+* and left unset it raises nothing.
+*/
+function ClientProfileFieldsetPhoneControl({ label, placeholder, requirement, errorInvalid, errorRequired, className, children }) {
+	const { namespace, saved, readOnly, rules, country } = useClientProfileFieldsetContext();
+	const name = useFieldsetField(namespace, "phone");
+	const binding = /* @__PURE__ */ jsx(FieldBinding, {
+		name,
+		label,
+		placeholder,
+		defaultValue: saved.phone,
+		rule: rules.phone,
+		disabled: readOnly,
+		children: /* @__PURE__ */ jsx(PhoneField, {
+			country,
+			requirement,
+			errorInvalid,
+			errorRequired,
+			className,
+			children
+		})
+	});
+	return /* @__PURE__ */ jsx("div", {
+		"data-fs-client-profile-fieldset-field": "phone",
+		children: binding
+	});
+}
+/**
+* `useFieldsetField` (through `useClientProfileFieldsetContext`'s namespace) lives only in this inner
+* component, mounted only once `ClientProfileDocumentControl` has already decided the document type is
+* supported. Splitting the decision from the registration this way (Decision 8) keeps a control that
+* renders nothing from registering a field name `FormClear` would otherwise dirty and dispatch.
+*/
+function ClientProfileDocumentControlInner({ documentType, label, placeholder, errorMessage, className, children }) {
+	const { namespace, saved, readOnly, rules } = useClientProfileFieldsetContext();
+	const name = useFieldsetField(namespace, "document");
+	return /* @__PURE__ */ jsx(FieldBinding, {
+		name,
+		label: label ?? DOCUMENTS[documentType].name,
+		placeholder,
+		defaultValue: saved.document,
+		rule: rules.document,
+		disabled: readOnly,
+		children: /* @__PURE__ */ jsx(DocumentField, {
+			documentType,
+			errorMessage,
+			className,
+			"data-fs-client-profile-fieldset-field": "document",
+			children
+		})
+	});
+}
+function ClientProfileDocumentControl({ label, placeholder, errorMessage, className, children }) {
+	const { documentType } = useClientProfileFieldsetContext();
+	if (!isSupportedDocumentType(documentType)) return null;
+	return /* @__PURE__ */ jsx(ClientProfileDocumentControlInner, {
+		documentType,
+		label,
+		placeholder,
+		errorMessage,
+		className,
+		children
+	});
+}
+//#endregion
+export { ClientProfileDocumentControl, ClientProfileDocumentControlDefinition, ClientProfileFieldset, ClientProfileFieldsetDefinition, ClientProfileFieldsetPhoneControl, ClientProfileFieldsetPhoneControlDefinition, ClientProfileFieldsetSkeleton, ClientProfileFirstNameControl, ClientProfileFirstNameControlDefinition, ClientProfileLastNameControl, ClientProfileLastNameControlDefinition };
+
+//# sourceMappingURL=client-profile-fieldset.js.map

package/dist/matter/client-profile-form/client-profile-fieldset.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-profile-fieldset.js","names":[],"sources":["../../../src/matter/client-profile-form/client-profile-fieldset.tsx"],"sourcesContent":["'use client';\n\nimport { defineComponent } from '@vtex/fs-core';\nimport {\n  type ComponentPropsWithRef,\n  createContext,\n  type ReactNode,\n  useCallback,\n  useContext,\n  useEffect,\n  useMemo,\n  useRef,\n  useState,\n} from 'react';\nimport { useFormContext } from 'react-hook-form';\nimport type { DocumentType } from '../../particles/document-field/document-field.js';\nimport { DOCUMENTS, DocumentField, isSupportedDocumentType } from '../../particles/document-field/document-field.js';\nimport type { FieldRule } from '../../particles/field/field.js';\nimport {\n  Field,\n  FieldBinding,\n  FieldsetFieldContext,\n  useFieldsetField,\n  useFieldsetFieldNames,\n  useNoAncestorFieldset,\n} from '../../particles/field/field.js';\nimport { Fieldset } from '../../particles/fieldset/fieldset.js';\nimport { useFormRegistry } from '../../particles/form/form.js';\nimport type { PhoneCountry } from '../../particles/phone-field/phone-field.js';\nimport { PhoneField, toE164 } from '../../particles/phone-field/phone-field.js';\nimport { useActionsOverride } from '../../sdk/actions/actions-override-context.js';\nimport type { ComponentActions } from '../../sdk/actions/types.js';\nimport { useDataOverride } from '../../sdk/data/data-override-context.js';\nimport { useEntityDataResolved } from '../../sdk/data/entity-resolution-context.js';\nimport { useReactiveDataSettled } from '../../sdk/data/use-reactive-data-settled.js';\nimport type { ClientProfileUpdateInput } from '../../sdk/identity/operations.js';\nimport { useSession } from '../session/session.js';\n\n/**\n * `ClientProfileFieldset` — the composable, one-Save write of the `ClientProfile` sibling entity\n * (RFC: Composable Entity Forms, `Proposal > Design > The fieldset`). It registers itself with the\n * enclosing `FormRoot` under the `clientProfile` namespace and dispatches\n * `$actions.identity.clientProfileUpdate` for its own submit slot; it renders no `<form>` of its own.\n *\n * The four controls below are the smallest placeable unit: each calls `useFieldsetField` for its full\n * field name, renders a `FieldBinding` carrying the field's static facts, and — inside it — either the\n * default anatomy or the author's own children. No control's field contract carries a blocking\n * `RegisterOptions` key (no `required`, `min`, `max`, `minLength`, `maxLength`, `pattern`); requiredness\n * on the phone control rides on its own `requirement` prop instead, which only ever gates required\n * validation — a field the store does not want is omitted from the page, not switched off by a prop.\n *\n * The fieldset's context name is `client-profile-fieldset`, not `client-profile`: the shipped\n * `ClientProfilePhoneControl` (`matter/client-profile/client-profile.tsx`) already requires\n * `client-profile` and writes on blur, so reusing that name here would let an on-blur control compile\n * inside this batched fieldset and write immediately. `ClientProfileFieldsetPhoneControl` carries the\n * same container prefix as the context it requires, naming the collision rather than hiding it.\n */\n\n// ---------------------------------------------------------------------------\n// GraphQL Fragment — colocated on the fieldset, its own data root\n// ---------------------------------------------------------------------------\n\nconst fragment = /* GraphQL */ `\n  fragment ClientProfileFieldsetData on Query {\n    clientProfile {\n      __typename\n      id\n      firstName\n      lastName\n      phone\n      document\n    }\n  }\n`;\n\n// ---------------------------------------------------------------------------\n// Types\n// ---------------------------------------------------------------------------\n\n/** The `$data` slice forwarded by the reactive runtime — the ClientProfile sibling entity, unwrapped. */\nexport type ClientProfileFieldsetData = {\n  firstName?: string | null;\n  lastName?: string | null;\n  phone?: string | null;\n  document?: string | null;\n} | null;\n\n/** The four keys this fieldset registers under its namespace. */\ntype ProfileFieldKey = 'firstName' | 'lastName' | 'phone' | 'document';\n\n/** What the fieldset publishes to its controls. Carries no live value — react-hook-form owns those. */\ntype ClientProfileFieldsetContextValue = Readonly<{\n  namespace: 'clientProfile';\n  /** Seeds, resolved from `$data`. Empty string, never null, so a control never seeds `undefined`. */\n  saved: Readonly<Record<ProfileFieldKey, string>>;\n  /** True when the session reports `canEditData: false`. */\n  readOnly: boolean;\n  /** Phone mask/validation country, from the fieldset's own prop. */\n  country: PhoneCountry;\n  /** Locale document type; the document control renders only when supported. */\n  documentType: string | undefined;\n  /** The fieldset's own validation rules, per key. Present and empty today (Decision 6). */\n  rules: Readonly<Partial<Record<ProfileFieldKey, FieldRule>>>;\n}>;\n\n/** No control publishes a rule today — a blocking `RegisterOptions` key would reopen the same submit\n * block for a read-only session (Decision 6): `readOnly` disables a control's rendered `<input>` via a\n * plain HTML attribute, never react-hook-form's own `disabled` registration option (`field.tsx`'s\n * `useController` call takes no `disabled`), so a required field would stay fully registered and\n * validated while the shopper has no way to focus or edit it. Kept as a stable empty object so the\n * context value's identity does not churn on every render. */\nconst NO_RULES: Readonly<Partial<Record<ProfileFieldKey, FieldRule>>> = {};\n\n/**\n * Rows `ClientProfileFieldsetSkeleton` draws when nobody says otherwise: one per control in the full\n * anatomy — first name, last name, phone, document. It is a default and not a derivation, because\n * the composed children are opaque here. A page that composes fewer sets `skeletonCount` to what it\n * composed, or the form jumps by the difference when the controls take the skeleton's place.\n */\nconst CLIENT_PROFILE_SKELETON_ROWS = 4;\n\nconst CLIENT_PROFILE_FIELDSET_UNSET = Symbol('ClientProfileFieldsetContextUnset');\n\nconst ClientProfileFieldsetContext = createContext<\n  ClientProfileFieldsetContextValue | typeof CLIENT_PROFILE_FIELDSET_UNSET\n>(CLIENT_PROFILE_FIELDSET_UNSET);\n\nfunction useClientProfileFieldsetContext(): ClientProfileFieldsetContextValue {\n  const ctx = useContext(ClientProfileFieldsetContext);\n  if (ctx === CLIENT_PROFILE_FIELDSET_UNSET) {\n    throw new Error('ClientProfileFieldset controls must be used inside ClientProfileFieldset.');\n  }\n  return ctx;\n}\n\n// ---------------------------------------------------------------------------\n// Props\n// ---------------------------------------------------------------------------\n\nexport type ClientProfileFieldsetProps = {\n  /** Phone mask/validation country, provided to the phone control via context. */\n  country?: PhoneCountry;\n  /** Locale document type; the document control renders only when supported. */\n  documentType?: string;\n  /** Placeholder rows the loading skeleton draws. Set it to the number of controls composed here. */\n  skeletonCount?: number;\n  /** Announced politely while the profile resolves. Blank means no announcement. */\n  loadingLabel?: string;\n  /** Announced politely once the controls mount. Blank means no announcement. */\n  loadedLabel?: string;\n  /** Accessible name of the `<fieldset>` group. Blank means no name is exposed. */\n  groupLabel?: string;\n  className?: string;\n  children?: ReactNode;\n  /** `ClientProfileFieldsetData` slice forwarded by the reactive runtime. */\n  $data?: ClientProfileFieldsetData;\n  /** Compiler-injected; carries `identity.clientProfileUpdate`. */\n  $actions?: ComponentActions;\n};\n\ntype ProfileTextControlProps = { label?: string; placeholder?: string; className?: string; children?: ReactNode };\n\nexport type ClientProfileFirstNameControlProps = ProfileTextControlProps;\nexport type ClientProfileLastNameControlProps = ProfileTextControlProps;\n\nexport type ClientProfileFieldsetPhoneControlProps = {\n  label?: string;\n  placeholder?: string;\n  /**\n   * Raises the field to required. The composite owns it; the contract carries no rule (Decision 6),\n   * so here the raise is the whole of the resolution. Unset is no opinion, which leaves the phone\n   * optional.\n   */\n  requirement?: 'mandatory' | 'optional';\n  errorInvalid?: string;\n  errorRequired?: string;\n  className?: string;\n  /** Given, replaces PhoneField's default Field.Label + PhoneFieldInput + Field.Error anatomy. */\n  children?: ReactNode;\n};\n\nexport type ClientProfileDocumentControlProps = {\n  label?: string;\n  placeholder?: string;\n  errorMessage?: string;\n  className?: string;\n  /** Given, replaces DocumentField's default Field.Label + DocumentFieldInput + Field.Error anatomy. */\n  children?: ReactNode;\n};\n\n// ---------------------------------------------------------------------------\n// Definitions\n// ---------------------------------------------------------------------------\n\nexport const ClientProfileFieldsetDefinition = defineComponent<ClientProfileFieldsetProps>({\n  name: 'ClientProfileFieldset',\n  importPath: '@vtex/faststore/components',\n  component: ClientProfileFieldset,\n  fragment,\n  fetchStrategy: 'reactive',\n  skeleton: ClientProfileFieldsetSkeleton,\n  requiresContext: ['form', 'session'],\n  providesContext: 'client-profile-fieldset',\n  actions: { identity: ['clientProfileUpdate'] },\n  editor: { label: 'Client Profile Fieldset', category: 'identity' },\n  schema: {\n    country: { type: 'string', default: 'US', label: 'Phone country (US or BR)' },\n    documentType: { type: 'string', label: 'Document type (e.g. CPF)' },\n    skeletonCount: { type: 'number', default: 4, label: 'Skeleton rows' },\n    loadingLabel: { type: 'string', default: 'Loading your details', label: 'Loading announcement' },\n    loadedLabel: { type: 'string', default: 'Your details are ready', label: 'Loaded announcement' },\n    groupLabel: { type: 'string', default: 'Your details', label: 'Accessible group name' },\n  },\n  guideline:\n    'Registers a batched write of the ClientProfile entity with the enclosing FormRoot; renders one Fieldset.Root and no <form>. Must be inside a FormRoot with a SessionRoot ancestor. Compose ClientProfileFirstNameControl / ClientProfileLastNameControl / ClientProfileFieldsetPhoneControl / ClientProfileDocumentControl as children, in any order. The controls mount only once the profile has resolved, with skeletonCount placeholder rows in their place until then — set it to the number of controls composed, or the form jumps by the difference. Style the announcement sr-only. Dispatches only the fields the shopper changed. groupLabel names the group as its accessible name; blank emits no aria-label, and a composed FieldsetLegend wins over it.',\n});\n\nexport const ClientProfileFirstNameControlDefinition = defineComponent<ClientProfileFirstNameControlProps>({\n  name: 'ClientProfileFirstNameControl',\n  importPath: '@vtex/faststore/components',\n  component: ClientProfileFirstNameControl,\n  requiresContext: 'client-profile-fieldset',\n  providesContext: 'field',\n  editor: { label: 'Client Profile First Name Control', category: 'identity' },\n  schema: {\n    // No default (Decision 1): absence means the platform's value, applied at render time by\n    // the control itself, not baked into the schema.\n    label: { type: 'string', label: 'Label' },\n    placeholder: { type: 'string', label: 'Placeholder' },\n  },\n  guideline:\n    \"The bound first-name control; must be a descendant of ClientProfileFieldset. Renders Field.Root > Field.Label + Field.Control + Field.Error by default, or the composed children in the author's own order.\",\n});\n\nexport const ClientProfileLastNameControlDefinition = defineComponent<ClientProfileLastNameControlProps>({\n  name: 'ClientProfileLastNameControl',\n  importPath: '@vtex/faststore/components',\n  component: ClientProfileLastNameControl,\n  requiresContext: 'client-profile-fieldset',\n  providesContext: 'field',\n  editor: { label: 'Client Profile Last Name Control', category: 'identity' },\n  schema: {\n    // No default (Decision 1): absence means the platform's value, applied at render time by\n    // the control itself, not baked into the schema.\n    label: { type: 'string', label: 'Label' },\n    placeholder: { type: 'string', label: 'Placeholder' },\n  },\n  guideline:\n    \"The bound last-name control; must be a descendant of ClientProfileFieldset. Renders Field.Root > Field.Label + Field.Control + Field.Error by default, or the composed children in the author's own order.\",\n});\n\nexport const ClientProfileFieldsetPhoneControlDefinition = defineComponent<ClientProfileFieldsetPhoneControlProps>({\n  name: 'ClientProfileFieldsetPhoneControl',\n  importPath: '@vtex/faststore/components',\n  component: ClientProfileFieldsetPhoneControl,\n  requiresContext: 'client-profile-fieldset',\n  // Provides both names (mirrors shipping-address.tsx:595's Decision 7): 'field' is what every\n  // fieldset Control declares (RFC:503), but this control also composes PhoneField, whose\n  // PhoneFieldInput part requires 'phone-field' — a page composing\n  // ClientProfileFieldsetPhoneControl > PhoneFieldInput would otherwise fail the build with a\n  // context-constraint violation, since PhoneField itself (the only 'phone-field' provider) never\n  // appears in the page schema (finding F1).\n  providesContext: ['field', 'phone-field'],\n  editor: { label: 'Client Profile Fieldset Phone Control', category: 'identity' },\n  schema: {\n    // No default (Decision 1): absence means the platform's value, applied at render time by\n    // the control itself, not baked into the schema.\n    label: { type: 'string', label: 'Label' },\n    placeholder: { type: 'string', label: 'Placeholder' },\n    // No default: an unset requirement is no opinion, not a raise to mandatory.\n    requirement: { type: ['mandatory', 'optional'] as const, label: 'Requirement' },\n    // No default (Decision 1): absence means the platform's value, applied at render time by\n    // the control itself, not baked into the schema.\n    errorInvalid: { type: 'string', label: 'Invalid error message' },\n    errorRequired: { type: 'string', label: 'Required error message' },\n  },\n  guideline:\n    \"The bound phone control; must be a descendant of ClientProfileFieldset. Distinct from ClientProfilePhoneControl (matter/client-profile), which writes on blur and requires the client-profile context — the two cannot compile into each other's container. Composes the PhoneField particle: recomposable (RFC:503) — given children, they replace PhoneField's default Field.Label + PhoneFieldInput + Field.Error anatomy, in any order; childless keeps today's order. Its className styles PhoneField's own root, the node that lays out label, input and error — not the wrapper, which carries only the data-fs-client-profile-fieldset-field=\\\"phone\\\" styling hook. A store that does not want a phone field omits this element from the page: requirement only governs required validation, never visibility.\",\n});\n\nexport const ClientProfileDocumentControlDefinition = defineComponent<ClientProfileDocumentControlProps>({\n  name: 'ClientProfileDocumentControl',\n  importPath: '@vtex/faststore/components',\n  component: ClientProfileDocumentControl,\n  requiresContext: 'client-profile-fieldset',\n  // Provides both names, same reasoning as ClientProfileFieldsetPhoneControlDefinition above: this\n  // control composes DocumentField, whose DocumentFieldInput part requires 'document-field' — a page\n  // composing ClientProfileDocumentControl > DocumentFieldInput would otherwise fail the build\n  // (finding F1).\n  providesContext: ['field', 'document-field'],\n  editor: { label: 'Client Profile Document Control', category: 'identity' },\n  schema: {\n    // No default (Decision 1): absence means the platform's value, applied at render time by\n    // the control itself, not baked into the schema.\n    label: { type: 'string', label: 'Label' },\n    placeholder: { type: 'string', label: 'Placeholder' },\n    errorMessage: { type: 'string', label: 'Error message' },\n  },\n  guideline:\n    \"The bound tax-document control; must be a descendant of ClientProfileFieldset. Renders nothing, and registers no field name, when the fieldset's documentType is unsupported. Composes the DocumentField particle: recomposable (RFC:503) — given children, they replace DocumentField's default Field.Label + DocumentFieldInput + Field.Error anatomy, in any order; childless keeps today's order.\",\n});\n\n// ---------------------------------------------------------------------------\n// Fieldset root\n// ---------------------------------------------------------------------------\n\n/**\n * Registers a batched write of the `ClientProfile` entity with the enclosing `FormRoot`\n * (`registerFieldset`, namespace `clientProfile`) on mount, unconditionally — so this fieldset keeps its\n * original dispatch slot even while its own query is still resolving. Its children — the seed values and\n * the field-name registry its controls need — render only once the entity has resolved; until then the\n * `Fieldset.Root` carries `-pending` and renders `ClientProfileFieldsetSkeleton` (Decision 5).\n * `dispatch` and `toPayload` are `useCallback([])`-stable and read `$actions`/`country`/`documentType`\n * through a ref, so the registration effect runs exactly once per mount regardless of how often the\n * parent re-renders.\n *\n * \"Resolved\" is two conditions, because `$data` alone cannot answer it. Under the reactive runtime the\n * slice is defined from the first render — `useReactiveEntity` hands down `fallbackData` while the cache\n * read is incomplete — so an empty server answer looks exactly like a resolved one, and the controls\n * would mount and seed `''` before the shopper's real profile arrives. `useSeedAdoption` re-seeds a\n * clean field with `defaultValue` on every render, but once the field turns dirty no later seed\n * ever reaches it again: a shopper who starts typing before the real profile arrives locks that\n * empty seed in for good, and even a shopper who does not type sees the field flash from `''` to\n * the real data. `useReactiveDataSettled` supplies the missing half: the page query's own\n * in-flight state, latched so it only ever goes pending → settled. The `$data === undefined` half still\n * carries trees with no reactive root above them, where the slice arrives as a plain prop.\n *\n * Both ends of that wait are spoken: the fieldset carries `aria-busy` while it lasts and holds a polite\n * live region that announces `loadingLabel` and then `loadedLabel`. Style the region `sr-only` — it is\n * text meant for a screen reader, not for the page.\n */\nexport function ClientProfileFieldset({\n  country = 'US',\n  documentType,\n  skeletonCount = CLIENT_PROFILE_SKELETON_ROWS,\n  loadingLabel = 'Loading your details',\n  loadedLabel = 'Your details are ready',\n  groupLabel = 'Your details',\n  className,\n  children,\n  $data: $dataProp,\n  $actions: $actionsProp,\n}: ClientProfileFieldsetProps) {\n  // Nesting fieldsets has no legitimate use: useFieldsetField resolves the *nearest*\n  // FieldsetFieldContext, not the one owning a control's actual namespace, so a control nested two\n  // fieldsets deep would silently register under the wrong one and its write would be discarded on\n  // submit. Runtime registry integrity, mirroring the namespace-collision throw FormRoot already ships\n  // (form.tsx:280-288).\n  useNoAncestorFieldset('ClientProfileFieldset');\n\n  const $data = useDataOverride($dataProp);\n\n  const $actions = useActionsOverride($actionsProp);\n  // Three conditions, not two. `useReactiveDataSettled` latches one way and never re-arms, so on its\n  // own it answers \"has this page ever resolved\", not \"is what I am holding right now the server's\n  // answer\" — after the page query's entity ref moves to one this cache never stored, or its root is\n  // skipped for want of a variable, the slice silently regresses to `fallbackData` while the latch\n  // still reads settled. `useEntityDataResolved` is the per-entity half: unlatched, so it follows the\n  // slice back down and returns this fieldset to its skeleton instead of leaving live controls seeded\n  // from a placeholder.\n  const settled = useReactiveDataSettled();\n  const sliceResolved = useEntityDataResolved();\n  const resolved = settled && sliceResolved && $data !== undefined;\n  // Also enforces the SessionRoot ancestor: useSession() throws when rendered outside one.\n  const { canEditData } = useSession();\n  const readOnly = !canEditData;\n\n  // Runs before useFormContext() below: useFormRegistry() throws the friendly \"Form parts must be used\n  // inside FormRoot.\" error when no FormRoot is above, so a FormRoot-less render fails there rather than\n  // reaching the getFieldState destructure, which throws an unhelpful TypeError instead (useFormContext()\n  // resolves to null outside a FormRoot, and destructuring null throws).\n  const { registerFieldset } = useFormRegistry();\n\n  // Decision 3, as later narrowed: this fieldset still reads dirtiness imperatively, but the rule is no\n  // longer the form's. `FormRoot` subscribes `dirtyFields` in render and decides which fieldsets to\n  // dispatch from it, by the fields each one has mounted, on react-hook-form's documented contract.\n  //\n  // The imperative read survives here because it asks a different question in a different place: which\n  // of *this* fieldset's own fields changed, resolved inside `toPayload` at submit time, by full\n  // registered field name — the shape `getFieldState` documents. `useFormContext()` adds no\n  // `formState` subscription of its own; one is created only when a caller reads a formState key off\n  // the `useForm`/`useFormState` proxy (or hands that already-subscribed object to `getFieldState`'s\n  // second argument). Calling `getFieldState(name)` with no second argument reads the current internal\n  // state directly, so this fieldset root still does not re-render on a keystroke.\n  const { getFieldState } = useFormContext();\n\n  const latest = useRef({ $actions, country, documentType, readOnly, getFieldState });\n  useEffect(() => {\n    latest.current = { $actions, country, documentType, readOnly, getFieldState };\n  }, [$actions, country, documentType, readOnly, getFieldState]);\n\n  const { registry: fieldsetRegistry, getFieldNames } = useFieldsetFieldNames('clientProfile');\n\n  const dispatch = useCallback(async (payload: Record<string, unknown>) => {\n    // Defence-in-depth: the UI disables every input while read-only, but `FormClear` sets values (and\n    // marks them dirty) on every registered field regardless of that disabled attribute — react-hook-\n    // form's own `useController` calls never receive a `disabled` registration option, so it has no\n    // notion of \"disabled\" of its own. Guarding here keeps the write from reaching the network even if\n    // some other composition dirties this fieldset while canEditData is false (the server also refuses,\n    // but a client-side guard should not depend on that).\n    if (latest.current.readOnly) {\n      throw new Error('ClientProfileFieldset cannot dispatch while the session is read-only.');\n    }\n    const update = latest.current.$actions?.identity?.clientProfileUpdate;\n    // Throwing is the contract's failure path: FormRoot catches it and records this fieldset's failure\n    // (form.tsx:264-266). Returning [] would report an unqualified success for a write that never\n    // happened.\n    if (!update) throw new Error('ClientProfileFieldset requires $actions.identity.clientProfileUpdate.');\n    return update(payload as ClientProfileUpdateInput);\n  }, []);\n\n  const toPayload = useCallback((values: Record<string, unknown>): Record<string, unknown> => {\n    const { country: activeCountry, getFieldState } = latest.current;\n    // FR-5: a key is emitted only when the shopper actually changed it — presence in `values` alone\n    // (every registered field is always present) is not enough. `dirtyFields` is not read directly;\n    // `getFieldState` is called with no second argument, which reads react-hook-form's current\n    // internal state without subscribing to it (Decision 3).\n    const isDirty = (key: ProfileFieldKey) => getFieldState(`clientProfile.${key}`).isDirty;\n    const payload: Record<string, string> = {};\n    if ('firstName' in values && isDirty('firstName')) payload.firstName = String(values.firstName ?? '').trim();\n    if ('lastName' in values && isDirty('lastName')) payload.lastName = String(values.lastName ?? '').trim();\n    if ('phone' in values && isDirty('phone')) {\n      const raw = String(values.phone ?? '').trim();\n      // toE164 on a blank value returns the bare country code, which would write \"+55\" over the\n      // shopper's number and fail every later save.\n      payload.phone = raw ? toE164(raw, activeCountry) : '';\n    }\n    if ('document' in values && isDirty('document')) {\n      payload.document = String(values.document ?? '').replace(/\\D/g, '');\n    }\n    return payload;\n  }, []);\n\n  useEffect(\n    () =>\n      registerFieldset({\n        namespace: 'clientProfile',\n        getFieldNames,\n        dispatch,\n        toPayload,\n        // Decision 1: the register is a machine identifier, the kebab-case ASCII rendering of this\n        // registration's own `namespace` (`clientProfile` → `client-profile`) — not authored per\n        // page (Decision 2).\n        label: 'client-profile',\n      }),\n    [registerFieldset, getFieldNames, dispatch, toPayload],\n  );\n\n  const saved = useMemo<Readonly<Record<ProfileFieldKey, string>>>(\n    () => ({\n      firstName: $data?.firstName ?? '',\n      lastName: $data?.lastName ?? '',\n      phone: $data?.phone ?? '',\n      document: $data?.document ?? '',\n    }),\n    [$data],\n  );\n\n  const contextValue = useMemo<ClientProfileFieldsetContextValue>(\n    () => ({ namespace: 'clientProfile', saved, readOnly, country, documentType, rules: NO_RULES }),\n    [saved, readOnly, country, documentType],\n  );\n\n  // Assistive technology only reports a change inside a region that was already in the tree, so a\n  // region mounted together with its text announces nothing. The region therefore sits in both\n  // branches and starts empty, with the wait written on the pass after mount and replaced — not\n  // cleared — once the controls are up: the skeleton is `aria-hidden`, so without this second\n  // message the form would materialise in silence (WCAG 2.1 SC 4.1.3).\n  const [announcement, setAnnouncement] = useState('');\n  const announced = resolved ? loadedLabel : loadingLabel;\n  useEffect(() => {\n    setAnnouncement(announced);\n  }, [announced]);\n\n  return (\n    <Fieldset.Root\n      className={className}\n      disabled={readOnly}\n      aria-busy={resolved ? undefined : true}\n      // FR-12: blank (or whitespace-only) means no name is exposed, mirroring the loadingLabel/\n      // loadedLabel convention. On the root itself (FR-13), so it is identical whether the fieldset\n      // is pending or resolved; a page-composed FieldsetLegend still wins via aria-labelledby.\n      {...(groupLabel?.trim() ? { 'aria-label': groupLabel } : {})}\n      data-fs-client-profile-fieldset=\"\"\n      {...(resolved ? {} : { 'data-fs-client-profile-fieldset-pending': '' })}\n      {...(readOnly ? { 'data-fs-client-profile-fieldset-readonly': '' } : {})}\n    >\n      {resolved ? (\n        <FieldsetFieldContext.Provider value={fieldsetRegistry}>\n          <ClientProfileFieldsetContext.Provider value={contextValue}>{children}</ClientProfileFieldsetContext.Provider>\n        </FieldsetFieldContext.Provider>\n      ) : (\n        <ClientProfileFieldsetSkeleton count={skeletonCount} />\n      )}\n      <output aria-live=\"polite\" data-fs-client-profile-fieldset-announcement=\"\">\n        {announcement}\n      </output>\n    </Fieldset.Root>\n  );\n}\n\n/**\n * The loading state of the fieldset, rendered in place of the controls until the entity resolves and\n * declared as the definition's `skeleton`. Purely visual: the wait is spoken by the fieldset's own live\n * region, so this is hidden from assistive technology rather than announced twice.\n */\nexport function ClientProfileFieldsetSkeleton({\n  count = CLIENT_PROFILE_SKELETON_ROWS,\n  className,\n  ...props\n}: ComponentPropsWithRef<'div'> & { count?: number }) {\n  return (\n    <div {...props} className={className} data-fs-client-profile-fieldset-skeleton=\"\" aria-hidden=\"true\">\n      {Array.from({ length: count }, (_, i) => (\n        <span key={i} data-fs-client-profile-fieldset-skeleton-field=\"\" />\n      ))}\n    </div>\n  );\n}\n\nClientProfileFieldset.Skeleton = ClientProfileFieldsetSkeleton;\n\n// ---------------------------------------------------------------------------\n// Text controls — first name, last name\n// ---------------------------------------------------------------------------\n\nfunction ProfileTextControl({\n  fieldKey,\n  attr,\n  autoComplete,\n  defaultLabel,\n  label,\n  placeholder,\n  className,\n  children,\n}: {\n  fieldKey: 'firstName' | 'lastName';\n  attr: string;\n  autoComplete: string;\n  defaultLabel: string;\n  label?: string;\n  placeholder?: string;\n  className?: string;\n  children?: ReactNode;\n}) {\n  const { namespace, saved, readOnly, rules } = useClientProfileFieldsetContext();\n  const name = useFieldsetField(namespace, fieldKey);\n\n  return (\n    <FieldBinding\n      name={name}\n      label={label ?? defaultLabel}\n      placeholder={placeholder}\n      defaultValue={saved[fieldKey]}\n      rule={rules[fieldKey]}\n      disabled={readOnly}\n      autoComplete={autoComplete}\n    >\n      <Field.Root className={className} data-fs-client-profile-fieldset-field={attr}>\n        {children ?? (\n          <>\n            <Field.Label />\n            <Field.Control />\n            <Field.Error />\n          </>\n        )}\n      </Field.Root>\n    </FieldBinding>\n  );\n}\n\nexport function ClientProfileFirstNameControl({\n  label,\n  placeholder,\n  className,\n  children,\n}: ClientProfileFirstNameControlProps) {\n  return (\n    <ProfileTextControl\n      fieldKey=\"firstName\"\n      attr=\"first-name\"\n      autoComplete=\"given-name\"\n      defaultLabel=\"First name\"\n      label={label}\n      placeholder={placeholder}\n      className={className}\n    >\n      {children}\n    </ProfileTextControl>\n  );\n}\n\nexport function ClientProfileLastNameControl({\n  label,\n  placeholder,\n  className,\n  children,\n}: ClientProfileLastNameControlProps) {\n  return (\n    <ProfileTextControl\n      fieldKey=\"lastName\"\n      attr=\"last-name\"\n      autoComplete=\"family-name\"\n      defaultLabel=\"Last name\"\n      label={label}\n      placeholder={placeholder}\n      className={className}\n    >\n      {children}\n    </ProfileTextControl>\n  );\n}\n\n// ---------------------------------------------------------------------------\n// Phone control — the fieldset-bound counterpart of ClientProfilePhoneControl\n// ---------------------------------------------------------------------------\n\n/**\n * Composes `PhoneField` inside a `FieldBinding`, wrapped in a `data-fs-client-profile-fieldset-field=\"phone\"`\n * node — the same styling hook attribute the text controls carry on their own `Field.Root`.\n * `useFieldsetField` runs unconditionally, before `requirement` is even read — there is no suppressed\n * state for this control to second-guess; `requirement` only ever raises the field to required,\n * and left unset it raises nothing.\n */\nexport function ClientProfileFieldsetPhoneControl({\n  label,\n  placeholder,\n  requirement,\n  errorInvalid,\n  errorRequired,\n  className,\n  children,\n}: ClientProfileFieldsetPhoneControlProps) {\n  const { namespace, saved, readOnly, rules, country } = useClientProfileFieldsetContext();\n  const name = useFieldsetField(namespace, 'phone');\n\n  const binding = (\n    <FieldBinding\n      name={name}\n      label={label}\n      placeholder={placeholder}\n      defaultValue={saved.phone}\n      rule={rules.phone}\n      disabled={readOnly}\n    >\n      <PhoneField\n        country={country}\n        requirement={requirement}\n        errorInvalid={errorInvalid}\n        errorRequired={errorRequired}\n        className={className}\n      >\n        {children}\n      </PhoneField>\n    </FieldBinding>\n  );\n\n  // The wrapper carries no className of its own (Decision 1): className lands on PhoneField's own\n  // Field.Root, the node that actually stacks label, input and error, so it needs no flex slot here.\n  return <div data-fs-client-profile-fieldset-field=\"phone\">{binding}</div>;\n}\n\n// ---------------------------------------------------------------------------\n// Document control — self-gates on documentType, through an inner component\n// ---------------------------------------------------------------------------\n\ntype ClientProfileDocumentControlInnerProps = ClientProfileDocumentControlProps & { documentType: DocumentType };\n\n/**\n * `useFieldsetField` (through `useClientProfileFieldsetContext`'s namespace) lives only in this inner\n * component, mounted only once `ClientProfileDocumentControl` has already decided the document type is\n * supported. Splitting the decision from the registration this way (Decision 8) keeps a control that\n * renders nothing from registering a field name `FormClear` would otherwise dirty and dispatch.\n */\nfunction ClientProfileDocumentControlInner({\n  documentType,\n  label,\n  placeholder,\n  errorMessage,\n  className,\n  children,\n}: ClientProfileDocumentControlInnerProps) {\n  const { namespace, saved, readOnly, rules } = useClientProfileFieldsetContext();\n  const name = useFieldsetField(namespace, 'document');\n\n  return (\n    <FieldBinding\n      name={name}\n      label={label ?? DOCUMENTS[documentType].name}\n      placeholder={placeholder}\n      defaultValue={saved.document}\n      rule={rules.document}\n      disabled={readOnly}\n    >\n      <DocumentField\n        documentType={documentType}\n        errorMessage={errorMessage}\n        className={className}\n        data-fs-client-profile-fieldset-field=\"document\"\n      >\n        {children}\n      </DocumentField>\n    </FieldBinding>\n  );\n}\n\nexport function ClientProfileDocumentControl({\n  label,\n  placeholder,\n  errorMessage,\n  className,\n  children,\n}: ClientProfileDocumentControlProps) {\n  const { documentType } = useClientProfileFieldsetContext();\n  if (!isSupportedDocumentType(documentType)) return null;\n\n  return (\n    <ClientProfileDocumentControlInner\n      documentType={documentType}\n      label={label}\n      placeholder={placeholder}\n      errorMessage={errorMessage}\n      className={className}\n    >\n      {children}\n    </ClientProfileDocumentControlInner>\n  );\n}\n"],"mappings":"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"}

package/dist/matter/identity-edit/identity-edit.js

@@ -20,7 +20,7 @@ const IdentityEditControllerDefinition = defineComponent({
 		category: "commerce"
 	},
 	schema: {},
-	guideline: "Owns the identity section's summary/form toggle: starts on the summary, opens on IdentityEditButton and returns on IdentityEditCancelButton. Saving does not move it, so the form's confirmation stays readable and ClientProfileForm never needs to know about a section around it. Self-contained: collapsing tells nothing else, so no other section opens as a result. Compose an IdentitySummaryView holding the summary parts and an IdentityEditForm holding a ClientProfileForm, plus an IdentityEditButton in the heading and an IdentityEditCancelButton next to the form. No state is named anywhere: which state a part belongs to is which component it is. Renders no DOM of its own."
+	guideline: "Owns the identity section's summary/form toggle: starts on the summary, opens on IdentityEditButton and returns on IdentityEditCancelButton. Saving does not move it, so the form stays open and no descendant needs to know about a section around it. Self-contained: collapsing tells nothing else, so no other section opens as a result. Compose an IdentitySummaryView holding the summary parts and an IdentityEditForm holding a FormRoot over ClientProfileFieldset, plus an IdentityEditButton in the heading and an IdentityEditCancelButton next to the form. No state is named anywhere: which state a part belongs to is which component it is. Renders no DOM of its own."
 });
 const IdentitySummaryViewDefinition = defineComponent({
 	name: "IdentitySummaryView",
@@ -44,7 +44,7 @@ const IdentityEditFormDefinition = defineComponent({
 		category: "commerce"
 	},
 	schema: {},
-	guideline: "Renders its children only while the identity section shows the form, and nothing while it shows the summary. Compose ClientProfileFormRoot and its parts inside, plus an IdentityEditCancelButton. Must be inside an IdentityEditController."
+	guideline: "Renders its children only while the identity section shows the form, and nothing while it shows the summary. Compose a FormRoot holding ClientProfileFieldset and its controls inside, plus an IdentityEditCancelButton. Must be inside an IdentityEditController."
 });
 const IdentityEditButtonDefinition = defineComponent({
 	name: "IdentityEditButton",