@brightspot/ui 6.8.0 → 6.8.2

package/docs/components/Popover.md

@@ -1,92 +1,59 @@
-# `src/components/popover/Popover.ts`:
+# `<btu-popover>`
 
-## class: `Popover`, `btu-popover`
+A popover component for displaying rich interactive content anchored to a trigger element.
 
-### Superclass
+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.
 
-| Name         | Module | Package |
-| ------------ | ------ | ------- |
-| `LitElement` |        | lit     |
+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
 
-### Mixins
+```js
+import '@brightspot/ui/components/popover/Popover.js'
+```
 
-| Name                | Module                         | Package |
-| ------------------- | ------------------------------ | ------- |
-| `EventEmitterMixin` | /src/util/EventEmitterMixin.js |         |
-| `ReadyMixin`        | /src/util/ReadyMixin.js        |         |
+Interactive examples: https://ui.brightspot.com/?path=/docs/components-popover--docs
 
-### Fields
+## Attributes
 
-| Name                      | Privacy | Type                                     | Default    | Description                                                                                                                                                 | Inherited From |
-| ------------------------- | ------- | ---------------------------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- |
-| `position`                |         | `'top' \| 'bottom' \| 'left' \| 'right'` | `'bottom'` | Position relative to the trigger element.&#xA;Auto-flips when constrained by the viewport.                                                                  |                |
-| `trigger`                 |         | `'click' \| 'hover' \| 'focus'`          | `'click'`  | How the popover is activated.&#xA;- 'click': Toggle on click with light dismiss&#xA;- 'hover': Show on mouseenter with delay&#xA;- 'focus': Show on focusin |                |
-| `delay`                   |         | `number`                                 | `300`      | Show delay in milliseconds (hover trigger only).                                                                                                            |                |
-| `offset`                  |         | `PopoverOffset \| null`                  | `null`     | Gap between trigger and popover (sm=4px, md=8px, lg=12px, xl=16px).                                                                                         |                |
-| `noArrow`                 |         | `boolean`                                | `false`    | Hide the arrow pseudo-element.                                                                                                                              |                |
-| `inverted`                |         | `boolean`                                | `false`    | Invert the panel surface (dark on light pages, light on dark pages).&#xA;Opt-in, since the panel holds arbitrary rich content.                              |                |
-| `open`                    |         | `boolean`                                | `false`    | Programmatic open/close state (reflected).                                                                                                                  |                |
-| `panelLabel`              |         | `string`                                 | `''`       | Accessible label for the popover panel (applied as aria-label on the dialog).                                                                               |                |
-| `_initialClassesCaptured` | private | `boolean`                                | `false`    |                                                                                                                                                             |                |
-| `_onTriggerMouseLeave`    | private |                                          |            |                                                                                                                                                             |                |
-| `_onTriggerFocusIn`       | private |                                          |            |                                                                                                                                                             |                |
-| `_onTriggerFocusOut`      | private |                                          |            |                                                                                                                                                             |                |
-| `_onPanelMouseEnter`      | private |                                          |            |                                                                                                                                                             |                |
-| `_onPanelMouseLeave`      | private |                                          |            |                                                                                                                                                             |                |
-| `_onNativeToggle`         | private |                                          |            |                                                                                                                                                             |                |
-| `_onKeyDown`              | private |                                          |            |                                                                                                                                                             |                |
-| `_onViewportChange`       | private |                                          |            |                                                                                                                                                             |                |
+| 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). |
 
-### Methods
+## Events
 
-| Name   | Privacy | Description                                                                                                                                                                                                                                                                        | Parameters                                              | Return    | Inherited From    |
-| ------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | --------- | ----------------- |
-| `emit` |         | Dispatches a type-safe CustomEvent with standardized configuration.&#xA;&#xA;All events are configured with:&#xA;- bubbles: true (event propagates up the DOM tree)&#xA;- cancelable: false (event cannot be cancelled)&#xA;- composed: true (event crosses shadow DOM boundaries) | `type: K, detail: UnpackCustomEvent<CustomEventMap[K]>` | `boolean` | EventEmitterMixin |
+| Event | Detail | Description |
+| --- | --- | --- |
+| `btu-popover-show` |  | Fired when the popover opens |
+| `btu-popover-hide` |  | Fired when the popover closes |
 
-### Events
+## Slots
 
