@epam/ai-dial-ui-kit 0.13.0-dev.9 → 0.14.0-dev.1

package/dist/migration-guides/0.13.0/focus-border-token-rename.md

@@ -0,0 +1,106 @@
+# Migrating the `focus` border token → `focus-black` — v0.12.x → v0.13.0
+
+## Why this changed
+
+The border token was named `focus` — after the _state_ it is used in rather than the _value_ it holds. That naming left nowhere to put a second focus colour, so when the blue focus ring arrived it had to be `focus-blue`, an odd sibling to a token whose name implied it covered all focus styling.
+
+Both tokens are now named for their colour: `focus-black` and `focus-blue`. The rendered colour of `focus-black` is identical to the old `focus` (`#161B2D`, grey-1000) — this is a naming change, not a visual one.
+
+## What changed
+
+| Before                        | After                  |
+| ----------------------------- | ---------------------- |
+| CSS variable `--stroke-focus` | `--stroke-focus-black` |
+| `border-focus`                | `border-focus-black`   |
+| `outline-focus`               | `outline-focus-black`  |
+| `divide-focus`                | `divide-focus-black`   |
+| `stroke-focus` (SVG)          | `stroke-focus-black`   |
+
+The token feeds Tailwind's `borderColor`, `outlineColor`, `divideColor`, and `stroke` scales, so every utility built on it moves together.
+
+**Not affected:**
+
+- `controls-focus` / `--controls-stroke-focus` — a separate token, unchanged.
+- `focus-blue` / `--stroke-focus-blue` — unchanged.
+- Tailwind's `focus:` and `focus-visible:` **variants** — unrelated to the token. `focus-visible:outline-focus` becomes `focus-visible:outline-focus-black`; the `focus-visible:` prefix stays exactly as it is.
+
+## Step-by-step migration
+
+### 1. Find all usages
+
+```bash
+grep -rEn "(border|outline|divide|stroke)-focus\b|--stroke-focus\b" src/
+```
+
+The `\b` matters: without it the search also flags `focus-blue` and `--stroke-focus-blue`, which do not change.
+
+### 2. Rename the utilities
+
+**Before:**
+
+```tsx
+<button className="focus-visible:outline focus-visible:outline-focus" />
+```
+
+**After:**
+
+```tsx
+<button className="focus-visible:outline focus-visible:outline-focus-black" />
+```
+
+The same applies inside SCSS `@apply` directives:
+
+```scss
+/* Before */
+.my-input:focus-visible {
+  @apply border-focus;
+}
+
+/* After */
+.my-input:focus-visible {
+  @apply border-focus-black;
+}
+```
+
+### 3. Rename the CSS variable override
+
+Only relevant if you theme the token. Update the custom property name wherever you set it:
+
+**Before:**
+
+```css
+:root {
+  --stroke-focus: #1a1a2e;
+}
+```
+
+**After:**
+
+```css
+:root {
+  --stroke-focus-black: #1a1a2e;
+}
+```
+
+An override left on `--stroke-focus` is **silently ignored** — the utility falls back to the built-in `#161B2D` with no error. This is the one failure mode that neither `typecheck` nor the compiler will catch, so grep for it explicitly.
+
+### 4. Verify
+
+```bash
+npm run typecheck
+npm run test
+```
+
+`typecheck` does not see Tailwind class strings, so also confirm the utilities resolve in the compiled output:
+
+```bash
+npm run build:css
+grep -c "stroke-focus-black" dist/index.css
+```
+
+A stale `border-focus` compiles to nothing at all — the element simply loses its focus border, which is easy to miss without a visual pass. Check focus states in Storybook by tabbing through affected controls.
+
+## Notes
+
+- `ringColor` is **not** wired to this token scale, so `ring-focus-black` does not resolve — just as `ring-focus` did not before. Use `outline-focus-black` for focus rings.
+- The colour value is unchanged, so a correctly-migrated codebase should be pixel-identical to 0.12.x.

package/dist/migration-guides/0.13.0/progress-bar-2-0-rewrite.md

