@ids-group-ltd/ids-design-system 0.14.1 → 0.14.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (94) hide show
  1. package/CHANGELOG.md +243 -0
  2. package/components.md +29 -26
  3. package/docs/agent/INDEX.md +3 -3
  4. package/docs/agent/charts/column-series-component.md +1 -1
  5. package/docs/agent/charts/ds-bar-chart.md +3 -3
  6. package/docs/agent/charts/ds-chart.md +1 -1
  7. package/docs/agent/charts/ds-column-chart.md +3 -3
  8. package/docs/agent/charts/ds-config.md +1 -1
  9. package/docs/agent/charts/ds-funnel-chart.md +3 -3
  10. package/docs/agent/charts/ds-heatmap-chart.md +1 -1
  11. package/docs/agent/charts/ds-line-chart.md +2 -2
  12. package/docs/agent/charts/ds-pie-chart.md +2 -2
  13. package/docs/agent/charts/ds-scatter-chart.md +1 -1
  14. package/docs/agent/charts/ds-waterfall-chart.md +1 -1
  15. package/docs/agent/charts/line-series-component.md +1 -1
  16. package/docs/agent/feedback/ds-description-list.md +3 -0
  17. package/docs/agent/forms/ds-textarea.md +1 -1
  18. package/docs/agent/navigation/ds-pagination.md +1 -1
  19. package/docs/agent/navigation/ds-tabs.md +1 -0
  20. package/docs/agent/overlays/ds-tooltip.md +3 -3
  21. package/docs/agent/tables/ds-table.md +1 -1
  22. package/fesm2022/ids-group-ltd-ids-design-system-components-autocomplete.mjs +4 -2
  23. package/fesm2022/ids-group-ltd-ids-design-system-components-autocomplete.mjs.map +1 -1
  24. package/fesm2022/ids-group-ltd-ids-design-system-components-bar-chart.mjs +22 -16
  25. package/fesm2022/ids-group-ltd-ids-design-system-components-bar-chart.mjs.map +1 -1
  26. package/fesm2022/ids-group-ltd-ids-design-system-components-chart-legend.mjs +19 -7
  27. package/fesm2022/ids-group-ltd-ids-design-system-components-chart-legend.mjs.map +1 -1
  28. package/fesm2022/ids-group-ltd-ids-design-system-components-chart-tooltip.mjs +180 -19
  29. package/fesm2022/ids-group-ltd-ids-design-system-components-chart-tooltip.mjs.map +1 -1
  30. package/fesm2022/ids-group-ltd-ids-design-system-components-chart.mjs +175 -93
  31. package/fesm2022/ids-group-ltd-ids-design-system-components-chart.mjs.map +1 -1
  32. package/fesm2022/ids-group-ltd-ids-design-system-components-column-chart.mjs +10 -11
  33. package/fesm2022/ids-group-ltd-ids-design-system-components-column-chart.mjs.map +1 -1
  34. package/fesm2022/ids-group-ltd-ids-design-system-components-description-list.mjs +3 -3
  35. package/fesm2022/ids-group-ltd-ids-design-system-components-description-list.mjs.map +1 -1
  36. package/fesm2022/ids-group-ltd-ids-design-system-components-funnel-chart.mjs +32 -18
  37. package/fesm2022/ids-group-ltd-ids-design-system-components-funnel-chart.mjs.map +1 -1
  38. package/fesm2022/ids-group-ltd-ids-design-system-components-heatmap-chart.mjs +47 -7
  39. package/fesm2022/ids-group-ltd-ids-design-system-components-heatmap-chart.mjs.map +1 -1
  40. package/fesm2022/ids-group-ltd-ids-design-system-components-line-chart.mjs +11 -11
  41. package/fesm2022/ids-group-ltd-ids-design-system-components-line-chart.mjs.map +1 -1
  42. package/fesm2022/ids-group-ltd-ids-design-system-components-multi-select.mjs +4 -2
  43. package/fesm2022/ids-group-ltd-ids-design-system-components-multi-select.mjs.map +1 -1
  44. package/fesm2022/ids-group-ltd-ids-design-system-components-pagination.mjs +11 -5
  45. package/fesm2022/ids-group-ltd-ids-design-system-components-pagination.mjs.map +1 -1
  46. package/fesm2022/ids-group-ltd-ids-design-system-components-pie-chart.mjs +15 -13
  47. package/fesm2022/ids-group-ltd-ids-design-system-components-pie-chart.mjs.map +1 -1
  48. package/fesm2022/ids-group-ltd-ids-design-system-components-scatter-chart.mjs +35 -5
  49. package/fesm2022/ids-group-ltd-ids-design-system-components-scatter-chart.mjs.map +1 -1
  50. package/fesm2022/ids-group-ltd-ids-design-system-components-select.mjs +4 -2
  51. package/fesm2022/ids-group-ltd-ids-design-system-components-select.mjs.map +1 -1
  52. package/fesm2022/ids-group-ltd-ids-design-system-components-table.mjs +32 -7
  53. package/fesm2022/ids-group-ltd-ids-design-system-components-table.mjs.map +1 -1
  54. package/fesm2022/ids-group-ltd-ids-design-system-components-tabs.mjs +66 -6
  55. package/fesm2022/ids-group-ltd-ids-design-system-components-tabs.mjs.map +1 -1
  56. package/fesm2022/ids-group-ltd-ids-design-system-components-textarea.mjs +61 -9
  57. package/fesm2022/ids-group-ltd-ids-design-system-components-textarea.mjs.map +1 -1
  58. package/fesm2022/ids-group-ltd-ids-design-system-components-tooltip.mjs +78 -6
  59. package/fesm2022/ids-group-ltd-ids-design-system-components-tooltip.mjs.map +1 -1
  60. package/fesm2022/ids-group-ltd-ids-design-system-components-waterfall-chart.mjs +25 -9
  61. package/fesm2022/ids-group-ltd-ids-design-system-components-waterfall-chart.mjs.map +1 -1
  62. package/fesm2022/ids-group-ltd-ids-design-system-components.mjs +85 -9
  63. package/fesm2022/ids-group-ltd-ids-design-system-components.mjs.map +1 -1
  64. package/fesm2022/ids-group-ltd-ids-design-system-core.mjs +4 -1
  65. package/fesm2022/ids-group-ltd-ids-design-system-core.mjs.map +1 -1
  66. package/fesm2022/ids-group-ltd-ids-design-system.mjs.map +1 -1
  67. package/migrations/0.14.2.json +427 -0
  68. package/package.json +1 -1
  69. package/schematics/check-overrides/surface.json +31 -2
  70. package/styles/_chart-frame.scss +34 -12
  71. package/styles/_chart-interactive.scss +10 -9
  72. package/styles/_chart-motion.scss +139 -16
  73. package/styles/_overlay-motion.scss +6 -0
  74. package/styles/_tokens.scss +19 -4
  75. package/types/ids-group-ltd-ids-design-system-components-bar-chart.d.ts +24 -10
  76. package/types/ids-group-ltd-ids-design-system-components-chart-legend.d.ts +6 -1
  77. package/types/ids-group-ltd-ids-design-system-components-chart-tooltip.d.ts +33 -2
  78. package/types/ids-group-ltd-ids-design-system-components-chart.d.ts +151 -103
  79. package/types/ids-group-ltd-ids-design-system-components-column-chart.d.ts +8 -9
  80. package/types/ids-group-ltd-ids-design-system-components-description-list.d.ts +1 -1
  81. package/types/ids-group-ltd-ids-design-system-components-funnel-chart.d.ts +23 -11
  82. package/types/ids-group-ltd-ids-design-system-components-heatmap-chart.d.ts +29 -2
  83. package/types/ids-group-ltd-ids-design-system-components-line-chart.d.ts +8 -8
  84. package/types/ids-group-ltd-ids-design-system-components-pagination.d.ts +3 -1
  85. package/types/ids-group-ltd-ids-design-system-components-pie-chart.d.ts +17 -7
  86. package/types/ids-group-ltd-ids-design-system-components-scatter-chart.d.ts +20 -2
  87. package/types/ids-group-ltd-ids-design-system-components-table.d.ts +6 -2
  88. package/types/ids-group-ltd-ids-design-system-components-tabs.d.ts +13 -2
  89. package/types/ids-group-ltd-ids-design-system-components-textarea.d.ts +22 -4
  90. package/types/ids-group-ltd-ids-design-system-components-tooltip.d.ts +10 -1
  91. package/types/ids-group-ltd-ids-design-system-components-waterfall-chart.d.ts +11 -2
  92. package/types/ids-group-ltd-ids-design-system-components.d.ts +33 -6
  93. package/types/ids-group-ltd-ids-design-system-core.d.ts +14 -1
  94. package/types/ids-group-ltd-ids-design-system.d.ts +1 -1
package/CHANGELOG.md CHANGED
@@ -1,5 +1,248 @@
1
1
  ## Unreleased
2
2
 
