@brightspot/ui 6.8.1 → 6.8.3-rc.1

package/docs/components/AiSparkle.md

@@ -1,70 +1,33 @@
-# `src/components/ai-sparkle/AiSparkle.ts`:
+# `<btu-ai-sparkle>`
 
-## class: `AiSparkle`, `btu-ai-sparkle`
+The animated AI-branding sparkle. Drive it with the `playing` boolean: `true` loops the clip to
+draw the eye to an AI entry point, `false` freezes the full sparkle so it reads as a static brand
+mark once the surface it advertises is engaged. Reduced-motion users always get the frozen frame.
 
-### Superclass
+Decorative by default (`aria-hidden="true"`, set only when absent) — the control it sits in owns
+the accessible name.
 
-| Name         | Module | Package |
-| ------------ | ------ | ------- |
-| `LitElement` |        | lit     |
+```js
+import '@brightspot/ui/components/ai-sparkle/AiSparkle.js'
+```
 
-### Mixins
+Interactive examples: https://ui.brightspot.com/?path=/docs/components-ai-sparkle--docs
 
-| Name                | Module                         | Package |
-| ------------------- | ------------------------------ | ------- |
-| `EventEmitterMixin` | /src/util/EventEmitterMixin.js |         |
-| `ReadyMixin`        | /src/util/ReadyMixin.js        |         |
+## Attributes
 
-### Fields
+| Attribute | Property | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `playing` | `playing` | `boolean` | `false` | Whether the sparkle animates; otherwise it holds the last (fully-formed) frame. Opt-in (default `false`) like `autoplay`: a boolean defaulting to `true` can't be cleared by attribute absence. The converter also treats `playing="false"` as paused (a plain `type: Boolean` would read any present value, even "false", as `true`). |
+| `size` | `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'` | Size of the sparkle, mirroring `<btu-avatar>`'s scale. `--ai-sparkle-size` overrides it. |
 
-| Name                    | Privacy | Type                                | Default | Description                                                                                                                                                                                                                                                                                                                                                    | Inherited From |
-| ----------------------- | ------- | ----------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- |
-| `playing`               |         | `boolean`                           | `false` | Whether the sparkle animates; otherwise it holds the last (fully-formed) frame. Opt-in&#xA;(default \`false\`) like \`autoplay\`: a boolean defaulting to \`true\` can't be cleared by attribute&#xA;absence. The converter also treats \`playing="false"\` as paused (a plain \`type: Boolean\` would&#xA;read any present value, even "false", as \`true\`). |                |
-| `size`                  |         | `AiSparkleSize`                     | `'md'`  | Size of the sparkle, mirroring \`\<btu-avatar>\`'s scale. \`--ai-sparkle-size\` overrides it.                                                                                                                                                                                                                                                                  |                |
-| `_containerRef`         | private | `Ref<HTMLDivElement>`               |         |                                                                                                                                                                                                                                                                                                                                                                |                |
-| `_animation`            | private | `AnimationItem \| null`             | `null`  |                                                                                                                                                                                                                                                                                                                                                                |                |
-| `_loaded`               | private | `boolean`                           | `false` |                                                                                                                                                                                                                                                                                                                                                                |                |
-| `_loadToken`            | private | `number`                            | `0`     |                                                                                                                                                                                                                                                                                                                                                                |                |
-| `_reduceMotion`         | private | `boolean`                           | `false` |                                                                                                                                                                                                                                                                                                                                                                |                |
-| `_visible`              | private | `boolean`                           | `true`  |                                                                                                                                                                                                                                                                                                                                                                |                |
-| `_resizeObserver`       | private | `ResizeObserver \| undefined`       |         |                                                                                                                                                                                                                                                                                                                                                                |                |
-| `_intersectionObserver` | private | `IntersectionObserver \| undefined` |         |                                                                                                                                                                                                                                                                                                                                                                |                |
-| `_motionQuery`          | private | `MediaQueryList \| undefined`       |         |                                                                                                                                                                                                                                                                                                                                                                |                |
-| `_onMotionChange`       | private |                                     |         |                                                                                                                                                                                                                                                                                                                                                                |                |
+## Events
 
-### Methods
+| Event | Detail | Description |
+| --- | --- | --- |
+| `btu-ai-sparkle-ready` |  | Fired after the first render |
 
-| Name         | Privacy | Description                                                                                                                                                                                                                                                                        | Parameters                                              | Return    | Inherited From    |
-| ------------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | --------- | ----------------- |
-| `_applySize` | private |                                                                                                                                                                                                                                                                                    |                                                         |           |                   |
-| `_build`     | private |                                                                                                                                                                                                                                                                                    |                                                         |           |                   |
-| `_sync`      | private |                                                                                                                                                                                                                                                                                    |                                                         |           |                   |
-| `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 |
+## CSS custom properties
 
