@vtex/faststore 0.0.10 → 0.0.11

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

@@ -1,7 +1,10 @@
 "use client";
 import { defineComponent } from "../../core/dist/define-component.js";
+import { defineContentType } from "../../core/dist/define-content-type.js";
 import "../../core/dist/index.js";
+import { useMessageFormatter } from "../../sdk/i18n/use-message-formatter.js";
 import { useActionsOverride } from "../../sdk/actions/actions-override-context.js";
+import { formatErrorCode } from "../../sdk/i18n/format-error-code.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";
@@ -74,10 +77,57 @@ function ClientProfileRoot({ $data: $dataProp, className, children }) {
 		})
 	});
 }
+const ClientProfilePhoneControlContent = defineContentType({
+	id: "client-profile-phone-control",
+	title: "Client Profile Phone Control",
+	description: "The phone field's label, its validation messages and the message for a refused save.",
+	schema: {
+		type: "object",
+		additionalProperties: false,
+		properties: {
+			label: {
+				type: "string",
+				title: "Label",
+				format: "icu-message",
+				messageSource: "Phone"
+			},
+			errorInvalid: {
+				type: "string",
+				title: "Invalid error message",
+				format: "icu-message",
+				messageSource: "Invalid phone number"
+			},
+			errorRequired: {
+				type: "string",
+				title: "Required error message",
+				format: "icu-message",
+				messageSource: "Phone number is required"
+			},
+			genericErrorMessage: {
+				type: "string",
+				title: "Save failure message",
+				description: "Shown for a network failure and for any refusal the shopper cannot act on.",
+				format: "icu-message",
+				messageSource: "Unable to save your details. Please try again."
+			}
+		}
+	}
+});
+/**
+* `ClientProfileUpdateErrorCode` of API Core's schema plus the client-minted transport failure. None is
+* something the shopper can fix by editing the phone, so all share the generic message.
+*/
+const CLIENT_PROFILE_PHONE_ERROR_FIELDS = {
+	MISSING_CART_CONTEXT: "genericErrorMessage",
+	CART_NOT_FOUND: "genericErrorMessage",
+	NO_PROFILE_FIELD_PROVIDED: "genericErrorMessage",
+	NETWORK_ERROR: "genericErrorMessage"
+};
 const ClientProfilePhoneControlDefinition = defineComponent({
 	name: "ClientProfilePhoneControl",
 	importPath: "@vtex/faststore/components",
 	component: ClientProfilePhoneControl,
+	content: ClientProfilePhoneControlContent,
 	requiresContext: "client-profile",
 	actions: { identity: ["clientProfileUpdate"] },
 	editor: {
@@ -85,11 +135,6 @@ const ClientProfilePhoneControlDefinition = defineComponent({
 		category: "identity"
 	},
 	schema: {
-		label: {
-			type: "string",
-			default: "Phone",
-			label: "Label"
-		},
 		country: {
 			type: "string",
 			default: "US",
@@ -99,19 +144,9 @@ const ClientProfilePhoneControlDefinition = defineComponent({
 			type: ["mandatory", "optional"],
 			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."
+	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, passing it the $content fields label, errorInvalid and errorRequired; a refused save shows genericErrorMessage."
 });
 /**
 * Renders the bound phone field by composing the reusable `PhoneField` particle. Reads the saved
@@ -120,10 +155,12 @@ const ClientProfilePhoneControlDefinition = defineComponent({
 * 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.
+* `data-fs-client-profile-phone-readonly`. Server `userErrors` are surfaced inline, worded by the
+* `$content` field for their code (genericErrorMessage for a code it does not know).
 */
-function ClientProfilePhoneControl({ label = "Phone", country = "US", requirement = "mandatory", errorInvalid = "Invalid phone number", errorRequired = "Phone number is required", className, $actions: $actionsProp }) {
+function ClientProfilePhoneControl({ country = "US", requirement = "mandatory", $content, $locale, className, $actions: $actionsProp }) {
 	const $actions = useActionsOverride($actionsProp);
+	const { format } = useMessageFormatter(ClientProfilePhoneControlContent, $content);
 	const { phone: savedPhone } = useClientProfileContext();
 	const { canEditData } = useSession();
 	const readOnly = !canEditData;
@@ -136,6 +173,9 @@ function ClientProfilePhoneControl({ label = "Phone", country = "US", requiremen
 		setPrevSaved(savedPhone);
 		if (!dirtyRef.current) setDraft(savedPhone);
 	}
+	function serverErrorMessage(error) {
+		return formatErrorCode(ClientProfilePhoneControlContent, CLIENT_PROFILE_PHONE_ERROR_FIELDS, error, format, "genericErrorMessage");
+	}
 	function handleValueChange(next) {
 		setDraft(next);
 		dirtyRef.current = true;
@@ -154,7 +194,7 @@ function ClientProfilePhoneControl({ label = "Phone", country = "US", requiremen
 		setServerError(null);
 		try {
 			const errors = await clientProfileUpdate({ phone }) ?? [];
-			if (errors.length > 0) setServerError(errors[0]?.message ?? null);
+			if (errors.length > 0) setServerError(errors[0] ?? null);
 			else dirtyRef.current = false;
 		} finally {
 			setPending(false);
@@ -166,17 +206,17 @@ function ClientProfilePhoneControl({ label = "Phone", country = "US", requiremen
 		...pending ? { "data-fs-client-profile-phone-pending": "" } : {},
 		...readOnly ? { "data-fs-client-profile-phone-readonly": "" } : {},
 		children: /* @__PURE__ */ jsx(PhoneField, {
-			label,
+			label: format("label"),
 			country,
 			requirement,
-			errorInvalid,
-			errorRequired,
+			errorInvalid: format("errorInvalid"),
+			errorRequired: format("errorRequired"),
 			value: draft,
 			onValueChange: handleValueChange,
 			onBlur: handleBlur,
 			isDisabled: pending || readOnly,
 			invalid: serverError != null || void 0,
-			error: serverError ?? void 0
+			error: serverError ? serverErrorMessage(serverError) : void 0
 		})
 	});
 }
@@ -185,6 +225,6 @@ const ClientProfile = {
 	PhoneControl: ClientProfilePhoneControl
 };
 //#endregion
-export { ClientProfile, ClientProfilePhoneControl, ClientProfilePhoneControlDefinition, ClientProfileRoot, ClientProfileRootDefinition };
+export { CLIENT_PROFILE_PHONE_ERROR_FIELDS, ClientProfile, ClientProfilePhoneControl, ClientProfilePhoneControlContent, ClientProfilePhoneControlDefinition, ClientProfileRoot, ClientProfileRootDefinition };
 
 //# sourceMappingURL=client-profile.js.map

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

@@ -1 +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 { 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 { 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, unwrapped. */\nexport type ClientProfileData = {\n  phone?: string | 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?.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';\n\nexport type ClientProfilePhoneControlProps = {\n  /** Visible field label. */\n  label?: string;\n  /** Selects the phone mask and validation rule. */\n  country?: PhoneCountry;\n  /** Controls 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: ['mandatory', 'optional'] as const, 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: $actionsProp,\n}: Readonly<ClientProfilePhoneControlProps>) {\n  const $actions = useActionsOverride($actionsProp);\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  // A plain ref, not state: set only from handlers (never during render), and read only inside the\n  // render-body re-seed comparison below — nothing here needs its own re-render, since every call\n  // site that sets it already triggers one via a sibling state setter in the same tick.\n  const dirtyRef = useRef(false);\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) — but never while an edit is in progress. A render-phase\n  // compare-and-set, not a ref: the comparison baseline lives in state, and the compare-and-set runs\n  // during render, so a render React abandons without committing — a suspended transition, a\n  // Suspense retry — never leaves a stale baseline behind the way a ref write would, and a reactive\n  // fetch landing mid-keystroke still can't silently replace what the shopper just typed.\n  const [prevSaved, setPrevSaved] = useState(savedPhone);\n  if (prevSaved !== savedPhone) {\n    setPrevSaved(savedPhone);\n    if (!dirtyRef.current) setDraft(savedPhone);\n  }\n\n  function handleValueChange(next: string) {\n    setDraft(next);\n    dirtyRef.current = true;\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) {\n        setServerError(errors[0]?.message ?? null);\n      } else {\n        // The edit is now committed — clear the guard so a later external change (another tab,\n        // a cache refresh) can re-seed the draft again.\n        dirtyRef.current = false;\n      }\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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"}
+{"version":3,"file":"client-profile.js","names":[],"sources":["../../../src/matter/client-profile/client-profile.tsx"],"sourcesContent":["'use client';\n\nimport {\n  type ContentValue,\n  defineComponent,\n  defineContentType,\n  type MessageFieldName,\n  type MessageLocaleProp,\n} 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 { 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 { formatErrorCode } from '../../sdk/i18n/format-error-code.js';\nimport { useMessageFormatter } from '../../sdk/i18n/use-message-formatter.js';\nimport type { ClientProfileUserError } from '../../sdk/identity/operations.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, unwrapped. */\nexport type ClientProfileData = {\n  phone?: string | 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?.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';\n\nexport const ClientProfilePhoneControlContent = defineContentType({\n  id: 'client-profile-phone-control',\n  title: 'Client Profile Phone Control',\n  description: \"The phone field's label, its validation messages and the message for a refused save.\",\n  schema: {\n    type: 'object',\n    additionalProperties: false,\n    properties: {\n      label: { type: 'string', title: 'Label', format: 'icu-message', messageSource: 'Phone' },\n      errorInvalid: {\n        type: 'string',\n        title: 'Invalid error message',\n        format: 'icu-message',\n        messageSource: 'Invalid phone number',\n      },\n      errorRequired: {\n        type: 'string',\n        title: 'Required error message',\n        format: 'icu-message',\n        messageSource: 'Phone number is required',\n      },\n      genericErrorMessage: {\n        type: 'string',\n        title: 'Save failure message',\n        description: 'Shown for a network failure and for any refusal the shopper cannot act on.',\n        format: 'icu-message',\n        messageSource: 'Unable to save your details. Please try again.',\n      },\n    },\n  },\n});\n\n/**\n * `ClientProfileUpdateErrorCode` of API Core's schema plus the client-minted transport failure. None is\n * something the shopper can fix by editing the phone, so all share the generic message.\n */\nexport const CLIENT_PROFILE_PHONE_ERROR_FIELDS = {\n  MISSING_CART_CONTEXT: 'genericErrorMessage',\n  CART_NOT_FOUND: 'genericErrorMessage',\n  NO_PROFILE_FIELD_PROVIDED: 'genericErrorMessage',\n  NETWORK_ERROR: 'genericErrorMessage',\n} as const satisfies Record<string, MessageFieldName<typeof ClientProfilePhoneControlContent>>;\n\nexport type ClientProfilePhoneControlProps = MessageLocaleProp & {\n  /** Selects the phone mask and validation rule. */\n  country?: PhoneCountry;\n  /** Controls required validation. */\n  requirement?: PhoneFieldRequirement;\n  /** The visible label, the messages for an invalid format and a mandatory field left empty, and the\n   * message for a refused save. */\n  $content?: ContentValue<typeof ClientProfilePhoneControlContent>;\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  content: ClientProfilePhoneControlContent,\n  requiresContext: 'client-profile',\n  actions: { identity: ['clientProfileUpdate'] },\n  editor: { label: 'Client Profile Phone Control', category: 'identity' },\n  schema: {\n    country: { type: 'string', default: 'US', label: 'Country (US or BR)' },\n    requirement: { type: ['mandatory', 'optional'] as const, default: 'mandatory', label: 'Requirement' },\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, passing it the $content fields label, errorInvalid and errorRequired; a refused save shows genericErrorMessage.',\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, worded by the\n * `$content` field for their code (genericErrorMessage for a code it does not know).\n */\nexport function ClientProfilePhoneControl({\n  country = 'US',\n  requirement = 'mandatory',\n  $content,\n  $locale,\n  className,\n  $actions: $actionsProp,\n}: Readonly<ClientProfilePhoneControlProps>) {\n  const $actions = useActionsOverride($actionsProp);\n  const { format } = useMessageFormatter(ClientProfilePhoneControlContent, $content);\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  // A plain ref, not state: set only from handlers (never during render), and read only inside the\n  // render-body re-seed comparison below — nothing here needs its own re-render, since every call\n  // site that sets it already triggers one via a sibling state setter in the same tick.\n  const dirtyRef = useRef(false);\n  const [pending, setPending] = useState(false);\n  const [serverError, setServerError] = useState<ClientProfileUserError | 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) — but never while an edit is in progress. A render-phase\n  // compare-and-set, not a ref: the comparison baseline lives in state, and the compare-and-set runs\n  // during render, so a render React abandons without committing — a suspended transition, a\n  // Suspense retry — never leaves a stale baseline behind the way a ref write would, and a reactive\n  // fetch landing mid-keystroke still can't silently replace what the shopper just typed.\n  const [prevSaved, setPrevSaved] = useState(savedPhone);\n  if (prevSaved !== savedPhone) {\n    setPrevSaved(savedPhone);\n    if (!dirtyRef.current) setDraft(savedPhone);\n  }\n\n  function serverErrorMessage(error: ClientProfileUserError): string {\n    return formatErrorCode(\n      ClientProfilePhoneControlContent,\n      CLIENT_PROFILE_PHONE_ERROR_FIELDS,\n      error,\n      format,\n      'genericErrorMessage',\n    );\n  }\n\n  function handleValueChange(next: string) {\n    setDraft(next);\n    dirtyRef.current = true;\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) {\n        setServerError(errors[0] ?? null);\n      } else {\n        // The edit is now committed — clear the guard so a later external change (another tab,\n        // a cache refresh) can re-seed the draft again.\n        dirtyRef.current = false;\n      }\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={format('label')}\n        country={country}\n        requirement={requirement}\n        errorInvalid={format('errorInvalid')}\n        errorRequired={format('errorRequired')}\n        value={draft}\n        onValueChange={handleValueChange}\n        onBlur={handleBlur}\n        isDisabled={pending || readOnly}\n        invalid={serverError != null || undefined}\n        error={serverError ? serverErrorMessage(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-fieldset.d.ts

@@ -1,9 +1,110 @@
+import { ContentTypeDefinition, ContentValue, MessageLocaleProp } from "../../core/dist/define-content-type.js";
 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 { ComponentPropsWithRef, ReactNode } from "react";
 //#region src/matter/client-profile-form/client-profile-fieldset.d.ts
+export declare const ClientProfileFieldsetContent: {
+  readonly id: "client-profile-fieldset";
+  readonly title: "Client Profile Fieldset";
+  readonly description: "The profile fieldset's loading and loaded announcements and its accessible group name.";
+  readonly schema: {
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly properties: {
+      readonly loadingLabel: {
+        readonly type: "string";
+        readonly title: "Loading announcement";
+        readonly format: "icu-message";
+        readonly messageSource: "Loading your details";
+      };
+      readonly loadedLabel: {
+        readonly type: "string";
+        readonly title: "Loaded announcement";
+        readonly format: "icu-message";
+        readonly messageSource: "Your details are ready";
+      };
+      readonly groupLabel: {
+        readonly type: "string";
+        readonly title: "Accessible group name";
+        readonly format: "icu-message";
+        readonly messageSource: "Your details";
+        readonly messageOptional: true;
+      };
+      readonly genericErrorMessage: {
+        readonly type: "string";
+        readonly title: "Generic error message";
+        readonly description: "Shown by FormError when the details could not be saved.";
+        readonly format: "icu-message";
+        readonly messageSource: "Unable to save your details. Please try again.";
+      };
+    };
+  };
+};
+export declare const ClientProfileFieldsetPhoneControlContent: {
+  readonly id: "client-profile-fieldset-phone";
+  readonly title: "Client Profile Fieldset Phone Control";
+  readonly description: "The phone control's label and its validation messages.";
+  readonly schema: {
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly properties: {
+      readonly label: {
+        readonly type: "string";
+        readonly title: "Label";
+        readonly format: "icu-message";
+        readonly messageSource: "Phone";
+      };
+      readonly errorInvalid: {
+        readonly type: "string";
+        readonly title: "Invalid error message";
+        readonly format: "icu-message";
+        readonly messageSource: "Invalid phone number";
+      };
+      readonly errorRequired: {
+        readonly type: "string";
+        readonly title: "Required error message";
+        readonly format: "icu-message";
+        readonly messageSource: "Phone number is required";
+      };
+    };
+  };
+};
+export declare const ClientProfileFirstNameControlContent: {
+  readonly id: "client-profile-first-name";
+  readonly title: "Client Profile First Name Control";
+  readonly description: "The first-name control's label.";
+  readonly schema: {
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly properties: {
+      readonly label: {
+        readonly type: "string";
+        readonly title: "Label";
+        readonly format: "icu-message";
+        readonly messageSource: "First name";
+      };
+    };
+  };
+};
+export declare const ClientProfileLastNameControlContent: {
+  readonly id: "client-profile-last-name";
+  readonly title: "Client Profile Last Name Control";
+  readonly description: "The last-name control's label.";
+  readonly schema: {
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly properties: {
+      readonly label: {
+        readonly type: "string";
+        readonly title: "Label";
+        readonly format: "icu-message";
+        readonly messageSource: "Last name";
+      };
+    };
+  };
+};
 /** The `$data` slice forwarded by the reactive runtime — the ClientProfile sibling entity, unwrapped. */
 export type ClientProfileFieldsetData = {
   firstName?: string | null;
@@ -11,19 +112,15 @@ export type ClientProfileFieldsetData = {
   phone?: string | null;
   document?: string | null;
 } | null;
-export type ClientProfileFieldsetProps = {
+export type ClientProfileFieldsetProps = MessageLocaleProp & {
   /** Phone mask/validation country, provided to the phone control via context. */
   country?: PhoneCountry;
   /** Locale document type; the document control renders only when supported. */
   documentType?: string;
   /** Placeholder rows the loading skeleton draws. Set it to the number of controls composed here. */
   skeletonCount?: number;
-  /** Announced politely while the profile resolves. Blank means no announcement. */
-  loadingLabel?: string;
-  /** Announced politely once the controls mount. Blank means no announcement. */
-  loadedLabel?: string;
-  /** Accessible name of the `<fieldset>` group. Blank means no name is exposed. */
-  groupLabel?: string;
+  /** The loading and loaded announcements and the accessible group name. */
+  $content?: ContentValue<typeof ClientProfileFieldsetContent>;
   className?: string;
   children?: ReactNode;
   /** `ClientProfileFieldsetData` slice forwarded by the reactive runtime. */
@@ -31,16 +128,16 @@ export type ClientProfileFieldsetProps = {
   /** Compiler-injected; carries `identity.clientProfileUpdate`. */
   $actions?: ComponentActions;
 };
-type ProfileTextControlProps = {
-  label?: string;
+type ProfileTextControlProps<T extends ContentTypeDefinition> = MessageLocaleProp & {
   placeholder?: string;
+  /** The control's label. */
+  $content?: ContentValue<T>;
   className?: string;
   children?: ReactNode;
 };
-export type ClientProfileFirstNameControlProps = ProfileTextControlProps;
-export type ClientProfileLastNameControlProps = ProfileTextControlProps;
-export type ClientProfileFieldsetPhoneControlProps = {
-  label?: string;
+export type ClientProfileFirstNameControlProps = ProfileTextControlProps<typeof ClientProfileFirstNameControlContent>;
+export type ClientProfileLastNameControlProps = ProfileTextControlProps<typeof ClientProfileLastNameControlContent>;
+export type ClientProfileFieldsetPhoneControlProps = MessageLocaleProp & {
   placeholder?: string;
   /**
    * Raises the field to required. The composite owns it; the contract carries no rule (Decision 6),
@@ -48,8 +145,8 @@ export type ClientProfileFieldsetPhoneControlProps = {
    * optional.
    */
   requirement?: 'mandatory' | 'optional';
-  errorInvalid?: string;
-  errorRequired?: string;
+  /** The label and the invalid and required messages. */
+  $content?: ContentValue<typeof ClientProfileFieldsetPhoneControlContent>;
   className?: string;
   /** Given, replaces PhoneField's default Field.Label + PhoneFieldInput + Field.Error anatomy. */
   children?: ReactNode;
@@ -63,8 +160,8 @@ export type ClientProfileDocumentControlProps = {
   children?: ReactNode;
 };
 export declare const ClientProfileFieldsetDefinition: ComponentDefinition<ClientProfileFieldsetProps>;
-export declare const ClientProfileFirstNameControlDefinition: ComponentDefinition<ProfileTextControlProps>;
-export declare const ClientProfileLastNameControlDefinition: ComponentDefinition<ProfileTextControlProps>;
+export declare const ClientProfileFirstNameControlDefinition: ComponentDefinition<ClientProfileFirstNameControlProps>;
+export declare const ClientProfileLastNameControlDefinition: ComponentDefinition<ClientProfileLastNameControlProps>;
 export declare const ClientProfileFieldsetPhoneControlDefinition: ComponentDefinition<ClientProfileFieldsetPhoneControlProps>;
 export declare const ClientProfileDocumentControlDefinition: ComponentDefinition<ClientProfileDocumentControlProps>;
 /**
@@ -89,10 +186,10 @@ export declare const ClientProfileDocumentControlDefinition: ComponentDefinition
  * 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
+ * live region that announces the `loadingLabel` and then the `loadedLabel` message. Style the region `sr-only` — it is
  * text meant for a screen reader, not for the page.
  */
-export declare function ClientProfileFieldset({ country, documentType, skeletonCount, loadingLabel, loadedLabel, groupLabel, className, children, $data: $dataProp, $actions: $actionsProp }: ClientProfileFieldsetProps): import("react/jsx-runtime").JSX.Element;
+export declare function ClientProfileFieldset({ country, documentType, skeletonCount, $content, $locale, className, children, $data: $dataProp, $actions: $actionsProp }: ClientProfileFieldsetProps): import("react/jsx-runtime").JSX.Element;
 export declare namespace ClientProfileFieldset {
   var Skeleton: typeof ClientProfileFieldsetSkeleton;
 }
@@ -104,8 +201,8 @@ export declare namespace ClientProfileFieldset {
 export declare function ClientProfileFieldsetSkeleton({ count, className, ...props }: ComponentPropsWithRef<'div'> & {
   count?: number;
 }): import("react/jsx-runtime").JSX.Element;
-export declare function ClientProfileFirstNameControl({ label, placeholder, className, children }: ClientProfileFirstNameControlProps): import("react/jsx-runtime").JSX.Element;
-export declare function ClientProfileLastNameControl({ label, placeholder, className, children }: ClientProfileLastNameControlProps): import("react/jsx-runtime").JSX.Element;
+export declare function ClientProfileFirstNameControl({ placeholder, $content, $locale, className, children }: ClientProfileFirstNameControlProps): import("react/jsx-runtime").JSX.Element;
+export declare function ClientProfileLastNameControl({ placeholder, $content, $locale, className, children }: ClientProfileLastNameControlProps): import("react/jsx-runtime").JSX.Element;
 /**
  * Composes `PhoneField` inside a `FieldBinding`, wrapped in a `data-fs-client-profile-fieldset-field="phone"`
  * node — the same styling hook attribute the text controls carry on their own `Field.Root`.
@@ -113,7 +210,7 @@ export declare function ClientProfileLastNameControl({ label, placeholder, class
  * state for this control to second-guess; `requirement` only ever raises the field to required,
  * and left unset it raises nothing.
  */
-export declare function ClientProfileFieldsetPhoneControl({ label, placeholder, requirement, errorInvalid, errorRequired, className, children }: ClientProfileFieldsetPhoneControlProps): import("react/jsx-runtime").JSX.Element;
+export declare function ClientProfileFieldsetPhoneControl({ placeholder, requirement, $content, $locale, className, children }: ClientProfileFieldsetPhoneControlProps): import("react/jsx-runtime").JSX.Element;
 export declare function ClientProfileDocumentControl({ label, placeholder, errorMessage, className, children }: ClientProfileDocumentControlProps): import("react/jsx-runtime").JSX.Element | null;
 //#endregion
 //# sourceMappingURL=client-profile-fieldset.d.ts.map