@brightspot/ui 1.11.0 → 3.0.1-cms-ui-migration.0

package/docs/components/Popover.md

@@ -34,6 +34,12 @@
 | `_onNativeToggle`      | private |                                          |            |                                                                                                                                                             |                |
 | `_onKeyDown`           | private |                                          |            |                                                                                                                                                             |                |
 
+### 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 |
@@ -54,6 +60,16 @@
 | `panel-label` | panelLabel |                |
 | `no-arrow`    | noArrow    |                |
 
+### CSS Properties
+
+| Name                         | Default | Description                                                                           |
+| ---------------------------- | ------- | ------------------------------------------------------------------------------------- |
+| `--popover-color-background` |         | Panel background color (default: var(--btu-theme-white))                              |
+| `--popover-color-content`    |         | Panel text color (default: oklch(var(--btu-theme-gray-900)))                          |
+| `--popover-border-radius`    |         | Panel corner radius (default: theme borderRadius.lg)                                  |
+| `--popover-offset`           |         | Gap between trigger and panel (default: 8px; see btu-popover-offset-{sm\|md\|lg\|xl}) |
+| `--popover-arrow-size`       |         | Width/height of the pointer arrow (default: 8px)                                      |
+
 ### Slots
 
 | Name      | Description                                          |

package/docs/components/README.md

@@ -9,11 +9,14 @@ This directory contains auto-generated API documentation for all Brightspot UI w
 - [`<btu-avatar>` - Avatar](Avatar.md)
 - [`<btu-avatar-group>` - AvatarGroup](AvatarGroup.md)
 - [`<btu-badge>` - Badge](Badge.md)
+- [`<btu-button-group>` - ButtonGroup](ButtonGroup.md)
+- [`<btu-checkbox>` - Checkbox](Checkbox.md)
 - [`<btu-circular-progress>` - CircularProgress](CircularProgress.md)
 - [`<btu-copy-to-clipboard>` - CopyToClipboard](CopyToClipboard.md)
 - [`<btu-dropdown>` - Dropdown](Dropdown.md)
 - [`<btu-dropdown-item>` - DropdownItem](DropdownItem.md)
 - [`<btu-dropdown-menu>` - DropdownMenu](DropdownMenu.md)
+- [`<btu-empty-state>` - EmptyState](EmptyState.md)
 - [`<btu-icon>` - Icon](Icon.md)
 - [`<btu-icon-button>` - IconButton](IconButton.md)
 - [`<btu-linear-progress>` - LinearProgress](LinearProgress.md)
@@ -22,6 +25,8 @@ This directory contains auto-generated API documentation for all Brightspot UI w
 - [`<btu-switch>` - Switch](Switch.md)
 - [`<btu-tab>` - Tab](Tab.md)
 - [`<btu-tabs>` - Tabs](Tabs.md)
+- [`<btu-upload>` - Upload](Upload.md)
+- [`<btu-upload-item>` - UploadItem](UploadItem.md)
 - [`<btu-widget>` - Widget](Widget.md)
 
 ---

package/docs/components/Switch.md

@@ -17,25 +17,26 @@
 
 ### Fields
 
