@vtex/faststore 0.0.1

package/dist/matter/client-preferences/client-preferences.js

@@ -0,0 +1,206 @@
+"use client";
+import { defineComponent } from "../../core/dist/define-component.js";
+import "../../core/dist/index.js";
+import { Field } from "../../particles/field/field.js";
+import { useDataOverride } from "../../sdk/data/data-override-context.js";
+import { useSession } from "../session/session.js";
+import { Icon } from "../../particles/icon/icon.js";
+import { Checkbox } from "../../particles/checkbox/checkbox.js";
+import { createContext, useCallback, useContext, useMemo, useState } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+const ClientPreferencesRootDefinition = defineComponent({
+	name: "ClientPreferencesRoot",
+	importPath: "@vtex/faststore/components",
+	component: ClientPreferencesRoot,
+	fragment: `
+  fragment ClientPreferencesData on Query {
+    clientPreferences {
+      __typename
+      id
+      optinNewsLetter
+      savePersonalData
+    }
+  }
+`,
+	fetchStrategy: "reactive",
+	providesContext: "client-preferences",
+	requiresContext: "session",
+	editor: {
+		label: "Client Preferences Root",
+		category: "identity"
+	},
+	schema: {},
+	guideline: "Binding provider for the consent opt-in section; reads both opt-in values (optinNewsLetter, savePersonalData) from the ClientPreferences identity entity (a sibling of Cart, via Query.clientPreferences) and exposes them to its Controls. Reads session state from useSession(); must be inside SessionRoot. Writes flow through $actions.identity.clientPreferencesUpdate. Wrap a NewsletterOptInControl and/or a SavePersonalDataOptInControl."
+});
+const NewsletterOptInControlDefinition = defineComponent({
+	name: "NewsletterOptInControl",
+	importPath: "@vtex/faststore/components",
+	component: NewsletterOptInControl,
+	requiresContext: "client-preferences",
+	actions: { identity: ["clientPreferencesUpdate"] },
+	editor: {
+		label: "Newsletter Opt-In Control",
+		category: "identity"
+	},
+	schema: { label: {
+		type: "string",
+		label: "Label"
+	} },
+	guideline: "The bound newsletter opt-in checkbox; must be a descendant of ClientPreferencesRoot. Toggling writes the optinNewsLetter preference via $actions.identity.clientPreferencesUpdate. Defaults to unchecked."
+});
+const SavePersonalDataOptInControlDefinition = defineComponent({
+	name: "SavePersonalDataOptInControl",
+	importPath: "@vtex/faststore/components",
+	component: SavePersonalDataOptInControl,
+	requiresContext: "client-preferences",
+	actions: { identity: ["clientPreferencesUpdate"] },
+	editor: {
+		label: "Save Personal Data Opt-In Control",
+		category: "identity"
+	},
+	schema: { label: {
+		type: "string",
+		label: "Label"
+	} },
+	guideline: "The bound save-personal-data opt-in checkbox; must be a descendant of ClientPreferencesRoot. Toggling writes the savePersonalData preference via $actions.identity.clientPreferencesUpdate. Defaults to unchecked."
+});
+const CLIENT_PREFERENCES_UNSET = Symbol("ClientPreferencesContextUnset");
+const ClientPreferencesContext = createContext(CLIENT_PREFERENCES_UNSET);
+function useClientPreferencesContext() {
+	const ctx = useContext(ClientPreferencesContext);
+	if (ctx === CLIENT_PREFERENCES_UNSET) throw new Error("A client-preferences Control must be used inside a ClientPreferencesRoot.");
+	return ctx;
+}
+/**
+* Renders the client-preferences section Root: reads `$data` (the `ClientPreferences` sibling entity),
+* reads `useSession()` (which also enforces the `SessionRoot` ancestor, mirroring
+* `EmailIdentificationControl`), seeds both opt-in values from the section fragment, and publishes a
+* section context exposing both values plus per-field pending/error tracking. The write itself flows
+* through the Control's `$actions.identity.clientPreferencesUpdate` (ADR-0010); this Root tracks which
+* keys are in flight and stores the returned userErrors under each key so each Control surfaces ITS OWN
+* pending/error. When the session reports `canEditData: false` (identified but unauthenticated claimed
+* profile — VTEX refuses the write server-side) every Control renders disabled with its readonly
+* `data-fs-*` attribute, mirroring `EmailIdentificationControl`.
+*/
+function ClientPreferencesRoot({ $data: $dataProp, className, children }) {
+	const $data = useDataOverride($dataProp);
+	const { canEditData } = useSession();
+	const readOnly = !canEditData;
+	const optinNewsLetter = Boolean($data?.clientPreferences?.optinNewsLetter ?? false);
+	const savePersonalData = Boolean($data?.clientPreferences?.savePersonalData ?? false);
+	const [pendingKeys, setPendingKeys] = useState(/* @__PURE__ */ new Set());
+	const [errorByKey, setErrorByKey] = useState({});
+	const trackWrite = useCallback((key, write) => {
+		setErrorByKey((prev) => ({
+			...prev,
+			[key]: []
+		}));
+		setPendingKeys((prev) => new Set(prev).add(key));
+		write.then((userErrors) => {
+			setErrorByKey((prev) => ({
+				...prev,
+				[key]: userErrors
+			}));
+		}).finally(() => {
+			setPendingKeys((prev) => {
+				const next = new Set(prev);
+				next.delete(key);
+				return next;
+			});
+		});
+	}, []);
+	const values = useMemo(() => ({
+		optinNewsLetter,
+		savePersonalData
+	}), [optinNewsLetter, savePersonalData]);
+	const contextValue = useMemo(() => ({
+		values,
+		trackWrite,
+		pendingKeys,
+		errorByKey,
+		readOnly
+	}), [
+		values,
+		trackWrite,
+		pendingKeys,
+		errorByKey,
+		readOnly
+	]);
+	return /* @__PURE__ */ jsx(ClientPreferencesContext, {
+		value: contextValue,
+		children: /* @__PURE__ */ jsx("div", {
+			className,
+			"data-fs-client-preferences-root": "",
+			children
+		})
+	});
+}
+/**
+* Renders one bound opt-in checkbox by inlining `Field` + `Checkbox` + `Icon` (no `CheckboxField`
+* particle). Reads ITS field's value, pending, and error from the section context and dispatches the
+* write through `$actions.identity.clientPreferencesUpdate({ [key]: value })`, handing the promise to
+* the section so the in-flight key and returned userErrors are tracked per field. The `fieldKey`,
+* `dataAttr`, `pendingAttr`, and `readonlyAttr` are fixed by each registered Control; only
+* `label`/`className` are merchant-configurable.
+*/
+function OptInControl({ fieldKey, dataAttr, pendingAttr, readonlyAttr, label, className, $actions }) {
+	const { values, trackWrite, pendingKeys, errorByKey, readOnly } = useClientPreferencesContext();
+	const fieldErrors = errorByKey[fieldKey] ?? [];
+	const value = values[fieldKey];
+	const pending = pendingKeys.has(fieldKey);
+	const disabled = pending || readOnly;
+	const [firstError] = fieldErrors;
+	const invalid = Boolean(firstError);
+	function handleCheckedChange(checked) {
+		const update = $actions?.identity?.clientPreferencesUpdate;
+		if (!update) return;
+		trackWrite(fieldKey, update({ [fieldKey]: checked }));
+	}
+	return /* @__PURE__ */ jsx("div", {
+		className,
+		[dataAttr]: "",
+		...pending ? { [pendingAttr]: "" } : {},
+		...readOnly ? { [readonlyAttr]: "" } : {},
+		children: /* @__PURE__ */ jsxs(Field.Root, {
+			invalid,
+			disabled,
+			"data-fs-field-root": "",
+			children: [/* @__PURE__ */ jsxs(Field.Label, { children: [/* @__PURE__ */ jsx(Checkbox.Root, {
+				checked: value,
+				onCheckedChange: handleCheckedChange,
+				disabled,
+				children: /* @__PURE__ */ jsx(Checkbox.Indicator, { children: /* @__PURE__ */ jsx(Icon, { name: "checked" }) })
+			}), label] }), invalid && firstError ? /* @__PURE__ */ jsx(Field.Error, {
+				match: true,
+				children: firstError.message
+			}) : null]
+		})
+	});
+}
+function NewsletterOptInControl(props) {
+	return /* @__PURE__ */ jsx(OptInControl, {
+		...props,
+		fieldKey: "optinNewsLetter",
+		dataAttr: "data-fs-newsletter-opt-in",
+		pendingAttr: "data-fs-newsletter-opt-in-pending",
+		readonlyAttr: "data-fs-newsletter-opt-in-readonly"
+	});
+}
+function SavePersonalDataOptInControl(props) {
+	return /* @__PURE__ */ jsx(OptInControl, {
+		...props,
+		fieldKey: "savePersonalData",
+		dataAttr: "data-fs-save-personal-data-opt-in",
+		pendingAttr: "data-fs-save-personal-data-opt-in-pending",
+		readonlyAttr: "data-fs-save-personal-data-opt-in-readonly"
+	});
+}
+const ClientPreferences = {
+	Root: ClientPreferencesRoot,
+	NewsletterOptInControl,
+	SavePersonalDataOptInControl
+};
+//#endregion
+export { ClientPreferences, ClientPreferencesRoot, ClientPreferencesRootDefinition, NewsletterOptInControl, NewsletterOptInControlDefinition, SavePersonalDataOptInControl, SavePersonalDataOptInControlDefinition };
+
+//# sourceMappingURL=client-preferences.js.map

