@brightspot/ui 6.8.1 → 6.8.3-rc.1

package/dist/storybook/docs/components/Radio.md

@@ -0,0 +1,55 @@
+# `<btu-radio>`
+
+A single radio option, selectable from a set of mutually exclusive choices.
+
+Uses a hidden native radio input internally for accessibility and form
+participation. Styled via the `btu-radio` Tailwind plugin classes. Typically
+placed inside a `btu-radio-group`, which owns the shared `name`, selection
+state, and arrow-key navigation; a standalone radio also works but manages
+only its own checked state. The component manages its own `className` — do not
+modify it externally after initialization (classes present at connection time
+are preserved).
+
+```js
+import '@brightspot/ui/components/radio/Radio.js'
+```
+
+Interactive examples: https://ui.brightspot.com/?path=/docs/components-radio--docs
+
+## Attributes
+
+| Attribute | Property | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `label` | `label` | `string \| undefined` |  | The text label displayed next to the radio. |
+| `description` | `description` | `string \| undefined` |  | Optional helper text displayed below the label. |
+| `size` | `size` | `'sm' \| 'md'` | `'sm'` | Controls the scale of the radio and associated typography. |
+| `checked` | `checked` | `boolean` | `false` | Whether this option is currently selected. |
+| `disabled` | `disabled` | `boolean` | `false` | If true, the radio is non-interactive and visually muted. |
+| `invalid` | `invalid` | `boolean` | `false` | If true, displays error styling on the radio. |
+| `error` | `error` | `string \| undefined` |  | Error message text displayed below the radio when validation fails. Setting this also activates error styling without needing to set invalid. |
+| `value` | `value` | `string \| undefined` |  | Value submitted with the form when this option is selected. |
+| `name` | `name` | `string \| undefined` |  | Name of the form control. Usually set by the parent `btu-radio-group` so every option in the group shares one name. |
+| `tooltip` | `tooltip` | `string` | `''` | Tooltip text content. Set to empty string to remove the tooltip. |
+| `tooltip-position` | `tooltipPosition` | `'top' \| 'bottom' \| 'left' \| 'right'` | `'top'` | Position relative to the host element. Auto-flips when constrained by the viewport. |
+| `tooltip-delay` | `tooltipDelay` | `number` | `300` | Show delay in milliseconds (hover trigger only). |
+| `tooltip-offset` | `tooltipOffset` | `'sm' \| 'md' \| 'lg' \| 'xl' \| null` | `null` | Gap between host and tooltip (sm=4px, md=8px, lg=12px, xl=16px). |
+| `tooltip-no-arrow` | `tooltipNoArrow` | `boolean` | `false` | Hide the arrow pseudo-element. |
+| `tooltip-trigger` | `tooltipTrigger` | `string` | `'hover focus'` | Space-separated trigger types: 'hover', 'focus', 'click'. |
+
+## Events
+
+| Event | Detail | Description |
+| --- | --- | --- |
+| `btu-radio-ready` |  | Fired after the radio is first rendered and initialized |
+| `btu-radio-change` | `{ checked: boolean; value: string }` | Fired when the user selects this option |
+
+## CSS custom properties
+
+| Property | Description |
+| --- | --- |
+| `--radio-color-primary` | Fill and border color when selected (default: oklch(var(--btu-theme-primary-700))) |
+| `--radio-color-border` | Border color in the unselected state (default: oklch(var(--btu-theme-gray-300))) |
+| `--radio-color-error` | Border and text color in the error state (default: oklch(var(--btu-theme-error-600))) |
+| `--radio-label-spacing` | Distance between the radio and the label (default: 0.75rem) |
+| `--radio-box-size` | [Internal] Diameter of the radio control, set by the size variant (sm: 1rem, md: 1.25rem). Use the `size` attribute instead of overriding directly — the dot must scale in tandem. |
+| `--radio-dot-size` | [Internal] Diameter of the selected dot, set by the size variant (sm: 0.375rem, md: 0.5rem). Use the `size` attribute instead of overriding directly. |

package/dist/storybook/docs/components/RadioGroup.md

