@ids-group-ltd/ids-design-system 0.10.0 → 0.10.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.
@@ -13,20 +13,25 @@
13
13
  "drawer-panel-close",
14
14
  "drawer-scrim-out",
15
15
  "ds-sheet-fade-out"
16
- ]
16
+ ],
17
+ "surface": "style",
18
+ "verify": "No global stylesheet names one of the seven removed exit keyframes, and any --ds-*-leave-keyframes points at a GLOBAL @keyframes (a component-scoped name is renamed by Angular and will not resolve)."
17
19
  },
18
20
  {
19
21
  "id": "dropdown-panel-radius",
20
22
  "kind": "behavior",
21
- "old": "--radius-md (8px) on the ds-select / ds-multi-select panel",
22
- "new": "--ds-radius-panel (12px)",
23
- "note": "CHANGED DEFAULT, visual: the dropdown panel behind ds-select and ds-multi-select has a 12px corner, was 8px. It was the one panel outside the radius role layer - modal, popover, date-picker, time-picker, autocomplete, bottom-sheet, card, stat and page-footer all resolve --ds-radius-panel already - so it both disagreed with its siblings and could not be retuned through the role a consumer is told to use. ACTION: none unless you want the old corner, in which case set --ds-radius-panel: 8px - which moves EVERY panel together, and is the only lever there is. (Corrected 2026-08-11: this note used to offer --ds-select-panel-radius: 8px for restoring just this panel. No such token exists - the dropdown resolves --ds-radius-panel directly - so setting it does nothing. ds-autocomplete does carry a per-panel --ds-autocomplete-panel-radius; the two dropdowns do not.) CHECK: a screen where a dropdown opens beside a popover or a date picker - that is where the 4px difference was visible and is now gone.",
23
+ "old": "ds-select",
24
+ "new": null,
25
+ "note": "CHANGED DEFAULT, visual: the dropdown panel behind ds-select has a 12px corner (--ds-radius-panel), was 8px. It was the one panel outside the radius role layer - modal, popover, date-picker, time-picker, autocomplete, bottom-sheet, card, stat and page-footer all resolve --ds-radius-panel - so it both disagreed with its siblings and could not be retuned through the role a consumer is told to use. ACTION: none unless you want the old corner, in which case set --ds-radius-panel: 8px, which moves EVERY panel together and is the only lever there is: there is no per-panel token for the select, and --ds-select-panel-radius does not exist. ds-autocomplete does carry a per-panel --ds-autocomplete-panel-radius. NOT AFFECTED: ds-multi-select, whose panel is its own element with a hardcoded border-radius: var(--radius-md) that the shared rule does not reach - it stays at 8px in this version. CHECK: a screen where a dropdown opens beside a popover or a date picker - that is where the 4px difference was visible and is now gone.",
24
26
  "searchHints": [
25
27
  "--radius-md",
26
28
  "dropdown-panel",
27
29
  "ds-select",
28
30
  "--ds-radius-panel"
29
- ]
31
+ ],
32
+ "surface": "style",
33
+ "restore": "--ds-radius-panel: 8px (moves every panel together - the only lever there is)",
34
+ "verify": "No consumer rule targets the select or multi-select panel radius directly; a deliberate 8px corner is set through --ds-radius-panel."
30
35
  },
31
36
  {
32
37
  "id": "auth-shell-selector-to-auth-layout",
@@ -36,7 +41,8 @@
36
41
  "note": "Component renamed (shipped as ds-auth-shell in the tagged 0.8.0 source, its only release under that name). \"Shell\" is not this library's word for a layout: the app-level one was renamed ds-app-shell -> ds-app-layout in 0.7.0, and calling the auth counterpart a shell put the split vocabulary back. ACTION: rename the element and its closing tag. Behaviour, inputs and slots are unchanged - brand, logoLetter, tagline, cardElevation, cardPadding, [brand], [dsBrandName] and dsAuthSupport all keep their names. Also rename the class and the tokens (separate entries below).",
37
42
  "searchHints": [
38
43
  "ds-auth-shell"
39
- ]
44
+ ],
45
+ "surface": "template"
40
46
  },
41
47
  {
42
48
  "id": "auth-shell-class-to-auth-layout",
@@ -46,7 +52,8 @@
46
52
  "note": "The exported component class renamed alongside the ds-auth-shell -> ds-auth-layout selector. Update imports and any type references. No members changed.",
47
53
  "searchHints": [
48
54
  "AuthShellComponent"
49
- ]
55
+ ],
56
+ "surface": "typescript"
50
57
  },
