@vtex/faststore 0.0.4 → 0.0.6

package/dist/matter/installments/installments.js

@@ -0,0 +1,176 @@
+"use client";
+import { defineComponent } from "../../core/dist/define-component.js";
+import "../../core/dist/index.js";
+import { useStorefrontContext } from "../../sdk/context/storefront-context.js";
+import { useActionsOverride } from "../../sdk/actions/actions-override-context.js";
+import { resolveAuthoredCopy } from "../../utils/resolve-authored-copy.js";
+import { Fieldset } from "../../particles/fieldset/fieldset.js";
+import { RadioGroup, RadioIndicator, RadioRoot } from "../../particles/radio/radio.js";
+import { substituteTemplate } from "../../utils/substitute-template.js";
+import { findInstallmentOption, resolveInstallmentTiers, useInstallmentsSelection } from "./use-installments-selection.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+//#region src/matter/installments/installments.tsx
+/**
+* `Installments` matter (specs/installments.md, T9 of the Credit Card epic;
+* docs/features/credit-card/rfc.md § D4). Lets a shopper pick an installment plan for both a
+* freshly entered card and a selected saved card, rendered as a `RadioGroup` — one row per tier the
+* matched option carries (the API guarantees a 1x tier is present in every option, so one is always
+* shown and selectable).
+*
+* Owns its own `fragment` on `Query.payment` selecting `installmentOptions` and `selectedInstallment`
+* — the two fields `PaymentSectionRoot`'s thin root fragment deliberately excludes (ADR-0011,
+* "decompose by data ownership").
+*
+* Matching, tier resolution, `selectedCount`, state derivation, the BIN-confirmation pending gate, and
+* the request-token-guarded `$actions.payment.setInstallments` dispatch all live in
+* `useInstallmentsSelection()` (T90, specs/render-installments-as-a-radio-group.md § Decision 3) — the
+* shared engine also consumed by `InstallmentsSelect`, so the two surfaces cannot drift apart (mirrors
+* `useDeliveryOptionSelection`). This component is now a thin renderer over that hook: it owns only
+* its own markup (a `RadioGroup` of rows) and its own `role="alert"`, exactly as
+* `useDeliveryOptionSelection`'s callers do. `findInstallmentOption` and `resolveInstallmentTiers` now
+* live in `use-installments-selection.ts` — the hook was their only caller, so this module re-exports
+* both unchanged (T90 finding 4: the previous arrangement, this file importing the hook while the hook
+* imported these two back out of this file, was a genuine two-way ESM cycle) — so their public API and
+* their existing tests are untouched. Render output is byte-identical to before T90 (INV-1); see the
+* hook's own doc comment for the full matching/gating rationale, including the PR #507 findings this
+* behavior must not regress.
+*/
+const fragment = `
+  fragment InstallmentsData on Query {
+    payment {
+      __typename
+      id
+      installmentOptions {
+        __typename
+        methodId
+        bin
+        installments {
+          __typename
+          count
+          value {
+            amount
+            currencyCode
+          }
+          interestRate
+        }
+      }
+      selectedInstallment {
+        __typename
+        count
+      }
+    }
+  }
+`;
+function formatInstallmentValue(amount, locale, currency) {
+	return new Intl.NumberFormat(locale, {
+		style: "currency",
+		currency
+	}).format(amount);
+}
+/**
+* The order form carries `interestRate` in hundredths of a percent (T174, FR-5): `100` is 1%. It is
+* scaled here and nowhere else — the API and the payment gateway body both keep the upstream value.
+*/
+function formatInterestRate(rate, locale) {
+	return new Intl.NumberFormat(locale, { maximumFractionDigits: 2 }).format(rate / 100);
+}
+/**
+* Formats one tier's row/option text. Exported (T90,
+* specs/render-installments-as-a-radio-group.md § FR-5) so `InstallmentsSelect` renders each option
+* with the exact same function `Installments` uses, driven by the same four authorable copy props —
+* the two surfaces cannot word a tier differently.
+*/
+function installmentLabel({ tier, locale, installmentTemplate, interestFreeLabel, interestTemplate }) {
+	const formattedValue = formatInstallmentValue(tier.value.amount, locale, tier.value.currencyCode);
+	const base = substituteTemplate(installmentTemplate, {
+		count: String(tier.count),
+		value: formattedValue
+	});
+	const interestSuffix = tier.interestRate === 0 ? interestFreeLabel : substituteTemplate(interestTemplate, { rate: formatInterestRate(tier.interestRate, locale) });
+	return interestSuffix ? `${base} ${interestSuffix}` : base;
+}
+const InstallmentsDefinition = defineComponent({
+	name: "Installments",
+	importPath: "@vtex/faststore/components",
+	component: Installments,
+	fragment,
+	fetchStrategy: "reactive",
+	requiresContext: "payment",
+	actions: { payment: ["setInstallments"] },
+	editor: {
+		label: "Installments",
+		category: "commerce"
+	},
+	schema: {
+		installmentTemplate: {
+			type: "string",
+			default: "{count}x of {value}",
+			label: "Installment template"
+		},
+		interestFreeLabel: {
+			type: "string",
+			default: "interest-free",
+			label: "Interest-free label"
+		},
+		interestTemplate: {
+			type: "string",
+			default: "{rate}% interest",
+			label: "Interest template"
+		},
+		legend: {
+			type: "string",
+			default: "Installments",
+			label: "Legend"
+		}
+	},
+	guideline: "Installment selector for checkout: shows count, per-installment value, and interest for the card currently being entered (matched by BIN) or the saved card currently selected (matched by the persisted BIN, falling back to method), rendering exactly the tiers the matched option returns (the API guarantees a 1x tier is present in every option, so one is always shown and selectable — see specs/installments.md). Must be inside a PaymentSectionRoot or PaymentSectionController — place it as a sibling of CardEntry and SavedCards, never nested inside either, so one instance serves both entry paths. Picking a row dispatches $actions.payment.setInstallments and the order total updates elsewhere from the normalized cache with no wiring here. Renders its own rows from real data — no children."
+});
+function Installments({ installmentTemplate = "{count}x of {value}", interestFreeLabel = "interest-free", interestTemplate = "{rate}% interest", legend, $data, $actions: $actionsProp, className, ...props }) {
+	const $actions = useActionsOverride($actionsProp);
+	const { locale } = useStorefrontContext();
+	const { tiers, selectedCount, state, isPending, selectionError, selectInstallment, placing, cardPaymentCollapsed } = useInstallmentsSelection({
+		$data,
+		$actions
+	});
+	if (cardPaymentCollapsed) return null;
+	return /* @__PURE__ */ jsxs("div", {
+		...props,
+		className,
+		inert: placing,
+		"aria-disabled": placing || void 0,
+		"data-fs-installments": "",
+		"data-fs-installments-state": state,
+		"aria-busy": isPending || void 0,
+		...placing ? { "data-fs-installments-placing": "" } : {},
+		children: [selectionError ? /* @__PURE__ */ jsx("div", {
+			role: "alert",
+			"data-fs-installments-error": "",
+			children: selectionError
+		}) : null, tiers.length > 0 ? /* @__PURE__ */ jsxs(Fieldset.Root, {
+			"data-fs-installments-fieldset": "",
+			children: [/* @__PURE__ */ jsx(Fieldset.Legend, { children: resolveAuthoredCopy(legend, "Installments") }), /* @__PURE__ */ jsx(RadioGroup, {
+				value: String(selectedCount),
+				onValueChange: (value) => selectInstallment(Number(value)),
+				disabled: isPending,
+				children: tiers.map((tier) => /* @__PURE__ */ jsxs(RadioRoot, {
+					value: String(tier.count),
+					disabled: isPending,
+					children: [/* @__PURE__ */ jsx(RadioIndicator, { "data-fs-installments-option-indicator": "" }), /* @__PURE__ */ jsx("span", {
+						"data-fs-installments-option-label": "",
+						children: installmentLabel({
+							tier,
+							locale,
+							installmentTemplate,
+							interestFreeLabel,
+							interestTemplate
+						})
+					})]
+				}, tier.count))
+			})]
+		}) : null]
+	});
+}
+//#endregion
+export { Installments, InstallmentsDefinition, findInstallmentOption, installmentLabel, resolveInstallmentTiers };
+
+//# sourceMappingURL=installments.js.map