@@ -0,0 +1,103 @@
+# Migrating `DialProgressBar` → `ProgressBar` — v0.12.x → v0.13.0
+
+## Why this changed
+
+`DialProgressBar` was built on 1.0 design tokens (`bg-layer-4`, `bg-controls-accent-primary`) that are on the removal list, so it could not be used in a 2.0 screen without dragging the legacy palette in with it. Rebuilding it on the 2.0 set also let it pick up the conventions the rest of the 2.0 components already follow: no `Dial*` prefix, the shared `ElementSize` enum instead of a bespoke one, and native props passed through.
+
+Unlike the [`Spinner` rename](spinner-dial-prefix-removal.md), this is **not** a rename only — the size enum, the label prop, and the rendered colors all changed.
+
+## What changed
+
+| Before                                | After                                        |
+| ------------------------------------- | -------------------------------------------- |
+| `DialProgressBar`                     | `ProgressBar`                                |
+| `DialProgressBarProps`                | `ProgressBarProps`                           |
+| `DialProgressBarSize.Small` (`'sm'`)  | `ElementSize.Small` (`'small'`)              |
+| `DialProgressBarSize.Medium` (`'md'`) | `ElementSize.Standard` (`'standard'`)        |
+| `ariaLabel="…"`                       | `aria-label="…"`                             |
+| _no visible label_                    | `label` — renders above the bar and names it |
+
+Unchanged: `value`, `max` (default `100`), `className` (still lands on the track element), the `role="progressbar"` element with `aria-valuenow` / `aria-valuemin` / `aria-valuemax`, the clamping of `value` into `0…max`, and the 4px / 8px heights.
+
+Also changed, but requiring no code edit:
+
+- **Colors** — track `bg-layer-4` → `bg-control-disable`, fill `bg-controls-accent-primary` → `bg-control-accent`. Both now match the 2.0 `Switch`.
+- **Native props** — `ProgressBarProps` extends `HTMLAttributes<HTMLDivElement>`, so `aria-valuetext`, `data-*`, `onClick`, and the rest reach the element. `aria-valuetext` is the one to reach for when a percentage is not the useful announcement.
+- **Reduced motion** — the width transition is now suppressed under `prefers-reduced-motion`.
+- **Degenerate input** — a non-positive `max` or a non-finite `value` renders an empty bar instead of `width: NaN%`.
+- The Storybook entry moved from `DIAL/Status/ProgressBar` to `Components_2_0/ProgressBar`. Story URLs only.
+
+## Step-by-step migration
+
+### 1. Find all usages
+
+```bash
+grep -rn "DialProgressBar" src/
+```
+
+### 2. Rename the import, the tag, and the size enum
+
+**Before:**
+
+```tsx
+import {
+  DialProgressBar,
+  DialProgressBarSize,
+  type DialProgressBarProps,
+} from '@epam/ai-dial-ui-kit';
+
+<DialProgressBar value={40} ariaLabel="Upload progress" />;
+<DialProgressBar value={40} size={DialProgressBarSize.Small} />;
+<DialProgressBar value={40} size={DialProgressBarSize.Medium} />;
+```
+
+**After:**
+
+```tsx
+import {
+  ProgressBar,
+  ElementSize,
+  type ProgressBarProps,
+} from '@epam/ai-dial-ui-kit';
+
+<ProgressBar value={40} aria-label="Upload progress" />;
+<ProgressBar value={40} size={ElementSize.Small} />;
+<ProgressBar value={40} size={ElementSize.Standard} />;
+```
+
+`ElementSize.Standard` is the default, so `size={DialProgressBarSize.Medium}` can simply be dropped.
+
+### 3. Replace the generic label with a real one
+
+`ariaLabel` defaulted to `"Progress"`, so a screen has as many bars called "Progress" as it has bars. Where the bar has visible surrounding text, promote it into `label` — it renders above the bar and names it through `aria-labelledby`:
+
+**Before:**
+
+```tsx
+<span className="dial-small-text">Uploading</span>
+<DialProgressBar value={progress} />
+```
+
+**After:**
+
+```tsx
+<ProgressBar value={progress} label="Uploading" />
+```
+
+Where the bar has no visible label, keep naming it explicitly with `aria-label`. The `"Progress"` fallback still applies if you pass neither, so no bar ends up anonymous.
+
+### 4. Verify
+
+```bash
+npm run typecheck
+npm run test
+```
+
+`typecheck` catches every usage: the old names are gone from the barrel, so the imports fail to resolve, and `ariaLabel` is no longer an accepted prop.
+
+## Notes
+
+- `ariaLabel` does **not** silently keep working — it is not part of `HTMLAttributes`, so TypeScript rejects it rather than passing it through as an unknown DOM attribute.
+- Tests asserting `getByRole('progressbar')` keep passing. Prefer tightening them to `getByRole('progressbar', { name })` now that the name is meaningful.
+- If you relied on the exact track color, note that `bg-control-disable` (`#DCE0E8`) is lighter than the old `bg-layer-4` (`#D1DBEA`).
+- `DialLoader` and `Skeleton` are different components and are not affected.

