@vtex/faststore 0.0.1

package/dist/docs/payment-methods.md

@@ -0,0 +1,139 @@
+# PaymentMethods
+
+**Category:** content
+**Purpose:** The store's accepted payment methods, rendered as a strip of flags with an optional heading, both editable in the CMS. The content arrives through the compiler-injected `$content` prop, backed by the `payment-methods` content model declared next to the component; the `heading` and `methods` props are the authored fallback for stores with no CMS binding. One element renders the whole strip.
+
+---
+
+## Visual cues (how to identify in an image)
+
+The image is the source of truth for layout. A PaymentMethods strip is present when you see:
+
+- A **horizontal row of small card flags** — Visa, Mastercard, Elo, Amex, the Pix logo, a Boleto mark — usually rounded rectangles of roughly uniform size.
+- Often a **short heading above or beside them**: *Formas de pagamento*, *We accept*, *Payment methods*.
+- The glyphs are **brand marks, not text links and not social icons**. Circular monochrome glyphs for Instagram or Facebook are a different component.
+- Typically in a footer band, sometimes wrapping to a second line on a narrow screen.
+
+---
+
+## When to use
+
+- The row of accepted payment brands in a footer or checkout reassurance band.
+- One instance per strip. Every flag in the row is one item of this component's content, not its own element.
+
+## When NOT to use
+
+- A product's **installment plan or "in 12× of R$ 9,90"** copy → use `PricingPaymentMethodsList`, which reads commerce data for one product rather than store-level configuration.
+- The shopper's **saved cards or payment selection** in checkout → that is a form, not this display strip.
+- A row of **social network icons** → use [[footer-social]]; different content model and different glyph set, and every glyph is a link.
+- A row of **trust or security seals** (SSL, Reclame Aqui) → not payment brands.
+- The **value-proposition strip** (free shipping, secure purchase) → use [[incentives]]; those items pair an icon with a line or two of copy rather than a bare brand flag.
+
+---
+
+## Composition
+
+`PaymentMethods` is a leaf in the schema — it has no sub-components and takes no children. The flags come from content, not from child elements.
+
+```
+FooterRoot
+├─ FooterLinkGroup      ← "Ajuda"        (siblings; order is visual order)
+├─ FooterLinkGroup      ← "Institucional"
+├─ PaymentMethods       ← the flag strip
+└─ FooterCopyright
+```
+
+**Content, then prop, per field.** The heading resolves from the CMS entry first and the `heading` prop second; the list resolves the same way, independently. The list is replaced whole rather than merged — an entry supplying an empty list wins over an authored list, because a merchant who cleared the methods cleared them. When no item survives the filter below, the component renders `null` (self-hide) and the footer omits the strip. Non-compiler hosts (Storybook, tests) pass a typed `$content` fixture directly.
+
+**Nothing in the model is required, so a half-filled entry still renders.** An entry with only a heading keeps the authored `methods` prop under the merchant's heading, and vice versa. What the component drops is per item, never the whole strip: an item is skipped when its label is blank, or when it carries neither a `method` nor an `iconUrl` — an icon nobody can name is the one thing this must not ship.
+
+**Every predefined name must be registered.** A `method` resolves to a sprite symbol the store's build has to include; the store's `global.json` writes the names out under `icons.include` — it is JSON, so it cannot import `PAYMENT_METHOD_NAMES`, and a test that derives the expected set from the exported constant is what keeps the two in step. A name the store never registered renders an empty `<svg>` — no build error and no runtime error, just a missing flag.
+
+---
+
+## Components
+
+### PaymentMethods
+
+| Prop | Type | Required | Notes |
+|-------|------|----------|-------|
+| `heading` | string | no | Authored fallback. Ignored when a CMS entry supplies a heading |
+| `methods` | array | no | Authored fallback list of `{ label, method?, iconUrl? }`. Ignored when a CMS entry supplies `methods` |
+
+Content model (`payment-methods`) fields, edited in the CMS:
+
+| Field | Type | Required | Notes |
+|-------|------|----------|-------|
+| `heading` | string | no | Optional strip heading. When set it also names the list for assistive tech; when blank or absent the list is left unnamed rather than given an invented English default |
+| `methods` | array | no | Ordered flags. Reordering here reorders the strip with no deployment. Optional so a heading-only entry falls back to the authored list. Declares `minItems: 1` and no ceiling — Admin-form guidance only, unenforced on the read path, so an empty list still reaches the component and self-hides there |
+| `methods[].method` | enum | no | One of `visa`, `amex`, `apple-pay`, `elo-card`, `diners`, `google-pay`, `mastercard`, `paypal`, `pix`, `stripe`. Renders the dialect glyph |
+| `methods[].label` | string | yes | The method's name. Names the flag for assistive tech; a blank label drops the item |
+| `methods[].iconUrl` | string | no | An uploaded image, for a brand the dialect has no glyph for (Boleto, a regional wallet). Wins over `method` when both are set |
+
+---
+
+## Canonical schema example
+
+```json
+{
+  "footer-payment-methods": {
+    "type": "PaymentMethods",
+    "style": ["flex", "flex-col", "gap-[12px]"]
+  }
+}
+```
+
+The element id is the content key, so name it for the section rather than its styling. Renaming it orphans the merchant's entry: the flags stay in the Content Platform while the component reads a key nobody writes.
+
+---
+
+## Common mistakes
+
+- **`PaymentMethodsList`, `PaymentIcons`, `PaymentFlags`, `AcceptedPayments`.** The correct name is `PaymentMethods`.
+- **Confusing it with `PricingPaymentMethodsList`.** That one renders one product's installment plan from commerce data. This one renders the store's accepted brands from CMS content. The names are close and the components are unrelated.
+- **One element per flag.** One element renders the whole strip; each flag is an item in its content.
+- **Giving it children.** It is a leaf; the flags are content, which is what makes adding one a CMS save instead of a deployment.
+- **Expecting a `boleto` method name.** The dialect has no Boleto glyph — upload one through `iconUrl` and give the item a `label`.
+- **Setting `iconUrl` and `method` and expecting the glyph.** The upload wins; drop `iconUrl` to get the dialect glyph back.
+- **Shipping without the icon size swatch.** Predefined glyphs default to 24×24 and uploaded images to their natural size, so a mixed strip renders ragged until `data-fs-payment-method-icon` is sized.
+
+---
+
+## Styling
+
+`PaymentMethods` renders one root you style directly, plus per-part hooks. The glyph hook covers both the `<svg>` and the `<img>` path, which is what makes a mixed strip line up.
+
+| Component | What you style | Plausible classes |
+|---|---|---|
+| `PaymentMethods` | Stacks the heading over the strip | `flex flex-col gap-[12px]` |
+| `data-fs-payment-methods-heading` | The strip heading | `text-[14px] font-bold uppercase text-[#1a1a1a]` |
+| `data-fs-payment-methods-list` | The flag row, wrapping on narrow screens | `flex flex-wrap items-center gap-[8px] list-none p-0 m-0` |
+| `data-fs-payment-method` | The box one flag occupies | `flex items-center` |
+| `data-fs-payment-method-icon` | Both glyph paths, sized to match | `w-[40px] h-[26px] object-contain` |
+
+The list carries an explicit `role="list"`. Keep it: WebKit drops the implicit list role from a `<ul>` whose computed `list-style` is `none`, and `list-none` is exactly what the strip needs, so the attribute is what holds the semantics the named list was chosen for.
+
+`data-fs-payment-method-name` carries the enum member on each predefined item — `[data-fs-payment-method-name="pix"]` targets one brand, for a flag that needs its own treatment. It is absent on items with no `method`.
+
+Styled example:
+
+```json
+{
+  "footer-payment-methods": {
+    "type": "PaymentMethods",
+    "style": ["flex", "flex-col", "gap-[12px]"]
+  }
+}
+```
+
+---
+
+## Related
+
+- [[footer-root]] — the `<footer>` landmark the strip usually sits inside.
+- [[footer-link-group]] — the headed link columns beside it; same `$content` mechanics, text links instead of glyphs.
+- [[footer-copyright]] — the legal line below it; same `$content` mechanics, plain text.
+- [[incentives]] — the benefit strip usually above it; same `$content` mechanics, and the closest visual sibling — icon-and-copy blocks where these are bare brand marks.
+- [[footer-social]] — the profile-icon row beside it; the same two glyph paths and the same shared icon hook, but every mark links out and the strip's flags do not.
+- `PricingPaymentMethodsList` — one product's installment plan, from commerce data. Closest name in the library and the most common mix-up. It carries no `.md` of its own; read its schema from `catalog.json`.
+- `Icon` — the particle each predefined flag renders. It carries no `.md` of its own; read its schema from `catalog.json`.

