@xplortech/apollo-core 2.5.0 → 2.7.0

package/dist/docs/xpl-tag/readme.md

@@ -1,15 +1,385 @@
 # xpl-tag
 
-Tags represent a set of interactive keywords that help label, organize, and categorize objects. Tags can be added or removed from an object by the user. Unlike Badges, Tags are clickable, draggable, used in dropdowns, multi-select, search bars, etc..
+Tags represent a set of interactive keywords that help label, organize, and categorize objects. Tags can be added or removed from an object by the user. Unlike Badges, Tags are clickable, used in dropdowns, multi-select, search bars, etc.
+
+## Usage Examples
+
+### Basic tag with dismiss
+
+```html
+<xpl-tag>Label</xpl-tag>
+```
+
+### Small size variant
+
+```html
+<xpl-tag size="sm">Small Tag</xpl-tag>
+```
+
+### Non-dismissible tag (no close button)
+
+```html
+<xpl-tag dismissible="false">Static Tag</xpl-tag>
+```
+
+### Disabled tag
+
+```html
+<xpl-tag disabled>Disabled Tag</xpl-tag>
+```
+
+### Handling events
+
+> **⚠️ Deprecation Notice:** The `close` event is **deprecated** and will be removed in a future major version. Use `tagRemove` for dismiss button clicks only.
+
+#### Why This Change?
+
+The `close` event name conflicts with a **native HTML event** used by `<dialog>` elements. The React wrapper's `isCoveredByReact()` function detects `onclose` as a native event and passes handlers to React's synthetic event system — but React doesn't actually handle `close` events this way, so handlers silently fail in React applications.
+
+**Why `tagRemove` works:** `ontagremove` is not a native event, so the wrapper correctly falls back to `addEventListener`.
+
+#### Event Behavior
+
+| Interaction | `close` (deprecated) | `tagRemove` (use this) |
+|-------------|------------------------|------------------------|
+| Dismiss (×) button clicked | ✅ Fires | ✅ Fires |
+| Content clicked (non-draggable) | ✅ Fires | ❌ Does NOT fire |
+| Content clicked (draggable) | ❌ Does NOT fire | ❌ Does NOT fire |
+| Keyboard Space/Enter on content (non-draggable) | ✅ Fires | ❌ Does NOT fire |
+| Keyboard Space/Enter on draggable label | ❌ Does NOT fire | ❌ Does NOT fire |
+
+#### Migration Examples
+
+**Before (deprecated):**
+```tsx
+// React — this may silently fail!
+<XplTag onClose={() => tag.remove()}>Label</XplTag>
+
+// Vanilla JS
+const tag = document.querySelector('xpl-tag');
+tag.addEventListener('close', () => tag.remove());
+```
+
+**After (recommended):**
+```tsx
+// React — works reliably
+<XplTag onTagRemove={() => tag.remove()}>Label</XplTag>
+
+// Vanilla JS — same pattern, clearer intent
+const tag = document.querySelector('xpl-tag');
+tag.addEventListener('tagRemove', () => tag.remove());
+```
+
+**React with Refs (if you must use deprecated `close`):**
+```tsx
+import { useEffect, useRef } from 'react';
+import { XplTag } from '@xplortech/apollo-react';
+
+function MyComponent() {
+  const tagRef = useRef<HTMLElement | null>(null);
+
+  useEffect(() => {
+    const el = tagRef.current;
+    if (!el) return;
+
+    const handleClose = () => el.remove();
+    el.addEventListener('close', handleClose);
+    return () => el.removeEventListener('close', handleClose);
+  }, []);
+
+  return <XplTag ref={tagRef}>Label</XplTag>;
+}
+```
+
+## Drag and drop
+
+Tags support **native HTML5 drag and drop**. Set the boolean prop **`isDraggable`** (HTML attribute **`is-draggable`**) to enable dragging. Optionally set **`tag-id`** so `dataTransfer` and `tagDragStart` / `tagDragEnd` detail carry a stable id.
+
+### How it works (important for handlers)
+
+- The **drag source** is an inner **label** element (a `div` with `role="button"`), not the `<xpl-tag>` host. Browsers do not start drags reliably on the custom element host; the **`is-draggable`** prop does **not** mirror the native host **`draggable`** attribute (see the `isDraggable` prop docs below).
+- On **`dragstart`**, the component uses **`setDragImage`** so the floating preview (“ghost”) looks like the **whole tag** (label + dismiss control), not only the label strip.
+- **Start the drag from the label text**, not from the dismiss (×) button.
+- In container listeners, **`dragstart`** may bubble with `event.target` equal to that inner node. Resolve the tag with:
+
+```js
+const tag = event.target instanceof Element ? event.target.closest('xpl-tag') : null;
+```
+
+### Making a tag draggable
+
+```html
+<xpl-tag is-draggable>Draggable tag</xpl-tag>
+
+<xpl-tag is-draggable tag-id="my-tag-1">Design</xpl-tag>
+```
+
+### Reordering tags within a container
+
+```html
+<div id="tag-container" style="display: flex; flex-wrap: wrap; gap: 8px">
+  <xpl-tag tag-id="t1" is-draggable>Design</xpl-tag>
+  <xpl-tag tag-id="t2" is-draggable>Development</xpl-tag>
+  <xpl-tag tag-id="t3" is-draggable>QA</xpl-tag>
+</div>
+
+<script>
+  const container = document.getElementById('tag-container');
+  let draggedEl = null;
+
+  container.addEventListener('dragstart', (e) => {
+    const tag = e.target instanceof Element ? e.target.closest('xpl-tag') : null;
+    if (tag) draggedEl = tag;
+  });
+
+  container.addEventListener('dragend', () => {
+    draggedEl = null;
+  });
+
+  container.addEventListener('dragover', (e) => {
+    e.preventDefault();
+    if (!draggedEl) return;
+    const afterEl = getDragAfterElement(container, e.clientX);
+    if (afterEl == null) container.appendChild(draggedEl);
+    else container.insertBefore(draggedEl, afterEl);
+  });
+
+  function getDragAfterElement(container, x) {
+    const tags = [...container.querySelectorAll('xpl-tag')].filter((el) => el !== draggedEl);
+    return tags.reduce(
+      (closest, child) => {
+        const box = child.getBoundingClientRect();
+        const offset = x - box.left - box.width / 2;
+        return offset < 0 && offset > closest.offset ? { offset, element: child } : closest;
+      },
+      { offset: Number.NEGATIVE_INFINITY },
+    ).element;
+  }
+</script>
+```
+
+### Dragging tags between containers
+
+```html
+<div
+  class="drop-zone"
+  style="display: flex; gap: 8px; padding: 16px; border: 2px dashed var(--xpl-border-default); border-radius: 8px"
+>
+  <xpl-tag tag-id="a1" is-draggable>Frontend</xpl-tag>
+  <xpl-tag tag-id="a2" is-draggable>Backend</xpl-tag>
+</div>
+
+<div
+  class="drop-zone"
+  style="
+    display: flex;
+    gap: 8px;
+    padding: 16px;
+    border: 2px dashed var(--xpl-border-default);
+    border-radius: 8px;
+    margin-top: 8px;
+  "
+>
+  <xpl-tag tag-id="b1" is-draggable>DevOps</xpl-tag>
+</div>
+
+<script>
+  document.querySelectorAll('.drop-zone').forEach((zone) => {
+    let draggedEl = null;
+
+    zone.addEventListener('dragstart', (e) => {
+      const tag = e.target instanceof Element ? e.target.closest('xpl-tag') : null;
+      if (tag) draggedEl = tag;
+    });
+
+    zone.addEventListener('dragend', () => {
+      draggedEl = null;
+    });
+
+    zone.addEventListener('dragover', (e) => e.preventDefault());
+
+    zone.addEventListener('drop', (e) => {
+      e.preventDefault();
+      if (draggedEl && draggedEl.parentNode !== zone) zone.appendChild(draggedEl);
+    });
+  });
+</script>
+```
+
+### `tagDragStart` / `tagDragEnd` events
+
+The component emits **`tagDragStart`** and **`tagDragEnd`** (Stencil camelCase). They bubble and are composed.
+
+```html
+<xpl-tag is-draggable tag-id="my-tag">Drag me</xpl-tag>
+
+<script>
+  const tag = document.querySelector('xpl-tag[tag-id="my-tag"]');
+
+  tag.addEventListener('tagDragStart', (e) => {
+    const { tagId, content, originalEvent } = e.detail;
+  });
+
+  tag.addEventListener('tagDragEnd', (e) => {
+    const { dropped, tagId, originalEvent } = e.detail;
+    if (dropped) {
+      /* dropEffect was 'move' */
+    }
+  });
+</script>
+```
+
+### React (`@xplortech/apollo-react`)
+
+Ensure the app loads Apollo **defineCustomElements** (see the main React package docs). Import **`XplTag`** and use **`isDraggable`**, **`tagId`**, and children for the label.
+
+`HTMLXplTagElement` is provided by Apollo’s Stencil typings (the same setup that types `defineCustomElements`). If your editor cannot resolve it, use `useRef<HTMLElement | null>(null)` and attach listeners on `ref.current`.
+
+`XplTag` is a thin wrapper around the web component. Custom events use the same names as in the DOM (`tagDragStart`, `tagDragEnd`, `tagRemove`). If your TypeScript definitions use different prop names for listeners, attach them with a **ref** (always works):
+
+```tsx
+import { useEffect, useRef } from 'react';
+import { XplTag } from '@xplortech/apollo-react';
+
+function TagBoard() {
+  const tagRef = useRef<HTMLXplTagElement | null>(null);
+
+  useEffect(() => {
+    const el = tagRef.current;
+    if (!el) return;
+
+    const onDragStart = (e: CustomEvent) => {
+      const { tagId, content } = e.detail;
+    };
+    const onDragEnd = (e: CustomEvent) => {
+      const { dropped, tagId } = e.detail;
+    };
+    const onTagRemove = () => {
+      el.remove(); // Handle dismiss button click
+    };
+
+    el.addEventListener('tagDragStart', onDragStart as EventListener);
+    el.addEventListener('tagDragEnd', onDragEnd as EventListener);
+    el.addEventListener('tagRemove', onTagRemove);
+    return () => {
+      el.removeEventListener('tagDragStart', onDragStart as EventListener);
+      el.removeEventListener('tagDragEnd', onDragEnd as EventListener);
+      el.removeEventListener('tagRemove', onTagRemove);
+    };
+  }, []);
+
+  return (
+    <XplTag ref={tagRef} isDraggable tagId="react-1">
+      Movable
+    </XplTag>
+  );
+}
+```
+
+Reorder / multi-container logic is unchanged: listen for native `dragstart`, `dragover`, `drop` on a React parent `div` (use refs) and call `closest('xpl-tag')` as in the HTML examples.
+
+### `DataTransfer` payload
+
+| MIME type | Value | Purpose |
+|-----------|-------|---------|
+| `application/x-tag-id` | `tag-id` prop, if set | Identify the tag in drop handlers |
+| `text/plain` | Trimmed text content of the tag | Fallback for external targets |
+
+`effectAllowed` is set to `move`.
+
+**`originalEvent` in `tagDragStart` / `tagDragEnd`:** the native `DragEvent` is included for convenience, but browsers may clear `dataTransfer` after the synchronous handler completes. Use `tagId`, `content`, and `dropped` from the custom event detail for anything needed after the current turn; only read `originalEvent.dataTransfer` synchronously in the listener.
+
+### Disabled tags
+
+`disabled` wins: the tag is not draggable and keep using a normal `<button>` label (no HTML5 drag on the host).
+
+```html
+<xpl-tag is-draggable disabled>Cannot drag</xpl-tag>
+```
+
+## Design Tokens
+
+| Property | Token |
+|----------|-------|
+| Border (default) | `var(--xpl-border-accent-information)` |
+| Border (disabled) | `var(--xpl-border-accent-subtle)` |
+| Background (default) | `var(--xpl-background-surface-default)` |
+| Background (hover) | `var(--xpl-background-surface-information-bold)` |
+| Background (disabled) | `var(--xpl-background-surface-subtle)` |
+| Text | `var(--xpl-text-strong)` |
+| Text (disabled) | `var(--xpl-text-disabled)` |
+| Dismiss icon | `var(--xpl-icon-default)` |
+| Dismiss icon (disabled) | `var(--xpl-icon-disabled)` |
+| Spacing (default) | `var(--xpl-space-2)` vertical, `var(--xpl-space-12)` horizontal |
+| Spacing (small) | `var(--xpl-space-2)` vertical, `var(--xpl-space-8)` horizontal |
+| Height (default) | `var(--xpl-size-150)` (24px) |
+| Height (small) | `var(--xpl-size-125)` (20px) |
+| Border radius | `var(--xpl-border-radius-button)` |
+| Typography (default) | `var(--xpl-font-size-body)` / `var(--xpl-font-weight-normal)` |
+| Typography (small) | `var(--xpl-font-size-callout)` / `var(--xpl-font-weight-semibold)` |
+| Background (dragging) | `var(--xpl-background-surface-information-bold)` |
+| Cursor (draggable) | `cursor: grab` → `cursor: grabbing` while dragging |
+
+## Accessibility
+
+### Keyboard Navigation
+
+| Key | Action |
+|-----|--------|
+| Tab | Focus tag content or dismiss button |
+| Enter/Space | Activate the focused control: on **dismiss**, emits deprecated `close` and `tagRemove`; on **content**, emits deprecated `close` only when the tag is **not** in drag mode (native `<button>` behavior). |
+
+### Drag mode
+
+- With `isDraggable`, focus moves to the **label** (`role="button"`). Enter/Space on the label does **not** dismiss the tag (same as click on draggable content).
+- Start drags from the **label**; the dismiss control remains a separate focus stop and is not the drag handle.
+
+### ARIA Attributes
+
+- Dismiss button sets `aria-label` to `Dismiss` plus the host element’s `textContent` (trimmed), or the word `tag` when empty, so multiple tags stay distinguishable in screen readers
+- When `disabled={true}`, buttons have `disabled` attribute preventing interaction
+- When `isDraggable` is set, **`aria-grabbed`** on the **label** reflects drag state (`"false"` at rest, `"true"` while dragging)
+
+### Icon Mapping
+
+| Element | Icon |
+|---------|------|
+| Dismiss button | `xmark` (size 10) |
+
+## Backward Compatibility (CSS class aliases)
+
+The refactored component preserves legacy CSS classes so existing consumer selectors keep working:
+
+| Legacy class | Element | Replaces / alias for |
+|---|---|---|
+| `xpl-tag-container` | Host (`<xpl-tag>`) | Old root class — now an alias; styles come from `.xpl-tag` |
+| `xpl-tag` | Content `<button>` / `<div>` | Old content selector (`button.xpl-tag`) — kept so `.xpl-tag-container .xpl-tag` selectors match |
+| `xpl-tag__close` | Dismiss `<button>` | Old dismiss selector — alias for `.xpl-tag__dismiss` |
+
+These aliases will be removed in a future major version. New code should target `.xpl-tag`, `.xpl-tag__content`, and `.xpl-tag__dismiss`.
 
 <!-- Auto Generated Below -->
 
 
