@vtex/faststore 0.0.1

package/dist/matter/delivery-options/delivery-options-controller.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"delivery-options-controller.js","names":[],"sources":["../../../src/matter/delivery-options/delivery-options-controller.tsx"],"sourcesContent":["'use client';\n\nimport { defineComponent } from '@vtex/fs-core';\nimport {\n  type ComponentPropsWithRef,\n  cloneElement,\n  createContext,\n  isValidElement,\n  type ReactNode,\n  useContext,\n  useMemo,\n  useState,\n} from 'react';\nimport type { ComponentActions } from '../../sdk/actions/types.js';\nimport {\n  OptionItemContext,\n  type ShippingOption,\n  ShippingSimulatorContext,\n  ShippingSimulatorOptionName,\n  ShippingSimulatorOptionPrice,\n} from '../shipping-simulator/shipping-simulator.js';\nimport { DeliveryOptionsListBody } from './delivery-options.js';\nimport { type RawDeliveryOptionsData, useDeliveryOptionSelection } from './use-delivery-option-selection.js';\n\n/**\n * The collapsed delivery-option surfaces (centered modal / slide-in panel) as a controller +\n * composed particles, replacing the former monolithic `DeliveryOptionsDialog` / `DeliveryOptionsDrawer`\n * (Decision 8). The page composes a raw `DialogRoot` or `DrawerRoot` and each of its particles\n * (`DialogTrigger` / `DialogBackdrop` / `DialogPopup` …) directly as `page.json` nodes, so every part\n * is a swatch-addressable node with zero Tailwind baked into the package — the portaled backdrop/popup\n * a descendant selector could not reach in the monolith are now first-class nodes (Decision 9).\n *\n * `DeliveryOptionsController` owns state only and renders no markup: it runs the shared\n * `useDeliveryOptionSelection` engine, holds the open state, and provides both the FSPG-832\n * `ShippingSimulatorContext` and a `DeliveryOptions` selection context to its subtree, then injects\n * `open` / `onOpenChange` into its single overlay-`Root` child via `cloneElement` — the same mechanism\n * as `CartOpenOnAdd` and `ShippingAddressSavedAddressDrawerController`. A single engine behind the\n * context keeps the trigger echo (`DeliveryOptionsSummary`) and the option list (`DeliveryOptionsList`)\n * on one selection state, so even a local `mockOptions` pick reflects on the trigger.\n *\n * Selection follows the shared rule (INV-10/11): a real pick dispatches `shipping.selectOption` and\n * the surface closes only once it resolves without a `userError`; a rejected pick keeps it open with\n * the inline `role=\"alert\"`; a `mockOptions` pick updates local state and closes immediately.\n */\n\nconst fragment = /* GraphQL */ `\n  fragment DeliveryOptionsControllerData on Query {\n    shipping {\n      id\n      options {\n        id\n        name\n        channel\n        shippingEstimate {\n          value\n          unit\n        }\n        price {\n          amount\n          currencyCode\n        }\n        listPrice {\n          amount\n          currencyCode\n        }\n      }\n      selectedOptionId\n    }\n  }\n`;\n\n// ---------------------------------------------------------------------------\n// Selection context — provided by DeliveryOptionsController, read by the leaves\n// ---------------------------------------------------------------------------\n\nexport type DeliveryOptionsContextValue = Readonly<{\n  /** Resolved option rows (real when the fetch has any, else the `mockOptions` fallback). */\n  options: ShippingOption[];\n  /** Group value: the persisted `selectedOptionId` for real data, local state under mock. */\n  selectedOptionId: string | null;\n  /** First `userError` message from the latest real selection, or `null`. */\n  selectionError: string | null;\n  /** Selects an option and closes the surface once the selection resolves without a `userError`. */\n  selectOption: (optionId: string) => void;\n}>;\n\nconst DELIVERY_OPTIONS_UNSET = Symbol('DeliveryOptionsContextUnset');\n\nconst DeliveryOptionsContextInternal = createContext<DeliveryOptionsContextValue | typeof DELIVERY_OPTIONS_UNSET>(\n  DELIVERY_OPTIONS_UNSET,\n);\n\n/**\n * Read the delivery-option selection state from the nearest `DeliveryOptionsController`. Throws when\n * called outside a controller subtree.\n */\nexport function useDeliveryOptions(): DeliveryOptionsContextValue {\n  const ctx = useContext(DeliveryOptionsContextInternal);\n  if (ctx === DELIVERY_OPTIONS_UNSET) {\n    throw new Error('useDeliveryOptions() must be used inside a <DeliveryOptionsController> subtree.');\n  }\n  return ctx;\n}\n\n// The minimal open-state shape the controller injects into its overlay-Root child; both\n// `DialogRoot` and `DrawerRoot` accept it.\ntype OverlayOpenProps = {\n  open?: boolean;\n  onOpenChange?: (open: boolean) => void;\n};\n\n// ---------------------------------------------------------------------------\n// Props\n// ---------------------------------------------------------------------------\n\nexport type DeliveryOptionsControllerProps = {\n  /** Shipping slice forwarded by the reactive runtime; `null` until shipping resolves. */\n  $data?: RawDeliveryOptionsData | null;\n  /** Compiler-injected action surface; carries `shipping.selectOption`. */\n  $actions?: ComponentActions;\n  /** Local/dev fallback rows, used only when the reactive fetch resolves no options. */\n  mockOptions?: ShippingOption[];\n  /** The single overlay `Root` to control — a `DialogRoot` (modal) or `DrawerRoot` (slide-in). */\n  children?: ReactNode;\n};\n\nexport type DeliveryOptionsSummaryProps = ComponentPropsWithRef<'span'> & {\n  /** Optional prefix shown before the summary value (e.g. \"Forma de entrega\"). */\n  label?: string;\n  /** Text shown while nothing is selected. */\n  placeholder?: string;\n  /** Separator between the selected option name and price. */\n  separator?: string;\n};\n\nexport type DeliveryOptionsListProps = ComponentPropsWithRef<'div'>;\n\n// ---------------------------------------------------------------------------\n// Definitions\n// ---------------------------------------------------------------------------\n\nexport const DeliveryOptionsControllerDefinition = defineComponent<DeliveryOptionsControllerProps>({\n  name: 'DeliveryOptionsController',\n  importPath: '@vtex/faststore/components',\n  component: DeliveryOptionsController,\n  fragment,\n  fetchStrategy: 'reactive',\n  actions: { shipping: ['selectOption'] },\n  // Its own `delivery-options` selection context, plus the reused option leaves' runtime contexts\n  // (Decision 2): `shipping-simulator-option` for the leaves composed under DeliveryOptionsList, and\n  // the outer `shipping-simulator` this controller also provides at runtime.\n  providesContext: ['delivery-options', 'shipping-simulator', 'shipping-simulator-option'],\n  editor: { label: 'Delivery Options Controller', category: 'commerce' },\n  schema: {\n    mockOptions: { type: 'array', label: 'Mock options (local/dev fallback, ignored once real data has options)' },\n  },\n  guideline:\n    'State-only controller for a collapsed delivery-option picker: wrap a single DialogRoot (centered modal) or DrawerRoot (slide-in) child and it becomes controlled — the surface opens from its trigger and closes once a real selection succeeds; a userError keeps it open. Renders no markup and bakes no styling: compose the overlay particles (DialogTrigger/DialogPortal/DialogBackdrop/DialogPopup or the Drawer equivalents) directly as page nodes, place a DeliveryOptionsSummary inside the trigger (echoes the selected name + price, or a placeholder) and a DeliveryOptionsList inside the popup (the option radio group; put the reused ShippingSimulatorOption leaves as its children). Selection dispatches $actions.shipping.selectOption; mockOptions is a local/dev-only fallback. Mirrors the CartOpenOnAdd / ShippingAddressSavedAddressDrawerController pattern.',\n});\n\nexport const DeliveryOptionsSummaryDefinition = defineComponent<DeliveryOptionsSummaryProps>({\n  name: 'DeliveryOptionsSummary',\n  importPath: '@vtex/faststore/components',\n  component: DeliveryOptionsSummary,\n  requiresContext: 'delivery-options',\n  editor: { label: 'Delivery Options Summary', category: 'commerce' },\n  schema: {\n    label: { type: 'string', label: 'Trigger label prefix' },\n    placeholder: { type: 'string', default: 'Selecionar forma de entrega', label: 'Placeholder' },\n    separator: { type: 'string', default: ' — ', label: 'Summary separator' },\n  },\n  guideline:\n    'The collapsed picker trigger echo: renders the selected option name + price (reusing the FSPG-832 option leaves), or a placeholder while nothing is selected. Place it inside the DialogTrigger / DrawerTrigger of a DeliveryOptionsController subtree. Reads the shared selection context, so it reflects the current pick — real or mockOptions. Must be inside DeliveryOptionsController.',\n});\n\nexport const DeliveryOptionsListDefinition = defineComponent<DeliveryOptionsListProps>({\n  name: 'DeliveryOptionsList',\n  importPath: '@vtex/faststore/components',\n  component: DeliveryOptionsList,\n  requiresContext: 'delivery-options',\n  editor: { label: 'Delivery Options List', category: 'commerce' },\n  schema: {},\n  guideline:\n    'The collapsed picker body: the whole-cart option list as a radio group bound to the selected option, plus the inline selection error (role=\"alert\"). Place it inside the DialogPopup / DrawerPopup of a DeliveryOptionsController subtree, with the reused option leaves (ShippingSimulatorOption, OptionName, OptionEstimate, OptionPrice, OptionFreeBadge) as its children template. Picking a row dispatches the selection and closes the surface on success. Must be inside DeliveryOptionsController.',\n});\n\n// ---------------------------------------------------------------------------\n// Implementations\n// ---------------------------------------------------------------------------\n\nexport function DeliveryOptionsController({ $data, $actions, mockOptions, children }: DeliveryOptionsControllerProps) {\n  const { options, selectedOptionId, selectionError, selectOption, contextValue } = useDeliveryOptionSelection({\n    $data,\n    $actions,\n    mockOptions,\n  });\n  const [open, setOpen] = useState(false);\n\n  const delivery = useMemo<DeliveryOptionsContextValue>(\n    () => ({\n      options,\n      selectedOptionId,\n      selectionError,\n      selectOption: (optionId: string) =>\n        selectOption(optionId, {\n          onSettled: (ok) => {\n            if (ok) setOpen(false);\n          },\n        }),\n    }),\n    [options, selectedOptionId, selectionError, selectOption],\n  );\n\n  if (!isValidElement<OverlayOpenProps>(children)) {\n    return children;\n  }\n\n  return (\n    <ShippingSimulatorContext value={contextValue}>\n      <DeliveryOptionsContextInternal value={delivery}>\n        {cloneElement(children, { open, onOpenChange: (next: boolean) => setOpen(next) })}\n      </DeliveryOptionsContextInternal>\n    </ShippingSimulatorContext>\n  );\n}\n\nexport function DeliveryOptionsSummary({\n  label,\n  placeholder = 'Selecionar forma de entrega',\n  separator = ' — ',\n  className,\n  ...props\n}: DeliveryOptionsSummaryProps) {\n  const { options, selectedOptionId } = useDeliveryOptions();\n  const selectedOption = options.find((option) => option.id === selectedOptionId) ?? null;\n\n  return (\n    <span {...props} className={className} data-fs-delivery-options-summary=\"\">\n      {label ? <span data-fs-delivery-options-summary-label=\"\">{label}</span> : null}\n      {selectedOption ? (\n        <OptionItemContext value={selectedOption}>\n          <span data-fs-delivery-options-summary-value=\"\">\n            <ShippingSimulatorOptionName />\n            <span data-fs-delivery-options-summary-separator=\"\">{separator}</span>\n            <ShippingSimulatorOptionPrice />\n          </span>\n        </OptionItemContext>\n      ) : (\n        <span data-fs-delivery-options-summary-placeholder=\"\">{placeholder}</span>\n      )}\n    </span>\n  );\n}\n\nexport function DeliveryOptionsList({ className, children, ...props }: DeliveryOptionsListProps) {\n  const { options, selectedOptionId, selectionError, selectOption } = useDeliveryOptions();\n\n  return (\n    <DeliveryOptionsListBody\n      {...props}\n      className={className}\n      options={options}\n      selectedOptionId={selectedOptionId}\n      selectionError={selectionError}\n      onSelectOption={selectOption}\n    >\n      {children}\n    </DeliveryOptionsListBody>\n  );\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6CA,MAAM,WAAyB;;;;;;;;;;;;;;;;;;;;;;;;;AAyC/B,MAAM,yBAAyB,OAAO,6BAA6B;AAEnE,MAAM,iCAAiC,cACrC,sBACF;;;;;AAMA,SAAgB,qBAAkD;CAChE,MAAM,MAAM,WAAW,8BAA8B;CACrD,IAAI,QAAQ,wBACV,MAAM,IAAI,MAAM,iFAAiF;CAEnG,OAAO;AACT;AAuCA,MAAa,sCAAsC,gBAAgD;CACjG,MAAM;CACN,YAAY;CACZ,WAAW;CACX;CACA,eAAe;CACf,SAAS,EAAE,UAAU,CAAC,cAAc,EAAE;CAItC,iBAAiB;EAAC;EAAoB;EAAsB;CAA2B;CACvF,QAAQ;EAAE,OAAO;EAA+B,UAAU;CAAW;CACrE,QAAQ,EACN,aAAa;EAAE,MAAM;EAAS,OAAO;CAAwE,EAC/G;CACA,WACE;AACJ,CAAC;AAED,MAAa,mCAAmC,gBAA6C;CAC3F,MAAM;CACN,YAAY;CACZ,WAAW;CACX,iBAAiB;CACjB,QAAQ;EAAE,OAAO;EAA4B,UAAU;CAAW;CAClE,QAAQ;EACN,OAAO;GAAE,MAAM;GAAU,OAAO;EAAuB;EACvD,aAAa;GAAE,MAAM;GAAU,SAAS;GAA+B,OAAO;EAAc;EAC5F,WAAW;GAAE,MAAM;GAAU,SAAS;GAAO,OAAO;EAAoB;CAC1E;CACA,WACE;AACJ,CAAC;AAED,MAAa,gCAAgC,gBAA0C;CACrF,MAAM;CACN,YAAY;CACZ,WAAW;CACX,iBAAiB;CACjB,QAAQ;EAAE,OAAO;EAAyB,UAAU;CAAW;CAC/D,QAAQ,CAAC;CACT,WACE;AACJ,CAAC;AAMD,SAAgB,0BAA0B,EAAE,OAAO,UAAU,aAAa,YAA4C;CACpH,MAAM,EAAE,SAAS,kBAAkB,gBAAgB,cAAc,iBAAiB,2BAA2B;EAC3G;EACA;EACA;CACF,CAAC;CACD,MAAM,CAAC,MAAM,WAAW,SAAS,KAAK;CAEtC,MAAM,WAAW,eACR;EACL;EACA;EACA;EACA,eAAe,aACb,aAAa,UAAU,EACrB,YAAY,OAAO;GACjB,IAAI,IAAI,QAAQ,KAAK;EACvB,EACF,CAAC;CACL,IACA;EAAC;EAAS;EAAkB;EAAgB;CAAY,CAC1D;CAEA,IAAI,CAAC,eAAiC,QAAQ,GAC5C,OAAO;CAGT,OACE,oBAAC,0BAAD;EAA0B,OAAO;EAC/B,UAAA,oBAAC,gCAAD;GAAgC,OAAO;GACpC,UAAA,aAAa,UAAU;IAAE;IAAM,eAAe,SAAkB,QAAQ,IAAI;GAAE,CAAC;EAClD,CAAA;CACR,CAAA;AAE9B;AAEA,SAAgB,uBAAuB,EACrC,OACA,cAAc,+BACd,YAAY,OACZ,WACA,GAAG,SAC2B;CAC9B,MAAM,EAAE,SAAS,qBAAqB,mBAAmB;CACzD,MAAM,iBAAiB,QAAQ,MAAM,WAAW,OAAO,OAAO,gBAAgB,KAAK;CAEnF,OACE,qBAAC,QAAD;EAAM,GAAI;EAAkB;EAAW,oCAAiC;EAAxE,UAAA,CACG,QAAQ,oBAAC,QAAD;GAAM,0CAAuC;GAAI,UAAA;EAAY,CAAA,IAAI,MACzE,iBACC,oBAAC,mBAAD;GAAmB,OAAO;GACxB,UAAA,qBAAC,QAAD;IAAM,0CAAuC;IAA7C,UAAA;KACE,oBAAC,6BAAD,CAA8B,CAAA;KAC9B,oBAAC,QAAD;MAAM,8CAA2C;MAAI,UAAA;KAAgB,CAAA;KACrE,oBAAC,8BAAD,CAA+B,CAAA;IAC3B;;EACW,CAAA,IAEnB,oBAAC,QAAD;GAAM,gDAA6C;GAAI,UAAA;EAAkB,CAAA,CAEvE;;AAEV;AAEA,SAAgB,oBAAoB,EAAE,WAAW,UAAU,GAAG,SAAmC;CAC/F,MAAM,EAAE,SAAS,kBAAkB,gBAAgB,iBAAiB,mBAAmB;CAEvF,OACE,oBAAC,yBAAD;EACE,GAAI;EACO;EACF;EACS;EACF;EAChB,gBAAgB;EAEf;CACsB,CAAA;AAE7B"}

