@ids-group-ltd/ids-design-system 0.7.0 → 0.8.0

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.
package/CHANGELOG.md CHANGED
@@ -8,6 +8,600 @@ While the package is on `0.x`, minor releases may contain breaking changes.
8
8
 
9
9
  ## Unreleased
10
10
 
11
+ ## 0.8.0 — 2026-08-05
12
+
13
+ ### Added
14
+
15
+ - **`ds-icon-button` forwards `ariaExpanded` and `ariaControls` to its inner `<button>`, and `ds-button` gains `ariaControls`.** A trigger that opens a panel has to announce state on the element a screen reader focuses; set on `<ds-icon-button>` itself those attributes land on the wrapper, which is not focusable and is never read. `ds-button` already forwarded `ariaExpanded`; the pair is now complete on both.
16
+ - **`LayoutScrollService` exposes its scroller and an absolute `scrollTo(top)`.** A scroll-spy or a virtualizer inside `ds-app-layout` needs the content region to measure against, and the only way to get it was `document.querySelector` against the layout's internal markup — a consumer reaching into DS internals for something the DS already holds. `scrollTo` assigns `scrollTop` rather than calling `scrollTo({ behavior })`, so a themed `scroll-behavior: smooth` cannot turn a positioning jump into an animation.
17
+ - **`dsRailTrigger` wires a consumer's own burger to the overlay rail.** The responsive rail shipped with `role="dialog"`, `aria-modal` and a focus trap, but nothing connected it to the button that opens it — the burger lives in the consumer's projected topbar, so it announced no state and no relationship. Put the directive on the burger and it toggles `[(railOpen)]` and keeps `aria-expanded` and `aria-controls` correct. Both attributes are dropped while the rail is not an overlay, where `aria-expanded="false"` would contradict what the user sees. A directive rather than a documentation note because these are exactly the attributes a consumer forgets — the DS itself forgot them. `ds-app-layout` also exposes `railId` and the read-only `railOverlay` signal for a consumer that builds its own trigger.
18
+
19
+ - **Overlay panels fade out when DISMISSED, and still close instantly when you choose something.** Floating
20
+ panels (select, autocomplete, multi-select, both pickers, colour picker, popover) have closed instantly
21
+ since the unconditional leave animation was cut, because ~120ms of fade after picking an option reads as the
22
+ panel lagging behind a decision already made. A dismissal is the opposite: Escape, a press outside or the
23
+ page scrolling away produced no result, so the fade reads as the panel backing out rather than as delay.
24
+ `disposeWithLeave()` now takes that cause — `'select'` (the default, instant) or `'dismiss'` — and each
25
+ panel passes `'dismiss'` from exactly its Escape / outside-press / scroll paths. Tab still closes instantly,
26
+ because a fading panel must not linger behind moved focus.
27
+ — Tunable through `--ds-overlay-leave-duration` / `-easing`, defaulting to the `--ds-motion-exit-*` role.
28
+ Reduced motion zeroes the duration at `:root`, so the animation still runs and still drives teardown. A
29
+ fading panel is `pointer-events: none`, so it cannot swallow a click aimed at what is behind it.
30
+
31
+ - **`ds-checkbox`, `ds-switch` and `ds-radio` now RENDER a projected caption, and expose its colour and
32
+ size.** `<ds-checkbox>I accept the <a …>Terms</a></ds-checkbox>` — the first thing a consumer tries, and
33
+ the idiom every other body-bearing DS component accepts — used to render a control with no caption at all:
34
+ no error, nothing in the types. 0.7.1 added a dev warning; this makes the markup work. `[label]` stays the
35
+ documented API and still wins when both are given. One difference worth knowing: the required asterisk
36
+ comes with `[label]` only, because a projected caption's own markup is the only thing that knows where the
37
+ marker belongs.
38
+ — New hooks: `--ds-checkbox-label-color` / `-label-font-size`, the same pair on `ds-switch`, and
39
+ `--ds-radio-label-font-size` (`--ds-radio-label-color` already shipped). The font-size hook beats the size
40
+ class, so setting it pins the caption regardless of `size`. These are deliberately NOT part of the
41
+ `--ds-field-label-*` contract: a label above an input is a heading for the field and reads secondary, while
42
+ a caption beside a checkbox is the content being agreed to and reads primary — routing them together would
43
+ put "Remember me" in uppercase in any brand that sets `--ds-field-label-transform`. Recorded in the token
44
+ reference so it reads as a decision rather than an omission.
45
+ - **`ds-table` renders only the rows in view: `[virtualScroll]="true"` + `virtualRowSize`.** The body used to
46
+ `@for` over every row of `data()`, so 10 000 rows tanked scroll and paint. Virtual mode keeps ~25 rows in
47
+ the DOM regardless of the row count, padding above and below with two spacer rows that stand in for the
48
+ rest — so the scrollbar still spans the whole data set. Needs `maxHeight`: a bounded scroller is the
49
+ viewport it windows against, and without one nothing is virtualized (dev-warned).
50
+ — **NOT the CDK virtual-scroll viewport**, deliberately. That arrangement wraps the table in a transformed
51
+ content wrapper, and the transform creates a containing block that breaks both the sticky header and the
52
+ sticky first column this table already has. Spacer rows leave the existing scroller — and everything
53
+ sticky in it — untouched.
54
+ — Uniform row height is the precondition, not a preference: `virtualRowSize` is the only thing telling the
55
+ arithmetic where a row starts, so one row that grows puts every offset below it out by the difference.
56
+ Virtual mode therefore drives the CSS row height from that same input, forces `table-layout: fixed` (auto
57
+ layout re-measures against whichever rows are rendered, and the columns twitch as you scroll) and keeps
58
+ cells to one line. Row EXPANSION is suppressed with a dev warning; `pageSize` alongside it is warned about
59
+ too, since virtual scrolling is what pagination was for. Sorting, filtering, selection, sticky header,
60
+ sticky first column and column resizing all keep working.
61
+ — Zebra striping switches from `:nth-child` to an absolute-index class while windowing: a rendered row's
62
+ parity depends on its real position, and the spacer rows are children too.
63
+ - **`ds-filter-bar` — a Priority+ filter row: as many filters as fit, the rest behind "+N more".**
64
+ Every admin list past three filters hits the same wall — the row wraps to a second line on a laptop, or
65
+ the consumer hand-rolls an overflow menu. Each filter goes in an
66
+ `<ng-template [dsFilterItem]="180">`, and the split is decided from those declared widths plus one
67
+ `ResizeObserver` on the row. Never by measuring the filters: they would have to be in the DOM to be
68
+ measured, so anything that did not fit would flash into view before being taken away.
69
+ — A template rather than plain projection because the bar has to MOVE what does not fit into the panel,
70
+ and projected DOM cannot be relocated. Consequence worth knowing: crossing that boundary destroys and
71
+ re-creates the view, so a control's internal state (an open dropdown, focus) does not survive a resize
72
+ that collapses it — its value does, because that lives in the consumer's own signal or form control.
73
+ — The declared width is a contract, not a hint: the slot is sized to exactly that number, so the
74
+ arithmetic is true by construction and a filter is the same width in the panel as in the row.
75
+ — Mark trailing controls with `dsFilterBarTrailing` (search, a Clear button) rather than wrapping them:
76
+ the bar owns that group's gap and alignment, and a projected wrapper would be a plain block whose children
77
+ stack. The group sits outside the measured row, so flexbox subtracts its width before the row is measured.
78
+ — The trigger carries the count as text plus `aria-expanded`, and the panel is a focus-trapped
79
+ `role="dialog"`. There is exactly one copy of each filter in the accessibility tree, because filters MOVE
80
+ rather than being rendered twice and hidden — the usual implementation of this pattern needs `aria-hidden`
81
+ bookkeeping to compensate. `moreLabel` and `panelLabel` are there for translation.
82
+ — Both slots collapse when nothing lands in them (`:not(:has(*))`, not `:empty`, which a single whitespace
83
+ text node defeats): an empty flex child would still take the row's gap. Dev-mode warning when content
84
+ reaches the bar carrying neither slot marker, since such content is silently dropped.
85
+ - **`ds-auth-shell` — the scaffold for the screens in front of the login, counterpart to `ds-app-layout`.**
86
+ Consumers hand-rolled the unauthenticated scaffold every time, and it is the same four parts in each: a
87
+ brand lockup, an optional tagline, one card holding the form, and a support line under it. The brand row
88
+ is the sidenav's row — same `brand` / `logoLetter` / `[dsBrandName]` contract and the same letter-mark
89
+ tile, so the mark on the login screen is the mark in the rail afterwards. Deliberately NOT the string
90
+ splitting the ports used to tint one slice of a wordmark: a split has to guess where the accent belongs,
91
+ and the projection already says.
92
+ — The card body is the default slot, the support line is `[dsAuthSupport]` (a real `<footer>`, so it
93
+ carries the `contentinfo` landmark), and both the tagline and the support line collapse when absent
94
+ rather than leaving an empty flex child that would take the column's gap and push the card off centre.
95
+ — `cardElevation` / `cardPadding` pass through to `ds-card`; `--ds-auth-shell-min-height`,
96
+ `-card-max-width`, `-gap`, `-bg-color` and the two `-mark-*` colours are the public hooks.
97
+ — The host is the ONLY full-height box, which is what the ports got wrong: nesting a `100vh` wrapper
98
+ inside a `100dvh` one scrolls a page whose content fits. It also carries `env(safe-area-inset-*)` so a
99
+ notched phone in landscape does not put the card under the cutout. Inside it the column centres with auto
100
+ margins rather than centre alignment — identical while the host can grow, but not when it cannot: embed
101
+ the shell at `--ds-auth-shell-min-height: 100%` in a fixed-height parent and centre alignment puts a form
102
+ taller than the box above the scroll origin where no scrolling reaches it (measured at −115px), while
103
+ auto margins collapse to zero and pin it to the padding edge.
104
+ - **`ds-password-rules` — the live requirement checklist under a new-password field.** One consumer had
105
+ written it twice (set-password and registration) and the two copies had already drifted: different labels
106
+ for the same rule, a different order, different state class names. Each rule carries its own `test`,
107
+ because the POLICY has to mirror the server and only the consumer knows it; the component owns the
108
+ tri-state glyph, the met/failed colours and the type scale. A rule that has not passed reads as PENDING
109
+ and only becomes a failure once `[showUnmet]` is true — bind that to "the user has tried to submit", or a
110
+ half-typed password scolds someone who is still typing. `[columns]="2"` for a checklist beside a wide
111
+ form, and `metCount` / `allMet` are exposed for a host gating its own submit — or import the standalone
112
+ `passwordRulesMet(value, rules)`, the same predicate that backs `allMet`, to gate a submit without
113
+ rendering the list at all. `[listId]` names the `<ul>` so a field's `aria-describedby` can point at it,
114
+ and `DsPasswordRule` (`{ label, test }`) and `DsPasswordRuleState` (`'pending' | 'met' | 'failed'`) are
115
+ exported for typing the rule set.
116
+ - **`ds-input` takes `ariaDescribedBy`, MERGED with its own message id.** Needed by the rule list above,
117
+ and by any policy note: setting `aria-describedby` on `<ds-input>` by hand lands on the wrapper, which no
118
+ screen reader reads, and replacing the attribute would have dropped the field's own hint/error
119
+ association. The input joins both ids instead.
120
+
121
+ - **`ds-table` persists the column layout and can render its own export button.** These were the last two
122
+ things keeping a consumer wrapper alive around the table: after 0.6.3/0.7.0 it owned every other feature
123
+ mm-broker forked it for, but the three column models were two-way with nothing storing them, so every
124
+ consumer wrote the same `localStorage` effect keyed by a screen id, and `exportCsv()` was a public method
125
+ with no affordance.
126
+ — `[persistLayout]="true"` + `storageKey` round-trip `columnOrder`, `columnWidths` and `hiddenKeys`
127
+ through `localStorage`. Both are required: without a key there is nothing to identify a screen by and two
128
+ tables would overwrite each other, so a missing key stores nothing rather than guessing. Only what was
129
+ actually saved is applied, so a table nobody has rearranged keeps its declaration order and `hidden`
130
+ flags.
131
+ — `[exportButton]="true"` renders the CSV button; `exportFilename` names the file and `exportFetcher`
132
+ covers the server-paged case — a table that only HAS the current page would otherwise export one page and
133
+ call it the export, so the button awaits the fetcher and disables itself while it runs. `exportCsv()`
134
+ stays public for a consumer’s own button and now takes an optional row set.
135
+ - **Focus-indicator style is a one-place switch: `<html data-focus="ring | field | edge | outline">`.**
136
+ The library shipped two fixed families — a soft halo on fields, a crisp double ring on controls — with no
137
+ way for a brand to choose. Since 20 components already resolve through `--ds-field-focus-shadow` /
138
+ `--ds-control-focus-shadow`, the switch simply retargets those roles: `ring` and `field` make both groups
139
+ match, `edge` is a hairline flush against the element, and `outline` swaps to a real `outline` — which a
140
+ box-shadow token cannot express, so that style also emits a zero-specificity `:where(:focus-visible)`
141
+ rule. Omit the attribute and today’s split is unchanged.
142
+ - **Focus survives Windows High Contrast.** Forced-colors mode DROPS `box-shadow`, so a shadow-only
143
+ indicator vanished entirely and a keyboard user in that mode had nothing to follow — a real a11y gap, now
144
+ closed once for every style with a `CanvasText` outline under `@media (forced-colors: active)`. A system
145
+ keyword rather than a brand colour, because forced-colors replaces the palette.
146
+ — Both the switch and this fallback live in the new `styles/_focus.scss`, forwarded into the bundled
147
+ `styles/ds` entry, so a consumer of that entry gets both automatically. A consumer who `@use`s DS
148
+ partials individually gets NEITHER until they add `@use 'styles/focus';`.
149
+ - **A role layer between the foundation scales and the components: radius, elevation and motion.** Reading
150
+ the raw scale directly meant a consumer could not re-round "panels" without also re-rounding every
151
+ control that shared `--radius-md`, could not lift every overlay without touching each surface, and could
152
+ not make panel entrances snappier without retuning each one. Every role defaults to the value its members
153
+ already used, so nothing moves until a role is set, and a per-component `--ds-<comp>-*` override still
154
+ wins over its role.
155
+ — **Radius:** `--ds-radius-inner` (the checkbox box, option rows, tags), `--ds-radius-control` (buttons,
156
+ field frames, picker triggers, tooltips), `--ds-radius-panel` (menus, popovers, cards, modals, drawers),
157
+ `--ds-radius-pill`. No `field` role: fields share `--radius-md` with buttons, so one would either
158
+ duplicate `control` or silently re-round every field — scope the role instead
159
+ (`ds-input { --ds-radius-control: 4px; }`).
160
+ — **Elevation:** `--ds-elevation-raised` / `-overlay` / `-floating` / `-modal`. Four, not the three first
161
+ sketched: the library genuinely uses four heights, and folding toast into `overlay` would have changed its
162
+ shadow. The older `--shadow-popover` / `-modal` / `-toast` / `-card` aliases now point AT the roles, so
163
+ either name works — a role moves every surface at that height, an alias retunes one family.
164
+ — **Motion:** `--ds-motion-enter-panel-*`, `-enter-surface-*`, `-enter-large-*`, `-exit-*`,
165
+ `-exit-large-*` (duration + easing each). Five roles, not four: panel LEAVES run at `--duration-base`,
166
+ not `fast`, so folding them into `exit` would have sped them up. `ds-loading-overlay` and the toast leave
167
+ stay on the raw scale — they use `--ease-standard`, which no role carries, and a role for two sites would
168
+ be worse than naming the value.
169
+ - **`ds-app-layout` restores the reader's scroll on the way BACK: opt-in `restoreScroll` +
170
+ `restoreScrollTimeout` (2000ms).** List → details → back returned the list to the top, because a real
171
+ back IS a path change and the layout resets on those. Off by default — a layout that silently moved the
172
+ scroll would surprise every existing consumer. Restores only when ARMED, which is the whole design: a
173
+ history traversal (back, forward, the mouse side button, `Alt+←`, an edge swipe — all arrive as
174
+ `popstate`), a host whose own "back to list" adds a history entry instead of traversing and says so with
175
+ `state: { dsRestoreScroll: true }`, or the first navigation after a reload. Following a link into a new
176
+ screen still lands at the top.
177
+ — The offset is remembered per PATH in `sessionStorage` (one namespaced blob, 20 entries, oldest first,
178
+ every access guarded — Safari private mode throws on write). Restoring waits for the content to grow via
179
+ `ResizeObserver` rather than counting frames, clamps to what the content allows at the deadline (a list
180
+ that loaded 8 of 40 rows still lands near the reader's row), and cancels on `wheel` / `touchstart` /
181
+ `keydown` — input events only, since our own restore writes emit `scroll`. It never touches
182
+ `history.scrollRestoration`, and it bails on a bfcache restore, which brings its own position back.
183
+ — `LayoutScrollService` gained `contentReady()` (optional: end the growth wait early when your data has
184
+ arrived) and `consumePendingOffset()` (take the offset and cancel the restore — for a virtualizer, which
185
+ needs it BEFORE deciding which rows to build).
186
+ — **Interaction worth knowing:** an app that scrolls on navigation itself — a docs shell whose URL names a
187
+ section, an anchor jump — writes after the layout does and therefore wins. That is the right precedence,
188
+ and it means `restoreScroll` is a no-op on those routes rather than a fight.
189
+ - **`ds-button` type and box hooks: `--ds-button-font-size` / `-weight` / `-tracking` / `-height` /
190
+ `-pad-x` / `-pad-y`, plus `data-variant` / `data-color` reflected on the host.** The label type and the
191
+ box were hard-coded, and the size class pinned `height` and `padding`, so a brand wanting 14px/600
192
+ buttons sized by their own padding had to write `.button.button.button { … }` to out-rank the shimmed
193
+ `.button.md` (0,3,0). The hooks follow the read-never-declare rule the colour resolvers already use, and
194
+ each size class re-resolves them with the hook still first — so `--ds-button-height` beats the size it
195
+ would otherwise pick instead of being undone by it. The reflected attributes let a consumer target one
196
+ axis from outside (`ds-button[data-variant="outline"] { --ds-button-border: white; }`) without reaching
197
+ for the `c-*` / `v-*` classes, which sit on the inner `<button>` and are not addressable from a
198
+ host-scoped rule.
199
+ - **`--ds-field-height` — one control-box height for the field family, and the `--field-h-*` scale is
200
+ finally the knob its name advertises.** `--field-h-sm`/`-md`/`-lg` have shipped as the field height
201
+ scale for as long as the token file has existed, but only `-lg` was ever read: `ds-input`, `ds-select`,
202
+ `ds-date-picker` and `ds-time-picker` all spelled the other two out as the raw `var(--hit-min)` /
203
+ `var(--hit-cozy)`. Retuning `--field-h-md` therefore changed nothing — a lever that looked live and was
204
+ not. All four now resolve through the scale (identical values, so nothing moves), and
205
+ `--ds-field-height` overrides the resolved size for a consumer who wants one height regardless of
206
+ `size`; scope it per component the usual way (`ds-select { --ds-field-height: 44px; }`).
207
+ - **One label contract for the whole field family: `--ds-field-label-font-size` / `-weight` / `-color` / `-transform` / `-tracking`.** Five components hard-coded the identical label rule and only `ds-input`
208
+ had hooks, so a form mixing a select with an input rendered labels in two sizes and colours out of the
209
+ box, and retuning them from an app needed `.field.field .label.label, .select-label.select-label` to
210
+ out-rank the shimmed component rule. `input`, `textarea`, `select`, `date-picker`, `time-picker` and
211
+ `radio-group` now resolve through one mixin and one token set. No per-component token set is needed —
212
+ custom-property scoping already narrows a retune to one component
213
+ (`ds-select { --ds-field-label-transform: uppercase; }`), and `-transform`/`-tracking` make the
214
+ uppercase tracked editorial label reachable through tokens for the first time. `ds-input`’s older
215
+ `--ds-input-label-color`/`-fs`/`-fw` still win where set, and now fall through to the family token
216
+ instead of straight to the raw scale.
217
+ - **Every field takes `error` and `warning` beside `hint`, and shows exactly one of them.** Until now a
218
+ field had one message input, so a consumer had to multiplex it by hand —
219
+ `[invalid]="showError()" [hint]="showError() ? errorText() : helperText()"` — on every screen that
220
+ validates, and the two bindings could silently disagree. The four sources now resolve on a fixed
221
+ ladder, highest first: `error` (an explicit string — shown at once, because binding it says you have
222
+ already decided), then validation errors, then `warning`, then `hint`. Only ONE line ever renders, so
223
+ a field's height does not depend on how many sources are populated — the same rule Carbon
224
+ (`invalidText` → `warnText` → `helperText`) and Material's subscript follow. `ds-field-message` gained
225
+ a matching `warning` state coloured from `--warning-text`.
226
+ - **Fields read validation state from the form control, so `error` is optional.** Both Angular form
227
+ systems are supported at once and neither needs the other. Signal forms binds `errors` and `touched`
228
+ straight in — those input names are Angular 21's `FormUiControl` contract, and the `Field` directive
229
+ already drives the value through the `ControlValueAccessor` the fields have always implemented.
230
+ Reactive and template-driven forms need nothing at all: the field resolves `NgControl` after first
231
+ render (it cannot be injected directly — a field provides `NG_VALUE_ACCESSOR` pointing at itself, so
232
+ asking for `NgControl` in the same constructor is a DI cycle) and subscribes to `control.events`,
233
+ which is what reports touching — `statusChanges` does not. Errors wait for the first blur, or for the
234
+ parent form to be submitted, so a `required` error never greets an untouched form. `invalid` no longer
235
+ has to be kept in sync by hand: it is now OR-ed with what the control reports, and the explicit input
236
+ still wins.
237
+ - **`DS_CONFIG.field.errorMessages` — one shared map from error kind to text.** A message on the error
238
+ itself always wins (`required(path, { message: … })` in signal forms, or `{ myError: 'text' }` from a
239
+ plain validator), so this is the fallback for Angular's built-ins, which carry detail objects and no
240
+ wording. Declare it once in `provideDsConfig` and a consumer writes no text at all for `required`,
241
+ `minlength` or `email`. An error that resolves to no text anywhere warns in dev rather than rendering
242
+ an error style with an empty line.
243
+
244
+ ### Changed
245
+
246
+ - **`ds-table`’s `clientSort` is replaced by `sortMode: 'client' | 'server' | 'none'`, and the default flips to client sorting.** The boolean could not express "nothing sorts", so a column marked `sortable: true` on a table with no sorting drew a header that looked live, showed a caret on hover and did nothing — an invisible failure that survived review and was caught by opening the page. An enum makes that state unrepresentable: `'none'` now renders the header as plain text, with no button, caret or `aria-sort`. Unset resolves to `'client'`, so `sortable: true` always does something; a server-sorted table declares `'server'`, which is the side that actually knows it wants server sorting. **Migration is mechanical except for one case:** a table that previously bound no `clientSort` and reordered in its own `(sortChange)` handler must now declare `sortMode="server"`, or it will sort locally as well. For a server-PAGED table (one that binds `total`) that is worse than a dead header, because only the current page reorders and the rows look sorted without being sorted — so dev builds warn on exactly that combination: `total` bound, sortable columns, `sortMode` never declared. Rejected alternative: reading `OutputEmitterRef.listeners` to detect an unbound `(sortChange)`. It is private, and a rename would kill the warning SILENTLY — `?.length` on `undefined` just means it never fires again. The union is exported as `TableSortMode`, so a host that keeps the mode in a signal or computed can type it instead of repeating the literals.
247
+
248
+ - **A `ds-menu` row's hover fill is square and runs edge to edge.** The row carried `--radius-md`, the
249
+ same 8px the standalone menu panel uses, while sitting flush inside it — and inside a `ds-popover`,
250
+ which drops its padding for a menu, that 8px sat against the popover's 12px corner and left visible
251
+ slivers at the top and bottom of the list. A curve at zero inset can never be concentric with the
252
+ panel's, so the row is now square and the panel clips it: `ds-menu` drops its own `padding` and gains
253
+ `overflow: hidden`, which is what rounds the first and last row. To keep the old rounded highlight,
254
+ set the new hook — `ds-menu { --ds-menu-item-radius: var(--radius-md); }` — and note the panel no
255
+ longer insets the rows, so a radius there reads best with a padding of your own.
256
+ - **`ds-radio-group`’s label now looks like every other field label.** It was the one component drawing
257
+ its own type (`medium` weight at `--font-size-s` on `--line-height-flat`) rather than the family’s
258
+ `bold`/`--font-size-xs`; in a form beside an input or a select it read as a different kind of thing.
259
+ Restore the old look with `ds-radio-group { --ds-field-label-weight: var(--font-weight-medium); --ds-field-label-font-size: var(--font-size-s); }`.
260
+ - **Fields no longer expose a `protected messageState`;** the resolved `message` (text + state) and
261
+ `invalidResolved` replace it. Only reachable by subclassing a field component, which is not a
262
+ supported extension point, but noted for parity with the class-member changes in 0.7.0.
263
+
264
+ ### Fixed
265
+
266
+ - **Two leftover `--combobox-*` tokens renamed to `--picker-*`.** `--combobox-offset` and
267
+ `--combobox-maxh` size the listbox panel shared by `ds-autocomplete` and `ds-multi-select`, and survived the
268
+ `ds-combobox` → `ds-autocomplete` rename carrying the name of a component that no longer exists. Now
269
+ `--picker-offset` / `--picker-maxh`. These are global scale tokens rather than `--ds-*` component tokens, so
270
+ the blast radius is anyone who happened to override them — rename the override. The docs also now state the
271
+ autocomplete-vs-multi-select boundary in both sections: the LIST decides, not the count — typing is how you
272
+ narrow a set too large to scan, while a checkbox list shows the whole choice and what is NOT selected.
273
+ - **A `required` `ds-time-picker` in `mode="range"` never announced as required.** `aria-required` was on the
274
+ single-mode trigger only, so a screen-reader user on a range field was not told either segment was
275
+ mandatory. Both segments now carry it. (Their accessible NAME was already correct — each announces the
276
+ field's own label plus "(from)" / "(to)" — and the docs gained a labelled, required range demo, whose
277
+ absence is why the gap went unnoticed.)
278
+ - **`ds-table`: with `stickyHeader` and `stickyFirstColumn` together, the first body row painted OVER the
279
+ header.** `--table-sticky-corner-z` exists so the corner where both sticky axes meet sits above the body's
280
+ pinned cells, but the sticky-header rule out-specified it, leaving the pinned header cells at the same
281
+ z-index as the pinned body cells — and on a tie DOM order wins, so the body won. The header row read as
282
+ the first row's data in the pinned columns. Found while building virtual scroll, and it was never specific
283
+ to it: any tall table with both flags had it. The sticky-header rule now leaves the pinned cells' z-index
284
+ to the corner token.
285
+ - **`ng add` never ran its schematic — in any released version.** The package is `"type": "module"` while
286
+ the compiled schematic is CommonJS, so Node refused to load it (`exports is not defined in ES module
287
+ scope`) and the DS global styles were never wired automatically; every consumer either added the `@use`
288
+ line by hand or shipped without the styles. The build already wrote a nested
289
+ `schematics/package.json` with `{"type":"commonjs"}` to fix exactly this, and **`npm pack` silently drops
290
+ it** — npm treats a directory holding a `package.json` as a separate package root — so the marker existed
291
+ in `dist/` and was absent from the tarball. The schematic is now authored as `.cts` and ships as `.cjs`,
292
+ which survives packing, and the build fails loudly if that emit is missing.
293
+ - **`ds-menu-divider` added a gap on top of the menu's own row rhythm, so a separated group read as a hole.** The divider carried `padding: var(--space-1) 0` while `ds-menu` already spaces its rows with `gap: var(--space-0-5)`. The two stack: measured in a consumer's account menu, adjacent items sat 2px apart while the divider produced 6px + line + 6px, tripling the local rhythm exactly where the eye reads a boundary. Menu items already carry their own `8px 12px` padding, so the line needs no help to separate. The default padding is now **0** — the line takes one row's place instead of adding a second gap — and a menu that genuinely wants divider *plus* air opts in with the new **`--ds-menu-divider-spacing`** token. This follows the direction the platforms took: Material 3 Expressive treats "with gap" as a device SEPARATE from "with divider" rather than bundling them, and Angular Material exposes the same spacing as tokens (`--mat-menu-divider-top-spacing` / `-bottom-spacing`) after shipping it baked in. Visual-only, and only for menus that use the divider.
294
+ - **`ds-table` gave the page a second scrollbar when it sat below the fold.** Its host was `display: block` with no `position`, while the `.visually-hidden` nodes it renders — the caption, the two `role="status"` announcers and the per-header sort-state spans — are `position: absolute`. With no positioned ancestor they resolved against the initial containing block, so each one contributed its layout offset to the DOCUMENT's root scroller: a consumer whose shell is `100vh` + `overflow: hidden` with one inner scrolling region got a phantom second scrollbar beside it, growing with how far down the page the table sat. Measured in a consumer with three tables on one tab — the root scroller reported 1902px against a 728px viewport, 1174px of overflow that no visible content occupied; with the host positioned it is 0 and the app's own region still scrolls. The host is now `position: relative`. Nothing else moves: the SR nodes stay 1×1 and clipped, and the overlays that must escape the table are portaled rather than absolutely positioned inside it.
295
+ - **A nested `ds-app-layout` opened its rail whenever an OUTER one was open, and its scrim swallowed the clicks meant for the outer.** The open state was written as `:host(.rail-open) &`, which Angular's emulated encapsulation compiles to a DESCENDANT selector — and every instance of a component shares one encapsulation attribute, so `.rail-open[_nghost-x] .rail[_ngcontent-x]` matched the rail of every layout nested inside an open one. Two layouts on a page (a docs shell holding a demo, an app holding a preview pane) opened and closed in lockstep, and clicking the backdrop hit the inner layout's scrim, whose `closeRail()` was a no-op. The state now lives on the elements it styles (`.rail.open` / `.scrim.open`), where a selector cannot reach across host boundaries.
296
+ - **The overlay rail escaped its layout and covered the whole window.** Below `lg` the rail is `position: fixed`, which resolves against the viewport, so a layout embedded in a page threw its rail over the top-left of the window instead of its own box — three shells on one docs page stacked three rails and three full-page scrims. The rail and scrim are now `absolute` against a `position: relative` host, which is identical for a full-viewport shell and correct for an embedded one.
297
+ - **A nested `ds-app-layout` could paint its rail OVER the outer shell's.** The rail sits at
298
+ `--layer-drawer` and its scrim one below; `position: relative` alone still left every layout resolving
299
+ that layer in the one root stacking context, so an inner layout's rail could stack above an outer
300
+ layout's open rail instead of beneath it. The host now sets `isolation: isolate`, giving each
301
+ `ds-app-layout` its own stacking context — the same fix `ds-drawer` already carries. Nothing changes
302
+ for a full-viewport shell with no layout embedded inside it.
303
+ - **The `ds-time-picker` panel drew the CONTROL radius, so it did not match the date picker beside it.**
304
+ Its dropdown was the one floating panel left on `--radius-md` (8px) while every other surface — menus,
305
+ popovers, cards, modals, and `ds-date-picker`'s own calendar — resolves the panel role. Two pickers in
306
+ one form therefore rendered different corners. The panel now reads
307
+ `var(--ds-time-picker-panel-radius, var(--ds-radius-panel))`, which is 12px, and the new hook is
308
+ FORWARDED onto the portaled pane — a token declared without being forwarded is dead for per-instance
309
+ overrides, which is exactly the `--ds-overlay-enter-scale` bug fixed elsewhere in this release. It was
310
+ also the only property on that element without a hook, since fill, border and shadow all had one.
311
+ Restore the old corner with `ds-time-picker { --ds-time-picker-panel-radius: var(--radius-md); }`; the
312
+ trigger's radius is untouched.
313
+ - **A path change that only mirrors the reader's position no longer resets the content scroll.** A docs shell whose scroll spy rewrites `/area/section` as the user scrolls hit a loop: the rewrite looked like a page change, the layout scrolled to top, the spy saw the first section again and rewrote the path back. Such a navigation must now carry `state: { dsSamePage: true }`, which the layout skips for both the scroll reset and the rail close. Read from `Router.lastSuccessfulNavigation()` — `getCurrentNavigation()` is already cleared when `NavigationEnd` reaches a subscriber.
314
+ - **Closing the rail by NAVIGATING no longer pulls focus back to the burger.** Restoring focus to the trigger is right for a dismissal — Escape, the scrim — and wrong for a link: the reader activated it, so focus belongs wherever the router put it, and handing it back announced "Open navigation" instead of the page they asked for. Dismissal keeps the restore; the navigation and breakpoint paths now clear `railOpen` directly. The breakpoint path had also depended on `compact` being written one line earlier to avoid focusing a trigger that is hidden on desktop — that ordering trap is gone with it.
315
+ - **A closed compact `ds-app-layout` rail no longer holds focus, or 112 tab stops, behind the screen.**
316
+ Below the breakpoint the rail is translated off-canvas, which hides it visually and not at all from
317
+ assistive tech: it kept `role="dialog"` + `aria-modal="true"`, every nav link stayed tabbable, and the
318
+ caret stayed inside the hidden panel after Escape or a scrim click — `cdkTrapFocusAutoCapture` hands
319
+ focus back only when the directive is DESTROYED, not when it flips off — so the next Tab continued from
320
+ invisible navigation with no visible focus ring. The closed overlay rail is now `inert`, and closing it
321
+ returns focus to whatever control claims the rail through `aria-controls`, which both `dsRailTrigger`
322
+ and the DS-button forwarding (`[ariaControls]="shell.railId"`) already set. Verified in Chrome at 604px.
323
+ At/above the breakpoint nothing changes — the rail stays in the layout and interactive.
324
+
325
+ - **`--ds-overlay-enter-scale` now reaches the portaled panel, so `ds-scale-in` can be retuned per
326
+ instance.** The token was declared and resolved on the pane but missing from the set
327
+ `prepareOverlayEnter()` forwards, so `ds-select { --ds-overlay-enter-scale: 0.9; }` did nothing while
328
+ the other four enter tokens worked — 0.7.1 shipped it as a known gap. Covers every overlay panel
329
+ (select, multi-select, autocomplete, date / time / colour picker, popover, tooltip, menu submenus). A
330
+ global override always worked and is unaffected.
331
+
332
+ ## 0.7.1 — 2026-08-04
333
+
334
+ ### Added
335
+
336
+ - **`TableColumn.sortValue` — sort a column by its DOMAIN value instead of the rendered text.** Without
337
+ it `clientSort` compares what the cell displays, so `$1.2M / $840K / $95K` sorted by the leading
338
+ character and `Oct 09, 2023 / Feb 27, 2024` sorted by month NAME: the table looked sorted and was not,
339
+ which is worse than leaving it unsorted. Pass an accessor per column —
340
+ `{ key: 'amount', label: 'Amount', sortValue: (row) => row.amountCents }` — returning a number, `Date`
341
+ or plain string. A consumer that had to re-parse its own rendered output (mm-broker shipped a
342
+ `display-compare.ts` sniffing currency, percents and three date formats) can delete it. Only affects
343
+ sorting: the header filter still lists what the user can see. Columns with plain numeric text already
344
+ sorted correctly and need nothing.
345
+
346
+ - **`ds-checkbox`, `ds-switch` and `ds-radio` warn in dev when a caption is projected instead of passed.**
347
+ `<ds-checkbox>Accept the terms</ds-checkbox>` renders no caption — the text comes from `[label]` only —
348
+ and it failed silently: no error, no warning, nothing in the types, so it survived review and was caught
349
+ by opening the page. All three share that contract, so all three now log which component swallowed the
350
+ text. Production is untouched: the probe that detects it is rendered only under `isDevMode()`, so no
351
+ extra node ships. Real projection support is still open — see `docs/todo.md`.
352
+
353
+ - **`ds-app-layout` collapses its rail to an off-canvas overlay below `lg`.** On narrow viewports the
354
+ rail no longer occupies a grid column: below the `lg` breakpoint (read at runtime from `--bp-lg`) it
355
+ leaves the flow, becomes a `position: fixed` panel translated off-canvas, and animates in over a
356
+ scrim. A new two-way `[(railOpen)]` model drives it (ignored at/above `lg`), and a
357
+ new `railLabel` input (`'Navigation'` by default) sets the panel's `aria-label` in compact mode. While
358
+ open and compact the panel is a focus-trapped `role="dialog"` with `aria-modal="true"`; clicking the
359
+ scrim, pressing `Escape` anywhere, navigating to a new path, or crossing back above `lg` all close it
360
+ (no body-scroll lock — the host is already `100dvh; overflow: hidden`). At/above `lg` nothing changes.
361
+ Wire a trigger — e.g. a burger in your own projected topbar — to `[(railOpen)]`. The rail keeps its DOM
362
+ position, so you still project the sidenav once. New tokens:
363
+ `--ds-app-layout-rail-bg-color` (`--surface-overlay`), `--ds-app-layout-rail-shadow`
364
+ (`--shadow-modal`), `--ds-app-layout-scrim-color` (`--scrim, hsl(220deg 20% 12% / 45%)`). The
365
+ breakpoint is read from the emitted `--bp-lg` with no literal fallback, so the query and the
366
+ stylesheet's media block cannot disagree; if that custom property is missing — meaning the DS global
367
+ styles were never included — the layout stays in desktop mode and says so in dev rather than guessing
368
+ a width.
369
+
370
+ - **`dsReserveMessages` — turn on the reserved message row for a whole form at once.** With
371
+ `reserveMessage` now off by default, a validated form would otherwise repeat `[reserveMessage]="true"`
372
+ on every control. Put the directive on the form and every DS field declared inside it reserves:
373
+ `<form dsReserveMessages>…</form>`. It provides `DS_CONFIG` for its subtree, so it composes with the
374
+ app-level config instead of replacing it, and a field's own `[reserveMessage]` still wins so one
375
+ control can opt back out. The switch is the directive's presence, not an input — providers resolve
376
+ before inputs exist. Note it applies to fields **declared** inside the host: projected content keeps
377
+ the injector of the template it was written in.
378
+
379
+ - **`ds-time-picker` gains `label`, `required` and `optional` — a date + time row now aligns without a
380
+ hand-rolled label.** The time picker had no label API at all, so a labelled form row meant authoring the
381
+ label yourself; the date picker's own label reserved a row the time picker did not, leaving the two
382
+ triggers 22.8px apart vertically. The label renders the same `.label` block with the same tokens as
383
+ `ds-date-picker`, and drives the single-mode trigger's accessible name (`aria-labelledby` when a label
384
+ is set, `aria-label` when it is not) plus `aria-required`; range mode's start/end segment triggers are
385
+ not wired to the label yet.
386
+ Measured on a two-column probe, date vs time now differ by 0px on label top/height, trigger
387
+ top/height/bottom, value inset and glyph top.
388
+
389
+ - **The value typography of both pickers is now tokenised.** It was hardcoded: the date value was pinned to
390
+ `--font-mono` and the time trigger to `--font-weight-medium`, so a brand could not bring either in line
391
+ with `ds-input` / `ds-select`. Adds `--ds-date-picker-value-font-family` / `-font-size` / `-weight` and
392
+ `--ds-time-picker-value-font-family` / `-font-size` / `-weight`, plus `--ds-time-picker-required-color`.
393
+ The date picker's ghost mask now follows the same three tokens — without that, overriding the family
394
+ drifted the painted placeholders off the value behind them — and both the input and the mask carry
395
+ `font-variant-numeric: tabular-nums`, so a proportional override still lands on the mask.
396
+
397
+ - **`ds-modal` / `ds-modal-card` take an `[eyebrow]` slot above the title.** Dialogs that need a context
398
+ line ("MY ACTIVITY · ROBERT THOMPSON") had to put it as the first line of the body. The slot renders
399
+ nothing when unfilled, and ships uppercase + tracked by default, retunable via
400
+ `--ds-modal-eyebrow-text-color` / `-font-size` / `-weight` / `-tracking` / `-transform`. Internally the
401
+ `<h2 class="title">` and the eyebrow are now wrapped together in a `<div class="heading">` that carries
402
+ the `flex: 1` the `<h2>` used to hold — a consumer whose own CSS targeted `.modal-card .title` for that
403
+ flex must retarget `.heading`.
404
+
405
+ - **`ds-table` takes a `rowId` accessor.** Row identity (tracking, selection, expansion, the active-row
406
+ highlight) defaulted to `row.id`, so display-only data with no natural key had to be mapped through a
407
+ synthetic id just to satisfy the generic. Pass `[rowId]="row => row.channel + row.sentAt"` instead; the
408
+ row type relaxes from `{ id: string }` to `object`, and the resolver is public as `rowKey(row)` for hosts
409
+ reading `selectedIds` / `expandedIds`. Rows keeping an `id` need no change.
410
+
411
+ - **`ds-date-picker` and `ds-time-picker` take `fullWidth`.** Both hugged their content, so neither filled
412
+ a grid/flex track the way `ds-input` and `ds-select` do — a mixed form row had to pin the picker widths
413
+ by hand. Opt-in; the default stays hug-your-content.
414
+
415
+ - **`ds-pagination` takes `showPageSize`, and its range label is tokenised.** A screen with a fixed page
416
+ size had to hide the rows-per-page dropdown in CSS; the label could only be switched off, not restyled.
417
+ Adds `--ds-pagination-label-font-size` / `-weight` / `-color`.
418
+
419
+ - **`ds-table` per-side cell padding + header tokens.** `--ds-table-cell-pad-{top,right,bottom,left}` each
420
+ fall back to the existing `-pad-x` / `-pad-y` pair, so an editorial table can ask for a right-only gutter
421
+ (first column flush) without redefining both axes. Also adds `--ds-table-head-border-color`,
422
+ `--ds-table-head-weight` and `--ds-table-head-tracking`.
423
+
424
+ - **`DS_CONFIG.field.reserveMessage` sets the message-row default app-wide.** With the per-field default
425
+ now `false` (see Changed), a form that validates throughout can turn the reserved row back on in one
426
+ place: `provideDsConfig({ field: { reserveMessage: true } })` covers all 14 message-bearing fields
427
+ instead of repeating `[reserveMessage]="true"` on every control; a per-field input still wins. The
428
+ input's type widens from `boolean` to `boolean | null` (`null` = "not set" → fall through to the config,
429
+ then to the hard-coded fallback), so existing bindings and bare attributes behave exactly as before.
430
+
431
+ - **`focus()` on `ds-search`, `ds-input` and `ds-textarea`.** The search input was only reachable from
432
+ inside the component, so a filter toolbar's Clear button — disabled once there is nothing left to clear —
433
+ blurred into `<body>` and restarted Tab order at the top of the document. Also gives forms a way to
434
+ focus the first invalid field.
435
+
436
+ - **Five override tokens that were previously hardcoded:** `--ds-modal-title-font-size` (pairs with the
437
+ existing `-title-weight`), `--ds-date-picker-trigger-radius` (the counterpart of
438
+ `--ds-time-picker-trigger-radius`), `--ds-date-picker-panel-radius` (forwarded onto the portaled pane),
439
+ `--ds-checkbox-radius` (the box only — the indeterminate dash keeps its own), and `--ds-menu-max-width`.
440
+ `ds-toast` also gains `--ds-toast-min-width` / `--ds-toast-max-width` as per-instance hooks over the
441
+ global `--toast-minw` / `--toast-maxw` geometry. All default to the current values.
442
+
443
+ - **`--ds-popover-min-width` and `--ds-menu-min-width`.** A popover (or a `ds-menu` projected into one)
444
+ hugged its content with no way to widen it — `--ds-popover-max-width` was the only size hook, so a user
445
+ menu that should be wider than its longest item needed global CSS against `.popover` / `ds-menu`. Both
446
+ default to `auto` (today's behaviour) and both are forwarded onto the portaled overlay pane on open, so
447
+ scoping them per instance (`ds-popover { --ds-popover-min-width: 220px; }`) works.
448
+
449
+ - **Surface entrances are now customizable per surface, via four shipped presets.** Every DS surface
450
+ names its entrance through `--ds-<surface>-enter-keyframes` and takes `-enter-duration` / `-enter-easing`
451
+ (plus `-enter-offset` or `-enter-scale` for the travel/scale a preset reads); surfaces that animate on
452
+ close also take `-leave-duration` / `-leave-easing`. Covered: overlay panels (`--ds-overlay-*`, shared by
453
+ select, multi-select, autocomplete, date / time / colour picker, popover, tooltip and menu submenus),
454
+ modal, drawer, bottom sheet, toast, banner, alert and loading overlay. The presets are global keyframes —
455
+ `ds-slide-in` (fade + short travel), `ds-scale-in` (grows from a micro-scale), `ds-fade-in` (opacity only)
456
+ and `ds-slide-edge-in` (full-distance travel, no fade) — so `ds-select { --ds-overlay-enter-keyframes:
457
+ ds-fade-in; }` is enough to re-skin one instance, and portaled panels forward the tokens onto their
458
+ overlay pane on open — every one except `--ds-overlay-enter-scale`, which is not forwarded, so scaling
459
+ one overlay panel per instance does not work yet (scope it globally instead). Your own `@keyframes` work
460
+ too, but must be declared in GLOBAL styles: emulated view encapsulation renames keyframes defined in a
461
+ component stylesheet. `none` disables an entrance.
462
+ All defaults are unchanged. Leave keyframes are deliberately not swappable — modal/drawer/bottom-sheet
463
+ teardown matches them by name — and reduced motion still wins: the library zeroes the duration itself,
464
+ so a custom entrance carrying its own timing is silenced too. New: `src/lib/styles/_surface-motion.scss`
465
+ (exported from `styles/ds`; add it alongside `styles/overlay-motion` if you import partials à la carte).
466
+
467
+ ### Changed
468
+
469
+ - **`clientSort` now sinks blank cells to the bottom in BOTH directions, and collates text naturally.**
470
+ Two changes to how an existing table sorts, both deliberate. (1) A cell that reads as "no data" — empty,
471
+ `—`, `–`, `-`, `n/a`, `never`, `none`, matched case-insensitively — sorts last regardless of direction,
472
+ so a descending sort no longer opens with a screen of empty rows. Previously an empty string was simply
473
+ the smallest value and floated to the top. (2) The text fallback now passes `{ numeric: true }` to
474
+ `localeCompare`, so `item 9` comes before `item 10` instead of after it. Both apply to every
475
+ `clientSort` column, with or without the new `sortValue`. If a table relied on blanks sorting first,
476
+ supply a `sortValue` that maps them to a real value.
477
+
478
+ - **Several exported component classes change their member surface, which breaks a consumer that extends
479
+ them.** Everything else in this release is additive for anyone using the `<ds-…>` elements. Subclassing
480
+ a DS component is unsupported (`design-system.md` § Components), but where it happens the names collide —
481
+ TS4114 demands an `override` modifier, TS2415 fires on a redeclared private member, TS2416 where a
482
+ signature differs. New members this range: all 14 message-bearing field components gain
483
+ `reserveMessageResolved`, and `CheckboxComponent`, `SwitchComponent` and `RadioComponent` also gain a
484
+ protected `devMode`; `InputComponent` and `TextareaComponent` also gain `control` and `focus`, and
485
+ `SearchComponent` gains `focus`; `TableComponent` gains `rowId` and `rowKey`; `PaginationComponent`
486
+ gains `showPageSize`; `TimePickerComponent` gains `label`, `required`, `optional`, `labelId` and
487
+ `fullWidth`; `DatePickerComponent` gains `fullWidth`; and `AppLayoutComponent` gains `railOpen`,
488
+ `railLabel`, `compact`, `closeRail` and the private `navigation`, `destroyRef` and
489
+ `watchDesktopBreakpoint`. One REMOVAL: `TooltipDirective` (`dsTooltip`) drops its protected `onOpen`,
490
+ split into `onPointerEnter` / `onFocusIn` / `onFocusOut` plus a private `scheduleShow`,
491
+ `describedElement` and `focusedTarget` — a subclass that overrode `onOpen` no longer compiles, because
492
+ its `override` now names a member the base does not declare. Rename the subclass's own member, or add
493
+ `override` where the base's semantics genuinely match. Build after upgrading — the compiler enumerates
494
+ every collision.
495
+
496
+ - **A nested `provideDsConfig` now MERGES with the config above it instead of replacing it.** The
497
+ config resolves through the element-injector chain, so it was always scopable to a route, component
498
+ or directive — but because the provider used `useValue`, a subtree that set one flag silently dropped
499
+ every unrelated app-level setting (scoping `field.reserveMessage` on a form would reset
500
+ `datePicker.locale`, `timePicker.format`, `breadcrumbs.separator` to their defaults, with no error).
501
+ Merging is section by section: only the keys you name are replaced. No action needed — a single
502
+ root-level call behaves exactly as before, and nested provision was neither documented nor usable
503
+ safely. The merge runs through a newly exported helper, `inheritDsConfig(config)`, which reads the
504
+ nearest ancestor config (`skipSelf`, `optional`) and shallow-merges per top-level section; call it from
505
+ within an injection context if you need the same behaviour in your own factory provider or directive
506
+ metadata. This is what makes `dsReserveMessages` composable.
507
+
508
+ - **BREAKING (layout): `reserveMessage` now defaults to `false` on every field.** It shipped default-on
509
+ in 0.7.0; the reserved row is right for a form that validates and wrong for the many forms that never
510
+ show a message, where it added ~23px of dead space under every control and made a normal 16px field
511
+ stack read as a ~39px hole. The resolution chain is unchanged — per-field input, then
512
+ `DS_CONFIG.field.reserveMessage`, then the default — only the final fallback flipped, so all 14
513
+ message-bearing fields follow (`ds-input`, `ds-textarea`, `ds-select`, `ds-autocomplete`,
514
+ `ds-multi-select`, `ds-checkbox`, `ds-radio`, `ds-radio-group`, `ds-switch`, `ds-slider`,
515
+ `ds-date-picker`, `ds-time-picker`, `ds-color-picker`, `ds-otp-input`). **To restore 0.7.0 behaviour
516
+ exactly, one line:** `provideDsConfig({ field: { reserveMessage: true } })`. Per form or per field,
517
+ bind `[reserveMessage]="true"`. Two clean-ups this enables: existing `[reserveMessage]="false"`
518
+ bindings are now redundant and can be deleted, and any tighter sub-stack added to absorb the reserved
519
+ gap should go back to the normal stack spacing.
520
+
521
+ - **`ds-time-picker` matches the field family: the clock glyph moved to the trailing edge, the value
522
+ weight dropped to regular, and the trigger gap narrowed.** The glyph rendered BEFORE the value at 14px
523
+ while every sibling field (`ds-date-picker`, `ds-select`, `ds-input`) puts its affordance last at 16px, so
524
+ a date + time row read as two mirrored controls; the trigger also carried `--font-weight-medium` against
525
+ the family's regular, and an 8px gap against 4px. Purely visual — set
526
+ `--ds-time-picker-value-weight: var(--font-weight-medium)` to keep the old weight.
527
+
528
+ - **`fullWidth` on `ds-date-picker` now pushes the calendar glyph to the trailing edge.** Stretching the
529
+ trigger left the value + glyph packed at the left (the glyph sat 122px short of the right edge on a 274px
530
+ field), so a full-width date field did not line up with the time picker or a `ds-select` beside it.
531
+
532
+ - **Overlay panels now enter FROM their trigger edge instead of always sliding downward.** A panel below
533
+ its trigger still slides down into place; one placed above now rises, and a side-placed panel comes in
534
+ horizontally — `ds-scale-in` likewise grows out of the anchored edge. Previously every panel, including
535
+ a tooltip sitting above its trigger, animated top-down. Purely visual; no API change.
536
+
537
+ ### Fixed
538
+
539
+ - **`dsTooltip` now describes the element that actually takes focus, so a tooltip on a non-focusable
540
+ host reaches a screen reader.** It set `aria-describedby` on its host unconditionally. That is right
541
+ when the host is the control, but `ds-menu-item` carries `role="none"` and puts the real `<button>`
542
+ inside, so the description landed on an element the user never focuses: a disabled menu item showed
543
+ its "why" to sighted keyboard users and to nobody else. The directive now records the target of the
544
+ `focusin` event — which bubbles, so it IS whatever took focus — and describes that. A pointer-only
545
+ open still uses the host, where no screen reader is involved. Deliberately not implemented by
546
+ searching the host's subtree for something focusable: that would put the tooltip inside another
547
+ component's internal DOM and hard-code a list of what counts as focusable.
548
+
549
+ - **`ds-pagination`'s rows-per-page dropdown no longer follows the app's field defaults.** The internal
550
+ `ds-select` was rendered without a `reserveMessage` binding, so it inherited whatever the app had set —
551
+ and a page-size dropdown shows neither hint nor error, so it had nothing to reserve. With the row
552
+ reserved the pager measured 54.8px instead of 32 and, because the `nav` centres its children, the
553
+ select's control sat ~11px above the page buttons' baseline. It is now pinned off inside the template,
554
+ which also makes it immune in the other direction: an app that opts back in with
555
+ `provideDsConfig({ field: { reserveMessage: true } })` or wraps a region in `dsReserveMessages` no
556
+ longer re-breaks every pager inside it. A consumer that collapsed the row with a global
557
+ `ds-pagination ds-field-message { display: none }` can drop that rule.
558
+
559
+ - **`ds-stat`'s card now fills a stretched host, so a KPI row renders equal-height tiles.** The host is
560
+ `display: block` and `.stat` carried no height, so in a `1fr` grid track the host stretched while the
561
+ visible surface stayed content-sized: three tiles where only two had a `caption` painted 102.1px inside
562
+ 126.9px hosts, leaving 24.8px of empty cell under the odd one out. It reads as a layout bug rather than
563
+ as a missing caption, and no token reached it — consumers were shipping
564
+ `ds-stat { height: 100%; .stat { height: 100% } }` from a global stylesheet against DS-internal markup.
565
+ A tile in an unstretched context is unaffected, since the host is still content-sized there.
566
+
567
+ - **`ds-app-layout` no longer scrolls the content back to top on a same-page URL change.**
568
+ `LayoutScrollService` reset the scroll on every router `NavigationEnd`, so a sort, page or filter change
569
+ that only rewrites the query string or fragment yanked the user to the top of the list. It now compares
570
+ the path (the part before `?` / `#`) and only resets when the path itself changes; `scrollToTop()` stays
571
+ public for a host that wants to reset explicitly, which is per-interaction and therefore more precise
572
+ than the old blanket reset.
573
+
574
+ - **`ds-table`'s header no longer desyncs when a host maps the "off" sort click back to its own default.**
575
+ Cycling past `desc` nulled `sortKey` internally; a server-paged host that cannot honour "unordered" pushes
576
+ its default key back, and on the *default* column that write is a no-op for Angular's binding diff — so the
577
+ table kept `sortKey === null`, leaving rows ordered while every header showed the neutral icon and
578
+ `aria-sort="none"`. The key now survives the cycle and `sortDir === null` alone means unsorted; rendering
579
+ is unchanged. **If your host reads `sortKey` to decide whether a sort is active, gate on `sortDir`
580
+ instead** — `sortKey` is now non-null after the third click (it names the column the user last touched),
581
+ so `if (sortKey) …` would keep sorting where it previously stopped.
582
+
583
+ - **A selected dropdown option no longer loses its tint to the hover/keyboard-active state.** In
584
+ `styles/_dropdown-overlay.scss` the `:hover` / `.is-active` branch out-ranked `.is-selected` on
585
+ specificity, so it repainted the row to `--surface-secondary` while keeping the selected label colour —
586
+ and because the panel seeds `.is-active` on the selected option when it opens, it showed at REST too, not
587
+ only under the cursor. A brand that gives the selected row a dark fill got unreadable text. The neutral
588
+ branch is now scoped with `:not(.is-selected)` and the selected row has its own hover/active step
589
+ (`--primary-muted`).
590
+
591
+ - **A read-only `ds-modal` no longer draws an empty footer strip.** `.actions` rendered its `border-top`
592
+ and padding even with nothing projected into `[actions]`; it now hides when empty, the same guard the
593
+ card already used for `.impact`.
594
+
595
+ - **`ds-docs`-style à la carte consumers were missing the overlay-panel entrance.** `styles/overlay-motion`
596
+ is now imported by the docs app itself, so portaled panels animate there as they do for consumers of the
597
+ bundled `styles/ds` entry.
598
+
599
+ - **Dialogs opened through `ModalService` no longer carry the `ds-overlay-pane` panel class.**
600
+ `ModalService.open()` — and therefore `confirm()` — tagged the CDK overlay pane with `ds-overlay-pane`,
601
+ which layered the shared overlay-panel entrance onto the modal on top of its own card/backdrop
602
+ animation; the class is dropped, so `styles/overlay-motion` no longer applies to the pane and the modal
603
+ plays only its own `--ds-modal-*` entrance.
604
+
11
605
  ## 0.7.0 — 2026-07-30
12
606
 
13
607
  ### Changed
@@ -50,6 +644,12 @@ While the package is on `0.x`, minor releases may contain breaking changes.
50
644
  `-pad-y` / `-content-max-width` / `-height` → `--ds-app-layout-*`). Behaviour is unchanged — rename the
