@xplortech/apollo-core 2.5.0 → 2.7.0

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

@@ -1,26 +1,124 @@
 # xpl-badge
 
+`xpl-badge` is a small, non-interactive status indicator used to communicate counts, states, or supplementary information next to another element. Badges are **never clickable** – use a button or link if you need interaction.
+
+Badges support multiple **variants** (colors), **sizes**, **shapes**, and **dot styles**, so they can be used both as pill labels and as compact status / notification indicators.
+
+## Usage
+
+```html
+<xpl-badge variant="green">Active</xpl-badge>
+<xpl-badge variant="yellow">Pending</xpl-badge>
+<xpl-badge variant="red">Error</xpl-badge>
+<xpl-badge variant="gray" size="small">Draft</xpl-badge>
+```
+
+Attach badges close to the item they describe (a label, row, chip, or control). Prefer **short labels** (often one or two words) for readability.
+
+### Label text and overflow
+
+Slot content is rendered inside an internal `.xpl-badge__label` wrapper (you do not add this in your markup). Labels are **single-line**: text does not wrap to multiple lines. When horizontal space is tight (for example a narrow column or flex layout), overflowing text **truncates with an ellipsis** (`…`). The host respects the parent width (`max-width: 100%`). If truncation makes a label hard to read, shorten the copy or widen the layout; use a tooltip or similar only if your product needs the full string on hover.
+
+## Sizes & shapes
+
+- **size**
+  - `default` (default): `24px` tall pill, used for most cases.
+  - `small`: `20px` tall, more compact for dense UIs or table rows.
+- **shape**
+  - `rounded` (default): full pill with fully rounded ends.
+  - `boxy`: rounded corners but not a full pill; better for more neutral / data-heavy contexts.
+
+```html
+<xpl-badge size="default" shape="rounded">Default pill</xpl-badge>
+<xpl-badge size="small" shape="boxy">Small boxy</xpl-badge>
+```
+
+## Dots and dot-only badges
+
+### Dot badge (pill with leading dot)
+
+Set `dot` to add a colored dot before the text, inside the pill:
+
+```html
+<xpl-badge variant="green" dot>Online</xpl-badge>
+<xpl-badge variant="yellow" dot>Syncing</xpl-badge>
+<xpl-badge variant="red" dot>Error</xpl-badge>
+```
+
+### Dot-only badge (compact status / count)
+
+> [!IMPORTANT]
+> Dot-only badges are meant to be used with **numeric values** (or very short strings). For longer text labels, use the standard badge (without `dot-only`).
+
+- When overlaying another element with a background color, use the `bordered` property so the badge separates clearly from what is behind it.
+
+Set `dot-only` when you want a badge built around the dot:
+
+- With **no children**: renders a small circular status dot.
+- With **children**: renders a compact pill with text or a number inside (for example an unread count).
+- **Notification-style counts** are often appended to a label or another component. Dot-only label text follows the same **single-line truncation** rules as standard badges when space is limited.
+- Use **`bordered`** to toggle a ring around the dot badge for separation from an avatar or similar surface.
+
+```html
+<!-- Status dot only -->
+<xpl-badge variant="green" dot-only></xpl-badge>
+
+<!-- Dot with count / text -->
+<xpl-badge variant="red" dot-only>3</xpl-badge>
+<xpl-badge variant="blue" dot-only>99+</xpl-badge>
+```
+
+## Variants
+
+Use variants to communicate state or category. Preferred values for `variant`:
+
+- `purple` (default)
+- `green`
+- `yellow`
+- `orange`
+- `gray`
+- `red`
+- `blue`
+
+The legacy semantic names `success`, `warning`, `inactive`, and `error` are still accepted and map to `green`, `yellow`, `gray`, and `red` respectively. Prefer the color names for new code.
+
+```html
+<xpl-badge variant="purple">Default</xpl-badge>
+<xpl-badge variant="orange" dot>In progress</xpl-badge>
+<xpl-badge variant="blue" dot-only>12</xpl-badge>
+```
+
+- Each dot has **stronger solid color** for dot-only badges, with dark-mode adjustments handled by CSS.
+
+- Each variant uses Apollo Foundation badge tokens (`--xpl-background-badge-`*, `--xpl-border-badge-*`, `--xpl-icon-badge-*`, `--xpl-text-badge-*`) that auto-switch between light and dark modes. Dot-only badges use the corresponding `--xpl-icon-badge-*` accent color for their solid fill.
+
 <!-- Auto Generated Below -->
 
 
 ## Properties
 