package/dist/matter/installments/installments.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"installments.js","names":[],"sources":["../../../src/matter/installments/installments.tsx"],"sourcesContent":["'use client';\n\nimport { defineComponent } from '@vtex/fs-core';\nimport type { ComponentPropsWithRef } from 'react';\nimport { Fieldset } from '../../particles/fieldset/fieldset.js';\nimport { RadioGroup, RadioIndicator, RadioRoot } from '../../particles/radio/radio.js';\nimport { useActionsOverride } from '../../sdk/actions/actions-override-context.js';\nimport type { ComponentActions } from '../../sdk/actions/types.js';\nimport { useStorefrontContext } from '../../sdk/context/storefront-context.js';\nimport { resolveAuthoredCopy } from '../../utils/resolve-authored-copy.js';\nimport { substituteTemplate } from '../../utils/substitute-template.js';\nimport { useInstallmentsSelection } from './use-installments-selection.js';\n\n/**\n * `Installments` matter (specs/installments.md, T9 of the Credit Card epic;\n * docs/features/credit-card/rfc.md § D4). Lets a shopper pick an installment plan for both a\n * freshly entered card and a selected saved card, rendered as a `RadioGroup` — one row per tier the\n * matched option carries (the API guarantees a 1x tier is present in every option, so one is always\n * shown and selectable).\n *\n * Owns its own `fragment` on `Query.payment` selecting `installmentOptions` and `selectedInstallment`\n * — the two fields `PaymentSectionRoot`'s thin root fragment deliberately excludes (ADR-0011,\n * \"decompose by data ownership\").\n *\n * Matching, tier resolution, `selectedCount`, state derivation, the BIN-confirmation pending gate, and\n * the request-token-guarded `$actions.payment.setInstallments` dispatch all live in\n * `useInstallmentsSelection()` (T90, specs/render-installments-as-a-radio-group.md § Decision 3) — the\n * shared engine also consumed by `InstallmentsSelect`, so the two surfaces cannot drift apart (mirrors\n * `useDeliveryOptionSelection`). This component is now a thin renderer over that hook: it owns only\n * its own markup (a `RadioGroup` of rows) and its own `role=\"alert\"`, exactly as\n * `useDeliveryOptionSelection`'s callers do. `findInstallmentOption` and `resolveInstallmentTiers` now\n * live in `use-installments-selection.ts` — the hook was their only caller, so this module re-exports\n * both unchanged (T90 finding 4: the previous arrangement, this file importing the hook while the hook\n * imported these two back out of this file, was a genuine two-way ESM cycle) — so their public API and\n * their existing tests are untouched. Render output is byte-identical to before T90 (INV-1); see the\n * hook's own doc comment for the full matching/gating rationale, including the PR #507 findings this\n * behavior must not regress.\n */\n\n// ---------------------------------------------------------------------------\n// GraphQL Fragment — raw template literal, matching `PaymentSectionRoot` / `PaymentSummary`'s\n// convention. The codegen `documents` glob does not scan `src/matter/payment*` / `src/matter/installments*`;\n// `data-component-contract.test.ts` validates this fragment against the real schema.\n//\n// Selects `payment { id }` so Apollo's InMemoryCache normalizes `Payment` by id — required for\n// `paymentInstallmentSelect`'s returned `payment` to update the same cache entity this fragment\n// reads (installments.test.tsx's \"selects payment.id so a setInstallments echo re-normalizes the\n// entity this fragment reads\" asserts this against the parsed fragment AST). `total` is\n// deliberately not selected: this component never renders or computes against it\n// (specs/installments.md § Decision 3).\n// ---------------------------------------------------------------------------\n\nconst fragment = /* GraphQL */ `\n  fragment InstallmentsData on Query {\n    payment {\n      __typename\n      id\n      installmentOptions {\n        __typename\n        methodId\n        bin\n        installments {\n          __typename\n          count\n          value {\n            amount\n            currencyCode\n          }\n          interestRate\n        }\n      }\n      selectedInstallment {\n        __typename\n        count\n      }\n    }\n  }\n`;\n\n// ---------------------------------------------------------------------------\n// Types\n// ---------------------------------------------------------------------------\n\nexport type InstallmentMoney = Readonly<{ amount: number; currencyCode: string }>;\n\nexport type InstallmentTier = Readonly<{\n  count: number;\n  value: InstallmentMoney;\n  interestRate: number;\n}>;\n\nexport type InstallmentOption = Readonly<{\n  methodId: string;\n  bin: string | null;\n  installments: readonly InstallmentTier[];\n}>;\n\n/**\n * `$data` forwarded by the reactive runtime — the unwrapped value of the `payment` top-level field\n * on `InstallmentsData on Query` (arity-1 fragment, ADR-0015), not a `{ payment: … }` wrapper.\n * Every field optional, mirroring `PaymentSummaryData` / `PaymentSectionData`: `$data` arrives\n * partial while the entity resolves.\n */\nexport type InstallmentsData = {\n  installmentOptions?: readonly InstallmentOption[];\n  selectedInstallment?: { count: number } | null;\n} | null;\n\nexport type InstallmentsProps = Omit<ComponentPropsWithRef<'div'>, 'children'> & {\n  /** Placeholders `{count}` / `{value}`, matching `PaymentSummary`'s / `PricingInstallment`'s convention. */\n  installmentTemplate?: string;\n  /** Appended when a tier's `interestRate` is `0`. */\n  interestFreeLabel?: string;\n  /**\n   * Placeholder `{rate}`; appended instead of `interestFreeLabel` when a tier's `interestRate` is above `0`.\n   * `{rate}` is the order form's `interestRate` (hundredths of a percent) divided by 100: `100` renders `1`.\n   */\n  interestTemplate?: string;\n  /**\n   * The radio group's accessible name, rendered as a visible `Fieldset.Legend` (T38, Decision 1).\n   * Resolved through `resolveAuthoredCopy`: an authored empty or whitespace-only string falls back to\n   * the default rather than rendering a nameless group.\n   */\n  legend?: string;\n  /** `InstallmentsData` slice forwarded by the reactive runtime. */\n  $data?: InstallmentsData;\n  /** Compiler-injected action surface; carries `payment.setInstallments`. */\n  $actions?: ComponentActions;\n};\n\n// ---------------------------------------------------------------------------\n// Resolution — `findInstallmentOption` and `resolveInstallmentTiers` now live in\n// `use-installments-selection.ts` (T90 finding 4); re-exported here, unchanged, because\n// `installments.test.tsx` and the package barrel (`src/index.ts`) both import them from this path.\n// ---------------------------------------------------------------------------\n\nexport { findInstallmentOption, resolveInstallmentTiers } from './use-installments-selection.js';\n\nfunction formatInstallmentValue(amount: number, locale: string, currency: string): string {\n  return new Intl.NumberFormat(locale, { style: 'currency', currency }).format(amount);\n}\n\n/**\n * The order form carries `interestRate` in hundredths of a percent (T174, FR-5): `100` is 1%. It is\n * scaled here and nowhere else — the API and the payment gateway body both keep the upstream value.\n */\nfunction formatInterestRate(rate: number, locale: string): string {\n  return new Intl.NumberFormat(locale, { maximumFractionDigits: 2 }).format(rate / 100);\n}\n\n/**\n * Formats one tier's row/option text. Exported (T90,\n * specs/render-installments-as-a-radio-group.md § FR-5) so `InstallmentsSelect` renders each option\n * with the exact same function `Installments` uses, driven by the same four authorable copy props —\n * the two surfaces cannot word a tier differently.\n */\nexport function installmentLabel({\n  tier,\n  locale,\n  installmentTemplate,\n  interestFreeLabel,\n  interestTemplate,\n}: {\n  tier: InstallmentTier;\n  locale: string;\n  installmentTemplate: string;\n  interestFreeLabel: string;\n  interestTemplate: string;\n}): string {\n  const formattedValue = formatInstallmentValue(tier.value.amount, locale, tier.value.currencyCode);\n  const base = substituteTemplate(installmentTemplate, { count: String(tier.count), value: formattedValue });\n  const interestSuffix =\n    tier.interestRate === 0\n      ? interestFreeLabel\n      : substituteTemplate(interestTemplate, { rate: formatInterestRate(tier.interestRate, locale) });\n  return interestSuffix ? `${base} ${interestSuffix}` : base;\n}\n\n// ---------------------------------------------------------------------------\n// Definition\n// ---------------------------------------------------------------------------\n\nexport const InstallmentsDefinition = defineComponent<InstallmentsProps>({\n  name: 'Installments',\n  importPath: '@vtex/faststore/components',\n  component: Installments,\n  fragment,\n  fetchStrategy: 'reactive',\n  requiresContext: 'payment',\n  actions: { payment: ['setInstallments'] },\n  editor: { label: 'Installments', category: 'commerce' },\n  schema: {\n    installmentTemplate: { type: 'string', default: '{count}x of {value}', label: 'Installment template' },\n    interestFreeLabel: { type: 'string', default: 'interest-free', label: 'Interest-free label' },\n    interestTemplate: { type: 'string', default: '{rate}% interest', label: 'Interest template' },\n    // T38: an inline literal, never an identifier — the native catalog builder extracts `schema`\n    // statically and silently drops an identifier-valued default (INV-8).\n    legend: { type: 'string', default: 'Installments', label: 'Legend' },\n  },\n  guideline:\n    'Installment selector for checkout: shows count, per-installment value, and interest for the card currently being entered (matched by BIN) or the saved card currently selected (matched by the persisted BIN, falling back to method), rendering exactly the tiers the matched option returns (the API guarantees a 1x tier is present in every option, so one is always shown and selectable — see specs/installments.md). Must be inside a PaymentSectionRoot or PaymentSectionController — place it as a sibling of CardEntry and SavedCards, never nested inside either, so one instance serves both entry paths. Picking a row dispatches $actions.payment.setInstallments and the order total updates elsewhere from the normalized cache with no wiring here. Renders its own rows from real data — no children.',\n});\n\n// ---------------------------------------------------------------------------\n// Implementation\n// ---------------------------------------------------------------------------\n\nexport function Installments({\n  installmentTemplate = '{count}x of {value}',\n  interestFreeLabel = 'interest-free',\n  interestTemplate = '{rate}% interest',\n  legend,\n  $data,\n  $actions: $actionsProp,\n  className,\n  ...props\n}: InstallmentsProps) {\n  const $actions = useActionsOverride($actionsProp);\n  // T192: the formatting locale is the storefront's, never an authored prop (RFC localization § 10).\n  const { locale } = useStorefrontContext();\n  const { tiers, selectedCount, state, isPending, selectionError, selectInstallment, placing, cardPaymentCollapsed } =\n    useInstallmentsSelection({\n      $data,\n      $actions,\n    });\n\n  // T191 (FR-7): nothing renders while the card payment is collapsed. Returned after the last hook, so\n  // this instance stays mounted and keeps its local state.\n  if (cardPaymentCollapsed) return null;\n\n  return (\n    <div\n      {...props}\n      className={className}\n      inert={placing}\n      aria-disabled={placing || undefined}\n      data-fs-installments=\"\"\n      data-fs-installments-state={state}\n      aria-busy={isPending || undefined}\n      {...(placing ? { 'data-fs-installments-placing': '' } : {})}\n    >\n      {selectionError ? (\n        <div role=\"alert\" data-fs-installments-error=\"\">\n          {selectionError}\n        </div>\n      ) : null}\n      {tiers.length > 0 ? (\n        // T38, Decision 1: Fieldset.Root + Fieldset.Legend, exactly what card-entry.tsx:1101-1112\n        // already ships — Base UI propagates the legend's id as aria-labelledby onto the descendant\n        // RadioGroup, so this one wrapper names both the fieldset and the radiogroup (measured).\n        <Fieldset.Root data-fs-installments-fieldset=\"\">\n          <Fieldset.Legend>{resolveAuthoredCopy(legend, 'Installments')}</Fieldset.Legend>\n          <RadioGroup\n            value={String(selectedCount)}\n            onValueChange={(value) => selectInstallment(Number(value))}\n            disabled={isPending}\n          >\n            {tiers.map((tier) => (\n              <RadioRoot key={tier.count} value={String(tier.count)} disabled={isPending}>\n                <RadioIndicator data-fs-installments-option-indicator=\"\" />\n                <span data-fs-installments-option-label=\"\">\n                  {installmentLabel({ tier, locale, installmentTemplate, interestFreeLabel, interestTemplate })}\n                </span>\n              </RadioRoot>\n            ))}\n          </RadioGroup>\n        </Fieldset.Root>\n      ) : null}\n    </div>\n  );\n}\n"],"mappings":"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"}