@@ -0,0 +1,34 @@
+# `<btu-radio-group>`
+
+A container that groups `btu-radio` options into a single-select control.
+
+Owns the shared form `name`, the selected `value`, and keyboard navigation
+following the WAI-ARIA radio group pattern: a single roving tabstop, and
+arrow keys that move focus and select in one step. Selection state and the
+`disabled` / `size` properties are propagated down to child radios.
+
+```js
+import '@brightspot/ui/components/radio/RadioGroup.js'
+```
+
+Interactive examples: https://ui.brightspot.com/?path=/docs/components-radio-group--docs
+
+## Attributes
+
+| Attribute | Property | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `name` | `name` | `string \| undefined` |  | Form field name shared by every radio in the group. |
+| `value` | `value` | `string \| undefined` |  | Value of the currently selected option. |
+| `orientation` | `orientation` | `'vertical' \| 'horizontal'` | `'vertical'` | Layout direction of the options. |
+| `size` | `size` | `'sm' \| 'md'` | `'sm'` | Controls the scale of every radio in the group. |
+| `required` | `required` | `boolean` | `false` | Marks a selection as mandatory for form submission. |
+| `disabled` | `disabled` | `boolean` | `false` | Disables every option in the group. |
+
+## Events
+
+| Event | Detail | Description |
+| --- | --- | --- |
+| `btu-radio-group-ready` |  | Fired after first render and initialization |
+| `btu-radio-group-change` | `{ value: string }` | Fired when the selected value changes |
+| `btu-radio-ready` |  | Fired when a child radio finishes initialization (bubbles from btu-radio) |
+| `btu-radio-change` | `{ checked: boolean; value: string }` | Fired when a child radio is selected (bubbles from btu-radio) |

package/dist/storybook/docs/components/Switch.md

@@ -0,0 +1,48 @@
+# `<btu-switch>`
+
+A toggle switch component for binary on/off states.
+
+Uses a hidden checkbox internally for accessibility, styled via the
+`btu-switch` Tailwind plugin classes.
+
+```js
+import '@brightspot/ui/components/switch/Switch.js'
+```
+
+Interactive examples: https://ui.brightspot.com/?path=/docs/components-switch--docs
+
+## Attributes
+
+| Attribute | Property | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `size` | `size` | `'sm' \| 'md' \| 'lg'` | `'sm'` | Controls the physical dimensions of the switch and the associated label typography. |
+| `label` | `label` | `string \| undefined` |  | The primary text displayed next to the toggle. |
+| `description` | `description` | `string \| undefined` |  | Optional helper text or secondary information displayed below the label. |
+| `checked` | `checked` | `boolean` | `false` | The current state of the switch (on/off). |
+| `disabled` | `disabled` | `boolean` | `false` | If true, the toggle is non-interactive and visually muted. |
+| `name` | `name` | `string \| undefined` |  | Name of the control for form participation. |
+| `label-position` | `labelPosition` | `'start' \| 'end'` | `'end'` | Determines if the label appears to the left or right of the switch. |
+| `on-icon` | `onIcon` | `string \| undefined` |  | Lucide icon name shown on the track when the switch is checked (on). |
+| `off-icon` | `offIcon` | `string \| undefined` |  | Lucide icon name shown on the track when the switch is unchecked (off). |
+
+## Events
+
+| Event | Detail | Description |
+| --- | --- | --- |
+| `btu-switch-ready` |  | Fired after the toggle is first rendered and initialized |
+| `btu-switch-change` | `{ checked: boolean }` | Fired when the user toggles the switch |
+| `btu-switch-focus` |  | Fired when the component gains focus |
+
+## CSS custom properties
+
+| Property | Description |
+| --- | --- |
+| `--switch-color-track-on` | Background color when the toggle is checked (default: var(--btu-theme-primary-700)) |
+| `--switch-color-track-off` | Background color when the toggle is unchecked (default: var(--btu-theme-gray-300)) |
+| `--switch-color-knob` | Color of the sliding circular handle (default: var(--btu-theme-white)) |
+| `--switch-label-spacing` | Distance between the switch and the text label (default: 0.75rem) |
+| `--switch-track-width` | Track width (default: sm 1.75rem, md 2.25rem, lg 2.75rem) |
+| `--switch-track-height` | Track height (default: sm 1rem, md 1.25rem, lg 1.5rem) |
+| `--switch-knob-size` | Knob diameter (default: sm 0.75rem, md 1rem, lg 1.25rem) |
+| `--switch-knob-padding` | Space between knob and track edges (default: 0.125rem) |
+| `--switch-track-icon-size` | Size of the track icons (default: sm 0.5rem, md 0.625rem, lg 0.75rem) |

