@vtex/faststore 0.0.1

package/dist/docs/product-information.md

@@ -0,0 +1,295 @@
+# ProductInformation
+
+**Category:** commerce
+**Purpose:** Renders textual product information on a PDP — title, description, brand, SKU, and reference ID. Reads from the active product via GraphQL fragment.
+
+---
+
+## Visual cues (how to identify in an image)
+
+A ProductInformation block is present when you see:
+
+- The **product name / title** rendered as a heading.
+- A **brand name** near the title.
+- A **product description** — short or long paragraph(s) of text.
+- A **SKU or reference code** label (e.g. "Ref: 12345", "SKU: ABC-001").
+
+Each of these is a separate sub-component. Include only the ones visible in the image.
+
+---
+
+## When to use
+
+- PDP product information block — the canonical use.
+
+## When NOT to use
+
+- Product shelf / PLP cards — use a shelf-specific title component.
+- Cart item names — use `CartItemName`.
+- Static text unrelated to a product — use a plain layout text element.
+
+---
+
+## Composition
+
+`ProductInformationRoot` declares `providesContext: 'product-information'`. Every sub-component declares `requiresContext: 'product-information'`, so the schema compiler rejects any page where a `ProductInformation*` sub-component is not nested inside **any element whose component provides that context** (`ContextConstraintError` — fails the build before any file is emitted). The check is contract-based: a `B2BProductInformationRoot` (or any future variant) that declares the same `providesContext: 'product-information'` value substitutes for `ProductInformationRoot` with no edit to the consumers. Each sub-component also renders `null` when its data field is absent — include only what is visible in the image.
+
+Child order reflects visual order — place sub-components in the same sequence they appear in the image.
+
+```text
+<any element with providesContext: 'product-information'>   # ProductInformationRoot, B2BProductInformationRoot, …
+├── ProductInformationBrand        (renders only when brand or vendor is present)
+├── ProductInformationTitle        (always renders when data is available)
+├── ProductInformationDescription  (renders only when description exists)
+├── ProductInformationSku          (renders only when variants exist)
+└── ProductInformationReferenceId  (renders only when referenceId exists)
+```
+
+Any subset, any order. Intermediate containers (e.g. `Container`) between the provider and the sub-components are fine — the contract is "some ancestor provides it", not "the immediate parent provides it".
+
+---
+
+## Components
+
+### ProductInformationRoot
+
+Root container. Declares the GraphQL fragment and provides context to all descendants. Reads `$data` reactively through the data-override context — when a future SKU Selector writes a new selected variant into the cache, the Root recomposes its subtree without a refetch.
+
+No schema props — it is a pure data provider.
+
+**Data:** declares `fragment ProductInformationData on Query`. Fetches: `id`, `title`, `description`, `descriptionHtml`, `referenceId`, `vendor`, `brand.name`, the first variant's `id` / `sku` / `name`, and `seo.title`. `variant.name` powers `ProductInformationTitle`'s `separator` composition; `seo.title` is exposed on the context for the future page-level `<title>` resolver (no current sub-component reads it).
+
+---
+
+### ProductInformationTitle
+
+Renders the product title. Always renders when inside a Root with valid data.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `as` | `h1\|h2\|h3\|h4\|h5\|h6` | `h1` | HTML tag to render. Use `h1` on the PDP. Use `h2` or lower when embedded in a card or secondary context. Non-heading tags are rejected so the PDP keeps its heading hierarchy. |
+| `separator` | string | _unset_ | When set **and** a variant with a non-null `name` is selected, the rendered text composes as `${title}${separator}${variant.name}` — e.g. `Running Shoe - Red, Size 10`. Without `separator`, or when the variant has no name, the title renders alone. Leave unset on PDPs that have no SKU Selector. The merchant picks the visible delimiter (`" - "`, `" · "`, `" — "`, `"/"`, …). An empty string is a valid value — it concatenates without a delimiter. |
+
+Emits `data-fs-product-information-title-as={as}` (alongside the existing `data-fs-product-information-title=""` presence attribute) for per-heading-level styling — e.g. `data-[fs-product-information-title-as=h2]:text-xl` applies only to title instances rendered as `<h2>`.
+
+**Composition truth table** (only relevant when the page also wires a SKU Selector via the data layer):
+
+| `separator` | `variant.name` | Rendered text |
+|---|---|---|
+| _unset_ | any | `title` |
+| set | `null` or `""` | `title` |
+| set to `" - "` | `"Red, Size 10"` | `"title - Red, Size 10"` |
+| set to `""` | `"Red, Size 10"` | `"titleRed, Size 10"` |
+
+---
+
+### ProductInformationDescription
+
+Renders the product description, optionally collapsed behind a "show more" toggle.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `format` | `'auto' \| 'plain' \| 'html'` | `'auto'` | Selects which source to render. `'auto'` prefers `descriptionHtml` and falls back to plain `description`. `'plain'` renders only `description` and never reads HTML. `'html'` renders only `descriptionHtml` via `dangerouslySetInnerHTML` and is strict — it never falls back. Returns nothing when the selected source is absent. |
+| `collapse` | `'none' \| 'showMore' \| 'section'` | `'none'` | Selects the collapse pattern. `'none'` renders the full block with no toggle (today's behavior). `'showMore'` clamps the body to `collapsedLines` and reveals the rest with a trigger that flips the clamp. `'section'` collapses the whole panel behind one trigger; the body uses Base UI Collapsible with `hidden="until-found"` so the full text stays in the SSR DOM and remains indexable. |
+| `defaultExpanded` | boolean | `true` | Initial open state for the panel. Only consulted when `collapse !== 'none'`. SSR-safe. |
+| `collapsedLines` | number | `4` | Line count for the CSS clamp in `'showMore'` mode. Ignored for `'none'` and `'section'`. |
+| `moreLabel` | string | `'Show more'` | Trigger label shown when the panel is collapsed. Localize per storefront (e.g. `'mais informações'` for pt-BR). |
+| `lessLabel` | string | `'Show less'` | Trigger label shown when the panel is expanded (e.g. `'menos informações'`). |
+
+The wrapper element follows from the resolved branch: plain text renders as `<p>` (semantic body-text exposure for screen-reader paragraph navigation and SEO); rich HTML renders as `<div>` so block-level markup inside `descriptionHtml` (`<p>`, `<ul>`, headings) stays valid DOM. The element that hosts the rendered description text carries `data-fs-text=""` so project-level `Text` typography defined in `global.json` cascades to the description automatically — no need to repeat font, size, color, leading, or tracking classes inline on every description node. With `collapse: 'none'` that element is the wrapper itself; with `collapse: 'showMore'` or `'section'` it is the panel (the `Collapsible.Root` and the trigger `<button>` deliberately do not carry it so body typography does not cascade onto the trigger label).
+
+Rich HTML is rendered via `dangerouslySetInnerHTML`; Storefront API Core sanitizes `descriptionHtml` upstream, so this is safe for first-party catalogs.
+
+When `collapse !== 'none'` the component renders a Base UI Collapsible: the root carries `data-fs-product-information-description-collapse={collapse}`, the trigger carries `data-fs-product-information-description-trigger=""`, and the panel carries `data-fs-product-information-description-panel=""`. Use these attributes from Tailwind arbitrary-attribute variants to style trigger and panel without sniffing tags — e.g. `[&_[data-fs-product-information-description-trigger]]:text-blue-600`.
+
+The keyboard contract is owned by Base UI Collapsible: Enter / Space toggle the panel and `aria-expanded` flips. In `'showMore'`, the trigger always references the panel via `aria-controls`; in `'section'`, Base UI follows APG Disclosure behavior and omits `aria-controls` while collapsed. SSR keeps the full description text in the source HTML in every collapse state. For `'showMore'` the panel is a visible-but-clamped `<div>`, so the text is fully crawlable in the pre-hydration HTML. For `'section'` the panel ships with `hidden=""` server-side and is promoted to `hidden="until-found"` by Base UI's hydration effect, which lets JS-aware crawlers (including Google) reveal it via in-page find.
+
+---
+
+### ProductInformationBrand
+
+Renders the brand name. Prefers `brand.name`; falls back to `vendor`. Returns `null` when both are absent. No props.
+
+---
+
+### ProductInformationSku
+
+Renders the first-variant SKU code. Returns `null` when the product has no variants. No props.
+
+---
+
+### ProductInformationReferenceId
+
+Renders the merchant reference ID. Returns `null` when absent. No props.
+
+---
+
+## Canonical schema example
+
+A full PDP information block — brand, title, and description visible:
+
+```json
+{
+  "product-info": {
+    "type": "ProductInformationRoot",
+    "children": ["product-brand", "product-title", "product-description"]
+  },
+  "product-brand":       { "type": "ProductInformationBrand" },
+  "product-title":       { "type": "ProductInformationTitle", "props": { "as": "h1" } },
+  "product-description": { "type": "ProductInformationDescription" }
+}
+```
+
+Minimal variant — title only:
+
+```json
+{
+  "product-info": {
+    "type": "ProductInformationRoot",
+    "children": ["product-title"]
+  },
+  "product-title": { "type": "ProductInformationTitle", "props": { "as": "h1" } }
+}
+```
+
+With SKU and reference ID visible:
+
+```json
+{
+  "product-info": {
+    "type": "ProductInformationRoot",
+    "children": ["product-title", "product-sku", "product-ref"]
+  },
+  "product-title": { "type": "ProductInformationTitle", "props": { "as": "h1" } },
+  "product-sku":   { "type": "ProductInformationSku" },
+  "product-ref":   { "type": "ProductInformationReferenceId" }
+}
+```
+
+Composed title — page has a SKU Selector and the visible heading reads `"<product name> - <variant name>"`:
+
+```json
+{
+  "product-info": {
+    "type": "ProductInformationRoot",
+    "children": ["product-title"]
+  },
+  "product-title": {
+    "type": "ProductInformationTitle",
+    "props": { "as": "h1", "separator": " - " }
+  }
+}
+```
+
+Description with inline "show more" — a clamped description followed by a `'mais informações'` link that flips the clamp:
+
+```json
+{
+  "product-info": {
+    "type": "ProductInformationRoot",
+    "children": ["product-title", "product-description"]
+  },
+  "product-title": { "type": "ProductInformationTitle", "props": { "as": "h1" } },
+  "product-description": {
+    "type": "ProductInformationDescription",
+    "props": {
+      "format": "html",
+      "collapse": "showMore",
+      "defaultExpanded": false,
+      "collapsedLines": 4,
+      "moreLabel": "mais informações",
+      "lessLabel": "menos informações"
+    }
+  }
+}
+```
+
+Description as a collapsible section — PDP where the body sits behind a single toggle and the full text remains crawlable via `hidden="until-found"`. Use this when the design hides the description behind an explicit "show more" / "read full description" affordance rather than clamping it inline:
+
+```json
+{
+  "pdp-description": {
+    "type": "ProductInformationRoot",
+    "children": ["pdp-description-body"]
+  },
+  "pdp-description-body": {
+    "type": "ProductInformationDescription",
+    "props": {
+      "format": "html",
+      "collapse": "section",
+      "defaultExpanded": false,
+      "moreLabel": "Ver descrição completa",
+      "lessLabel": "Ocultar descrição"
+    }
+  }
+}
+```
+
+---
+
+## Common mistakes
+
+- **Inventing `ProductTitle` or `ProductName`.** The correct name is `ProductInformationTitle`. There is no standalone `ProductTitle`.
+- **Inventing `ProductDescription`.** The correct name is `ProductInformationDescription`.
+- **Using `ProductInformationTitle` outside an element providing `product-information` context.** The schema compiler rejects the page with `ContextConstraintError` before emitting any file; the runtime context guard still throws if the component is rendered outside a provider through a non-compiler path (Storybook, tests). All sub-components require an ancestor that declares `providesContext: 'product-information'` — typically `ProductInformationRoot`.
+- **Using `as="h1"` when the block is embedded in a card or secondary section.** Reserve `h1` for the main PDP heading; use `h2` or lower elsewhere.
+- **Setting `as` to a non-heading tag like `as="div"` or `as="span"`.** The Title is always a heading — only `h1`–`h6` are accepted. Non-heading values are rejected at the type level (FSPG-628) so the PDP cannot silently lose its `<h1>`. If you need the title to *look* like body text, style it with `text-base font-normal` (or your equivalent swatch); keep the semantic tag as a heading.
+- **Including `ProductInformationSku` or `ProductInformationReferenceId` when not visible in the image.** They render `null` silently, but add noise to the schema. Only include what's shown.
+- **Setting `separator` on a PDP that has no SKU Selector.** The variant half stays inert (the cache is never written) and the title renders alone. In production a `console.warn` fires once when the null state persists across renders (NFR-3 — the SigNoz alert is a follow-up). Either add the SKU Selector or omit `separator`.
+
+---
+
+## Styling
+
+Style `ProductInformationRoot` as the text-block layout and each sub-component as its own typographic line. Read font size, weight, and color off the image.
+
+### ProductInformationRoot
+
+Stacks the title, description, and other lines. Typical: `flex flex-col gap-[4px] w-full` (use a larger gap like `gap-[8px]` when the image shows the lines spaced apart).
+
+### ProductInformationTitle
+
+The main heading — large and bold. Typical: `text-[20px] leading-[1.3] font-semibold text-[#1A1A1A] tracking-[-0.005em] m-0`. Scale `text-[...]` to the heading size in the image; read the ink color as an arbitrary hex.
+
+### ProductInformationDescription
+
+Body copy — smaller, lighter, comfortable line height. Typical: `text-[14px] leading-[1.6] font-normal text-[#666666]`. The element that hosts the text carries `data-fs-text=""` in every collapse mode (the wrapper itself for `collapse: 'none'`, the panel for `'showMore'` and `'section'`), so if the project's `global.json` defines `Text.base` with the body-text typography (font, size, leading, weight, color), those styles cascade to the description automatically and no inline typography classes are needed on the description node.
+
+When `collapse` is `'showMore'` or `'section'`, the trigger element is a real `<button>` rendered as a sibling of the panel inside the Collapsible root. Style it via the `data-fs-product-information-description-trigger` attribute hook so the trigger inherits the description's flex container without being centered or stretched. Typical: `[&_[data-fs-product-information-description-trigger]]:self-start [&_[data-fs-product-information-description-trigger]]:text-[14px] [&_[data-fs-product-information-description-trigger]]:font-medium [&_[data-fs-product-information-description-trigger]]:underline`. Pair with the brand's link color via an arbitrary hex (e.g. `[&_[data-fs-product-information-description-trigger]]:text-[#e60014]`).
+
+### ProductInformationBrand / Sku / ReferenceId
+
+Secondary labels — small and muted. Typical: `text-[12px] leading-[1.4] font-normal text-[#8A8A8A]`. Use `uppercase tracking-[0.04em]` for an eyebrow-style brand label when the image shows it that way.
+
+Styled example — brand, title, and description visible:
+
+```json
+{
+  "product-info": {
+    "type": "ProductInformationRoot",
+    "children": ["product-brand", "product-title", "product-description"],
+    "style": ["flex", "flex-col", "gap-[4px]", "w-full"]
+  },
+  "product-brand": {
+    "type": "ProductInformationBrand",
+    "style": ["text-[12px]", "leading-[1.4]", "font-normal", "text-[#8A8A8A]", "uppercase", "tracking-[0.04em]"]
+  },
+  "product-title": {
+    "type": "ProductInformationTitle",
+    "props": { "as": "h1" },
+    "style": ["text-[20px]", "leading-[1.3]", "font-semibold", "text-[#1A1A1A]", "tracking-[-0.005em]", "m-0"]
+  },
+  "product-description": {
+    "type": "ProductInformationDescription",
+    "style": ["text-[14px]", "leading-[1.6]", "font-normal", "text-[#666666]"]
+  }
+}
+```
+
+---
+
+## Related
+
+- [[pricing]] — price block, sibling on the PDP.
+- [[product-gallery]] — media gallery block, sibling on the PDP.
+- [[buy-button]] — purchase action, sibling on the PDP.

package/dist/docs/product-list.md

@@ -0,0 +1,170 @@
+# ProductList (card content parts)
+
+**Category:** commerce
+**Purpose:** The product-list matter and its **card content parts** — the pieces that render one product inside a repeated card. `ProductListRoot` provides a prop-driven products context (the PLP case); `ProductListGrid` repeats a card template one row per product. The card leaves — `ProductCardImage`, `ProductCardName`, `ProductCardPrice`, `ProductCardListPrice` — read a single product from the per-item context and render it. These same leaves are **source-agnostic**: they render identically under the PLP grid and under `ProductShelfItems` (the facet-sourced `ProductShelf`), because both publish the same per-item context.
+
+---
+
+## When to use
+
+- **`ProductListRoot` + `ProductListGrid`**: a prop-driven product list (e.g. a PLP fed by the route/search), where the products are supplied to the root and each is rendered with a shared card template.
+- **The `ProductCard*` content parts**: any card composition — under the PLP grid or under a `ProductShelf` — that needs the product image, name, selling price, and list price.
+
+## When NOT to use
+
+- A facet-sourced, data-owning shelf → use `ProductShelfRoot` (it owns a `products(filter:)` fragment); compose these same card parts inside its `ProductShelfItems`.
+- PDP single-product pricing → use `PricingRoot`.
+
+---
+
+## Behavior model
+
+- **Two context boundaries.** The root owns the products + tax-display config; each row owns exactly one item. Card leaves read the item through a guarded hook (`useProductListItem()`, which throws when used outside a grid/items row) and never take list-shaped props.
+- **Content comes from the catalog.** `ProductCardName` renders `item.name` (the product title) and the prices render `item.price` / `item.listPrice` — never a manually authored CMS field.
+- **List-price presence is state-driven.** `ProductCardListPrice` renders **only** when `item.listPrice > item.price`; otherwise it returns nothing. There is no `showListPrice` prop — composition decides the part *can* appear, item state decides it *does*.
+- **Currency is resolved per item.** Both price leaves format with `item.currency ?? context.currency`, using the active storefront context's locale for number formatting, so the selling price and list price always agree on currency. The price *value* already reflects the session's sales channel / trade policy / price table via the data source.
+- **Image layout is configurable.** `ProductCardImage` exposes `aspectRatio` (e.g. `1/1`, `3/4`, `16/9`) and `objectFit`; they are orthogonal — `aspectRatio` sizes the box, `objectFit` fits the pixels. Alt text comes from `item.image.alt` (the catalog alt text, falling back to the product name at the data source).
+- **Availability is a derived card state.** The optional `ProductCard` wrapper emits `data-fs-product-card-out-of-stock` when `item.availableForSale === false || item.availableQuantity === 0` (unset ⇒ in stock), so a swatch can grey / reduce the opacity of the whole card. It is a derived state attribute, not a boolean prop, and the wrapper never suppresses its children — price and discount still render on an out-of-stock card. Dropping unavailable products entirely is the shelf's `availableOnly` config (`ProductShelfRoot`, T2), not a card concern.
+- **The card border is a style toggle.** The `ProductCard` wrapper also takes a `bordered` prop (default `true`) and reflects it onto `data-fs-product-card-bordered` (`"true"` / `"false"`, always present). A border is not an independently placeable part, so it is a boolean appearance config, not compose-or-omit; the actual border look is a swatch keyed off the attribute value — the component ships none. Because the attribute carries an explicit value, a swatch can style both the bordered and the unbordered case (`[data-fs-product-card-bordered='true']` / `'false']`). It is orthogonal to the out-of-stock state and does not affect children.
+- **Tax display is a config.** When the root config `usePriceWithTaxes` is on, `ProductCardPrice` and `ProductCardListPrice` render **tax-inclusive** values — `base × (1 + rate)` with `rate = item.taxPercentage ?? item.tax / item.price` (missing/zero-price tax data ⇒ rate `0`, prices unchanged). The same rate applies to both, so the list-price guard still compares the base prices. `ProductCardTaxLabel` renders the configured `taxesLabel` beside the price, but **only when `usePriceWithTaxes` is enabled** (state-driven presence — compose to place it, omit to hide). Default is tax-exclusive (off).
+
+---
+
+## Props
+
+### ProductListRoot
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `products` | `ProductListItem[]` | `[]` | The products to render; published through the products context |
+| `usePriceWithTaxes` | boolean | `false` | When true, card prices render tax-inclusive and `ProductCardTaxLabel` shows |
+| `taxesLabel` | string | `Tax included` | Text rendered by `ProductCardTaxLabel` when tax display is on |
+
+`ProductShelfRoot` exposes the same `usePriceWithTaxes` / `taxesLabel` config (it publishes the same config context).
+
+### ProductListGrid
+
+Repeats its children once per product, wrapping each in the per-item context. No props beyond standard `div` attributes.
+
+### ProductCard
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `bordered` | boolean | `true` | Reflects onto `data-fs-product-card-bordered` (`"true"` / `"false"`); a swatch draws the border |
+
+Optional card **wrapper** for the `ProductCard*` parts. It reads the item from the per-item context, always emits the `data-fs-product-card` identity hook, and adds `data-fs-product-card-out-of-stock` when the product is unavailable — `item.availableForSale === false || item.availableQuantity === 0` (unset availability ⇒ in stock, backward compatible). Availability is **derived state, not a prop**. The `bordered` prop is a purely visual toggle: it always emits `data-fs-product-card-bordered` carrying the stringified value, and the border look is a swatch keyed off it (the wrapper ships no baked border). It renders **all children unchanged** — an out-of-stock card still shows its price and discount (cross-feature rule). Standard `div` attributes pass through.
+
+### ProductCardImage
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `aspectRatio` | string | — | CSS `aspect-ratio` for the image box (e.g. `1/1`, `3/4`, `16/9`) |
+| `objectFit` | `contain \| cover \| fill \| none` | `cover` | How the image fits its box; orthogonal to `aspectRatio` |
+
+Renders `item.image.src` with `item.image.alt`. Standard `img` attributes pass through.
+
+### ProductCardName
+
+Renders `item.name` (the product title). Standard `span` attributes pass through; pass children to override the text (rarely needed — the point is catalog data).
+
+### ProductCardPrice
+
+Renders the selling price `item.price` formatted with the active storefront context's locale and `item.currency ?? context.currency`. When `usePriceWithTaxes` is on, it renders the tax-inclusive value instead (`item.price × (1 + rate)`).
+
+### ProductCardListPrice
+
+Renders `item.listPrice` (strikethrough via swatch) formatted like the selling price — **only when `item.listPrice > item.price`**, otherwise renders nothing. When `usePriceWithTaxes` is on, it renders the tax-inclusive list price at the same rate as the selling price.
+
+### ProductCardTaxLabel
+
+Renders the config `taxesLabel` (default "Tax included") beside the price, **only when `usePriceWithTaxes` is enabled** — otherwise renders nothing (state-driven presence, no toggle: compose it to place the label, omit it to hide it). Children override the text. Emits `data-fs-product-card-tax-label` for styling. Reads only the config (not the item), so its placement in the card template is free.
+
+### ProductCardDiscount
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `format` | `percentage \| absolute` | `percentage` | `percentage` → `-{pct}%`; `absolute` → `-{amount saved}` in the price currency |
+
+A discount badge that **composes the `Badge` particle**. It auto-computes the markdown from the item's prices — `percentOff = round((listPrice − price) / listPrice × 100)`, `amountOff = listPrice − price` — and renders **only when `item.listPrice > item.price`** (state-driven, no toggle: compose the part to show it, omit it to hide it). Children override the computed label. It also emits `data-fs-product-card-discount-tier` (`low` / `medium` / `high`, from the percentage) for swatch color tiers. Uses `price` (not `spotPrice`); spot/Pix discount is out of scope.
+
+> `ProductCardAddToCart` also exists in this matter, but its cart integration is out of scope for the Product Shelf feature.
+
+---
+
+## Per-item context
+
+Each row publishes a `ProductListItem`; the card content parts read these fields:
+
+| Field | Used by |
+|-------|---------|
+| `image` (`{ src, alt }`) | `ProductCardImage` |
+| `name` | `ProductCardName` |
+| `price` | `ProductCardPrice`; `ProductCardDiscount` (discount base) |
+| `listPrice` | `ProductCardListPrice` and `ProductCardDiscount` (rendered only when `> price`) |
+| `currency` | price / discount formatting (falls back to the storefront context currency) |
+| `availableForSale` / `availableQuantity` | `ProductCard` (out-of-stock state when `availableForSale === false` or `availableQuantity === 0`) |
+| `tax` / `taxPercentage` | `ProductCardPrice` / `ProductCardListPrice` (tax-inclusive value when `usePriceWithTaxes` is on) |
+
+The type is widened (optional `spotPrice`, `tax`, `taxPercentage`, `availableForSale`, `availableQuantity`, `currency`) so the same leaves compose under `ProductShelfItems`, which supplies those extra fields for the discount / out-of-stock / tax card parts.
+
+---
+
+## Composition
+
+```
+ProductListRoot            (owns products + tax-display config)
+└── ProductListGrid        (repeats the card template per product)
+    └── ProductCard        (optional wrapper; data-fs-product-card [+ -bordered, + -out-of-stock])
+        ├── ProductCardImage       (aspectRatio, objectFit)
+        ├── ProductCardName
+        ├── ProductCardDiscount    (badge; renders only when listPrice > price)
+        ├── ProductCardPrice       (tax-inclusive when usePriceWithTaxes)
+        ├── ProductCardListPrice   (renders only when listPrice > price)
+        └── ProductCardTaxLabel    (renders only when usePriceWithTaxes)
+```
+
+The same card template composes inside a `ProductShelf` — swap `ProductListRoot > ProductListGrid` for `ProductShelfRoot > CarouselRoot > ProductShelfItems`.
+
+---
+
+## Minimal schema example
+
+```json
+{
+  "list": {
+    "type": "ProductListRoot",
+    "props": { "usePriceWithTaxes": true, "taxesLabel": "Tax included" },
+    "children": ["grid"]
+  },
+  "grid": {
+    "type": "ProductListGrid",
+    "children": ["card"]
+  },
+  "card": {
+    "type": "ProductCard",
+    "props": { "bordered": true },
+    "children": ["card-image", "card-name", "card-discount", "card-price", "card-list-price", "card-tax-label"]
+  },
+  "card-image": { "type": "ProductCardImage", "props": { "aspectRatio": "1/1", "objectFit": "cover" } },
+  "card-name": { "type": "ProductCardName" },
+  "card-discount": { "type": "ProductCardDiscount", "props": { "format": "percentage" } },
+  "card-price": { "type": "ProductCardPrice" },
+  "card-list-price": { "type": "ProductCardListPrice" },
+  "card-tax-label": { "type": "ProductCardTaxLabel" }
+}
+```
+
+---
+
+## Styling
+
+All appearance is chosen by swatches keyed off the structural hooks:
+
+- `data-fs-product-list-root` / `data-fs-product-list-grid` — the container and grid
+- `data-fs-product-card` — the optional card wrapper; `data-fs-product-card-bordered` carries `"true"` / `"false"` from the `bordered` toggle (draw the border here — e.g. `[data-fs-product-card-bordered='true']`); `data-fs-product-card-out-of-stock` is present only when the product is unavailable (grey / reduce opacity here; scope it so price/discount stay legible)
+- `data-fs-product-card-image` — the image (carries `aspect-ratio` + `object-fit` styles)
+- `data-fs-product-card-name` — the title text
+- `data-fs-product-card-price` — the selling price
+- `data-fs-product-card-list-price` — the list price (apply the strikethrough here)
+- `data-fs-product-card-tax-label` — the tax label (present only when `usePriceWithTaxes` is on)
+- `data-fs-product-card-discount` — the discount badge (also carries `data-fs-badge`); `data-fs-product-card-discount-tier` = `low` / `medium` / `high` for color tiers

package/dist/docs/product-quantity.md

@@ -0,0 +1,88 @@
+# ProductQuantity
+
+**Category:** commerce
+**Purpose:** Headless boundary that holds the purchase quantity for a single product on a PDP and shares it with the BuyButton and a bound quantity selector. Exposes the selected seller's stock as the selector `max`. Renders no DOM of its own.
+
+---
+
+## Visual cues (how to identify in an image)
+
+ProductQuantity has no visual of its own. You identify it indirectly when a PDP shows **both**:
+
+- A **quantity stepper** (a number input flanked by `−` / `+` controls), and
+- A **BuyButton** that should add that quantity to the cart.
+
+The stepper itself is rendered by `ProductQuantitySelector` (wrapping the generic `QuantitySelectorRoot`); the `ProductQuantityRoot` is the invisible provider that connects it to the BuyButton.
+
+---
+
+## When to use
+
+- A PDP where clicking the BuyButton must add the quantity chosen in the stepper.
+
+## When NOT to use
+
+- A standalone quantity stepper with no cart wiring — use the generic `QuantitySelectorRoot` particle directly.
+- Cart line item quantity controls — use the cart-specific quantity components.
+
+---
+
+## Composition
+
+`ProductQuantityRoot` is a **headless context boundary**: it renders no element, so it never affects layout. It only needs to be an **ancestor** of both the BuyButton and the `ProductQuantitySelector` in the element tree — they do **not** need to be adjacent or share a visual container.
+
+```text
+ProductQuantityRoot            (headless — no DOM)
+├── ... any layout blocks ...
+│   └── BuyButtonRoot
+│       └── BuyButtonButton
+└── ... any other layout block ...
+    └── ProductQuantitySelector
+        ├── NumberFieldGroup
+        │   ├── NumberFieldDecrement
+        │   ├── NumberFieldInput
+        │   └── NumberFieldIncrement
+        └── ProductQuantity.Message   (optional — shows the max-exceeded message)
+```
+
+### Placement
+
+Because it renders nothing, place `ProductQuantityRoot` **as high as a single product's scope allows** — typically at the PDP page/layout root. The BuyButton and the selector can then sit in entirely different layout blocks below it.
+
+### Scope
+
+One `ProductQuantityRoot` represents **one product**. On a standard PDP that is the whole page, so a single high-level provider is correct. If a page ever offers **multiple independently purchasable products** (e.g. a "buy together" block), give each its own `ProductQuantityRoot` subtree instead of one shared provider — otherwise all of them would share a single quantity.
+
+---
+
+## Components
+
+### ProductQuantityRoot
+
+Headless provider. Holds the selected quantity (default `1`) and derives the `max` from stock. Renders no DOM element.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `defaultValue` | number | `1` | Initial quantity |
+
+**Data:** declares `fragment ProductQuantityData on Query`. Reads the first variant's sellers and exposes the **default seller's** `offer.availableQuantity` as `max` (mirrors BuyButton's seller-selection rule so the cap matches the seller actually purchased). `max` is `null` when no data is provided.
+
+---
+
+### ProductQuantitySelector
+
+Quantity stepper bound to the `ProductQuantityRoot` context. Renders the generic `QuantitySelectorRoot` wired to the shared quantity state, with `min` of `1` and `max` from stock. Pass-through props and children are forwarded to `QuantitySelectorRoot`.
+
+Must be a descendant of `ProductQuantityRoot`. Without it, the selector falls back to a quantity of `1` and is effectively read-only.
+
+---
+
+### ProductQuantity.Message
+
+Thin alias of the particle part `QuantitySelectorMessage`. Renders a message when a shopper enters a quantity above the stock-derived `max` and the value was clamped down; renders nothing otherwise. Place it inside `ProductQuantitySelector` so it reads the selector context. Set `children` to override the default copy — the text is operational UI, sourced in the component until the `@vtex/fs-i18n` catalog exists.
+
+---
+
+## BuyButton integration
+
+`BuyButtonButton` reads the quantity from this context (via `useProductQuantity()`) and passes it to `cart.addItem()`. The hook has a safe default, so a BuyButton rendered **without** a `ProductQuantityRoot` ancestor still works and adds quantity `1` — the integration is opt-in by mounting the provider.