package/dist/matter/installments/use-installments-selection.d.ts

@@ -0,0 +1,29 @@
+import "../../sdk/actions/types.js";
+import "./installments-select.js";
+import { InstallmentOption, InstallmentTier } from "./installments.js";
+//#region src/matter/installments/use-installments-selection.d.ts
+/**
+ * Bin-first, methodId-fallback lookup — the client mirror of the server's own
+ * `findMatchingInstallmentOption` (`apps/storefront-api-core/.../checkout/mappers.ts`). Returns
+ * `null` when neither a `bin` nor a `methodId` match exists — never a guessed or nearest-match option
+ * (specs/installments.md § Decision 1).
+ */
+export declare function findInstallmentOption(options: readonly InstallmentOption[], { bin, methodId }: {
+  bin: string | null;
+  methodId: string | null;
+}): InstallmentOption | null;
+/**
+ * Returns the matched option's tiers as the API projected them. The API
+ * guarantees a `count: 1` tier is present in every `installmentOptions`
+ * entry, including those with an empty tier list (`mappers.ts:guaranteeSingleInstallmentTier`),
+ * so this function returns it verbatim — no client-side synthesis. A tier
+ * invented only on the read side was a dead end: `paymentInstallmentSelect`
+ * validates the picked count against the same upstream list the synthesis was
+ * compensating for (`index.ts:1675-1688`), so it either dispatched nothing or
+ * was rejected `INVALID_INSTALLMENT_COUNT`. That rationale is why neither surface
+ * may re-add client-side synthesis — the guarantee belongs server-side, and is
+ * now closed by the read/write guarantee. Returns `[]` when no option resolved.
+ */
+export declare function resolveInstallmentTiers(option: InstallmentOption | null): readonly InstallmentTier[];
+//#endregion
+//# sourceMappingURL=use-installments-selection.d.ts.map