package/dist/docs/phone-field.md

@@ -0,0 +1,106 @@
+# PhoneField
+
+**Category:** action
+**Purpose:** A presentational, country-aware phone input that composes the `Field` and `Input` particles (label + masked `<input type="tel">` + inline error). It owns per-country masking (US / BR, US fallback) and validates the number on blur. It is data-agnostic — value flows through props; it consumes no GraphQL and no domain context.
+
+---
+
+## Visual cues (how to identify in an image)
+
+- A single-line input labelled **"Phone"**, **"Telefone"**, or similar, showing a masked number: `(123) 456-7890` (US) or `(11) 99999-9999` (BR).
+- The mask formats digits as they are typed; a leading `+1` / `+55` appears for E.164 input.
+- When invalid, an inline error message below the input (e.g. *"Invalid phone number"* or *"Phone number is required"*).
+
+The image is the source of truth for layout. If the input is the profile phone of a checkout identity step (pre-filled, persisted), wrap it in `ClientProfilePhoneControl`; otherwise use `PhoneField` directly.
+
+---
+
+## When to use
+
+- A standalone, presentational phone input where the host owns the value and the persistence.
+- As the field rendered by `ClientProfilePhoneControl` (the checkout-bound wrapper).
+- Reused later in MyAccount / extensions — it carries no business logic.
+
+## When NOT to use
+
+- When the field must read/write the shopper profile → use `ClientProfilePhoneControl`, which wraps this particle.
+- For a generic non-phone text field → use the `Field` particle directly.
+
+---
+
+## Composition
+
+`PhoneField` is a single leaf particle. Internally it renders:
+
+```
+PhoneField                 (data-fs-phone-field-root + data-fs-phone-field-root-country)
+├── Field.Label            (data-fs-phone-field-label; the `label` prop)
+├── Input                  (data-fs-phone-field-input; masked <input type="tel" inputMode="numeric">)
+└── Field.Error            (data-fs-phone-field-error; shown when invalid)
+```
+
+With `requirement: 'hidden'` the particle renders `null` — no DOM node is emitted.
+
+---
+
+## Props
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `value` | string | — | Controlled raw (unmasked) value. Omit for uncontrolled use. |
+| `defaultValue` | string | `''` | Uncontrolled initial raw value (pre-fill). |
+| `onValueChange` | `(value: string) => void` | — | Fires on every change with the raw (unmasked) value. |
+| `country` | `'US' \| 'BR'` | `'US'` | Selects the mask and validation rule; other codes fall back to US. |
+| `label` | string | `'Phone'` | Accessible label. |
+| `isDisabled` | boolean | `false` | Disables the input (e.g. while a write is in flight). |
+| `placeholder` | string | — | Input placeholder. |
+| `invalid` | boolean | — | Host-forced invalid state; overrides the internal blur validation when set. |
+| `error` | string | — | Host-supplied error text; overrides the internal error string when set. |
+| `errorInvalid` | string | `'Invalid phone number'` | Inline error for an invalid format. |
+| `errorRequired` | string | `'Phone number is required'` | Inline error when a mandatory field is empty. |
+| `requirement` | `'mandatory' \| 'optional' \| 'hidden'` | `'mandatory'` | `mandatory`: empty blocks; `optional`: empty allowed, format still checked when present; `hidden`: renders `null`. |
+| `onBlur` | `() => void` | — | Fires on blur, after validation runs. |
+
+**Validation:** the number is checked on blur/submit only — never per keystroke. A prior error clears while the shopper edits and is re-evaluated on the next blur. Changing `country` resets the local validation state.
+
+**Known limitations:**
+
+- Country coverage is US/BR only; every other ISO-2 code falls back to the US mask and validation (Gap-06 in the PhoneField spec).
+- Cross-country values are not detected: a saved E.164 number from another country (e.g. `+5511999998888` rendered with `country="US"`) is masked and validated under the configured country's rules, so it displays badly formatted and blurs as invalid. The `country` prop must match the country of the stored number.
+
+---
+
+## Accessibility
+
+The label is associated with the input and the error is linked via `aria-describedby` automatically by the Base UI `Field` primitive (WCAG 2.1 AA). The input uses `type="tel"` and `inputMode="numeric"` for a numeric mobile keypad. Validation never blocks typing.
+
+---
+
+## Styling
+
+`PhoneField` owns no CSS. Style it via compound swatches / Tailwind targeting the `data-fs-*` attributes:
+
+| Target | What you style |
+|---|---|
+| `data-fs-phone-field-root` | The field container (stack the label, input, error). |
+| `data-fs-phone-field-root-country` | Country variant selector (`US` / `BR`) for country-specific tweaks. |
+| `data-fs-phone-field-label` | The label typography. |
+| `data-fs-phone-field-input` | The input box; use `data-invalid:` for the error border. |
+| `data-fs-phone-field-error` | The inline error text (small, red). |
+
+---
+
+## Common mistakes
+
+- **Validating on every keystroke.** Format validation runs on blur/submit only.
+- **Wiring GraphQL into this particle.** It is data-agnostic; use `ClientProfilePhoneControl` for the checkout-bound binding.
+- **Localizing via a message id.** There is no `react-intl`; pass `label` / `errorInvalid` / `errorRequired` as strings.
+- **Reading the masked value.** `onValueChange` emits the raw (unmasked) value — persist that, not the display string.
+
+---
+
+## Related
+
+- [[client-profile]] — the checkout-bound matter that binds this particle to the shopper `ClientProfile` and persists the phone.
+- [[email-field]] — the equivalent presentational identity particle for email.
+- [[field]] — the underlying form-field particle this composes.

