@brightspot/ui 6.8.0 → 6.8.2

package/dist/storybook/docs/components/Dropdown.md

@@ -0,0 +1,74 @@
+# `<btu-dropdown>`
+
+A dropdown component that renders a trigger button and manages a floating panel
+containing a `btu-dropdown-menu`.
+
+Uses the native Popover API and CSS anchor positioning for panel management.
+The trigger button is built with existing `btu-button-*` classes.
+
+**Trigger button styling:** Set `--button-*` CSS custom properties on `<btu-dropdown>`
+or a parent element to customize the trigger via CSS inheritance (e.g.,
+`--button-border-radius`, `--button-color-background`). See
+`tailwind-plugin-button.ts` for available props.
+
+```js
+import '@brightspot/ui/components/dropdown/Dropdown.js'
+```
+
+Interactive examples: https://ui.brightspot.com/?path=/docs/components-dropdown--docs
+
+## Attributes
+
+| Attribute | Property | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `label` | `label` | `string` | `''` | Trigger button text. |
+| `open` | `open` | `boolean` | `false` | Panel visibility state. Can be set programmatically (e.g., for tour UIs) — syncs to `showPopover()`/`hidePopover()` in `updated()`. |
+| `placement` | `placement` | `'bottom-start' \| 'bottom-end' \| 'top-start' \| 'top-end'` | `'bottom-start'` | Panel placement: 'bottom-start', 'bottom-end', 'top-start', 'top-end'. |
+| `size` | `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Button size: 'sm', 'md', 'lg'. |
+| `disabled` | `disabled` | `boolean` | `false` | Prevents opening. |
+| `variant` | `variant` | `'primary' \| 'secondary' \| 'tertiary' \| 'primary-clear' \| 'secondary-clear' \| 'tertiary-clear'` | `'secondary'` | Button variant: 'primary', 'secondary', 'tertiary', 'primary-clear', 'secondary-clear', 'tertiary-clear'. |
+| `symbol` | `symbol` | `string` | `''` | Lucide icon symbol for the trigger. |
+| `icon-position` | `iconPosition` | `'leading' \| 'trailing'` | `'leading'` | Icon position: 'leading' or 'trailing'. |
+| `icon-only` | `iconOnly` | `boolean` | `false` | Hides label, shows icon only. |
+| `stay-open-on-select` | `stayOpenOnSelect` | `boolean` | `false` | Keeps panel open on item click. |
+| `no-chevron` | `noChevron` | `boolean` | `false` | Hides the chevron icon on the trigger button. |
+| `tooltip` | `tooltip` | `string` | `''` | Tooltip text content. Set to empty string to remove the tooltip. |
+| `tooltip-position` | `tooltipPosition` | `'top' \| 'bottom' \| 'left' \| 'right'` | `'top'` | Position relative to the host element. Auto-flips when constrained by the viewport. |
+| `tooltip-delay` | `tooltipDelay` | `number` | `300` | Show delay in milliseconds (hover trigger only). |
+| `tooltip-offset` | `tooltipOffset` | `'sm' \| 'md' \| 'lg' \| 'xl' \| null` | `null` | Gap between host and tooltip (sm=4px, md=8px, lg=12px, xl=16px). |
+| `tooltip-no-arrow` | `tooltipNoArrow` | `boolean` | `false` | Hide the arrow pseudo-element. |
+| `tooltip-trigger` | `tooltipTrigger` | `string` | `'hover focus'` | Space-separated trigger types: 'hover', 'focus', 'click'. |
+
+## Events
+
+| Event | Detail | Description |
+| --- | --- | --- |
+| `btu-dropdown-ready` |  | Fired after first render and initialization |
+| `btu-dropdown-show` |  | Fired when the dropdown panel opens |
+| `btu-dropdown-hide` |  | Fired when the dropdown panel closes |
+| `btu-dropdown-item-select` | `{label: string, value: string, selected: boolean}` | Fired when a menu item is activated (bubbles from btu-dropdown-item) |
+| `btu-dropdown-item-favorite` | `{label: string, favorited: boolean}` | Fired when a menu item's favorite is toggled (bubbles from btu-dropdown-item) |
+
+## Slots
+
+| Slot | Description |
+| --- | --- |
+| (default) | A `btu-dropdown-menu` element containing `btu-dropdown-item` children |
+
+## CSS custom properties
+
+| Property | Description |
+| --- | --- |
+| `--dropdown-panel-background` | Panel background color (default: white) |
+| `--dropdown-panel-border-color` | Panel border color (default: gray-200) |
+| `--dropdown-panel-border-radius` | Panel border radius (default: borderRadius.lg) |
+| `--dropdown-panel-min-width` | Panel minimum width (default: max(12rem, anchor-size(width))) |
+| `--dropdown-item-background` | Item background color (default: transparent) |
+| `--dropdown-item-color` | Item text color (default: gray-700) |
+| `--dropdown-item-hover-background` | Item hover background (default: gray-100) |
+| `--dropdown-item-hover-color` | Item hover text color (default: gray-900) |
+| `--dropdown-item-selected-background` | Selected item background (default: primary-50) |
+| `--dropdown-item-selected-color` | Selected item text color (default: primary-700) |
+| `--dropdown-item-font-size` | Item font size (default: fontSize.sm) |
+| `--dropdown-divider-color` | Divider line color (default: gray-200) |
+| `--dropdown-empty-color` | Empty state text color (default: gray-400) |

package/dist/storybook/docs/components/DropdownItem.md

@@ -0,0 +1,45 @@
+# `<btu-dropdown-item>`
+
+A menu item component for use inside `btu-dropdown-menu`.
+
+Renders as a menu item, divider, or subhead depending on the `type` property.
+Supports checkbox mode (inherited from parent menu), icons, keyboard shortcuts,
+and favorite toggles.
+
+```js
+import '@brightspot/ui/components/dropdown/DropdownItem.js'
+```
+
+## Attributes
+
+| Attribute | Property | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `label` | `label` | `string` | `''` | Display text for the item. |
+| `type` | `type` | `'default' \| 'divider' \| 'subhead'` | `'default'` | Item type: 'default', 'divider', or 'subhead'. |
+| `symbol` | `symbol` | `string` | `''` | Lucide icon symbol. |
+| `shortcut` | `shortcut` | `string` | `''` | Keyboard shortcut display text. |
+| `value` | `value` | `string` | `''` | Optional data value associated with the item. |
+| `disabled` | `disabled` | `boolean` | `false` | Whether the item is disabled. |
+| `selected` | `selected` | `boolean` | `false` | Whether the item is selected/checked. |
+| `favorited` | `favorited` | `boolean` | `false` | Whether the item is favorited. |
+| `error` | `error` | `boolean` | `false` | Whether the item has an error. |
+
+## Events
+
+| Event | Detail | Description |
+| --- | --- | --- |
+| `btu-dropdown-item-ready` |  | Fired after first render |
+| `btu-dropdown-item-select` | `{label: string, value: string, selected: boolean}` | Fired when item is activated |
+| `btu-dropdown-item-favorite` | `{label: string, favorited: boolean}` | Fired when favorite is toggled |
+
+## CSS custom properties
+
+| Property | Description |
+| --- | --- |
+| `--dropdown-item-font-size` | Item font size (default: theme fontSize.sm) |
+| `--dropdown-item-color` | Item text color (default: gray-700) |
+| `--dropdown-item-background` | Item background color (default: transparent) |
+| `--dropdown-item-hover-background` | Background on hover (default: gray-100) |
+| `--dropdown-item-hover-color` | Text color on hover (default: gray-900) |
+| `--dropdown-item-selected-background` | Background when selected (default: primary-50) |
+| `--dropdown-item-selected-color` | Text color when selected (default: primary-700) |

package/dist/storybook/docs/components/DropdownMenu.md

@@ -0,0 +1,41 @@
+# `<btu-dropdown-menu>`
+
+A menu container component that provides keyboard navigation and ARIA menu semantics.
+
+Contains `btu-dropdown-item` children and manages roving tabindex, typeahead search,
+and keyboard navigation following the WAI-ARIA Menu Button Pattern.
+
+```js
+import '@brightspot/ui/components/dropdown/DropdownMenu.js'
+```
+
+## Attributes
+
+| Attribute | Property | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `name` | `name` | `string` | `''` | Accessible name for the menu, displayed in header when header is true. |
+| `header` | `header` | `boolean` | `false` | Show header bar with menu name. |
+| `checkbox` | `checkbox` | `boolean` | `false` | Enable checkbox mode for items (menuitemcheckbox role). |
+| `icon` | `icon` | `boolean` | `false` | Show icons before each item. |
+| `symbol` | `symbol` | `string` | `''` | Fallback Lucide icon symbol for items without their own. |
+| `favorites` | `favorites` | `boolean` | `false` | Show favorite toggle on each item. |
+| `shortcuts` | `shortcuts` | `boolean` | `false` | Show keyboard shortcut text on each item. |
+| `empty-message` | `emptyMessage` | `string` | `'No items available'` | Message displayed when the menu has no focusable items. |
+
+## Events
+
+| Event | Detail | Description |
+| --- | --- | --- |
+| `btu-dropdown-menu-ready` |  | Fired after first render |
+
+## Slots
+
+| Slot | Description |
+| --- | --- |
+| (default) | Menu items (`btu-dropdown-item` elements) |
+
+## CSS custom properties
+
+| Property | Description |
+| --- | --- |
+| `--dropdown-empty-color` | Empty state text color (default: gray-400) |

package/dist/storybook/docs/components/EmptyState.md

@@ -0,0 +1,62 @@
+# `<btu-empty-state>`
+
+An empty state component for displaying placeholder content when no data is available.
+
+Supports a graphic slot for icons/images/pictures/SVGs, a heading, a description,
+and an actions slot for buttons or links. Available in three sizes (sm, md, lg)
+with semantic heading levels.
+
+## Architecture: Light DOM + Pseudo-Slots
+
+This component uses **Light DOM** (no Shadow Root) with pseudo-slots:
+- User-provided children are physically moved into internal containers
+- Movement is based on `slot` attributes
+- The `onFind` utility detects and redistributes newly-added children (one-time per element)
+
+### Node Redistribution Rules
+- `slot="graphic"` - Moved to graphic container (icon, image, picture, or SVG)
+- `slot="actions"` - Moved to an internal `btu-button-group` (variant="spaced")
+
+### Actions composition
+
+The actions container IS a `btu-button-group` with `variant="spaced"`. Its `size`
+is mapped from the empty-state `size` prop (sm→small, md→medium, lg→large) so all
+child `btu-button` / `btu-icon-button` elements get consistent sizing and group
+semantics (`role="group"`, roving tabindex, disabled propagation) for free.
+
+```js
+import '@brightspot/ui/components/empty-state/EmptyState.js'
+```
+
+Interactive examples: https://ui.brightspot.com/?path=/docs/components-empty-state--docs
+
+## Attributes
+
+| Attribute | Property | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `heading` | `heading` | `string` | `''` | Heading text displayed in the empty state. |
+| `description` | `description` | `string \| undefined` |  | Description text displayed below the heading. |
+| `size` | `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Size variant of the empty state. Affects spacing, description text, graphic size, and — when `heading-level` is unset — the default heading level (sm→5, md→4, lg→3). |
+| `heading-level` | `headingLevel` | `number \| undefined` |  | Heading level (1-6). When set to a valid integer 1-6, overrides the size-based default and drives both the semantic h1-h6 tag and the visual heading size (btu-heading-1 through btu-heading-6). Invalid values log a warning and fall back to the size-based default. |
+
+## Events
+
+| Event | Detail | Description |
+| --- | --- | --- |
+| `btu-empty-state-ready` |  | Fired after first render and initialization |
+| `btu-button-group-ready` |  | Bubbles from the internal actions button-group |
+
+## Slots
+
+| Slot | Description |
+| --- | --- |
+| `graphic` | Pseudo-slot for icon, image, picture, or SVG graphic. When the child is a `btu-icon`, the component overrides its `size` attribute based on the empty-state `size` prop (sm→md, md→lg, lg→xl). Use an `img`, `picture`, or inline `svg` for full size control. |
+| `actions` | Pseudo-slot for action buttons. Children are moved into an internal `btu-button-group` (variant="spaced"), so size and disabled state are managed by the group. |
+
+## CSS custom properties
+
+| Property | Description |
+| --- | --- |
+| `--empty-state-max-width` | Maximum width of the content block (default: min(75cqw, 360px)) |
+| `--empty-state-color-heading` | Heading text color (default: gray-900) |
+| `--empty-state-color-description` | Description text color (default: gray-500) |