package/dist/matter/client-preferences/client-preferences.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-preferences.js","names":[],"sources":["../../../src/matter/client-preferences/client-preferences.tsx"],"sourcesContent":["'use client';\n\nimport { defineComponent } from '@vtex/fs-core';\nimport { createContext, type ReactNode, useCallback, useContext, useMemo, useState } from 'react';\nimport { Checkbox } from '../../particles/checkbox/checkbox.js';\nimport { Field } from '../../particles/field/field.js';\nimport { Icon } from '../../particles/icon/icon.js';\nimport type { ComponentActions } from '../../sdk/actions/types.js';\nimport { useDataOverride } from '../../sdk/data/data-override-context.js';\nimport type { ClientPreferenceKey, ClientProfileUserError } from '../../sdk/identity/operations.js';\nimport { useSession } from '../session/session.js';\n\n/**\n * The `client-preferences` section matter (per ADR-0011: a matter is decomposed by DATA OWNERSHIP,\n * not per field). Both opt-ins — newsletter (`optinNewsLetter`) and save-personal-data\n * (`savePersonalData`) — are light booleans owned by the User Identity `ClientPreferences` entity\n * (a SIBLING of `Cart`, not nested under it, per the identity RFC), so they live under ONE\n * `ClientPreferencesRoot` that declares a single section fragment on `Query` selecting both fields.\n * The two merchant-facing Controls consume that one section context (ADR-0011 governs data\n * ownership, not the editor palette) and share one internal `OptInControl` implementation: the\n * section context, the `$data` → values seeding, the per-field pending/error tracking, the inlined\n * `Checkbox` + `Field` Control render, and dispatch via `$actions.identity.clientPreferencesUpdate`\n * (mirrors the `email-identification` matter; reads/writes follow ADR-0006 / ADR-0010 / ADR-0011).\n */\n\n// ---------------------------------------------------------------------------\n// GraphQL Fragment — colocated (ADR-0011), reads the ClientPreferences sibling\n// entity via Query. Authored as a raw string (not the codegen graphql() factory),\n// mirroring the EmailIdentification matter: the compiler derives the entity fragment\n// on `clientPreferences` and subscribes reactively. One section fragment owns both\n// opt-in fields (ADR-0011).\n// ---------------------------------------------------------------------------\n\nconst fragment = /* GraphQL */ `\n  fragment ClientPreferencesData on Query {\n    clientPreferences {\n      __typename\n      id\n      optinNewsLetter\n      savePersonalData\n    }\n  }\n`;\n\n// ---------------------------------------------------------------------------\n// Types\n// ---------------------------------------------------------------------------\n\n/** The `$data` slice forwarded by the reactive runtime — the `ClientPreferences` sibling entity. */\nexport type ClientPreferencesData = {\n  clientPreferences?: {\n    optinNewsLetter?: boolean | null;\n    savePersonalData?: boolean | null;\n  } | null;\n} | null;\n\nexport type ClientPreferencesRootProps = {\n  /** `Query` slice forwarded by the reactive runtime (value of the section fragment). */\n  $data?: ClientPreferencesData;\n  className?: string;\n  children?: ReactNode;\n};\n\nexport type ClientPreferencesControlProps = {\n  label: string;\n  className?: string;\n  /** Injected by the compiler from `actions: { identity: ['clientPreferencesUpdate'] }`; the write surface. */\n  $actions?: ComponentActions;\n};\n\nexport type NewsletterOptInControlProps = ClientPreferencesControlProps;\nexport type SavePersonalDataOptInControlProps = ClientPreferencesControlProps;\n\n// ---------------------------------------------------------------------------\n// Definitions\n// ---------------------------------------------------------------------------\n\nexport const ClientPreferencesRootDefinition = defineComponent<ClientPreferencesRootProps>({\n  name: 'ClientPreferencesRoot',\n  importPath: '@vtex/faststore/components',\n  component: ClientPreferencesRoot,\n  fragment,\n  fetchStrategy: 'reactive',\n  providesContext: 'client-preferences',\n  requiresContext: 'session',\n  editor: { label: 'Client Preferences Root', category: 'identity' },\n  schema: {},\n  guideline:\n    'Binding provider for the consent opt-in section; reads both opt-in values (optinNewsLetter, savePersonalData) from the ClientPreferences identity entity (a sibling of Cart, via Query.clientPreferences) and exposes them to its Controls. Reads session state from useSession(); must be inside SessionRoot. Writes flow through $actions.identity.clientPreferencesUpdate. Wrap a NewsletterOptInControl and/or a SavePersonalDataOptInControl.',\n});\n\nexport const NewsletterOptInControlDefinition = defineComponent<NewsletterOptInControlProps>({\n  name: 'NewsletterOptInControl',\n  importPath: '@vtex/faststore/components',\n  component: NewsletterOptInControl,\n  requiresContext: 'client-preferences',\n  actions: { identity: ['clientPreferencesUpdate'] },\n  editor: { label: 'Newsletter Opt-In Control', category: 'identity' },\n  schema: {\n    label: { type: 'string', label: 'Label' },\n  },\n  guideline:\n    'The bound newsletter opt-in checkbox; must be a descendant of ClientPreferencesRoot. Toggling writes the optinNewsLetter preference via $actions.identity.clientPreferencesUpdate. Defaults to unchecked.',\n});\n\nexport const SavePersonalDataOptInControlDefinition = defineComponent<SavePersonalDataOptInControlProps>({\n  name: 'SavePersonalDataOptInControl',\n  importPath: '@vtex/faststore/components',\n  component: SavePersonalDataOptInControl,\n  requiresContext: 'client-preferences',\n  actions: { identity: ['clientPreferencesUpdate'] },\n  editor: { label: 'Save Personal Data Opt-In Control', category: 'identity' },\n  schema: {\n    label: { type: 'string', label: 'Label' },\n  },\n  guideline:\n    'The bound save-personal-data opt-in checkbox; must be a descendant of ClientPreferencesRoot. Toggling writes the savePersonalData preference via $actions.identity.clientPreferencesUpdate. Defaults to unchecked.',\n});\n\n// ---------------------------------------------------------------------------\n// Context\n// ---------------------------------------------------------------------------\n\ntype ClientPreferencesContextValue = Readonly<{\n  /** Current value of each opt-in, seeded from the query response (null → unchecked). */\n  values: Readonly<Record<ClientPreferenceKey, boolean>>;\n  /**\n   * Records that a write for `key` is in flight and stores its returned userErrors under that key so\n   * each Control surfaces ITS OWN pending/error. The Control owns the actual dispatch (it holds\n   * `$actions`); it hands the resulting promise here for the section to track.\n   */\n  trackWrite: (key: ClientPreferenceKey, write: Promise<readonly ClientProfileUserError[]>) => void;\n  /**\n   * The fields whose writes are currently in flight. A per-key set, not a single slot: concurrent\n   * writes on different fields must each keep their own Control disabled until THEIR write settles.\n   */\n  pendingKeys: ReadonlySet<ClientPreferenceKey>;\n  /** The userErrors returned by the most recent write, keyed by the field that produced them. */\n  errorByKey: Readonly<Partial<Record<ClientPreferenceKey, readonly ClientProfileUserError[]>>>;\n  /**\n   * True when the session reports `canEditData: false` — VTEX refuses profile-data edits for an\n   * identified-but-unauthenticated claimed profile, so the Controls render disabled instead of\n   * accepting writes that are doomed server-side (mirrors the email control).\n   */\n  readOnly: boolean;\n}>;\n\nconst CLIENT_PREFERENCES_UNSET = Symbol('ClientPreferencesContextUnset');\n\nconst ClientPreferencesContext = createContext<ClientPreferencesContextValue | typeof CLIENT_PREFERENCES_UNSET>(\n  CLIENT_PREFERENCES_UNSET,\n);\n\nfunction useClientPreferencesContext(): ClientPreferencesContextValue {\n  const ctx = useContext(ClientPreferencesContext);\n  if (ctx === CLIENT_PREFERENCES_UNSET) {\n    throw new Error('A client-preferences Control must be used inside a ClientPreferencesRoot.');\n  }\n  return ctx;\n}\n\n// ---------------------------------------------------------------------------\n// Root\n// ---------------------------------------------------------------------------\n\n/**\n * Renders the client-preferences section Root: reads `$data` (the `ClientPreferences` sibling entity),\n * reads `useSession()` (which also enforces the `SessionRoot` ancestor, mirroring\n * `EmailIdentificationControl`), seeds both opt-in values from the section fragment, and publishes a\n * section context exposing both values plus per-field pending/error tracking. The write itself flows\n * through the Control's `$actions.identity.clientPreferencesUpdate` (ADR-0010); this Root tracks which\n * keys are in flight and stores the returned userErrors under each key so each Control surfaces ITS OWN\n * pending/error. When the session reports `canEditData: false` (identified but unauthenticated claimed\n * profile — VTEX refuses the write server-side) every Control renders disabled with its readonly\n * `data-fs-*` attribute, mirroring `EmailIdentificationControl`.\n */\nexport function ClientPreferencesRoot({ $data: $dataProp, className, children }: ClientPreferencesRootProps) {\n  const $data = useDataOverride($dataProp);\n  // Also enforces the SessionRoot ancestor: useSession() throws when rendered outside one.\n  const { canEditData } = useSession();\n  const readOnly = !canEditData;\n\n  const optinNewsLetter = Boolean($data?.clientPreferences?.optinNewsLetter ?? false);\n  const savePersonalData = Boolean($data?.clientPreferences?.savePersonalData ?? false);\n\n  const [pendingKeys, setPendingKeys] = useState<ReadonlySet<ClientPreferenceKey>>(new Set());\n  const [errorByKey, setErrorByKey] = useState<Partial<Record<ClientPreferenceKey, readonly ClientProfileUserError[]>>>(\n    {},\n  );\n\n  const trackWrite = useCallback((key: ClientPreferenceKey, write: Promise<readonly ClientProfileUserError[]>) => {\n    // Clear the key's stale error at the start of a retry (parity with the email control clearing\n    // its serverError on a new write).\n    setErrorByKey((prev) => ({ ...prev, [key]: [] }));\n    setPendingKeys((prev) => new Set(prev).add(key));\n    void write\n      .then((userErrors) => {\n        setErrorByKey((prev) => ({ ...prev, [key]: userErrors }));\n      })\n      .finally(() => {\n        setPendingKeys((prev) => {\n          const next = new Set(prev);\n          next.delete(key);\n          return next;\n        });\n      });\n  }, []);\n\n  const values = useMemo(() => ({ optinNewsLetter, savePersonalData }) as const, [optinNewsLetter, savePersonalData]);\n\n  const contextValue = useMemo<ClientPreferencesContextValue>(\n    () => ({ values, trackWrite, pendingKeys, errorByKey, readOnly }),\n    [values, trackWrite, pendingKeys, errorByKey, readOnly],\n  );\n\n  return (\n    <ClientPreferencesContext value={contextValue}>\n      <div className={className} data-fs-client-preferences-root=\"\">\n        {children}\n      </div>\n    </ClientPreferencesContext>\n  );\n}\n\n// ---------------------------------------------------------------------------\n// Controls\n// ---------------------------------------------------------------------------\n\n/**\n * Renders one bound opt-in checkbox by inlining `Field` + `Checkbox` + `Icon` (no `CheckboxField`\n * particle). Reads ITS field's value, pending, and error from the section context and dispatches the\n * write through `$actions.identity.clientPreferencesUpdate({ [key]: value })`, handing the promise to\n * the section so the in-flight key and returned userErrors are tracked per field. The `fieldKey`,\n * `dataAttr`, `pendingAttr`, and `readonlyAttr` are fixed by each registered Control; only\n * `label`/`className` are merchant-configurable.\n */\nfunction OptInControl({\n  fieldKey,\n  dataAttr,\n  pendingAttr,\n  readonlyAttr,\n  label,\n  className,\n  $actions,\n}: ClientPreferencesControlProps & {\n  fieldKey: ClientPreferenceKey;\n  dataAttr: string;\n  pendingAttr: string;\n  readonlyAttr: string;\n}) {\n  const { values, trackWrite, pendingKeys, errorByKey, readOnly } = useClientPreferencesContext();\n  const fieldErrors = errorByKey[fieldKey] ?? [];\n  const value = values[fieldKey];\n  const pending = pendingKeys.has(fieldKey);\n  const disabled = pending || readOnly;\n  const [firstError] = fieldErrors;\n  const invalid = Boolean(firstError);\n\n  function handleCheckedChange(checked: boolean) {\n    const update = $actions?.identity?.clientPreferencesUpdate;\n    if (!update) return;\n    trackWrite(fieldKey, update({ [fieldKey]: checked }));\n  }\n\n  return (\n    <div\n      className={className}\n      {...{ [dataAttr]: '' }}\n      {...(pending ? { [pendingAttr]: '' } : {})}\n      {...(readOnly ? { [readonlyAttr]: '' } : {})}\n    >\n      <Field.Root invalid={invalid} disabled={disabled} data-fs-field-root=\"\">\n        <Field.Label>\n          <Checkbox.Root checked={value} onCheckedChange={handleCheckedChange} disabled={disabled}>\n            <Checkbox.Indicator>\n              <Icon name=\"checked\" />\n            </Checkbox.Indicator>\n          </Checkbox.Root>\n          {label}\n        </Field.Label>\n        {invalid && firstError ? <Field.Error match>{firstError.message}</Field.Error> : null}\n      </Field.Root>\n    </div>\n  );\n}\n\nexport function NewsletterOptInControl(props: NewsletterOptInControlProps) {\n  return (\n    <OptInControl\n      {...props}\n      fieldKey=\"optinNewsLetter\"\n      dataAttr=\"data-fs-newsletter-opt-in\"\n      pendingAttr=\"data-fs-newsletter-opt-in-pending\"\n      readonlyAttr=\"data-fs-newsletter-opt-in-readonly\"\n    />\n  );\n}\n\nexport function SavePersonalDataOptInControl(props: SavePersonalDataOptInControlProps) {\n  return (\n    <OptInControl\n      {...props}\n      fieldKey=\"savePersonalData\"\n      dataAttr=\"data-fs-save-personal-data-opt-in\"\n      pendingAttr=\"data-fs-save-personal-data-opt-in-pending\"\n      readonlyAttr=\"data-fs-save-personal-data-opt-in-readonly\"\n    />\n  );\n}\n\n// ---------------------------------------------------------------------------\n// Namespace export\n// ---------------------------------------------------------------------------\n\nexport const ClientPreferences = {\n  Root: ClientPreferencesRoot,\n  NewsletterOptInControl,\n  SavePersonalDataOptInControl,\n};\n"],"mappings":"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"}