3
+ ## 0.14.2 — 2026-09-25
4
+
5
+ ### Breaking
6
+
7
+ - **A click on a chart mark holds it by default.** `pinOnClick` on `ds-bar-chart`, `ds-column-chart`,
8
+ `ds-funnel-chart`, `ds-line-chart`, `ds-pie-chart`, `ds-heatmap-chart`, `ds-scatter-chart`,
9
+ `ds-waterfall-chart` and the `dsColumnSeries` / `dsLineSeries` marks, and `cursorPin` on
10
+ `ds-chart`, now default to `null` and fall back to `DS_CONFIG.chart.pinOnClick`, then `true` (was
11
+ `false`). A pointer click or tap now holds the mark - its tooltip and highlight stay after the
12
+ pointer leaves and it shows a pin disc on itself - until a second click, Escape or a press elsewhere
13
+ lets go; keyboard focus reaches a mark without pinning it (on a heat map, Enter or Space focus a
14
+ cell, a click pins). `pointClicked` fires either way. To keep marks unheld, set
15
+ `pinOnClick="false"` (`cursorPin="false"` on `ds-chart`) on the one chart, or
16
+ `DS_CONFIG.chart.pinOnClick: false` for all.
17
+
18
+ - **A chart answers a resting pointer after 500 ms.** The tooltip, the highlight and the dimming of a
19
+ mark, the category cursor, a legend entry, a heat map scale step and a bar's label wait
20
+ `DS_CONFIG.chart.hoverDelayMs` (default `500`) of rest before they show (was: at once). Once a chart
21
+ has answered, the next mark answers at once until the pointer leaves it; touch, keyboard focus, a
22
+ pin and a delay of `0` answer at once. To answer at once, set `DS_CONFIG.chart.hoverDelayMs: 0`. A
23
+ test that hovers a mark and asserts on its tooltip in the same tick waits the delay, or sets it to
24
+ `0`.
25
+
26
+ - **`pinOnClick` and `ds-chart`'s `cursorPin` are `boolean | null`** (was `boolean`), `null` meaning
27
+ unset, on `ds-bar-chart`, `ds-column-chart`, `ds-funnel-chart`, `ds-line-chart`, `ds-pie-chart`,
28
+ `dsColumnSeries` and `dsLineSeries`. Binding them in a template is unaffected. Code that reads the
29
+ raw input back, or a subclass overriding it, must handle `null`, which falls back to
30
+ `DS_CONFIG.chart.pinOnClick` and then `true`; `dsColumnSeries` and `dsLineSeries` expose the result
31
+ as `pinOnClickResolved()`, `ds-chart` as `cursorPinResolved()`. A reader testing `pinOnClick()` for
32
+ truthiness now sees `null` on an unset chart that does pin, and takes the other branch with no
33
+ compile error.
34
+
35
+ - **Under the category cursor, the category's drawn band is the one hover area.** The pointer anywhere
36
+ in the band opens the band and its single category tooltip together; the gap between two bands
37
+ answers nothing; a `dsColumnSeries` column or `dsLineSeries` mark under the cursor no longer opens a
38
+ per-mark panel on hover (focus and click still do). This is a `ds-chart` with `cursor="category"`,
39
+ or `"auto"` on two or more marks that show a tooltip; the column, line and waterfall presets draw no
40
+ category cursor and are unaffected. To keep a per-mark hover panel there, set `cursor="none"` on that
41
+ `ds-chart`. A hand-composed mark reads `CHART_SCALES.cursorOn` to leave pointer hover to the band.
42
+
43
+ - **Chart entrances are slower and staged.** `--ds-motion-chart-mark-enter-duration` is `400ms` (was
44
+ `180ms`) and `--ds-motion-chart-mark-enter-easing` is `--ease-emphasized-decelerate` (was
45
+ `--ease-decelerate`). Columns, bars and waterfall steps grow out of their baseline over the grow
46
+ duration with no fade; a solid line draws on and a dashed one fades; an area fades in under its line;
47
+ the pie ring turns into place; funnel stages rise in; scatter points and line markers settle about
48
+ their centre; heat map cells fade in column by column, having not animated before. Value labels,
49
+ markers, table rows and legend swatches follow once their mark has arrived. Under reduced motion
50
+ every mark appears at once, delays included. A test that waits a fixed time for a chart to finish
51
+ arriving waits about 1.1s, or runs under reduced motion. To bring back the old enter timing:
52
+ `--ds-motion-chart-mark-enter-duration: var(--duration-base); --ds-motion-chart-mark-enter-easing:
53
+ var(--ease-decelerate);` - growing and sweeping marks follow `--ds-motion-chart-mark-grow-duration`
54
+ and `--ds-motion-chart-mark-sweep-duration` instead.
55
+
56
+ - **`staggerMs` defaults to `40` on `ds-bar-chart`, `ds-column-chart`, `ds-line-chart`,
57
+ `dsColumnSeries` and `dsLineSeries`, and to `60` on `ds-funnel-chart`** (was `0`); `ds-pie-chart` is
58
+ unchanged, and `ds-heatmap-chart` and `ds-waterfall-chart` gain the input at `40`. A long series
59
+ narrows its step so the whole arrival fits within 260ms, rather than stopping at a 300ms cap after
60
+ which every later mark landed at once. To have a series arrive all at once, set `staggerMs="0"`. A
61
+ visual regression test that screenshots a chart a fixed time after it renders now catches later
62
+ marks still arriving.
63
+
64
+ - **A custom pagination `range` or table `[rangeAnnouncement]` receives zeros on an empty list.**
65
+ `ds-pagination` on an empty list now calls `DS_INTL.pagination.range(0, 0, 0)` (was `(1, 0, 0)`),
66
+ and a paged `ds-table` with no empty-state text now calls its `[rangeAnnouncement]` with `(0, 0, 0)`
67
+ (was never called on an empty table). A formatter that prints first and last unconditionally now
68
+ shows a range of 0 to 0, on the pager and in the table's live-region announcement; guard
69
+ `total === 0` and return your empty-list wording, or, on the table, an empty string to stay silent.
70
+ The default wording returns `Showing 0 of 0`, so an app that never overrides the range text has
71
+ nothing to do.
72
+
73
+ - **`DsIntl` gains a required key: `field.overLimit: (excess: number) => string`.** A complete
74
+ `DsIntl` dictionary, or a complete `field` section of one, declared as a typed object stops
75
+ compiling until it lists it. Overrides passed to `provideDsIntl` are partial and need nothing.
76
+
77
+ - **A horizontal `ds-description-list` stacks every item once a value would get less than
78
+ `--ds-description-list-value-min-width`** (default `14rem`, 224px at a 16px root). Each item is a
79
+ wrapping flex row (was: a two-column grid): when the value column would fall below the minimum,
80
+ the label moves above the value (was: the value squeezed beside the label and broke mid-word). The
81
+ label keeps the label width there, so a longer label still wraps at it, where
82
+ `orientation="stacked"` gives the label the full row. Every item of a list switches at the same
83
+ list width, label width + column gap + value minimum: 364px with
84
+ the defaults, 428px with a 180px label and a 24px gap. `orientation="stacked"` is unchanged, and a
85
+ `ds-description-item` outside a list switches the same way at its own width. In a parent that
86
+ sizes to its content - an inline-block, a float, an absolutely positioned box, a flex row item
87
+ with an auto basis, an `auto` grid track - a list whose widest value is narrower than the minimum
88
+ now stacks; give the list or its parent a width, or lower `--ds-description-list-value-min-width`
89
+ on it. To stack later or earlier, set `--ds-description-list-value-min-width` on the list.
90
+
91
+ - **Subclassing one of these breaks on a name collision.** `BarChartComponent`, `ChartComponent`,
92
+ `ColumnSeriesComponent`, `LineSeriesComponent`, `FunnelChartComponent`, `HeatmapChartComponent`,
93
+ `PieChartComponent`, `ScatterChartComponent` and `WaterfallChartComponent` gained the pinning,
94
+ hover-delay, label-highlight and stagger members; `ColumnChartComponent` and `LineChartComponent`
95
+ only had `pinOnClick` change type; `PaginationComponent` gained `empty`, `TableComponent` gained
96
+ `emptyCell` and `emptyCellText`, `TooltipDirective` gained `detachAncestor`, `disclosesOwnText` and
97
+ `listenToFocusableAncestor`, `TextareaComponent` gained `describedBy`, `maxLengthMode`,
98
+ `nativeMaxLength`, `overflowMirror`, `overflowParts`, `overLimitBy` and `syncOverflowScroll`, and
99
+ `TabsComponent` gained `tablist`, `scrollsHorizontally`, `overflowing`, `showScrollArrows`,
100
+ `canScrollPrevious`, `canScrollNext`, `updateScrollArrows` and `scrollPage`; and three classes
101
+ reachable only through their own entry points gained members too - the internal
102
+ `ChartLegendComponent`, the internal `ChartTooltipPanelComponent` and the internal
103
+ `WaterfallMarksComponent`. Five protected members of `ColumnSeriesComponent` are
104
+ gone: `pinDiscRadius`, `pinGlyph`, `pinGlyphOffset`, `pinGlyphSize` and `slotStepPx`. Build after
105
+ upgrading; rename or mark `override` every member the compiler reports colliding, and delete an
106
+ override whose base member is gone. Subclassing a DS component is unsupported.
107
+
108
+ ### Added
109
+
110
+ - **A `scrollable` `ds-tabs` strip shows previous and next arrows while tabs lie beyond its edges.**
111
+ Each arrow turns the strip by a page of tabs and hides at its own edge; a strip that fits shows
112
+ none. The strip scrolls smoothly unless reduced motion is set, on an arrow and when a selected tab
113
+ comes into view. The arrows sit outside the tab order and are hidden from assistive technology,
114
+ because the arrow keys already bring the selected tab into view; a click on one leaves focus where
115
+ it was. A scrollable horizontal `ds-tabs` host is a grid: the arrows sit either side of the tab
116
+ list, and the panel spans the row below.
117
+
118
+ - **`maxLengthMode` on `ds-textarea`.** `'hard'` (the default) keeps the native `maxlength`: typing
119
+ and paste stop at `maxLength`. `'soft'` lets the text run past it: the counter turns red, the
120
+ characters past the limit are highlighted inside the field, and the field reports `aria-invalid`
121
+ with the counter, which reads out the excess, as its description. Both modes count `value.length`,
122
+ whitespace included. A soft limit does not block a submit: validate the length in the form. The type
123
+ is `TextareaMaxLengthMode`, and `DS_INTL.field.overLimit(excess)` words the excess (default
124
+ `120 characters over the limit`).
125
+
126
+ - **`DS_CONFIG.chart.pinOnClick` and `DS_CONFIG.chart.hoverDelayMs`.** Across every chart,
127
+ `pinOnClick` (default `true`) sets whether a click holds a mark and `hoverDelayMs` (default `500`)
128
+ how long a resting pointer waits before the chart answers.
129
+
130
+ - **`pinOnClick` on `ds-heatmap-chart`, `ds-scatter-chart` and `ds-waterfall-chart`.** A
131
+ `boolean | null` input (default `null`, falling back to `DS_CONFIG.chart.pinOnClick`, then `true`)
132
+ that none of the three had, with the Unpin control the other charts show.
133
+
134
+ - **`staggerMs` on `ds-heatmap-chart` and `ds-waterfall-chart`** (default `40`): the heat map
135
+ staggers its columns, the waterfall its steps. Heat map cells fade in column by column, having not
136
+ animated before.
137
+
138
+ - **Chart entrance tokens.** `--ds-motion-chart-mark-grow-duration` (600ms) and
139
+ `--ds-motion-chart-mark-grow-easing` (`--ease-settle`) time a mark growing out of its baseline;
140
+ `--ds-motion-chart-mark-sweep-duration` (600ms) a ring turning in or a line drawing on;
141
+ `--ds-motion-chart-mark-detail-duration` (180ms) what follows a mark, its value label or marker. They
142
+ sit on three new primitives: `--duration-slowest` (600ms, 0ms under reduced motion),
143
+ `--ease-emphasized-decelerate` and `--ease-settle`, a critically damped spring that never
144
+ overshoots.
145
+
146
+ - **`--ds-description-list-value-min-width`** (default `14rem`): the narrowest value a horizontal
147
+ `ds-description-list` keeps beside its label before every item stacks.
148
+
149
+ ### Changed
150
+
151
+ - **The Unpin control sits at the top end of a chart, on its caption's line** (was: floating over the
152
+ bottom centre, where it covered axis labels, legends and tables). While it shows, a caption leaves
153
+ room for it and a chart with no caption gains the line, so it covers nothing.
154
+
155
+ - **A held mark always shows its pin disc**: a column, a bar, a slice, a funnel stage, a heat map
156
+ cell, a scatter point, a line marker, and a category held under the category cursor (a disc at the
157
+ foot of its band).
158
+
159
+ - **The pointer cursor appears where a click does something**: over a mark a click would hold, a mark
160
+ set `interactive`, and a category band under the category cursor when a press holds it. The gap
161
+ between two bands keeps the default cursor.
162
+
163
+ - **Naming a series or a category highlights it on every chart, and the dimming follows the answered
164
+ mark.** A legend entry dims the other series as before; a `ds-funnel-chart` stage row dims the other
165
+ stages whatever `dimOthers` says; a heat map's scale step dims every cell outside that step; a bar's
166
+ label, and a `ds-chart` category label on the axis without the category cursor (`ds-waterfall-chart`
167
+ included), dim the other bars. `dimOthers` follows the mark the chart has answered rather than the
168
+ raw hover, so the fade waits out the hover delay with the tooltip and follows focus. A hand-composed
169
+ mark reads `CHART_SCALES.categoryLabelHover` and `CHART_SCALES.hoverDelayMs` to answer the same way.
170
+
171
+ - **A column's hover area stops at its own category band** (was: the whole step to the next column),
172
+ so the gap between two columns answers no pointer.
173
+
174
+ - **A chart tooltip fades in rather than scaling in**, so its rows no longer drift into place each
175
+ time it opens on another mark. `--ds-overlay-enter-keyframes` still overrides it; every other
176
+ overlay keeps its scale.
177
+
178
+ - **A category tooltip lists its readings top to bottom, in the order their marks are drawn at that
179
+ category** (was: the order the series were declared). The legend keeps the declared order. A
180
+ hand-composed mark that reports its readings through `CHART_SCALES` places each one by its `y`, its
181
+ height in plot pixels from the top; a reading without it follows the placed ones in declared order.
182
+
183
+ - **A hatched column's stripes run from bottom left to top right, and the tooltip swatch's stripe runs
184
+ the same way.** Width, colour and repeat are unchanged.
185
+
186
+ - **A tooltip swatch is ringed only when its colour would vanish into the panel.** A swatch below 3:1
187
+ contrast against the tooltip background takes a 1.5px ring in the tooltip's text colour, drawn inside
188
+ the 12px dot; every other swatch has no ring (was: every swatch, ringed outside the dot in the
189
+ surface colour). The check follows the theme, so a colour ringed on the light panel can go unringed
190
+ on the dark one.
191
+
192
+ ### Fixed
193
+
194
+ - **A tap that pins a mark on a touch screen stays pinned.** The click a browser sends after the tap
195
+ no longer unpins it.
196
+
197
+ - **Under the category cursor, focus on a column names its category, and focus leaving clears it.**
198
+ Focusing a `dsColumnSeries` column opens the band and the category panel, as focusing a
199
+ `dsLineSeries` marker already did, and focus leaving a column or a marker takes the band and the
200
+ panel down (was: they stayed on screen after focus had gone).
201
+
202
+ - **A `ds-bar-chart` bar grows out of its value axis in a right-to-left page** (was: from the far
203
+ end).
204
+
205
+ - **The `dsTooltip` panel wraps a value with no break opportunity.** A long file name or id ran past
206
+ the panel's edge on one line; it now breaks inside the panel's max width.
207
+
208
+ - **`ds-select`, `ds-autocomplete` and `ds-multi-select` disclose a clipped label.** `ds-select` shows
209
+ its trigger value and option labels, `ds-autocomplete` its option and create labels, and
210
+ `ds-multi-select` its option labels in a tooltip when an ellipsis cuts one off; a label that fits
211
+ shows none.
212
+
213
+ - **A clipped label inside a button or a clickable row discloses on keyboard focus.** A
214
+ `dsTooltipWhenClipped` host that cannot take focus opened on hover only. It now also opens when
215
+ keyboard focus lands on its nearest focusable ancestor, and closes on that ancestor's blur, click or
216
+ any key; a mouse click opens nothing, an ancestor focusable only through a negative `tabindex`
217
+ (such as a `<main tabindex="-1">` that takes focus on navigation) opens nothing, and of several
218
+ clipped hosts in one ancestor only the first opens. This covers `ds-select`'s trigger value and
219
+ `ds-table`'s clipped cells in an interactive row. A plain `dsTooltip` without
220
+ `dsTooltipWhenClipped` on a non-focusable element stays hover-only.
221
+
222
+ - **A clipped-text tooltip is read once by a screen reader.** A `dsTooltipWhenClipped` tip whose text
223
+ the host already contains set `aria-describedby` on the focused element, so the text was announced
224
+ as its name and again as its description. It now sets none, on a focusable host or its ancestor; a
225
+ tip given a `dsTooltip` that says more than the host still describes it, as does a plain
226
+ `dsTooltip`. A test asserting `aria-describedby` on a clipped disclosure finds none.
227
+
228
+ - **`ds-pagination` handles an empty list.** With `total` at `0` the range read `Showing 1-0 of 0` and
229
+ page 1 was marked current; it now reads `Showing 0 of 0`, disables every button, Previous and Next
230
+ included, and marks none current.
231
+
232
+ - **A paged `ds-table` announces an emptied table.** Its live region went silent when a filter or new
233
+ data left the table with no rows; it now announces the table's empty state - the `[empty]` content
234
+ or `emptyTemplate` text - or, with no empty-state text, its range announcement (`Showing 0 of 0` by
235
+ default).
236
+
237
+ ### What you can now DELETE
238
+
239
+ | Delete | Why | Replace with |
240
+ | --- | --- | --- |
241
+ | a `pinOnClick`, `pinOnClick="true"` or `[pinOnClick]="true"` binding on a chart or a `dsColumnSeries` / `dsLineSeries` mark | a click holds a mark by default, so a binding of `true` restates it | nothing; keep it where `DS_CONFIG.chart.pinOnClick` is `false` and this chart is the exception |
242
+ | a `cursorPin`, `cursorPin="true"` or `[cursorPin]="true"` binding on `ds-chart` | a press holds the category cursor by default, so a binding of `true` restates it | nothing; keep it where `DS_CONFIG.chart.pinOnClick` is `false` and this chart is the exception |
243
+ | a `[title]=` or `[attr.title]=` on a `ds-select`, `ds-autocomplete` or `ds-multi-select` that repeats the selected or option label | the picker shows a clipped label in full in a tooltip, so the title adds a second, native one | nothing; a `title` that says more than the label stays legitimate |
244
+ | an `[orientation]` on `ds-description-list` switched on a viewport breakpoint, such as `'stacked' : 'horizontal'`, only to stack a narrow list | a horizontal list stacks by itself once a value would get less than `--ds-description-list-value-min-width` | `--ds-description-list-value-min-width` on the list where the switch has to move; keep a switch driven by something other than width |
245
+
3
246
  ## 0.14.1 — 2026-09-24