-### Events
-
-| Name                   | Type          | Description                  | Inherited From |
-| ---------------------- | ------------- | ---------------------------- | -------------- |
-| `btu-ai-sparkle-ready` | `CustomEvent` | Fired after the first render |                |
-
-### Attributes
-
-| Name      | Field   | Inherited From |
-| --------- | ------- | -------------- |
-| `playing` | playing |                |
-| `size`    | size    |                |
-
-### CSS Properties
-
-| Name                | Default | Description                                                                         |
-| ------------------- | ------- | ----------------------------------------------------------------------------------- |
-| `--ai-sparkle-size` |         | Width and height of the sparkle; overrides the \`size\` attribute (default: 2.5rem) |
-
-<hr/>
-
-## Exports
-
-| Kind                        | Name             | Declaration | Module                                 | Package |
-| --------------------------- | ---------------- | ----------- | -------------------------------------- | ------- |
-| `js`                        | `default`        | AiSparkle   | src/components/ai-sparkle/AiSparkle.ts |         |
-| `custom-element-definition` | `btu-ai-sparkle` | AiSparkle   | src/components/ai-sparkle/AiSparkle.ts |         |
+| Property | Description |
+| --- | --- |
+| `--ai-sparkle-size` | Width and height of the sparkle; overrides the `size` attribute (default: 2.5rem) |

package/docs/components/Avatar.md

@@ -1,88 +1,45 @@
-# `src/components/avatar/Avatar.ts`:
-
-## class: `Avatar`, `btu-avatar`
-
-### 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 |
-| ------------------------- | ------- | ----------------------------------------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- |
-| `src`                     |         | `string`                                        | `''`            | Image source URL                                                                                                                                                                                                 |                |
-| `alt`                     |         | `string`                                        | `''`            | Alt text for the image                                                                                                                                                                                           |                |
-| `fallback`                |         | `string`                                        | `''`            | Fallback text (typically user initials)                                                                                                                                                                          |                |
-| `size`                    |         | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| 'xxl'` | `'md'`          | Size variant.
- 'xs': Extra small (1.5rem)
- 'sm': Small (2.25rem)
- 'md': Medium (2.5rem) - default
- 'lg': Large (3rem)
- 'xl': Extra large (3.5rem)
- 'xxl': Extra extra large (4rem) |                |
-| `_initialClassesCaptured` | private | `boolean`                                       | `false`         |                                                                                                                                                                                                                  |                |
-| `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    |
-| ------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | --------- | ----------------- |
-| `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-avatar-ready`        | `CustomEvent`                              | Fired after first render and initialization |                |
-| `btu-avatar-image-loaded` | `CustomEvent<{src: string}>`               | Fired when image successfully loads         |                |
-| `btu-avatar-image-error`  | `CustomEvent<{src: string, error: Event}>` | Fired when image fails to load              |                |
-
-### Attributes
-
-| Name               | Field           | Inherited From |
-| ------------------ | --------------- | -------------- |
-| `src`              | src             |                |
-| `alt`              | alt             |                |
-| `fallback`         | fallback        |                |
-| `size`             | size            |                |
-| `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                                     |
-| -------------------------- | ------- | ----------------------------------------------- |
-| `--avatar-size`            |         | Custom size (overrides size prop)               |
-| `--avatar-bg-color`        |         | Fallback background color (default: purple-600) |
-| `--avatar-corner-rounding` |         | How rounded is the avatar (default: circle)     |
-| `--avatar-ring-color`      |         | Optional ring border color                      |
-| `--avatar-ring-width`      |         | Ring border width (default: 2px)                |
-
-<hr/>
-
-## Exports
-
-| Kind                        | Name         | Declaration | Module                          | Package |
-| --------------------------- | ------------ | ----------- | ------------------------------- | ------- |
-| `js`                        | `default`    | Avatar      | src/components/avatar/Avatar.ts |         |
-| `custom-element-definition` | `btu-avatar` | Avatar      | src/components/avatar/Avatar.ts |         |
+# `<btu-avatar>`
+
+An avatar component for displaying user profile images with fallback support.
+
+Avatars display user profile images with automatic fallback to initials when
+the image fails to load or is not provided.
+
+```js
+import '@brightspot/ui/components/avatar/Avatar.js'
+```
+
+Interactive examples: https://ui.brightspot.com/?path=/docs/components-avatar--docs
+
+## Attributes
+
+| Attribute | Property | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `src` | `src` | `string` | `''` | Image source URL |
+| `alt` | `alt` | `string` | `''` | Alt text for the image |
+| `fallback` | `fallback` | `string` | `''` | Fallback text (typically user initials) |
+| `size` | `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| 'xxl'` | `'md'` | Size variant. - 'xs': Extra small (1.5rem) - 'sm': Small (2.25rem) - 'md': Medium (2.5rem) - default - 'lg': Large (3rem) - 'xl': Extra large (3.5rem) - 'xxl': Extra extra large (4rem) |
+| `tooltip` | `tooltip` | `string` | `''` | Tooltip text content. Set to empty string to remove the tooltip. |
+| `tooltip-position` | `tooltipPosition` | `'top' \| 'bottom' \| 'left' \| 'right'` | `'top'` | Position relative to the host element. Auto-flips when constrained by the viewport. |
+| `tooltip-delay` | `tooltipDelay` | `number` | `300` | Show delay in milliseconds (hover trigger only). |
+| `tooltip-offset` | `tooltipOffset` | `'sm' \| 'md' \| 'lg' \| 'xl' \| null` | `null` | Gap between host and tooltip (sm=4px, md=8px, lg=12px, xl=16px). |
+| `tooltip-no-arrow` | `tooltipNoArrow` | `boolean` | `false` | Hide the arrow pseudo-element. |
+| `tooltip-trigger` | `tooltipTrigger` | `string` | `'hover focus'` | Space-separated trigger types: 'hover', 'focus', 'click'. |
+
+## Events
+
+| Event | Detail | Description |
+| --- | --- | --- |
+| `btu-avatar-ready` |  | Fired after first render and initialization |
+| `btu-avatar-image-loaded` | `{src: string}` | Fired when image successfully loads |
+| `btu-avatar-image-error` | `{src: string, error: Event}` | Fired when image fails to load |
+
+## CSS custom properties
+
+| Property | Description |
+| --- | --- |
+| `--avatar-size` | Custom size (overrides size prop) |
+| `--avatar-bg-color` | Fallback background color (default: purple-600) |
+| `--avatar-corner-rounding` | How rounded is the avatar (default: circle) |
+| `--avatar-ring-color` | Optional ring border color |
+| `--avatar-ring-width` | Ring border width (default: 2px) |

