@brightspot/ui 6.8.1 → 6.8.3-rc.1

package/docs/components/CircularProgress.md

@@ -1,84 +1,40 @@
-# `src/components/circular-progress/CircularProgress.ts`:
-
-## class: `CircularProgress`, `btu-circular-progress`
-
-### Superclass
-
-| Name         | Module | Package |
-| ------------ | ------ | ------- |
-| `LitElement` |        | lit     |
-
-### Mixins
-
-| Name                | Module                         | Package |
-| ------------------- | ------------------------------ | ------- |
-| `ProgressMixin`     | /src/util/ProgressMixin.js     |         |
-| `EventEmitterMixin` | /src/util/EventEmitterMixin.js |         |
-| `ReadyMixin`        | /src/util/ReadyMixin.js        |         |
-
-### Fields
-
-| Name                      | Privacy | Type                                               | Default     | Description                                                                                                                                 | Inherited From |
-| ------------------------- | ------- | -------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------- | -------------- |
-| `indeterminate`           |         | `boolean`                                          | `true`      | Whether the progress indicator is indeterminate (animated spinner).
When false, shows determinate progress based on the progress value. |                |
-| `size`                    |         | `'sm' \| 'md' \| 'lg'`                             | `'sm'`      | Size variant.
- 'sm': Small (16px) - default
- 'md': Medium (32px)
- 'lg': Large (48px)                                         |                |
-| `color`                   |         | `ProgressColors`                                   | `'primary'` | Color theme of the progress indicator.
Supports: black, white, primary, teal, gray, purple, rose, error, warning, success               | ProgressMixin  |
-| `thickness`               |         | `number \| undefined`                              |             | Stroke width of the progress indicator.                                                                                                     | ProgressMixin  |
-| `_progress`               | private | `number`                                           | `0`         |                                                                                                                                             | ProgressMixin  |
-| `progress`                |         | `number`                                           |             | Progress value for determinate variant. Clamped to 0–100.                                                                                   | ProgressMixin  |
-| `label`                   |         | `string \| undefined`                              |             | Optional label text to display with the progress indicator.                                                                                 | ProgressMixin  |
-| `initialAnimation`        |         | `boolean`                                          | `true`      | Whether to animate progress from 0 to target value when component first becomes visible.                                                    | ProgressMixin  |
-| `ariaLabel`               |         | `string \| null`                                   | `null`      | Optional aria-label attribute for screen readers.
Describes what the progress indicator represents.                                     | ProgressMixin  |
-| `ariaLabelledBy`          |         | `string \| null`                                   | `null`      | Optional aria-labelledby attribute for screen readers.
References the ID of an element that labels the progress indicator.              | ProgressMixin  |
-| `ariaValueText`           |         | `string \| null`                                   | `null`      | Optional aria-valuetext attribute for screen readers.
Provides human-readable text alternative for progress value.                      | ProgressMixin  |
-| `completionAnnouncement`  |         | `string \| undefined`                              |             | Optional message to announce to screen readers when progress reaches 100%.
If not provided, no announcement will be made on completion. | ProgressMixin  |
-| `_isAnimationInitialized` | private | `boolean`                                          | `false`     |                                                                                                                                             | ProgressMixin  |
-| `_intersectionObserver`   | private | `IntersectionObserver \| undefined`                |             |                                                                                                                                             | ProgressMixin  |
-| `_hasCompletedAt100`      | private | `boolean`                                          | `false`     |                                                                                                                                             | ProgressMixin  |
-| `_hostTag`                | private | `'btu-linear-progress' \| 'btu-circular-progress'` |             |                                                                                                                                             | ProgressMixin  |
-
-### 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-circular-progress-ready`    | `CustomEvent` | Fired after first render and initialization |                |
-| `btu-circular-progress-complete` | `CustomEvent` | Fired when determinate progress reaches 100 |                |
-
-### Attributes
-
-| Name                      | Field                  | Inherited From |
-| ------------------------- | ---------------------- | -------------- |
-| `indeterminate`           | indeterminate          |                |
-| `size`                    | size                   |                |
-| `color`                   | color                  | ProgressMixin  |
-| `thickness`               | thickness              | ProgressMixin  |
-| `progress`                | progress               | ProgressMixin  |
-| `label`                   | label                  | ProgressMixin  |
-| `initial-animation`       | initialAnimation       | ProgressMixin  |
-| `aria-label`              | ariaLabel              | ProgressMixin  |
-| `aria-labelledby`         | ariaLabelledBy         | ProgressMixin  |
-| `aria-valuetext`          | ariaValueText          | ProgressMixin  |
-| `completion-announcement` | completionAnnouncement | ProgressMixin  |
-
-### CSS Properties
-
-| Name               | Default | 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)           |
-
-<hr/>
-
-## Exports
-
-| Kind                        | Name                    | Declaration      | Module                                               | Package |
-| --------------------------- | ----------------------- | ---------------- | ---------------------------------------------------- | ------- |
-| `js`                        | `default`               | CircularProgress | src/components/circular-progress/CircularProgress.ts |         |
-| `custom-element-definition` | `btu-circular-progress` | CircularProgress | src/components/circular-progress/CircularProgress.ts |         |
+# `<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/docs/components/CopyToClipboard.md