package/dist/matter/delivery-options/delivery-options.d.ts

@@ -0,0 +1,31 @@
+import { ComponentDefinition } from "../../core/dist/define-component.js";
+import "../../core/dist/index.js";
+import { ShippingOption } from "../shipping-simulator/shipping-simulator.js";
+import { ComponentActions } from "../../sdk/actions/types.js";
+import { RawDeliveryOptionsData } from "./use-delivery-option-selection.js";
+import { ComponentPropsWithRef } from "react";
+//#region src/matter/delivery-options/delivery-options.d.ts
+export type DeliveryOptionsRootProps = ComponentPropsWithRef<'div'> & {
+  /**
+   * Shipping slice forwarded by the reactive runtime (`ReactiveDataProvider`) — it is the value of
+   * the `shipping` top-level field on `DeliveryOptionsData on Query`, not the wrapping
+   * `{ shipping: … }` shape. Receives `null` when shipping has not yet resolved.
+   */
+  $data?: RawDeliveryOptionsData | null;
+  /** Compiler-injected action surface; carries `shipping.selectOption`. */
+  $actions?: ComponentActions;
+  /**
+   * Local/dev fallback rows, used only when the reactive fetch resolves no options — real data
+   * always wins the moment it has any. `Shipping.options` is non-nullable, so a genuinely empty
+   * cart is indistinguishable from "no data yet" at this prop's shape; setting `mockOptions` is an
+   * explicit per-page opt-in that accepts showing these rows in both cases. Omit on production
+   * pages. Selecting a mock row is handled entirely with local state and never calls
+   * `$actions.shipping.selectOption` — there is no real cart/address for the real mutation to act
+   * on, so dispatching it would only ever surface a domain error (e.g. `MISSING_SHIPPING_ADDRESS`).
+   */
+  mockOptions?: ShippingOption[];
+};
+export declare const DeliveryOptionsRootDefinition: ComponentDefinition<DeliveryOptionsRootProps>;
+export declare function DeliveryOptionsRoot({ $data, $actions, mockOptions, className, children, ...props }: DeliveryOptionsRootProps): import("react/jsx-runtime").JSX.Element;
+//#endregion
+//# sourceMappingURL=delivery-options.d.ts.map

