@ids-group-ltd/ids-design-system 0.11.2 → 0.11.4
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 +319 -12
- package/components.md +35 -12
- package/design-system.md +135 -1
- package/docs/agent/INDEX.md +99 -0
- package/docs/agent/domain/ds-w3w.md +10 -0
- package/docs/agent/feedback/ds-alert.md +9 -0
- package/docs/agent/feedback/ds-avatar-group.md +7 -0
- package/docs/agent/feedback/ds-avatar.md +6 -0
- package/docs/agent/feedback/ds-badge.md +7 -0
- package/docs/agent/feedback/ds-banner.md +10 -0
- package/docs/agent/feedback/ds-empty-state.md +7 -0
- package/docs/agent/feedback/ds-progress.md +7 -0
- package/docs/agent/feedback/ds-skeleton.md +6 -0
- package/docs/agent/feedback/ds-spinner.md +6 -0
- package/docs/agent/feedback/ds-stat.md +7 -0
- package/docs/agent/feedback/ds-status-dot.md +6 -0
- package/docs/agent/feedback/ds-tag.md +8 -0
- package/docs/agent/feedback/ds-toast.md +12 -0
- package/docs/agent/forms/ds-autocomplete.md +9 -0
- package/docs/agent/forms/ds-button.md +14 -0
- package/docs/agent/forms/ds-checkbox.md +6 -0
- package/docs/agent/forms/ds-date-picker.md +7 -0
- package/docs/agent/forms/ds-dropzone.md +10 -0
- package/docs/agent/forms/ds-icon-button.md +10 -0
- package/docs/agent/forms/ds-input.md +22 -0
- package/docs/agent/forms/ds-multi-select.md +6 -0
- package/docs/agent/forms/ds-number-stepper.md +8 -0
- package/docs/agent/forms/ds-radio.md +6 -0
- package/docs/agent/forms/ds-search.md +10 -0
- package/docs/agent/forms/ds-select.md +7 -0
- package/docs/agent/forms/ds-switch.md +6 -0
- package/docs/agent/forms/ds-textarea.md +9 -0
- package/docs/agent/forms/the-picker-family-ds-select-ds-multi-select-ds-autocomplete.md +21 -0
- package/docs/agent/foundations/global-helper-classes.md +18 -0
- package/docs/agent/foundations/grid.md +35 -0
- package/docs/agent/foundations/tokens.md +47 -0
- package/docs/agent/navigation/ds-app-layout.md +10 -0
- package/docs/agent/navigation/ds-auth-layout.md +9 -0
- package/docs/agent/navigation/ds-breadcrumbs.md +7 -0
- package/docs/agent/navigation/ds-divider.md +9 -0
- package/docs/agent/navigation/ds-page-footer.md +7 -0
- package/docs/agent/navigation/ds-page-header.md +8 -0
- package/docs/agent/navigation/ds-pagination.md +7 -0
- package/docs/agent/navigation/ds-sidenav-group.md +8 -0
- package/docs/agent/navigation/ds-sidenav-item.md +9 -0
- package/docs/agent/navigation/ds-sidenav.md +9 -0
- package/docs/agent/navigation/ds-stepper.md +6 -0
- package/docs/agent/navigation/ds-tabs.md +9 -0
- package/docs/agent/navigation/ds-topbar.md +8 -0
- package/docs/agent/overlays/ds-bottom-sheet.md +9 -0
- package/docs/agent/overlays/ds-drawer.md +9 -0
- package/docs/agent/overlays/ds-menu.md +8 -0
- package/docs/agent/overlays/ds-modal-card.md +6 -0
- package/docs/agent/overlays/ds-modal.md +8 -0
- package/docs/agent/overlays/ds-popover.md +6 -0
- package/docs/agent/overlays/ds-tooltip.md +8 -0
- package/docs/agent/platform/body-scroll-lock-service.md +12 -0
- package/docs/agent/platform/breadcrumbs-service.md +30 -0
- package/docs/agent/platform/ds-config.md +60 -0
- package/docs/agent/platform/ds-icon-registry.md +23 -0
- package/docs/agent/platform/toast-service.md +17 -0
- package/docs/agent/surfaces/ds-accordion.md +8 -0
- package/docs/agent/surfaces/ds-card.md +10 -0
- package/docs/agent/tables/ds-table.md +15 -0
- package/fesm2022/ids-group-ltd-ids-design-system.mjs +924 -763
- package/fesm2022/ids-group-ltd-ids-design-system.mjs.map +1 -1
- package/migrations/0.11.3.json +152 -0
- package/migrations/0.11.4.json +241 -0
- package/migrations/0.8.0.json +6 -5
- package/package.json +1 -1
- package/styles/_control-label.scss +18 -0
- package/styles/_dropdown-overlay.scss +25 -32
- package/styles/_ds-color.scss +37 -12
- package/styles/_focus.scss +16 -0
- package/styles/_skeleton-shimmer.scss +10 -26
- package/styles/_tokens-charts.scss +2 -3
- package/styles/_tokens.scss +158 -321
- package/themes/README.md +32 -1
- package/themes/_base-palette.scss +35 -76
- package/themes/_semantic.scss +16 -4
- package/types/ids-group-ltd-ids-design-system.d.ts +205 -230
package/CHANGELOG.md
CHANGED
|
@@ -8,6 +8,315 @@ While the package is on `0.x`, minor releases may contain breaking changes.
|
|
|
8
8
|
|
|
9
9
|
## Unreleased
|
|
10
10
|
|
|
11
|
+
## 0.11.4 — 2026-09-03
|
|
12
|
+
|
|
13
|
+
### Breaking
|
|
14
|
+
|
|
15
|
+
- **`ds-banner` and `ds-alert` no longer announce themselves unless asked.** Both applied `role` and
|
|
16
|
+
`aria-live` unconditionally, and an `alert` region fires on INSERTION — so a static "maintenance on
|
|
17
|
+
Sunday" strip interrupted a screen reader on every client-side route into the page. MDN says it
|
|
18
|
+
outright: do not use `alert` on content the user has not interacted with. Measured on this site's own
|
|
19
|
+
pages: 12 assertive regions before, 0 now. Pass `[announce]="true"` for a banner the app raises in
|
|
20
|
+
response to an event; for anything transient use `ToastService`, which owns a region built for it.
|
|
21
|
+
|
|
22
|
+
- **`<ds-toast>`'s `message` input is now `body`**, matching `ToastOptions.body` and `ToastEntry.body`.
|
|
23
|
+
One concept had three spellings across the family; `body` wins because it is the one every consumer
|
|
24
|
+
already passes to the service.
|
|
25
|
+
|
|
26
|
+
- **Five toast border tokens gain the `-color` the rest of the library uses**:
|
|
27
|
+
`--ds-toast-border` → `--ds-toast-border-color`, and the four variant suffixes with it. They are
|
|
28
|
+
colours, and they were the last holdouts of the old naming.
|
|
29
|
+
|
|
30
|
+
- **`maxVisible` defaults to 5 instead of unlimited.** An uncapped stack was more permissive than any
|
|
31
|
+
system this component is measured against — Material shows one snackbar and dismisses the previous,
|
|
32
|
+
Carbon and Halstack stack but expect a ceiling. `provideDsConfig({ toast: { maxVisible: n } })` still sets it, and `0` still means
|
|
33
|
+
no cap; a configured `0` is now forwarded rather than skipped, since it is the only way left to ask
|
|
34
|
+
for one.
|
|
35
|
+
|
|
36
|
+
- **A screen reader was told nothing about a toast, for three of the five variants.** `aria-live` sat
|
|
37
|
+
on each toast, and a live region has to exist in the DOM *before* its text arrives — a node created
|
|
38
|
+
with its message already inside it is the one case NVDA and JAWS reliably do not announce. The
|
|
39
|
+
region host was `role="region"`, a landmark, not a live region. Announcements now go through the CDK
|
|
40
|
+
`LiveAnnouncer`, whose region is built once at service construction and only has its text replaced.
|
|
41
|
+
`error` and `warning` announce assertively, the rest politely. WCAG 2.2 SC 4.1.3.
|
|
42
|
+
|
|
43
|
+
A burst is coalesced into one announcement rather than queued, and that is forced rather than
|
|
44
|
+
chosen: `announce()` clears its region synchronously and writes on a 120ms timeout, resolving its
|
|
45
|
+
promise inside that callback — so even a strictly serialised chain loses all but the last message.
|
|
46
|
+
Measured: five announcements each landed and were cleared again in the same millisecond.
|
|
47
|
+
|
|
48
|
+
A `<ds-toast>` you place yourself is now silent to a reader. It is a specimen, not an event; use
|
|
49
|
+
`ToastService` for anything that should be announced.
|
|
50
|
+
|
|
51
|
+
- **Toast defaults move into `provideDsConfig`, and the two toast tokens are gone.**
|
|
52
|
+
`DS_TOAST_CONFIG` and `DS_TOAST_POSITION` were the only configuration in the library that did not
|
|
53
|
+
go through `DsConfig` — thirteen other areas already did — so an app set everything in one call and
|
|
54
|
+
then remembered two bare `InjectionToken` providers for toasts. They are now
|
|
55
|
+
`provideDsConfig({ toast: { maxVisible, position } })`, and the `DsToastConfig` interface is
|
|
56
|
+
removed with its token.
|
|
57
|
+
`position` is PARTIAL and merged field by field over `right` / `top` / `var(--space-6)`: the old
|
|
58
|
+
token's type required all three fields, so moving the stack to the bottom meant restating the other
|
|
59
|
+
two. `DS_TOAST_POSITION_DEFAULT` is unchanged and still exported. One caveat, and it is not new:
|
|
60
|
+
`ToastService` is `providedIn: 'root'`, so the `toast` section resolves only at the root injector —
|
|
61
|
+
a route-level `provideDsConfig` cannot narrow it, unlike every other section.
|
|
62
|
+
|
|
63
|
+
### Changed
|
|
64
|
+
|
|
65
|
+
- **Toast and table class internals moved again — only matters if you SUBCLASS one of them.**
|
|
66
|
+
Every name here is a `private` or `protected` internal, not public API and not a signal, but
|
|
67
|
+
`private` collides with TS2415 exactly as a public name does, so a member of yours sharing one
|
|
68
|
+
still stops the build. `ToastComponent` **lost `role`** — the component no longer sets one, so
|
|
69
|
+
an `override role` overrides nothing. `ToastRegionComponent` gained `leaveTimers`,
|
|
70
|
+
`slideNeighbours`, `toastNodes`, `measureTops` and `leaveDuration`, and **renamed
|
|
71
|
+
`promoteFromQueue` to `drainQueue`**; an override of the old name now runs never, so move it.
|
|
72
|
+
`ToastService` gained `announcer`, `pendingAnnouncements`, `pendingAssertive`, `announceTimer`,
|
|
73
|
+
`scrimWatcher`, `announce` and `keepAboveScrims`, and **lost `position`** with the token it
|
|
74
|
+
read. `TableComponent` gained `eventsAtExport`,
|
|
75
|
+
`eventMessages`, `tableHead`, `hostElement` and `announceExport`; its inputs, outputs, models
|
|
76
|
+
and exported types are unchanged. `BannerComponent` and `AlertComponent` each gained
|
|
77
|
+
`announce`, and their `ariaRole` and `ariaLive` now return `null` as well — a subclass that
|
|
78
|
+
narrowed either type back, or code that assumed the getter is never null, stops compiling.
|
|
79
|
+
The compiler enumerates every collision, so building after the upgrade is the whole check.
|
|
80
|
+
|
|
81
|
+
- **The stack no longer jumps when a toast is added.** Its neighbours are put back where they were
|
|
82
|
+
with a `transform` and released, so the re-stack runs on the compositor instead of the browser
|
|
83
|
+
moving them all in one frame. Two new tokens tune it: `--ds-toast-shift-duration` (default
|
|
84
|
+
`--duration-fast`) and `--ds-toast-shift-easing`. A dismissal keeps its own, longer timing — a
|
|
85
|
+
re-stack and a leave are different motions.
|
|
86
|
+
|
|
87
|
+
### Fixed
|
|
88
|
+
|
|
89
|
+
- **A click between a boolean control and its label hit nothing.** `ds-radio`, `ds-checkbox` and
|
|
90
|
+
`ds-switch` set the space between control and label with a flex `gap`, which belongs to neither
|
|
91
|
+
box — so the 8px strip between them swallowed the click instead of toggling. That space is now
|
|
92
|
+
padding on the label, which extends its clickable box across the strip: the target grows from
|
|
93
|
+
18px to 26px tall while the text's start position and the row height stay put. No API or token
|
|
94
|
+
change.
|
|
95
|
+
|
|
96
|
+
- **`ds-table`'s bulk-actions bar rendered its buttons invisible.** The bar is an inverted
|
|
97
|
+
surface, and its buttons were coloured through a bare `.button` rule that stopped applying once
|
|
98
|
+
the button became `ds-button` — which takes its label from `--ds-button-label-color` and ignores
|
|
99
|
+
inherited `color`, so the label sat on the bar's own colour and disappeared. The bar now sets
|
|
100
|
+
ds-button's public tokens for an inverted surface: label to `--text-inverted`, background to
|
|
101
|
+
`transparent`, and hover and active backgrounds to `--surface-inverted-hover`. No new token —
|
|
102
|
+
these are ds-button's existing hooks.
|
|
103
|
+
|
|
104
|
+
- **The skeleton shimmer stepped instead of sweeping, on any page but a light one.** The travel was
|
|
105
|
+
`--skeleton-shimmer-x`, one animated, registered, INHERITED custom property on `:root` that
|
|
106
|
+
every skeleton read through `mask-position`. A registered custom property is a computed value, so changing it invalidated
|
|
107
|
+
style for the ENTIRE document on every frame and then repainted — fine on the docs site, visibly
|
|
108
|
+
jerky inside a heavy host application. The animation moved onto each skeleton's own band,
|
|
109
|
+
animating `mask-position` per element; `--skeleton-shimmer-x` and the `:root` animation that drove
|
|
110
|
+
it are gone, so anything that referenced it now resolves to nothing. The trade is that a skeleton mounted mid-cycle starts its own pass instead
|
|
111
|
+
of joining the one in flight; the old lock-step was never viewport-anchored anyway, because
|
|
112
|
+
`mask-position` is measured from the host's own box.
|
|
113
|
+
- **A focused row drew TWO rings, and neither was the focus colour.** `ds-list-item`, `ds-tree`,
|
|
114
|
+
`ds-tag`, `ds-description-list` and `ds-color-picker` each drew their own `outline` on
|
|
115
|
+
`:focus-visible` while the blanket `:where(:focus-visible)` shadow kept painting under it — an
|
|
116
|
+
accent halo outside, their own outline inside. Worse, that outline asked for
|
|
117
|
+
`--focus-ring-color`, which **nothing defined**, so all seven call sites fell through to
|
|
118
|
+
`currentColor` and ringed themselves in their own text colour: near-black on a list row, grey on
|
|
119
|
+
a tree node. The token is defined now, from the same hue channels as the ring's outer halo, and
|
|
120
|
+
the seven sites share a `focus.outline-indicator` mixin that silences the shadow. The colour is
|
|
121
|
+
`--accent`, so it is the brand hue by default and the family's hue inside a `ds-color` zone —
|
|
122
|
+
measured: `hsl(229 100% 59%)` outside, `hsl(0 75% 49%)` under `[ds-color="error"]`. Override it
|
|
123
|
+
per brand with `--focus-ring-color`.
|
|
124
|
+
- **A selected `ds-list-item` or `ds-tree` node retinted its label and left its icon behind.**
|
|
125
|
+
On the list the icon stayed on its resting colour beside an accent label; on the tree the row
|
|
126
|
+
set `color` correctly but `.node-icon` declared its own and won. Both follow the label now,
|
|
127
|
+
through new
|
|
128
|
+
`--ds-list-item-selected-icon-color` / `--ds-tree-row-selected-icon-color` hooks that default to
|
|
129
|
+
the selected label colour.
|
|
130
|
+
- **`ds-avatar-group` and `ds-button-group` styled their children by tag name, so a host that
|
|
131
|
+
renames the tag got neither.** Both pierced encapsulation with `::ng-deep ds-avatar` /
|
|
132
|
+
`::ng-deep ds-button`. Measured through the custom-element build, where a tag nested inside
|
|
133
|
+
another component's template has to be renamed (angular/angular#24536), all three
|
|
134
|
+
avatars came back `margin-left: 0` with no ring, and the joined buttons lost their overlap
|
|
135
|
+
margin and every flattened radius. They match the direct child now, so the grouping holds whatever the child is rendered
|
|
136
|
+
as. Computed output in an ordinary Angular app is unchanged — verified identical before and
|
|
137
|
+
after.
|
|
138
|
+
|
|
139
|
+
- **Six connected-panel tokens did nothing when scoped to one picker.** `--ds-option-padding`,
|
|
140
|
+
`-gap`, `-radius`, `-row-gap`, `--ds-option-bg-color-active` and `--ds-dropdown-panel-maxh` are read
|
|
141
|
+
on the panel, which the CDK portals outside the component, so they only ever resolved from a global
|
|
142
|
+
declaration: `ds-select { --ds-option-padding: … }` was silently ignored while
|
|
143
|
+
`ds-select { --ds-dropdown-panel-radius: … }` beside it worked, because that one was on the
|
|
144
|
+
forwarded list and these were not. They join the shared list every connected picker forwards, so the
|
|
145
|
+
family behaves one way. `--ds-dropdown-panel-maxh` was also the one token `ds-autocomplete` forwarded
|
|
146
|
+
and its two siblings did not. Nothing moves unless you had written one of these on an element, where
|
|
147
|
+
it now takes effect — if you reached for a global declaration because the scoped one did nothing, the
|
|
148
|
+
scoped one is the narrower fix.
|
|
149
|
+
|
|
150
|
+
- **`ds-split-button`'s hover left its label unreadable inside a status zone.** The hover background defaulted to the family's readable ON-TINT colour — the one meant for text on light surfaces — and this was the only place in the library using it as a background, so the label landed at 1.87:1 on `success` in dark and 2.46:1 on `error`. It now defaults to `--accent-hover`, the family base mixed toward black in light and white in dark, so the hover follows the rest state instead of jumping to another hue: error 5.94 light / 4.22 dark, success 4.17 / 2.85, warning 9.11 / 12.31. `--ds-split-button-bg-hover-color` still overrides it.
|
|
151
|
+
|
|
152
|
+
This does not close the whole problem. The label colour on a family's solid background already falls below 4.5:1 at REST for `success` (3.30) and `secondary` (3.31), in both themes and on every solid button — a palette question, not this component's.
|
|
153
|
+
|
|
154
|
+
- **A chip row could drop a chip, or fail to, when the field sat in a box that sizes itself to its content.** The budget for how many chips fit comes off the trigger's parent, which is only a fixed quantity while that parent takes its width from somewhere else. A parent at `fit-content`, an `inline-block` one, or a flex item that cannot grow all take their width from the chips instead, so the cut was reading back its own result. The parent is now asked whether its width depends on the trigger, and the trigger's own width is used only when it cannot answer. Affects `ds-multi-select` and `ds-autocomplete`.
|
|
155
|
+
|
|
156
|
+
- **Eight defects the two-wave review confirmed and nobody had acted on.** The toast region and its
|
|
157
|
+
service never tore anything down, so every pending timer fired into a destroyed component — harmless
|
|
158
|
+
in a long-lived app, a stream of "N timers still in the queue" in a consumer's `fakeAsync` tests. The
|
|
159
|
+
180 ms leave timer was untracked and survived `dismissAll()`. `remove()` had no existence guard, so a
|
|
160
|
+
stale `ToastRef.dismiss()` ran the whole leave path on an id nothing held. `LEAVE_DURATION_MS` was
|
|
161
|
+
hardcoded against `--ds-toast-leave-duration`, a public token: the leave length is now READ off the
|
|
162
|
+
node, measured at 964 ms with the token set to 900, where it used to be 180 whatever the consumer
|
|
163
|
+
asked for. Raising `maxVisible` at runtime promoted nothing until the next dismissal; promotion is a
|
|
164
|
+
drain loop now. A negative `maxVisible` said the opposite of what it did and warns in dev. The
|
|
165
|
+
spinner inside a `loading` toast carried its own `role="status"`, which — now that announcements have
|
|
166
|
+
moved to the announcer — was the only live node left in there, so it is `aria-hidden`. And
|
|
167
|
+
`ToastPromiseMessages` is generic, so `promise<T>` stops discarding `T` and a `success` callback
|
|
168
|
+
receives the resolved value instead of `unknown`.
|
|
169
|
+
|
|
170
|
+
|
|
171
|
+
- **A modal, drawer, confirm or bottom sheet opened after a toast covered it and swallowed its action
|
|
172
|
+
button.** `--layer-toast: 1500` could not prevent it and never could: CDK 21 gives every overlay host
|
|
173
|
+
`popover="manual"` and calls `showPopover()`, so hosts live in the browser's top layer, which paints
|
|
174
|
+
strictly in the order things were shown and ignores z-index and stacking contexts. The toast host is
|
|
175
|
+
now re-shown when a scrimmed overlay appears, which is the only thing that moves it back to the
|
|
176
|
+
front. Measured before and after on the same probe: the scrim was the topmost element at the toast's
|
|
177
|
+
centre, and is not any more.
|
|
178
|
+
|
|
179
|
+
Only *scrimmed* overlays trigger it. A tooltip or dropdown neither covers the toast meaningfully nor
|
|
180
|
+
eats a click, and the documented scale deliberately puts `--layer-tooltip` above the toast.
|
|
181
|
+
|
|
182
|
+
|
|
183
|
+
- **Typing on a CLOSED `ds-select` did nothing.** Type-ahead landed with the jump wired only for
|
|
184
|
+
an open panel: the closed branch of the key handler returned before reaching it, so a letter
|
|
185
|
+
pressed on a collapsed trigger neither jumped nor committed. It now commits the first
|
|
186
|
+
matching option without opening the panel — `value` is a `model`, so `valueChange` fires —
|
|
187
|
+
the way a native `<select>` does; a key that matches nothing is ignored.
|
|
188
|
+
- **A `ds-table` loading scrim covered the top of the first row, or overlapped the header.**
|
|
189
|
+
Its top edge assumed a 40px header. The header is 42.89px at the default density and
|
|
190
|
+
26.89px under `[data-density="ultra-compact"]`, so it cut 2.89px into the header normally
|
|
191
|
+
and started 13.11px too low under that density, where the first row showed through it. The
|
|
192
|
+
header is measured now, so the edge lands on it at every density and at any header font size
|
|
193
|
+
you set. `--ds-table-head-h` still overrides it if you set that, which you should no longer
|
|
194
|
+
need to.
|
|
195
|
+
- **One export left `ds-table`'s live region stuck for the rest of the page's life.** The export
|
|
196
|
+
status outranked the sort, row-range and row-expansion lines and was never cleared, so from the
|
|
197
|
+
first export onwards a screen reader heard "Export ready" and nothing else: every later sort,
|
|
198
|
+
page change and bulk expansion was swallowed. The export line now holds the region only until
|
|
199
|
+
one of those lines has something new to say, so "Export failed" still stands until the reader
|
|
200
|
+
moves on, and everything after it is announced again.
|
|
201
|
+
|
|
202
|
+
## 0.11.3 — 2026-09-02
|
|
203
|
+
|
|
204
|
+
### Breaking
|
|
205
|
+
|
|
206
|
+
- **`ds.color()` now refuses a family it does not know, and that stops your Sass build.**
|
|
207
|
+
`@include ds.color(brand)` used to compile and emit eleven `--accent-*` pointers at values that
|
|
208
|
+
could never resolve, so a zone painted itself with `unset` and the mistake looked like a theming
|
|
209
|
+
problem. It `@error`s now, naming the five families it takes: `secondary`, `tertiary`, `error`,
|
|
210
|
+
`success`, `warning`. Anything else fails the build at the `@include`. The `ds-color="…"`
|
|
211
|
+
attribute is untouched — no Sass runs for it.
|
|
212
|
+
|
|
213
|
+
### Changed
|
|
214
|
+
|
|
215
|
+
- **The banner and toast icon now centres on the message block**, where most shapes aligned it to
|
|
216
|
+
the first line of text. The two rules agree on a one-line message — which is most toasts — and
|
|
217
|
+
diverge as the text grows: the icon sat some 12px above the block centre at two lines and 21px at
|
|
218
|
+
three. A `compact` banner was already centred and does not move.
|
|
219
|
+
|
|
220
|
+
It is `align-self` on the icon rather than `align-items` on the row, so the close button and the
|
|
221
|
+
action buttons keep the positions they had. `--banner-ic-mt` is **removed**; it existed only to
|
|
222
|
+
nudge the icon down by one border-width under the old rule.
|
|
223
|
+
|
|
224
|
+
`ds-alert` follows, for the same reason: it carried the same nudge inlined as
|
|
225
|
+
`var(--border-width-default)` rather than through the token.
|
|
226
|
+
|
|
227
|
+
**Known limit.** The icon centres on the flex LINE, which equals the message block only while the
|
|
228
|
+
message is the tallest thing in the row. A one-line toast with a close button is 0.53px off, and with
|
|
229
|
+
a projected `[actions]` button 6–14px off depending on its size. `align-items: center` would be
|
|
230
|
+
unconditional but moves the close button, which is the trade above.
|
|
231
|
+
|
|
232
|
+
- **`ToastRegionComponent`'s member surface moved again — only matters if you SUBCLASS it.** The
|
|
233
|
+
timer and pause work gained `arm`, `focusWithin`, `host`, `hovered`, `onFocusWithin`, `onHover`,
|
|
234
|
+
`paused`, `pauseAll`, `remaining`, `resumeAll`, `startedAt` and `syncPause`, and **lost
|
|
235
|
+
`startCountdown`**: a countdown is armed when a toast becomes visible and re-armed from what is
|
|
236
|
+
left when a pause ends, where before the region started one timer per toast. Every one is a
|
|
237
|
+
`private` or `protected` internal — none is public API, none is a signal, and there is no
|
|
238
|
+
replacement to call for `startCountdown`, so an override of it should simply go. A member of
|
|
239
|
+
yours sharing one of those names still stops the build, because `private` collides with TS2415
|
|
240
|
+
exactly as a public name does. `host` is the one most likely to clash.
|
|
241
|
+
Rename yours — `override` is not a way out for ten of the twelve, because a member whose base
|
|
242
|
+
declaration is `private` rejects it with the same TS2415 as a plain redeclaration, and that
|
|
243
|
+
includes `host`. Only the two `protected` ones, `onHover` and `onFocusWithin`, accept it. The
|
|
244
|
+
compiler enumerates every
|
|
245
|
+
collision, so building after the upgrade is the whole check.
|
|
246
|
+
|
|
247
|
+
Worth flagging for anyone who followed 0.11.2's note: `startCountdown` was announced there as a
|
|
248
|
+
member the region had just gained, so an `override startCountdown` added one release ago now
|
|
249
|
+
overrides nothing and silently never runs. There is no public replacement to call — the countdown
|
|
250
|
+
is the region's own business now. Delete the override.
|
|
251
|
+
|
|
252
|
+
- **`components.md` documented a component that does not exist and four events that never fired.**
|
|
253
|
+
It carried a `<ds-dropdown>` entry through nine releases; that component was absorbed into
|
|
254
|
+
`<ds-select>` and an import written from the document fails to compile. Four documented event
|
|
255
|
+
names were never identifiers here: `ds-banner` and `ds-toast` emit `(closed)`, not `(dismissed)`;
|
|
256
|
+
`ds-pagination` emits `(currentPageChange)`, not `(pageChange)`; `ds-table` emits `(rowClicked)`,
|
|
257
|
+
not `(rowClick)`. An unknown event binding registers a DOM listener and never fires, so those
|
|
258
|
+
four handlers were silently dead with nothing in the console. `<ds-alert>` was missing from the
|
|
259
|
+
document entirely and is now in it, `'neutral'` variant included.
|
|
260
|
+
|
|
261
|
+
### Fixed
|
|
262
|
+
|
|
263
|
+
- **`ds-color="error"`, `="success"` and `="warning"` lost their accent colour.** Those zones map
|
|
264
|
+
`--accent-strong` onto `--<family>-strong`, and the three status families never defined it — only
|
|
265
|
+
the brand families did. The declaration was invalid at computed-value time, so inside a status
|
|
266
|
+
zone every place that reads `--accent-strong` reset to `unset`: selected list and tree rows,
|
|
267
|
+
the active sidenav item and its rail, the active tab pill, avatar and avatar-group initials, the
|
|
268
|
+
active tag, dropzone text, the date-picker range label, the toast's action label, the selected
|
|
269
|
+
toggle button, the split-button hover fill, the `tonal`, `ghost`, `outline` and `text` variants
|
|
270
|
+
of `ds-button`, and the `tonal` variant of `ds-icon-button`. Text there fell through to the
|
|
271
|
+
inherited body colour; the fill
|
|
272
|
+
and the rail, which inherit nothing, disappeared.
|
|
273
|
+
|
|
274
|
+
No new token was needed: a status family already carries its readable on-tint colour as `-text`,
|
|
275
|
+
so `--accent-strong` now asks for `-strong` first and `-text` second, and the brand families keep
|
|
276
|
+
answering it as `-strong` because they have no `-text`. Each pointer also ends in a fallback — to
|
|
277
|
+
the family's base for `-hover`, `-pressed` and `-strong`, to its `-muted` for the tint pointers,
|
|
278
|
+
and to the theme-wide role for `-on` and the two focus pointers — so a role that goes missing in
|
|
279
|
+
future degrades instead of disappearing.
|
|
280
|
+
|
|
281
|
+
- **`ToastService.promise()` could destroy its own result.** It ran the settled toast's
|
|
282
|
+
auto-dismiss on a wall-clock timer started when the promise resolved, not when the toast became
|
|
283
|
+
visible — the one thing the rest of the timer work had already moved into the region. With a
|
|
284
|
+
`maxVisible` cap set, a promise that settled while its toast was still queued had the result spliced
|
|
285
|
+
out of the queue before anyone saw it: the user saved, it succeeded, and no toast appeared at all.
|
|
286
|
+
The settled duration is now handed to the region with the content, so it starts on promotion.
|
|
287
|
+
|
|
288
|
+
- **A toast carrying an `action` no longer auto-dismisses.** The overlay is the last child of `body`,
|
|
289
|
+
so the region is dead last in tab order; a keyboard user cannot cross a real page in the five
|
|
290
|
+
seconds the button was alive. An `action` toast now waits, and is always dismissible. Note that
|
|
291
|
+
a `durationMs` you pass alongside an `action` is discarded — the toast waits regardless — and
|
|
292
|
+
`dismissible: false` is discarded on any toast that cannot expire, not only on a `loading` one.
|
|
293
|
+
|
|
294
|
+
- **Hovering or focusing the region pauses every countdown**, resuming when the pointer or focus
|
|
295
|
+
leaves. A toast being read is not a toast that has been read. The pause is derived from both
|
|
296
|
+
sources rather than latched, so tabbing out of a region the pointer is still over does not
|
|
297
|
+
resume, moving focus between the action and the close button is not a leave, and a toast that
|
|
298
|
+
becomes visible under a stationary pointer — a burst past the cap, or a promise settling — is
|
|
299
|
+
banked rather than counted. A toast paused with almost nothing left resumes with at least 600ms, so
|
|
300
|
+
one hovered with
|
|
301
|
+
almost nothing left does not vanish as the pointer leaves.
|
|
302
|
+
|
|
303
|
+
- **A disabled accordion item's chevron did not look disabled.** It asked for a colour token this
|
|
304
|
+
library does not define, so the declaration was invalid at computed-value time and the chevron
|
|
305
|
+
inherited whatever colour surrounded it — while the label beside it greyed correctly. It reads the
|
|
306
|
+
disabled text colour now, like the label.
|
|
307
|
+
|
|
308
|
+
- **The `ds-banner` close button had no accessible name.** It announced as a bare "button", where
|
|
309
|
+
the same control on `ds-toast` and `ds-alert` already said "Dismiss". It says it now.
|
|
310
|
+
|
|
311
|
+
- **A long unbroken word in a toast overflowed the pill.** A URL or an id with no break
|
|
312
|
+
opportunity ran past the rounded edge instead of wrapping inside it.
|
|
313
|
+
|
|
314
|
+
- **Nothing that cannot expire can also be unclosable.** The rule is now that any toast with no
|
|
315
|
+
duration is dismissible, whatever you asked for — a `loading` variant, one carrying an `action`,
|
|
316
|
+
or an explicit `durationMs: 0`. A `loading` toast was created with `dismissible: false` and no
|
|
317
|
+
duration, so a promise that never settled held its slot for the life of the page — with a cap of 3, three hung requests blocked the whole channel, including the error
|
|
318
|
+
toasts that would have explained the hang.
|
|
319
|
+
|
|
11
320
|
## 0.11.2 — 2026-09-01
|
|
12
321
|
|
|
13
322
|
### Added
|
|
@@ -168,14 +477,13 @@ While the package is on `0.x`, minor releases may contain breaking changes.
|
|
|
168
477
|
|
|
169
478
|
### Fixed
|
|
170
479
|
- **Dev-mode warnings no longer ship to production bundles.** They were guarded by
|
|
171
|
-
`isDevMode()`, which is a function CALL — a bundler cannot prove the branch dead, so all
|
|
480
|
+
`isDevMode()`, which is a function CALL — a bundler cannot prove the branch dead, so all thirteen
|
|
172
481
|
warning sites and their message closures reached production builds. Each site is now guarded inline
|
|
173
482
|
with `typeof ngDevMode === 'undefined' || ngDevMode`, which `@angular/build` folds away whenever
|
|
174
483
|
script optimization is on, closures included. **Measured: 1 590 B gzip off an app using most of the
|
|
175
484
|
library, 827 B of it off a single `<ds-button>`.** Nothing changes for you — no API, no behaviour,
|
|
176
485
|
and the warnings still fire in development builds exactly as before.
|
|
177
486
|
|
|
178
|
-
|
|
179
487
|
- **A loading scrim stopped the pointer and let the keyboard walk straight under it.**
|
|
180
488
|
`ds-loading-overlay` paints an absolutely positioned scrim over its content, which intercepts
|
|
181
489
|
every pointer event — so a control behind it could not be clicked, and looked unavailable. Nothing
|
|
@@ -2738,6 +3046,15 @@ genuine gap worth reporting.
|
|
|
2738
3046
|
- **Fields no longer expose a `protected messageState`;** the resolved `message` (text + state) and
|
|
2739
3047
|
`invalidResolved` replace it. Only reachable by subclassing a field component, which is not a
|
|
2740
3048
|
supported extension point, but noted for parity with the class-member changes in 0.7.0.
|
|
3049
|
+
- **The `ds-time-picker` panel lost its corner radius.** It had drawn `--radius-md` (8px) while every
|
|
3050
|
+
other floating surface — popovers, cards, modals and `ds-date-picker`'s own calendar — resolves the panel
|
|
3051
|
+
role. The move onto that role reads a private `:host` token, which a CDK-portaled panel cannot see, so
|
|
3052
|
+
`border-radius` resolves to its initial `0` and the panel renders SQUARE. The new
|
|
3053
|
+
`--ds-time-picker-panel-radius` hook is inert for the same reason. Force the corner back with a global
|
|
3054
|
+
`.cdk-overlay-container { --_time-picker-panel-radius: var(--radius-md); }`. It declares the
|
|
3055
|
+
private token the panel already reads on an ancestor the panel DOES have, so it inherits down;
|
|
3056
|
+
fighting the component’s own rule with a selector is not needed. A rule scoped under
|
|
3057
|
+
`ds-time-picker` cannot reach the portaled panel at all. The trigger's radius is untouched.
|
|
2741
3058
|
|
|
2742
3059
|
### Fixed
|
|
2743
3060
|
|
|
@@ -2773,16 +3090,6 @@ genuine gap worth reporting.
|
|
|
2773
3090
|
layout's open rail instead of beneath it. The host now sets `isolation: isolate`, giving each
|
|
2774
3091
|
`ds-app-layout` its own stacking context — the same fix `ds-drawer` already carries. Nothing changes
|
|
2775
3092
|
for a full-viewport shell with no layout embedded inside it.
|
|
2776
|
-
- **The `ds-time-picker` panel drew the CONTROL radius, so it did not match the date picker beside it.**
|
|
2777
|
-
Its dropdown was the one floating panel left on `--radius-md` (8px) while every other surface — menus,
|
|
2778
|
-
popovers, cards, modals, and `ds-date-picker`'s own calendar — resolves the panel role. Two pickers in
|
|
2779
|
-
one form therefore rendered different corners. The panel now reads
|
|
2780
|
-
`var(--ds-time-picker-panel-radius, var(--ds-radius-panel))`, which is 12px, and the new hook is
|
|
2781
|
-
FORWARDED onto the portaled pane — a token declared without being forwarded is dead for per-instance
|
|
2782
|
-
overrides, which is exactly the `--ds-overlay-enter-scale` bug fixed elsewhere in this release. It was
|
|
2783
|
-
also the only property on that element without a hook, since fill, border and shadow all had one.
|
|
2784
|
-
Restore the old corner with `ds-time-picker { --ds-time-picker-panel-radius: var(--radius-md); }`; the
|
|
2785
|
-
trigger's radius is untouched.
|
|
2786
3093
|
- **A path change that only mirrors the reader's position no longer resets the content scroll.** A docs shell whose scroll spy rewrites `/area/section` as the user scrolls hit a loop: the rewrite looked like a page change, the layout scrolled to top, the spy saw the first section again and rewrote the path back. Such a navigation must now carry `state: { dsSamePage: true }`, which the layout skips for both the scroll reset and the rail close. Read from `Router.lastSuccessfulNavigation()` — `getCurrentNavigation()` is already cleared when `NavigationEnd` reaches a subscriber.
|
|
2787
3094
|
- **Closing the rail by NAVIGATING no longer pulls focus back to the burger.** Restoring focus to the trigger is right for a dismissal — Escape, the scrim — and wrong for a link: the reader activated it, so focus belongs wherever the router put it, and handing it back announced "Open navigation" instead of the page they asked for. Dismissal keeps the restore; the navigation and breakpoint paths now clear `railOpen` directly. The breakpoint path had also depended on `compact` being written one line earlier to avoid focusing a trigger that is hidden on desktop — that ordering trap is gone with it.
|
|
2788
3095
|
- **A closed compact `ds-app-layout` rail no longer holds focus behind the screen.** Below the
|
package/components.md
CHANGED
|
@@ -2,6 +2,12 @@
|
|
|
2
2
|
|
|
3
3
|
> Index of the design system components, global helpers, tokens and icons. Use it as a single reference when migrating UI to DS.
|
|
4
4
|
>
|
|
5
|
+
> **If you are an agent, read `docs/agent/INDEX.md` instead of this file.** The same content
|
|
6
|
+
> is generated there as an index plus one leaf per entry, so answering a question about one
|
|
7
|
+
> component costs ~1.6 KB and the index, not the 58 KB of this catalogue. This file stays the
|
|
8
|
+
> single place a human edits — the leaves are derived from it and a CI gate fails when they
|
|
9
|
+
> drift.
|
|
10
|
+
>
|
|
5
11
|
> **This file is the WHAT — the inventory.** For the HOW (which spacing between what,
|
|
6
12
|
> which type role where, how a page is composed) see `design-system.md`, which carries
|
|
7
13
|
> the rules this catalogue deliberately does not.
|
|
@@ -293,14 +299,21 @@ Content slot: `[actions]` — CTA buttons / links.
|
|
|
293
299
|
|
|
294
300
|
#### `<ds-banner>` — `BannerComponent`
|
|
295
301
|
Inputs: `variant: 'info' | 'success' | 'warning' | 'severe' | 'error' | 'neutral' = 'info'`, `title: string = ''`, `dismissible: boolean = false`, `icon: IconName | null = null` (variant-derived default), `compact: boolean = false`, `layout: 'stacked' | 'row' = 'stacked'`, `accentRail: boolean = true`
|
|
296
|
-
Output: `(
|
|
302
|
+
Output: `(closed): void`
|
|
297
303
|
Content slots: default (body text), `[actions]` (trailing CTAs)
|
|
298
304
|
- `layout="stacked"` (default): actions wrap onto a new line, indented under the body. Use for multi-line messages or multiple CTAs.
|
|
299
305
|
- `layout="row"`: actions sit at the right edge, vertically centred with the body. Use for one-line messages with a single trailing CTA.
|
|
300
306
|
|
|
307
|
+
#### `<ds-alert>` — `AlertComponent`
|
|
308
|
+
Inline message, `ds-banner`'s smaller twin — same anatomy, sized for placement inside a form or a card rather than across a page.
|
|
309
|
+
Inputs: `variant: 'info' | 'success' | 'warning' | 'error' | 'neutral' = 'info'`, `title: string = ''`, `dismissible: boolean = false`, `icon: IconName | null = null` (variant-derived default)
|
|
310
|
+
Output: `(closed): void`
|
|
311
|
+
Content slots: default (body text), `[actions]` (trailing CTAs)
|
|
312
|
+
|
|
301
313
|
#### `<ds-toast>` — `ToastComponent`
|
|
302
|
-
Inputs: `variant: 'info' | 'success' | 'warning' | 'error' = 'info'`, `title: string = ''`, `message: string = ''`, `dismissible: boolean = false`, `icon: IconName | null = null` (variant-derived default)
|
|
303
|
-
Output: `(
|
|
314
|
+
Inputs: `variant: 'info' | 'success' | 'warning' | 'error' | 'loading' = 'info'`, `title: string = ''`, `message: string = ''`, `dismissible: boolean = false`, `icon: IconName | null = null` (variant-derived default), `action: ToastAction | null = null` (`{ label, handler }` — renders a trailing button)
|
|
315
|
+
Output: `(closed): void`
|
|
316
|
+
Content slots: default (body text, an alternative to `message`), `[actions]` (trailing CTAs). Neither is reachable through `ToastService`, which renders from `ToastOptions` — they are for a `<ds-toast>` you place yourself.
|
|
304
317
|
|
|
305
318
|
The companion `<ds-toast-region>` lives inside the `ToastService` (see Services) — it is auto-mounted via a CDK overlay on first `toast.show()`, so consumers do **not** need to place `<ds-toast-region>` anywhere in their markup. Render `<ds-toast>` directly only for static specimens.
|
|
306
319
|
|
|
@@ -367,7 +380,7 @@ Inputs: `steps: readonly string[] = []`, `current: number = 0`. Horizontal step
|
|
|
367
380
|
|
|
368
381
|
#### `<ds-pagination>` — `PaginationComponent`
|
|
369
382
|
Inputs: `total: required number`, `pageSize: model<number> = 10`, `currentPage: model<number> = 1`, `pageSizeOptions: number[] = [10, 25, 50, 100]`, `showLabel: boolean = true`
|
|
370
|
-
Outputs: `(
|
|
383
|
+
Outputs: `(currentPageChange): number`, `(pageSizeChange): number`
|
|
371
384
|
|
|
372
385
|
#### `<ds-divider>` — `DividerComponent`
|
|
373
386
|
Inputs: `variant: 'default' | 'strong' | 'vertical' | 'label' = 'default'`, `spacing: 'none' | 'sm' | 'md' | 'lg' = 'md'`
|
|
@@ -422,18 +435,13 @@ Renders `<ds-tooltip-panel>` via CDK overlay on hover / focus; hides on leave /
|
|
|
422
435
|
#### `<ds-menu>` + `<ds-menu-item>` — `MenuComponent`, `MenuItemComponent`
|
|
423
436
|
Menu is a container. Item inputs: `icon: IconName | null = null`, `disabled: boolean = false`, `danger: boolean = false`. Output: `(pressed): MouseEvent`. Content: label text; supports `[icon]` content slot for custom icons.
|
|
424
437
|
|
|
425
|
-
#### `<ds-dropdown>` — `DropdownComponent`
|
|
426
|
-
Trigger button + CDK overlay panel combo.
|
|
427
|
-
Inputs: `value: model<string> = ''`, `options: DropdownOption[]` (`{ label, value, disabled?, icon? }`), `placeholder: string = 'Select…'`, `size: 'sm' | 'md' | 'lg' = 'md'`, `label: string = ''`, `disabled: boolean = false`, `readOnly: boolean = false`, `error: boolean = false`, `name: string | null = null`
|
|
428
|
-
Selection is communicated via the `value` model. Keyboard: ArrowUp/Down, Enter/Space, Home/End, Escape.
|
|
429
|
-
|
|
430
438
|
---
|
|
431
439
|
|
|
432
440
|
### Tables
|
|
433
441
|
|
|
434
442
|
#### `<ds-table>` — `TableComponent<T extends { id: string }>`
|
|
435
443
|
Inputs: `data: required readonly T[]`, `columns: required readonly TableColumn<T>[]`, `selectable: boolean = false`, `bordered: boolean = false` (opt-in outer border + radius; off by default so tables flush inside `<ds-card padding="none">` don't double-border), `loading: false | 'skeleton' | 'overlay' = false`, `stickyHeader: boolean = true`, `selectedIds: model<Set<string>>`, `sortKey: model<string | null>`, `sortDir: model<SortDir>` (`'asc' | 'desc' | null`), `skeletonRows: number = 5`
|
|
436
|
-
Outputs: `(
|
|
444
|
+
Outputs: `(rowClicked): T`, `(sortChange): SortChangeEvent` (`{ key, dir }`)
|
|
437
445
|
Column shape: `{ key: string, label: string, sortable?: boolean, align?: 'left' | 'right' | 'center', cell?: (row: T) => string }`
|
|
438
446
|
Opening a row: give one column `link: (row) => <route target> | null` and its value renders as a real `<a>` — visible without hovering, in the tab order as a link, and Ctrl/Cmd-clickable, none of which a clickable `<tr>` can do. `null` for a row leaves that cell as plain text, so a partly-reachable list stays one column; external URLs go through a `[dsCellTemplate]` instead, since `link` takes Angular route targets only. It composes with `rowInteractive` (the link stops its click from reaching the row), but the two together cost **two tab stops per row** — on a long list prefer the link alone. `interactive: true` only tints a cell on row hover, which a keyboard or touch user never sees; prefer `link` wherever the row actually leads somewhere.
|
|
439
447
|
Cell templates: `<ng-template dsCellTemplate="<colKey>" let-row>…</ng-template>` — `row` is typed `unknown`, narrow via a helper method on the host.
|
|
@@ -575,10 +583,25 @@ this.crumbs.clear();
|
|
|
575
583
|
|
|
576
584
|
#### `ToastService`
|
|
577
585
|
`@Injectable({ providedIn: 'root' })`. Inject and call:
|
|
578
|
-
- `show(opts: ToastOptions): ToastRef` — `{ title?, body, variant?: 'info' | 'success' | 'warning' | 'error', dismissible?, durationMs? = 5000 }`. Returns `{ id, dismiss() }`.
|
|
586
|
+
- `show(opts: ToastOptions): ToastRef` — `{ title?, body, variant?: 'info' | 'success' | 'warning' | 'error' | 'loading', dismissible?, icon?, action?: ToastAction, durationMs? = 5000 }`. Returns `{ id, dismiss() }`. `durationMs: 0` (and any negative) means it never auto-dismisses, and it is counted from the moment the toast becomes VISIBLE, not from the call — a toast queued behind `maxVisible` keeps its full time on screen. A `loading` toast is forced to 0 and discards a supplied `durationMs`.
|
|
587
|
+
- `promise<T>(source: Promise<T>, messages: ToastPromiseMessages): Promise<T>` — shows a `loading` toast, then patches it in place to `success` or `error` when `source` settles. Returns `source` itself, so an un-`catch`ed call still produces an unhandled rejection. The settled toast dismisses after a hard-coded 4s (success) or 6s (error), counted from the moment it becomes visible and not overridable; `dismissAll()` cancels it like any other.
|
|
579
588
|
- `dismissAll(): void`
|
|
580
589
|
|
|
581
|
-
|
|
590
|
+
Defaults come from `provideDsConfig({ toast: … })`:
|
|
591
|
+
- `maxVisible?: number` — cap on concurrently visible toasts. Default `5`; `0` means unlimited. Extras queue and appear as earlier ones dismiss.
|
|
592
|
+
- `position?: { horizontalPosition?: 'left' | 'center' | 'right', verticalPosition?: 'top' | 'bottom', offset?: string }` — merged field by field over `right` / `top` / `var(--space-6)`, so naming one key keeps the other two.
|
|
593
|
+
|
|
594
|
+
The `toast` section resolves **once, at the root injector**, when the service is first used — unlike every other section, which a `Route` or a component can narrow. `ToastService` is `providedIn: 'root'`, so a route-level `provideDsConfig` never reaches it, and the position cannot change after the first `show()`.
|
|
595
|
+
|
|
596
|
+
On first `show()` the service lazily creates a CDK overlay and mounts a `<ds-toast-region>` into it. **Do not place `<ds-toast-region>` yourself** — the service only ever talks to the instance it created, so a hand-placed one is an invisible empty box that never receives a toast, with no warning. It appears in the generated API table only because the extractor lists every exported component.
|
|
597
|
+
|
|
598
|
+
#### `BodyScrollLockService`
|
|
599
|
+
|
|
600
|
+
`@Injectable({ providedIn: 'root' })`. Ref-counted lock on `document.body` scroll, shared by every overlay that covers the viewport — `ds-modal`, `ds-drawer`, `ds-bottom-sheet` all take one. Exported since 0.7.0 so a consumer's own full-screen overlay can participate in the same lock instead of fighting it.
|
|
601
|
+
- `lock(): void` — the FIRST call saves the current `body` overflow and hides it.
|
|
602
|
+
- `unlock(): void` — only the LAST one restores it, so closing one overlay cannot re-enable page scroll under another still open above it.
|
|
603
|
+
|
|
604
|
+
Calls must be paired: one `unlock()` per `lock()`. An unmatched `unlock()` is a no-op rather than an error, so a leaked `lock()` leaves the page unscrollable with nothing to show why.
|
|
582
605
|
|
|
583
606
|
---
|
|
584
607
|
|
package/design-system.md
CHANGED
|
@@ -101,6 +101,10 @@ Every field-shaped control resolves it — inputs, selects, pickers, search, but
|
|
|
101
101
|
field group, the number stepper. A literal `height` on a control is a bug: it will not
|
|
102
102
|
line up with its neighbours and will not follow a density change.
|
|
103
103
|
|
|
104
|
+
### Corner radius has its own section
|
|
105
|
+
|
|
106
|
+
Radius is a role, not a step, and nested radii must decrease — see §8.
|
|
107
|
+
|
|
104
108
|
### Never express a rule in pixels
|
|
105
109
|
|
|
106
110
|
`[data-density]` retunes the private spacing and height tokens underneath everything
|
|
@@ -306,7 +310,137 @@ internals.
|
|
|
306
310
|
|
|
307
311
|
---
|
|
308
312
|
|
|
309
|
-
## 8.
|
|
313
|
+
## 8. Radius
|
|
314
|
+
|
|
315
|
+
### Reach for a ROLE, never a step
|
|
316
|
+
|
|
317
|
+
Four role tokens carry every corner in the library. Occurrence counts across the library's own
|
|
318
|
+
components (measured 2026-09-01) show which one a given surface actually takes:
|
|
319
|
+
|
|
320
|
+
| Role | Resolves to | Uses | What it is for |
|
|
321
|
+
| --- | --- | --- | --- |
|
|
322
|
+
| `--ds-radius-inner` | `--radius-sm` (4px) | 37 | Something nested INSIDE a control — a tick, a kbd cap, a focus halo, a segment |
|
|
323
|
+
| `--ds-radius-control` | `--radius-md` (8px) | 26 | The control itself — button, field, tag, tooltip, segmented, search |
|
|
324
|
+
| `--ds-radius-panel` | `--radius-lg` (12px) | 13 | A surface that CONTAINS controls — card, modal, bottom sheet, popover, the picker panels, page footer |
|
|
325
|
+
| `--ds-radius-pill` | `--radius-pill` (999px) | 4 | Fully round by meaning, not by size — avatar, badge, radio, progress track |
|
|
326
|
+
|
|
327
|
+
The raw steps (`--radius-sm` … `--radius-2xl`) are the scale the roles map onto. Using one
|
|
328
|
+
directly says "this corner belongs to no role", which is almost never true. `--radius-xl` (16px)
|
|
329
|
+
and `--radius-2xl` (24px) have no consumer in the library at all — their comments in
|
|
330
|
+
the token file describe an intent, not a usage.
|
|
331
|
+
|
|
332
|
+
### Nesting: inner < control < panel, and never equal
|
|
333
|
+
|
|
334
|
+
A rounded thing inside a rounded thing needs a SMALLER radius, or the inner corner appears
|
|
335
|
+
to bulge out of the outer one. The three roles are ordered for exactly this: a field
|
|
336
|
+
(`control`, 8px) inside a card (`panel`, 12px); a tick (`inner`, 4px) inside a checkbox
|
|
337
|
+
(`control`). If two nested surfaces share a radius, one of them is wrong.
|
|
338
|
+
|
|
339
|
+
The optical rule when you need a value the roles do not cover: inner radius = outer radius
|
|
340
|
+
minus the padding between them. A 12px panel with 8px of padding wants an 8px child, not 12px.
|
|
341
|
+
|
|
342
|
+
### `--radius-flat` is a statement, not a zero
|
|
343
|
+
|
|
344
|
+
`--radius-flat` resolves to `--radius-0`, and it exists so that "this corner is deliberately
|
|
345
|
+
square" reads differently from "nobody set a radius". It is what the middle of a button
|
|
346
|
+
group and an in-range calendar day use. Writing `border-radius: 0` there loses the intent
|
|
347
|
+
the next reader needs.
|
|
348
|
+
|
|
349
|
+
### Overriding
|
|
350
|
+
|
|
351
|
+
Most components with a corner expose `--ds-<component>-radius` on `:host`, resolving through
|
|
352
|
+
the role — but not all of them, and `ds-toast` is the one to know about: it reads `--radius-lg`
|
|
353
|
+
directly, so only the raw step moves it. Retheming corners means moving the four roles rather
|
|
354
|
+
than editing components: set `--ds-radius-control` once and every control that resolves it
|
|
355
|
+
follows.
|
|
356
|
+
|
|
357
|
+
---
|
|
358
|
+
|
|
359
|
+
## 9. Page composition — where things go
|
|
360
|
+
|
|
361
|
+
The grid itself (tiers, spans, the canonical 8+4 / 6+6 / 9+3 splits, the forbidden 7+5, the
|
|
362
|
+
720px prose cap) is specified in `docs/agent/foundations/grid.md`. This section is the layer
|
|
363
|
+
above it: which region holds what, and in which order.
|
|
364
|
+
|
|
365
|
+
### The page is four regions, and three of them are components
|
|
366
|
+
|
|
367
|
+
```
|
|
368
|
+
ds-app-layout
|
|
369
|
+
├── [sidenav] ds-sidenav — reserve the rail, OUTSIDE the page grid
|
|
370
|
+
├── [topbar] ds-topbar — global, not per-page
|
|
371
|
+
└── (default) the page itself
|
|
372
|
+
├── ds-page-header — breadcrumbs · title · meta · actions · tabs
|
|
373
|
+
├── ds-filter-bar — only if the page has data to filter
|
|
374
|
+
├── the content, on .page-grid
|
|
375
|
+
└── ds-page-footer — optional, page-level actions or legal
|
|
376
|
+
```
|
|
377
|
+
|
|
378
|
+
The `ds-page-header` slots are the order the eye reads, and they are not interchangeable:
|
|
379
|
+
`[breadcrumbs]` above the title, `[title-badge]` beside it, `[meta]` under it, `[actions]`
|
|
380
|
+
right-aligned on the title line, `[tabs]` last so the tab row sits on the header's bottom
|
|
381
|
+
edge. Putting page actions anywhere else — a floating button, a row above the header —
|
|
382
|
+
breaks the one place a user has learned to look.
|
|
383
|
+
|
|
384
|
+
### Filters sit directly above the data they filter
|
|
385
|
+
|
|
386
|
+
`ds-filter-bar` goes between the header and the content, full width, with no wrapper that
|
|
387
|
+
could clip its overflow popover. Not in a sidebar, not inside the table's own card, not
|
|
388
|
+
above the page header. A filter placed away from its data stops reading as a control over
|
|
389
|
+
that data, and the 9+3 split is what a genuine filter RAIL is for — reserved, not the
|
|
390
|
+
default.
|
|
391
|
+
|
|
392
|
+
### Primary action per region, once
|
|
393
|
+
|
|
394
|
+
One primary (default `variant`) per region: one in the page header, one per card, one in a
|
|
395
|
+
modal's `[actions]`. A second primary in the same region makes neither primary. Secondary
|
|
396
|
+
work takes `outline`, dismissive work takes `ghost`. A modal's actions read
|
|
397
|
+
destructive-last: cancel then confirm, never the reverse.
|
|
398
|
+
|
|
399
|
+
### When content belongs in a card, and when it does not
|
|
400
|
+
|
|
401
|
+
A `ds-card` earns its border when the content inside it is a UNIT that could be moved,
|
|
402
|
+
collapsed or repeated — a record summary, a KPI tile, one form section. It does not earn one
|
|
403
|
+
for "this page has content": a full-width table already has its own frame (`ds-table`
|
|
404
|
+
resolves `--ds-radius-control`), and a card around it double-borders. The DS default is no card;
|
|
405
|
+
reach for one when the boundary means something.
|
|
406
|
+
|
|
407
|
+
### Supporting information goes under, never beside
|
|
408
|
+
|
|
409
|
+
Hints, counts, timestamps and helper text sit UNDER the thing they describe, at
|
|
410
|
+
`--space-1`. Beside is reserved for actions. `ds-field-message` is the mechanism for a
|
|
411
|
+
field; for anything else it is a `.t-s` line at `--text-secondary`. Never a tooltip: a
|
|
412
|
+
tooltip is hover-only, so it cannot carry information the user needs in order to act.
|
|
413
|
+
|
|
414
|
+
### The pattern catalogue
|
|
415
|
+
|
|
416
|
+
Five page shapes cover what the DS is built for. Naming which one you are building settles
|
|
417
|
+
most placement questions before they come up:
|
|
418
|
+
|
|
419
|
+
| Pattern | Made of | The rule that is easy to miss |
|
|
420
|
+
| --- | --- | --- |
|
|
421
|
+
| **List + filters** | header · filter-bar · `ds-table` (or a card list) · `ds-pagination` | Filters above the data, pagination below it, both full width |
|
|
422
|
+
| **Record detail** | header with `[meta]` · 8+4 grid — main left, meta sidebar right | The sidebar is metadata, never navigation |
|
|
423
|
+
| **Form** | header · one `ds-card` per section · actions in the last card | One primary; submit gates on presence, never on validity |
|
|
424
|
+
| **Dashboard** | header · a row of `ds-stat` tiles · charts or tables below | Tiles are one row that wraps, not a grid you hand-place |
|
|
425
|
+
| **Empty / error** | `ds-empty-state` centred in the region that would have held the data | It replaces the region, not the page — header and filters stay |
|
|
426
|
+
|
|
427
|
+
### Checking a composition, instead of eyeballing it
|
|
428
|
+
|
|
429
|
+
Five checks, in the order that catches the most:
|
|
430
|
+
|
|
431
|
+
1. **Every gap is a token.** A literal `px` between two elements will not follow
|
|
432
|
+
`[data-density]` — see §3. Grep the diff for `px` outside a token declaration.
|
|
433
|
+
2. **Every span is a column.** `col-span-*` on `.page-grid`, and the split is 8+4, 6+6 or
|
|
434
|
+
9+3. If a region needs 7+5, the content is wrong, not the grid.
|
|
435
|
+
3. **One grid per page.** A sub-region aligns to the page tracks; a local `display: grid`
|
|
436
|
+
with its own columns is how alignment drifts one screen at a time.
|
|
437
|
+
4. **Nested radii decrease.** See §8. Two nested surfaces with the same radius is a defect
|
|
438
|
+
you can see once you look for it.
|
|
439
|
+
5. **One primary per region**, and prose capped at `--col-cap-text`.
|
|
440
|
+
|
|
441
|
+
---
|
|
442
|
+
|
|
443
|
+
## 10. Where the rest lives
|
|
310
444
|
|
|
311
445
|
The decisions this file does NOT make are the ones about which COMPONENT to reach for, and they
|
|
312
446
|
have their own home: the documentation site's `Practice → Do / Don't` (modal vs drawer, button hierarchy, table
|