package/dist/storybook/docs/components/Tab.md

@@ -0,0 +1,40 @@
+# `<btu-tab>`
+
+An individual tab within a tab group.
+
+Renders a button with role="tab" that participates in keyboard navigation
+and selection state managed by the parent `btu-tabs` container.
+
+```js
+import '@brightspot/ui/components/tabs/Tab.js'
+```
+
+Interactive examples: https://ui.brightspot.com/?path=/docs/components-tabs-tab--docs
+
+## Attributes
+
+| Attribute | Property | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `name` | `name` | `string \| undefined` |  | Value that identifies this tab and links it to panel elements that share the same `name` attribute. |
+| `label` | `label` | `string \| undefined` |  | Text displayed in the tab. |
+| `description` | `description` | `string \| undefined` |  | Accessibility description for screen readers. |
+| `disabled` | `disabled` | `boolean` | `false` | Whether the tab is disabled and non-interactive. |
+| `symbol` | `symbol` | `string \| undefined` |  | Lucide icon symbol to display. |
+| `icon-position` | `iconPosition` | `'leading' \| 'trailing'` | `'leading'` | Placement of the icon relative to the label. |
+| `icon-only` | `iconOnly` | `boolean` | `false` | When true, hides the label visually while maintaining accessibility. |
+| `error` | `error` | `boolean` | `false` | When true, displays an error badge on the tab. |
+| `badge` | `badge` | `string \| undefined` |  | Displays a badge with the given value alongside the label. |
+
+## Events
+
+| Event | Detail | Description |
+| --- | --- | --- |
+| `btu-tab-ready` |  | Fired after first render |
+| `btu-tab-change` | `{name: string}` | Fired when a non-disabled tab with a name is clicked |
+
+## CSS custom properties
+
+| Property | Description |
+| --- | --- |
+| `--badge-color-background` | Background color of the count indicator badge (default: gray-50) |
+| `--badge-color-foreground` | Text color of the count indicator badge (default: gray-800) |

package/dist/storybook/docs/components/Tabs.md

@@ -0,0 +1,49 @@
+# `<btu-tabs>`
+
+A container component for managing a group of tabs.
+
+Provides selection state management, size propagation to child tabs,
+and keyboard navigation following the WAI-ARIA Tabs pattern.
+
+When a tab becomes active, direct sibling elements that share the same
+`name` value are shown; other siblings with a `name` attribute are
+hidden. Only direct siblings are managed — nested tab groups control their
+own panels independently.
+
+```js
+import '@brightspot/ui/components/tabs/Tabs.js'
+```
+
+Interactive examples: https://ui.brightspot.com/?path=/docs/components-tabs--docs
+
+## Attributes
+
+| Attribute | Property | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `size` | `size` | `'xs' \| 'sm' \| 'md' \| 'lg'` | `'md'` | Size variant applied to all child tabs. |
+| `active-tab` | `activeTab` | `string \| undefined` |  | The `name` value of the currently active tab. |
+| `variant` | `variant` | `'full' \| 'menu'` | `'full'` | Layout variant. - 'full': tabs scroll horizontally when they overflow (default) - 'menu': all tabs are hidden; the active tab label and a chevron dropdown are shown instead |
+
+## Events
+
+| Event | Detail | Description |
+| --- | --- | --- |
+| `btu-tabs-ready` |  | Fired after first render and initialization |
+| `btu-tabs-show` | `{name: string}` | Fired when a tab becomes active |
+| `btu-tabs-hide` | `{name: string}` | Fired when a tab is deactivated |
+| `btu-tab-change` | `{name: string}` | Fired when a tab is selected (bubbles from btu-tab) |
+| `btu-tab-ready` |  | Fired when a child tab finishes initialization (bubbles from btu-tab) |
+
+## CSS custom properties
+
+| Property | Description |
+| --- | --- |
+| `--tabs-active-color` | Text and icon color of the active tab (default: gray-700) |
+| `--tabs-active-indicator-color` | Color of the active tab underline indicator (default: primary-500 → primary-700 → primary-900 gradient) |
+| `--tabs-border-color` | Color of the bottom border divider (default: gray-200) |
+| `--tabs-color` | Text and icon color for all tabs (default: gray-500; active/hover tabs use gray-700) |
+| `--tabs-background` | Background color for all tab buttons (default: transparent) |
+| `--tabs-container-background` | Background color of the tabs container (default: theme white) |
+| `--tabs-hover-background` | Background color of a tab on hover (default: gray-100) |
+| `--tabs-hover-color` | Text and icon color of a tab on hover (default: gray-700) |
+| `--tabs-gap` | Spacing between tabs (default: 1rem) |