package/dist/matter/delivery-options/delivery-options.js

@@ -0,0 +1,103 @@
+"use client";
+import { defineComponent } from "../../core/dist/define-component.js";
+import "../../core/dist/index.js";
+import { RadioGroup, RadioRoot } from "../../particles/radio/radio.js";
+import { OptionItemContext, ShippingSimulatorContext } from "../shipping-simulator/shipping-simulator.js";
+import { useDeliveryOptionSelection } from "./use-delivery-option-selection.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+const DeliveryOptionsRootDefinition = defineComponent({
+	name: "DeliveryOptionsRoot",
+	importPath: "@vtex/faststore/components",
+	component: DeliveryOptionsRoot,
+	fragment: `
+  fragment DeliveryOptionsData on Query {
+    shipping {
+      id
+      options {
+        id
+        name
+        channel
+        shippingEstimate {
+          value
+          unit
+        }
+        price {
+          amount
+          currencyCode
+        }
+        listPrice {
+          amount
+          currencyCode
+        }
+      }
+      selectedOptionId
+    }
+  }
+`,
+	fetchStrategy: "reactive",
+	actions: { shipping: ["selectOption"] },
+	editor: {
+		label: "Delivery Options",
+		category: "commerce"
+	},
+	schema: { mockOptions: {
+		type: "array",
+		label: "Mock options (local/dev fallback, ignored once real data has options)"
+	} },
+	providesContext: ["shipping-simulator", "shipping-simulator-option"],
+	guideline: "Root for the whole-cart delivery-option list at the delivery step: renders Shipping.options as a radio group bound to selectedOptionId, reusing the FSPG-832 option leaves (ShippingSimulatorOption, OptionName, OptionEstimate, OptionPrice, OptionFreeBadge) as the per-option template placed as children. Selecting a row dispatches $actions.shipping.selectOption. No local selection state — the group value is always the server selectedOptionId. mockOptions is a local/dev-only fallback rendered when the real fetch has no options; omit it in production."
+});
+/**
+* The list body shared by `DeliveryOptionsRoot` (always-open) and `DeliveryOptionsList` (the
+* collapsed-surface body under `DeliveryOptionsController`): the inline selection error plus the
+* radio group of options, reusing the FSPG-832 option leaves as the per-option `children` template.
+* It owns no data or selection engine — the caller resolves `options` / `selectedOptionId` /
+* `selectionError` and supplies the `onSelect` dispatch, so both surfaces render through one
+* component and cannot drift. Not registered: it renders no independently placeable part of its own
+* (the `data-fs-delivery-options` container hook and the reused leaves are the addressable parts).
+*/
+function DeliveryOptionsListBody({ options, selectedOptionId, selectionError, onSelectOption, className, children, ...props }) {
+	return /* @__PURE__ */ jsxs("div", {
+		...props,
+		className,
+		"data-fs-delivery-options": "",
+		children: [selectionError ? /* @__PURE__ */ jsx("div", {
+			role: "alert",
+			"data-fs-delivery-options-error": "",
+			children: selectionError
+		}) : null, options.length > 0 ? /* @__PURE__ */ jsx(RadioGroup, {
+			value: selectedOptionId ?? "",
+			onValueChange: onSelectOption,
+			children: options.map((option) => /* @__PURE__ */ jsx(OptionItemContext, {
+				value: option,
+				children: /* @__PURE__ */ jsx(RadioRoot, {
+					value: option.id,
+					children
+				})
+			}, option.id))
+		}) : null]
+	});
+}
+function DeliveryOptionsRoot({ $data, $actions, mockOptions, className, children, ...props }) {
+	const { options, selectedOptionId, selectionError, selectOption, contextValue } = useDeliveryOptionSelection({
+		$data,
+		$actions,
+		mockOptions
+	});
+	return /* @__PURE__ */ jsx(ShippingSimulatorContext, {
+		value: contextValue,
+		children: /* @__PURE__ */ jsx(DeliveryOptionsListBody, {
+			...props,
+			className,
+			options,
+			selectedOptionId,
+			selectionError,
+			onSelectOption: (optionId) => selectOption(optionId),
+			children
+		})
+	});
+}
+//#endregion
+export { DeliveryOptionsListBody, DeliveryOptionsRoot, DeliveryOptionsRootDefinition };
+
+//# sourceMappingURL=delivery-options.js.map

