@brightspot/ui 6.8.1 → 6.8.3-rc.1

package/docs/components/Switch.md

@@ -1,84 +1,48 @@
-# `src/components/switch/Switch.ts`:
-
-## class: `Switch`, `btu-switch`
-
-### Superclass
-
-| Name         | Module | Package |
-| ------------ | ------ | ------- |
-| `LitElement` |        | lit     |
-
-### Mixins
-
-| Name                | Module                         | Package |
-| ------------------- | ------------------------------ | ------- |
-| `EventEmitterMixin` | /src/util/EventEmitterMixin.js |         |
-| `ReadyMixin`        | /src/util/ReadyMixin.js        |         |
-
-### Fields
-
-| Name            | Privacy | Type                   | Default | Description                                                                         | Inherited From |
-| --------------- | ------- | ---------------------- | ------- | ----------------------------------------------------------------------------------- | -------------- |
-| `size`          |         | `'sm' \| 'md' \| 'lg'` | `'sm'`  | Controls the physical dimensions of the switch and the associated label typography. |                |
-| `label`         |         | `string \| undefined`  |         | The primary text displayed next to the toggle.                                      |                |
-| `description`   |         | `string \| undefined`  |         | Optional helper text or secondary information displayed below the label.            |                |
-| `checked`       |         | `boolean`              | `false` | The current state of the switch (on/off).                                           |                |
-| `disabled`      |         | `boolean`              | `false` | If true, the toggle is non-interactive and visually muted.                          |                |
-| `name`          |         | `string \| undefined`  |         | Name of the control for form participation.                                         |                |
-| `labelPosition` |         | `'start' \| 'end'`     | `'end'` | Determines if the label appears to the left or right of the switch.                 |                |
-| `onIcon`        |         | `string \| undefined`  |         | Lucide icon name shown on the track when the switch is checked (on).                |                |
-| `offIcon`       |         | `string \| undefined`  |         | Lucide icon name shown on the track when the switch is unchecked (off).             |                |
-
-### Methods
-
-| Name             | Privacy | Description                                                                                                                                                                                                                                                                        | Parameters                                              | Return    | Inherited From    |
-| ---------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | --------- | ----------------- |
-| `_onInputChange` | private |                                                                                                                                                                                                                                                                                    | `e: Event`                                              | `void`    |                   |
-| `_onFocus`       | private |                                                                                                                                                                                                                                                                                    |                                                         | `void`    |                   |
-| `_toggleInput`   | private |                                                                                                                                                                                                                                                                                    |                                                         | `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-switch-ready`  | `CustomEvent`                       | Fired after the toggle is first rendered and initialized |                |
-| `btu-switch-change` | `CustomEvent<{ checked: boolean }>` | Fired when the user toggles the switch                   |                |
-| `btu-switch-focus`  | `CustomEvent`                       | Fired when the component gains focus                     |                |
-
-### Attributes
-
-| Name             | Field         | Inherited From |
-| ---------------- | ------------- | -------------- |
-| `size`           | size          |                |
-| `label`          | label         |                |
-| `description`    | description   |                |
-| `checked`        | checked       |                |
-| `disabled`       | disabled      |                |
-| `name`           | name          |                |
-| `label-position` | labelPosition |                |
-| `on-icon`        | onIcon        |                |
-| `off-icon`       | offIcon       |                |
-
-### CSS Properties
-
-| Name                       | Default | 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)               |
-
-<hr/>
-
-## Exports
-
-| Kind                        | Name         | Declaration | Module                          | Package |
-| --------------------------- | ------------ | ----------- | ------------------------------- | ------- |
-| `js`                        | `default`    | Switch      | src/components/switch/Switch.ts |         |
-| `custom-element-definition` | `btu-switch` | Switch      | src/components/switch/Switch.ts |         |
+# `<btu-switch>`
+
+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) |

package/docs/components/Tab.md

@@ -1,80 +1,40 @@
-# `src/components/tabs/Tab.ts`:
+# `<btu-tab>`
 
-## class: `Tab`, `btu-tab`
+An individual tab within a tab group.
 
-### Superclass
+Renders a button with role="tab" that participates in keyboard navigation
+and selection state managed by the parent `btu-tabs` container.
 
-| Name         | Module | Package |
-| ------------ | ------ | ------- |
-| `LitElement` |        | lit     |
+```js
+import '@brightspot/ui/components/tabs/Tab.js'
+```
 
-### Mixins
+Interactive examples: https://ui.brightspot.com/?path=/docs/components-tabs-tab--docs
 
-| Name                | Module                         | Package |
-| ------------------- | ------------------------------ | ------- |
-| `EventEmitterMixin` | /src/util/EventEmitterMixin.js |         |
-| `ReadyMixin`        | /src/util/ReadyMixin.js        |         |
+## Attributes
 
-### Static Fields
+| 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. |
 
-| Name      | Privacy | Type | Default | Description | Inherited From |
-| --------- | ------- | ---- | ------- | ----------- | -------------- |
-| `tagName` |         |      |         |             |                |
+## Events
 
-### Fields
+| 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 |
 