-| Name            | Privacy | Type                             | Default   | Description                                                                         | Inherited From |
-| --------------- | ------- | -------------------------------- | --------- | ----------------------------------------------------------------------------------- | -------------- |
-| `size`          |         | `'small' \| 'medium' \| 'large'` | `'small'` | Controls the physical dimensions of the switch and the associated label typography. |                |
-| `label`         |         | `string \| undefined`            |           | The primary text displayed next to the toggle.                                      |                |
-| `description`   |         | `string \| undefined`            |           | Optional helper text or secondary information displayed below the label.            |                |
-| `checked`       |         | `boolean`                        | `false`   | The current state of the switch (on/off).                                           |                |
-| `disabled`      |         | `boolean`                        | `false`   | If true, the toggle is non-interactive and visually muted.                          |                |
-| `name`          |         | `string \| undefined`            |           | Name of the control for form participation.                                         |                |
-| `labelPosition` |         | `'start' \| 'end'`               | `'end'`   | Determines if the label appears to the left or right of the switch.                 |                |
-| `onIcon`        |         | `string \| undefined`            |           | Lucide icon name shown on the track when the switch is checked (on).                |                |
-| `offIcon`       |         | `string \| undefined`            |           | Lucide icon name shown on the track when the switch is unchecked (off).             |                |
+| Name            | Privacy | Type                   | Default | Description                                                                         | Inherited From |
+| --------------- | ------- | ---------------------- | ------- | ----------------------------------------------------------------------------------- | -------------- |
+| `size`          |         | `'sm' \| 'md' \| 'lg'` | `'sm'`  | Controls the physical dimensions of the switch and the associated label typography. |                |
+| `label`         |         | `string \| undefined`  |         | The primary text displayed next to the toggle.                                      |                |
+| `description`   |         | `string \| undefined`  |         | Optional helper text or secondary information displayed below the label.            |                |
+| `checked`       |         | `boolean`              | `false` | The current state of the switch (on/off).                                           |                |
+| `disabled`      |         | `boolean`              | `false` | If true, the toggle is non-interactive and visually muted.                          |                |
+| `name`          |         | `string \| undefined`  |         | Name of the control for form participation.                                         |                |
+| `labelPosition` |         | `'start' \| 'end'`     | `'end'` | Determines if the label appears to the left or right of the switch.                 |                |
+| `onIcon`        |         | `string \| undefined`  |         | Lucide icon name shown on the track when the switch is checked (on).                |                |
+| `offIcon`       |         | `string \| undefined`  |         | Lucide icon name shown on the track when the switch is unchecked (off).             |                |
 
 ### Methods
 
-| Name             | Privacy | Description | Parameters | Return | Inherited From |
-| ---------------- | ------- | ----------- | ---------- | ------ | -------------- |
-| `_onInputChange` | private |             | `e: Event` | `void` |                |
-| `_onFocus`       | private |             |            | `void` |                |
-| `_toggleInput`   | private |             |            | `void` |                |
+| Name             | Privacy | Description                                                                                                                                                                                                                                                                        | Parameters                                              | Return    | Inherited From    |
+| ---------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | --------- | ----------------- |
+| `_onInputChange` | private |                                                                                                                                                                                                                                                                                    | `e: Event`                                              | `void`    |                   |
+| `_onFocus`       | private |                                                                                                                                                                                                                                                                                    |                                                         | `void`    |                   |
+| `_toggleInput`   | private |                                                                                                                                                                                                                                                                                    |                                                         | `void`    |                   |
+| `emit`           |         | Dispatches a type-safe CustomEvent with standardized configuration.&#xA;&#xA;All events are configured with:&#xA;- bubbles: true (event propagates up the DOM tree)&#xA;- cancelable: false (event cannot be cancelled)&#xA;- composed: true (event crosses shadow DOM boundaries) | `type: K, detail: UnpackCustomEvent<CustomEventMap[K]>` | `boolean` | EventEmitterMixin |
 
 ### Events
 
@@ -67,6 +68,10 @@
 | `--switch-color-track-off` |         | Background color when the toggle is unchecked (default: var(--btu-theme-gray-300))  |
 | `--switch-color-knob`      |         | Color of the sliding circular handle (default: var(--btu-theme-white))              |
 | `--switch-label-spacing`   |         | Distance between the switch and the text label (default: 0.75rem)                   |
+| `--switch-track-width`     |         | Track width (default: sm 1.75rem, md 2.25rem, lg 2.75rem)                           |
+| `--switch-track-height`    |         | Track height (default: sm 1rem, md 1.25rem, lg 1.5rem)                              |
+| `--switch-knob-size`       |         | Knob diameter (default: sm 0.75rem, md 1rem, lg 1.25rem)                            |
+| `--switch-knob-padding`    |         | Space between knob and track edges (default: 0.125rem)                              |
 | `--switch-track-icon-size` |         | Size of the track icons (default: sm 0.5rem, md 0.625rem, lg 0.75rem)               |
 
 <hr/>