package/dist/matter/delivery-options/delivery-options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"delivery-options.js","names":[],"sources":["../../../src/matter/delivery-options/delivery-options.tsx"],"sourcesContent":["'use client';\n\nimport { defineComponent } from '@vtex/fs-core';\nimport type { ComponentPropsWithRef } from 'react';\nimport { RadioGroup, RadioRoot } from '../../particles/radio/radio.js';\nimport type { ComponentActions } from '../../sdk/actions/types.js';\nimport {\n  OptionItemContext,\n  type ShippingOption,\n  ShippingSimulatorContext,\n} from '../shipping-simulator/shipping-simulator.js';\nimport { type RawDeliveryOptionsData, useDeliveryOptionSelection } from './use-delivery-option-selection.js';\n\n/**\n * The `DeliveryOptions` matter section (specs/delivery-options-step.md, T3 of the Single Address\n * Delivery epic). `DeliveryOptionsRoot` is a reactive Root over the persisted `Shipping` entity\n * (Decision 1) that becomes the THIRD provider of the FSPG-832 option-leaf runtime contexts —\n * `ShippingSimulatorContext` and the per-option `OptionItemContext` — alongside the two existing\n * simulator Roots (Decision 2), so `ShippingSimulatorOption` / `OptionName` / `OptionEstimate` /\n * `OptionPrice` / `OptionFreeBadge` render identically here with zero edits to those leaves.\n * `children` is the per-option template, rendered once per option inside a `RadioRoot` (radio\n * particle) whose group value is bound directly to `selectedOptionId` (Decision 5 — no local\n * selection state); changing it fires the `shipping.selectOption` action. Fields the reused leaves\n * do not read for this section (`postalCode`, `setPostalCode`, `submit`, `status`) are inert\n * defaults, satisfying the shared context type without a simulation flow. Exception: while\n * rendering `mockOptions` (no real data), selection is local-only and never dispatches the action —\n * see `mockOptions` on `DeliveryOptionsRootProps`.\n */\n\n// ---------------------------------------------------------------------------\n// GraphQL Fragment — raw template literal, matching the ShippingSimulator matter's own convention\n// (not yet migrated to the codegen `graphql()` pipeline; see codegen.ts's documents glob comment).\n//\n// Selects `shipping { id ... }` (not shown in the spec's fragment snippet) so Apollo's\n// InMemoryCache normalizes `Shipping` by id — required for `shippingOptionSelect`'s returned\n// `shipping` to update the same cache entity this fragment reads (Decision 1/Decision 5's\n// \"reactive cache, no local state\" only holds if both sides normalize to the same entity).\n// ---------------------------------------------------------------------------\n\nconst fragment = /* GraphQL */ `\n  fragment DeliveryOptionsData on Query {\n    shipping {\n      id\n      options {\n        id\n        name\n        channel\n        shippingEstimate {\n          value\n          unit\n        }\n        price {\n          amount\n          currencyCode\n        }\n        listPrice {\n          amount\n          currencyCode\n        }\n      }\n      selectedOptionId\n    }\n  }\n`;\n\n// ---------------------------------------------------------------------------\n// Props\n// ---------------------------------------------------------------------------\n\nexport type DeliveryOptionsRootProps = ComponentPropsWithRef<'div'> & {\n  /**\n   * Shipping slice forwarded by the reactive runtime (`ReactiveDataProvider`) — it is the value of\n   * the `shipping` top-level field on `DeliveryOptionsData on Query`, not the wrapping\n   * `{ shipping: … }` shape. Receives `null` when shipping has not yet resolved.\n   */\n  $data?: RawDeliveryOptionsData | null;\n  /** Compiler-injected action surface; carries `shipping.selectOption`. */\n  $actions?: ComponentActions;\n  /**\n   * Local/dev fallback rows, used only when the reactive fetch resolves no options — real data\n   * always wins the moment it has any. `Shipping.options` is non-nullable, so a genuinely empty\n   * cart is indistinguishable from \"no data yet\" at this prop's shape; setting `mockOptions` is an\n   * explicit per-page opt-in that accepts showing these rows in both cases. Omit on production\n   * pages. Selecting a mock row is handled entirely with local state and never calls\n   * `$actions.shipping.selectOption` — there is no real cart/address for the real mutation to act\n   * on, so dispatching it would only ever surface a domain error (e.g. `MISSING_SHIPPING_ADDRESS`).\n   */\n  mockOptions?: ShippingOption[];\n};\n\n// ---------------------------------------------------------------------------\n// Definition\n// ---------------------------------------------------------------------------\n\nexport const DeliveryOptionsRootDefinition = defineComponent<DeliveryOptionsRootProps>({\n  name: 'DeliveryOptionsRoot',\n  importPath: '@vtex/faststore/components',\n  component: DeliveryOptionsRoot,\n  fragment,\n  fetchStrategy: 'reactive',\n  actions: { shipping: ['selectOption'] },\n  editor: { label: 'Delivery Options', category: 'commerce' },\n  schema: {\n    mockOptions: { type: 'array', label: 'Mock options (local/dev fallback, ignored once real data has options)' },\n  },\n  // Re-provides the reused option leaves' runtime contexts (Decision 2): the inner\n  // `shipping-simulator-option` token is required — the option leaves compose as direct children\n  // here with no `ShippingSimulatorOptions` node between them — and the outer `shipping-simulator`\n  // token reflects the `ShippingSimulatorContext` this Root also provides at runtime.\n  providesContext: ['shipping-simulator', 'shipping-simulator-option'],\n  guideline:\n    'Root for the whole-cart delivery-option list at the delivery step: renders Shipping.options as a radio group bound to selectedOptionId, reusing the FSPG-832 option leaves (ShippingSimulatorOption, OptionName, OptionEstimate, OptionPrice, OptionFreeBadge) as the per-option template placed as children. Selecting a row dispatches $actions.shipping.selectOption. No local selection state — the group value is always the server selectedOptionId. mockOptions is a local/dev-only fallback rendered when the real fetch has no options; omit it in production.',\n});\n\n// ---------------------------------------------------------------------------\n// Shared list body\n// ---------------------------------------------------------------------------\n\nexport type DeliveryOptionsListBodyProps = ComponentPropsWithRef<'div'> & {\n  /** Resolved option rows (real or mock), supplied by the caller's selection engine. */\n  options: ShippingOption[];\n  /** Group value bound to the radio group; `null` renders nothing selected. */\n  selectedOptionId: string | null;\n  /** First `userError` message from the latest selection, or `null`; rendered as `role=\"alert\"`. */\n  selectionError: string | null;\n  /** Dispatched on a row change with the picked option id. */\n  onSelectOption: (optionId: string) => void;\n};\n\n/**\n * The list body shared by `DeliveryOptionsRoot` (always-open) and `DeliveryOptionsList` (the\n * collapsed-surface body under `DeliveryOptionsController`): the inline selection error plus the\n * radio group of options, reusing the FSPG-832 option leaves as the per-option `children` template.\n * It owns no data or selection engine — the caller resolves `options` / `selectedOptionId` /\n * `selectionError` and supplies the `onSelect` dispatch, so both surfaces render through one\n * component and cannot drift. Not registered: it renders no independently placeable part of its own\n * (the `data-fs-delivery-options` container hook and the reused leaves are the addressable parts).\n */\nexport function DeliveryOptionsListBody({\n  options,\n  selectedOptionId,\n  selectionError,\n  onSelectOption,\n  className,\n  children,\n  ...props\n}: DeliveryOptionsListBodyProps) {\n  return (\n    <div {...props} className={className} data-fs-delivery-options=\"\">\n      {selectionError ? (\n        <div role=\"alert\" data-fs-delivery-options-error=\"\">\n          {selectionError}\n        </div>\n      ) : null}\n      {options.length > 0 ? (\n        <RadioGroup value={selectedOptionId ?? ''} onValueChange={onSelectOption}>\n          {options.map((option) => (\n            <OptionItemContext key={option.id} value={option}>\n              <RadioRoot value={option.id}>{children}</RadioRoot>\n            </OptionItemContext>\n          ))}\n        </RadioGroup>\n      ) : null}\n    </div>\n  );\n}\n\n// ---------------------------------------------------------------------------\n// Implementation\n// ---------------------------------------------------------------------------\n\nexport function DeliveryOptionsRoot({\n  $data,\n  $actions,\n  mockOptions,\n  className,\n  children,\n  ...props\n}: DeliveryOptionsRootProps) {\n  const { options, selectedOptionId, selectionError, selectOption, contextValue } = useDeliveryOptionSelection({\n    $data,\n    $actions,\n    mockOptions,\n  });\n\n  return (\n    <ShippingSimulatorContext value={contextValue}>\n      <DeliveryOptionsListBody\n        {...props}\n        className={className}\n        options={options}\n        selectedOptionId={selectedOptionId}\n        selectionError={selectionError}\n        onSelectOption={(optionId) => selectOption(optionId)}\n      >\n        {children}\n      </DeliveryOptionsListBody>\n    </ShippingSimulatorContext>\n  );\n}\n"],"mappings":";;;;;;;AA8FA,MAAa,gCAAgC,gBAA0C;CACrF,MAAM;CACN,YAAY;CACZ,WAAW;CACX;;;;;;;;;;;;;;;;;;;;;;;;;CACA,eAAe;CACf,SAAS,EAAE,UAAU,CAAC,cAAc,EAAE;CACtC,QAAQ;EAAE,OAAO;EAAoB,UAAU;CAAW;CAC1D,QAAQ,EACN,aAAa;EAAE,MAAM;EAAS,OAAO;CAAwE,EAC/G;CAKA,iBAAiB,CAAC,sBAAsB,2BAA2B;CACnE,WACE;AACJ,CAAC;;;;;;;;;;AA0BD,SAAgB,wBAAwB,EACtC,SACA,kBACA,gBACA,gBACA,WACA,UACA,GAAG,SAC4B;CAC/B,OACE,qBAAC,OAAD;EAAK,GAAI;EAAkB;EAAW,4BAAyB;EAA/D,UAAA,CACG,iBACC,oBAAC,OAAD;GAAK,MAAK;GAAQ,kCAA+B;GAC9C,UAAA;EACE,CAAA,IACH,MACH,QAAQ,SAAS,IAChB,oBAAC,YAAD;GAAY,OAAO,oBAAoB;GAAI,eAAe;GACvD,UAAA,QAAQ,KAAK,WACZ,oBAAC,mBAAD;IAAmC,OAAO;IACxC,UAAA,oBAAC,WAAD;KAAW,OAAO,OAAO;KAAK;IAAoB,CAAA;GACjC,GAFK,OAAO,EAEZ,CACpB;EACS,CAAA,IACV,IACD;;AAET;AAMA,SAAgB,oBAAoB,EAClC,OACA,UACA,aACA,WACA,UACA,GAAG,SACwB;CAC3B,MAAM,EAAE,SAAS,kBAAkB,gBAAgB,cAAc,iBAAiB,2BAA2B;EAC3G;EACA;EACA;CACF,CAAC;CAED,OACE,oBAAC,0BAAD;EAA0B,OAAO;EAC/B,UAAA,oBAAC,yBAAD;GACE,GAAI;GACO;GACF;GACS;GACF;GAChB,iBAAiB,aAAa,aAAa,QAAQ;GAElD;EACsB,CAAA;CACD,CAAA;AAE9B"}

