@ids-group-ltd/ids-design-system 0.7.1 → 0.9.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,704 @@ While the package is on `0.x`, minor releases may contain breaking changes.
8
8
 
9
9
  ## Unreleased
10
10
 
11
+ ## 0.9.0 — 2026-08-10
12
+
13
+ ### Changed (breaking, behaviour)
14
+
15
+ - **`ds-table` `sortMode` and `filterMode` default to `'server'`, were `'client'`.** Server-paged is the
16
+ normal case, and there the old default was actively wrong: the table sorted the current page, so the
17
+ rows looked sorted and were not — a dev warning existed only to say so. An undeclared table now emits
18
+ `(sortChange)` / updates `columnFilters` and reorders nothing itself. **A table that holds every row
19
+ must now declare `sortMode="client"` / `filterMode="client"`**; the dev warning has been turned around
20
+ to catch exactly that case (no `total` bound + sortable or filterable columns + no declared mode).
21
+
22
+ ### Changed (breaking, visual)
23
+
24
+ - **The `ds-select` / `ds-multi-select` dropdown panel has a 12px corner, was 8px.** It was the one panel
25
+ outside the radius role layer — modal, popover, date picker, time picker, autocomplete, bottom sheet, card,
26
+ stat and page footer all resolve `--ds-radius-panel` — so it disagreed with its siblings by 4px and could
27
+ not be retuned through the role consumers are told to use. Restore with
28
+ `--ds-select-panel-radius: 8px`, or `--ds-radius-panel: 8px` to move every panel together.
29
+
30
+ - **Seven exit `@keyframes` are gone, replaced by four global presets.** `modal-out`, `ds-sheet-fade-out`
31
+ and `drawer-scrim-out` become `ds-fade-out`; `ds-sheet-down` and the four `drawer-panel-close-*` become
32
+ `ds-slide-edge-out`. They were view-encapsulated, so referencing one was only possible from a global
33
+ stylesheet — but if you did, that is the mapping. Nothing about the rendered motion changed.
34
+
35
+ - **`ds-search` is 40px tall by default, was 36px.** It was the only control in the library on that
36
+ height — `ds-button`, `ds-input`, `ds-select` and both pickers all resolve `--field-h-md` — so a search
37
+ box in a toolbar sat a step short of everything beside it. All three sizes now come off the field scale
38
+ (sm 32 / md 40 / lg 48; only md moved). Restore with `ds-search { --ds-search-height: 36px; }`. The
39
+ height also falls through `--ds-field-height` now, so one token levels a whole toolbar.
40
+
41
+ - **The global `--search-h` token is gone.** It existed only to hold that 36px and nothing reads it.
42
+ Use `--ds-search-height` to retune search alone, or `--ds-field-height` for the family.
43
+
44
+ ### Changed
45
+
46
+ - **`ds-auth-layout` compresses its own chrome on a short viewport, so the layout is never the reason a
47
+ card scrolls.** Block padding, the column gap, the letter-mark tile and the masthead's inner gap clamp
48
+ against `svh`. At ~330px of viewport — a landscape phone — that furniture costs ~131px instead of ~219px.
49
+ Every multiplier reaches its maximum at a viewport **800px tall or more** — a viewport height, not a
50
+ screen size: a 1366x768 laptop sits near 630px once browser and OS chrome come off, and a 1080p screen at
51
+ 150% display scaling near 585px, so a good many desktops render the compressed furniture too.
52
+ **Type is deliberately excluded.** An earlier draft clamped the wordmark and the tile's glyph as well;
53
+ both were measured to buy zero vertical space — the wordmark shares a flex row with the tile, whose height
54
+ exceeds the wordmark's line box at every viewport height, and the glyph sits in a fixed-size grid box —
55
+ while shrinking the brand against a fixed 14px tagline, worst for the users who scale their display up.
56
+ Both are back to the fixed sizes 0.8.0 ships.
57
+ `svh` rather than `dvh` because the dynamic unit changes as a mobile URL bar hides, which would re-space
58
+ the column mid-scroll; `min-height` stays on `dvh` so no strip of body background shows when the bar
59
+ retracts. New opt-outs: `--ds-auth-layout-pad-block` and `--ds-auth-layout-mark-size` (set
60
+ either, or the existing `-gap`, to a fixed value and that dimension stops compressing). A card taller than
61
+ the space left still scrolls — deliberately, because the alternative (pinning the masthead and footer out
62
+ of the flow) frees more room but lets chrome overlap a tall form.
63
+
64
+ - **`ds-auth-layout` — a round of fixes from an audit of the above.** All additive or corrective; nothing
65
+ to migrate. The letter-mark is now `aria-hidden`, so a screen reader announces "MyAdmin" rather than
66
+ "A MyAdmin"; it also carries `flex-shrink: 0`, so a long wordmark can no longer squash the square tile
67
+ into a rectangle. `logoLetter` on its own renders its tile instead of nothing (the outer gate never
68
+ tested it). The glyph is taken with a code-point split rather than `charAt(0)`, which returned half a
69
+ surrogate pair for a brand starting with an emoji. `box-sizing: border-box` is declared on the host
70
+ rather than inherited, because the documented à-la-carte style path omits `styles/reset` and without it
71
+ `min-height: 100dvh` plus the block padding overflows by exactly that padding — the scrollbar this
72
+ component exists to avoid. The four `env(safe-area-inset-*)` calls gained `0px` fallbacks and moved to
73
+ physical `padding-left`/`padding-right`, since the safe area belongs to the device and must not swap
74
+ sides with text direction; note the insets are inert unless the **host app** sets `viewport-fit=cover`
75
+ in its viewport meta, which the library cannot do and did not previously say. New tokens, both
76
+ defaulting to today's behaviour: `--ds-auth-layout-mark-radius` (the tile's radius was the one value
77
+ with no override hop) and `--ds-auth-layout-brand-max-height` (`none` by default — set it to cap a
78
+ projected `[brand]` logo, which nothing constrained). New input `landmark` (`'none'` by default): the
79
+ card holds the whole content of an auth screen but `ds-card` renders an `<article>`, which is not a
80
+ landmark, so `landmark="main"` gives a screen-reader user something to jump to on a standalone auth
81
+ page. It is opt-in because the layout is also embedded inside pages that already own a `main`.
82
+
83
+ - **BREAKING: `ds-auth-shell` is renamed `ds-auth-layout`** (`AuthShellComponent` → `AuthLayoutComponent`,
84
+ and `--ds-auth-shell-*` → `--ds-auth-layout-*`). "Shell" is not this library's word for a layout — the
85
+ app-level one was renamed `ds-app-shell` → `ds-app-layout` back in 0.7.0, and shipping an auth counterpart
86
+ called a shell in 0.8.0 reintroduced the split vocabulary that rename existed to remove. Mechanical:
87
+ rename the tag, the class and the six tokens. Nothing about the behaviour or the slots changes.
88
+
89
+ ### Changed (internal, no action)
90
+
91
+ - **`--ds-radius-inner` now reaches the small affordances it was written for.** Thirty-three reads across
92
+ fifteen component stylesheets took `var(--radius-sm)` directly — dropdown options, field clear buttons,
93
+ calendar days, chips, tag and toast close buttons — so the role a consumer is told to retune reached
94
+ exactly one component. Nothing moves (the role's default IS `--radius-sm`, verified by measuring a page
95
+ before and after), but it changes what a square brand costs: zeroing the three radius roles used to leave
96
+ five surfaces rounded and now squares every one. Five focus-ring radii inside `:focus-visible` keep
97
+ following the raw scale deliberately — a ring traces a box, it is not a surface a brand designs.
98
+
99
+ ### Added
100
+
101
+ - **Exit motion is swappable, the way entrances already were** — `--ds-modal-leave-keyframes`,
102
+ `--ds-drawer-leave-keyframes` and `--ds-bottom-sheet-leave-keyframes`, plus four global presets that
103
+ mirror the entrance vocabulary (`ds-fade-out`, `ds-scale-out`, `ds-slide-out`, `ds-slide-edge-out`).
104
+ This was blocked by a real constraint the code documented: teardown matched the animation NAME on
105
+ `animationend`, so renaming the keyframe broke closing entirely. The guard now checks that the event came
106
+ from the animated element rather than from a child, which frees the name — and that same check collapsed
107
+ the drawer's four direction-specific exits into one preset, since an exit reads `--_ds-exit-x/y/scale`
108
+ and falls back to the matching `--_ds-enter-*`. Point a token at your own **global** `@keyframes`; a
109
+ component-scoped name is renamed by Angular and will not resolve.
110
+
111
+ - **Signal Forms bind to every DS control, with no wrapper and no adapter** — `<ds-input [formField]="f.email" />`
112
+ and the form owns the value, the validation, `touched`, `disabled` and the error text. This was very nearly
113
+ true already and nobody knew: `FormValueControl` requires exactly one member, a `value` `model()`, and all
114
+ fifteen controls had it. Measured across all of them — thirteen bound with no library change at all. What
115
+ was fixed here: `min`/`max`/`maxLength` on `ds-input`, `ds-textarea` and `ds-number-stepper` now accept
116
+ `undefined` on the write side (the binder sends it for an unset bound; read types are untouched);
117
+ `readonly` joins `ds-input`, `ds-textarea` and `ds-select` as the contract spelling of the existing
118
+ `readOnly`, because signal forms binds by NAME and a `readonly()` rule was reaching nothing; `minLength`
119
+ and `pattern` are new native attributes on `ds-input` and `ds-textarea`; `hidden` is declared on both
120
+ control-value-accessor bases, so a `hidden()` rule removes the control on all thirteen that carry one; and
121
+ `focus()` resolves the element that holds the value, so `focusBoundControl()` reaches the stepper's number
122
+ box rather than its minus button and the tabbable radio rather than the first in the DOM. Not implemented:
123
+ `dirty`, `pending`, `disabledReasons`. Reactive and template-driven forms are untouched. Docs: **Practice →
124
+ Signal Forms**, with a live form and a contract table stating the measured state.
125
+
126
+ - **`ds-modal` takes a `[title-badge]` slot and a `subtitle`.** Two consumer screens had abandoned
127
+ `ds-modal` and hand-rolled a `.scrim` + `.panel` because the header could only hold one string — losing
128
+ the focus trap, focus restore, the scroll lock, Escape, the enter/leave animation and, in one case, the
129
+ footer, which put a destructive action beside the close button. Same shape as `ds-page-header`; `title`
130
+ stays the accessible name, so projected markup never enters `aria-labelledby`. Two tokens:
131
+ `--ds-modal-subtitle-text-color` and `-font-size`.
132
+
133
+ - **`[dividers]` on `ds-modal` / `ds-modal-card`, default `true`.** `[dividers]="false"` drops the header
134
+ and actions rules AND the vertical padding that existed to clear them, because those are one design
135
+ decision. Two consumers had set `--ds-modal-divider: transparent` and were left with a 35px gap where 16
136
+ was wanted; one needed `!important` to win it back.
137
+
138
+ - **`ds-table`: the rest of what mm-broker's fork did that the base could not.** Keyboard column resizing —
139
+ the handle is a focusable `role="separator"` with Arrow (16px), PageUp/PageDown (64px) and Home to hand
140
+ the column back to automatic sizing; a drag handle that answered only to a pointer made a resizable column
141
+ unusable without a mouse. `exportFetcher` may now resolve a `Blob` or a URL as well as rows, for a file
142
+ the backend already formatted, and `exportFailed` emits the rejection — swallowing it made a failed export
143
+ indistinguishable from a slow one. Two box tokens: `--ds-table-min-width` (a readability floor, default 0)
144
+ and `--ds-table-hscroll-bottom` (offsets the sticky scrollbar out of a padded container, default 0).
145
+
146
+ - **The three `ds-modal` regions take their padding from tokens** — `--ds-modal-pad-x` for the gutter all
147
+ three share, plus `--ds-modal-header-pad-y`, `-body-pad-y` and `-actions-pad-y`. Two consumers were
148
+ rewriting these, one with `!important`, because the regions are padded for a divider-separated layout:
149
+ set `--ds-modal-divider: transparent` and you are left with spacing sized for dividers that are no
150
+ longer there. Nothing moves by default. Note the tokens go on `ds-modal` AND `ds-modal-card` — a dialog
151
+ opened through `ModalService` renders the card with no `ds-modal` ancestor.
152
+
153
+ - **`maxItems` on `ds-breadcrumbs`** — collapses the middle of a deep trail into a crumb that says how
154
+ many it stands for, keeping the first and, crucially, the LAST. Without a cap the row is `nowrap` with
155
+ `overflow: hidden`, so an overlong trail is clipped from the END — hiding the current page, the one
156
+ crumb the reader needs most. Opt-in; every crumb still renders by default.
157
+
158
+ - **Dev warnings no longer repeat themselves.** Every component with one wrote the same four lines around
159
+ it — `isDevMode`, an `effect`, a condition, a `console.warn` — and each copy shared the same flaw: the
160
+ effect re-runs when ANY signal it read changes, so a warning about a static misconfiguration could be
161
+ logged again on every keystroke. They now go through one internal helper that fires at most once per
162
+ message. Eleven hand-written warnings across `ds-button`, `ds-stat` and `ds-table` moved onto it —
163
+ ten call sites at HEAD, since the table gained more with lazy loading. `ds-tabs` keeps its own, because
164
+ its effect also owns registry bookkeeping that a plain warning cannot express.
165
+
166
+ - **`maxVisibleChips` on `ds-autocomplete`** — caps the chips in the trigger and collapses the rest into
167
+ "+N more". Without it a multi-select trigger grows a line per selection and pushes the rest of the form
168
+ down the page, which is how it was reported. Same input name, same transform and same wording as
169
+ `ds-multi-select`, which already had it — the two multi-value pickers should not diverge on this.
170
+ Backspace still removes the last SELECTED chip, not the last visible one.
171
+
172
+ - **`ds-stat` takes a projected value** — `[dsStatValue]` for a tile whose headline is a badge, a status
173
+ dot or anything a number slot cannot hold. `value` is now optional and acts as the fallback, the same
174
+ shape `[delta]` already had; existing tiles are untouched. The slot is namespaced on purpose: twenty
175
+ components in this library have a `value` input, so a bare `value` attribute would have set theirs to
176
+ the empty string on the way past. A dev warning fires if `unit` is set with no `value`, since a
177
+ projected headline owns the whole line and the suffix would silently vanish.
178
+
179
+ - **The package now ships `design-system.md` and `components.md`.** `design-system.md` is no longer a
180
+ catalogue: it carries the RULES — which spacing token goes between what, which type role a piece of
181
+ text takes, the field-height contract, who owns a gap, and how to override a component (including the
182
+ two things that break it: reaching for an internal class, and portaled panels). The 491-line inventory
183
+ it used to be moved to `components.md`. Both are readable from `node_modules`, so a consumer's agents
184
+ and tooling can follow the system instead of guessing plausible token values.
185
+
186
+ - **`ds-tabs` warns when two strips claim the same `urlParam`.** Both write the same query parameter, so
187
+ each erases the other's tab and a reload restores whichever wrote last — nothing throws and the URL
188
+ looks plausible. It is the easy mistake when turning `urlParam` on across an app, because `"tab"` is the
189
+ obvious name every time. Dev-mode only.
190
+
191
+ - **Selected dropdown rows have their own hooks** — `--ds-option-selected-bg-color`, `-label-color`,
192
+ `-bg-color-hover` and `--ds-option-check-color`, defaulting to the theme roles they used to read
193
+ directly. A brand that wanted a different selected treatment previously had to RETARGET `--primary-*`
194
+ inside `.ds-dropdown-panel` and then track what else in the panel read the same role. Panel-level: one
195
+ partial paints select, autocomplete and multi-select alike. Nothing moves by default.
196
+
197
+ - **`ds-field-group` — several controls in one bordered box** (`select + input`, `input + button`,
198
+ `input + select`). The group owns the border, the radius, the divider and a single `:focus-within` ring;
199
+ the controls inside render naked. Segments hug their content, `grow` takes the slack. `size` uses the
200
+ field height scale, plus `invalid` and `fullWidth`. A control knows it is a segment by injecting
201
+ `DS_FIELD_GROUP` rather than being told with an input — the alternative is manual, and one segment where
202
+ it was forgotten draws its own border mid-row. Six controls can be segments: `ds-input`, `ds-select`,
203
+ `ds-search`, `ds-autocomplete`, `ds-date-picker` and `ds-button`. Not `ds-number-stepper` (a composite
204
+ already) or `ds-multi-select` (its chips wrap, which a fixed-height row cannot take). Grouped controls must not carry a `label` or `hint` — the message row
205
+ would break the glued line, so it is suppressed and a group-level one is not built.
206
+
207
+ - **`ds-table` lazy loading** — `[lazy]` plus a `(lazyLoad)` output emitting `{ first, rows }` for the
208
+ range now on screen. `data` becomes a sparse array `total` long: write each fetched row at its absolute
209
+ index, and every gap inside the window renders a skeleton row until it arrives. The scroller is sized
210
+ from `total` rather than from what has arrived, so the scrollbar tells the truth from the first frame.
211
+ Needs `virtualScroll` (there is no window to fetch against otherwise) and `total`; a request is not
212
+ re-sent while the range it covered is still on screen. Dev warnings cover all three ways to wire it
213
+ wrong, including `sortMode="client"`, which would sort only the rows that happen to have loaded.
214
+
215
+ - **`[quiet]` on `ds-menu-item`** — a muted row for a secondary action like "Sign out" under a divider,
216
+ the sibling of the existing `[error]`. Recolouring one item was previously impossible through the
217
+ token: `--ds-menu-item-label-color` resolves on the host against the value inherited from `ds-menu`, so
218
+ setting it per item did not win and the colour had to go on the inner element. `[error]` still wins if
219
+ both are set. Colour comes from `--ds-menu-item-quiet-label-color`.
220
+
221
+ - **21 hooks for type and box values that a `font:`/`border:`/`padding` shorthand had swallowed.** Same
222
+ shape every time: the value sat inside a shorthand, so overriding the one property meant a selector
223
+ out-ranking the shimmed component rule. `ds-description-item` completes the eyebrow set both halves
224
+ (`--ds-description-list-term-weight` / `-tracking` / `-transform`, `-details-font-size` / `-weight`) —
225
+ the same five `ds-field-label` and the modal eyebrow already exposed. `ds-segmented` gains
226
+ `--ds-segmented-btn-border` (for a hairline chip row), `-btn-pad-x` and label type; `ds-tabs` gains
227
+ `--ds-tab-pad-top` / `-bottom` (an underline tab wants bottom-only and could not say so), label type,
228
+ `--ds-tabs-strip-gap` and `--ds-tabs-panel-pad-top`; `ds-menu` gains item padding, item label type and
229
+ `--ds-menu-gap`; `ds-checkbox` gains `--ds-checkbox-label-weight`, the third label property where size
230
+ and colour were already hookable. Every default reproduces today's value.
231
+
232
+ - **The theme's radius and elevation roles now reach portaled panels.** A pane lives under `<body>`, so
233
+ nothing component-scoped could reach it: squaring `--ds-radius-panel` left a square app with round
234
+ dropdowns, and the only fix was re-declaring the roles on `.ds-overlay-pane` globally. Roles now travel
235
+ with the tokens each component already forwards — but only where the host actually overrides the root,
236
+ so an open panel still follows a theme switch instead of pinning the value it opened with.
237
+
238
+ - **`--ds-badge-white-space`** (default `nowrap`, so nothing moves). A badge in a narrow, fixed-layout
239
+ table column has to be allowed to wrap or its label clips, and the property was the one thing on that
240
+ element not reachable through a token — the workaround was a global rule against the private `.badge`.
241
+
242
+ - **`showPageSize` and `showLabel` on `ds-table`**, forwarded to its footer pager. Both have always existed
243
+ on the standalone `ds-pagination` but were unreachable once the pager was inside a table, so hiding the
244
+ size picker on a fixed-page-size table meant a global selector reaching into the DS. Default `true` — no
245
+ change unless set.
246
+
247
+ - **`--ds-table-head-pad-top` / `--ds-table-head-pad-bottom`.** Header cells were the one padding in the
248
+ table that stayed symmetric — body cells have had per-side hooks since 07-31 — so a header wanting its
249
+ label tight to the top with air above the rule could only be reached with `!important`. Both fall back to
250
+ the density value, so nothing moves until one is set.
251
+
252
+ - **`ds-autocomplete` can be built as a search field.** `dsAutocompletePrefix` / `dsAutocompleteSuffix`
253
+ content slots — the same names and the same contract as `ds-input`'s addon slots — plus `[showChevron]`
254
+ (default `true`) to drop the trailing arrow, which on a search field invites a click that would list
255
+ everything. Previously a leading glyph had to be absolutely positioned over the field and the chevron
256
+ hidden with a global selector reaching for `.autocomplete-chevron`. Unlike a fixed `variant="search"`,
257
+ the slots also cover the icon-**and**-chevron case a combobox often wants.
258
+
259
+ - **`ds-autocomplete.clear()`**, emptying both the selected value and the text the user typed. Setting
260
+ `value` to null from outside left the typed query on screen, because the query is component state with no
261
+ input bound to it — so a host resetting the field after navigating had to query the inner `<input>` and
262
+ dispatch a synthetic `input` event at it. It deliberately does not move focus.
263
+
264
+ - **`--ds-autocomplete-panel-maxh`**, so the dropdown's height before it scrolls no longer needs the private
265
+ `--picker-maxh` (which `ds-multi-select` also reads, making it the wrong lever for one component).
266
+
267
+ - **`--ds-autocomplete-panel-radius`, bringing the last panel into the radius role layer.** Its dropdown was
268
+ the one portaled surface still hard-coding `--radius-lg` while modal, popover, card, bottom-sheet and both
269
+ picker panels resolve `--ds-radius-panel`, so a consumer who squared the three radius roles got a square
270
+ app with one rounded panel and no hook to reach it. Nothing moves by default — the role still resolves to
271
+ `--radius-lg` — and the token is forwarded onto the portaled pane on open like the other panel tokens.
272
+
273
+ - **`ds-app-layout` takes a `scrollReset` strategy, and `LayoutNavigationService` is public** (both asked
274
+ for by the ai-sdlc starter after their `ds-app-layout` migration). Owning the scroll CONTAINER had
275
+ quietly meant owning the POLICY: `scrollToTop()` was public so a screen could ADD a reset, but nothing
276
+ could suppress one the layout decided to do. `scrollReset: 'path' | 'never' | 'always'` defaults to
277
+ `'path'`, which is exactly today's behaviour — no consumer sees a change unless they set it. `'always'`
278
+ also resets on a query- or fragment-only navigation (what a server-paged list wants); `'never'` hands the
279
+ decision to the screen.
280
+ — Exporting the navigation service removes a duplication the layout was causing: "did the path change?"
281
+ was being re-derived per consumer, and one of them had THREE answers that disagreed, because a
282
+ `split('?')` keeps the fragment `pathChanged` strips. It is root-provided and stateless, so exposing it
283
+ costs nothing.
284
+
285
+ - **`ds-icon` warns in dev when a name resolves to nothing** (asked for by the ai-sdlc starter after an audit
286
+ found misspelled names on three screens). An unknown name rendered an empty `<svg>` in silence: the types
287
+ cannot catch it, because `IconName` stays open (`| (string & {})`) so a consumer can register their own
288
+ glyphs through `provideDsIcons()`, and closing the union would reject every registered name. The warning
289
+ names the offending value and sits on the one branch that knows — production pays a single falsy check.
290
+
291
+ ### Fixed
292
+
293
+ - **Opening `ds-date-picker` with the mouse no longer takes the caret out of the field.** Clicking the
294
+ calendar glyph moved focus into the day grid, which a mouse user did not ask for and which, with
295
+ `allowInput` on by default, pulled them out of a field they may have been typing in. The glyph now behaves
296
+ like a click on the field itself: focus follows what the field IS — typeable keeps the caret, read-only
297
+ focuses the grid. The keyboard path is unchanged, ArrowDown still enters the grid however the panel opened.
298
+
299
+ - **A settled `ds-autocomplete` no longer shows an empty text box beside its value.** In single mode the
300
+ chosen label has always rendered as its own element, but the filter input stayed 80px wide next to it and
301
+ took the caret, so a field with a value read as free text rather than a picker. With a value and the panel
302
+ closed the input now collapses to zero width — it keeps focus, so clicking still opens the panel and
303
+ typing still filters.
304
+
305
+ - **A column resize no longer moves columns the reader never touched.** Only the dragged column had a width,
306
+ so the browser redistributed the remainder across the auto-sized rest and they visibly jumped. The first
307
+ resize — pointer or keyboard — now freezes every visible column at what it currently measures, once.
308
+
309
+ - **The clipped-cell popover reaches template cells, and a narrowed header keeps its label.** Clip detection
310
+ walks descendants, so overflow inside a `dsCellTemplate` behaves like a plain truncated cell; a header
311
+ narrowed by resizing gets a `title` with the full label on hover. Scoped to columns that asked for
312
+ `truncate` — a handler on every cell would swallow the row click on an interactive table.
313
+
314
+ - **`sortValue` string ordering is case- and accent-insensitive** (`sensitivity: 'base'`), matching the
315
+ comparator consumers are migrating off, so a column of strings does not silently reorder.
316
+
317
+ - **`--ds-field-height` now reaches six more controls.** `ds-autocomplete`, `ds-multi-select`,
318
+ `ds-color-picker`, `ds-number-stepper`, `ds-split-button` and the `ModalService` confirm input each
319
+ spelled their height as the raw `--hit-*` value, so the knob the token name advertises did nothing for
320
+ them. All six are on the `field-box-height` contract now, and no raw `--hit-cozy` height is left in the
321
+ library. Same pixels at every size **except `ds-number-stepper` at `size="lg"`, which goes 44px → 48px**
322
+ to match the family's large field; the other sizes are unchanged.
323
+
324
+ - **Date and time pickers keep step with the fields beside them under `[data-density]`.** Both triggers
325
+ hard-coded their horizontal padding, which happened to equal `--field-pad-x` at default density but did
326
+ not shrink with it — so setting a density left a picker 8px wider than the `ds-input` next to it. Both now
327
+ resolve `--ds-date-picker-trigger-pad-x` / `--ds-time-picker-trigger-pad-x` from the field family.
328
+
329
+ - **`ds-card`'s box fills a stretched host**, so a grid row of cards with unequal content paints equal
330
+ heights instead of a stretched host wrapping a short bordered box. `ds-stat` already did this; cards
331
+ needed a `::ng-deep .card { height: 100% }` from the consumer. Nothing changes where the host is
332
+ content-sized, which is every card not in a stretching row.
333
+
334
+ - **`density="compact"` no longer defeats every `ds-table` padding hook.** It pinned `padding` straight onto
335
+ the cells, which out-specifies the `--ds-table-cell-pad-*` and head hooks, so a compact table silently
336
+ ignored all of them. It now retunes the same density tokens `[data-density]` uses — identical spacing, and
337
+ the hooks apply.
338
+
339
+ - **`ds-date-picker`'s trigger stays visibly active while its own panel is open.** The indicator was bound to
340
+ focus only, and opening from the calendar glyph moves focus into the day grid — so the trigger went dark
341
+ while its panel was open, and the refocus on close made it read as a flicker.
342
+
343
+ - **`ds-table`: the three things that still forced a consumer wrapper.** All from mm-broker folding its
344
+ 2160-line `ids-data-table` fork onto the base.
345
+ — **`filterMode: 'client' | 'server' | 'none'`**, mirroring `sortMode` — it shipped defaulting to
346
+ `'client'` and the default was flipped to `'server'` later in this same release, above — plus
347
+ **`columnFilterOptions`** for the real value domain. A header filter on a server-paged table was wrong
348
+ twice over: the checklist could only offer values from the page in hand, and the local pass then filtered
349
+ what the server had already filtered. `'server'` tracks `columnFilters` and filters nothing; `'none'`
350
+ drops the affordance. A dev warning catches the silent case — `filter: 'set'` with `total` bound and no
351
+ declared mode.
352
+ — **`dsHeaderFilter`**, a template slot for a criterion the checklist cannot express (a date range, a
353
+ numeric threshold, an async lookup). The table keeps the header button, the popover and the active-filter
354
+ styling; `active` on the directive tells the highlight whether your criterion is set, because only you
355
+ know. The context carries `close`, so the panel can dismiss itself after applying.
356
+ — **A live region for sort state and row range.** The table announced loading and nothing else, so a
357
+ screen-reader user got no confirmation that the order changed and paging never announced the new range.
358
+ One `role="status"` now carries both, with loading taking precedence while it lasts. `sortAnnouncement`
359
+ and `rangeAnnouncement` take the facts and return the sentence, so translation and word order stay with
360
+ the consumer.
361
+
362
+ - **`ds-tabs` keeps the active tab in the URL: `urlParam="tab"`** (asked for by the ai-sdlc starter). The
363
+ input both switches it on and names the parameter; leave it out and the URL is untouched. Names come from
364
+ each `ds-tab`'s `value` — the identifier `tabClosed` already emits — so there is no second list to keep in
365
+ step. The evidence for shipping it: in one admin port THREE of the four tabbed screens never got the
366
+ hand-wiring at all, so only the screen whose author reached for a helper worked.
367
+ — Names, not indices (`?tab=1` would repoint every old link the moment a tab is inserted); the first tab
368
+ writes no parameter and every write replaces (clean address, and flipping tabs does not fill the Back
369
+ button); an unknown or missing name lands on tab 0 rather than throwing. Outside a routed context the
370
+ input is inert — the router is injected optionally, so a strip in a dialog is unaffected.
371
+
372
+ - **Options in the picker panels had no pressed state.** Hover only — so on a phone, where there is no
373
+ hover, tapping a row in `ds-select`, `ds-autocomplete` or `ds-multi-select` gave no feedback that it had
374
+ been hit. The equivalent rows elsewhere (`ds-menu-item`, `ds-list-item`) have had one since 0.7.x. Fixed
375
+ once in the shared dropdown-overlay partial, so all three pickers get it, with a selected-row variant that
376
+ stays in the brand family rather than stranding the selected label colour on a neutral fill.
377
+
378
+ - **`ds-textarea size="sm"` and `="lg"` got the md vertical padding.** The size variants set the inner
379
+ `<textarea>`'s vertical pad (`--space-2` / `--space-4`), but the `:host`-prefixed pin at the end of the
380
+ file — added so the docs' unencapsulated `.field .control` specimen could not zero it — out-ranks them
381
+ once emulated encapsulation shims both selectors: `[_nghost] .field[_ngcontent] .control[_ngcontent]
382
+ textarea[_ngcontent]` carries one more attribute than `.field.sm[_ngcontent] …`. So every textarea
383
+ rendered with 12px top and bottom regardless of `size`, and retuning
384
+ `--ds-input-pad-y` moved all three. There are now three pins, one per size, and the size blocks keep
385
+ only the horizontal padding they own. Consumers see it only on a non-md textarea; the md default is
386
+ unchanged.
387
+
388
+ ## 0.8.0 — 2026-08-05
389
+
390
+ ### Added
391
+
392
+ - **`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.
393
+ - **`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.
394
+ - **`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.
395
+
396
+ - **Overlay panels fade out when DISMISSED, and still close instantly when you choose something.** Floating
397
+ panels (select, autocomplete, multi-select, both pickers, colour picker, popover) have closed instantly
398
+ since the unconditional leave animation was cut, because ~120ms of fade after picking an option reads as the
399
+ panel lagging behind a decision already made. A dismissal is the opposite: Escape, a press outside or the
400
+ page scrolling away produced no result, so the fade reads as the panel backing out rather than as delay.
401
+ `disposeWithLeave()` now takes that cause — `'select'` (the default, instant) or `'dismiss'` — and each
402
+ panel passes `'dismiss'` from exactly its Escape / outside-press / scroll paths. Tab still closes instantly,
403
+ because a fading panel must not linger behind moved focus.
404
+ — Tunable through `--ds-overlay-leave-duration` / `-easing`, defaulting to the `--ds-motion-exit-*` role.
405
+ Reduced motion zeroes the duration at `:root`, so the animation still runs and still drives teardown. A
406
+ fading panel is `pointer-events: none`, so it cannot swallow a click aimed at what is behind it.
407
+
408
+ - **`ds-checkbox`, `ds-switch` and `ds-radio` now RENDER a projected caption, and expose its colour and
409
+ size.** `<ds-checkbox>I accept the <a …>Terms</a></ds-checkbox>` — the first thing a consumer tries, and
410
+ the idiom every other body-bearing DS component accepts — used to render a control with no caption at all:
411
+ no error, nothing in the types. 0.7.1 added a dev warning; this makes the markup work. `[label]` stays the
412
+ documented API and still wins when both are given. One difference worth knowing: the required asterisk
413
+ comes with `[label]` only, because a projected caption's own markup is the only thing that knows where the
414
+ marker belongs.
415
+ — New hooks: `--ds-checkbox-label-color` / `-label-font-size`, the same pair on `ds-switch`, and
416
+ `--ds-radio-label-font-size` (`--ds-radio-label-color` already shipped). The font-size hook beats the size
417
+ class, so setting it pins the caption regardless of `size`. These are deliberately NOT part of the
418
+ `--ds-field-label-*` contract: a label above an input is a heading for the field and reads secondary, while
419
+ a caption beside a checkbox is the content being agreed to and reads primary — routing them together would
420
+ put "Remember me" in uppercase in any brand that sets `--ds-field-label-transform`. Recorded in the token
421
+ reference so it reads as a decision rather than an omission.
422
+ - **`ds-table` renders only the rows in view: `[virtualScroll]="true"` + `virtualRowSize`.** The body used to
423
+ `@for` over every row of `data()`, so 10 000 rows tanked scroll and paint. Virtual mode keeps ~25 rows in
424
+ the DOM regardless of the row count, padding above and below with two spacer rows that stand in for the
425
+ rest — so the scrollbar still spans the whole data set. Needs `maxHeight`: a bounded scroller is the
426
+ viewport it windows against, and without one nothing is virtualized (dev-warned).
427
+ — **NOT the CDK virtual-scroll viewport**, deliberately. That arrangement wraps the table in a transformed
428
+ content wrapper, and the transform creates a containing block that breaks both the sticky header and the
429
+ sticky first column this table already has. Spacer rows leave the existing scroller — and everything
430
+ sticky in it — untouched.
431
+ — Uniform row height is the precondition, not a preference: `virtualRowSize` is the only thing telling the
432
+ arithmetic where a row starts, so one row that grows puts every offset below it out by the difference.
433
+ Virtual mode therefore drives the CSS row height from that same input, forces `table-layout: fixed` (auto
434
+ layout re-measures against whichever rows are rendered, and the columns twitch as you scroll) and keeps
435
+ cells to one line. Row EXPANSION is suppressed with a dev warning; `pageSize` alongside it is warned about
436
+ too, since virtual scrolling is what pagination was for. Sorting, filtering, selection, sticky header,
437
+ sticky first column and column resizing all keep working.
438
+ — Zebra striping switches from `:nth-child` to an absolute-index class while windowing: a rendered row's
439
+ parity depends on its real position, and the spacer rows are children too.
440
+ - **`ds-filter-bar` — a Priority+ filter row: as many filters as fit, the rest behind "+N more".**
441
+ Every admin list past three filters hits the same wall — the row wraps to a second line on a laptop, or
442
+ the consumer hand-rolls an overflow menu. Each filter goes in an
443
+ `<ng-template [dsFilterItem]="180">`, and the split is decided from those declared widths plus one
444
+ `ResizeObserver` on the row. Never by measuring the filters: they would have to be in the DOM to be
445
+ measured, so anything that did not fit would flash into view before being taken away.
446
+ — A template rather than plain projection because the bar has to MOVE what does not fit into the panel,
447
+ and projected DOM cannot be relocated. Consequence worth knowing: crossing that boundary destroys and
448
+ re-creates the view, so a control's internal state (an open dropdown, focus) does not survive a resize
449
+ that collapses it — its value does, because that lives in the consumer's own signal or form control.
450
+ — The declared width is a contract, not a hint: the slot is sized to exactly that number, so the
451
+ arithmetic is true by construction and a filter is the same width in the panel as in the row.
452
+ — Mark trailing controls with `dsFilterBarTrailing` (search, a Clear button) rather than wrapping them:
453
+ the bar owns that group's gap and alignment, and a projected wrapper would be a plain block whose children
454
+ stack. The group sits outside the measured row, so flexbox subtracts its width before the row is measured.
455
+ — The trigger carries the count as text plus `aria-expanded`, and the panel is a focus-trapped
456
+ `role="dialog"`. There is exactly one copy of each filter in the accessibility tree, because filters MOVE
457
+ rather than being rendered twice and hidden — the usual implementation of this pattern needs `aria-hidden`
458
+ bookkeeping to compensate. `moreLabel` and `panelLabel` are there for translation.
459
+ — Both slots collapse when nothing lands in them (`:not(:has(*))`, not `:empty`, which a single whitespace
460
+ text node defeats): an empty flex child would still take the row's gap. Dev-mode warning when content
461
+ reaches the bar carrying neither slot marker, since such content is silently dropped.
462
+ - **`ds-auth-shell` — the scaffold for the screens in front of the login, counterpart to `ds-app-layout`.**
463
+ Consumers hand-rolled the unauthenticated scaffold every time, and it is the same four parts in each: a
464
+ brand lockup, an optional tagline, one card holding the form, and a support line under it. The brand row
465
+ is the sidenav's row — same `brand` / `logoLetter` / `[dsBrandName]` contract and the same letter-mark
466
+ tile, so the mark on the login screen is the mark in the rail afterwards. Deliberately NOT the string
467
+ splitting the ports used to tint one slice of a wordmark: a split has to guess where the accent belongs,
468
+ and the projection already says.
469
+ — The card body is the default slot, the support line is `[dsAuthSupport]` (a real `<footer>`, so it
470
+ carries the `contentinfo` landmark), and both the tagline and the support line collapse when absent
471
+ rather than leaving an empty flex child that would take the column's gap and push the card off centre.
472
+ — `cardElevation` / `cardPadding` pass through to `ds-card`; `--ds-auth-shell-min-height`,
473
+ `-card-max-width`, `-gap`, `-bg-color` and the two `-mark-*` colours are the public hooks.
474
+ — The host is the ONLY full-height box, which is what the ports got wrong: nesting a `100vh` wrapper
475
+ inside a `100dvh` one scrolls a page whose content fits. It also carries `env(safe-area-inset-*)` so a
476
+ notched phone in landscape does not put the card under the cutout. Inside it the column centres with auto
477
+ margins rather than centre alignment — identical while the host can grow, but not when it cannot: embed
478
+ the shell at `--ds-auth-shell-min-height: 100%` in a fixed-height parent and centre alignment puts a form
479
+ taller than the box above the scroll origin where no scrolling reaches it (measured at −115px), while
480
+ auto margins collapse to zero and pin it to the padding edge.
481
+ - **`ds-password-rules` — the live requirement checklist under a new-password field.** One consumer had
482
+ written it twice (set-password and registration) and the two copies had already drifted: different labels
483
+ for the same rule, a different order, different state class names. Each rule carries its own `test`,
484
+ because the POLICY has to mirror the server and only the consumer knows it; the component owns the
485
+ tri-state glyph, the met/failed colours and the type scale. A rule that has not passed reads as PENDING
486
+ and only becomes a failure once `[showUnmet]` is true — bind that to "the user has tried to submit", or a
487
+ half-typed password scolds someone who is still typing. `[columns]="2"` for a checklist beside a wide
488
+ form, and `metCount` / `allMet` are exposed for a host gating its own submit — or import the standalone
489
+ `passwordRulesMet(value, rules)`, the same predicate that backs `allMet`, to gate a submit without
490
+ rendering the list at all. `[listId]` names the `<ul>` so a field's `aria-describedby` can point at it,
491
+ and `DsPasswordRule` (`{ label, test }`) and `DsPasswordRuleState` (`'pending' | 'met' | 'failed'`) are
492
+ exported for typing the rule set.
493
+ - **`ds-input` takes `ariaDescribedBy`, MERGED with its own message id.** Needed by the rule list above,
494
+ and by any policy note: setting `aria-describedby` on `<ds-input>` by hand lands on the wrapper, which no
495
+ screen reader reads, and replacing the attribute would have dropped the field's own hint/error
496
+ association. The input joins both ids instead.
497
+
498
+ - **`ds-table` persists the column layout and can render its own export button.** These were the last two
499
+ things keeping a consumer wrapper alive around the table: after 0.6.3/0.7.0 it owned every other feature
500
+ mm-broker forked it for, but the three column models were two-way with nothing storing them, so every
501
+ consumer wrote the same `localStorage` effect keyed by a screen id, and `exportCsv()` was a public method
502
+ with no affordance.
503
+ — `[persistLayout]="true"` + `storageKey` round-trip `columnOrder`, `columnWidths` and `hiddenKeys`
504
+ through `localStorage`. Both are required: without a key there is nothing to identify a screen by and two
505
+ tables would overwrite each other, so a missing key stores nothing rather than guessing. Only what was
506
+ actually saved is applied, so a table nobody has rearranged keeps its declaration order and `hidden`
507
+ flags.
508
+ — `[exportButton]="true"` renders the CSV button; `exportFilename` names the file and `exportFetcher`
509
+ covers the server-paged case — a table that only HAS the current page would otherwise export one page and
510
+ call it the export, so the button awaits the fetcher and disables itself while it runs. `exportCsv()`
511
+ stays public for a consumer’s own button and now takes an optional row set.
512
+ - **Focus-indicator style is a one-place switch: `<html data-focus="ring | field | edge | outline">`.**
513
+ The library shipped two fixed families — a soft halo on fields, a crisp double ring on controls — with no
514
+ way for a brand to choose. Since 20 components already resolve through `--ds-field-focus-shadow` /
515
+ `--ds-control-focus-shadow`, the switch simply retargets those roles: `ring` and `field` make both groups
516
+ match, `edge` is a hairline flush against the element, and `outline` swaps to a real `outline` — which a
517
+ box-shadow token cannot express, so that style also emits a zero-specificity `:where(:focus-visible)`
518
+ rule. Omit the attribute and today’s split is unchanged.
519
+ - **Focus survives Windows High Contrast.** Forced-colors mode DROPS `box-shadow`, so a shadow-only
520
+ indicator vanished entirely and a keyboard user in that mode had nothing to follow — a real a11y gap, now
521
+ closed once for every style with a `CanvasText` outline under `@media (forced-colors: active)`. A system
522
+ keyword rather than a brand colour, because forced-colors replaces the palette.
523
+ — Both the switch and this fallback live in the new `styles/_focus.scss`, forwarded into the bundled
524
+ `styles/ds` entry, so a consumer of that entry gets both automatically. A consumer who `@use`s DS
525
+ partials individually gets NEITHER until they add `@use 'styles/focus';`.
526
+ - **A role layer between the foundation scales and the components: radius, elevation and motion.** Reading
527
+ the raw scale directly meant a consumer could not re-round "panels" without also re-rounding every
528
+ control that shared `--radius-md`, could not lift every overlay without touching each surface, and could
529
+ not make panel entrances snappier without retuning each one. Every role defaults to the value its members
530
+ already used, so nothing moves until a role is set, and a per-component `--ds-<comp>-*` override still
531
+ wins over its role.
532
+ — **Radius:** `--ds-radius-inner` (the checkbox box, option rows, tags), `--ds-radius-control` (buttons,
533
+ field frames, picker triggers, tooltips), `--ds-radius-panel` (menus, popovers, cards, modals, drawers),
534
+ `--ds-radius-pill`. No `field` role: fields share `--radius-md` with buttons, so one would either
535
+ duplicate `control` or silently re-round every field — scope the role instead
536
+ (`ds-input { --ds-radius-control: 4px; }`).
537
+ — **Elevation:** `--ds-elevation-raised` / `-overlay` / `-floating` / `-modal`. Four, not the three first
538
+ sketched: the library genuinely uses four heights, and folding toast into `overlay` would have changed its
539
+ shadow. The older `--shadow-popover` / `-modal` / `-toast` / `-card` aliases now point AT the roles, so
540
+ either name works — a role moves every surface at that height, an alias retunes one family.
541
+ — **Motion:** `--ds-motion-enter-panel-*`, `-enter-surface-*`, `-enter-large-*`, `-exit-*`,
542
+ `-exit-large-*` (duration + easing each). Five roles, not four: panel LEAVES run at `--duration-base`,
543
+ not `fast`, so folding them into `exit` would have sped them up. `ds-loading-overlay` and the toast leave
544
+ stay on the raw scale — they use `--ease-standard`, which no role carries, and a role for two sites would
545
+ be worse than naming the value.
546
+ - **`ds-app-layout` restores the reader's scroll on the way BACK: opt-in `restoreScroll` +
547
+ `restoreScrollTimeout` (2000ms).** List → details → back returned the list to the top, because a real
548
+ back IS a path change and the layout resets on those. Off by default — a layout that silently moved the
549
+ scroll would surprise every existing consumer. Restores only when ARMED, which is the whole design: a
550
+ history traversal (back, forward, the mouse side button, `Alt+←`, an edge swipe — all arrive as
551
+ `popstate`), a host whose own "back to list" adds a history entry instead of traversing and says so with
552
+ `state: { dsRestoreScroll: true }`, or the first navigation after a reload. Following a link into a new
553
+ screen still lands at the top.
554
+ — The offset is remembered per PATH in `sessionStorage` (one namespaced blob, 20 entries, oldest first,
555
+ every access guarded — Safari private mode throws on write). Restoring waits for the content to grow via
556
+ `ResizeObserver` rather than counting frames, clamps to what the content allows at the deadline (a list
557
+ that loaded 8 of 40 rows still lands near the reader's row), and cancels on `wheel` / `touchstart` /
558
+ `keydown` — input events only, since our own restore writes emit `scroll`. It never touches
559
+ `history.scrollRestoration`, and it bails on a bfcache restore, which brings its own position back.
560
+ — `LayoutScrollService` gained `contentReady()` (optional: end the growth wait early when your data has
561
+ arrived) and `consumePendingOffset()` (take the offset and cancel the restore — for a virtualizer, which
562
+ needs it BEFORE deciding which rows to build).
563
+ — **Interaction worth knowing:** an app that scrolls on navigation itself — a docs shell whose URL names a
564
+ section, an anchor jump — writes after the layout does and therefore wins. That is the right precedence,
565
+ and it means `restoreScroll` is a no-op on those routes rather than a fight.
566
+ - **`ds-button` type and box hooks: `--ds-button-font-size` / `-weight` / `-tracking` / `-height` /
567
+ `-pad-x` / `-pad-y`, plus `data-variant` / `data-color` reflected on the host.** The label type and the
568
+ box were hard-coded, and the size class pinned `height` and `padding`, so a brand wanting 14px/600
569
+ buttons sized by their own padding had to write `.button.button.button { … }` to out-rank the shimmed
570
+ `.button.md` (0,3,0). The hooks follow the read-never-declare rule the colour resolvers already use, and
571
+ each size class re-resolves them with the hook still first — so `--ds-button-height` beats the size it
572
+ would otherwise pick instead of being undone by it. The reflected attributes let a consumer target one
573
+ axis from outside (`ds-button[data-variant="outline"] { --ds-button-border: white; }`) without reaching
574
+ for the `c-*` / `v-*` classes, which sit on the inner `<button>` and are not addressable from a
575
+ host-scoped rule.
576
+ - **`--ds-field-height` — one control-box height for the field family, and the `--field-h-*` scale is
577
+ finally the knob its name advertises.** `--field-h-sm`/`-md`/`-lg` have shipped as the field height
578
+ scale for as long as the token file has existed, but only `-lg` was ever read: `ds-input`, `ds-select`,
579
+ `ds-date-picker` and `ds-time-picker` all spelled the other two out as the raw `var(--hit-min)` /
580
+ `var(--hit-cozy)`. Retuning `--field-h-md` therefore changed nothing — a lever that looked live and was
581
+ not. All four now resolve through the scale (identical values, so nothing moves), and
582
+ `--ds-field-height` overrides the resolved size for a consumer who wants one height regardless of
583
+ `size`; scope it per component the usual way (`ds-select { --ds-field-height: 44px; }`).
584
+ - **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`
585
+ had hooks, so a form mixing a select with an input rendered labels in two sizes and colours out of the
586
+ box, and retuning them from an app needed `.field.field .label.label, .select-label.select-label` to
587
+ out-rank the shimmed component rule. `input`, `textarea`, `select`, `date-picker`, `time-picker` and
588
+ `radio-group` now resolve through one mixin and one token set. No per-component token set is needed —
589
+ custom-property scoping already narrows a retune to one component
590
+ (`ds-select { --ds-field-label-transform: uppercase; }`), and `-transform`/`-tracking` make the
591
+ uppercase tracked editorial label reachable through tokens for the first time. `ds-input`’s older
592
+ `--ds-input-label-color`/`-fs`/`-fw` still win where set, and now fall through to the family token
593
+ instead of straight to the raw scale.
594
+ - **Every field takes `error` and `warning` beside `hint`, and shows exactly one of them.** Until now a
595
+ field had one message input, so a consumer had to multiplex it by hand —
596
+ `[invalid]="showError()" [hint]="showError() ? errorText() : helperText()"` — on every screen that
597
+ validates, and the two bindings could silently disagree. The four sources now resolve on a fixed
598
+ ladder, highest first: `error` (an explicit string — shown at once, because binding it says you have
599
+ already decided), then validation errors, then `warning`, then `hint`. Only ONE line ever renders, so
600
+ a field's height does not depend on how many sources are populated — the same rule Carbon
601
+ (`invalidText` → `warnText` → `helperText`) and Material's subscript follow. `ds-field-message` gained
602
+ a matching `warning` state coloured from `--warning-text`.
603
+ - **Fields read validation state from the form control, so `error` is optional.** Both Angular form
604
+ systems are supported at once and neither needs the other. Signal forms binds `errors` and `touched`
605
+ straight in — those input names are Angular 21's `FormUiControl` contract, and the `Field` directive
606
+ already drives the value through the `ControlValueAccessor` the fields have always implemented.
607
+ Reactive and template-driven forms need nothing at all: the field resolves `NgControl` after first
608
+ render (it cannot be injected directly — a field provides `NG_VALUE_ACCESSOR` pointing at itself, so
609
+ asking for `NgControl` in the same constructor is a DI cycle) and subscribes to `control.events`,
610
+ which is what reports touching — `statusChanges` does not. Errors wait for the first blur, or for the
611
+ parent form to be submitted, so a `required` error never greets an untouched form. `invalid` no longer
612
+ has to be kept in sync by hand: it is now OR-ed with what the control reports, and the explicit input
613
+ still wins.
614
+ - **`DS_CONFIG.field.errorMessages` — one shared map from error kind to text.** A message on the error
615
+ itself always wins (`required(path, { message: … })` in signal forms, or `{ myError: 'text' }` from a
616
+ plain validator), so this is the fallback for Angular's built-ins, which carry detail objects and no
617
+ wording. Declare it once in `provideDsConfig` and a consumer writes no text at all for `required`,
618
+ `minlength` or `email`. An error that resolves to no text anywhere warns in dev rather than rendering
619
+ an error style with an empty line.
620
+
621
+ ### Changed
622
+
623
+ - **`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.
624
+
625
+ - **A `ds-menu` row's hover fill is square and runs edge to edge.** The row carried `--radius-md`, the
626
+ same 8px the standalone menu panel uses, while sitting flush inside it — and inside a `ds-popover`,
627
+ which drops its padding for a menu, that 8px sat against the popover's 12px corner and left visible
628
+ slivers at the top and bottom of the list. A curve at zero inset can never be concentric with the
629
+ panel's, so the row is now square and the panel clips it: `ds-menu` drops its own `padding` and gains
630
+ `overflow: hidden`, which is what rounds the first and last row. To keep the old rounded highlight,
631
+ set the new hook — `ds-menu { --ds-menu-item-radius: var(--radius-md); }` — and note the panel no
632
+ longer insets the rows, so a radius there reads best with a padding of your own.
633
+ - **`ds-radio-group`’s label now looks like every other field label.** It was the one component drawing
634
+ its own type (`medium` weight at `--font-size-s` on `--line-height-flat`) rather than the family’s
635
+ `bold`/`--font-size-xs`; in a form beside an input or a select it read as a different kind of thing.
636
+ 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); }`.
637
+ - **Fields no longer expose a `protected messageState`;** the resolved `message` (text + state) and
638
+ `invalidResolved` replace it. Only reachable by subclassing a field component, which is not a
639
+ supported extension point, but noted for parity with the class-member changes in 0.7.0.
640
+
641
+ ### Fixed
642
+
643
+ - **Two leftover `--combobox-*` tokens renamed to `--picker-*`.** `--combobox-offset` and
644
+ `--combobox-maxh` size the listbox panel shared by `ds-autocomplete` and `ds-multi-select`, and survived the
645
+ `ds-combobox` → `ds-autocomplete` rename carrying the name of a component that no longer exists. Now
646
+ `--picker-offset` / `--picker-maxh`. These are global scale tokens rather than `--ds-*` component tokens, so
647
+ the blast radius is anyone who happened to override them — rename the override. The docs also now state the
648
+ autocomplete-vs-multi-select boundary in both sections: the LIST decides, not the count — typing is how you
649
+ narrow a set too large to scan, while a checkbox list shows the whole choice and what is NOT selected.
650
+ - **A `required` `ds-time-picker` in `mode="range"` never announced as required.** `aria-required` was on the
651
+ single-mode trigger only, so a screen-reader user on a range field was not told either segment was
652
+ mandatory. Both segments now carry it. (Their accessible NAME was already correct — each announces the
653
+ field's own label plus "(from)" / "(to)" — and the docs gained a labelled, required range demo, whose
654
+ absence is why the gap went unnoticed.)
655
+ - **`ds-table`: with `stickyHeader` and `stickyFirstColumn` together, the first body row painted OVER the
656
+ header.** `--table-sticky-corner-z` exists so the corner where both sticky axes meet sits above the body's
657
+ pinned cells, but the sticky-header rule out-specified it, leaving the pinned header cells at the same
658
+ z-index as the pinned body cells — and on a tie DOM order wins, so the body won. The header row read as
659
+ the first row's data in the pinned columns. Found while building virtual scroll, and it was never specific
660
+ to it: any tall table with both flags had it. The sticky-header rule now leaves the pinned cells' z-index
661
+ to the corner token.
662
+ - **`ng add` never ran its schematic — in any released version.** The package is `"type": "module"` while
663
+ the compiled schematic is CommonJS, so Node refused to load it (`exports is not defined in ES module
664
+ scope`) and the DS global styles were never wired automatically; every consumer either added the `@use`
665
+ line by hand or shipped without the styles. The build already wrote a nested
666
+ `schematics/package.json` with `{"type":"commonjs"}` to fix exactly this, and **`npm pack` silently drops
667
+ it** — npm treats a directory holding a `package.json` as a separate package root — so the marker existed
668
+ in `dist/` and was absent from the tarball. The schematic is now authored as `.cts` and ships as `.cjs`,
669
+ which survives packing, and the build fails loudly if that emit is missing.
670
+ - **`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.
671
+ - **`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.
672
+ - **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.
673
+ - **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.
674
+ - **A nested `ds-app-layout` could paint its rail OVER the outer shell's.** The rail sits at
675
+ `--layer-drawer` and its scrim one below; `position: relative` alone still left every layout resolving
676
+ that layer in the one root stacking context, so an inner layout's rail could stack above an outer
677
+ layout's open rail instead of beneath it. The host now sets `isolation: isolate`, giving each
678
+ `ds-app-layout` its own stacking context — the same fix `ds-drawer` already carries. Nothing changes
679
+ for a full-viewport shell with no layout embedded inside it.
680
+ - **The `ds-time-picker` panel drew the CONTROL radius, so it did not match the date picker beside it.**
681
+ Its dropdown was the one floating panel left on `--radius-md` (8px) while every other surface — menus,
682
+ popovers, cards, modals, and `ds-date-picker`'s own calendar — resolves the panel role. Two pickers in
683
+ one form therefore rendered different corners. The panel now reads
684
+ `var(--ds-time-picker-panel-radius, var(--ds-radius-panel))`, which is 12px, and the new hook is
685
+ FORWARDED onto the portaled pane — a token declared without being forwarded is dead for per-instance
686
+ overrides, which is exactly the `--ds-overlay-enter-scale` bug fixed elsewhere in this release. It was
687
+ also the only property on that element without a hook, since fill, border and shadow all had one.
688
+ Restore the old corner with `ds-time-picker { --ds-time-picker-panel-radius: var(--radius-md); }`; the
689
+ trigger's radius is untouched.
690
+ - **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.
691
+ - **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.
692
+ - **A closed compact `ds-app-layout` rail no longer holds focus, or 112 tab stops, behind the screen.**
693
+ Below the breakpoint the rail is translated off-canvas, which hides it visually and not at all from
694
+ assistive tech: it kept `role="dialog"` + `aria-modal="true"`, every nav link stayed tabbable, and the
695
+ caret stayed inside the hidden panel after Escape or a scrim click — `cdkTrapFocusAutoCapture` hands
696
+ focus back only when the directive is DESTROYED, not when it flips off — so the next Tab continued from
697
+ invisible navigation with no visible focus ring. The closed overlay rail is now `inert`, and closing it
698
+ returns focus to whatever control claims the rail through `aria-controls`, which both `dsRailTrigger`
699
+ and the DS-button forwarding (`[ariaControls]="shell.railId"`) already set. Verified in Chrome at 604px.
700
+ At/above the breakpoint nothing changes — the rail stays in the layout and interactive.
701
+
702
+ - **`--ds-overlay-enter-scale` now reaches the portaled panel, so `ds-scale-in` can be retuned per
703
+ instance.** The token was declared and resolved on the pane but missing from the set
704
+ `prepareOverlayEnter()` forwards, so `ds-select { --ds-overlay-enter-scale: 0.9; }` did nothing while
705
+ the other four enter tokens worked — 0.7.1 shipped it as a known gap. Covers every overlay panel
706
+ (select, multi-select, autocomplete, date / time / colour picker, popover, tooltip, menu submenus). A
707
+ global override always worked and is unaffected.
708
+
11
709
  ## 0.7.1 — 2026-08-04
