@vtex/faststore 0.0.1

package/dist/docs/navigation-link-list.md

@@ -0,0 +1,171 @@
+# NavigationLinkList
+
+**Category:** navigation
+**Purpose:** The navigation's whole link list as one CMS-editable collection — a merchant adds, removes and reorders links without a deployment. The list arrives through the compiler-injected `$content` prop, backed by the `navigation-link-list` content model declared next to the component; the `links` prop is the authored fallback for stores with no CMS binding. It owns its own `<ul>`, so one element renders the entire list and takes no children.
+
+---
+
+## Visual cues (how to identify in an image)
+
+The image is the source of truth for layout. A NavigationLinkList is present when you see:
+
+- A **horizontal row of plain text links** in a header band — *Ofertas*, *Novidades*, *Marcas*, *Atendimento* — with no thumbnails and no price.
+- The **same set of links stacked vertically** inside a slide-in panel behind a hamburger button, on a narrow screen.
+- Links that are **siblings of equal weight**, not a heading over a list — that distinguishes it from [[footer-link-group]].
+- **No chevrons or dropdown arrows** on the items. A row whose items open panels on hover is `NavigationMenu` composing its flyout parts instead.
+
+---
+
+## When to use
+
+- The header's main navigation, on both the desktop bar and the mobile drawer panel.
+- Any list of navigation links whose *membership* a merchant must control from the CMS.
+- One element for the whole list. Four links in the image is still one `NavigationLinkList`.
+
+## When NOT to use
+
+- A **single** link — a logo link, an account link, one call to action → use `NavigationLink`.
+- A **headed** list of institutional links in a footer → use [[footer-link-group]]; it carries the heading and the mobile accordion with it.
+- A navigation whose items **open flyout panels** → compose `NavigationMenu` with `NavigationMenuTrigger` and `NavigationMenuContent`; this list has no panels.
+- A row of **social or payment icons** → use [[footer-social]] or `PaymentMethods`; those carry glyphs, not text labels.
+- A list whose links need **individually different styling or placement** → author one `NavigationLink` element each. Membership then costs a deployment, which is the trade.
+
+---
+
+## Composition
+
+`NavigationLinkList` is a leaf in the schema — no sub-components, no children. The links are content, not child elements.
+
+It renders one `<ul>` and nothing above it, which is what lets the same element serve both header surfaces:
+
+```
+layout-header
+├─ nav-desktop (Container, $desktop-only)
+│   └─ NavigationMenuRoot
+│       └─ NavigationLinkList     ← the shared element: nav > ul > li
+└─ nav-mobile (Container, $mobile-only)
+    └─ DrawerRoot
+        ├─ DrawerTrigger
+        └─ DrawerPortal
+            └─ DrawerPopup
+                └─ NavigationLinkList     ← the same element id: ul > li, no second landmark
+```
+
+**Reference one element from both parents.** A layout is a flat map of id to element and `children` holds ids, so the same `NavigationLinkList` id belongs in the desktop subtree and in the drawer's. The element id is the CMS content key, so sharing gives **one entry, one edit, both surfaces**. Authoring two elements also compiles and is the mistake to avoid: it makes two entries a merchant must keep in sync for one list a shopper sees once.
+
+**Do not wrap it in `NavigationMenuList`.** That part is Base UI's own `<ul>`, so nesting produces `<ul><ul>`. Compose this list directly under `NavigationMenuRoot`, which supplies the `nav` landmark. `NavigationMenuList` and `NavigationMenuItem` belong to the hand-authored form, where one `NavigationLink` element is composed per item.
+
+**Content, then prop.** The list resolves from the CMS entry first and the `links` prop second. An entry supplying an empty list wins over an authored list — a merchant who cleared the links cleared them. The Admin form itself asks for at least one link (`minItems: 1`), so that empty list arrives from a host that authors the entry directly rather than from a save; nothing enforces the bound at read time. When no renderable link survives, the component renders `null`, leaving the surrounding `nav` landmark empty rather than throwing. Non-compiler hosts (Storybook, tests) pass a typed `$content` fixture directly.
+
+**A malformed link costs the whole list.** Each link's `label` and `href` are required, so the content runtime omits this component — before any prop is consulted — when the entry holds a link missing either field. Worth knowing when the navigation disappears right after a CMS save. `links` itself is not required, so an entry that has not been filled in yet falls back to the authored list instead of omitting the navigation.
+
+---
+
+## Components
+
+### NavigationLinkList
+
+| Prop | Type | Required | Notes |
+|-------|------|----------|-------|
+| `links` | array | no | Authored fallback list of `{ label, href, target? }`. Ignored when a CMS entry supplies `links` |
+
+Content model (`navigation-link-list`) fields, edited in the CMS:
+
+| Field | Type | Required | Notes |
+|-------|------|----------|-------|
+| `links` | array | no | Ordered links. Adding, removing or reordering here changes the navigation with no deployment. Optional so an unfilled entry falls back to the authored list |
+| `links[].label` | string | yes | Link text. A blank label drops that link — an anchor with no name is unusable |
+| `links[].href` | string | yes | Destination. `http:`, `https:`, `mailto:`, `tel:`, or a path starting with a single `/` |
+| `links[].target` | `_self` \| `_blank` | no | `_blank` opens a new tab and adds `rel="noopener noreferrer"` automatically. Write an "(opens in new tab)" cue into the label — the component announces nothing on its own |
+
+---
+
+## Canonical schema example
+
+One element, referenced from both surfaces:
+
+```json
+{
+  "nav-desktop": { "type": "Container", "style": ["$desktop-only"], "children": ["nav-menu"] },
+  "nav-menu": {
+    "type": "NavigationMenuRoot",
+    "props": { "orientation": "horizontal" },
+    "children": ["nav-links"]
+  },
+  "nav-links": {
+    "type": "NavigationLinkList",
+    "props": {
+      "links": [
+        { "label": "Ofertas", "href": "/collection/ofertas" },
+        { "label": "Novidades", "href": "/collection/novidades" }
+      ]
+    },
+    "style": ["flex", "items-center", "gap-[24px]", "list-none", "m-0", "p-0"]
+  },
+  "nav-mobile": { "type": "Container", "style": ["$mobile-only"], "children": ["nav-drawer"] },
+  "nav-drawer": {
+    "type": "DrawerRoot",
+    "props": { "swipeDirection": "left", "modal": true },
+    "children": ["nav-trigger", "nav-portal"]
+  },
+  "nav-trigger": { "type": "DrawerTrigger", "props": { "children": "Menu" } },
+  "nav-portal": { "type": "DrawerPortal", "children": ["nav-popup"] },
+  "nav-popup": { "type": "DrawerPopup", "children": ["nav-links"] }
+}
+```
+
+`nav-links` appears in two `children` arrays and is defined once. The element id is the content key, so name it for the navigation rather than for either surface — renaming it orphans the merchant's entry.
+
+---
+
+## Common mistakes
+
+- **One element per link.** This component is the whole list; the links are content, which is what makes adding one a CMS save instead of a deployment. Per-link elements are the other form, built from `NavigationLink`.
+- **`NavigationLinks`, `NavigationList`, `NavLinkList`, `NavigationMenuLinks`.** The correct name is `NavigationLinkList`.
+- **Nesting it in `NavigationMenuList`.** It brings its own `<ul>`; put it directly under `NavigationMenuRoot`.
+- **Authoring it twice, once per surface.** Reference one element id from both `children` arrays instead, or the merchant edits two entries for one list.
+- **Putting it in the drawer under a second `NavigationMenuRoot`.** That adds a second `nav` landmark. The drawer panel wants the bare list.
+- **Looking for a `direction`, `orientation` or `isMobile` prop.** There is none: the row and the stack are the store's swatches on the same markup.
+- **Giving it children.** It is a leaf and ignores them.
+- **Passing `rel` yourself for a new-tab link.** `target: "_blank"` already adds `rel="noopener noreferrer"`.
+- **Expecting a bare `#anchor`, a query-only `?q=1`, or a relative `ofertas` to link.** Only the four schemes and single-slash paths above become anchors; anything else keeps its label and renders as plain text.
+
+---
+
+## Styling
+
+The component ships no list reset, so `list-none m-0 p-0` on the list hook is the store's to supply in both surfaces.
+
+| Component | What you style | Plausible classes |
+|---|---|---|
+| `NavigationLinkList` | The `<ul>`: direction, gap and the list reset | `flex items-center gap-[24px] list-none m-0 p-0` |
+| `data-fs-navigation-link-list-item` | The box one link occupies | `shrink-0` |
+| `data-fs-navigation-link-list` `[data-fs-navigation-link]` | A link's typography | `text-[13px] font-medium uppercase no-underline hover:underline` |
+| `data-fs-navigation-link-list-text` | A refused destination, rendered as text | `text-[13px] text-[#999999]` |
+
+**The two surfaces style one element.** A shared element carries a single `style` array, so where the bar and the panel need different looks the *ancestor* reaches in with a descendant variant rather than the list carrying both:
+
+```json
+"nav-popup": {
+  "type": "DrawerPopup",
+  "style": [
+    "[&_[data-fs-navigation-link-list]]:flex-col",
+    "[&_[data-fs-navigation-link-list]]:gap-[8px]",
+    "[&_[data-fs-navigation-link]]:block",
+    "[&_[data-fs-navigation-link]]:px-[20px]",
+    "[&_[data-fs-navigation-link]]:py-[12px]"
+  ],
+  "children": ["nav-links"]
+}
+```
+
+The list itself then authors the desktop look, and the drawer overrides the axis and spacing for its copy.
+
+---
+
+## Related
+
+- `NavigationLink` — one link on its own, and the particle each item here renders. Use it directly when a link needs its own placement or styling.
+- `NavigationMenu` — the hover/focus menu primitive. `NavigationMenuRoot` supplies the `nav` landmark this list sits in; its `List` and `Item` parts belong to the per-link form instead.
+- [[footer-link-group]] — the footer's equivalent: same `$content` collection mechanics and the same link check, plus a heading and its own mobile accordion.
+- `Drawer` — the panel primitive the mobile surface composes. It carries no `.md` of its own; read its schema from `catalog.json`.