package/dist/storybook/docs/components/EscaAvatar.md

@@ -0,0 +1,40 @@
+# `<btu-esca-avatar>`
+
+The animated avatar for the Esca AI assistant, driven entirely by its `state` attribute so the same
+element works wherever the assistant appears.
+
+Accessibility: the avatar is a visual indicator, not a status channel. By default it exposes a static
+accessible name (`role="img"`, `aria-label="Esca"`) so it reads like an author/identity avatar; both
+are only set when absent, so consumers can override them.
+- When the assistant is already named in the surrounding UI (the common case in a chat), treat the
+  avatar as decorative: set `aria-hidden="true"` to avoid a redundant announcement.
+- Do NOT convey activity (thinking / done) by changing this element's ARIA per `state` — a looping
+  `search` would announce repeatedly. Surface status as text in a polite `aria-live` region owned by
+  the chat UI, which has the context to word and time announcements. This component intentionally
+  does not announce its own state.
+
+```js
+import '@brightspot/ui/components/esca-avatar/EscaAvatar.js'
+```
+
+Interactive examples: https://ui.brightspot.com/?path=/docs/components-esca-avatar--docs
+
+## Attributes
+
+| Attribute | Property | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `state` | `state` | `'idle' \| 'wave' \| 'search' \| 'complete' \| 'glow'` | `'idle'` | Animation to play; changing it swaps the clip. |
+| `size` | `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'` | Size of the avatar, mirroring `<btu-avatar>`'s scale. `--esca-avatar-size` overrides it. |
+
+## Events
+
+| Event | Detail | Description |
+| --- | --- | --- |
+| `btu-esca-avatar-ready` |  | Fired after the first render |
+| `btu-esca-avatar-complete` | `{state: string}` | Fired when a non-looping animation finishes |
+
+## CSS custom properties
+
+| Property | Description |
+| --- | --- |
+| `--esca-avatar-size` | Width and height of the avatar; overrides the `size` attribute (default: 2.5rem) |