package/dist/matter/delivery-options/use-delivery-option-selection.d.ts

@@ -0,0 +1,9 @@
+import { ShippingOption } from "../shipping-simulator/shipping-simulator.js";
+import "../../sdk/actions/types.js";
+//#region src/matter/delivery-options/use-delivery-option-selection.d.ts
+export type RawDeliveryOptionsData = {
+  options: ShippingOption[];
+  selectedOptionId: string | null;
+};
+//#endregion
+//# sourceMappingURL=use-delivery-option-selection.d.ts.map

package/dist/matter/delivery-options/use-delivery-option-selection.js

@@ -0,0 +1,76 @@
+"use client";
+import { useDataOverride } from "../../sdk/data/data-override-context.js";
+import { useMemo, useRef, useState } from "react";
+//#region src/matter/delivery-options/use-delivery-option-selection.ts
+const EMPTY_OPTIONS = [];
+/**
+* Shared selection engine behind `DeliveryOptionsRoot` and its collapsed variants
+* (`DeliveryOptionsAccordion` / `Dialog` / `Drawer`). It owns the four behaviours the spec
+* requires identically across every surface, so they cannot drift apart:
+*
+* - real-vs-mock option resolution — real options of any length always win (INV-8);
+* - the local mock selection, reset whenever the real↔mock boundary flips so a stale mock
+*   choice from before a real-options interlude never reappears (Decision 7);
+* - the reactive `selectedOptionId` binding (Decision 5 — no local state for real data);
+* - the request-sequenced `selectOption` dispatch that resolves `userErrors` for inline display
+*   (US-4), guarding against an earlier click's result overwriting a later one.
+*
+* Callers render `selectionError` (as `role="alert"`) and wire `contextValue` themselves; the
+* collapsed variants additionally use `onSettled` to close their panel only on success.
+*/
+function useDeliveryOptionSelection({ $data: $dataProp, $actions, mockOptions }) {
+	const $data = useDataOverride($dataProp);
+	const realOptions = $data?.options;
+	const usingMockOptions = !realOptions?.length && !!mockOptions?.length;
+	const options = realOptions?.length ? realOptions : mockOptions ?? EMPTY_OPTIONS;
+	const [mockSelectedOptionId, setMockSelectedOptionId] = useState(null);
+	const [wasUsingMockOptions, setWasUsingMockOptions] = useState(usingMockOptions);
+	if (usingMockOptions !== wasUsingMockOptions) {
+		setWasUsingMockOptions(usingMockOptions);
+		setMockSelectedOptionId(null);
+	}
+	const selectedOptionId = usingMockOptions ? mockSelectedOptionId : $data?.selectedOptionId ?? null;
+	const [selectionError, setSelectionError] = useState(null);
+	const selectionToken = useRef(0);
+	function selectOption(optionId, callbacks) {
+		if (usingMockOptions) {
+			setMockSelectedOptionId(optionId);
+			callbacks?.onSettled?.(true);
+			return;
+		}
+		setSelectionError(null);
+		const dispatch = $actions?.shipping?.selectOption;
+		if (!dispatch) {
+			callbacks?.onSettled?.(false);
+			return;
+		}
+		const token = ++selectionToken.current;
+		dispatch(optionId).then((userErrors) => {
+			if (selectionToken.current !== token) return;
+			const [firstError] = userErrors;
+			if (firstError) {
+				setSelectionError(firstError.message);
+				callbacks?.onSettled?.(false);
+			} else callbacks?.onSettled?.(true);
+		});
+	}
+	return {
+		options,
+		selectedOptionId,
+		usingMockOptions,
+		selectionError,
+		selectOption,
+		contextValue: useMemo(() => ({
+			postalCode: "",
+			setPostalCode: () => {},
+			status: "idle",
+			shippingOptions: options,
+			userErrors: [],
+			submit: () => {}
+		}), [options])
+	};
+}
+//#endregion
+export { useDeliveryOptionSelection };
+
+//# sourceMappingURL=use-delivery-option-selection.js.map

