@brightspot/ui 6.8.1 → 6.8.2

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

@@ -0,0 +1,55 @@
+# `<btu-action-bar>`
+
+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) |

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

@@ -0,0 +1,50 @@
+# `<btu-action-item>`
+
+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 |

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

@@ -0,0 +1,33 @@
+# `<btu-ai-sparkle>`
+
+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) |

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

@@ -0,0 +1,45 @@
+# `<btu-avatar>`
+
+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) |

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

@@ -0,0 +1,34 @@
+# `<btu-avatar-group>`
+
+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 |

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

@@ -0,0 +1,47 @@
+# `<btu-badge>`
+
+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) |

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

@@ -0,0 +1,35 @@
+# `<btu-banner>`
+
+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. |

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

@@ -0,0 +1,65 @@
+# `<btu-button-group>`
+
+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) |

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

@@ -0,0 +1,67 @@
+# `<btu-card>`
+
+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) |

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

@@ -0,0 +1,49 @@
+# `<btu-checkbox>`
+
+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. |

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

@@ -0,0 +1,40 @@
+# `<btu-circular-progress>`
+
+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) |

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

@@ -0,0 +1,51 @@
+# `<btu-copy-to-clipboard>`
+
+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) |