package/dist/migration-guides/0.13.0/spinner-dial-prefix-removal.md

@@ -0,0 +1,69 @@
+# Migrating `DialSpinner` → `Spinner` — v0.12.x → v0.13.0
+
+## Why this changed
+
+The spinner is part of the 2.0 component set, which drops the `Dial*` prefix. Keeping `DialSpinner` alongside the unprefixed 2.0 components made the export list read as two conventions at once, with no signal about which era a component belongs to.
+
+This is a **rename only**. The component's props, defaults, DOM, roles, and styling are untouched.
+
+## What changed
+
+| Before             | After          |
+| ------------------ | -------------- |
+| `DialSpinner`      | `Spinner`      |
+| `DialSpinnerProps` | `SpinnerProps` |
+
+Unchanged: `size` (default `40`), `className`, `fullWidth` (default `false`), `ariaLabel` (default `"Loading"`), the outer `role="status"` container, and the inner `role="img"` ring.
+
+The Storybook entry also moved from `DIAL/Status/Spinner` to `Components_2_0/Spinner`. This affects story URLs only, not consumers of the package.
+
+## Step-by-step migration
+
+### 1. Find all usages
+
+```bash
+grep -rn "DialSpinner" src/
+```
+
+### 2. Rename the import and the JSX tag
+
+**Before:**
+
+```tsx
+import { DialSpinner, type DialSpinnerProps } from '@epam/ai-dial-ui-kit';
+
+const Busy: FC<DialSpinnerProps> = (props) => <DialSpinner {...props} />;
+
+<DialSpinner size={24} fullWidth ariaLabel="Loading results" />;
+```
+
+**After:**
+
+```tsx
+import { Spinner, type SpinnerProps } from '@epam/ai-dial-ui-kit';
+
+const Busy: FC<SpinnerProps> = (props) => <Spinner {...props} />;
+
+<Spinner size={24} fullWidth ariaLabel="Loading results" />;
+```
+
+If `Spinner` collides with a local component of the same name, alias the import rather than renaming your own:
+
+```tsx
+import { Spinner as DialSpinner } from '@epam/ai-dial-ui-kit';
+```
+
+### 3. Verify
+
+```bash
+npm run typecheck
+npm run test
+```
+
+`typecheck` catches every usage — there is no runtime-only path to miss, since the old name is removed from the barrel and the import fails to resolve.
+
+## Notes
+
+- Tests that render the spinner need no assertion changes: it still exposes `role="status"` on the container and `role="img"` with the `ariaLabel` name on the ring.
+- `DialLoader` is a different component and is **not** renamed.
+- `Notification`'s `loading` variant renders this spinner internally; no consumer change is needed there.

package/dist/migration-guides/0.13.0/typography-heading-scale-shift.md