package/dist/matter/installments/use-installments-selection.js

@@ -0,0 +1,95 @@
+"use client";
+import { useDataOverride } from "../../sdk/data/data-override-context.js";
+import { isCardMethod } from "../payment/use-payment-method-selection.js";
+import { usePayment } from "../payment/payment.js";
+import { useCallback, useRef, useState } from "react";
+//#region src/matter/installments/use-installments-selection.ts
+const EMPTY_TIERS = [];
+/**
+* Bin-first, methodId-fallback lookup — the client mirror of the server's own
+* `findMatchingInstallmentOption` (`apps/storefront-api-core/.../checkout/mappers.ts`). Returns
+* `null` when neither a `bin` nor a `methodId` match exists — never a guessed or nearest-match option
+* (specs/installments.md § Decision 1).
+*/
+function findInstallmentOption(options, { bin, methodId }) {
+	if (bin) {
+		const matchedByBin = options.find((option) => option.bin === bin);
+		if (matchedByBin) return matchedByBin;
+	}
+	if (methodId) return options.find((option) => option.methodId === methodId) ?? null;
+	return null;
+}
+/**
+* Returns the matched option's tiers as the API projected them. The API
+* guarantees a `count: 1` tier is present in every `installmentOptions`
+* entry, including those with an empty tier list (`mappers.ts:guaranteeSingleInstallmentTier`),
+* so this function returns it verbatim — no client-side synthesis. A tier
+* invented only on the read side was a dead end: `paymentInstallmentSelect`
+* validates the picked count against the same upstream list the synthesis was
+* compensating for (`index.ts:1675-1688`), so it either dispatched nothing or
+* was rejected `INVALID_INSTALLMENT_COUNT`. That rationale is why neither surface
+* may re-add client-side synthesis — the guarantee belongs server-side, and is
+* now closed by the read/write guarantee. Returns `[]` when no option resolved.
+*/
+function resolveInstallmentTiers(option) {
+	return option ? option.installments : EMPTY_TIERS;
+}
+const EMPTY_OPTIONS = [];
+const ONE_TIME_COUNT = 1;
+/**
+* Precedence unchanged from `Installments`' own (now-removed) local `installmentsState`: loading,
+* then pending, then empty, then ready.
+*/
+function installmentsSelectionState({ loading, count, binConfirmation }) {
+	if (loading) return "loading";
+	if (binConfirmation === "pending") return "pending";
+	if (count === 0) return "empty";
+	return "ready";
+}
+function useInstallmentsSelection({ $data: $dataProp, $actions }) {
+	const $data = useDataOverride($dataProp);
+	const { draft, selectedMethodId, selectedMethod, selectedBin, binConfirmation, placing, cardPaymentCollapsed } = usePayment();
+	const loading = $data == null;
+	const tiers = resolveInstallmentTiers(findInstallmentOption($data?.installmentOptions ?? EMPTY_OPTIONS, {
+		bin: draft.bin ?? selectedBin ?? null,
+		methodId: selectedMethod !== null && isCardMethod(selectedMethod) ? selectedMethodId : null
+	}));
+	const [selectionError, setSelectionError] = useState(null);
+	const [requestedCount, setRequestedCount] = useState(null);
+	const selectionToken = useRef(0);
+	const isPending = binConfirmation === "pending";
+	const selectedCount = requestedCount ?? $data?.selectedInstallment?.count ?? ONE_TIME_COUNT;
+	const selectInstallment = useCallback((count) => {
+		if (binConfirmation === "pending") return;
+		setSelectionError(null);
+		const dispatch = $actions?.payment?.setInstallments;
+		if (!dispatch) return;
+		const token = ++selectionToken.current;
+		setRequestedCount(count);
+		dispatch(count).then((userErrors) => {
+			if (selectionToken.current !== token) return;
+			const [firstError] = userErrors;
+			if (firstError) setSelectionError(firstError.message);
+		}).finally(() => {
+			if (selectionToken.current === token) setRequestedCount(null);
+		});
+	}, [$actions, binConfirmation]);
+	return {
+		tiers,
+		selectedCount,
+		state: installmentsSelectionState({
+			loading,
+			count: tiers.length,
+			binConfirmation
+		}),
+		isPending,
+		selectionError,
+		selectInstallment,
+		placing,
+		cardPaymentCollapsed
+	};
+}
+//#endregion
+export { findInstallmentOption, resolveInstallmentTiers, useInstallmentsSelection };
+
+//# sourceMappingURL=use-installments-selection.js.map