4
247
 
5
248
  ### Breaking
package/components.md CHANGED
@@ -226,7 +226,7 @@ New: `autosize: boolean = false` (grows with content; forces `resize='none'`), `
226
226
  Methods: `focus(options?)`, `selectionStart` / `selectionEnd` (reads), `setSelectionRange(start, end, direction?)`, `select()` - all forwarded to the native `<textarea>`, so an editor toolbar never queries the component's DOM. A value written through `value` lands a microtask later and moves the caret to the end; set a range after `value.set(...)` from a `setTimeout`.
227
227
 
228
228
  <!-- inputs:ds-textarea -->
229
- All inputs: `hint: string = ''`, `error: string = ''`, `warning: string = ''`, `reserveMessage: boolean | null = null`, `messageIcon: IconName | false | null = null`, `errors: readonly DsFieldError[] = []`, `invalid: boolean = false`, `touched: boolean = false`, `hidden: boolean = false`, `value: string = ''`, `size: 'sm' | 'md' | 'lg' = null`, `label: string = ''`, `placeholder: string = ''`, `disabled: boolean = false`, `readOnly: boolean = false`, `readonlyBinding: boolean = false`, `success: string = ''`, `required: boolean = false`, `optional: boolean = false`, `rows: number = 3`, `name: string | null = null`, `autosize: boolean = false`, `minRows: number | null = null`, `maxRows: number | null = null`, `resize: 'none' | 'vertical' | 'horizontal' | 'both' = 'vertical'`, `ariaLabel: string | null = null`, `maxLength: number | null = null`, `minLength: number | null = null`, `pattern: readonly RegExp[] = []`
229
+ All inputs: `hint: string = ''`, `error: string = ''`, `warning: string = ''`, `reserveMessage: boolean | null = null`, `messageIcon: IconName | false | null = null`, `errors: readonly DsFieldError[] = []`, `invalid: boolean = false`, `touched: boolean = false`, `hidden: boolean = false`, `value: string = ''`, `size: 'sm' | 'md' | 'lg' = null`, `label: string = ''`, `placeholder: string = ''`, `disabled: boolean = false`, `readOnly: boolean = false`, `readonlyBinding: boolean = false`, `success: string = ''`, `required: boolean = false`, `optional: boolean = false`, `rows: number = 3`, `name: string | null = null`, `autosize: boolean = false`, `minRows: number | null = null`, `maxRows: number | null = null`, `resize: 'none' | 'vertical' | 'horizontal' | 'both' = 'vertical'`, `ariaLabel: string | null = null`, `maxLength: number | null = null`, `maxLengthMode: 'hard' | 'soft' = 'hard'`, `minLength: number | null = null`, `pattern: readonly RegExp[] = []`
230
230
  <!-- /inputs -->
231
231
 
232
232
  #### `<ds-number-stepper>` — `NumberStepperComponent`
@@ -575,6 +575,8 @@ All inputs: `nodes: readonly TreeNode[] = []`, `expandedIds: Set<string>`, `sele
575
575
  <!-- /inputs -->
576
576
 
577
577
  #### `<ds-description-list>` — `DescriptionListComponent`
578
+ **A horizontal list stacks when a value would get too narrow.** Each item is a wrapping flex row: once the list is narrower than label width + column gap + `--ds-description-list-value-min-width` (14rem), every item puts its label above its value at once, and the switch follows `--ds-description-list-label-width` by itself. A standalone `ds-description-item` switches the same way at its own width. In a parent that sizes to its content (inline-block, float, absolute position, a flex row item with an auto basis, an `auto` grid track) a list whose widest value is under the minimum stacks; give it a width there. `orientation="stacked"` stacks at every width.
579
+ Tokens: `--ds-description-list-label-width`, `--ds-description-list-column-gap`, `--ds-description-list-row-gap`, `--ds-description-list-value-min-width`
578
580
 
579
581
  <!-- inputs:ds-description-list -->
580
582
  All inputs: `orientation: 'horizontal' | 'stacked' = 'horizontal'`
@@ -673,6 +675,7 @@ All inputs: `items: BreadcrumbItem[] | null = null`, `separator: IconName | null
673
675
  Container holds `<ds-tab label="…">` children.
674
676
  Tabs inputs: `selectedIndex: model<number> = 0`, `variant: 'line' | 'pills' = 'line'`
675
677
  Tab inputs: `label: required string`, `icon: IconName | null = null`, `count: number | null = null`, `disabled: boolean = false`. The tab's projected content renders in the active panel.
678
+ `scrollable` scrolls a horizontal strip inside its own box and, while tabs lie beyond an edge, shows a previous/next arrow on that side that turns the strip by a page (hidden at its own edge; no arrows on a strip that fits). The arrows are pointer affordances outside the tab order and hidden from assistive technology, since arrow keys already bring the selected tab into view.
676
679
  Tokens: `--ds-tab-label-color`, `--ds-tab-label-color-hover`, `--ds-tab-label-color-active`, `--ds-tab-indicator-color`, `--ds-tab-indicator-width`, `--ds-tab-padding-x`, `--ds-tab-padding-y`, `--ds-tabs-divider`, `--ds-tabs-pills-bg-color`, `--ds-tab-pill-bg-color-hover` (inactive hover, defaults to `var(--primary-subtle)`), `--ds-tab-pill-bg-color-active` (defaults to `var(--surface-default)` — elevated card), `--ds-tab-pill-bg-color-active-hover` (defaults to `var(--primary-subtle)`), `--ds-tab-pill-label-color-active` (defaults to `var(--primary-strong)`), `--ds-tab-pill-radius` (defaults to `var(--radius-md)` — same as buttons/inputs; override per-instance to `var(--radius-pill)` for fully round pills).
677
680
 
678
681
  <!-- inputs:ds-tabs -->
@@ -687,7 +690,7 @@ All inputs: `steps: readonly string[] = []`, `current: number = 0`, `labelPositi
687
690
  <!-- /inputs -->
688
691
 
689
692
  #### `<ds-pagination>` — `PaginationComponent`
690
- Inputs: `total: required number`, `pageSize: model<number> = 10`, `currentPage: model<number> = 1`, `pageSizeOptions: number[] = [10, 25, 50, 100]`, `showLabel: boolean = true`, `size: DsSize | null = null` (unset resolves `DS_CONFIG.pagination.size`, then `DS_CONFIG.control.size`, then `sm`), `layout: PaginationLayout | null = null` (`'grouped' | 'spread'`; unset resolves `DS_CONFIG.pagination.layout`, then `'grouped'`; `'spread'` gives the nav full width and pushes the label and the controls to opposite edges), `loading: boolean = false` (every control disables, the range label is masked with a `ds-skeleton` so a stale `total` is never quoted, and the nav reports `aria-busy`). Inside `ds-table` `size` and `layout` arrive as `paginationSize` / `paginationLayout`, and `loading` is set from `loading="skeleton"`.
693
+ Inputs: `total: required number`, `pageSize: model<number> = 10`, `currentPage: model<number> = 1`, `pageSizeOptions: number[] = [10, 25, 50, 100]`, `showLabel: boolean = true`, `size: DsSize | null = null` (unset resolves `DS_CONFIG.pagination.size`, then `DS_CONFIG.control.size`, then `sm`), `layout: PaginationLayout | null = null` (`'grouped' | 'spread'`; unset resolves `DS_CONFIG.pagination.layout`, then `'grouped'`; `'spread'` gives the nav full width and pushes the label and the controls to opposite edges), `loading: boolean = false` (every control disables, the range label is masked with a `ds-skeleton` so a stale `total` is never quoted, and the nav reports `aria-busy`). Inside `ds-table` `size` and `layout` arrive as `paginationSize` / `paginationLayout`, and `loading` is set from `loading="skeleton"`. With `total` at 0 the label is `DS_INTL.pagination.range(0, 0, 0)`, `Showing 0 of 0` by default, and every page button is disabled with none marked current.
691
694
  Outputs: `(currentPageChange): number`, `(pageSizeChange): number`