51
58
  {
52
59
  "id": "auth-shell-tokens-to-auth-layout",
@@ -56,7 +63,8 @@
56
63
  "note": "Prefix rename for the six component tokens: --ds-auth-shell-min-height / -card-max-width / -gap / -bg-color / -mark-bg-color / -mark-label-color -> --ds-auth-layout-*. Values and defaults are unchanged. DS-owned tokens only (no others ship under this prefix); a consumer's own --ds-auth-shell-* variable is out of scope. EXCLUDED, do not rename: the global scale token --auth-card-w, the fallback behind -card-max-width, which carries no --ds-auth-shell- prefix and keeps its name. Confirm the new name exists in the installed package.",
57
64
  "searchHints": [
58
65
  "--ds-auth-shell-"
59
- ]
66
+ ],
67
+ "surface": "style"
60
68
  },
61
69
  {
62
70
  "id": "search-height-joins-field-scale",
@@ -68,7 +76,10 @@
68
76
  "ds-search",
69
77
  "--ds-search-height",
70
78
  "--search-h"
71
- ]
79
+ ],
80
+ "surface": "style",
81
+ "restore": "ds-search { --ds-search-height: 36px; }",
82
+ "verify": "No toolbar assumes a 36px search box: it either takes the 40px field height or pins --ds-search-height / --ds-field-height deliberately."
72
83
  },
73
84
  {
74
85
  "id": "search-h-token-removed",
@@ -78,7 +89,12 @@
78
89
  "note": "The global --search-h token is gone; it existed only to hold ds-search's 36px and nothing reads it any more. Its replacements, in precedence order: --ds-search-height (retunes search alone) and --ds-field-height (levels the whole field family). If you declared --search-h to resize search, that declaration is now inert - swap it for --ds-search-height with the same value. Reading it in your own CSS resolves to nothing. The --hit-md scale token it pointed at (36px) is untouched and still available.",
79
90
  "searchHints": [
80
91
  "--search-h"
81
- ]
92
+ ],
93
+ "surface": "style",
94
+ "detect": [
95
+ "--search-h"
96
+ ],
97
+ "verify": "No stylesheet declares or reads --search-h; a search resize goes through --ds-search-height, a whole-family one through --ds-field-height."
82
98
  },
83
99
  {
84
100
  "id": "table-sort-filter-mode-default-server",
@@ -92,6 +108,12 @@
92
108
  "filterMode",
93
109
  "sortable",
94
110
  "sortChange"
111
+ ],
112
+ "surface": "template",
113
+ "restore": "sortMode=\"client\" (and filterMode=\"client\") on the tables that hold all their rows",
114
+ "verify": "No table with a sortable column and no `total` binding is left without a declared sortMode - that combination is the one the dev warning names.",
115
+ "supersedes": [
116
+ "0.8.0#table-client-sort-replaced-by-sort-mode"
95
117
  ]
96
118
  },
97
119
  {
@@ -104,7 +126,17 @@
104
126
  "ds-number-stepper",
105
127
  "size=\"lg\"",
106
128
  "--hit-comfy"
107
- ]
129
+ ],
130
+ "surface": [
131
+ "template",
132
+ "style"
133
+ ],
134
+ "detect": [
135
+ "ds-number-stepper",
136
+ "size=\"lg\""
137
+ ],
138
+ "restore": "ds-number-stepper { --ds-field-height: 44px; }",
139
+ "verify": "Every size=\"lg\" stepper is meant to stand 48px beside a large input, or pins --ds-field-height back to 44px."
108
140
  },
109
141
  {
110
142
  "id": "tabs-url-param-adoption",
@@ -117,7 +149,17 @@
117
149
  "ds-tabs",
118
150
  "tabChanged",
119
151
  "queryParamMap"
120
- ]
152
+ ],
153
+ "surface": [
154
+ "template",
155
+ "typescript"
156
+ ],
157
+ "detect": [
158
+ "urlParam",
159
+ "queryParamMap",
160
+ "ds-tab"
161
+ ],
162
+ "verify": "For every strip that adopts urlParam: each ds-tab declares a `value`, no two strips on a screen share a parameter name, and the hand-rolled queryParamMap + navigate() wiring it replaces is gone."
121
163
  },