12
710
 
13
711
  ### Added
@@ -31,8 +729,8 @@ While the package is on `0.x`, minor releases may contain breaking changes.
31
729
 
32
730
  - **`ds-app-layout` collapses its rail to an off-canvas overlay below `lg`.** On narrow viewports the
33
731
  rail no longer occupies a grid column: below the `lg` breakpoint (read at runtime from `--bp-lg`) it
34
- leaves the flow, becomes a `position: fixed` panel translated off-canvas, and
35
- animates in over a scrim. A new two-way `[(railOpen)]` model drives it (ignored at/above `lg`), and a
732
+ leaves the flow, becomes a `position: fixed` panel translated off-canvas, and animates in over a
733
+ scrim. A new two-way `[(railOpen)]` model drives it (ignored at/above `lg`), and a
36
734
  new `railLabel` input (`'Navigation'` by default) sets the panel's `aria-label` in compact mode. While
37
735
  open and compact the panel is a focus-trapped `role="dialog"` with `aria-modal="true"`; clicking the
38
736
  scrim, pressing `Escape` anywhere, navigating to a new path, or crossing back above `lg` all close it
@@ -136,8 +834,8 @@ While the package is on `0.x`, minor releases may contain breaking changes.
136
834
  ds-fade-in; }` is enough to re-skin one instance, and portaled panels forward the tokens onto their
137
835
  overlay pane on open — every one except `--ds-overlay-enter-scale`, which is not forwarded, so scaling
138
836
  one overlay panel per instance does not work yet (scope it globally instead). Your own `@keyframes` work
139
- too, but must be declared in GLOBAL styles: emulated
140
- view encapsulation renames keyframes defined in a component stylesheet. `none` disables an entrance.
837
+ too, but must be declared in GLOBAL styles: emulated view encapsulation renames keyframes defined in a
838
+ component stylesheet. `none` disables an entrance.
141
839
  All defaults are unchanged. Leave keyframes are deliberately not swappable — modal/drawer/bottom-sheet
142
840
  teardown matches them by name — and reduced motion still wins: the library zeroes the duration itself,
143
841
  so a custom entrance carrying its own timing is silenced too. New: `src/lib/styles/_surface-motion.scss`