@vtex/faststore 0.0.10 → 0.0.11

package/dist/matter/challenge-return/challenge-return.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"challenge-return.js","names":[],"sources":["../../../src/matter/challenge-return/challenge-return.tsx"],"sourcesContent":["'use client';\n\nimport { type ContentValue, defineComponent, defineContentType, type MessageLocaleProp } from '@vtex/fs-core';\nimport { type ComponentPropsWithRef, useEffect, useRef, useState } from 'react';\nimport { useActionsOverride } from '../../sdk/actions/actions-override-context.js';\nimport type { ComponentActions } from '../../sdk/actions/types.js';\nimport { useMessageFormatter } from '../../sdk/i18n/use-message-formatter.js';\nimport { StorefrontLink } from '../../sdk/navigation/storefront-link.js';\nimport type { PageRef } from '../../sdk/navigation/types.js';\nimport { useStorefrontNavigation } from '../../sdk/navigation/use-storefront-navigation.js';\nimport { readChallengeReturn } from '../../sdk/payment/challenge-return.js';\nimport { PAYMENT_NETWORK_ERROR_CODE, type PaymentUserError } from '../../sdk/payment/operations.js';\nimport { emitPurchaseForOrder, useSettledOrderRead } from '../../sdk/payment/resumed-purchase.js';\nimport { resolveSiteRelativeHref } from '../../utils/safe-href.js';\n\n/**\n * The page a shopper lands on when the bank sends them back from a 3D Secure challenge (T208). It finishes\n * the order with no click: one `gatewayCallback` for the order group in its own URL, one read of the settled\n * order, one `purchase`, and a replace to the confirmation page. A whole-page handover component, like\n * `SignInRedirect`: it does its work in an effect and renders only the state it is in.\n *\n * **A return never pays.** This page reaches `payment.gatewayCallback` and nothing else of the payment\n * actions, and renders no field of any kind: the card was handed to the gateway before the shopper left.\n *\n * The query is read from the document in the effect, never through `useSearchParams()`, which would need a\n * `Suspense` boundary the generator does not emit on a prerendered route; a prerender has no query at all,\n * so the first paint is the resuming state and the effect decides.\n */\n\nconst CHECKOUT_PAGE: PageRef = { standard: 'checkout' };\nconst ORDER_PLACED_PAGE: PageRef = { standard: 'order-placed' };\n\n// Field names avoid the card-field pattern the catalog sweep reads.\nexport const ChallengeReturnContent = defineContentType({\n  id: 'challenge-return',\n  title: 'Challenge Return',\n  description: 'Copy for the page the bank sends the shopper back to after a 3D Secure challenge.',\n  schema: {\n    type: 'object',\n    additionalProperties: false,\n    properties: {\n      resumingMessage: {\n        type: 'string',\n        title: 'Message while finishing the order',\n        format: 'icu-message',\n        messageSource: 'Finishing your order...',\n      },\n      lateReturnMessage: {\n        type: 'string',\n        title: 'Message when the verification lapsed',\n        description: 'Shown in an alert when the callback answered a refusal: the order was not placed.',\n        format: 'icu-message',\n        messageSource: '3D Secure expired. Go back to the checkout to place your order again.',\n      },\n      unconfirmedMessage: {\n        type: 'string',\n        title: 'Message when the order could not be confirmed',\n        description: 'Shown as a status when the callback gave no answer: the payment may still be processing.',\n        format: 'icu-message',\n        messageSource:\n          'We could not confirm your order yet. Your payment may still be processing, so please do not pay again.',\n      },\n      checkoutLabel: {\n        type: 'string',\n        title: 'Back to the checkout label',\n        description: 'Label of the link back to the checkout, shown with the late-return message.',\n        format: 'icu-message',\n        messageSource: 'Back to the checkout',\n      },\n    },\n  },\n});\n\nexport type ChallengeReturnProps = ComponentPropsWithRef<'div'> &\n  MessageLocaleProp & {\n    /** Where the late-return link goes. e.g. `{ standard: 'checkout' }` */\n    checkoutHref?: PageRef | string;\n    /**\n     * Where the shopper lands once the order is finished. A page reference gets the order's Node id as its\n     * `orderId` param. e.g. `{ standard: 'order-placed' }`\n     */\n    successHref?: PageRef | string;\n    /** Merchant-authored copy for each state the page can end on. */\n    $content?: ContentValue<typeof ChallengeReturnContent>;\n    /** Compiler-injected action surface; carries `payment.gatewayCallback` and `analytics.track`. */\n    $actions?: ComponentActions;\n  };\n\nexport const ChallengeReturnDefinition = defineComponent<ChallengeReturnProps>({\n  name: 'ChallengeReturn',\n  importPath: '@vtex/faststore/components',\n  component: ChallengeReturn,\n  actions: { payment: ['gatewayCallback'], analytics: ['track'] },\n  content: ChallengeReturnContent,\n  editor: { label: 'Challenge Return', category: 'commerce' },\n  schema: {\n    // Literals, not shared constants: the native catalog builder extracts `schema` statically and silently\n    // drops an identifier-valued default.\n    checkoutHref: { type: 'link', default: { standard: 'checkout' }, label: 'Checkout page' },\n    successHref: {\n      type: 'link',\n      default: { standard: 'order-placed' },\n      fills: ['orderId'],\n      label: 'Confirmation Page',\n    },\n  },\n  guideline:\n    \"The whole of the page the bank sends the shopper back to after a 3D Secure challenge: on mount it finishes the order with no click (one gateway callback for the order group in the URL, one read of the order, one purchase event) and replaces the page with the order confirmation. Place it alone on its own page, named by PlaceOrder's challengeReturnHref, never beside anything the shopper is meant to read. It renders no payment field and never pays: a shopper who returns after the verification lapsed reads an alert with a link back to the checkout, and one whose order could not be confirmed reads a status that says not to pay again, with no such link. See challenge-return.md.\",\n});\n\n/** What a result with no readable `userErrors` collapses to: this package's own code, which says nothing about the order. */\nconst PAYMENT_NETWORK_ERROR_CODE_ENTRY: PaymentUserError = {\n  code: PAYMENT_NETWORK_ERROR_CODE,\n  message: 'Unable to complete the request. Please try again.',\n};\n\ntype ReturnState = 'resuming' | 'done' | 'late' | 'unconfirmed';\n\n/** True when the entry carries a code the server sent: an answer about this payment, not this package's own collapse. */\nfunction carriesServerCode(userErrors: readonly PaymentUserError[]): boolean {\n  return userErrors.some(\n    (userError) => typeof userError?.code === 'string' && userError.code !== PAYMENT_NETWORK_ERROR_CODE,\n  );\n}\n\n/** The confirmation target: the authored page filled with the Node id, or a site-relative path of the store. */\nfunction confirmationTarget(successHref: PageRef | string, orderNodeId: string): PageRef | string {\n  if (typeof successHref !== 'string') {\n    return { ...successHref, params: { ...successHref.params, orderId: orderNodeId } };\n  }\n  const destination = resolveSiteRelativeHref(successHref);\n  if (destination.safe && !destination.href.includes('{')) return destination.href;\n  if (process.env.NODE_ENV !== 'production') {\n    console.warn('[ChallengeReturn] successHref is not a path of this store; going to the confirmation page instead.');\n  }\n  return { ...ORDER_PLACED_PAGE, params: { orderId: orderNodeId } };\n}\n\ntype GatewayCallback = NonNullable<NonNullable<ComponentActions['payment']>['gatewayCallback']>;\n\ntype FinishArgs = {\n  gatewayCallback: GatewayCallback | undefined;\n  track: NonNullable<ComponentActions['analytics']>['track'];\n  readOrder: ReturnType<typeof useSettledOrderRead>;\n  replace: ReturnType<typeof useStorefrontNavigation>['replace'];\n  hrefFor: ReturnType<typeof useStorefrontNavigation>['hrefFor'];\n  successHref: PageRef | string;\n  settle: (next: ReturnState) => void;\n};\n\n/** The order node id the callback settled, or the state the page ends on when it did not. */\nasync function callGateway(\n  callback: GatewayCallback,\n  orderGroup: string,\n): Promise<{ orderNodeId: string } | { failedState: ReturnState }> {\n  let result: Awaited<ReturnType<GatewayCallback>>;\n  try {\n    result = await callback(orderGroup, { acceptChallenges: true });\n  } catch {\n    return { failedState: 'unconfirmed' };\n  }\n\n  const userErrors = Array.isArray(result?.userErrors) ? result.userErrors : [PAYMENT_NETWORK_ERROR_CODE_ENTRY];\n  if (userErrors.length > 0) return { failedState: carriesServerCode(userErrors) ? 'late' : 'unconfirmed' };\n\n  // The order may well be placed, but nothing can address its confirmation, so nothing is reported and\n  // nowhere is navigated to.\n  const orderNodeId = result.orderNodeId ?? null;\n  return orderNodeId === null ? { failedState: 'unconfirmed' } : { orderNodeId };\n}\n\n/** Reports the purchase and goes to the confirmation page; the state the page ends on. */\nasync function reportAndConfirm(\n  { track, readOrder, replace, hrefFor, successHref }: Omit<FinishArgs, 'gatewayCallback' | 'settle'>,\n  orderNodeId: string,\n): Promise<ReturnState> {\n  await emitPurchaseForOrder({ track, readOrder, orderNodeId });\n  const confirmation = confirmationTarget(successHref, orderNodeId);\n  // The order is placed and reported, so a confirmation page the store cannot reach, or a router that\n  // throws, must not leave a blank page or a status that never ends. It reads as the unconfirmed state:\n  // the payment may be done, so no message tells the shopper to pay again and none links back to the checkout.\n  if (hrefFor(confirmation) === null) return 'unconfirmed';\n  try {\n    replace(confirmation);\n  } catch {\n    console.error('[ChallengeReturn] could not go to the confirmation page');\n    return 'unconfirmed';\n  }\n  return 'done';\n}\n\nasync function finishChallengeReturn({ gatewayCallback, settle, ...rest }: FinishArgs): Promise<void> {\n  const returned = readChallengeReturn(globalThis.location.search);\n  if (returned === null) {\n    settle('late');\n    return;\n  }\n\n  if (!gatewayCallback) {\n    console.error('[ChallengeReturn] the payment action namespace is not injected');\n    settle('unconfirmed');\n    return;\n  }\n\n  const outcome = await callGateway(gatewayCallback, returned.orderGroup);\n  if ('failedState' in outcome) {\n    settle(outcome.failedState);\n    return;\n  }\n  settle(await reportAndConfirm(rest, outcome.orderNodeId));\n}\n\nexport function ChallengeReturn({\n  $content,\n  $locale,\n  checkoutHref = CHECKOUT_PAGE,\n  successHref = ORDER_PLACED_PAGE,\n  $actions: $actionsProp,\n  className,\n  ref,\n  ...props\n}: ChallengeReturnProps) {\n  const $actions = useActionsOverride($actionsProp);\n  const { format } = useMessageFormatter(ChallengeReturnContent, $content);\n  const gatewayCallback = $actions?.payment?.gatewayCallback;\n  const track = $actions?.analytics?.track;\n  const readOrder = useSettledOrderRead();\n  const { replace, hrefFor } = useStorefrontNavigation();\n  const [state, setState] = useState<ReturnState>('resuming');\n  // StrictMode runs an effect twice, and a second callback on an order already being finished is a repeat\n  // of a call whose behaviour on repetition is unmeasured. The ref survives the simulated remount, and also\n  // keeps a re-render that hands the effect new dependencies from starting the sequence again.\n  const startedRef = useRef(false);\n  // Whether the page is still mounted. The sequence outlives a render, so a result that lands after the\n  // shopper left must not write state. It is a ref, not a flag local to the effect: StrictMode's simulated\n  // cleanup would cancel the one sequence there is, and the second run is barred from starting another.\n  const mountedRef = useRef(false);\n\n  useEffect(() => {\n    mountedRef.current = true;\n    if (!startedRef.current) {\n      startedRef.current = true;\n      const settle = (next: ReturnState) => {\n        if (mountedRef.current) setState(next);\n      };\n      void finishChallengeReturn({ gatewayCallback, track, readOrder, replace, hrefFor, successHref, settle });\n    }\n    return () => {\n      mountedRef.current = false;\n    };\n  }, [gatewayCallback, track, readOrder, replace, hrefFor, successHref]);\n\n  return (\n    <div {...props} ref={ref} className={className} data-fs-challenge-return=\"\">\n      {state === 'resuming' ? <output data-fs-challenge-return-resuming=\"\">{format('resumingMessage')}</output> : null}\n      {state === 'late' ? (\n        <div role=\"alert\" data-fs-challenge-return-late=\"\">\n          <span data-fs-challenge-return-message=\"\">{format('lateReturnMessage')}</span>\n          <StorefrontLink href={checkoutHref} data-fs-challenge-return-checkout-link=\"\">\n            {format('checkoutLabel')}\n          </StorefrontLink>\n        </div>\n      ) : null}\n      {state === 'unconfirmed' ? (\n        <output data-fs-challenge-return-unconfirmed=\"\">{format('unconfirmedMessage')}</output>\n      ) : null}\n    </div>\n  );\n}\n"],"mappings":"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"}

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