@@ -0,0 +1,93 @@
+# Migrating the heading type scale — v0.12.x → v0.13.0
+
+## Why this changed
+
+The design system's type scale has three display sizes and three heading sizes. The kit only had two display classes, so the 22px step that design calls **Display 3** was shipping as `dial-h1-text`, and every heading class was one step larger than the design named it.
+
+Adding `dial-display3-text` at 22px/32px puts the 22px step where it belongs and lets `dial-h1-text`, `dial-h2-text`, and `dial-h3-text` carry the sizes design assigns to Heading 1–3. The set of available sizes is unchanged — the same six steps exist before and after. What moved is which class name each one answers to.
+
+## What changed
+
+| Class                 | Before      | After             |
+| --------------------- | ----------- | ----------------- |
+| `.dial-display1-text` | 32px / 48px | 32px / 48px       |
+| `.dial-display2-text` | 28px / 40px | 28px / 40px       |
+| `.dial-display3-text` | —           | 22px / 32px (new) |
+| `.dial-h1-text`       | 22px / 32px | **20px / 28px**   |
+| `.dial-h2-text`       | 20px / 28px | **18px / 26px**   |
+| `.dial-h3-text`       | 18px / 26px | **16px / 24px**   |
+
+All six stay `font-weight: 600` with no letter-spacing.
+
+The kit also styles bare `h1`, `h2`, and `h3` elements from these classes, so **unclassed headings shrink one step too** — an `<h1>` with no `className` renders at 20px/28px instead of 22px/32px.
+
+## Step-by-step migration
+
+### 1. Find all usages
+
+```bash
+grep -rEn "dial-h[123]-text" src/
+```
+
+Also find headings that rely on the element defaults rather than a class, since those change with no class name to grep for:
+
+```bash
+grep -rEn "<h[123](\s|>)" src/
+```
+
+### 2. Decide per usage: keep the size, or keep the semantic level
+
+This is the whole migration, and it is a judgement call rather than a rename — a blind find-and-replace gets it wrong either way.
+
+**To keep the rendered size identical**, shift the class name up one step:
+
+| Before                | After                       |
+| --------------------- | --------------------------- |
+| `dial-h1-text` (22px) | `dial-display3-text` (22px) |
+| `dial-h2-text` (20px) | `dial-h1-text` (20px)       |
+| `dial-h3-text` (18px) | `dial-h2-text` (18px)       |
+
+**To adopt the new scale**, leave the class name alone and accept the smaller size. This is right where the class was chosen to match the heading level (an `<h2>` styled `dial-h2-text`) rather than to hit a specific pixel size.
+
+**Before** — a dialog title that should stay at 20px:
+
+```tsx
+<h2 className="dial-h2-text">Delete conversation</h2>
+```
+
+**After:**
+
+```tsx
+<h2 className="dial-h1-text">Delete conversation</h2>
+```
+
+An `<h3>` that was picked purely for its 18px size and does not head a section is usually better off as `dial-body-semi-text` (16px/24px, the same metrics as the new `dial-h3-text`) on a non-heading element.
+
+### 3. Re-check unclassed headings
+
+A bare `<h1>` in prose, markdown output, or a `prose` block picks up the new 20px/28px automatically. If a specific block must hold its old size, name the class explicitly:
+
+```tsx
+<h1 className="dial-display3-text">Reports</h1>
+```
+
+### 4. Verify
+
+```bash
+npm run typecheck
+npm run test
+```
+
+Neither sees Tailwind class strings, so confirm the compiled values as well:
+
+```bash
+npm run build:css
+grep -o "\.dial-h1-text{[^}]*}" dist/index.css
+```
+
+Then do a visual pass in Storybook — **DIAL/Typography** shows the full scale side by side, and a heading that shrank one step is the failure mode to look for.
+
+## Notes
+
+- Inside the kit, the 2.0 `Popup` title was re-pointed `dial-h2-text` → `dial-h1-text` and renders exactly as it did in 0.12.x. The 1.0 `DialPopup` title keeps `dial-h3-text` and therefore **adopts the new scale**: it drops from 18px/26px to 16px/24px. Nothing to change on your side — pass `titleClassName="dial-h2-text"` if a particular dialog must hold its old size.
+- Nothing about this change is visible to TypeScript. A missed usage compiles, tests pass, and the heading simply renders one step small — so the grep in step 1 is the only reliable sweep.

package/dist/migration-guides/README.md

@@ -16,6 +16,12 @@ migration-guides/
 | ------- | ----- | ------- |
 | 0.11.0 | [dropdown-menu-prop-flatten](0.11.0/dropdown-menu-prop-flatten.md) | `DialDropdown`/`DialDropdownIcon` `menu` prop replaced with flat `items`, `onItemClick`, `menuHeader`, `menuFooter` props |
 | 0.12.0 | [legacy-typography-classes-removal](0.12.0/legacy-typography-classes-removal.md) | Legacy `dial-h*`, `dial-body`, `dial-small*`, `dial-tiny*`, `dial-caption` classes removed in favor of the `dial-*-text` scale |
