@ismail-elkorchi/ui-primitives 0.1.1 → 0.2.0

package/README.md

@@ -5,41 +5,56 @@ Shadow DOM web components backed by the shared token CSS variables from `@ismail
 ## Usage
 
 ```ts
-import '@ismail-elkorchi/ui-primitives/register'; // defines all elements
+import "@ismail-elkorchi/ui-primitives/register"; // defines all elements
 // or import individual components for tree-shaking:
-import '@ismail-elkorchi/ui-primitives/uik-alert';
-import '@ismail-elkorchi/ui-primitives/uik-badge';
-import '@ismail-elkorchi/ui-primitives/uik-box';
-import '@ismail-elkorchi/ui-primitives/uik-button';
-import '@ismail-elkorchi/ui-primitives/uik-checkbox';
-import '@ismail-elkorchi/ui-primitives/uik-dialog';
-import '@ismail-elkorchi/ui-primitives/uik-heading';
-import '@ismail-elkorchi/ui-primitives/uik-icon';
-import '@ismail-elkorchi/ui-primitives/uik-input';
-import '@ismail-elkorchi/ui-primitives/uik-link';
-import '@ismail-elkorchi/ui-primitives/uik-nav';
-import '@ismail-elkorchi/ui-primitives/uik-tree-view';
-import '@ismail-elkorchi/ui-primitives/uik-popover';
-import '@ismail-elkorchi/ui-primitives/uik-progress';
-import '@ismail-elkorchi/ui-primitives/uik-radio';
-import '@ismail-elkorchi/ui-primitives/uik-radio-group';
-import '@ismail-elkorchi/ui-primitives/uik-select';
-import '@ismail-elkorchi/ui-primitives/uik-separator';
-import '@ismail-elkorchi/ui-primitives/uik-spinner';
-import '@ismail-elkorchi/ui-primitives/uik-stack';
-import '@ismail-elkorchi/ui-primitives/uik-surface';
-import '@ismail-elkorchi/ui-primitives/uik-switch';
-import '@ismail-elkorchi/ui-primitives/uik-text';
-import '@ismail-elkorchi/ui-primitives/uik-textarea';
-import '@ismail-elkorchi/ui-primitives/uik-tooltip';
-import '@ismail-elkorchi/ui-primitives/uik-visually-hidden';
+import "@ismail-elkorchi/ui-primitives/uik-alert";
+import "@ismail-elkorchi/ui-primitives/uik-badge";
+import "@ismail-elkorchi/ui-primitives/uik-code-block";
+import "@ismail-elkorchi/ui-primitives/uik-box";
+import "@ismail-elkorchi/ui-primitives/uik-button";
+import "@ismail-elkorchi/ui-primitives/uik-checkbox";
+import "@ismail-elkorchi/ui-primitives/uik-description-list";
+import "@ismail-elkorchi/ui-primitives/uik-dialog";
+import "@ismail-elkorchi/ui-primitives/uik-command-palette";
+import "@ismail-elkorchi/ui-primitives/uik-heading";
+import "@ismail-elkorchi/ui-primitives/uik-icon";
+import "@ismail-elkorchi/ui-primitives/uik-input";
+import "@ismail-elkorchi/ui-primitives/uik-listbox";
+import "@ismail-elkorchi/ui-primitives/uik-combobox";
+import "@ismail-elkorchi/ui-primitives/uik-menu";
+import "@ismail-elkorchi/ui-primitives/uik-menu-item";
+import "@ismail-elkorchi/ui-primitives/uik-menubar";
+import "@ismail-elkorchi/ui-primitives/uik-link";
+import "@ismail-elkorchi/ui-primitives/uik-nav";
+import "@ismail-elkorchi/ui-primitives/uik-nav-rail";
+import "@ismail-elkorchi/ui-primitives/uik-option";
+import "@ismail-elkorchi/ui-primitives/uik-tree-view";
+import "@ismail-elkorchi/ui-primitives/uik-popover";
+import "@ismail-elkorchi/ui-primitives/uik-pagination";
+import "@ismail-elkorchi/ui-primitives/uik-progress";
+import "@ismail-elkorchi/ui-primitives/uik-radio";
+import "@ismail-elkorchi/ui-primitives/uik-radio-group";
+import "@ismail-elkorchi/ui-primitives/uik-select";
+import "@ismail-elkorchi/ui-primitives/uik-separator";
+import "@ismail-elkorchi/ui-primitives/uik-resizable-panels";
+import "@ismail-elkorchi/ui-primitives/uik-spinner";
+import "@ismail-elkorchi/ui-primitives/uik-stack";
+import "@ismail-elkorchi/ui-primitives/uik-surface";
+import "@ismail-elkorchi/ui-primitives/uik-switch";
+import "@ismail-elkorchi/ui-primitives/uik-tabs";
+import "@ismail-elkorchi/ui-primitives/uik-tab";
+import "@ismail-elkorchi/ui-primitives/uik-tab-panel";
+import "@ismail-elkorchi/ui-primitives/uik-text";
+import "@ismail-elkorchi/ui-primitives/uik-textarea";
+import "@ismail-elkorchi/ui-primitives/uik-tooltip";
+import "@ismail-elkorchi/ui-primitives/uik-visually-hidden";
 ```
 
 Ensure your app imports tokens before Tailwind so the theme variables exist:
 
 ```css