122
164
  {
123
165
  "id": "exported-class-members-grew",
@@ -143,7 +185,14 @@
143
185
  "isStriped",
144
186
  "TS4114",
145
187
  "distinctValuesOf"
146
- ]
188
+ ],
189
+ "surface": "typescript",
190
+ "detect": [
191
+ "extends TableComponent",
192
+ "extends ",
193
+ "override "
194
+ ],
195
+ "verify": "A typecheck reports no TS4114 / TS2415 / TS2416 on any class extending a DS component; a subclass that overrode isStriped() reads an ABSOLUTE row index now."
147
196
  }
148
197
  ],
149
198
  "informational": [
@@ -178,27 +227,227 @@
178
227
  "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.",
179
228
  "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.",
180
229
  "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.",
181
- "WHAT YOU CAN NOW DELETE - 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.",
182
- "DELETE-LIST: if you have `.button.button.button { … }` or rules against `.v-outline` / `.c-secondary` -> `ds-button` reflects `[data-variant]` and `[data-color]` on the HOST. Use `ds-button[data-variant=\"outline\"]`",
183
- "DELETE-LIST: if you have `--radius-sm: 0` to square a checkbox -> `--ds-checkbox-radius`",
184
- "DELETE-LIST: if you have `.title.title { font-size }` inside a modal -> `--ds-modal-title-font-size`",
185
- "DELETE-LIST: if you have Pagination label type overrides -> `--ds-pagination-label-*`",
186
- "DELETE-LIST: if you have `.size { display: none }` on a pager -> `[showPageSize]=\"false\"` — and it is now forwarded through `ds-table` too",
187
- "DELETE-LIST: if you have `.actions:empty { display: none }` on a modal -> The library already ships it",
188
- "DELETE-LIST: if you have `--ds-modal-divider: transparent`, plus whatever you rewrote the modal padding to afterwards -> `[dividers]=\"false\"` — it drops the rules *and* the padding that existed to clear them",
189
- "DELETE-LIST: if you have A defensive hover rule on the selected dropdown row -> The `:not(.is-selected)` branch already handles it",
190
- "DELETE-LIST: if you have `ds-menu-divider { padding: 0 }` -> `--ds-menu-divider-spacing`, which already defaults to 0",
191
- "DELETE-LIST: if you have A dozen scattered `--ds-*-radius: 0` -> For a fully square brand, four lines: `--radius-sm/md/lg/xl: 0` (leave `--radius-pill`). Measured — the three ROLES alone leave options, clear buttons and dropdown panels rounded; they are the tool for squaring one family and keeping another. Worked example on the Theming page",
192
- "DELETE-LIST: if you have A global rule squaring `.ds-overlay-pane` -> Radius and elevation roles now travel onto portaled panes when the host overrides them",
193
- "DELETE-LIST: if you have Absolutely positioning a search glyph over an autocomplete, or hiding `.autocomplete-chevron` -> `dsAutocompletePrefix` and `[showChevron]=\"false\"`",
194
- "DELETE-LIST: if you have Querying the autocomplete's inner `<input>` and dispatching a synthetic `input` event to clear it -> `clear()`",
195
- "DELETE-LIST: if you have A hand-built KPI tile whose value is a badge -> `ds-stat` takes a projected `[dsStatValue]`",
196
- "DELETE-LIST: if you have A pinned `--ds-search-height` (or any sibling) to get a shorter control row -> `density=\"compact\"` on the container — every field control is 32px there, measured",
197
- "DELETE-LIST: if you have A hand-rolled `.scrim` + `.panel` dialog, written because the modal header could not hold a badge or a second line -> `ds-modal` projects `[title-badge]` and takes a `subtitle`. You get back the focus trap, focus restore, the scroll lock, Escape and the footer",
198
- "DELETE-LIST: if you have `[value]=\"f.x().value()\" (valueChange)=\"f.x().value.set($event)\"` on every field of a signal form -> `[formField]=\"f.x\"` — the control implements the contract already",
199
- "DELETE-LIST: if you have `white-space: normal` forced onto a badge in a table cell -> `--ds-badge-white-space`",
200
- "DELETE-LIST: if you have `::ng-deep .card { height: 100% }` for equal-height cards -> The card's box fills a stretched host on its own",
201
- "DELETE-LIST: if you have `!important` on `ds-table` cell padding under `density=\"compact\"` -> Compact no longer out-specifies the padding hooks",
202
- "DELETE-LIST: if you have A wrapper around `ds-table` for sort/range announcements, keyboard column resize, or a header filter the checklist cannot express -> All three ship: the live region, the `role=\"separator\"` handle, and `dsHeaderFilter`"
230
+ "WHAT YOU CAN NOW DELETE - 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."
231
+ ],
232
+ "deleteList": [
233
+ {
234
+ "id": "button-variant-class-selectors",
235
+ "surface": "style",
236
+ "find": [
237
+ ".button.button.button",
238
+ ".v-outline",
239
+ ".c-secondary"
240
+ ],
241
+ "why": "`.button.button.button { … }` or rules against `.v-outline` / `.c-secondary`",
242
+ "replaceWith": "`ds-button` reflects `[data-variant]` and `[data-color]` on the HOST. Use `ds-button[data-variant=\"outline\"]`"
243
+ },
244
+ {
245
+ "id": "checkbox-squared-by-radius-token",
246
+ "surface": "style",
247
+ "find": [
248
+ "--radius-sm: 0"
249
+ ],
250
+ "why": "`--radius-sm: 0` to square a checkbox",
251
+ "replaceWith": "`--ds-checkbox-radius`"
252
+ },
253
+ {
254
+ "id": "modal-title-font-size-override",
255
+ "surface": "style",
256
+ "find": [
257
+ ".title.title",
258
+ ".modal .title"
259
+ ],
260
+ "why": "`.title.title { font-size }` inside a modal",
261
+ "replaceWith": "`--ds-modal-title-font-size`"
262
+ },
263
+ {
264
+ "id": "pagination-label-type-overrides",
265
+ "surface": "style",
266
+ "find": [
267
+ "ds-pagination",
268
+ "--ds-pagination-label"
269
+ ],
270
+ "why": "Pagination label type overrides",
271
+ "replaceWith": "`--ds-pagination-label-*`"
272
+ },
273
+ {
274
+ "id": "pager-size-select-hidden",
275
+ "surface": "style",
276
+ "find": [
277
+ ".size",
278
+ "display: none"
279
+ ],
280
+ "why": "`.size { display: none }` on a pager",
281
+ "replaceWith": "`[showPageSize]=\"false\"` — and it is now forwarded through `ds-table` too"
282
+ },
283
+ {
284
+ "id": "modal-empty-actions-hidden",
285
+ "surface": "style",
286
+ "find": [
287
+ ".actions:empty"
288
+ ],
289
+ "why": "`.actions:empty { display: none }` on a modal",
290
+ "replaceWith": "The library already ships it"
291
+ },
292
+ {
293
+ "id": "modal-divider-transparent-plus-padding",
294
+ "surface": "style",
295
+ "find": [
296
+ "--ds-modal-divider",
297
+ "!important"
298
+ ],
299
+ "why": "`--ds-modal-divider: transparent`, plus whatever you rewrote the modal padding to afterwards",
300
+ "replaceWith": "`[dividers]=\"false\"` — it drops the rules *and* the padding that existed to clear them"
301
+ },
302
+ {
303
+ "id": "dropdown-selected-row-hover-guard",
304
+ "surface": "style",
305
+ "find": [
306
+ "is-selected",
307
+ ":hover"
308
+ ],
309
+ "why": "A defensive hover rule on the selected dropdown row",
310
+ "replaceWith": "The `:not(.is-selected)` branch already handles it"
311
+ },
312
+ {
313
+ "id": "menu-divider-padding-zero",
314
+ "surface": "style",
315
+ "find": [
316
+ "ds-menu-divider",
317
+ "padding: 0"
318
+ ],
319
+ "why": "`ds-menu-divider { padding: 0 }`",
320
+ "replaceWith": "`--ds-menu-divider-spacing`, which already defaults to 0"
321
+ },
322
+ {
323
+ "id": "scattered-radius-zero-overrides",
324
+ "surface": "style",
325
+ "find": [
326
+ "-radius: 0"
327
+ ],
328
+ "why": "A dozen scattered `--ds-*-radius: 0`",
329
+ "replaceWith": "For a fully square brand, four lines: `--radius-sm/md/lg/xl: 0` (leave `--radius-pill`). Measured — the three ROLES alone leave options, clear buttons and dropdown panels rounded; they are the tool for squaring one family and keeping another. Worked example on the Theming page"
330
+ },
331
+ {
332
+ "id": "overlay-pane-squared-globally",
333
+ "surface": "style",
334
+ "find": [
335
+ ".ds-overlay-pane"
336
+ ],
337
+ "why": "A global rule squaring `.ds-overlay-pane`",
338
+ "replaceWith": "Radius and elevation roles now travel onto portaled panes when the host overrides them"
339
+ },
340
+ {
341
+ "id": "autocomplete-prefix-and-chevron-hacks",
342
+ "surface": [
343
+ "template",
344
+ "style"
345
+ ],
346
+ "find": [
347
+ ".autocomplete-chevron",
348
+ "position: absolute"
349
+ ],
350
+ "why": "Absolutely positioning a search glyph over an autocomplete, or hiding `.autocomplete-chevron`",
351
+ "replaceWith": "`dsAutocompletePrefix` and `[showChevron]=\"false\"`"
352
+ },
353
+ {
354
+ "id": "autocomplete-synthetic-input-clear",
355
+ "surface": "typescript",
356
+ "find": [
357
+ "new Event('input'",
358
+ "dispatchEvent",
359
+ "querySelector"
360
+ ],
361
+ "why": "Querying the autocomplete's inner `<input>` and dispatching a synthetic `input` event to clear it",
362
+ "replaceWith": "`clear()`"
363
+ },
364
+ {
365
+ "id": "hand-built-kpi-tile",
366
+ "surface": "template",
367
+ "find": [
368
+ "ds-stat",
369
+ "kpi",
370
+ "ds-badge"
371
+ ],
372
+ "why": "A hand-built KPI tile whose value is a badge",
373
+ "replaceWith": "`ds-stat` takes a projected `[dsStatValue]`"
374
+ },
375
+ {
376
+ "id": "search-height-pinned-for-a-short-row",
377
+ "surface": "style",
378
+ "find": [
379
+ "--ds-search-height",
380
+ "density="
381
+ ],
382
+ "why": "A pinned `--ds-search-height` (or any sibling) to get a shorter control row",
383
+ "replaceWith": "`density=\"compact\"` on the container — every field control is 32px there, measured"
384
+ },
385
+ {
386
+ "id": "hand-rolled-scrim-panel-dialog",
387
+ "surface": [
388
+ "template",
389
+ "style"
390
+ ],
391
+ "find": [
392
+ ".scrim",
393
+ ".panel"
394
+ ],
395
+ "why": "A hand-rolled `.scrim` + `.panel` dialog, written because the modal header could not hold a badge or a second line",
396
+ "replaceWith": "`ds-modal` projects `[title-badge]` and takes a `subtitle`. You get back the focus trap, focus restore, the scroll lock, Escape and the footer"
397
+ },
398
+ {
399
+ "id": "signal-form-field-wiring",
400
+ "surface": "template",
401
+ "find": [
402
+ ".value.set($event)",
403
+ "(valueChange)=\"f."
404
+ ],
405
+ "why": "`[value]=\"f.x().value()\" (valueChange)=\"f.x().value.set($event)\"` on every field of a signal form",
406
+ "replaceWith": "`[formField]=\"f.x\"` — the control implements the contract already"
407
+ },
408
+ {
409
+ "id": "badge-wrapping-in-a-cell",
410
+ "surface": "style",
411
+ "find": [
412
+ "white-space: normal",
413
+ "ds-badge"
414
+ ],
415
+ "why": "`white-space: normal` forced onto a badge in a table cell",
416
+ "replaceWith": "`--ds-badge-white-space`"
417
+ },
418
+ {
419
+ "id": "equal-height-card-deep-rule",
420
+ "surface": "style",
421
+ "find": [
422
+ "::ng-deep .card",
423
+ "height: 100%"
424
+ ],
425
+ "why": "`::ng-deep .card { height: 100% }` for equal-height cards",
426
+ "replaceWith": "The card's box fills a stretched host on its own"
427
+ },
428
+ {
429
+ "id": "compact-cell-padding-important",
430
+ "surface": "style",
431
+ "find": [
432
+ "!important",
433
+ "density="
434
+ ],
435
+ "why": "`!important` on `ds-table` cell padding under `density=\"compact\"`",
436
+ "replaceWith": "Compact no longer out-specifies the padding hooks"
437
+ },
438
+ {
439
+ "id": "table-wrapper-for-a11y-and-filters",
440
+ "surface": [
441
+ "typescript",
442
+ "template"
443
+ ],
444
+ "find": [
445
+ "aria-live",
446
+ "role=\"separator\"",
447
+ "ds-table"
448
+ ],
449
+ "why": "A wrapper around `ds-table` for sort/range announcements, keyboard column resize, or a header filter the checklist cannot express",
450
+ "replaceWith": "All three ship: the live region, the `role=\"separator\"` handle, and `dsHeaderFilter`"
451
+ }
203
452
  ]