package/dist/matter/delivery-options/use-delivery-option-selection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-delivery-option-selection.js","names":[],"sources":["../../../src/matter/delivery-options/use-delivery-option-selection.ts"],"sourcesContent":["'use client';\n\nimport { useMemo, useRef, useState } from 'react';\nimport type { ComponentActions } from '../../sdk/actions/types.js';\nimport { useDataOverride } from '../../sdk/data/data-override-context.js';\nimport type { ShippingOption, ShippingSimulatorContextValue } from '../shipping-simulator/shipping-simulator.js';\n\n// ---------------------------------------------------------------------------\n// Raw data type (shape of the reactive fragment result). `$data` is the unwrapped\n// `Shipping` entity the reactive runtime forwards (Decision 7 / INV-7), not `{ shipping: … }`.\n// Shared by DeliveryOptionsRoot and its collapsed variants (Accordion/Dialog/Drawer), all of\n// which read the same `shipping { options … selectedOptionId }` selection.\n// ---------------------------------------------------------------------------\n\nexport type RawDeliveryOptionsData = {\n  options: ShippingOption[];\n  selectedOptionId: string | null;\n};\n\nconst EMPTY_OPTIONS: ShippingOption[] = [];\n\n/**\n * Joins the structural classes a collapsed variant always applies (positioning, sizing, animation)\n * with the page-supplied visual override, dropping empty slots. Keeps the visual layer out of the\n * component (Free Particle Model) while guaranteeing the overlay still positions itself.\n */\nexport function cx(...classes: Array<string | undefined>): string {\n  return classes.filter(Boolean).join(' ');\n}\n\nexport type DeliveryOptionSelection = {\n  /** Real options when the fetch has any, else the `mockOptions` fallback, else empty. */\n  options: ShippingOption[];\n  /** Group value: the persisted `selectedOptionId` for real data, local state under mock. */\n  selectedOptionId: string | null;\n  /** True while the mock fallback is showing (no real options + `mockOptions` present). */\n  usingMockOptions: boolean;\n  /** Message of the first `userError` from the latest real selection, or `null`. */\n  selectionError: string | null;\n  /**\n   * Selects an option. Under mock data the choice is local-only and never dispatches the action.\n   * Under real data it dispatches `shipping.selectOption`, request-sequenced so only the latest\n   * click wins the error state. `onSettled(ok)` fires once the selection resolves — `ok` is `false`\n   * when the mutation surfaced a `userError` (or no action was injected) — letting collapsed\n   * variants close only on success.\n   */\n  selectOption: (optionId: string, callbacks?: { onSettled?: (ok: boolean) => void }) => void;\n  /** The FSPG-832 simulator context value (inert simulation fields) providers must supply. */\n  contextValue: ShippingSimulatorContextValue;\n};\n\n/**\n * Shared selection engine behind `DeliveryOptionsRoot` and its collapsed variants\n * (`DeliveryOptionsAccordion` / `Dialog` / `Drawer`). It owns the four behaviours the spec\n * requires identically across every surface, so they cannot drift apart:\n *\n * - real-vs-mock option resolution — real options of any length always win (INV-8);\n * - the local mock selection, reset whenever the real↔mock boundary flips so a stale mock\n *   choice from before a real-options interlude never reappears (Decision 7);\n * - the reactive `selectedOptionId` binding (Decision 5 — no local state for real data);\n * - the request-sequenced `selectOption` dispatch that resolves `userErrors` for inline display\n *   (US-4), guarding against an earlier click's result overwriting a later one.\n *\n * Callers render `selectionError` (as `role=\"alert\"`) and wire `contextValue` themselves; the\n * collapsed variants additionally use `onSettled` to close their panel only on success.\n */\nexport function useDeliveryOptionSelection({\n  $data: $dataProp,\n  $actions,\n  mockOptions,\n}: {\n  $data?: RawDeliveryOptionsData | null;\n  $actions?: ComponentActions;\n  mockOptions?: ShippingOption[];\n}): DeliveryOptionSelection {\n  const $data = useDataOverride($dataProp);\n  const realOptions = $data?.options;\n  const usingMockOptions = !realOptions?.length && !!mockOptions?.length;\n  const options = realOptions?.length ? realOptions : (mockOptions ?? EMPTY_OPTIONS);\n\n  const [mockSelectedOptionId, setMockSelectedOptionId] = useState<string | null>(null);\n  const [wasUsingMockOptions, setWasUsingMockOptions] = useState(usingMockOptions);\n  if (usingMockOptions !== wasUsingMockOptions) {\n    setWasUsingMockOptions(usingMockOptions);\n    setMockSelectedOptionId(null);\n  }\n  const selectedOptionId = usingMockOptions ? mockSelectedOptionId : ($data?.selectedOptionId ?? null);\n\n  const [selectionError, setSelectionError] = useState<string | null>(null);\n  const selectionToken = useRef(0);\n\n  function selectOption(optionId: string, callbacks?: { onSettled?: (ok: boolean) => void }) {\n    if (usingMockOptions) {\n      setMockSelectedOptionId(optionId);\n      callbacks?.onSettled?.(true);\n      return;\n    }\n    setSelectionError(null);\n    const dispatch = $actions?.shipping?.selectOption;\n    if (!dispatch) {\n      callbacks?.onSettled?.(false);\n      return;\n    }\n    const token = ++selectionToken.current;\n    dispatch(optionId).then((userErrors) => {\n      if (selectionToken.current !== token) return;\n      const [firstError] = userErrors;\n      if (firstError) {\n        setSelectionError(firstError.message);\n        callbacks?.onSettled?.(false);\n      } else {\n        callbacks?.onSettled?.(true);\n      }\n    });\n  }\n\n  const contextValue = useMemo<ShippingSimulatorContextValue>(\n    () => ({\n      postalCode: '',\n      setPostalCode: () => {},\n      status: 'idle',\n      shippingOptions: options,\n      userErrors: [],\n      submit: () => {},\n    }),\n    [options],\n  );\n\n  return { options, selectedOptionId, usingMockOptions, selectionError, selectOption, contextValue };\n}\n"],"mappings":";;;;AAmBA,MAAM,gBAAkC,CAAC;;;;;;;;;;;;;;;;AA+CzC,SAAgB,2BAA2B,EACzC,OAAO,WACP,UACA,eAK0B;CAC1B,MAAM,QAAQ,gBAAgB,SAAS;CACvC,MAAM,cAAc,OAAO;CAC3B,MAAM,mBAAmB,CAAC,aAAa,UAAU,CAAC,CAAC,aAAa;CAChE,MAAM,UAAU,aAAa,SAAS,cAAe,eAAe;CAEpE,MAAM,CAAC,sBAAsB,2BAA2B,SAAwB,IAAI;CACpF,MAAM,CAAC,qBAAqB,0BAA0B,SAAS,gBAAgB;CAC/E,IAAI,qBAAqB,qBAAqB;EAC5C,uBAAuB,gBAAgB;EACvC,wBAAwB,IAAI;CAC9B;CACA,MAAM,mBAAmB,mBAAmB,uBAAwB,OAAO,oBAAoB;CAE/F,MAAM,CAAC,gBAAgB,qBAAqB,SAAwB,IAAI;CACxE,MAAM,iBAAiB,OAAO,CAAC;CAE/B,SAAS,aAAa,UAAkB,WAAmD;EACzF,IAAI,kBAAkB;GACpB,wBAAwB,QAAQ;GAChC,WAAW,YAAY,IAAI;GAC3B;EACF;EACA,kBAAkB,IAAI;EACtB,MAAM,WAAW,UAAU,UAAU;EACrC,IAAI,CAAC,UAAU;GACb,WAAW,YAAY,KAAK;GAC5B;EACF;EACA,MAAM,QAAQ,EAAE,eAAe;EAC/B,SAAS,QAAQ,CAAC,CAAC,MAAM,eAAe;GACtC,IAAI,eAAe,YAAY,OAAO;GACtC,MAAM,CAAC,cAAc;GACrB,IAAI,YAAY;IACd,kBAAkB,WAAW,OAAO;IACpC,WAAW,YAAY,KAAK;GAC9B,OACE,WAAW,YAAY,IAAI;EAE/B,CAAC;CACH;CAcA,OAAO;EAAE;EAAS;EAAkB;EAAkB;EAAgB;EAAc,cAZ/D,eACZ;GACL,YAAY;GACZ,qBAAqB,CAAC;GACtB,QAAQ;GACR,iBAAiB;GACjB,YAAY,CAAC;GACb,cAAc,CAAC;EACjB,IACA,CAAC,OAAO,CAGqF;CAAE;AACnG"}

package/dist/matter/email-identification/email-identification.d.ts

@@ -0,0 +1,37 @@
+import { ComponentDefinition } from "../../core/dist/define-component.js";
+import "../../core/dist/index.js";
+import { ComponentActions } from "../../sdk/actions/types.js";
+import { ComponentPropsWithRef } from "react";
+//#region src/matter/email-identification/email-identification.d.ts
+/** ClientProfile slice forwarded by the reactive runtime — only `email` is consumed for pre-fill. */
+export type EmailIdentificationSlice = {
+  email?: string | null;
+};
+export type EmailIdentificationControlProps = Omit<ComponentPropsWithRef<'div'>, 'onChange'> & {
+  /** Accessible label passed to the EmailField. */
+  label?: string;
+  /** Input placeholder passed to the EmailField. */
+  placeholder?: string;
+  /** Inline error text for an invalid email format (port of `checkout/form-messages.invalid-email`). */
+  invalidEmailMessage?: string;
+  /** ClientProfile slice forwarded by the reactive runtime; `null` until the entity resolves. */
+  $data?: EmailIdentificationSlice | null;
+  /** Compiler-injected action surface; carries `identity.clientProfileUpdate`. */
+  $actions?: ComponentActions;
+};
+export declare const EmailIdentificationControlDefinition: ComponentDefinition<EmailIdentificationControlProps>;
+/**
+ * Matter that binds the presentational `EmailField` to the User Identity foundation. It reads
+ * `clientProfile.email` (colocated reactive fragment) for the pre-fill, reads the identification
+ * tri-state and `canEditData` from `useSession()` (which also enforces the `SessionRoot` ancestor),
+ * and on a **valid, changed** email persists only the `email` field through
+ * `$actions.identity.clientProfileUpdate` (async / pessimistic, Decision 1). While the write is in
+ * flight the field is disabled and `data-fs-email-identification-pending` is present so a
+ * checkout-CTA guard can block. When the session reports `canEditData: false` (identified but
+ * unauthenticated claimed profile — VTEX refuses the write server-side) the field renders disabled
+ * with `data-fs-email-identification-readonly`. Server `userErrors` are surfaced inline; the
+ * session state is never computed locally.
+ */
+export declare function EmailIdentificationControl({ label, placeholder, invalidEmailMessage, $data: $dataProp, $actions, className, ...props }: EmailIdentificationControlProps): import("react/jsx-runtime").JSX.Element;
+//#endregion
+//# sourceMappingURL=email-identification.d.ts.map

