@brightspot/ui 1.10.0 → 3.0.0

package/dist/util/upload.js

@@ -0,0 +1,113 @@
+import { l10n } from './i18n.js';
+/**
+ * Validate a File against an `accept` attribute string, matching the HTML
+ * `<input accept>` attribute format. Client-side filter only — 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:
+ * - `matchesAccept(file, "image/*")` — any image
+ * - `matchesAccept(file, "image/*,application/pdf")` — images and PDFs
+ * - `matchesAccept(file, ".jpg,.jpeg,.png,.heic")` — specific extensions
+ * - `matchesAccept(file, "")` — allow all (returns true)
+ *
+ * Note: users can bypass the file picker's filter (most browsers offer an
+ * "All Files" option), so this function is a UX filter, not a security
+ * boundary.
+ */
+export function matchesAccept(file, accept) {
+    if (!accept || !accept.trim())
+        return true;
+    const types = accept
+        .split(',')
+        .map(t => t.trim().toLowerCase())
+        .filter(Boolean);
+    const fileMime = file.type.toLowerCase();
+    const fileName = file.name.toLowerCase();
+    return types.some(type => {
+        if (type.startsWith('.')) {
+            return fileName.endsWith(type);
+        }
+        if (type.endsWith('/*')) {
+            const category = type.slice(0, type.indexOf('/'));
+            return fileMime.startsWith(category + '/');
+        }
+        return fileMime === type;
+    });
+}
+/**
+ * Validate a File's size against a maximum byte limit.
+ * Returns false if file exceeds `maxSize` bytes.
+ * Returns true if `maxSize` is 0 (unlimited).
+ */
+export function validateFileSize(file, maxSize) {
+    if (maxSize <= 0)
+        return true;
+    return file.size <= maxSize;
+}
+/**
+ * Resolve a MIME type to a Lucide icon symbol name.
+ *
+ * Mappings:
+ * - `image/*` → `'image'`
+ * - `video/*` → `'film'`
+ * - `audio/*` → `'music'`
+ * - document types → `'file'`
+ * - everything else → `'upload-cloud'`
+ */
+export function resolveFileSymbol(mimeType) {
+    if (!mimeType)
+        return 'upload-cloud';
+    const mime = mimeType.toLowerCase();
+    if (mime.startsWith('image/'))
+        return 'image';
+    if (mime.startsWith('video/'))
+        return 'film';
+    if (mime.startsWith('audio/'))
+        return 'music';
+    if (mime.startsWith('text/') ||
+        mime === 'application/pdf' ||
+        mime === 'application/msword' ||
+        mime.startsWith('application/vnd.openxmlformats')) {
+        return 'file';
+    }
+    return 'upload-cloud';
+}
+/**
+ * Format a byte count to a human-readable file size string.
+ *
+ * Output format: `"200 KB"`, `"4.2 MB"`, `"16 MB"`, `"1.3 GB"`
+ * Uses `l10n()` for unit labels.
+ *
+ * Thresholds:
+ * - 0 bytes → `"< 1 KB"`
+ * - < 1 KB → `"< 1 KB"` (sub-KB files render the same)
+ * - < 1 MB → whole number KB
+ * - < 1 GB → one decimal MB
+ * - >= 1 GB → one decimal GB
+ */
+export function formatFileSize(bytes) {
+    const KB = 1024;
+    const MB = KB * 1024;
+    const GB = MB * 1024;
+    if (bytes < KB) {
+        return l10n('upload', 'sizeSubKB', '< 1 KB');
+    }
+    if (bytes < MB) {
+        const kb = Math.round(bytes / KB);
+        return `${kb} ${l10n('upload', 'unitKB', 'KB')}`;
+    }
+    if (bytes < GB) {
+        const mb = bytes / MB;
+        const formatted = mb >= 10 ? Math.round(mb).toString() : mb.toFixed(1);
+        return `${formatted} ${l10n('upload', 'unitMB', 'MB')}`;
+    }
+    const gb = bytes / GB;
+    const formatted = gb >= 10 ? Math.round(gb).toString() : gb.toFixed(1);
+    return `${formatted} ${l10n('upload', 'unitGB', 'GB')}`;
+}
+//# sourceMappingURL=upload.js.map

package/dist/util/upload.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"upload.js","sourceRoot":"","sources":["../../src/util/upload.ts"],"names":[],"mappings":"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"}

package/docs/components/ActionBar.md