package/dist/docs/navigation-link.md

@@ -0,0 +1,163 @@
+# NavigationLink
+
+**Category:** navigation
+**Purpose:** Client-side navigation link built on Next.js Link. Renders a single `<a>` and moves the shopper between routes without a full-page reload. Carries no commerce data of its own.
+
+---
+
+## Visual cues (how to identify in an image)
+
+`NavigationLink` is a leaf: one piece of clickable text pointing somewhere else. The image is the source of truth for layout.
+
+Reach for it when the image shows:
+
+- A **text label styled differently from the surrounding copy** — a different color, an underline, or a weight that marks it as clickable.
+- A **row or column of such labels** acting as a menu: a header nav bar, a footer link column, a sidebar list of categories.
+- A **standalone call to action that reads as navigation** rather than a button, such as "continue shopping" or "see all".
+- A label followed by an **external-link glyph or an "(opens in new tab)" cue**, which signals `target: "_blank"`.
+
+A label drawn as a filled or outlined rectangle is a button, not a link. Judge by how it is drawn, not by what it says.
+
+---
+
+## When to use
+
+- Any route-to-route navigation inside the store: header menu items, footer links, category shortcuts, "continue shopping" on a cart page.
+- Links to destinations outside the store, paired with `target: "_blank"`.
+
+## When NOT to use
+
+- **Links inside a `NavigationMenu` flyout panel** — use `NavigationMenuLink`. It closes the open menu as it navigates, which this particle does not do; a `NavigationLink` inside `NavigationMenuContent` leaves the panel hanging open over the destination.
+- **Breadcrumb trail items** — use `BreadcrumbLink`, which reads its label and URL from the breadcrumb data instead of from authored props.
+- **Wrapping a brand logo** — use `Logo`, which already composes this particle around the image. Wrapping it in another link nests one anchor inside another, which is invalid HTML.
+- **Anything that changes state** (add to cart, apply a coupon, submit a form) — a link navigates and never mutates. Use `Button` with the matching `$actions.*` call.
+- **Closing a drawer or dialog** — use `DrawerClose` / `DialogClose`. Those dismiss an overlay; they do not navigate.
+- **Switching panels inside the same page** — that is `TabsTab`. A link changes the route; a tab does not.
+
+---
+
+## Composition
+
+`NavigationLink` is a leaf. It has no required parent, no children elements, and provides no context. The link text is authored as a **string `children` prop**, not as a child element.
+
+```text
+Container
+├── NavigationLink   ← label comes from props.children
+├── NavigationLink
+└── NavigationLink
+```
+
+Sibling links share the same `children` array on the parent, and their order reflects the visual order of the group.
+
+---
+
+## Components
+
+### NavigationLink
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `href` | `string` | — | Destination. An internal path (`/collection/sale`) keeps client-side navigation; an absolute URL (`https://…`) leaves the store. |
+| `target` | `_self` \| `_blank` | `_self` | `_blank` opens the destination in a new tab. The component then adds `noopener` and `noreferrer` to the anchor's `rel` on its own. |
+| `children` | `string` | — | The link text. This is also the link's accessible name, so it has to describe the destination on its own. |
+
+`rel` is deliberately not authorable. The tab-nabbing defense is the component's responsibility, not the author's.
+
+Content model (`navigation-link`) fields, edited in the CMS:
+
+| Field | Type | Required | Notes |
+|-------|------|----------|-------|
+| `text` | string | yes | The link label |
+| `href` | string | no | Cleared, absent, or outside the allowlist keeps the authored `href` |
+| `target` | `_self` \| `_blank` | no | Absent keeps the authored `target` |
+
+**Props and content both work.** The props stay the authoring surface, and a CMS entry overrides them field by field, so a merchant can retitle a link or repoint it without a deploy. A store with no CMS binding receives no `$content` and renders from the props alone. The safety `rel` follows the *resolved* target, so a `_blank` that arrives from the CMS is defended exactly like an authored one — but the "(opens in new tab)" cue lives in the label, which means a merchant who switches a link to `_blank` has to write that cue into `text` themselves.
+
+The model constrains `href` as a `uri-reference` rather than a `uri`, which would reject the root-relative paths (`/collection/sale`) most navigation destinations are. That constraint and its pattern are author-time guidance for the Admin form; the pattern also admits an empty value, so clearing the field to fall back on the authored `href` stays valid.
+
+**A destination from the CMS that is not a plain web address is refused.** Only `http:`, `https:`, `mailto:`, `tel:`, and single-slash site-relative paths reach the anchor; anything else — a `javascript:` URL, a protocol-relative `//host` — falls back to the authored `href` and logs the reason. No read-time validator enforces a URL pattern, so this is the only gate on the value the CMS supplied. The `href` prop is not gated: it comes from the store's own source, not from the Admin.
+
+---
+
+## Canonical schema example
+
+A group of store links — three internal, one external opening in a new tab. `Container` here is the generic wrapper that groups the links inside the page's centered column; it is not a menu bar component, and the links are plain siblings in its `children` array:
+
+```json
+{
+  "link-group": {
+    "type": "Container",
+    "children": ["nav-sale", "nav-new", "nav-brands", "nav-partner"]
+  },
+  "nav-sale":   { "type": "NavigationLink", "props": { "href": "/collection/sale", "children": "Sale" } },
+  "nav-new":    { "type": "NavigationLink", "props": { "href": "/collection/new-in", "children": "New in" } },
+  "nav-brands": { "type": "NavigationLink", "props": { "href": "/collection/brands", "children": "Brands" } },
+  "nav-partner": {
+    "type": "NavigationLink",
+    "props": {
+      "href": "https://partner.example/loyalty",
+      "target": "_blank",
+      "children": "Loyalty program (opens in new tab)"
+    }
+  }
+}
+```
+
+When you author `target: "_blank"`, write the "(opens in new tab)" cue into `children` as shown. The component adds no announcement of its own, so the link text is the only warning a shopper gets before the store disappears behind a new tab.
+
+---
+
+## Common mistakes
+
+- **`Link`, `Anchor`, `NavLink`, or `MenuLink`.** The correct name is `NavigationLink`.
+- **Confusing it with `NavigationMenuLink`.** The names are one word apart and the components are not interchangeable: `NavigationMenuLink` belongs inside `NavigationMenuContent` and dismisses the flyout on navigation, while `NavigationLink` is the standalone link used everywhere else.
+- **Authoring a `rel` prop.** It is not part of the schema. For `target: "_blank"` the component already emits `noopener noreferrer`.
+- **Authoring `$content` in the schema.** `$content` is compiler-injected from the page's or layout's content entry; naming it in `props` fails the build.
+- **Authoring `target: "_blank"` with a bare label.** Add the "(opens in new tab)" cue to `children`; without it the change of context is silent.
+- **Using `NavigationLink` for breadcrumb items.** The breadcrumb trail composes `BreadcrumbLink`, which is fed by breadcrumb data.
+- **Wrapping the label in a `Text` child.** The label is a string prop: `"props": { "children": "Sale" }`, not a nested `Text` element.
+- **Using a link to trigger a cart action.** Navigation is not a mutation.
+
+---
+
+## Styling
+
+`NavigationLink` renders one `<a>`, so there is a single element to style: the label itself. Read the color, size, and weight off the image, and add the hover treatment the design implies.
+
+| Component | What you style | Plausible classes |
+|---|---|---|
+| `NavigationLink` | The label — typography, color, and hover affordance | `text-[14px] leading-[1.4] font-medium text-[#1A1A1A] no-underline hover:underline` |
+
+The spacing between links belongs to the parent that groups them, not to the link. Give that parent the `flex` and `gap-[*]` classes and keep each link to typography and color.
+
+Styled example of a row of links:
+
+```json
+{
+  "link-group": {
+    "type": "Container",
+    "children": ["nav-sale", "nav-new"],
+    "style": ["flex", "flex-row", "items-center", "gap-[24px]"]
+  },
+  "nav-sale": {
+    "type": "NavigationLink",
+    "props": { "href": "/collection/sale", "children": "Sale" },
+    "style": ["text-[14px]", "leading-[1.4]", "font-medium", "text-[#1A1A1A]", "no-underline", "hover:underline"]
+  },
+  "nav-new": {
+    "type": "NavigationLink",
+    "props": { "href": "/collection/new-in", "children": "New in" },
+    "style": ["text-[14px]", "leading-[1.4]", "font-medium", "text-[#1A1A1A]", "no-underline", "hover:underline"]
+  }
+}
+```
+
+---
+
+## Related
+
+- `NavigationMenuLink` — the anchor for links inside a `NavigationMenu` flyout; it dismisses the panel on navigation, which this particle does not.
+- `BreadcrumbLink` — the trail variant, built on this particle but fed by breadcrumb data rather than authored props.
+- [[logo]] — the brand mark that composes this particle internally; use it for the header logo instead of linking an image by hand.
+- [[cart]] — `CartGoCheckout` is the checkout link built on this particle; on a cart page a plain `NavigationLink` is what sends the shopper back to browsing.
+- [[tabs]] — switches panels within one page, where this particle changes the route.