@@ -1,56 +1,51 @@
-# `src/components/copy-to-clipboard/CopyToClipboard.ts`:
+# `<btu-copy-to-clipboard>`
 
-## class: `CopyToClipboard`, `btu-copy-to-clipboard`
+A button component that copies text to the system clipboard.
 
-### Superclass
+Provides visual feedback when text is successfully copied by applying
+a temporary state that can be styled with CSS.
 
-| Name         | Module | Package |
-| ------------ | ------ | ------- |
-| `LitElement` |        | lit     |
+Button styling is inherited from `btu-button-*` classes. Override appearance
+by passing custom classes via the `buttonclasses` attribute.
 
-### Mixins
+```js
+import '@brightspot/ui/components/copy-to-clipboard/CopyToClipboard.js'
+```
 
-| Name                   | Module                            | Package |
-| ---------------------- | --------------------------------- | ------- |
-| `ClipboardMixin`       | /src/util/ClipboardMixin.js       |         |
-| `ComponentStatesMixin` | /src/util/ComponentStatesMixin.js |         |
-| `EventEmitterMixin`    | /src/util/EventEmitterMixin.js    |         |
-| `ReadyMixin`           | /src/util/ReadyMixin.js           |         |
+The CMS page defines this element itself, so a plugin can use it there without the import.
 
-### Fields
+Interactive examples: https://ui.brightspot.com/?path=/docs/components-copy-to-clipboard--docs
 
-| Name             | Privacy | Type                             | Default | Description                                                                     | Inherited From |
-| ---------------- | ------- | -------------------------------- | ------- | ------------------------------------------------------------------------------- | -------------- |
-| `copydata`       |         | `string \| undefined`            |         | The text to be copied to the system clipboard.                                  |                |
-| `buttonClasses`  |         | `string \| undefined`            |         | Custom CSS classes for the button. If provided, replaces the default classes.   |                |
-| `copiedStateKey` |         | `'btu-copy-to-clipboard-copied'` |         | Custom state applied briefly after a successful copy; also emitted as an event. | ClipboardMixin |
+## Attributes
 
-### Methods
+| 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. |
 