-@import '@ismail-elkorchi/ui-tokens/index.css';
-@import 'tailwindcss';
+@import "@ismail-elkorchi/ui-tokens/index.css";
+@import "tailwindcss";
 ```
 
 ## Parts (consistent strategy)
@@ -48,6 +63,31 @@ Ensure your app imports tokens before Tailwind so the theme variables exist:
 - Form-field primitives expose `part="control"` wrappers plus `part="label"`, `part="hint"`, and `part="error"` slots when slotted.
 - Layout and text primitives expose `part="base"` on their container or rendered tag.
 
+## Focus + roving focus contract
+
+- Roving focus is implemented with a single `tabIndexValue=0` target and `tabIndexValue=-1` for the rest of the roving set (usually `uik-button` inside a composite widget).
+- Arrow keys move focus within the roving set; `Home`/`End` jump to the first/last enabled item. `Enter`/`Space` activate the focused item per APG expectations.
+- Focus state is tracked by item id and updated on focus and when the items list changes (falling back to the active or first enabled item).
+- `uik-listbox` and `uik-tabs` use `uik-option` and `uik-tab` as the roving focus targets; `uik-listbox` can switch to `focus-mode="activedescendant"` for combobox-style inputs.
+- `uik-menu` uses `uik-menu-item` for roving focus and returns focus to the trigger on close.
+- Shell components must delegate roving focus to primitives such as `uik-nav-rail`/`uik-tree-view` instead of re-implementing keyboard logic.
+
+## Overlay contract
+
+- Overlay primitives emit `overlay-close` with reason `escape | outside | programmatic | toggle`.
+- Focus origin is captured on open for focus-taking overlays; `uik-dialog` restores focus to the opener on close. Hover surfaces (`uik-tooltip`) never move focus.
+- Initial focus relies on native `<dialog>` behavior; popovers/tooltips leave focus on the trigger unless the host moves it.
+- Outside-dismiss policy: click popovers dismiss on outside click when not using the native Popover API; tooltips close on pointer/blur; dialog cancel reports `escape`.
+
+## Form association fallback
+
+Form-associated primitives use `ElementInternals` when available. When it is
+unavailable, components fall back to reflecting their current value on the host
+`value` attribute and continue to emit their normal change/input or
+component-specific events. In fallback mode, the controls do not participate in
+native form submission or constraint validation, so value collection and
+validation must be handled by the host.
+
 ## Components and contracts
 
 ### `<uik-alert>`
@@ -80,8 +120,8 @@ Ensure your app imports tokens before Tailwind so the theme variables exist:
   - Sizing is enforced on the `:host`. The internal button fills the host (100% width/height).
   - `active`/`muted` props control stateful colors (especially for ghost variant).
   - `part="base"` allows overrides, but avoid fighting the host sizing.
-- **A11y**: `aria-label`/`aria-labelledby`/`aria-pressed` are forwarded to the internal `<button>` for icon-only buttons and toggle states.
-- **Forms**: `type="submit"` and `type="reset"` invoke `form.requestSubmit()`/`form.reset()` when inside a form.
+- **A11y**: `aria-label`/`aria-labelledby`/`aria-describedby`/`aria-pressed`/`aria-haspopup`/`aria-expanded`/`aria-controls`/`role` are forwarded to the internal `<button>` for icon-only buttons and toggle states.
+- **Forms**: `type="submit"` and `type="reset"` invoke `form.requestSubmit()`/`form.reset()` when inside a form (uses ElementInternals when available, otherwise the closest form).
 
 ### `<uik-checkbox>`
 
@@ -90,17 +130,47 @@ Ensure your app imports tokens before Tailwind so the theme variables exist:
 - **Parts**: `base`, `control`, `label`, `hint`, `error`.
 - **Events**: native `change` bubbles from the internal `<input>`.
 - **A11y**: label slot or `aria-label`; hint/error slots are announced via `aria-describedby`.
-- **Forms**: form-associated and participates in `FormData` when checked.
+- **Forms**: form-associated and participates in `FormData` when checked (see Form association fallback).
 - **Custom properties**: `--uik-component-checkbox-accent`, `--uik-component-checkbox-size`.
 
+### `<uik-code-block>`
+
+- **Attributes/props**: `copy` (boolean), `inline` (boolean), `copy-label`, `aria-label`, `aria-labelledby`.
+- **Slots**: default slot for code content, `copy-label` for the copy button.
+- **Parts**: `base`, `content`, `copy-button`, `inline`.
+- **Events**: `code-block-copy` (`detail: {value, success}`).
+- **Usage**: use `inline` for short values or commands; default mode renders a scrollable block.
+- **A11y**: provide `aria-label`/`aria-labelledby` when the block needs a name; copy button uses `copy-label`.
+- **Custom properties**: `--uik-component-code-block-*`, `--uik-component-code-block-copy-*`.
+
+### `<uik-description-list>`
+
+- **Attributes/props**: `density` (`comfortable | compact`).
+- **Slots**: default slot for `dt`/`dd` pairs.
+- **Parts**: `base`.
+- **Usage**: use one `dt` followed by one `dd` per row; inline values can use `uik-code-block`.
+- **A11y**: use proper `dt`/`dd` pairs so assistive tech announces the term/value relationship.
+- **Custom properties**: `--uik-component-description-list-*`.
+
 ### `<uik-dialog>`
 
 - **Attributes/props**: `open`, `modal` (boolean).
 - **Slots**: `title`, `description`, default slot for body, `actions`.
 - **Parts**: `base`, `panel`, `title`, `description`, `body`, `actions`.
-- **Events**: native `close`/`cancel` from `<dialog>` bubble.
-- **A11y**: uses native dialog semantics and forwards `aria-label`/`aria-labelledby`/`aria-describedby` to `<dialog>`.
+- **Events**: native `close`/`cancel` from `<dialog>` bubble; `overlay-close` (`detail: {reason}`) with `escape | programmatic | toggle`.
+- **A11y**: uses native dialog semantics and forwards `aria-label`/`aria-labelledby`/`aria-describedby` to `<dialog>`; Escape closes and focus returns to the opener.
 - **Methods**: `showModal()`, `show()`, `close()`.
+- **Custom properties**: `--uik-component-dialog-bg`, `--uik-component-dialog-fg`, `--uik-component-dialog-border`, `--uik-component-dialog-radius`, `--uik-component-dialog-padding`, `--uik-component-dialog-shadow`, `--uik-component-dialog-max-width`, `--uik-component-dialog-title-fg`, `--uik-component-dialog-description-fg`, `--uik-component-dialog-actions-gap`.
+
+### `<uik-command-palette>`
+
+- **Attributes/props**: `open`, `query`, `placeholder`, `loading`, `disabled`, `disableFilter`, `disableAutoClose`, `highlightMatches`, `inputLabel`, `virtualize`, `itemHeight`, `viewportHeight`, `overscan`.
+- **Slots**: `title`, `description`, `label`, `empty`, `loading`, `footer`.
+- **Parts**: `dialog`, `panel`, `header`, `title`, `description`, `label`, `input`, `list`, `group`, `group-label`, `item`, `item-label`, `item-description`, `item-shortcut`, `highlight`, `empty`, `loading`, `footer`.
+- **Events**: `command-palette-open-change`, `command-palette-query-change`, `command-palette-select`.
+- **A11y**: combobox + listbox with `aria-activedescendant`; input receives focus on open; Escape closes and focus returns to the opener.
+- **Items**: set `.items` to `{ id, label, description?, value?, keywords?, shortcut?, group?, isDisabled? }[]`.
+- **Custom properties**: `--uik-component-command-palette-*`.
 
 ### `<uik-heading>`
 
@@ -123,7 +193,7 @@ Ensure your app imports tokens before Tailwind so the theme variables exist:
 - **Slots**: `label`, `hint`, `error`.
 - **Events**: native `input` and `change` bubble from the internal `<input>` (no re-dispatch).
 - **A11y**: label slot associates via `for`, hint/error slot text is wired to `aria-describedby`, and `aria-invalid` is set when `invalid` or an error slot is present.
-- **Forms**: form-associated via `ElementInternals` and participates in `FormData` when `name` is set.
+- **Forms**: form-associated via `ElementInternals` when available and participates in `FormData` when `name` is set (see Form association fallback).
 
 ### `<uik-link>`
 
@@ -134,13 +204,82 @@ Ensure your app imports tokens before Tailwind so the theme variables exist:
 - **A11y**: forwards `aria-label`/`aria-labelledby`/`aria-describedby` to `<a>`.
 - **Custom properties**: `--uik-component-link-fg-default`, `--uik-component-link-fg-hover`, `--uik-component-link-underline-offset`.
 
+### `<uik-listbox>`
+
+- **Attributes/props**: `value`, `selectionMode` (`single | multiple`), `focusMode` (`roving | activedescendant`), `activeId`.
+- **Slots**: default slot for `<uik-option>`.
+- **Parts**: `base`.
+- **Events**: `listbox-select` (`detail: {value, values, option}`), `listbox-active` (`detail: {id, value, option}`).
+- **A11y**: `role="listbox"` with roving focus; `aria-multiselectable` when `selectionMode="multiple"`.
+- **Custom properties**: `--uik-component-listbox-*`, `--uik-component-listbox-item-*`.
+
+### `<uik-option>`
+
+- **Attributes/props**: `value`, `selected`, `disabled`, `active`, `tabIndexValue` (number).
+- **Slots**: default slot for option label.
+- **Parts**: `base`.
+- **A11y**: `role="option"` with `aria-selected` + `aria-disabled`.
+- **Custom properties**: `--uik-component-listbox-item-*`.
+
+### `<uik-combobox>`
+
+- **Attributes/props**: `value`, `open` (boolean), `items` (array), `name`, `placeholder`, `disabled`, `required`, `readonly`, `invalid`.
+- **Items**: `[{id, label, value?, isDisabled?}]` (`value` defaults to `id`).
+- **Slots**: `label`, `hint`, `error`.
+- **Parts**: `base`, `control`, `label`, `hint`, `error`, `panel`.
+- **Events**: `combobox-select` (`detail: {value, item}`).
+- **A11y**: input uses `role="combobox"` with `aria-controls` + `aria-activedescendant`; Arrow keys move active option.
+- **Forms**: form-associated via `ElementInternals` when available (see Form association fallback).
+- **Custom properties**: `--uik-component-combobox-base-*`, `--uik-component-combobox-panel-offset` plus listbox tokens.
+
+### `<uik-menu>`
+
+- **Attributes/props**: `open`, `placement`, `popover`, `value`, `activeId`.
+- **Slots**: `trigger`, default slot for `<uik-menu-item>`.
+- **Parts**: `control`, `base`.
+- **Events**: `menu-active` (`detail: {id, value, item}`), `menu-select` (`detail: {id, value, item}`), `menu-open`, `menu-close`.
+- **A11y**: `role="menu"` with roving focus; `Escape` closes and returns focus to the trigger.
+- **Custom properties**: `--uik-component-menu-*`, `--uik-component-menu-item-*`.
+
+### `<uik-menu-item>`
+
+- **Attributes/props**: `value`, `disabled`, `active`, `tabIndexValue` (number).
+- **Slots**: default slot for item label.
+- **Parts**: `base`.
+- **A11y**: `role="menuitem"` with `aria-disabled` when disabled.
+- **Custom properties**: `--uik-component-menu-item-*`.
+
+### `<uik-menubar>`
+
+- **Slots**: default slot for `<uik-menu>` children.
+- **Parts**: `base`.
+- **A11y**: `role="menubar"` with roving focus across triggers; ArrowLeft/ArrowRight + Home/End move; ArrowDown opens.
+- **Custom properties**: `--uik-component-menubar-*`.
+
+### `<uik-tabs>`
+
+- **Attributes/props**: `activeId`, `orientation` (`horizontal | vertical`), `activation` (`auto | manual`).
+- **Slots**: `uik-tab` and `uik-tab-panel` children (slot names are applied automatically).
+- **Pairs**: each `uik-tab` should share the same `value` as its `uik-tab-panel`.
+- **Parts**: `tablist`, `panels`.
+- **Events**: `tabs-select` (`detail: {id}`).
+- **A11y**: roving focus within the tablist; manual activation uses `Enter`/`Space`.
+- **Custom properties**: `--uik-component-tabs-*`.
+
+### `<uik-tab>` / `<uik-tab-panel>`
+
+- **Attributes/props**: `value` on both; `selected`, `disabled`, `tabIndexValue` on `uik-tab`.
+- **Slots**: default slots for tab label and panel content.
+- **Parts**: `base` (tab + panel), `indicator` (tab).
+
 ### `<uik-tree-view>`
 
-- **Attributes/props**: `items` (array), `selectedIds` (string[]), `openIds` (string[]).
+- **Attributes/props**: `items` (array), `openIds` (string[]), `currentId`.
 - **Slots**: none.
-- **Parts**: `base`, `item`, `toggle`, `selection`, `label`.
-- **Events**: `tree-view-select`, `tree-view-open`, `tree-view-toggle`.
-- **A11y**: `role="tree"` with roving focus; Space toggles selection, Enter opens/toggles; `aria-checked` reflects tri-state.
+- **Parts**: `base`, `item`, `toggle`, `label`.
+- **Events**: `tree-view-activate`, `tree-view-toggle`.
+- **A11y**: `role="tree"` with roving focus; Arrow/Home/End + typeahead navigation; Enter/Space activates; `aria-current="page"` marks the current item.
+- **Notes**: typeahead matches labels; selection patterns are app-owned; async loading listens for toggle/activate and updates `items`/`openIds`.
 - **Custom properties**: `--uik-component-tree-view-item-*`, `--uik-component-tree-view-indent`, `--uik-component-tree-view-text-*`, `--uik-component-tree-view-toggle-fg`.
 
 ### `<uik-nav>`
@@ -152,14 +291,34 @@ Ensure your app imports tokens before Tailwind so the theme variables exist:
 - **A11y**: renders links inside a `<nav>` element with `aria-current="page"` for the active item.
 - **Custom properties**: `--uik-component-nav-item-*`, `--uik-component-nav-indent`, `--uik-component-nav-text-*`, `--uik-component-nav-toggle-fg`.
 
+### `<uik-nav-rail>`
+
+- **Attributes/props**: `items` (array), `activeId`, `orientation` (`vertical | horizontal`).
+- **Slots**: none.
+- **Parts**: `base`, `item`, `item-button`, `item-indicator`, `item-icon`.
+- **Events**: `nav-rail-select`.
+- **A11y**: toolbar role with roving focus; Arrow/Home/End move focus; Enter/Space activate items.
+- **Custom properties**: `--uik-component-nav-rail-bg`, `--uik-component-nav-rail-fg`, `--uik-component-nav-rail-width`, `--uik-component-nav-rail-gap`, `--uik-component-nav-rail-padding-y`, `--uik-component-nav-rail-item-size`, `--uik-component-nav-rail-item-indicator-bg`, `--uik-component-nav-rail-item-indicator-radius`, `--uik-component-nav-rail-item-indicator-width`, `--uik-component-nav-rail-icon-size`.
+
 ### `<uik-popover>`
 
 - **Attributes/props**: `open`, `placement` (`bottom-start | bottom | bottom-end | top-start | top | top-end`), `popover` (`auto | manual | hint`).
 - **Slots**: `trigger`, default slot for panel content.
 - **Parts**: `control` (trigger wrapper), `base` (panel).
-- **Events**: native events bubble from slotted trigger; panel listens for `toggle` when supported.
+- **Events**: native events bubble from slotted trigger; panel listens for `toggle` when supported; `overlay-close` (`detail: {reason}`) with `escape | outside | programmatic | toggle`.
 - **A11y**: forwards `aria-label`/`aria-labelledby`/`aria-describedby` to the panel.
 - **Behavior**: uses the Popover API when available; falls back to a positioned panel in Shadow DOM.
+- **Custom properties**: `--uik-component-popover-bg`, `--uik-component-popover-fg`, `--uik-component-popover-border`, `--uik-component-popover-radius`, `--uik-component-popover-padding-x`, `--uik-component-popover-padding-y`, `--uik-component-popover-shadow`, `--uik-component-popover-offset`.
+
+### `<uik-pagination>`
+
+- **Attributes/props**: `page`, `page-count`, `total`, `max-buttons`, `aria-label`, `aria-labelledby`.
+- **Slots**: `summary`.
+- **Parts**: `base`, `list`, `item`, `button`, `summary`, `ellipsis`.
+- **Events**: `pagination-change` (`detail: {page}`).
+- **Usage**: pair with tables or list views and drive `page`, `page-count`, and `total` from your data source; override `summary` for ranges like `1-20 of 240`.
+- **A11y**: `aria-current="page"` marks the active page; label the nav with `aria-label`/`aria-labelledby`.
+- **Custom properties**: `--uik-component-pagination-*`.
 
 ### `<uik-progress>`
 
@@ -176,7 +335,7 @@ Ensure your app imports tokens before Tailwind so the theme variables exist:
 - **Parts**: `base`, `control`, `label`, `hint`, `error`.
 - **Events**: native `change` bubbles from the internal `<input>`.
 - **A11y**: label slot or `aria-label`; hint/error slots are announced via `aria-describedby`.
-- **Forms**: form-associated; when inside `uik-radio-group`, the group manages the submitted value.
+- **Forms**: form-associated; when inside `uik-radio-group`, the group manages the submitted value (see Form association fallback).
 - **Custom properties**: `--uik-component-radio-accent`, `--uik-component-radio-size`.
 
 ### `<uik-radio-group>`
@@ -187,7 +346,7 @@ Ensure your app imports tokens before Tailwind so the theme variables exist:
 - **Events**: native `change` bubbles from child radios.
 - **A11y**: label slot wires to `aria-labelledby`; hint/error are announced via `aria-describedby`.
 - **Keyboard**: arrow keys move selection within the group.
-- **Forms**: form-associated via `ElementInternals`.
+- **Forms**: form-associated via `ElementInternals` when available (see Form association fallback).
 - **Custom properties**: `--uik-component-radio-group-gap`.
 
 ### `<uik-separator>`
@@ -196,6 +355,16 @@ Ensure your app imports tokens before Tailwind so the theme variables exist:
 - **Events**: none; presentational.
 - **Styling hooks**: token-driven color, `part="base"`. Horizontal renders as `<hr>`, vertical as `role="separator"`.
 
+### `<uik-resizable-panels>`
+
+- **Attributes/props**: `orientation` (`horizontal | vertical`), `startSize`, `minStartSize`, `minEndSize`, `step`, `stepLarge` (px).
+- **Slots**: `start`, `end`.
+- **Parts**: `base`, `panel-start`, `panel-end`, `handle`, `handle-grip`.
+- **Events**: `resizable-panels-resize` (`detail: {startSize, endSize, ratio, source, phase}`).
+- **A11y**: handle uses `role="separator"` with keyboard resizing and `aria-valuenow`; label defaults to "Resize panels" unless `aria-label`/`aria-labelledby` is set.
+- **Motion/contrast**: handle transitions use motion tokens; forced-colors uses system colors.
+- **Custom properties**: `--uik-component-resizable-panels-panel-min-size`, `--uik-component-resizable-panels-panel-start-size`, `--uik-component-resizable-panels-handle-hit`, `--uik-component-resizable-panels-handle-size`, `--uik-component-resizable-panels-handle-bg`, `--uik-component-resizable-panels-handle-hover-bg`, `--uik-component-resizable-panels-handle-active-bg`, `--uik-component-resizable-panels-handle-radius`, `--uik-component-resizable-panels-step`, `--uik-component-resizable-panels-step-lg`.
+
 ### `<uik-select>`
 
 - **Attributes/props**: `name`, `value`, `disabled`, `required`, `invalid`.
@@ -203,7 +372,7 @@ Ensure your app imports tokens before Tailwind so the theme variables exist:
 - **Parts**: `base`, `control`, `label`, `hint`, `error`.
 - **Events**: native `change` bubbles from the internal `<select>`.
 - **A11y**: label slot or `aria-label`; hint/error slots are announced via `aria-describedby`.
-- **Forms**: form-associated via `ElementInternals`.
+- **Forms**: form-associated via `ElementInternals` when available (see Form association fallback).
 - **Custom properties**: `--uik-component-select-base-*` (bg, border-default, border-hover, border-focus, fg, padding-x, padding-y, radius, shadow, font-size, line-height).
 
 ### `<uik-spinner>`
@@ -235,7 +404,7 @@ Ensure your app imports tokens before Tailwind so the theme variables exist:
 - **Parts**: `base`, `control`, `track`, `thumb`, `label`, `hint`, `error`.
 - **Events**: native `change` bubbles from the internal `<input>`.
 - **A11y**: `role="switch"` plus label slot or `aria-label`.
-- **Forms**: form-associated and participates in `FormData` when checked.
+- **Forms**: form-associated and participates in `FormData` when checked (see Form association fallback).
 - **Custom properties**: `--uik-component-switch-height`, `--uik-component-switch-width`, `--uik-component-switch-padding`, `--uik-component-switch-thumb-size`, `--uik-component-switch-thumb-bg`, `--uik-component-switch-thumb-shadow`, `--uik-component-switch-track-bg-default`, `--uik-component-switch-track-bg-checked`, `--uik-component-switch-track-border-default`, `--uik-component-switch-track-border-checked`.
 
 ### `<uik-text>`
@@ -252,7 +421,7 @@ Ensure your app imports tokens before Tailwind so the theme variables exist:
 - **Parts**: `base`, `control`, `label`, `hint`, `error`.
 - **Events**: native `input` and `change` bubble from the internal `<textarea>`.
 - **A11y**: label slot or `aria-label`; hint/error slots are announced via `aria-describedby`.
-- **Forms**: form-associated via `ElementInternals`.
+- **Forms**: form-associated via `ElementInternals` when available (see Form association fallback).
 - **Custom properties**: `--uik-component-textarea-base-*` (bg, border-default, border-hover, border-focus, fg, placeholder, padding-x, padding-y, radius, shadow, font-size, line-height, min-height).
 
 ### `<uik-tooltip>`
@@ -260,7 +429,9 @@ Ensure your app imports tokens before Tailwind so the theme variables exist:
 - **Attributes/props**: `open`, `placement`, `popover` (defaults to `popover="hint"`).
 - **Slots**: `trigger`, default slot for tooltip content.
 - **Parts**: `control` (trigger wrapper), `base` (panel).
+- **Events**: `overlay-close` (`detail: {reason}`) with `escape | outside | programmatic | toggle`.
 - **A11y**: panel uses `role="tooltip"` and wires `aria-describedby` onto the trigger.
+- **Custom properties**: `--uik-component-tooltip-bg`, `--uik-component-tooltip-fg`, `--uik-component-tooltip-radius`, `--uik-component-tooltip-padding-x`, `--uik-component-tooltip-padding-y`, `--uik-component-tooltip-shadow`, `--uik-component-tooltip-offset`.
 
 ### `<uik-visually-hidden>`