package/docs/components/Tab.md

@@ -29,12 +29,18 @@
 | `label`        |         | `string \| undefined`     |             | Text displayed in the tab.                                                                            |                |
 | `description`  |         | `string \| undefined`     |             | Accessibility description for screen readers.                                                         |                |
 | `disabled`     |         | `boolean`                 | `false`     | Whether the tab is disabled and non-interactive.                                                      |                |
-| `iconName`     |         | `string \| undefined`     |             | Lucide icon name to display.                                                                          |                |
+| `symbol`       |         | `string \| undefined`     |             | Lucide icon symbol to display.                                                                        |                |
 | `iconPosition` |         | `'leading' \| 'trailing'` | `'leading'` | Placement of the icon relative to the label.                                                          |                |
 | `iconOnly`     |         | `boolean`                 | `false`     | When true, hides the label visually while maintaining accessibility.                                  |                |
 | `error`        |         | `boolean`                 | `false`     | When true, displays an error badge on the tab.                                                        |                |
 | `badge`        |         | `string \| undefined`     |             | Displays a badge with the given value alongside the label.                                            |                |
 
+### 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 |
@@ -50,7 +56,7 @@
 | `label`         | label        |                |
 | `description`   | description  |                |
 | `disabled`      | disabled     |                |
-| `icon-name`     | iconName     |                |
+| `symbol`        | symbol       |                |
 | `icon-position` | iconPosition |                |
 | `icon-only`     | iconOnly     |                |
 | `error`         | error        |                |

package/docs/components/Tabs.md

@@ -34,6 +34,14 @@
 | `menuLabel`      | private | `HTMLSpanElement \| null`      | `null`   |                                                                                                                                                                                      |                |
 | `menuIcon`       | private | `HTMLElement \| null`          | `null`   |                                                                                                                                                                                      |                |
 | `menuErrorBadge` | private | `HTMLElement \| null`          | `null`   |                                                                                                                                                                                      |                |
+| `_dropdownSize`  | private | `'sm' \| 'md' \| 'lg'`         |          |                                                                                                                                                                                      |                |
+| `_menuIconSize`  | private | `'sm' \| 'md'`                 |          |                                                                                                                                                                                      |                |
+
+### Methods
+
+| Name   | Privacy | Description                                                                                                                                                                                                                                                                        | Parameters                                              | Return    | Inherited From    |
+| ------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | --------- | ----------------- |
+| `emit` |         | Dispatches a type-safe CustomEvent with standardized configuration.&#xA;&#xA;All events are configured with:&#xA;- bubbles: true (event propagates up the DOM tree)&#xA;- cancelable: false (event cannot be cancelled)&#xA;- composed: true (event crosses shadow DOM boundaries) | `type: K, detail: UnpackCustomEvent<CustomEventMap[K]>` | `boolean` | EventEmitterMixin |
 
 ### Events
 

package/docs/components/Upload.md

