@epam/ai-dial-ui-kit 0.15.0-dev.5 → 0.15.0-dev.50

package/README.md

@@ -26,6 +26,7 @@ The AI DIAL UI Kit is an production-ready React component library designed to st
   - [Development Setup](#development-setup)
   - [Project Structure](#project-structure)
 - [🎨 Theming & Customization](#-theming--customization)
+  - [Public class names](#public-class-names)
 - [♿ Accessibility](#-accessibility)
   - [Naming icon-only controls](#naming-icon-only-controls)
   - [Target size (WCAG 2.5.5, Level AAA)](#target-size-wcag-255-level-aaa)
@@ -48,7 +49,7 @@ The AI DIAL UI Kit is an production-ready React component library designed to st
 - 🎨 **Highly Customizable**: Deep theming capabilities with CSS custom properties
 - 🧪 **Well-Tested**: Comprehensive test coverage (70%+) with Vitest and React Testing Library
 - 📚 **Storybook Ready**: Includes interactive component documentation and development playground
-- 🛠️ **Developer Experience**: Leverage ESLint, Prettier, Husky for maintainable code quality
+- 🛠️ **Developer Experience**: Leverage ESLint and Prettier for maintainable code quality
 - 📦 **Distribution Ready**: Deployed as NPM package ready for easy integration
 
 ## 📖 Documentation
@@ -192,6 +193,196 @@ These are defaults, not overrides: a `rounded-*` utility passed to a single
 control through `className` still wins, because a consumer's utilities are
 emitted after this package's stylesheet.
 
+#### Overlay stacking
+
+Overlays render in a portal at the end of `<body>`, so they stack against the
+host's own fixed and sticky chrome — a header, a side sheet, an embedding
+overlay. They sit on a four-step ladder driven by one variable:
+
+| Layer             | Utility                 | `z-index`                  | Components                                                       |
+| ----------------- | ----------------------- | -------------------------- | ---------------------------------------------------------------- |
+| Popup             | `z-popup`               | `var(--z-overlay, 52)`     | `Popup` backdrop, both generations                               |
+| Floating panel    | `z-floating`            | `--z-overlay` + 1          | `Dropdown` and `Select` overlays, submenus, `Calendar`           |
+| Interactive panel | `z-interactive-tooltip` | `--z-overlay` + 2          | `InteractiveTooltip`                                             |
+| Tooltip           | `z-tooltip`             | `--z-overlay` + 3          | `Tooltip`, both generations                                      |
+
+To lift every overlay above a host layer, set the base once:
+
+```css
+:root {
+  --z-overlay: 1000; /* popup 1000, dropdown 1001, interactive tooltip 1002, tooltip 1003 */
+}
+```
+
+Each layer is a fixed step above the one below, so raising the base never
+reorders them: a dropdown still opens above the popup it sits in, and a tooltip
+above the dropdown row that triggered it. Set the variable on `:root`, or in the
+class a `ThemeScope` re-applies to its portalled overlays — a portal escapes any
+other wrapper, so a value set only there never reaches the overlay.
+
+A single overlay can still be moved on its own: a `z-*` utility passed to a
+`Dropdown`'s `listClassName`, a `Popup`'s `overlayClassName`, an
+`InteractiveTooltip`'s `contentClassName` or a `Calendar`'s `panelClassName`
+replaces the layer's own step rather than landing beside it, because
+`mergeClasses` knows the ladder utilities are z-index.
+
+### Public class names
+
+Some hosts need to restyle a part of a component the props do not reach — the
+padding of a menu's row list, the radius of a row, the caret badge of an icon
+trigger. The kit's own classes are Tailwind utilities and hashed module locals,
+so a host that reaches for them ends up on selectors that break on the next
+upgrade: `[class*='_selectedItem_']`, `> div:nth-child(2) > button`,
+`[role='none'][aria-label='dropdown']` — the last of which is an accessibility
+contract and, being a plain English string, is not one a localised host can rely
+on either.
+
+Every design-system 2.0 component therefore stamps a stable class on the element
+that draws it. They are exported as one record:
+
+```tsx
+import { DIAL_KIT_CLASS } from '@epam/ai-dial-ui-kit';
+
+DIAL_KIT_CLASS.menuItem; // 'dial-kit-menuitem'
+```
+
+```css
+.dial-kit-dropdown-list {
+  padding-block: 0;
+}
+
+.dial-kit-menuitem {
+  border-radius: 8px;
+}
+```
+
+Nothing in `dist/index.css` selects on them: they carry no declarations of their
+own and exist only as selectors, so a host's rule needs no `!important` it would
+not otherwise need. Renaming one, or moving it to a different element, is a
+breaking change and goes through the migration-guide process.
+
+#### Feedback and status
+
+| Key             | Class                     | Element                                                                                  |
+| --------------- | ------------------------- | ---------------------------------------------------------------------------------------- |
+| `spinner`       | `dial-kit-spinner`        | The `role="status"` root of a `Spinner`                                                  |
+| `progressBar`   | `dial-kit-progress-bar`   | The outermost element of a `ProgressBar` — its wrapper, or the track when it has neither label nor readout |
+| `skeleton`      | `dial-kit-skeleton`       | The root of a `Skeleton`                                                                 |
+| `notification`  | `dial-kit-notification`   | The `Notification` surface, including every toast and section-message wrapper             |
+| `noDataContent` | `dial-kit-no-data-content` | The empty-state root of `NoDataContent`                                                 |
+| `transferQueue` | `dial-kit-transfer-queue` | The `role="status"` panel of a `TransferQueue`: header, rows and aggregate bar           |
+
+#### Text
+
+| Key             | Class                     | Element                                                             |
+| --------------- | ------------------------- | ------------------------------------------------------------------- |
+| `highlight`     | `dial-kit-highlight`      | The text element of a `Highlight`                                   |
+| `captionText`   | `dial-kit-caption-text`   | The caption line under a field                                      |
+| `errorText`     | `dial-kit-error-text`     | A caption in its error variant, additive to `captionText`           |
+| `label`         | `dial-kit-label`          | The `Label` root, wrapping its `label` element and its info button   |
+
+#### Containers
+
+| Key                  | Class                             | Element                                                              |
+| -------------------- | --------------------------------- | -------------------------------------------------------------------- |
+| `cardShell`          | `dial-kit-card-shell`             | The `article` element of a `CardShell`                               |
+| `collapsibleSidebar` | `dial-kit-collapsible-sidebar`    | The `aside` element of a `CollapsibleSidebar`                        |
+| `resizableContainer` | `dial-kit-resizable-container`    | The content box inside a `ResizableContainer`'s resize frame         |
+| `popup`              | `dial-kit-popup`                  | The `role="dialog"` panel of a `Popup`                               |
+| `bottomSheet`        | `dial-kit-bottom-sheet`           | The `role="dialog"` panel of a `BottomSheet`                         |
+| `sideDrawer`         | `dial-kit-side-drawer`            | The `role="dialog"` panel of a `SideDrawer`, open or closed          |
+| `confirmationPopup`  | `dial-kit-confirmation-popup`     | A `ConfirmationPopup`'s panel, additive to `popup`                   |
+| `accordion`          | `dial-kit-accordion`              | The root of an `Accordion`                                           |
+| `folderPath`         | `dial-kit-folder-path`            | The breadcrumb root of a `FolderPath`                                |
+| `breadcrumbs`        | `dial-kit-breadcrumbs`            | The `nav` element of a `Breadcrumbs` trail                           |
+| `breadcrumbsItem`    | `dial-kit-breadcrumbs-item`       | One segment of it: the link, button or span that draws the label     |
+
+#### Menus and overlays
+
+| Key                 | Class                             | Element                                                                                          |
+| ------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------ |
+| `dropdown`          | `dial-kit-dropdown`               | The trigger wrapper of a `Dropdown`                                                              |
+| `dropdownList`      | `dial-kit-dropdown-list`          | The `role="none"` item list inside a dropdown overlay, and a submenu's own list. Both generations |
+| `menuItem`          | `dial-kit-menuitem`               | One overlay row: a dropdown item, a `Select` option, a submenu trigger or child                   |
+| `menuItemCheck`     | `dial-kit-menuitem-check`         | The trailing check of a chosen `MenuItemMark.Check` row                                          |
+| `dropdownIcon`      | `dial-kit-dropdown-icon`          | The primary icon of a `DialDropdownIcon` trigger                                                 |
+| `dropdownIconCaret` | `dial-kit-dropdown-icon-caret`    | Its caret badge. Absent when `showCaret` is `false`                                              |
+| `tooltip`           | `dial-kit-tooltip`                | The bubble of a `Tooltip`                                                                        |
+| `interactiveTooltip` | `dial-kit-interactive-tooltip`   | The panel of an `InteractiveTooltip`                                                             |
+| `ellipsisTooltip`   | `dial-kit-ellipsis-tooltip`       | The text element of an `EllipsisTooltip`, which is also its trigger                              |
+
+#### Fields
+
+| Key                    | Class                                 | Element                                                        |
+| ---------------------- | ------------------------------------- | -------------------------------------------------------------- |
+| `search`               | `dial-kit-search`                     | The `Search` field box, additive to `dial-kit-input`           |
+| `passwordInput`        | `dial-kit-password-input`             | The `PasswordInput` field box, additive to `dial-kit-input`    |
+| `numberInput`          | `dial-kit-number-input`               | The `NumberInput` field box, additive to `dial-kit-input`      |
+| `tagInput`             | `dial-kit-tag-input`                  | The `TagInput` field box, additive to `dial-kit-input`         |
+| `autocompleteTagInput` | `dial-kit-autocomplete-tag-input`     | The `AutocompleteTagInput` field box, additive to `dial-kit-input` |
+| `select`               | `dial-kit-select`                     | The root of a `Select`                                         |
+| `inlineSelect`         | `dial-kit-inline-select`              | The trigger button of an `InlineSelect`                        |
+| `calendar`             | `dial-kit-calendar`                   | The root of a `Calendar`, in every mode                        |
+| `schemaRenderer`       | `dial-kit-schema-renderer`            | The root of a `SchemaRenderer`                                 |
+| `schemaRendererSection` | `dial-kit-schema-renderer-section`   | One collapsible `SchemaRenderer` section card, at any depth    |
+| `fileDropzone`         | `dial-kit-file-dropzone`              | The drop area of a `FileDropzone`                              |
+| `fileIcon`             | `dial-kit-file-icon`                  | The root of a `FileIcon`: glyph or spinner, and the shared badge |
+| `fileName`             | `dial-kit-file-name`                  | The row of a `FileName`: its type icon, the name and any details |
+| `folderName`           | `dial-kit-folder-name`                | The `FileName` row of a `FolderName`, additive to `fileName` |
+| `sharedEntityIndicator` | `dial-kit-shared-entity-indicator`   | The badge of a `SharedEntityIndicator`, including the one on a `FileIcon` |
+| `badge`                | `dial-kit-badge`                      | The root of a `Badge`: the label box, with its icon when it has one |
+| `avatar`               | `dial-kit-avatar`                     | The root of an `Avatar`: the image, or the initials box that replaces it |
+| `entityIdentity`         | `dial-kit-entity-identity`              | The root row of an `EntityIdentity`: icon, type label, name and version |
+| `radioGroupPopupField` | `dial-kit-radio-group-popup-field`    | The root of a `RadioGroupPopupField`                           |
+
+#### Controls
+
+| Key                    | Class                                 | Element                                                    |
+| ---------------------- | ------------------------------------- | ---------------------------------------------------------- |
+| `switch`               | `dial-kit-switch`                     | The row of a `Switch`: the control and its label           |
+| `checkbox`             | `dial-kit-checkbox`                   | The row of a `Checkbox`                                    |
+| `checkboxBox`          | `dial-kit-checkbox-box`               | The decorative box a `CheckboxBox` draws                   |
+| `radio`                | `dial-kit-radio`                      | The row of a `Radio`                                       |
+| `radioGroup`           | `dial-kit-radio-group`                | The root of a `RadioGroup`                                 |
+| `segmentedControl`     | `dial-kit-segmented-control`          | The `role="radiogroup"` track of a `SegmentedControl`       |
+| `segmentedControlItem` | `dial-kit-segmented-control-item`     | One segment of it                                          |
+| `tabs`                 | `dial-kit-tabs`                       | The outermost element of a `Tabs` — the heading wrapper, or the tab list when there is no `sectionLabel` |
+| `tabList`              | `dial-kit-tab-list`                   | The `role="tablist"` inside it, in either orientation      |
+| `tab`                  | `dial-kit-tab`                        | One tab inside it                                          |
+| `tabSelected`          | `dial-kit-tab-selected`               | The selected tab, in either orientation                    |
+| `tabsSectionLabel`     | `dial-kit-tabs-section-label`         | The `sectionLabel` heading above a `Tabs`                  |
+| `tag`                  | `dial-kit-tag`                        | A `Tag` pill, including a `TagInput`'s rows                |
+| `filterChips`          | `dial-kit-filter-chips`               | The `role="group"` row of a `FilterChips`; its chips carry `dial-kit-tag` |
+| `toggleIconButton`     | `dial-kit-toggle-icon-button`         | A `ToggleIconButton`, additive to `dial-kit-base-icon-button` |
+| `closeButton`          | `dial-kit-close-button`               | A `CloseButton`, additive to `dial-kit-base-icon-button`    |
+| `infoButton`           | `dial-kit-info-button`                | An `InfoButton`, additive to `dial-kit-base-icon-button`    |
+| `buttonDropdown`       | `dial-kit-button-dropdown`            | The wrapper of a `ButtonDropdown`                          |
+
+#### Components with no entry, and why
+
+Some 2.0 components are deliberately absent, because the element a host would
+target already carries a stable class:
+
+| Component                                     | Target it already |
+| --------------------------------------------- | ----------------- |
+| `Button` and its six variant wrappers         | `dial-kit-base-button` (plus a per-variant class such as `dial-kit-primary-solid-button`) |
+| `IconButton` and its five variant wrappers    | `dial-kit-base-icon-button` |
+| `FabButton`                                   | `dial-kit-fab-button` |
+| `Input`                                       | `dial-kit-input` |
+| `Textarea`                                    | `dial-kit-textarea` |
+| `Slider`                                      | `dial-kit-slider` |
+| `MarkdownEditor`                              | `dial-kit-markdown-editor` |
+| `Grid`                                        | `dial-kit-grid` (exported as `GRID_ROOT_CLASS`) |
+
+Four more contribute no element of their own, and are addressed through what
+they render: `ThemeScope` (a `display: contents` wrapper), `MultiSelectTags`
+(`Tag`s), and `TooltipContainer` / `TooltipTrigger`.
+
+Two neighbouring elements are reached through props instead, and keep being: a
+`Dropdown`'s floating panel takes `listClassName`, a `Popup`'s backdrop takes
+`overlayClassName`, and the `DialDropdownIcon` trigger button takes
+`buttonClassName`.
+
 ## ♿ Accessibility
 
 ### Naming icon-only controls
@@ -232,6 +423,8 @@ not AAA:
 | `Radio` circle | 20×20 rendered | Reaches 24×24 through `dial-kit-minimum-target`; a 44px target would overhang 12px per side and swallow the adjacent label. Clicking the label selects the radio, so the practical target is wider |
 | `Checkbox` box | 20×20 rendered | Reaches 24×24 through `dial-kit-minimum-target`; a 44px target would overhang 12px per side and swallow the adjacent label. Clicking the label toggles the checkbox, so the practical target is wider |
 | `Slider` track row | 24px tall | The pointer target spans the full track width but is only 24px tall; a 44px row would add 20px of dead space to every form the slider sits in, and the thumb is dragged rather than tapped |
+| `Breadcrumbs` segment link | content | Exempt under the 2.5.5 *Inline* exception — a segment is a text link in a line of text, and expanding it would overlap the segments beside it |
+| `Breadcrumbs` overflow button | 16×16 rendered | Reaches 24×24 through `dial-kit-minimum-target`; a 44px target would overhang 14px per side and swallow the segments on either side of it in an inline trail |
 | `SegmentedControl` segment | 32px tall | Sits 4px from its neighbours inside a 40px track, so a 44px target would overhang 6px per side and swallow the adjacent segments; the segment is already wider than 24px on both axes |
 | `ResizableContainer` resize handle | 10px wide pointer strip | The handle has to sit exactly on the panel boundary, so a 44px-wide strip would swallow content on both sides of it — essential to the control. It is a focusable `separator`, so the resize is also available from the keyboard with the arrow keys |
 

package/dist/CHANGELOG.md

@@ -7,6 +7,92 @@ Versions match the git tags on the `development` branch.
 
 ---
 
+## [0.15.0]
+
+### Breaking Changes
+
+- **Legacy theme variable fallbacks removed** — 0.14.0 renamed several theme variables but kept the old names in the fallback chain, so every token resolved two variables and a theme could set either. The old names are no longer read: `--bg-control-neutral-hover` → `--bg-control-neutral-hover-muted`, `--stroke-focus-black` → `--stroke-focus`, and `--bg-control-accent-gradient-from` / `-to` / `-hover-from` / `-active-to` → `--bg-gradient-1` / `-2` / `-1-hover` / `-2-active`. A theme that still sets an old name falls back to the kit's default colour; rename the variable.
+  See [migration guide](migration-guides/0.15.0/legacy-theme-variable-fallbacks-removal.md).
+
+- **`Slider` (2.0) — redrawn thumb and track** — the slider now follows the new 2.0 design: a 12px solid accent thumb (was a 16px white disc with a border) that grows a soft halo on hover, focus and drag, over an accent-tint track (was grey). The props are unchanged, so typecheck cannot flag it, but every `Slider` renders differently and host CSS aimed at the old thumb needs a second look. The 24px pointer row and the `dial-kit-slider` class stay as they were.
+  See [migration guide](migration-guides/0.15.0/slider-redesign.md).
+
+### Added
+
+- **`Slider` (2.0) — `showTooltip`, `showTicks`, `leftContent`, `rightContent`** — the rest of the new slider design. `showTooltip` shows the formatted value in a bubble above the thumb; `showTicks` marks every step on the unfilled track for a discrete slider. Both are hidden while disabled. The bubble is `aria-hidden`, because the input already announces the value through `aria-valuetext`. `leftContent` and `rightContent` are the slider container's side slots, centred on the track: an icon on the left, a `NumberInput` or the value as text on the right. The kit does not sync a `NumberInput` placed there; the caller passes it the same `value` and setter. All four are opt-in.
+
+- **`SchemaRenderer` (2.0)** — a JSON Schema form built only from 2.0 controls. `DialSchemaRenderer` exists only in 1.0, so a 2.0 screen that renders a schema-driven form had to mix in 1.0 inputs, selects and the 1.0 `Dropdown` surface. The 2.0 renderer keeps the 1.0 props, except `jsonEditorTheme`: the three variants, `oneOf`/`anyOf` with select or radio selectors, arrays with discriminator types, key-value maps, `dial:resource` options, `skipUntouched`, `renderField` and `texts`. Primitives render as `Input`, `NumberInput`, `PasswordInput`, `Select`, `Switch` or `RadioGroup`. Values the schema does not describe are edited as JSON in a monospace `Textarea`, not in Monaco, so the form loads no editor bundle. Section headers are real toggle buttons with `aria-expanded`, and the remove and info buttons sit next to the toggle instead of inside it. Every control has an accessible name, including array items and key-value rows. `renderField` replaces only the control, so the field keeps its label and error. Stamps `DIAL_KIT_CLASS.schemaRenderer` (`dial-kit-schema-renderer`) on the root and `DIAL_KIT_CLASS.schemaRendererSection` (`dial-kit-schema-renderer-section`) on each section card. The schema types, enums and utils are shared with 1.0 from neutral modules; the 1.0 import paths still work. Additive.
+
+- **`AutocompleteTagInput` (2.0)** — a tag field that suggests values while typing and still accepts its own. `TagInput` takes only free text and a multiple `Select` only listed values, so a field such as a list of MIME types — where the common ones should be one keystroke away but any `<type>/<subtype>` is valid — had to be hand-built in each app (the DIAL admin's attachment types, the QuickApps editor's). Typing lists up to `maxSuggestions` (default 5) of the `suggestions` whose label, value or description contains the text and which are not already tags; Enter or comma adds the highlighted one, or the typed text when nothing matches; the arrow keys move the highlight, Escape and leaving the field close the list, Backspace on an empty input removes the last tag. The input follows the ARIA combobox pattern and keeps focus while the list is open, the list floats on the `z-floating` layer and takes the field's width, and the tags share the multiple `Select`'s look. `getRemoveTagLabel` names each tag's remove button, so a localised host is not left with the English `Remove <tag>`. Stamps `DIAL_KIT_CLASS.autocompleteTagInput` (`dial-kit-autocomplete-tag-input`) on the field. Additive; nothing else changes.
+
+- **Public class names on every design-system 2.0 component** — a host embedding the kit had no honest selector for the parts of a component its props do not reach: the kit's own classes are Tailwind utilities and hashed module locals, so hosts were left on `[class*='_selectedItem_']`, `> div:nth-child(2) > button` and `[role='none'][aria-label='dropdown']` — the last an accessibility contract, and a plain English string a localised host cannot rely on. Every 2.0 component now stamps a stable class on the element that draws it, exported as one record: `DIAL_KIT_CLASS.menuItem` is `'dial-kit-menuitem'`, and so on for 48 elements across the feedback components (`Spinner`, `ProgressBar`, `Skeleton`, `Notification`, `NoDataContent`), the text components (`Highlight`, `CaptionText`/`ErrorText`, `Label`), the containers (`CardShell`, `CollapsibleSidebar`, `ResizableContainer`, `Popup`, `ConfirmationPopup`, `Accordion`, `FolderPath`), the menus and overlays (`Dropdown` and its item list, rows and chosen-row check, `DialDropdownIcon`'s icon and caret badge, `Tooltip`, `InteractiveTooltip`, `EllipsisTooltip`), the fields (`Search`, `PasswordInput`, `NumberInput`, `TagInput`, `Select`, `InlineSelect`, `Calendar`, `FileDropzone`, `RadioGroupPopupField`) and the controls (`Switch`, `Checkbox`, `CheckboxBox`, `Radio`, `RadioGroup`, `SegmentedControl` and its segments, `Tabs` and its tabs, `Tag`, `ToggleIconButton`, `CloseButton`, `InfoButton`, `ButtonDropdown`). `dial-kit-dropdown-list` and `dial-kit-menuitem` are on the 1.0 dropdown family too, since `DialDropdownIcon` opens one.
+
+  Nothing in `dist/index.css` selects on any of them — they carry no declarations and exist only as selectors, so this is not a visual change and a host rule needs no `!important` it would not otherwise need. A row's class sits on the element that draws the row box, which is the wrapper rather than the inner button for a `MenuItem` with a `rightControl`; a `ProgressBar` with neither label nor readout returns its track as its own root, and the class follows it there. Components whose target element already carries a stable `dial-kit-*` class have no entry, because a second name for one thing is worse than none: `Button` and `IconButton` with their variant wrappers, `FabButton`, `Input`, `Textarea`, `Slider`, `MarkdownEditor` and `Grid`. A `Dropdown`'s floating panel, a `Popup`'s backdrop and the `DialDropdownIcon` trigger button keep being reached through `listClassName`, `overlayClassName` and `buttonClassName`. See the README for the full table. Requested in [ai-dial-chat#8707](https://github.com/epam/ai-dial-chat/issues/8707), the counterpart of the `dial-*` classes that issue adds to the chat libraries.
+
+- **Overlay stacking token, `--z-overlay`** — every portalled overlay was a hardcoded Tailwind literal (`z-[52]` for the `Popup` backdrop, `z-[53]` for dropdown and select overlays, submenus and the `Calendar`, `z-[54]` for `InteractiveTooltip`, `z-[55]` for `Tooltip`), so a host whose own overlay or sticky header sits higher had no documented way to lift the kit's menus above it and fell back to `[role='menu']` and `z-[52]` overrides. The four layers are now theme steps — `z-popup`, `z-floating`, `z-interactive-tooltip`, `z-tooltip` — computed from one variable as base, +1, +2 and +3, so setting `--z-overlay` on `:root` (or in a `ThemeScope` class) moves the whole ladder without reordering it. The fallback is `52`, which reproduces today's values exactly: a host that sets nothing sees no change. `mergeClasses` registers the four steps as z-index, so a `z-*` a caller passes through `listClassName`, `overlayClassName`, `contentClassName` or `panelClassName` still replaces the layer's step rather than landing beside it. See the README's _Overlay stacking_ section. Requested in [ai-dial-chat#8943](https://github.com/epam/ai-dial-chat/issues/8943).
+
+- **`Dropdown` (2.0) — `listStyle`** — the floating panel renders in a portal at the end of `<body>`, so CSS custom properties a caller sets on its own wrapper never reach the panel's rows or `menuHeader`, and `listClassName` can carry a class but not a runtime value. A wrapping component that themes its menu through `var(--…)` — a composer's model picker colouring its selected row and check — had no way to deliver the values. `listStyle` is an inline style on that panel. Positioning stays the dropdown's own: `floatingStyles` is applied on top, so a caller's `position`, `top` or `transform` cannot unanchor it. Additive; nothing renders differently without it. Requested in [ai-dial-chat#8943](https://github.com/epam/ai-dial-chat/issues/8943).
+
+- **`ButtonDropdown` (2.0) — `dropdownProps`**: until now `ButtonDropdown` built its menu `Dropdown` with fixed options, so a caller could neither class the menu panel nor stop the panel from taking the button's width. A short label like "Add" produced a menu as narrow as the button. `dropdownProps` forwards `listClassName` and `matchReferenceWidth` to that `Dropdown`. With `matchReferenceWidth: false` and a `min-w-*` class, the menu gets a width of its own. Additive; a `ButtonDropdown` without it renders exactly as before.
+
+- **`Notification` (2.0) — `action` slot** — a notification had nowhere to put a control of its own: a "Try again" or "Reload" button had to be packed into `message`, where it sat inside the text column, wrapped with the copy and could not line up against a title. `action` takes any node and renders it at the inline end of the notification, after the text and before the close button, vertically centred and never shrunk by a long message. It sits inside the live region, so the control is reachable right where the error is announced; the caller supplies its visible label and handler. The slot is additive — a notification without `action` renders exactly as before. Requested in [ai-dial-chat#8979](https://github.com/epam/ai-dial-chat/issues/8979), where a failed chat response offers "Try again" inside its error banner.
+
+- **`FilterChips` (2.0)** — a row of filter chips that picks one value out of a few, the chip-shaped sibling of `Tabs` and `SegmentedControl`. It draws `TagAppearance.Selectable` tags: no fill until selected, a semibold label once selected. Each chip is a toggle button carrying its state on `aria-pressed` inside a named `role="group"`, so every chip is its own tab stop and arrowing across the row never changes the filter by accident — unlike a `radiogroup`. `stretch` grows the chips to share the row width equally for a filter row spanning a side panel; without it they hug their labels. There is no disabled chip: an option the user must not pick is left out of `items`. Labels carry no English defaults, so the caller translates them. The row carries the public class `dial-kit-filter-chips` (`DIAL_KIT_CLASS.filterChips`); its chips are `Tag` pills, so they carry `dial-kit-tag`.
+
+- **`Tabs` — `tabListClassName`, and a public class on the selected tab** — `className` lands on whichever element is outermost, so a `Tabs` with a `sectionLabel` left its `role="tablist"` unreachable: a caller wanting to repad the list had to choose between that and styling the wrapper. `tabListClassName` reaches the list in either case, and is additive to `className` when there is no heading and the two elements are one. The selected tab now also carries `dial-kit-tab-selected` (`DIAL_KIT_CLASS.tabSelected`) in both orientations, additive to `dial-kit-tab` — a wrapping component could mark a tab but not its selection, since the horizontal row's `dial-kit-tab-selected-underline` carries the gradient rule and the vertical rail draws its selection in Tailwind utilities alone. Like every entry in the record it carries no declarations. Both are additive: nothing renders differently.
+
+- **`Breadcrumbs` (2.0)** — the navigation trail of the 2.0 generation, and the first one built without `DialBreadcrumb` underneath it. `items` is a flat list, outermost first; the last entry is the current page, drawn semibold and primary with `aria-current="page"` and never rendered as a control, since a link to the page you are already on does nothing. An earlier entry with an `href` renders as a link, one with only an `onClick` as a button, and one with neither as plain text — the read-only location path, without a separate component for it. The trail never wraps: segments truncate, each revealing its full label through `EllipsisTooltip` only once it is actually clipped, and a trail longer than `maxVisibleItems` (4) collapses its middle into an ellipsis `Dropdown` so the root and the current page always stay on screen. Separators are decorative and `aria-hidden`, so the trail is announced as a list of links rather than a string of chevrons; the chevron mirrors itself in RTL. `ariaLabel` and `overflowAriaLabel` default to English and take an override for translation. `size` picks the trail's type scale: `BreadcrumbsSize.Small` (`dial-small-text`) by default, or `BreadcrumbsSize.Heading` (`dial-h2-text`) for a path that doubles as the page title — that token is semibold on its own, so the heading trail is semibold throughout, the current page included, and there is no `dial-h2-semi-text` to reach for. The `nav` carries `dial-kit-breadcrumbs` (`DIAL_KIT_CLASS.breadcrumbs`) and each segment `dial-kit-breadcrumbs-item`. The 1.0 `DialBreadcrumb` is untouched.
+
+- **`FileIcon`, `FileName`, `FolderName` and `SharedEntityIndicator` (2.0)** — the file-manager row pieces of the 2.0 generation, counterparts of `DialFileManagerItemIcon`, `DialFileName`, `DialFolderName` and `DialSharedEntityIndicator`, built without any of them underneath. `FileIcon` draws the new file-type glyphs — one sheet, coloured and marked by kind: images, video, audio, code, text, PDF, spreadsheet, presentation, archive, DIAL and a generic fallback, picked by extension — and a folder glyph of its own, with a shared badge and a `Spinner` while `loading`. The glyphs are inline SVG rather than imported assets, so each one takes its gradient `id` from `useId` — a list of files does not repeat one document-wide id, which blanks every copy's gradient once the first is hidden — and its colours from theme tokens instead of fixed hex. It is a `role="img"` named after the item ("PDF file", "Folder", ", shared" appended when shared; `label` overrides it), where the 1.0 icon called every file "File type icon" and left folders unnamed. `FileName` puts it before a truncating name with an optional `details` line; since the visible name already says what the item is, it hides the icon and announces the shared state through a visually-hidden `sharedLabel` instead, and while `loading` leaves the spinner in the tree so the busy state is still announced. `FolderName` is a `FileName` fixed to the folder type. `SharedEntityIndicator` is the badge on its own, a named `role="img"` whose tooltip is a pointer-only hint. Default icon size is 20px (`DIAL_ICON_SIZE.MD`), where 1.0 used 18px. They carry `dial-kit-file-icon`, `dial-kit-file-name`, `dial-kit-folder-name` (additive to `dial-kit-file-name`) and `dial-kit-shared-entity-indicator`. The 1.0 components are untouched.
+
+- **`TransferQueue` (2.0)** — the floating "Importing 5 files" panel for an upload, download, import or export, moved into the kit from `@epam/ai-dial-conversation-panel`'s `ImportExportQueue` so the file manager can use it for uploads too. It is generic: `items` are `{ id, name, status, percent?, message? }` with `TransferQueueItemStatus` (`InProgress`, `Success`, `Warning`, `Failed`, `Canceled`), not the conversation-transfer job the chat library used. Each row draws the 2.0 `FileIcon` for its name, a truncating name, and a trailing status: a named spinner with a cancel control on hover or focus (only when `onCancelItem` is passed; the spinner never takes the pointer, so the control stays clickable in the same cell), a named check, a warning or error icon whose `message` is both its tooltip and its focusable accessible name — a tooltip alone renders nothing on touch — or "Canceled". The header has the caller's `title` verbatim, a failed-item count badge, and collapse (`aria-expanded`/`aria-controls`) and close controls. Collapsed while work runs, the rows give way to one aggregate `ProgressBar` whose `aria-valuetext` counts settled items rather than a percentage. Closing with work in progress or a failure unread asks for confirmation first; once every item succeeds the queue calls `onClose` by itself after `autoCloseDelay` (8000 ms by default, `0` disables), and a warned or canceled row keeps it open. The root is a polite `role="status"` region carrying `dial-kit-transfer-queue` (`DIAL_KIT_CLASS.transferQueue`); positioning is the host's. Every string has an English default in `DEFAULT_TRANSFER_QUEUE_LABELS` and takes an override through `labels`.
+
+- **`Accordion` (2.0) — `caretPosition`** — the header always drew its caret after the title, pushed to the far edge, and a caller whose design puts it beside the title had no way to ask for that. `caretPosition` takes `AccordionCaretPosition.Start` (before the title, with a gap) or `AccordionCaretPosition.End` (the default, today's placement). A non-collapsible panel still draws no caret. Additive; nothing renders differently without it. Requested in [ai-dial-chat](https://github.com/epam/ai-dial-chat) while moving its hand-rolled disclosures onto `Accordion`.
+
+- **`InlineSelect` (2.0) — `triggerClassName`, `triggerLabelClassName` and `onOpenChange`** — the trigger could not be restyled: `InlineSelect` took no class for it, and a caller whose design puts the value in a bordered pill, themed by its own colour properties, had to keep a hand-rolled trigger beside the kit `Dropdown`. `triggerClassName` is merged onto the trigger button after its own classes, `triggerLabelClassName` onto its label (now a `<span>`, so a type-scale or colour class has something to land on), and `onOpenChange` reports the dropdown opening and closing, for a caller that reacts to it beyond what `aria-expanded` styles. All three are additive; nothing renders differently without them. Requested in [ai-dial-chat](https://github.com/epam/ai-dial-chat) for the share popover's access pill.
+
+- **`InlineSelect` (2.0) — controlled `open`, and `listStyle`** — `onOpenChange` reported the dropdown opening, but the caller could not close it: a popover that owns Escape (closing its own menu first and itself only on a second press) had no way to shut the select without shutting itself. `open` makes the open state controlled, the same way `Dropdown`'s already is; without it the select keeps its own. `listStyle` is passed through to the `Dropdown` overlay, which renders in a portal, so custom properties a caller sets on its own wrapper can reach the rows, as they already can for `Dropdown`. Both are additive; nothing renders differently without them.
+
+- **`BottomSheet` (2.0)** — a panel that slides up from the bottom edge over a dimmed page, the mobile counterpart of `Popup`, moved into the kit from ai-dial-chat's `BottomSheetShell`, which sat inside one feature library and was imported across a library boundary by another. It is built on the same Floating UI pieces as `Popup` rather than on a hand-written focus trap: a portal, a scroll-locking `FloatingOverlay` on the `z-popup` layer, a `FloatingFocusManager` that moves focus to the panel on open, keeps it inside and returns it on close, and `useDismiss`, so Escape, the close button and a press on the backdrop (unless `closeOnOutsideClick` is false) all call `onClose` while `open` stays the caller's. A `title` gives a 60px header with the title centred as an `<h2>` that names the dialog, a close button at the end and, with `onBack`, a back button at the start whose arrow mirrors in RTL; without a title there is no header and `ariaLabel` names the sheet. `backAriaLabel` and `closeAriaLabel` default to English. The body scrolls past 85% of the viewport height. The panel slides in over 300ms (`animate-slideUp`, a new theme animation) and not at all under `prefers-reduced-motion`. The panel carries `dial-kit-bottom-sheet` (`DIAL_KIT_CLASS.bottomSheet`).
+
+- **`Badge` (2.0)** — a short, static label: a topic, a category, or a status that is not a control, moved into the kit from ai-dial-chat's catalog, where `CardTag` and `FeaturedChip` drew two hand-rolled 24px labels. `Tag` is the kit's selectable, dismissable chip at 32px; a badge never responds to the pointer. `BadgeVariant.Outlined` (the default) is the neutral label, bordered on the sunken layer in `dial-tiny-text`; `BadgeVariant.Filled` is a pill in one of the theme's visual colours — `BadgeColor.Blue` (default), `Green`, `Violet`, `Indigo`, `Brown` or `Red` — in the self-uppercasing `dial-caption-lead-semi-text`, so the label is passed in sentence case. `textClassName` replaces the variant's type scale, `icon` adds a decorative icon before the label, and native span attributes pass through. The root carries `dial-kit-badge` (`DIAL_KIT_CLASS.badge`).
+
+- **`Avatar` (2.0)** — a person's or an entity's picture, or its initials on a colour picked from its name, moved into the kit from `@epam/ai-dial-chat-shared`'s `InitialsAvatar` and `@epam/ai-dial-navigation-panel`'s `UserAvatar`, which hosts were each reimplementing. `name` gives the initials (through the newly exported `extractInitials`: 1–2 letters, Unicode-aware, punctuation skipped, `?` when there are none) and a colour pair from the theme's visual tokens — the same name always gets the same colours, and they follow the active theme. `initials` overrides the derived ones. `src` shows an image instead; a missing or broken image falls back to the initials, `onImageError` reports the failure, and a new `src` is tried again. `shape` is `AvatarShape.Circle` for a person (the default) or `AvatarShape.Square` for an application or model. `size` sets the width and height and, unless `textClassName` supplies a type-scale class, a font size of 40% of it. With an `alt` the avatar is a `role="img"` named by it, image or initials alike; without one it is decorative and hidden from assistive technology. The root carries `dial-kit-avatar` (`DIAL_KIT_CLASS.avatar`).
+
+- **`SideDrawer` (2.0)** — a full-height panel that slides in from the inline end over a dimmed page, moved into the kit from ai-dial-chat, where the catalog's `DetailsPanel` and `StandalonePublishPanel` each carried a near-identical copy with its own backdrop, transform transition, `inert` handling and hand-written Tab trap. Neither `Popup` (a centred modal) nor `CollapsibleSidebar` (an inline rail) covered it. It is built on the same Floating UI pieces as `Popup`: a scroll-locking `FloatingOverlay` on `z-popup`, a `FloatingFocusManager` that moves focus to the panel on open and returns it on close, and `useDismiss` for Escape and a press on the backdrop (unless `closeOnOutsideClick` is false), all calling `onClose` while `open` stays the caller's. Unlike `Popup` the panel stays mounted while closed, so it slides out as well as in and keeps the state of what it holds; closed, it is `inert`, the focus manager and scroll lock are off, and the backdrop lets pointer events through. On desktop it is 540px wide with a rounded, bordered leading edge; on mobile it takes the full width; it slides from the end in either writing direction over 300ms, and not at all under `prefers-reduced-motion`. The header follows `Popup`: `onBack` (with `backDisabled`), the title — a string `header` renders an `<h2>` that names the dialog, a node needs `ariaLabel` — then `headerActions` and the close button, which `closeDisabled` disables and `hideClose` leaves out. The panel carries `dial-kit-side-drawer` (`DIAL_KIT_CLASS.sideDrawer`).
+
+- **`BottomSheet` and `SideDrawer` (2.0) — `style` and `overlayStyle`, and `headerClassName` on `BottomSheet`** — both render in a portal at the end of `<body>`, so custom properties a caller sets on its own wrapper never reached the panel, its header or the backdrop, and `className` can carry a class but not a runtime value. A host theming the sheet through `var(--…)` — a panel background, a title colour, a divider, a backdrop tint — had no way to deliver the values. `style` is an inline style on the panel and `overlayStyle` one on the backdrop, merged after its own positioning; `headerClassName` reaches `BottomSheet`'s header row, which `SideDrawer` already exposed. All additive; nothing renders differently without them. Requested in [ai-dial-chat](https://github.com/epam/ai-dial-chat), whose bottom sheets and side panels theme their surfaces through public colour props.
+
+- **`Select` (2.0) — `collapseTagOverflow`, a one-row multi-select with a `+N` counter** — a multi-select could only wrap its tags onto more rows, so a field in a dense form or a table cell grew without bound. `collapseTagOverflow` keeps the tags on one row, as it does on `TagInput`, and folds the ones that do not fit into a `+N` tag; hovering it opens an `InteractiveTooltip` listing the hidden tags, each still removable. The count follows the width the field has, not the number of tags: the tags are taken in order while they fit beside the counter, and it is recomputed on resize. Without the prop the tags wrap as before; the prop is ignored with `customMultiSelectTagsRenderer`, and on a mobile screen the tags wrap, since the panel opens on hover. Additive.
+
+### Changed
+
+- **`StarterButton` (2.0) — a sparkles icon by default** — the design puts a sparkles glyph before every starter label, so each host was passing the same `iconBefore`. `iconBefore` now defaults to a 20px `IconSparkles` at the 1.5 stroke, `aria-hidden`, and stroked with the starter gradient like any other icon. A caller-supplied `iconBefore` replaces it; `iconBefore={null}` keeps a label-only pill. A `StarterButton` that passed no `iconBefore` now draws the icon; no other API changes.
+
+- **`Select` (2.0) — multi-select tags are 24px, and the field wraps them with an 8px gap** — the tags in a multi-select field used the 32px pill of `Tag`, taller than the design's field chip. They are now 24px with a `rounded-md` shape, a `layer-sunken` fill and a `stroke-secondary` rim, and the wrapped field pads 8px vertically with 8px between tags, so one row of tags still fills the 40px field. `Tag` itself is unchanged. Visual only; no API changes.
+
+### Fixed
+
+- **`Textarea` (2.0) — `invalid` no longer reaches the DOM** — the prop was spread onto the `<textarea>`, so React warned about a non-boolean `invalid` attribute on every render. It now only selects the error styling. No visual change.
+
+- **`Dropdown` and `Select` — a submenu closes when its menu or the page scrolls** — a submenu is portalled and repositioned by Floating UI's `autoUpdate`, so scrolling the list that holds its trigger, or the page, left the submenu open and dragged it along after the trigger, even once the trigger had scrolled out of the clipped list. The submenu now closes when an ancestor of its trigger scrolls. Scrolling inside the submenu does not close it. The fix is in the shared submenu hook, so it covers the 2.0 and 1.0 `Dropdown` and `Select` submenus. Reported in [ai-dial-chat#9295](https://github.com/epam/ai-dial-chat/issues/9295), on the catalog's Create menu.
+
+- **`Select` and `Dropdown` (2.0) — rows keep their 40px when the panel is capped** — the rows are `flex-col` items with a fixed height inside a list that scrolls at the panel's height cap, and a flex item shrinks by default: on a short viewport the rows collapsed to their content, with the check boxes squeezed and the focus ring hugging the text. The shared overlay row no longer shrinks.
+
+- **`Button` and `IconButton` (2.0) — a disabled button's tooltip opens** — `tooltipProps` wraps the button in `<Tooltip asChild>`, but a natively `disabled` button receives no pointer or focus events, so its tooltip could never open. That is exactly the state where a "why is this unavailable" hint matters, and callers worked around it with their own `<span>` wrapper, which no keyboard user could reach either. A disabled button that has a visible tooltip is now marked `aria-disabled="true"` instead of `disabled`: it stays in the tab order and answers hover and focus, so the tooltip opens for mouse and keyboard users alike, and it is still announced as unavailable. Its click is swallowed with `preventDefault`, so neither `onClick` nor a `type="submit"` form submission fires. Without a tooltip, or while `hideTooltip` is set, the button stays natively disabled as before. The disabled look is unchanged, since every 2.0 variant already styles `[aria-disabled="true"]`; the two ghost icon-button rules that styled only `:disabled` now style both. Requested in [ai-dial-chat](https://github.com/epam/ai-dial-chat), where the chat-settings dialog explains why "Apply changes" is disabled.
+
+- **`InlineSelectTrigger` (2.0) — a `className` no longer wipes out the trigger's own classes** — the props were spread after the merged `className`, so passing `className` replaced it outright: the trigger lost its padding, pill shape, hover tint and focus ring, and the public `dial-kit-inline-select` class. `className` is now merged after the trigger's own classes, the way every other 2.0 component takes it. The trigger's own `aria-haspopup`, `aria-expanded` and `aria-label` also now win over the same attributes passed as props.
+
+- **`Accordion` (2.0) — the caret follows the reading direction, and the panel slides open and shut** — the collapsed caret pointed right under `dir="rtl"` too, against the reading direction; it now turns to point left in RTL and still points down once open. The content was also mounted only while expanded, so it appeared and vanished in one frame. It now stays mounted and animates its height (`grid-template-rows` 0fr ↔ 1fr, 200 ms, off under `prefers-reduced-motion`); while collapsed it is `inert`, so nothing in it is focusable or announced, and `aria-controls` always points at the region. The 12px gap under the header moved inside the clipped part, so a collapsed panel is exactly as tall as before. A caller that relied on the content unmounting while collapsed (to defer an expensive render, or to reset child state on close) now needs to render it conditionally itself. Requested in [ai-dial-chat](https://github.com/epam/ai-dial-chat) while moving its conversation stages onto `Accordion`.
+
+- **`Select` and `Dropdown` (2.0) — rows are 2px apart, and every option list and submenu has the same vertical inset** — rows were stacked edge to edge, so a selected row's tint and a hovered neighbour's merged into one block; every option list, menu and kit-rendered submenu now stacks its rows with `gap-0.5` (the shared `overlayListClassName`). Separately, the `Dropdown` menu wraps its rows in `py-1` inside the panel's `p-1`, but the `Select` option list and the submenus of both components rendered their rows straight into the panel, so the first and last rows (and the focus ring of a keyboard-focused one) sat flush against its top and bottom edge. The `Select` option list now carries the same `py-1`, and a submenu panel of kit-rendered rows takes `py-2` — the same 8px in total. A `Dropdown` submenu drawn through `renderSubMenu` keeps the plain panel, as a `renderOverlay` body does at the top level.
+
+- **`MarkdownEditor` (2.0) — the live preview is part of the card now, instead of a sheet of GitHub's own CSS laid over it** — the 2.0 restyle covered the card and the toolbar and stopped at the split: everything right of it was still `@uiw/react-md-editor`'s default stylesheet. Three things came out of that. The pane divider was the library's `inset` box-shadow in a hardcoded `#d0d7de`, drawn on the preview and then painted over by the markdown body's opaque white — and since that body is only as tall as its content, the divider survived as a hairline starting halfway down the pane, under the last rendered block. The white itself was the second: a `#ffffff` patch over the card's `bg-layer-raised`, which a dark theme would have kept white. And Tailwind's preflight, which the kit ships, had stripped the list markers and the task-list checkbox out of the rendered markdown — a bulleted list came out as indented lines, a `- [ ]` as a 0×0 box. The divider is now a real border on `border-secondary`, the body and its table rows are transparent, code, quotes, tables and headings take kit tokens, and lists and task boxes render again. The preview also inherits the host's font and `text-primary` instead of the library's `-apple-system` stack and `#24292f`; the edit pane keeps its monospace face. Both panes gained a 16px gutter beside the divider, so text no longer butts against it.
+- **`MarkdownEditor` (2.0) — the two panes no longer sit on top of each other in RTL** — live mode pins the preview with a physical `right: 0` while the edit pane is a plain block at the inline start, so under `dir="rtl"` both landed on the right unless the host knew to add the library's own `w-md-editor-rtl` class. The preview is now placed with logical insets and the panes' text aligns to `start`, so the edit pane and the preview swap sides with the document direction — divider, gutters and the quote bar included — with no class for the host to remember.
+- **`DialSchemaRenderer` — required-field errors quote the field label** — the message was `${label} is required`, so with a long schema `title` the reader could not tell where the field name ended and "is required" began. The label is now wrapped in double quotes (`"API key" is required`) wherever the renderer builds the message — the inline field error and the `validateRequired` result alike. The label is still the schema `title` (or the label derived from the property key), never the entered value. Consumers asserting the old text in their tests need to add the quotes. Requested in [ai-dial-admin-frontend#4731](https://github.com/epam/ai-dial-admin-frontend/issues/4731).
+
+---
+
 ## [0.14.0]
 
 ### Breaking Changes