-| Name                      | Privacy | Type                      | Default     | Description                                                                                           | Inherited From |
-| ------------------------- | ------- | ------------------------- | ----------- | ----------------------------------------------------------------------------------------------------- | -------------- |
-| `name`                    |         | `string \| undefined`     |             | Value that identifies this tab and links it to panel elements that share the same \`name\` attribute. |                |
-| `label`                   |         | `string \| undefined`     |             | Text displayed in the tab.                                                                            |                |
-| `description`             |         | `string \| undefined`     |             | Accessibility description for screen readers.                                                         |                |
-| `disabled`                |         | `boolean`                 | `false`     | Whether the tab is disabled and non-interactive.                                                      |                |
-| `symbol`                  |         | `string \| undefined`     |             | Lucide icon symbol to display.                                                                        |                |
-| `iconPosition`            |         | `'leading' \| 'trailing'` | `'leading'` | Placement of the icon relative to the label.                                                          |                |
-| `iconOnly`                |         | `boolean`                 | `false`     | When true, hides the label visually while maintaining accessibility.                                  |                |
-| `error`                   |         | `boolean`                 | `false`     | When true, displays an error badge on the tab.                                                        |                |
-| `badge`                   |         | `string \| undefined`     |             | Displays a badge with the given value alongside the label.                                            |                |
-| `_initialClassesCaptured` | private | `boolean`                 | `false`     |                                                                                                       |                |
+## CSS custom properties
 
-### 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-tab-ready`  | `CustomEvent`                 | Fired after first render                             |                |
-| `btu-tab-change` | `CustomEvent<{name: string}>` | Fired when a non-disabled tab with a name is clicked |                |
-
-### Attributes
-
-| Name            | Field        | Inherited From |
-| --------------- | ------------ | -------------- |
-| `name`          | name         |                |
-| `label`         | label        |                |
-| `description`   | description  |                |
-| `disabled`      | disabled     |                |
-| `symbol`        | symbol       |                |
-| `icon-position` | iconPosition |                |
-| `icon-only`     | iconOnly     |                |
-| `error`         | error        |                |
-| `badge`         | badge        |                |
-
-### CSS Properties
-
-| Name                       | Default | 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)      |
-
-<hr/>
-
-## Exports
-
-| Kind                        | Name      | Declaration | Module                     | Package |
-| --------------------------- | --------- | ----------- | -------------------------- | ------- |
-| `js`                        | `default` | Tab         | src/components/tabs/Tab.ts |         |
-| `custom-element-definition` | `btu-tab` | Tab         | src/components/tabs/Tab.ts |         |
+| 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) |

package/docs/components/Tabs.md

@@ -1,86 +1,49 @@
-# `src/components/tabs/Tabs.ts`:
-
-## class: `Tabs`, `btu-tabs`
-
-### Superclass
-
-| Name         | Module | Package |
-| ------------ | ------ | ------- |
-| `LitElement` |        | lit     |
-
-### Mixins
-
-| Name                  | Module                           | Package |
-| --------------------- | -------------------------------- | ------- |
-| `RovingTabindexMixin` | /src/util/RovingTabindexMixin.js |         |
-| `EventEmitterMixin`   | /src/util/EventEmitterMixin.js   |         |
-| `ReadyMixin`          | /src/util/ReadyMixin.js          |         |
-
-### Static Fields
-
-| Name      | Privacy | Type | Default | Description | Inherited From |
-| --------- | ------- | ---- | ------- | ----------- | -------------- |
-| `tagName` |         |      |         |             |                |
-
-### Fields
-
-| Name                      | Privacy | Type                           | Default  | Description                                                                                                                                                                          | Inherited From |
-| ------------------------- | ------- | ------------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------- |
-| `size`                    |         | `'xs' \| 'sm' \| 'md' \| 'lg'` | `'md'`   | Size variant applied to all child tabs.                                                                                                                                              |                |
-| `activeTab`               |         | `string \| undefined`          |          | The \`name\` value of the currently active tab.                                                                                                                                      |                |
-| `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 |                |
-| `_initialClassesCaptured` | private | `boolean`                      | `false`  |                                                                                                                                                                                      |                |
-| `menuWrapper`             | private | `HTMLElement \| null`          | `null`   |                                                                                                                                                                                      |                |
-| `menuDropdown`            | private | `Dropdown \| null`             | `null`   |                                                                                                                                                                                      |                |
-| `menuLabel`               | private | `HTMLSpanElement \| null`      | `null`   |                                                                                                                                                                                      |                |
-| `menuIcon`                | private | `HTMLElement \| null`          | `null`   |                                                                                                                                                                                      |                |
-| `menuErrorBadge`          | private | `HTMLElement \| null`          | `null`   |                                                                                                                                                                                      |                |
-| `_dropdownSize`           | private | `'sm' \| 'md' \| 'lg'`         |          |                                                                                                                                                                                      |                |
-| `_menuIconSize`           | private | `'sm' \| 'md'`                 |          |                                                                                                                                                                                      |                |
-
-### 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-tabs-ready` | `CustomEvent`                 | Fired after first render and initialization                           |                |
-| `btu-tabs-show`  | `CustomEvent<{name: string}>` | Fired when a tab becomes active                                       |                |
-| `btu-tabs-hide`  | `CustomEvent<{name: string}>` | Fired when a tab is deactivated                                       |                |
-| `btu-tab-change` | `CustomEvent<{name: string}>` | Fired when a tab is selected (bubbles from btu-tab)                   |                |
-| `btu-tab-ready`  | `CustomEvent`                 | Fired when a child tab finishes initialization (bubbles from btu-tab) |                |
-
-### Attributes
-
-| Name         | Field     | Inherited From |
-| ------------ | --------- | -------------- |
-| `size`       | size      |                |
-| `active-tab` | activeTab |                |
-| `variant`    | variant   |                |
-
-### CSS Properties
-
-| Name                            | Default | 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)                                                                    |
-
-<hr/>
-
-## Exports
-
-| Kind                        | Name       | Declaration | Module                      | Package |
-| --------------------------- | ---------- | ----------- | --------------------------- | ------- |
-| `js`                        | `default`  | Tabs        | src/components/tabs/Tabs.ts |         |
-| `custom-element-definition` | `btu-tabs` | Tabs        | src/components/tabs/Tabs.ts |         |
+# `<btu-tabs>`
+
+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) |