+| 0.13.0 | [spinner-dial-prefix-removal](0.13.0/spinner-dial-prefix-removal.md) | `DialSpinner`/`DialSpinnerProps` renamed to `Spinner`/`SpinnerProps` |
+| 0.13.0 | [focus-border-token-rename](0.13.0/focus-border-token-rename.md) | Border token `focus` renamed to `focus-black` (`--stroke-focus` → `--stroke-focus-black`) |
+| 0.13.0 | [typography-heading-scale-shift](0.13.0/typography-heading-scale-shift.md) | `dial-display3-text` added at 22px; `dial-h1`/`h2`/`h3-text` shifted one step down to 20/18/16px |
+| 0.13.0 | [caption-semi-text-lead-rename](0.13.0/caption-semi-text-lead-rename.md) | `dial-caption-semi-text` renamed to `dial-caption-lead-semi-text` and now uppercases |
+| 0.13.0 | [progress-bar-2-0-rewrite](0.13.0/progress-bar-2-0-rewrite.md) | `DialProgressBar` rebuilt on 2.0 tokens as `ProgressBar`; `DialProgressBarSize` → `ElementSize`, `ariaLabel` → `aria-label` |
+| 0.13.0 | [field-label-props-unification](0.13.0/field-label-props-unification.md) | `Calendar`, `Switch` and `ProgressBar` take `labelProps` instead of `label`, so every 2.0 field names itself through `Label` |
 
 ---
 

package/dist/src/components/Accordion/Accordion.d.ts