package/dist/docs/navigation-menu.md

@@ -0,0 +1,264 @@
+# NavigationMenu
+
+**Category:** layout
+**Purpose:** Site navigation primitive. Wraps Base UI's NavigationMenu to give a `nav` landmark, list semantics, keyboard support, and optional animated flyout panels. Composes in two shapes: a **flat bar** of links, or a **flyout menu** with panels per entry.
+
+---
+
+## Visual cues (how to identify in an image)
+
+A NavigationMenu is present when you see a **set of navigation labels grouped as a bar or column**, usually in the header, pointing at categories or institutional pages.
+
+Which shape to compose depends on one thing only — **does an entry reveal a panel?**
+
+- **Flat bar** — the labels are plain text with nothing attached. No chevrons, no dropdown shadow, no hint of a panel. This is the common storefront header: `Sale`, `New in`, `Brands`.
+- **Flyout menu** — at least one label carries a **chevron / caret**, or the image shows an **open panel** below or beside a label holding sub-links, columns, or promotional tiles.
+
+If the image shows no panel and no chevron, compose the flat bar. Adding the flyout parts "just in case" ships a menu that never opens.
+
+---
+
+## When to use
+
+- The store's main navigation: a header bar of category links, with or without panels.
+- A vertical navigation column that behaves as site navigation (set `orientation: "vertical"`).
+
+## When NOT to use
+
+- **A single link on its own** — use `NavigationLink`. The landmark and list semantics only earn their keep for a group.
+- **Switching panels inside one page** — that is [[tabs]]. Navigation changes the route; a tab does not.
+- **The mobile menu panel** — use the `Drawer` particle with the same links inside. Desktop bar and mobile drawer are two compositions selected by a responsive class, not one component with a mode prop.
+- **The breadcrumb trail** — use `BreadcrumbLink`, fed by breadcrumb data.
+- **A menu of actions** (sort, filter, account actions) — those mutate or filter rather than navigate.
+
+---
+
+## Composition
+
+`NavigationMenuRoot` renders the `<nav>` landmark. Everything else is optional depending on the shape.
+
+**Flat bar** — three parts, nothing else:
+
+```text
+NavigationMenuRoot
+└── NavigationMenuList          (the <ul>)
+    └── NavigationMenuItem      (one <li> per entry)
+        └── NavigationLink      (the anchor; client-side navigation)
+```
+
+**Flyout menu** — the list gains a trigger and content per entry, and the Portal chain frames the panel:
+
+```text
+NavigationMenuRoot
+├── NavigationMenuList
+│   └── NavigationMenuItem            (unique `value` per entry)
+│       ├── NavigationMenuTrigger     (the button that opens the panel)
+│       │   └── NavigationMenuIcon    (optional chevron; rotates via data-open)
+│       └── NavigationMenuContent     (the panel body — inside Item, not Portal)
+│           └── NavigationMenuLink    (anchors that dismiss the panel as they navigate)
+└── NavigationMenuPortal              (sibling of List, teleports to <body>)
+    └── NavigationMenuPositioner
+        └── NavigationMenuPopup
+            ├── NavigationMenuArrow   (optional)
+            └── NavigationMenuViewport
+```
+
+**Composition rules:**
+
+- `NavigationMenuContent` goes inside `NavigationMenuItem`, alongside its `NavigationMenuTrigger`. The Portal does **not** hold the content; it renders the animated Popup that frames whichever content is active.
+- All panels share one `NavigationMenuViewport`, which is what animates smoothly between entries.
+- The Portal chain is only needed when at least one entry has content. The flat bar omits it entirely.
+- Child order reflects visual order.
+
+---
+
+## Components
+
+### NavigationMenuRoot
+
+Renders the `<nav>` landmark and manages hover/focus open state across entries.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `orientation` | `'horizontal' \| 'vertical'` | `"horizontal"` | Arrow-key axis and layout direction |
+| `delay` | number | `50` | Milliseconds before a hovered entry opens |
+| `closeDelay` | number | `50` | Milliseconds before an unhovered panel closes |
+
+**This part takes no `style`.** It accepts no `className` and emits no `data-fs-*` attribute, so there is no hook to attach a swatch to. Put the bar's layout classes on the `NavigationMenuList`. Responsive visibility belongs on a `Container` wrapping the whole root, never on the list: hiding the list leaves the `nav` landmark rendered and announced with nothing inside it.
+
+### NavigationMenuList
+
+The `<ul>` holding every entry. Owns the bar's own layout — direction, gap, alignment.
+
+No schema props. Styleable via `data-fs-navigation-menu-list`.
+
+### NavigationMenuItem
+
+One `<li>` per entry.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `value` | string | — | Keys the open panel. Optional: Base UI generates an id when it is omitted |
+
+Author a `value` anyway. It keeps the emitted markup deterministic instead of carrying a generated id the schema does not control, and a flyout entry needs a stable key.
+
+### NavigationMenuTrigger
+
+The `<button>` that opens an entry's panel. Only for the flyout shape — a flat bar has no trigger, because there is nothing to open.
+
+### NavigationMenuIcon
+
+Decorative chevron inside a trigger. Rotates via `data-open`, so animate it with the `data-[open]` attribute selector.
+
+### NavigationMenuContent
+
+An entry's panel body. Lives inside `NavigationMenuItem`; rendered into the Viewport through the Portal.
+
+### NavigationMenuLink
+
+Anchor **for links inside a panel**. It dismisses the open panel as it navigates, which a plain link does not — a `NavigationLink` inside a panel leaves it hanging open over the destination.
+
+It is a plain `<a>`, so it costs a full-page reload. In a flat bar, where there is no panel to dismiss, use `NavigationLink` instead for client-side navigation and its `target` support.
+
+### NavigationMenuPortal
+
+Teleports the positioner to `<body>`. Wraps `NavigationMenuPositioner`. Takes only children.
+
+### NavigationMenuPositioner
+
+Places the popup relative to the active entry.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `side` | `'top' \| 'bottom' \| 'left' \| 'right'` | `"bottom"` | Which edge of the trigger the popup sits on |
+| `align` | `'start' \| 'center' \| 'end'` | `"center"` | Alignment along that edge |
+| `sideOffset` | number | `0` | Gap in pixels between trigger and popup |
+
+### NavigationMenuPopup
+
+The animated container that frames the viewport. Where the panel's background, border, radius and shadow go.
+
+### NavigationMenuArrow
+
+Optional pointer tying the popup to its trigger.
+
+### NavigationMenuViewport
+
+Shared animation container inside the popup. Every entry's content renders through it, which is what makes moving between entries animate rather than cut.
+
+---
+
+## Canonical schema example
+
+The storefront header's desktop bar — the flat shape. Note what is absent: no trigger, no content, no portal chain.
+
+```json
+{
+  "nav-desktop": {
+    "type": "NavigationMenuRoot",
+    "children": ["nav-list"]
+  },
+  "nav-list": {
+    "type": "NavigationMenuList",
+    "style": ["flex", "flex-row", "items-center", "gap-[24px]", "list-none", "m-0", "p-0"],
+    "children": ["nav-item-sale", "nav-item-new"]
+  },
+  "nav-item-sale": { "type": "NavigationMenuItem", "props": { "value": "sale" }, "children": ["nav-link-sale"] },
+  "nav-item-new": { "type": "NavigationMenuItem", "props": { "value": "new-in" }, "children": ["nav-link-new"] },
+  "nav-link-sale": {
+    "type": "NavigationLink",
+    "props": { "href": "/collection/sale", "children": "Sale" },
+    "style": ["text-[14px]", "font-medium", "text-[#1A1A1A]", "no-underline", "hover:underline"]
+  },
+  "nav-link-new": {
+    "type": "NavigationLink",
+    "props": { "href": "/collection/new-in", "children": "New in" },
+    "style": ["text-[14px]", "font-medium", "text-[#1A1A1A]", "no-underline", "hover:underline"]
+  }
+}
+```
+
+### Flyout variant (one entry with a panel)
+
+```json
+{
+  "nav-root": { "type": "NavigationMenuRoot", "children": ["nav-list", "nav-portal"] },
+  "nav-list": {
+    "type": "NavigationMenuList",
+    "style": ["flex", "flex-row", "items-center", "gap-[24px]", "list-none", "m-0", "p-0"],
+    "children": ["nav-item-clothing"]
+  },
+  "nav-item-clothing": {
+    "type": "NavigationMenuItem",
+    "props": { "value": "clothing" },
+    "children": ["nav-trigger-clothing", "nav-content-clothing"]
+  },
+  "nav-trigger-clothing": {
+    "type": "NavigationMenuTrigger",
+    "props": { "children": "Clothing" },
+    "style": ["flex", "items-center", "gap-[4px]", "text-[14px]"],
+    "children": ["nav-icon-clothing"]
+  },
+  "nav-icon-clothing": { "type": "NavigationMenuIcon", "style": ["data-[open]:rotate-180"] },
+  "nav-content-clothing": {
+    "type": "NavigationMenuContent",
+    "style": ["grid", "grid-cols-2", "gap-[12px]", "p-[16px]", "w-[320px]"],
+    "children": ["nav-panel-shirts", "nav-panel-jeans"]
+  },
+  "nav-panel-shirts": {
+    "type": "NavigationMenuLink",
+    "props": { "href": "/collection/shirts", "children": "Shirts" },
+    "style": ["block", "text-[14px]"]
+  },
+  "nav-panel-jeans": {
+    "type": "NavigationMenuLink",
+    "props": { "href": "/collection/jeans", "children": "Jeans" },
+    "style": ["block", "text-[14px]"]
+  },
+  "nav-portal": { "type": "NavigationMenuPortal", "children": ["nav-positioner"] },
+  "nav-positioner": { "type": "NavigationMenuPositioner", "props": { "sideOffset": 8 }, "children": ["nav-popup"] },
+  "nav-popup": {
+    "type": "NavigationMenuPopup",
+    "style": ["bg-white", "border", "border-[#E5E5E5]", "rounded-[8px]", "shadow-lg", "overflow-hidden"],
+    "children": ["nav-viewport"]
+  },
+  "nav-viewport": { "type": "NavigationMenuViewport" }
+}
+```
+
+---
+
+## Common mistakes
+
+- **Styling `NavigationMenuRoot`.** It takes no `className` and emits no `data-fs-*` hook. Put the bar's layout on `NavigationMenuList`, and anything that has to style or hide the whole block on a wrapping `Container`.
+- **Composing the flyout parts for a plain bar.** A `Trigger`, `Portal`, `Positioner`, `Popup` and `Viewport` with no `Content` build a menu that can never open. If the image shows no panel, stop at `Item > NavigationLink`.
+- **Putting `NavigationMenuContent` inside the Portal.** Content belongs inside its `NavigationMenuItem`, next to the trigger. The Portal holds the Popup that frames it.
+- **Using `NavigationLink` inside a panel.** Use `NavigationMenuLink` there; it dismisses the panel as it navigates. Conversely, using `NavigationMenuLink` in a flat bar costs a full-page reload for no benefit.
+- **Duplicate `value` across items in one root.** Each entry needs its own; opening one would otherwise open both.
+- **A `Viewport` per entry.** There is one shared viewport inside the popup. Per-entry viewports break the transition between entries.
+- **Inventing `Navbar`, `NavMenu`, `NavigationBar` or `NavigationMenuListItem`.** The names are exactly `NavigationMenuRoot`, `NavigationMenuList`, `NavigationMenuItem`, and so on. There is no Navbar component — the bar *is* this composition.
+- **Reaching for this particle to hold the mobile menu.** The mobile panel is a `Drawer`; both shapes wrap the same links.
+
+---
+
+## Styling
+
+| Component | What you style | Plausible classes |
+|---|---|---|
+| `NavigationMenuList` | The bar itself — direction, gap, alignment, list reset | `flex flex-row items-center gap-[24px] list-none m-0 p-0` |
+| `NavigationMenuItem` | Rarely styled; per-entry spacing if the gap is uneven | `shrink-0` |
+| `NavigationMenuTrigger` | The label and its hit area | `flex items-center gap-[4px] px-[12px] py-[8px] text-[14px]` |
+| `NavigationMenuIcon` | The chevron and its open-state rotation | `text-[10px] transition-transform data-[open]:rotate-180` |
+| `NavigationMenuContent` | The panel's internal layout | `grid grid-cols-2 gap-[12px] p-[16px] w-[320px]` |
+| `NavigationMenuPopup` | The panel's frame — background, border, radius, shadow | `bg-white border border-[#E5E5E5] rounded-[8px] shadow-lg` |
+
+The link labels themselves are styled on the links, not here. `NavigationMenuRoot` has no styling surface at all.
+
+---
+
+## Related
+
+- [[navigation-link]] — the anchor the flat bar composes; gives client-side navigation, `target` support, and a CMS-editable label.
+- `Drawer` — the mobile counterpart. The header pairs a flat bar with a drawer holding the same links, switching between them by responsive class. It has no doc of its own yet; read its `catalog.json` guideline strings.
+- [[tabs]] — switches panels within one page, where this particle changes the route.
+- [[container]] — the generic wrapper used when the whole navigation block needs styling or responsive visibility, which the root cannot take.