692
695
 
693
696
  <!-- inputs:ds-pagination -->
@@ -808,9 +811,9 @@ All inputs: `align: 'start' | 'end' = 'start'`, `placement: 'top' | 'bottom' | '
808
811
  <!-- /inputs -->
809
812
 
810
813
  #### `[dsTooltip]` — `TooltipDirective`
811
- Attribute directive. Apply to any focusable element.
812
- Inputs: `dsTooltip: string = ''` (the text; empty disables), `dsTooltipPlacement: 'top' | 'bottom' | 'left' | 'right' = 'top'`, `dsTooltipDelay: number = 120` (ms)
813
- Renders `<ds-tooltip-panel>` via CDK overlay on hover / focus; hides on leave / blur.
814
+ Attribute directive. Apply to any focusable element; with `dsTooltipWhenClipped` also to a label that cannot take focus.
815
+ Inputs: `dsTooltip: string = ''` (the text; empty disables), `dsTooltipPlacement: 'top' | 'bottom' | 'left' | 'right' = 'top'`, `dsTooltipDelay: number = 120` (ms), `dsTooltipWhenClipped` (open only while the host shows less text than it holds; an empty `dsTooltip` then discloses the host's own text)
816
+ Renders `<ds-tooltip-panel>` via CDK overlay on hover / focus; hides on leave / blur. A `dsTooltipWhenClipped` host that cannot take focus (a label inside a button, a cell of a clickable row) also opens when keyboard focus lands on its nearest focusable ancestor, and closes on that ancestor's blur, click or any key; a mouse click opens nothing, and of several clipped hosts in one ancestor only the first in document order opens. A clipped tip whose text the host already contains sets no `aria-describedby` (the text is in the DOM already); a `dsTooltip` that says more than the host, and a plain `dsTooltip`, describe the focused element. A plain `dsTooltip` on a non-focusable element stays hover-only: put an info tooltip on its own focusable element, not inside a button. The panel wraps a value with no break opportunity (a file name, an id) inside its max width.
814
817
 
815
818
  <!-- inputs:[dsTooltip] -->
816
819
  All inputs: `dsTooltip: string = ''`, `dsTooltipPlacement: 'top' | 'bottom' | 'left' | 'right' = 'top'`, `dsTooltipDelay: number = 120`, `dsTooltipWhenClipped: boolean = false`
@@ -841,7 +844,7 @@ Opening a row: give one column `link: (row) => <route target> | null` and its va
841
844
  Cell templates: `<ng-template dsCellTemplate="<colKey>" [dsCellTemplateOf]="rows" let-row>…</ng-template>` — bound to the same rows as `[data]`, `dsCellTemplateOf` types `row` as `T` under strict templates (a field typo is a compile error) and is never read at runtime. Without it `row` is `unknown`; narrow via a helper method on the host. `CellTemplateContext<T>` (`$implicit` and `row`) is exported.
842
845
  Content slots: `[empty]` (rendered when `data.length === 0`), `[bulk-actions]` (rendered in the bulk action bar when `selectable && some selected`)
843
846
  Loading modes: `'skeleton'` replaces rows with shimmer placeholders driven by the global `--skeleton-shimmer-x` keyframe; `'overlay'` keeps existing rows visible behind a translucent layer with a centred spinner; under `'skeleton'` the footer pager takes `loading` as well - its controls disable and its range label is masked, so it never quotes the previous query's count. `'overlay'` leaves the pager live, like the header.
844
- Footer pager: `pageSizeOptions`, `showPageSize`, `showLabel`, `paginationSize: DsSize | null = null` and `paginationLayout: PaginationLayout | null = null` are the embedded `ds-pagination`'s own inputs forwarded one-to-one; the last two unset resolve `DS_CONFIG.pagination.size` (then `DS_CONFIG.control.size`, then `sm`) and `DS_CONFIG.pagination.layout` (then `'grouped'`), so an app whose every pager wants `md` / `spread` says it once in the config.
847
+ Footer pager: `pageSizeOptions`, `showPageSize`, `showLabel`, `paginationSize: DsSize | null = null` and `paginationLayout: PaginationLayout | null = null` are the embedded `ds-pagination`'s own inputs forwarded one-to-one; the last two unset resolve `DS_CONFIG.pagination.size` (then `DS_CONFIG.control.size`, then `sm`) and `DS_CONFIG.pagination.layout` (then `'grouped'`), so an app whose every pager wants `md` / `spread` says it once in the config. A paged table with no rows announces its empty state's text (`[empty]` or `emptyTemplate`); with none it announces `rangeAnnouncement(0, 0, 0)`, `Showing 0 of 0` by default.
845
848
  Tokens: `--ds-table-border: var(--border-default)`, `--ds-table-radius: var(--radius-md)`, `--ds-table-bg-color`, `--ds-table-head-text-color: var(--text-secondary)`, `--ds-table-head-bg-color: var(--surface-secondary)`, `--ds-table-head-font-size: var(--font-size-xs)`, `--ds-table-row-hover-bg-color`, `--ds-table-row-selected-bg-color`, `--ds-table-divider`, `--ds-table-sort-active-icon-color`, `--ds-table-cell-padding-x/y`, `--ds-table-utility-column-width` (the column the column picker and the row-actions ⋮ ride in; default `--space-6`, the buttons' own size, so the column is as wide as its padding makes it) and `--ds-table-utility-column-padding-x` (one length for both sides; default the cell padding chain), `--ds-table-footer-padding-y` / `-top` / `-bottom` (the pagination footer's block padding; default `--space-3`). (Renamed 2026-06: `--ds-table-header-*` → `--ds-table-head-*`, matching the tokens reference.)
846
849
 
847
850
  <!-- inputs:ds-table -->
@@ -880,10 +883,10 @@ All inputs: `dsTableExport: boolean = true`, `exportFilename: string = 'table.cs
880
883
  ### Charts
881
884
 
882
885
  #### `<ds-bar-chart>` — `BarChartComponent`
883
- Inputs: `data: readonly BarChartRow[]` (required), `max: number | null = null` (track length is relative to this; null uses the largest value, so the longest row always fills its track — a max BELOW the largest value is allowed and its bar clips at the track edge), `caption: string | null = null`, `summary: string | null = null` (accessible name; generated from the data when omitted), `dataTable: 'none' | 'toggle' | 'visible' = 'none'` (`'toggle'` renders a closed `<details>`; `'none'` is only correct when the same numbers are already in the DOM nearby), `showPercent: boolean = true`, `loading: boolean = false`, `emptyText: string = 'No data'`, `error: boolean = false`, `errorText: string = 'Could not load the data'`, `valueFormat: (value: number) => string`, `interactive: boolean = false`, `tooltip: 'item' | 'none' = 'item'`, `staggerMs: number = 0`
886
+ Inputs: `data: readonly BarChartRow[]` (required), `max: number | null = null` (track length is relative to this; null uses the largest value, so the longest row always fills its track — a max BELOW the largest value is allowed and its bar clips at the track edge), `caption: string | null = null`, `summary: string | null = null` (accessible name; generated from the data when omitted), `dataTable: 'none' | 'toggle' | 'visible' = 'none'` (`'toggle'` renders a closed `<details>`; `'none'` is only correct when the same numbers are already in the DOM nearby), `showPercent: boolean = true`, `loading: boolean = false`, `emptyText: string = 'No data'`, `error: boolean = false`, `errorText: string = 'Could not load the data'`, `valueFormat: (value: number) => string`, `interactive: boolean = false`, `tooltip: 'item' | 'none' = 'item'`, `staggerMs: number = 40`
884
887
  Output: `(rowClicked): BarChartRow` — emits the clicked row.
885
888
  Interaction: `interactive: boolean = false` turns on the affordance — pointer cursor, hover tint and the keyboard route. `dimOthers: boolean = false` is a SEPARATE opt-in that fades every other mark while one is hovered or focused; off by default, because the fade costs the separation between the faded marks (dE 14.8 -> 2.1 at the default dim opacity) — it buys loudness for one mark and pays for it with the rest. The output fires whether or not it is set. The keyboard route is ONE tab stop for the whole chart, not one per mark: arrows walk the marks, Home and End reach the extremes, and the ends wrap. `tooltip: 'item' | 'none' = 'item'` opens a panel for the hovered, tapped or focused mark; a tap latches it until the next tap outside. Project an `<ng-template #dsChartTooltip let-tip>` to replace its contents — `tip` is `{ category: string; entries: { label, value, formatted, color }[] }`.
886
- Motion: marks that leave finish leaving before marks that arrive start. `staggerMs: number = 0` spaces the arrivals; `40` is the documented step and the total is capped at 300ms. Every duration is a `--ds-motion-chart-*` role, so `prefers-reduced-motion` zeroes them with nothing per chart.
889
+ Motion: marks that leave finish leaving before marks that arrive start. A bar grows out of the value axis, then its value rises in. `staggerMs: number = 40` spaces the arrivals, narrowed so a series finishes arriving within 260ms; `0` brings every mark in at once. Every duration is a `--ds-motion-chart-*` role, so `prefers-reduced-motion` shows every mark at once, delays included.
887
890
  States: `loading` draws skeleton marks at the real count; `error` shows `errorText` in place of the plot, which is a different claim from an empty `data` showing `emptyText`.
888
891
  Row: `BarChartRow = { label: string; value: number; percent?: number; color?: string }`. `percent` is derived from `value / max` when omitted.
889
892
  `value` may be a `[low, high]` pair instead of a number: the bar spans between its own ends rather than from zero, which compares a duration and its PLACEMENT at once, and the ends may be written either way round. `target` draws a tick across the bar at one reading; `ranges` paints qualitative bands behind it, given as their upper bounds in ascending order. Together they are the bullet chart, which is a bar with two extras rather than a chart type. The bands take one neutral hue at rising opacity, never the series palette. Tokens: `--ds-bar-chart-band-color`, `--ds-bar-chart-target-color`, `--ds-bar-chart-target-width`, `--ds-bar-chart-target-overhang`.
@@ -894,15 +897,15 @@ Rhythm: a label belongs to the bar under it, so `--ds-bar-chart-label-gap` is de
894
897
  Tokens: `--ds-bar-chart-track-color`, `--ds-bar-chart-track-height`, `--ds-bar-chart-row-gap`, `--ds-bar-chart-label-gap`.
895
898
 
896
899
  <!-- inputs:ds-bar-chart -->
