# pd-components > Unstyled, composable, framework-agnostic navigation custom elements (light DOM, no Shadow DOM) > for Shopify Online Store themes — or any website. Interaction wiring is Invoker Commands first > (command/commandfor); configuration is pure HTML attributes; styling is entirely yours (vanilla > CSS or Tailwind); WCAG 2.2 AA is normative. One runtime dependency (invokers-polyfill, loaded > only where the platform lacks CommandEvent). Elements: pd-nav, pd-nav-panel, pd-drawer, pd-drilldown, pd-drilldown-panel, pd-disclosure (accordion via group attributes), pd-filter, pd-filter-status, pd-header, pd-sticky-stack, pd-sticky, pd-dynamic-grid (also the standalone carousel). Installation: pd-components is not published to npm. In a theme repository, use `bun x @prosper-digital-au/create-theme components add `; it vendors selected sets into Vite themes or use `--bundle-only` for a plain theme. Without create-theme, build this repository with `npm ci && npm run build`, then copy `dist/pd-components.js` into site assets as a self-defining module script (~11 kB gzip). Source: https://github.com/prosper-digital-au/pd-components --- # pd-components — Design Specification (v2) **This document is the contract.** Every component, test, and docs page must conform to it. If an implementation needs to deviate, the deviation must be written back into this file. ## 1. What this library is A set of **unstyled, composable, framework-agnostic custom elements** (light DOM) that provide the *behavior and accessibility* of storefront navigation. Interaction wiring is **declarative-first**, built on the HTML Invoker Commands API (`command` / `commandfor`) with a bundled polyfill. ### 1.1 Composition map (breadth-first) ``` Layer 0 — platform primitives (no library elements involved)

…