+## Properties
+
+| Property      | Attribute      | Description                                                                                                                                                                                                                                                                                                                                                                          | Type                | Default     |
+| ------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------- | ----------- |
+| `disabled`    | `disabled`     | Whether the tag is disabled                                                                                                                                                                                                                                                                                                                                                          | `boolean`           | `false`     |
+| `dismissible` | `dismissible`  | Whether the tag shows a dismiss button                                                                                                                                                                                                                                                                                                                                               | `boolean`           | `true`      |
+| `isDraggable` | `is-draggable` | When true, the tag label uses native HTML5 drag (the inner label is the drag source). Named `isDraggable` so the Stencil prop does not collide with the native `HTMLElement.draggable` API. `reflect: false` avoids syncing a `draggable` attribute onto the host; the inner label remains the drag source. Host `onDragStart` still suppresses stray native drags from host chrome. | `boolean`           | `false`     |
+| `size`        | `size`         | The size of the tag                                                                                                                                                                                                                                                                                                                                                                  | `"default" \| "sm"` | `'default'` |
+| `tagId`       | `tag-id`       | Optional stable id for the tag. When set, it is included in `tagDragStart` / `tagDragEnd` detail and written to `dataTransfer` as `application/x-tag-id`.                                                                                                                                                                                                                            | `string`            | `undefined` |
+
+
 ## Events
 