@@ -0,0 +1,112 @@
+# `src/components/upload/Upload.ts`:
+
+## class: `Upload`, `btu-upload`
+
+### 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 |
+| --------------------- | ------- | -------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- |
+| `accept`              |         | `string`                   | `''`        | Accepted file types, matching the HTML \`\<input accept>\` attribute format.&#xA;Client-side filter only — the browser's file picker uses this as a hint,&#xA;and drag-drop is enforced by this component. Server-side validation is&#xA;still required.&#xA;&#xA;Supported forms (comma-separated, any combination):&#xA;- \`image/\*\` — MIME wildcard (any image)&#xA;- \`application/pdf\` — exact MIME type&#xA;- \`.pdf\`, \`.docx\` — file extension (case-insensitive)&#xA;&#xA;Examples:&#xA;- \`accept="image/\*"\` — any image&#xA;- \`accept="image/\*,application/pdf"\` — images and PDFs&#xA;- \`accept=".jpg,.jpeg,.png,.heic"\` — specific extensions&#xA;- \`accept=""\` (or omitted) — allow all&#xA;&#xA;Note: users can bypass the file picker's filter (most browsers offer an&#xA;"All Files" option), so this attribute is a UX filter, not a security&#xA;boundary. |                |
+| `maxFileSize`         |         | `number`                   | `0`         | Maximum file size in bytes. Files exceeding this are rejected. 0 means unlimited.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |                |
+| `maxFiles`            |         | `number`                   | `Infinity`  | Maximum number of files allowed. When omitted, uploads are unlimited.&#xA;\`max-files="1"\` enters single-file mode (selecting a new file replaces the existing one).&#xA;\`max-files="0"\` allows zero files. Values above 1 cap the queue at that many files.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |                |
+| `disabled`            |         | `boolean`                  | `false`     | Disables all interaction — file selection, drag-and-drop, and action buttons.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |                |
+| `noDrag`              |         | `boolean`                  | `false`     | Disables drag-and-drop. File selection via click still works.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |                |
+| `_files`              | private | `Map<string, FileState>`   | `new Map()` |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |                |
+| `_items`              | private | `Map<string, UploadItem>`  | `new Map()` |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |                |
+| `_milestones`         | private | `Map<string, Set<number>>` | `new Map()` |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |                |
+| `_dragOver`           | private | `boolean`                  | `false`     |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |                |
+| `_dragCounter`        | private | `number`                   | `0`         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |                |
+| `_inputEl`            | private | `HTMLInputElement \| null` |             |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |                |
+| `_dropzoneFull`       | private | `boolean`                  |             |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |                |
+| `_interactionBlocked` | private | `boolean`                  |             |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |                |
+| `_showCountPill`      | private | `boolean`                  |             |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |                |
+
+### Methods
+
+| Name                   | Privacy | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Parameters                                                | Return                 | Inherited From    |
+| ---------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- | ---------------------- | ----------------- |
+| `_handleInputChange`   | private |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `e: Event`                                                | `void`                 |                   |
+| `_handleSelectClick`   | private |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `e: Event`                                                | `void`                 |                   |
+| `_handleDropzoneClick` | private |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |                                                           | `void`                 |                   |
+| `_handleDragEnter`     | private |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `e: DragEvent`                                            | `void`                 |                   |
+| `_handleDragOver`      | private |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `e: DragEvent`                                            | `void`                 |                   |
+| `_handleDragLeave`     | private |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `e: DragEvent`                                            | `void`                 |                   |
+| `_handleDrop`          | private |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `e: DragEvent`                                            | `void`                 |                   |
+| `_processFiles`        | private |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `files: File[]`                                           | `void`                 |                   |
+| `_rejectCount`         | private |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `file: File`                                              | `void`                 |                   |
+| `_validateFile`        | private |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `file: File`                                              | `boolean`              |                   |
+| `_addFile`             | private |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `file: File`                                              | `void`                 |                   |
+| `_reportUnknownId`     | private |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `method: ApiMethod, id: string`                           | `void`                 |                   |
+| `_getOrReport`         | private |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `method: ApiMethod, id: string`                           | `FileState \| null`    |                   |
+| `_renderItem`          | private |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `fileState: FileState`                                    | `void`                 |                   |
+| `setFileProgress`      |         | Update the progress of a file upload.&#xA;Clamps value to 0-100 and coerces non-finite inputs to 0. Announces milestones&#xA;(25%, 50%, 75%) to screen readers; 100% completion is announced by setFileStatus('complete').&#xA;&#xA;Status transitions:&#xA;- \`pending\` → \`uploading\` (auto — first progress report starts the upload)&#xA;- \`uploading\` → \`uploading\` (progress updates)&#xA;- \`error\` → \`error\` (progress updates only; status is preserved so a stale late&#xA;  callback can't wipe the error UI. To recover from error, call&#xA;  \`setFileStatus(id, 'uploading')\` first, then report progress.)&#xA;- \`complete\` → ignored (terminal state) | `id: string, percent: number`                             | `void`                 |                   |
+| `setFileStatus`        |         | Set the status of a file.&#xA;Valid statuses: 'uploading', 'complete', 'error'. For 'error' status, an&#xA;optional message can be provided.&#xA;&#xA;Transitions from 'complete' are rejected (terminal state) — a late-resolving&#xA;XHR cannot overwrite a prior success. Rejected calls emit \`btu-upload-api-error\`&#xA;with reason: 'invalid-transition'.                                                                                                                                                                                                                                                                                                                   | `id: string, status: FileStatusSettable, message: string` | `void`                 |                   |
+| `setFileSymbol`        |         | Override the icon symbol for a file.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | `id: string, symbol: string`                              | `void`                 |                   |
+| `removeFile`           |         | Remove a file programmatically. Fires \`btu-upload-file-removed\`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `id: string`                                              | `void`                 |                   |
+| `getFiles`             |         | Get a snapshot of all current files and their states.&#xA;States are readonly; mutations on the returned array's elements are ineffective.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |                                                           | `readonly FileState[]` |                   |
+| `_renderSelectButton`  | private |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `text: 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-upload-ready`          | `CustomEvent<unknown>`                                                                                     | Fired when the component has completed first render                                              |                |
+| `btu-upload-file-added`     | `CustomEvent<{id: string, file: File}>`                                                                    | Fired when a file passes validation and is added                                                 |                |
+| `btu-upload-file-removed`   | `CustomEvent<{id: string, file: File}>`                                                                    | Fired when a file is removed (user action, programmatic, or on disconnect for in-flight uploads) |                |
+| `btu-upload-file-retry`     | `CustomEvent<{id: string, file: File}>`                                                                    | Fired when user clicks "Try again" on a failed upload                                            |                |
+| `btu-upload-file-rejected`  | `CustomEvent<{file: File, reason: 'type' \| 'size' \| 'count'}>`                                           | Fired when a file fails client-side validation or the queue is full                              |                |
+| `btu-upload-file-completed` | `CustomEvent<{id: string, file: File}>`                                                                    | Fired when a file's status transitions into 'complete'                                           |                |
+| `btu-upload-api-error`      | `CustomEvent<{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       |                |
+
+### Attributes
+
+| Name            | Field       | Inherited From |
+| --------------- | ----------- | -------------- |
+| `accept`        | accept      |                |
+| `max-file-size` | maxFileSize |                |
+| `max-files`     | maxFiles    |                |
+| `disabled`      | disabled    |                |
+| `no-drag`       | noDrag      |                |
+
+### CSS Properties
+
+| Name                                   | Default | 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)                                                  |
+
+<hr/>
+
+## Exports
+
+| Kind                        | Name                 | Declaration        | Module                          | Package |
+| --------------------------- | -------------------- | ------------------ | ------------------------------- | ------- |
+| `js`                        | `FileState`          | FileState          | src/components/upload/Upload.ts |         |
+| `js`                        | `FileStatus`         | FileStatus         | src/components/upload/Upload.ts |         |
+| `js`                        | `FileStatusSettable` | FileStatusSettable | src/components/upload/Upload.ts |         |
+| `js`                        | `default`            | Upload             | src/components/upload/Upload.ts |         |
+| `custom-element-definition` | `btu-upload`         | Upload             | src/components/upload/Upload.ts |         |

