@ids-group-ltd/ids-design-system 0.11.0 → 0.11.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (50) hide show
  1. package/CHANGELOG.md +1368 -1021
  2. package/components.md +49 -26
  3. package/design-system.md +18 -18
  4. package/fesm2022/ids-group-ltd-ids-design-system.mjs +1750 -598
  5. package/fesm2022/ids-group-ltd-ids-design-system.mjs.map +1 -1
  6. package/migrations/0.10.0.json +19 -19
  7. package/migrations/0.10.1.json +20 -7
  8. package/migrations/0.10.2.json +8 -8
  9. package/migrations/0.10.3.json +2 -2
  10. package/migrations/0.11.0.json +9 -54
  11. package/migrations/0.11.1.json +279 -0
  12. package/migrations/0.11.2.json +158 -0
  13. package/migrations/0.2.0.json +17 -5
  14. package/migrations/0.2.2.json +1 -1
  15. package/migrations/0.3.0.json +1 -1
  16. package/migrations/0.4.0.json +1 -1
  17. package/migrations/0.5.1/badge-statuses.md +1 -3
  18. package/migrations/0.5.1.json +1 -1
  19. package/migrations/0.6.3.json +1 -1
  20. package/migrations/0.7.1.json +6 -6
  21. package/migrations/0.8.0.json +5 -5
  22. package/migrations/0.9.0.json +12 -11
  23. package/migrations/0.9.1.json +2 -2
  24. package/migrations/README.md +34 -52
  25. package/package.json +1 -1
  26. package/styles/_dropdown-overlay.scss +64 -23
  27. package/styles/_ds-color.scss +3 -3
  28. package/styles/_field-box.scss +2 -6
  29. package/styles/_field-label.scss +5 -10
  30. package/styles/_field-state.scss +3 -2
  31. package/styles/_focus.scss +0 -2
  32. package/styles/_layout-utils.scss +2 -2
  33. package/styles/_overlay-motion.scss +2 -3
  34. package/styles/_press.scss +3 -5
  35. package/styles/_reset.scss +0 -1
  36. package/styles/_scrollbar.scss +1 -3
  37. package/styles/_status.scss +1 -2
  38. package/styles/_surface-motion.scss +3 -4
  39. package/styles/_text-clip.scss +1 -1
  40. package/styles/_theme-activation.scss +1 -1
  41. package/styles/_tokens-charts.scss +1 -3
  42. package/styles/_tokens.scss +5 -4
  43. package/styles/_typography.scss +2 -2
  44. package/themes/README.md +6 -6
  45. package/themes/_base-palette.scss +2 -2
  46. package/themes/_semantic.scss +2 -2
  47. package/themes/dark/_palette.scss +1 -2
  48. package/themes/light/_palette.scss +1 -1
  49. package/themes/light/_theme.scss +1 -1
  50. package/types/ids-group-ltd-ids-design-system.d.ts +608 -72
@@ -8,7 +8,7 @@
8
8
  "new": "sortMode",
9
9
  "action": "`[clientSort]=\"true\"` and a bare `clientSort` become `sortMode=\"client\"`; `[clientSort]=\"false\"` or `[clientSort]=\"expr\"` becomes `[sortMode]=\"expr ? 'client' : 'server'\"`. A table that had NO clientSort binding and reorders in its own `(sortChange)` handler must declare `sortMode=\"server\"`. A table that renders a sortable column but sorts nowhere declares `sortMode=\"none\"`, which drops the button, the caret and `aria-sort` instead of leaving a dead control. TypeScript callers can type the value with `import type { TableSortMode }`.",
10
10
  "pitfall": "The last case is the one that is not a find/replace, because the DEFAULT CHANGED: unset resolves to `client` at this version. A server-paged table that only emitted `sortChange` will now ALSO sort its own rows — and client sorting reorders the current page only, so the rows look sorted and are not. Dev builds warn on `total` plus client, but a production build says nothing.",
