@xplortech/apollo-core 2.6.0 → 2.7.0

package/dist/docs/xpl-table/xpl-table-footer-cell/readme.md

@@ -0,0 +1,30 @@
+# xpl-table-footer-cell
+
+
+
+<!-- Auto Generated Below -->
+
+
+## Properties
+
+| Property | Attribute | Description                                | Type                            | Default  |
+| -------- | --------- | ------------------------------------------ | ------------------------------- | -------- |
+| `align`  | `align`   | Horizontal text alignment within the cell. | `"center" \| "left" \| "right"` | `'left'` |
+
+
+## Dependencies
+
+### Used by
+
+ - [xpl-table](..)
+
+### Graph
+```mermaid
+graph TD;
+  xpl-table --> xpl-table-footer-cell
+  style xpl-table-footer-cell fill:#f9f,stroke:#333,stroke-width:4px
+```
+
+----------------------------------------------
+
+*Built with [StencilJS](https://stenciljs.com/)*

package/dist/docs/{xpl-table-header → xpl-table/xpl-table-header}/readme.md

@@ -1,13 +1,13 @@
-# xpl-table-header
-
-Component parts used to assemble the Dynamic Table.
-
-> **Note:** This component is currently in beta. Use with caution as it may have breaking changes in future releases.
-
-
-<!-- Auto Generated Below -->
-
-
-----------------------------------------------
-
-*Built with [StencilJS](https://stenciljs.com/)*
+# xpl-table-header
+
+Semantic wrapper for the header **row group** in a compositional `xpl-table` (`role="rowgroup"`). Place one `xpl-table-row` (with `xpl-table-header-cell` children) inside.
+
+> **Note:** This component is currently in beta. Use with caution as it may have breaking changes in future releases.
+
+
+<!-- Auto Generated Below -->
+
+
+----------------------------------------------
+
+*Built with [StencilJS](https://stenciljs.com/)*

package/dist/docs/xpl-table/xpl-table-header-cell/readme.md

@@ -0,0 +1,66 @@
+# xpl-table-header-cell
+
+> **Note:** This component is currently in beta. Use with caution as it may have breaking changes in future releases.
+
+The `icon` property accepts icon names as strings. See [xpl-icon available icons](../xpl-icon/ICONS.md) for the complete list.
+
+When this cell is used inside a compositional [`xpl-table`](../xpl-table) with `selectable`, **you** add a `type="checkbox"` header cell for select-all; `xpl-table` keeps `checked` and `indeterminate` in sync with row selection.
+
+For **sortable** columns (`type="label"`), set **`sortable`** and optionally **`sort-key`**; the parent table emits **`sortChanged`** (see [`xpl-table` events](../xpl-table#events)).
+
+**Column width (compositional grid):** Each header cell defines one grid column on the parent `xpl-table`. By default the track is **`auto`** (sizes from content). Set **`width`** for a fixed pixel width (minimum 48px), or **`column-width`** for any CSS grid track string (`1fr`, `minmax(120px, 1fr)`, etc.). When both are set, **`column-width` wins**.
+
+---
+
+<!-- Auto Generated Below -->
+
+
+## Properties
+
+| Property            | Attribute             | Description                                                                                                                                                                                                              | Type                                         | Default     |
+| ------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------- | ----------- |
+| `align`             | `align`               | Horizontal text alignment within the header cell.                                                                                                                                                                        | `"center" \| "left" \| "right"`              | `'left'`    |
+| `checkboxAriaLabel` | `checkbox-aria-label` | Accessible name for the header checkbox (native `aria-label`). Defaults to “Select all rows” when `type` is `checkbox`.                                                                                                  | `string`                                     | `undefined` |
+| `checked`           | `checked`             | Whether the header checkbox is checked                                                                                                                                                                                   | `boolean`                                    | `false`     |
+| `columnWidth`       | `column-width`        | CSS grid track size for this column (e.g. `1fr`, `minmax(120px, 1fr)`, `auto`). When set, overrides `width`. Use this when you need flexible columns; default layout uses `auto` per column unless you set a track here. | `string`                                     | `undefined` |
+| `icon`              | `icon`                | Icon to display in the cell.  See [xpl-icon available icons](../xpl-icon/ICONS.md) for valid icon names.                                                                                                                 | `string`                                     | `undefined` |
+| `indeterminate`     | `indeterminate`       | Whether the checkbox is in indeterminate (partially selected) state                                                                                                                                                      | `boolean`                                    | `false`     |
+| `label`             | `label`               | Text to display in the cell.                                                                                                                                                                                             | `string`                                     | `''`        |
+| `sortDirection`     | `sort-direction`      | Active sort direction for this column when `sortable`. Set by `xpl-table` when used inside a compositional table; may be set by the app for controlled updates.                                                          | `"asc" \| "desc"`                            | `undefined` |
+| `sortKey`           | `sort-key`            | When `sortable` is true, optional stable id used as the key in `sortChanged`’s detail object. Falls back to a slug of `label` when omitted.                                                                              | `string`                                     | `undefined` |
+| `sortable`          | `sortable`            | When true (and `type` is `label`), renders a sort control (button + affordance icon).                                                                                                                                    | `boolean`                                    | `false`     |
+| `type`              | `type`                | The type of cell to render.                                                                                                                                                                                              | `"checkbox" \| "empty" \| "icon" \| "label"` | `'label'`   |
+| `width`             | `width`               | Fixed width for this column in pixels (minimum 48px). Sets the grid track to `Npx`. Ignored when `columnWidth` is set. When omitted, the column track defaults to `auto` (content-sized).                                | `number`                                     | `undefined` |
+
+
+## Events
+
+| Event                  | Description                                                                                                        | Type                                  |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------- |
+| `headerCheckboxChange` | Emitted when header checkbox changes                                                                               | `CustomEvent<boolean>`                |
+| `headerSortChange`     | Emitted when a sortable label header is activated. Parent `xpl-table` coordinates columns and emits `sortChanged`. | `CustomEvent<HeaderSortChangeDetail>` |
+
+
+## Dependencies
+
+### Used by
+
+ - [xpl-table](..)
+
+### Depends on
+
+- [xpl-icon](../../xpl-icon)
+- [xpl-checkbox](../../xpl-checkbox)
+
+### Graph
+```mermaid
+graph TD;
+  xpl-table-header-cell --> xpl-icon
+  xpl-table-header-cell --> xpl-checkbox
+  xpl-table --> xpl-table-header-cell
+  style xpl-table-header-cell fill:#f9f,stroke:#333,stroke-width:4px
+```
+
+----------------------------------------------
+
+*Built with [StencilJS](https://stenciljs.com/)*

package/dist/docs/xpl-table/xpl-table-row/readme.md

@@ -0,0 +1,19 @@
+# xpl-table-row
+
+
+
+<!-- Auto Generated Below -->
+
+
+## Properties
+
+| Property   | Attribute  | Description                                                                                                                             | Type      | Default     |
+| ---------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------- | --------- | ----------- |
+| `disabled` | `disabled` | Whether the row and its cells are disabled.                                                                                             | `boolean` | `false`     |
+| `rowId`    | `row-id`   | Stable identifier for this row when used with a selectable compositional `xpl-table`. If omitted, the parent table assigns a unique id. | `string`  | `undefined` |
+| `selected` | `selected` | Whether the row is visually selected.                                                                                                   | `boolean` | `false`     |
+
+
+----------------------------------------------
+
+*Built with [StencilJS](https://stenciljs.com/)*

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

@@ -1,23 +1,76 @@
 # xpl-tabs
 
-Tabs organize content across different screens, data sets, and other interactions.
+`xpl-tabs` groups related views into a single surface: users pick a **tab** to show the matching **panel**. It implements the WAI-ARIA tabs pattern with a horizontal tab list, optional full-width layout, and two visual styles—**underline** (`type="tabs"`, default) and **segment** (`type="segment"`, pill controls in a bordered track)—selected with the **`type`** prop. On narrow viewports the heading row is replaced by an `xpl-select` so the same targets and keyboard behavior stay consistent.
+
+The **Tabs** and **Segment control** Storybook entries document this **one component** with different defaults and Figma references. Each page adds variant-specific guidance (when to use, examples, tokens); the sections below describe behavior that is **the same for both** styles.
+
+Pair **`xpl-tab` (slot `heading`)** with **`xpl-tab-panel` (slot `panel`)** and use the same **`target`** string on each pair so selection stays in sync.
+
+## Usage
+
+### Web component (`<xpl-tabs>`)
+
+Minimal group with two tabs: each `xpl-tab` and `xpl-tab-panel` shares a `target` value. Set `value` on `xpl-tabs` to control the selected tab (defaults to the first tab’s `target` if omitted).
+
+```html
+<xpl-tabs value="one">
+  <xpl-tab slot="heading" target="one">First</xpl-tab>
+  <xpl-tab slot="heading" target="two">Second</xpl-tab>
+  <xpl-tab-panel slot="panel" target="one">Content for first tab.</xpl-tab-panel>
+  <xpl-tab-panel slot="panel" target="two">Content for second tab.</xpl-tab-panel>
+</xpl-tabs>
+```
+
+Listen for selection changes with the **`tabChange`** event (detail is the selected `target` string):
+
+```html
+<xpl-tabs id="demo" value="a">
+  <xpl-tab slot="heading" target="a">A</xpl-tab>
+  <xpl-tab slot="heading" target="b">B</xpl-tab>
+  <xpl-tab-panel slot="panel" target="a">…</xpl-tab-panel>
+  <xpl-tab-panel slot="panel" target="b">…</xpl-tab-panel>
+</xpl-tabs>
+<script>
+  document.getElementById('demo').addEventListener('tabChange', (e) => {
+    console.log(e.detail); // "a" | "b"
+  });
+</script>
+```
+
+Disable the entire group (headings, mobile select, and segment pills) with **`disabled`** on `xpl-tabs`. Disable individual tabs with **`disabled`** on `xpl-tab`.
+
+### Plain HTML (BEM classes)
+
+When styling with `tabs.css` without the Stencil component, mirror the structure: `xpl-tabs`, `xpl-tabs__headings` with `role="tablist"` and `aria-orientation="horizontal"`, `xpl-tabs__active-bar` for the underline variant (position/size normally set by JS), **`button.xpl-tab__button`** with **`role="tab"`** (not links), and **`xpl-tab-panel`** for panels. For **segment** (`xpl-tabs--segment`), each heading is **`xpl-tab.xpl-tab--segment`** wrapping **`xpl-button`** (not `.xpl-tab__button`). On small viewports, include **`xpl-tabs__mobile-select`** with **`xpl-select`** for parity with the component.
+
+## Accessibility
+
+- Each **`xpl-tabs`** root gets a unique **`data-tabs-instance-id`** (for example `xpl-tg-1`). **`xpl-tab`** and **`xpl-tab-panel`** derive matching DOM **`id`** values from that id plus the shared **`target`** string: the tab control is **`…-tab-<target>`**, the panel is **`…-panel-<target>`** (with `target` sanitized for HTML `id` rules). The tab exposes **`aria-controls`** pointing at the panel id, **`aria-selected`**, and the panel uses **`aria-labelledby`** pointing at the tab id. **Segment (pill) tabs** render **`xpl-button`**; because **`xpl-button`** does not forward **`id`** / **`role`** / **`aria-*`** to its inner `<button>`, **`xpl-tab`** sets those on the native button after render so focus order and **`aria-labelledby`** stay correct (same pattern as underline tabs, different host element).
+- The tab list container is **`role="tablist"`** with **`aria-orientation="horizontal"`**. Underline tabs use **`role="tab"`** on the inner `<button>`; panels use **`role="tabpanel"`** on **`xpl-tab-panel`**.
+- **Roving tabindex:** only the active tab’s control is in the tab order (`tabindex="0"`); others use `tabindex="-1"` until focused with arrows.
+- **Keyboard:** **Arrow Left/Right** (and **Arrow Up/Down** as next/previous), **Home**, and **End** move between enabled tabs; **Enter** and **Space** activate (via `xpl-button` in segment mode). Direction mirrors in **RTL**.
+- When **`disabled`** is set on `xpl-tabs`, tab keyboard navigation and selection are suppressed for the group.
+
+Variant-specific Foundation mappings for underline vs. segment live in the **Tabs** and **Segment control** Storybook pages. The **`xpl-select`** mobile row reuses **`xpl-select`** / **`xpl-dropdown`** tokens from those components.
 
 <!-- Auto Generated Below -->
 
 
 ## Properties
 
-| Property    | Attribute    | Description                                              | Type      | Default     |
-| ----------- | ------------ | -------------------------------------------------------- | --------- | ----------- |
-| `fullWidth` | `full-width` | Whether to make the tabs full width                      | `boolean` | `false`     |
-| `value`     | `value`      | The selected tab target value, defaults to the first tab | `string`  | `undefined` |
+| Property    | Attribute    | Description                                                                   | Type                  | Default     |
+| ----------- | ------------ | ----------------------------------------------------------------------------- | --------------------- | ----------- |
+| `disabled`  | `disabled`   | Disables the whole tab group (headings, mobile select, and segment pills).    | `boolean`             | `false`     |
+| `fullWidth` | `full-width` | Whether to make the tabs full width                                           | `boolean`             | `false`     |
+| `type`      | `type`       | Visual and layout variant: classic underline tabs or segment (pill) controls. | `"segment" \| "tabs"` | `'tabs'`    |
+| `value`     | `value`      | The selected tab target value, defaults to the first tab                      | `string`              | `undefined` |
 
 
 ## Events
 
-| Event       | Description                                     | Type                  |
-| ----------- | ----------------------------------------------- | --------------------- |
-| `tabChange` | Event that emits the target of the selected tab | `CustomEvent<string>` |
+| Event       | Description                                                                                                                                                                                                                                                                                     | Type                  |
+| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- |
+| `tabChange` | Emitted when the selected tab changes (click, keyboard, or mobile `xpl-select`). The event `detail` is the selected tab’s `target` string. Always dispatched from this host (including after heading clicks) so `event.target` is consistent for listeners on `xpl-tabs` or bubbling ancestors. | `CustomEvent<string>` |
 
 
 ## Slots
@@ -41,6 +94,7 @@ graph TD;
   xpl-select --> xpl-tag
   xpl-select --> xpl-icon
   xpl-select --> xpl-dropdown
+  xpl-tag --> xpl-icon
   xpl-dropdown --> xpl-dropdown-group
   xpl-dropdown --> xpl-dropdown-option
   xpl-dropdown-group --> xpl-dropdown-group

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
 ```