-| Name               | Type          | Description                   | Inherited From |
-| ------------------ | ------------- | ----------------------------- | -------------- |
-| `btu-popover-show` | `CustomEvent` | Fired when the popover opens  |                |
-| `btu-popover-hide` | `CustomEvent` | Fired when the popover closes |                |
-
-### Attributes
-
-| Name          | Field      | Inherited From |
-| ------------- | ---------- | -------------- |
-| `position`    | position   |                |
-| `trigger`     | trigger    |                |
-| `delay`       | delay      |                |
-| `offset`      | offset     |                |
-| `no-arrow`    | noArrow    |                |
-| `inverted`    | inverted   |                |
-| `open`        | open       |                |
-| `panel-label` | panelLabel |                |
-
-### CSS Properties
-
-| Name                         | Default | 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)                                               |
-
-### Slots
-
-| Name      | Description                                          |
-| --------- | ---------------------------------------------------- |
-| `trigger` | The element that activates the popover               |
+| Slot | Description |
+| --- | --- |
+| `trigger` | The element that activates the popover |
 | `content` | Rich HTML content displayed inside the popover panel |
 
-<hr/>
-
-## Exports
-
-| Kind                        | Name          | Declaration | Module                            | Package |
-| --------------------------- | ------------- | ----------- | --------------------------------- | ------- |
-| `js`                        | `default`     | Popover     | src/components/popover/Popover.ts |         |
-| `custom-element-definition` | `btu-popover` | Popover     | src/components/popover/Popover.ts |         |
+## CSS custom properties
+
+| Property | Description |
+| --- | --- |
+| `--popover-color-background` | Panel background color (default: var(--btu-theme-white); inverted: var(--btu-theme-black)) |
+| `--popover-color-content` | Panel text color (default: oklch(var(--btu-theme-gray-900)); inverted: var(--btu-theme-white)) |
+| `--popover-border-radius` | Panel corner radius (default: theme borderRadius.lg) |
+| `--popover-border-width` | Edge width, panel and arrow (default: 1px; 0 removes it) |
+| `--popover-border-color` | Edge color, panel and arrow (default: oklch(var(--btu-theme-gray-200))) |
+| `--popover-offset` | Gap between trigger and panel (default: 8px; see btu-popover-offset-{sm\|md\|lg\|xl}) |
+| `--popover-arrow-size` | Width/height of the pointer arrow (default: 8px) |

package/docs/components/README.md

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

package/docs/components/Radio.md