package/docs/components/UploadItem.md

@@ -0,0 +1,61 @@
+# `src/components/upload/UploadItem.ts`:
+
+## class: `UploadItem`, `btu-upload-item`
+
+### Superclass
+
+| Name         | Module | Package |
+| ------------ | ------ | ------- |
+| `LitElement` |        | lit     |
+
+### Mixins
+
+| Name                | Module                         | Package |
+| ------------------- | ------------------------------ | ------- |
+| `EventEmitterMixin` | /src/util/EventEmitterMixin.js |         |
+| `ReadyMixin`        | /src/util/ReadyMixin.js        |         |
+
+### Fields
+
+| Name                    | Privacy | Type                 | Default | Description | Inherited From |
+| ----------------------- | ------- | -------------------- | ------- | ----------- | -------------- |
+| `_state`                | private | `FileState \| null`  | `null`  |             |                |
+| `_baseClasses`          | private | `string`             | `''`    |             |                |
+| `_previousStatus`       | private | `FileStatus \| null` | `null`  |             |                |
+| `_stopProgressComplete` | private |                      |         |             |                |
+
+### Methods
+
+| Name                 | Privacy | Description                                                                                                                                                                                                                                                                        | Parameters                                              | Return    | Inherited From    |
+| -------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | --------- | ----------------- |
+| `_scheduleCelebrate` | private |                                                                                                                                                                                                                                                                                    |                                                         | `void`    |                   |
+| `_handleRemove`      | private |                                                                                                                                                                                                                                                                                    |                                                         | `void`    |                   |
+| `_handleRetry`       | private |                                                                                                                                                                                                                                                                                    |                                                         | `void`    |                   |
+| `emit`               |         | Dispatches a type-safe CustomEvent with standardized configuration.&#xA;&#xA;All events are configured with:&#xA;- bubbles: true (event propagates up the DOM tree)&#xA;- cancelable: false (event cannot be cancelled)&#xA;- composed: true (event crosses shadow DOM boundaries) | `type: K, detail: UnpackCustomEvent<CustomEventMap[K]>` | `boolean` | EventEmitterMixin |
+
+### Events
+
+| Name                     | Type                        | Description                         | Inherited From |
+| ------------------------ | --------------------------- | ----------------------------------- | -------------- |
+| `btu-upload-item-remove` | `CustomEvent<{id: string}>` | Fired when remove button is clicked |                |
+| `btu-upload-item-retry`  | `CustomEvent<{id: string}>` | Fired when retry link is clicked    |                |
+
+### CSS Properties
+
+| Name                                  | Default | 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)       |
+
+<hr/>
+
+## Exports
+
+| Kind                        | Name              | Declaration | Module                              | Package |
+| --------------------------- | ----------------- | ----------- | ----------------------------------- | ------- |
+| `js`                        | `default`         | UploadItem  | src/components/upload/UploadItem.ts |         |
+| `custom-element-definition` | `btu-upload-item` | UploadItem  | src/components/upload/UploadItem.ts |         |

