@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.
@@ -8,7 +8,15 @@ One file per released version — `migrations/<version>.json` — mirroring that
8
8
  { "version": "X.Y.Z",
9
9
  "items": [ { "id": "<stable-kebab-slug>", "kind": "<kind>", "old": "...", "new": "... | null",
10
10
  "note": "<concrete consumer migration steps>", "searchHints": ["..."],
11
- "map": { "<oldValue>": "<full replacement token | null>" } } ],
11
+ "map": { "<oldValue>": "<full replacement token | null>" },
12
+ "surface": "template | typescript | style | config | none (or an array of them)",
13
+ "detect": ["<shape written the way the CONSUMER writes it>", "..."],
14
+ "verify": "<the positive assertion that proves this landed>",
15
+ "restore": "<literal snippet that brings the old behaviour back | null>",
16
+ "supersedes": ["<version>#<id>"] } ],
17
+ "deleteList": [ { "id": "<slug>", "surface": "<surface>", "find": ["<shape>", "..."],
18
+ "why": "<what made it unnecessary>",
19
+ "replaceWith": "<the API that replaces it>" } ],
12
20
  "informational": [ "<one-line FYI per non-actionable change group>" ] }
13
21
  ```
14
22
 
@@ -18,6 +26,24 @@ One file per released version — `migrations/<version>.json` — mirroring that
18
26
  `attr="oldValue"` token, `null` to drop the attribute; a value mapping to itself is still valid;
19
27
  a value absent from the map is undocumented-as-changed and must be left untouched.
20
28
  - `old` of an element-scoped item is `element[attr]`.
29
+ - **`surface`** — which of the consumer's artifacts changes: their `template`, their `typescript`,
30
+ their `style`, their app `config`, or `none` when the only action is to LOOK. It is a required
31
+ statement, not a hint: `none` and "the author forgot" must not read the same to a finder.
32
+ - **`detect`** — the shapes to grep for when `old` is a DS symbol the affected code never mentions.
33
+ Written the way the consumer writes it (`orderBy: sortKey`, `?? config.control?.size`), not the
34
+ way we do. Mandatory on a `behavior` / `removed-api` item whose surface includes `typescript` or
35
+ `config`; a `style` surface is exempt, because there the consumer writes our token names verbatim
36
+ and `--ds-search-height` IS the locator.
37
+ - **`verify`** — the positive assertion that proves the migration landed, for the items where
38
+ "the old symbol is gone" proves nothing because there was never a symbol to remove.
39
+ - **`restore`** — the literal snippet that brings the old behaviour back on a changed default, or an
40
+ explicit `null` when there is no way back.
41
+ - **`supersedes`** — `<version>#<id>`, declared on the item that REVERSES an earlier one. It points
42
+ BACKWARD only. An upgrade walks one version at a time and each manifest is frozen when the next is
43
+ 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
45
+ item, which is the one an upgrade reaches second.
46
+ - **`deleteList`** — the structured form of "what you can now delete" (see below).
21
47
 
22
48
  **Why:** the auto-update plugin reads the prose changelog with an LLM planner — correct, but
23
49
  re-derived on every consumer run. A shipped manifest makes the plan deterministic: the planner
@@ -35,8 +61,8 @@ See `AUTHORING.md` for how to write a good entry.
35
61
  plugin loads `<version>.json`, and the only content the manifest did not already carry was the
36
62
  delete-list. Worse, it went stale inside one release — three late changes never reached it — and a
37
63
  stale duplicate misleads where no file would merely be silent. Its content now lives in the two
38
- places that ARE read: the `DELETE-LIST:` entries in `<version>.json`, and a "What you can now
39
- DELETE" table in that version's CHANGELOG block.
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.
40
66
 
41
67
  **A sibling folder `migrations/<version>/*.md` is still legal for the rare case a `note` genuinely
42
68
  cannot hold** — a worked before/after with code on both sides, like `migrations/0.5.1/badge-statuses.md`.
@@ -49,8 +75,39 @@ CHANGELOG instead.
49
75
  Two dogfooding audits (mm-ecm 08-06, mm-broker 08-07) read consumer stylesheets as a record of what
50
76
  this library made them write, and both found the same thing — most workarounds were written against
51
77
  hooks that ALREADY existed, because a release note says what broke and never says what became
