@vtex/faststore 0.0.6 → 0.0.7

package/dist/matter/payment/payment.js.map

@@ -1 +1 @@
-{"version":3,"file":"payment.js","names":[],"sources":["../../../src/matter/payment/payment.tsx"],"sourcesContent":["'use client';\n\nimport { defineComponent } from '@vtex/fs-core';\nimport { type ComponentPropsWithRef, createContext, useContext, useId, useLayoutEffect, useMemo } 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 { useDataOverride } from '../../sdk/data/data-override-context.js';\nimport { PaymentSubmissionProvider } from '../../sdk/payment/submission-registry.js';\nimport { resolveAuthoredCopy } from '../../utils/resolve-authored-copy.js';\nimport { PaymentCardCaptureProvider, type PaymentCartData } from './payment-card-capture.js';\nimport {\n  type PaymentMethodSelection,\n  type PaymentSectionData,\n  resolveCanRevealCardPayment,\n  resolvePreselectionCandidateId,\n  splitCardMethods,\n  usePaymentMethodSelection,\n} from './use-payment-method-selection.js';\n\n/**\n * The `PaymentSection` matter root (specs/payment-section-root.md, T5 of the Credit Card epic;\n * docs/features/credit-card/rfc.md § D1). `PaymentSectionRoot` is the always-visible presentation\n * variant over the `Payment` entity T1 projects: it owns a thin `fragment` (the method list with its\n * server-driven validator config, plus the current selection), runs the shared\n * `usePaymentMethodSelection` engine, and provides the `payment` context its leaves read — the card\n * entry (T7), cardholder document (T8), installments (T9), save-card (T10), billing address (T11),\n * saved cards (T12), and place-order CTA (T14) — through the guarded `usePayment()` hook rather than\n * drilled props (ADR-0009). `PaymentSectionController` (payment-controller.tsx) is the second provider\n * of the same context for a collapsed overlay surface; ADR-0009 matches by contract identifier, so the\n * two substitute for one another with zero edits to any consumer.\n *\n * \"Thin\" means no `installmentOptions` (T9's own fragment), no `savedCards` (T12's), and no\n * `selectedInstallment` (T6's) — the heavy, optional, and iterated subtrees ADR-0011/ADR-0012 split out.\n * `methods[].validator` *is* selected here: it is a non-normalized value object off `Payment.methods`\n * that cannot be subscribed separately, and T7 tests every method's `numberRegex` to detect a network.\n *\n * `children` is the section composition, not a per-method template — the method picker is\n * `PaymentMethodList`, an independently placeable part with its own hooks.\n */\n\n// ---------------------------------------------------------------------------\n// GraphQL Fragment — raw template literal, matching the merged `payment-summary` sibling. The codegen\n// `documents` glob does not scan `src/matter/payment*`, so the typed `graphql()` factory is\n// unavailable here; `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 the\n// `Payment` entity that `paymentMethodSelect` echoes back to update the same cache entity this\n// fragment reads. `fetchStrategy: 'reactive'`'s no-refetch guarantee holds only if both sides\n// normalize to one entity.\n// ---------------------------------------------------------------------------\n\nconst fragment = /* GraphQL */ `\n  fragment PaymentSectionData on Query {\n    payment {\n      __typename\n      id\n      methods {\n        __typename\n        id\n        name\n        groupName\n        validator {\n          __typename\n          numberMask\n          numberRegex\n          cvvMask\n          cvvRegex\n          cvvRequired\n          expirationRequired\n          holderNameRequired\n          billingAddressRequired\n          documentDisplayable\n          documentRequired\n        }\n      }\n      selectedMethodId\n      selectedAccountId\n      selectedBin\n    }\n    cart {\n      __typename\n      id\n      total {\n        __typename\n        amount\n        currencyCode\n      }\n    }\n  }\n`;\n\n/**\n * The default payment-group scope: credit and debit (T140, FR-2, Decision 2). Both strings are\n * store-configured, so a store whose groups differ must set `group` explicitly; `group: ''` scopes\n * nothing (specs/payment-section-root.md § Documentation Gaps item 1). Widened from a single string to\n * a set (Decision 1) — a public API break for any consumer importing it directly (Interfaces).\n */\n/**\n * The roots' keyed `$data` (ADR-0015, arity 2): the `Payment` slice the selection engine reads, and the\n * cart total `add_payment_info` needs (moved here from `CardEntry`, which reads no cart).\n */\nexport type PaymentSectionRootData = {\n  payment?: PaymentSectionData;\n  cart?: PaymentCartData;\n} | null;\n\nexport const DEFAULT_METHOD_GROUP: readonly string[] = ['creditCardPaymentGroup', 'debitCardPaymentGroup'];\n\n// ---------------------------------------------------------------------------\n// Payment context — provided by both section roots, read by every leaf\n// ---------------------------------------------------------------------------\n\n/**\n * The `payment` context contract, normative for T7–T12 and T14. Everything the selection engine\n * resolves, plus the overlay disclosure. What is deliberately absent is part of the contract too: no\n * card number, CVV, expiration, or holder name (RFC D13 — they live only in the card entry's local\n * state); no submission channel for the place-order sequence, which is the separate, narrow\n * `PaymentSubmissionProvider` below (T13) precisely so no card-shaped value ever joins this contract;\n * no `installmentOptions` / `savedCards` / `selectedInstallment` (their owners' fragments); and no\n * optimistic mirror of the persisted selection.\n */\nexport type PaymentContextValue = Readonly<\n  PaymentMethodSelection & {\n    /** The collapsed surface's disclosure state. Always `true` under `PaymentSectionRoot`. */\n    open: boolean;\n    /**\n     * Drives the collapsed surface. A no-op under `PaymentSectionRoot`, so a leaf written for the\n     * overlay composes unchanged inline. Selecting a method never closes the surface on its own — the\n     * shopper still has a card to type — so closing is the composition's call (Decision 5).\n     */\n    setOpen: (open: boolean) => void;\n  }\n>;\n\nconst PAYMENT_CONTEXT_UNSET = Symbol('PaymentContextUnset');\n\nconst PaymentContextInternal = createContext<PaymentContextValue | typeof PAYMENT_CONTEXT_UNSET>(PAYMENT_CONTEXT_UNSET);\n\n/** The provider both section roots render. Exported for `PaymentSectionController`. */\nexport const PaymentContext = PaymentContextInternal as React.Context<PaymentContextValue>;\n\n/**\n * Read the payment section's selection state, draft, and overlay disclosure from the nearest\n * `PaymentSectionRoot` or `PaymentSectionController`. Throws outside either subtree — a misplaced\n * consumer is a composition bug the author should see immediately, not a silent degrade to an empty\n * selection — mirroring `useSession()` / `useDeliveryOptions()`. ADR-0009's compiler check catches the\n * same mistake before emission for schema-authored pages; this is the defense-in-depth layer for\n * Storybook, tests, and hand-written JSX.\n */\nexport function usePayment(): PaymentContextValue {\n  const ctx = useContext(PaymentContextInternal);\n  if (ctx === PAYMENT_CONTEXT_UNSET) {\n    throw new Error('usePayment() must be used inside a <PaymentSectionRoot> or <PaymentSectionController> subtree.');\n  }\n  return ctx;\n}\n\nconst NO_DISCLOSURE = () => {};\n\n// ---------------------------------------------------------------------------\n// Props\n// ---------------------------------------------------------------------------\n\nexport type PaymentSectionRootProps = ComponentPropsWithRef<'div'> & {\n  /**\n   * Scopes the method list to a **set** of `PaymentMethod.groupName` values — a method is in scope\n   * when its `groupName` is a member (T140, FR-1, Decision 1). A single string is still accepted and\n   * scopes to exactly that one group (FR-4, US-3). T1's read model is method-agnostic and assigns the\n   * narrowing to the consumer; this prop supplies no method, label, or ordering — the list itself is\n   * fragment data. An empty string scopes nothing.\n   */\n  group?: string | readonly string[];\n  /** Keyed `{ payment, cart }` forwarded by the reactive runtime (arity-2 fragment, ADR-0015). */\n  $data?: PaymentSectionRootData;\n  /** Compiler-injected action surface; carries `payment.setMethod`, `payment.sendPayments`, and `analytics.track`. */\n  $actions?: ComponentActions;\n};\n\n/** Renders its own controls from the context's method list — `children` would have nothing to template. */\nexport type PaymentMethodListProps = Omit<ComponentPropsWithRef<'div'>, 'children'> & {\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  /**\n   * The single card control's name (T171, Decision 8). The control stands for every in-scope\n   * credit/debit method at once, so it cannot take its name from one of their `method.name` values the\n   * way a per-network row did — it is authored copy instead, defaulting to the PRD's own string.\n   * Resolved through `resolveAuthoredCopy` exactly as `legend` is, so an authored empty or\n   * whitespace-only string falls back rather than rendering a nameless control.\n   */\n  cardLabel?: string;\n};\n\n// ---------------------------------------------------------------------------\n// Definitions\n// ---------------------------------------------------------------------------\n\nexport const PaymentSectionRootDefinition = defineComponent<PaymentSectionRootProps>({\n  name: 'PaymentSectionRoot',\n  importPath: '@vtex/faststore/components',\n  component: PaymentSectionRoot,\n  fragment,\n  fetchStrategy: 'reactive',\n  actions: { payment: ['setMethod', 'sendPayments'], analytics: ['track'] },\n  providesContext: ['payment', 'card-capture'],\n  editor: { label: 'Payment Section', category: 'commerce' },\n  schema: {\n    // A literal, not `DEFAULT_METHOD_GROUP`: the native catalog builder extracts `schema` statically\n    // and silently drops an identifier-valued default, so the built entry would carry no default and\n    // the compiler would emit the section unscoped. `payment.test.tsx` asserts the literal matches the\n    // constant, and that the built catalog kept the default.\n    // T140, Decision 2/OQ-6: `type: 'array'` — no code path in packages/sukima/crates/sukima-core/\n    // validates an authored prop's JSON value against this declared type, so a store's existing bare\n    // string keeps compiling. No `items`: an enum would validate against a closed set of group names,\n    // which is wrong for a store that renamed its group (OQ-3) — the exact fragility Decision 1 closes.\n    group: {\n      type: 'array',\n      default: ['creditCardPaymentGroup', 'debitCardPaymentGroup'],\n      label: 'Payment method group',\n    },\n  },\n  guideline:\n    \"Root of the checkout payment section: reads the payment methods and the current selection from the order form and provides the 'payment' context every payment leaf needs and the 'card-capture' context CardEntry needs, so place CardEntry, CardholderDocument, Installments, SaveCard, BillingAddress, SavedCards, PlaceOrder, and PaymentMethodList as its children — none of them render without a payment root ancestor. Renders one container div and no chrome or copy of its own; headings and layout belong to the composition. Selecting a payment option dispatches $actions.payment.setMethod and every subscriber re-renders from the cache with no refetch — and for a card it is the number the shopper types that decides the network, not an option they pick, so PaymentMethodList shows every in-scope credit and debit method as ONE card option. Which methods exist is always real data — never author them as props; group only scopes the list by the store's payment group(s) — defaults to credit and debit together, accepts one group name or a set of them, and set it to \\\"\\\" to show every method, one option each, with no card option. Use PaymentSectionController instead when the section should live in a drawer or modal. See payment.md.\",\n});\n\nexport const PaymentMethodListDefinition = defineComponent<PaymentMethodListProps>({\n  name: 'PaymentMethodList',\n  importPath: '@vtex/faststore/components',\n  component: PaymentMethodList,\n  requiresContext: 'payment',\n  editor: { label: 'Payment Method List', category: 'commerce' },\n  schema: {\n    // T38/T171: inline literals, never identifiers — the native catalog builder extracts `schema`\n    // statically and silently drops an identifier-valued default (INV-8).\n    legend: { type: 'string', default: 'Payment method', label: 'Legend' },\n    cardLabel: { type: 'string', default: 'Pay with Credit / Debit Card', label: 'Card option label' },\n  },\n  guideline:\n    'The payment-method picker: a radio group of the payment options the order form offers, plus the inline selection error (role=\"alert\"). Every in-scope credit and debit method is ONE option — the network comes from the card number the shopper types, never from a row they pick — and any other in-scope method (e.g. Pix) keeps a row of its own; set group to \"\" on the root to switch that off and get one row per method. Selecting an option dispatches the method selection. Selecting a non-card option hides the card form, and the card option brings it back. Place it inside a PaymentSectionRoot, or inside the DialogPopup/DrawerPopup of a PaymentSectionController. It renders its own options from real data, so it takes no children and no method props; author the card option\\'s wording with cardLabel. Keep it composed: it is the only element that surfaces a rejected selection, and the only control that can recover a selection this section does not serve — omit it and a shopper whose persisted method sits outside group has no reachable way back. Must be inside a payment root.',\n});\n\n// ---------------------------------------------------------------------------\n// Implementations\n// ---------------------------------------------------------------------------\n\nexport function PaymentSectionRoot({\n  group = DEFAULT_METHOD_GROUP,\n  $data: $dataProp,\n  $actions: $actionsProp,\n  className,\n  children,\n  ...props\n}: PaymentSectionRootProps) {\n  const $data = useDataOverride($dataProp);\n  const $actions = useActionsOverride($actionsProp);\n  const selection = usePaymentMethodSelection({ group, $data: $data?.payment ?? null, $actions });\n  const payment = useMemo<PaymentContextValue>(\n    () => ({ ...selection, open: true, setOpen: NO_DISCLOSURE }),\n    [selection],\n  );\n\n  return (\n    <PaymentContextInternal value={payment}>\n      <PaymentSubmissionProvider path={selection.draft.path}>\n        <PaymentCardCaptureProvider selection={selection} cart={$data?.cart} $actions={$actions}>\n          <div\n            {...props}\n            className={className}\n            data-fs-payment-section=\"\"\n            {...(selection.draft.path ? { 'data-fs-payment-section-path': selection.draft.path } : {})}\n            // T28, Decision 5: presence attribute only, deliberately never `inert` — `PlaceOrder` composes\n            // as a child of this same container (FR-6), so making it inert here would swallow the CTA's\n            // own role=\"alert\"/role=\"status\" regions, the shopper's only channel for the outcome.\n            {...(selection.placing ? { 'data-fs-payment-section-placing': '' } : {})}\n          >\n            {children}\n          </div>\n        </PaymentCardCaptureProvider>\n      </PaymentSubmissionProvider>\n    </PaymentContextInternal>\n  );\n}\n\n/**\n * The picker's presence state, always emitted so a swatch can surface a row-less container — otherwise\n * a zero-height element under any stacking swatch, and the \"visible empty region\" the section's\n * group-default risk is accepted on. `loading` (still resolving) and `empty` (resolved, nothing in\n * scope) stay distinct: one is a wait, the other a misconfiguration.\n */\nfunction methodListState({ loading, count }: { loading: boolean; count: number }): 'loading' | 'empty' | 'ready' {\n  if (loading) return 'loading';\n  if (count === 0) return 'empty';\n  return 'ready';\n}\n\n/**\n * The DOM value the collapsed card control carries inside the `RadioGroup`. Base UI requires every\n * radio root to have one, and this control stands for N methods, so there is no `method.id` it could\n * use.\n *\n * It is a radio-group value and nothing else — **never a method id** (INV-1, ADR-0023). It is never\n * dispatched: `handleValueChange` below maps it back to `resolvePreselectionCandidateId`'s answer\n * before calling `selectMethod`, and records card mode through `selectNewCard()`, which dispatches\n * nothing, when there is no candidate (T191, FR-6). The prefix keeps it from ever colliding with a\n * `PaymentMethod.id` a standalone row is bound to.\n */\nconst CARD_CONTROL_VALUE = '__fs-card-control';\n\nexport function PaymentMethodList({ legend, cardLabel, className, ...props }: PaymentMethodListProps) {\n  const {\n    methods,\n    allMethods,\n    persistedMethodId,\n    selectedMethodId,\n    selectionError,\n    selectMethod,\n    selectNewCard,\n    cardModeActive,\n    loading,\n    placing,\n    setMethodListMounted,\n  } = usePayment();\n\n  // T171, FR-1/FR-2: one control for the in-scope card methods, one row for every other in-scope\n  // method. Memoized off the two lists only (NFR-5) — nothing here may widen what re-creates the\n  // `payment` context value, which a keystroke already churns enough.\n  const { collapsedCardMethods, standaloneMethods } = useMemo(\n    () => splitCardMethods({ methods, allMethods }),\n    [methods, allMethods],\n  );\n  // Decision 3: the collapsed control dispatches the *shared* preselection candidate, so the escape\n  // hatch and the preselection can never disagree about whether an id is available.\n  const cardCandidateId = useMemo(() => resolvePreselectionCandidateId(methods), [methods]);\n  const canRevealCardPayment = resolveCanRevealCardPayment({ collapsedCardMethods, standaloneMethods });\n\n  // Decision 2: derived, never bound to one `method.id` — a control standing for N methods has none.\n  // Checked when the persisted selection resolves inside the collapsed set, and when nothing is\n  // persisted at all (PRD REQ-02's \"the card payment option is selected by default\"). The second arm\n  // is a deliberate divergence from the pre-T171 bound-to-`$data` behaviour: the control can read\n  // checked while `$data.selectedMethodId` is still null, having dispatched nothing. `persistedMethodId`\n  // is the raw, unscoped fact on purpose — a persisted method this section does not serve must leave the\n  // control unchecked, which is what keeps it activatable as US-5's way back. T191 (FR-6): card mode is\n  // the third arm, the card option chosen over such a selection or over a non-card one.\n  const cardControlChecked =\n    collapsedCardMethods.length > 0 &&\n    (persistedMethodId === null ||\n      collapsedCardMethods.some((method) => method.id === selectedMethodId) ||\n      cardModeActive);\n\n  // Fix pass, finding R2: registers this instance with the shared engine so the card leaves know an\n  // escape hatch exists before they ever collapse — a section composed with no `PaymentMethodList` at\n  // all must never hide the only remaining way to change the method (typing a new card number).\n  // Retracted unconditionally on unmount, unlike `setPlacing`'s own \"leave it if still placing\"\n  // carve-out: there is no in-flight sequence here for an abandoned instance to still be part of.\n  //\n  // T191, Decision 5 (after T171's Decision 4): what is registered is `canRevealCardPayment`, not the\n  // bare fact of being mounted — whether this list can bring the card form back. A rendered card\n  // option always can, since card mode needs no method id; without one, only a row bound to a card\n  // method can. See `resolveCanRevealCardPayment`'s own doc comment. The dependency list carries it,\n  // so the registration re-runs when the method list resolves.\n  //\n  // Fix pass round 2 (flash regression): `useLayoutEffect`, not `useEffect` — mirroring\n  // `place-order.tsx`'s own `setPlacing` registration, the structurally identical precedent for\n  // publishing a ref-counted fact to this shared engine from a leaf's mount. A passive effect runs\n  // after the browser has already painted, so a root whose persisted selection is genuinely out of\n  // scope committed one real frame with `methodListMounted` still `false` — the collapse (then\n  // `selectionOutOfScope && methodListMounted`, now `cardPaymentCollapsed`) computed `false` for that\n  // frame, painting the card form visible, focusable, and with its security code not yet cleared,\n  // before the registration ever landed and a second commit hid it. A layout effect's own state update\n  // is guaranteed to flush synchronously before the browser paints, so the very first frame a shopper\n  // can ever see already reflects `methodListMounted`. The card leaves read it purely at render time,\n  // not from an effect of their own, so this reorders nothing on that side: whichever commit this\n  // layout effect's own update produces is the one their next render (still pre-paint) sees.\n  const instanceKey = useId();\n  useLayoutEffect(() => {\n    setMethodListMounted(instanceKey, canRevealCardPayment);\n    return () => setMethodListMounted(instanceKey, false);\n  }, [instanceKey, setMethodListMounted, canRevealCardPayment]);\n\n  // INV-1: only an id the read model supplied is ever dispatched. A standalone row's value *is* its own\n  // `method.id`; the collapsed control's value is a DOM value with no method behind it, so it routes\n  // through the shared candidate instead (FR-4). With no candidate to name it records card mode, which\n  // brings the card form back and sends nothing (T191, FR-6, Decision 6).\n  function handleValueChange(value: string) {\n    if (value === CARD_CONTROL_VALUE) {\n      if (cardCandidateId !== null) {\n        selectMethod({ methodId: cardCandidateId });\n      } else {\n        selectNewCard();\n      }\n      return;\n    }\n    selectMethod({ methodId: value });\n  }\n\n  return (\n    <div\n      {...props}\n      className={className}\n      inert={placing}\n      aria-disabled={placing || undefined}\n      data-fs-payment-method-list=\"\"\n      data-fs-payment-method-list-state={methodListState({ loading, count: methods.length })}\n      {...(placing ? { 'data-fs-payment-method-list-placing': '' } : {})}\n    >\n      {selectionError ? (\n        <div role=\"alert\" data-fs-payment-method-list-error=\"\">\n          {selectionError}\n        </div>\n      ) : null}\n      {methods.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-payment-method-list-fieldset=\"\">\n          <Fieldset.Legend>{resolveAuthoredCopy(legend, 'Payment method')}</Fieldset.Legend>\n          <RadioGroup\n            value={cardControlChecked ? CARD_CONTROL_VALUE : (selectedMethodId ?? '')}\n            onValueChange={handleValueChange}\n          >\n            {collapsedCardMethods.length > 0 ? (\n              // One control for every in-scope credit and debit method (FR-1, Decision 1). Both\n              // styling hooks stay exactly where a per-network row carried them — `payment.md`'s\n              // styling table documents them, so a store's swatch keeps its selectors.\n              <RadioRoot value={CARD_CONTROL_VALUE}>\n                <RadioIndicator data-fs-payment-method-indicator=\"\" />\n                <span data-fs-payment-method-name=\"\">\n                  {resolveAuthoredCopy(cardLabel, 'Pay with Credit / Debit Card')}\n                </span>\n              </RadioRoot>\n            ) : null}\n            {standaloneMethods.map((method) => (\n              <RadioRoot key={method.id} value={method.id}>\n                <RadioIndicator data-fs-payment-method-indicator=\"\" />\n                <span data-fs-payment-method-name=\"\">{method.name}</span>\n              </RadioRoot>\n            ))}\n          </RadioGroup>\n        </Fieldset.Root>\n      ) : null}\n    </div>\n  );\n}\n"],"mappings":"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"}
+{"version":3,"file":"payment.js","names":[],"sources":["../../../src/matter/payment/payment.tsx"],"sourcesContent":["'use client';\n\nimport { defineComponent } from '@vtex/fs-core';\nimport { type ComponentPropsWithRef, createContext, useContext, useId, useLayoutEffect, useMemo } 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 { useDataOverride } from '../../sdk/data/data-override-context.js';\nimport { PaymentSubmissionProvider } from '../../sdk/payment/submission-registry.js';\nimport { resolveAuthoredCopy } from '../../utils/resolve-authored-copy.js';\nimport { PaymentCardCaptureProvider, type PaymentCartData } from './payment-card-capture.js';\nimport {\n  type PaymentMethodSelection,\n  type PaymentSectionData,\n  resolveCanRevealCardPayment,\n  resolvePreselectionCandidateId,\n  splitCardMethods,\n  usePaymentMethodSelection,\n} from './use-payment-method-selection.js';\n\n/**\n * The `PaymentSection` matter root (specs/payment-section-root.md, T5 of the Credit Card epic;\n * docs/features/credit-card/rfc.md § D1). `PaymentSectionRoot` is the always-visible presentation\n * variant over the `Payment` entity T1 projects: it owns a thin `fragment` (the method list with its\n * server-driven validator config, plus the current selection), runs the shared\n * `usePaymentMethodSelection` engine, and provides the `payment` context its leaves read — the card\n * entry (T7), cardholder document (T8), installments (T9), save-card (T10), billing address (T11),\n * saved cards (T12), and place-order CTA (T14) — through the guarded `usePayment()` hook rather than\n * drilled props (ADR-0009). `PaymentSectionController` (payment-controller.tsx) is the second provider\n * of the same context for a collapsed overlay surface; ADR-0009 matches by contract identifier, so the\n * two substitute for one another with zero edits to any consumer.\n *\n * \"Thin\" means no `installmentOptions` (T9's own fragment), no `savedCards` (T12's), and no\n * `selectedInstallment` (T6's) — the heavy, optional, and iterated subtrees ADR-0011/ADR-0012 split out.\n * `methods[].validator` *is* selected here: it is a non-normalized value object off `Payment.methods`\n * that cannot be subscribed separately, and T7 tests every method's `numberRegex` to detect a network.\n *\n * `children` is the section composition, not a per-method template — the method picker is\n * `PaymentMethodList`, an independently placeable part with its own hooks.\n */\n\n// ---------------------------------------------------------------------------\n// GraphQL Fragment — raw template literal, matching the merged `payment-summary` sibling. The codegen\n// `documents` glob does not scan `src/matter/payment*`, so the typed `graphql()` factory is\n// unavailable here; `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 the\n// `Payment` entity that `paymentMethodSelect` echoes back to update the same cache entity this\n// fragment reads. `fetchStrategy: 'reactive'`'s no-refetch guarantee holds only if both sides\n// normalize to one entity.\n// ---------------------------------------------------------------------------\n\nconst fragment = /* GraphQL */ `\n  fragment PaymentSectionData on Query {\n    payment {\n      __typename\n      id\n      methods {\n        __typename\n        id\n        name\n        groupName\n        validator {\n          __typename\n          numberMask\n          numberRegex\n          cvvMask\n          cvvRegex\n          cvvRequired\n          expirationRequired\n          holderNameRequired\n          billingAddressRequired\n          documentDisplayable\n          documentRequired\n        }\n      }\n      selectedMethodId\n      selectedAccountId\n      selectedBin\n    }\n    cart {\n      __typename\n      id\n      total {\n        __typename\n        amount\n        currencyCode\n      }\n    }\n  }\n`;\n\n/**\n * The default payment-group scope: credit and debit (T140, FR-2, Decision 2). Both strings are\n * store-configured, so a store whose groups differ must set `group` explicitly; `group: ''` scopes\n * nothing (specs/payment-section-root.md § Documentation Gaps item 1). Widened from a single string to\n * a set (Decision 1) — a public API break for any consumer importing it directly (Interfaces).\n */\n/**\n * The roots' keyed `$data` (ADR-0015, arity 2): the `Payment` slice the selection engine reads, and the\n * cart total `add_payment_info` needs (moved here from `CardEntry`, which reads no cart).\n */\nexport type PaymentSectionRootData = {\n  payment?: PaymentSectionData;\n  cart?: PaymentCartData;\n} | null;\n\nexport const DEFAULT_METHOD_GROUP: readonly string[] = ['creditCardPaymentGroup', 'debitCardPaymentGroup'];\n\n// ---------------------------------------------------------------------------\n// Payment context — provided by both section roots, read by every leaf\n// ---------------------------------------------------------------------------\n\n/**\n * The `payment` context contract, normative for T7–T12 and T14. Everything the selection engine\n * resolves, plus the overlay disclosure. What is deliberately absent is part of the contract too: no\n * card number, CVV, expiration, or holder name (RFC D13 — they live only in the card entry's local\n * state); no submission channel for the place-order sequence, which is the separate, narrow\n * `PaymentSubmissionProvider` below (T13) precisely so no card-shaped value ever joins this contract;\n * no `installmentOptions` / `savedCards` / `selectedInstallment` (their owners' fragments); and no\n * optimistic mirror of the persisted selection.\n */\nexport type PaymentContextValue = Readonly<\n  PaymentMethodSelection & {\n    /** The collapsed surface's disclosure state. Always `true` under `PaymentSectionRoot`. */\n    open: boolean;\n    /**\n     * Drives the collapsed surface. A no-op under `PaymentSectionRoot`, so a leaf written for the\n     * overlay composes unchanged inline. Selecting a method never closes the surface on its own — the\n     * shopper still has a card to type — so closing is the composition's call (Decision 5).\n     */\n    setOpen: (open: boolean) => void;\n  }\n>;\n\nconst PAYMENT_CONTEXT_UNSET = Symbol('PaymentContextUnset');\n\nconst PaymentContextInternal = createContext<PaymentContextValue | typeof PAYMENT_CONTEXT_UNSET>(PAYMENT_CONTEXT_UNSET);\n\n/** The provider both section roots render. Exported for `PaymentSectionController`. */\nexport const PaymentContext = PaymentContextInternal as React.Context<PaymentContextValue>;\n\n/**\n * Read the payment section's selection state, draft, and overlay disclosure from the nearest\n * `PaymentSectionRoot` or `PaymentSectionController`. Throws outside either subtree — a misplaced\n * consumer is a composition bug the author should see immediately, not a silent degrade to an empty\n * selection — mirroring `useSession()` / `useDeliveryOptions()`. ADR-0009's compiler check catches the\n * same mistake before emission for schema-authored pages; this is the defense-in-depth layer for\n * Storybook, tests, and hand-written JSX.\n */\nexport function usePayment(): PaymentContextValue {\n  const ctx = useContext(PaymentContextInternal);\n  if (ctx === PAYMENT_CONTEXT_UNSET) {\n    throw new Error('usePayment() must be used inside a <PaymentSectionRoot> or <PaymentSectionController> subtree.');\n  }\n  return ctx;\n}\n\nconst NO_DISCLOSURE = () => {};\n\n// ---------------------------------------------------------------------------\n// Props\n// ---------------------------------------------------------------------------\n\nexport type PaymentSectionRootProps = ComponentPropsWithRef<'div'> & {\n  /**\n   * Scopes the method list to a **set** of `PaymentMethod.groupName` values — a method is in scope\n   * when its `groupName` is a member (T140, FR-1, Decision 1). A single string is still accepted and\n   * scopes to exactly that one group (FR-4, US-3). T1's read model is method-agnostic and assigns the\n   * narrowing to the consumer; this prop supplies no method, label, or ordering — the list itself is\n   * fragment data. An empty string scopes nothing.\n   */\n  group?: string | readonly string[];\n  /** Keyed `{ payment, cart }` forwarded by the reactive runtime (arity-2 fragment, ADR-0015). */\n  $data?: PaymentSectionRootData;\n  /** Compiler-injected action surface; carries `payment.setMethod`, `payment.sendPayments`, and `analytics.track`. */\n  $actions?: ComponentActions;\n};\n\n/** Renders its own controls from the context's method list — `children` would have nothing to template. */\nexport type PaymentMethodListProps = Omit<ComponentPropsWithRef<'div'>, 'children'> & {\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  /**\n   * The single card control's name (T171, Decision 8). The control stands for every in-scope\n   * credit/debit method at once, so it cannot take its name from one of their `method.name` values the\n   * way a per-network row did — it is authored copy instead, defaulting to the PRD's own string.\n   * Resolved through `resolveAuthoredCopy` exactly as `legend` is, so an authored empty or\n   * whitespace-only string falls back rather than rendering a nameless control.\n   */\n  cardLabel?: string;\n};\n\n// ---------------------------------------------------------------------------\n// Definitions\n// ---------------------------------------------------------------------------\n\nexport const PaymentSectionRootDefinition = defineComponent<PaymentSectionRootProps>({\n  name: 'PaymentSectionRoot',\n  importPath: '@vtex/faststore/components',\n  component: PaymentSectionRoot,\n  fragment,\n  fetchStrategy: 'reactive',\n  actions: { payment: ['setMethod', 'sendPayments'], analytics: ['track'] },\n  providesContext: ['payment', 'card-capture'],\n  hardened: true,\n  editor: { label: 'Payment Section', category: 'commerce' },\n  schema: {\n    // A literal, not `DEFAULT_METHOD_GROUP`: the native catalog builder extracts `schema` statically\n    // and silently drops an identifier-valued default, so the built entry would carry no default and\n    // the compiler would emit the section unscoped. `payment.test.tsx` asserts the literal matches the\n    // constant, and that the built catalog kept the default.\n    // T140, Decision 2/OQ-6: `type: 'array'` — no code path in packages/sukima/crates/sukima-core/\n    // validates an authored prop's JSON value against this declared type, so a store's existing bare\n    // string keeps compiling. No `items`: an enum would validate against a closed set of group names,\n    // which is wrong for a store that renamed its group (OQ-3) — the exact fragility Decision 1 closes.\n    group: {\n      type: 'array',\n      default: ['creditCardPaymentGroup', 'debitCardPaymentGroup'],\n      label: 'Payment method group',\n    },\n  },\n  guideline:\n    \"Root of the checkout payment section: reads the payment methods and the current selection from the order form and provides the 'payment' context every payment leaf needs and the 'card-capture' context CardEntry needs, so place CardEntry, CardholderDocument, Installments, SaveCard, BillingAddress, SavedCards, PlaceOrder, and PaymentMethodList as its children — none of them render without a payment root ancestor. Renders one container div and no chrome or copy of its own; headings and layout belong to the composition. Selecting a payment option dispatches $actions.payment.setMethod and every subscriber re-renders from the cache with no refetch — and for a card it is the number the shopper types that decides the network, not an option they pick, so PaymentMethodList shows every in-scope credit and debit method as ONE card option. Which methods exist is always real data — never author them as props; group only scopes the list by the store's payment group(s) — defaults to credit and debit together, accepts one group name or a set of them, and set it to \\\"\\\" to show every method, one option each, with no card option. Use PaymentSectionController instead when the section should live in a drawer or modal. See payment.md.\",\n});\n\nexport const PaymentMethodListDefinition = defineComponent<PaymentMethodListProps>({\n  name: 'PaymentMethodList',\n  importPath: '@vtex/faststore/components',\n  component: PaymentMethodList,\n  requiresContext: 'payment',\n  editor: { label: 'Payment Method List', category: 'commerce' },\n  schema: {\n    // T38/T171: inline literals, never identifiers — the native catalog builder extracts `schema`\n    // statically and silently drops an identifier-valued default (INV-8).\n    legend: { type: 'string', default: 'Payment method', label: 'Legend' },\n    cardLabel: { type: 'string', default: 'Pay with Credit / Debit Card', label: 'Card option label' },\n  },\n  guideline:\n    'The payment-method picker: a radio group of the payment options the order form offers, plus the inline selection error (role=\"alert\"). Every in-scope credit and debit method is ONE option — the network comes from the card number the shopper types, never from a row they pick — and any other in-scope method (e.g. Pix) keeps a row of its own; set group to \"\" on the root to switch that off and get one row per method. Selecting an option dispatches the method selection. Selecting a non-card option hides the card form, and the card option brings it back. Place it inside a PaymentSectionRoot, or inside the DialogPopup/DrawerPopup of a PaymentSectionController. It renders its own options from real data, so it takes no children and no method props; author the card option\\'s wording with cardLabel. Keep it composed: it is the only element that surfaces a rejected selection, and the only control that can recover a selection this section does not serve — omit it and a shopper whose persisted method sits outside group has no reachable way back. Must be inside a payment root.',\n});\n\n// ---------------------------------------------------------------------------\n// Implementations\n// ---------------------------------------------------------------------------\n\nexport function PaymentSectionRoot({\n  group = DEFAULT_METHOD_GROUP,\n  $data: $dataProp,\n  $actions: $actionsProp,\n  className,\n  children,\n  ...props\n}: PaymentSectionRootProps) {\n  const $data = useDataOverride($dataProp);\n  const $actions = useActionsOverride($actionsProp);\n  const selection = usePaymentMethodSelection({ group, $data: $data?.payment ?? null, $actions });\n  const payment = useMemo<PaymentContextValue>(\n    () => ({ ...selection, open: true, setOpen: NO_DISCLOSURE }),\n    [selection],\n  );\n\n  return (\n    <PaymentContextInternal value={payment}>\n      <PaymentSubmissionProvider path={selection.draft.path}>\n        <PaymentCardCaptureProvider selection={selection} cart={$data?.cart} $actions={$actions}>\n          <div\n            {...props}\n            className={className}\n            data-fs-payment-section=\"\"\n            {...(selection.draft.path ? { 'data-fs-payment-section-path': selection.draft.path } : {})}\n            // T28, Decision 5: presence attribute only, deliberately never `inert` — `PlaceOrder` composes\n            // as a child of this same container (FR-6), so making it inert here would swallow the CTA's\n            // own role=\"alert\"/role=\"status\" regions, the shopper's only channel for the outcome.\n            {...(selection.placing ? { 'data-fs-payment-section-placing': '' } : {})}\n          >\n            {children}\n          </div>\n        </PaymentCardCaptureProvider>\n      </PaymentSubmissionProvider>\n    </PaymentContextInternal>\n  );\n}\n\n/**\n * The picker's presence state, always emitted so a swatch can surface a row-less container — otherwise\n * a zero-height element under any stacking swatch, and the \"visible empty region\" the section's\n * group-default risk is accepted on. `loading` (still resolving) and `empty` (resolved, nothing in\n * scope) stay distinct: one is a wait, the other a misconfiguration.\n */\nfunction methodListState({ loading, count }: { loading: boolean; count: number }): 'loading' | 'empty' | 'ready' {\n  if (loading) return 'loading';\n  if (count === 0) return 'empty';\n  return 'ready';\n}\n\n/**\n * The DOM value the collapsed card control carries inside the `RadioGroup`. Base UI requires every\n * radio root to have one, and this control stands for N methods, so there is no `method.id` it could\n * use.\n *\n * It is a radio-group value and nothing else — **never a method id** (INV-1, ADR-0023). It is never\n * dispatched: `handleValueChange` below maps it back to `resolvePreselectionCandidateId`'s answer\n * before calling `selectMethod`, and records card mode through `selectNewCard()`, which dispatches\n * nothing, when there is no candidate (T191, FR-6). The prefix keeps it from ever colliding with a\n * `PaymentMethod.id` a standalone row is bound to.\n */\nconst CARD_CONTROL_VALUE = '__fs-card-control';\n\nexport function PaymentMethodList({ legend, cardLabel, className, ...props }: PaymentMethodListProps) {\n  const {\n    methods,\n    allMethods,\n    persistedMethodId,\n    selectedMethodId,\n    selectionError,\n    selectMethod,\n    selectNewCard,\n    cardModeActive,\n    loading,\n    placing,\n    setMethodListMounted,\n  } = usePayment();\n\n  // T171, FR-1/FR-2: one control for the in-scope card methods, one row for every other in-scope\n  // method. Memoized off the two lists only (NFR-5) — nothing here may widen what re-creates the\n  // `payment` context value, which a keystroke already churns enough.\n  const { collapsedCardMethods, standaloneMethods } = useMemo(\n    () => splitCardMethods({ methods, allMethods }),\n    [methods, allMethods],\n  );\n  // Decision 3: the collapsed control dispatches the *shared* preselection candidate, so the escape\n  // hatch and the preselection can never disagree about whether an id is available.\n  const cardCandidateId = useMemo(() => resolvePreselectionCandidateId(methods), [methods]);\n  const canRevealCardPayment = resolveCanRevealCardPayment({ collapsedCardMethods, standaloneMethods });\n\n  // Decision 2: derived, never bound to one `method.id` — a control standing for N methods has none.\n  // Checked when the persisted selection resolves inside the collapsed set, and when nothing is\n  // persisted at all (PRD REQ-02's \"the card payment option is selected by default\"). The second arm\n  // is a deliberate divergence from the pre-T171 bound-to-`$data` behaviour: the control can read\n  // checked while `$data.selectedMethodId` is still null, having dispatched nothing. `persistedMethodId`\n  // is the raw, unscoped fact on purpose — a persisted method this section does not serve must leave the\n  // control unchecked, which is what keeps it activatable as US-5's way back. T191 (FR-6): card mode is\n  // the third arm, the card option chosen over such a selection or over a non-card one.\n  const cardControlChecked =\n    collapsedCardMethods.length > 0 &&\n    (persistedMethodId === null ||\n      collapsedCardMethods.some((method) => method.id === selectedMethodId) ||\n      cardModeActive);\n\n  // Fix pass, finding R2: registers this instance with the shared engine so the card leaves know an\n  // escape hatch exists before they ever collapse — a section composed with no `PaymentMethodList` at\n  // all must never hide the only remaining way to change the method (typing a new card number).\n  // Retracted unconditionally on unmount, unlike `setPlacing`'s own \"leave it if still placing\"\n  // carve-out: there is no in-flight sequence here for an abandoned instance to still be part of.\n  //\n  // T191, Decision 5 (after T171's Decision 4): what is registered is `canRevealCardPayment`, not the\n  // bare fact of being mounted — whether this list can bring the card form back. A rendered card\n  // option always can, since card mode needs no method id; without one, only a row bound to a card\n  // method can. See `resolveCanRevealCardPayment`'s own doc comment. The dependency list carries it,\n  // so the registration re-runs when the method list resolves.\n  //\n  // Fix pass round 2 (flash regression): `useLayoutEffect`, not `useEffect` — mirroring\n  // `place-order.tsx`'s own `setPlacing` registration, the structurally identical precedent for\n  // publishing a ref-counted fact to this shared engine from a leaf's mount. A passive effect runs\n  // after the browser has already painted, so a root whose persisted selection is genuinely out of\n  // scope committed one real frame with `methodListMounted` still `false` — the collapse (then\n  // `selectionOutOfScope && methodListMounted`, now `cardPaymentCollapsed`) computed `false` for that\n  // frame, painting the card form visible, focusable, and with its security code not yet cleared,\n  // before the registration ever landed and a second commit hid it. A layout effect's own state update\n  // is guaranteed to flush synchronously before the browser paints, so the very first frame a shopper\n  // can ever see already reflects `methodListMounted`. The card leaves read it purely at render time,\n  // not from an effect of their own, so this reorders nothing on that side: whichever commit this\n  // layout effect's own update produces is the one their next render (still pre-paint) sees.\n  const instanceKey = useId();\n  useLayoutEffect(() => {\n    setMethodListMounted(instanceKey, canRevealCardPayment);\n    return () => setMethodListMounted(instanceKey, false);\n  }, [instanceKey, setMethodListMounted, canRevealCardPayment]);\n\n  // INV-1: only an id the read model supplied is ever dispatched. A standalone row's value *is* its own\n  // `method.id`; the collapsed control's value is a DOM value with no method behind it, so it routes\n  // through the shared candidate instead (FR-4). With no candidate to name it records card mode, which\n  // brings the card form back and sends nothing (T191, FR-6, Decision 6).\n  function handleValueChange(value: string) {\n    if (value === CARD_CONTROL_VALUE) {\n      if (cardCandidateId !== null) {\n        selectMethod({ methodId: cardCandidateId });\n      } else {\n        selectNewCard();\n      }\n      return;\n    }\n    selectMethod({ methodId: value });\n  }\n\n  return (\n    <div\n      {...props}\n      className={className}\n      inert={placing}\n      aria-disabled={placing || undefined}\n      data-fs-payment-method-list=\"\"\n      data-fs-payment-method-list-state={methodListState({ loading, count: methods.length })}\n      {...(placing ? { 'data-fs-payment-method-list-placing': '' } : {})}\n    >\n      {selectionError ? (\n        <div role=\"alert\" data-fs-payment-method-list-error=\"\">\n          {selectionError}\n        </div>\n      ) : null}\n      {methods.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-payment-method-list-fieldset=\"\">\n          <Fieldset.Legend>{resolveAuthoredCopy(legend, 'Payment method')}</Fieldset.Legend>\n          <RadioGroup\n            value={cardControlChecked ? CARD_CONTROL_VALUE : (selectedMethodId ?? '')}\n            onValueChange={handleValueChange}\n          >\n            {collapsedCardMethods.length > 0 ? (\n              // One control for every in-scope credit and debit method (FR-1, Decision 1). Both\n              // styling hooks stay exactly where a per-network row carried them — `payment.md`'s\n              // styling table documents them, so a store's swatch keeps its selectors.\n              <RadioRoot value={CARD_CONTROL_VALUE}>\n                <RadioIndicator data-fs-payment-method-indicator=\"\" />\n                <span data-fs-payment-method-name=\"\">\n                  {resolveAuthoredCopy(cardLabel, 'Pay with Credit / Debit Card')}\n                </span>\n              </RadioRoot>\n            ) : null}\n            {standaloneMethods.map((method) => (\n              <RadioRoot key={method.id} value={method.id}>\n                <RadioIndicator data-fs-payment-method-indicator=\"\" />\n                <span data-fs-payment-method-name=\"\">{method.name}</span>\n              </RadioRoot>\n            ))}\n          </RadioGroup>\n        </Fieldset.Root>\n      ) : null}\n    </div>\n  );\n}\n"],"mappings":"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"}