-| Name   | Privacy | Description                                                                                                                                                                                                                                                                        | Parameters                                              | Return    | Inherited From    |
-| ------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | --------- | ----------------- |
-| `copy` |         | Copies the copydata to the system clipboard.&#xA;Displays a success state for 3 seconds after copying.                                                                                                                                                                             | `text: string, timeout`                                 |           | ClipboardMixin    |
-| `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 |
+## Properties
 
-### Events
+These have no attribute; set them from JavaScript.
 
-| Name                           | Type          | Description                                         | Inherited From |
-| ------------------------------ | ------------- | --------------------------------------------------- | -------------- |
-| `btu-copy-to-clipboard-ready`  | `CustomEvent` | Fired after first render and initialization         |                |
-| `btu-copy-to-clipboard-copied` | `CustomEvent` | Fired when text is successfully copied to clipboard |                |
+| 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. |
 
-### Attributes
+## Methods
 
-| Name            | Field         | Inherited From |
-| --------------- | ------------- | -------------- |
-| `copydata`      | copydata      |                |
-| `buttonclasses` | buttonClasses |                |
+| Method | Description |
+| --- | --- |
+| `copy(text: string, timeout: unknown)` | Copies the copydata to the system clipboard. Displays a success state for 3 seconds after copying. |
 
-<hr/>
+## Events
 
-## Exports
+| 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 |
 
-| Kind                        | Name                    | Declaration     | Module                                              | Package |
-| --------------------------- | ----------------------- | --------------- | --------------------------------------------------- | ------- |
-| `js`                        | `default`               | CopyToClipboard | src/components/copy-to-clipboard/CopyToClipboard.ts |         |
-| `custom-element-definition` | `btu-copy-to-clipboard` | CopyToClipboard | src/components/copy-to-clipboard/CopyToClipboard.ts |         |
+## CSS states
+
+| State | Description |
+| --- | --- |
+| `:state(btu-copy-to-clipboard-copied)` | Applied briefly after a successful copy, targetable via :state(btu-copy-to-clipboard-copied) |

package/docs/components/Dropdown.md

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

package/docs/components/DropdownItem.md

@@ -1,81 +1,45 @@
-# `src/components/dropdown/DropdownItem.ts`:
-
-## class: `DropdownItem`, `btu-dropdown-item`
-
-### 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 |
-| ----------- | ------- | ------------------------------------- | ----------- | ---------------------------------------------- | -------------- |
-| `label`     |         | `string`                              | `''`        | Display text for the item.                     |                |
-| `type`      |         | `'default' \| 'divider' \| 'subhead'` | `'default'` | Item type: 'default', 'divider', or 'subhead'. |                |
-| `symbol`    |         | `string`                              | `''`        | Lucide icon symbol.                            |                |
-| `shortcut`  |         | `string`                              | `''`        | Keyboard shortcut display text.                |                |
-| `value`     |         | `string`                              | `''`        | Optional data value associated with the item.  |                |
-| `disabled`  |         | `boolean`                             | `false`     | Whether the item is disabled.                  |                |
-| `selected`  |         | `boolean`                             | `false`     | Whether the item is selected/checked.          |                |
-| `favorited` |         | `boolean`                             | `false`     | Whether the item is favorited.                 |                |
-| `error`     |         | `boolean`                             | `false`     | Whether the item has an error.                 |                |
-
-### Methods
-
-| Name              | Privacy | Description                                                                                                                                                                                                                                                                        | Parameters                                              | Return    | Inherited From    |
-| ----------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | --------- | ----------------- |
-| `_toggleFavorite` | private | Toggle favorite state                                                                                                                                                                                                                                                              | `e: Event`                                              | `void`    |                   |
-| `_handleClick`    | 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-dropdown-item-ready`    | `CustomEvent`                                                    | Fired after first render       |                |
-| `btu-dropdown-item-select`   | `CustomEvent<{label: string, value: string, selected: boolean}>` | Fired when item is activated   |                |
-| `btu-dropdown-item-favorite` | `CustomEvent<{label: string, favorited: boolean}>`               | Fired when favorite is toggled |                |
-
-### Attributes
-
-| Name        | Field     | Inherited From |
-| ----------- | --------- | -------------- |
-| `label`     | label     |                |
-| `type`      | type      |                |
-| `symbol`    | symbol    |                |
-| `shortcut`  | shortcut  |                |
-| `value`     | value     |                |
-| `disabled`  | disabled  |                |
-| `selected`  | selected  |                |
-| `favorited` | favorited |                |
-| `error`     | error     |                |
-
-### CSS Properties
-
-| Name                                  | Default | Description                                     |
-| ------------------------------------- | ------- | ----------------------------------------------- |
-| `--dropdown-item-font-size`           |         | Item font size (default: theme fontSize.sm)     |
-| `--dropdown-item-color`               |         | Item text color (default: gray-700)             |
-| `--dropdown-item-background`          |         | Item background color (default: transparent)    |
-| `--dropdown-item-hover-background`    |         | Background on hover (default: gray-100)         |
-| `--dropdown-item-hover-color`         |         | Text color on hover (default: gray-900)         |
-| `--dropdown-item-selected-background` |         | Background when selected (default: primary-50)  |
-| `--dropdown-item-selected-color`      |         | Text color when selected (default: primary-700) |
-
-<hr/>
-
-## Exports
-
-| Kind                        | Name                | Declaration  | Module                                  | Package |
-| --------------------------- | ------------------- | ------------ | --------------------------------------- | ------- |
-| `js`                        | `default`           | DropdownItem | src/components/dropdown/DropdownItem.ts |         |
-| `custom-element-definition` | `btu-dropdown-item` | DropdownItem | src/components/dropdown/DropdownItem.ts |         |
+# `<btu-dropdown-item>`
+
+A menu item component for use inside `btu-dropdown-menu`.
+
+Renders as a menu item, divider, or subhead depending on the `type` property.
+Supports checkbox mode (inherited from parent menu), icons, keyboard shortcuts,
+and favorite toggles.
+
+```js
+import '@brightspot/ui/components/dropdown/DropdownItem.js'
+```
+
+## Attributes
+
+| Attribute | Property | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `label` | `label` | `string` | `''` | Display text for the item. |
+| `type` | `type` | `'default' \| 'divider' \| 'subhead'` | `'default'` | Item type: 'default', 'divider', or 'subhead'. |
+| `symbol` | `symbol` | `string` | `''` | Lucide icon symbol. |
+| `shortcut` | `shortcut` | `string` | `''` | Keyboard shortcut display text. |
+| `value` | `value` | `string` | `''` | Optional data value associated with the item. |
+| `disabled` | `disabled` | `boolean` | `false` | Whether the item is disabled. |
+| `selected` | `selected` | `boolean` | `false` | Whether the item is selected/checked. |
+| `favorited` | `favorited` | `boolean` | `false` | Whether the item is favorited. |
+| `error` | `error` | `boolean` | `false` | Whether the item has an error. |
+
+## Events
+
+| Event | Detail | Description |
+| --- | --- | --- |
+| `btu-dropdown-item-ready` |  | Fired after first render |
+| `btu-dropdown-item-select` | `{label: string, value: string, selected: boolean}` | Fired when item is activated |
+| `btu-dropdown-item-favorite` | `{label: string, favorited: boolean}` | Fired when favorite is toggled |
+
+## CSS custom properties
+
+| Property | Description |
+| --- | --- |
+| `--dropdown-item-font-size` | Item font size (default: theme fontSize.sm) |
+| `--dropdown-item-color` | Item text color (default: gray-700) |
+| `--dropdown-item-background` | Item background color (default: transparent) |
+| `--dropdown-item-hover-background` | Background on hover (default: gray-100) |
+| `--dropdown-item-hover-color` | Text color on hover (default: gray-900) |
+| `--dropdown-item-selected-background` | Background when selected (default: primary-50) |
+| `--dropdown-item-selected-color` | Text color when selected (default: primary-700) |