package/docs/components/AvatarGroup.md

@@ -1,54 +1,34 @@
-# `src/components/avatar/AvatarGroup.ts`:
+# `<btu-avatar-group>`
 
-## class: `AvatarGroup`, `btu-avatar-group`
+A container component for grouping multiple avatars with consistent styling.
 
-### Superclass
+AvatarGroup wraps multiple avatar elements and provides:
+- Overflow handling (shows "+N" for excess avatars)
+- Consistent spacing and ring borders
+- Size inheritance for all child avatars
 
-| Name         | Module | Package |
-| ------------ | ------ | ------- |
-| `LitElement` |        | lit     |
+```js
+import '@brightspot/ui/components/avatar/AvatarGroup.js'
+```
 
-### Mixins
+Interactive examples: https://ui.brightspot.com/?path=/docs/components-avatar-group--docs
 
-| Name                | Module                         | Package |
-| ------------------- | ------------------------------ | ------- |
-| `EventEmitterMixin` | /src/util/EventEmitterMixin.js |         |
-| `ReadyMixin`        | /src/util/ReadyMixin.js        |         |
+## Attributes
 
-### Fields
+| Attribute | Property | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `max` | `max` | `number \| undefined` |  | Maximum number of visible avatars. Remaining avatars shown as "+N" |
+| `size` | `size` | `'xs' \| 'sm' \| 'md'` | `'md'` | Size variant for all child avatars (unless individually overridden) |
 