897
- All inputs: `data: required readonly BarChartRow[]`, `max: number | null = null`, `frame: 'auto' | 'none' = null`, `tooltipLingerMs: number | null = null`, `caption: string | null = null`, `summary: string | null = null`, `dataTable: 'toggle' | 'visible' | 'none' = null`, `partOfWhole: boolean = false`, `showPercent: boolean = true`, `loading: boolean = false`, `emptyText: string | null = null`, `error: boolean = false`, `errorText: string | null = null`, `valueFormat: ChartValueFormat | null = null`, `interactive: boolean = false`, `pinOnClick: boolean = false`, `dimOthers: boolean = false`, `highlighted: string | null = null`, `staggerMs: number = 0`, `tooltip: 'item' | 'none' = 'item'`
900
+ All inputs: `data: required readonly BarChartRow[]`, `max: number | null = null`, `frame: 'auto' | 'none' = null`, `tooltipLingerMs: number | null = null`, `caption: string | null = null`, `summary: string | null = null`, `dataTable: 'toggle' | 'visible' | 'none' = null`, `partOfWhole: boolean = false`, `showPercent: boolean = true`, `loading: boolean = false`, `emptyText: string | null = null`, `error: boolean = false`, `errorText: string | null = null`, `valueFormat: ChartValueFormat | null = null`, `pinOnClick: boolean | null = null`, `interactive: boolean = false`, `dimOthers: boolean = false`, `highlighted: string | null = null`, `staggerMs: number = 40`, `tooltip: 'item' | 'none' = 'item'`
898
901
  <!-- /inputs -->
899
902
 
900
903
  #### `<ds-column-chart>` — `ColumnChartComponent`
901
904
  Vertical columns for a short series read left to right — months, stages, teams — measured against one value axis whose ticks snap to round numbers.
902
- Inputs: `data: readonly ColumnChartPoint[]` (required), `showValues: boolean = true` (each column prints its own value above itself), `tickCount: number = 5` (a hint: ticks snap to a round step, so an axis asked for three ends up with five and one asked for ten stops at eight), `caption: string | null = null`, `summary: string | null = null`, `dataTable: 'none' | 'toggle' | 'visible' = 'none'`, `loading: boolean = false`, `emptyText: string = 'No data'`, `error: boolean = false`, `errorText: string = 'Could not load the data'`, `valueFormat: (value: number) => string`, `interactive: boolean = false`, `tooltip: 'item' | 'none' = 'item'`, `staggerMs: number = 0`, `thresholds: readonly ChartThreshold[] = []`
905
+ Inputs: `data: readonly ColumnChartPoint[]` (required), `showValues: boolean = true` (each column prints its own value above itself), `tickCount: number = 5` (a hint: ticks snap to a round step, so an axis asked for three ends up with five and one asked for ten stops at eight), `caption: string | null = null`, `summary: string | null = null`, `dataTable: 'none' | 'toggle' | 'visible' = 'none'`, `loading: boolean = false`, `emptyText: string = 'No data'`, `error: boolean = false`, `errorText: string = 'Could not load the data'`, `valueFormat: (value: number) => string`, `interactive: boolean = false`, `tooltip: 'item' | 'none' = 'item'`, `staggerMs: number = 40`, `thresholds: readonly ChartThreshold[] = []`
903
906
  Output: `(pointClicked): ColumnChartPoint` — same contract as `ds-bar-chart`'s `rowClicked`.
904
907
  Interaction: `interactive: boolean = false` turns on the affordance — pointer cursor, hover tint and the keyboard route. `dimOthers: boolean = false` is a SEPARATE opt-in that fades every other mark while one is hovered or focused; off by default, because the fade costs the separation between the faded marks (dE 14.8 -> 2.1 at the default dim opacity) — it buys loudness for one mark and pays for it with the rest. The output fires whether or not it is set. The keyboard route is ONE tab stop for the whole chart, not one per mark: arrows walk the marks, Home and End reach the extremes, and the ends wrap. `tooltip: 'item' | 'none' = 'item'` opens a panel for the hovered, tapped or focused mark; a tap latches it until the next tap outside. Project an `<ng-template #dsChartTooltip let-tip>` to replace its contents — `tip` is `{ category: string; entries: { label, value, formatted, color }[] }`.
905
- Motion: marks that leave finish leaving before marks that arrive start. `staggerMs: number = 0` spaces the arrivals; `40` is the documented step and the total is capped at 300ms. Every duration is a `--ds-motion-chart-*` role, so `prefers-reduced-motion` zeroes them with nothing per chart.
908
+ Motion: marks that leave finish leaving before marks that arrive start. A column grows out of its baseline, then its value rises in. `staggerMs: number = 40` spaces the arrivals, narrowed so a series finishes arriving within 260ms; `0` brings every mark in at once. Every duration is a `--ds-motion-chart-*` role, so `prefers-reduced-motion` shows every mark at once, delays included.
906
909
  States: `loading` draws skeleton marks at the real count; `error` shows `errorText` in place of the plot, which is a different claim from an empty `data` showing `emptyText`.
907
910
  Point: `ColumnChartPoint = { label: string; value: number; color?: string }`
908
911
  Thresholds: `ChartThreshold = { value: number; label?: string; color?: string; to?: number; dash?: 'solid' | 'dashed' | 'dotted' }` draws a target, a budget or an SLA across the plot, behind the columns. ONE number, not a coordinate pair; `to` makes the same object a band between two readings, in either order; `dash` defaults to `'dashed'`. A threshold widens the value axis to hold it, and is named in the generated description, so a target above every column is neither drawn off the plot nor left unsaid.
@@ -910,7 +913,7 @@ Colour: the categorical palette by position — `--ds-chart-series-1-color` onwa
910
913
  Tokens: `--ds-column-chart-plot-height`, `--ds-column-chart-column-width` (share of its own cell), `--ds-column-chart-column-max-width` (the cap that stops a five-column chart drawing slabs wider than their labels), `--ds-column-chart-column-gap`, `--ds-column-chart-grid-line-color`, `--ds-column-chart-value-space` (headroom for the value printed above a full-height column), `--ds-column-chart-axis-width` (the tick-label column; widen it for a `valueFormat` that prints longer ticks, which are clipped rather than wrapped). Reference lines take `--ds-chart-threshold-color`, `--ds-chart-threshold-band-opacity`, `--ds-chart-threshold-dashed-pattern` and `--ds-chart-threshold-dotted-pattern`.
911
914
 
912
915
  <!-- inputs:ds-column-chart -->
913
- All inputs: `data: required readonly ColumnChartPoint[] | readonly ColumnChartSeries[]`, `stack: 'none' | 'grouped' | 'stacked' | 'normalized' = 'none'`, `thresholds: readonly ChartThreshold[] = []`, `showValues: boolean = true`, `tickCount: number = 5`, `frame: 'auto' | 'none' = null`, `tooltipLingerMs: number | null = null`, `caption: string | null = null`, `summary: string | null = null`, `dataTable: 'toggle' | 'visible' | 'none' = null`, `partOfWhole: boolean = false`, `loading: boolean = false`, `emptyText: string | null = null`, `error: boolean = false`, `errorText: string | null = null`, `valueFormat: ChartValueFormat | null = null`, `interactive: boolean = false`, `pinOnClick: boolean = false`, `dimOthers: boolean = false`, `staggerMs: number = 0`, `tooltip: 'item' | 'none' = 'item'`, `tooltipAnchor: 'mark' | 'cell' = 'mark'`
916
+ All inputs: `data: required readonly ColumnChartPoint[] | readonly ColumnChartSeries[]`, `stack: 'none' | 'grouped' | 'stacked' | 'normalized' = 'none'`, `thresholds: readonly ChartThreshold[] = []`, `showValues: boolean = true`, `tickCount: number = 5`, `frame: 'auto' | 'none' = null`, `tooltipLingerMs: number | null = null`, `caption: string | null = null`, `summary: string | null = null`, `dataTable: 'toggle' | 'visible' | 'none' = null`, `partOfWhole: boolean = false`, `loading: boolean = false`, `emptyText: string | null = null`, `error: boolean = false`, `errorText: string | null = null`, `valueFormat: ChartValueFormat | null = null`, `interactive: boolean = false`, `pinOnClick: boolean | null = null`, `dimOthers: boolean = false`, `staggerMs: number = 40`, `tooltip: 'item' | 'none' = 'item'`, `tooltipAnchor: 'mark' | 'cell' = 'mark'`
914
917
  <!-- /inputs -->
915
918
 
916
919
  #### `<ds-pie-chart>` — `PieChartComponent`
@@ -918,7 +921,7 @@ A ring that splits one total into its parts, with the middle free for the total
918
921
  Inputs: `data: readonly PieChartSlice[]` (required), `centerValue: string | null = null`, `centerLabel: string | null = null`, `legend: 'end' | 'bottom' | 'none' = 'end'`, `maxSlices: number | null = null`, `otherLabel: string | null = null` (unset: `DS_INTL.chart.other`), `innerRadius: number = 0.68`, `caption: string | null = null`, `summary: string | null = null`, `dataTable: 'none' | 'toggle' | 'visible' = 'none'`, `loading: boolean = false`, `emptyText: string = 'No data'`, `error: boolean = false`, `errorText: string = 'Could not load the data'`, `valueFormat: (value: number) => string`, `interactive: boolean = false`, `tooltip: 'item' | 'none' = 'item'`, `staggerMs: number = 0`
919
922
  Output: `(sliceClicked): PieChartSlice`
920
923
  Interaction: `interactive: boolean = false` turns on the affordance — pointer cursor, hover tint and the keyboard route. `dimOthers: boolean = false` is a SEPARATE opt-in that fades every other mark while one is hovered or focused; off by default, because the fade costs the separation between the faded marks (dE 14.8 -> 2.1 at the default dim opacity) — it buys loudness for one mark and pays for it with the rest. The output fires whether or not it is set. The keyboard route is ONE tab stop for the whole chart, not one per mark: arrows walk the marks, Home and End reach the extremes, and the ends wrap. `tooltip: 'item' | 'none' = 'item'` opens a panel for the hovered, tapped or focused mark; a tap latches it until the next tap outside. Project an `<ng-template #dsChartTooltip let-tip>` to replace its contents — `tip` is `{ category: string; entries: { label, value, formatted, color }[] }`.
921
- Motion: the RING fades as one object rather than slice by slice — arcs share their edges, and fading them one at a time lets the background through every seam. `staggerMs` is accepted for parity with the other four charts and has no effect here, because there is nothing to stagger. Marks that leave finish leaving before marks that arrive start. `staggerMs: number = 0` spaces the arrivals; `40` is the documented step and the total is capped at 300ms. Every duration is a `--ds-motion-chart-*` role, so `prefers-reduced-motion` zeroes them with nothing per chart.
924
+ Motion: the RING turns into place as one object rather than slice by slice - arcs share their edges, and moving them one at a time lets the background through every seam. The legend swatches and the centre follow once it has landed. `staggerMs` is accepted for parity with the other charts and has no effect here, because there is nothing to stagger. Marks that leave finish leaving before marks that arrive start. Every duration is a `--ds-motion-chart-*` role, so `prefers-reduced-motion` shows the ring at once.
922
925
  States: `loading` draws skeleton marks at the real count; `error` shows `errorText` in place of the plot, which is a different claim from an empty `data` showing `emptyText`.
923
926
  Slice: `PieChartSlice = { id: string; label: string; value: number; slot?: number }`. `slot` is a 1-based palette slot: pinning a slice keeps every other slice's colour where it is when one is filtered out of `data`; left off, the colour follows the index and the whole ring repaints.
924
927
  Colour: slices ARE different things, so this is the chart the categorical palette exists for — `--ds-chart-series-1-color` … `--ds-chart-series-8-color`.
@@ -929,15 +932,15 @@ Behaviour: percentages use largest-remainder rounding, so a legend's shares add
929
932
  Tokens: `--ds-pie-chart-size`, `--ds-pie-chart-gap`, `--ds-pie-chart-swatch-size`, `--ds-pie-chart-legend-row-gap`, `--ds-pie-chart-legend-row-height`, `--ds-chart-legend-hover-bg-color` and `--ds-chart-legend-hover-text-color` (shared with every chart legend), `--ds-pie-chart-outline-width` (the placeholder ring drawn when there is no data and when every slice is zero).
930
933
 
931
934
  <!-- inputs:ds-pie-chart -->