@@ -1,22 +1,90 @@
+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 { ComponentPropsWithRef, ReactNode } from "react";
 //#region src/matter/client-preferences/client-preferences-fieldset.d.ts
+export declare const ClientPreferencesFieldsetContent: {
+  readonly id: "client-preferences-fieldset";
+  readonly title: "Client Preferences Fieldset";
+  readonly description: "The preferences 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 preferences";
+      };
+      readonly loadedLabel: {
+        readonly type: "string";
+        readonly title: "Loaded announcement";
+        readonly format: "icu-message";
+        readonly messageSource: "Your preferences are ready";
+      };
+      readonly groupLabel: {
+        readonly type: "string";
+        readonly title: "Accessible group name";
+        readonly format: "icu-message";
+        readonly messageSource: "Your preferences";
+        readonly messageOptional: true;
+      };
+      readonly genericErrorMessage: {
+        readonly type: "string";
+        readonly title: "Generic error message";
+        readonly description: "Shown by FormError when the preferences could not be saved.";
+        readonly format: "icu-message";
+        readonly messageSource: "Unable to save your preferences. Please try again.";
+      };
+    };
+  };
+};
+export declare const ClientPreferencesNewsletterControlContent: {
+  readonly id: "client-preferences-newsletter";
+  readonly title: "Client Preferences Newsletter Control";
+  readonly description: "The newsletter opt-in'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: "Email me with news and offers";
+      };
+    };
+  };
+};
+export declare const ClientPreferencesSavePersonalDataControlContent: {
+  readonly id: "client-preferences-save-data";
+  readonly title: "Client Preferences Save Personal Data Control";
+  readonly description: "The save-personal-data opt-in'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: "Save my information for next time";
+      };
+    };
+  };
+};
 /** The `$data` slice forwarded by the reactive runtime — the ClientPreferences sibling entity, unwrapped. */
 export type ClientPreferencesFieldsetData = {
   optinNewsLetter?: boolean | null;
   savePersonalData?: boolean | null;
 } | null;
