@ids-group-ltd/ids-design-system 0.10.1 → 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.
- package/CHANGELOG.md +374 -14
- package/components.md +68 -13
- package/fesm2022/ids-group-ltd-ids-design-system.mjs +350 -145
- package/fesm2022/ids-group-ltd-ids-design-system.mjs.map +1 -1
- package/migrations/0.10.0.json +420 -44
- package/migrations/0.10.1.json +80 -16
- package/migrations/0.10.2.json +482 -0
- package/migrations/0.2.0.json +32 -8
- package/migrations/0.3.0.json +19 -3
- package/migrations/0.4.0.json +50 -11
- package/migrations/0.5.0.json +93 -24
- package/migrations/0.5.1.json +106 -29
- package/migrations/0.6.0.json +2 -1
- package/migrations/0.6.2.json +33 -3
- package/migrations/0.6.3.json +19 -3
- package/migrations/0.7.0.json +77 -25
- package/migrations/0.7.1.json +84 -8
- package/migrations/0.8.0.json +46 -10
- package/migrations/0.9.0.json +284 -35
- package/migrations/AUTHORING.md +125 -12
- package/migrations/README.md +62 -5
- package/package.json +1 -1
- package/styles/_dropdown-overlay.scss +4 -3
- package/styles/_field-group-segment.scss +9 -0
- package/styles/_focus.scss +16 -0
- package/styles/_text-clip.scss +17 -0
- package/themes/_semantic.scss +20 -3
- package/types/ids-group-ltd-ids-design-system.d.ts +187 -68
package/CHANGELOG.md
CHANGED
|
@@ -8,6 +8,320 @@ While the package is on `0.x`, minor releases may contain breaking changes.
|
|
|
8
8
|
|
|
9
9
|
## Unreleased
|
|
10
10
|
|
|
11
|
+
## 0.10.2 — 2026-08-24
|
|
12
|
+
|
|
13
|
+
### Added
|
|
14
|
+
|
|
15
|
+
- **`TableColumn.interactive` — the cell that says WHICH text opens the record.** On a
|
|
16
|
+
`[rowInteractive]` table the whole row is the control, so the hover tint says "clickable" and
|
|
17
|
+
nothing says what the click leads to; a `cursor: pointer` does not name a target. Mark the column
|
|
18
|
+
`interactive: true` and its cell takes a link colour plus an underline while the row is hovered —
|
|
19
|
+
**both, never hue alone** — through `--ds-table-cell-link-color` (default `--accent`) and
|
|
20
|
+
`--ds-table-cell-link-decoration` (default `underline`). Off unless a column asks for it, and inert
|
|
21
|
+
on a passive table for the same reason the row tint is: nothing should promise a click that does not
|
|
22
|
+
happen. Four list screens in one consumer had written this as
|
|
23
|
+
`:host ::ng-deep ds-table tr:hover .cell-name { color: var(--accent); text-decoration: underline }`,
|
|
24
|
+
which was their last table reach that no token could replace.
|
|
25
|
+
|
|
26
|
+
- **`TableRowAction` can vary its items per row: `hidden` and `disabledReason`.** The contract could
|
|
27
|
+
only GREY an item that was always there, so a menu whose items swap by status — a draft offering Edit
|
|
28
|
+
+ Launch where a live record offers Revert + Delete — grew a permanently dead half on every row. That
|
|
29
|
+
is why the row-action column shipped in 0.6.3 and one consumer adopted it in **zero** of eleven row
|
|
30
|
+
menus. `hidden?: (row) => boolean` leaves the item out instead, and **a row with every item hidden
|
|
31
|
+
renders no kebab at all** rather than opening an empty menu. `disabledReason?: string | ((row) =>
|
|
32
|
+
string)` puts the why on the item's second line, read only when `disabled` returns true for that row —
|
|
33
|
+
a reason on a live item would read as a caveat on something that works.
|
|
34
|
+
|
|
35
|
+
- **`ds-menu-item` takes a `description` — a standing second line under the label.** For a limitation
|
|
36
|
+
the action carries ("only the first 1,000 rows", "read-only in this workspace"), visible without hover
|
|
37
|
+
or focus, which is what separates it from a `[dsTooltip]`. **It reaches assistive tech as
|
|
38
|
+
`aria-describedby`, not as part of the item's name:** the line is `aria-hidden` and referenced by id,
|
|
39
|
+
so the projected label alone names the action. Seven items across four files in one consumer
|
|
40
|
+
hand-rolled this with the same five-line rule; the width cap is now
|
|
41
|
+
`--ds-menu-item-description-max-width` instead of each app's own `14rem`.
|
|
42
|
+
|
|
43
|
+
- **`data-focus="inset"` — a focus style that survives a clipping ancestor.** The ring is a box-shadow
|
|
44
|
+
outside the border box, so any `overflow: hidden` ancestor ate it and left the element focusable with
|
|
45
|
+
**no indicator at all** — measured in four places in one app, one of them a `ds-button` inside a
|
|
46
|
+
wrapper that clips for its own animation. Clipping a card to hold a full-bleed child inside a rounded
|
|
47
|
+
corner is normal, and `ds-card` + `padding: none` invites exactly that. **Unlike the other four focus
|
|
48
|
+
styles this one is NOT pinned to `:root`:** a clip is a local problem, so the attribute works wherever
|
|
49
|
+
you set it and the declarations inherit into the subtree. Put it on the clipping element.
|
|
50
|
+
|
|
51
|
+
- **`ds-search.clear()` is public.** It empties the field, DROPS an armed keystroke and publishes `''`
|
|
52
|
+
at once — which writing `''` into `value` does not do: the effect watching `value` cancels the timer
|
|
53
|
+
only when the incoming text DIFFERS from what the control last pushed, so a host-owned Clear button
|
|
54
|
+
could not always drop the debounce it was clearing. Public for the same reason `focus()` is, and the
|
|
55
|
+
same button needs both.
|
|
56
|
+
|
|
57
|
+
- **`ds-search` binds to a form — both systems — and a disabled search now looks disabled.** It held a
|
|
58
|
+
value that nothing could bind: no `NG_VALUE_ACCESSOR`, so `[(ngModel)]`, a `formControlName` and a
|
|
59
|
+
signal form all slid off it while its own `[(value)]` kept working. It extends
|
|
60
|
+
`DsControlValueAccessor` now, like every other control that carries a value, and a new `disabled`
|
|
61
|
+
input folds together with the form's own disabled state. The shell paints the disabled surface from
|
|
62
|
+
the inner input's state, which it never did — a disabled search looked live and still took a click.
|
|
63
|
+
**Deliberately no label and no message row.** A toolbar filter is not a validated field, and giving
|
|
64
|
+
it the field chrome would restyle every toolbar it sits in; reach for `ds-input` where a search
|
|
65
|
+
needs a label.
|
|
66
|
+
|
|
67
|
+
- **`--ds-menu-radius` — the bare `ds-menu` corner, which two token descriptions already promised.**
|
|
68
|
+
The component hardcoded `var(--radius-md)` while `token-descriptions.json` referred to
|
|
69
|
+
`--ds-menu-radius` as though it were public; the dead-token audit caught it. Same default, so
|
|
70
|
+
nothing moves — this only makes the documented hook real. The panelled case stays separate: inside a
|
|
71
|
+
`ds-popover` the menu clips to `--ds-menu-clip-radius`, which the popover publishes.
|
|
72
|
+
|
|
73
|
+
### Changed
|
|
74
|
+
|
|
75
|
+
- **`ds-search` no longer takes the field message inputs, because it never rendered them.**
|
|
76
|
+
Since it gained form binding it extended `DsControlValueAccessor`, which sits on `DsFieldBase` — so
|
|
77
|
+
the API reference advertised `hint`, `error`, `warning`, `errors`, `invalid`, `touched`,
|
|
78
|
+
`reserveMessage` and `messageIcon` on a component whose template has no `ds-field-message` and whose
|
|
79
|
+
class reads none of them. **A consumer binding `error="Too short"` on a `ds-search` got silence, and
|
|
80
|
+
the reference had told them it would work.** Those eight inputs are gone from it now; the reference
|
|
81
|
+
lists the ten it actually implements.
|
|
82
|
+
**BREAKING only if you bound one:** it used to compile and do nothing, and now it is a template type
|
|
83
|
+
error, which is the point. Where a search needs a label or an error line, that is `ds-input` — a
|
|
84
|
+
toolbar filter is not a validated field, which is the same reasoning that kept the message row off it
|
|
85
|
+
in the first place.
|
|
86
|
+
**How the split works, since it is a shape other controls may want:** the `ControlValueAccessor`
|
|
87
|
+
plumbing is now `valueControlBridge()`, a function rather than a base class, so a control can bind to
|
|
88
|
+
a form without inheriting the message API. `DsControlValueAccessor` is that function plus
|
|
89
|
+
`DsFieldBase` and delegates to it, so the logic exists once rather than twice. `hidden` stayed on
|
|
90
|
+
`ds-search`: it belongs to the forms contract — signal forms reaches every control through it — not to
|
|
91
|
+
the message API.
|
|
92
|
+
- **A field's message line now carries a glyph for `error`, `warning` and `success` — and not for
|
|
93
|
+
`hint`.** Colour was the whole signal before, and in the light theme warning (#8A7400) against success
|
|
94
|
+
(#156822) is a hue apart and nothing else: WCAG 1.4.1 is about exactly that, and four of the six
|
|
95
|
+
systems audited for the fill question carry a per-state icon in the field. **`hint` deliberately stays
|
|
96
|
+
bare** — it is the resting text rather than a state, and it is the majority of rows on any real form
|
|
97
|
+
(25 of 43 on our own input page), so a glyph there is noise rather than signal.
|
|
98
|
+
**Per state, independently, app-wide:**
|
|
99
|
+
`provideDsConfig({ field: { stateIcons: { warning: false, hint: 'info' } } })` — a name replaces the
|
|
100
|
+
glyph, `false` removes it, each key is independent of the others, and **`stateIcons: false` is the one
|
|
101
|
+
line back to how fields looked before**. **Per field:** `messageIcon` wins over both —
|
|
102
|
+
`[messageIcon]="false"` drops the glyph on that field alone. It is declared once on the shared
|
|
103
|
+
field base, so it reaches all fifteen fields that render a message row.
|
|
104
|
+
**Two new hooks:** `--ds-field-message-icon-gap`, and `--ds-field-message-icon-offset`, which centres
|
|
105
|
+
the glyph on the FIRST line rather than the block — the row is `align-items: flex-start` now, so a
|
|
106
|
+
message that wraps keeps its glyph beside the first line instead of floating in the middle. The offset
|
|
107
|
+
defaults to a calc over the two tokens that set that line, so it survives a retuned message type.
|
|
108
|
+
**The size is not a token, on purpose:** `ds-icon` takes a number and writes `width`/`height`
|
|
109
|
+
attributes, so a CSS hook would mean reaching into another component's template. The glyph is 14px
|
|
110
|
+
(`--icon-sm`, under the 12px message text); making icon size CSS-driven is a separate change to
|
|
111
|
+
`ds-icon`.
|
|
112
|
+
- **`ds-stat`'s `value` takes `string | number | null`, so Angular's own pipes bind to it.**
|
|
113
|
+
`number`, `currency`, `percent` and `date` are all typed `string | null`, so
|
|
114
|
+
`[value]="count | number"` failed `strictTemplates` with TS2322 and consumers wrote
|
|
115
|
+
`count.toLocaleString('en-US')` in the template instead — which pins a locale rather than reading
|
|
116
|
+
`LOCALE_ID`, and re-runs on every change-detection pass where a pure pipe is cached. One consumer's
|
|
117
|
+
KPI row carries both idioms side by side for exactly this reason. `null` renders as nothing, like the
|
|
118
|
+
empty default, and the four pipes now have a demo on the docs page — which is also the test, since
|
|
119
|
+
that section compiles under `strictTemplates`.
|
|
120
|
+
|
|
121
|
+
- **If you EXTEND a DS component, eleven classes grew and six members changed type.** `npm run
|
|
122
|
+
class-surface` against 0.10.1: `DsFieldBase` (`messageIcon` — the state glyph, declared once for
|
|
123
|
+
every field rather than per component), `DsControlValueAccessor` (`bridge`),
|
|
124
|
+
`FieldMessageComponent` (`config`, `iconResolved`), `AutocompleteComponent` and
|
|
125
|
+
`MultiSelectComponent` (`chipsMode`, `showsEveryChip`), `MenuItemComponent` (`description`,
|
|
126
|
+
`descriptionId`), `SearchComponent` (the CVA surface it now declares itself: `bridge`,
|
|
127
|
+
`disabled`, `formDisabled`, `hidden`, `isDisabled`, `markTouched`, `registerOnChange`,
|
|
128
|
+
`registerOnTouched`, `setDisabledState`, `writeValue`), `SidenavItemComponent` (`rail`,
|
|
129
|
+
`railResolved`), `SidenavComponent` (`rail`), `TableComponent` (`actionReason`, `actionsFor`,
|
|
130
|
+
`hasActionsFor`, `visibleRowActions`) and `TimePickerComponent` (`insideATrigger`). A subclass
|
|
131
|
+
declaring any of those names now fails with TS4114 — or TS2415, since a redeclared private
|
|
132
|
+
collides just as a public one does, and a name on `DsFieldBase` reaches every field through it.
|
|
133
|
+
**Six members kept their name and changed type**, which is the case that compiles for a caller
|
|
134
|
+
and breaks an overrider: `maxVisibleChips` on both pickers (widened to
|
|
135
|
+
`number | 'fit' | 'all' | null`, default now `null`), `FieldMessageComponent.icon` (widened to
|
|
136
|
+
`IconName | false | null`, so `false` can mean "no glyph" against a state that supplies one),
|
|
137
|
+
`DsConfig.field` (its shape grew the glyph defaults), `SearchComponent.clear` (`protected` →
|
|
138
|
+
public), `StatComponent.value` (widened to `string | number | null`) and
|
|
139
|
+
`TimeColumnsComponent.onKey` (its parameter list changed). **What the report does NOT show:**
|
|
140
|
+
`ds-search` no longer extends the field base, so it loses eight inherited inputs — the tool
|
|
141
|
+
compares declarations per file and a dropped `extends` moves nothing, so that break is documented
|
|
142
|
+
in its own entry above and not here.
|
|
143
|
+
|
|
144
|
+
- **Every readback that resolves through `DS_CONFIG` is now public.** `sizeResolved` on fourteen
|
|
145
|
+
controls, plus `elevationResolved` / `paddingResolved` (card), `withDotResolved` (badge),
|
|
146
|
+
`borderedResolved` / `stickyScrollbarResolved` (table), `dividersResolved` (both modals),
|
|
147
|
+
`reserveMessageResolved` (every field), the picker locale/format resolvers, and
|
|
148
|
+
`brandName` / `letterGlyph` / `taglineText` (sidenav, auth-layout). They were `protected`, so the
|
|
149
|
+
migration path 0.10.0 published — "read `sizeResolved()` now that `size()` returns null when unbound"
|
|
150
|
+
— did not compile: reading one from a host, a test or a `viewChild` was TS2445.
|
|
151
|
+
**The line is `DS_CONFIG`, and it is deliberate.** A host cannot recompute an app-level default, so
|
|
152
|
+
that readback has to be public. Members a host CAN derive from its own bindings stay closed:
|
|
153
|
+
`invalidResolved`, `railResolved`, `sortModeResolved`, `filterModeResolved`.
|
|
154
|
+
**Subclassers:** these are new public names on the classes, so a subclass that happens to use one now
|
|
155
|
+
needs `override`. Composition remains the supported route.
|
|
156
|
+
|
|
157
|
+
- **The focus ring's inner gap is `transparent`, not `--surface-canvas`.** The 2px band exists to
|
|
158
|
+
separate the ring from the element, so it has to match what is actually BEHIND — and a named surface
|
|
159
|
+
only is that when nothing intervenes. In a dark app with white cards it painted the dark canvas as a
|
|
160
|
+
rim around a white card, reading as a rendering artifact rather than a focus state. Transparent costs
|
|
161
|
+
nothing on a canvas-coloured ground (the same pixels show through) and is right on every other.
|
|
162
|
+
|
|
163
|
+
- **`maxVisibleChips`: `null` means "unset" now, and `'all'` is the mode that shows every chip.**
|
|
164
|
+
`ds-autocomplete` and `ds-multi-select` took `number | 'fit' | null`, in which `null` was the
|
|
165
|
+
LOUDEST setting — render every chip and let the trigger wrap — while 0.10.0 gave `null` a service
|
|
166
|
+
meaning on twenty-two other inputs: not deciding, fall through to the default. The three modes are
|
|
167
|
+
named now: `'fit'` measures the trigger and shows what fits, a number is a ceiling that is still
|
|
168
|
+
measured ("at most N"), `'all'` renders the lot. **BREAKING: `[maxVisibleChips]="null"` used to show
|
|
169
|
+
every chip and now resolves to `'fit'`** — bind `maxVisibleChips="all"` for the old behaviour. Leaving
|
|
170
|
+
it unbound behaves exactly as before, since `'fit'` was already the default, and `null` now leaves
|
|
171
|
+
room for a `DS_CONFIG` slot to answer it app-wide.
|
|
172
|
+
|
|
173
|
+
- **The active `ds-sidenav-item` is a tinted wash with a coloured label, not a solid brand pill** — and
|
|
174
|
+
the edge rail is an input rather than a token you blank out. The item filled with `--accent` and put
|
|
175
|
+
`--text-on-primary` on its label, making the loudest element on the screen out of a state that only
|
|
176
|
+
says "you are here"; two apps independently replaced it, which is the signal that decided this.
|
|
177
|
+
Material fills its navigation drawer's active item with `secondary-container` and labels it
|
|
178
|
+
`on-secondary-container`; Carbon uses `$background-selected` with a border and a weight bump.
|
|
179
|
+
Neither fills with the brand accent. Ours is `--accent-subtitle` behind an `--accent-strong` label,
|
|
180
|
+
and hover deepens toward the accent (`--accent-muted`) instead of lightening toward white — the old
|
|
181
|
+
88%-toward-white mix was invisible on a wash. **The state still does not rest on colour alone:** the
|
|
182
|
+
edge rail and the weight bump both stay — and **the rail is now `--accent-strong`, the active label's
|
|
183
|
+
own colour, instead of `--secondary`.** An orange bar across a monochrome-blue row measured **2.33:1**
|
|
184
|
+
on the light wash, under the 3:1 floor a non-text indicator needs; the accent measures 6.16:1 light and
|
|
185
|
+
5.28:1 dark. Carbon's indicator is the interactive colour and Material's IS the wash — neither
|
|
186
|
+
introduces a second hue. Restore the old bar with `--ds-sidenav-item-rail: var(--secondary)`.
|
|
187
|
+
Every `--ds-sidenav-item-*-active` token keeps its name, so
|
|
188
|
+
an app that already retuned them keeps its own look and needs no edit.
|
|
189
|
+
**`[rail]="false"` on `ds-sidenav`** drops the edge marker for every item, and an item can override
|
|
190
|
+
it for itself (`[rail]` on `ds-sidenav-item`, unset = follow the parent). The old route was
|
|
191
|
+
`--ds-sidenav-item-rail: transparent` or a `::ng-deep` box-shadow reset — both still work, but the
|
|
192
|
+
input says what it means. `SidenavContract` gained a `rail: () => boolean` member; nothing outside
|
|
193
|
+
the library is expected to implement it.
|
|
194
|
+
|
|
195
|
+
- **The shipped migration manifests say WHERE to look, not only what changed — and a lint now holds
|
|
196
|
+
them to it.** `migrations/<version>.json` (the files `dist/ds/migrations/` carries into your
|
|
197
|
+
`node_modules`, which the auto-update plugin runs) gained `surface`, `detect`, `verify`, `restore`,
|
|
198
|
+
`supersedes` / `supersededBy`, and a structured `deleteList`. The reason is a consumer upgrade that
|
|
199
|
+
went 0.6.0 → 0.10.1 and passed over two entries in silence: `0.7.1`'s
|
|
200
|
+
`table-sortkey-non-null-when-unsorted` pointed at `ds-table[sortKey]`, which appears in nobody's
|
|
201
|
+
template, while the code that breaks was their own store —
|
|
202
|
+
`sorting: store.sortKey() ? { path: store.sortKey()!, … } : undefined` — so the search found
|
|
203
|
+
nothing, the item was recorded not-applicable, and the re-check's clean grep agreed. Three
|
|
204
|
+
server-paged screens kept sorting by a column whose header showed no sort. `surface` and `detect`
|
|
205
|
+
make that item searchable in the artifact that actually changes; `verify` gives a behavioural entry
|
|
206
|
+
the positive assertion a re-check can test, since there is no removed symbol whose absence proves
|
|
207
|
+
anything. **Every published manifest was back-filled the same day:** 167 items across 19 releases
|
|
208
|
+
got a `surface`, every behavioural one a `verify`, every changed default a `restore`, and the 32
|
|
209
|
+
prose `DELETE-LIST:` lines became `deleteList` arrays with a greppable `find` each — four of those
|
|
210
|
+
"lines" turned out to be the words "the DELETE-LIST" inside ordinary prose. Two default flips that
|
|
211
|
+
reverse each other now link both ways: `0.7.0` / `0.7.1` on `reserveMessage`, and `0.8.0` / `0.9.0`
|
|
212
|
+
on the table's sort mode. `npm run migration-lint` enforces the contract with no warning level, and
|
|
213
|
+
both the release preflight and the PR gate run it, so a manifest nobody can act on stops the
|
|
214
|
+
pipeline instead of reaching a consumer. Three CHANGELOG blocks also gained the "What you can now
|
|
215
|
+
DELETE" table their manifests had been carrying alone — 0.10.0's nineteen rows, 0.10.1's and
|
|
216
|
+
0.6.2's.
|
|
217
|
+
|
|
218
|
+
### Fixed
|
|
219
|
+
|
|
220
|
+
- **One focus ring per field, not two.** Since 0.10.0 the universal `:where(:focus-visible)` rule has
|
|
221
|
+
given every focusable element a `box-shadow`, and these shells paint their own on `:focus-within` —
|
|
222
|
+
`outline: 0`, which each inner control already had, cannot cancel a shadow. So a focused field drew a
|
|
223
|
+
tight ring around its inner control AND a halo around the box. Measured on five shapes: `ds-search`,
|
|
224
|
+
`ds-autocomplete`, `ds-date-picker`, `ds-number-stepper`, and any field inside a `ds-field-group`
|
|
225
|
+
(fixed once in the shared segment mixin). It is the same trap 0.10.0 warned consumers about — an app
|
|
226
|
+
rule that styles focus with an `outline` only — landing in our own components.
|
|
227
|
+
**The reset is scoped to the control the shell speaks for, deliberately.** A `ds-number-stepper` step
|
|
228
|
+
button keeps its own ring, and so does a chip's close button: those are `tabindex="0"` tab stops, and
|
|
229
|
+
the halo is already on, so it cannot say which of them focus moved to. The date picker's calendar
|
|
230
|
+
toggle is `tabindex="-1"` and correctly loses its ring.
|
|
231
|
+
|
|
232
|
+
- **A flat line box stopped shaving descenders off clipped labels** (mm-broker MBP-245). `.option` sets
|
|
233
|
+
`line-height: 1` while `.option-label` adds the `overflow: hidden` its ellipsis needs and no padding,
|
|
234
|
+
so the label box was exactly the font size tall and the glyph box was taller: measured **2.13px above
|
|
235
|
+
the cap line and 1.47px below the baseline** clipped, on every option rather than only the ones with a
|
|
236
|
+
descender. Fixed with `overflow: clip` plus a `var(--space-1)` clip margin, which **moves no geometry**
|
|
237
|
+
— the option row stays 30px, the multi-select row 36px, the table row 38px.
|
|
238
|
+
**Six sites:** the shared dropdown overlay (`ds-select`, `ds-autocomplete`), `ds-multi-select`'s own
|
|
239
|
+
copy, `.cell-clip` in `ds-table` and `.label` in `ds-breadcrumbs` (both measured), and the `.crumb`
|
|
240
|
+
rules in `ds-topbar` / `ds-page-header`, which share the shape and are unreachable in our own docs.
|
|
241
|
+
**Two behaviours checked rather than assumed:** the ellipsis still applies (`text-overflow` reads any
|
|
242
|
+
non-`visible` overflow), and `ds-table`'s clipped-cell popover still fires, since `scrollWidth >
|
|
243
|
+
clientWidth` still reports true under `clip`.
|
|
244
|
+
- **A field bound with signal forms threw once per field, and then showed an error it had already
|
|
245
|
+
cleared.** `resolveFieldMessage` subscribes to `NgControl`'s `events` stream to follow reactive and
|
|
246
|
+
template-driven forms. The `NgControl` that signal forms bridges carries no such stream, so the
|
|
247
|
+
subscription threw `TypeError: Cannot read properties of undefined (reading 'pipe')` — four times on
|
|
248
|
+
our own Practice → Signal Forms page, swallowed into the console. **The second half is what a user
|
|
249
|
+
saw:** the throw left that snapshot frozen at first render, and the message resolver falls back to it
|
|
250
|
+
whenever the live errors go empty — so a field that had just become VALID went on showing its FIRST
|
|
251
|
+
failure, with `aria-invalid="true"`. Measured through CDP with real input: empty → "We need an email",
|
|
252
|
+
`nope` → "That does not look like an email address", a valid address → **the required message again**.
|
|
253
|
+
Now the `NgControl` path bows out entirely when it has no live stream, leaving the component's own
|
|
254
|
+
inputs — which is where a signal-forms field's errors and touched arrive — as the single source. The
|
|
255
|
+
same sequence now clears the message and drops `aria-invalid`. **Reactive and template-driven forms are
|
|
256
|
+
untouched** and were re-checked on `/components/input`: too short, empty and valid each render
|
|
257
|
+
correctly, as before.
|
|
258
|
+
|
|
259
|
+
- **`components.md` was missing two layouts and naming three sidenav defaults that are not the
|
|
260
|
+
defaults.** The digest `tools/build-schematics.mjs` copies into `dist/ds/` is what a consumer's own
|
|
261
|
+
agent reads to answer "what does this library have", and `ds-app-layout` and `ds-auth-layout` were
|
|
262
|
+
absent from it entirely — an agent asked to build a shell or a sign-in screen could not find either
|
|
263
|
+
and had no way to know they existed. It also named `--primary`, `--text-on-primary` and
|
|
264
|
+
`--secondary` as the active sidenav item's defaults, which the wash rework in this same release
|
|
265
|
+
replaced. Both are corrected. Three smaller claims went with them: the search page said two things
|
|
266
|
+
skip the debounce where the code and this changelog both say three, the `--ds-stat-value-white-space`
|
|
267
|
+
description said an unwrapped phrase is clipped when it escapes the tile instead, and `ds-badge`
|
|
268
|
+
carried a superseded docblock. **No API changed** — only what the shipped documentation says about it.
|
|
269
|
+
|
|
270
|
+
- **Five more overlays dismiss on a click in the host's own empty width.** `ds-select`,
|
|
271
|
+
`ds-multi-select`, `ds-autocomplete`, `ds-time-picker` and `ds-color-picker` all tested the whole
|
|
272
|
+
HOST in their outside-pointer guard, which is the defect `ds-date-picker` was fixed for in 0.10.1
|
|
273
|
+
(MBP-225): the trigger box hugs its own content while the host takes whatever width a consumer's
|
|
274
|
+
layout gives it, so the label, the message row and any bare strip beside the trigger swallowed the
|
|
275
|
+
dismiss instead of performing it. Each guard now tests its TRIGGER, as `ds-popover` always did;
|
|
276
|
+
`ds-time-picker` tests whichever of its three triggers are present, since a range renders two.
|
|
277
|
+
**Behaviour change if you relied on it:** a press on the label of an open picker now closes the
|
|
278
|
+
panel. A press on the trigger still keeps it open, which is what that exception exists for (the
|
|
279
|
+
caret, and re-focus).
|
|
280
|
+
|
|
281
|
+
- **`variant="tonal"` now reads as disabled in the dark theme, where it rested on desaturation alone.**
|
|
282
|
+
Measured on `/components/button`: the disabled label was **1.11:1** from the enabled one (#778ff8 →
|
|
283
|
+
#979eb5) and the fill **1.20:1**, so the only signal was a hue going grey — and the label sat at 5.51:1
|
|
284
|
+
on its own fill, which reads as a live control. Tonal now takes the same 40% label mix ghost, text and
|
|
285
|
+
outline already use, toward `--surface-default`: the state gap becomes **2.90:1** in dark and **3.39:1**
|
|
286
|
+
in light, and the label keeps its hue instead of turning grey. **Toward the surface and not toward
|
|
287
|
+
tonal's own fill, even though the label sits on that fill** — the disabled fill has already moved
|
|
288
|
+
toward the label, so mixing into it yields only 2.56:1. The fill itself still barely moves (1.09:1
|
|
289
|
+
light, 1.20:1 dark) and does not need to: the label carries the state, which is the same division of
|
|
290
|
+
labour the transparent variants shipped with in 0.10.1. Override with
|
|
291
|
+
`--ds-button-label-color-disabled` as before.
|
|
292
|
+
|
|
293
|
+
- **`ds-multi-select`'s panel follows `--ds-dropdown-panel-radius` like the other two.** Its panel
|
|
294
|
+
element is `class="panel"`, not `.dropdown-panel`, so it never picked up the shared overlay rule and
|
|
295
|
+
sat at a hardcoded `--radius-md` (8px) while `ds-select` and `ds-autocomplete` moved with the token. It
|
|
296
|
+
now resolves the same chain, so a brand that rounds its dropdowns rounds all three.
|
|
297
|
+
|
|
298
|
+
- **`ds-date-picker`: a click on the host's own empty width now dismisses the open calendar.** The
|
|
299
|
+
outside-pointer guard treated the whole host element as the trigger, but the visible trigger box
|
|
300
|
+
hugs its mask while the host takes whatever a consumer's layout gives it — `flex-grow: 1` beside a
|
|
301
|
+
Clear button leaves a wide bare strip between the field and the button, and a click there kept the
|
|
302
|
+
calendar open with no visible reason (mm-broker MBP-225). The guard now tests the trigger box
|
|
303
|
+
itself: a press on the field or its calendar glyph still keeps the panel up, while the label, the
|
|
304
|
+
message row and the host's empty width dismiss it like any other outside click.
|
|
305
|
+
|
|
306
|
+
### What you can now DELETE
|
|
307
|
+
|
|
308
|
+
None of this is required — skipping it leaves working code that is merely redundant. Each row is a
|
|
309
|
+
workaround written against a hook that only landed in this release.
|
|
310
|
+
|
|
311
|
+
| If you have | Delete it, because |
|
|
312
|
+
| --- | --- |
|
|
313
|
+
| A hand-rolled second line inside a `ds-menu-item` — a projected span, a `max-width` near `14rem`, and probably no `aria-describedby` | The `description` input, capped by `--ds-menu-item-description-max-width` |
|
|
314
|
+
| `overflow: visible` forced back onto an element that needs to clip, or your own inset shadow standing in for a focus ring | `data-focus="inset"` on the clipping element |
|
|
315
|
+
| A `border-radius` override aimed at `ds-multi-select .panel` alone | `--ds-dropdown-panel-radius` now reaches all three connected panels |
|
|
316
|
+
| A timer of your own around a `ds-search` Clear button, or a value written twice to make the debounce let go | `clear()` |
|
|
317
|
+
| A copy of the config fallback chain in your own host — `this.size() ?? config.control?.size ?? 'md'` | The component's resolver is public now; read `sizeResolved()` |
|
|
318
|
+
| Your own wash replacing the solid active sidenav pill — a `--ds-sidenav-item-bg-color-active` override plus a matching label colour | That IS the default now; compare yours against it and drop it if they agree |
|
|
319
|
+
| `--ds-sidenav-item-rail: transparent`, or a `::ng-deep` box-shadow reset to hide the active rail | `[rail]="false"` on `ds-sidenav` |
|
|
320
|
+
| A `::ng-deep` `border-radius` rule on a bare `ds-menu` | `--ds-menu-radius` |
|
|
321
|
+
| `--ds-button-label-color-disabled` pinned on a tonal button to make its disabled state visible, most likely only in the dark theme | The default disabled-label recipe carries it |
|
|
322
|
+
| `count.toLocaleString('en-US')` (or any hand-rolled formatting) inside a `ds-stat` binding, because `[value]="count \| number"` would not typecheck | The pipe binds now, and it reads `LOCALE_ID` instead of a pinned locale |
|
|
323
|
+
| A `::ng-deep ds-table tr:hover .some-cell { color; text-decoration }` rule to make one cell read as the row's link target | `interactive: true` on that column, retuned with `--ds-table-cell-link-color` / `--ds-table-cell-link-decoration` |
|
|
324
|
+
|
|
11
325
|
## 0.10.1 — 2026-08-20
|
|
12
326
|
|
|
13
327
|
### Removed
|
|
@@ -192,8 +506,8 @@ While the package is on `0.x`, minor releases may contain breaking changes.
|
|
|
192
506
|
mix (0.036 → 0.099 light), so the disabled label stays tinted rather than going grey; that was
|
|
193
507
|
chosen deliberately over a desaturating variant after looking at both.
|
|
194
508
|
**`solid` and `tonal` are unchanged**, deliberately: a white label mixed into a white surface does
|
|
195
|
-
not move, and tonal's disabled fill already carries the state on its own.
|
|
196
|
-
mix target is `--surface-default`, a stand-in for "whatever is behind" — CSS cannot read the actual
|
|
509
|
+
not move, and tonal's disabled fill already carries the state on its own.
|
|
510
|
+
**Known limitation:** the mix target is `--surface-default`, a stand-in for "whatever is behind" — CSS cannot read the actual
|
|
197
511
|
backdrop, so on a tinted ground (a card at `--surface-secondary`, an alert) the disabled label is
|
|
198
512
|
computed against the page colour rather than that ground. Consumers who set
|
|
199
513
|
`--ds-button-label-color-disabled` are unaffected.
|
|
@@ -229,6 +543,14 @@ While the package is on `0.x`, minor releases may contain breaking changes.
|
|
|
229
543
|
`DsFieldBase` is internal and deliberately not exported — it holds only the inputs every field has,
|
|
230
544
|
which is why `success`, `label`, `required` and `optional` stayed on the components.
|
|
231
545
|
|
|
546
|
+
### What you can now DELETE
|
|
547
|
+
|
|
548
|
+
None of this is required — skipping it leaves working code that is merely redundant. Each row is a workaround this release made unnecessary.
|
|
549
|
+
|
|
550
|
+
| If you have | Delete it, because |
|
|
551
|
+
| --- | --- |
|
|
552
|
+
| A `?? ''` guard wrapped around a message binding - `[error]="form.errors?.message ?? ''"` - added because a null pushed into `hint` / `error` / `warning` / `success` threw a TypeError during render. | nothing - bind the expression directly, the inputs absorb null now |
|
|
553
|
+
|
|
232
554
|
## 0.10.0 — 2026-08-18
|
|
233
555
|
|
|
234
556
|
### Added
|
|
@@ -299,10 +621,7 @@ While the package is on `0.x`, minor releases may contain breaking changes.
|
|
|
299
621
|
The two signals are read-only — a subclass that used to `.set()` them (they were protected writables)
|
|
300
622
|
drives them through `runExport()` now.
|
|
301
623
|
|
|
302
|
-
- **`provideDsConfig` answers seven more inputs
|
|
303
|
-
itself.** Five of the release's eight new sections — `avatar`, `brand` and `modal` have their own
|
|
304
|
-
entries:
|
|
305
|
-
`control.size` (honoured by button, icon-button, input, textarea, select, autocomplete, search,
|
|
624
|
+
- **`provideDsConfig` answers seven more inputs, so an app stops restating itself.** Five new sections: `control.size` (honoured by button, icon-button, input, textarea, select, autocomplete, search,
|
|
306
625
|
date/time picker, number stepper, checkbox, radio, switch and field-group), `card.elevation` and
|
|
307
626
|
`card.padding`, `table.stickyScrollbar` and `table.bordered`, `icon.size`, and `badge.withDot`.
|
|
308
627
|
Precedence is **input → config → built-in**, so a screen that differs still binds the attribute and
|
|
@@ -349,7 +668,7 @@ While the package is on `0.x`, minor releases may contain breaking changes.
|
|
|
349
668
|
|
|
350
669
|
- **`--ds-dropdown-panel-radius` — the lever 0.9.0's notes promised and never shipped.** That release
|
|
351
670
|
said an 8px select panel could be restored with `--ds-select-panel-radius`; no such token existed,
|
|
352
|
-
so the advice did nothing
|
|
671
|
+
so the advice did nothing. This is the honest version, and it is
|
|
353
672
|
panel-level rather than per-component on purpose: retuning one picker's corner is not a thing to
|
|
354
673
|
encourage, while `--ds-radius-panel` moves modal, popover and date picker too. Defaults to that
|
|
355
674
|
role, so an untouched theme is unchanged, and it is forwarded onto the portaled pane — scope it with
|
|
@@ -674,6 +993,12 @@ While the package is on `0.x`, minor releases may contain breaking changes.
|
|
|
674
993
|
specificity. **If you deliberately suppressed a focus ring** by leaving an element unstyled, it will now
|
|
675
994
|
show one; give that element `box-shadow: none` explicitly. Note the rule also drops the outline such an
|
|
676
995
|
element used to get from the browser, so if an `outline` was what you wanted there, declare it yourself.
|
|
996
|
+
**The case that actually bites, added 2026-08-21 after a consumer hit it fourteen times:** an app rule
|
|
997
|
+
that styles `:focus-visible` with an **`outline` only**. That rule keeps winning on `outline`, but it
|
|
998
|
+
says nothing about `box-shadow`, so the base rule still supplies one and the element renders **both** —
|
|
999
|
+
a second ring in the app's colour around the DS ring. Nothing fails a build and nothing greps for it:
|
|
1000
|
+
the app rule looks untouched because it is. Add `box-shadow: none` to that rule, or — better, and what
|
|
1001
|
+
this release is for — delete the rule and retint the DS ring through `--ds-control-focus-shadow`.
|
|
677
1002
|
|
|
678
1003
|
- **A disabled `ds-button` / `ds-icon-button` now reads as disabled on a COLOURED accent.** One label recipe
|
|
679
1004
|
for every variant — `oklch(from accent 70% 0.035 h)` — replacing the 58% default, and on `ds-button` the
|
|
@@ -957,6 +1282,32 @@ While the package is on `0.x`, minor releases may contain breaking changes.
|
|
|
957
1282
|
could `.set()` — and a plain `private pending: … = null` is not a field the parser recognises, which
|
|
958
1283
|
is how `SearchComponent`'s `pending` and `pushed` sit outside its reported seven.
|
|
959
1284
|
|
|
1285
|
+
### What you can now DELETE
|
|
1286
|
+
|
|
1287
|
+
None of this is required — skipping it leaves working code that is merely redundant. Each row is a workaround this release made unnecessary.
|
|
1288
|
+
|
|
1289
|
+
| If you have | Delete it, because |
|
|
1290
|
+
| --- | --- |
|
|
1291
|
+
| A `ResizeObserver`, a container query or a hand-tuned per-breakpoint `maxVisibleChips` number, keeping a chip trigger on one line. | `maxVisibleChips="fit"`, which re-splits on any width change rather than at the breakpoints you listed |
|
|
1292
|
+
| A `max-height` plus `overflow: hidden` on a chip trigger, stopping it growing a line per selection - it clips a chip mid-glyph and hides the count. | `maxVisibleChips` (a number, or `"fit"`), which drops whole chips and reports how many are hidden |
|
|
1293
|
+
| Your own `max-height` on a logo projected into `ds-sidenav`'s `[brand]` slot, or a wrapper sized to hold it. | `--ds-sidenav-brand-max-height` (default `none`, so nothing changes until you set it) |
|
|
1294
|
+
| A global rule against `.ds-dropdown-panel` or `.cdk-overlay-pane` to change a dropdown corner. | `--ds-dropdown-panel-radius`, which scopes to one picker when written under a component selector |
|
|
1295
|
+
| A query for `ds-autocomplete`'s inner `<input>` plus a synthetic `input` event, clearing leftover filter text after a pick. | `clear()` - and the component clears that text itself now |
|
|
1296
|
+
| A local `.link-button` class, or a padding / border / background / font reset on `button.link` in your overrides. | the global `.link` class with `.inline` / `.standalone` / `.sm` / `.xs` |
|
|
1297
|
+
| A `[dsStatValue]` projection used only to set `white-space: normal` or a smaller font size on a TEXT value. | the two hooks on the ordinary `value` input - keep the slot for a value that is genuinely another component, like a badge |
|
|
1298
|
+
| A wrapper around `ds-search` adding a typing debounce (typically 200ms) with an immediate path when the field empties. | `[debounce]`, which does both plus the Enter flush |
|
|
1299
|
+
| `--ds-button-height` / `--ds-button-font-size` / `--ds-button-pad-x` pinned under `ds-filter-bar` to force its trigger smaller. | `triggerSize="sm"` |
|
|
1300
|
+
| `[dividers]="false"` repeated on every modal (one consumer had 41), or a reach into `.modal > .header` / `.body` / `.actions` with `!important` because hiding the rules left the padding stacked. | `provideDsConfig({ modal: { dividers: false } })`, which drops the rules AND the padding that existed to clear them |
|
|
1301
|
+
| A helper keeping the last visited tab per path in `sessionStorage`. | `rememberLastTab` on `ds-tabs` (needs `urlParam`, which supplies the names) |
|
|
1302
|
+
| An adapter component that injects a brand object and fans it out into `brand` / `logoLetter` / `tagline` bindings on each auth screen. | `provideDsConfig({ brand: … })`; the accent stays a `[dsBrandName]` projection instead of a `brandAccent` string plus an `indexOf` split |
|
|
1303
|
+
| The `ds-avatar` wiring around your own initials helper (the helper itself stays yours). | `[name]` plus one `[initialsRule]` |
|
|
1304
|
+
| An attribute repeated identically on every element - one consumer binds `[stickyScrollbar]="true"` on all 35 of its tables and `size="sm"` on 146 buttons. | `provideDsConfig` with the matching section (`table`, `control.size`, …) |
|
|
1305
|
+
| A button wired to `exportCsv()` on a SERVER-PAGED table - it serialises the rows the table holds, so the file is one page. | `runExport()` with an `exportFetcher` |
|
|
1306
|
+
| The computed beside every list table - `items().length > 0 ? 'overlay' : 'skeleton'` - one consumer feature carried three copies of it. | `[loading]="true"`, which resolves the treatment itself; pin a value only where you mean to override the rule |
|
|
1307
|
+
| An override retuning `--opacity-muted` to compensate for a washed-out disabled state. That token is a de-emphasis level for hints and secondary text and carries no disabled state at all - and on `ds-button` / `ds-icon-button` it was always inert, because neither ever read it. | `--ds-button-label-color-disabled` / `--ds-icon-button-icon-color-disabled` |
|
|
1308
|
+
| A `::ng-deep ds-table { .table th, .table td { width: 1%; white-space: nowrap } }` override - the shrink-to-content idiom. | `TableColumn.width: 'content'` |
|
|
1309
|
+
| A `stopPropagation()` on a control inside a clickable row, added so the row would not steal the control's KEY. Read each hit before deleting: a CLICK still bubbles (`onRowClick` only skips a target inside an `<input>`), so a click-path guard stays. | nothing on the key path - `onRowKey` now requires `target === currentTarget` |
|
|
1310
|
+
|
|
960
1311
|
## 0.9.1 — 2026-08-10
|
|
961
1312
|
|
|
962
1313
|
### Added
|
|
@@ -1058,14 +1409,14 @@ genuine gap worth reporting.
|
|
|
1058
1409
|
|
|
1059
1410
|
### Changed (breaking, visual)
|
|
1060
1411
|
|
|
1061
|
-
- **The `ds-select`
|
|
1062
|
-
|
|
1063
|
-
|
|
1412
|
+
- **The `ds-select` dropdown panel has a 12px corner, was 8px.** It was the one panel outside the
|
|
1413
|
+
radius role layer — modal, popover, date picker, time picker, autocomplete, bottom sheet, stat and
|
|
1414
|
+
page footer all resolve `--ds-radius-panel` — so it disagreed with its siblings by 4px and could
|
|
1064
1415
|
not be retuned through the role consumers are told to use. Restore with `--ds-radius-panel: 8px`,
|
|
1065
|
-
which moves every panel together
|
|
1066
|
-
`--ds-select-panel-radius
|
|
1067
|
-
|
|
1068
|
-
|
|
1416
|
+
which moves every panel together; there is no per-panel token for the select, and
|
|
1417
|
+
`--ds-select-panel-radius` does not exist. `ds-multi-select` is not part of this: its panel is a
|
|
1418
|
+
separate element with a hardcoded `border-radius: var(--radius-md)` that the shared rule does not
|
|
1419
|
+
reach, so it stays at 8px.
|
|
1069
1420
|
|
|
1070
1421
|
- **Seven exit `@keyframes` are gone, replaced by four global presets.** `modal-out`, `ds-sheet-fade-out`
|
|
1071
1422
|
and `drawer-scrim-out` become `ds-fade-out`; `ds-sheet-down` and the four `drawer-panel-close-*` become
|
|
@@ -2370,6 +2721,15 @@ genuine gap worth reporting.
|
|
|
2370
2721
|
scrim click-to-close, panel-scoped plus document-level Escape, `animationend` teardown, and the focus
|
|
2371
2722
|
trap are all unchanged.
|
|
2372
2723
|
|
|
2724
|
+
### What you can now DELETE
|
|
2725
|
+
|
|
2726
|
+
None of this is required — skipping it leaves working code that is merely redundant. Each row is a workaround this release made unnecessary.
|
|
2727
|
+
|
|
2728
|
+
| If you have | Delete it, because |
|
|
2729
|
+
| --- | --- |
|
|
2730
|
+
| A logo overlaid or absolutely positioned on top of ds-sidenav's brand row, written when there was no slot for one. | project it into `[brand]` |
|
|
2731
|
+
| A scrollTop pin or a scroll-lock hack written against the content jolt an opening sheet used to cause in a shell that is a containing block for fixed descendants. | nothing - the entering panel no longer contributes that overflow |
|
|
2732
|
+
|
|
2373
2733
|
## 0.6.1 — 2026-07-16
|
|
2374
2734
|
|
|
2375
2735
|
### Fixed
|
package/components.md
CHANGED
|
@@ -120,13 +120,29 @@ Every entry below names its exported class (`ButtonComponent`, `TableComponent<T
|
|
|
120
120
|
|
|
121
121
|
**The `--ds-*` token contract, once for every component below.** Every public `--ds-<component>-*` token is READ WITH A FALLBACK and never declared by the component, so a consumer's value always wins and always inherits: set it on the host (`ds-button { --ds-button-bg-color: teal }`), on any ancestor, at `:root`, or inline. Unset tokens fall through to the component's own default, so there is nothing to opt into and nothing to reset. Two consequences worth stating: a token set at `:root` reaches EVERY instance — scope per instance or per section and keep theme-wide re-skins at role level (`--primary`, `--ds-radius-control`) — and where a component derives one value from another (a hover fill mixed from the resolved background), overriding the source retunes the derived states with it. Individual entries below therefore note only what DEVIATES from this: a derived state, a variant-specific default, a token that beats a size class.
|
|
122
122
|
|
|
123
|
-
> **Token and API lists below are hand-maintained
|
|
123
|
+
> **Token and API lists below are hand-maintained, so treat this file as prose about intent.** The authoritative surfaces are the **Component API tables** and the **token reference** in `ds-docs`, both extracted from source on every build, so they cannot go stale — trust those first, and read this file for the reasoning a generated table cannot carry. Where the two disagree, the generated one is right. Reconciled 2026-08-21 (the `ds-button` section named here as drifted had already been rewritten; that note was itself out of date).
|
|
124
124
|
|
|
125
125
|
### Form & input
|
|
126
126
|
|
|
127
|
+
**Shared by every field** (input, textarea, select, multi-select, autocomplete, date/time/colour picker,
|
|
128
|
+
checkbox, radio, radio-group, switch, slider, segmented, OTP): `label`, `hint`, `error`, `warning`,
|
|
129
|
+
`errors`, `invalid`, `touched`, `reserveMessage` — and one message line under the control that renders
|
|
130
|
+
whichever of them wins. The ladder is error → errors → warning → advisory errors → success → hint.
|
|
131
|
+
|
|
132
|
+
`error`, `warning` and `success` lead that line with a glyph; `hint` does not, because it is the resting
|
|
133
|
+
text rather than a state. Retune app-wide with `DS_CONFIG.field.stateIcons` (per state, independent —
|
|
134
|
+
`false` removes one, an `IconName` replaces it, `stateIcons: false` removes all four), or per field with
|
|
135
|
+
`messageIcon: IconName | false | null`, which wins over the config. Spacing hooks:
|
|
136
|
+
`--ds-field-message-icon-gap`, `--ds-field-message-icon-offset`.
|
|
137
|
+
|
|
138
|
+
**`ds-search` is deliberately NOT on that list.** It binds to a form like the others — `[formControl]`,
|
|
139
|
+
`formControlName`, `[(ngModel)]`, signal forms, plus its own `[(value)]` — and it takes `disabled` and
|
|
140
|
+
`hidden`, but it renders no message row and therefore takes none of the message inputs. A toolbar filter
|
|
141
|
+
is not a validated field; where a search needs a label or an error line, use `ds-input`.
|
|
142
|
+
|
|
127
143
|
#### `<ds-button>` — `ButtonComponent`
|
|
128
144
|
Inputs: **two orthogonal axes** — `color: ButtonColor = 'primary'` (`'primary' | 'secondary' | 'tertiary' | 'neutral' | 'error' | 'success' | 'warning'`) and `variant: ButtonVariant = 'solid'` (`'solid' | 'tonal' | 'outline' | 'ghost' | 'text'`). Plus `size: DsSize | null = null` (unset resolves `DS_CONFIG.control.size`, then `md`), `type: 'button' | 'submit' | 'reset' = 'button'`, `disabled`, `loading`, `fullWidth`, `icon: IconName | null`.
|
|
129
|
-
Axis meaning: **variant is loudness** (solid > tonal > outline/ghost/text), **color is hue** — every pair renders, and the UX-discouraged ones dev-warn (see `DISCOURAGED_COMBOS`). Only solid and tonal paint a fill: outline, ghost and text are TRANSPARENT, so they adopt the surface they sit on. Disabled
|
|
145
|
+
Axis meaning: **variant is loudness** (solid > tonal > outline/ghost/text), **color is hue** — every pair renders, and the UX-discouraged ones dev-warn (see `DISCOURAGED_COMBOS`). Only solid and tonal paint a fill: outline, ghost and text are TRANSPARENT, so they adopt the surface they sit on. Disabled splits by whether the fill can carry the state: `solid` and `tonal` keep `oklch(from accent 70% 0.035 h)`, while `outline`, `ghost` and `text` — the three with no fill of their own — mix the label toward the surface, `color-mix(in srgb, <label> 40%, var(--surface-default))`, because a fixed lightness cannot serve both themes. (History: the single `variant` axis was split into color × variant in 2026-06; `danger`→`error`, `link`→`text`, the old `ghost`→`outline`.)
|
|
130
146
|
Output: `(pressed): MouseEvent` — only fires when not disabled and not loading
|
|
131
147
|
Content slots: default (label / leading or trailing icon). For icon-only actions use `<ds-icon-button>`.
|
|
132
148
|
Tokens: `--ds-button-bg-color`, `--ds-button-bg-color-hover`, `--ds-button-bg-color-active`, `--ds-button-bg-color-disabled`, `--ds-button-label-color`, `--ds-button-label-color-disabled`, `--ds-button-border`, `--ds-button-radius`, `--ds-button-focus-shadow`, `--ds-button-pressed-shadow`. For `variant="solid"`, `-bg-color-hover` / `-bg-color-active` / `-pressed-shadow` default to a `color-mix()` derivation of the resolved fill (88 % / 76 % + black — the theme's hover/pressed recipe), so overriding the fill alone retints the whole state set; tonal, outline, ghost and text keep explicit ramp defaults, so a full retint there means setting the state tokens too.
|
|
@@ -187,9 +203,11 @@ Inputs: `options: readonly ComboboxOption<T>[]` (`{ value: T, label: string }`),
|
|
|
187
203
|
In multi mode, selected values render as `<ds-tag closable>` chips above the trigger.
|
|
188
204
|
|
|
189
205
|
#### `<ds-search>` — `SearchComponent`
|
|
190
|
-
Pre-styled search input with built-in icon.
|
|
191
|
-
Inputs: `value: model<string>`, `placeholder: string = 'Search'`, `shortcut: string = ''` (rendered as a hint pill, e.g. `⌘K`), `showIcon: boolean = true`
|
|
206
|
+
Pre-styled search input with built-in icon. A form control, but not a field: no label, no message row.
|
|
207
|
+
Inputs: `value: model<string>`, `placeholder: string = 'Search'`, `shortcut: string = ''` (rendered as a hint pill, e.g. `⌘K`), `showIcon: boolean = true`, `clearable: boolean = false`, `ariaLabel: string = ''`, `disabled: boolean = false`, `hidden: boolean = false`, `size: DsSize | null = null`, `debounce: number = 0` (ms held before `value` updates; clearing, Enter and `clear()` all skip the timer)
|
|
192
208
|
Output: `(submitted): string` — emits the current value on Enter / form submit
|
|
209
|
+
Methods: `clear()` — empties the field, drops an armed keystroke and publishes `''` at once, which writing `''` into `value` does not; `focus()`.
|
|
210
|
+
Binds through `NG_VALUE_ACCESSOR`, taking the CVA plumbing without `DsFieldBase` — so `hint` / `error` / `warning` / `errors` / `invalid` / `touched` / `reserveMessage` / `messageIcon` are NOT inputs here.
|
|
193
211
|
|
|
194
212
|
#### `<ds-date-picker>` — `DatePickerComponent`
|
|
195
213
|
Inputs: `mode: 'single' | 'range' = 'single'`, `size: 'sm' | 'md' | 'lg' = 'md'`, `value: model<Date | RangeValue | null>` (`RangeValue = [Date | null, Date | null]`), `placeholder: string = 'Select date'`, `label: string = ''`, `hint: string = ''`, `required: boolean = false`, `optional: boolean = false`
|
|
@@ -259,7 +277,7 @@ The companion `<ds-toast-region>` lives inside the `ToastService` (see Services)
|
|
|
259
277
|
### Layout & navigation
|
|
260
278
|
|
|
261
279
|
#### `<ds-sidenav>` — `SidenavComponent`
|
|
262
|
-
Inputs: `collapsed: boolean = false`, `brand: string =
|
|
280
|
+
Inputs: `collapsed: boolean = false`, `brand: string | null = null` (renders a letter mark + name; omit to project custom content, or set `DS_CONFIG.brand.name`), `logoLetter: string | null = null` (the mark's glyph; derived from `brand` when unset), `rail: boolean = true` (whether an active item draws its edge marker — turn it off here rather than painting `--ds-sidenav-item-rail` transparent)
|
|
263
281
|
Content: default slot for groups/items + custom brand/footer rows
|
|
264
282
|
Tokens: `--ds-sidenav-bg-color`, `--ds-sidenav-border`, `--ds-sidenav-width`, `--ds-sidenav-width-collapsed`, `--ds-sidenav-mark-bg-color`, `--ds-sidenav-mark-label-color`
|
|
265
283
|
|
|
@@ -269,15 +287,28 @@ Content slots: default (items); `[ds-group-icon]` (custom group icon when not us
|
|
|
269
287
|
When `expandable=true` renders header button with toggle + caret; collapses body when not expanded.
|
|
270
288
|
|
|
271
289
|
#### `<ds-sidenav-item>` — `SidenavItemComponent`
|
|
272
|
-
Inputs: `icon: IconName | null = null` (optional — falls back to `[icon]` slot), `label: required string`, `href: string = ''`, `routerLink: string | readonly unknown[] | null = null`, `active: boolean = false`, `badge: number | null = null`, `hasAlert: boolean = false`
|
|
290
|
+
Inputs: `icon: IconName | null = null` (optional — falls back to `[icon]` slot), `label: required string`, `href: string = ''`, `routerLink: string | readonly unknown[] | null = null`, `active: boolean = false`, `badge: number | null = null`, `hasAlert: boolean = false`, `rail: boolean | null = null` (draws the active item's edge marker; unset follows the parent `ds-sidenav`)
|
|
273
291
|
Content slots: `[icon]` (custom icon when not using a DS IconName), `[trailing]` (right-aligned chrome — badges, indicators, kbd shortcuts)
|
|
274
|
-
Tokens (on `:host`): `--ds-sidenav-item-label-color`, `--ds-sidenav-item-label-color-hover`, `--ds-sidenav-item-bg-color-hover`, `--ds-sidenav-item-bg-color-active` (default: `--
|
|
292
|
+
Tokens (on `:host`): `--ds-sidenav-item-label-color`, `--ds-sidenav-item-label-color-hover`, `--ds-sidenav-item-bg-color-hover`, `--ds-sidenav-item-bg-color-active` (default: `--accent-subtitle` — a wash, not a solid pill), `--ds-sidenav-item-label-color-active` (default: `--accent-strong`), `--ds-sidenav-item-bg-color-active-hover` (default: `--accent-muted`, deepening toward the accent), `--ds-sidenav-item-rail` (left rail, default: `--accent-strong`), `--ds-sidenav-item-radius`, `--ds-sidenav-alert-color`
|
|
275
293
|
|
|
276
294
|
#### `<ds-topbar>` — `TopBarComponent`
|
|
277
295
|
No inputs.
|
|
278
296
|
Content slots: `[title]`, `[breadcrumbs]`, `[search]`, `[actions]`. Sits at `--topbar-h` height.
|
|
279
297
|
Tokens (on `:host`): `--ds-topbar-height`, `--ds-topbar-bg-color`, `--ds-topbar-border`, `--ds-topbar-title-text-color`, plus the `--ds-topbar-crumb-*` set for the breadcrumb row. **The topbar owns no bottom gap** — it has no margin token and sets no margin; spacing to the next block belongs to the page or to `ds-app-layout`'s content padding. (This paragraph previously documented a `--ds-topbar-margin-b` that has never existed in the shipped component.)
|
|
280
298
|
|
|
299
|
+
#### `<ds-app-layout>` — `AppLayoutComponent`
|
|
300
|
+
Inputs: `topbarSpan: 'content' | 'full' = 'content'`, `railOpen: model<boolean> = false` (the overlay rail below `--bp-lg`), `railLabel: string = 'Navigation'`, `restoreScroll: boolean = false`, `restoreScrollTimeout: number = 2000` (ms), `scrollReset: 'path' | 'always' | 'never' = 'path'`
|
|
301
|
+
Content slots: `[sidenav]`, `[topbar]`, default (the page)
|
|
302
|
+
Reads: `railId` and the read-only `railOverlay` signal, for a consumer-built burger; `dsRailTrigger` wires one for you.
|
|
303
|
+
Tokens: `--ds-app-layout-pad-x`, `--ds-app-layout-pad-y`, `--ds-app-layout-content-max-width`, `--ds-app-layout-height`, `--ds-app-layout-rail-bg-color`, `--ds-app-layout-rail-shadow`, `--ds-app-layout-scrim-color`
|
|
304
|
+
It owns the app's scroll CONTAINER, so a screen that needs to move the scroll calls `LayoutScrollService` rather than touching `window`.
|
|
305
|
+
|
|
306
|
+
#### `<ds-auth-layout>` — `AuthLayoutComponent`
|
|
307
|
+
Inputs: `brand: string | null = null`, `logoLetter: string | null = null`, `tagline: string | null = null` (all three fall back to `DS_CONFIG.brand`), `cardElevation: CardElevation = 'raised'`, `cardPadding: CardPadding = 'lg'`, `landmark: 'main' | 'none' = 'none'`
|
|
308
|
+
Content slots: `[brand]` (replaces the whole mark row), `[dsBrandName]` (the name beside the generated mark), default (the card body), `[dsAuthSupport]` (the line under the card)
|
|
309
|
+
Tokens: `--ds-auth-layout-min-height`, `--ds-auth-layout-bg-color`, `--ds-auth-layout-gap`, `--ds-auth-layout-pad-block`, `--ds-auth-layout-card-max-width`, `--ds-auth-layout-mark-size`, `--ds-auth-layout-mark-radius`, `--ds-auth-layout-mark-bg-color`, `--ds-auth-layout-mark-label-color`
|
|
310
|
+
`landmark="main"` only when the page has no other `<main>`; the sign-in card is not automatically the document's main landmark.
|
|
311
|
+
|
|
281
312
|
#### `<ds-page-header>` — `PageHeaderComponent`
|
|
282
313
|
Inputs: `eyebrow: string = ''`, `title: required string`, `subtitle: string = ''`, `compact: boolean = false`, `divider: boolean = false`, `metaDivider: boolean = false`
|
|
283
314
|
Content slots: `[breadcrumbs]`, `[title-badge]` (sits next to the title text), `[actions]` (right edge of title row), `[meta]` (under the title row), `[tabs]` (under the meta row)
|
|
@@ -436,19 +467,43 @@ bootstrapApplication(AppComponent, {
|
|
|
436
467
|
|
|
437
468
|
`DsConfig` shape (see `src/lib/config/ds-config.ts`):
|
|
438
469
|
|
|
470
|
+
Twelve sections. `src/lib/config/ds-config.ts` is the source of truth — each key carries its own
|
|
471
|
+
doc comment there, including why it is an app-level decision at all.
|
|
472
|
+
|
|
439
473
|
```ts
|
|
440
474
|
interface DsConfig {
|
|
441
|
-
|
|
442
|
-
|
|
443
|
-
|
|
475
|
+
field?: {
|
|
476
|
+
reserveMessage?: boolean; // keep a message line of space when empty
|
|
477
|
+
errorMessages?: Record<string, string>; // fallback text per validation-error kind
|
|
478
|
+
stateIcons?: false | { // the message line's leading glyph, per state
|
|
479
|
+
error?: IconName | false; // default: `error`
|
|
480
|
+
warning?: IconName | false; // default: `warn`
|
|
481
|
+
success?: IconName | false; // default: `success`
|
|
482
|
+
hint?: IconName | false; // default: NONE — hint is not a state
|
|
483
|
+
};
|
|
444
484
|
};
|
|
485
|
+
control?: { size?: DsSize }; // every control on the field-height contract
|
|
486
|
+
card?: { elevation?: CardElevation; padding?: CardPadding };
|
|
487
|
+
table?: { stickyScrollbar?: boolean; bordered?: boolean };
|
|
488
|
+
modal?: { dividers?: boolean }; // reaches a ModalService confirm, which has no host to bind
|
|
489
|
+
icon?: { size?: number };
|
|
490
|
+
badge?: { withDot?: boolean };
|
|
491
|
+
breadcrumbs?: { separator?: IconName; clickable?: boolean };
|
|
492
|
+
datePicker?: { locale?: string; dateFormat?: string; firstDayOfWeek?: number };
|
|
493
|
+
timePicker?: { format?: '24h' | '12h' };
|
|
494
|
+
avatar?: { initials?: (name: string) => string };
|
|
495
|
+
brand?: { name?: string; logoLetter?: string; tagline?: string };
|
|
445
496
|
}
|
|
446
497
|
```
|
|
447
498
|
|
|
448
|
-
|
|
449
|
-
|
|
499
|
+
Precedence is always: **explicit input → config → component default.** A component publishes what it
|
|
500
|
+
resolved as a public readback (`sizeResolved()`, `dividersResolved()`, …) so a host can read the
|
|
501
|
+
effective value rather than re-deriving the chain.
|
|
450
502
|
|
|
451
|
-
|
|
503
|
+
**Call `provideDsConfig` once per injector.** Two calls in the same `providers` array do NOT merge —
|
|
504
|
+
both resolve their parent with `skipSelf`, so the later wins and the earlier is silently lost. Merging
|
|
505
|
+
happens across injector LEVELS: a route or component inherits the app's config and overrides only the
|
|
506
|
+
keys it names.
|
|
452
507
|
|
|
453
508
|
---
|
|
454
509
|
|