932
- All inputs: `data: required readonly PieChartSlice[]`, `centerValue: string | null = null`, `centerLabel: string | null = null`, `legend: 'end' | 'bottom' | 'none' = 'end'`, `maxSlices: number | null = null`, `otherLabel: string | null = null`, `innerRadius: number = 0.68`, `frame: 'auto' | 'none' = null`, `tooltipLingerMs: number | null = null`, `caption: string | null = null`, `summary: string | null = null`, `dataTable: 'toggle' | 'visible' | 'none' = null`, `partOfWhole: boolean = true`, `loading: boolean = false`, `emptyText: string | null = null`, `error: boolean = false`, `errorText: string | null = null`, `valueFormat: ChartValueFormat | null = null`, `interactive: boolean = false`, `pinOnClick: boolean = false`, `dimOthers: boolean = false`, `staggerMs: number = 0`, `tooltip: 'item' | 'none' = 'item'`
935
+ All inputs: `data: required readonly PieChartSlice[]`, `centerValue: string | null = null`, `centerLabel: string | null = null`, `legend: 'end' | 'bottom' | 'none' = 'end'`, `maxSlices: number | null = null`, `otherLabel: string | null = null`, `innerRadius: number = 0.68`, `frame: 'auto' | 'none' = null`, `tooltipLingerMs: number | null = null`, `caption: string | null = null`, `summary: string | null = null`, `dataTable: 'toggle' | 'visible' | 'none' = null`, `partOfWhole: boolean = true`, `loading: boolean = false`, `emptyText: string | null = null`, `error: boolean = false`, `errorText: string | null = null`, `valueFormat: ChartValueFormat | null = null`, `pinOnClick: boolean | null = null`, `interactive: boolean = false`, `dimOthers: boolean = false`, `staggerMs: number = 0`, `tooltip: 'item' | 'none' = 'item'`
933
936
  <!-- /inputs -->
934
937
 
935
938
  #### `<ds-funnel-chart>` — `FunnelChartComponent`
936
939
  Stages of a journey, drawn top to bottom in the order you give them — they are never sorted, because the order is the meaning.
937
- Inputs: `data: readonly FunnelChartStage[]` (required), `shape: 'taper' | 'width' | 'area' = 'area'`, `showTable: boolean = true` (the aligned stage table under the funnel: value, share of the first stage, and how much fell away since the stage above), `caption: string | null = null`, `summary: string | null = null`, `dataTable: 'none' | 'toggle' | 'visible' = 'none'`, `loading: boolean = false`, `emptyText: string = 'No data'`, `error: boolean = false`, `errorText: string = 'Could not load the data'`, `valueFormat: (value: number) => string`, `interactive: boolean = false`, `tooltip: 'item' | 'none' = 'item'`, `staggerMs: number = 0`
940
+ Inputs: `data: readonly FunnelChartStage[]` (required), `shape: 'taper' | 'width' | 'area' = 'area'`, `showTable: boolean = true` (the aligned stage table under the funnel: value, share of the first stage, and how much fell away since the stage above), `caption: string | null = null`, `summary: string | null = null`, `dataTable: 'none' | 'toggle' | 'visible' = 'none'`, `loading: boolean = false`, `emptyText: string = 'No data'`, `error: boolean = false`, `errorText: string = 'Could not load the data'`, `valueFormat: (value: number) => string`, `interactive: boolean = false`, `tooltip: 'item' | 'none' = 'item'`, `staggerMs: number = 60`
938
941
  Output: `(stageClicked): FunnelChartStage`
939
942
  Interaction: `interactive: boolean = false` turns on the affordance — pointer cursor, hover tint and the keyboard route. `dimOthers: boolean = false` is a SEPARATE opt-in that fades every other mark while one is hovered or focused; off by default, because the fade costs the separation between the faded marks (dE 14.8 -> 2.1 at the default dim opacity) — it buys loudness for one mark and pays for it with the rest. The output fires whether or not it is set. The keyboard route is ONE tab stop for the whole chart, not one per mark: arrows walk the marks, Home and End reach the extremes, and the ends wrap. `tooltip: 'item' | 'none' = 'item'` opens a panel for the hovered, tapped or focused mark; a tap latches it until the next tap outside. Project an `<ng-template #dsChartTooltip let-tip>` to replace its contents — `tip` is `{ category: string; entries: { label, value, formatted, color }[] }`.
940
- Motion: marks that leave finish leaving before marks that arrive start. `staggerMs: number = 0` spaces the arrivals; `40` is the documented step and the total is capped at 300ms. Every duration is a `--ds-motion-chart-*` role, so `prefers-reduced-motion` zeroes them with nothing per chart.
943
+ Motion: marks that leave finish leaving before marks that arrive start. Stages rise in from the top, and each table row follows its stage. `staggerMs: number = 60` spaces the arrivals, narrowed so a series finishes arriving within 260ms; `0` brings every mark in at once. Every duration is a `--ds-motion-chart-*` role, so `prefers-reduced-motion` shows every mark at once, delays included.
941
944
  States: `loading` draws skeleton marks at the real count; `error` shows `errorText` in place of the plot, which is a different claim from an empty `data` showing `emptyText`.
942
945
  Stage: `FunnelChartStage = { id: string; label: string; value: number }`
943
946
  Shape: `'area'` is the default — the fixed silhouette with the stage boundaries moved so each band's AREA is proportional to its value, the honest encoding that still leaves a labellable tail. `'width'` reads every boundary straight off the values, which collapses the tail of a steep funnel below a labellable width. `'taper'` encodes NOTHING: the silhouette is fixed whatever the data, so editing the values moves the table and never the shape — reach for it only where the numbers are read from the table.
@@ -946,7 +949,7 @@ Colour: the stages are one quantity draining, not N categories, so they take the
946
949
  Tokens: `--ds-funnel-chart-stage-height`, `--ds-funnel-chart-stage-gap`, `--ds-funnel-chart-row-gap`.
947
950
 
948
951
  <!-- inputs:ds-funnel-chart -->
949
- All inputs: `data: required readonly FunnelChartStage[]`, `shape: 'taper' | 'width' | 'area' = 'area'`, `showTable: boolean = true`, `frame: 'auto' | 'none' = null`, `tooltipLingerMs: number | null = null`, `caption: string | null = null`, `summary: string | null = null`, `dataTable: 'toggle' | 'visible' | 'none' = null`, `drop: 'relative' | 'absolute' | 'none' = 'relative'`, `loading: boolean = false`, `emptyText: string | null = null`, `error: boolean = false`, `errorText: string | null = null`, `valueFormat: ChartValueFormat | null = null`, `interactive: boolean = false`, `pinOnClick: boolean = false`, `dimOthers: boolean = false`, `staggerMs: number = 0`, `tooltip: 'item' | 'none' = 'item'`
952
+ All inputs: `data: required readonly FunnelChartStage[]`, `shape: 'taper' | 'width' | 'area' = 'area'`, `showTable: boolean = true`, `frame: 'auto' | 'none' = null`, `tooltipLingerMs: number | null = null`, `caption: string | null = null`, `summary: string | null = null`, `dataTable: 'toggle' | 'visible' | 'none' = null`, `drop: 'relative' | 'absolute' | 'none' = 'relative'`, `loading: boolean = false`, `emptyText: string | null = null`, `error: boolean = false`, `errorText: string | null = null`, `valueFormat: ChartValueFormat | null = null`, `pinOnClick: boolean | null = null`, `interactive: boolean = false`, `dimOthers: boolean = false`, `staggerMs: number = 60`, `tooltip: 'item' | 'none' = 'item'`
950
953
  <!-- /inputs -->
951
954
 
952
955
  #### `<ds-heatmap-chart>` — `HeatmapChartComponent`
@@ -963,7 +966,7 @@ The grid scrolls sideways below its natural width rather than crushing the cells
963
966
  Tokens: `--ds-heatmap-chart-cell-size`, `--ds-heatmap-chart-cell-gap`, `--ds-heatmap-chart-cell-radius`, `--ds-heatmap-chart-label-color`, `--ds-heatmap-chart-label-font-size`, `--ds-heatmap-chart-missing-color`, `--ds-heatmap-chart-focus-color`, `--ds-heatmap-chart-focus-width`.
964
967
 
965
968
  <!-- inputs:ds-heatmap-chart -->
966
- All inputs: `columns: readonly string[] = []`, `data: readonly HeatmapChartRow[] = []`, `caption: string | null = null`, `min: number | null = null`, `max: number | null = null`, `showValues: boolean = false`, `interactive: boolean = false`, `dimOthers: boolean = false`, `frame: 'auto' | 'none' = null`, `loading: boolean = false`, `error: boolean = false`, `emptyText: string | null = null`, `errorText: string | null = null`, `valueFormat: ChartValueFormat | null = null`, `tooltip: 'item' | 'none' = 'item'`
969
+ All inputs: `columns: readonly string[] = []`, `data: readonly HeatmapChartRow[] = []`, `caption: string | null = null`, `min: number | null = null`, `max: number | null = null`, `showValues: boolean = false`, `interactive: boolean = false`, `dimOthers: boolean = false`, `pinOnClick: boolean | null = null`, `frame: 'auto' | 'none' = null`, `loading: boolean = false`, `error: boolean = false`, `emptyText: string | null = null`, `errorText: string | null = null`, `valueFormat: ChartValueFormat | null = null`, `tooltip: 'item' | 'none' = 'item'`, `staggerMs: number = 40`
967
970
  <!-- /inputs -->
968
971
 
969
972
  #### `<ds-scatter-chart>` — `ScatterChartComponent`
@@ -980,7 +983,7 @@ The budget is a gate, not a paragraph: the decimator is fed 100 000 readings and
980
983
  Tokens: `--ds-scatter-chart-grid-line-color`, `--ds-scatter-chart-axis-line-color`, `--ds-scatter-chart-axis-label-color`, `--ds-scatter-chart-axis-font-size`, `--ds-scatter-chart-dot-radius`, `--ds-scatter-chart-dot-opacity`, `--ds-scatter-chart-focus-color`, `--ds-scatter-chart-focus-width`.
981
984
 
982
985
  <!-- inputs:ds-scatter-chart -->
983
- All inputs: `data: readonly ScatterChartSeries[] = []`, `xLabel: string | null = null`, `yLabel: string | null = null`, `decimator: 'minMax' | 'lttb' | 'none' = 'minMax'`, `tickCount: number = 5`, `caption: string | null = null`, `summary: string | null = null`, `interactive: boolean = false`, `frame: 'auto' | 'none' = null`, `dataTable: 'toggle' | 'visible' | 'none' = null`, `loading: boolean = false`, `error: boolean = false`, `emptyText: string | null = null`, `errorText: string | null = null`, `valueFormat: ChartValueFormat | null = null`, `tooltip: 'item' | 'none' = 'item'`, `dimOthers: boolean = false`
986
+ All inputs: `data: readonly ScatterChartSeries[] = []`, `xLabel: string | null = null`, `yLabel: string | null = null`, `decimator: 'minMax' | 'lttb' | 'none' = 'minMax'`, `tickCount: number = 5`, `caption: string | null = null`, `summary: string | null = null`, `interactive: boolean = false`, `frame: 'auto' | 'none' = null`, `dataTable: 'toggle' | 'visible' | 'none' = null`, `loading: boolean = false`, `error: boolean = false`, `emptyText: string | null = null`, `errorText: string | null = null`, `valueFormat: ChartValueFormat | null = null`, `tooltip: 'item' | 'none' = 'item'`, `dimOthers: boolean = false`, `pinOnClick: boolean | null = null`
984
987
  <!-- /inputs -->
985
988
 
986
989
  #### `<ds-waterfall-chart>` — `WaterfallChartComponent`
@@ -997,12 +1000,12 @@ Built on `<ds-chart>` with a column series and a waterfall-specific mark project
997
1000
  Tokens: `--ds-waterfall-chart-connector-color`, `--ds-waterfall-chart-skeleton-height`.
998
1001
 
