@brightspot/ui 6.8.1 → 6.8.2

package/docs/components/IconButton.md

@@ -1,83 +1,36 @@
-# `src/components/icon-button/IconButton.ts`:
-
-## class: `IconButton`, `btu-icon-button`
-
-### 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 |
-| ------------------ | ------- | ---------------------------------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- |
-| `name`             |         | `string \| undefined`                    |                 | Optional name for the button which can be used to identify the button in a callback.                                                                      |                |
-| `type`             |         | `IconButtonType`                         | `'primary'`     | Specifies the type of icon-button, controlling the visual style.                                                                                          |                |
-| `symbol`           |         | `string \| undefined`                    |                 | Lucide icon symbol.                                                                                                                                       |                |
-| `size`             |         | `IconButtonSize`                         | `'md'`          | Specifies the size of icon-button.                                                                                                                        |                |
-| `destructive`      |         | `boolean`                                | `false`         | Specifies an icon-button will be used to take any destructive action overriding the
default color used for the icon-button type with the error color. |                |
-| `disabled`         |         | `boolean`                                | `false`         | Disables the button, preventing interaction and indicating an inactive state.                                                                             |                |
-| `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    |
-| --------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | --------- | ----------------- |
-| `_relayTooltipAttrs`  | private |                                                                                                                                                                                                                                                                                    |                                                         | `void`    |                   |
-| `_handleClick`        | private |                                                                                                                                                                                                                                                                                    |                                                         | `void`    |                   |
-| `_buildButtonClasses` | private |                                                                                                                                                                                                                                                                                    |                                                         | `string`  |                   |
-| `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-icon-button-ready` | `CustomEvent`                              | Fired after first render and initialization |                |
-| `btu-icon-button-click` | `CustomEvent<{name: string \| undefined}>` | Fired when the button is clicked            |                |
-
-### Attributes
-
-| Name               | Field           | Inherited From |
-| ------------------ | --------------- | -------------- |
-| `name`             | name            |                |
-| `type`             | type            |                |
-| `symbol`           | symbol          |                |
-| `size`             | size            |                |
-| `destructive`      | destructive     |                |
-| `disabled`         | disabled        |                |
-| `tooltip`          | tooltip         | TooltipMixin   |
-| `tooltip-position` | tooltipPosition | TooltipMixin   |
-| `tooltip-delay`    | tooltipDelay    | TooltipMixin   |
-| `tooltip-offset`   | tooltipOffset   | TooltipMixin   |
-| `tooltip-no-arrow` | tooltipNoArrow  | TooltipMixin   |
-| `tooltip-trigger`  | tooltipTrigger  | TooltipMixin   |
-
-<hr/>
-
-## Exports
-
-| Kind                        | Name              | Declaration | Module                                   | Package |
-| --------------------------- | ----------------- | ----------- | ---------------------------------------- | ------- |
-| `js`                        | `default`         | IconButton  | src/components/icon-button/IconButton.ts |         |
-| `custom-element-definition` | `btu-icon-button` | IconButton  | src/components/icon-button/IconButton.ts |         |
+# `<btu-icon-button>`
+
+Surfaces the different actions someone can perform in an interface where space is limited.
+
+Uses an icon to communicate the action and supports multiple visual types and sizes.
+Tooltip support is built-in for accessibility in compact layouts.
+
+```js
+import '@brightspot/ui/components/icon-button/IconButton.js'
+```
+
+Interactive examples: https://ui.brightspot.com/?path=/docs/components-icon-button--docs
+
+## Attributes
+
+| Attribute | Property | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `name` | `name` | `string \| undefined` |  | Optional name for the button which can be used to identify the button in a callback. |
+| `type` | `type` | `'primary' \| 'primary-clear' \| 'primary-stroke' \| 'secondary' \| 'secondary-clear' \| 'secondary-stroke' \| 'tertiary' \| 'tertiary-clear' \| 'tertiary-stroke'` | `'primary'` | Specifies the type of icon-button, controlling the visual style. |
+| `symbol` | `symbol` | `string \| undefined` |  | Lucide icon symbol. |
+| `size` | `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Specifies the size of icon-button. |
+| `destructive` | `destructive` | `boolean` | `false` | Specifies an icon-button will be used to take any destructive action overriding the default color used for the icon-button type with the error color. |
+| `disabled` | `disabled` | `boolean` | `false` | Disables the button, preventing interaction and indicating an inactive state. |
+| `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-icon-button-ready` |  | Fired after first render and initialization |
+| `btu-icon-button-click` | `{name: string \| undefined}` | Fired when the button is clicked |