52
- unnecessary. Ship those as `DELETE-LIST: if you have <X> -> <why it can go>` entries in
53
- `informational`; 0.9.0 has 21 of them and is the shape to follow.
78
+ unnecessary.
79
+
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
86
+ CONSUMER's code, a string or an array of them — and keep the human copy in that version's CHANGELOG
87
+ "What you can now DELETE" table. Two copies, each read by someone; the third copy in `informational`
88
+ is the one that goes stale, so new manifests do not carry it.
89
+
90
+ **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:
94
+
95
+ - `0.7.1#table-sortkey-non-null-when-unsorted` named `ds-table[sortKey]` as `old`, and every
96
+ `searchHint` named the DS. What breaks is the host's own store code —
97
+ `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.
100
+ - `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.
103
+
104
+ Hence `surface`, `detect`, `verify` and `restore`: say WHERE the consumer's code changes, what that
105
+ 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.
54
111
 
55
112
  **Authoring:** drafted at release time alongside the CHANGELOG entry (the `/changelog` workflow
56
113
  drafts it from the release diff; the release author reviews). The prose changelog stays canonical
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ids-group-ltd/ids-design-system",
3
- "version": "0.10.0",
3
+ "version": "0.10.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/",
@@ -4,6 +4,8 @@
4
4
  // `panelClass: 'ds-dropdown-panel'` on the overlay config; this partial
5
5
  // declares the matching rules so the portaled panel renders styled.
6
6
 
7
+ @use 'text-clip' as text-clip;
8
+
7
9
  .ds-dropdown-panel {
8
10
  /* The selected row used to paint straight from the theme roles, so a brand that
9
11
  wanted a different selected treatment had to RETARGET --primary-* inside this
@@ -101,9 +103,8 @@
101
103
  .option-label {
102
104
  flex: 1;
103
105
  min-width: 0;
104
- overflow: hidden;
105
- text-overflow: ellipsis;
106
- white-space: nowrap;
106
+
107
+ @include text-clip.single-line-ellipsis;
107
108
  }
108
109
 
109
110
  .option-check {
@@ -25,5 +25,14 @@
25
25
  box-shadow: none;
26
26
  outline: 0;
27
27
  }
28
+
29
+ /* The GROUP owns the ring for the whole row, so nothing inside a segment may
30
+ draw one: styles/_focus.scss gives every focusable a box-shadow at zero
31
+ specificity, and the block above only clears it from the segment BOX — the
32
+ native input inside it kept its own, so a field group painted two rings, a
33
+ tight one around the control and the halo around the row. */
34
+ :where(:focus-visible) {
35
+ box-shadow: none;
36
+ }
28
37
  }
29
38
  }
@@ -18,6 +18,12 @@
18
18
  // Base indicator for anything focusable that styles none itself, so it cannot fall
19
19
  // through to the browser default. `:where()` keeps it at ZERO specificity, so every
20
20
  // component and app rule still wins.
21
+ //
22
+ // CONSEQUENCE for a control the user focuses INSIDE a ringed shell: the shell must
23
+ // silence the inner element, because a shadow is what this rule sets and `outline: 0`
24
+ // cannot cancel a shadow — leave it and the field paints two rings, one round the inner
25
+ // control and one round the box. The shells that do it: autocomplete, date-picker,
26
+ // field-group, number-stepper, search.
21
27
  :where(:focus-visible) {
22
28
  outline: none;
23
29
  box-shadow: var(--ds-control-focus-shadow);
@@ -43,6 +49,16 @@
43
49
  var(--error);
44
50
  }
45
51
 