@@ -0,0 +1,77 @@
+# `src/components/action-bar/ActionBar.ts`:
+
+## class: `ActionBar`, `btu-action-bar`
+
+### Superclass
+
+| Name         | Module | Package |
+| ------------ | ------ | ------- |
+| `LitElement` |        | lit     |
+
+### Mixins
+
+| Name                  | Module                           | Package |
+| --------------------- | -------------------------------- | ------- |
+| `RovingTabindexMixin` | /src/util/RovingTabindexMixin.js |         |
+| `EventEmitterMixin`   | /src/util/EventEmitterMixin.js   |         |
+| `ReadyMixin`          | /src/util/ReadyMixin.js          |         |
+
+### Fields
+
+| Name        | Privacy | Type        | Default     | Description                                                                                                                                                                                                     | Inherited From |
+| ----------- | ------- | ----------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- |
+| `position`  |         | `Position`  | `'bottom'`  | Bar position: 'top' or 'bottom' (default).                                                                                                                                                                      |                |
+| `sticky`    |         | `boolean`   | `false`     | Enables CSS sticky positioning. When combined with position='top',
the bar sticks to the top of the scroll container. With position='bottom'
(default), it sticks to the bottom.                        |                |
+| `alignment` |         | `Alignment` | `'default'` | Content alignment: 'default' (two-zone), 'start', 'center', 'end'.
Non-default alignments disable two-zone layout.                                                                                          |                |
+| `shadow`    |         | `boolean`   | `false`     | Adds a box-shadow to the bar.                                                                                                                                                                                   |                |
+| `label`     |         | `string`    | `''`        | Accessible label for the toolbar region.                                                                                                                                                                        |                |
+| `compact`   |         | `boolean`   | `false`     | Enables progressive label compacting. When space shrinks, items marked
\`compactable\` (with icons) have their labels hidden one-by-one
from least to most important before items overflow into "More". |                |
+
+### Methods
+
+| Name   | Privacy | Description                                                                                                                                                                                                                                                                        | Parameters                                              | Return    | Inherited From    |
+| ------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | --------- | ----------------- |
+| `emit` |         | Dispatches a type-safe CustomEvent with standardized configuration.&#xA;&#xA;All events are configured with:&#xA;- bubbles: true (event propagates up the DOM tree)&#xA;- cancelable: false (event cannot be cancelled)&#xA;- composed: true (event crosses shadow DOM boundaries) | `type: K, detail: UnpackCustomEvent<CustomEventMap[K]>` | `boolean` | EventEmitterMixin |
+
+### Events
+
+| Name                    | Type                           | Description                                                         | Inherited From |
+| ----------------------- | ------------------------------ | ------------------------------------------------------------------- | -------------- |
+| `btu-action-bar-ready`  | `CustomEvent`                  | Fired after first render and initialization                         |                |
+| `btu-action-item-click` | `CustomEvent<{label: string}>` | Fired when an action item is clicked (bubbles from btu-action-item) |                |
+
+### Attributes
+
+| Name             | Field     | Inherited From |
+| ---------------- | --------- | -------------- |
+| `position`       | position  |                |
+| `sticky`         | sticky    |                |
+| `item-alignment` | alignment |                |
+| `shadow`         | shadow    |                |
+| `label`          | label     |                |
+| `compact`        | compact   |                |
+
+### CSS Properties
+
+| Name                        | Default | Description                          |
+| --------------------------- | ------- | ------------------------------------ |
+| `--action-bar-gap`          |         | Gap between items (default: 0.75rem) |
+| `--action-bar-padding`      |         | Bar padding (default: 1.5rem)        |
+| `--action-bar-background`   |         | Background color (default: white)    |
+| `--action-bar-border-color` |         | Border color (default: gray-200)     |
+| `--action-bar-z-index`      |         | Z-index (default: 100)               |
+
+### Slots
+
+| Name | Description                              |
+| ---- | ---------------------------------------- |
+|      | One or more \`btu-action-item\` elements |
+
+<hr/>
+
+## Exports
+
+| Kind                        | Name             | Declaration | Module                                 | Package |
+| --------------------------- | ---------------- | ----------- | -------------------------------------- | ------- |
+| `js`                        | `default`        | ActionBar   | src/components/action-bar/ActionBar.ts |         |
+| `custom-element-definition` | `btu-action-bar` | ActionBar   | src/components/action-bar/ActionBar.ts |         |

package/docs/components/ActionItem.md

@@ -0,0 +1,101 @@
+# `src/components/action-bar/ActionItem.ts`:
+
+## class: `ActionItem`, `btu-action-item`
+
+### Superclass
+
+| Name         | Module | Package |
+| ------------ | ------ | ------- |
+| `LitElement` |        | lit     |
+
+### Mixins
+
+| Name                | Module                         | Package |
+| ------------------- | ------------------------------ | ------- |
+| `TooltipMixin`      | /src/util/TooltipMixin.js      |         |
+| `EventEmitterMixin` | /src/util/EventEmitterMixin.js |         |
+| `ReadyMixin`        | /src/util/ReadyMixin.js        |         |
+
+### Fields
+
+| Name               | Privacy | Type                                     | Default         | Description                                                                                                                                                                                                                                                                                               | Inherited From |
+| ------------------ | ------- | ---------------------------------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- |
+| `label`            |         | `string`                                 | `''`            | Button label text.                                                                                                                                                                                                                                                                                        |                |
+| `variant`          |         | `ActionItemVariant`                      | `'secondary'`   | Visual variant: 'primary', 'secondary', 'tertiary', 'destructive'.                                                                                                                                                                                                                                        |                |
+| `symbol`           |         | `string`                                 | `''`            | Lucide icon symbol for the leading icon.                                                                                                                                                                                                                                                                  |                |
+| `iconOnly`         |         | `boolean`                                | `false`         | Show icon only, hiding the label. Tooltip activates automatically with the label text.                                                                                                                                                                                                                    |                |
+| `disabled`         |         | `boolean`                                | `false`         | Disables the action item. The button remains focusable for accessibility
but click events are suppressed.                                                                                                                                                                                             |                |
+| `loading`          |         | `boolean`                                | `false`         | Shows a loading spinner and prevents interaction.                                                                                                                                                                                                                                                         |                |
+| `zone`             |         | `'start' \| 'end' \| ''`                 | `''`            | Zone placement: 'start' or 'end'. Used by ActionBar for two-zone layout.
If unset, auto-detected from variant (destructive → start, others → end).                                                                                                                                                    |                |
+| `compactable`      |         | `boolean`                                | `false`         | Opt-in for progressive label compacting. When the parent bar has \`compact\`
enabled and space shrinks, compactable items with icons have their labels
hidden one-by-one (least important first) before overflowing.
Items without an icon ignore this attribute and go directly to overflow. |                |
+| `tooltip`          |         | `string`                                 | `''`            | Tooltip text content. Set to empty string to remove the tooltip.                                                                                                                                                                                                                                          | TooltipMixin   |
+| `tooltipPosition`  |         | `'top' \| 'bottom' \| 'left' \| 'right'` | `'top'`         | Position relative to the host element. Auto-flips when constrained by the viewport.                                                                                                                                                                                                                       | TooltipMixin   |
+| `tooltipDelay`     |         | `number`                                 | `300`           | Show delay in milliseconds (hover trigger only).                                                                                                                                                                                                                                                          | TooltipMixin   |
+| `tooltipOffset`    |         | `TooltipOffset \| null`                  | `null`          | Gap between host and tooltip (sm=4px, md=8px, lg=12px, xl=16px).                                                                                                                                                                                                                                          | TooltipMixin   |
+| `tooltipNoArrow`   |         | `boolean`                                | `false`         | Hide the arrow pseudo-element.                                                                                                                                                                                                                                                                            | TooltipMixin   |
+| `tooltipTrigger`   |         | `string`                                 | `'hover focus'` | Space-separated trigger types: 'hover', 'focus', 'click'.                                                                                                                                                                                                                                                 | TooltipMixin   |
+| `_onMouseLeave`    | private |                                          |                 |                                                                                                                                                                                                                                                                                                           | TooltipMixin   |
+| `_onFocusIn`       | private |                                          |                 |                                                                                                                                                                                                                                                                                                           | TooltipMixin   |
+| `_onFocusOut`      | private |                                          |                 |                                                                                                                                                                                                                                                                                                           | TooltipMixin   |
+| `_onClick`         | private |                                          |                 |                                                                                                                                                                                                                                                                                                           | TooltipMixin   |
+| `_onNativeToggle`  | private |                                          |                 |                                                                                                                                                                                                                                                                                                           | TooltipMixin   |
+| `_onKeyDown`       | private |                                          |                 |                                                                                                                                                                                                                                                                                                           | TooltipMixin   |
+| `_onDocumentClick` | private | `((e: MouseEvent) => void) \| null`      | `null`          |                                                                                                                                                                                                                                                                                                           | TooltipMixin   |
+
+### Methods
+
+| Name                  | Privacy | Description                                                                                                                                                                                                                                                                        | Parameters                                              | Return                   | Inherited From    |
+| --------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | ------------------------ | ----------------- |
+| `_relayTooltipAttrs`  | private |                                                                                                                                                                                                                                                                                    |                                                         | `void`                   |                   |
+| `_handleClick`        | private |                                                                                                                                                                                                                                                                                    |                                                         | `void`                   |                   |
+| `_getSpinnerColor`    | private |                                                                                                                                                                                                                                                                                    |                                                         | `string`                 |                   |
+| `_buildButtonClasses` | private |                                                                                                                                                                                                                                                                                    |                                                         | `string`                 |                   |
+| `_getButtonStyles`    | private |                                                                                                                                                                                                                                                                                    |                                                         | `Record<string, 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-action-item-click` | `CustomEvent<{label: string}>` | Fired when the action item is clicked (not fired when disabled or loading) |                |
+
+### Attributes
+
+| Name               | Field           | Inherited From |
+| ------------------ | --------------- | -------------- |
+| `label`            | label           |                |
+| `variant`          | variant         |                |
+| `symbol`           | symbol          |                |
+| `icon-only`        | iconOnly        |                |
+| `disabled`         | disabled        |                |
+| `loading`          | loading         |                |
+| `zone`             | zone            |                |
+| `compactable`      | compactable     |                |
+| `tooltip`          | tooltip         | TooltipMixin   |
+| `tooltipPosition`  | tooltipPosition | TooltipMixin   |
+| `tooltipDelay`     | tooltipDelay    | TooltipMixin   |
+| `tooltipOffset`    | tooltipOffset   | TooltipMixin   |
+| `tooltipNoArrow`   | tooltipNoArrow  | TooltipMixin   |
+| `tooltipTrigger`   | tooltipTrigger  | TooltipMixin   |
+| `tooltip-position` | tooltipPosition | TooltipMixin   |
+| `tooltip-delay`    | tooltipDelay    | TooltipMixin   |
+| `tooltip-offset`   | tooltipOffset   | TooltipMixin   |
+| `tooltip-no-arrow` | tooltipNoArrow  | TooltipMixin   |
+| `tooltip-trigger`  | tooltipTrigger  | TooltipMixin   |
+
+### CSS Properties
+
+| Name                     | Default | Description                      |
+| ------------------------ | ------- | -------------------------------- |
+| `--button-color`         |         | Override button background color |
+| `--button-text-color`    |         | Override button text color       |
+| `--button-border-radius` |         | Override button border radius    |
+
+<hr/>
+
+## Exports
+
+| Kind                        | Name              | Declaration | Module                                  | Package |
+| --------------------------- | ----------------- | ----------- | --------------------------------------- | ------- |
+| `js`                        | `default`         | ActionItem  | src/components/action-bar/ActionItem.ts |         |
+| `custom-element-definition` | `btu-action-item` | ActionItem  | src/components/action-bar/ActionItem.ts |         |

package/docs/components/Avatar.md

@@ -18,12 +18,31 @@
 
 ### Fields
 
-| Name       | Privacy | Type                                            | Default | Description                                                                                                                                                                                                      | Inherited From |
-| ---------- | ------- | ----------------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- |
-| `src`      |         | `string`                                        | `''`    | Image source URL                                                                                                                                                                                                 |                |
-| `alt`      |         | `string`                                        | `''`    | Alt text for the image                                                                                                                                                                                           |                |
-| `fallback` |         | `string`                                        | `''`    | Fallback text (typically user initials)                                                                                                                                                                          |                |
-| `size`     |         | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| 'xxl'` | `'md'`  | Size variant.
- 'xs': Extra small (1.5rem)
- 'sm': Small (2.25rem)
- 'md': Medium (2.5rem) - default
- 'lg': Large (3rem)
- 'xl': Extra large (3.5rem)
- 'xxl': Extra extra large (4rem) |                |
+| Name               | Privacy | Type                                            | Default         | Description                                                                                                                                                                                                      | Inherited From |
+| ------------------ | ------- | ----------------------------------------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- |
+| `src`              |         | `string`                                        | `''`            | Image source URL                                                                                                                                                                                                 |                |
+| `alt`              |         | `string`                                        | `''`            | Alt text for the image                                                                                                                                                                                           |                |
+| `fallback`         |         | `string`                                        | `''`            | Fallback text (typically user initials)                                                                                                                                                                          |                |
+| `size`             |         | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| 'xxl'` | `'md'`          | Size variant.
- 'xs': Extra small (1.5rem)
- 'sm': Small (2.25rem)
- 'md': Medium (2.5rem) - default
- 'lg': Large (3rem)
- 'xl': Extra large (3.5rem)
- 'xxl': Extra extra large (4rem) |                |
+| `tooltip`          |         | `string`                                        | `''`            | Tooltip text content. Set to empty string to remove the tooltip.                                                                                                                                                 | TooltipMixin   |
+| `tooltipPosition`  |         | `'top' \| 'bottom' \| 'left' \| 'right'`        | `'top'`         | Position relative to the host element. Auto-flips when constrained by the viewport.                                                                                                                              | TooltipMixin   |
+| `tooltipDelay`     |         | `number`                                        | `300`           | Show delay in milliseconds (hover trigger only).                                                                                                                                                                 | TooltipMixin   |
+| `tooltipOffset`    |         | `TooltipOffset \| null`                         | `null`          | Gap between host and tooltip (sm=4px, md=8px, lg=12px, xl=16px).                                                                                                                                                 | TooltipMixin   |
+| `tooltipNoArrow`   |         | `boolean`                                       | `false`         | Hide the arrow pseudo-element.                                                                                                                                                                                   | TooltipMixin   |
+| `tooltipTrigger`   |         | `string`                                        | `'hover focus'` | Space-separated trigger types: 'hover', 'focus', 'click'.                                                                                                                                                        | TooltipMixin   |
+| `_onMouseLeave`    | private |                                                 |                 |                                                                                                                                                                                                                  | TooltipMixin   |
+| `_onFocusIn`       | private |                                                 |                 |                                                                                                                                                                                                                  | TooltipMixin   |
+| `_onFocusOut`      | private |                                                 |                 |                                                                                                                                                                                                                  | TooltipMixin   |
+| `_onClick`         | private |                                                 |                 |                                                                                                                                                                                                                  | TooltipMixin   |
+| `_onNativeToggle`  | private |                                                 |                 |                                                                                                                                                                                                                  | TooltipMixin   |
+| `_onKeyDown`       | private |                                                 |                 |                                                                                                                                                                                                                  | TooltipMixin   |
+| `_onDocumentClick` | private | `((e: MouseEvent) => void) \| null`             | `null`          |                                                                                                                                                                                                                  | TooltipMixin   |
+
+### Methods
+
+| Name   | Privacy | Description                                                                                                                                                                                                                                                                        | Parameters                                              | Return    | Inherited From    |
+| ------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | --------- | ----------------- |
+| `emit` |         | Dispatches a type-safe CustomEvent with standardized configuration.&#xA;&#xA;All events are configured with:&#xA;- bubbles: true (event propagates up the DOM tree)&#xA;- cancelable: false (event cannot be cancelled)&#xA;- composed: true (event crosses shadow DOM boundaries) | `type: K, detail: UnpackCustomEvent<CustomEventMap[K]>` | `boolean` | EventEmitterMixin |
 
 ### Events
 
@@ -35,12 +54,23 @@
 
 ### Attributes
 
-| Name       | Field    | Inherited From |
-| ---------- | -------- | -------------- |
-| `src`      | src      |                |
-| `alt`      | alt      |                |
-| `fallback` | fallback |                |
-| `size`     | size     |                |
+| Name               | Field           | Inherited From |
+| ------------------ | --------------- | -------------- |
+| `src`              | src             |                |
+| `alt`              | alt             |                |
+| `fallback`         | fallback        |                |
+| `size`             | size            |                |
+| `tooltip`          | tooltip         | TooltipMixin   |
+| `tooltipPosition`  | tooltipPosition | TooltipMixin   |
+| `tooltipDelay`     | tooltipDelay    | TooltipMixin   |
+| `tooltipOffset`    | tooltipOffset   | TooltipMixin   |
+| `tooltipNoArrow`   | tooltipNoArrow  | TooltipMixin   |
+| `tooltipTrigger`   | tooltipTrigger  | TooltipMixin   |
+| `tooltip-position` | tooltipPosition | TooltipMixin   |
+| `tooltip-delay`    | tooltipDelay    | TooltipMixin   |
+| `tooltip-offset`   | tooltipOffset   | TooltipMixin   |
+| `tooltip-no-arrow` | tooltipNoArrow  | TooltipMixin   |
+| `tooltip-trigger`  | tooltipTrigger  | TooltipMixin   |
 
 ### CSS Properties
 

package/docs/components/AvatarGroup.md

@@ -24,9 +24,10 @@
 
 ### Methods
 
-| Name             | Privacy | Description                                                                                                                 | Parameters | Return | Inherited From |
-| ---------------- | ------- | --------------------------------------------------------------------------------------------------------------------------- | ---------- | ------ | -------------- |
-| `processAvatars` |         | Process all avatar children: apply size, handle overflow
Call this method when avatars are dynamically added or removed |            | `void` |                |
+| Name             | Privacy | Description                                                                                                                                                                                                                                                                        | Parameters                                              | Return    | Inherited From    |
+| ---------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | --------- | ----------------- |
+| `processAvatars` |         | Process all avatar children: apply size, handle overflow
Call this method when avatars are dynamically added or removed                                                                                                                                                        |                                                         | `void`    |                   |
+| `emit`           |         | Dispatches a type-safe CustomEvent with standardized configuration.&#xA;&#xA;All events are configured with:&#xA;- bubbles: true (event propagates up the DOM tree)&#xA;- cancelable: false (event cannot be cancelled)&#xA;- composed: true (event crosses shadow DOM boundaries) | `type: K, detail: UnpackCustomEvent<CustomEventMap[K]>` | `boolean` | EventEmitterMixin |
 
 ### Events
 

package/docs/components/Badge.md

@@ -21,7 +21,13 @@
 | --------- | ------- | ---------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- |
 | `variant` |         | `'info' \| 'primary' \| 'error' \| 'success' \| 'warning'` | `'info'` | Style of the badge.
- 'info': Informational (default)
- 'primary': Primary action or emphasis
- 'error': Error or danger state
- 'success': Success or completion state
- 'warning': Warning or caution state |                |
 | `dot`     |         | `boolean`                                                  | `false`  | Should a dot be displayed before the label?                                                                                                                                                                                       |                |
-| `size`    |         | `string`                                                   | `'sm'`   | Size variant.
- 'sm': Small (default)
- 'md': Medium
- 'lg': Large                                                                                                                                                    |                |
+| `size`    |         | `'sm' \| 'md' \| 'lg'`                                     | `'sm'`   | Size variant.
- 'sm': Small (default)
- 'md': Medium
- 'lg': Large                                                                                                                                                    |                |
+
+### 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
 
@@ -48,6 +54,12 @@
 | `--badge-py`               |         | Vertical padding (overrides size default)                    |
 | `--badge-dot-size`         |         | Size of the dot affordance (default: 6px)                    |
 
+### Slots
+
+| Name | Description                                          |
+| ---- | ---------------------------------------------------- |
+|      | Label text or child elements (e.g., btu-icon + text) |
+
 <hr/>
 
 ## Exports

package/docs/components/ButtonGroup.md

@@ -0,0 +1,91 @@
+# `src/components/button-group/ButtonGroup.ts`:
+
+## class: `ButtonGroup`, `btu-button-group`
+
+### Superclass
+
+| Name         | Module | Package |
+| ------------ | ------ | ------- |
+| `LitElement` |        | lit     |
+
+### Mixins
+
+| Name                   | Module                            | Package |
+| ---------------------- | --------------------------------- | ------- |
+| `RovingTabindexMixin`  | /src/util/RovingTabindexMixin.js  |         |
+| `ComponentStatesMixin` | /src/util/ComponentStatesMixin.js |         |
+| `EventEmitterMixin`    | /src/util/EventEmitterMixin.js    |         |
+| `ReadyMixin`           | /src/util/ReadyMixin.js           |         |
+
+### Static Fields
+
+| Name      | Privacy | Type | Default | Description | Inherited From |
+| --------- | ------- | ---- | ------- | ----------- | -------------- |
+| `tagName` |         |      |         |             |                |
+
+### Fields
+
+| Name          | Privacy | Type                               | Default        | Description                                                                                                                                                         | Inherited From |
+| ------------- | ------- | ---------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- |
+| `label`       |         | `string`                           | `''`           | Accessible name for the group, announced by assistive devices via aria-label.                                                                                       |                |
+| `orientation` |         | `'horizontal' \| 'vertical'`       | `'horizontal'` | Layout direction of the buttons.                                                                                                                                    |                |
+| `variant`     |         | `'connected' \| 'spaced'`          | `'connected'`  | \`connected\` collapses shared borders for a joined appearance.
\`spaced\` renders buttons with a gap.                                                          |                |
+| `size`        |         | `'sm' \| 'md' \| 'lg'`             | `'md'`         | Propagates a uniform size to all child buttons.                                                                                                                     |                |
+| `disabled`    |         | `boolean`                          | `false`        | When true, disables all child buttons as a group.                                                                                                                   |                |
+| `selection`   |         | `'none' \| 'single' \| 'multiple'` | `'none'`       | Enables toggle/selection behavior.
\`single\` allows one active button; \`multiple\` allows many.                                                               |                |
+| `value`       |         | `string`                           | `''`           | Reflects the currently selected button value(s).
For \`single\`, the value of the active button.
For \`multiple\`, a comma-delimited list of active values. |                |
+| `name`        |         | `string`                           | `''`           | When set, creates hidden input(s) for native form participation.                                                                                                    |                |
+
+### Methods
+
+| Name   | Privacy | Description                                                                                                                                                                                                                                                                        | Parameters                                              | Return    | Inherited From    |
+| ------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | --------- | ----------------- |
+| `emit` |         | Dispatches a type-safe CustomEvent with standardized configuration.&#xA;&#xA;All events are configured with:&#xA;- bubbles: true (event propagates up the DOM tree)&#xA;- cancelable: false (event cannot be cancelled)&#xA;- composed: true (event crosses shadow DOM boundaries) | `type: K, detail: UnpackCustomEvent<CustomEventMap[K]>` | `boolean` | EventEmitterMixin |
+
+### Events
+
+| Name                      | Type                                       | Description                                               | Inherited From |
+| ------------------------- | ------------------------------------------ | --------------------------------------------------------- | -------------- |
+| `btu-button-group-ready`  | `CustomEvent`                              | Fired after first render and initialization               |                |
+| `btu-button-group-change` | `CustomEvent<{value: string}>`             | Fired when selection changes (single/multiple modes only) |                |
+| `btu-icon-button-click`   | `CustomEvent<{name: string \| undefined}>` | Bubbles from child btu-icon-button elements when clicked  |                |
+
+### Attributes
+
+| Name          | Field       | Inherited From |
+| ------------- | ----------- | -------------- |
+| `label`       | label       |                |
+| `orientation` | orientation |                |
+| `variant`     | variant     |                |
+| `size`        | size        |                |
+| `disabled`    | disabled    |                |
+| `selection`   | selection   |                |
+| `value`       | value       |                |
+| `name`        | name        |                |
+
+### CSS Properties
+
+| Name                               | Default | Description                                                             |
+| ---------------------------------- | ------- | ----------------------------------------------------------------------- |
+| `--button-group-gap`               |         | Space between buttons when variant="spaced" (default: spacing.sm)       |
+| `--button-group-border-radius`     |         | Corner radius of outer edges when variant="connected" (default: 0.5rem) |
+| `--button-group-border-color`      |         | Internal divider color between connected buttons (default: gray-300)    |
+| `--button-group-selection-bg`      |         | Background of a toggled/selected child (default: primary-50)            |
+| `--button-group-selection-color`   |         | Text/icon color of a toggled/selected child (default: primary-700)      |
+| `--button-group-shimmer-highlight` |         | Highlight color of the selection shimmer effect (default: primary-200)  |
+
+### Slots
+
+| Name  | Description                                                                                    |
+| ----- | ---------------------------------------------------------------------------------------------- |
+|       | One or more btu-button or btu-icon-button elements to display in the group                     |
+| `end` | Pushes the child to the end of the group via auto-margin (vertical: bottom, horizontal: right) |
+
+<hr/>
+
+## Exports
+
+| Kind                        | Name               | Declaration | Module                                     | Package |
+| --------------------------- | ------------------ | ----------- | ------------------------------------------ | ------- |
+| `js`                        | `default`          | ButtonGroup | src/components/button-group/ButtonGroup.ts |         |
+| `custom-element-definition` | `btu-button-group` | ButtonGroup | src/components/button-group/ButtonGroup.ts |         |