@vtex/faststore 0.0.4 → 0.0.6

package/dist/docs/select.md

@@ -0,0 +1,465 @@
+# Select
+
+**Category:** layout
+**Purpose:** Composable dropdown-select anatomy — nineteen generic `Select.*` parts wrapping Base UI's
+`Select`, plus four `FieldSelect.*` parts that bind a chosen-option field to react-hook-form through the
+field contract (`FieldBinding`/`useField`, see [[field]]).
+
+---
+
+## Visual cues (how to identify in an image)
+
+A Select block is a **single-choice dropdown control**: a closed trigger showing either the chosen
+option's label or a placeholder, with a small indicator glyph (chevron, caret) hinting it opens a list.
+Clicking or tapping it reveals a floating popup listing the choices; the popup is not part of the
+resting layout — it does not appear in a screenshot of the closed state. The image is the source of
+truth for layout.
+
+Signals that distinguish it from other controls:
+
+- A **bordered, button-like box** with a text label and a trailing chevron/caret glyph (`▾`, `⌄`, an
+  SVG arrow) — not a checkbox square, not a radio circle, not a toggle track.
+- The label inside reads like a **chosen value** (a country name, a size, a sort order), not a
+  static caption — a static caption next to the box is the field's label, rendered separately.
+- Grouped variants show a **section heading** inside the popup (`SelectGroupLabel`) above a cluster of
+  related options, with a divider line (`SelectSeparator`) between groups.
+- A **country/region selector** (ISO codes resolved to display names), a **sort-order dropdown**, or a
+  **quantity/unit picker** are the most common PDP/checkout uses.
+
+This particle currently has no `store-editor` knowledge-base row: it is a leaf control with no
+distinct visual region of its own, and the bound `FieldSelect.*` parts cannot be generated from a
+screenshot without the bound Control that consumes them (`ShippingAddressCountryControl`). This section documents the
+visual pattern for a human reader; it is not wired into image→schema detection.
+
+---
+
+## When to use
+
+- Any field whose value is chosen from a closed, platform- or merchant-defined list: country, state,
+  sort order, page size, unit, saved-address selection.
+- `FieldSelect.*` specifically: a select whose value must persist through a react-hook-form submit
+  alongside the rest of a form's fields (the same contract every other bound field part uses).
+
+## When NOT to use
+
+- A boolean toggle → use `Checkbox`/`Field.Checkbox` ([[checkbox]], [[field]]), not a two-option Select.
+- Free text entry → use `Field.Control` ([[field]]).
+- A list of mutually exclusive options **all visible at once** (radio buttons, a swatch row) → Select
+  hides the options behind a trigger; use a different particle when the design shows every option
+  simultaneously (e.g. `VariantSelector`'s swatches).
+- Authoring the option list yourself in a schema for a bound select → not supported.
+  `FieldSelectOptionsDefinition` declares `schema: {}`; the list always comes from the field contract's
+  `options`, never from a prop (the platform owns the list; an author only reorders and
+  restyles).
+
+---
+
+## Composition
+
+### Generic anatomy (fully schema-authorable)
+
+```
+SelectRoot                        (renders no element of its own)
+├── SelectLabel                   (optional; outside SelectTrigger)
+├── SelectTrigger
+│   ├── SelectValue
+│   └── SelectIcon
+└── SelectPortal                  (renders no element of its own)
+    ├── SelectBackdrop            (optional; modal dismiss layer)
+    └── SelectPositioner
+        └── SelectPopup
+            ├── SelectArrow               (optional)
+            ├── SelectScrollUpArrow       (optional)
+            ├── SelectList
+            │   ├── SelectItem
+            │   │   ├── SelectItemText
+            │   │   └── SelectItemIndicator
+            │   ├── SelectSeparator       (optional, between groups)
+            │   └── SelectGroup           (optional, instead of flat SelectItems)
+            │       ├── SelectGroupLabel
+            │       └── SelectItem …
+            └── SelectScrollDownArrow     (optional)
+```
+
+Child order reflects visual/DOM order. `SelectLabel` is a sibling of `SelectTrigger`, not a child of it —
+screen readers announce it separately. `SelectRoot` and `SelectPortal` render no host element of their
+own (Base UI: *"Doesn't render its own HTML element"*), so neither can carry a `className` or a styling
+hook — style `SelectTrigger`/`SelectPositioner`/`SelectPopup` instead.
+
+### Bound anatomy (`FieldSelect.*`)
+
+`FieldSelectRoot` recomposes exactly the same generic tree; the difference is which four nodes read the
+enclosing field contract instead of taking props directly. Childless, it renders the full nine-node
+default:
+
+```
+FieldSelectRoot                   (drives SelectRoot; requires a field contract + react-hook-form)
+├── FieldSelectTrigger            (renders SelectTrigger)
+│   ├── FieldSelectValue          (renders SelectValue, label resolved from contract.options)
+│   └── SelectIcon                (generic; no default glyph)
+└── SelectPortal
+    └── SelectPositioner
+        └── SelectPopup
+            └── SelectList
+                └── FieldSelectOptions   (renders one SelectItem per contract.options entry)
+```
+
+Given children, `FieldSelectRoot` renders them instead and steps aside — an author places
+`FieldSelect.Trigger`/`Value`/`Options` anywhere among the generic `Select.*` parts (icon before value,
+an error above the trigger, a custom item indicator) and the binding still works, because **a node gets
+a bound part if and only if the field contract has something to say about it**: the root (identity, seed,
+rule, input semantics), the trigger (requiredness), the value (options → label, placeholder), the item
+list (options). Every other node — icon, portal, positioner, popup, list, arrows, group, separator,
+item indicator — stays the plain generic part; nothing about it is duplicated for the bound anatomy.
+
+`FieldSelectOptions` renders no wrapper of its own: it iterates `contract.options` and emits that many
+`SelectItem`s directly into whatever container holds it (normally `SelectList`).
+
+**A schema-authored `FieldSelectRoot` compiles but does not bind on its own.** `requiresContext: 'field'`
+is a compiler check satisfied by any ancestor declaring `providesContext: 'field'` (`FieldRootDefinition`
+does) — but the actual field contract is supplied at runtime only by `FieldBinding`, a code-level export
+that is never catalogued (see [[field]]). A schema places `FieldRoot > FieldSelectRoot` and it renders —
+identically to a plain `SelectRoot`, with no seeded value and nothing persisted — because there is no
+`FieldBinding` above it at runtime. Bound behaviour only exists where a matter's own code renders
+`FieldBinding` internally (the pattern `ShippingAddressCountryControl` follows).
+
+---
+
+## Components
+
+### SelectRoot
+
+Root of the dropdown. Manages selection state, modal overlay, and hidden-input form integration.
+Renders no element of its own.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `disabled` | boolean | `false` | Prevents the popup from opening. |
+| `modal` | boolean | `true` | `false` allows interacting with background elements while open. |
+| `required` | boolean | `false` | Sets `aria-required` on the trigger **and** native `required` on the hidden input — see *Common mistakes*. |
+| `readOnly` | boolean | `false` | |
+| `value` / `defaultValue` | string | — | Controlled / uncontrolled selection. |
+| `onValueChange` | `(value: string \| null) => void` | — | Called with the chosen item's `value`, or `null` when cleared. |
+| `open` / `defaultOpen` / `onOpenChange` | — | | Popup open state, controlled or uncontrolled. |
+| `name` | string | — | Name of the hidden `<input>` Base UI renders for native form participation. |
+| `autoComplete` | string | — | Forwarded to the hidden `<input>`; turns on browser autofill for the field. |
+
+### SelectLabel
+
+Accessible label for the trigger. No props beyond `className`/`children`. Always a sibling of
+`SelectTrigger`, never a child of it.
+
+### SelectTrigger
+
+Opens/closes the popup on click. Style `data-open` and `data-placeholder` for open-state and
+empty-state styling.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `disabled` | boolean | `false` | |
+
+### SelectValue
+
+Renders the selected item's text, or the placeholder when nothing is selected.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `placeholder` | string | — | Shown when nothing is selected and no function child overrides it. |
+| `children` | `ReactNode \| ((value: string \| null) => ReactNode)` | — | **A function child is required for the label to be correct before the shopper opens the dropdown at least once — see the measured-behaviour note below.** |
+
+**Measured behaviour, pinned by `select.test.tsx`:** with no function child and no `items` prop on
+`SelectRoot`, `SelectValue` shows the *raw stored value*, not the matching option's label — permanently,
+not merely on first paint. Base UI resolves the label through `resolveSelectedLabel(value, items, …)`;
+`items` is fed only by `SelectRoot`'s own `items` prop (unsupported by this wrapper — see *Common
+mistakes*) and never by a mounted `SelectItem`, so opening and closing the popup does not repair it.
+`FieldSelectValue` exists precisely to carry this resolution with the part; a plain `SelectValue` in a
+hand-composed anatomy needs its own function child.
+
+### SelectIcon
+
+Decorative glyph (chevron, arrow) inside the trigger. Renders with no children by default — a brand
+supplies the glyph. Style `data-open` to rotate/swap it.
+
+### SelectPortal
+
+Teleports the popup subtree to `<body>`. Renders no element of its own. Always wrap
+`SelectPositioner` with it.
+
+### SelectBackdrop
+
+Invisible overlay that closes the select on outside click. Required when `modal={true}` to trap
+interaction.
+
+### SelectPositioner
+
+Positions the popup relative to the trigger.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `side` | `'top' \| 'bottom' \| 'left' \| 'right'` | `'bottom'` | |
+| `align` | `'start' \| 'center' \| 'end'` | `'center'` | |
+| `sideOffset` | number | `0` | |
+| `alignItemWithTrigger` | boolean | `true` | Overlaps the selected item visually with the trigger. |
+
+### SelectPopup
+
+Visible container for the list. Style background, border, shadow here.
+
+### SelectArrow
+
+Pointing arrow attached to the popup. Optional — omit when the design has no anchor arrow.
+
+### SelectList
+
+Scrollable container for `SelectItem`s (and, when grouped, `SelectGroup`s).
+
+### SelectItem
+
+One selectable option.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `value` | string | — | Required for the item to be selectable. |
+| `disabled` | boolean | `false` | |
+| `label` | string | — | Used by Base UI for keyboard typeahead matching — not the same mechanism as the trigger's label resolution (see `SelectValue` above). |
+
+Style `data-selected`/`data-highlighted` for state.
+
+### SelectItemText
+
+The item's visible text. Base UI also uses this node for keyboard-typeahead matching.
+
+### SelectItemIndicator
+
+Checkmark or similar, shown only when the item is selected (`keepMounted` to animate in/out instead
+of unmounting).
+
+### SelectSeparator
+
+Visual divider, typically between option groups.
+
+### SelectGroup
+
+Groups related items under a shared `SelectGroupLabel`.
+
+### SelectGroupLabel
+
+Non-interactive label for a `SelectGroup`, announced by screen readers as the group name.
+
+### SelectScrollUpArrow / SelectScrollDownArrow
+
+Hover targets that scroll an overflowing list. Appear automatically when the list overflows in that
+direction; `keepMounted` forces them to always render.
+
+### FieldSelectRoot
+
+Bound select over the shipped `Select` particle: reads the enclosing field contract, registers with
+react-hook-form via `useController({ name, rules, defaultValue })`, and drives `SelectRoot`. Requires a
+field contract (`requiresContext: 'field'`); additionally requires a react-hook-form context to take its
+bound path — with a contract but no `FormProvider`, it
+renders an uncontrolled `SelectRoot` with the given children (or the default anatomy), still honouring
+the contract's static `disabled`/`readOnly` facts, but persisting nothing.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `modal` | boolean | `true` | Forwarded to `SelectRoot`. The one authorable knob that carries no field meaning. |
+| `children` | ReactNode | — | Childless renders the nine-node default anatomy; given children, renders them instead. |
+
+Bound behaviour: `value={typeof field.value === 'string' ? field.value : ''}`,
+`onValueChange={(next) => field.onChange(next ?? '')}` — Base UI's `null` (a cleared selection) is
+always normalised to `''` before reaching react-hook-form, never left as `null`. Also passes
+`disabled`/`readOnly`/`name`/`autoComplete` from the contract. Renders **no** `data-fs-field-select-*` hook of its own —
+`SelectRoot` renders no element to put one on (Decision 8); style the bound select through
+`FieldSelectTrigger` instead.
+
+### FieldSelectTrigger
+
+Bound trigger: renders `SelectTrigger` with `aria-required={contract.rule?.required ? true : undefined}`
+and the styling hook `data-fs-field-select-trigger=""`, alongside the generic
+`data-fs-select-trigger=""`. Requires a field contract; does **not** additionally require
+react-hook-form (Decision 4) — `aria-required` is static contract data.
+
+Never passes native `required` to `SelectRoot` — only `aria-required`. A native `required` would also
+mark Base UI's hidden input `required`, turning on browser constraint validation, which fires before
+react-hook-form's `handleSubmit` and would show a native validation bubble instead of `Field.Error`.
+
+No props beyond standard button attributes (`className`, `children`).
+
+### FieldSelectValue
+
+Bound value: renders `SelectValue` with a function child that resolves the current selection's label
+from `contract.options`, plus `data-fs-field-select-value=""` alongside the generic
+`data-fs-select-value=""`. This is the part that closes the measured-behaviour gap noted under
+`SelectValue` above — the resolution travels with the part, so a recomposed anatomy that places
+`FieldSelectValue` gets a correct label on first paint, not only after the dropdown has been opened.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `placeholder` | string | — | Wins over the contract's `placeholder` when given. Shown for an empty value. |
+
+Resolution order for the trigger's text: empty value → `placeholder ?? contract.placeholder`; a value
+matching a `contract.options` entry → that option's `label`; a value matching nothing → the raw value
+itself (never blank).
+
+### FieldSelectOptions
+
+Bound option list: renders one `SelectItem` per `contract.options` entry, in contract order, each
+containing a `SelectItemText` (the option's label — platform data, not authored) followed by whatever
+`children` this part was given (e.g. a `SelectItemIndicator`). Renders `null` when the contract carries
+no `options`, without throwing. Renders no wrapper of its own — items land directly in whatever contains
+this part (normally `SelectList`).
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `className` | string | — | Applied to every item this part renders. |
+| `children` | ReactNode | — | Rendered inside every item, after its text. |
+
+Every rendered item carries `data-fs-field-select-option=""` alongside the generic
+`data-fs-select-item=""`.
+
+---
+
+## Canonical schema example
+
+`FieldBinding` is never catalogued, so the only composition a schema can *bind* is the generic anatomy —
+the same shape below works whether or not a `FieldSelectRoot` happens to sit above it, because without a
+real `FieldBinding` at runtime a schema-authored `FieldSelectRoot` renders unbound (see *Composition*
+above):
+
+```json
+{
+  "country-select": {
+    "type": "SelectRoot",
+    "children": ["country-label", "country-trigger", "country-portal"]
+  },
+  "country-label": { "type": "SelectLabel", "props": { "children": "Country" } },
+  "country-trigger": {
+    "type": "SelectTrigger",
+    "children": ["country-value", "country-icon"]
+  },
+  "country-value": { "type": "SelectValue", "props": { "placeholder": "Choose…" } },
+  "country-icon": { "type": "SelectIcon", "props": { "children": "▾" } },
+  "country-portal": {
+    "type": "SelectPortal",
+    "children": ["country-positioner"]
+  },
+  "country-positioner": {
+    "type": "SelectPositioner",
+    "children": ["country-popup"]
+  },
+  "country-popup": {
+    "type": "SelectPopup",
+    "children": ["country-list"]
+  },
+  "country-list": {
+    "type": "SelectList",
+    "children": ["country-brazil", "country-usa"]
+  },
+  "country-brazil": {
+    "type": "SelectItem",
+    "props": { "value": "BRA", "label": "Brasil" },
+    "children": ["country-brazil-text"]
+  },
+  "country-brazil-text": { "type": "SelectItemText", "props": { "children": "Brasil" } },
+  "country-usa": {
+    "type": "SelectItem",
+    "props": { "value": "USA", "label": "Estados Unidos" },
+    "children": ["country-usa-text"]
+  },
+  "country-usa-text": { "type": "SelectItemText", "props": { "children": "Estados Unidos" } }
+}
+```
+
+Note the absence of a function child on `country-value` above: authored this way — plainly, with no
+`items` on `country-select` — the trigger shows the raw `value` string until (and after) a function
+child is added, per the measured behaviour documented under `SelectValue`. A bound composition
+(`FieldSelectRoot` given real `FieldBinding` at runtime, as `ShippingAddressCountryControl` does) does
+not have this problem, because `FieldSelectValue` supplies the function child itself.
+
+---
+
+## Common mistakes
+
+- **Expecting `SelectValue` to resolve the label automatically once the popup has been opened.** It does
+  not, in `@base-ui/react@1.3.0` — see the measured-behaviour note under `SelectValue`. Pass a function
+  child, or use `FieldSelectValue` in a bound composition.
+- **Passing `required` to `SelectRoot` expecting only `aria-required`.** It also sets native `required`
+  on the hidden input, enabling browser constraint validation that pre-empts react-hook-form's
+  `handleSubmit`. Use `FieldSelectTrigger`'s `aria-required` (or a manual `aria-required` prop) instead.
+- **Putting a `className` or a `data-fs-*` hook expectation on `SelectRoot` or `SelectPortal`.** Neither
+  renders an element — the prop is silently dropped. Style `SelectTrigger`/`SelectPositioner`/
+  `SelectPopup` instead.
+- **Authoring an `options` prop on `FieldSelectOptions`.** There is none —
+  `FieldSelectOptionsDefinition` declares `schema: {}`. The option list always comes from the field
+  contract, never from a prop.
+- **Expecting a schema-authored `FieldSelectRoot` to bind just because a `FieldRoot` sits above it.**
+  The compiler's context check passes, but nothing supplies a live contract at runtime without a real
+  `FieldBinding`, which only a matter's own code renders. The result compiles green and behaves like a
+  plain, unseeded `SelectRoot`.
+- **Nesting the field name as a prop anywhere under `FieldSelectRoot`.** No `FieldSelect.*` part accepts
+  one; the only way to name a field is a `FieldBinding` above it.
+- **Reordering `SelectItemText`/`SelectItemIndicator` inside a `FieldSelectOptions`-rendered item.**
+  `FieldSelectOptions` fixes the text first, `children` after — a different order for the indicator is a
+  CSS `order`/`flex-direction` concern on `[data-fs-select-item-text]`/`[data-fs-select-item-indicator]`,
+  not a composition option.
+- **Using `Field.Select`.** There is no such member. The bound namespace is `FieldSelect` (`FieldSelect
+  .Root/.Trigger/.Value/.Options`), ships from this directory, and is not part of the `Field` namespace —
+  a deliberate naming divergence.
+
+---
+
+## Styling
+
+`SelectRoot` and `SelectPortal` render no element and cannot be styled directly — style the parts that
+do.
+
+| Component | What you style | Plausible classes |
+|---|---|---|
+| `SelectTrigger` | The closed control's box | `inline-flex items-center gap-2 border border-gray-300 rounded-md px-3 py-2 text-sm bg-white hover:border-gray-400 data-open:border-blue-500` |
+| `SelectValue` | The chosen label / placeholder text | `flex-1 text-left` (target `data-placeholder:text-gray-400` for the empty state) |
+| `SelectIcon` | The trailing glyph | `text-gray-400` |
+| `SelectPopup` | The floating panel | `bg-white border border-gray-200 rounded-md shadow-lg overflow-hidden` |
+| `SelectList` | The scrollable list | `py-1 max-h-60 overflow-auto` |
+| `SelectItem` | One option row | `flex items-center gap-2 px-3 py-2 text-sm cursor-default hover:bg-blue-50 data-highlighted:bg-blue-50 data-selected:text-blue-600` |
+| `SelectGroupLabel` | A group heading inside the list | `px-3 py-1 text-xs font-semibold text-gray-500 uppercase tracking-wide` |
+| `SelectSeparator` | The divider between groups | `my-1 border-t border-gray-100` |
+
+The four `FieldSelect.*` parts render alongside their generic counterpart's own hook
+(`FieldSelectTrigger` on the same `<button>` as `SelectTrigger`, and so on) — style through the generic
+class names above; the bound `data-fs-field-select-*` attributes exist for a brand that specifically
+needs to target *the bound select* without touching every generic select in the app.
+
+Styled bound example (the `BoundRecomposed` story):
+
+```tsx
+<FieldSelect.Root>
+  <FieldSelect.Trigger className="inline-flex items-center gap-2 border border-gray-300 rounded-md px-3 py-2 text-sm bg-white hover:border-gray-400 data-open:border-blue-500">
+    <SelectIcon className="text-gray-400">▾</SelectIcon>
+    <FieldSelect.Value className="flex-1 text-left" />
+  </FieldSelect.Trigger>
+  <SelectPortal>
+    <SelectPositioner>
+      <SelectPopup className="bg-white border border-gray-200 rounded-md shadow-lg overflow-hidden">
+        <SelectList className="py-1 max-h-60 overflow-auto">
+          <FieldSelect.Options className="flex items-center gap-2 px-3 py-2 text-sm cursor-default hover:bg-blue-50 data-highlighted:bg-blue-50 data-selected:text-blue-600">
+            <SelectItemIndicator className="w-4 text-blue-600">✓</SelectItemIndicator>
+          </FieldSelect.Options>
+        </SelectList>
+      </SelectPopup>
+    </SelectPositioner>
+  </SelectPortal>
+</FieldSelect.Root>
+```
+
+---
+
+## Related
+
+- [[field]] — the field contract (`FieldBinding`/`useField`, `FieldContract`, `FieldOption`) that
+  `FieldSelect.*` consumes. The `Field` namespace itself gains no `Select` member — see *Common
+  mistakes* above.
+- [[checkbox]] — the sibling bound part for a boolean field is `Field.Checkbox` (lives in `field.tsx`,
+  not here); `FieldSelect.*` is the equivalent family for a chosen-option field, kept in its own
+  directory.
+- `ShippingAddressCountryControl` (`packages/faststore/src/matter/shipping-address/shipping-address.tsx`)
+  — today's only select in the repo, and the only consumer of `FieldSelect.*`.

package/dist/docs/session.md

@@ -34,7 +34,7 @@ Exactly one `SessionRoot` per rendered tree. A layout-hosted provider already co
 ## Layout hosting vs. page hosting
 
 Layout and page scope still fetch differently, even though both now see the shopper's cookie
-([`specs/ssr-cookie-forwarding-fetch.md`](../../../../../specs/ssr-cookie-forwarding-fetch.md)):
+([SSR session cookie forwarding](../../../../../docs/storefront-core/reference-ssr-session-cookie-forwarding.md)):
 
 - **Layout scope** emits `LAYOUT_QUERY` inside a client component with no SSR seed — no `serverVariables`, no
   `initialData`. The read happens once in the browser and is reused from cache across client-side navigation.