51
645
  references (see `migrations/`). A consumer still on 0.6.3's `ds-app-shell` must migrate.
52
646
 
647
+ - **Retroactive note: `TableComponent` gained four more members (`total`, `sortingOrder`,
648
+ `animateHeight`, `scrollToTopOnPageChange`), and most other component classes changed too**, so a
649
+ consumer that extends a DS class (unsupported — `design-system.md` § Components) can collide on a
650
+ name here as well, exactly as in 0.6.3. Same resolution: rename the subclass's own member, or add
651
+ `override` where the base's semantics genuinely match.
652
+
53
653
  ### Added
54
654
 
55
655
  - **New override tokens for two baked-in weights: `--ds-sidenav-item-label-weight` and
@@ -279,6 +879,15 @@ While the package is on `0.x`, minor releases may contain breaking changes.
279
879
  - **`ds-toast` now slides up from below into place as it enters** (previously it dropped in from
280
880
  slightly above). The exit animation is unchanged — the toast still slides up as it fades out.
281
881
  Visual/motion only; no API change.
882
+ - **Retroactive note: the new `ds-table` column API grew `TableComponent`'s member surface by ~76
883
+ names, which breaks a consumer that extends the class.** Everything above is additive for anyone
884
+ using the `<ds-table>` element. Subclassing a DS component is unsupported (`design-system.md`
885
+ § Components), but where it happens the new names collide — TS4114 demands an `override` modifier,
886
+ TS2416 fires where the signature differs. Collisions seen in the wild: `zebra`, `columnOrder`,
887
+ `orderedColumns`, `visibleColumns`, `toggleColumn`, `onColumnDrop`, `moveColumn`, `resetColumns`,
888
+ `columnFilters`, `exportCsv`, `onResizeMove`, `onResizeEnd`. Rename the subclass's own member, or
889
+ add `override` where the base's semantics genuinely match (`zebra` must then adopt the base's
890
+ `booleanAttribute` transform). Build after upgrading — the compiler enumerates every collision.
282
891
 
283
892
  ### Fixed
284
893