package/dist/matter/installments/use-installments-selection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-installments-selection.js","names":[],"sources":["../../../src/matter/installments/use-installments-selection.ts"],"sourcesContent":["'use client';\n\nimport { useCallback, useRef, useState } from 'react';\nimport type { ComponentActions } from '../../sdk/actions/types.js';\nimport { useDataOverride } from '../../sdk/data/data-override-context.js';\nimport { usePayment } from '../payment/payment.js';\nimport { isCardMethod, type PaymentBinConfirmation } from '../payment/use-payment-method-selection.js';\nimport type { InstallmentOption, InstallmentsData, InstallmentTier } from './installments.js';\nimport type { InstallmentsSelectData } from './installments-select.js';\n\n// ---------------------------------------------------------------------------\n// Resolution — moved here from `installments.tsx` (T90 finding 4, review of\n// specs/render-installments-as-a-radio-group.md). This hook was these two functions' only caller, so\n// `installments.tsx` importing the hook while the hook imported the functions back out of\n// `installments.tsx` was a genuine two-way ESM cycle. `installments.tsx` now re-exports both\n// unchanged, so `installments.test.tsx` (zero-diff) and the package barrel (`src/index.ts`) keep\n// importing them from the same path. Mirrors `use-delivery-option-selection.ts`, which owns its own\n// helpers outright and depends on no renderer.\n// ---------------------------------------------------------------------------\n\nconst EMPTY_TIERS: readonly InstallmentTier[] = [];\n\n/**\n * Bin-first, methodId-fallback lookup — the client mirror of the server's own\n * `findMatchingInstallmentOption` (`apps/storefront-api-core/.../checkout/mappers.ts`). Returns\n * `null` when neither a `bin` nor a `methodId` match exists — never a guessed or nearest-match option\n * (specs/installments.md § Decision 1).\n */\nexport function findInstallmentOption(\n  options: readonly InstallmentOption[],\n  { bin, methodId }: { bin: string | null; methodId: string | null },\n): InstallmentOption | null {\n  if (bin) {\n    const matchedByBin = options.find((option) => option.bin === bin);\n    if (matchedByBin) return matchedByBin;\n  }\n  if (methodId) {\n    return options.find((option) => option.methodId === methodId) ?? null;\n  }\n  return null;\n}\n\n/**\n * Returns the matched option's tiers as the API projected them. The API\n * guarantees a `count: 1` tier is present in every `installmentOptions`\n * entry, including those with an empty tier list (`mappers.ts:guaranteeSingleInstallmentTier`),\n * so this function returns it verbatim — no client-side synthesis. A tier\n * invented only on the read side was a dead end: `paymentInstallmentSelect`\n * validates the picked count against the same upstream list the synthesis was\n * compensating for (`index.ts:1675-1688`), so it either dispatched nothing or\n * was rejected `INVALID_INSTALLMENT_COUNT`. That rationale is why neither surface\n * may re-add client-side synthesis — the guarantee belongs server-side, and is\n * now closed by the read/write guarantee. Returns `[]` when no option resolved.\n */\nexport function resolveInstallmentTiers(option: InstallmentOption | null): readonly InstallmentTier[] {\n  return option ? option.installments : EMPTY_TIERS;\n}\n\n/**\n * Shared selection engine behind `Installments` (the radio surface) and `InstallmentsSelect` (the\n * collapsed dropdown — T90, specs/render-installments-as-a-radio-group.md § Decision 3). Owns the\n * behaviours the spec requires identically across every surface, so they cannot drift apart, mirroring\n * `useDeliveryOptionSelection`:\n *\n * - **Matching.** Bin-first, methodId-fallback lookup (`draft.bin ?? selectedBin`, then\n *   `selectedMethodId` when the selected method is a card — T191, FR-9) via `findInstallmentOption` —\n *   the client mirror of the server's own `findMatchingInstallmentOption`.\n * - **Tier resolution.** `resolveInstallmentTiers` returns the matched option's own `installments`\n *   reference verbatim — no client-side synthesis. A v1 version of this synthesized a `count: 1` row\n *   when upstream omitted one; PR #507's review (finding F1) proved that row a dead end —\n *   `paymentInstallmentSelect` validates the picked count against the same upstream list the\n *   synthesis was compensating for, so a client-invented tier could never actually be selected. The\n *   read/write guarantee (`mappers.ts:guaranteeSingleInstallmentTier`) now closes this server-side\n *   instead (specs/installments.md § Decision 2).\n * - **`selectedCount`.** Bound to the count of this engine's own latest `setInstallments` dispatch while\n *   it is unsettled, and to the persisted `selectedInstallment.count` (defaulting to `1`) otherwise\n *   (T174, FR-4, amending INV-3). A pick shows at once, and a refused one falls back to the persisted\n *   plan once its dispatch settles.\n * - **State derivation.** `loading` / `pending` / `empty` / `ready`, identical in meaning for both\n *   surfaces. `ready` does not guarantee a matched tier: the persisted count can be unreachable in the\n *   currently matched option (e.g. the shopper edits the BIN to one offering fewer tiers).\n * - **The pending gate.** Dispatch is held while `binConfirmation === 'pending'` — a tri-state signal\n *   from `usePaymentMethodSelection` that compares the persisted `selectedBin` against `draft.bin` and\n *   tracks whether a `payment.setMethod` is in flight. The earlier component-local gate (PR #507\n *   review, finding F3) wedged permanently because its confirming signal never changed reference for\n *   this fragment's own selection set; this gate reads `Payment.selectedBin` from T5's fragment and an\n *   in-flight counter instead (specs/epics/credit-card.md, decisions.md:105).\n * - **Dispatch.** Request-token-guarded `$actions.payment.setInstallments`, surfacing the first\n *   `userError` inline — exactly like `PaymentMethodList` / `DeliveryOptionsListBody`.\n *\n * Calls `useDataOverride()` and `usePayment()` itself, exactly as `useDeliveryOptionSelection` does.\n * Not exported from the package barrel — an internal engine, matching `use-delivery-option-selection.ts`.\n * Each surface renders its own markup and its own `role=\"alert\"`; label formatting\n * (`installmentLabel`, exported from `installments.tsx`) is deliberately NOT part of this engine — it\n * is a rendering concern each surface applies to the `tiers` this hook returns.\n */\nexport type InstallmentsSelection = {\n  /** Tiers of the matched option, in API order. Empty when nothing matched. */\n  tiers: readonly InstallmentTier[];\n  /** The bound value: the latest unsettled pick's count, else persisted `selectedInstallment.count`, else 1. */\n  selectedCount: number;\n  /** Presence state, identical in meaning for both surfaces. */\n  state: 'loading' | 'pending' | 'empty' | 'ready';\n  /** True while `binConfirmation === 'pending'` — disables the control and holds dispatch. */\n  isPending: boolean;\n  /** First `userError` message from the latest selection, or null. */\n  selectionError: string | null;\n  /** Request-token-guarded dispatch of `$actions.payment.setInstallments`. No-op while pending. */\n  selectInstallment: (count: number) => void;\n  /** An order-placement sequence is in flight (T28); `Installments` renders its whole subtree\n   * non-interactive while this is true. Read straight off `usePayment()`, never mirrored. */\n  placing: boolean;\n  /** The card payment is collapsed (T191, FR-7); both surfaces render nothing while this is true. Read\n   * straight off `usePayment()`, never mirrored. */\n  cardPaymentCollapsed: boolean;\n};\n\nconst EMPTY_OPTIONS: readonly InstallmentOption[] = [];\nconst ONE_TIME_COUNT = 1;\n\n/**\n * Precedence unchanged from `Installments`' own (now-removed) local `installmentsState`: loading,\n * then pending, then empty, then ready.\n */\nfunction installmentsSelectionState({\n  loading,\n  count,\n  binConfirmation,\n}: {\n  loading: boolean;\n  count: number;\n  binConfirmation: PaymentBinConfirmation;\n}): 'loading' | 'pending' | 'empty' | 'ready' {\n  if (loading) return 'loading';\n  if (binConfirmation === 'pending') return 'pending';\n  if (count === 0) return 'empty';\n  return 'ready';\n}\n\nexport function useInstallmentsSelection({\n  $data: $dataProp,\n  $actions,\n}: {\n  $data?: InstallmentsData | InstallmentsSelectData;\n  $actions?: ComponentActions;\n}): InstallmentsSelection {\n  const $data = useDataOverride($dataProp);\n  const { draft, selectedMethodId, selectedMethod, selectedBin, binConfirmation, placing, cardPaymentCollapsed } =\n    usePayment();\n\n  const loading = $data == null;\n  const options = $data?.installmentOptions ?? EMPTY_OPTIONS;\n  const matchedOption = findInstallmentOption(options, {\n    bin: draft.bin ?? selectedBin ?? null,\n    // T191 (FR-9, Decision 10): only a card method's own options apply — card mode over a persisted\n    // Promissory reads `empty` until a card is recorded, never Promissory's own `1x` tier.\n    methodId: selectedMethod !== null && isCardMethod(selectedMethod) ? selectedMethodId : null,\n  });\n  const tiers = resolveInstallmentTiers(matchedOption);\n\n  const [selectionError, setSelectionError] = useState<string | null>(null);\n  // T174 (FR-4, Decision 4): the count of the latest `setInstallments` dispatch until it settles.\n  const [requestedCount, setRequestedCount] = useState<number | null>(null);\n  const selectionToken = useRef(0);\n  const isPending = binConfirmation === 'pending';\n  const selectedCount = requestedCount ?? $data?.selectedInstallment?.count ?? ONE_TIME_COUNT;\n\n  const selectInstallment = useCallback(\n    (count: number) => {\n      if (binConfirmation === 'pending') return;\n      setSelectionError(null);\n      const dispatch = $actions?.payment?.setInstallments;\n      if (!dispatch) return;\n      const token = ++selectionToken.current;\n      setRequestedCount(count);\n      dispatch(count)\n        .then((userErrors) => {\n          if (selectionToken.current !== token) return;\n          const [firstError] = userErrors;\n          if (firstError) setSelectionError(firstError.message);\n        })\n        .finally(() => {\n          // A successful echo already carries this count; a refused pick falls back to the persisted one.\n          if (selectionToken.current === token) setRequestedCount(null);\n        });\n    },\n    [$actions, binConfirmation],\n  );\n\n  return {\n    tiers,\n    selectedCount,\n    state: installmentsSelectionState({ loading, count: tiers.length, binConfirmation }),\n    isPending,\n    selectionError,\n    selectInstallment,\n    placing,\n    cardPaymentCollapsed,\n  };\n}\n"],"mappings":";;;;;;AAoBA,MAAM,cAA0C,CAAC;;;;;;;AAQjD,SAAgB,sBACd,SACA,EAAE,KAAK,YACmB;CAC1B,IAAI,KAAK;EACP,MAAM,eAAe,QAAQ,MAAM,WAAW,OAAO,QAAQ,GAAG;EAChE,IAAI,cAAc,OAAO;CAC3B;CACA,IAAI,UACF,OAAO,QAAQ,MAAM,WAAW,OAAO,aAAa,QAAQ,KAAK;CAEnE,OAAO;AACT;;;;;;;;;;;;;AAcA,SAAgB,wBAAwB,QAA8D;CACpG,OAAO,SAAS,OAAO,eAAe;AACxC;AA6DA,MAAM,gBAA8C,CAAC;AACrD,MAAM,iBAAiB;;;;;AAMvB,SAAS,2BAA2B,EAClC,SACA,OACA,mBAK4C;CAC5C,IAAI,SAAS,OAAO;CACpB,IAAI,oBAAoB,WAAW,OAAO;CAC1C,IAAI,UAAU,GAAG,OAAO;CACxB,OAAO;AACT;AAEA,SAAgB,yBAAyB,EACvC,OAAO,WACP,YAIwB;CACxB,MAAM,QAAQ,gBAAgB,SAAS;CACvC,MAAM,EAAE,OAAO,kBAAkB,gBAAgB,aAAa,iBAAiB,SAAS,yBACtF,WAAW;CAEb,MAAM,UAAU,SAAS;CAQzB,MAAM,QAAQ,wBANQ,sBADN,OAAO,sBAAsB,eACQ;EACnD,KAAK,MAAM,OAAO,eAAe;EAGjC,UAAU,mBAAmB,QAAQ,aAAa,cAAc,IAAI,mBAAmB;CACzF,CACkD,CAAC;CAEnD,MAAM,CAAC,gBAAgB,qBAAqB,SAAwB,IAAI;CAExE,MAAM,CAAC,gBAAgB,qBAAqB,SAAwB,IAAI;CACxE,MAAM,iBAAiB,OAAO,CAAC;CAC/B,MAAM,YAAY,oBAAoB;CACtC,MAAM,gBAAgB,kBAAkB,OAAO,qBAAqB,SAAS;CAE7E,MAAM,oBAAoB,aACvB,UAAkB;EACjB,IAAI,oBAAoB,WAAW;EACnC,kBAAkB,IAAI;EACtB,MAAM,WAAW,UAAU,SAAS;EACpC,IAAI,CAAC,UAAU;EACf,MAAM,QAAQ,EAAE,eAAe;EAC/B,kBAAkB,KAAK;EACvB,SAAS,KAAK,CAAC,CACZ,MAAM,eAAe;GACpB,IAAI,eAAe,YAAY,OAAO;GACtC,MAAM,CAAC,cAAc;GACrB,IAAI,YAAY,kBAAkB,WAAW,OAAO;EACtD,CAAC,CAAC,CACD,cAAc;GAEb,IAAI,eAAe,YAAY,OAAO,kBAAkB,IAAI;EAC9D,CAAC;CACL,GACA,CAAC,UAAU,eAAe,CAC5B;CAEA,OAAO;EACL;EACA;EACA,OAAO,2BAA2B;GAAE;GAAS,OAAO,MAAM;GAAQ;EAAgB,CAAC;EACnF;EACA;EACA;EACA;EACA;CACF;AACF"}