-export type ClientPreferencesFieldsetProps = {
+export type ClientPreferencesFieldsetProps = MessageLocaleProp & {
   /** Placeholder rows the loading skeleton draws. Set it to the number of controls composed here. */
   skeletonCount?: number;
-  /** Announced politely while the preferences resolve. 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 ClientPreferencesFieldsetContent>;
   className?: string;
   children?: ReactNode;
   /** `ClientPreferencesFieldsetData` slice forwarded by the reactive runtime. */
@@ -24,16 +92,17 @@ export type ClientPreferencesFieldsetProps = {
   /** Compiler-injected; carries `identity.clientPreferencesUpdate`. */
   $actions?: ComponentActions;
 };
-type PreferenceControlProps = {
-  label?: string;
+type PreferenceControlProps<T extends ContentTypeDefinition> = MessageLocaleProp & {
+  /** The control's label. */
+  $content?: ContentValue<T>;
   className?: string;
   children?: ReactNode;
 };
-export type ClientPreferencesNewsletterControlProps = PreferenceControlProps;
-export type ClientPreferencesSavePersonalDataControlProps = PreferenceControlProps;
+export type ClientPreferencesNewsletterControlProps = PreferenceControlProps<typeof ClientPreferencesNewsletterControlContent>;
+export type ClientPreferencesSavePersonalDataControlProps = PreferenceControlProps<typeof ClientPreferencesSavePersonalDataControlContent>;
 export declare const ClientPreferencesFieldsetDefinition: ComponentDefinition<ClientPreferencesFieldsetProps>;
-export declare const ClientPreferencesNewsletterControlDefinition: ComponentDefinition<PreferenceControlProps>;
-export declare const ClientPreferencesSavePersonalDataControlDefinition: ComponentDefinition<PreferenceControlProps>;
+export declare const ClientPreferencesNewsletterControlDefinition: ComponentDefinition<ClientPreferencesNewsletterControlProps>;
+export declare const ClientPreferencesSavePersonalDataControlDefinition: ComponentDefinition<ClientPreferencesSavePersonalDataControlProps>;
 /**
  * Registers a batched write of the `ClientPreferences` entity with the enclosing `FormRoot`
  * (`registerFieldset`, namespace `clientPreferences`) on mount, unconditionally — so this fieldset keeps
@@ -56,10 +125,10 @@ export declare const ClientPreferencesSavePersonalDataControlDefinition: Compone
  * 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 ClientPreferencesFieldset({ skeletonCount, loadingLabel, loadedLabel, groupLabel, className, children, $data: $dataProp, $actions: $actionsProp }: ClientPreferencesFieldsetProps): import("react/jsx-runtime").JSX.Element;
+export declare function ClientPreferencesFieldset({ skeletonCount, $content, $locale, className, children, $data: $dataProp, $actions: $actionsProp }: ClientPreferencesFieldsetProps): import("react/jsx-runtime").JSX.Element;
 export declare namespace ClientPreferencesFieldset {
   var Skeleton: typeof ClientPreferencesFieldsetSkeleton;
 }
@@ -71,7 +140,7 @@ export declare namespace ClientPreferencesFieldset {
 export declare function ClientPreferencesFieldsetSkeleton({ count, className, ...props }: ComponentPropsWithRef<'div'> & {
   count?: number;
 }): import("react/jsx-runtime").JSX.Element;
-export declare function ClientPreferencesNewsletterControl({ label, className, children }: ClientPreferencesNewsletterControlProps): import("react/jsx-runtime").JSX.Element;
-export declare function ClientPreferencesSavePersonalDataControl({ label, className, children }: ClientPreferencesSavePersonalDataControlProps): import("react/jsx-runtime").JSX.Element;
+export declare function ClientPreferencesNewsletterControl({ $content, $locale, className, children }: ClientPreferencesNewsletterControlProps): import("react/jsx-runtime").JSX.Element;
+export declare function ClientPreferencesSavePersonalDataControl({ $content, $locale, className, children }: ClientPreferencesSavePersonalDataControlProps): import("react/jsx-runtime").JSX.Element;
 //#endregion
 //# sourceMappingURL=client-preferences-fieldset.d.ts.map

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

@@ -1,15 +1,18 @@
 "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 { 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 { formatErrorCode } from "../../sdk/i18n/format-error-code.js";
 import { useDataOverride } from "../../sdk/data/data-override-context.js";
 import { useSession } from "../session/session.js";
-import { useFormRegistry } from "../../particles/form/form.js";
-import { Icon } from "../../particles/icon/icon.js";
 import { useEntityDataResolved } from "../../sdk/data/entity-resolution-context.js";
 import { useReactiveDataSettled } from "../../sdk/data/use-reactive-data-settled.js";
+import { useFormRegistry } from "../../particles/form/form.js";
+import { Icon } from "../../particles/icon/icon.js";
 import { Fieldset } from "../../particles/fieldset/fieldset.js";
 import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState } from "react";
 import { jsx, jsxs } from "react/jsx-runtime";
@@ -39,6 +42,90 @@ const fragment = `
     }
   }
 `;
+const ClientPreferencesFieldsetContent = defineContentType({
+	id: "client-preferences-fieldset",
+	title: "Client Preferences Fieldset",
+	description: "The preferences fieldset's loading and loaded announcements and its accessible group name.",
+	schema: {
+		type: "object",
+		additionalProperties: false,
+		properties: {
+			loadingLabel: {
+				type: "string",
+				title: "Loading announcement",
+				format: "icu-message",
+				messageSource: "Loading your preferences"
+			},
+			loadedLabel: {
+				type: "string",
+				title: "Loaded announcement",
+				format: "icu-message",
+				messageSource: "Your preferences are ready"
+			},
+			groupLabel: {
+				type: "string",
+				title: "Accessible group name",
+				format: "icu-message",
+				messageSource: "Your preferences",
+				messageOptional: true
+			},
+			genericErrorMessage: {
+				type: "string",
+				title: "Generic error message",
+				description: "Shown by FormError when the preferences could not be saved.",
+				format: "icu-message",
+				messageSource: "Unable to save your preferences. Please try again."
+			}
+		}
+	}
+});
+/**
+* The message for each refusal of the preferences write: every `ClientPreferencesUpdateErrorCode` plus
+* the client-minted transport failure. None is a fault the shopper can fix, so all share one message.
+* `dispatch` hands `FormError` this copy, and genericErrorMessage for an unknown code.
+*/
+const CLIENT_PREFERENCES_FIELDSET_ERROR_FIELDS = {
+	MISSING_CART_CONTEXT: "genericErrorMessage",
+	CART_NOT_FOUND: "genericErrorMessage",
+	NO_PREFERENCE_PROVIDED: "genericErrorMessage",
+	NETWORK_ERROR: "genericErrorMessage"
+};
+function wordClientPreferencesError(error, { format }) {
+	return {
+		code: error.code,
+		message: formatErrorCode(ClientPreferencesFieldsetContent, CLIENT_PREFERENCES_FIELDSET_ERROR_FIELDS, error, format, "genericErrorMessage")
+	};
+}
+const ClientPreferencesNewsletterControlContent = defineContentType({
+	id: "client-preferences-newsletter",
+	title: "Client Preferences Newsletter Control",
+	description: "The newsletter opt-in's label.",
+	schema: {
+		type: "object",
+		additionalProperties: false,
+		properties: { label: {
+			type: "string",
+			title: "Label",
+			format: "icu-message",
+			messageSource: "Email me with news and offers"
+		} }
+	}
+});
+const ClientPreferencesSavePersonalDataControlContent = defineContentType({
+	id: "client-preferences-save-data",
+	title: "Client Preferences Save Personal Data Control",
+	description: "The save-personal-data opt-in's label.",
+	schema: {
+		type: "object",
+		additionalProperties: false,
+		properties: { label: {
+			type: "string",
+			title: "Label",
+			format: "icu-message",
+			messageSource: "Save my information for next time"
+		} }
+	}
+});
 /** 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 = {};
@@ -60,6 +147,7 @@ const ClientPreferencesFieldsetDefinition = defineComponent({
 	name: "ClientPreferencesFieldset",
 	importPath: "@vtex/faststore/components",
 	component: ClientPreferencesFieldset,
+	content: ClientPreferencesFieldsetContent,
 	fragment,
 	fetchStrategy: "reactive",
 	skeleton: ClientPreferencesFieldsetSkeleton,
@@ -70,61 +158,40 @@ const ClientPreferencesFieldsetDefinition = defineComponent({
 		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."
+	schema: { skeletonCount: {
+		type: "number",
+		default: 2,
+		label: "Skeleton rows"
+	} },
+	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; it reads the $content fields loadingLabel and loadedLabel. Dispatches only the flags the shopper changed. The $content field groupLabel names the group as its accessible name; an unauthored one emits no aria-label, and a composed FieldsetLegend wins over it."
 });
 const ClientPreferencesNewsletterControlDefinition = defineComponent({
 	name: "ClientPreferencesNewsletterControl",
 	importPath: "@vtex/faststore/components",
 	component: ClientPreferencesNewsletterControl,
+	content: ClientPreferencesNewsletterControlContent,
 	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."
+	schema: {},
+	guideline: "The bound newsletter opt-in control, labelled by the $content field label; 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,
+	content: ClientPreferencesSavePersonalDataControlContent,
 	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."
+	schema: {},
+	guideline: "The bound save-personal-data opt-in control, labelled by the $content field label; 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`
@@ -148,13 +215,16 @@ const ClientPreferencesSavePersonalDataControlDefinition = defineComponent({
 * 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.
 */
-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 }) {
+function ClientPreferencesFieldset({ skeletonCount = CLIENT_PREFERENCES_SKELETON_ROWS, $content, $locale, className, children, $data: $dataProp, $actions: $actionsProp }) {
 	useNoAncestorFieldset("ClientPreferencesFieldset");
 	const $data = useDataOverride($dataProp);
 	const $actions = useActionsOverride($actionsProp);
+	const messages = useMessageFormatter(ClientPreferencesFieldsetContent, $content);
+	const { format } = messages;
+	const groupLabel = format("groupLabel");
 	const settled = useReactiveDataSettled();
 	const sliceResolved = useEntityDataResolved();
 	const resolved = settled && sliceResolved && $data !== void 0;
@@ -165,25 +235,28 @@ function ClientPreferencesFieldset({ skeletonCount = CLIENT_PREFERENCES_SKELETON
 	const latest = useRef({
 		$actions,
 		readOnly,
-		getFieldState
+		getFieldState,
+		messages
 	});
 	useEffect(() => {
 		latest.current = {
 			$actions,
 			readOnly,
-			getFieldState
+			getFieldState,
+			messages
 		};
 	}, [
 		$actions,
 		readOnly,
-		getFieldState
+		getFieldState,
+		messages
 	]);
 	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);
+		return (await update(payload)).map((error) => wordClientPreferencesError(error, latest.current.messages));
 	}, []);
 	const toPayload = useCallback((values) => {
 		const { getFieldState } = latest.current;
@@ -216,7 +289,7 @@ function ClientPreferencesFieldset({ skeletonCount = CLIENT_PREFERENCES_SKELETON
 		rules: NO_RULES
 	}), [saved, readOnly]);
 	const [announcement, setAnnouncement] = useState("");
-	const announced = resolved ? loadedLabel : loadingLabel;
+	const announced = format(resolved ? "loadedLabel" : "loadingLabel");
 	useEffect(() => {
 		setAnnouncement(announced);
 	}, [announced]);
@@ -224,7 +297,7 @@ function ClientPreferencesFieldset({ skeletonCount = CLIENT_PREFERENCES_SKELETON
 		className,
 		disabled: readOnly,
 		"aria-busy": resolved ? void 0 : true,
-		...groupLabel?.trim() ? { "aria-label": groupLabel } : {},
+		...groupLabel.trim() ? { "aria-label": groupLabel } : {},
 		"data-fs-client-preferences-fieldset": "",
 		...resolved ? {} : { "data-fs-client-preferences-fieldset-pending": "" },
 		...readOnly ? { "data-fs-client-preferences-fieldset-readonly": "" } : {},
@@ -256,44 +329,43 @@ function ClientPreferencesFieldsetSkeleton({ count = CLIENT_PREFERENCES_SKELETON
 	});
 }
 ClientPreferencesFieldset.Skeleton = ClientPreferencesFieldsetSkeleton;
-function PreferenceControl({ fieldKey, attr, defaultLabel, label, className, children }) {
+function PreferenceControl({ fieldKey, attr, 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,
+		label,
 		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] })
+			children: children ?? /* @__PURE__ */ jsxs(Field.Label, { children: [/* @__PURE__ */ jsx(Field.Checkbox, { children: /* @__PURE__ */ jsx(Checkbox.Indicator, { children: /* @__PURE__ */ jsx(Icon, { name: "checked" }) }) }), label] })
 		})
 	});
 }