package/dist/docs/postal-code-field.md

@@ -0,0 +1,126 @@
+# PostalCodeField
+
+**Category:** content
+**Purpose:** A presentational postal-code input that composes the `Field` and `Input` particles (label + native `<input>` + inline error). It formats the value against a configured mask template as the shopper types (e.g. CEP `00000-000`) and flags an incomplete value on blur. It is country-agnostic — the pattern is a `mask` prop, not a country table — and data-agnostic: the value, the submit, and the server's verdict belong to the host.
+
+---
+
+## Visual cues (how to identify in an image)
+
+- A single-line text input labelled **"Postal code"**, **"CEP"**, **"ZIP code"**, or the local equivalent, usually with a submit button beside or below it.
+- Shows a masked placeholder like `00000-000` and formats digits as they are typed.
+- Often inside a region/delivery modal opened from a header control, or as one field of an address form.
+- When invalid, an inline error below the input (e.g. *"Enter a complete postal code"*).
+
+The image is the source of truth for layout.
+
+---
+
+## When to use
+
+- Any postal-code entry where the host owns the value and the submit: a region modal, a delivery estimate, an address form.
+- As the postal-code field of a larger form that batches its own write.
+
+## When NOT to use
+
+- For a generic text field → use the `Field` particle directly.
+- For a tax document (CPF) → use `DocumentField`, which adds check-digit validation.
+- To own the region write or the shipping estimate → those belong to the host; this particle performs no mutation.
+
+---
+
+## Composition
+
+`PostalCodeField` is a single leaf particle. Internally it renders:
+
+```
+PostalCodeField            (data-fs-postal-code-field + inherited data-fs-field-root)
+├── Field.Label            (data-fs-postal-code-field-label; the `label` prop, omitted when empty)
+├── Input                  (data-fs-postal-code-field-input + data-fs-input; the masked control)
+└── Field.Error            (data-fs-postal-code-field-error; the `errorMessage`, shown when invalid)
+```
+
+---
+
+## Props
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `mask` | string | `'99999-999'` | Mask template: `9` digit, `A` alpha, `S` alphanumeric, `*` any, interleaved with literals. Pipe-delimited alternates (`99999\|99999-999`) cover formats of different lengths. Build-time configuration, not CMS-authored. |
+| `label` | string | — | Accessible label. The `<label>` element is omitted when no label resolves. |
+| `placeholder` | string | — | Input placeholder. |
+| `errorMessage` | string | — | Inline error text, shown when the field is invalid. |
+| `value` | string | — | Controlled value. Masked on render, so a raw value is accepted. |
+| `defaultValue` | string | `''` | Uncontrolled initial value, masked on mount. |
+| `onValueChange` | `(value: string) => void` | — | Fires on every change with the **masked** value. Use `stripPostalCodeMask` if the write path wants slot characters only. |
+| `onBlur` | `(event) => void` | — | Fires on blur, after the completeness verdict runs. |
+| `invalid` | boolean | `false` | Host-forced invalid state (e.g. a server rejection). ORs with the internal verdict — typing never clears it. |
+| `required` | boolean | `false` | Sets the native `required` attribute. |
+| `disabled` | boolean | `false` | Disables the field. |
+| `name` | string | `'postalCode'` | Field/input name. |
+| `aria-label` / `aria-labelledby` | string | — | Forwarded to the input, not to the wrapper. The way to name the control when no label resolves. |
+| `$content` | content entry | — | Merchant-authored `label`, `placeholder`, and `errorMessage`, all optional; each present, non-blank field wins over its prop — a blank one keeps the prop. |
+
+**Masking:** applied progressively on every change; input is never blocked, reordered, or rejected. Overflow past the mask's slot count is dropped. A mask whose slots are all `9` strips non-digits and hints `inputMode="numeric"`; one carrying any `A`, `S`, or `*` slot does neither. Masking is idempotent, so a raw pre-fill and an already-masked value display identically.
+
+**Verdict:** on blur, a non-empty value that does not fill every mask slot marks the field invalid and renders `errorMessage`. An empty value produces no verdict — emptiness is the host's submit-gating concern. The verdict clears on the next keystroke and is re-evaluated on the next blur. Semantic correctness (does this postal code exist, does it match the city) is the server's; postal codes carry no check digit.
+
+**Helpers:** `applyPostalCodeMask(value, mask)`, `stripPostalCodeMask(value, mask)`, and `isPostalCodeComplete(value, mask)` are exported so a host can gate its submit with the same rule instead of duplicating it.
+
+---
+
+## Accessibility
+
+The label is associated with the input and the error is linked via `aria-describedby` automatically by the Base UI `Field` primitive (WCAG 2.1 AA). `autocomplete="postal-code"` satisfies 1.3.5 Identify Input Purpose. Standard text-input keyboard editing: masking weaves literals into the value and never intercepts a key or moves the caret.
+
+The control needs a name: with no `label` and no `$content.label` no `Field.Label` renders, and a placeholder is not an accessible name. Name it with `aria-label` or `aria-labelledby` — both are forwarded to the input rather than to the wrapper.
+
+---
+
+## Canonical schema example
+
+```json
+{
+  "type": "PostalCodeField",
+  "id": "region-postal-code",
+  "props": {
+    "mask": "99999-999",
+    "label": "Postal code",
+    "placeholder": "00000-000",
+    "errorMessage": "Enter a complete postal code"
+  }
+}
+```
+
+The element `id` is the durable content key for the `postal-code-field` entry slice, so renaming it orphans the authored copy.
+
+---
+
+## Common mistakes
+
+- **Using `ZipCodeField` or `CepField`.** The correct name is `PostalCodeField`.
+- **Passing a country code instead of a pattern.** There is no `country` prop — set `mask` to the country's format.
+- **Expecting server validation here.** The field only reports "this does not fill the pattern"; the host surfaces the server verdict through `invalid` + `errorMessage`.
+- **Treating an empty field as invalid.** Empty produces no verdict; the host decides whether an empty submit is blocked.
+- **Authoring the mask in the CMS.** Only `label`, `placeholder`, and `errorMessage` are content; the mask is a build-time prop.
+
+---
+
+## Styling
+
+`PostalCodeField` owns no CSS. Style it via compound swatches / Tailwind targeting the `data-fs-*` attributes:
+
+| Target | What you style | Plausible classes |
+|---|---|---|
+| `data-fs-postal-code-field` | The field container (stacks label, input, error) | `flex flex-col gap-[8px]` |
+| `data-fs-postal-code-field-label` | The label typography | `text-[13px] font-semibold text-[#1a1a1a]` |
+| `data-fs-postal-code-field-input` | The input box; compose with `data-invalid`, `data-focused`, `data-disabled` | `h-11 rounded-lg border border-[#d4d4d4] px-4 text-[15px]` |
+| `data-fs-postal-code-field-error` | The inline error text | `text-[12px] text-[#c1272d]` |
+
+---
+
+## Related
+
+- [[document-field]] — the sibling masked field for tax documents; shares this mask engine, adds check-digit validation.
+- [[phone-field]] — the sibling masked field for phone numbers; selects its format by country instead of a pattern.
+- [[field]] — the underlying form-field particle this composes.