-| Name                      | Privacy | Type                   | Default | Description                                                         | Inherited From |
-| ------------------------- | ------- | ---------------------- | ------- | ------------------------------------------------------------------- | -------------- |
-| `max`                     |         | `number \| undefined`  |         | Maximum number of visible avatars. Remaining avatars shown as "+N"  |                |
-| `size`                    |         | `'xs' \| 'sm' \| 'md'` | `'md'`  | Size variant for all child avatars (unless individually overridden) |                |
-| `_initialClassesCaptured` | private | `boolean`              | `false` |                                                                     |                |
+## Methods
 
-### Methods
+| Method | Description |
+| --- | --- |
+| `processAvatars(): void` | Process all avatar children: apply size, handle overflow Call this method when avatars are dynamically added or removed |
 
-| Name             | Privacy | Description                                                                                                                                                                                                                                                                        | Parameters                                              | Return    | Inherited From    |
-| ---------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | --------- | ----------------- |
-| `processAvatars` |         | Process all avatar children: apply size, handle overflow&#xA;Call this method when avatars are dynamically added or removed                                                                                                                                                        |                                                         | `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
 
-### Events
-
-| Name                        | Type                            | Description                                    | Inherited From |
-| --------------------------- | ------------------------------- | ---------------------------------------------- | -------------- |
-| `btu-avatar-group-ready`    | `CustomEvent`                   | Fired after first render and initialization    |                |
-| `btu-avatar-group-overflow` | `CustomEvent<{hidden: number}>` | Fired when avatars are hidden due to max limit |                |
-
-### Attributes
-
-| Name   | Field | Inherited From |
-| ------ | ----- | -------------- |
-| `max`  | max   |                |
-| `size` | size  |                |
-
-<hr/>
-
-## Exports
-
-| Kind                        | Name               | Declaration | Module                               | Package |
-| --------------------------- | ------------------ | ----------- | ------------------------------------ | ------- |
-| `js`                        | `default`          | AvatarGroup | src/components/avatar/AvatarGroup.ts |         |
-| `custom-element-definition` | `btu-avatar-group` | AvatarGroup | src/components/avatar/AvatarGroup.ts |         |
+| Event | Detail | Description |
+| --- | --- | --- |
+| `btu-avatar-group-ready` |  | Fired after first render and initialization |
+| `btu-avatar-group-overflow` | `{hidden: number}` | Fired when avatars are hidden due to max limit |

package/docs/components/Badge.md

@@ -1,75 +1,47 @@
-# `src/components/badge/Badge.ts`:
+# `<btu-badge>`
 
-## class: `Badge`, `btu-badge`
+A badge component for highlighting important information.
 
-### Superclass
+Badges help highlight notifications, status, or new messages.
+Primarily used for communicating secondary or additional information.
 
-| Name         | Module | Package |
-| ------------ | ------ | ------- |
-| `LitElement` |        | lit     |
+```js
+import '@brightspot/ui/components/badge/Badge.js'
+```
 
-### Mixins
+The CMS page defines this element itself, so a plugin can use it there without the import.
 
-| Name                | Module                         | Package |
-| ------------------- | ------------------------------ | ------- |
-| `EventEmitterMixin` | /src/util/EventEmitterMixin.js |         |
-| `ReadyMixin`        | /src/util/ReadyMixin.js        |         |
+Interactive examples: https://ui.brightspot.com/?path=/docs/components-badge--docs
 
-### Fields
+## Attributes
 