package/docs/components/LinearProgress.md

@@ -1,79 +1,37 @@
-# `src/components/linear-progress/LinearProgress.ts`:
+# `<btu-linear-progress>`
 
-## class: `LinearProgress`, `btu-linear-progress`
+A horizontal linear progress bar for showing task completion.
 
-### Superclass
+```js
+import '@brightspot/ui/components/linear-progress/LinearProgress.js'
+```
 
-| Name         | Module | Package |
-| ------------ | ------ | ------- |
-| `LitElement` |        | lit     |
+Interactive examples: https://ui.brightspot.com/?path=/docs/components-linear-progress--docs
 
-### Mixins
+## Attributes
 
-| Name                | Module                         | Package |
-| ------------------- | ------------------------------ | ------- |
-| `ProgressMixin`     | /src/util/ProgressMixin.js     |         |
-| `EventEmitterMixin` | /src/util/EventEmitterMixin.js |         |
-| `ReadyMixin`        | /src/util/ReadyMixin.js        |         |
+| Attribute | Property | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `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. |
 
-### Fields
+## Events
 
-| Name                      | Privacy | Type                                               | Default     | Description                                                                                                                                 | Inherited From |
-| ------------------------- | ------- | -------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------- | -------------- |
-| `color`                   |         | `ProgressColors`                                   | `'primary'` | Color theme of the progress indicator.&#xA;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.&#xA;Describes what the progress indicator represents.                                     | ProgressMixin  |
-| `ariaLabelledBy`          |         | `string \| null`                                   | `null`      | Optional aria-labelledby attribute for screen readers.&#xA;References the ID of an element that labels the progress indicator.              | ProgressMixin  |
-| `ariaValueText`           |         | `string \| null`                                   | `null`      | Optional aria-valuetext attribute for screen readers.&#xA;Provides human-readable text alternative for progress value.                      | ProgressMixin  |
-| `completionAnnouncement`  |         | `string \| undefined`                              |             | Optional message to announce to screen readers when progress reaches 100%.&#xA;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  |
+| Event | Detail | Description |
+| --- | --- | --- |
+| `btu-linear-progress-ready` |  | Fired after first render and initialization |
+| `btu-linear-progress-complete` |  | Fired when progress reaches 100 |
 
-### Methods
+## CSS custom properties
 
-| 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-linear-progress-ready`    | `CustomEvent` | Fired after first render and initialization |                |
-| `btu-linear-progress-complete` | `CustomEvent` | Fired when progress reaches 100             |                |
-
-### Attributes
-
-| Name                      | Field                  | Inherited From |
-| ------------------------- | ---------------------- | -------------- |
-| `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 bar color (overrides theme color)   |
-| `--track-color`    |         | Track/background color (overrides default gray-100) |
-
-<hr/>
-
-## Exports
-
-| Kind                        | Name                  | Declaration    | Module                                           | Package |
-| --------------------------- | --------------------- | -------------- | ------------------------------------------------ | ------- |
-| `js`                        | `default`             | LinearProgress | src/components/linear-progress/LinearProgress.ts |         |
-| `custom-element-definition` | `btu-linear-progress` | LinearProgress | src/components/linear-progress/LinearProgress.ts |         |
+| Property | Description |
+| --- | --- |
+| `--progress-color` | Custom progress bar color (overrides theme color) |
+| `--track-color` | Track/background color (overrides default gray-100) |

package/docs/components/Message.md

@@ -1,75 +1,50 @@
-# `src/components/banner/Message.ts`:
+# `<btu-message>`
 
-## class: `Message`, `btu-message`
+A message for communicating high-visibility content that is not tied to the
+user's current task — alerts, breaking news, and persistent status. Use it on
+its own as a contained, bordered card, or place it inside a `<btu-banner>` to
+span the full width of the page (e.g., pinned above the CMS content area).
 
-### Superclass
+Messages render a leading icon, an optional badge, a label, an optional
+description, and an optional dismiss control. The label and description
+stack vertically in a text column; everything else sits on the same row.
 
-| Name         | Module | Package |
-| ------------ | ------ | ------- |
-| `LitElement` |        | lit     |
+```js
+import '@brightspot/ui/components/banner/Message.js'
+```
 
-### Mixins
+Interactive examples: https://ui.brightspot.com/?path=/docs/components-message--docs
 
-| Name                | Module                         | Package |
-| ------------------- | ------------------------------ | ------- |
-| `EventEmitterMixin` | /src/util/EventEmitterMixin.js |         |
-| `ReadyMixin`        | /src/util/ReadyMixin.js        |         |
+## Attributes
 
-### Fields
+| Attribute | Property | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `variant` | `variant` | `'primary' \| 'info' \| 'warning' \| 'error' \| 'success'` | `'info'` | Visual style and semantic meaning of the message. |
+| `label` | `label` | `string \| undefined` |  | The primary message or title text displayed. |
+| `symbol` | `symbol` | `string \| undefined` |  | Name of the Lucide icon to display. Defaults to a sensible icon per variant. |
+| `dismissible` | `dismissible` | `boolean` | `false` | If true, a close icon is provided to allow the user to hide the message. |
 
-| Name          | Privacy | Type                  | Default  | Description                                                                  | Inherited From |
-| ------------- | ------- | --------------------- | -------- | ---------------------------------------------------------------------------- | -------------- |
-| `variant`     |         | `MessageVariant`      | `'info'` | Visual style and semantic meaning of the message.                            |                |
-| `label`       |         | `string \| undefined` |          | The primary message or title text displayed.                                 |                |
-| `symbol`      |         | `string \| undefined` |          | Name of the Lucide icon to display. Defaults to a sensible icon per variant. |                |
-| `dismissible` |         | `boolean`             | `false`  | If true, a close icon is provided to allow the user to hide the message.     |                |
+## Events
 
-### Methods
+| Event | Detail | Description |
+| --- | --- | --- |
+| `btu-message-ready` |  | Fired after the message is first rendered and initialized |
+| `btu-message-dismiss` |  | Fired when the user clicks the close/dismiss button. Cancelable: the message hides itself (sets `hidden`) unless the listener calls `preventDefault()`. |
 
-| Name             | Privacy | Description                                                                                                                                                                                                                                                                        | Parameters                                              | Return    | Inherited From    |
-| ---------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | --------- | ----------------- |
-| `_handleDismiss` | 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 |
+## Slots
 
-### Events
+| Slot | Description |
+| --- | --- |
+| `badge` | Pseudo-slot for a leading status/version tag, typically a `<btu-badge>`. The slotted child is moved into the header row, before the label. |
+| `description` | Pseudo-slot for supporting text rendered directly beneath the label. Slot a single inline element (e.g., `<span slot="description">`) or a block element to enable rich content (links, emphasis). |
+| `actions` | Pseudo-slot for CTA buttons, links, or a `<btu-pagination>`. Children with `slot="actions"` are moved into an internal container on the trailing edge of the body. `.btu-button` children inherit the message's foreground color across all states. The message does not emit an action-click event — attach handlers to your own elements. |
 
-| Name                  | Type          | Description                                                                                                                                                 | Inherited From |
-| --------------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- |
-| `btu-message-ready`   | `CustomEvent` | Fired after the message is first rendered and initialized                                                                                                   |                |
-| `btu-message-dismiss` | `CustomEvent` | Fired when the user clicks the close/dismiss button. Cancelable: the message hides itself (sets \`hidden\`) unless the listener calls \`preventDefault()\`. |                |
+## CSS custom properties
 
-### Attributes
-
-| Name          | Field       | Inherited From |
-| ------------- | ----------- | -------------- |
-| `variant`     | variant     |                |
-| `label`       | label       |                |
-| `symbol`      | symbol      |                |
-| `dismissible` | dismissible |                |
-
-### CSS Properties
-
-| Name                         | Default | Description                                                      |
-| ---------------------------- | ------- | ---------------------------------------------------------------- |
-| `--message-color-background` |         | Overrides the background color for the message                   |
-| `--message-color-foreground` |         | Overrides the text and icon color                                |
-| `--message-color-border`     |         | Overrides the border color (defaults to the variant's 300 shade) |
-| `--message-padding`          |         | Overrides the internal padding (default: 1rem)                   |
-| `--message-border-radius`    |         | Overrides the corner rounding (default: 8px)                     |
-
-### Slots
-
-| Name          | Description                                                                                                                                                                                                                                                                                                                                        |
-| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `badge`       | Pseudo-slot for a leading status/version tag, typically a \`\<btu-badge>\`. The slotted child is moved into the header row, before the label.                                                                                                                                                                                                      |
-| `description` | Pseudo-slot for supporting text rendered directly beneath the label. Slot a single inline element (e.g., \`\<span slot="description">\`) or a block element to enable rich content (links, emphasis).                                                                                                                                              |
-| `actions`     | Pseudo-slot for CTA buttons, links, or a \`\<btu-pagination>\`. Children with \`slot="actions"\` are moved into an internal container on the trailing edge of the body. \`.btu-button\` children inherit the message's foreground color across all states. The message does not emit an action-click event — attach handlers to your own elements. |
-
-<hr/>
-
-## Exports
-
-| Kind                        | Name          | Declaration | Module                           | Package |
-| --------------------------- | ------------- | ----------- | -------------------------------- | ------- |
-| `js`                        | `default`     | Message     | src/components/banner/Message.ts |         |
-| `custom-element-definition` | `btu-message` | Message     | src/components/banner/Message.ts |         |
+| Property | Description |
+| --- | --- |
+| `--message-color-background` | Overrides the background color for the message |
+| `--message-color-foreground` | Overrides the text and icon color |
+| `--message-color-border` | Overrides the border color (defaults to the variant's 300 shade) |
+| `--message-padding` | Overrides the internal padding (default: 1rem) |
+| `--message-border-radius` | Overrides the corner rounding (default: 8px) |

package/docs/components/Pagination.md

@@ -1,100 +1,70 @@
-# `src/components/pagination/Pagination.ts`:
-
-## class: `Pagination`, `btu-pagination`
-
-### 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 |
-| ------------------------- | ------- | --------------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- |
-| `page`                    |         | `number`              | `1`            | Current page number (1-based)                                                                                                                                                           |                |
-| `pageSize`                |         | `number`              | `0`            | Number of items per page                                                                                                                                                                |                |
-| `disabled`                |         | `boolean`             | `false`        | Disables all pagination controls                                                                                                                                                        |                |
-| `loading`                 |         | `boolean`             | `false`        | Shows loading spinner and dims controls                                                                                                                                                 |                |
-| `hideOnSinglePage`        |         | `boolean`             | `true`         | Hide controls when there is only one page                                                                                                                                               |                |
-| `pageSizeChanger`         |         | `boolean`             | `true`         | Show the page size dropdown                                                                                                                                                             |                |
-| `pageSizeOptions`         |         | `string`              | `'10, 20, 50'` | Comma-separated page size options                                                                                                                                                       |                |
-| `totalItems`              |         | `number`              | `0`            | Total number of items across all pages                                                                                                                                                  |                |
-| `boundaryButtons`         |         | `boolean`             | `true`         | Show first and last page buttons                                                                                                                                                        |                |
-| `hideTotalCount`          |         | `boolean`             | `false`        | Hide the item count display (e.g., "1-10 of 200")                                                                                                                                       |                |
-| `pageJumper`              |         | `boolean`             | `false`        | Show the page jumper dropdown. Intended for moderate page counts (under \~100 pages).
For large datasets, use a custom \`slot="jumper"\` with a virtualized or input-based control. |                |
-| `label`                   |         | `string \| undefined` |                | Accessible label for the pagination nav landmark                                                                                                                                        |                |
-| `_initialClassesCaptured` | private | `boolean`             | `false`        |                                                                                                                                                                                         |                |
-| `_parsedPageSizeOptions`  | private | `number[]`            |                |                                                                                                                                                                                         |                |
-| `_totalPages`             | private | `number`              |                |                                                                                                                                                                                         |                |
-| `_startItem`              | private | `number`              |                |                                                                                                                                                                                         |                |
-| `_endItem`                | private | `number`              |                |                                                                                                                                                                                         |                |
-
-### Methods
-
-| Name                       | Privacy | Description                                                                                                                                                                                                                                                                        | Parameters                                              | Return    | Inherited From    |
-| -------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | --------- | ----------------- |
-| `_setupSlots`              | private |                                                                                                                                                                                                                                                                                    |                                                         | `void`    |                   |
-| `_goToFirstPage`           | private |                                                                                                                                                                                                                                                                                    | `e: Event`                                              | `void`    |                   |
-| `_goToPreviousPage`        | private |                                                                                                                                                                                                                                                                                    | `e: Event`                                              | `void`    |                   |
-| `_goToNextPage`            | private |                                                                                                                                                                                                                                                                                    | `e: Event`                                              | `void`    |                   |
-| `_goToLastPage`            | private |                                                                                                                                                                                                                                                                                    | `e: Event`                                              | `void`    |                   |
-| `_manageBoundaryFocus`     | private |                                                                                                                                                                                                                                                                                    | `clickedButton: IconButton`                             | `void`    |                   |
-| `_onBuiltinPageSizeSelect` | private |                                                                                                                                                                                                                                                                                    | `e: Event`                                              | `void`    |                   |
-| `_onBuiltinJumperSelect`   | private |                                                                                                                                                                                                                                                                                    | `e: Event`                                              | `void`    |                   |
-| `emit`                     |         | Dispatches a type-safe CustomEvent with standardized configuration.&#xA;&#xA;All events are configured with:&#xA;- bubbles: true (event propagates up the DOM tree)&#xA;- cancelable: false (event cannot be cancelled)&#xA;- composed: true (event crosses shadow DOM boundaries) | `type: K, detail: UnpackCustomEvent<CustomEventMap[K]>` | `boolean` | EventEmitterMixin |
-
-### Events
-
-| Name                              | Type                                            | Description               | Inherited From |
-| --------------------------------- | ----------------------------------------------- | ------------------------- | -------------- |
-| `btu-pagination-ready`            | `CustomEvent`                                   | Fired after first render  |                |
-| `btu-pagination-change`           | `CustomEvent<{page: number, pageSize: number}>` | Fired on page navigation  |                |
-| `btu-pagination-page-size-change` | `CustomEvent<{page: number, pageSize: number}>` | Fired on page size change |                |
-
-### Attributes
-
-| Name                  | Field            | Inherited From |
-| --------------------- | ---------------- | -------------- |
-| `page`                | page             |                |
-| `page-size`           | pageSize         |                |
-| `disabled`            | disabled         |                |
-| `loading`             | loading          |                |
-| `hide-on-single-page` | hideOnSinglePage |                |
-| `page-size-changer`   | pageSizeChanger  |                |
-| `page-size-options`   | pageSizeOptions  |                |
-| `total-items`         | totalItems       |                |
-| `boundary-buttons`    | boundaryButtons  |                |
-| `hide-total-count`    | hideTotalCount   |                |
-| `page-jumper`         | pageJumper       |                |
-| `label`               | label            |                |
-
-### CSS Properties
-
-| Name                            | Default | Description                                         |
-| ------------------------------- | ------- | --------------------------------------------------- |
-| `--pagination-color-background` |         | Background color for dropdowns, buttons, and jumper |
-| `--pagination-color-foreground` |         | Text/icon color                                     |
-
-### Slots
-
-| Name        | Description                                                                                    |
-| ----------- | ---------------------------------------------------------------------------------------------- |
-| `page-size` | Custom page-size selector (replaces built-in dropdown). Consumer manages all behavior.         |
-| `jumper`    | Custom jumper content (replaces built-in page jumper dropdown). Consumer manages all behavior. |
-
-<hr/>
-
-## Exports
-
-| Kind                        | Name             | Declaration | Module                                  | Package |
-| --------------------------- | ---------------- | ----------- | --------------------------------------- | ------- |
-| `js`                        | `default`        | Pagination  | src/components/pagination/Pagination.ts |         |
-| `custom-element-definition` | `btu-pagination` | Pagination  | src/components/pagination/Pagination.ts |         |
+# `<btu-pagination>`
+
+A pagination component for navigating through paged content.
+
+Supports multiple layout variants (Search, Widget, Widget Small, Calendar)
+through configurable props and pseudo-slots.
+
+**Page size modes:**
+
+- **Built-in** (default): When no `slot="page-size"` is provided and `page-size-changer`
+  is true, Pagination renders its own `btu-dropdown` from the `page-size-options` attribute.
+  Events, label sync, and page size changes are managed automatically.
+
+- **Custom slot**: When a child has `slot="page-size"`, the built-in dropdown is suppressed.
+  The consumer owns all behavior — event handling, label sync, etc. Use this for non-standard
+  selectors like a calendar week/month toggle.
+
+**Page jumper modes:**
+
+- **Built-in**: When `page-jumper` is true and no `slot="jumper"` is provided, Pagination
+  renders a dropdown with "Page 1" through "Page N" items. Fully reactive — updates
+  automatically when page, page size, or total items change.
+
+- **Custom slot**: When a child has `slot="jumper"`, the built-in dropdown is suppressed.
+  The consumer owns all behavior. Use this for custom jumper content like a "Today" button.
+
+```js
+import '@brightspot/ui/components/pagination/Pagination.js'
+```
+
+Interactive examples: https://ui.brightspot.com/?path=/docs/components-pagination--docs
+
+## Attributes
+
+| Attribute | Property | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `page` | `page` | `number` | `1` | Current page number (1-based) |
+| `page-size` | `pageSize` | `number` | `0` | Number of items per page |
+| `disabled` | `disabled` | `boolean` | `false` | Disables all pagination controls |
+| `loading` | `loading` | `boolean` | `false` | Shows loading spinner and dims controls |
+| `hide-on-single-page` | `hideOnSinglePage` | `boolean` | `true` | Hide controls when there is only one page |
+| `page-size-changer` | `pageSizeChanger` | `boolean` | `true` | Show the page size dropdown |
+| `page-size-options` | `pageSizeOptions` | `string` | `'10, 20, 50'` | Comma-separated page size options |
+| `total-items` | `totalItems` | `number` | `0` | Total number of items across all pages |
+| `boundary-buttons` | `boundaryButtons` | `boolean` | `true` | Show first and last page buttons |
+| `hide-total-count` | `hideTotalCount` | `boolean` | `false` | Hide the item count display (e.g., "1-10 of 200") |
+| `page-jumper` | `pageJumper` | `boolean` | `false` | Show the page jumper dropdown. Intended for moderate page counts (under ~100 pages). For large datasets, use a custom `slot="jumper"` with a virtualized or input-based control. |
+| `label` | `label` | `string \| undefined` |  | Accessible label for the pagination nav landmark |
+
+## Events
+
+| Event | Detail | Description |
+| --- | --- | --- |
+| `btu-pagination-ready` |  | Fired after first render |
+| `btu-pagination-change` | `{page: number, pageSize: number}` | Fired on page navigation |
+| `btu-pagination-page-size-change` | `{page: number, pageSize: number}` | Fired on page size change |
+
+## Slots
+
+| Slot | Description |
+| --- | --- |
+| `page-size` | Custom page-size selector (replaces built-in dropdown). Consumer manages all behavior. |
+| `jumper` | Custom jumper content (replaces built-in page jumper dropdown). Consumer manages all behavior. |
+
+## CSS custom properties
+
+| Property | Description |
+| --- | --- |
+| `--pagination-color-background` | Background color for dropdowns, buttons, and jumper |
+| `--pagination-color-foreground` | Text/icon color |