package/dist/storybook/docs/components/Icon.md

@@ -0,0 +1,40 @@
+# `<btu-icon>`
+
+An icon component for displaying Lucide icons.
+
+Icons inherit parent text color by default or can use gradient fills.
+All icons are from the Lucide icon library (https://lucide.dev/icons/).
+Supports both direct SVG rendering and mask-based gradient fills.
+
+```js
+import '@brightspot/ui/components/icon/Icon.js'
+```
+
+The CMS page defines this element itself, so a plugin can use it there without the import.
+
+Interactive examples: https://ui.brightspot.com/?path=/docs/components-icon--docs
+
+## Attributes
+
+| Attribute | Property | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `size` | `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'` | Size of the icon. - 'xs': Extra small (0.75rem) - 'sm': Small (1rem) - 'md': Medium (1.25rem, default) - 'lg': Large (1.5rem) - 'xl': Extra large (1.75rem) |
+| `symbol` | `symbol` | `string` | `'circle-dashed'` | Lucide icon name to display. See https://lucide.dev/icons/ for available icons. Lucide v1 removed all brand logos - legacy facebook/instagram/slack/twitter swap to the vendored brand marks at runtime, any other brand name falls back to circle-dashed. |
+| `brand` | `brand` | `string \| undefined` |  | Vendored brand mark to display instead of a Lucide icon (names in src/brand-icons.ts); takes precedence over `symbol`. |
+| `gradient` | `gradient` | `IconGradientColor \| undefined` |  | Theme color to use for gradient fill. When set, icon displays with gradient. When undefined, icon inherits parent text color. |
+| `emphasize` | `emphasize` | `boolean \| 'pulse' \| undefined` |  | Emphasize mode — renders a tonal circle with ring behind the icon. Colors are derived from `currentColor` via oklch relative color syntax. Defaults to primary; override with Tailwind `text-*` classes or `style="color: ..."`. Set as a boolean for the static circle, or `"pulse"` for a one-shot ring animation. Not intended for use with `gradient` — the two features target conflicting rendering modes. |
+
+## Events
+
+| Event | Detail | Description |
+| --- | --- | --- |
+| `btu-icon-ready` |  | Fired after first render and initialization |
+
+## CSS custom properties
+
+| Property | Description |
+| --- | --- |
+| `--icon-size` | Icon size (overrides size default) |
+| `--icon-stroke-width` | SVG stroke width as a unitless number in viewBox units; scales visually with icon size (default: 2) |
+| `--icon-fill` | Icon fill color for filled icons (e.g., "currentColor") |
+| `--icon-svg` | SVG data URI for mask-based rendering |

package/dist/storybook/docs/components/IconButton.md

@@ -0,0 +1,36 @@
+# `<btu-icon-button>`
+
+Surfaces the different actions someone can perform in an interface where space is limited.
+
+Uses an icon to communicate the action and supports multiple visual types and sizes.
+Tooltip support is built-in for accessibility in compact layouts.
+
+```js
+import '@brightspot/ui/components/icon-button/IconButton.js'
+```
+
+Interactive examples: https://ui.brightspot.com/?path=/docs/components-icon-button--docs
+
+## Attributes
+
+| Attribute | Property | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `name` | `name` | `string \| undefined` |  | Optional name for the button which can be used to identify the button in a callback. |
+| `type` | `type` | `'primary' \| 'primary-clear' \| 'primary-stroke' \| 'secondary' \| 'secondary-clear' \| 'secondary-stroke' \| 'tertiary' \| 'tertiary-clear' \| 'tertiary-stroke'` | `'primary'` | Specifies the type of icon-button, controlling the visual style. |
+| `symbol` | `symbol` | `string \| undefined` |  | Lucide icon symbol. |
+| `size` | `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Specifies the size of icon-button. |
+| `destructive` | `destructive` | `boolean` | `false` | Specifies an icon-button will be used to take any destructive action overriding the default color used for the icon-button type with the error color. |
+| `disabled` | `disabled` | `boolean` | `false` | Disables the button, preventing interaction and indicating an inactive state. |
+| `tooltip` | `tooltip` | `string` | `''` | Tooltip text content. Set to empty string to remove the tooltip. |
+| `tooltip-position` | `tooltipPosition` | `'top' \| 'bottom' \| 'left' \| 'right'` | `'top'` | Position relative to the host element. Auto-flips when constrained by the viewport. |
+| `tooltip-delay` | `tooltipDelay` | `number` | `300` | Show delay in milliseconds (hover trigger only). |
+| `tooltip-offset` | `tooltipOffset` | `'sm' \| 'md' \| 'lg' \| 'xl' \| null` | `null` | Gap between host and tooltip (sm=4px, md=8px, lg=12px, xl=16px). |
+| `tooltip-no-arrow` | `tooltipNoArrow` | `boolean` | `false` | Hide the arrow pseudo-element. |
+| `tooltip-trigger` | `tooltipTrigger` | `string` | `'hover focus'` | Space-separated trigger types: 'hover', 'focus', 'click'. |
+
+## Events
+
+| Event | Detail | Description |
+| --- | --- | --- |
+| `btu-icon-button-ready` |  | Fired after first render and initialization |
+| `btu-icon-button-click` | `{name: string \| undefined}` | Fired when the button is clicked |

package/dist/storybook/docs/components/LinearProgress.md

@@ -0,0 +1,37 @@
+# `<btu-linear-progress>`
+
+A horizontal linear progress bar for showing task completion.
+
+```js
+import '@brightspot/ui/components/linear-progress/LinearProgress.js'
+```
+
+Interactive examples: https://ui.brightspot.com/?path=/docs/components-linear-progress--docs
+
+## Attributes
+
+| Attribute | Property | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `color` | `color` | `ProgressColors` | `'primary'` | Color theme of the progress indicator. Supports: black, white, primary, teal, gray, purple, rose, error, warning, success |
+| `thickness` | `thickness` | `number \| undefined` |  | Stroke width of the progress indicator. |
+| `progress` | `progress` | `number` |  | Progress value for determinate variant. Clamped to 0–100. |
+| `label` | `label` | `string \| undefined` |  | Optional label text to display with the progress indicator. |
+| `initial-animation` | `initialAnimation` | `boolean` | `true` | Whether to animate progress from 0 to target value when component first becomes visible. |
+| `aria-label` | `ariaLabel` | `string \| null` | `null` | Optional aria-label attribute for screen readers. Describes what the progress indicator represents. |
+| `aria-labelledby` | `ariaLabelledBy` | `string \| null` | `null` | Optional aria-labelledby attribute for screen readers. References the ID of an element that labels the progress indicator. |
+| `aria-valuetext` | `ariaValueText` | `string \| null` | `null` | Optional aria-valuetext attribute for screen readers. Provides human-readable text alternative for progress value. |
+| `completion-announcement` | `completionAnnouncement` | `string \| undefined` |  | Optional message to announce to screen readers when progress reaches 100%. If not provided, no announcement will be made on completion. |
+
+## Events
+
+| Event | Detail | Description |
+| --- | --- | --- |
+| `btu-linear-progress-ready` |  | Fired after first render and initialization |
+| `btu-linear-progress-complete` |  | Fired when progress reaches 100 |
+
+## CSS custom properties
+
+| Property | Description |
+| --- | --- |
+| `--progress-color` | Custom progress bar color (overrides theme color) |
+| `--track-color` | Track/background color (overrides default gray-100) |

package/dist/storybook/docs/components/Message.md

@@ -0,0 +1,50 @@
+# `<btu-message>`
+
+A message for communicating high-visibility content that is not tied to the
+user's current task — alerts, breaking news, and persistent status. Use it on
+its own as a contained, bordered card, or place it inside a `<btu-banner>` to
+span the full width of the page (e.g., pinned above the CMS content area).
+
+Messages render a leading icon, an optional badge, a label, an optional
+description, and an optional dismiss control. The label and description
+stack vertically in a text column; everything else sits on the same row.
+
+```js
+import '@brightspot/ui/components/banner/Message.js'
+```
+
+Interactive examples: https://ui.brightspot.com/?path=/docs/components-message--docs
+
+## Attributes
+
+| Attribute | Property | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `variant` | `variant` | `'primary' \| 'info' \| 'warning' \| 'error' \| 'success'` | `'info'` | Visual style and semantic meaning of the message. |
+| `label` | `label` | `string \| undefined` |  | The primary message or title text displayed. |
+| `symbol` | `symbol` | `string \| undefined` |  | Name of the Lucide icon to display. Defaults to a sensible icon per variant. |
+| `dismissible` | `dismissible` | `boolean` | `false` | If true, a close icon is provided to allow the user to hide the message. |
+
+## Events
+
+| Event | Detail | Description |
+| --- | --- | --- |
+| `btu-message-ready` |  | Fired after the message is first rendered and initialized |
+| `btu-message-dismiss` |  | Fired when the user clicks the close/dismiss button. Cancelable: the message hides itself (sets `hidden`) unless the listener calls `preventDefault()`. |
+
+## Slots
+
+| Slot | Description |
+| --- | --- |
+| `badge` | Pseudo-slot for a leading status/version tag, typically a `<btu-badge>`. The slotted child is moved into the header row, before the label. |
+| `description` | Pseudo-slot for supporting text rendered directly beneath the label. Slot a single inline element (e.g., `<span slot="description">`) or a block element to enable rich content (links, emphasis). |
+| `actions` | Pseudo-slot for CTA buttons, links, or a `<btu-pagination>`. Children with `slot="actions"` are moved into an internal container on the trailing edge of the body. `.btu-button` children inherit the message's foreground color across all states. The message does not emit an action-click event — attach handlers to your own elements. |
+
+## CSS custom properties
+
+| Property | Description |
+| --- | --- |
+| `--message-color-background` | Overrides the background color for the message |
+| `--message-color-foreground` | Overrides the text and icon color |
+| `--message-color-border` | Overrides the border color (defaults to the variant's 300 shade) |
+| `--message-padding` | Overrides the internal padding (default: 1rem) |
+| `--message-border-radius` | Overrides the corner rounding (default: 8px) |

package/dist/storybook/docs/components/Pagination.md

@@ -0,0 +1,70 @@
+# `<btu-pagination>`
+
+A pagination component for navigating through paged content.
+
+Supports multiple layout variants (Search, Widget, Widget Small, Calendar)
+through configurable props and pseudo-slots.
+
+**Page size modes:**
+
+- **Built-in** (default): When no `slot="page-size"` is provided and `page-size-changer`
+  is true, Pagination renders its own `btu-dropdown` from the `page-size-options` attribute.
+  Events, label sync, and page size changes are managed automatically.
+
+- **Custom slot**: When a child has `slot="page-size"`, the built-in dropdown is suppressed.
+  The consumer owns all behavior — event handling, label sync, etc. Use this for non-standard
+  selectors like a calendar week/month toggle.
+
+**Page jumper modes:**
+
+- **Built-in**: When `page-jumper` is true and no `slot="jumper"` is provided, Pagination
+  renders a dropdown with "Page 1" through "Page N" items. Fully reactive — updates
+  automatically when page, page size, or total items change.
+
+- **Custom slot**: When a child has `slot="jumper"`, the built-in dropdown is suppressed.
+  The consumer owns all behavior. Use this for custom jumper content like a "Today" button.
+
+```js
+import '@brightspot/ui/components/pagination/Pagination.js'
+```
+
+Interactive examples: https://ui.brightspot.com/?path=/docs/components-pagination--docs
+
+## Attributes
+
+| Attribute | Property | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `page` | `page` | `number` | `1` | Current page number (1-based) |
+| `page-size` | `pageSize` | `number` | `0` | Number of items per page |
+| `disabled` | `disabled` | `boolean` | `false` | Disables all pagination controls |
+| `loading` | `loading` | `boolean` | `false` | Shows loading spinner and dims controls |
+| `hide-on-single-page` | `hideOnSinglePage` | `boolean` | `true` | Hide controls when there is only one page |
+| `page-size-changer` | `pageSizeChanger` | `boolean` | `true` | Show the page size dropdown |
+| `page-size-options` | `pageSizeOptions` | `string` | `'10, 20, 50'` | Comma-separated page size options |
+| `total-items` | `totalItems` | `number` | `0` | Total number of items across all pages |
+| `boundary-buttons` | `boundaryButtons` | `boolean` | `true` | Show first and last page buttons |
+| `hide-total-count` | `hideTotalCount` | `boolean` | `false` | Hide the item count display (e.g., "1-10 of 200") |
+| `page-jumper` | `pageJumper` | `boolean` | `false` | Show the page jumper dropdown. Intended for moderate page counts (under ~100 pages). For large datasets, use a custom `slot="jumper"` with a virtualized or input-based control. |
+| `label` | `label` | `string \| undefined` |  | Accessible label for the pagination nav landmark |
+
+## Events
+
+| Event | Detail | Description |
+| --- | --- | --- |
+| `btu-pagination-ready` |  | Fired after first render |
+| `btu-pagination-change` | `{page: number, pageSize: number}` | Fired on page navigation |
+| `btu-pagination-page-size-change` | `{page: number, pageSize: number}` | Fired on page size change |
+
+## Slots
+
+| Slot | Description |
+| --- | --- |
+| `page-size` | Custom page-size selector (replaces built-in dropdown). Consumer manages all behavior. |
+| `jumper` | Custom jumper content (replaces built-in page jumper dropdown). Consumer manages all behavior. |
+
+## CSS custom properties
+
+| Property | Description |
+| --- | --- |
+| `--pagination-color-background` | Background color for dropdowns, buttons, and jumper |
+| `--pagination-color-foreground` | Text/icon color |

package/dist/storybook/docs/components/Popover.md

@@ -0,0 +1,59 @@
+# `<btu-popover>`
+
+A popover component for displaying rich interactive content anchored to a trigger element.
+
+Uses the native HTML Popover API for top-layer rendering, light dismiss (click-outside
+and Escape for click triggers), and focus management. CSS anchor positioning handles
+viewport-aware placement.
+
+For click triggers (`popover="auto"`), the browser provides:
+- Light dismiss (Escape key and click-outside)
+- Top-layer rendering (no z-index needed)
+- Focus restoration on close
+- `autofocus` support — add `autofocus` to an element inside `slot="content"`
+  to have it receive focus when the popover opens
+
+```js
+import '@brightspot/ui/components/popover/Popover.js'
+```
+
+Interactive examples: https://ui.brightspot.com/?path=/docs/components-popover--docs
+
+## Attributes
+
+| Attribute | Property | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `position` | `position` | `'top' \| 'bottom' \| 'left' \| 'right'` | `'bottom'` | Position relative to the trigger element. Auto-flips when constrained by the viewport. |
+| `trigger` | `trigger` | `'click' \| 'hover' \| 'focus'` | `'click'` | How the popover is activated. - 'click': Toggle on click with light dismiss - 'hover': Show on mouseenter with delay - 'focus': Show on focusin |
+| `delay` | `delay` | `number` | `300` | Show delay in milliseconds (hover trigger only). |
+| `offset` | `offset` | `'sm' \| 'md' \| 'lg' \| 'xl' \| null` | `null` | Gap between trigger and popover (sm=4px, md=8px, lg=12px, xl=16px). |
+| `no-arrow` | `noArrow` | `boolean` | `false` | Hide the arrow pseudo-element. |
+| `inverted` | `inverted` | `boolean` | `false` | Invert the panel surface (dark on light pages, light on dark pages). Opt-in, since the panel holds arbitrary rich content. |
+| `open` | `open` | `boolean` | `false` | Programmatic open/close state (reflected). |
+| `panel-label` | `panelLabel` | `string` | `''` | Accessible label for the popover panel (applied as aria-label on the dialog). |
+
+## Events
+
+| Event | Detail | Description |
+| --- | --- | --- |
+| `btu-popover-show` |  | Fired when the popover opens |
+| `btu-popover-hide` |  | Fired when the popover closes |
+
+## Slots
+
+| Slot | Description |
+| --- | --- |
+| `trigger` | The element that activates the popover |
+| `content` | Rich HTML content displayed inside the popover panel |
+
+## CSS custom properties
+
+| Property | Description |
+| --- | --- |
+| `--popover-color-background` | Panel background color (default: var(--btu-theme-white); inverted: var(--btu-theme-black)) |
+| `--popover-color-content` | Panel text color (default: oklch(var(--btu-theme-gray-900)); inverted: var(--btu-theme-white)) |
+| `--popover-border-radius` | Panel corner radius (default: theme borderRadius.lg) |
+| `--popover-border-width` | Edge width, panel and arrow (default: 1px; 0 removes it) |
+| `--popover-border-color` | Edge color, panel and arrow (default: oklch(var(--btu-theme-gray-200))) |
+| `--popover-offset` | Gap between trigger and panel (default: 8px; see btu-popover-offset-{sm\|md\|lg\|xl}) |
+| `--popover-arrow-size` | Width/height of the pointer arrow (default: 8px) |

package/dist/storybook/docs/components/README.md

@@ -0,0 +1,48 @@
+# Brightspot UI component API reference
+
+Generated from the Custom Elements Manifest by `yarn cem:docs`. Don't edit these files by hand.
+
+## Using these in a plugin
+
+The CMS page already styles every component here, but it defines only four of the elements: `btu-badge`, `btu-copy-to-clipboard`, `btu-icon` and `btu-widget`.
+
+Import any other element in your plugin's frontend entry, for example
+`import '@brightspot/ui/components/card/Card.js'`, or the tag stays an undefined, inert element. That includes elements
+your Java renders through the generated `com.brightspot.ui.dari` classes. Importing one of the four changes nothing on a
+CMS page, because the CMS defines it first.
+
+See [Dari HTML elements](../dari-elements.md) for how to render these components from Java.
+
+## Components
+
+- [`<btu-action-bar>`](ActionBar.md): A persistent container for primary, secondary, tertiary, and destructive actions within an interface, typically anchored to the bottom of a view
+- [`<btu-action-item>`](ActionItem.md): An action item button for use within `btu-action-bar`
+- [`<btu-ai-sparkle>`](AiSparkle.md): The animated AI-branding sparkle
+- [`<btu-avatar>`](Avatar.md): An avatar component for displaying user profile images with fallback support
+- [`<btu-avatar-group>`](AvatarGroup.md): A container component for grouping multiple avatars with consistent styling
+- [`<btu-badge>`](Badge.md): A badge component for highlighting important information
+- [`<btu-banner>`](Banner.md): A full-width container that pins a `<btu-message>` to the top of the CMS or a content edit page
+- [`<btu-button-group>`](ButtonGroup.md): A semantic container for grouping related buttons together
+- [`<btu-card>`](Card.md): A flexible content container for presenting and organizing information
+- [`<btu-checkbox>`](Checkbox.md): A checkbox component for selecting one or more options from a set
+- [`<btu-circular-progress>`](CircularProgress.md): A circular progress indicator for showing loading states or progress
+- [`<btu-copy-to-clipboard>`](CopyToClipboard.md): A button component that copies text to the system clipboard
+- [`<btu-dropdown>`](Dropdown.md): A dropdown component that renders a trigger button and manages a floating panel containing a `btu-dropdown-menu`
+- [`<btu-dropdown-item>`](DropdownItem.md): A menu item component for use inside `btu-dropdown-menu`
+- [`<btu-dropdown-menu>`](DropdownMenu.md): A menu container component that provides keyboard navigation and ARIA menu semantics
+- [`<btu-empty-state>`](EmptyState.md): An empty state component for displaying placeholder content when no data is available
+- [`<btu-esca-avatar>`](EscaAvatar.md): The animated avatar for the Esca AI assistant, driven entirely by its `state` attribute so the same element works wherever the assistant appears
+- [`<btu-icon>`](Icon.md): An icon component for displaying Lucide icons
+- [`<btu-icon-button>`](IconButton.md): Surfaces the different actions someone can perform in an interface where space is limited
+- [`<btu-linear-progress>`](LinearProgress.md): A horizontal linear progress bar for showing task completion
+- [`<btu-message>`](Message.md): A message for communicating high-visibility content that is not tied to the user's current task — alerts, breaking news, and persistent status
+- [`<btu-pagination>`](Pagination.md): A pagination component for navigating through paged content
+- [`<btu-popover>`](Popover.md): A popover component for displaying rich interactive content anchored to a trigger element
+- [`<btu-radio>`](Radio.md): A single radio option, selectable from a set of mutually exclusive choices
+- [`<btu-radio-group>`](RadioGroup.md): A container that groups `btu-radio` options into a single-select control
+- [`<btu-switch>`](Switch.md): A toggle switch component for binary on/off states
+- [`<btu-tab>`](Tab.md): An individual tab within a tab group
+- [`<btu-tabs>`](Tabs.md): A container component for managing a group of tabs
+- [`<btu-upload>`](Upload.md): A file upload component with drop zone and file list
+- [`<btu-upload-item>`](UploadItem.md): Internal upload item sub-component for displaying individual file upload state
+- [`<btu-widget>`](Widget.md): A widget component for displaying content with header, body, and footer sections