package/dist/matter/client-profile/client-profile.d.ts

@@ -0,0 +1,59 @@
+import { ComponentDefinition } from "../../core/dist/define-component.js";
+import "../../core/dist/index.js";
+import { ComponentActions } from "../../sdk/actions/types.js";
+import { PhoneCountry } from "../../particles/phone-field/phone-field.js";
+import { ReactNode } from "react";
+//#region src/matter/client-profile/client-profile.d.ts
+/** The `$data` slice forwarded by the reactive runtime — the `ClientProfile` sibling entity. */
+export type ClientProfileData = {
+  clientProfile?: {
+    phone?: string | null;
+  } | null;
+} | null;
+export type ClientProfileRootProps = {
+  /** ClientProfile entity slice forwarded by the reactive runtime (value of the section fragment). */
+  $data?: ClientProfileData;
+  className?: string;
+  children?: ReactNode;
+};
+export declare const ClientProfileRootDefinition: ComponentDefinition<ClientProfileRootProps>;
+/**
+ * Renders the client-profile section Root: reads `$data` (the `ClientProfile` sibling entity), seeds
+ * the profile values from the colocated fragment, and publishes a section context. It also reads
+ * `useSession()` — which enforces the `SessionRoot` ancestor. Writes are owned by the Control's
+ * `$actions.identity` (ADR-0010); the Root only supplies the pre-fill.
+ */
+export declare function ClientProfileRoot({ $data: $dataProp, className, children }: ClientProfileRootProps): import("react/jsx-runtime").JSX.Element;
+type PhoneFieldRequirement = 'mandatory' | 'optional' | 'hidden';
+export type ClientProfilePhoneControlProps = {
+  /** Visible field label. */
+  label?: string;
+  /** Selects the phone mask and validation rule. */
+  country?: PhoneCountry;
+  /** Controls field visibility and required validation. */
+  requirement?: PhoneFieldRequirement;
+  /** Error string shown when the input format is invalid. */
+  errorInvalid?: string;
+  /** Error string shown when the mandatory field is left empty. */
+  errorRequired?: string;
+  className?: string;
+  /** Injected by the compiler from `actions: { identity: ['clientProfileUpdate'] }`; the write surface. */
+  $actions?: ComponentActions;
+};
+export declare const ClientProfilePhoneControlDefinition: ComponentDefinition<ClientProfilePhoneControlProps>;
+/**
+ * Renders the bound phone field by composing the reusable `PhoneField` particle. Reads the saved
+ * phone from the section context, and on a **changed** value persists only `phone` — normalized to
+ * E.164 — through `$actions.identity.clientProfileUpdate({ phone })` on blur (pessimistic,
+ * mirroring `EmailIdentificationControl`). While the write is in flight the field is disabled and
+ * `data-fs-client-profile-phone-pending` is present so a checkout-CTA guard can block. When the
+ * session reports `canEditData: false` the field renders disabled with
+ * `data-fs-client-profile-phone-readonly`. Server `userErrors` are surfaced inline.
+ */
+export declare function ClientProfilePhoneControl({ label, country, requirement, errorInvalid, errorRequired, className, $actions }: ClientProfilePhoneControlProps): import("react/jsx-runtime").JSX.Element;
+export declare const ClientProfile: {
+  Root: typeof ClientProfileRoot;
+  PhoneControl: typeof ClientProfilePhoneControl;
+};
+//#endregion
+//# sourceMappingURL=client-profile.d.ts.map

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