11
- "note": "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. mm-broker shipped several detail tables that way and caught it only in a browser walkthrough.",
11
+ "note": "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.",
12
12
  "searchHints": [
13
13
  "clientSort",
14
14
  "[clientSort]",
@@ -29,7 +29,7 @@
29
29
  "new": null,
30
30
  "action": "Build after upgrading — the compiler enumerates every collision. Per member: rename your own, or add `override` where the base semantics genuinely match. A subclass that overrode `messageState` should move its logic to an `error` or `warning` binding on the element instead, since the message is resolved centrally now.",
31
31
  "appliesWhen": "Only a consumer that EXTENDS a DS component class. Subclassing is unsupported (design-system.md § Components); template users of the `<ds-…>` elements need nothing.",
32
- "pitfall": "A PRIVATE member collides too — TS2415 — and `TableComponent.saveLayout()` is the one that actually bit a consumer whose own table happened to declare the same name. Two more shapes hide here: this release REMOVES members as well as adding them (the fourteen fields dropped protected `messageState`, DatePicker also `messageText`, and Checkbox, Switch and Radio dropped protected `devMode`), so an `override` can start naming nothing; and `close()` gained an optional `cause`, which an override declared as `close()` still satisfies — only a subclass that re-declares the parameter list differently breaks.",
32
+ "pitfall": "A PRIVATE member collides too — TS2415 — and `TableComponent.saveLayout()` is the likeliest to collide, because a table wrapper commonly declares the same name. Two more shapes hide here: this release REMOVES members as well as adding them (the fourteen fields dropped protected `messageState`, DatePicker also `messageText`, and Checkbox, Switch and Radio dropped protected `devMode`), so an `override` can start naming nothing; and `close()` gained an optional `cause`, which an override declared as `close()` still satisfies — only a subclass that re-declares the parameter list differently breaks.",
33
33
  "note": "Additions: the fourteen field classes gained the `error`, `warning`, `errors` and `touched` inputs plus protected `message` and `invalidResolved`; both CVA bases gained protected `touchedSelf`; AppLayoutComponent gained `railOverlay` and `railId`; TableComponent lost `clientSort` and gained `sortModeResolved`, `sortableCol()`, `exporting`, `runExport()`, `virtualizing`, `virtualRowHeight`, `virtualWindow`, `windowData`, `isStriped()`, the `persistLayout`, `storageKey`, `exportButton`, `exportFilename`, `exportFetcher`, `virtualScroll` and `virtualRowSize` inputs and the private `saveLayout()` / `restoreLayout()`; ButtonComponent gained `ariaControls`; IconButtonComponent `ariaExpanded` and `ariaControls`; LayoutScrollService `scroller`, `scrollTo()`, `configureRestore()`, `consumePendingOffset()` and `contentReady()`.",
34
34
  "searchHints": [
35
35
  "extends InputComponent",
@@ -230,13 +230,13 @@
230
230
  "ds-table gained [persistLayout] + storageKey (round-tripping columnOrder, columnWidths and hiddenKeys through localStorage) and [exportButton] + exportFilename + exportFetcher. All opt-in and off by default, so NO ACTION. A consumer who wrote their own localStorage effect for the three column models, or their own export button, can delete both - together with the sortValue accessor these were the last three reasons to keep a wrapper around ds-table. exportCsv() is unchanged for existing callers and now accepts an optional row set as its second argument.",
231
231
  "New component ds-password-rules: the live requirement checklist under a new-password field. Purely additive, NO ACTION. A consumer with a hand-rolled password checklist can replace it - pass the rule set as { label, test } pairs (the policy stays yours, it has to mirror your server), bind [value] to the field and [showUnmet] to whether the user has tried to submit. Exposes metCount and allMet for gating a submit button, and the standalone passwordRulesMet(value, rules) function — the same predicate that backs allMet — for gating one without rendering the list. Also exported: the DsPasswordRule ({ label, test }) and DsPasswordRuleState ('pending' | 'met' | 'failed') types for typing the rule set, plus a listId input that names the <ul> so a field's aria-describedby can point at the checklist.",
232
232
  "ds-input gained ariaDescribedBy, merged with the field's own message id rather than replacing it - for describing a field with a password-rule list or a policy note. Additive, NO ACTION. Note that setting aria-describedby on the <ds-input> element itself does NOT work: it lands on the wrapper, not the inner input.",
233
- "New component ds-auth-shell: the scaffold for the screens in front of the login (sign-in, forgot password, reset, MFA), counterpart to ds-app-layout. Purely additive, NO ACTION. A consumer with a hand-rolled auth scaffold can replace it: brand lockup + optional tagline + one card holding the form + a support line. The brand row is the ds-sidenav row - same brand / logoLetter / [dsBrandName] contract and the same letter-mark tile - so it is NOT the string-splitting brandAccent the ports used; project [dsBrandName] to tint a slice of the wordmark. Card body is the default slot, the support line goes in [dsAuthSupport] (a real <footer>, so it carries the contentinfo landmark). cardElevation / cardPadding pass through to ds-card. Tokens: --ds-auth-shell-min-height, -card-max-width, -gap, -bg-color, -mark-bg-color, -mark-label-color. WORTH KNOWING when porting: the shell owns the full-height box itself, so do NOT wrap it in your own 100vh/100dvh container - the ports that stacked two scrolled a page whose content fits. It also adds env(safe-area-inset-*) padding, and centres with auto margins rather than centre alignment so a form taller than the box stays reachable when the shell is embedded at min-height 100%.",
233
+ "New component ds-auth-shell: the scaffold for the screens in front of the login (sign-in, forgot password, reset, MFA), counterpart to ds-app-layout. Purely additive, NO ACTION. A consumer with a hand-rolled auth scaffold can replace it: brand lockup + optional tagline + one card holding the form + a support line. The brand row is the ds-sidenav row - same brand / logoLetter / [dsBrandName] contract and the same letter-mark tile - so it is NOT a string-splitting brandAccent; project [dsBrandName] to tint a slice of the wordmark. Card body is the default slot, the support line goes in [dsAuthSupport] (a real <footer>, so it carries the contentinfo landmark). cardElevation / cardPadding pass through to ds-card. Tokens: --ds-auth-shell-min-height, -card-max-width, -gap, -bg-color, -mark-bg-color, -mark-label-color. WORTH KNOWING when porting: the shell owns the full-height box itself, so do NOT wrap it in your own 100vh/100dvh container - nesting two of them scrolls a page whose content fits. It also adds env(safe-area-inset-*) padding, and centres with auto margins rather than centre alignment so a form taller than the box stays reachable when the shell is embedded at min-height 100%.",
234
234
  "New component ds-filter-bar: a Priority+ filter row - as many filters as fit inline, the rest behind a \"+N more\" panel. Purely additive, NO ACTION. A consumer with a hand-rolled filter row (or one that wraps to two lines on a laptop) can replace it. Each filter goes in an <ng-template [dsFilterItem]=\"180\"> carrying the width it should occupy; the bar decides the split from those numbers plus a ResizeObserver on the row. Trailing controls (search, Clear) carry the dsFilterBarTrailing attribute - mark each control, do NOT wrap them in a div: the bar owns that group's gap and alignment, and a projected wrapper is a plain block whose children stack. Tokens: --ds-filter-bar-gap, --ds-filter-bar-panel-gap. Inputs moreLabel and panelLabel exist for translation. WORTH KNOWING: the declared width is a contract, not a hint - the slot is sized to exactly that number, so declare what the control actually occupies. And because a filter that collapses is MOVED into the panel, its view is destroyed and re-created: internal state such as an open dropdown or focus does not survive that, while its value does (it lives in your signal or form control). Content that reaches the bar with neither slot marker is dropped, with a dev-mode console warning.",
235
- "ds-table gained virtual scrolling: [virtualScroll]=\"true\" plus virtualRowSize (px). Opt-in and off by default, so NO ACTION. Only the rows in view stay in the DOM (~25 regardless of row count), padded by two spacer rows so the scrollbar still spans the whole data set. REQUIRES maxHeight - a bounded scroller is the viewport it windows against, and without one nothing is virtualized (dev warning). CONSTRAINTS in virtual mode, all enforced rather than assumed: every row is exactly virtualRowSize tall (the CSS height comes from that same input), table-layout becomes fixed, and cells are kept to one line - so declare column widths, and do not rely on wrapping cell text there. Row EXPANSION is suppressed with a dev warning (an expanded row is taller than virtualRowSize and every offset below it would be wrong); pageSize alongside virtualScroll is also warned about, since virtual scrolling is what pagination was for. Sorting, filtering, selection, sticky header, sticky first column and column resizing all keep working. NOT built on the CDK virtual-scroll viewport on purpose: that wraps the table in a transformed content wrapper, and the transform breaks this table's sticky header and sticky first column. STILL OPEN: lazy loading (fetching slices from a server as they scroll into view) is NOT part of this - see the backlog item.",
235
+ "ds-table gained virtual scrolling: [virtualScroll]=\"true\" plus virtualRowSize (px). Opt-in and off by default, so NO ACTION. Only the rows in view stay in the DOM (~25 regardless of row count), padded by two spacer rows so the scrollbar still spans the whole data set. REQUIRES maxHeight - a bounded scroller is the viewport it windows against, and without one nothing is virtualized (dev warning). CONSTRAINTS in virtual mode, all enforced rather than assumed: every row is exactly virtualRowSize tall (the CSS height comes from that same input), table-layout becomes fixed, and cells are kept to one line - so declare column widths, and do not rely on wrapping cell text there. Row EXPANSION is suppressed with a dev warning (an expanded row is taller than virtualRowSize and every offset below it would be wrong); pageSize alongside virtualScroll is also warned about, since virtual scrolling is what pagination was for. Sorting, filtering, selection, sticky header, sticky first column and column resizing all keep working. NOT built on the CDK virtual-scroll viewport on purpose: that wraps the table in a transformed content wrapper, and the transform breaks this table's sticky header and sticky first column. STILL OPEN: lazy loading (fetching slices from a server as they scroll into view) is NOT part of this.",
236
236
  "FIXED in ds-table: with stickyHeader and stickyFirstColumn both on, the first body row painted OVER the header in the pinned columns, so the header read as that row's data. --table-sticky-corner-z was already there to keep the corner above the body, but the sticky-header rule out-specified it and both ended up at the same z-index, where DOM order puts the body on top. No action needed - it is a pure CSS fix. If you worked around it with your own z-index on DS table cells, that override can go. (delete list: table-sticky-corner-zindex-workaround)",
237
237
  "ds-checkbox / ds-switch / ds-radio now RENDER a projected caption instead of dropping it, and expose the caption's colour and size. Additive, NO ACTION - [label] stays the documented API and still wins when both are supplied. If you added a dev-warning workaround after 0.7.1 (moving markup-bearing captions into a string), you can move them back: <ds-checkbox>I accept the <a href=...>Terms</a></ds-checkbox> now works. ONE DIFFERENCE: the required asterisk comes with [label] only - a projected caption owns its own marker, since only your markup knows where it belongs. New hooks: --ds-checkbox-label-color / -label-font-size, the same pair on ds-switch, and --ds-radio-label-font-size (--ds-radio-label-color already shipped). The font-size hook beats the size class. These are deliberately NOT part of the --ds-field-label-* contract: a label above an input is a heading for the field and reads secondary, a caption beside a checkbox is the content being agreed to and reads primary. If you were overriding the caption colour with a descendant selector against .control-text, replace it with the token.",
238
238
  "Overlay panels now fade out when DISMISSED and still close instantly when something is CHOSEN. No action - behaviour only. Escape, a press outside, or the page scrolling away fades the panel over --ds-motion-exit-duration (120ms); picking an option, pressing the trigger again, or Tab still closes instantly, because a fade on a deliberate choice reads as the panel lagging behind it. Applies to select, autocomplete, multi-select, date-picker, time-picker, color-picker and popover. Tune with --ds-overlay-leave-duration / --ds-overlay-leave-easing, or set the duration to 0ms to get the old always-instant close everywhere. Reduced motion already zeroes it. A fading panel is pointer-events: none, so it cannot swallow a click aimed at what is behind it. If you built anything that assumed the overlay pane is removed from the DOM synchronously on Escape, note that it now lives for one exit duration longer (the component state - open(), overlayRef - is still cleared immediately).",
239
- "design-system.md now states the --ds-* token contract once instead of repeating it per component, and carries a warning that its hand-written API and token lists have drifted from the code (ds-button is documented with its pre-color/variant API and the pre-rename --ds-button-bg / -fg names). For the authoritative surface use the auto-generated Component API tables and token reference in ds-docs, which are extracted from source on every build. No action - documentation only."
239
+ "design-system.md now states the --ds-* token contract once instead of repeating it per component, and carries a warning that its hand-written API and token lists have drifted from the code (ds-button is documented with its pre-color/variant API and the pre-rename --ds-button-bg / -fg names). For the authoritative surface use the Component API tables and token reference on the documentation site, generated from the source of each release. No action - documentation only."
240
240
  ],
241
241
  "deleteList": [
242
242
  {
@@ -89,6 +89,7 @@
89
89
  "searchHints": [
90
90
  "ds-search",
91
91
  "--ds-search-height",
92
+ "--hit-min",
92
93
  "--search-h"
93
94
  ],
94
95
  "surface": "style",
@@ -191,10 +192,10 @@
191
192
  "kind": "behavior",
192
193
  "old": "extends TableComponent",
193
194
  "new": null,
194
- "action": "Run `npm run class-surface v0.8.0 v0.9.0` for the authoritative list, then per member: rename your own, or add `override` where the base semantics genuinely match. Build after upgrading — the compiler enumerates every collision.",
195
- "appliesWhen": "Only a consumer that EXTENDS a DS component class. Subclassing is unsupported (design-system.md § Components); template users need nothing. This is not hypothetical: migrating to 0.8.0, one consumer's ids-data-table failed on exactly three.",
196
- "pitfall": "Two things the compiler will NOT tell you. `isStriped()` keeps its signature but now takes an ABSOLUTE row index rather than a window-relative one, so a subclass that overrode it silently computes the wrong row. And `distinctValuesOf()` was replaced by `optionsFor()` — a subclass that CALLED the old name loses it silently at the call site while only the declaration errors. Also note both CVA bases gained a `focus()` inherited by every field control, so a subclass with its own needs `override`, and four new exported symbols can shadow a local name: FieldGroupComponent, DS_FIELD_GROUP, HeaderFilterDirective, HeaderFilterContext.",
197
- "note": "TableComponent changed by far the most; ModalComponent, ModalCardComponent, InputComponent, TextareaComponent, SelectComponent, AutocompleteComponent, BreadcrumbsComponent, MenuItemComponent, AppLayoutComponent, AuthLayoutComponent, TabsComponent, LayoutScrollService and both CVA bases also moved. TS4114 demands `override`, TS2415 fires on a redeclared private, TS2416 on a differing signature.",
195
+ "action": "Build after upgrading: the compiler raises most of these collisions, but NOT the ones named in `pitfall` below — check those by hand, because they compile clean. Then per member: rename your own, or add `override` where the base semantics genuinely match.",
196
+ "appliesWhen": "Only a consumer that EXTENDS a DS component class. Subclassing is unsupported (design-system.md § Components); template users need nothing.",
197
+ "pitfall": "Two things the compiler will NOT tell you. `isStriped()` keeps its signature but now takes an ABSOLUTE row index rather than a window-relative one, so a subclass that overrode it silently computes the wrong row. And `distinctValuesOf()` was replaced by `optionsFor()` — a subclass that CALLED the old name loses it silently at the call site while only the declaration errors. Also note both CVA bases gained a `focus()` inherited by every field control, so a subclass with its own needs `override`, and five new exported symbols can shadow a local name: AuthLayoutComponent, FieldGroupComponent, DS_FIELD_GROUP, HeaderFilterDirective, HeaderFilterContext — none of these existed at 0.8.0, so they are new exports rather than grown classes.",
198
+ "note": "Seventeen classes grew a member. TableComponent changed by far the most; ModalComponent, ModalCardComponent, InputComponent, TextareaComponent, SelectComponent, AutocompleteComponent, BreadcrumbsComponent, MenuItemComponent, ButtonComponent, DatePickerComponent, SearchComponent (the last three gained `inGroup`), AppLayoutComponent, TabsComponent, LayoutScrollService and both CVA bases also moved. TS4114 demands `override`, TS2415 fires on a redeclared private, TS2416 on a differing signature.",
198
199
  "searchHints": [
199
200
  "extends TableComponent",
200
201
  "extends InputComponent",
@@ -252,11 +253,11 @@
252
253
  }
253
254
  ],
254
255
  "informational": [
255
- "--ds-radius-inner now actually reaches the small affordances. 33 reads across fifteen component stylesheets took var(--radius-sm) directly - dropdown options, field clear buttons, calendar days, chips, tag and toast close buttons - so the role a consumer is told to retune reached exactly one component. They resolve the role now, and its default IS --radius-sm, so NOTHING MOVES: verified by measuring a component page before and after, identical surfaces at identical radii. NO ACTION, but it changes what a square brand costs you: zeroing the three roles used to leave five surfaces rounded and now leaves one. Two deliberate exclusions - five focus-ring radii inside :focus-visible keep following the raw scale (a ring traces a box, it is not a brand surface), and the shared dropdown panel behind ds-select / ds-multi-select still reads --radius-md (8px) where every other panel resolves --ds-radius-panel (12px). That last one is a tracked inconsistency, not a hook: squaring it needs the scale. Worked example on the Theming page.",
256
- "A 32px toolbar is `density=\"compact\"`, not a per-control height pin. Measured on a nine-control row: search, input, select, autocomplete, date-picker, time-picker, multi-select, number-stepper and button are all 40px by default and all 32px under [data-density=\"compact\"] on the container. DELETE-LIST MATERIAL: if you pin --ds-search-height (or any sibling) to get a shorter row - one consumer pins --hit-min and its comment complains that md used to be 36px - that pin can go, and after the height contract it was fighting the family rather than joining it. Known limit at the bottom of the scale: ds-multi-select and ds-autocomplete hold chips, so they set a min-height rather than a height and stop following the floor once it drops below what the text needs - under ultra-compact they are 33px and 29px where the rest reach 24px, because a density tier scales padding and hit targets but not the type scale. Compact is unaffected in practice (33 against 32). Documented on the Density page. (delete list: search-height-pinned-for-a-short-row)",
256
+ "--ds-radius-inner now actually reaches the small affordances. 33 reads across fifteen component stylesheets took var(--radius-sm) directly - dropdown options, field clear buttons, calendar days, chips, tag and toast close buttons - so the role a consumer is told to retune reached exactly one component. They resolve the role now, and its default IS --radius-sm, so NOTHING MOVES. NO ACTION, but it changes what a square brand costs you: zeroing the three roles used to leave five surfaces rounded and now leaves one. Two deliberate exclusions - five focus-ring radii inside :focus-visible keep following the raw scale (a ring traces a box, it is not a brand surface), and the shared dropdown panel behind ds-select / ds-multi-select still reads --radius-md (8px) where every other panel resolves --ds-radius-panel (12px). That last one is a known inconsistency, not a hook: squaring it needs the scale. Worked example on the Theming page.",
257
+ "A 32px toolbar is `density=\"compact\"`, not a per-control height pin. Measured on a nine-control row: search, input, select, autocomplete, date-picker, time-picker, multi-select, number-stepper and button are all 40px by default and all 32px under [data-density=\"compact\"] on the container. DELETE-LIST MATERIAL: if you pin --ds-search-height, or reach past it to --hit-min, to get a shorter row - that pin can go, and after the height contract it was fighting the family rather than joining it. `--hit-min` is also a legitimate density knob, so discard hits where it is set deliberately rather than to shorten a search row. Known limit at the bottom of the scale: ds-multi-select and ds-autocomplete hold chips, so they set a min-height rather than a height and stop following the floor once it drops below what the text needs - under ultra-compact they are 33px and 29px where the rest reach 24px, because a density tier scales padding and hit targets but not the type scale. Compact is unaffected in practice (33 against 32). Documented on the Density page. (delete list: search-height-pinned-for-a-short-row)",
257
258
  "SIGNAL FORMS WORK — no adapter, no wrapper, no DS import. Put [formField] from @angular/forms/signals on any DS control and the form owns the value, validation, touched and disabled state. This was ALWAYS nearly true and nobody knew: FormValueControl requires exactly one member, a `value` model(), and every DS control already had it. Measured across all fifteen controls - thirteen bound with no library change at all. Additive, NO ACTION. WHAT CHANGED HERE, and it is why the other four rules now work too: min/max/maxLength on ds-input, ds-textarea and ds-number-stepper accept undefined on the WRITE side (the binder sends it for an unset bound; the read type is untouched); `readonly` joins ds-input, ds-textarea and ds-select as the contract spelling of the existing readOnly, because signal forms binds by NAME and a readonly() rule was reaching nothing; `minLength` and `pattern` are new native attributes on ds-input and ds-textarea; and `hidden` is declared on both control-value-accessor bases, so a hidden() rule now removes the control on all thirteen that carry one. focus() is implemented too, so focusBoundControl() - the usual way to reach the first invalid field after a failed submit - lands on the element that holds the value rather than on the host, which is a <ds-*> element and not focusable, so focus previously went nowhere. It resolves per control: the stepper's number box rather than its minus button, the tabbable radio rather than the first in the DOM, a picker's trigger rather than an input inside its closed panel. NOT implemented: dirty, pending and disabledReasons - the form still tracks them, and they are blocked on a visual decision rather than wiring. ERROR TEXT still comes from your validator: required(path.email, { message: '...' }) or a provideDsConfig field.errorMessages mapping, otherwise the field goes red with no words and only a dev warning explains why. Docs: the Practice > Signal Forms page, with a live form and the measured contract table.",
258
- "ds-modal / ds-modal-card gained [dividers] (default true = today's rendering). Additive, NO ACTION - but DELETE-LIST MATERIAL if you set --ds-modal-divider: transparent. Two consumer apps did exactly that, and both were then left with header and actions padding sized to clear a rule that was no longer drawn, stacking into a 35px gap where 16px was wanted; one needed !important plus a stylelint-disable to win it back. [dividers]=\"false\" drops the rules AND the padding in one move, because those are one design decision. If you kept a deliberate --ds-modal-divider colour, nothing changes. If you set it transparent, replace it with [dividers]=\"false\" and delete whatever padding overrides you wrote afterwards - and note --ds-modal-body-pad-y now falls to 0 in that mode, so set it explicitly if you want a value in both. (delete list: modal-divider-transparent-plus-padding)",
259
- "ds-modal / ds-modal-card gained a [title-badge] content slot and a subtitle input, so a dialog header can carry a status chip and a second line without abandoning the component. Additive, NO ACTION - both are absent by default and the header renders exactly as before. WORTH A LOOK IF YOU HAND-ROLLED A DIALOG: a consumer audit found two screens that dropped ds-modal purely because the header could not hold `title + ds-badge` over a `carrier - type` line, and re-implemented the scrim, the body scroll lock, backdrop-click and Escape by hand - losing the focus trap, focus restore, the enter/leave animation and, in one case, the footer, which put a destructive action next to the close button. The shape matches ds-page-header: [title-badge] projects beside the title, subtitle is a plain string under it. The accessible name is still the title string - projected markup never enters aria-labelledby. Retune with --ds-modal-subtitle-text-color and --ds-modal-subtitle-font-size.",
259
+ "ds-modal / ds-modal-card gained [dividers] (default true = today's rendering). Additive, NO ACTION - but DELETE-LIST MATERIAL if you set --ds-modal-divider: transparent. Setting it transparent leaves the header and actions padding sized to clear a rule that is no longer drawn, stacking into a 35px gap where 16px was wanted. [dividers]=\"false\" drops the rules AND the padding in one move, because those are one design decision. If you kept a deliberate --ds-modal-divider colour, nothing changes. If you set it transparent, replace it with [dividers]=\"false\" and delete whatever padding overrides you wrote afterwards - and note --ds-modal-body-pad-y now falls to 0 in that mode, so set it explicitly if you want a value in both. (delete list: modal-divider-transparent-plus-padding)",
260
+ "ds-modal / ds-modal-card gained a [title-badge] content slot and a subtitle input, so a dialog header can carry a status chip and a second line without abandoning the component. Additive, NO ACTION - both are absent by default and the header renders exactly as before. WORTH A LOOK IF YOU HAND-ROLLED A DIALOG: a header that has to carry `title + ds-badge` over a second line used to be a reason to drop ds-modal and re-implement the scrim, the body scroll lock, backdrop-click and Escape by hand - which costs the focus trap, focus restore, the enter/leave animation and, easily, the footer, leaving a destructive action next to the close button. The shape matches ds-page-header: [title-badge] projects beside the title, subtitle is a plain string under it. The accessible name is still the title string - projected markup never enters aria-labelledby. Retune with --ds-modal-subtitle-text-color and --ds-modal-subtitle-font-size.",
260
261
  "NEW COMPONENT ds-field-group: several controls in one bordered box (select + input, input + button, search + date-picker). Additive, NO ACTION. If you hand-rolled a glued row by stripping borders off two controls and wrapping them, this replaces it - wrap them in <ds-field-group> and mark the stretching one with grow. Six controls can be segments: ds-input, ds-select, ds-search, ds-autocomplete, ds-date-picker, ds-button. ds-number-stepper and ds-multi-select are excluded by design. Grouped controls must not be given a label or hint - the message row would break the glued line and is suppressed.",
261
262
  "ds-table gained [lazy] + (lazyLoad) for fetching rows as they scroll into view. Additive and opt-in, NO ACTION. If you paged a long list yourself to keep it responsive, this is the alternative: set lazy with virtualScroll and total, make data a SPARSE array total long, and write each fetched row at its ABSOLUTE index - gaps inside the window render skeleton rows. Note sortMode must not be \"client\" (it would sort only the rows that happen to have arrived); the new server default is already right.",
262
263
  "--ds-field-height now reaches ds-autocomplete, ds-multi-select, ds-color-picker, ds-number-stepper, ds-split-button and the ds-modal confirm input. All six spelled their height as the raw --hit-* value, so the token the name advertises did nothing for them; they read the field scale now. Pixel-identical at every size EXCEPT ds-number-stepper at size=\"lg\" (its own actionable entry above). NO ACTION unless you had already worked around the gap by pinning height on one of these - that pin can go.",
@@ -268,9 +269,9 @@
268
269
  "ds-date-picker and ds-time-picker resolve their trigger's horizontal padding from --field-pad-x (new hooks: --ds-date-picker-trigger-pad-x, --ds-time-picker-trigger-pad-x) instead of a hard-coded --space-3. Identical at the default density; the difference shows under [data-density], where the token shrinks and the literal did not, leaving a picker 8px wider than the input beside it. NO ACTION unless you hand-pinned picker padding to compensate.",
269
270
  "The ds-auth-shell -> ds-auth-layout rename is vocabulary only: no input, output, slot, token value or behaviour changed, and it is the same component 0.8.0 shipped. If you never adopted ds-auth-shell (it was added in 0.8.0), there is nothing to do.",
270
271
  "FIXED in ds-textarea: size=\"sm\" and size=\"lg\" rendered the md vertical padding (12px top and bottom) regardless of the size. The size blocks set the inner textarea's vertical pad, but a :host-prefixed pin at the end of the file out-ranked them once emulated encapsulation shimmed both selectors - it carries one more attribute than the size selector. There are now three pins, one per size, and the size blocks keep only the horizontal padding they own. NO ACTION: the change is visible only on a non-md textarea and the md default is unchanged. Note that retuning --ds-input-pad-y previously moved all three sizes together; if you compensated for the wrong padding with your own override on a sm or lg textarea, that override now stacks on the corrected value and can go.",
271
- "ds-auth-layout now COMPRESSES its own chrome on a short viewport: block padding, the column gap, the letter-mark tile and the masthead inner gap clamp against svh. No action - behaviour only, and a viewport 800px tall or more renders exactly what it did before. Read that as a VIEWPORT height, not a screen size: a 1366x768 laptop sits near 630px after browser and OS chrome, and a 1080p screen at 150% display scaling near 585px, so plenty of desktops do get the compressed furniture - an earlier wording of this line said 'so desktop is unchanged', which was wrong. Type is deliberately NOT clamped: the wordmark and the tile's glyph were measured to buy zero vertical space (the tile sets the row height at every viewport, and the glyph sits in a fixed-size box) while flattening the brand against a fixed 14px tagline, so both keep the fixed sizes 0.8.0 ships. Below 800px the remaining furniture shrinks so it is not what pushes a card into scrolling (~131px instead of ~219px at a landscape phone's ~330px). Two tokens opt out per dimension: --ds-auth-layout-pad-block and --ds-auth-layout-mark-size; setting any of those or the existing --ds-auth-layout-gap to a fixed value stops that one compressing. A card taller than the remaining space still scrolls - that is intended.",
272
+ "ds-auth-layout now COMPRESSES its own chrome on a short viewport: block padding, the column gap, the letter-mark tile and the masthead inner gap clamp against svh. No action - behaviour only, and a viewport 800px tall or more renders exactly what it did before. Read that as a VIEWPORT height, not a screen size: a 1366x768 laptop sits near 630px after browser and OS chrome, and a 1080p screen at 150% display scaling near 585px, so plenty of desktops do get the compressed furniture. Type is deliberately NOT clamped: the wordmark and the tile's glyph were measured to buy zero vertical space (the tile sets the row height at every viewport, and the glyph sits in a fixed-size box) while flattening the brand against a fixed 14px tagline, so both keep the fixed sizes 0.8.0 ships. Below 800px the remaining furniture shrinks so it is not what pushes a card into scrolling (~131px instead of ~219px at a landscape phone's ~330px). Two tokens opt out per dimension: --ds-auth-layout-pad-block and --ds-auth-layout-mark-size; setting any of those or the existing --ds-auth-layout-gap to a fixed value stops that one compressing. A card taller than the remaining space still scrolls - that is intended.",
272
273
  "ds-auth-layout audit fixes, all additive or corrective - NO ACTION. The letter-mark tile is now aria-hidden (a screen reader announced 'A MyAdmin', now 'MyAdmin') and carries flex-shrink: 0 so a long wordmark cannot squash it out of square; logoLetter on its own renders its tile instead of nothing; the glyph is taken by code point rather than charAt(0), which returned half a surrogate pair for a brand starting with an emoji; box-sizing: border-box is declared on the host rather than inherited, so the component still avoids its own overflow scrollbar for a consumer composing style partials without styles/reset. The four env(safe-area-inset-*) calls gained 0px fallbacks and moved to physical padding-left/padding-right so the insets cannot swap sides under RTL - and note they are inert unless YOUR app sets viewport-fit=cover in its viewport meta, which the library cannot set for you. New tokens, both defaulting to today's behaviour: --ds-auth-layout-mark-radius (the tile's radius was the one value with no override hop) and --ds-auth-layout-brand-max-height (none by default; set it to cap a projected [brand] logo, which nothing constrained). New input landmark, default 'none': set landmark=\"main\" on a standalone auth page so the card - an <article>, which is not a landmark - becomes something a screen-reader user can jump to; it stays opt-in because this layout is also embedded inside pages that already own a main.",
273
- "ds-icon now logs a dev-mode warning when an icon name is in neither the DS set nor your provideDsIcons() registry - previously it rendered an empty <svg> silently. No action, and nothing changes in production. Expect the warning to surface real typos the moment you upgrade: an audit of three screens in one consumer is what prompted it.",
274
+ "ds-icon now logs a dev-mode warning when an icon name is in neither the DS set nor your provideDsIcons() registry - previously it rendered an empty <svg> silently. No action, and nothing changes in production. Expect the warning to surface real typos the moment you upgrade.",
274
275
  "ds-app-layout gained scrollReset: \"path\" | \"never\" | \"always\" (default \"path\" = existing behaviour, so NO ACTION), and LayoutNavigationService is now exported. If you wrote your own \"did the path change?\" check to work around the layout resetting scroll - or to skip a view transition, or to reset a tab - replace it with inject(LayoutNavigationService).pathChanged: it is NavigationEnd, path only, de-duplicated, and it skips a navigation carrying state: { dsSamePage: true }. Note a naive split(\"?\") is NOT equivalent, it keeps the fragment this stream strips. To stop the layout resetting scroll on a paged or filtered list, set scrollReset=\"never\" and call LayoutScrollService.scrollToTop() where you actually want it.",
275
276
  "Options in ds-select / ds-autocomplete / ds-multi-select panels now have a pressed state (they had hover only, which does nothing on touch). No action - visual only. If you styled :active on .option yourself to work around it, you can drop that override; if you want a different pressed fill, it reads --surface-muted (neutral rows) and --primary-subtitle (the selected row). (delete list: dropdown-option-active-override)",
276
277
  "ds-table gained filterMode: \"client\" | \"server\" | \"none\" and columnFilterOptions. It resolves to \"server\" when unset - see the table-sort-filter-mode-default-server item, which is where the action for that lives. If your table is server-paged (you bind `total`) and any column has filter: \"set\", you WANT filterMode=\"server\" plus columnFilterOptions with the real value domain - otherwise the checklist offers only the values on the current page and then filters locally on top of the server. A dev warning now points this out.",
@@ -283,7 +284,7 @@
283
284
  "ds-date-picker keeps its trigger indicator while the panel is open (an \"open\" class alongside the focus rules). Visual only, NO ACTION. If you styled .trigger:focus-within yourself to work around the trigger going dark, you can drop it. (delete list: date-picker-trigger-focus-within-override)",
284
285
  "ds-autocomplete in single mode collapses its filter input once a value is chosen and the panel is closed, so the field reads as a picker instead of a text box. Visual only, NO ACTION. Clicking the field still opens the panel and expands the input, and typing still filters. If you set --ds-autocomplete-input-minw to work around the empty box, you can drop it. (delete list: autocomplete-input-minw-override)",
285
286
  "ds-date-picker: clicking the calendar glyph no longer moves focus into the day grid. It now behaves like a click on the field - with allowInput (the default) the caret stays in the field, and a read-only field still focuses the grid. No action; ArrowDown on the field enters the grid as before. If you scripted tests that assumed a glyph click lands focus on a day button, they need updating.",
286
- "WHAT THE DELETE LIST COVERS - the half a release note usually leaves out. Two dogfooding audits (mm-ecm 2026-08-06, mm-broker 2026-08-07) read consumer stylesheets as a record of what this library made them write, and both found the same thing: most of the workarounds were written against hooks that ALREADY existed, because a release note says what broke and never says what became unnecessary. Each line below is SEARCH-FOR -> WHY IT CAN GO. None of it is required: skipping it leaves working code that is merely redundant. How to sweep for the rest: grep your styles for ::ng-deep, !important, and any selector naming a DS internal class (.button, .trigger, .option, .modal) - each hit is either an entry below or a genuine gap worth reporting."
287
+ "WHAT THE DELETE LIST COVERS - the half a release note usually leaves out. Most of the workarounds are written against hooks that ALREADY existed, because a release note says what broke and never says what became unnecessary. Each line below is SEARCH-FOR -> WHY IT CAN GO. None of it is required: skipping it leaves working code that is merely redundant. How to sweep for the rest: grep your styles for ::ng-deep, !important, and any selector naming a DS internal class (.button, .trigger, .option, .modal) - each hit is either an entry below or a genuine gap worth reporting."
287
288
  ],
288
289
  "deleteList": [
289
290
  {
@@ -2,10 +2,10 @@
2
2
  "version": "0.9.1",
3
3
  "items": [],
4
4
  "informational": [
5
- "Nothing in this release changes the package's runtime. Its entire src/ diff is JSDoc, which feeds the generated token and component reference; every component behaves exactly as it did on 0.9.0.",
5
+ "Nothing in this release changes the package's runtime. The entire change is documentation, feeding the token and component reference; every component behaves exactly as it did on 0.9.0.",
6
6
  "THREE documented behaviours were guessable wrong, so check these if you use them - the code always worked this way, only the reference was silent. (1) ds-time-columns `value` is always HH:mm in 24h and `format` changes only the DISPLAY, so a picker showing 12h still emits 24h - code that parsed the emitted value as 12h was wrong. (2) ds-time-columns `minTime`/`maxTime` DISABLE the out-of-range rows rather than removing them, so the columns keep their height as a bound moves - a layout that assumed the list shortens was wrong. (3) ds-calendar-day `tabIndex` is a roving tabindex owned by the grid (exactly one cell at 0, the rest at -1), not a tab position to set per day - setting it per cell fights the grid's keyboard model.",
7
7
  "41 public tokens and props gained descriptions in the reference: 10 --ds-* tokens (the whole --ds-password-rules-* set, --ds-multi-select-panel-bg-color and --ds-menu-item-radius among them) and 31 inputs and outputs across ds-calendar-day, ds-time-columns, ds-field-message, ds-divider, ds-sidenav-footer and the three layout primitives. Names, types and defaults are unchanged.",
8
- "Every version's migration manifest now carries its DELETE-LIST entries, so an upgrade tool can act on what a release made UNNECESSARY and not only on what it broke. 0.9.0 has 21 of them. They existed before only in a prose file no tooling read, and that file has been retired."
8
+ "A release manifest carries a deleteList wherever that release made a workaround unnecessary, so an upgrade tool can act on what became redundant and not only on what broke. Each row is machine-readable: { id, surface, find, why, replaceWith }."
9
9
  ],
10
10
  "deleteList": []
11
11
  }
@@ -1,8 +1,7 @@
1
1
  # Machine-readable migration manifests
2
2
 
3
3
  One file per released version — `migrations/<version>.json` — mirroring that version's
4
- `CHANGELOG.md` block as a structured **MigrationPlan** (the exact schema the
5
- `/design-system:auto-update-package` plugin's planner produces from prose):
4
+ `CHANGELOG.md` block as a structured **MigrationPlan**:
6
5
 
7
6
  ```json
8
7
  { "version": "X.Y.Z",
@@ -41,77 +40,60 @@ One file per released version — `migrations/<version>.json` — mirroring that
41
40
  - **`supersedes`** — `<version>#<id>`, declared on the item that REVERSES an earlier one. It points
42
41
  BACKWARD only. An upgrade walks one version at a time and each manifest is frozen when the next is
43
42
  written, so a file cannot name its own future: there is no `supersededBy`, and a note that says
44
- "in the next release" is a defect (M028, M029). The reversal is described in full by the later
43
+ "in the next release" is a defect. The reversal is described in full by the later
45
44
  item, which is the one an upgrade reaches second.
45
+ - **`action`** — the imperative: what to change, in the order to change it. The one field an
46
+ upgrade executes.
47
+ - **`appliesWhen`** — the boundary: which components, which bindings, and what is explicitly NOT
48
+ affected, so an item can be ruled out without searching.
49
+ - **`pitfall`** — the way to apply the item mechanically correctly and still ship a broken app.
50
+ Read it before deciding a clean build means done.
46
51
  - **`deleteList`** — the structured form of "what you can now delete" (see below).
47
52
 
48
- **Why:** the auto-update plugin reads the prose changelog with an LLM planner — correct, but
49
- re-derived on every consumer run. A shipped manifest makes the plan deterministic: the planner
50
- validates and prefers it, falling back to prose only when a version has no manifest. **Every
51
- published version has one**, so the fallback should never fire — the earliest were authored
52
- retroactively, and `0.6.1`, `0.6.2` and `0.9.1` were backfilled on 2026-08-11 after an audit found
53
- them missing. A patch release is not exempt: 0.6.2 turned out to carry an actionable change (a sheet
53
+ **Why:** an upgrade tool can read the plan out of the prose changelog, but it re-derives it on
54
+ every run. A shipped manifest makes it deterministic: the tool validates and prefers the
55
+ manifest, falling back to prose only when a version has no manifest. **Every published version
56
+ has one**, so the fallback should never fire. A patch
57
+ release is not exempt: 0.6.2 carries an actionable change (a sheet
54
58
  with nothing focusable in it stopped closing on Escape), which is exactly the kind a "just fixes"
55
59
  release is assumed not to have.
56
60
 
57
- See `AUTHORING.md` for how to write a good entry.
58
-
59
- **Do NOT write a prose guide per release — 0.9.0 tried it and it was retired the same day.**
60
- `migrations/unreleased/README.md` restated the manifest in a form nothing reads: the auto-update
61
- plugin loads `<version>.json`, and the only content the manifest did not already carry was the
62
- delete-list. Worse, it went stale inside one release — three late changes never reached it — and a
63
- stale duplicate misleads where no file would merely be silent. Its content now lives in the two
64
- places that ARE read: the `deleteList` array in `<version>.json`, and a "What you can now DELETE"
65
- table in that version's CHANGELOG block.
66
-
67
- **A sibling folder `migrations/<version>/*.md` is still legal for the rare case a `note` genuinely
68
- cannot hold** — a worked before/after with code on both sides, like `migrations/0.5.1/badge-statuses.md`.
69
- The folder never matches the `*.json` glob, so tooling ignores it, and `tools/changelog-release.mjs`
70
- promotes `migrations/unreleased/` alongside the manifest if one exists. The test before writing one:
71
- **would a tool or an agent ever open it?** If the answer is "a human might", it belongs in the
72
- CHANGELOG instead.
61
+ A version may also ship a sibling folder `migrations/<version>/*.md` holding a worked
62
+ before/after too long for a `note` — `migrations/0.5.1/badge-statuses.md` is the one that exists.
63
+ It never matches the `*.json` glob, so tooling ignores it.
73
64
 
74
65
  **What the manifest must carry that a release note usually omits: what the consumer can now DELETE.**
75
- Two dogfooding audits (mm-ecm 08-06, mm-broker 08-07) read consumer stylesheets as a record of what
76
- this library made them write, and both found the same thing — most workarounds were written against
77
- hooks that ALREADY existed, because a release note says what broke and never says what became
78
- unnecessary.
66
+ Most workarounds in an app are written against hooks that
67
+ ALREADY existed, because a release note says what broke and never says what became unnecessary.
79
68
 
80
- **Those entries are the `deleteList` ARRAY, not prose.** 0.9.0 and 0.10.0 shipped 21 and 24 of them
81
- as `DELETE-LIST:` sentences inside `informational`, and in the mm-broker upgrade (2026-08-21) not one
82
- of them was acted on by the loop: an array of strings has no `find` for a finder to run, so every one
83
- of the 45 waited for a human to read all 63 informational lines and recognise their own code in a
84
- sentence. Twelve local classes and a duplicated `visually-hidden` recipe survived the upgrade that
85
- way. Write each as `{ id, surface, find, why, replaceWith }` — `find` being the shape in the
69
+ **Those entries are the `deleteList` ARRAY, not prose.** A delete hint written as a sentence inside
70
+ `informational` has no `find` for a finder to run, so it waits for a human to recognise their own
71
+ code in it. Write each as `{ id, surface, find, why, replaceWith }` — `find` being the shape in the
86
72
  CONSUMER's code, a string or an array of them — and keep the human copy in that version's CHANGELOG
87
73
  "What you can now DELETE" table. Two copies, each read by someone; the third copy in `informational`
88
74
  is the one that goes stale, so new manifests do not carry it.
89
75
 
90
76
  **What made an item findable is now part of the schema, because a well-formed item can still be
91
- undetectable.** mm-broker walked 0.6.0 → 0.10.1 with the plugin and a review afterwards found two
92
- items the whole find/apply/recheck loop had passed over in silence — not malformed, not ambiguous,
93
- just impossible to locate from what they carried:
77
+ undetectable.** Two shapes slip past a find/apply/recheck loop — not malformed, not ambiguous, just
78
+ impossible to locate from what they carry:
94
79
 
95
80
  - `0.7.1#table-sortkey-non-null-when-unsorted` named `ds-table[sortKey]` as `old`, and every
96
81
  `searchHint` named the DS. What breaks is the host's own store code —
97
82
  `sorting: store.sortKey() ? { path: sortKey()!, order: sortDir() ?? 'Asc' } : undefined` — which
98
- mentions no DS symbol at all. Zero hits, "not applicable", and the recheck's clean grep CONFIRMED
99
- the verdict. Three server-paged screens kept ordering by a column whose header showed no sort.
83
+ mentions no DS symbol at all. A DS-named search returns zero hits, the item is
84
+ recorded not-applicable, and a clean re-check grep agrees — while the table keeps ordering by a
85
+ column whose header shows no sort.
100
86
  - `0.7.1#field-reserve-message-default-off` put "consumers that wrote `[reserveMessage]="false"` can
101
- delete those bindings" at word 150 of a 200-word note, with no delete entry. Three of them
102
- survived.
87
+ delete those bindings" deep inside a long note, with no delete entry, so the bindings survive.
103
88
 
104
89
  Hence `surface`, `detect`, `verify` and `restore`: say WHERE the consumer's code changes, what that
105
90
  code LOOKS like when it names nothing of ours, what proves the change landed, and how to get the old
106
- behaviour back. **`tools/migration-lint.mjs` enforces it** — run `npm run migration-lint`; the
107
- `preversion` hook and the PR gate both run it, so neither a release nor a merge can carry a manifest
108
- nobody can act on. **Every published manifest was back-filled to this contract on 2026-08-21** (167
109
- items across 19 releases, 32 prose delete lines into arrays), so there is no legacy tier and no
110
- warning level: a gap is an error wherever it appears.
91
+ behaviour back. **Every published manifest meets this contract**, back to the earliest release, so there is no
92
+ legacy tier and no warning level: `surface`, `detect`, `verify` and `restore` are present wherever
93
+ they apply.
111
94
 
112
- **Authoring:** drafted at release time alongside the CHANGELOG entry (the `/changelog` workflow
113
- drafts it from the release diff; the release author reviews). The prose changelog stays canonical
114
- for humans — the manifest is its machine mirror; if they disagree, fix the manifest.
95
+ The prose CHANGELOG is the human copy of a release; the manifest is its machine mirror of the
96
+ same release. Where the two disagree, the CHANGELOG is the one to trust.
115
97
 
116
- **Shipping:** `tools/build-schematics.mjs` copies `migrations/` into `dist/ds/migrations/`, so
117
- consumers get manifests in `node_modules` and the plugin also reads them from the repo clone.
98
+ **Shipping:** the manifests are in
99
+ `node_modules/@ids-group-ltd/ids-design-system/migrations/`.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ids-group-ltd/ids-design-system",
3
- "version": "0.11.0",
3
+ "version": "0.11.2",
4
4
  "description": "IDS Group Angular design system: components, tokens, themes",
5
5
  "license": "MIT",
6
6
  "homepage": "https://ids-ds.proto.ids-group.co.uk/",
@@ -5,6 +5,7 @@
5
5
  // declares the matching rules so the portaled panel renders styled.
6
6
 
7
7
  @use 'text-clip' as text-clip;
8
+ @use 'visually-hidden' as visually-hidden;
8
9
 
9
10
  .ds-dropdown-panel {
10
11
  /* The selected row used to paint straight from the theme roles, so a brand that
@@ -22,39 +23,64 @@
22
23
  picker's corner is not a thing a design system should encourage, but moving
23
24
  every panel — modal, popover, date picker — to reach the dropdowns is too
24
25
  blunt. This is the middle lever, and `--ds-radius-panel` stays its default so
25
- an untouched theme is unchanged. 0.9.0's notes promised a per-component
26
- `--ds-select-panel-radius`, which never existed; this is what they meant. */
26
+ an untouched theme is unchanged. */
27
27
  --_dropdown-panel-radius: var(--ds-dropdown-panel-radius, var(--ds-radius-panel));
28
28
 
29
+ /* Only bite in `content` width mode, where the pane is auto-sized: in `fill` the
30
+ component pins the pane to the trigger and there is nothing left to bound. */
31
+ --_option-gap: var(--ds-option-gap, var(--space-2));
32
+ --_option-padding: var(--ds-option-padding, var(--space-2) var(--space-2-5));
33
+ --_option-radius: var(--ds-option-radius, var(--ds-radius-inner));
34
+ --_option-row-gap: var(--ds-option-row-gap, 2px);
35
+ --_option-bg-color-active: var(--ds-option-bg-color-active, var(--surface-secondary));
36
+
37
+ --_dropdown-panel-bg-color: var(--ds-dropdown-panel-bg-color, var(--surface-overlay));
38
+ --_dropdown-panel-maxh: var(--ds-dropdown-panel-maxh, 320px);
39
+ --_dropdown-panel-minw: var(--ds-dropdown-panel-minw, 0);
40
+ --_dropdown-panel-maxw: var(--ds-dropdown-panel-maxw, none);
41
+
29
42
  .dropdown-panel {
30
- // Fill the cdk-overlay-pane width (set from trigger.getBoundingClientRect()
31
- // in dropdown.component.ts). Without `width: 100%` the panel is a flex
32
- // child of the pane and shrinks to its own option content width.
43
+ // The pane is sized from the trigger, so without `width: 100%` the panel is a flex
44
+ // child of it and shrinks to its own option content width.
33
45
  width: 100%;
34
- background: var(--surface-overlay);
46
+ background: var(--_dropdown-panel-bg-color);
35
47
  border: var(--border-width-default) solid var(--border-default);
36
48
  border-radius: var(--_dropdown-panel-radius);
37
49
  box-shadow: var(--shadow-popover);
38
50
  padding: var(--space-1);
39
- max-height: 320px;
40
- overflow-y: auto;
51
+ min-width: var(--_dropdown-panel-minw);
52
+ max-width: var(--_dropdown-panel-maxw);
53
+ max-height: var(--_dropdown-panel-maxh);
54
+
55
+ // The panel clips and the LIST scrolls, so a filter row or a select-all row
56
+ // stays put while the options move under it. A panel that scrolled itself
57
+ // would carry those rows out of view.
58
+ display: flex;
59
+ flex-direction: column;
60
+ overflow: hidden;
41
61
  z-index: var(--layer-popover);
42
62
  }
43
63
 
44
64
  .dropdown-list {
65
+ max-height: var(--picker-maxh);
45
66
  list-style: none;
46
67
  margin: 0;
47
68
  padding: 0;
48
69
  display: flex;
49
70
  flex-direction: column;
50
- gap: 2px;
71
+
72
+ // A flex child will not shrink below its content without this, so the list
73
+ // would push the panel past its own max-height instead of scrolling.
74
+ min-height: 0;
75
+ overflow-y: auto;
76
+ gap: var(--_option-row-gap);
51
77
  }
52
78
 
53
79
  .optgroup {
54
80
  list-style: none;
55
81
  display: flex;
56
82
  flex-direction: column;
57
- gap: 2px;
83
+ gap: var(--_option-row-gap);
58
84
  }
59
85
 
60
86
  .optgroup-label {
@@ -77,21 +103,27 @@
77
103
  padding: 0;
78
104
  display: flex;
79
105
  flex-direction: column;
80
- gap: 2px;
106
+ gap: var(--_option-row-gap);
107
+ }
108
+
109
+ .empty {
110
+ padding: var(--space-3) var(--space-4);
111
+ color: var(--text-tertiary);
112
+ text-align: center;
81
113
  }
82
114
 
83
115
  .option {
84
116
  display: flex;
85
117
  align-items: center;
86
- gap: var(--space-2);
118
+ gap: var(--_option-gap);
87
119
  width: 100%;
88
- padding: var(--space-2) var(--space-2-5);
120
+ padding: var(--_option-padding);
89
121
  border: 0;
90
122
  background: transparent;
91
123
  font: var(--font-weight-medium) var(--font-size-s) / var(--line-height-flat) var(--font-sans);
92
124
  color: var(--text-primary);
93
125
  cursor: pointer;
94
- border-radius: var(--ds-radius-inner);
126
+ border-radius: var(--_option-radius);
95
127
  text-align: left;
96
128
  transition: background-color var(--duration-fast) var(--ease-standard);
97
129
 
@@ -107,6 +139,12 @@
107
139
  @include text-clip.single-line-ellipsis;
108
140
  }
109
141
 
142
+ // Visually hidden, not display:none — the latter leaves the accessibility
143
+ // tree and the reason would be announced nowhere.
144
+ .option-reason {
145
+ @include visually-hidden.visually-hidden;
146
+ }
147
+
110
148
  .option-check {
111
149
  color: var(--_option-check-color);
112
150
  flex: 0 0 auto;
@@ -116,17 +154,20 @@
116
154
  // on specificity, so without it a hovered (or keyboard-active) selected row
117
155
  // repaints to the neutral surface while KEEPING the selected label colour —
118
156
  // unreadable as soon as a brand gives the selected row a dark fill.
119
- &:hover:not(.is-disabled, .is-selected),
120
- &.is-active:not(.is-disabled, .is-selected) {
121
- background: var(--surface-secondary);
157
+ &:disabled {
158
+ color: var(--text-disabled);
159
+ cursor: not-allowed;
160
+ }
161
+
162
+ &:hover:not(.is-disabled, .is-selected, :disabled),
163
+ &.is-active:not(.is-disabled, .is-selected, :disabled) {
164
+ background: var(--_option-bg-color-active);
122
165
  }
123
166
 
124
- // Pressed. The equivalent rows elsewhere (ds-menu-item, ds-list-item) have
125
- // had one since 2026-07-02; the picker panels were left with hover only, so
126
- // a tap on a phone — where there is no hover at all — gave no feedback that
127
- // the row had been hit. One rule here covers select, autocomplete and
128
- // multi-select, which all render their options through this partial.
129
- &:active:not(.is-disabled) {
167
+ // A tap on a phone has no hover, so a pressed state is the only feedback that the
168
+ // row was hit. One rule here covers select, autocomplete and multi-select, which
169
+ // all render their options through this partial.
170
+ &:active:not(.is-disabled, :disabled) {
130
171
  background: var(--surface-muted);
131
172
  }
132
173
 
@@ -1,9 +1,9 @@
1
1
  // Scoped accent recolour. A `ds-color="<family>"` attribute — on a zone
2
2
  // container, on a component host, or applied via the ds.color() mixin in
3
3
  // consumer config — flips the --accent-* pointer family to another brand/status
4
- // family for its subtree. Components read --accent-* for their accent (the
5
- // Phase 2 sweep), so the whole subtree recolours from this one rule. Pairs with
6
- // the button/icon-button `color` input (Phase 1), which flips the same pointers
4
+ // family for its subtree. Components read --accent-* for their accent, so the whole
5
+ // subtree recolours from this one rule. Pairs with the button/icon-button `color`
6
+ // input, which flips the same pointers
7
7
  // per instance. With no attribute, --accent-* stays the primary family (see
8
8
  // themes/_semantic.scss), so the default theme is unchanged.
9
9
 
@@ -1,11 +1,7 @@
1
1
  // One control-box height for the field family.
2
2
  //
3
- // `--field-h-sm`/`-md`/`-lg` have shipped as the field height scale since the
4
- // token file was written, but only `-lg` was ever read: every field spelled the
5
- // other two as the raw `var(--hit-min)` / `var(--hit-cozy)` instead. A consumer
6
- // retuning `--field-h-md` — the obvious lever, and the one the token name
7
- // advertises — therefore changed nothing. Same values, so routing through the
8
- // scale is visually neutral; it just makes the knob real.
3
+ // `--field-h-sm`/`-md`/`-lg` is the height scale every field-shaped control resolves
4
+ // through, so retuning `--field-h-md` moves them together.
9
5
  //
10
6
  // `--ds-field-height` is the public override and beats the size class, because a
11
7
  // consumer setting it has already decided. Per-instance is CSS-variable scoping:
@@ -1,14 +1,12 @@
1
1
  // One label contract for the field family.
2
2
  //
3
- // Five components hard-coded the identical rule and ds-select named its element
4
- // `.select-label`, so a form mixing a select with an input rendered labels in two
5
- // sizes and colours out of the box, and retuning them from an app needed
6
- // `.field.field .label.label, .select-label.select-label` to out-rank the shimmed
7
- // component rule. One class (`.label`), one token set, resolved here.
3
+ // One class (`.label`), one token set, resolved here, so a form mixing a select with an
4
+ // input renders its labels at one size and colour. It lives in one place because
5
+ // out-ranking a shimmed component rule from an app needs doubled selectors
6
+ // (`.field.field .label.label`).
8
7
  //
9
8
  // A MIXIN, not a global rule: a global `.label` would match consumer markup that
10
- // happens to use the same class name — the leak that global `.field`/`.check`
11
- // specimens caused in ds-docs. Each field pays ~6 declarations of its own CSS.
9
+ // happens to use the same class name. Each field pays ~6 declarations of its own CSS.
12
10
  //
13
11
  // Per-instance retune is CSS-variable scoping, so no per-component token set is
14
12
  // needed: `ds-select { --ds-field-label-transform: uppercase; }` reaches exactly
@@ -23,9 +21,6 @@
23
21
 
24
22
  display: flex;
25
23
  align-items: center;
26
-
27
- // --field-gap-req is the label↔asterisk token; the old rules all spelled its
28
- // value out as var(--space-1) instead of naming it.
29
24
  gap: var(--field-gap-req);
30
25
  font: var(--_field-label-weight) var(--_field-label-font-size) / var(--line-height-base) var(--font-sans);
31
26
  color: var(--_field-label-color);
@@ -1,6 +1,7 @@
1
1
  // Keyed off `data-field-state` on the host, which each field binds from
2
- // `resolveFieldMessage`'s `controlState`. The tinted-fill variant of warning and
3
- // success is parked in docs/todo.md.
2
+ // `resolveFieldMessage`'s `controlState`. Only error carries a fill: a warning or
3
+ // success tint measures 1.05:1 against a white field, too faint to do the
4
+ // findability job a fill exists for, so neither carries one.
4
5
  //
5
6
  // The colour arguments exist so a component can pass its own `--ds-<name>-*-error`
6
7
  // resolver: hardcoding the family token here would silently drop overrides
@@ -19,7 +19,6 @@
19
19
  // `$control` names ONE control and must never be a blanket: a box-wide reset also
20
20
  // silences the tab stops living in the box — a clear button, a stepper arrow — and
21
21
  // then tabbing from the field to that button changes nothing on screen.
22
- // Enforced by tools/check-focus-rings.mjs.
23
22
  @mixin owns-the-focus-ring($control) {
24
23
  #{$control}:where(:focus-visible) {
25
24
  box-shadow: none;
@@ -36,7 +35,6 @@
36
35
  --ds-control-focus-shadow-error: var(--focus-field-error);
37
36
  }
38
37
 
39
- // A hairline flush against the element, no gap — from the pin-475 prototype.
40
38
  :root[data-focus='edge'] {
41
39
  --ds-field-focus-shadow: 0 0 0 var(--border-width-default) var(--primary);
42
40
  --ds-field-focus-shadow-error: 0 0 0 var(--border-width-default) var(--error);
@@ -1,5 +1,5 @@
1
- // Layout utility classes — grid helpers from patterns.css §Grid helpers.
2
- // (Divider lives in _divider.scss — single canonical source.)
1
+ // Layout utility classes — grid helpers. A divider is the ds-divider component,
2
+ // which is the single canonical source for one.
3
3
 
4
4
  @use 'breakpoints' as bp;
5
5
 
@@ -2,9 +2,8 @@
2
2
  // panelClass (select, autocomplete, multi-select, date-picker, time-picker,
3
3
  // color-picker, popover, tooltip, menu submenu). Animates the panel's ROOT
4
4
  // CHILD, not the pane itself, so CDK's positioning transforms on
5
- // `.cdk-overlay-pane` are left untouched. The leave/exit animation was removed
6
- // (close is instant) — see the TODO(overlay-leave) in components/overlay-motion.ts
7
- // to reinstate it.
5
+ // `.cdk-overlay-pane` are left untouched. A leave animation runs on an ambient
6
+ // dismiss only; picking an option closes instantly (see `.ds-leaving` below).
8
7
  //
9
8
  // `data-ds-placement` names WHERE the panel sits relative to its trigger and is
10
9
  // stamped by `prepareOverlayEnter()` before the panel is attached, so the panel
@@ -1,8 +1,6 @@
1
- // Rounded press feedback — Recipe C (approved by Stas 2026-07-02).
2
- //
3
- // Complements the global tap-highlight reset (_reset.scss). The native mobile
4
- // tap overlay was a rectangle that ignored border-radius; we removed it, and
5
- // this gives each interactive control a press state that INHERITS its shape:
1
+ // Complements the global tap-highlight reset (_reset.scss), which drops the native
2
+ // mobile overlay — a rectangle that ignored border-radius. This replaces it with a
3
+ // press state that INHERITS the control shape:
6
4
  // `filter` + `transform` apply to the rendered element, so any border-radius /
7
5
  // clip is followed automatically, and neither conflicts with the box-shadow
8
6
  // focus rings (different properties).