package/dist/storybook/docs/components/Upload.md

@@ -0,0 +1,63 @@
+# `<btu-upload>`
+
+A file upload component with drop zone and file list.
+
+The component is presentation + file-selection only. It handles file browsing,
+drag-and-drop reception, client-side validation, and rendering the file list
+with progress bars. It does not perform network requests — the consumer listens
+for events, performs their own upload, and drives state back via imperative methods.
+
+```js
+import '@brightspot/ui/components/upload/Upload.js'
+```
+
+Interactive examples: https://ui.brightspot.com/?path=/docs/components-upload--docs
+
+## Attributes
+
+| Attribute | Property | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `accept` | `accept` | `string` | `''` | Accepted file types, matching the HTML `<input accept>` attribute format. Client-side filter only — the browser's file picker uses this as a hint, and drag-drop is enforced by this component. Server-side validation is still required. Supported forms (comma-separated, any combination): - `image/*` — MIME wildcard (any image) - `application/pdf` — exact MIME type - `.pdf`, `.docx` — file extension (case-insensitive) Examples: - `accept="image/*"` — any image - `accept="image/*,application/pdf"` — images and PDFs - `accept=".jpg,.jpeg,.png,.heic"` — specific extensions - `accept=""` (or omitted) — allow all Note: users can bypass the file picker's filter (most browsers offer an "All Files" option), so this attribute is a UX filter, not a security boundary. |
+| `max-file-size` | `maxFileSize` | `number` | `0` | Maximum file size in bytes. Files exceeding this are rejected. 0 means unlimited. |
+| `max-files` | `maxFiles` | `number` | `Infinity` | Maximum number of files allowed. When omitted, uploads are unlimited. `max-files="1"` enters single-file mode (selecting a new file replaces the existing one). `max-files="0"` allows zero files. Values above 1 cap the queue at that many files. |
+| `disabled` | `disabled` | `boolean` | `false` | Disables all interaction — file selection, drag-and-drop, and action buttons. |
+| `no-drag` | `noDrag` | `boolean` | `false` | Disables drag-and-drop. File selection via click still works. |
+
+## Methods
+
+| Method | Description |
+| --- | --- |
+| `setFileProgress(id: string, percent: number): void` | Update the progress of a file upload. Clamps value to 0-100 and coerces non-finite inputs to 0. Announces milestones (25%, 50%, 75%) to screen readers; 100% completion is announced by setFileStatus('complete'). Status transitions: - `pending` → `uploading` (auto — first progress report starts the upload) - `uploading` → `uploading` (progress updates) - `error` → `error` (progress updates only; status is preserved so a stale late callback can't wipe the error UI. To recover from error, call `setFileStatus(id, 'uploading')` first, then report progress.) - `complete` → ignored (terminal state) |
+| `setFileStatus(id: string, status: FileStatusSettable, message?: string): void` | Set the status of a file. Valid statuses: 'uploading', 'complete', 'error'. For 'error' status, an optional message can be provided. Transitions from 'complete' are rejected (terminal state) — a late-resolving XHR cannot overwrite a prior success. Rejected calls emit `btu-upload-api-error` with reason: 'invalid-transition'. |
+| `setFileSymbol(id: string, symbol: string): void` | Override the icon symbol for a file. |
+| `removeFile(id: string): void` | Remove a file programmatically. Fires `btu-upload-file-removed`. |
+| `getFiles(): readonly FileState[]` | Get a snapshot of all current files and their states. States are readonly; mutations on the returned array's elements are ineffective. |
+
+## Events
+
+| Event | Detail | Description |
+| --- | --- | --- |
+| `btu-upload-ready` | `unknown` | Fired when the component has completed first render |
+| `btu-upload-file-added` | `{id: string, file: File}` | Fired when a file passes validation and is added |
+| `btu-upload-file-removed` | `{id: string, file: File}` | Fired when a file is removed (user action, programmatic, or on disconnect for in-flight uploads) |
+| `btu-upload-file-retry` | `{id: string, file: File}` | Fired when user clicks "Try again" on a failed upload |
+| `btu-upload-file-rejected` | `{file: File, reason: 'type' \| 'size' \| 'count'}` | Fired when a file fails client-side validation or the queue is full |
+| `btu-upload-file-completed` | `{id: string, file: File}` | Fired when a file's status transitions into 'complete' |
+| `btu-upload-api-error` | `{method: string, id: string, reason: 'unknown-id' \| 'invalid-transition', message: string}` | Fired when an imperative API call references an unknown id or an illegal status transition |
+
+## CSS custom properties
+
+| Property | Description |
+| --- | --- |
+| `--upload-dropzone-bg` | Drop zone background color (default: gray-25) |
+| `--upload-dropzone-border-color` | Drop zone border color (default: gray-300; gray-200 when disabled, gray-400 in high-contrast) |
+| `--upload-dropzone-border-radius` | Drop zone border radius (default: borderRadius.lg) |
+| `--upload-dropzone-hover-bg` | Drop zone hover background (hover default: gray-50; drag-over default: primary-25) |
+| `--upload-dropzone-hover-border-color` | Drop zone hover/focus border color (default: primary-300; drag-over uses primary-400) |
+| `--upload-dropzone-focus-ring-color` | Drop zone focus ring color (default: primary-100) |
+| `--upload-item-bg` | Item background color (default: white) |
+| `--upload-item-border-color` | Item border color (default: gray-200) |
+| `--upload-item-active-border-color` | Item active/in-progress border (default: gray-300) |
+| `--upload-item-complete-border-color` | Item completed border color (default: primary-500) |
+| `--upload-item-error-bg` | Item error background (default: error-25) |
+| `--upload-item-error-border-color` | Item error border color (default: error-300) |

package/dist/storybook/docs/components/UploadItem.md

@@ -0,0 +1,30 @@
+# `<btu-upload-item>`
+
+Internal upload item sub-component for displaying individual file upload state.
+
+This component is not part of the public API — consumers should not create,
+query, or modify items directly. All interaction goes through `btu-upload` methods.
+
+```js
+import '@brightspot/ui/components/upload/UploadItem.js'
+```
+
+Interactive examples: https://ui.brightspot.com/?path=/docs/components-upload-upload-item--docs
+
+## Events
+
+| Event | Detail | Description |
+| --- | --- | --- |
+| `btu-upload-item-remove` | `{id: string}` | Fired when remove button is clicked |
+| `btu-upload-item-retry` | `{id: string}` | Fired when retry link is clicked |
+
+## CSS custom properties
+
+| Property | Description |
+| --- | --- |
+| `--upload-item-bg` | Item background color (default: white) |
+| `--upload-item-border-color` | Item border color (default: gray-200) |
+| `--upload-item-active-border-color` | Item active/in-progress border (default: gray-300) |
+| `--upload-item-complete-border-color` | Item completed border color (default: primary-500) |
+| `--upload-item-error-bg` | Item error background (default: error-25) |
+| `--upload-item-error-border-color` | Item error border color (default: error-300) |

package/dist/storybook/docs/components/Widget.md

@@ -0,0 +1,88 @@
+# `<btu-widget>`
+
+A widget component for displaying content with header, body, and footer sections.
+
+## Architecture: Light DOM + Manager Pattern
+
+This component uses **Light DOM** (no Shadow Root) with the **Manager Pattern**:
+- User-provided children are physically moved into internal containers
+- Movement is based on `slot` attributes (pseudo-slots)
+- The `onFind` utility automatically redistributes dynamically-added content
+
+### Node Redistribution Rules
+- `slot="controls"` → Moved to header actions area (before system buttons)
+- `slot="footer"` → Moved to footer container
+- *(no slot)* → Moved to body container (default)
+
+## Features
+
+- **Collapsible**: Optional chevron toggle to hide/show body and footer
+- **Fullscreen**: Optional maximize button for fullscreen mode via `:state(fullscreen)` custom state
+- **Dynamic Content**: `onFind` handles content added after initialization
+- **Accessible**: Full ARIA support and keyboard navigation
+- **Themeable**: CSS custom properties for colors and spacing
+
+## Accessibility
+
+- **Collapse toggle**: `aria-expanded`, `aria-controls`, `aria-label`
+- **Fullscreen toggle**: `aria-pressed`, `aria-label`
+- **Body region**: `role="region"`, `aria-labelledby` linking to heading
+- **Tab order**: Natural flow via physical DOM placement
+- **Collapsed content**: Hidden via `inert` attribute and CSS grid collapse
+
+```js
+import '@brightspot/ui/components/widget/Widget.js'
+```
+
+The CMS page defines this element itself, so a plugin can use it there without the import.
+
+Interactive examples: https://ui.brightspot.com/?path=/docs/components-widget--docs
+
+## Attributes
+
+| Attribute | Property | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `heading` | `heading` | `string` | `''` | Heading text displayed in the header. |
+| `collapsible` | `collapsible` | `boolean` | `false` | Whether the widget can be collapsed/expanded. When true, a chevron toggle button appears in the header. |
+| `collapsed` | `collapsed` | `boolean` | `false` | Whether the widget is currently collapsed. When true, body and footer are hidden. Implies collapsible. |
+| `fullscreenable` | `fullscreenable` | `boolean` | `false` | Whether the widget can enter fullscreen mode. When true, a fullscreen toggle button appears in the header. |
+
+## Properties
+
+These have no attribute; set them from JavaScript.
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `isFullscreen` (read-only) | `boolean` |  | Whether the widget is currently in fullscreen mode (read-only). Use `btu-widget-fullscreen-changed` event to react to changes. |
+
+## Events
+
+| Event | Detail | Description |
+| --- | --- | --- |
+| `btu-widget-ready` |  | Fired after first render and redistribution |
+| `btu-widget-collapse-changed` | `{collapsed: boolean}` | Fired when collapsed state changes |
+| `btu-widget-fullscreen-changed` | `{fullscreen: boolean}` | Fired when fullscreen state changes |
+
+## Slots
+
+| Slot | Description |
+| --- | --- |
+| (default) | Default pseudo-slot: elements without slot attribute are moved to body |
+| `controls` | Pseudo-slot: buttons/actions moved to header actions area |
+| `footer` | Pseudo-slot: content moved to footer container |
+
+## CSS custom properties
+
+| Property | Description |
+| --- | --- |
+| `--widget-background` | Body and footer background color (default: --btu-theme-white) |
+| `--widget-border` | Widget border and dividers (default: 1px solid gray-200) |
+| `--widget-border-color` | Color of header bottom divider (default: gray-200) |
+| `--header-background` | Header background color (default: transparent) |
+
+## CSS states
+
+| State | Description |
+| --- | --- |
+| `:state(collapsed)` | Applied when the widget is collapsed, targetable via :state(collapsed) |
+| `:state(fullscreen)` | Applied when the widget is in fullscreen mode, targetable via :state(fullscreen) |

package/dist/storybook/docs/dari-elements.md

@@ -0,0 +1,55 @@
+# Dari HTML elements
+
+`com.brightspot.ui.dari` contains generated Java classes for the `btu-*` web components, one class per element,
+so Java code in Brightspot and in plugins can render them with typed attribute setters instead of raw HTML strings.
+The classes are generated from the same [Custom Elements Manifest](components/README.md) used for the component API
+reference, and compile into the `com.brightspot.ui:ui` jar.
+
+The `BrightspotUi` interface holds one constant per element, named from its tag—for example `BrightspotUi#BADGE`
+for `<btu-badge>`. Each constant is an instance of the generated class, so chaining an element's own setters with
+inherited ones (`classList`, `attr`, `with`, and the rest of `com.psddev.dari.html`) compiles in any order:
+
+```java
+import static com.brightspot.ui.dari.BrightspotUi.BADGE;
+
+BADGE.classList("Page-env").variant("success").dot(true).with("QA")
+// <btu-badge class="Page-env" variant="success" dot>QA</btu-badge>
+```
+
+Rendering a constant emits only the tag—the page must also load the component, or the element stays inert. On a
+CMS page, import it in the plugin's front-end entry, the same as for any other element not defined by the CMS. See
+[Using these in a plugin](components/README.md#using-these-in-a-plugin) for which elements the CMS already defines.
+
+Nest content, including other elements, with `with`:
+
+```java
+import static com.brightspot.ui.dari.BrightspotUi.CARD;
+import static com.brightspot.ui.dari.BrightspotUi.BADGE;
+
+CARD.heading("Release notes").headingLevel(3).with(BADGE.with("New"))
+// <btu-card heading="Release notes" heading-level="3"><btu-badge>New</btu-badge></btu-card>
+```
+
+## Setter types
+
+Each generated setter's parameter type follows the element's CEM attribute type:
+
+| CEM type | Java parameter | Behavior |
+|---|---|---|
+| `boolean` | `boolean` | Emits a bare attribute (for example `dot`) when `true`, omits it when `false`. |
+| `number` | `Number` | Emits the attribute set to the number's string form. |
+| anything else, including unions like `boolean \| 'pulse'` | `String` | Emits the attribute set to the string value. |
+
+A handful of boolean attributes default to `true` in the component itself, such as `indeterminate` on
+`<btu-circular-progress>`. Because an HTML boolean attribute can only be present or absent, calling the setter with
+`false` has no effect—there is no way to represent "explicitly false" in the markup, so the component falls back to
+its own default.
+
+## Icon, widget, and copy-to-clipboard
+
+`ICON`, `WIDGET`, and `COPY_TO_CLIPBOARD` render the library elements, which the CMS defines. For a gradient icon, use
+`ICON.gradient("primary")`—the library icon has no `fill` attribute.
+
+`com.psddev.cms.ui.Components` also has `ICON` and `WIDGET` constants. A class that statically imports both
+`Components.*` and `BrightspotUi.*` gets an ambiguous-name compile error, so import `BrightspotUi` constants by name,
+as in the examples above.

package/dist/storybook/iframe.html

@@ -613,7 +613,7 @@
   }
 </style>
 
-    <script type="module" crossorigin src="./assets/iframe-Byo_x5o2.js"></script>
+    <script type="module" crossorigin src="./assets/iframe-DlBK9Drk.js"></script>
     <link rel="modulepreload" crossorigin href="./assets/preload-helper-PPVm8Dsz.js">
     <link rel="stylesheet" crossorigin href="./assets/iframe-BzrT7trF.css">
   </head>

package/dist/storybook/index.html

@@ -3,7 +3,7 @@
   <head>
     <meta charset="utf-8" />
 
-    <title>storybook - Storybook</title>
+    <title>Brightspot UI components - Storybook</title>
     <meta name="viewport" content="width=device-width, initial-scale=1" />
 
     
@@ -53,7 +53,22 @@
     <link href="./sb-addons/vitest-2/manager-bundle.js" rel="modulepreload" />
     
     <link href="./sb-addons/storybook-3/manager-bundle.js" rel="modulepreload" />
-      <link rel="icon" type="image/svg+xml" href="./BSPLogoMark.svg" />
+      <!--
+  Keep these above the no-JS paragraph: anything after it lands in <body>.
+  No og:url or canonical, because every page shares this one HTML file.
+-->
+<meta
+  name="description"
+  content="Web components, a Tailwind CSS preset and design tokens for Brightspot CMS screens and plugins, with live examples."
+/>
+<meta property="og:type" content="website" />
+<meta property="og:site_name" content="Brightspot UI" />
+<meta property="og:title" content="Brightspot UI components" />
+<meta
+  property="og:description"
+  content="Web components, a Tailwind CSS preset and design tokens for Brightspot CMS screens and plugins, with live examples."
+/>
+<link rel="icon" type="image/svg+xml" href="./BSPLogoMark.svg" />
 <style>
   /* Must match brandImage in theme.ts. */
   img[src='./brightspot-logo.svg'] {
@@ -91,6 +106,18 @@
     }
   }
 </style>
+<link rel="describedby" href="./llms.txt" type="text/markdown" />
+<!--
+  Shown only without JavaScript, which is also how agents fetch the page. A paragraph survives their HTML-to-markdown
+  conversion (the parser moves it into <body>), where meta tags and <noscript> don't.
+-->
+<p id="no-js">
+  This site needs JavaScript. The component docs are also available as markdown:
+  <a href="./llms.txt">https://ui.brightspot.com/llms.txt</a>
+</p>
+<script>
+  document.getElementById('no-js').remove()
+</script>
  
 
     <style>