999
1002
  <!-- inputs:ds-waterfall-chart -->
1000
- All inputs: `data: readonly WaterfallChartBar[] = []`, `showValues: boolean = true`, `showConnectors: boolean = true`, `caption: string | null = null`, `summary: string | null = null`, `tickCount: number = 5`, `interactive: boolean = false`, `frame: 'auto' | 'none' = null`, `dataTable: 'toggle' | 'visible' | 'none' = null`, `loading: boolean = false`, `error: boolean = false`, `emptyText: string | null = null`, `errorText: string | null = null`, `valueFormat: ChartValueFormat | null = null`
1003
+ All inputs: `data: readonly WaterfallChartBar[] = []`, `showValues: boolean = true`, `showConnectors: boolean = true`, `caption: string | null = null`, `summary: string | null = null`, `tickCount: number = 5`, `interactive: boolean = false`, `frame: 'auto' | 'none' = null`, `dataTable: 'toggle' | 'visible' | 'none' = null`, `loading: boolean = false`, `error: boolean = false`, `emptyText: string | null = null`, `errorText: string | null = null`, `valueFormat: ChartValueFormat | null = null`, `pinOnClick: boolean | null = null`, `staggerMs: number = 40`
1001
1004
  <!-- /inputs -->
1002
1005
 
1003
1006
  #### `<ds-line-chart>` — `LineChartComponent`
1004
1007
  One or more series plotted over a shared set of categories.
1005
- Inputs: `categories: readonly string[]` (required), `series: readonly LineChartSeries[]` (required), `yAxisMode: 'aligned' | 'exact' | 'dual-grid' | 'split' = 'aligned'`, `curve: 'linear' | 'step' | 'smooth' = 'linear'`, `stack: 'none' | 'stacked' | 'normalized' = 'none'`, `showMarkers: boolean = true`, `gaps: 'break' | 'zero' = 'break'`, `tickCount: number = 5`, `caption: string | null = null`, `summary: string | null = null`, `dataTable: 'none' | 'toggle' | 'visible' = 'none'`, `loading: boolean = false`, `emptyText: string = 'No data'`, `error: boolean = false`, `errorText: string = 'Could not load the data'`, `valueFormat: (value: number) => string`, `interactive: boolean = false`, `tooltip: 'item' | 'axis' | 'none' = 'axis'`, `patterns: boolean = false`, `staggerMs: number = 0`, `legendFilters: boolean = false`, `hiddenSeries: readonly string[] = []` (two-way), `rescaleOnHide: boolean = false`, `noVisibleSeriesText: string | null = null` (unset: `DS_INTL.chart.noVisibleSeries`)
1008
+ Inputs: `categories: readonly string[]` (required), `series: readonly LineChartSeries[]` (required), `yAxisMode: 'aligned' | 'exact' | 'dual-grid' | 'split' = 'aligned'`, `curve: 'linear' | 'step' | 'smooth' = 'linear'`, `stack: 'none' | 'stacked' | 'normalized' = 'none'`, `showMarkers: boolean = true`, `gaps: 'break' | 'zero' = 'break'`, `tickCount: number = 5`, `caption: string | null = null`, `summary: string | null = null`, `dataTable: 'none' | 'toggle' | 'visible' = 'none'`, `loading: boolean = false`, `emptyText: string = 'No data'`, `error: boolean = false`, `errorText: string = 'Could not load the data'`, `valueFormat: (value: number) => string`, `interactive: boolean = false`, `tooltip: 'item' | 'axis' | 'none' = 'axis'`, `patterns: boolean = false`, `staggerMs: number = 40`, `legendFilters: boolean = false`, `hiddenSeries: readonly string[] = []` (two-way), `rescaleOnHide: boolean = false`, `noVisibleSeriesText: string | null = null` (unset: `DS_INTL.chart.noVisibleSeries`)
1006
1009
  Output: `(pointClicked): LineChartReading` — the reading that was clicked or activated. Fires whether or not `interactive` is set.
1007
1010
  Interaction: a pointer moving over the plot picks the CATEGORY under it — a band paints behind every series and `tooltip="axis"`, the default here, names every series at that category. Tabbing reaches ONE marker per series; arrows walk that series' readings, and a focused marker's tooltip names its own series alone. A tap picks a category and latches the panel until the next tap outside; markers carry a transparent hit stroke of 24px, or 44px under `(pointer: coarse)`. `dimOthers` is the same separate opt-in as on the other four, and here it is the legend hover that drives it.
1008
1011
  Legend: drawn whenever there is more than one series. `legendFilters` turns each entry into a checkbox that hides its series, `hiddenSeries` is two-way so a page can drive it from a URL parameter, and hovering or focusing an entry tints it, dims the others and thickens the one hovered. **The axis does not move when a series is hidden** unless `rescaleOnHide` says so — a silent rescale turns a period-over-period comparison into a different claim. Hiding every series replaces the plot with `noVisibleSeriesText` on a `role="status"` line, legend still rendered.
@@ -1014,11 +1017,11 @@ Colour: series ARE different things, so the categorical palette applies — `--d
1014
1017
  Tokens: `--ds-line-chart-plot-height`, `--ds-line-chart-line-width`, `--ds-line-chart-dot-radius`, `--ds-line-chart-area-opacity`, `--ds-line-chart-swatch-size`, `--ds-line-chart-grid-line-color`, `--ds-line-chart-axis-line-color`, `--ds-line-chart-axis-label-color`, `--ds-line-chart-axis-font-size`, `--ds-line-chart-annotation-color`, `--ds-line-chart-annotation-font-size`, `--ds-line-chart-annotation-font-weight`, `--ds-line-chart-annotation-halo-color`, `--ds-line-chart-annotation-halo-width`.
1015
1018
 
1016
1019
  <!-- inputs:ds-line-chart -->
1017
- All inputs: `categories: required readonly string[]`, `series: required readonly LineChartSeries[]`, `yAxisMode: 'aligned' | 'exact' | 'dual-grid' | 'split' = 'aligned'`, `showMarkers: boolean = true`, `outline: boolean = true`, `annotations: readonly LineChartAnnotation[] = []`, `interactive: boolean = false`, `pinOnClick: boolean = false`, `dimOthers: boolean = false`, `gaps: 'break' | 'zero' = 'break'`, `curve: 'linear' | 'step' | 'smooth' = 'linear'`, `stack: 'none' | 'stacked' | 'normalized' = 'none'`, `yAxisLabel: string | null = null`, `secondaryAxisLabel: string | null = null`, `tickCount: number = 5`, `frame: 'auto' | 'none' = null`, `tooltipLingerMs: number | null = null`, `caption: string | null = null`, `summary: string | null = null`, `dataTable: 'toggle' | 'visible' | 'none' = null`, `max: number | null = null`, `maxSecondary: number | null = null`, `loading: boolean = false`, `emptyText: string | null = null`, `error: boolean = false`, `errorText: string | null = null`, `valueFormat: ChartValueFormat | null = null`, `hiddenSeries: readonly string[] = []`, `rescaleOnHide: boolean = false`, `legendFilters: boolean = false`, `legendMode: 'toggle' | 'isolate' = 'isolate'`, `noVisibleSeriesText: string | null = null`, `patterns: boolean = false`, `staggerMs: number = 0`, `tooltip: 'item' | 'axis' | 'none' = 'axis'`, `tooltipAnchor: 'point' | 'pointer' = 'point'`
1020
+ All inputs: `categories: required readonly string[]`, `series: required readonly LineChartSeries[]`, `yAxisMode: 'aligned' | 'exact' | 'dual-grid' | 'split' = 'aligned'`, `showMarkers: boolean = true`, `outline: boolean = true`, `annotations: readonly LineChartAnnotation[] = []`, `interactive: boolean = false`, `pinOnClick: boolean | null = null`, `dimOthers: boolean = false`, `gaps: 'break' | 'zero' = 'break'`, `curve: 'linear' | 'step' | 'smooth' = 'linear'`, `stack: 'none' | 'stacked' | 'normalized' = 'none'`, `yAxisLabel: string | null = null`, `secondaryAxisLabel: string | null = null`, `tickCount: number = 5`, `frame: 'auto' | 'none' = null`, `tooltipLingerMs: number | null = null`, `caption: string | null = null`, `summary: string | null = null`, `dataTable: 'toggle' | 'visible' | 'none' = null`, `max: number | null = null`, `maxSecondary: number | null = null`, `loading: boolean = false`, `emptyText: string | null = null`, `error: boolean = false`, `errorText: string | null = null`, `valueFormat: ChartValueFormat | null = null`, `hiddenSeries: readonly string[] = []`, `rescaleOnHide: boolean = false`, `legendFilters: boolean = false`, `legendMode: 'toggle' | 'isolate' = 'isolate'`, `noVisibleSeriesText: string | null = null`, `patterns: boolean = false`, `staggerMs: number = 40`, `tooltip: 'item' | 'axis' | 'none' = 'axis'`, `tooltipAnchor: 'point' | 'pointer' = 'point'`
1018
1021
  <!-- /inputs -->
1019
1022
 
1020
1023
  #### Chart defaults — what `DS_CONFIG` decides once
1021
- Four chart inputs resolve through `DS_CONFIG.chart` because they are one decision per APP, not per plot: `valueFormat` (a number reads one way in a product; a formatter passed per chart drifts as soon as there are two screens), `dataTable` (whether the numbers behind a plot have a non-visual route is an accessibility policy), `frame` and `tooltipLingerMs`. Precedence is the input, then the config, then the built-in — so binding one on a single chart still wins. The empty and error copy is wording, so it lives in `DS_INTL.chart.empty` / `.error`; the number locale is `DsConfig.locale`.
1024
+ Five chart inputs resolve through `DS_CONFIG.chart` because they are one decision per APP, not per plot: `valueFormat` (a number reads one way in a product; a formatter passed per chart drifts as soon as there are two screens), `dataTable` (whether the numbers behind a plot have a non-visual route is an accessibility policy), `frame`, `tooltipLingerMs` and `pinOnClick` (default `true`: a click holds a mark, with a pin disc on it, until a second click, Escape or a press elsewhere). `DS_CONFIG.chart.hoverDelayMs` (default `500`) is how long a resting pointer waits before any chart answers it; once a chart has answered, the next mark answers at once until the pointer leaves it, and focus, a tap and a pinning click answer at once. Precedence is the input, then the config, then the built-in — so binding one on a single chart still wins. The empty and error copy is wording, so it lives in `DS_INTL.chart.empty` / `.error`; the number locale is `DsConfig.locale`.
1022
1025
 
1023
1026
  `DS_CONFIG.chart.rendering` decides how charts build on a long page and is off by default: every chart draws as soon as it is created. With `deferUntilVisible: true` each chart shows a still placeholder of its own shape until it comes within `visibleMargin` (default `'10% 0px'`) of the viewport; `buildAheadWhileIdle` (default `true`) builds the charts within `buildAheadMargin` (default `'100% 0px'`) while the page is idle; `frameBudgetMs` (default `8`) caps how long one task spends building; `skipWhileOffscreen` (default `true`) lets the browser skip a built chart's rendering off screen through `content-visibility: auto`. Until a deferred chart is built a screen reader meets its caption only.
1024
1027
 
@@ -1053,7 +1056,7 @@ All inputs: `columns: readonly string[] = []`, `rows: readonly ChartDataRow[] =
1053
1056
  #### `<ds-chart>` — `ChartComponent`
1054
1057
 
1055
1058
  <!-- inputs:ds-chart -->