-| Name                      | Privacy | Type                                                       | Default  | Description                                                                                                                                                                                                                                                                                                                            | Inherited From |
-| ------------------------- | ------- | ---------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- |
-| `variant`                 |         | `'info' \| 'primary' \| 'error' \| 'success' \| 'warning'` | `'info'` | Style of the badge.&#xA;- 'info': Informational (default)&#xA;- 'primary': Primary action or emphasis&#xA;- 'error': Error or danger state&#xA;- 'success': Success or completion state&#xA;- 'warning': Warning or caution state                                                                                                      |                |
-| `dot`                     |         | `boolean`                                                  | `false`  | Should a dot be displayed before the label?                                                                                                                                                                                                                                                                                            |                |
-| `size`                    |         | `'sm' \| 'md' \| 'lg'`                                     | `'sm'`   | Size variant.&#xA;- 'sm': Small (default)&#xA;- 'md': Medium&#xA;- 'lg': Large                                                                                                                                                                                                                                                         |                |
-| `activity`                |         | `'busy' \| 'live' \| undefined`                            |          | Attention state that draws the eye to the badge. Names the \*intent\*; the&#xA;component owns the visual treatment (so it can change without callers).&#xA;- 'busy': an in-progress state — a glint shimmers across the label text&#xA;- 'live': a live/active state — a ring ripples out from the leading dot&#xA;  (implies \`dot\`) |                |
-| `fill`                    |         | `'soft' \| 'solid'`                                        | `'soft'` | Fill style.&#xA;- 'soft': pale background with strong text (default)&#xA;- 'solid': swaps the shades for a filled pill                                                                                                                                                                                                                 |                |
-| `_initialClassesCaptured` | private | `boolean`                                                  | `false`  |                                                                                                                                                                                                                                                                                                                                        |                |
+| Attribute | Property | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `variant` | `variant` | `'info' \| 'primary' \| 'error' \| 'success' \| 'warning'` | `'info'` | Style of the badge. - 'info': Informational (default) - 'primary': Primary action or emphasis - 'error': Error or danger state - 'success': Success or completion state - 'warning': Warning or caution state |
+| `dot` | `dot` | `boolean` | `false` | Should a dot be displayed before the label? |
+| `size` | `size` | `'sm' \| 'md' \| 'lg'` | `'sm'` | Size variant. - 'sm': Small (default) - 'md': Medium - 'lg': Large |
+| `activity` | `activity` | `'busy' \| 'live' \| undefined` |  | Attention state that draws the eye to the badge. Names the *intent*; the component owns the visual treatment (so it can change without callers). - 'busy': an in-progress state — a glint shimmers across the label text - 'live': a live/active state — a ring ripples out from the leading dot (implies `dot`) |
+| `fill` | `fill` | `'soft' \| 'solid'` | `'soft'` | Fill style. - 'soft': pale background with strong text (default) - 'solid': swaps the shades for a filled pill |
 
-### 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-badge-ready` |  | Fired after first render and initialization |
 
-### Events
+## Slots
 
-| Name              | Type          | Description                                 | Inherited From |
-| ----------------- | ------------- | ------------------------------------------- | -------------- |
-| `btu-badge-ready` | `CustomEvent` | Fired after first render and initialization |                |
+| Slot | Description |
+| --- | --- |
+| (default) | Label text or child elements (e.g., btu-icon + text) |
 
-### Attributes
+## CSS custom properties
 