-| Property  | Attribute | Description                                    | Type                                              | Default     |
-| --------- | --------- | ---------------------------------------------- | ------------------------------------------------- | ----------- |
-| `dot`     | `dot`     | Whether badge shows a dot icon before the text | `boolean`                                         | `undefined` |
-| `variant` | `variant` | Color styles to indicate varied states         | `"error" \| "inactive" \| "success" \| "warning"` | `undefined` |
+| Property   | Attribute  | Description                                                                                                                                                                                                                                                                                            | Type                                                                                                                          | Default     |
+| ---------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- | ----------- |
+| `bordered` | `bordered` | Whether badge shows a bordered ring                                                                                                                                                                                                                                                                    | `boolean`                                                                                                                     | `false`     |
+| `dot`      | `dot`      | Whether badge shows a dot icon before the text (inside the pill)                                                                                                                                                                                                                                       | `boolean`                                                                                                                     | `undefined` |
+| `dotOnly`  | `dot-only` | When true, render a compact badge built around the dot. - With no children: just a dot (status/dot badge) - With children: a small dot badge with the text/number inside                                                                                                                               | `boolean`                                                                                                                     | `false`     |
+| `shape`    | `shape`    | Badge shape rounded (pill) boxy (rounded corners)                                                                                                                                                                                                                                                      | `"boxy" \| "rounded"`                                                                                                         | `'rounded'` |
+| `size`     | `size`     | Badge size default \| small                                                                                                                                                                                                                                                                            | `"default" \| "small"`                                                                                                        | `'default'` |
+| `variant`  | `variant`  | Badge variant (color).  Preferred values: `purple`, `green`, `yellow`, `orange`, `gray`, `red`, `blue`.  The legacy semantic names `success`, `warning`, `inactive`, and `error` are still accepted and map to `green`, `yellow`, `gray`, and `red` respectively. Prefer the color names for new code. | `"blue" \| "error" \| "gray" \| "green" \| "inactive" \| "orange" \| "purple" \| "red" \| "success" \| "warning" \| "yellow"` | `'purple'`  |
 
 
 ## Dependencies
 
 ### Used by
 
- - [xpl-list](../xpl-list)
+ - [xpl-avatar](../xpl-avatar)
+ - [xpl-list-item](../xpl-list/xpl-list-item)
 
 ### Graph
 ```mermaid
 graph TD;
-  xpl-list --> xpl-badge
+  xpl-avatar --> xpl-badge
+  xpl-list-item --> xpl-badge
   style xpl-badge fill:#f9f,stroke:#333,stroke-width:4px
 ```
 

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