@@ -0,0 +1,185 @@
+"use client";
+import { defineComponent } from "../../core/dist/define-component.js";
+import "../../core/dist/index.js";
+import { useDataOverride } from "../../sdk/data/data-override-context.js";
+import { useSession } from "../session/session.js";
+import { PhoneField, toE164, validatePhoneNumber } from "../../particles/phone-field/phone-field.js";
+import { createContext, useContext, useMemo, useRef, useState } from "react";
+import { jsx } from "react/jsx-runtime";
+//#region src/matter/client-profile/client-profile.tsx
+/**
+* The `client-profile` section matter (per ADR-0011: a matter is decomposed by DATA OWNERSHIP, not
+* per field). The shopper-profile fields recorded on the cart's `clientProfileData` live on the User
+* Identity `ClientProfile` entity — a SIBLING of `Cart`, not nested under it. They are read through
+* `Query.clientProfile` and written through the shared `$actions.identity.clientProfileUpdate`
+* action, which performs a partial write that leaves the fields it is not given untouched.
+*
+* This matter wires only `phone`: a `ClientProfilePhoneControl` that composes the reusable,
+* business-agnostic `PhoneField` particle (reused later in MyAccount / extensions; the binding here
+* owns the data source and persistence). Room is kept for future profile Controls on the same Root.
+* Reads follow the colocated-fragment Root pattern (ADR-0006, fetchStrategy 'reactive'), mirroring
+* `EmailIdentificationControl`; writes flow through `$actions.identity` (ADR-0010). The write is
+* pessimistic (awaits the mutation) and is dispatched on blur — form-bound saving via the profile-form
+* CTA is a follow-up, not implemented here.
+*/
+const fragment = `
+  fragment ClientProfilePhoneData on Query {
+    clientProfile {
+      __typename
+      id
+      phone
+    }
+  }
+`;
+const CLIENT_PROFILE_UNSET = Symbol("ClientProfileContextUnset");
+const ClientProfileContext = createContext(CLIENT_PROFILE_UNSET);
+function useClientProfileContext() {
+	const ctx = useContext(ClientProfileContext);
+	if (ctx === CLIENT_PROFILE_UNSET) throw new Error("A client-profile Control must be used inside a ClientProfileRoot.");
+	return ctx;
+}
+const ClientProfileRootDefinition = defineComponent({
+	name: "ClientProfileRoot",
+	importPath: "@vtex/faststore/components",
+	component: ClientProfileRoot,
+	fragment,
+	fetchStrategy: "reactive",
+	providesContext: "client-profile",
+	requiresContext: "session",
+	editor: {
+		label: "Client Profile Root",
+		category: "identity"
+	},
+	schema: {},
+	guideline: "Binding provider for the shopper-profile section; reads the profile fields (today: phone) from the ClientProfile entity (Query.clientProfile) and exposes them to its Controls. Writes flow through $actions.identity.clientProfileUpdate. Must be inside SessionRoot. Wrap a ClientProfilePhoneControl."
+});
+/**
+* Renders the client-profile section Root: reads `$data` (the `ClientProfile` sibling entity), seeds
+* the profile values from the colocated fragment, and publishes a section context. It also reads
+* `useSession()` — which enforces the `SessionRoot` ancestor. Writes are owned by the Control's
+* `$actions.identity` (ADR-0010); the Root only supplies the pre-fill.
+*/
+function ClientProfileRoot({ $data: $dataProp, className, children }) {
+	const $data = useDataOverride($dataProp);
+	useSession();
+	const phone = $data?.clientProfile?.phone ?? "";
+	const contextValue = useMemo(() => ({ phone }), [phone]);
+	return /* @__PURE__ */ jsx(ClientProfileContext, {
+		value: contextValue,
+		children: /* @__PURE__ */ jsx("div", {
+			className,
+			"data-fs-client-profile-root": "",
+			children
+		})
+	});
+}
+const ClientProfilePhoneControlDefinition = defineComponent({
+	name: "ClientProfilePhoneControl",
+	importPath: "@vtex/faststore/components",
+	component: ClientProfilePhoneControl,
+	requiresContext: "client-profile",
+	actions: { identity: ["clientProfileUpdate"] },
+	editor: {
+		label: "Client Profile Phone Control",
+		category: "identity"
+	},
+	schema: {
+		label: {
+			type: "string",
+			default: "Phone",
+			label: "Label"
+		},
+		country: {
+			type: "string",
+			default: "US",
+			label: "Country (US or BR)"
+		},
+		requirement: {
+			type: "string",
+			default: "mandatory",
+			label: "Requirement"
+		},
+		errorInvalid: {
+			type: "string",
+			default: "Invalid phone number",
+			label: "Invalid error message"
+		},
+		errorRequired: {
+			type: "string",
+			default: "Phone number is required",
+			label: "Required error message"
+		}
+	},
+	guideline: "The bound phone field; must be a descendant of ClientProfileRoot. Reads the saved phone from the ClientProfile entity and persists it on blur via $actions.identity.clientProfileUpdate({ phone }). Composes the reusable PhoneField particle."
+});
+/**
+* Renders the bound phone field by composing the reusable `PhoneField` particle. Reads the saved
+* phone from the section context, and on a **changed** value persists only `phone` — normalized to
+* E.164 — through `$actions.identity.clientProfileUpdate({ phone })` on blur (pessimistic,
+* mirroring `EmailIdentificationControl`). While the write is in flight the field is disabled and
+* `data-fs-client-profile-phone-pending` is present so a checkout-CTA guard can block. When the
+* session reports `canEditData: false` the field renders disabled with
+* `data-fs-client-profile-phone-readonly`. Server `userErrors` are surfaced inline.
+*/
+function ClientProfilePhoneControl({ label = "Phone", country = "US", requirement = "mandatory", errorInvalid = "Invalid phone number", errorRequired = "Phone number is required", className, $actions }) {
+	const { phone: savedPhone } = useClientProfileContext();
+	const { canEditData } = useSession();
+	const readOnly = !canEditData;
+	const [draft, setDraft] = useState(savedPhone);
+	const [pending, setPending] = useState(false);
+	const [serverError, setServerError] = useState(null);
+	const prevSavedRef = useRef(savedPhone);
+	if (prevSavedRef.current !== savedPhone) {
+		prevSavedRef.current = savedPhone;
+		setDraft(savedPhone);
+	}
+	function handleValueChange(next) {
+		setDraft(next);
+		if (serverError) setServerError(null);
+	}
+	async function handleBlur() {
+		const clientProfileUpdate = $actions?.identity?.clientProfileUpdate;
+		if (!clientProfileUpdate) return;
+		if (draft === savedPhone) return;
+		const isEmpty = !draft.trim();
+		if (requirement === "mandatory" && isEmpty) return;
+		if (!isEmpty && !validatePhoneNumber(draft, country)) return;
+		const phone = isEmpty ? "" : toE164(draft, country);
+		if (phone === savedPhone) return;
+		setPending(true);
+		setServerError(null);
+		try {
+			const errors = await clientProfileUpdate({ phone }) ?? [];
+			if (errors.length > 0) setServerError(errors[0]?.message ?? null);
+		} finally {
+			setPending(false);
+		}
+	}
+	return /* @__PURE__ */ jsx("div", {
+		className,
+		"data-fs-client-profile-phone-control": "",
+		...pending ? { "data-fs-client-profile-phone-pending": "" } : {},
+		...readOnly ? { "data-fs-client-profile-phone-readonly": "" } : {},
+		children: /* @__PURE__ */ jsx(PhoneField, {
+			label,
+			country,
+			requirement,
+			errorInvalid,
+			errorRequired,
+			value: draft,
+			onValueChange: handleValueChange,
+			onBlur: handleBlur,
+			isDisabled: pending || readOnly,
+			invalid: serverError != null || void 0,
+			error: serverError ?? void 0
+		})
+	});
+}
+const ClientProfile = {
+	Root: ClientProfileRoot,
+	PhoneControl: ClientProfilePhoneControl
+};
+//#endregion
+export { ClientProfile, ClientProfilePhoneControl, ClientProfilePhoneControlDefinition, ClientProfileRoot, ClientProfileRootDefinition };
+
+//# sourceMappingURL=client-profile.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"client-profile.js","names":[],"sources":["../../../src/matter/client-profile/client-profile.tsx"],"sourcesContent":["'use client';\n\nimport { defineComponent } from '@vtex/fs-core';\nimport { createContext, type ReactNode, useContext, useMemo, useRef, useState } from 'react';\nimport type { PhoneCountry } from '../../particles/phone-field/phone-field.js';\nimport { PhoneField, toE164, validatePhoneNumber } from '../../particles/phone-field/phone-field.js';\nimport type { ComponentActions } from '../../sdk/actions/types.js';\nimport { useDataOverride } from '../../sdk/data/data-override-context.js';\nimport { useSession } from '../session/session.js';\n\n/**\n * The `client-profile` section matter (per ADR-0011: a matter is decomposed by DATA OWNERSHIP, not\n * per field). The shopper-profile fields recorded on the cart's `clientProfileData` live on the User\n * Identity `ClientProfile` entity — a SIBLING of `Cart`, not nested under it. They are read through\n * `Query.clientProfile` and written through the shared `$actions.identity.clientProfileUpdate`\n * action, which performs a partial write that leaves the fields it is not given untouched.\n *\n * This matter wires only `phone`: a `ClientProfilePhoneControl` that composes the reusable,\n * business-agnostic `PhoneField` particle (reused later in MyAccount / extensions; the binding here\n * owns the data source and persistence). Room is kept for future profile Controls on the same Root.\n * Reads follow the colocated-fragment Root pattern (ADR-0006, fetchStrategy 'reactive'), mirroring\n * `EmailIdentificationControl`; writes flow through `$actions.identity` (ADR-0010). The write is\n * pessimistic (awaits the mutation) and is dispatched on blur — form-bound saving via the profile-form\n * CTA is a follow-up, not implemented here.\n */\n\n// ---------------------------------------------------------------------------\n// GraphQL Fragment — colocated on the ClientProfile sibling entity (ADR-0011)\n// ---------------------------------------------------------------------------\n\nconst fragment = /* GraphQL */ `\n  fragment ClientProfilePhoneData on Query {\n    clientProfile {\n      __typename\n      id\n      phone\n    }\n  }\n`;\n\n// ---------------------------------------------------------------------------\n// Raw data shape of the section fragment\n// ---------------------------------------------------------------------------\n\n/** The `$data` slice forwarded by the reactive runtime — the `ClientProfile` sibling entity. */\nexport type ClientProfileData = {\n  clientProfile?: {\n    phone?: string | null;\n  } | null;\n} | null;\n\n// ---------------------------------------------------------------------------\n// Context — the Root publishes the seeded profile values to its Controls\n// ---------------------------------------------------------------------------\n\nexport type ClientProfileContextValue = Readonly<{\n  /** Current value of each profile field, seeded from the ClientProfile entity (null → empty). */\n  phone: string;\n}>;\n\nconst CLIENT_PROFILE_UNSET = Symbol('ClientProfileContextUnset');\n\nconst ClientProfileContext = createContext<ClientProfileContextValue | typeof CLIENT_PROFILE_UNSET>(\n  CLIENT_PROFILE_UNSET,\n);\n\nfunction useClientProfileContext(): ClientProfileContextValue {\n  const ctx = useContext(ClientProfileContext);\n  if (ctx === CLIENT_PROFILE_UNSET) {\n    throw new Error('A client-profile Control must be used inside a ClientProfileRoot.');\n  }\n  return ctx;\n}\n\n// ---------------------------------------------------------------------------\n// Root\n// ---------------------------------------------------------------------------\n\nexport type ClientProfileRootProps = {\n  /** ClientProfile entity slice forwarded by the reactive runtime (value of the section fragment). */\n  $data?: ClientProfileData;\n  className?: string;\n  children?: ReactNode;\n};\n\nexport const ClientProfileRootDefinition = defineComponent<ClientProfileRootProps>({\n  name: 'ClientProfileRoot',\n  importPath: '@vtex/faststore/components',\n  component: ClientProfileRoot,\n  fragment,\n  fetchStrategy: 'reactive',\n  providesContext: 'client-profile',\n  requiresContext: 'session',\n  editor: { label: 'Client Profile Root', category: 'identity' },\n  schema: {},\n  guideline:\n    'Binding provider for the shopper-profile section; reads the profile fields (today: phone) from the ClientProfile entity (Query.clientProfile) and exposes them to its Controls. Writes flow through $actions.identity.clientProfileUpdate. Must be inside SessionRoot. Wrap a ClientProfilePhoneControl.',\n});\n\n/**\n * Renders the client-profile section Root: reads `$data` (the `ClientProfile` sibling entity), seeds\n * the profile values from the colocated fragment, and publishes a section context. It also reads\n * `useSession()` — which enforces the `SessionRoot` ancestor. Writes are owned by the Control's\n * `$actions.identity` (ADR-0010); the Root only supplies the pre-fill.\n */\nexport function ClientProfileRoot({ $data: $dataProp, className, children }: ClientProfileRootProps) {\n  const $data = useDataOverride($dataProp);\n  // Reads identification state and, as a side effect, throws when rendered outside <SessionRoot>.\n  useSession();\n\n  const phone = $data?.clientProfile?.phone ?? '';\n\n  const contextValue = useMemo<ClientProfileContextValue>(() => ({ phone }), [phone]);\n\n  return (\n    <ClientProfileContext value={contextValue}>\n      <div className={className} data-fs-client-profile-root=\"\">\n        {children}\n      </div>\n    </ClientProfileContext>\n  );\n}\n\n// ---------------------------------------------------------------------------\n// Phone Control\n// ---------------------------------------------------------------------------\n\ntype PhoneFieldRequirement = 'mandatory' | 'optional' | 'hidden';\n\nexport type ClientProfilePhoneControlProps = {\n  /** Visible field label. */\n  label?: string;\n  /** Selects the phone mask and validation rule. */\n  country?: PhoneCountry;\n  /** Controls field visibility and required validation. */\n  requirement?: PhoneFieldRequirement;\n  /** Error string shown when the input format is invalid. */\n  errorInvalid?: string;\n  /** Error string shown when the mandatory field is left empty. */\n  errorRequired?: string;\n  className?: string;\n  /** Injected by the compiler from `actions: { identity: ['clientProfileUpdate'] }`; the write surface. */\n  $actions?: ComponentActions;\n};\n\nexport const ClientProfilePhoneControlDefinition = defineComponent<ClientProfilePhoneControlProps>({\n  name: 'ClientProfilePhoneControl',\n  importPath: '@vtex/faststore/components',\n  component: ClientProfilePhoneControl,\n  requiresContext: 'client-profile',\n  actions: { identity: ['clientProfileUpdate'] },\n  editor: { label: 'Client Profile Phone Control', category: 'identity' },\n  schema: {\n    label: { type: 'string', default: 'Phone', label: 'Label' },\n    country: { type: 'string', default: 'US', label: 'Country (US or BR)' },\n    requirement: { type: 'string', default: 'mandatory', label: 'Requirement' },\n    errorInvalid: { type: 'string', default: 'Invalid phone number', label: 'Invalid error message' },\n    errorRequired: { type: 'string', default: 'Phone number is required', label: 'Required error message' },\n  },\n  guideline:\n    'The bound phone field; must be a descendant of ClientProfileRoot. Reads the saved phone from the ClientProfile entity and persists it on blur via $actions.identity.clientProfileUpdate({ phone }). Composes the reusable PhoneField particle.',\n});\n\n/**\n * Renders the bound phone field by composing the reusable `PhoneField` particle. Reads the saved\n * phone from the section context, and on a **changed** value persists only `phone` — normalized to\n * E.164 — through `$actions.identity.clientProfileUpdate({ phone })` on blur (pessimistic,\n * mirroring `EmailIdentificationControl`). While the write is in flight the field is disabled and\n * `data-fs-client-profile-phone-pending` is present so a checkout-CTA guard can block. When the\n * session reports `canEditData: false` the field renders disabled with\n * `data-fs-client-profile-phone-readonly`. Server `userErrors` are surfaced inline.\n */\nexport function ClientProfilePhoneControl({\n  label = 'Phone',\n  country = 'US',\n  requirement = 'mandatory',\n  errorInvalid = 'Invalid phone number',\n  errorRequired = 'Phone number is required',\n  className,\n  $actions,\n}: ClientProfilePhoneControlProps) {\n  const { phone: savedPhone } = useClientProfileContext();\n  // VTEX refuses profile edits for an identified-but-unauthenticated claimed profile; render the\n  // field read-only instead of accepting a write that is doomed server-side (mirrors\n  // EmailIdentificationControl).\n  const { canEditData } = useSession();\n  const readOnly = !canEditData;\n  const [draft, setDraft] = useState(savedPhone);\n  const [pending, setPending] = useState(false);\n  const [serverError, setServerError] = useState<string | null>(null);\n\n  // Re-seed the local draft when the saved value changes (e.g. cache update after a write, or a\n  // logged-in shopper's profile resolving). Like the email control's pre-fill sync, this overwrites\n  // any in-progress draft — the profile is the source of truth when it changes.\n  const prevSavedRef = useRef(savedPhone);\n  if (prevSavedRef.current !== savedPhone) {\n    // react-doctor-disable-next-line no-ref-current-in-render -- paired with the setDraft call right below, both replay together\n    prevSavedRef.current = savedPhone;\n    setDraft(savedPhone);\n  }\n\n  function handleValueChange(next: string) {\n    setDraft(next);\n    if (serverError) setServerError(null);\n  }\n\n  async function handleBlur() {\n    const clientProfileUpdate = $actions?.identity?.clientProfileUpdate;\n    if (!clientProfileUpdate) return;\n    // Untouched → nothing to persist.\n    if (draft === savedPhone) return;\n    // Client-side invalid → skip the write and let the PhoneField's inline error stand; don't\n    // rely on server userErrors for a value the mask/validator already rejects. Mirrors the\n    // validity the PhoneField particle computes on blur (mandatory-empty or bad format).\n    const isEmpty = !draft.trim();\n    if (requirement === 'mandatory' && isEmpty) return;\n    if (!isEmpty && !validatePhoneNumber(draft, country)) return;\n    const phone = isEmpty ? '' : toE164(draft, country);\n    // Unchanged after normalization (e.g. the saved \"+12015551234\" re-typed as \"2015551234\") →\n    // nothing to persist either.\n    if (phone === savedPhone) return;\n\n    setPending(true);\n    setServerError(null);\n    try {\n      const errors = (await clientProfileUpdate({ phone })) ?? [];\n      if (errors.length > 0) setServerError(errors[0]?.message ?? null);\n    } finally {\n      setPending(false);\n    }\n  }\n\n  return (\n    <div\n      className={className}\n      data-fs-client-profile-phone-control=\"\"\n      {...(pending ? { 'data-fs-client-profile-phone-pending': '' } : {})}\n      {...(readOnly ? { 'data-fs-client-profile-phone-readonly': '' } : {})}\n    >\n      <PhoneField\n        label={label}\n        country={country}\n        requirement={requirement}\n        errorInvalid={errorInvalid}\n        errorRequired={errorRequired}\n        value={draft}\n        onValueChange={handleValueChange}\n        onBlur={handleBlur}\n        isDisabled={pending || readOnly}\n        invalid={serverError != null || undefined}\n        error={serverError ?? undefined}\n      />\n    </div>\n  );\n}\n\n// ---------------------------------------------------------------------------\n// Namespace export\n// ---------------------------------------------------------------------------\n\nexport const ClientProfile = {\n  Root: ClientProfileRoot,\n  PhoneControl: ClientProfilePhoneControl,\n};\n"],"mappings":"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"}