-function ClientPreferencesNewsletterControl({ label, className, children }) {
+function ClientPreferencesNewsletterControl({ $content, $locale, className, children }) {
+	const { format } = useMessageFormatter(ClientPreferencesNewsletterControlContent, $content);
 	return /* @__PURE__ */ jsx(PreferenceControl, {
 		fieldKey: "optinNewsLetter",
 		attr: "newsletter",
-		defaultLabel: "Email me with news and offers",
-		label,
+		label: format("label"),
 		className,
 		children
 	});
 }
-function ClientPreferencesSavePersonalDataControl({ label, className, children }) {
+function ClientPreferencesSavePersonalDataControl({ $content, $locale, className, children }) {
+	const { format } = useMessageFormatter(ClientPreferencesSavePersonalDataControlContent, $content);
 	return /* @__PURE__ */ jsx(PreferenceControl, {
 		fieldKey: "savePersonalData",
 		attr: "save-personal-data",
-		defaultLabel: "Save my information for next time",
-		label,
+		label: format("label"),
 		className,
 		children
 	});
 }
 //#endregion
-export { ClientPreferencesFieldset, ClientPreferencesFieldsetDefinition, ClientPreferencesFieldsetSkeleton, ClientPreferencesNewsletterControl, ClientPreferencesNewsletterControlDefinition, ClientPreferencesSavePersonalDataControl, ClientPreferencesSavePersonalDataControlDefinition };
+export { CLIENT_PREFERENCES_FIELDSET_ERROR_FIELDS, ClientPreferencesFieldset, ClientPreferencesFieldsetContent, ClientPreferencesFieldsetDefinition, ClientPreferencesFieldsetSkeleton, ClientPreferencesNewsletterControl, ClientPreferencesNewsletterControlContent, ClientPreferencesNewsletterControlDefinition, ClientPreferencesSavePersonalDataControl, ClientPreferencesSavePersonalDataControlContent, ClientPreferencesSavePersonalDataControlDefinition };
 
 //# sourceMappingURL=client-preferences-fieldset.js.map