package/dist/matter/product-shelf/product-shelf.d.ts

@@ -1,8 +1,51 @@
+import { ContentValue } from "../../core/dist/define-content-type.js";
 import { ComponentDefinition } from "../../core/dist/define-component.js";
 import "../../core/dist/index.js";
 import { ProductListItem } from "../product-list/product-list.js";
 import { ComponentPropsWithRef } from "react";
 //#region src/matter/product-shelf/product-shelf.d.ts
+export declare const ProductShelfContent: {
+  readonly id: "product-shelf";
+  readonly title: "Product Shelf";
+  readonly description: "Which products a shelf shows: how many, in which order, and from which facet.";
+  readonly schema: {
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly properties: {
+      readonly first: {
+        readonly type: "integer";
+        readonly title: "Number of products";
+        readonly minimum: 1;
+        readonly maximum: 100;
+      };
+      readonly sort: {
+        readonly type: "string";
+        readonly enum: readonly ["relevance", "price_asc", "price_desc", "name_asc", "name_desc", "release", "orders", "discount"];
+        readonly title: "Sort";
+      };
+      readonly categoryId: {
+        readonly type: "string";
+        readonly title: "Category ID";
+      };
+      readonly brandId: {
+        readonly type: "string";
+        readonly title: "Brand ID";
+      };
+      readonly collectionId: {
+        readonly type: "string";
+        readonly title: "Collection ID";
+      };
+      readonly searchTerm: {
+        readonly type: "string";
+        readonly title: "Search term";
+      };
+      readonly availableOnly: {
+        readonly type: "boolean";
+        readonly title: "Available only";
+      };
+    };
+  };
+};
 type RawMoney = {
   amount: number;
   currencyCode: string;
@@ -54,62 +97,49 @@ export type ProductShelfItem = ProductListItem;
 export type ProductShelfSort = 'relevance' | 'price_asc' | 'price_desc' | 'name_asc' | 'name_desc' | 'release' | 'orders' | 'discount';
 export type ProductSortField = 'TITLE' | 'PRICE' | 'RELEASE_DATE' | 'RELEVANCE' | 'BEST_SELLING';
 export type SortDirection = 'ASC' | 'DESC';
-export type ProductsFilterInput = {
-  searchTerm?: string;
-  categoryIds?: string[];
-  brandIds?: string[];
-  collectionId?: string;
-  specifications?: Array<{
-    name: string;
-    values: string[];
-  }>;
-  availableOnly?: boolean;
-};
-export type ProductShelfVariables = {
-  first: number;
-  orderBy?: {
-    field: ProductSortField;
-    direction: SortDirection;
-  };
-  filter: ProductsFilterInput;
-};
+/**
+ * The query configuration the shelf resolved for this element: the content slice when the
+ * merchant filled a field, else the prop. The query has already applied these values; the
+ * context republishes them for parts that describe the shelf (a "sorted by" label, a facet link).
+ */
 export type ProductShelfConfig = {
-  first?: number;
-  itemsPerPage?: number;
-  sort?: ProductShelfSort;
+  first: number;
+  sort: ProductShelfSort;
   searchTerm?: string;
   categoryId?: string;
   brandId?: string;
   collectionId?: string;
-  specifications?: Array<{
-    name: string;
-    values: string[];
-  }>;
-  availableOnly?: boolean;
+  availableOnly: boolean;
 };
 export type ProductShelfContextValue = {
   itemsPerPage: number;
-  variables: ProductShelfVariables;
+  config: ProductShelfConfig;
   count: number;
 };
-export type ProductShelfRootProps = ComponentPropsWithRef<'section'> & ProductShelfConfig & {
+export type ProductShelfRootProps = ComponentPropsWithRef<'section'> & Partial<ProductShelfConfig> & {
+  itemsPerPage?: number;
   /** When true, card prices render tax-inclusive (from each item's tax data). Default false. */
   usePriceWithTaxes?: boolean;
   /** Text for the tax label part when tax display is on. Default `'Tax included'`. */
   taxesLabel?: string;
   products?: ProductShelfItem[];
+  /** Injected by the compiler, sliced from the page's or layout's composite content entry. */
+  $content?: ContentValue<typeof ProductShelfContent>;
   $data?: ProductShelfData | null;
 };
 export type ProductShelfItemsProps = ComponentPropsWithRef<'div'>;
 export type ProductShelfHeadingProps = ComponentPropsWithRef<'h2'>;
 export declare function useProductShelf(): ProductShelfContextValue;
 export declare function useProductShelfItem(): ProductShelfItem;
-export declare function buildProductShelfVariables(config: ProductShelfConfig): ProductShelfVariables;
+export declare const PRODUCT_SHELF_SORT_MAP: Record<ProductShelfSort, {
+  field: ProductSortField;
+  direction: SortDirection;
+}>;
 export declare function transformProducts(data: ProductShelfData): ProductShelfItem[];
 export declare const ProductShelfRootDefinition: ComponentDefinition<ProductShelfRootProps>;
 export declare const ProductShelfItemsDefinition: ComponentDefinition<import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>>;
 export declare const ProductShelfHeadingDefinition: ComponentDefinition<import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLHeadingElement>, HTMLHeadingElement>>;
-export declare function ProductShelfRoot({ first, itemsPerPage, sort, searchTerm, categoryId, brandId, collectionId, specifications, availableOnly, usePriceWithTaxes, taxesLabel, products, $data: $dataProp, className, children, ...props }: ProductShelfRootProps): import("react/jsx-runtime").JSX.Element | null;
+export declare function ProductShelfRoot({ first, itemsPerPage, sort, searchTerm, categoryId, brandId, collectionId, availableOnly, usePriceWithTaxes, taxesLabel, products, $content, $data: $dataProp, className, children, ...props }: ProductShelfRootProps): import("react/jsx-runtime").JSX.Element | null;
 export declare namespace ProductShelfRoot {
   var Skeleton: typeof ProductShelfSkeleton;
 }

package/dist/matter/product-shelf/product-shelf.js

@@ -1,16 +1,79 @@
 "use client";
 import { defineComponent } from "../../core/dist/define-component.js";
+import { defineContentType } from "../../core/dist/define-content-type.js";
 import "../../core/dist/index.js";
 import { useDataOverride } from "../../sdk/data/data-override-context.js";
 import { Text } from "../../particles/text/text.js";
 import { ProductListConfigContext, ProductListItemContext } from "../product-list/product-list.js";
 import { CarouselTrack } from "../../particles/carousel/carousel.js";
+import { isEmptyContentValue } from "../../sdk/data/empty-content-value.js";
 import { createContext, useCallback, useContext, useEffect, useId, useMemo, useState } from "react";
 import { jsx, jsxs } from "react/jsx-runtime";
 //#region src/matter/product-shelf/product-shelf.tsx
+const ProductShelfContent = defineContentType({
+	id: "product-shelf",
+	title: "Product Shelf",
+	description: "Which products a shelf shows: how many, in which order, and from which facet.",
+	schema: {
+		type: "object",
+		additionalProperties: false,
+		properties: {
+			first: {
+				type: "integer",
+				title: "Number of products",
+				minimum: 1,
+				maximum: 100
+			},
+			sort: {
+				type: "string",
+				enum: [
+					"relevance",
+					"price_asc",
+					"price_desc",
+					"name_asc",
+					"name_desc",
+					"release",
+					"orders",
+					"discount"
+				],
+				title: "Sort"
+			},
+			categoryId: {
+				type: "string",
+				title: "Category ID"
+			},
+			brandId: {
+				type: "string",
+				title: "Brand ID"
+			},
+			collectionId: {
+				type: "string",
+				title: "Collection ID"
+			},
+			searchTerm: {
+				type: "string",
+				title: "Search term"
+			},
+			availableOnly: {
+				type: "boolean",
+				title: "Available only"
+			}
+		}
+	}
+});
 const fragment = `
   fragment ProductShelfData on Query {
-    products(first: 12, orderBy: { field: RELEVANCE, direction: DESC }) {
+    products(
+      first: $first
+      orderBy: $orderBy
+      filter: {
+        categoryIds: $categoryId
+        brandIds: $brandId
+        collectionId: $collectionId
+        searchTerm: $searchTerm
+        availableOnly: $availableOnly
+      }
+    ) {
       edges {
         node {
           id
@@ -88,7 +151,7 @@ function useProductShelfItem() {
 	if (!item) throw new Error("Product card components must be used inside ProductShelfItems.");
 	return item;
 }
-const SORT_MAP = {
+const PRODUCT_SHELF_SORT_MAP = {
 	relevance: {
 		field: "RELEVANCE",
 		direction: "DESC"
@@ -122,21 +185,6 @@ const SORT_MAP = {
 		direction: "DESC"
 	}
 };
-function buildProductShelfVariables(config) {
-	const { first = 5, sort = "relevance", searchTerm, categoryId, brandId, collectionId, specifications, availableOnly } = config;
-	const filter = {};
-	if (searchTerm) filter.searchTerm = searchTerm;
-	if (categoryId) filter.categoryIds = [categoryId];
-	if (brandId) filter.brandIds = [brandId];
-	if (collectionId) filter.collectionId = collectionId;
-	if (specifications && specifications.length > 0) filter.specifications = specifications;
-	if (availableOnly) filter.availableOnly = true;
-	return {
-		first,
-		orderBy: SORT_MAP[sort],
-		filter
-	};
-}
 function transformProducts(data) {
 	return data.edges.map(({ node }) => {
 		const image = node.images.edges[0]?.node;
@@ -175,21 +223,69 @@ const ProductShelfRootDefinition = defineComponent({
 	fragment,
 	fetchStrategy: "lazy",
 	skeleton: ProductShelfSkeleton,
+	content: ProductShelfContent,
+	variables: { orderBy: {
+		from: "sort",
+		values: {
+			relevance: {
+				field: "RELEVANCE",
+				direction: "DESC"
+			},
+			price_asc: {
+				field: "PRICE",
+				direction: "ASC"
+			},
+			price_desc: {
+				field: "PRICE",
+				direction: "DESC"
+			},
+			name_asc: {
+				field: "TITLE",
+				direction: "ASC"
+			},
+			name_desc: {
+				field: "TITLE",
+				direction: "DESC"
+			},
+			release: {
+				field: "RELEASE_DATE",
+				direction: "DESC"
+			},
+			orders: {
+				field: "BEST_SELLING",
+				direction: "DESC"
+			},
+			discount: {
+				field: "RELEVANCE",
+				direction: "DESC"
+			}
+		}
+	} },
 	editor: {
 		label: "Product Shelf Root",
 		category: "commerce"
 	},
 	providesContext: "product-shelf",
 	schema: {
-		first: {
+		itemsPerPage: {
 			type: "number",
 			default: 5,
-			label: "Number of Products"
+			label: "Items Per Page"
 		},
-		itemsPerPage: {
+		usePriceWithTaxes: {
+			type: "boolean",
+			default: false,
+			label: "Use Price With Taxes"
+		},
+		taxesLabel: {
+			type: "string",
+			default: "Tax included",
+			label: "Taxes Label"
+		},
+		first: {
 			type: "number",
 			default: 5,
-			label: "Items Per Page"
+			label: "Number of Products"
 		},
 		sort: {
 			type: [
@@ -221,27 +317,13 @@ const ProductShelfRootDefinition = defineComponent({
 			type: "string",
 			label: "Collection ID"
 		},
-		specifications: {
-			type: "array",
-			label: "Specification Filters"
-		},
 		availableOnly: {
 			type: "boolean",
 			default: false,
 			label: "Available Only"
-		},
-		usePriceWithTaxes: {
-			type: "boolean",
-			default: false,
-			label: "Use Price With Taxes"
-		},
-		taxesLabel: {
-			type: "string",
-			default: "Tax included",
-			label: "Taxes Label"
 		}
 	},
-	guideline: "Data-owning root of a facet-sourced product shelf. Owns a products(filter:) fragment and receives $data lazily. Compose as: ProductShelfRoot > (ProductShelfHeading + CarouselRoot > (ProductShelfItems + CarouselPrevious + CarouselNext + CarouselBullets)). Compose ProductShelfHeading with the title as its children to render a heading; set the source with categoryId / brandId / collectionId / searchTerm / specifications and tune first, sort, availableOnly. Renders a skeleton while loading and nothing when the result is empty. Bind itemsPerPage to the CarouselRoot so paging matches the shelf config. See product-shelf.md."
+	guideline: "Data-owning root of a facet-sourced product shelf. Owns a products(first:, orderBy:, filter:) fragment whose variables bind to this element: the merchant fills them in the CMS (content model product-shelf) and the props of the same name are the defaults. Receives $data lazily. Compose as: ProductShelfRoot > (ProductShelfHeading + CarouselRoot > (ProductShelfItems + CarouselPrevious + CarouselNext + CarouselBullets)). Compose ProductShelfHeading with the title as its children to render a heading; set the source with categoryId / brandId / collectionId / searchTerm and tune first, sort, availableOnly. Renders a skeleton while loading and nothing when the result is empty. Bind itemsPerPage to the CarouselRoot so paging matches the shelf config. See product-shelf.md."
 });
 const ProductShelfItemsDefinition = defineComponent({
 	name: "ProductShelfItems",
@@ -267,8 +349,31 @@ const ProductShelfHeadingDefinition = defineComponent({
 	schema: {},
 	guideline: "Renders its children as the shelf title (an <h2>) and provides the section's accessible label. Author the title text as its children (props.children). Place it inside ProductShelfRoot where the title should sit — usually above CarouselRoot. Renders nothing when it has no children."
 });
-function ProductShelfRoot({ first = 5, itemsPerPage = 5, sort = "relevance", searchTerm, categoryId, brandId, collectionId, specifications, availableOnly = false, usePriceWithTaxes = false, taxesLabel = "Tax included", products, $data: $dataProp, className, children, ...props }) {
+/** The content value when the merchant filled the field, else the prop (the shared emptiness rule). */
+function contentOrProp(content, prop) {
+	if (content === void 0 || isEmptyContentValue(content)) return prop;
+	return content;
+}
+function ProductShelfRoot({ first = 5, itemsPerPage = 5, sort = "relevance", searchTerm, categoryId, brandId, collectionId, availableOnly = false, usePriceWithTaxes = false, taxesLabel = "Tax included", products, $content, $data: $dataProp, className, children, ...props }) {
 	const $data = useDataOverride($dataProp);
+	const shelfConfig = useMemo(() => ({
+		first: contentOrProp($content?.first, first),
+		sort: contentOrProp($content?.sort, sort),
+		searchTerm: contentOrProp($content?.searchTerm, searchTerm),
+		categoryId: contentOrProp($content?.categoryId, categoryId),
+		brandId: contentOrProp($content?.brandId, brandId),
+		collectionId: contentOrProp($content?.collectionId, collectionId),
+		availableOnly: contentOrProp($content?.availableOnly, availableOnly)
+	}), [
+		$content,
+		first,
+		sort,
+		searchTerm,
+		categoryId,
+		brandId,
+		collectionId,
+		availableOnly
+	]);
 	const headingId = useId();
 	const [headingCount, setHeadingCount] = useState(0);
 	const registerHeading = useCallback(() => {
@@ -283,27 +388,22 @@ function ProductShelfRoot({ first = 5, itemsPerPage = 5, sort = "relevance", sea
 		usePriceWithTaxes,
 		taxesLabel
 	}), [usePriceWithTaxes, taxesLabel]);
-	const hasHeading = headingCount > 0;
-	let items;
-	if (products !== void 0) items = products;
-	else if ($data === void 0) return /* @__PURE__ */ jsx(ProductShelfSkeleton, { className });
-	else items = $data ? transformProducts($data) : [];
-	items = items.slice(0, first);
-	if (items.length === 0) return null;
-	const shelf = {
+	const items = useMemo(() => {
+		if (products !== void 0) return products;
+		return $data ? transformProducts($data) : [];
+	}, [products, $data]);
+	const shelf = useMemo(() => ({
 		itemsPerPage,
-		variables: buildProductShelfVariables({
-			first,
-			sort,
-			searchTerm,
-			categoryId,
-			brandId,
-			collectionId,
-			specifications,
-			availableOnly
-		}),
+		config: shelfConfig,
 		count: items.length
-	};
+	}), [
+		itemsPerPage,
+		shelfConfig,
+		items.length
+	]);
+	const hasHeading = headingCount > 0;
+	if (products === void 0 && $data === void 0) return /* @__PURE__ */ jsx(ProductShelfSkeleton, { className });
+	if (items.length === 0) return null;
 	return /* @__PURE__ */ jsx(ProductListConfigContext, {
 		value: config,
 		children: /* @__PURE__ */ jsx(ProductShelfProductsContext, {
@@ -373,6 +473,6 @@ const ProductShelf = {
 	Skeleton: ProductShelfSkeleton
 };
 //#endregion
-export { ProductShelf, ProductShelfHeading, ProductShelfHeadingDefinition, ProductShelfItems, ProductShelfItemsDefinition, ProductShelfRoot, ProductShelfRootDefinition, ProductShelfSkeleton, buildProductShelfVariables, transformProducts, useProductShelf, useProductShelfItem };
+export { PRODUCT_SHELF_SORT_MAP, ProductShelf, ProductShelfContent, ProductShelfHeading, ProductShelfHeadingDefinition, ProductShelfItems, ProductShelfItemsDefinition, ProductShelfRoot, ProductShelfRootDefinition, ProductShelfSkeleton, transformProducts, useProductShelf, useProductShelfItem };
 
 //# sourceMappingURL=product-shelf.js.map