@@ -1,105 +1,55 @@
-# `src/components/radio/Radio.ts`:
-
-## class: `Radio`, `btu-radio`
-
-### Superclass
-
-| Name         | Module | Package |
-| ------------ | ------ | ------- |
-| `LitElement` |        | lit     |
-
-### Mixins
-
-| Name                | Module                         | Package |
-| ------------------- | ------------------------------ | ------- |
-| `TooltipMixin`      | /src/util/TooltipMixin.js      |         |
-| `EventEmitterMixin` | /src/util/EventEmitterMixin.js |         |
-| `ReadyMixin`        | /src/util/ReadyMixin.js        |         |
-
-### Fields
-
-| Name                      | Privacy | Type                                     | Default                                    | Description                                                                                                                                       | Inherited From |
-| ------------------------- | ------- | ---------------------------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- |
-| `label`                   |         | `string \| undefined`                    |                                            | The text label displayed next to the radio.                                                                                                       |                |
-| `description`             |         | `string \| undefined`                    |                                            | Optional helper text displayed below the label.                                                                                                   |                |
-| `size`                    |         | `'sm' \| 'md'`                           | `'sm'`                                     | Controls the scale of the radio and associated typography.                                                                                        |                |
-| `checked`                 |         | `boolean`                                | `false`                                    | Whether this option is currently selected.                                                                                                        |                |
-| `disabled`                |         | `boolean`                                | `false`                                    | If true, the radio is non-interactive and visually muted.                                                                                         |                |
-| `invalid`                 |         | `boolean`                                | `false`                                    | If true, displays error styling on the radio.                                                                                                     |                |
-| `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`                   |         | `string \| undefined`                    |                                            | Value submitted with the form when this option is selected.                                                                                       |                |
-| `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.                         |                |
-| `_userInitiated`          | private | `boolean`                                | `false`                                    |                                                                                                                                                   |                |
-| `_initialClasses`         | private | `string[]`                               | `[]`                                       |                                                                                                                                                   |                |
-| `_initialClassesCaptured` | private | `boolean`                                | `false`                                    |                                                                                                                                                   |                |
-| `_descId`                 | private |                                          | `` `radio-desc-${crypto.randomUUID()}` ``  |                                                                                                                                                   |                |
-| `_errorId`                | private |                                          | `` `radio-error-${crypto.randomUUID()}` `` |                                                                                                                                                   |                |
-| `_handleClick`            | private |                                          |                                            |                                                                                                                                                   |                |
-| `_describedBy`            | private | `string \| undefined`                    |                                            |                                                                                                                                                   |                |
-| `tooltip`                 |         | `string`                                 | `''`                                       | Tooltip text content. Set to empty string to remove the tooltip.                                                                                  | TooltipMixin   |
-| `tooltipPosition`         |         | `'top' \| 'bottom' \| 'left' \| 'right'` | `'top'`                                    | Position relative to the host element. Auto-flips when constrained by the viewport.                                                               | TooltipMixin   |
-| `tooltipDelay`            |         | `number`                                 | `300`                                      | Show delay in milliseconds (hover trigger only).                                                                                                  | TooltipMixin   |
-| `tooltipOffset`           |         | `TooltipOffset \| null`                  | `null`                                     | Gap between host and tooltip (sm=4px, md=8px, lg=12px, xl=16px).                                                                                  | TooltipMixin   |
-| `tooltipNoArrow`          |         | `boolean`                                | `false`                                    | Hide the arrow pseudo-element.                                                                                                                    | TooltipMixin   |
-| `tooltipTrigger`          |         | `string`                                 | `'hover focus'`                            | Space-separated trigger types: 'hover', 'focus', 'click'.                                                                                         | TooltipMixin   |
-| `_onMouseLeave`           | private |                                          |                                            |                                                                                                                                                   | TooltipMixin   |
-| `_onFocusIn`              | private |                                          |                                            |                                                                                                                                                   | TooltipMixin   |
-| `_onFocusOut`             | private |                                          |                                            |                                                                                                                                                   | TooltipMixin   |
-| `_onClick`                | private |                                          |                                            |                                                                                                                                                   | TooltipMixin   |
-| `_onNativeToggle`         | private |                                          |                                            |                                                                                                                                                   | TooltipMixin   |
-| `_onKeyDown`              | private |                                          |                                            |                                                                                                                                                   | TooltipMixin   |
-| `_onDocumentClick`        | private | `((e: MouseEvent) => void) \| null`      | `null`                                     |                                                                                                                                                   | TooltipMixin   |
-
-### Methods
-
-| Name             | Privacy | Description                                                                                                                                                                                                                                                                        | Parameters                                              | Return    | Inherited From    |
-| ---------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | --------- | ----------------- |
-| `_onInputChange` | private |                                                                                                                                                                                                                                                                                    | `e: Event`                                              | `void`    |                   |
-| `emit`           |         | Dispatches a type-safe CustomEvent with standardized configuration.&#xA;&#xA;All events are configured with:&#xA;- bubbles: true (event propagates up the DOM tree)&#xA;- cancelable: false (event cannot be cancelled)&#xA;- composed: true (event crosses shadow DOM boundaries) | `type: K, detail: UnpackCustomEvent<CustomEventMap[K]>` | `boolean` | EventEmitterMixin |
-
-### Events
-
-| Name               | Type                                               | Description                                             | Inherited From |
-| ------------------ | -------------------------------------------------- | ------------------------------------------------------- | -------------- |
-| `btu-radio-ready`  | `CustomEvent`                                      | Fired after the radio is first rendered and initialized |                |
-| `btu-radio-change` | `CustomEvent<{ checked: boolean; value: string }>` | Fired when the user selects this option                 |                |
-
-### Attributes
-
-| Name               | Field           | Inherited From |
-| ------------------ | --------------- | -------------- |
-| `label`            | label           |                |
-| `description`      | description     |                |
-| `size`             | size            |                |
-| `checked`          | checked         |                |
-| `disabled`         | disabled        |                |
-| `invalid`          | invalid         |                |
-| `error`            | error           |                |
-| `value`            | value           |                |
-| `name`             | name            |                |
-| `tooltip`          | tooltip         | TooltipMixin   |
-| `tooltip-position` | tooltipPosition | TooltipMixin   |
-| `tooltip-delay`    | tooltipDelay    | TooltipMixin   |
-| `tooltip-offset`   | tooltipOffset   | TooltipMixin   |
-| `tooltip-no-arrow` | tooltipNoArrow  | TooltipMixin   |
-| `tooltip-trigger`  | tooltipTrigger  | TooltipMixin   |
-
-### CSS Properties
-
-| Name                    | Default | 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.                              |
-
-<hr/>
-
-## Exports
-
-| Kind                        | Name        | Declaration | Module                        | Package |
-| --------------------------- | ----------- | ----------- | ----------------------------- | ------- |
-| `js`                        | `default`   | Radio       | src/components/radio/Radio.ts |         |
-| `custom-element-definition` | `btu-radio` | Radio       | src/components/radio/Radio.ts |         |
+# `<btu-radio>`
+
+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. |

package/docs/components/RadioGroup.md

@@ -1,63 +1,34 @@
-# `src/components/radio/RadioGroup.ts`:
+# `<btu-radio-group>`
 
-## class: `RadioGroup`, `btu-radio-group`
+A container that groups `btu-radio` options into a single-select control.
 
-### Superclass
+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.
 
-| Name         | Module | Package |
-| ------------ | ------ | ------- |
-| `LitElement` |        | lit     |
+```js
+import '@brightspot/ui/components/radio/RadioGroup.js'
+```
 
-### Mixins
+Interactive examples: https://ui.brightspot.com/?path=/docs/components-radio-group--docs
 
-| Name                  | Module                           | Package |
-| --------------------- | -------------------------------- | ------- |
-| `RovingTabindexMixin` | /src/util/RovingTabindexMixin.js |         |
-| `EventEmitterMixin`   | /src/util/EventEmitterMixin.js   |         |
-| `ReadyMixin`          | /src/util/ReadyMixin.js          |         |
+## Attributes
 
-### Fields
+| 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. |
 
-| Name          | Privacy | Type                         | Default      | Description                                         | Inherited From |
-| ------------- | ------- | ---------------------------- | ------------ | --------------------------------------------------- | -------------- |
-| `name`        |         | `string \| undefined`        |              | Form field name shared by every radio in the group. |                |
-| `value`       |         | `string \| undefined`        |              | Value of the currently selected option.             |                |
-| `orientation` |         | `'vertical' \| 'horizontal'` | `'vertical'` | Layout direction of the options.                    |                |
-| `size`        |         | `'sm' \| 'md'`               | `'sm'`       | Controls the scale of every radio in the group.     |                |
-| `required`    |         | `boolean`                    | `false`      | Marks a selection as mandatory for form submission. |                |
-| `disabled`    |         | `boolean`                    | `false`      | Disables every option in the group.                 |                |
+## Events
 
-### Methods
-
-| Name   | Privacy | Description                                                                                                                                                                                                                                                                        | Parameters                                              | Return    | Inherited From    |
-| ------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | --------- | ----------------- |
-| `emit` |         | Dispatches a type-safe CustomEvent with standardized configuration.&#xA;&#xA;All events are configured with:&#xA;- bubbles: true (event propagates up the DOM tree)&#xA;- cancelable: false (event cannot be cancelled)&#xA;- composed: true (event crosses shadow DOM boundaries) | `type: K, detail: UnpackCustomEvent<CustomEventMap[K]>` | `boolean` | EventEmitterMixin |
-
-### Events
-
-| Name                     | Type                                               | Description                                                               | Inherited From |
-| ------------------------ | -------------------------------------------------- | ------------------------------------------------------------------------- | -------------- |
-| `btu-radio-group-ready`  | `CustomEvent`                                      | Fired after first render and initialization                               |                |
-| `btu-radio-group-change` | `CustomEvent<{ value: string }>`                   | Fired when the selected value changes                                     |                |
-| `btu-radio-ready`        | `CustomEvent`                                      | Fired when a child radio finishes initialization (bubbles from btu-radio) |                |
-| `btu-radio-change`       | `CustomEvent<{ checked: boolean; value: string }>` | Fired when a child radio is selected (bubbles from btu-radio)             |                |
-
-### Attributes
-
-| Name          | Field       | Inherited From |
-| ------------- | ----------- | -------------- |
-| `name`        | name        |                |
-| `value`       | value       |                |
-| `orientation` | orientation |                |
-| `size`        | size        |                |
-| `required`    | required    |                |
-| `disabled`    | disabled    |                |
-
-<hr/>
-
-## Exports
-
-| Kind                        | Name              | Declaration | Module                             | Package |
-| --------------------------- | ----------------- | ----------- | ---------------------------------- | ------- |
-| `js`                        | `default`         | RadioGroup  | src/components/radio/RadioGroup.ts |         |
-| `custom-element-definition` | `btu-radio-group` | RadioGroup  | src/components/radio/RadioGroup.ts |         |
+| 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) |