package/dist/matter/my-account-profile/my-account-profile.js

@@ -5,16 +5,16 @@ import { Field } from "../../particles/field/field.js";
 import { useActionsOverride } from "../../sdk/actions/actions-override-context.js";
 import { useDataOverride } from "../../sdk/data/data-override-context.js";
 import { useSession } from "../session/session.js";
+import { Select } from "../../particles/select/select.js";
+import { DocumentField, isSupportedDocumentType, isValidDocument, maskDocumentValue } from "../../particles/document-field/document-field.js";
 import { Input } from "../../particles/input/input.js";
 import { PhoneField, applyPhoneMask, toE164, validatePhoneNumber } from "../../particles/phone-field/phone-field.js";
-import { DocumentField, isSupportedDocumentType, isValidDocument, maskDocumentValue } from "../../particles/document-field/document-field.js";
-import { Select } from "../../particles/select/select.js";
 import { useToast } from "../../particles/toast/toast.js";
 import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState } from "react";
 import { jsx, jsxs } from "react/jsx-runtime";
 //#region src/matter/my-account-profile/my-account-profile.tsx
 /**
-* The `my-account-profile` compound (specs/sfs-3287-my-account-profile-root.md) — the data root
+* The `my-account-profile` compound (see my-account-profile.md; spec archived at the specs-archive tag) — the data root
 * plus form mechanics for the shopper's persistent account profile. `Root` owns the saved profile,
 * the draft, the view↔edit toggle, and the single batched Save; it publishes a context whose
 * registration API is the seam every field Control attaches to.
@@ -123,12 +123,12 @@ const MyAccountProfileRootDefinition = defineComponent({
 		},
 		saveFailedMessage: {
 			type: "string",
-			default: DEFAULT_SAVE_FAILED_MESSAGE,
+			default: "Unable to save your profile. Please try again.",
 			label: "Save failure message"
 		},
 		savedMessage: {
 			type: "string",
-			default: DEFAULT_SAVED_MESSAGE,
+			default: "Your profile has been saved.",
 			label: "Save success message"
 		}
 	},