package/dist/matter/email-identification/email-identification.js

@@ -0,0 +1,111 @@
+"use client";
+import { defineComponent } from "../../core/dist/define-component.js";
+import "../../core/dist/index.js";
+import { EmailField, isValidEmail } from "../../particles/email-field/email-field.js";
+import { useDataOverride } from "../../sdk/data/data-override-context.js";
+import { useSession } from "../session/session.js";
+import { useEffect, useState } from "react";
+import { jsx } from "react/jsx-runtime";
+const EmailIdentificationControlDefinition = defineComponent({
+	name: "EmailIdentificationControl",
+	importPath: "@vtex/faststore/components",
+	component: EmailIdentificationControl,
+	fragment: `
+  fragment EmailIdentificationData on Query {
+    clientProfile {
+      __typename
+      id
+      email
+    }
+  }
+`,
+	fetchStrategy: "reactive",
+	actions: { identity: ["clientProfileUpdate"] },
+	requiresContext: "session",
+	editor: {
+		label: "Email Identification",
+		category: "identity"
+	},
+	schema: {
+		label: {
+			type: "string",
+			label: "Label"
+		},
+		placeholder: {
+			type: "string",
+			label: "Placeholder"
+		},
+		invalidEmailMessage: {
+			type: "string",
+			label: "Invalid email message"
+		}
+	},
+	guideline: "Checkout-bound email field: pre-fills from clientProfile.email and persists a valid changed email via $actions.identity.clientProfileUpdate (anonymous→identified). Must be inside SessionRoot. See email-identification.md."
+});
+/**
+* Matter that binds the presentational `EmailField` to the User Identity foundation. It reads
+* `clientProfile.email` (colocated reactive fragment) for the pre-fill, reads the identification
+* tri-state and `canEditData` from `useSession()` (which also enforces the `SessionRoot` ancestor),
+* and on a **valid, changed** email persists only the `email` field through
+* `$actions.identity.clientProfileUpdate` (async / pessimistic, Decision 1). While the write is in
+* flight the field is disabled and `data-fs-email-identification-pending` is present so a
+* checkout-CTA guard can block. When the session reports `canEditData: false` (identified but
+* unauthenticated claimed profile — VTEX refuses the write server-side) the field renders disabled
+* with `data-fs-email-identification-readonly`. Server `userErrors` are surfaced inline; the
+* session state is never computed locally.
+*/
+function EmailIdentificationControl({ label, placeholder, invalidEmailMessage, $data: $dataProp, $actions, className, ...props }) {
+	const $data = useDataOverride($dataProp);
+	const { canEditData } = useSession();
+	const readOnly = !canEditData;
+	const savedEmail = $data?.email ?? "";
+	const [value, setValue] = useState(savedEmail);
+	const [pending, setPending] = useState(false);
+	const [serverError, setServerError] = useState(null);
+	useEffect(() => {
+		setValue(savedEmail);
+	}, [savedEmail]);
+	function handleValueChange(next) {
+		setValue(next);
+		if (serverError) setServerError(null);
+	}
+	async function handleBlur() {
+		const trimmed = value.trim();
+		if (trimmed === "" && savedEmail !== "") {
+			setValue(savedEmail);
+			return;
+		}
+		if (!isValidEmail(trimmed)) return;
+		if (trimmed === savedEmail) return;
+		setPending(true);
+		setServerError(null);
+		try {
+			const errors = await $actions?.identity?.clientProfileUpdate?.({ email: trimmed }) ?? [];
+			if (errors.length > 0) setServerError(errors[0]?.message ?? null);
+		} finally {
+			setPending(false);
+		}
+	}
+	return /* @__PURE__ */ jsx("div", {
+		...props,
+		className,
+		"data-fs-email-identification-control": "",
+		...pending ? { "data-fs-email-identification-pending": "" } : {},
+		...readOnly ? { "data-fs-email-identification-readonly": "" } : {},
+		children: /* @__PURE__ */ jsx(EmailField, {
+			label,
+			placeholder,
+			value,
+			disabled: pending || readOnly,
+			invalid: serverError != null,
+			errorMessage: serverError ?? invalidEmailMessage,
+			onValueChange: handleValueChange,
+			onBlur: handleBlur,
+			required: true
+		})
+	});
+}
+//#endregion
+export { EmailIdentificationControl, EmailIdentificationControlDefinition };
+
+//# sourceMappingURL=email-identification.js.map