-| Name       | Field    | Inherited From |
-| ---------- | -------- | -------------- |
-| `variant`  | variant  |                |
-| `dot`      | dot      |                |
-| `size`     | size     |                |
-| `activity` | activity |                |
-| `fill`     | fill     |                |
-
-### CSS Properties
-
-| Name                       | Default | Description                                                  |
-| -------------------------- | ------- | ------------------------------------------------------------ |
-| `--badge-color-foreground` |         | Text color (overrides theme color)                           |
-| `--badge-color-background` |         | Background color (overrides theme color)                     |
-| `--badge-radius-size`      |         | Border radius size (overrides shape default, default: 999px) |
-| `--badge-px`               |         | Horizontal padding (overrides size default)                  |
-| `--badge-py`               |         | Vertical padding (overrides size default)                    |
-| `--badge-dot-size`         |         | Size of the dot affordance (default: 6px)                    |
-
-### Slots
-
-| Name | Description                                          |
-| ---- | ---------------------------------------------------- |
-|      | Label text or child elements (e.g., btu-icon + text) |
-
-<hr/>
-
-## Exports
-
-| Kind                        | Name        | Declaration | Module                        | Package |
-| --------------------------- | ----------- | ----------- | ----------------------------- | ------- |
-| `js`                        | `default`   | Badge       | src/components/badge/Badge.ts |         |
-| `custom-element-definition` | `btu-badge` | Badge       | src/components/badge/Badge.ts |         |
+| Property | Description |
+| --- | --- |
+| `--badge-color-foreground` | Text color (overrides theme color) |
+| `--badge-color-background` | Background color (overrides theme color) |
+| `--badge-radius-size` | Border radius size (overrides shape default, default: 999px) |
+| `--badge-px` | Horizontal padding (overrides size default) |
+| `--badge-py` | Vertical padding (overrides size default) |
+| `--badge-dot-size` | Size of the dot affordance (default: 6px) |

package/docs/components/Banner.md

@@ -1,49 +1,35 @@
-# `src/components/banner/Banner.ts`:
+# `<btu-banner>`
 
-## class: `Banner`, `btu-banner`
+A full-width container that pins a `<btu-message>` to the top of the CMS or a
+content edit page. The banner has no content API of its own — compose a
+`<btu-message>` inside it (or several, e.g. for a paginated banner) and the banner
+spans each to 100% of the host, rendering it full-bleed (edge-to-edge, bottom
+border only, no corner rounding).
 
-### Superclass
+Set the content (variant, label, symbol, dismissible, badge/description/actions
+slots) on the message itself. The full-width treatment lives on this wrapper, so
+the message has no `full-width` attribute — the banner owns that.
 
-| Name         | Module | Package |
-| ------------ | ------ | ------- |
-| `LitElement` |        | lit     |
+```js
+import '@brightspot/ui/components/banner/Banner.js'
+```
 
-### Mixins
+Interactive examples: https://ui.brightspot.com/?path=/docs/components-banner--docs
 
-| Name                | Module                         | Package |
-| ------------------- | ------------------------------ | ------- |
-| `EventEmitterMixin` | /src/util/EventEmitterMixin.js |         |
-| `ReadyMixin`        | /src/util/ReadyMixin.js        |         |
+## Events
 
-### Methods
+| Event | Detail | Description |
+| --- | --- | --- |
+| `btu-banner-ready` |  | Fired after the banner is first rendered and initialized |
 
-| 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 |
+## Slots
 
-### Events
+| Slot | Description |
+| --- | --- |
+| (default) | One or more `<btu-message>` elements, full-bleed to the host width. With more than one, the banner auto-creates a `<btu-pagination>` and shows one at a time. |
 
-| Name               | Type          | Description                                              | Inherited From |
-| ------------------ | ------------- | -------------------------------------------------------- | -------------- |
-| `btu-banner-ready` | `CustomEvent` | Fired after the banner is first rendered and initialized |                |
+## CSS custom properties
 
-### CSS Properties
-
-| Name               | Default | Description                                                                                                                                                       |
-| ------------------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `--banner-z-index` |         | Stack order for the banner (default: 100). The banner is \`position: relative\`, so this always applies; set \`position: sticky\` to also pin it to the viewport. |
-
-### Slots
-
-| Name | Description                                                                                                                                                         |
-| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-|      | One or more \`\<btu-message>\` elements, full-bleed to the host width. With more than one, the banner auto-creates a \`\<btu-pagination>\` and shows one at a time. |
-
-<hr/>
-
-## Exports
-
-| Kind                        | Name         | Declaration | Module                          | Package |
-| --------------------------- | ------------ | ----------- | ------------------------------- | ------- |
-| `js`                        | `default`    | Banner      | src/components/banner/Banner.ts |         |
-| `custom-element-definition` | `btu-banner` | Banner      | src/components/banner/Banner.ts |         |
+| Property | Description |
+| --- | --- |
+| `--banner-z-index` | Stack order for the banner (default: 100). The banner is `position: relative`, so this always applies; set `position: sticky` to also pin it to the viewport. |