-| Event   | Description                                                           | Type               |
-| ------- | --------------------------------------------------------------------- | ------------------ |
-| `close` | Callback function that is called when tag text or `x` icon is clicked | `CustomEvent<any>` |
+| Event          | Description                                                                                                                                                                                                                                                                                                                                      | Type                              |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------- |
+| `close`        | <span style="color:red">**[DEPRECATED]**</span> Use `tagRemove` for dismiss button clicks only. The `close` event will be removed in a future major version.<br/><br/>Emitted when the tag is dismissed (content click when `isDraggable` is false, or dismiss button click).                                                                    | `CustomEvent<void>`               |
+| `tagDragEnd`   | Emitted when a drag operation ends. `event.detail`: `{ tagId?, dropped, originalEvent }`. `dropped` is `true` when `dataTransfer.dropEffect === 'move'`. `originalEvent` is the native `DragEvent`; browsers may clear `dataTransfer` after the synchronous handler runs — do not read `originalEvent.dataTransfer.getData(...)` asynchronously. | `CustomEvent<TagDragEndDetail>`   |
+| `tagDragStart` | Emitted when a drag operation starts (native `dragstart` on the inner label). `event.detail`: `{ tagId?, content, originalEvent }`. `originalEvent` is the native `DragEvent`; browsers may clear `dataTransfer` after the synchronous handler runs — do not read `originalEvent.dataTransfer.getData(...)` asynchronously.                      | `CustomEvent<TagDragStartDetail>` |
+| `tagRemove`    | Emitted when the tag dismiss (×) button is clicked                                                                                                                                                                                                                                                                                               | `CustomEvent<void>`               |
 
 
 ## Dependencies