package/dist/matter/email-identification/email-identification.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"email-identification.js","names":[],"sources":["../../../src/matter/email-identification/email-identification.tsx"],"sourcesContent":["'use client';\n\nimport { defineComponent } from '@vtex/fs-core';\nimport type { ComponentPropsWithRef } from 'react';\nimport { useEffect, useState } from 'react';\nimport { EmailField, isValidEmail } from '../../particles/email-field/email-field.js';\nimport type { ComponentActions } from '../../sdk/actions/types.js';\nimport { useDataOverride } from '../../sdk/data/data-override-context.js';\nimport { useSession } from '../session/session.js';\n\n// ---------------------------------------------------------------------------\n// GraphQL Fragment (colocated, ADR-0011) — reads only clientProfile.email.\n// Authored as a raw string (not the codegen graphql() factory), mirroring the ShippingSimulator\n// matter: the compiler derives the entity fragment on `clientProfile` and subscribes reactively.\n// ---------------------------------------------------------------------------\n\nconst fragment = /* GraphQL */ `\n  fragment EmailIdentificationData on Query {\n    clientProfile {\n      __typename\n      id\n      email\n    }\n  }\n`;\n\n// ---------------------------------------------------------------------------\n// Types\n// ---------------------------------------------------------------------------\n\n/** ClientProfile slice forwarded by the reactive runtime — only `email` is consumed for pre-fill. */\nexport type EmailIdentificationSlice = {\n  email?: string | null;\n};\n\nexport type EmailIdentificationControlProps = Omit<ComponentPropsWithRef<'div'>, 'onChange'> & {\n  /** Accessible label passed to the EmailField. */\n  label?: string;\n  /** Input placeholder passed to the EmailField. */\n  placeholder?: string;\n  /** Inline error text for an invalid email format (port of `checkout/form-messages.invalid-email`). */\n  invalidEmailMessage?: string;\n  /** ClientProfile slice forwarded by the reactive runtime; `null` until the entity resolves. */\n  $data?: EmailIdentificationSlice | null;\n  /** Compiler-injected action surface; carries `identity.clientProfileUpdate`. */\n  $actions?: ComponentActions;\n};\n\n// ---------------------------------------------------------------------------\n// Definition\n// ---------------------------------------------------------------------------\n\nexport const EmailIdentificationControlDefinition = defineComponent<EmailIdentificationControlProps>({\n  name: 'EmailIdentificationControl',\n  importPath: '@vtex/faststore/components',\n  component: EmailIdentificationControl,\n  fragment,\n  fetchStrategy: 'reactive',\n  actions: { identity: ['clientProfileUpdate'] },\n  requiresContext: 'session',\n  editor: { label: 'Email Identification', category: 'identity' },\n  schema: {\n    label: { type: 'string', label: 'Label' },\n    placeholder: { type: 'string', label: 'Placeholder' },\n    invalidEmailMessage: { type: 'string', label: 'Invalid email message' },\n  },\n  guideline:\n    'Checkout-bound email field: pre-fills from clientProfile.email and persists a valid changed email via $actions.identity.clientProfileUpdate (anonymous→identified). Must be inside SessionRoot. See email-identification.md.',\n});\n\n// ---------------------------------------------------------------------------\n// Implementation\n// ---------------------------------------------------------------------------\n\n/**\n * Matter that binds the presentational `EmailField` to the User Identity foundation. It reads\n * `clientProfile.email` (colocated reactive fragment) for the pre-fill, reads the identification\n * tri-state and `canEditData` from `useSession()` (which also enforces the `SessionRoot` ancestor),\n * and on a **valid, changed** email persists only the `email` field through\n * `$actions.identity.clientProfileUpdate` (async / pessimistic, Decision 1). While the write is in\n * flight the field is disabled and `data-fs-email-identification-pending` is present so a\n * checkout-CTA guard can block. When the session reports `canEditData: false` (identified but\n * unauthenticated claimed profile — VTEX refuses the write server-side) the field renders disabled\n * with `data-fs-email-identification-readonly`. Server `userErrors` are surfaced inline; the\n * session state is never computed locally.\n */\nexport function EmailIdentificationControl({\n  label,\n  placeholder,\n  invalidEmailMessage,\n  $data: $dataProp,\n  $actions,\n  className,\n  ...props\n}: EmailIdentificationControlProps) {\n  const $data = useDataOverride($dataProp);\n  // Also enforces the SessionRoot ancestor: useSession() throws when rendered outside one.\n  const { canEditData } = useSession();\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.\n  const readOnly = !canEditData;\n\n  const savedEmail = $data?.email ?? '';\n  const [value, setValue] = useState(savedEmail);\n  const [pending, setPending] = useState(false);\n  const [serverError, setServerError] = useState<string | null>(null);\n\n  // Sync the pre-fill when the saved profile email resolves or changes (identified/logged-in shopper).\n  // Does not fire while the shopper is typing, since `savedEmail` only changes when the profile does.\n  useEffect(() => {\n    setValue(savedEmail);\n  }, [savedEmail]);\n\n  function handleValueChange(next: string) {\n    setValue(next);\n    if (serverError) setServerError(null);\n  }\n\n  async function handleBlur() {\n    const trimmed = value.trim();\n    // Cleared field → re-fill with the saved email; clearing must not visually \"un-identify\"\n    // (changing email = switching user is a deliberate act, done by typing a new one).\n    if (trimmed === '' && savedEmail !== '') {\n      setValue(savedEmail);\n      return;\n    }\n    // Invalid format → EmailField shows its own inline error; no persist, no step advance.\n    if (!isValidEmail(trimmed)) return;\n    // Unchanged → nothing to persist.\n    if (trimmed === savedEmail) return;\n\n    setPending(true);\n    setServerError(null);\n    try {\n      const errors = (await $actions?.identity?.clientProfileUpdate?.({ email: trimmed })) ?? [];\n      if (errors.length > 0) setServerError(errors[0]?.message ?? null);\n    } finally {\n      setPending(false);\n    }\n  }\n\n  return (\n    <div\n      {...props}\n      className={className}\n      data-fs-email-identification-control=\"\"\n      {...(pending ? { 'data-fs-email-identification-pending': '' } : {})}\n      {...(readOnly ? { 'data-fs-email-identification-readonly': '' } : {})}\n    >\n      <EmailField\n        label={label}\n        placeholder={placeholder}\n        value={value}\n        disabled={pending || readOnly}\n        invalid={serverError != null}\n        errorMessage={serverError ?? invalidEmailMessage}\n        onValueChange={handleValueChange}\n        onBlur={handleBlur}\n        required\n      />\n    </div>\n  );\n}\n"],"mappings":";;;;;;;;AAoDA,MAAa,uCAAuC,gBAAiD;CACnG,MAAM;CACN,YAAY;CACZ,WAAW;CACX;;;;;;;;;CACA,eAAe;CACf,SAAS,EAAE,UAAU,CAAC,qBAAqB,EAAE;CAC7C,iBAAiB;CACjB,QAAQ;EAAE,OAAO;EAAwB,UAAU;CAAW;CAC9D,QAAQ;EACN,OAAO;GAAE,MAAM;GAAU,OAAO;EAAQ;EACxC,aAAa;GAAE,MAAM;GAAU,OAAO;EAAc;EACpD,qBAAqB;GAAE,MAAM;GAAU,OAAO;EAAwB;CACxE;CACA,WACE;AACJ,CAAC;;;;;;;;;;;;;AAkBD,SAAgB,2BAA2B,EACzC,OACA,aACA,qBACA,OAAO,WACP,UACA,WACA,GAAG,SAC+B;CAClC,MAAM,QAAQ,gBAAgB,SAAS;CAEvC,MAAM,EAAE,gBAAgB,WAAW;CAGnC,MAAM,WAAW,CAAC;CAElB,MAAM,aAAa,OAAO,SAAS;CACnC,MAAM,CAAC,OAAO,YAAY,SAAS,UAAU;CAC7C,MAAM,CAAC,SAAS,cAAc,SAAS,KAAK;CAC5C,MAAM,CAAC,aAAa,kBAAkB,SAAwB,IAAI;CAIlE,gBAAgB;EACd,SAAS,UAAU;CACrB,GAAG,CAAC,UAAU,CAAC;CAEf,SAAS,kBAAkB,MAAc;EACvC,SAAS,IAAI;EACb,IAAI,aAAa,eAAe,IAAI;CACtC;CAEA,eAAe,aAAa;EAC1B,MAAM,UAAU,MAAM,KAAK;EAG3B,IAAI,YAAY,MAAM,eAAe,IAAI;GACvC,SAAS,UAAU;GACnB;EACF;EAEA,IAAI,CAAC,aAAa,OAAO,GAAG;EAE5B,IAAI,YAAY,YAAY;EAE5B,WAAW,IAAI;EACf,eAAe,IAAI;EACnB,IAAI;GACF,MAAM,SAAU,MAAM,UAAU,UAAU,sBAAsB,EAAE,OAAO,QAAQ,CAAC,KAAM,CAAC;GACzF,IAAI,OAAO,SAAS,GAAG,eAAe,OAAO,EAAE,EAAE,WAAW,IAAI;EAClE,UAAU;GACR,WAAW,KAAK;EAClB;CACF;CAEA,OACE,oBAAC,OAAD;EACE,GAAI;EACO;EACX,wCAAqC;EACrC,GAAK,UAAU,EAAE,wCAAwC,GAAG,IAAI,CAAC;EACjE,GAAK,WAAW,EAAE,yCAAyC,GAAG,IAAI,CAAC;EAEnE,UAAA,oBAAC,YAAD;GACS;GACM;GACN;GACP,UAAU,WAAW;GACrB,SAAS,eAAe;GACxB,cAAc,eAAe;GAC7B,eAAe;GACf,QAAQ;GACR,UAAA;EACD,CAAA;CACE,CAAA;AAET"}

package/dist/matter/free-shipping-progress/free-shipping-progress.d.ts

@@ -0,0 +1,44 @@
+import { ComponentDefinition } from "../../core/dist/define-component.js";
+import "../../core/dist/index.js";
+import { ComponentPropsWithRef } from "react";
+//#region src/matter/free-shipping-progress/free-shipping-progress.d.ts
+type MoneyValue = {
+  amount: number | string;
+  currencyCode: string;
+};
+type FreeShippingProgressData = {
+  cart?: {
+    id: string;
+    total?: MoneyValue | null;
+    freeShippingProgress?: {
+      threshold: MoneyValue | null;
+      remaining: MoneyValue;
+      qualified: boolean;
+    } | null;
+  } | null;
+};
+export type FreeShippingProgressRootProps = ComponentPropsWithRef<'div'> & {
+  threshold?: number;
+  remaining?: number;
+  qualified?: boolean;
+  cartTotal?: number;
+  $data?: FreeShippingProgressData['cart'] | null;
+};
+export type FreeShippingProgressBarProps = ComponentPropsWithRef<'div'>;
+export type FreeShippingProgressMessageProps = ComponentPropsWithRef<'div'> & {
+  label?: string;
+  qualifiedLabel?: string;
+};
+export declare const FreeShippingProgressRootDefinition: ComponentDefinition<FreeShippingProgressRootProps>;
+export declare const FreeShippingProgressBarDefinition: ComponentDefinition<import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>>;
+export declare const FreeShippingProgressMessageDefinition: ComponentDefinition<FreeShippingProgressMessageProps>;
+export declare function FreeShippingProgressRoot({ threshold, remaining, qualified, cartTotal, $data: $dataProp, className, children, ...props }: FreeShippingProgressRootProps): import("react/jsx-runtime").JSX.Element | null;
+export declare function FreeShippingProgressBar({ className, ...props }: FreeShippingProgressBarProps): import("react/jsx-runtime").JSX.Element;
+export declare function FreeShippingProgressMessage({ label, qualifiedLabel, className, children, ...props }: FreeShippingProgressMessageProps): import("react/jsx-runtime").JSX.Element;
+export declare const FreeShippingProgress: {
+  Root: typeof FreeShippingProgressRoot;
+  Bar: typeof FreeShippingProgressBar;
+  Message: typeof FreeShippingProgressMessage;
+};
+//#endregion
+//# sourceMappingURL=free-shipping-progress.d.ts.map