@@ -29,6 +29,7 @@ export interface DialAccordionProps {
 /**
  * A collapsible panel that toggles its content when the header is clicked.
  * aliases: Collapse|Disclosure|ExpandablePanel
+ * Design system 1.0
  *
  * Works as a controlled component when `expanded` is provided, otherwise it manages
  * its own state from `defaultExpanded`. The header shows a chevron that rotates when

package/dist/src/components/Analytics/Bar/Bar.d.ts

@@ -1,8 +1,11 @@
 import { FC, ReactNode } from 'react';
 import { AnalyticsBarColorStop } from '../../../models/analytics';
 export interface DialAnalyticsBarProps {
-    /** Current value used to size and color the bar. Omit it when `error` is set. */
-    value?: number;
+    /**
+     * Current value used to size and color the bar. Pass `null` when there is no
+     * data (em dash, no progress bar). Omit it when `error` is set.
+     */
+    value?: number | null;
     /** Upper bound of the scale. Defaults to `1`. */
     maxValue?: number;
     /**
@@ -18,8 +21,8 @@ export interface DialAnalyticsBarProps {
     /** Optional label rendered above the bar, on the left. */
     title?: ReactNode;
     /**
-     * Text rendered above the bar, on the right. Defaults to `value`.
-     * Pass a formatted node (e.g. `"85%"`) to override.
+     * Text rendered above the bar, on the right. Defaults to `value`, or an em dash
+     * (`—`) when `value` is `null`. Pass a formatted node (e.g. `"85%"`) to override.
      */
     valueLabel?: ReactNode;
     /**
@@ -45,10 +48,12 @@ export interface DialAnalyticsBarProps {
  * A compact analytics meter: a horizontal bar whose fill width and color reflect a
  * value relative to `maxValue`, with an optional title on the left and value on the right.
  * aliases: MetricBar|Meter|ScoreBar
+ * Design system 1.0
  *
  * The fill color is resolved from `colorMap` based on the normalized ratio
  * (`value / maxValue`), so the bar shifts hue as the value grows. An empty bar
- * (value `0`) shows only the `bg-layer-1` track.
+ * (value `0`) shows only the `bg-layer-1` track. A missing value (`null`) shows
+ * an em dash and no progress bar.
  *
  * @example
  * ```tsx
@@ -65,12 +70,12 @@ export interface DialAnalyticsBarProps {
  * />
  * ```
  *
- * @param [value] - Current value used to size and color the bar. Omit it when `error` is set.
+ * @param [value] - Current value used to size and color the bar. Pass `null` for no data (em dash, no bar). Omit when `error` is set.
  * @param [maxValue=1] - Upper bound of the scale.
  * @param [error] - Renders the error state (error-colored bar + error tag).
  * @param [isLoading] - Renders the loading state (loader + empty track).
  * @param [title] - Optional label rendered above the bar, on the left.
- * @param [valueLabel] - Text rendered above the bar, on the right. Defaults to `value`.
+ * @param [valueLabel] - Text rendered above the bar, on the right. Defaults to `value` or `—` when null.
  * @param [colorMap=DEFAULT_ANALYTICS_BAR_COLOR_MAP] - Color bands keyed by ratio.
  * @param [className] - Additional CSS classes for the outer container.
  * @param [titleClassName] - Additional CSS classes for the title label.

package/dist/src/components/Analytics/BarGroup/BarGroup.d.ts

@@ -7,14 +7,19 @@ export interface DialAnalyticsBarGroupProps {
     titleTooltip?: ReactNode;
     /** Description passed to the accordion header. Defaults to the number of entries. */
     description?: ReactNode;
-    /** Map of metric name to numeric value. Each entry renders one bar. */
-    data: Record<string, number>;
     /**
-     * When provided, enables compare mode: each entry renders a delta badge (computed
-     * as `data[key] - compareData[key]`) and two bars — one for `data` and one for
-     * `compareData`. `onBarClick` is ignored in compare mode.
+     * Map of metric name to numeric value. Each entry renders one bar.
+     * Pass `null` for a key when there is no data (em dash, no progress bar).
      */
-    compareData?: Record<string, number>;
+    data: Record<string, number | null>;
+    /**
+     * When provided, enables compare mode: keys are the union of `data` and
+     * `compareData`. Each entry renders two bars and, when both sides are numeric,
+     * a delta badge (`compareData[key] - data[key]`, three decimal places). A
+     * missing key (or explicit `null`) on either side shows an em dash with no
+     * progress bar and no delta. A rounded delta of `0` is omitted.
+     */
+    compareData?: Record<string, number | null>;
     /**
      * Labels shown next to each of the two bars in compare mode.
      * The first label is for `data`, the second for `compareData`.
@@ -34,8 +39,12 @@ export interface DialAnalyticsBarGroupProps {
     nonCollapsible?: boolean;
     /** Renders a loader in place of the bars while the data is being fetched. */
     isLoading?: boolean;
-    /** Invoked with the entry key and value when a bar is clicked. When set, each bar becomes an interactive button. */
-    onBarClick?: (key: string, value: number) => void;
+    /**
+     * Invoked with the entry key and value when a bar is clicked. When set, each
+     * bar becomes an interactive button. In compare mode the whole entry (label,
+     * delta, both bars) is the click target.
+     */
+    onBarClick?: (key: string, value: number | null) => void;
     /** Renders every bar on a single row (50% title, 50% bar + value). */
     inline?: boolean;
     /** Additional CSS classes for each bar's title label. */
@@ -44,10 +53,7 @@ export interface DialAnalyticsBarGroupProps {
     barValueClassName?: string;
     /** Additional CSS classes for each bar's outer container (e.g. for custom hover effects). */
     barClassName?: string;
-    /**
-     * Map of bar key to tooltip content. When provided, hovering each bar shows its description.
-     * Not applied in compare mode.
-     */
+    /** Map of bar key to tooltip content. When provided, hovering each bar shows its description. */
     barDescriptions?: Record<string, ReactNode>;
     /** Additional CSS classes for the accordion container. */
     className?: string;
@@ -58,6 +64,7 @@ export interface DialAnalyticsBarGroupProps {
  * is shown as the header description, and each entry renders a {@link DialAnalyticsBar}
  * with the key as its title and the value as its value.
  * aliases: MetricBarGroup|BarList|NumericResults
+ * Design system 1.0
  *
  * @example
  * ```tsx
@@ -70,20 +77,20 @@ export interface DialAnalyticsBarGroupProps {
  * @param title - Title passed to the accordion header.
  * @param [titleTooltip] - Tooltip shown when hovering the accordion header title.
  * @param [description] - Description passed to the accordion header. Defaults to the number of entries.
- * @param data - Map of metric name to numeric value. Each entry renders one bar.
- * @param [compareData] - Enables compare mode: each entry shows a delta badge and two bars.
+ * @param data - Map of metric name to numeric value (or `null` when missing). Each entry renders one bar.
+ * @param [compareData] - Enables compare mode: union of keys, delta badge (`compareData − data`) when both sides are numeric and the rounded delta is non-zero, em dash (no bar) when a side is missing.
  * @param [compareLabels] - Labels for the two bars in compare mode: first for `data`, second for `compareData`.
  * @param [maxValue] - Upper bound passed to every bar.
  * @param [colorMap] - Color map passed to every bar.
  * @param [defaultExpanded=true] - Whether the accordion is expanded initially.
  * @param [nonCollapsible] - Renders the group permanently expanded without a toggle or chevron.
  * @param [isLoading] - Renders a loader in place of the bars while the data is being fetched.
- * @param [onBarClick] - Invoked with the entry key and value when a bar is clicked.
+ * @param [onBarClick] - Invoked with the entry key and value when a bar (or, in compare mode, the whole entry) is clicked.
  * @param [inline] - Renders every bar on a single row (50% title, 50% bar + value).
  * @param [barTitleClassName] - Additional CSS classes for each bar's title label.
  * @param [barValueClassName] - Additional CSS classes for each bar's value label.
  * @param [barClassName] - Additional CSS classes for each bar's outer container.
- * @param [barDescriptions] - Map of bar key to tooltip content. Hovering each bar shows its description. Not applied in compare mode.
+ * @param [barDescriptions] - Map of bar key to tooltip content. Hovering each bar shows its description.
  * @param [className] - Additional CSS classes for the accordion container.
  */
 export declare const DialAnalyticsBarGroup: FC<DialAnalyticsBarGroupProps>;

package/dist/src/components/Analytics/Card/Card.d.ts

@@ -25,6 +25,11 @@ export interface DialAnalyticsCardProps {
      * When omitted, `delta ≥ 0` → success, `delta < 0` → error.
      */
     deltaPositive?: boolean;
+    /**
+     * Suffix appended to the formatted delta with no space (e.g. `"s"` → `+9s`,
+     * `-19s`). Any string is valid (`s`, `ms`, `%`).
+     */
+    deltaUnit?: string;
     /**
      * When provided, enables compare mode: the value area is split 50/50 with a
      * vertical divider and each side shows its own sub-title and value.
@@ -36,6 +41,7 @@ export interface DialAnalyticsCardProps {
  * A simple analytics summary card that displays a single metric as a title,
  * a prominent value, and an optional description.
  * aliases: MetricCard|StatCard|KpiCard
+ * Design system 1.0
  *
  * Two visual variants are available via the {@link AnalyticsCardVariant} enum:
  * - `Default` — `bg-layer-3`, large `dial-display2-text` value, supports a description.
@@ -43,8 +49,9 @@ export interface DialAnalyticsCardProps {
  *   description (the `description` prop is ignored in this variant).
  *
  * **Compare mode** — pass `compareValues` to split the value area 50/50 between two
- * metrics, each with its own sub-title. Pair with `delta` to show a change badge next
- * to the card title.
+ * metrics, each with its own sub-title. Long sub-titles truncate to a single line and
+ * show the full text in a tooltip. Pair with `delta` to show a change badge next
+ * to the card title, and `deltaUnit` for a suffix such as `"s"`.
  *
  * @example
  * ```tsx
@@ -59,7 +66,9 @@ export interface DialAnalyticsCardProps {
  * ```tsx
  * <DialAnalyticsCard
  *   title="Response time"
- *   delta={12}
+ *   delta={9}
+ *   deltaUnit="s"
+ *   deltaPositive={false}
  *   compareValues={[
  *     { title: 'This week', value: '248ms' },
  *     { title: 'Last week', value: '220ms' },
@@ -75,6 +84,8 @@ export interface DialAnalyticsCardProps {
  * @param [isLoading] - Renders a loader in place of the value.
  * @param [className] - Additional CSS classes for the card container.
  * @param [delta] - Numeric change shown as a badge next to the title. ≥0 = success, <0 = error.
+ * @param [deltaPositive] - Overrides sign-based badge colour. Use for lower-is-better metrics.
+ * @param [deltaUnit] - Suffix appended to the formatted delta (e.g. `"s"` → `+9s`).
  * @param [compareValues] - Enables compare mode with two side-by-side metrics.
  */
 export declare const DialAnalyticsCard: FC<DialAnalyticsCardProps>;

package/dist/src/components/Analytics/ErrorTag/ErrorTag.d.ts

@@ -7,6 +7,7 @@ export interface DialAnalyticsErrorTagProps {
 }
 /**
  * A non-interactive error tag used across analytics components to indicate that a
+ * Design system 1.0
  * metric value could not be provided. Renders a {@link DialTag} styled with the
  * error palette (`bg-error`, `text-error`, `border-error`).
  *

package/dist/src/components/Analytics/Histogram/Histogram.d.ts

@@ -18,7 +18,7 @@ export interface DialAnalyticsHistogramProps {
     isLoading?: boolean;
     /** Additional CSS classes for the outer container. */
     className?: string;
-    /** Second set of values to overlay in compare mode. Each column renders as a paired striped bar. */
+    /** Second set of values to overlay in compare mode. Primary bars are striped; compare bars are solid. */
     compareValues?: number[];
     /** Label for the primary values set, shown on the first tooltip line in compare mode. */
     valueSetLabel?: string;
@@ -27,11 +27,14 @@ export interface DialAnalyticsHistogramProps {
 }
 /**
  * A histogram that distributes `values` across the bands of a color map and draws a
- * column per band. Each column's height is relative to the most populated band; empty
- * columns are outlined, populated columns are filled with their band color. A baseline
- * separates the columns from the interval labels, and hovering a column reveals a
- * tooltip with its share of the total.
+ * column per band. Each column's height is relative to the Y-axis max (an even
+ * ceiling of the dataset size — the "out of N" in the tooltip). Empty columns
+ * are outlined, populated columns are filled with their band color. A left
+ * Y-axis (count) and horizontal grid lines provide scale; interval labels run
+ * along the bottom. Hovering a column reveals a tooltip with its share of the
+ * total.
  * aliases: Distribution|ColumnChart|FrequencyChart
+ * Design system 1.0
  *
  * @example
  * ```tsx
@@ -49,7 +52,7 @@ export interface DialAnalyticsHistogramProps {
  * @param [showCount] - When `true`, renders each column's count inside its bar.
  * @param [isLoading] - Renders a loader in place of the histogram while the data is being fetched.
  * @param [className] - Additional CSS classes for the outer container.
- * @param [compareValues] - Second set of values; enables compare mode with paired striped columns.
+ * @param [compareValues] - Second set of values; enables compare mode (primary striped, compare solid).
  * @param [valueSetLabel] - Label for the primary values set (compare mode tooltip).
  * @param [compareValueSetLabel] - Label for the compare values set (compare mode tooltip).
  */

package/dist/src/components/Analytics/Histogram/utils.d.ts

@@ -29,6 +29,16 @@ export declare const getHistogramColumnIndex: (value: number, colorMap: Analytic
  * column and computes each column's height as a ratio of the tallest column.
  */
 export declare const buildHistogramColumns: (values: number[], colorMap: AnalyticsBarColorStop[]) => AnalyticsHistogramColumn[];
+/**
+ * Top of the Y-axis for a dataset of `total` values (the "out of N" in the
+ * tooltip). Rounds odd totals up so the midpoint tick is an integer
+ * (Figma: 0, 24, 48). Empty data still gets a 0–2 scale so the axis is visible.
+ */
+export declare const getHistogramYMax: (total: number) => number;
+/**
+ * Three Y-axis ticks from top to bottom: `yMax`, `yMax / 2`, `0`.
+ */
+export declare const getHistogramYTicks: (total: number) => number[];
 /** Formats a column's interval bound for the axis label (trims float noise). */
 export declare const formatHistogramInterval: (value: number) => string;
 /**

package/dist/src/components/AutocompleteInput/AutocompleteInputValue.d.ts

@@ -9,6 +9,7 @@ export interface DialAutocompleteInputValueProps {
 /**
  * A component that displays a list of selected items in a customizable, styled list. Each item is
  * aliases: SelectedList|ItemDisplay
+ * Design system 1.0
  *
  * rendered as a tag wrapped in a tooltip, allowing for truncation and additional context when
  * hovered. The component is flexible and supports custom CSS classes for styling the list and