52
+ // The one style NOT pinned to :root: a clipping ancestor is a local problem, so this
53
+ // attribute works wherever it is set and inherits into the subtree. Put it on the
54
+ // clipping element and everything inside keeps an indicator instead of losing it.
55
+ [data-focus='inset'] {
56
+ --ds-field-focus-shadow: var(--focus-ring-inset);
57
+ --ds-field-focus-shadow-error: var(--focus-ring-inset-error);
58
+ --ds-control-focus-shadow: var(--focus-ring-inset);
59
+ --ds-control-focus-shadow-error: var(--focus-ring-inset-error);
60
+ }
61
+
46
62
  :root[data-focus='outline'] {
47
63
  --ds-field-focus-shadow: none;
48
64
  --ds-field-focus-shadow-error: none;
@@ -0,0 +1,17 @@
1
+ // Single-line text that truncates with an ellipsis. Mixin-only, so it is NOT
2
+ // forwarded from `ds.scss` — components `@use` it directly, like `chip-row`.
3
+
4
+ @mixin single-line-ellipsis {
5
+ /* `clip` with a margin, not `hidden`: an ellipsis box needs a non-`visible`
6
+ overflow, and where the line box is tighter than the font's glyph box that
7
+ overflow eats the glyph. Mulish measures 1.257em, so --line-height-flat (1)
8
+ and -tight (1.1) are both under it — at 14px the shave was 2.13px above the
9
+ cap line and 1.47px below the baseline, on EVERY label, not only the ones
10
+ with descenders (MBP-245). The margin returns that room without moving any
11
+ geometry, and `text-overflow` reads any non-`visible` overflow, so the
12
+ ellipsis still applies. */
13
+ overflow: clip;
14
+ overflow-clip-margin: var(--space-1);
15
+ text-overflow: ellipsis;
16
+ white-space: nowrap;
17
+ }
@@ -217,8 +217,6 @@
217
217
  Each token has a real consumer in the codebase; symmetric "unused"
218
218
  numeric stops are deliberately omitted. */
219
219
  --opacity-disabled: 0.5; /* full disabled state on interactive components */
220
- --opacity-muted: 0.6; /* legacy alias, no component reads it since the disabled
221
- states moved onto --text-disabled + --opacity-disabled */
222
220
  --opacity-text-disabled: 0.38; /* disabled text alpha (WCAG-derived) */
223
221
  --opacity-scrim: 0.55; /* modal/drawer backdrop overlay (light theme) */
224
222
  --opacity-state-hover: 0.08; /* hover layer over surface (overlay vs surface swap) */
@@ -203,9 +203,14 @@
203
203
  /* Focus rings.
204
204
  Outer halos use hsla() composed from brand/danger HSL channels
205
205
  so re-skinning --primary-h propagates into focus state.
206
- The inner halo reads --surface-canvas so the ring stays visible
207
- in both light and dark themes (canvas flips, ring adapts). */
208
- --focus-ring-inner: var(--surface-canvas);
206
+
207
+ The inner halo is TRANSPARENT, not a colour: its job is to separate the ring
208
+ from the element, so it has to match whatever is actually behind — which a
209
+ named surface only is when nothing intervenes. Painting --surface-canvas here
210
+ drew a dark rim around a white card in a dark app, reading as a rendering
211
+ artifact rather than a focus state. Transparent costs nothing on a canvas
212
+ ground (the same pixels show through) and is correct on every other. */
213
+ --focus-ring-inner: transparent;
209
214
  --focus-ring-outer-h: var(--primary-h);
210
215
  --focus-ring-outer-s: var(--primary-s);
211
216
  --focus-ring-outer-l: var(--primary-l);
@@ -221,6 +226,18 @@
221
226
  0 0 0 2px var(--focus-ring-inner),
222
227
  0 0 0 4px hsl(var(--error-h) var(--error-s) var(--error-l) / 100%);
223
228
 
229
+ /* Same ring drawn INSIDE the border box, for a subtree under a clipping
230
+ ancestor. An outset shadow is outside the box, so any `overflow: hidden`
231
+ ancestor eats it and leaves the element focusable with no indicator at all —
232
+ and clipping is the normal way to hold a full-bleed child inside a rounded
233
+ card. Reached through `[data-focus="inset"]`, not by re-declaring the role. */
234
+ --focus-ring-inset:
235
+ inset 0 0 0 2px var(--focus-ring-inner),
236
+ inset 0 0 0 4px hsl(var(--focus-ring-outer-h) var(--focus-ring-outer-s) var(--focus-ring-outer-l) / var(--focus-ring-outer-alpha));
237
+ --focus-ring-inset-error:
238
+ inset 0 0 0 2px var(--focus-ring-inner),
239
+ inset 0 0 0 4px hsl(var(--error-h) var(--error-s) var(--error-l) / 100%);
240
+
224
241
  /* Field focus — coloured halo only (no double-ring). Derived from
225
242
  brand HSL so it tracks rebrand. Alpha is a token so dark themes
226
243
  can boost it for legibility. */