package/docs/components/Widget.md

@@ -35,6 +35,12 @@
 | `_fullscreenTooltip` | private |           | `new TooltipController(this, { target: 'button[data-tooltip="fullscreen"]', text: () => (this._isFullscreen ? 'Exit fullscreen' : 'Enter fullscreen'), position: 'bottom', noArrow: true, offset: 'sm', })` |                                                                                                                                      |                |
 | `isFullscreen`       |         | `boolean` |                                                                                                                                                                                                             | Whether the widget is currently in fullscreen mode (read-only).
Use \`btu-widget-fullscreen-changed\` event to react to changes. |                |
 
+### 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 |
@@ -51,15 +57,15 @@
 | `collapsible`    | collapsible    |                |
 | `collapsed`      | collapsed      |                |
 | `fullscreenable` | fullscreenable |                |
-| `id`             |                |                |
 
 ### CSS Properties
 
-| Name                  | Default | Description                                                   |
-| --------------------- | ------- | ------------------------------------------------------------- |
-| `--widget-background` |         | Body and footer background color (default: --btu-theme-white) |
-| `--widget-border`     |         | Widget border and dividers (default: 1px solid gray-200)      |
-| `--header-background` |         | Header background color (default: transparent)                |
+| Name                    | Default | 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)                |
 
 ### Slots
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brightspot/ui",
-  "version": "1.11.0",
+  "version": "3.0.1-cms-ui-migration.0",
   "type": "module",
   "license": "UNLICENSED",
   "description": "A UI library for building Brightspot CMS components.",
@@ -21,11 +21,14 @@
     "cem:watch": "cem analyze --litelement --watch",
     "cem:docs": "yarn cem && node scripts/generate-docs.mjs",
     "build": "yarn clean && tsc --noEmitOnError && yarn cem && node scripts/copy-component-css.mjs && shx cp ./src/*.ts ./dist && shx rm ./dist/tailwind.storybook.config* && shx rm -Rf ./dist/stories",
-    "prepack": "yarn build && yarn build-storybook",
+    "prepack": "yarn build && yarn build-storybook && (cd src/legacy/tool-ui && yarn build)",
     "storybook": "yarn cem && storybook dev -p 6006",
     "build-storybook": "yarn cem && storybook build -o ./dist/storybook",
     "test:storybook": "vitest --project=storybook",
-    "prepare": "husky"
+    "check:conventions": "yarn cem && node scripts/check-conventions-all.mjs",
+    "check:conventions:fast": "node scripts/check-conventions.mjs",
+    "prepare": "husky && (cd src/legacy/tool-ui && yarn install)",
+    "prepublishOnly": "yarn install --frozen-lockfile && (cd src/legacy/tool-ui && yarn install --frozen-lockfile)"
   },
   "devDependencies": {
     "@commitlint/cli": "^20.1.0",
@@ -59,7 +62,7 @@
     "postcss-loader": "^8.0.0",
     "prettier": "^3.2.5",
     "prettier-plugin-organize-imports": "^4.3.0",
-    "prettier-plugin-tailwindcss": "^0.6.8",
+    "prettier-plugin-tailwindcss": "0.7.2",
     "shx": "^0.4.0",
     "storybook": "10.2.12",
     "style-loader": "^3.3.1",
@@ -88,7 +91,8 @@
   ],
   "files": [
     "dist/**/*",
-    "docs/**/*"
+    "docs/**/*",
+    "src/legacy/tool-ui/src/main/webapp/dist/**/*"
   ],
   "lint-staged": {
     "src/components/**/*.ts": [

package/src/legacy/tool-ui/src/main/webapp/dist/011a678e3efe41981754.png

@@ -0,0 +1 @@
+export default "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABoAAAAaCAQAAAADQ4RFAAACf0lEQVR4AY1UM3gkARTePdvdoTxXKc+qTl3aU5U6b2Kbkz3Gtq3Zw6ziLGNPzrYx7946Tr6/ee/XeCQ4D3ykPtL5tHno4n0d/h3+xfuWHGLX81cn7r0iTNzjr7LrlxCqPtkbTQEHeqOrTy4Yyt3VCi/IOB0v7rVC7q45Q3Gr5K6jt+3Gl5nCoDD4MtO+j96Wu8atmhGqcNGHObuf8OM/x3AMx38+4Z2sPqzCxRFK2aF2e5Jol56XTLyggAMTL56XOMoS1W4pOyjUcGGQdZxU6qRh7B9Zp+PfpOFlqt0zyDZckPi1ttmIp03jX8gyJ8a/PG2yutpS/Vol7peZIbZcKBAEEheEIAgFbDkz5H6Zrkm2hVWGiXKiF4Ycw0RWKdtC16Q7qe3X4iOMxruonzegJzWaXFrU9utOSsLUmrc0YjeWYjCW4PDMADElpJSSQ0vQvA1Tm6/JlKnqFs1EGyZiFCqnRZTEJJJiKRYzVYzJck2Rm6P4iH+cmSY0YzimYa8l0EtTODFWhcMIMVqdsI2uiTvKmTisIDHJ3od5GILVhBCarCfVRmo4uTjkhrhzkiBV7SsaqS+TzrzM1qpGGUFt28pIySQHR6h7F6KSwGWm97ay+Z+ZqMcEjEWebE7wxCSQwpkhJqoZA5ivCdZDjJepuJ9IQjGGUmuXJdBFUygxVqVsxFsLMbDe8ZbDYVCGKxs+W080max1hFCarCfV+C1KATwcnvE9gRRuMP2prdbWGowm1KB1y+zwMMENkM755cJ2yPDtqhTI6ED1M/82yIDtC/4j4BijjeObflpO9I9MwXTCsSX8jWAFeHr05WoLTJ5G8IQVS/7vwR6ohirYM7f6HzYpogfS3R2OAAAAAElFTkSuQmCC"