@epam/ai-dial-ui-kit 0.14.2 → 0.15.0-dev.10

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)
@@ -192,6 +193,149 @@ 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.
 
+### 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`                                                 |
+
+#### 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`                               |
+| `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`         |
+| `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                        |
+| `fileDropzone`         | `dial-kit-file-dropzone`              | The drop area of a `FileDropzone`                              |
+| `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                                          |
+| `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 +376,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,20 @@ Versions match the git tags on the `development` branch.
 
 ---
 
+## [0.15.0]
+
+### Added
+
+- **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.
+
+- **`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`.
+
+- **`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. The `nav` carries `dial-kit-breadcrumbs` (`DIAL_KIT_CLASS.breadcrumbs`) and each segment `dial-kit-breadcrumbs-item`. The 1.0 `DialBreadcrumb` is untouched.
+
+---
+
 ## [0.14.0]
 
 ### Breaking Changes