@@ -18,9 +388,14 @@ Tags represent a set of interactive keywords that help label, organize, and cate
 
  - [xpl-select](../xpl-select)
 
+### Depends on
+
+- [xpl-icon](../xpl-icon)
+
 ### Graph
 ```mermaid
 graph TD;
+  xpl-tag --> xpl-icon
   xpl-select --> xpl-tag
   style xpl-tag fill:#f9f,stroke:#333,stroke-width:4px
 ```

package/dist/docs/xpl-toast/readme.md

@@ -8,7 +8,62 @@ When possible, Toasts should auto-dismiss after 8 seconds. When an action is pre
 
 Match your messaging with the sentiment of the toast. Most messages will have a neutral sentiment. Reserve negative sentiments for when an explicit failure has occurred. Give users the information they need to correct the issue. 
 
-Toasts only support a single action and up to 85 characters. If multiple actions can be taken, or the message is longer than a few words, use a [Modal component](https://xplor-apollo.herokuapp.com/?path=/story/components-modal--modal) instead.
+Toasts only support a single action and up to 85 characters. If multiple actions can be taken, or the message is longer than a few words, use a [Modal component](https://apollo.xplordocs.com/?path=/story/components-modal--modal) instead.
+
+## Positioning
+
+The default position is arbitrarily set to `40px` from top and `40px` from right of the browser viewport on desktop and bottom-center on mobile. This position should be adjusted to ensure it's not covering your App's header. Apollo, by design, does not prescribe a position for toasts because this will be dependent on the app that it is being used in.
+
+Positioning of toasts should be global to your app. For example, if it is decided that your app will always position the toast in the top right corner, then this convention should be followed throughout. It should not be positioned top-right on one screen and bottom-center on another.
+
+*****Consult your designer for the best placement for your product.**
+
+### Overriding the default position
+
+The toast uses `position: fixed` and can be repositioned by overriding the `.xpl-toast` CSS class in your app's stylesheet. Set `top`, `right`, `bottom`, and `left` as needed and use `unset` or `initial` to clear any defaults you don't want.
+
+**Top-left example:**
+```css
+.xpl-toast {
+  top: 24px;
+  right: unset;
+  left: 24px;
+}
+```
+
+**Bottom-right example:**
+```css
+.xpl-toast {
+  top: unset;
+  right: 24px;
+  bottom: 24px;
+}
+```
+
+**Centered at the top:**
+```css
+.xpl-toast {
+  top: 24px;
+  right: unset;
+  left: 50%;
+  transform: translateX(-50%);
+}
+```
+
+The mobile breakpoint (≤ 768px) resets the toast to bottom-center. If your app needs a different mobile position, override the media query as well:
+
+```css
+@media screen and (max-width: 768px) {
+  .xpl-toast {
+    /* your mobile overrides */
+    bottom: 16px;
+    left: 50%;
+    transform: translateX(-50%);
+  }
+}
+```
+
+> **Tip:** Place these overrides in a global stylesheet so every toast in your app appears in the same location.
 
 <!-- Auto Generated Below -->
 

package/dist/docs/xpl-top-nav/readme.md

@@ -0,0 +1,179 @@
+# xpl-top-nav
+
+Top navigation shell for brand, primary navigation, right-side actions, and an optional account menu.
+
+## Usage
+
+Use slots only for layout content. The component provides the internal wrappers for the right rail and user menu. The right side renders `right-aside` then the user menu (built-in trigger + panel). `left-aside` is intended for `xpl-top-nav-item` links (each item should use **`slot="left-aside"`** so they are direct children of the internal **`role="list"`** — avoid wrapping them in a single container with that slot). Set the **`child-account-label`** attribute (or **`childAccountLabel`** in React) for the built-in menu trigger label beside the chevron; use **`slot="user-menu-trigger"`** to replace that trigger entirely. If `brand-href` is set, the brand uses native link navigation. If not, the component emits `brandClick`.
+
+### Web component (typical layout)
+
+```html
+<xpl-top-nav
+  brand-name="My App"
+  brand-href="/"
+  label="Main navigation"
+  child-account-label="Account"
+  nav-control
+>
+  <xpl-top-nav-item slot="left-aside" label="Home" href="/" icon="house-4"></xpl-top-nav-item>
+  <xpl-top-nav-item slot="left-aside" label="Reports" href="/reports"></xpl-top-nav-item>
+
+  <xpl-button slot="right-aside" variant="secondary">Help</xpl-button>
+  <xpl-nav-header-menu slot="user-menu" username="Alex User" email="alex@example.com">
+    <xpl-top-nav-item slot="right-aside-mobile" label="Help" href="/help"></xpl-top-nav-item>
+    <xpl-top-nav-item label="Profile" href="/profile" icon="person-1"></xpl-top-nav-item>
+    <xpl-top-nav-item label="Sign out" href="/logout" icon="open-rect-arrow-out"></xpl-top-nav-item>
+  </xpl-nav-header-menu>
+</xpl-top-nav>
+```
+
+### Logo from URL and SPA brand (no `brand-href`)
+
+```html
+<xpl-top-nav brand-logo="https://example.com/logo.svg" brand-name="Apollo">
+  <xpl-top-nav-item slot="left-aside" label="Dashboard" href="#"></xpl-top-nav-item>
+</xpl-top-nav>
+```
+
+Listen for `brandClick` on the host when `brand-href` is omitted.
+
+### Plain HTML (static documentation)
+
+Use the same tags in any HTML page that loads Apollo styles and the component bundle. Prefer slots and `xpl-top-nav-item` rather than copying internal BEM classes.
+
+## Responsive behavior
+
+- `nav-control` enables the mobile drawer toggle. The control is only visible on **narrow viewports** (see **`top-nav.css`**: one pixel below Tailwind **`md`**; hidden from **`md`** / **768px** width upward at default Tailwind).
+- Below **`md`**, **`slot="left-aside"`** (`.xpl-nav-left`) is **hidden** unless **`nav-control`** is set **and** the drawer is open (`xpl-top-nav--nav-control` + `xpl-top-nav--open`). **Without `nav-control` there is no mobile drawer** — primary links are not shown in the narrow bar (duplicate into **`xpl-nav-header-menu`** or widen the viewport if they must stay reachable).
+- Pressing `Escape` closes nested dropdowns first, then closes the mobile drawer if it is still open (when `nav-control` is set). Focus then returns to the hamburger toggle. **Escape** is ignored for closing the drawer while **any** descendant **`xpl-popover`** is open (including the account menu or a consumer-slotted popover in **`left-aside`** / **`right-aside`**).
+- Opening the built-in **account** popover while the mobile drawer is open **closes the drawer** and emits **`navOpen(false)`** so the two surfaces do not stack.
+- On **narrow viewports**, **`slot="right-aside"`** is hidden in the bar. Duplicate those actions into **`xpl-nav-header-menu`** **`slot="right-aside-mobile"`** (narrow-only strip below profile, above the list) so they stay reachable from the account menu.
+- On **`xpl-top-nav-item`**, use **`selected`** for the current page (**`aria-current="page"`**) and optional **`active`** for extra accent styling; see the item readme for modifier details.
+- **`slot="dropdown"`** does not implement arrow-key roving focus; put focusable elements inside the panel or treat full “menu” keyboard behavior as a future enhancement.
+
+## Theming
+
+- The host applies the Foundation `dark` scope so the bar and its slotted children resolve dark-mode purpose tokens automatically.
+- Floating overlays rendered outside the host, such as teleported popover content, may need their own `dark` class if they should match the shell.
+
+## Icon Mapping
+
+| Location | Icon name | Notes |
+| -------- | --------- | ----- |
+| Mobile nav toggle (`nav-control`) | `menu` | Shown inside the bar control when `nav-control` is set. |
+| Built-in account trigger | `chevron-down` | `xpl-button` `icon` prop (end). |
+| Dropdown row (`xpl-top-nav-item` with `slot="dropdown"`) | `chevron-down` | Trailing indicator on the row control. |
+
+Consumer-provided `icon` props on `xpl-top-nav-item` use names from `@xplortech/apollo-icons`.
+
+## Token use
+
+| Area | Token / variable |
+| ---- | ---------------- |
+| Bar surface | `var(--xpl-background-surface-default)` |
+| Bar text (default) | `var(--xpl-text-subdued)` |
+| Bar height | `var(--xpl-size-350)` |
+| Bar padding | `var(--xpl-space-8)` / `var(--xpl-space-16)` |
+| Bottom border | `var(--xpl-border-small)` `var(--xpl-border-default)` |
+| Focus ring | `var(--xpl-border-focus)` with `outline-2` / `outline-offset-2` (see `top-nav.css`) |
+| Panel / drawer width | `var(--xpl-top-nav-panel-width)` (component custom property in `top-nav.css`) |
+| Account popover offset | `var(--xpl-space-16)` below bar (`margin-top` on menu content) |
+
+## Accessibility
+
+- **`nav` landmark:** The `label` prop maps to `aria-label` on the inner `<nav>`. If omitted, it defaults to **`top-navigation-bar`**. Use a unique label when multiple navigation regions exist (e.g. side nav + top nav).
+- **Mobile control:** With `nav-control`, the toggle is a native `<button>` with `aria-expanded` reflecting the drawer and an accessible name for open/close.
+- **Account menu:** The built-in `xpl-button` trigger sets `aria-haspopup="dialog"` to match the internal `xpl-popover` trigger. Chevron-only mode (no `child-account-label` text) adds `aria-label="Open account menu"`. The popover's internal wrapper `<span>` is hidden via CSS `visibility: hidden` so the `xpl-button` is the **single tab stop** — click and keyboard events still bubble to the popover. Custom triggers via `slot="user-menu-trigger"` should set their own accessible name and `aria-haspopup`.
+- **Primary links:** Brand and items use `xpl-top-nav-item` (native `<a>` or `role="button"`) with keyboard activation (Enter / Space where applicable).
+- **Dropdown items:** Items with `slot="dropdown"` expose `aria-expanded` on the inner control; **Escape** closes the dropdown (document capture). **Escape** on the shell closes the mobile drawer only after dropdowns and **any** open descendant **`xpl-popover`** are closed (document capture vs bubble ordering). Arrow-key navigation within the dropdown panel is not built in.
+- **Icon-only items:** With **`icon`** and no **`label`** or default-slot text, the inner control gets **`aria-label`** (**`item-aria-label`** to override, else **`Navigation item`**).
+- **Lists:** `left-aside` is wrapped in `role="list"`; each primary link `xpl-top-nav-item` uses `role="listitem"`. The built-in brand row (`xpl-top-nav__brand`) omits `listitem` because it sits outside that list; `slot="right-aside-mobile"` rows omit it as well. `xpl-nav-header-menu` default-slot rows still use `listitem` (menu list contract).
+
+<!-- Auto Generated Below -->
+
+
+## Overview
+
+Horizontal top navigation with **`left-aside`** and a **right rail**: **`right-aside`** then **user menu**
+(see **`.xpl-top-nav__right-rail`** in `render()`). The account menu uses an internal **`xpl-popover`** (**`bottom-end`**, **`display="menu"`**): built-in trigger uses **`child-account-label`** (prop / attribute) as the label beside a trailing **`chevron-down`** on **`xpl-button`** (**`icon`** / **`iconPosition="end"`**), or **`slot="user-menu-trigger"`** for a custom trigger; panel from **`slot="user-menu"`** (e.g. **`xpl-nav-header-menu`**).
+Optional **`nav-control`** and **`navOpen`**. **`left-aside`** uses **`role="list"`** for primary **`xpl-top-nav-item`** rows (**`role="listitem"`** on each item host). The built-in **`xpl-top-nav__brand`** item omits **`listitem`** (it is not a child of that list). **`label`** maps to **`nav`** **`aria-label`**. Opening state is internal (not a prop) — use **`navOpen`** and host **`xpl-top-nav--open`** for styling.
+
+**Escape:** With **`nav-control`**, **Escape** closes the mobile drawer and emits **`navOpen`** **`false`** (skips while **any** descendant **`xpl-popover`** is open — detected from each popover’s inner **`.xpl-popover--is-open`** marker — or when a **`xpl-top-nav-item`** dropdown is open — capture/bubble order). Focus returns to the nav toggle after the drawer closes (**Escape** or second toggle click).
+**`xpl-top-nav-item`** **`slot="dropdown"`** uses document **capture** for **Escape** first; the shell uses **bubble**
+on **`ownerDocument`** so nested dropdowns close before the drawer.
+
+**Theming:** The host always includes Foundation’s **`dark`** class so **`--xpl-*`** purpose tokens under this subtree
+resolve to dark-mode values even when the page root is light. Floating overlays (e.g. **`xpl-popover`** / **`xpl-dropdown`**
+content teleported outside the host) do not inherit this scope — add **`dark`** on those panels if they should match.
+
+**Layout:** **`right-aside`** and the user-menu region are wrapped internally (**`.xpl-top-nav__right-lead`**, etc.).
+Consumers should not add those BEM classes — slot content only.
+
+**Brand logo:** use **`brand-logo`** (URL) for a built-in **`<img>`**, or **`slot="brand-logo"`** for custom markup (e.g. **`xpl-icon`**, SVG). When the URL prop is set, it takes precedence and the slot is not used for the image. On **narrow viewports** (one pixel below Tailwind **`md`** — see **`top-nav.css`**), **`brand-name`** text is hidden in the bar (logo / slot mark only); keep a meaningful **`alt`** on **`brand-logo`** or accessible slotted mark for context.
+
+**Narrow / mobile** (same breakpoint as above): **`slot="left-aside"`** is **hidden** in the bar until **`nav-control`**
+is set **and** the drawer is open (floating panel per Figma). **Without **`nav-control`**, there is no mobile drawer** —
+primary links remain hidden below **`md`** until the viewport is wide enough for the horizontal bar. The built-in **brand**
+stays in the top bar (**hamburger → brand** when **`nav-control`** is set). **`right-aside`** is hidden in the bar on narrow
+viewports (**`top-nav.css`**, one pixel below Tailwind **`md`**); duplicate those actions into **`xpl-nav-header-menu`**
+**`slot="right-aside-mobile"`** (below profile, above the list; narrow-only CSS in **`top-nav.css`**) per Figma.
+
+**Account menu vs drawer:** Opening the built-in account **`xpl-popover`** while the mobile drawer is open **closes the drawer**
+and emits **`navOpen(false)`** so the two layers do not stack.
+
+## Properties
+
+| Property            | Attribute             | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Type      | Default     |
+| ------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ----------- |
+| `brandHref`         | `brand-href`          | Destination URL for the brand control when using native navigation (**`<a href>`**). When unset, the brand is a **`role="button"`** control and **`brandClick`** fires on activation instead.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | `string`  | `undefined` |
+| `brandLogo`         | `brand-logo`          | Optional image URL for the brand mark (leading the brand row, before **`brand-name`** text). When set, renders **`<img class="xpl-top-nav__brand-logo">`** and ignores **`slot="brand-logo"`** for the mark. When unset, use **`slot="brand-logo"`** for custom logo content.                                                                                                                                                                                                                                                                                                                                                                                                               | `string`  | `undefined` |
+| `brandName`         | `brand-name`          | Visible product / app name next to **`brand-logo`**. Omit for logo-only; provide **`brand-logo`** and/or this string to show the built-in brand row (**`left-aside`** is then primary nav links only).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `string`  | `undefined` |
+| `childAccountLabel` | `child-account-label` | Label text for the built-in account menu trigger (shown **before** the **`chevron-down`** icon) when **`slot="user-menu"`** is present and **`slot="user-menu-trigger"`** is not used. When empty or whitespace-only, the trigger shows only the chevron and uses **`aria-label="Open account menu"`** on the button.                                                                                                                                                                                                                                                                                                                                                                       | `string`  | `undefined` |
+| `label`             | `label`               | Accessible name for the `<nav>` landmark (maps to `aria-label`). Use a unique label when the page has multiple navigation regions (e.g. side nav + top nav). When unset, defaults to `top-navigation-bar`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | `string`  | `undefined` |
+| `navControl`        | `nav-control`         | When true, renders the navigation control (hamburger) for toggling the left slot on small viewports. The control is **hidden from the Tailwind `md` breakpoint up**; collapse/show for **`left-aside`** uses **`max-width: calc(theme('screens.md') - 1px)`** in **`top-nav.css`** (Figma’s 767px at a 16px root and default **`screens.md`**). Reflected to the **`nav-control`** attribute so host updates (framework props) re-run **`@Watch`**: drawer state and document **Escape** handling stay in sync, the host **`xpl-top-nav--nav-control`** class toggles for **`top-nav.css`**, and **`navOpen(false)`** is emitted if **`nav-control`** is cleared while the drawer was open. | `boolean` | `undefined` |
+
+
+## Events
+
+| Event        | Description                                                                                                                                                                                                                                                          | Type                      |
+| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- |
+| `brandClick` | Emitted when the brand control is activated and **`brandHref`** is **not** set (SPA / in-app navigation). **`detail`** is the **`MouseEvent`** from **`xpl-top-nav-item`** **`navItemClick`**. Not emitted when **`brandHref`** is set (use native link navigation). | `CustomEvent<MouseEvent>` |
+| `navOpen`    | Emitted when the mobile nav open state changes: hamburger toggle, or **Escape** closing the drawer (when **`nav-control`** is set and the bar was open). Detail is the new open state (**`true`** = open, **`false`** = closed).                                     | `CustomEvent<boolean>`    |
+
+
+## Slots
+
+| Slot                  | Description                                                                                                                                                                                                                                                                                                                                                     |
+| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `"brand-logo"`        | Custom brand mark when **`brand-logo`** URL is not set; placed before **`brand-name`** in the brand row.                                                                                                                                                                                                                                                        |
+| `"left-aside"`        | Primary navigation (**`xpl-top-nav-item`** links). After the brand on wide viewports; below **`md`**, visible only inside the **`nav-control`** drawer when open (otherwise hidden).                                                                                                                                                                            |
+| `"right-aside"`       | Right-side actions before the user menu. Hidden on narrow viewports (**`top-nav.css`** below **`md`**).                                                                                                                                                                                                                                                         |
+| `"user-menu"`         | Account popover panel only (e.g. **`xpl-nav-header-menu`** with menu **`xpl-top-nav-item`** children). Trigger is **`slot="user-menu-trigger"`** or the built-in button (**`child-account-label`** text + chevron). Use **`slot="right-aside-mobile"`** on **`xpl-nav-header-menu`** for narrow-only duplicates of **`right-aside`** (below the profile block). |
+| `"user-menu-trigger"` | Optional override for the popover trigger. When set, the built-in **`child-account-label`** trigger is ignored.                                                                                                                                                                                                                                                 |
+
+
+## Dependencies
+
+### Depends on
+
+- [xpl-icon](../xpl-icon)
+- [xpl-top-nav-item](xpl-top-nav-item)
+- [xpl-popover](../xpl-popover)
+- [xpl-button](../xpl-button)
+
+### Graph
+```mermaid
+graph TD;
+  xpl-top-nav --> xpl-icon
+  xpl-top-nav --> xpl-top-nav-item
+  xpl-top-nav --> xpl-popover
+  xpl-top-nav --> xpl-button
+  xpl-top-nav-item --> xpl-icon
+  xpl-button --> xpl-icon
+  style xpl-top-nav fill:#f9f,stroke:#333,stroke-width:4px
+```
+
+----------------------------------------------
+
+*Built with [StencilJS](https://stenciljs.com/)*