@brightspot/ui 6.8.1 → 6.8.2

package/dist/storybook/llms-full.txt

@@ -0,0 +1,1721 @@
+# Brightspot UI
+
+> `@brightspot/ui` 6.8.2: Lit web components (`btu-*` tags) and a TailwindCSS v3 preset for building Brightspot CMS screens and plugins.
+
+These docs describe 6.8.2. Prefer them over what you remember about this library, because component APIs change between minor versions. For the version a project actually uses, read `node_modules/@brightspot/ui/llms.txt` in that project. Releases without that file still have their manifest at `https://cdn.jsdelivr.net/npm/@brightspot/ui@<version>/dist/custom-elements.json`.
+
+Components render in the light DOM, not a shadow root. In HTML, use the attribute names from each component page: many differ from the JavaScript property names, for example `heading-level` for `headingLevel`.
+
+The guide and component pages linked below are markdown.
+
+## Getting started
+
+- [README](https://ui.brightspot.com/README.md): install, the Tailwind preset and importing components
+- [Using components in a CMS plugin](https://ui.brightspot.com/docs/components/README.md): the CMS defines only `btu-badge`, `btu-copy-to-clipboard`, `btu-icon` and `btu-widget`; import every other element you use
+- [Rendering components from Java](https://ui.brightspot.com/docs/dari-elements.md): the generated `com.brightspot.ui.dari` classes
+
+## Components
+
+- [`<btu-action-bar>`](https://ui.brightspot.com/docs/components/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>`](https://ui.brightspot.com/docs/components/ActionItem.md): An action item button for use within `btu-action-bar`
+- [`<btu-ai-sparkle>`](https://ui.brightspot.com/docs/components/AiSparkle.md): The animated AI-branding sparkle
+- [`<btu-avatar>`](https://ui.brightspot.com/docs/components/Avatar.md): An avatar component for displaying user profile images with fallback support
+- [`<btu-avatar-group>`](https://ui.brightspot.com/docs/components/AvatarGroup.md): A container component for grouping multiple avatars with consistent styling
+- [`<btu-badge>`](https://ui.brightspot.com/docs/components/Badge.md): A badge component for highlighting important information
+- [`<btu-banner>`](https://ui.brightspot.com/docs/components/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>`](https://ui.brightspot.com/docs/components/ButtonGroup.md): A semantic container for grouping related buttons together
+- [`<btu-card>`](https://ui.brightspot.com/docs/components/Card.md): A flexible content container for presenting and organizing information
+- [`<btu-checkbox>`](https://ui.brightspot.com/docs/components/Checkbox.md): A checkbox component for selecting one or more options from a set
+- [`<btu-circular-progress>`](https://ui.brightspot.com/docs/components/CircularProgress.md): A circular progress indicator for showing loading states or progress
+- [`<btu-copy-to-clipboard>`](https://ui.brightspot.com/docs/components/CopyToClipboard.md): A button component that copies text to the system clipboard
+- [`<btu-dropdown>`](https://ui.brightspot.com/docs/components/Dropdown.md): A dropdown component that renders a trigger button and manages a floating panel containing a `btu-dropdown-menu`
+- [`<btu-dropdown-item>`](https://ui.brightspot.com/docs/components/DropdownItem.md): A menu item component for use inside `btu-dropdown-menu`
+- [`<btu-dropdown-menu>`](https://ui.brightspot.com/docs/components/DropdownMenu.md): A menu container component that provides keyboard navigation and ARIA menu semantics
+- [`<btu-empty-state>`](https://ui.brightspot.com/docs/components/EmptyState.md): An empty state component for displaying placeholder content when no data is available
+- [`<btu-esca-avatar>`](https://ui.brightspot.com/docs/components/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>`](https://ui.brightspot.com/docs/components/Icon.md): An icon component for displaying Lucide icons
+- [`<btu-icon-button>`](https://ui.brightspot.com/docs/components/IconButton.md): Surfaces the different actions someone can perform in an interface where space is limited
+- [`<btu-linear-progress>`](https://ui.brightspot.com/docs/components/LinearProgress.md): A horizontal linear progress bar for showing task completion
+- [`<btu-message>`](https://ui.brightspot.com/docs/components/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>`](https://ui.brightspot.com/docs/components/Pagination.md): A pagination component for navigating through paged content
+- [`<btu-popover>`](https://ui.brightspot.com/docs/components/Popover.md): A popover component for displaying rich interactive content anchored to a trigger element
+- [`<btu-radio>`](https://ui.brightspot.com/docs/components/Radio.md): A single radio option, selectable from a set of mutually exclusive choices
+- [`<btu-radio-group>`](https://ui.brightspot.com/docs/components/RadioGroup.md): A container that groups `btu-radio` options into a single-select control
+- [`<btu-switch>`](https://ui.brightspot.com/docs/components/Switch.md): A toggle switch component for binary on/off states
+- [`<btu-tab>`](https://ui.brightspot.com/docs/components/Tab.md): An individual tab within a tab group
+- [`<btu-tabs>`](https://ui.brightspot.com/docs/components/Tabs.md): A container component for managing a group of tabs
+- [`<btu-upload>`](https://ui.brightspot.com/docs/components/Upload.md): A file upload component with drop zone and file list
+- [`<btu-upload-item>`](https://ui.brightspot.com/docs/components/UploadItem.md): Internal upload item sub-component for displaying individual file upload state
+- [`<btu-widget>`](https://ui.brightspot.com/docs/components/Widget.md): A widget component for displaying content with header, body, and footer sections
+
+## Tailwind classes
+
+Each link is a plugin source file; its header comment lists the classes.
+
+- [Button](https://cdn.jsdelivr.net/npm/@brightspot/ui@6.8.2/dist/tailwind-plugin-button.ts): Buttons communicate actions that users can take such as submit a form, begin a new task, trigger a new UI element to appear or take a new or next step in some process
+- [Heading](https://cdn.jsdelivr.net/npm/@brightspot/ui@6.8.2/dist/tailwind-plugin-heading.ts): Headings are a combination of font-size, line-height and weight
+- [Scroll Shadow](https://cdn.jsdelivr.net/npm/@brightspot/ui@6.8.2/dist/tailwind-plugin-scroll-shadow.ts): This plugin adds shadows to the edges of a scrollable container when the content of the container overflows
+- [Icon](https://cdn.jsdelivr.net/npm/@brightspot/ui@6.8.2/dist/tailwind-plugin-icon.ts): Lucide icons as classes, for example `before:btu-icon before:btu-icon-heart`, plus size and gradient modifiers
+
+## Optional
+
+- [All component pages in one file](https://ui.brightspot.com/llms-full.txt)
+- [Custom Elements Manifest](https://ui.brightspot.com/custom-elements.json): the machine-readable API of every element
+- [Changelog](https://ui.brightspot.com/CHANGELOG.md): what changed in each release
+- [Storybook](https://ui.brightspot.com/): interactive examples; needs JavaScript, so fetching it returns no content
+
+---
+
+# `<btu-action-bar>`
+Source: https://ui.brightspot.com/docs/components/ActionBar.md
+
+A persistent container for primary, secondary, tertiary, and destructive actions
+within an interface, typically anchored to the bottom of a view.
+
+Uses a two-zone layout: destructive actions on the left (start zone),
+main actions on the right (end zone). Both zones maintain their position
+even when the other zone is empty (BSP-18087).
+
+**Positioning:** Uses `margin-top: auto` to push to bottom of flex/grid parents.
+In block layout parents, the bar sits after content (a console warning is emitted).
+
+**Overflow:** When items don't fit, the least important overflow into a "More" dropdown.
+Items are auto-sorted by variant priority (tertiary → secondary → primary).
+With `compact`, compactable items progressively hide labels one-by-one before overflowing.
+
+```js
+import '@brightspot/ui/components/action-bar/ActionBar.js'
+```
+
+Interactive examples: https://ui.brightspot.com/?path=/docs/components-action-bar--docs
+
+## Attributes
+
+| Attribute | Property | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `position` | `position` | `'top' \| 'bottom'` | `'bottom'` | Bar position: 'top' or 'bottom' (default). |
+| `sticky` | `sticky` | `boolean` | `false` | Enables CSS sticky positioning. When combined with position='top', the bar sticks to the top of the scroll container. With position='bottom' (default), it sticks to the bottom. |
+| `item-alignment` | `alignment` | `'default' \| 'start' \| 'center' \| 'end'` | `'default'` | Content alignment: 'default' (two-zone), 'start', 'center', 'end'. Non-default alignments disable two-zone layout. |
+| `shadow` | `shadow` | `boolean` | `false` | Adds a box-shadow to the bar. |
+| `label` | `label` | `string` | `''` | Accessible label for the toolbar region. |
+| `compact` | `compact` | `boolean` | `false` | Enables progressive label compacting. When space shrinks, items marked `compactable` (with icons) have their labels hidden one-by-one from least to most important before items overflow into "More". |
+
+## Events
+
+| Event | Detail | Description |
+| --- | --- | --- |
+| `btu-action-bar-ready` |  | Fired after first render and initialization |
+| `btu-action-item-click` | `{label: string}` | Fired when an action item is clicked (bubbles from btu-action-item) |
+
+## Slots
+
+| Slot | Description |
+| --- | --- |
+| (default) | One or more `btu-action-item` elements |
+
+## CSS custom properties
+
+| Property | Description |
+| --- | --- |
+| `--action-bar-gap` | Gap between items (default: 0.75rem) |
+| `--action-bar-padding` | Bar padding (default: 1.5rem) |
+| `--action-bar-background` | Background color (default: white) |
+| `--action-bar-border-color` | Border color (default: gray-200) |
+| `--action-bar-z-index` | Z-index (default: 100) |
+
+---
+
+# `<btu-action-item>`
+Source: https://ui.brightspot.com/docs/components/ActionItem.md
+
+An action item button for use within `btu-action-bar`.
+
+Renders a styled button using existing `btu-button-*` classes. Supports
+primary, secondary, tertiary, and destructive variants. When `iconOnly`
+is set, the label is hidden and a tooltip is shown instead.
+
+**Button styling:** Set `--button-*` CSS custom properties on `<btu-action-item>`
+or a parent element to customize via CSS inheritance. See
+`tailwind-plugin-button.ts` for available props.
+
+```js
+import '@brightspot/ui/components/action-bar/ActionItem.js'
+```
+
+Interactive examples: https://ui.brightspot.com/?path=/docs/components-action-bar-action-item--docs
+
+## Attributes
+
+| Attribute | Property | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `label` | `label` | `string` | `''` | Button label text. |
+| `variant` | `variant` | `'primary' \| 'secondary' \| 'tertiary' \| 'destructive'` | `'secondary'` | Visual variant: 'primary', 'secondary', 'tertiary', 'destructive'. |
+| `symbol` | `symbol` | `string` | `''` | Lucide icon symbol for the leading icon. |
+| `icon-only` | `iconOnly` | `boolean` | `false` | Show icon only, hiding the label. Tooltip activates automatically with the label text. |
+| `disabled` | `disabled` | `boolean` | `false` | Disables the action item. The button remains focusable for accessibility but click events are suppressed. |
+| `loading` | `loading` | `boolean` | `false` | Shows a loading spinner and prevents interaction. |
+| `zone` | `zone` | `'start' \| 'end' \| ''` | `''` | Zone placement: 'start' or 'end'. Used by ActionBar for two-zone layout. If unset, auto-detected from variant (destructive → start, others → end). |
+| `compactable` | `compactable` | `boolean` | `false` | Opt-in for progressive label compacting. When the parent bar has `compact` enabled and space shrinks, compactable items with icons have their labels hidden one-by-one (least important first) before overflowing. Items without an icon ignore this attribute and go directly to overflow. |
+| `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-action-item-click` | `{label: string}` | Fired when the action item is clicked (not fired when disabled or loading) |
+
+## CSS custom properties
+
+| Property | Description |
+| --- | --- |
+| `--button-color` | Override button background color |
+| `--button-text-color` | Override button text color |
+| `--button-border-radius` | Override button border radius |
+
+---
+
+# `<btu-ai-sparkle>`
+Source: https://ui.brightspot.com/docs/components/AiSparkle.md
+
+The animated AI-branding sparkle. Drive it with the `playing` boolean: `true` loops the clip to
+draw the eye to an AI entry point, `false` freezes the full sparkle so it reads as a static brand
+mark once the surface it advertises is engaged. Reduced-motion users always get the frozen frame.
+
+Decorative by default (`aria-hidden="true"`, set only when absent) — the control it sits in owns
+the accessible name.
+
+```js
+import '@brightspot/ui/components/ai-sparkle/AiSparkle.js'
+```
+
+Interactive examples: https://ui.brightspot.com/?path=/docs/components-ai-sparkle--docs
+
+## Attributes
+
+| Attribute | Property | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `playing` | `playing` | `boolean` | `false` | Whether the sparkle animates; otherwise it holds the last (fully-formed) frame. Opt-in (default `false`) like `autoplay`: a boolean defaulting to `true` can't be cleared by attribute absence. The converter also treats `playing="false"` as paused (a plain `type: Boolean` would read any present value, even "false", as `true`). |
+| `size` | `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'` | Size of the sparkle, mirroring `<btu-avatar>`'s scale. `--ai-sparkle-size` overrides it. |
+
+## Events
+
+| Event | Detail | Description |
+| --- | --- | --- |
+| `btu-ai-sparkle-ready` |  | Fired after the first render |
+
+## CSS custom properties
+
+| Property | Description |
+| --- | --- |
+| `--ai-sparkle-size` | Width and height of the sparkle; overrides the `size` attribute (default: 2.5rem) |
+
+---
+
+# `<btu-avatar>`
+Source: https://ui.brightspot.com/docs/components/Avatar.md
+
+An avatar component for displaying user profile images with fallback support.
+
+Avatars display user profile images with automatic fallback to initials when
+the image fails to load or is not provided.
+
+```js
+import '@brightspot/ui/components/avatar/Avatar.js'
+```
+
+Interactive examples: https://ui.brightspot.com/?path=/docs/components-avatar--docs
+
+## Attributes
+
+| Attribute | Property | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `src` | `src` | `string` | `''` | Image source URL |
+| `alt` | `alt` | `string` | `''` | Alt text for the image |
+| `fallback` | `fallback` | `string` | `''` | Fallback text (typically user initials) |
+| `size` | `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| 'xxl'` | `'md'` | Size variant. - 'xs': Extra small (1.5rem) - 'sm': Small (2.25rem) - 'md': Medium (2.5rem) - default - 'lg': Large (3rem) - 'xl': Extra large (3.5rem) - 'xxl': Extra extra large (4rem) |
+| `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-avatar-ready` |  | Fired after first render and initialization |
+| `btu-avatar-image-loaded` | `{src: string}` | Fired when image successfully loads |
+| `btu-avatar-image-error` | `{src: string, error: Event}` | Fired when image fails to load |
+
+## CSS custom properties
+
+| Property | Description |
+| --- | --- |
+| `--avatar-size` | Custom size (overrides size prop) |
+| `--avatar-bg-color` | Fallback background color (default: purple-600) |
+| `--avatar-corner-rounding` | How rounded is the avatar (default: circle) |
+| `--avatar-ring-color` | Optional ring border color |
+| `--avatar-ring-width` | Ring border width (default: 2px) |
+
+---
+
+# `<btu-avatar-group>`
+Source: https://ui.brightspot.com/docs/components/AvatarGroup.md
+
+A container component for grouping multiple avatars with consistent styling.
+
+AvatarGroup wraps multiple avatar elements and provides:
+- Overflow handling (shows "+N" for excess avatars)
+- Consistent spacing and ring borders
+- Size inheritance for all child avatars
+
+```js
+import '@brightspot/ui/components/avatar/AvatarGroup.js'
+```
+
+Interactive examples: https://ui.brightspot.com/?path=/docs/components-avatar-group--docs
+
+## Attributes
+
+| Attribute | Property | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `max` | `max` | `number \| undefined` |  | Maximum number of visible avatars. Remaining avatars shown as "+N" |
+| `size` | `size` | `'xs' \| 'sm' \| 'md'` | `'md'` | Size variant for all child avatars (unless individually overridden) |
+
+## Methods
+
+| Method | Description |
+| --- | --- |
+| `processAvatars(): void` | Process all avatar children: apply size, handle overflow Call this method when avatars are dynamically added or removed |
+
+## Events
+
+| Event | Detail | Description |
+| --- | --- | --- |
+| `btu-avatar-group-ready` |  | Fired after first render and initialization |
+| `btu-avatar-group-overflow` | `{hidden: number}` | Fired when avatars are hidden due to max limit |
+
+---
+
+# `<btu-badge>`
+Source: https://ui.brightspot.com/docs/components/Badge.md
+
+A badge component for highlighting important information.
+
+Badges help highlight notifications, status, or new messages.
+Primarily used for communicating secondary or additional information.
+
+```js
+import '@brightspot/ui/components/badge/Badge.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-badge--docs
+
+## Attributes
+
+| Attribute | Property | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `variant` | `variant` | `'info' \| 'primary' \| 'error' \| 'success' \| 'warning'` | `'info'` | Style of the badge. - 'info': Informational (default) - 'primary': Primary action or emphasis - 'error': Error or danger state - 'success': Success or completion state - 'warning': Warning or caution state |
+| `dot` | `dot` | `boolean` | `false` | Should a dot be displayed before the label? |
+| `size` | `size` | `'sm' \| 'md' \| 'lg'` | `'sm'` | Size variant. - 'sm': Small (default) - 'md': Medium - 'lg': Large |
+| `activity` | `activity` | `'busy' \| 'live' \| undefined` |  | Attention state that draws the eye to the badge. Names the *intent*; the component owns the visual treatment (so it can change without callers). - 'busy': an in-progress state — a glint shimmers across the label text - 'live': a live/active state — a ring ripples out from the leading dot (implies `dot`) |
+| `fill` | `fill` | `'soft' \| 'solid'` | `'soft'` | Fill style. - 'soft': pale background with strong text (default) - 'solid': swaps the shades for a filled pill |
+
+## Events
+
+| Event | Detail | Description |
+| --- | --- | --- |
+| `btu-badge-ready` |  | Fired after first render and initialization |
+
+## Slots
+
+| Slot | Description |
+| --- | --- |
+| (default) | Label text or child elements (e.g., btu-icon + text) |
+
+## CSS custom properties
+
+| Property | Description |
+| --- | --- |
+| `--badge-color-foreground` | Text color (overrides theme color) |
+| `--badge-color-background` | Background color (overrides theme color) |
+| `--badge-radius-size` | Border radius size (overrides shape default, default: 999px) |
+| `--badge-px` | Horizontal padding (overrides size default) |
+| `--badge-py` | Vertical padding (overrides size default) |
+| `--badge-dot-size` | Size of the dot affordance (default: 6px) |
+
+---
+
+# `<btu-banner>`
+Source: https://ui.brightspot.com/docs/components/Banner.md
+
+A full-width container that pins a `<btu-message>` to the top of the CMS or a
+content edit page. The banner has no content API of its own — compose a
+`<btu-message>` inside it (or several, e.g. for a paginated banner) and the banner
+spans each to 100% of the host, rendering it full-bleed (edge-to-edge, bottom
+border only, no corner rounding).
+
+Set the content (variant, label, symbol, dismissible, badge/description/actions
+slots) on the message itself. The full-width treatment lives on this wrapper, so
+the message has no `full-width` attribute — the banner owns that.
+
+```js
+import '@brightspot/ui/components/banner/Banner.js'
+```
+
+Interactive examples: https://ui.brightspot.com/?path=/docs/components-banner--docs
+
+## Events
+
+| Event | Detail | Description |
+| --- | --- | --- |
+| `btu-banner-ready` |  | Fired after the banner is first rendered and initialized |
+
+## Slots
+
+| Slot | Description |
+| --- | --- |
+| (default) | One or more `<btu-message>` elements, full-bleed to the host width. With more than one, the banner auto-creates a `<btu-pagination>` and shows one at a time. |
+
+## CSS custom properties
+
+| Property | Description |
+| --- | --- |
+| `--banner-z-index` | Stack order for the banner (default: 100). The banner is `position: relative`, so this always applies; set `position: sticky` to also pin it to the viewport. |
+
+---
+
+# `<btu-button-group>`
+Source: https://ui.brightspot.com/docs/components/ButtonGroup.md
+
+A semantic container for grouping related buttons together.
+
+Supports connected (joined) and spaced layouts, horizontal and vertical
+orientation, group-level size and disabled propagation, and optional
+toggle/selection modes (single-select or multi-select).
+
+```js
+import '@brightspot/ui/components/button-group/ButtonGroup.js'
+```
+
+Interactive examples: https://ui.brightspot.com/?path=/docs/components-button-group--docs
+
+## Attributes
+
+| Attribute | Property | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `label` | `label` | `string` | `''` | Accessible name for the group, announced by assistive devices via aria-label. |
+| `orientation` | `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Layout direction of the buttons. |
+| `variant` | `variant` | `'connected' \| 'spaced'` | `'connected'` | `connected` collapses shared borders for a joined appearance. `spaced` renders buttons with a gap. |
+| `size` | `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Propagates a uniform size to all child buttons. |
+| `disabled` | `disabled` | `boolean` | `false` | When true, disables all child buttons as a group. |
+| `selection` | `selection` | `'none' \| 'single' \| 'multiple'` | `'none'` | Enables toggle/selection behavior. `single` allows one active button; `multiple` allows many. |
+| `value` | `value` | `string` | `''` | Reflects the currently selected button value(s). For `single`, the value of the active button. For `multiple`, a comma-delimited list of active values. |
+| `name` | `name` | `string` | `''` | When set, creates hidden input(s) for native form participation. |
+
+## Events
+
+| Event | Detail | Description |
+| --- | --- | --- |
+| `btu-button-group-ready` |  | Fired after first render and initialization |
+| `btu-button-group-change` | `{value: string}` | Fired when selection changes (single/multiple modes only) |
+| `btu-icon-button-click` | `{name: string \| undefined}` | Bubbles from child btu-icon-button elements when clicked |
+
+## Slots
+
+| Slot | Description |
+| --- | --- |
+| (default) | One or more `<button class="btu-button …">` or `<btu-icon-button>` elements to display in the group. The `connected` variant rounds the outer corners on the real `<button>`, so anchors styled as `.btu-button` slotted directly will not get rounded corners. Use `<button>` for grouped controls. |
+| `end` | Pushes the child to the end of the group via auto-margin (vertical: bottom, horizontal: right) |
+
+## CSS custom properties
+
+| Property | Description |
+| --- | --- |
+| `--button-group-gap` | Space between buttons when variant="spaced" (default: spacing.sm) |
+| `--button-group-border-radius` | Corner radius of outer edges when variant="connected" (default: 0.5rem) |
+| `--button-group-border-color` | Internal divider color between connected buttons (default: gray-300) |
+| `--button-group-selection-bg` | Background of a toggled/selected child (default: child's --button-tint-subtle) |
+| `--button-group-selection-color` | Text/icon color of a toggled/selected child (default: child's --button-tint-strong) |
+| `--button-group-shimmer-highlight` | Highlight color of the selection shimmer effect (default: child's --button-tint-highlight) Reads the following CSS custom properties from each child button (set by the button plugin per color variant — see tailwind-plugin-button.ts): |
+| `--button-tint-subtle` | Subtle tint of the child button's color family (read-only here) |
+| `--button-tint-strong` | Strong tint of the child button's color family (read-only here) |
+| `--button-tint-highlight` | Highlight tint of the child button's color family (read-only here) |
+
+## CSS states
+
+| State | Description |
+| --- | --- |
+| `:state(btu-connected)` | Applied when variant="connected", targetable via :state(btu-connected) |
+| `:state(btu-spaced)` | Applied when variant="spaced", targetable via :state(btu-spaced) |
+| `:state(btu-horizontal)` | Applied when orientation="horizontal", targetable via :state(btu-horizontal) |
+| `:state(btu-vertical)` | Applied when orientation="vertical", targetable via :state(btu-vertical) |
+| `:state(btu-disabled)` | Applied when the group is disabled, targetable via :state(btu-disabled) |
+
+---
+
+# `<btu-card>`
+Source: https://ui.brightspot.com/docs/components/Card.md
+
+A flexible content container for presenting and organizing information.
+
+The layout is driven by composition:
+
+- a direct `<img>` or `<btu-icon>` child renders the media layout (image area);
+  the icon shows in the image area as the fallback.
+- neither child renders a text-only card.
+- the `compact` attribute renders a quick-start tile; only a
+  featured `<btu-icon>` and the `action` slot are used.
+
+Composable children, all relocated into the layout automatically:
+- `<img>` — the thumbnail.
+- `<btu-icon>` — the featured icon (compact) or the media image fallback (shown
+  when no `<img>` is provided or it fails to load; defaults to `file-text`). The card sizes it.
+- `<btu-badge>` — a status badge.
+- `slot="action"` / `slot="secondary-action"` — a control in the top-right corner
+  or next to the title. A `<btu-checkbox>` there stays visible and toggles the
+  selected styling (listen for the bubbling `btu-checkbox-change` event); buttons
+  reveal on hover/focus.
+
+Cards are full-width by default and rely on the parent layout (grid or flex) to
+control their size.
+
+```js
+import '@brightspot/ui/components/card/Card.js'
+```
+
+Interactive examples: https://ui.brightspot.com/?path=/docs/components-card--docs
+
+## Attributes
+
+| Attribute | Property | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `heading` | `heading` | `string` | `''` | Heading text displayed on the card. |
+| `heading-level` | `headingLevel` | `number` | `2` | Heading level (1-6) for the card heading element. Drives the semantic h1–h6 tag. Invalid values log a warning and fall back to the default (2). |
+| `description` | `description` | `string \| undefined` |  | Supporting body text. Truncated to 3 lines via CSS. |
+| `compact` | `compact` | `boolean` | `false` | Renders the card as a compact quick-start tile. Badge, image, fields, and secondary-action children are ignored in this case. |
+| `disabled` | `disabled` | `boolean` | `false` | Whether the card is disabled. |
+| `href` | `href` | `string \| undefined` |  | Navigation URL for the entire card surface. When set, the card renders as a link. |
+
+## Events
+
+| Event | Detail | Description |
+| --- | --- | --- |
+| `btu-card-ready` |  | Fired after first render and initialization |
+
+## Slots
+
+| Slot | Description |
+| --- | --- |
+| `action` | Intended for a single action in the top-right corner of the card. |
+| `secondary-action` | Intended for a single action next to the title. |
+| `fields` | Intended for additional metadata fields displayed below the title & description |
+
+## CSS custom properties
+
+| Property | Description |
+| --- | --- |
+| `--card-min-width` | Minimum width of the card (default: 160px) |
+| `--card-background` | Background color (default: var(--btu-theme-white)) |
+| `--card-border` | Border style (default: 1px solid gray-200) |
+| `--card-radius` | Corner rounding (default: 8px) |
+| `--card-img-ratio` | Fixed aspect ratio for the thumbnail when an `<img>` child is present (default: 16 / 9) |
+| `--card-img-fit` | Object-fit mode for the `<img>` child thumbnail (default: contain) |
+| `--card-icon-background` | Background color behind the composed icon (compact card and media-image fallback) (default: gray-100) |
+
+---
+
+# `<btu-checkbox>`
+Source: https://ui.brightspot.com/docs/components/Checkbox.md
+
+A checkbox component for selecting one or more options from a set.
+
+Uses a hidden native checkbox internally for accessibility and form
+participation. Styled via the `btu-checkbox` Tailwind plugin classes.
+The component manages its own `className` — do not modify it externally
+after initialization (classes present at connection time are preserved).
+
+```js
+import '@brightspot/ui/components/checkbox/Checkbox.js'
+```
+
+Interactive examples: https://ui.brightspot.com/?path=/docs/components-checkbox--docs
+
+## Attributes
+
+| Attribute | Property | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `label` | `label` | `string \| undefined` |  | The text label displayed next to the checkbox. |
+| `description` | `description` | `string \| undefined` |  | Optional helper text displayed below the label. |
+| `size` | `size` | `'sm' \| 'md'` | `'sm'` | Controls the scale of the checkbox and associated typography. |
+| `checked` | `checked` | `boolean` | `false` | Whether the checkbox is currently selected. |
+| `indeterminate` | `indeterminate` | `boolean` | `false` | Whether the checkbox is in a partially selected state. Sets `aria-checked='mixed'` and activates the native `:indeterminate` pseudo-class. Cleared automatically when the user clicks the checkbox. |
+| `disabled` | `disabled` | `boolean` | `false` | If true, the checkbox is non-interactive and visually muted. |
+| `invalid` | `invalid` | `boolean` | `false` | If true, displays error styling on the checkbox. |
+| `error` | `error` | `string \| undefined` |  | Error message text displayed below the checkbox when validation fails. Setting this also activates error styling without needing to set invalid. |
+| `required` | `required` | `boolean` | `false` | Marks the field as mandatory for form submission. |
+| `name` | `name` | `string \| undefined` |  | Name of the form control submitted with the form data. |
+| `value` | `value` | `string` | `'on'` | Value associated with the checkbox when submitted. |
+
+## Events
+
+| Event | Detail | Description |
+| --- | --- | --- |
+| `btu-checkbox-ready` |  | Fired after the checkbox is first rendered and initialized |
+| `btu-checkbox-change` | `{ checked: boolean }` | Fired when the user toggles the checked state |
+
+## CSS custom properties
+
+| Property | Description |
+| --- | --- |
+| `--checkbox-color-primary` | Background and border color when checked or indeterminate, and tinted background/border on unchecked hover (default: oklch(var(--btu-theme-primary-700))) |
+| `--checkbox-color-border` | Border color in the unchecked state (default: oklch(var(--btu-theme-gray-300))) |
+| `--checkbox-color-error` | Border and text color in the error state (default: oklch(var(--btu-theme-error-600))) |
+| `--checkbox-border-radius` | Corner rounding of the checkbox square (default: 4px) |
+| `--checkbox-label-spacing` | Distance between the checkbox and the label (default: 0.75rem) |
+| `--checkbox-box-size` | [Internal] Width and height of the checkbox square, set by the size variant (sm: 1rem, md: 1.25rem). Use the `size` attribute instead of overriding directly — the icon must scale in tandem. |
+| `--checkbox-icon-size` | [Internal] Width and height of the icon inside the box, set by the size variant (sm: 0.75rem, md: 0.875rem). Use the `size` attribute instead of overriding directly. |
+
+---
+
+# `<btu-circular-progress>`
+Source: https://ui.brightspot.com/docs/components/CircularProgress.md
+
+A circular progress indicator for showing loading states or progress.
+
+```js
+import '@brightspot/ui/components/circular-progress/CircularProgress.js'
+```
+
+Interactive examples: https://ui.brightspot.com/?path=/docs/components-circular-progress--docs
+
+## Attributes
+
+| Attribute | Property | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `indeterminate` | `indeterminate` | `boolean` | `true` | Whether the progress indicator is indeterminate (animated spinner). When false, shows determinate progress based on the progress value. |
+| `size` | `size` | `'sm' \| 'md' \| 'lg'` | `'sm'` | Size variant. - 'sm': Small (16px) - default - 'md': Medium (32px) - 'lg': Large (48px) |
+| `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-circular-progress-ready` |  | Fired after first render and initialization |
+| `btu-circular-progress-complete` |  | Fired when determinate progress reaches 100 |
+
+## CSS custom properties
+
+| Property | Description |
+| --- | --- |
+| `--progress-color` | Custom progress indicator color (overrides theme color) |
+| `--track-color` | Track/background color (overrides default gray-100) |
+| `--progress-size` | Custom size in pixels (overrides size preset) |
+
+---
+
+# `<btu-copy-to-clipboard>`
+Source: https://ui.brightspot.com/docs/components/CopyToClipboard.md
+
+A button component that copies text to the system clipboard.
+
+Provides visual feedback when text is successfully copied by applying
+a temporary state that can be styled with CSS.
+
+Button styling is inherited from `btu-button-*` classes. Override appearance
+by passing custom classes via the `buttonclasses` attribute.
+
+```js
+import '@brightspot/ui/components/copy-to-clipboard/CopyToClipboard.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-copy-to-clipboard--docs
+
+## Attributes
+
+| Attribute | Property | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `copydata` | `copydata` | `string \| undefined` |  | The text to be copied to the system clipboard. |
+| `buttonclasses` | `buttonClasses` | `string \| undefined` |  | Custom CSS classes for the button. If provided, replaces the default classes. |
+
+## Properties
+
+These have no attribute; set them from JavaScript.
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `copiedStateKey` (read-only) | `'btu-copy-to-clipboard-copied'` |  | Custom state applied briefly after a successful copy; also emitted as an event. |
+
+## Methods
+
+| Method | Description |
+| --- | --- |
+| `copy(text: string, timeout: unknown)` | Copies the copydata to the system clipboard. Displays a success state for 3 seconds after copying. |
+
+## Events
+
+| Event | Detail | Description |
+| --- | --- | --- |
+| `btu-copy-to-clipboard-ready` |  | Fired after first render and initialization |
+| `btu-copy-to-clipboard-copied` |  | Fired when text is successfully copied to clipboard |
+
+## CSS states
+
+| State | Description |
+| --- | --- |
+| `:state(btu-copy-to-clipboard-copied)` | Applied briefly after a successful copy, targetable via :state(btu-copy-to-clipboard-copied) |
+
+---
+
+# `<btu-dropdown>`
+Source: https://ui.brightspot.com/docs/components/Dropdown.md
+
+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) |
+
+---
+
+# `<btu-dropdown-item>`
+Source: https://ui.brightspot.com/docs/components/DropdownItem.md
+
+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) |
+
+---
+
+# `<btu-dropdown-menu>`
+Source: https://ui.brightspot.com/docs/components/DropdownMenu.md
+
+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) |
+
+---
+
+# `<btu-empty-state>`
+Source: https://ui.brightspot.com/docs/components/EmptyState.md
+
+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) |
+
+---
+
+# `<btu-esca-avatar>`
+Source: https://ui.brightspot.com/docs/components/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.
+
+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) |
+
+---
+
+# `<btu-icon>`
+Source: https://ui.brightspot.com/docs/components/Icon.md
+
+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 |
+
+---
+
+# `<btu-icon-button>`
+Source: https://ui.brightspot.com/docs/components/IconButton.md
+
+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 |
+
+---
+
+# `<btu-linear-progress>`
+Source: https://ui.brightspot.com/docs/components/LinearProgress.md
+
+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) |
+
+---
+
+# `<btu-message>`
+Source: https://ui.brightspot.com/docs/components/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. 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) |
+
+---
+
+# `<btu-pagination>`
+Source: https://ui.brightspot.com/docs/components/Pagination.md
+
+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 |
+
+---
+
+# `<btu-popover>`
+Source: https://ui.brightspot.com/docs/components/Popover.md
+
+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) |
+
+---
+
+# `<btu-radio>`
+Source: https://ui.brightspot.com/docs/components/Radio.md
+
+A single radio option, selectable from a set of mutually exclusive choices.
+
+Uses a hidden native radio input internally for accessibility and form
+participation. Styled via the `btu-radio` Tailwind plugin classes. Typically
+placed inside a `btu-radio-group`, which owns the shared `name`, selection
+state, and arrow-key navigation; a standalone radio also works but manages
+only its own checked state. The component manages its own `className` — do not
+modify it externally after initialization (classes present at connection time
+are preserved).
+
+```js
+import '@brightspot/ui/components/radio/Radio.js'
+```
+
+Interactive examples: https://ui.brightspot.com/?path=/docs/components-radio--docs
+
+## Attributes
+
+| Attribute | Property | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `label` | `label` | `string \| undefined` |  | The text label displayed next to the radio. |
+| `description` | `description` | `string \| undefined` |  | Optional helper text displayed below the label. |
+| `size` | `size` | `'sm' \| 'md'` | `'sm'` | Controls the scale of the radio and associated typography. |
+| `checked` | `checked` | `boolean` | `false` | Whether this option is currently selected. |
+| `disabled` | `disabled` | `boolean` | `false` | If true, the radio is non-interactive and visually muted. |
+| `invalid` | `invalid` | `boolean` | `false` | If true, displays error styling on the radio. |
+| `error` | `error` | `string \| undefined` |  | Error message text displayed below the radio when validation fails. Setting this also activates error styling without needing to set invalid. |
+| `value` | `value` | `string \| undefined` |  | Value submitted with the form when this option is selected. |
+| `name` | `name` | `string \| undefined` |  | Name of the form control. Usually set by the parent `btu-radio-group` so every option in the group shares one name. |
+| `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-radio-ready` |  | Fired after the radio is first rendered and initialized |
+| `btu-radio-change` | `{ checked: boolean; value: string }` | Fired when the user selects this option |
+
+## CSS custom properties
+
+| Property | Description |
+| --- | --- |
+| `--radio-color-primary` | Fill and border color when selected (default: oklch(var(--btu-theme-primary-700))) |
+| `--radio-color-border` | Border color in the unselected state (default: oklch(var(--btu-theme-gray-300))) |
+| `--radio-color-error` | Border and text color in the error state (default: oklch(var(--btu-theme-error-600))) |
+| `--radio-label-spacing` | Distance between the radio and the label (default: 0.75rem) |
+| `--radio-box-size` | [Internal] Diameter of the radio control, set by the size variant (sm: 1rem, md: 1.25rem). Use the `size` attribute instead of overriding directly — the dot must scale in tandem. |
+| `--radio-dot-size` | [Internal] Diameter of the selected dot, set by the size variant (sm: 0.375rem, md: 0.5rem). Use the `size` attribute instead of overriding directly. |
+
+---
+
+# `<btu-radio-group>`
+Source: https://ui.brightspot.com/docs/components/RadioGroup.md
+
+A container that groups `btu-radio` options into a single-select control.
+
+Owns the shared form `name`, the selected `value`, and keyboard navigation
+following the WAI-ARIA radio group pattern: a single roving tabstop, and
+arrow keys that move focus and select in one step. Selection state and the
+`disabled` / `size` properties are propagated down to child radios.
+
+```js
+import '@brightspot/ui/components/radio/RadioGroup.js'
+```
+
+Interactive examples: https://ui.brightspot.com/?path=/docs/components-radio-group--docs
+
+## Attributes
+
+| Attribute | Property | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `name` | `name` | `string \| undefined` |  | Form field name shared by every radio in the group. |
+| `value` | `value` | `string \| undefined` |  | Value of the currently selected option. |
+| `orientation` | `orientation` | `'vertical' \| 'horizontal'` | `'vertical'` | Layout direction of the options. |
+| `size` | `size` | `'sm' \| 'md'` | `'sm'` | Controls the scale of every radio in the group. |
+| `required` | `required` | `boolean` | `false` | Marks a selection as mandatory for form submission. |
+| `disabled` | `disabled` | `boolean` | `false` | Disables every option in the group. |
+
+## Events
+
+| Event | Detail | Description |
+| --- | --- | --- |
+| `btu-radio-group-ready` |  | Fired after first render and initialization |
+| `btu-radio-group-change` | `{ value: string }` | Fired when the selected value changes |
+| `btu-radio-ready` |  | Fired when a child radio finishes initialization (bubbles from btu-radio) |
+| `btu-radio-change` | `{ checked: boolean; value: string }` | Fired when a child radio is selected (bubbles from btu-radio) |
+
+---
+
+# `<btu-switch>`
+Source: https://ui.brightspot.com/docs/components/Switch.md
+
+A toggle switch component for binary on/off states.
+
+Uses a hidden checkbox internally for accessibility, styled via the
+`btu-switch` Tailwind plugin classes.
+
+```js
+import '@brightspot/ui/components/switch/Switch.js'
+```
+
+Interactive examples: https://ui.brightspot.com/?path=/docs/components-switch--docs
+
+## Attributes
+
+| Attribute | Property | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `size` | `size` | `'sm' \| 'md' \| 'lg'` | `'sm'` | Controls the physical dimensions of the switch and the associated label typography. |
+| `label` | `label` | `string \| undefined` |  | The primary text displayed next to the toggle. |
+| `description` | `description` | `string \| undefined` |  | Optional helper text or secondary information displayed below the label. |
+| `checked` | `checked` | `boolean` | `false` | The current state of the switch (on/off). |
+| `disabled` | `disabled` | `boolean` | `false` | If true, the toggle is non-interactive and visually muted. |
+| `name` | `name` | `string \| undefined` |  | Name of the control for form participation. |
+| `label-position` | `labelPosition` | `'start' \| 'end'` | `'end'` | Determines if the label appears to the left or right of the switch. |
+| `on-icon` | `onIcon` | `string \| undefined` |  | Lucide icon name shown on the track when the switch is checked (on). |
+| `off-icon` | `offIcon` | `string \| undefined` |  | Lucide icon name shown on the track when the switch is unchecked (off). |
+
+## Events
+
+| Event | Detail | Description |
+| --- | --- | --- |
+| `btu-switch-ready` |  | Fired after the toggle is first rendered and initialized |
+| `btu-switch-change` | `{ checked: boolean }` | Fired when the user toggles the switch |
+| `btu-switch-focus` |  | Fired when the component gains focus |
+
+## CSS custom properties
+
+| Property | Description |
+| --- | --- |
+| `--switch-color-track-on` | Background color when the toggle is checked (default: var(--btu-theme-primary-700)) |
+| `--switch-color-track-off` | Background color when the toggle is unchecked (default: var(--btu-theme-gray-300)) |
+| `--switch-color-knob` | Color of the sliding circular handle (default: var(--btu-theme-white)) |
+| `--switch-label-spacing` | Distance between the switch and the text label (default: 0.75rem) |
+| `--switch-track-width` | Track width (default: sm 1.75rem, md 2.25rem, lg 2.75rem) |
+| `--switch-track-height` | Track height (default: sm 1rem, md 1.25rem, lg 1.5rem) |
+| `--switch-knob-size` | Knob diameter (default: sm 0.75rem, md 1rem, lg 1.25rem) |
+| `--switch-knob-padding` | Space between knob and track edges (default: 0.125rem) |
+| `--switch-track-icon-size` | Size of the track icons (default: sm 0.5rem, md 0.625rem, lg 0.75rem) |
+
+---
+
+# `<btu-tab>`
+Source: https://ui.brightspot.com/docs/components/Tab.md
+
+An individual tab within a tab group.
+
+Renders a button with role="tab" that participates in keyboard navigation
+and selection state managed by the parent `btu-tabs` container.
+
+```js
+import '@brightspot/ui/components/tabs/Tab.js'
+```
+
+Interactive examples: https://ui.brightspot.com/?path=/docs/components-tabs-tab--docs
+
+## Attributes
+
+| Attribute | Property | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `name` | `name` | `string \| undefined` |  | Value that identifies this tab and links it to panel elements that share the same `name` attribute. |
+| `label` | `label` | `string \| undefined` |  | Text displayed in the tab. |
+| `description` | `description` | `string \| undefined` |  | Accessibility description for screen readers. |
+| `disabled` | `disabled` | `boolean` | `false` | Whether the tab is disabled and non-interactive. |
+| `symbol` | `symbol` | `string \| undefined` |  | Lucide icon symbol to display. |
+| `icon-position` | `iconPosition` | `'leading' \| 'trailing'` | `'leading'` | Placement of the icon relative to the label. |
+| `icon-only` | `iconOnly` | `boolean` | `false` | When true, hides the label visually while maintaining accessibility. |
+| `error` | `error` | `boolean` | `false` | When true, displays an error badge on the tab. |
+| `badge` | `badge` | `string \| undefined` |  | Displays a badge with the given value alongside the label. |
+
+## Events
+
+| Event | Detail | Description |
+| --- | --- | --- |
+| `btu-tab-ready` |  | Fired after first render |
+| `btu-tab-change` | `{name: string}` | Fired when a non-disabled tab with a name is clicked |
+
+## CSS custom properties
+
+| Property | Description |
+| --- | --- |
+| `--badge-color-background` | Background color of the count indicator badge (default: gray-50) |
+| `--badge-color-foreground` | Text color of the count indicator badge (default: gray-800) |
+
+---
+
+# `<btu-tabs>`
+Source: https://ui.brightspot.com/docs/components/Tabs.md
+
+A container component for managing a group of tabs.
+
+Provides selection state management, size propagation to child tabs,
+and keyboard navigation following the WAI-ARIA Tabs pattern.
+
+When a tab becomes active, direct sibling elements that share the same
+`name` value are shown; other siblings with a `name` attribute are
+hidden. Only direct siblings are managed — nested tab groups control their
+own panels independently.
+
+```js
+import '@brightspot/ui/components/tabs/Tabs.js'
+```
+
+Interactive examples: https://ui.brightspot.com/?path=/docs/components-tabs--docs
+
+## Attributes
+
+| Attribute | Property | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `size` | `size` | `'xs' \| 'sm' \| 'md' \| 'lg'` | `'md'` | Size variant applied to all child tabs. |
+| `active-tab` | `activeTab` | `string \| undefined` |  | The `name` value of the currently active tab. |
+| `variant` | `variant` | `'full' \| 'menu'` | `'full'` | Layout variant. - 'full': tabs scroll horizontally when they overflow (default) - 'menu': all tabs are hidden; the active tab label and a chevron dropdown are shown instead |
+
+## Events
+
+| Event | Detail | Description |
+| --- | --- | --- |
+| `btu-tabs-ready` |  | Fired after first render and initialization |
+| `btu-tabs-show` | `{name: string}` | Fired when a tab becomes active |
+| `btu-tabs-hide` | `{name: string}` | Fired when a tab is deactivated |
+| `btu-tab-change` | `{name: string}` | Fired when a tab is selected (bubbles from btu-tab) |
+| `btu-tab-ready` |  | Fired when a child tab finishes initialization (bubbles from btu-tab) |
+
+## CSS custom properties
+
+| Property | Description |
+| --- | --- |
+| `--tabs-active-color` | Text and icon color of the active tab (default: gray-700) |
+| `--tabs-active-indicator-color` | Color of the active tab underline indicator (default: primary-500 → primary-700 → primary-900 gradient) |
+| `--tabs-border-color` | Color of the bottom border divider (default: gray-200) |
+| `--tabs-color` | Text and icon color for all tabs (default: gray-500; active/hover tabs use gray-700) |
+| `--tabs-background` | Background color for all tab buttons (default: transparent) |
+| `--tabs-container-background` | Background color of the tabs container (default: theme white) |
+| `--tabs-hover-background` | Background color of a tab on hover (default: gray-100) |
+| `--tabs-hover-color` | Text and icon color of a tab on hover (default: gray-700) |
+| `--tabs-gap` | Spacing between tabs (default: 1rem) |
+
+---
+
+# `<btu-upload>`
+Source: https://ui.brightspot.com/docs/components/Upload.md
+
+A file upload component with drop zone and file list.
+
+The component is presentation + file-selection only. It handles file browsing,
+drag-and-drop reception, client-side validation, and rendering the file list
+with progress bars. It does not perform network requests — the consumer listens
+for events, performs their own upload, and drives state back via imperative methods.
+
+```js
+import '@brightspot/ui/components/upload/Upload.js'
+```
+
+Interactive examples: https://ui.brightspot.com/?path=/docs/components-upload--docs
+
+## Attributes
+
+| Attribute | Property | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `accept` | `accept` | `string` | `''` | Accepted file types, matching the HTML `<input accept>` attribute format. Client-side filter only — the browser's file picker uses this as a hint, and drag-drop is enforced by this component. Server-side validation is still required. Supported forms (comma-separated, any combination): - `image/*` — MIME wildcard (any image) - `application/pdf` — exact MIME type - `.pdf`, `.docx` — file extension (case-insensitive) Examples: - `accept="image/*"` — any image - `accept="image/*,application/pdf"` — images and PDFs - `accept=".jpg,.jpeg,.png,.heic"` — specific extensions - `accept=""` (or omitted) — allow all Note: users can bypass the file picker's filter (most browsers offer an "All Files" option), so this attribute is a UX filter, not a security boundary. |
+| `max-file-size` | `maxFileSize` | `number` | `0` | Maximum file size in bytes. Files exceeding this are rejected. 0 means unlimited. |
+| `max-files` | `maxFiles` | `number` | `Infinity` | Maximum number of files allowed. When omitted, uploads are unlimited. `max-files="1"` enters single-file mode (selecting a new file replaces the existing one). `max-files="0"` allows zero files. Values above 1 cap the queue at that many files. |
+| `disabled` | `disabled` | `boolean` | `false` | Disables all interaction — file selection, drag-and-drop, and action buttons. |
+| `no-drag` | `noDrag` | `boolean` | `false` | Disables drag-and-drop. File selection via click still works. |
+
+## Methods
+
+| Method | Description |
+| --- | --- |
+| `setFileProgress(id: string, percent: number): void` | Update the progress of a file upload. Clamps value to 0-100 and coerces non-finite inputs to 0. Announces milestones (25%, 50%, 75%) to screen readers; 100% completion is announced by setFileStatus('complete'). Status transitions: - `pending` → `uploading` (auto — first progress report starts the upload) - `uploading` → `uploading` (progress updates) - `error` → `error` (progress updates only; status is preserved so a stale late callback can't wipe the error UI. To recover from error, call `setFileStatus(id, 'uploading')` first, then report progress.) - `complete` → ignored (terminal state) |
+| `setFileStatus(id: string, status: FileStatusSettable, message?: string): void` | Set the status of a file. Valid statuses: 'uploading', 'complete', 'error'. For 'error' status, an optional message can be provided. Transitions from 'complete' are rejected (terminal state) — a late-resolving XHR cannot overwrite a prior success. Rejected calls emit `btu-upload-api-error` with reason: 'invalid-transition'. |
+| `setFileSymbol(id: string, symbol: string): void` | Override the icon symbol for a file. |
+| `removeFile(id: string): void` | Remove a file programmatically. Fires `btu-upload-file-removed`. |
+| `getFiles(): readonly FileState[]` | Get a snapshot of all current files and their states. States are readonly; mutations on the returned array's elements are ineffective. |
+
+## Events
+
+| Event | Detail | Description |
+| --- | --- | --- |
+| `btu-upload-ready` | `unknown` | Fired when the component has completed first render |
+| `btu-upload-file-added` | `{id: string, file: File}` | Fired when a file passes validation and is added |
+| `btu-upload-file-removed` | `{id: string, file: File}` | Fired when a file is removed (user action, programmatic, or on disconnect for in-flight uploads) |
+| `btu-upload-file-retry` | `{id: string, file: File}` | Fired when user clicks "Try again" on a failed upload |
+| `btu-upload-file-rejected` | `{file: File, reason: 'type' \| 'size' \| 'count'}` | Fired when a file fails client-side validation or the queue is full |
+| `btu-upload-file-completed` | `{id: string, file: File}` | Fired when a file's status transitions into 'complete' |
+| `btu-upload-api-error` | `{method: string, id: string, reason: 'unknown-id' \| 'invalid-transition', message: string}` | Fired when an imperative API call references an unknown id or an illegal status transition |
+
+## CSS custom properties
+
+| Property | Description |
+| --- | --- |
+| `--upload-dropzone-bg` | Drop zone background color (default: gray-25) |
+| `--upload-dropzone-border-color` | Drop zone border color (default: gray-300; gray-200 when disabled, gray-400 in high-contrast) |
+| `--upload-dropzone-border-radius` | Drop zone border radius (default: borderRadius.lg) |
+| `--upload-dropzone-hover-bg` | Drop zone hover background (hover default: gray-50; drag-over default: primary-25) |
+| `--upload-dropzone-hover-border-color` | Drop zone hover/focus border color (default: primary-300; drag-over uses primary-400) |
+| `--upload-dropzone-focus-ring-color` | Drop zone focus ring color (default: primary-100) |
+| `--upload-item-bg` | Item background color (default: white) |
+| `--upload-item-border-color` | Item border color (default: gray-200) |
+| `--upload-item-active-border-color` | Item active/in-progress border (default: gray-300) |
+| `--upload-item-complete-border-color` | Item completed border color (default: primary-500) |
+| `--upload-item-error-bg` | Item error background (default: error-25) |
+| `--upload-item-error-border-color` | Item error border color (default: error-300) |
+
+---
+
+# `<btu-upload-item>`
+Source: https://ui.brightspot.com/docs/components/UploadItem.md
+
+Internal upload item sub-component for displaying individual file upload state.
+
+This component is not part of the public API — consumers should not create,
+query, or modify items directly. All interaction goes through `btu-upload` methods.
+
+```js
+import '@brightspot/ui/components/upload/UploadItem.js'
+```
+
+Interactive examples: https://ui.brightspot.com/?path=/docs/components-upload-upload-item--docs
+
+## Events
+
+| Event | Detail | Description |
+| --- | --- | --- |
+| `btu-upload-item-remove` | `{id: string}` | Fired when remove button is clicked |
+| `btu-upload-item-retry` | `{id: string}` | Fired when retry link is clicked |
+
+## CSS custom properties
+
+| Property | Description |
+| --- | --- |
+| `--upload-item-bg` | Item background color (default: white) |
+| `--upload-item-border-color` | Item border color (default: gray-200) |
+| `--upload-item-active-border-color` | Item active/in-progress border (default: gray-300) |
+| `--upload-item-complete-border-color` | Item completed border color (default: primary-500) |
+| `--upload-item-error-bg` | Item error background (default: error-25) |
+| `--upload-item-error-border-color` | Item error border color (default: error-300) |
+
+---
+
+# `<btu-widget>`
+Source: https://ui.brightspot.com/docs/components/Widget.md
+
+A widget component for displaying content with header, body, and footer sections.
+
+## Architecture: Light DOM + Manager Pattern
+
+This component uses **Light DOM** (no Shadow Root) with the **Manager Pattern**:
+- User-provided children are physically moved into internal containers
+- Movement is based on `slot` attributes (pseudo-slots)
+- The `onFind` utility automatically redistributes dynamically-added content
+
+### Node Redistribution Rules
+- `slot="controls"` → Moved to header actions area (before system buttons)
+- `slot="footer"` → Moved to footer container
+- *(no slot)* → Moved to body container (default)
+
+## Features
+
+- **Collapsible**: Optional chevron toggle to hide/show body and footer
+- **Fullscreen**: Optional maximize button for fullscreen mode via `:state(fullscreen)` custom state
+- **Dynamic Content**: `onFind` handles content added after initialization
+- **Accessible**: Full ARIA support and keyboard navigation
+- **Themeable**: CSS custom properties for colors and spacing
+
+## Accessibility
+
+- **Collapse toggle**: `aria-expanded`, `aria-controls`, `aria-label`
+- **Fullscreen toggle**: `aria-pressed`, `aria-label`
+- **Body region**: `role="region"`, `aria-labelledby` linking to heading
+- **Tab order**: Natural flow via physical DOM placement
+- **Collapsed content**: Hidden via `inert` attribute and CSS grid collapse
+
+```js
+import '@brightspot/ui/components/widget/Widget.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-widget--docs
+
+## Attributes
+
+| Attribute | Property | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `heading` | `heading` | `string` | `''` | Heading text displayed in the header. |
+| `collapsible` | `collapsible` | `boolean` | `false` | Whether the widget can be collapsed/expanded. When true, a chevron toggle button appears in the header. |
+| `collapsed` | `collapsed` | `boolean` | `false` | Whether the widget is currently collapsed. When true, body and footer are hidden. Implies collapsible. |
+| `fullscreenable` | `fullscreenable` | `boolean` | `false` | Whether the widget can enter fullscreen mode. When true, a fullscreen toggle button appears in the header. |
+
+## Properties
+
+These have no attribute; set them from JavaScript.
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `isFullscreen` (read-only) | `boolean` |  | Whether the widget is currently in fullscreen mode (read-only). Use `btu-widget-fullscreen-changed` event to react to changes. |
+
+## Events
+
+| Event | Detail | Description |
+| --- | --- | --- |
+| `btu-widget-ready` |  | Fired after first render and redistribution |
+| `btu-widget-collapse-changed` | `{collapsed: boolean}` | Fired when collapsed state changes |
+| `btu-widget-fullscreen-changed` | `{fullscreen: boolean}` | Fired when fullscreen state changes |
+
+## Slots
+
+| Slot | Description |
+| --- | --- |
+| (default) | Default pseudo-slot: elements without slot attribute are moved to body |
+| `controls` | Pseudo-slot: buttons/actions moved to header actions area |
+| `footer` | Pseudo-slot: content moved to footer container |
+
+## CSS custom properties
+
+| Property | Description |
+| --- | --- |
+| `--widget-background` | Body and footer background color (default: --btu-theme-white) |
+| `--widget-border` | Widget border and dividers (default: 1px solid gray-200) |
+| `--widget-border-color` | Color of header bottom divider (default: gray-200) |
+| `--header-background` | Header background color (default: transparent) |
+
+## CSS states
+
+| State | Description |
+| --- | --- |
+| `:state(collapsed)` | Applied when the widget is collapsed, targetable via :state(collapsed) |
+| `:state(fullscreen)` | Applied when the widget is in fullscreen mode, targetable via :state(fullscreen) |