1056
- All inputs: `categories: readonly string[] = []`, `tickCount: number = 5`, `min: number | null = null`, `max: number | null = null`, `cursor: 'none' | 'category' | 'auto' = 'auto'`, `cursorPin: boolean = false`, `tooltipLingerMs: number | null = null`, `maxSecondary: number | null = null`, `plotHeight: number = 240`, `axisGutter: number = 46`, `valueSpace: number = 20`, `caption: string | null = null`, `interactive: boolean = false`, `summary: string | null = null`, `frame: 'auto' | 'none' = null`, `loading: boolean = false`, `emptyText: string | null = null`, `error: boolean = false`, `errorText: string | null = null`, `valueFormat: ChartValueFormat | null = null`, `secondaryAxisMode: 'aligned' | 'exact' | 'dual-grid' | 'split' = 'aligned'`, `axisColor: string | null = null`, `secondaryAxisColor: string | null = null`, `axisLabel: string | null = null`, `secondaryAxisLabel: string | null = null`, `tooltipTemplate: TemplateRef<{
1059
+ All inputs: `categories: readonly string[] = []`, `tickCount: number = 5`, `min: number | null = null`, `max: number | null = null`, `cursor: 'none' | 'category' | 'auto' = 'auto'`, `cursorPin: boolean | null = null`, `tooltipLingerMs: number | null = null`, `maxSecondary: number | null = null`, `plotHeight: number = 240`, `axisGutter: number = 46`, `valueSpace: number = 20`, `caption: string | null = null`, `interactive: boolean = false`, `summary: string | null = null`, `frame: 'auto' | 'none' = null`, `loading: boolean = false`, `emptyText: string | null = null`, `error: boolean = false`, `errorText: string | null = null`, `valueFormat: ChartValueFormat | null = null`, `secondaryAxisMode: 'aligned' | 'exact' | 'dual-grid' | 'split' = 'aligned'`, `axisColor: string | null = null`, `secondaryAxisColor: string | null = null`, `axisLabel: string | null = null`, `secondaryAxisLabel: string | null = null`, `tooltipTemplate: TemplateRef<{
1057
1060
  $implicit: ChartTooltipContext;
1058
1061
  }> | null = null`, `tooltipExtraGap: number = 0`
1059
1062
  <!-- /inputs -->
@@ -1061,13 +1064,13 @@ All inputs: `categories: readonly string[] = []`, `tickCount: number = 5`, `min:
1061
1064
  #### `<g[dsColumnSeries]>` — `ColumnSeriesComponent`
1062
1065
 
1063
1066
  <!-- inputs:g[dsColumnSeries] -->
1064
- All inputs: `data: readonly ColumnSeriesPoint[] = []`, `showValues: boolean = true`, `interactive: boolean = false`, `pinOnClick: boolean = false`, `dimOthers: boolean = false`, `staggerMs: number = 0`, `partOfWhole: boolean = false`, `tooltip: 'item' | 'none' = 'item'`, `tooltipAnchor: 'mark' | 'cell' = 'mark'`, `tooltipLingerMs: number = 0`, `valueFormat: ChartValueFormat`, `columnWidthRatio: number = 0.8`, `slot: number = 0`, `slotCount: number = 1`, `offsets: readonly ChartStackOffset[] | null = null`, `axis: 'primary' | 'secondary' = 'primary'`, `seriesColor: string | null = null`, `seriesFill: 'solid' | 'hatched' = null`, `seriesLabel: string | null = null`, `seriesKey: string | null = null`, `highlighted: string | null = null`
1067
+ All inputs: `data: readonly ColumnSeriesPoint[] = []`, `showValues: boolean = true`, `interactive: boolean = false`, `pinOnClick: boolean | null = null`, `dimOthers: boolean = false`, `staggerMs: number = 40`, `partOfWhole: boolean = false`, `tooltip: 'item' | 'none' = 'item'`, `tooltipAnchor: 'mark' | 'cell' = 'mark'`, `tooltipLingerMs: number = 0`, `valueFormat: ChartValueFormat`, `columnWidthRatio: number = 0.8`, `slot: number = 0`, `slotCount: number = 1`, `offsets: readonly ChartStackOffset[] | null = null`, `axis: 'primary' | 'secondary' = 'primary'`, `seriesColor: string | null = null`, `seriesFill: 'solid' | 'hatched' = null`, `seriesLabel: string | null = null`, `seriesKey: string | null = null`, `highlighted: string | null = null`
1065
1068
  <!-- /inputs -->
1066
1069
 
1067
1070
  #### `<g[dsLineSeries]>` — `LineSeriesComponent`
1068
1071
 
1069
1072
  <!-- inputs:g[dsLineSeries] -->
1070
- All inputs: `data: readonly LineSeriesData[] = []`, `showMarkers: boolean = true`, `outline: boolean = true`, `interactive: boolean = false`, `pinOnClick: boolean = false`, `dimOthers: boolean = false`, `highlighted: string | null = null`, `patterns: readonly string[] = []`, `stacked: boolean = false`, `staggerMs: number = 0`, `gaps: 'break' | 'zero' = 'break'`, `curve: 'linear' | 'step' | 'smooth' = 'linear'`, `tooltip: 'item' | 'axis' | 'none' = 'item'`, `tooltipAnchor: 'reading' | 'pointer' = 'reading'`, `tooltipLingerMs: number = 0`, `valueFormat: ChartValueFormat`
1073
+ All inputs: `data: readonly LineSeriesData[] = []`, `showMarkers: boolean = true`, `outline: boolean = true`, `interactive: boolean = false`, `pinOnClick: boolean | null = null`, `dimOthers: boolean = false`, `highlighted: string | null = null`, `patterns: readonly string[] = []`, `stacked: boolean = false`, `staggerMs: number = 40`, `gaps: 'break' | 'zero' = 'break'`, `curve: 'linear' | 'step' | 'smooth' = 'linear'`, `tooltip: 'item' | 'axis' | 'none' = 'item'`, `tooltipAnchor: 'reading' | 'pointer' = 'reading'`, `tooltipLingerMs: number = 0`, `valueFormat: ChartValueFormat`
1071
1074
  <!-- /inputs -->
1072
1075
 
1073
1076
  #### `<g[dsSeriesAnnotation]>` — `SeriesAnnotationComponent`
@@ -27,7 +27,7 @@ and token names.** These leaves are for orientation and usage.
27
27
  - [<ds-scatter-chart> — ScatterChartComponent](charts/ds-scatter-chart.md) — Two continuous quantities against each other — weight against carriage cost, distance against time, volume aga
28
28
  - [<ds-waterfall-chart> — WaterfallChartComponent](charts/ds-waterfall-chart.md) — A running total, bar by bar: what a figure started at, what moved it, and what it ended at.
29
29
  - [<ds-line-chart> — LineChartComponent](charts/ds-line-chart.md) — One or more series plotted over a shared set of categories.
30
- - [Chart defaults — what DS_CONFIG decides once](charts/ds-config.md) — Four chart inputs resolve through DS_CONFIG.chart because they are one decision per APP, not per plot: valueFo
30
+ - [Chart defaults — what DS_CONFIG decides once](charts/ds-config.md) — Five chart inputs resolve through DS_CONFIG.chart because they are one decision per APP, not per plot: valueFo
31
31
  - [Chart frame — the box a chart draws around itself](charts/chart-frame-the-box-a-chart-draws-around-itself.md) — Every chart paints its own border, radius, padding and --surface-default background, on by default. That is un
32
32
  - [Chart colour — which palette a chart takes](charts/chart-colour-which-palette-a-chart-takes.md) — Three families, and reaching for the wrong one is the usual chart bug. Set the --ds-chart-* contract tokens, n
33
33
  - [<ds-chart-data-table> — ChartDataTableComponent](charts/ds-chart-data-table.md) — The annex table under a chart: every reading in a <details> a reader can open. Cells arrive already formatted,
@@ -63,7 +63,7 @@ and token names.** These leaves are for orientation and usage.
63
63
  - [<ds-timeline-item> — TimelineItemComponent](feedback/ds-timeline-item.md) — <!-- inputs:ds-timeline-item -->
64
64
  - [<ds-toast-region> — ToastRegionComponent](feedback/ds-toast-region.md) — <!-- inputs:ds-toast-region -->
65
65
  - [<ds-tree> — TreeComponent](feedback/ds-tree.md) — <!-- inputs:ds-tree -->
66
- - [<ds-description-list> — DescriptionListComponent](feedback/ds-description-list.md) — <!-- inputs:ds-description-list -->
66
+ - [<ds-description-list> — DescriptionListComponent](feedback/ds-description-list.md) — **A horizontal list stacks when a value would get too narrow.** Each item is a wrapping flex row: once the lis
67
67
  - [<ds-description-item> — DescriptionItemComponent](feedback/ds-description-item.md) — <!-- inputs:ds-description-item -->
68
68
 
69
69
  ## forms
@@ -125,7 +125,7 @@ and token names.** These leaves are for orientation and usage.
125
125
  - [<ds-drawer> — DrawerComponent](overlays/ds-drawer.md) — Side panel (no side input — always anchored right).
126
126
  - [<ds-bottom-sheet> — BottomSheetComponent](overlays/ds-bottom-sheet.md) — Mobile-first panel anchored to the bottom edge (touch equivalent of drawer/modal). Drag-down on the grab strip
127
127
  - [<ds-popover> — PopoverComponent](overlays/ds-popover.md) — Floating panel anchored to a trigger via CDK overlay. Input: align: 'start' | 'end' = 'start' — controls overl
128
- - [[dsTooltip] — TooltipDirective](overlays/ds-tooltip.md) — Attribute directive. Apply to any focusable element.
128
+ - [[dsTooltip] — TooltipDirective](overlays/ds-tooltip.md) — Attribute directive. Apply to any focusable element; with dsTooltipWhenClipped also to a label that cannot tak
129
129
  - [<ds-menu> + <ds-menu-item> — MenuComponent, MenuItemComponent](overlays/ds-menu.md) — Menu is a container. Item inputs: icon: IconName | null = null, disabled: boolean = false, danger: boolean = f
130
130
  - [<ds-tooltip-panel> — TooltipPanelComponent](overlays/ds-tooltip-panel.md) — <!-- inputs:ds-tooltip-panel -->
131
131
 
@@ -4,5 +4,5 @@
4
4
  Group: Charts
5
5
 
6
6
  <!-- inputs:g[dsColumnSeries] -->
7
- All inputs: `data: readonly ColumnSeriesPoint[] = []`, `showValues: boolean = true`, `interactive: boolean = false`, `pinOnClick: boolean = false`, `dimOthers: boolean = false`, `staggerMs: number = 0`, `partOfWhole: boolean = false`, `tooltip: 'item' | 'none' = 'item'`, `tooltipAnchor: 'mark' | 'cell' = 'mark'`, `tooltipLingerMs: number = 0`, `valueFormat: ChartValueFormat`, `columnWidthRatio: number = 0.8`, `slot: number = 0`, `slotCount: number = 1`, `offsets: readonly ChartStackOffset[] | null = null`, `axis: 'primary' | 'secondary' = 'primary'`, `seriesColor: string | null = null`, `seriesFill: 'solid' | 'hatched' = null`, `seriesLabel: string | null = null`, `seriesKey: string | null = null`, `highlighted: string | null = null`
7
+ All inputs: `data: readonly ColumnSeriesPoint[] = []`, `showValues: boolean = true`, `interactive: boolean = false`, `pinOnClick: boolean | null = null`, `dimOthers: boolean = false`, `staggerMs: number = 40`, `partOfWhole: boolean = false`, `tooltip: 'item' | 'none' = 'item'`, `tooltipAnchor: 'mark' | 'cell' = 'mark'`, `tooltipLingerMs: number = 0`, `valueFormat: ChartValueFormat`, `columnWidthRatio: number = 0.8`, `slot: number = 0`, `slotCount: number = 1`, `offsets: readonly ChartStackOffset[] | null = null`, `axis: 'primary' | 'secondary' = 'primary'`, `seriesColor: string | null = null`, `seriesFill: 'solid' | 'hatched' = null`, `seriesLabel: string | null = null`, `seriesKey: string | null = null`, `highlighted: string | null = null`
8
8
  <!-- /inputs -->