204
453
  }
@@ -65,6 +65,63 @@ non-target occurrences the finder will later drop:
65
65
  Rule of thumb: a hint that risks a false *negative* (missed usage) is worse than one that risks a
66
66
  false *positive* (the finder/recheck discard those cheaply).
67
67
 
68
+ ## Detectability (the false-NEGATIVE guard): `surface`, `detect`, `verify`
69
+
70
+ The scope rules above stop an item matching code it does not own. These stop the opposite, which is
71
+ worse because it is silent: an entry that is correct, complete, unambiguous — and locates nothing.
72
+
73
+ mm-broker walked 0.6.0 → 0.10.1 with this plugin (2026-08-21) and a review afterwards found two
74
+ entries the loop had passed over without a word. Both are worth knowing by heart, because neither
75
+ looks defective:
76
+
77
+ > `0.7.1#table-sortkey-non-null-when-unsorted` — `old: "ds-table[sortKey]"`, hints `sortKey`,
78
+ > `sortDir`, `sortChange`. The code that breaks is the consumer's OWN store:
79
+ > `sorting: store.sortKey() ? { path: store.sortKey()!, order: store.sortDir() ?? 'Asc' } : undefined`.
80
+ > It binds no `sortKey` on the element — nobody does; the key arrives through `(sortChange)` — so the
81
+ > element-scoped `old` matched **nowhere**, the finder returned zero hits, the orchestrator recorded
82
+ > *not applicable*, and the recheck's clean grep CONFIRMED that verdict. Three server-paged screens
83
+ > kept ordering by a column whose header showed no sort.
84
+
85
+ > `0.7.1#field-reserve-message-default-off` — the sentence that mattered ("consumers that had
86
+ > written `[reserveMessage]="false"` to opt OUT can delete those bindings") sat at word 150 of a
87
+ > 200-word note, with no delete entry to act on. Three dead bindings survived the upgrade.
88
+
89
+ - **`surface` is required on every item, and `none` is an answer.** Say which artifact of the
90
+ consumer's changes: `template`, `typescript`, `style`, `config`, or `none` when the only action is
91
+ to look at a screen. An array is legal where a change genuinely spans two (`["template",
92
+ "typescript"]` for a value remap whose values also come from a typed field). A missing `surface`
93
+ and a deliberate `none` must never read the same to a finder — that ambiguity is what let a
94
+ TypeScript-surface item be searched as a template item.
95
+ - **`detect` carries the CONSUMER's shapes, not ours.** Once a `behavior` item's surface reaches
96
+ their `typescript` or their app `config`, `old` and `searchHints` stop being enough: our symbol
97
+ names appear in their templates and not in the logic that has to change. (A `style` surface is the
98
+ exception — in a stylesheet they write our token names verbatim, so `--ds-search-height` is already
99
+ the locator.) Write the shapes the way they write them —
100
+ `orderBy: sortKey`, `sortKey() ?`, `?? config.control?.size`, `protected clear(` — and expect them
101
+ to be imperfect; they are recall seeds for a semantic pass, not a find/replace.
102
+ - **`verify` is the positive assertion.** For a rename, "the old name is gone" is proof. For a
103
+ behaviour change there was never a symbol to remove, so the recheck has nothing to grep and
104
+ reports success by default. Give it the sentence it can actually test: *"every place that turns
105
+ (sortChange) into a query gates on the direction, not the key"*. If you cannot write that sentence,
106
+ the item is not yet understood well enough to ship.
107
+ - **A missing item is worse than a noisy one.** The scope rules trade a false positive for cheap
108
+ discard work; these trade a false negative for the same. When in doubt, name the surface widely and
109
+ let the semantic pass narrow it.
110
+
111
+ ## Supersession: name the item you reverse
112
+
113
+ A default flipped in one release and flipped back in the next reads as two independent instructions,
114
+ and a consumer walking the chain does the first release's work and then undoes it — or, if they skip
115
+ a version (0.9.0 was skipped entirely by one consumer going 0.8.0 → 0.9.1), acts on guidance that no
116
+ longer holds. `0.8.0#table-client-sort-replaced-by-sort-mode` told consumers unset now resolves to
117
+ `'client'` and that a server-paged table must declare `"server"`; `0.9.0#table-sort-filter-mode-default-server`
118
+ made unset mean `'server'` again.
119
+
120
+ So the later item carries `supersedes: ["0.8.0#table-client-sort-replaced-by-sort-mode"]` and the
121
+ earlier one `supersededBy: ["0.9.0#table-sort-filter-mode-default-server"]`. Both directions, because
122
+ both readers exist. `tools/migration-lint.mjs` resolves every reference, so a typo or a renamed id
123
+ fails the release rather than pointing at nothing.
124
+
68
125
  ## `value-remap` map conventions
69
126
 
70
127
  - **Key = old VALUE. Value = the FULL replacement of the whole `attr="oldValue"` token** (or `null`
@@ -81,13 +138,37 @@ false *positive* (the finder/recheck discard those cheaply).
81
138
  - **Dynamic bindings.** If the changelog moves values to a different attribute, say in `note` that
82
139
  `[attr]="expr"` bindings and any method/field/type supplying old values must be rebound/retyped too.
83
140
 
84
- ## Default-value changes get their OWN entry
141
+ ## Default-value changes get their OWN entry, and they carry TWO facts
85
142
 
86
143
  A changed default is invisible in a diff, so it hides. Give it a dedicated item (usually `behavior`),
87
- worded **"was X, now Y, restore via Z"** with the literal restore snippet. Do NOT bury it inside a
144
+ worded **"was X, now Y, restore via Z"** with the literal restore snippet in the `restore` field —
145
+ `null` there when there is genuinely no way back, never an absent field. Do NOT bury it inside a
88
146
  rename entry. (E.g. a button size default moving `l`→`md`, or a hue default moving to a new palette
89
147
  family with "point the channel back at `--primary-h/s/l` to keep the old look".)
90
148
 
149
+ **The second fact is what the flip made REDUNDANT, and it belongs in `deleteList`, not in the note.**
150
+ A default that moves to what half the consumers were already writing turns their binding into a
151
+ restatement — `[reserveMessage]="false"` against a default of `false`, `sortMode="server"` against a
152
+ default of `'server'`. 0.7.1 put that sentence in the note and three dead bindings survived the
153
+ upgrade; the delete entry is what a finder can run. The linter flags a default-change note with no
154
+ `restore`, and a `deleteList` you can write and did not is the failure it cannot see — so write it.
155
+
156
+ ## A `deleteList` entry is a find, a why, and a replacement
157
+
158
+ `{ id, surface, find, why, replaceWith }`. The whole value is in `find`: the shape in the CONSUMER's
159
+ code, written the way they wrote it, a string or an array of them (`["ds-table tr:hover",
160
+ "::ng-deep ds-table"]`). `why` says what made it unnecessary — a hook that already existed, a default
161
+ that moved, an API that became public. `replaceWith` names the API that replaces it, or the literal
162
+ word "nothing" where the answer is simply to delete.
163
+
164
+ Two things to get right, both learned from the 45 prose entries that nothing acted on:
165
+
166
+ - **Never a bare token as the `find`.** `--ds-menu-item-radius` is OUR name for the fix; their code
167
+ says `ds-menu-divider { padding: 0 }`. Grep-ability decides whether the entry exists in practice.
168
+ - **Say when the workaround is still legitimate.** `[reserveMessage]="false"` is dead under the new
169
+ default and load-bearing under a `dsReserveMessages` host — the entry that omits that turns a
170
+ cleanup into a regression.
171
+
91
172
  ## Changes that aren't a clean find/replace
92
173
 
93
174
  - **One-old-maps-to-many-new** (a semantic rename where the replacement depends on context): classify
@@ -108,6 +189,7 @@ family with "point the channel back at `--primary-h/s/l` to keep the old look".)
108
189
  | new code the consumer must ADD | `code-add` (snippet in `new`, site in `note`, `searchHints` locate it) |
109
190
  | API removed WITH a replacement path | `removed-api` |
110
191
  | needs a code edit but not a find/replace (wrap, restructure, changed default/timing/event payload) | `behavior` |
192
+ | type of an existing exported member widened or changed | `behavior` (see the widening rule below) |
111
193
  | documented but needs NO consumer code edit (additive / visual-only / internal) | NOT an item → `informational` |
112
194
 
113
195
  **Catch-all:** if you can't confidently fit a breaking/changed entry to a mechanical kind, make it
@@ -139,22 +221,53 @@ resolution: rename the subclass's own member, or add `override` where the base's
139
221
  match. Keep the feature bullets themselves in `informational` — the item is the collision, not the
140
222
  feature.
141
223
 
142
- **Do not compile that list by eye — run `npm run class-surface`.** It diffs the exported member
143
- surface between the last tag and HEAD and prints it per class. Twice now the list was assembled by
144
- reading the diff and twice it was wrong in a way a consumer found first: 0.8.0 named the public
145
- additions but not the private `saveLayout` that broke their build, and 0.9.0 shipped with no entry
146
- while sixteen classes had grown. Two things the tool cannot see, so check them by hand: a member
147
- whose SIGNATURE changed (same name, so it compiles and then misbehaves — `TableComponent.isStriped()`
148
- went window-relative to absolute) and a member that moved to a base class.
224
+ **Widening an exported type is actionable, and it will not look it.** A field on an exported
225
+ interface going `number` → `number | 'content'`, an input going `boolean` → `boolean | null`, a
226
+ returned union growing a member — each is source-compatible for whoever WRITES the value and
227
+ breaking for whoever READS it back (`sum += col.width` → TS2365) or overrides it in a subclass
228
+ (the `equal` position of `InputSignalWithTransform` is invariant, so TS2416 fires even when the
229
+ values are compatible). That asymmetry is exactly why release notes describe a widening as a new
230
+ capability: 0.10.0 shipped two of these with nothing actionable in the manifest, and the
231
+ consumer's type-checker was the only finder — firing only after the bump was already installed.
232
+ Emit a `behavior` entry per widened type naming who breaks (readers and overriders — not the
233
+ writers, who are fine), with the resolution in the `note`: usually "handle the new union member
234
+ where the field is read back", with the literal old → new type.
235
+
236
+ **Do not compile either list by eye — run `npm run class-surface`.** It diffs the exported surface
237
+ between the last tag and HEAD (`[base] [head]` overrides both ends) and prints it per class:
238
+ gained/lost member names AND changed types — annotated fields, `input`/`model`/`output`
239
+ initializers, exported interface members, type aliases and `extends` clauses. Twice the names list
240
+ was assembled by reading the diff and twice it was wrong in a way a consumer found first (0.8.0's
241
+ private `saveLayout`, 0.9.0's sixteen grown classes); the type diff exists because 0.10.0 then
242
+ shipped two widenings the same way. What it still cannot see, so check by hand: a member whose
243
+ BEHAVIOR changed under an unchanged signature (`TableComponent.isStriped()` went window-relative
244
+ to absolute), and a CLASS member that moved to a base class (interface members that move get a
245
+ "check the base" hint).
149
246
 
150
247
  ## Per-entry checklist
151
248
 
152
- - [ ] `id` is a stable, unique kebab slug.
249
+ Run `npm run migration-lint` before you call the manifest done — it mechanises the lines marked
250
+ (lint) below, and a release cannot be cut past it. The rest are judgment the linter cannot make.
251
+
252
+ - [ ] `id` is a stable, unique kebab slug. (lint)
153
253
  - [ ] `old`/`new`/`searchHints` are exact code strings; element-scoped as `element[attr]` where shared.
154
- - [ ] `kind` correct; `map` present iff `value-remap`; `new: null` for removals & `behavior`.
254
+ - [ ] `kind` correct; `map` present iff `value-remap`; `new: null` for `behavior`. (lint)
255
+ - [ ] `surface` says which of the consumer's artifacts changes — `none` where nothing does. (lint)
256
+ - [ ] `detect` carries the consumer's own shapes wherever the affected code names no DS symbol; an
257
+ item whose every locator is a DS name while its surface is not the template fails the lint.
258
+ - [ ] `verify` states the positive assertion for every `behavior` / `removed-api` entry — what a
259
+ recheck can test when there is no old symbol to find. (lint)
155
260
  - [ ] `value-remap` map: full-token replacements, only changed values listed, identities map to self.
156
261
  - [ ] Pattern/prefix items state coverage AND exclusions in `note`.
157
- - [ ] Default-value / timing / event-payload changes are their own `behavior` entry with restore info.
262
+ - [ ] Default-value / timing / event-payload changes are their own `behavior` entry, with `restore`
263
+ (or an explicit `null`) AND a `deleteList` entry for whatever the flip made redundant. (lint,
264
+ for the `restore` half)
265
+ - [ ] An entry that reverses an earlier release's guidance links it both ways — `supersedes` here,
266
+ `supersededBy` there. (lint, for the references resolving)
158
267
  - [ ] Substring-colliding renames: longer has its own entry; shorter's `note` says "rename longer first".
159
268
  - [ ] Non-mechanical entries carry the decision rule + where to read the real new name, not "review".
269
+ - [ ] Widened/changed exported types each have a `behavior` entry naming who breaks
270
+ (run `npm run class-surface` — do not assemble the list by eye).
271
+ - [ ] `deleteList` holds every "you can now delete X" — with a greppable `find`, not our token name,
272
+ and a word on when the workaround is still legitimate. (lint, for the shape)
160
273
  - [ ] Nothing documented in the block is silently dropped (actionable → item; else → `informational`).