package/dist/matter/client-profile-form/client-profile-form.d.ts

@@ -0,0 +1,126 @@
+import { ComponentDefinition } from "../../core/dist/define-component.js";
+import "../../core/dist/index.js";
+import { ComponentActions } from "../../sdk/actions/types.js";
+import { PhoneCountry } from "../../particles/phone-field/phone-field.js";
+import { ReactNode } from "react";
+//#region src/matter/client-profile-form/client-profile-form.d.ts
+/** The `$data` slice forwarded by the reactive runtime — both identity sibling entities. */
+export type ClientProfileFormData = {
+  clientProfile?: {
+    email?: string | null;
+    firstName?: string | null;
+    lastName?: string | null;
+    phone?: string | null;
+    document?: string | null;
+  } | null;
+  clientPreferences?: {
+    optinNewsLetter?: boolean | null;
+    savePersonalData?: boolean | null;
+  } | null;
+} | null;
+export type ClientProfileFormRootProps = {
+  /** Phone mask/validation country, provided to the phone leaf via context. */
+  country?: PhoneCountry;
+  /** Locale document type; the document leaf renders only when supported. Provided via context. */
+  documentType?: string;
+  className?: string;
+  children?: ReactNode;
+  /** `ClientProfileFormData` slice forwarded by the reactive runtime. */
+  $data?: ClientProfileFormData;
+  /** Compiler-injected action surface; carries `identity.clientProfileUpdate` / `clientPreferencesUpdate`. */
+  $actions?: ComponentActions;
+};
+export type ClientProfileFormFieldsetProps = {
+  /** Visible legend; omitted (no title) when unset. */
+  legend?: string;
+  /** Value emitted on `data-fs-client-profile-form-section` for scoped styling (e.g. `profile`). */
+  section?: string;
+  className?: string;
+  children?: ReactNode;
+};
+type LabelledFieldProps = {
+  label?: string;
+  className?: string;
+};
+export type ClientProfileFormEmailFieldProps = LabelledFieldProps;
+export type ClientProfileFormFirstNameFieldProps = LabelledFieldProps;
+export type ClientProfileFormLastNameFieldProps = LabelledFieldProps;
+export type ClientProfileFormPhoneFieldProps = LabelledFieldProps;
+export type ClientProfileFormDocumentFieldProps = LabelledFieldProps;
+export type ClientProfileFormNewsletterCheckboxProps = LabelledFieldProps;
+export type ClientProfileFormSavePersonalDataCheckboxProps = LabelledFieldProps;
+export type ClientProfileFormErrorProps = {
+  className?: string;
+};
+export type ClientProfileFormConfirmationProps = {
+  message?: string;
+  className?: string;
+};
+export type ClientProfileFormSubmitButtonProps = {
+  label?: string;
+  className?: string;
+  children?: ReactNode;
+};
+export declare const ClientProfileFormRootDefinition: ComponentDefinition<ClientProfileFormRootProps>;
+export declare const ClientProfileFormFieldsetDefinition: ComponentDefinition<ClientProfileFormFieldsetProps>;
+export declare const ClientProfileFormEmailFieldDefinition: ComponentDefinition<LabelledFieldProps>;
+export declare const ClientProfileFormFirstNameFieldDefinition: ComponentDefinition<LabelledFieldProps>;
+export declare const ClientProfileFormLastNameFieldDefinition: ComponentDefinition<LabelledFieldProps>;
+export declare const ClientProfileFormPhoneFieldDefinition: ComponentDefinition<LabelledFieldProps>;
+export declare const ClientProfileFormDocumentFieldDefinition: ComponentDefinition<LabelledFieldProps>;
+export declare const ClientProfileFormNewsletterCheckboxDefinition: ComponentDefinition<LabelledFieldProps>;
+export declare const ClientProfileFormSavePersonalDataCheckboxDefinition: ComponentDefinition<LabelledFieldProps>;
+export declare const ClientProfileFormErrorDefinition: ComponentDefinition<ClientProfileFormErrorProps>;
+export declare const ClientProfileFormConfirmationDefinition: ComponentDefinition<ClientProfileFormConfirmationProps>;
+export declare const ClientProfileFormSubmitButtonDefinition: ComponentDefinition<ClientProfileFormSubmitButtonProps>;
+/**
+ * Data root + form shell. Seeds a local draft from `$data`, tracks dirty fields (background `$data`
+ * refreshes only re-seed untouched fields), runs format-only validation, and on Save dispatches the
+ * batched `clientProfileUpdate` / `clientPreferencesUpdate` (touched fields only), showing the
+ * confirmation on success. Provides everything the field leaves need via context; renders a `<form>`
+ * around its children.
+ *
+ * It publishes nothing. A finished press is not announced, so no section collapses as a result and
+ * nothing outside this form can react to it. Whether a checkout sequences on a completed form is left to
+ * the flow-of-steps RFC (#611).
+ */
+export declare function ClientProfileFormRoot({ country, documentType, className, children, $data: $dataProp, $actions }: ClientProfileFormRootProps): import("react/jsx-runtime").JSX.Element;
+export declare function ClientProfileFormFieldset({ legend, section, className, children }: ClientProfileFormFieldsetProps): import("react/jsx-runtime").JSX.Element;
+export declare function ClientProfileFormEmailField({ label, className }: ClientProfileFormEmailFieldProps): import("react/jsx-runtime").JSX.Element;
+export declare function ClientProfileFormFirstNameField({ label, className }: ClientProfileFormFirstNameFieldProps): import("react/jsx-runtime").JSX.Element;
+export declare function ClientProfileFormLastNameField({ label, className }: ClientProfileFormLastNameFieldProps): import("react/jsx-runtime").JSX.Element;
+export declare function ClientProfileFormPhoneField({ label, className }: ClientProfileFormPhoneFieldProps): import("react/jsx-runtime").JSX.Element;
+export declare function ClientProfileFormDocumentField({ label, className }: ClientProfileFormDocumentFieldProps): import("react/jsx-runtime").JSX.Element | null;
+export declare function ClientProfileFormNewsletterCheckbox({ label, className }: ClientProfileFormNewsletterCheckboxProps): import("react/jsx-runtime").JSX.Element;
+export declare function ClientProfileFormSavePersonalDataCheckbox({ label, className }: ClientProfileFormSavePersonalDataCheckboxProps): import("react/jsx-runtime").JSX.Element;
+export declare function ClientProfileFormError({ className }: ClientProfileFormErrorProps): import("react/jsx-runtime").JSX.Element | null;
+export declare function ClientProfileFormConfirmation({ message, className }: ClientProfileFormConfirmationProps): import("react/jsx-runtime").JSX.Element | null;
+export declare function ClientProfileFormSubmitButton({ label, className, children }: ClientProfileFormSubmitButtonProps): import("react/jsx-runtime").JSX.Element | null;
+export declare const ClientProfileForm: {
+  Root: typeof ClientProfileFormRoot;
+  RootDefinition: ComponentDefinition<ClientProfileFormRootProps>;
+  Fieldset: typeof ClientProfileFormFieldset;
+  FieldsetDefinition: ComponentDefinition<ClientProfileFormFieldsetProps>;
+  EmailField: typeof ClientProfileFormEmailField;
+  EmailFieldDefinition: ComponentDefinition<LabelledFieldProps>;
+  FirstNameField: typeof ClientProfileFormFirstNameField;
+  FirstNameFieldDefinition: ComponentDefinition<LabelledFieldProps>;
+  LastNameField: typeof ClientProfileFormLastNameField;
+  LastNameFieldDefinition: ComponentDefinition<LabelledFieldProps>;
+  PhoneField: typeof ClientProfileFormPhoneField;
+  PhoneFieldDefinition: ComponentDefinition<LabelledFieldProps>;
+  DocumentField: typeof ClientProfileFormDocumentField;
+  DocumentFieldDefinition: ComponentDefinition<LabelledFieldProps>;
+  NewsletterCheckbox: typeof ClientProfileFormNewsletterCheckbox;
+  NewsletterCheckboxDefinition: ComponentDefinition<LabelledFieldProps>;
+  SavePersonalDataCheckbox: typeof ClientProfileFormSavePersonalDataCheckbox;
+  SavePersonalDataCheckboxDefinition: ComponentDefinition<LabelledFieldProps>;
+  Error: typeof ClientProfileFormError;
+  ErrorDefinition: ComponentDefinition<ClientProfileFormErrorProps>;
+  Confirmation: typeof ClientProfileFormConfirmation;
+  ConfirmationDefinition: ComponentDefinition<ClientProfileFormConfirmationProps>;
+  SubmitButton: typeof ClientProfileFormSubmitButton;
+  SubmitButtonDefinition: ComponentDefinition<ClientProfileFormSubmitButtonProps>;
+};
+//#endregion
+//# sourceMappingURL=client-profile-form.d.ts.map