``` - The element **is** the panel (no trigger/panel wrappers). `ensureId` if missing. - Handles `--pd-toggle/--pd-open/--pd-close`. Syncs `aria-expanded` on all invokers (immediately at logical flip, not after animation). Keyboard = native button. State/visibility per §3. - Accordion = several disclosures as siblings; exclusivity opt-in: `group="name"` attribute — opening one closes other connected disclosures with the same group name (document scope, cancelable close). There is deliberately **no wrapper element** (hard rule: attributes over wrappers; Base UI's accordion is likewise its collapsible + grouping). Per the current APG Accordion pattern, no arrow-key/Home/End navigation is required — Tab + native Enter/Space fully satisfy it. - Within a group, `collapsible="false"` (on any member) keeps ≥1 panel open: the sole open member's `hide()` is vetoed (returns `false`) and its invokers get `aria-disabled="true"` — never native `disabled`; APG keeps the trigger tabbable. Released the moment another member opens. Direct `open`-attribute mutation still bypasses (§3). - Height animation is pure CSS via the grid-rows `0fr → 1fr` recipe (docs) — interpolable, Baseline, measurement-free. A measured `--pd-panel-height` property was evaluated and **rejected**: the measurement itself forces the first open style flush, so the value can never be present when the transition target is computed (the `auto` fallback doesn't interpolate). - Grouped (accordion) usage dev-warns when a member's invoker isn't wrapped in a heading (`h1`–`h6`/`[role="heading"]`), per the APG accordion's heading requirement. ### 5.2 `pd-nav` + `pd-nav-panel` — disclosure navigation menu (mega menu) Follows the APG **Disclosure Navigation Menu** pattern — never `role="menu"`/`menubar` and never `aria-haspopup` (menu roles are wrong for link navigation; normative). ```html
``` - `pd-nav-panel` behaves like `pd-disclosure` (same commands, events, aria-expanded syncing) plus nav coordination. ID-based commands work from any placement inside `pd-nav`, but native Tab/Shift+Tab always follows source order: each panel must immediately follow its owning invoker in the same semantic item (normally the same `
  • `) when keyboard users should enter it next. Absolute positioning/grid can still make that nested panel a full-width row. It sets nothing on itself but `data-state`/component-owned `inert`/`hidden`; the author provides ` ``` Notes: - The panel is a flat sibling of the trigger ``/` {% for link in linklists.main-menu.links %} {% if link.links.size > 0 %} {% endif %} {% endfor %} ``` The `label` attribute rendered onto each destination panel (bound to the link's title above) isn't decorative — it's what lets a screen reader announce which section a shopper just drilled into (see the [Accessibility guide](/guide/accessibility)). Reset the drilldown so the drawer always reopens at its root, rather than wherever the shopper left it. This is plain JS, not Liquid — it's the one non-Liquid script this integration needs, and it's the docs recipe from SPEC §5.4 (call `reset()` on the drawer's `pd:closed`): ```html ``` ## 4. Brand index from `collections`/`vendors` An A–Z filter (SPEC §5.5) needs two things: a static alphabet of invoker buttons, and a list whose items carry `data-filter-value`. Where that list's data comes from depends on how your catalog models brands. **If brands are collections** (a common pattern: one collection per brand, tagged so you can find them), loop `collections` and filter by whatever convention your theme uses — a tag shown here: ```liquid {% assign letters = "a,b,c,d,e,f,g,h,i,j,k,l,m,n,o,p,q,r,s,t,u,v,w,x,y,z" | split: "," %} {% for letter in letters %} {% endfor %} Showing {count} of {total} brands ``` **If brands are just product vendors** (no dedicated collection per brand), `shop.vendors` gives you the shop-wide vendor list directly, linked into the all-products collection's vendor filter: ```liquid ``` Either way, `data-filter-value` must carry the exact string `pd-filter` compares against (its match is Unicode-fold + case-insensitive, so accents and casing are forgiving, but the letter buttons' `value` attributes and the list's `data-filter-value`s need to agree on what the alphabet means for your catalog). ## Settings-schema-free stance pd-components has no `settings_schema.json` entry and never will (SPEC §1.2 rule 6: "Configuration is HTML attributes and/or JS properties/methods only. No JSON blobs, no settings schema."). Every behavioral knob documented on the component pages — `hover`, `hover-open-delay`, `arrow-nav`, `orientation`, `close-on-outside-click`, `scroll-lock`, `threshold`, `match`, `toggle` — is a plain HTML attribute your section or snippet renders. If you want a merchant-configurable toggle, that's an ordinary Shopify section setting driving a Liquid conditional on the attribute, exactly like any other markup decision your theme already makes — the library doesn't need to know settings exist: ```liquid {% schema %} { "name": "Header", "settings": [ { "type": "checkbox", "id": "enable_hover", "label": "Open mega menu on hover", "default": true } ] } {% endschema %} ... ``` The schema block above is your section's own settings — normal Shopify practice, unrelated to and unowned by pd-components. The library only ever sees the resulting `hover` attribute (or its absence) on the rendered `` tag. --- # Testing The suite is split into three layers on purpose (SPEC §7): unit tests exercise the **invoker-commands polyfill** path in jsdom (fast, broad coverage of every command/event/attribute combination); e2e tests exercise the **native** browser path in real Chromium plus focused WebKit coverage for `pd-nav`/`pd-drawer`, along with everything jsdom structurally can't emulate (hover timing, focus traps, real animations, real scroll). Both halves of the polyfill-vs-native split are covered — a bug that only shows up under one or the other still gets caught. ## How this repo tests ### Unit — Vitest + jsdom + the polyfill `vitest.config.ts` runs `tests/**/*.test.ts` in a jsdom environment with `tests/setup.ts` as a global setup file — one glob, so a single `vitest run` covers both this Unit layer and the A11y layer below (they're conceptually separate, not separately configured). That file imports `invokers-polyfill` unconditionally — jsdom has no native `CommandEvent`, so every unit test exercises the same polyfilled invoker path a non-supporting browser gets — and extends Vitest's `expect` with `vitest-axe`'s matchers for the a11y layer below. `tests/helpers.ts` gives every test file four building blocks: - `mount(html)` — appends markup into a fresh `
    ` and awaits one macrotask, long enough for a component's `whenParsed()`-deferred initial sync (and any `afterAnimations` resolution) to run. - `tick(ms)` — a raw `setTimeout` promise for anything that needs more time. - `press(target, key)` — dispatches a real bubbling, cancelable `KeyboardEvent`, so keyboard-map tests exercise the actual `keydown` listeners rather than calling internal methods directly. - `invoke(button)` — calls `.click()` on a real invoker button; the polyfill turns that into a `CommandEvent`, so command wiring is tested through the same path an author's markup uses, never through a private method. Per module (`tests/unit/.test.ts`), the baseline coverage required by SPEC §7 is: idempotent `define()`; command wiring via real invoker buttons; components created *before* their children parse (append markup after connect, not before — catches upgrade-ordering bugs); ARIA syncing including author-supplied id preservation and the no-`aria-controls` rule; the complete keyboard map; every event including canceling `pd:open`/`pd:close`; attribute configuration (defaults, overrides, runtime changes); focus management (Escape return, drill/back, drawer restore where jsdom allows); disconnect cleanup (no ghost listeners after `.remove()`); and malformed markup (missing dialog/invoker/list) producing a console warning, never a thrown error. ### A11y — vitest-axe `tests/a11y/.a11y.test.ts` mounts a realistic fixture — not a minimal one; `nav.a11y.test.ts` for example mounts a full two-item mega menu with real link/button markup, matching what a theme would actually render — and runs `axe()` against it in both a **closed** and an **open** state, each required to return zero violations. Opening is done through the component's own public API (`panel.show()`, or `invoke()` on a real trigger) rather than by waiting on an animation, since `afterAnimations` already resolves synchronously in jsdom (see the caveats below). ### E2E — Playwright + Chromium/WebKit `playwright.config.ts` runs the full suite in Chromium and repeats the `pd-nav`/`pd-drawer` interaction suites in WebKit, served by Vite at `http://localhost:4173` (`npm run dev`, i.e. `vite.demo.config.ts`) with `webServer` configured to boot that dev server automatically. Fixtures live in `e2e/fixtures/` as plain HTML pages that import `/src/define.ts` directly. Chromium therefore exercises its **native** Invoker Commands API, the other half of the coverage split from jsdom; WebKit exercises the entry point's conditional `invokers-polyfill` import in a real browser while supplying an independent focus/modality implementation. Page-level Tab-order cases that depend on the host macOS Full Keyboard Access preference are explicitly skipped there, while Enter/Space, arrows, Escape layering, modal containment, and focus restoration still run. This is also where everything jsdom can't emulate gets asserted: hover intent driven by real `page.mouse.move()` timing (not fake timers); the drawer's native focus trap and focus restore; Escape flows; synchronous `inert` → exit-animation → `hidden`/`dialog.close()` sequencing against real CSS animations (`getAnimations()` genuinely runs here, unlike the jsdom no-op); `pd-header` show/hide on real `scroll` events with real layout; drilldown focus journeys; and `@axe-core/playwright` scans of every fixture in both open and closed states. ## jsdom caveats (SPEC §7) These are structural jsdom limitations, not bugs — know them before "fixing" a unit test that looks wrong: - **`getAnimations` is absent.** `afterAnimations()` (`src/internal/animation.ts`) falls back to resolving synchronously when `el.getAnimations` is undefined. Unit tests can assert the *sequence* an exit follows (`data-state="closed"` + component-owned `inert` synchronously, then `hidden`/native dialog close and `pd:closed`) but never real animation timing. Unit coverage also verifies rapid reopen removes only managed inertness and author-supplied `inert` survives; real transition timing belongs to the e2e exit-animation-sequencing coverage. - **`:focus-visible` is unsupported.** `isFocusVisible()` (`src/internal/focus.ts`) wraps `el.matches(':focus-visible')` in a try/catch and returns `false` in jsdom. Any unit test that needs to exercise `open-on-focus` must `vi.mock` the focus module and stub `isFocusVisible` to return `true` (see the top of `tests/unit/nav.test.ts`) — otherwise every focus-driven open silently no-ops and the test would pass for the wrong reason. - **Native `` focus trap isn't emulated.** The jsdom version pinned in this repo doesn't implement `HTMLDialogElement.prototype.showModal`/`close` at all. `tests/unit/drawer.test.ts` and `tests/a11y/drawer.a11y.test.ts` install a minimal shim that toggles the `open` attribute (mirroring the real methods' visible effect) purely so `pd-drawer`'s `try { dialog.showModal() }` / `if (dialog.open) dialog.close()` guards have something to call. That shim does **not** reproduce top-layer stacking, background inertness, or the native Tab-cycle focus trap — those assertions live in e2e only. - **Hover-intent timing.** Unit tests use `vi.useFakeTimers()` + `vi.advanceTimersByTimeAsync()` to assert `hover-open-delay`/`hover-close-delay` behavior deterministically and instantly; e2e uses real timers driven by actual pointer movement to prove the same behavior holds under real `pointerover`/`pointerout` timing. ## Smoke-testing your theme integration The library's own suite proves the *components* are correct. It cannot see the markup, Liquid loops, or copy your theme wraps around them (see the [Shopify integration guide](/guide/shopify)) — that's your integration's job to verify, not this one's. A minimal smoke test for a consuming theme: 1. **Axe scan.** After vendoring the bundle, run an automated scan — the axe DevTools browser extension for a manual pass, or `@axe-core/playwright` in the theme's own CI — against every template that renders a `pd-*` component, in both a closed and a representative open state: mega menu open, cart drawer open, mobile drilldown two levels deep, brand index filtered. Zero violations is the bar this library holds itself to in `tests/a11y/*`; what a scan here actually catches is missing labels, bad contrast, and landmark structure — the parts the library structurally cannot verify for you (see the [Accessibility guide](/guide/accessibility)). 2. **Keyboard walk.** Tab from the top of the page through every top-level nav stop. Open a mega menu panel with Enter or `ArrowDown` and confirm focus lands inside it; `ArrowRight`/`ArrowLeft` across top-level stops without leaving a panel open behind you; `Escape` closes and returns focus to the trigger. Open the mobile drawer, confirm Tab cycles only inside it and `Escape` closes and restores focus to the opener. Drill into a drilldown panel and back out, confirming focus returns to the exact button that drilled in. Tab through an A–Z filter and confirm empty letters are genuinely skipped (`disabled`, not merely styled to look inactive). 3. **Wire it into CI.** A lightweight Playwright spec per template, using `@axe-core/playwright`, mirrors this repo's own `e2e/*.spec.ts` pattern — just point it at the theme's preview URL instead of `e2e/fixtures`. It doesn't replace this library's test suite; it validates the Liquid loops and markup the theme wrote on top of it, which is outside this suite's reach by construction. --- # Nav & mega menu — `pd-nav` + `pd-nav-panel` > **[See it live in the styled storefront ›](/examples/storefront.html)** — the mega menu in the > demo shop's header: hover intent, single-open, and the full keyboard map. `pd-nav` is a **coordinator**: it owns no state of its own and instead orchestrates one or more `pd-nav-panel` descendants — the disclosure panels that make up a mega menu. `pd-nav-panel` owns exactly one piece of state (`open`) and behaves like [`pd-disclosure`](/components/disclosure) plus nav-specific coordination (single-open, hover intent, focus handling, arrow keys). Together they implement the APG **Disclosure Navigation Menu** pattern, not a menu/menubar widget. That distinction drives most of the design decisions below. ## Anatomy ```html ``` 1. `