@vtex/faststore 0.0.4 → 0.0.6

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

@@ -0,0 +1,299 @@
+"use client";
+import { defineComponent } from "../../core/dist/define-component.js";
+import "../../core/dist/index.js";
+import { Checkbox } from "../../particles/checkbox/checkbox.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 { Icon } from "../../particles/icon/icon.js";
+import { Fieldset } from "../../particles/fieldset/fieldset.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 { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { useFormContext } from "react-hook-form";
+//#region src/matter/client-preferences/client-preferences-fieldset.tsx
+/**
+* `ClientPreferencesFieldset` — the composable, one-Save write of the `ClientPreferences` sibling
+* entity (RFC: Composable Entity Forms, `Proposal > Design > The fieldset`). It registers itself with
+* the enclosing `FormRoot` under the `clientPreferences` namespace and dispatches
+* `$actions.identity.clientPreferencesUpdate` for its own submit slot; it renders no `<form>` of its
+* own.
+*
+* `ClientPreferencesRoot` (`client-preferences.tsx`) already reads both flags and writes on toggle; this
+* fieldset is a second, batched write timing for the same two flags. To keep the two from compiling into
+* each other's container, the shipped self-persisting matter's context is renamed to
+* `client-preferences-toggle`, freeing `client-preferences` for this fieldset. Placing
+* `NewsletterOptInControl` inside this fieldset, or `ClientPreferencesNewsletterControl` inside
+* `ClientPreferencesRoot`, is therefore a build failure rather than a surprise write.
+*/
+const fragment = `
+  fragment ClientPreferencesFieldsetData on Query {
+    clientPreferences {
+      __typename
+      id
+      optinNewsLetter
+      savePersonalData
+    }
+  }
+`;
+/** No control publishes a rule today (Decision 6) — kept as a stable empty object so the context
+* value's identity does not churn on every render. */
+const NO_RULES = {};
+/**
+* Rows `ClientPreferencesFieldsetSkeleton` draws when nobody says otherwise: one per consent flag in
+* the full anatomy. It is a default and not a derivation, because the composed children are opaque
+* here. A page that composes only one control sets `skeletonCount` to 1, or the form jumps by a row
+* when the controls take the skeleton's place.
+*/
+const CLIENT_PREFERENCES_SKELETON_ROWS = 2;
+const CLIENT_PREFERENCES_FIELDSET_UNSET = Symbol("ClientPreferencesFieldsetContextUnset");
+const ClientPreferencesFieldsetContext = createContext(CLIENT_PREFERENCES_FIELDSET_UNSET);
+function useClientPreferencesFieldsetContext() {
+	const ctx = useContext(ClientPreferencesFieldsetContext);
+	if (ctx === CLIENT_PREFERENCES_FIELDSET_UNSET) throw new Error("ClientPreferencesFieldset controls must be used inside ClientPreferencesFieldset.");
+	return ctx;
+}
+const ClientPreferencesFieldsetDefinition = defineComponent({
+	name: "ClientPreferencesFieldset",
+	importPath: "@vtex/faststore/components",
+	component: ClientPreferencesFieldset,
+	fragment,
+	fetchStrategy: "reactive",
+	skeleton: ClientPreferencesFieldsetSkeleton,
+	requiresContext: ["form", "session"],
+	providesContext: "client-preferences",
+	actions: { identity: ["clientPreferencesUpdate"] },
+	editor: {
+		label: "Client Preferences Fieldset",
+		category: "identity"
+	},
+	schema: {
+		skeletonCount: {
+			type: "number",
+			default: 2,
+			label: "Skeleton rows"
+		},
+		loadingLabel: {
+			type: "string",
+			default: "Loading your preferences",
+			label: "Loading announcement"
+		},
+		loadedLabel: {
+			type: "string",
+			default: "Your preferences are ready",
+			label: "Loaded announcement"
+		},
+		groupLabel: {
+			type: "string",
+			default: "Your preferences",
+			label: "Accessible group name"
+		}
+	},
+	guideline: "Registers a batched write of the ClientPreferences entity with the enclosing FormRoot; renders one Fieldset.Root and no <form>. Distinct from ClientPreferencesRoot (matter/client-preferences), which writes on toggle and requires client-preferences-toggle — the two cannot compile into each other's container. Must be inside a FormRoot with a SessionRoot ancestor. Compose ClientPreferencesNewsletterControl and/or ClientPreferencesSavePersonalDataControl as children. The controls mount only once the preferences have 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 flags the shopper changed. groupLabel names the group as its accessible name; blank emits no aria-label, and a composed FieldsetLegend wins over it."
+});
+const ClientPreferencesNewsletterControlDefinition = defineComponent({
+	name: "ClientPreferencesNewsletterControl",
+	importPath: "@vtex/faststore/components",
+	component: ClientPreferencesNewsletterControl,
+	requiresContext: "client-preferences",
+	providesContext: "field",
+	editor: {
+		label: "Client Preferences Newsletter Control",
+		category: "identity"
+	},
+	schema: { label: {
+		type: "string",
+		label: "Label"
+	} },
+	guideline: "The bound newsletter opt-in control; must be a descendant of ClientPreferencesFieldset. Renders Field.Root > Field.Label > Field.Checkbox by default, or the composed children in the author's own order. Defaults to unchecked."
+});
+const ClientPreferencesSavePersonalDataControlDefinition = defineComponent({
+	name: "ClientPreferencesSavePersonalDataControl",
+	importPath: "@vtex/faststore/components",
+	component: ClientPreferencesSavePersonalDataControl,
+	requiresContext: "client-preferences",
+	providesContext: "field",
+	editor: {
+		label: "Client Preferences Save Personal Data Control",
+		category: "identity"
+	},
+	schema: { label: {
+		type: "string",
+		label: "Label"
+	} },
+	guideline: "The bound save-personal-data opt-in control; must be a descendant of ClientPreferencesFieldset. Renders Field.Root > Field.Label > Field.Checkbox by default, or the composed children in the author's own order. Defaults to unchecked."
+});
+/**
+* Registers a batched write of the `ClientPreferences` entity with the enclosing `FormRoot`
+* (`registerFieldset`, namespace `clientPreferences`) 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 `ClientPreferencesFieldsetSkeleton` (Decision 5).
+* `dispatch` and `toPayload` are `useCallback([])`-stable and read `$actions` 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 checkboxes
+* would mount seeded unchecked before the shopper's saved consent arrives. `useSeedAdoption` re-seeds a
+* clean checkbox with `defaultValue` on every render, but once it turns dirty no later seed ever
+* reaches it again: a shopper who toggles it before the real consent arrives locks that unchecked
+* seed in for good, and even a shopper who does not toggle it sees the checkbox flash to the saved
+* value. `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 ClientPreferencesFieldset({ skeletonCount = CLIENT_PREFERENCES_SKELETON_ROWS, loadingLabel = "Loading your preferences", loadedLabel = "Your preferences are ready", groupLabel = "Your preferences", className, children, $data: $dataProp, $actions: $actionsProp }) {
+	useNoAncestorFieldset("ClientPreferencesFieldset");
+	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,
+		readOnly,
+		getFieldState
+	});
+	useEffect(() => {
+		latest.current = {
+			$actions,
+			readOnly,
+			getFieldState
+		};
+	}, [
+		$actions,
+		readOnly,
+		getFieldState
+	]);
+	const { registry: fieldsetRegistry, getFieldNames } = useFieldsetFieldNames("clientPreferences");
+	const dispatch = useCallback(async (payload) => {
+		if (latest.current.readOnly) throw new Error("ClientPreferencesFieldset cannot dispatch while the session is read-only.");
+		const update = latest.current.$actions?.identity?.clientPreferencesUpdate;
+		if (!update) throw new Error("ClientPreferencesFieldset requires $actions.identity.clientPreferencesUpdate.");
+		return update(payload);
+	}, []);
+	const toPayload = useCallback((values) => {
+		const { getFieldState } = latest.current;
+		const isDirty = (key) => getFieldState(`clientPreferences.${key}`).isDirty;
+		const payload = {};
+		if ("optinNewsLetter" in values && isDirty("optinNewsLetter")) payload.optinNewsLetter = Boolean(values.optinNewsLetter);
+		if ("savePersonalData" in values && isDirty("savePersonalData")) payload.savePersonalData = Boolean(values.savePersonalData);
+		return payload;
+	}, []);
+	useEffect(() => registerFieldset({
+		namespace: "clientPreferences",
+		getFieldNames,
+		dispatch,
+		toPayload,
+		label: "client-preferences"
+	}), [
+		registerFieldset,
+		getFieldNames,
+		dispatch,
+		toPayload
+	]);
+	const saved = useMemo(() => ({
+		optinNewsLetter: Boolean($data?.optinNewsLetter ?? false),
+		savePersonalData: Boolean($data?.savePersonalData ?? false)
+	}), [$data]);
+	const contextValue = useMemo(() => ({
+		namespace: "clientPreferences",
+		saved,
+		readOnly,
+		rules: NO_RULES
+	}), [saved, readOnly]);
+	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-preferences-fieldset": "",
+		...resolved ? {} : { "data-fs-client-preferences-fieldset-pending": "" },
+		...readOnly ? { "data-fs-client-preferences-fieldset-readonly": "" } : {},
+		children: [resolved ? /* @__PURE__ */ jsx(FieldsetFieldContext.Provider, {
+			value: fieldsetRegistry,
+			children: /* @__PURE__ */ jsx(ClientPreferencesFieldsetContext.Provider, {
+				value: contextValue,
+				children
+			})
+		}) : /* @__PURE__ */ jsx(ClientPreferencesFieldsetSkeleton, { count: skeletonCount }), /* @__PURE__ */ jsx("output", {
+			"aria-live": "polite",
+			"data-fs-client-preferences-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 ClientPreferencesFieldsetSkeleton({ count = CLIENT_PREFERENCES_SKELETON_ROWS, className, ...props }) {
+	return /* @__PURE__ */ jsx("div", {
+		...props,
+		className,
+		"data-fs-client-preferences-fieldset-skeleton": "",
+		"aria-hidden": "true",
+		children: Array.from({ length: count }, (_, i) => /* @__PURE__ */ jsx("span", { "data-fs-client-preferences-fieldset-skeleton-field": "" }, i))
+	});
+}
+ClientPreferencesFieldset.Skeleton = ClientPreferencesFieldsetSkeleton;
+function PreferenceControl({ fieldKey, attr, defaultLabel, label, className, children }) {
+	const { namespace, saved, readOnly, rules } = useClientPreferencesFieldsetContext();
+	const name = useFieldsetField(namespace, fieldKey);
+	const resolvedLabel = label ?? defaultLabel;
+	return /* @__PURE__ */ jsx(FieldBinding, {
+		name,
+		label: resolvedLabel,
+		defaultValue: saved[fieldKey],
+		rule: rules[fieldKey],
+		disabled: readOnly,
+		children: /* @__PURE__ */ jsx(Field.Root, {
+			className,
+			"data-fs-client-preferences-fieldset-field": attr,
+			children: children ?? /* @__PURE__ */ jsxs(Field.Label, { children: [/* @__PURE__ */ jsx(Field.Checkbox, { children: /* @__PURE__ */ jsx(Checkbox.Indicator, { children: /* @__PURE__ */ jsx(Icon, { name: "checked" }) }) }), resolvedLabel] })
+		})
+	});
+}
+function ClientPreferencesNewsletterControl({ label, className, children }) {
+	return /* @__PURE__ */ jsx(PreferenceControl, {
+		fieldKey: "optinNewsLetter",
+		attr: "newsletter",
+		defaultLabel: "Email me with news and offers",
+		label,
+		className,
+		children
+	});
+}
+function ClientPreferencesSavePersonalDataControl({ label, className, children }) {
+	return /* @__PURE__ */ jsx(PreferenceControl, {
+		fieldKey: "savePersonalData",
+		attr: "save-personal-data",
+		defaultLabel: "Save my information for next time",
+		label,
+		className,
+		children
+	});
+}
+//#endregion
+export { ClientPreferencesFieldset, ClientPreferencesFieldsetDefinition, ClientPreferencesFieldsetSkeleton, ClientPreferencesNewsletterControl, ClientPreferencesNewsletterControlDefinition, ClientPreferencesSavePersonalDataControl, ClientPreferencesSavePersonalDataControlDefinition };
+
+//# sourceMappingURL=client-preferences-fieldset.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"client-preferences-fieldset.js","names":[],"sources":["../../../src/matter/client-preferences/client-preferences-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 { Checkbox } from '../../particles/checkbox/checkbox.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 { Icon } from '../../particles/icon/icon.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 { ClientPreferenceKey, ClientPreferencesUpdateInput } from '../../sdk/identity/operations.js';\nimport { useSession } from '../session/session.js';\n\n/**\n * `ClientPreferencesFieldset` — the composable, one-Save write of the `ClientPreferences` sibling\n * entity (RFC: Composable Entity Forms, `Proposal > Design > The fieldset`). It registers itself with\n * the enclosing `FormRoot` under the `clientPreferences` namespace and dispatches\n * `$actions.identity.clientPreferencesUpdate` for its own submit slot; it renders no `<form>` of its\n * own.\n *\n * `ClientPreferencesRoot` (`client-preferences.tsx`) already reads both flags and writes on toggle; this\n * fieldset is a second, batched write timing for the same two flags. To keep the two from compiling into\n * each other's container, the shipped self-persisting matter's context is renamed to\n * `client-preferences-toggle`, freeing `client-preferences` for this fieldset. Placing\n * `NewsletterOptInControl` inside this fieldset, or `ClientPreferencesNewsletterControl` inside\n * `ClientPreferencesRoot`, is therefore a build failure rather than a surprise write.\n */\n\n// ---------------------------------------------------------------------------\n// GraphQL Fragment — colocated on the fieldset, its own data root\n// ---------------------------------------------------------------------------\n\nconst fragment = /* GraphQL */ `\n  fragment ClientPreferencesFieldsetData 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, unwrapped. */\nexport type ClientPreferencesFieldsetData = {\n  optinNewsLetter?: boolean | null;\n  savePersonalData?: boolean | null;\n} | null;\n\n/** What the fieldset publishes to its controls. Carries no live value — react-hook-form owns those. */\ntype ClientPreferencesFieldsetContextValue = Readonly<{\n  namespace: 'clientPreferences';\n  /** Seeds, resolved from `$data`. `null` (not chosen yet) reads as unchecked, per the opt-in default. */\n  saved: Readonly<Record<ClientPreferenceKey, boolean>>;\n  /** True when the session reports `canEditData: false`. */\n  readOnly: boolean;\n  /** The fieldset's own validation rules, per key. Present and empty today (Decision 6). */\n  rules: Readonly<Partial<Record<ClientPreferenceKey, FieldRule>>>;\n}>;\n\n/** No control publishes a rule today (Decision 6) — kept as a stable empty object so the context\n * value's identity does not churn on every render. */\nconst NO_RULES: Readonly<Partial<Record<ClientPreferenceKey, FieldRule>>> = {};\n\n/**\n * Rows `ClientPreferencesFieldsetSkeleton` draws when nobody says otherwise: one per consent flag in\n * the full anatomy. It is a default and not a derivation, because the composed children are opaque\n * here. A page that composes only one control sets `skeletonCount` to 1, or the form jumps by a row\n * when the controls take the skeleton's place.\n */\nconst CLIENT_PREFERENCES_SKELETON_ROWS = 2;\n\nconst CLIENT_PREFERENCES_FIELDSET_UNSET = Symbol('ClientPreferencesFieldsetContextUnset');\n\nconst ClientPreferencesFieldsetContext = createContext<\n  ClientPreferencesFieldsetContextValue | typeof CLIENT_PREFERENCES_FIELDSET_UNSET\n>(CLIENT_PREFERENCES_FIELDSET_UNSET);\n\nfunction useClientPreferencesFieldsetContext(): ClientPreferencesFieldsetContextValue {\n  const ctx = useContext(ClientPreferencesFieldsetContext);\n  if (ctx === CLIENT_PREFERENCES_FIELDSET_UNSET) {\n    throw new Error('ClientPreferencesFieldset controls must be used inside ClientPreferencesFieldset.');\n  }\n  return ctx;\n}\n\n// ---------------------------------------------------------------------------\n// Props\n// ---------------------------------------------------------------------------\n\nexport type ClientPreferencesFieldsetProps = {\n  /** Placeholder rows the loading skeleton draws. Set it to the number of controls composed here. */\n  skeletonCount?: number;\n  /** Announced politely while the preferences resolve. 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  /** `ClientPreferencesFieldsetData` slice forwarded by the reactive runtime. */\n  $data?: ClientPreferencesFieldsetData;\n  /** Compiler-injected; carries `identity.clientPreferencesUpdate`. */\n  $actions?: ComponentActions;\n};\n\ntype PreferenceControlProps = { label?: string; className?: string; children?: ReactNode };\n\nexport type ClientPreferencesNewsletterControlProps = PreferenceControlProps;\nexport type ClientPreferencesSavePersonalDataControlProps = PreferenceControlProps;\n\n// ---------------------------------------------------------------------------\n// Definitions\n// ---------------------------------------------------------------------------\n\nexport const ClientPreferencesFieldsetDefinition = defineComponent<ClientPreferencesFieldsetProps>({\n  name: 'ClientPreferencesFieldset',\n  importPath: '@vtex/faststore/components',\n  component: ClientPreferencesFieldset,\n  fragment,\n  fetchStrategy: 'reactive',\n  skeleton: ClientPreferencesFieldsetSkeleton,\n  requiresContext: ['form', 'session'],\n  providesContext: 'client-preferences',\n  actions: { identity: ['clientPreferencesUpdate'] },\n  editor: { label: 'Client Preferences Fieldset', category: 'identity' },\n  schema: {\n    skeletonCount: { type: 'number', default: 2, label: 'Skeleton rows' },\n    loadingLabel: { type: 'string', default: 'Loading your preferences', label: 'Loading announcement' },\n    loadedLabel: { type: 'string', default: 'Your preferences are ready', label: 'Loaded announcement' },\n    groupLabel: { type: 'string', default: 'Your preferences', label: 'Accessible group name' },\n  },\n  guideline:\n    \"Registers a batched write of the ClientPreferences entity with the enclosing FormRoot; renders one Fieldset.Root and no <form>. Distinct from ClientPreferencesRoot (matter/client-preferences), which writes on toggle and requires client-preferences-toggle — the two cannot compile into each other's container. Must be inside a FormRoot with a SessionRoot ancestor. Compose ClientPreferencesNewsletterControl and/or ClientPreferencesSavePersonalDataControl as children. The controls mount only once the preferences have 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 flags 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 ClientPreferencesNewsletterControlDefinition = defineComponent<ClientPreferencesNewsletterControlProps>({\n  name: 'ClientPreferencesNewsletterControl',\n  importPath: '@vtex/faststore/components',\n  component: ClientPreferencesNewsletterControl,\n  requiresContext: 'client-preferences',\n  providesContext: 'field',\n  editor: { label: 'Client Preferences Newsletter 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  },\n  guideline:\n    \"The bound newsletter opt-in control; must be a descendant of ClientPreferencesFieldset. Renders Field.Root > Field.Label > Field.Checkbox by default, or the composed children in the author's own order. Defaults to unchecked.\",\n});\n\nexport const ClientPreferencesSavePersonalDataControlDefinition =\n  defineComponent<ClientPreferencesSavePersonalDataControlProps>({\n    name: 'ClientPreferencesSavePersonalDataControl',\n    importPath: '@vtex/faststore/components',\n    component: ClientPreferencesSavePersonalDataControl,\n    requiresContext: 'client-preferences',\n    providesContext: 'field',\n    editor: { label: 'Client Preferences Save Personal Data 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    },\n    guideline:\n      \"The bound save-personal-data opt-in control; must be a descendant of ClientPreferencesFieldset. Renders Field.Root > Field.Label > Field.Checkbox by default, or the composed children in the author's own order. Defaults to unchecked.\",\n  });\n\n// ---------------------------------------------------------------------------\n// Fieldset root\n// ---------------------------------------------------------------------------\n\n/**\n * Registers a batched write of the `ClientPreferences` entity with the enclosing `FormRoot`\n * (`registerFieldset`, namespace `clientPreferences`) on mount, unconditionally — so this fieldset keeps\n * its original dispatch slot even while its own query is still resolving. Its children — the seed values\n * and the field-name registry its controls need — render only once the entity has resolved; until then\n * the `Fieldset.Root` carries `-pending` and renders `ClientPreferencesFieldsetSkeleton` (Decision 5).\n * `dispatch` and `toPayload` are `useCallback([])`-stable and read `$actions` through a ref, so the\n * registration effect runs exactly once per mount regardless of how often the 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 checkboxes\n * would mount seeded unchecked before the shopper's saved consent arrives. `useSeedAdoption` re-seeds a\n * clean checkbox with `defaultValue` on every render, but once it turns dirty no later seed ever\n * reaches it again: a shopper who toggles it before the real consent arrives locks that unchecked\n * seed in for good, and even a shopper who does not toggle it sees the checkbox flash to the saved\n * value. `useReactiveDataSettled` supplies\n * the missing half: the page query's own in-flight state, latched so it only ever goes pending →\n * settled. The `$data === undefined` half still carries trees with no reactive root above them, where\n * 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 ClientPreferencesFieldset({\n  skeletonCount = CLIENT_PREFERENCES_SKELETON_ROWS,\n  loadingLabel = 'Loading your preferences',\n  loadedLabel = 'Your preferences are ready',\n  groupLabel = 'Your preferences',\n  className,\n  children,\n  $data: $dataProp,\n  $actions: $actionsProp,\n}: ClientPreferencesFieldsetProps) {\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('ClientPreferencesFieldset');\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, readOnly, getFieldState });\n  useEffect(() => {\n    latest.current = { $actions, readOnly, getFieldState };\n  }, [$actions, readOnly, getFieldState]);\n\n  const { registry: fieldsetRegistry, getFieldNames } = useFieldsetFieldNames('clientPreferences');\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('ClientPreferencesFieldset cannot dispatch while the session is read-only.');\n    }\n    const update = latest.current.$actions?.identity?.clientPreferencesUpdate;\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('ClientPreferencesFieldset requires $actions.identity.clientPreferencesUpdate.');\n    return update(payload as ClientPreferencesUpdateInput);\n  }, []);\n\n  const toPayload = useCallback((values: Record<string, unknown>): Record<string, unknown> => {\n    const { getFieldState } = latest.current;\n    // FR-6: a flag is emitted only when the shopper actually toggled it. `getFieldState` is called\n    // with no second argument, which reads react-hook-form's current internal state without\n    // subscribing to it (Decision 3).\n    const isDirty = (key: ClientPreferenceKey) => getFieldState(`clientPreferences.${key}`).isDirty;\n    // Boolean() coercion is defence in depth: the bound checkbox part itself now writes its own\n    // field's typed empty value on Clear (false, not ''), but this fieldset should not depend on\n    // every caller writing a well-typed value.\n    const payload: Record<string, boolean> = {};\n    if ('optinNewsLetter' in values && isDirty('optinNewsLetter')) {\n      payload.optinNewsLetter = Boolean(values.optinNewsLetter);\n    }\n    if ('savePersonalData' in values && isDirty('savePersonalData')) {\n      payload.savePersonalData = Boolean(values.savePersonalData);\n    }\n    return payload;\n  }, []);\n\n  useEffect(\n    () =>\n      registerFieldset({\n        namespace: 'clientPreferences',\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` (`clientPreferences` → `client-preferences`) — not authored\n        // per page (Decision 2).\n        label: 'client-preferences',\n      }),\n    [registerFieldset, getFieldNames, dispatch, toPayload],\n  );\n\n  const saved = useMemo<Readonly<Record<ClientPreferenceKey, boolean>>>(\n    () => ({\n      optinNewsLetter: Boolean($data?.optinNewsLetter ?? false),\n      savePersonalData: Boolean($data?.savePersonalData ?? false),\n    }),\n    [$data],\n  );\n\n  const contextValue = useMemo<ClientPreferencesFieldsetContextValue>(\n    () => ({ namespace: 'clientPreferences', saved, readOnly, rules: NO_RULES }),\n    [saved, readOnly],\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-preferences-fieldset=\"\"\n      {...(resolved ? {} : { 'data-fs-client-preferences-fieldset-pending': '' })}\n      {...(readOnly ? { 'data-fs-client-preferences-fieldset-readonly': '' } : {})}\n    >\n      {resolved ? (\n        <FieldsetFieldContext.Provider value={fieldsetRegistry}>\n          <ClientPreferencesFieldsetContext.Provider value={contextValue}>\n            {children}\n          </ClientPreferencesFieldsetContext.Provider>\n        </FieldsetFieldContext.Provider>\n      ) : (\n        <ClientPreferencesFieldsetSkeleton count={skeletonCount} />\n      )}\n      <output aria-live=\"polite\" data-fs-client-preferences-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 ClientPreferencesFieldsetSkeleton({\n  count = CLIENT_PREFERENCES_SKELETON_ROWS,\n  className,\n  ...props\n}: ComponentPropsWithRef<'div'> & { count?: number }) {\n  return (\n    <div {...props} className={className} data-fs-client-preferences-fieldset-skeleton=\"\" aria-hidden=\"true\">\n      {Array.from({ length: count }, (_, i) => (\n        <span key={i} data-fs-client-preferences-fieldset-skeleton-field=\"\" />\n      ))}\n    </div>\n  );\n}\n\nClientPreferencesFieldset.Skeleton = ClientPreferencesFieldsetSkeleton;\n\n// ---------------------------------------------------------------------------\n// Controls\n// ---------------------------------------------------------------------------\n\nfunction PreferenceControl({\n  fieldKey,\n  attr,\n  defaultLabel,\n  label,\n  className,\n  children,\n}: {\n  fieldKey: ClientPreferenceKey;\n  attr: string;\n  defaultLabel: string;\n  label?: string;\n  className?: string;\n  children?: ReactNode;\n}) {\n  const { namespace, saved, readOnly, rules } = useClientPreferencesFieldsetContext();\n  const name = useFieldsetField(namespace, fieldKey);\n  const resolvedLabel = label ?? defaultLabel;\n\n  return (\n    <FieldBinding\n      name={name}\n      label={resolvedLabel}\n      defaultValue={saved[fieldKey]}\n      rule={rules[fieldKey]}\n      disabled={readOnly}\n    >\n      <Field.Root className={className} data-fs-client-preferences-fieldset-field={attr}>\n        {children ?? (\n          <Field.Label>\n            <Field.Checkbox>\n              <Checkbox.Indicator>\n                <Icon name=\"checked\" />\n              </Checkbox.Indicator>\n            </Field.Checkbox>\n            {resolvedLabel}\n          </Field.Label>\n        )}\n      </Field.Root>\n    </FieldBinding>\n  );\n}\n\nexport function ClientPreferencesNewsletterControl({\n  label,\n  className,\n  children,\n}: ClientPreferencesNewsletterControlProps) {\n  return (\n    <PreferenceControl\n      fieldKey=\"optinNewsLetter\"\n      attr=\"newsletter\"\n      defaultLabel=\"Email me with news and offers\"\n      label={label}\n      className={className}\n    >\n      {children}\n    </PreferenceControl>\n  );\n}\n\nexport function ClientPreferencesSavePersonalDataControl({\n  label,\n  className,\n  children,\n}: ClientPreferencesSavePersonalDataControlProps) {\n  return (\n    <PreferenceControl\n      fieldKey=\"savePersonalData\"\n      attr=\"save-personal-data\"\n      defaultLabel=\"Save my information for next time\"\n      label={label}\n      className={className}\n    >\n      {children}\n    </PreferenceControl>\n  );\n}\n"],"mappings":"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"}

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

@@ -3,12 +3,10 @@ import "../../core/dist/index.js";
 import { ComponentActions } from "../../sdk/actions/types.js";
 import { ReactNode } from "react";
 //#region src/matter/client-preferences/client-preferences.d.ts
-/** The `$data` slice forwarded by the reactive runtime — the `ClientPreferences` sibling entity. */
+/** The `$data` slice forwarded by the reactive runtime — the `ClientPreferences` sibling entity, unwrapped. */
 export type ClientPreferencesData = {
-  clientPreferences?: {
-    optinNewsLetter?: boolean | null;
-    savePersonalData?: boolean | null;
-  } | null;
+  optinNewsLetter?: boolean | null;
+  savePersonalData?: boolean | null;
 } | null;
 export type ClientPreferencesRootProps = {
   /** `Query` slice forwarded by the reactive runtime (value of the section fragment). */

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

@@ -1,12 +1,12 @@
 "use client";
 import { defineComponent } from "../../core/dist/define-component.js";
 import "../../core/dist/index.js";
+import { Checkbox } from "../../particles/checkbox/checkbox.js";
 import { Field } 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 { 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({
@@ -24,7 +24,7 @@ const ClientPreferencesRootDefinition = defineComponent({
   }
 `,
 	fetchStrategy: "reactive",
-	providesContext: "client-preferences",
+	providesContext: "client-preferences-toggle",
 	requiresContext: "session",
 	editor: {
 		label: "Client Preferences Root",
@@ -37,7 +37,7 @@ const NewsletterOptInControlDefinition = defineComponent({
 	name: "NewsletterOptInControl",
 	importPath: "@vtex/faststore/components",
 	component: NewsletterOptInControl,
-	requiresContext: "client-preferences",
+	requiresContext: "client-preferences-toggle",
 	actions: { identity: ["clientPreferencesUpdate"] },
 	editor: {
 		label: "Newsletter Opt-In Control",
@@ -53,7 +53,7 @@ const SavePersonalDataOptInControlDefinition = defineComponent({
 	name: "SavePersonalDataOptInControl",
 	importPath: "@vtex/faststore/components",
 	component: SavePersonalDataOptInControl,
-	requiresContext: "client-preferences",
+	requiresContext: "client-preferences-toggle",
 	actions: { identity: ["clientPreferencesUpdate"] },
 	editor: {
 		label: "Save Personal Data Opt-In Control",
@@ -87,8 +87,8 @@ 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 optinNewsLetter = Boolean($data?.optinNewsLetter ?? false);
+	const savePersonalData = Boolean($data?.savePersonalData ?? false);
 	const [pendingKeys, setPendingKeys] = useState(/* @__PURE__ */ new Set());
 	const [errorByKey, setErrorByKey] = useState({});
 	const trackWrite = useCallback((key, write) => {

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

@@ -1 +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 { 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 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: $actionsProp,\n}: ClientPreferencesControlProps & {\n  fieldKey: ClientPreferenceKey;\n  dataAttr: string;\n  pendingAttr: string;\n  readonlyAttr: string;\n}) {\n  const $actions = useActionsOverride($actionsProp);\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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"}
+{"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 { 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 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, unwrapped. */\nexport type ClientPreferencesData = {\n  optinNewsLetter?: boolean | null;\n  savePersonalData?: boolean | 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-toggle',\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-toggle',\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-toggle',\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?.optinNewsLetter ?? false);\n  const savePersonalData = Boolean($data?.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: $actionsProp,\n}: ClientPreferencesControlProps & {\n  fieldKey: ClientPreferenceKey;\n  dataAttr: string;\n  pendingAttr: string;\n  readonlyAttr: string;\n}) {\n  const $actions = useActionsOverride($actionsProp);\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

@@ -4,11 +4,9 @@ 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. */
+/** The `$data` slice forwarded by the reactive runtime — the `ClientProfile` sibling entity, unwrapped. */
 export type ClientProfileData = {
-  clientProfile?: {
-    phone?: string | null;
-  } | null;
+  phone?: string | null;
 } | null;
 export type ClientProfileRootProps = {
   /** ClientProfile entity slice forwarded by the reactive runtime (value of the section fragment). */
@@ -24,13 +22,13 @@ export declare const ClientProfileRootDefinition: ComponentDefinition<ClientProf
  * `$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';
+type PhoneFieldRequirement = 'mandatory' | 'optional';
 export type ClientProfilePhoneControlProps = {
   /** Visible field label. */
   label?: string;
   /** Selects the phone mask and validation rule. */
   country?: PhoneCountry;
-  /** Controls field visibility and required validation. */
+  /** Controls required validation. */
   requirement?: PhoneFieldRequirement;
   /** Error string shown when the input format is invalid. */
   errorInvalid?: string;

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

@@ -63,7 +63,7 @@ const ClientProfileRootDefinition = defineComponent({
 function ClientProfileRoot({ $data: $dataProp, className, children }) {
 	const $data = useDataOverride($dataProp);
 	useSession();
-	const phone = $data?.clientProfile?.phone ?? "";
+	const phone = $data?.phone ?? "";
 	const contextValue = useMemo(() => ({ phone }), [phone]);
 	return /* @__PURE__ */ jsx(ClientProfileContext, {
 		value: contextValue,
@@ -96,7 +96,7 @@ const ClientProfilePhoneControlDefinition = defineComponent({
 			label: "Country (US or BR)"
 		},
 		requirement: {
-			type: "string",
+			type: ["mandatory", "optional"],
 			default: "mandatory",
 			label: "Requirement"
 		},
@@ -128,15 +128,17 @@ function ClientProfilePhoneControl({ label = "Phone", country = "US", requiremen
 	const { canEditData } = useSession();
 	const readOnly = !canEditData;
 	const [draft, setDraft] = useState(savedPhone);
+	const dirtyRef = useRef(false);
 	const [pending, setPending] = useState(false);
 	const [serverError, setServerError] = useState(null);
-	const prevSavedRef = useRef(savedPhone);
-	if (prevSavedRef.current !== savedPhone) {
-		prevSavedRef.current = savedPhone;
-		setDraft(savedPhone);
+	const [prevSaved, setPrevSaved] = useState(savedPhone);
+	if (prevSaved !== savedPhone) {
+		setPrevSaved(savedPhone);
+		if (!dirtyRef.current) setDraft(savedPhone);
 	}
 	function handleValueChange(next) {
 		setDraft(next);
+		dirtyRef.current = true;
 		if (serverError) setServerError(null);
 	}
 	async function handleBlur() {
@@ -153,6 +155,7 @@ function ClientProfilePhoneControl({ label = "Phone", country = "US", requiremen
 		try {
 			const errors = await clientProfileUpdate({ phone }) ?? [];
 			if (errors.length > 0) setServerError(errors[0]?.message ?? null);
+			else dirtyRef.current = false;
 		} finally {
 			setPending(false);
 		}