@@ -0,0 +1,203 @@
+# xpl-banner
+
+Banners display a system level or page level message at the top of the screen. The section-banner variant displays important messages inline within a section.
+
+## Usage
+
+### Web component (`<xpl-banner>`)
+
+Bar layout (default) with heading, description, primary action, and dismiss:
+
+```html
+<xpl-banner
+  appearance="information"
+  heading="Your session will expire soon."
+  description="Save your work to avoid losing changes."
+  action-text="Extend session"
+  is-dismissible="true"
+></xpl-banner>
+```
+
+Section layout with optional secondary action and no leading icon:
+
+```html
+<xpl-banner
+  appearance="positive"
+  is-section="true"
+  has-icon="false"
+  heading="Changes saved"
+  description="Your updates are stored."
+  action-text="View details"
+  secondary-action-text="Undo"
+></xpl-banner>
+```
+
+### Plain HTML (BEM classes)
+
+Use the same structure when styling with `banner.css` without the Stencil component. Switch bar vs section with host modifiers (`xpl-banner--section`, `xpl-banner--no-icon`, `xpl-banner--{appearance}`).
+
+## Accessibility
+
+`xpl-banner` uses `role="region"` so the banner is a navigable landmark.
+
+**`aria-label` on the host (never empty):**
+
+| Layout | `aria-label` source |
+| ------ | ------------------- |
+| Bar (default) | Fixed label from `appearance`: `"Information banner"`, `"Positive banner"`, `"Warning banner"`, or `"Error banner"`. |
+| Section | Trimmed `heading` when present; otherwise `"Section banner"`. |
+
+Keyboard: **Tab** moves focus to action buttons and the dismiss control; **Enter** and **Space** activate `xpl-button` actions and the dismiss button. Focus rings use `:focus-visible` (dismiss uses appearance-specific outline tokens in CSS; actions use `xpl-button` focus styles).
+
+- The leading icon wrapper carries `aria-hidden="true"` — the icon is decorative; the message text is the accessible content.
+- The dismiss `<xpl-icon>` inside the dismiss button also carries `aria-hidden="true"` so the decorative icon is not announced in addition to the button label.
+- The dismiss button `aria-label` is `"Dismiss banner"` in bar layout and `"Dismiss section banner"` when `is-section` is true.
+
+## Token Use
+
+- `information`
+  - Background: `--xpl-background-messaging-information`
+  - Border: `--xpl-border-accent-information`
+  - Icon: `--xpl-icon-default`
+  - Main text: `--xpl-text-strong` (with `--xpl-text-default` fallback)
+  - Detail text: `--xpl-text-default`
+- `warning`
+  - Background: `--xpl-background-messaging-warning`
+  - Border: `--xpl-border-accent-warning`
+  - Icon: `--xpl-icon-default`
+  - Main text: `--xpl-text-strong` (with `--xpl-text-default` fallback)
+  - Detail text: `--xpl-text-default`
+  - Dismiss focus ring: `--xpl-border-accent-warning`
+- `positive`
+  - Background: `--xpl-background-messaging-positive`
+  - Border: `--xpl-border-positive`
+  - Icon: `--xpl-icon-default`
+  - Main text: `--xpl-text-strong` (with `--xpl-text-default` fallback)
+  - Detail text: `--xpl-text-default`
+- `error`
+  - Background: `--xpl-background-messaging-negative-bold`
+  - Border: `--xpl-border-negative`
+  - Icon and text: `--xpl-text-inverse-on-dark`
+  - Dismiss focus ring: `--xpl-text-inverse-on-dark`
+- Dismiss button follows the same icon token as the current appearance.
+- `information` dismiss focus ring uses `--xpl-border-accent-information`.
+
+Light and dark mode are handled by Apollo Foundation token definitions. `xpl-banner` does not use component-level `.dark` token overrides.
+
+## Icon Mapping
+
+Each `appearance` value maps to a fixed `xpl-icon` name. When building the component in plain HTML, use the icon from this table:
+
+| `appearance`  | `xpl-icon` name    |
+| ------------- | ------------------ |
+| `information` | `circle-info`      |
+| `warning`     | `triangle-warning` |
+| `positive`    | `circle-check`     |
+| `error`       | `octagon-warning`  |
+
+## Actions
+
+Use `actionText` and `secondaryActionText` to render up to two `xpl-button` actions in the banner.
+Both action buttons always render at `size="xs"` to match compact banner spacing.
+
+The `variant` and `state` attributes on the action buttons depend on both `appearance` and layout:
+
+| Layout    | `appearance`  | `variant`   | `state`     |
+| --------- | ------------- | ----------- | ----------- |
+| bar       | `information` | `subtle`    | —           |
+| bar       | `warning`     | `subtle`    | —           |
+| bar       | `positive`    | `subtle`    | —           |
+| bar       | `error`       | `primary`   | `warning`   |
+| section   | `information` | `subtle`    | —           |
+| section   | `warning`     | `subtle`    | —           |
+| section   | `positive`    | `subtle`    | `success`   |
+| section   | `error`       | `subtle`    | `warning`   |
+
+## Section Layout
+
+Set `is-section` to render the section-banner layout:
+- Header row with icon, heading, and optional dismiss
+- Description below the header (2-line clamp by default)
+- Actions below description
+
+Set `has-icon="false"` to hide the leading icon in the section layout. This applies `xpl-banner--no-icon` on the host, which shifts heading, description, and actions to start in the first grid column instead of the second. In bar layout the icon always renders regardless of `hasIcon`.
+
+Bar and section variants share the same DOM shape. Plain-HTML example (classes only):
+
+```html
+<!-- Bar variant -->
+<div class="xpl-banner xpl-banner--information">
+  <div class="xpl-banner__icon" aria-hidden="true">
+    <xpl-icon icon="circle-info" size="24"></xpl-icon>
+  </div>
+  <div class="xpl-banner__body">
+    <p class="xpl-banner__heading">Heading</p>
+    <p class="xpl-banner__description">Description text</p>
+  </div>
+  <div class="xpl-banner__actions">
+    <xpl-button size="xs" variant="subtle">Action</xpl-button>
+  </div>
+  <button class="xpl-banner__dismiss" type="button" aria-label="Dismiss banner">
+    <xpl-icon icon="xmark" size="24" aria-hidden="true"></xpl-icon>
+  </button>
+</div>
+
+<!-- Section variant — add xpl-banner--section; same markup otherwise -->
+<div class="xpl-banner xpl-banner--section xpl-banner--information">
+  ...
+</div>
+
+<!-- Section variant without icon -->
+<div class="xpl-banner xpl-banner--section xpl-banner--no-icon xpl-banner--information">
+  <!-- omit .xpl-banner__icon -->
+  <div class="xpl-banner__body">...</div>
+  ...
+</div>
+```
+
+<!-- Auto Generated Below -->
+
+
+## Properties
+
+| Property              | Attribute               | Description                                                                                                                                                                                                                                                                | Type                                                  | Default         |
+| --------------------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | --------------- |
+| `actionText`          | `action-text`           | Primary action label. When provided, an action button is rendered.                                                                                                                                                                                                         | `string`                                              | `undefined`     |
+| `appearance`          | `appearance`            | Controls the visual appearance and semantic meaning of the banner. These values map to messaging background/border token sets in `banner.css`. Banner icons use `--xpl-icon-default`, except `error` which uses inverse icon/text tokens for contrast on dark backgrounds. | `"error" \| "information" \| "positive" \| "warning"` | `'information'` |
+| `description`         | `description`           | Optional supporting message shown after the heading. Description text uses `--xpl-text-default`.                                                                                                                                                                           | `string`                                              | `undefined`     |
+| `hasIcon`             | `has-icon`              | Whether to render the leading icon in section layout. Ignored in bar layout — bar banners always show the icon.                                                                                                                                                            | `boolean`                                             | `true`          |
+| `heading`             | `heading`               | Primary banner message shown with stronger title typography.                                                                                                                                                                                                               | `string`                                              | `undefined`     |
+| `isDismissible`       | `is-dismissible`        | Whether to show the trailing dismiss control.                                                                                                                                                                                                                              | `boolean`                                             | `true`          |
+| `isSection`           | `is-section`            | Renders the section-style banner layout when true.                                                                                                                                                                                                                         | `boolean`                                             | `false`         |
+| `secondaryActionText` | `secondary-action-text` | Secondary action label. When provided, a second action button is rendered.                                                                                                                                                                                                 | `string`                                              | `undefined`     |
+| `truncateDesc`        | `truncate-desc`         | When true, `description` is constrained to one line with ellipsis so banner height stays stable.                                                                                                                                                                           | `boolean`                                             | `false`         |
+
+
+## Events
+
+| Event             | Description                                   | Type                |
+| ----------------- | --------------------------------------------- | ------------------- |
+| `action`          | Emitted when the primary action is clicked.   | `CustomEvent<void>` |
+| `dismiss`         | Emitted when the dismiss button is clicked.   | `CustomEvent<void>` |
+| `secondaryAction` | Emitted when the secondary action is clicked. | `CustomEvent<void>` |
+
+
+## Dependencies
+
+### Depends on
+
+- [xpl-icon](../xpl-icon)
+- [xpl-button](../xpl-button)
+
+### Graph
+```mermaid
+graph TD;
+  xpl-banner --> xpl-icon
+  xpl-banner --> xpl-button
+  xpl-button --> xpl-icon
+  style xpl-banner fill:#f9f,stroke:#333,stroke-width:4px
+```
+
+----------------------------------------------
+
+*Built with [StencilJS](https://stenciljs.com/)*

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

@@ -1,41 +1,188 @@
 # xpl-button
 
-Buttons allow users to take an action.  Three sizes and three sentiments are available with leading and trailing icons. Hide an icon and the label for an icon-only button.
+Buttons allow users to take an action with clear visual hierarchy (variant), semantic meaning (sentiment), and size.
+
+## Usage
+
+> [!IMPORTANT]
+> Older props such as `state` still work, but we recommend using the sentiment described below.
+
+
+### Basic button
+
+Pass button text via the default slot (same as native `<button>`):
+
+```html
+<xpl-button>Primary action</xpl-button>
+```
+
+### Variant and sentiment
+
+Use `variant` for style (primary, secondary, tertiary) and `sentiment` for intent (default, positive, negative):
+
+```html
+<xpl-button variant="secondary">Secondary</xpl-button>
+<xpl-button variant="tertiary" sentiment="positive">Positive action</xpl-button>
+<xpl-button sentiment="negative">Destructive</xpl-button>
+```
+
+### Size
+
+Use **`size`** for button size: `default`, `sm` (small), or `xs` (extra small):
+
+```html
+<xpl-button size="sm">Small</xpl-button>
+<xpl-button size="xs">Extra small</xpl-button>
+```
+
+### Icon from Apollo icon library
+
+Use `icon` with a name from the xpl-icon library; use `icon-position` to place the icon at start or end:
+
+```html
+<xpl-button icon="download" icon-position="end">
+  Download
+</xpl-button>
+```
+
+### Icon-only button
+
+Use `icon-only` when the button shows only an icon (no label). Always set `icon` and use a descriptive `aria-label` on the host or inner button for accessibility:
+
+```html
+<xpl-button icon-only icon="x" aria-label="Close"></xpl-button>
+```
+
+### Loading state
+
+When `is-loading` is true, the button shows a spinner, hides the label and icon, stays the same size, and is non-interactive:
+
+```html
+<xpl-button is-loading>Submitting</xpl-button>
+```
+
+### Form submission
+
+The component renders a native `<button>`. Use `type` (`submit`, `reset`, or `button`), `name`, `value`, and `form` for form behaviour:
+
+```html
+<form id="my-form">
+  <xpl-button type="submit" name="action" value="save">Save</xpl-button>
+</form>
+```
+
+### Disabled
+
+Use the `disabled` prop to disable the button (same as native `disabled`):
+
+```html
+<xpl-button disabled>Disabled</xpl-button>
+```
+
+## DOM classes
+
+The host element includes BEM-style classes, including:
+
+- **Size:** `xpl-button--default` | `xpl-button--sm` | `xpl-button--xs`
+- **Variant:** `xpl-button--primary` | `xpl-button--secondary` | `xpl-button--tertiary` (and `xpl-button--subtle` while that value is still supported)
+- **Sentiment:** `xpl-button--neutral` | `xpl-button--positive` | `xpl-button--negative` when using `sentiment`
+- **Deprecated `state`:** if set, legacy classes `xpl-button--neutral` | `xpl-button--warning` | `xpl-button--success` are applied instead of the sentiment-based classes above (see migration)
+
+Prefer targeting **`sentiment`** + **`variant`** + **`size`** in new code; avoid relying on deprecated `state` class names for new selectors.
+
+## Migration Notes:
+
+The class **`xpl-button--default`** on the host continues to mean **size** (`size="default"`), not sentiment.
+
+### Deprecated `state` prop
+
+The **`state`** prop (`neutral` | `warning` | `success`) is deprecated. Use **`sentiment`** instead:
+
+| Old `state`   | New `sentiment` |
+| ------------- | ----------------- |
+| `neutral`     | `neutral` (default) |
+| `warning`     | `negative`        |
+| `success`     | `positive`        |
+
+**Backward compatibility:** if **`state`** is set, it controls the sentiment segment of the host class list (`xpl-button--neutral`, `xpl-button--warning`, `xpl-button--success`) so existing styles or tests that key off those class names can keep working. New work should use **`sentiment`** only (`neutral` | `negative` | `positive`).
+
+### Deprecated `variant="subtle"` → `tertiary`
+
+**`variant="subtle"`** is deprecated and retained only for backward compatibility, applying the **`xpl-button--subtle`** class. Use **`variant="tertiary"`** instead, which applies **`xpl-button--tertiary`**.
+
+### Other API notes
+
+- **`isLoading` / `is-loading`:** loading UI without forcing the disabled (gray) visual treatment.
+- **`icon`**, **`icon-position`**, **`icon-only`:** use Apollo icon names; no inline SVGs required.
+- **`data-*`, `aria-*`, and `role` on the host:** mirrored onto the inner `<button>` after render for accessibility and testing tools. After forwarding, these attributes are removed from the host element. Avoid relying on `role` on the host for external selectors.
+
+## Guidelines
+
+- **Pass button content via the default slot:** `<xpl-button>Save</xpl-button>`. Slots support rich content (formatted text, inline icons, etc.).
+- Use **`iconOnly`** for icon-only buttons and provide an **`aria-label`** (or ensure the inner button has an accessible name).
+- Use **`icon`** for icon names from the xpl-icon library; use **`icon-position`** to place the icon at start or end of the slot content.
+
+## Accessibility
+
+- The component renders a native `<button>`, so it is focusable and keyboard-activable by default.
+- When **`is-loading`** is true, the inner button has `aria-busy="true"` and the loading spinner is marked **`aria-hidden="true"`** so the label remains the accessible name.
+- For **icon-only** buttons, provide an accessible name via **`aria-label`** on the host (e.g. `<xpl-button icon-only icon="x" aria-label="Close">`) so screen readers announce the action.
+- For **WAI-ARIA composite widgets** (like tabs), use the **`controlAttrs`** prop to apply `id`, `role`, `aria-controls`, `aria-selected`, and `aria-current` directly to the inner `<button>`. This is preferred over setting these attributes on the host, which would be forwarded and removed from the host.
 
 <!-- Auto Generated Below -->
 
 
 ## Properties
 
-| Property    | Attribute    | Description                                       | Type                                   | Default     |
-| ----------- | ------------ | ------------------------------------------------- | -------------------------------------- | ----------- |
-| `disabled`  | `disabled`   | whether button should be disabled                 | `boolean`                              | `undefined` |
-| `form`      | `form`       |                                                   | `string`                               | `undefined` |
-| `fullWidth` | `full-width` | whether button should render with full width      | `boolean`                              | `undefined` |
-| `iconOnly`  | `icon-only`  | whether button should render icon only            | `boolean`                              | `undefined` |
-| `link`      | `link`       | whether button should yield a slot for a link tag | `boolean`                              | `undefined` |
-| `name`      | `name`       |                                                   | `string`                               | `undefined` |
-| `size`      | `size`       |                                                   | `"default" \| "sm" \| "xs"`            | `'default'` |
-| `state`     | `state`      |                                                   | `"neutral" \| "success" \| "warning"`  | `'neutral'` |
-| `type`      | `type`       |                                                   | `"button" \| "reset" \| "submit"`      | `undefined` |
-| `value`     | `value`      |                                                   | `string`                               | `undefined` |
-| `variant`   | `variant`    |                                                   | `"primary" \| "secondary" \| "subtle"` | `'primary'` |
+| Property       | Attribute       | Description                                                                                                                                                                                                                            | Type                                                                                                                      | Default     |
+| -------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | ----------- |
+| `controlAttrs` | --              | Attributes to apply to the inner native `<button>` (e.g., tab a11y wiring). Use this instead of setting `id` / `role` / `aria-*` on the host when the inner control is the element that needs them (e.g., WAI-ARIA composite widgets). | `{ id?: string; role?: string; 'aria-controls'?: string; 'aria-selected'?: "true" \| "false"; 'aria-current'?: string; }` | `undefined` |
+| `disabled`     | `disabled`      | Whether button should be disabled                                                                                                                                                                                                      | `boolean`                                                                                                                 | `false`     |
+| `form`         | `form`          | An optional form attribute for the button if type is submit                                                                                                                                                                            | `string`                                                                                                                  | `undefined` |
+| `fullWidth`    | `full-width`    | Whether the button should be of full width as per parent container.                                                                                                                                                                    | `boolean`                                                                                                                 | `false`     |
+| `icon`         | `icon`          | Icon to render - icon name as string (from xpl-icon library).                                                                                                                                                                          | `string`                                                                                                                  | `''`        |
+| `iconOnly`     | `icon-only`     | When true, the button renders in icon-only circular style. Use for icon-only buttons.                                                                                                                                                  | `boolean`                                                                                                                 | `false`     |
+| `iconPosition` | `icon-position` | Icon position relative to slot content. Ignored if no icon is provided.                                                                                                                                                                | `"end" \| "start"`                                                                                                        | `'start'`   |
+| `isLoading`    | `is-loading`    | When true, shows a loading overlay with spinner over the button. Button is non-interactive.                                                                                                                                            | `boolean`                                                                                                                 | `false`     |
+| `link`         | `link`          | whether button should yield a slot for a link tag                                                                                                                                                                                      | `boolean`                                                                                                                 | `undefined` |
+| `name`         | `name`          | Name of the button, submitted with form data. Passed through to the native button element.                                                                                                                                             | `string`                                                                                                                  | `undefined` |
+| `sentiment`    | `sentiment`     | Sentiment of the button, which applies different color schemes to indicate purpose/intent.                                                                                                                                             | `"negative" \| "neutral" \| "positive"`                                                                                   | `'neutral'` |
+| `size`         | `size`          | Button size. Use 'default', 'xs' (extra small), or 'sm' (small).                                                                                                                                                                       | `"default" \| "sm" \| "xs"`                                                                                               | `'default'` |
+| `state`        | `state`         | <span style="color:red">**[DEPRECATED]**</span> : Use `sentiment` with values "neutral", "negative", "positive" instead of `state` .<br/><br/>                                                                                         | `"neutral" \| "success" \| "warning"`                                                                                     | `undefined` |
+| `type`         | `type`          | HTML button type attribute.                                                                                                                                                                                                            | `"button" \| "reset" \| "submit"`                                                                                         | `undefined` |
+| `value`        | `value`         | Value of the button, submitted with form data. Passed through to the native button element.                                                                                                                                            | `string`                                                                                                                  | `undefined` |
+| `variant`      | `variant`       | Button variant/style. Use "primary", "secondary", "tertiary" for new usage. "subtle" is deprecated but still supported for backward compatibility.                                                                                     | `"primary" \| "secondary" \| "subtle" \| "tertiary"`                                                                      | `'primary'` |
 
 
 ## Dependencies
 
 ### Used by
 
+ - [xpl-banner](../xpl-banner)
  - [xpl-button-row](../xpl-button-row)
+ - [xpl-list-item](../xpl-list/xpl-list-item)
  - [xpl-modal](../xpl-modal)
  - [xpl-slideout](../xpl-slideout)
+ - [xpl-spotlight](../xpl-spotlight)
+ - [xpl-tab](../xpl-tab)
+ - [xpl-top-nav](../xpl-top-nav)
+
+### Depends on
+
+- [xpl-icon](../xpl-icon)
 
 ### Graph
 ```mermaid
 graph TD;
+  xpl-button --> xpl-icon
+  xpl-banner --> xpl-button
   xpl-button-row --> xpl-button
+  xpl-list-item --> xpl-button
   xpl-modal --> xpl-button
   xpl-slideout --> xpl-button
+  xpl-spotlight --> xpl-button
+  xpl-tab --> xpl-button
+  xpl-top-nav --> xpl-button
   style xpl-button fill:#f9f,stroke:#333,stroke-width:4px
 ```
 

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

@@ -33,6 +33,7 @@
 ```mermaid
 graph TD;
   xpl-button-row --> xpl-button
+  xpl-button --> xpl-icon
   style xpl-button-row fill:#f9f,stroke:#333,stroke-width:4px
 ```
 

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

@@ -1,6 +1,7 @@
 # xpl-calendar
 
-
+Calendars allow users to view and select dates.  Use XPL-Calendar when date picking is needed on a page or in a in a container.
+If a calendar is needed within a form, use [XPL-Datepicker](https://apollo.xplordocs.com/?path=/story/components-input--datepicker).
 
 <!-- Auto Generated Below -->
 

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

@@ -1,21 +1,26 @@
-# xpl-checkbox
-
+# xpl-checkbox
+
+Checkboxes allow users to make selections or choices. Checkboxes can be multi-select, and also act as controls.
+
+Provide visible label text in the default slot, or set `aria-label` when the checkbox has no adjacent label (for example, icon-only toolbars or table selection cells).
+
 <!-- Auto Generated Below -->
 
 
 ## Properties
 
-| Property        | Attribute       | Description                                                                         | Type      | Default     |
-| --------------- | --------------- | ----------------------------------------------------------------------------------- | --------- | ----------- |
-| `checked`       | `checked`       | Whether the input is checked                                                        | `boolean` | `undefined` |
-| `dataId`        | `data-id`       | A custom data attribute for the checkbox                                            | `string`  | `undefined` |
-| `description`   | `description`   | Description text for the field                                                      | `string`  | `undefined` |
-| `disabled`      | `disabled`      | Whether the input is disabled                                                       | `boolean` | `undefined` |
-| `indeterminate` | `indeterminate` | A visual state for when the input has not been interacted with                      | `boolean` | `undefined` |
-| `name`          | `name`          | The name attribute for the html input. (submitted in form as name/value pair)       | `string`  | `undefined` |
-| `required`      | `required`      | Whether the input is required                                                       | `boolean` | `undefined` |
-| `styled`        | `styled`        | Whether the input is contained in a box with a border and a background              | `boolean` | `undefined` |
-| `value`         | `value`         | The value attribute for the checkbox input. (submittted in form as name/value pair) | `string`  | `undefined` |
+| Property        | Attribute       | Description                                                                                                                                                                                                                                                                          | Type      | Default     |
+| --------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------- | ----------- |
+| `ariaLabel`     | `aria-label`    | Accessible name for the native checkbox input (sets `aria-label` on the `input`). Use when there is no visible label text in the default slot. Defaults to `''`; empty or whitespace-only values omit `aria-label` on the input so a visible `<label>` remains the sole name source. | `string`  | `''`        |
+| `checked`       | `checked`       | Whether the input is checked                                                                                                                                                                                                                                                         | `boolean` | `undefined` |
+| `dataId`        | `data-id`       | A custom data attribute for the checkbox                                                                                                                                                                                                                                             | `string`  | `undefined` |
+| `description`   | `description`   | Description text for the field                                                                                                                                                                                                                                                       | `string`  | `undefined` |
+| `disabled`      | `disabled`      | Whether the input is disabled                                                                                                                                                                                                                                                        | `boolean` | `undefined` |
+| `indeterminate` | `indeterminate` | A visual state for when the input has not been interacted with                                                                                                                                                                                                                       | `boolean` | `undefined` |
+| `name`          | `name`          | The name attribute for the html input. (submitted in form as name/value pair)                                                                                                                                                                                                        | `string`  | `undefined` |
+| `required`      | `required`      | Whether the input is required                                                                                                                                                                                                                                                        | `boolean` | `undefined` |
+| `styled`        | `styled`        | Whether the input is contained in a box with a border and a background                                                                                                                                                                                                               | `boolean` | `undefined` |
+| `value`         | `value`         | The value attribute for the checkbox input. (submittted in form as name/value pair)                                                                                                                                                                                                  | `string`  | `undefined` |
 
 
 ## Events
@@ -31,7 +36,7 @@
 
  - [xpl-choicelist](../xpl-choicelist)
  - [xpl-header-accordion](../xpl-header-accordion)
- - [xpl-table-header-cell](../xpl-table-header-cell)
+ - [xpl-table-header-cell](../xpl-table/xpl-table-header-cell)
 
 ### Graph
 ```mermaid

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

@@ -1,5 +1,6 @@
 # xpl-choicelist
 
+A Choice List allows users to make single or multiple selections from a list of choices.  This component is meant to consume the radio and checkbox components, either styled or unstyled, then allow for customizing an option list very quickly.
 <!-- Auto Generated Below -->