@ids-group-ltd/ids-design-system 0.11.1 → 0.11.3
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 +342 -31
- package/components.md +27 -12
- package/design-system.md +135 -1
- package/docs/agent/INDEX.md +98 -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/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 +19 -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 +1530 -865
- package/fesm2022/ids-group-ltd-ids-design-system.mjs.map +1 -1
- package/migrations/0.11.0.json +0 -45
- package/migrations/0.11.1.json +9 -35
- package/migrations/0.11.2.json +158 -0
- package/migrations/0.11.3.json +152 -0
- package/migrations/0.2.0.json +17 -5
- package/migrations/0.4.0.json +1 -1
- package/migrations/0.7.1.json +3 -3
- package/migrations/0.9.0.json +2 -2
- package/package.json +1 -1
- package/styles/_dropdown-overlay.scss +50 -38
- package/styles/_ds-color.scss +31 -12
- package/styles/_tokens-charts.scss +2 -3
- package/styles/_tokens.scss +159 -322
- package/themes/README.md +35 -4
- package/themes/_base-palette.scss +35 -76
- package/themes/_semantic.scss +5 -2
- package/types/ids-group-ltd-ids-design-system.d.ts +424 -188
package/CHANGELOG.md
CHANGED
|
@@ -8,6 +8,340 @@ While the package is on `0.x`, minor releases may contain breaking changes.
|
|
|
8
8
|
|
|
9
9
|
## Unreleased
|
|
10
10
|
|
|
11
|
+
## 0.11.3 — 2026-09-02
|
|
12
|
+
|
|
13
|
+
### Breaking
|
|
14
|
+
|
|
15
|
+
- **`ds.color()` now refuses a family it does not know, and that stops your Sass build.**
|
|
16
|
+
`@include ds.color(brand)` used to compile and emit eleven `--accent-*` pointers at values that
|
|
17
|
+
could never resolve, so a zone painted itself with `unset` and the mistake looked like a theming
|
|
18
|
+
problem. It `@error`s now, naming the five families it takes: `secondary`, `tertiary`, `error`,
|
|
19
|
+
`success`, `warning`. Anything else fails the build at the `@include`. The `ds-color="…"`
|
|
20
|
+
attribute is untouched — no Sass runs for it.
|
|
21
|
+
|
|
22
|
+
### Changed
|
|
23
|
+
|
|
24
|
+
- **The banner and toast icon now centres on the message block**, where most shapes aligned it to
|
|
25
|
+
the first line of text. The two rules agree on a one-line message — which is most toasts — and
|
|
26
|
+
diverge as the text grows: the icon sat some 12px above the block centre at two lines and 21px at
|
|
27
|
+
three. A `compact` banner was already centred and does not move.
|
|
28
|
+
|
|
29
|
+
It is `align-self` on the icon rather than `align-items` on the row, so the close button and the
|
|
30
|
+
action buttons keep the positions they had. `--banner-ic-mt` is **removed**; it existed only to
|
|
31
|
+
nudge the icon down by one border-width under the old rule.
|
|
32
|
+
|
|
33
|
+
`ds-alert` follows, for the same reason: it carried the same nudge inlined as
|
|
34
|
+
`var(--border-width-default)` rather than through the token.
|
|
35
|
+
|
|
36
|
+
**Known limit.** The icon centres on the flex LINE, which equals the message block only while the
|
|
37
|
+
message is the tallest thing in the row. A one-line toast with a close button is 0.53px off, and with
|
|
38
|
+
a projected `[actions]` button 6–14px off depending on its size. `align-items: center` would be
|
|
39
|
+
unconditional but moves the close button, which is the trade above.
|
|
40
|
+
|
|
41
|
+
- **`ToastRegionComponent`'s member surface moved again — only matters if you SUBCLASS it.** The
|
|
42
|
+
timer and pause work gained `arm`, `focusWithin`, `host`, `hovered`, `onFocusWithin`, `onHover`,
|
|
43
|
+
`paused`, `pauseAll`, `remaining`, `resumeAll`, `startedAt` and `syncPause`, and **lost
|
|
44
|
+
`startCountdown`**: a countdown is armed when a toast becomes visible and re-armed from what is
|
|
45
|
+
left when a pause ends, where before the region started one timer per toast. Every one is a
|
|
46
|
+
`private` or `protected` internal — none is public API, none is a signal, and there is no
|
|
47
|
+
replacement to call for `startCountdown`, so an override of it should simply go. A member of
|
|
48
|
+
yours sharing one of those names still stops the build, because `private` collides with TS2415
|
|
49
|
+
exactly as a public name does. `host` is the one most likely to clash.
|
|
50
|
+
Rename yours — `override` is not a way out for ten of the twelve, because a member whose base
|
|
51
|
+
declaration is `private` rejects it with the same TS2415 as a plain redeclaration, and that
|
|
52
|
+
includes `host`. Only the two `protected` ones, `onHover` and `onFocusWithin`, accept it. The
|
|
53
|
+
compiler enumerates every
|
|
54
|
+
collision, so building after the upgrade is the whole check.
|
|
55
|
+
|
|
56
|
+
Worth flagging for anyone who followed 0.11.2's note: `startCountdown` was announced there as a
|
|
57
|
+
member the region had just gained, so an `override startCountdown` added one release ago now
|
|
58
|
+
overrides nothing and silently never runs. There is no public replacement to call — the countdown
|
|
59
|
+
is the region's own business now. Delete the override.
|
|
60
|
+
|
|
61
|
+
- **`components.md` documented a component that does not exist and four events that never fired.**
|
|
62
|
+
It carried a `<ds-dropdown>` entry through nine releases; that component was absorbed into
|
|
63
|
+
`<ds-select>` and an import written from the document fails to compile. Four documented event
|
|
64
|
+
names were never identifiers here: `ds-banner` and `ds-toast` emit `(closed)`, not `(dismissed)`;
|
|
65
|
+
`ds-pagination` emits `(currentPageChange)`, not `(pageChange)`; `ds-table` emits `(rowClicked)`,
|
|
66
|
+
not `(rowClick)`. An unknown event binding registers a DOM listener and never fires, so those
|
|
67
|
+
four handlers were silently dead with nothing in the console. `<ds-alert>` was missing from the
|
|
68
|
+
document entirely and is now in it, `'neutral'` variant included.
|
|
69
|
+
|
|
70
|
+
### Fixed
|
|
71
|
+
|
|
72
|
+
- **`ds-color="error"`, `="success"` and `="warning"` lost their accent colour.** Those zones map
|
|
73
|
+
`--accent-strong` onto `--<family>-strong`, and the three status families never defined it — only
|
|
74
|
+
the brand families did. The declaration was invalid at computed-value time, so inside a status
|
|
75
|
+
zone every place that reads `--accent-strong` reset to `unset`: selected list and tree rows,
|
|
76
|
+
the active sidenav item and its rail, the active tab pill, avatar and avatar-group initials, the
|
|
77
|
+
active tag, dropzone text, the date-picker range label, the toast's action label, the selected
|
|
78
|
+
toggle button, the split-button hover fill, the `tonal`, `ghost`, `outline` and `text` variants
|
|
79
|
+
of `ds-button`, and the `tonal` variant of `ds-icon-button`. Text there fell through to the
|
|
80
|
+
inherited body colour; the fill
|
|
81
|
+
and the rail, which inherit nothing, disappeared.
|
|
82
|
+
|
|
83
|
+
No new token was needed: a status family already carries its readable on-tint colour as `-text`,
|
|
84
|
+
so `--accent-strong` now asks for `-strong` first and `-text` second, and the brand families keep
|
|
85
|
+
answering it as `-strong` because they have no `-text`. Each pointer also ends in a fallback — to
|
|
86
|
+
the family's base for `-hover`, `-pressed` and `-strong`, to its `-muted` for the tint pointers,
|
|
87
|
+
and to the theme-wide role for `-on` and the two focus pointers — so a role that goes missing in
|
|
88
|
+
future degrades instead of disappearing.
|
|
89
|
+
|
|
90
|
+
- **`ToastService.promise()` could destroy its own result.** It ran the settled toast's
|
|
91
|
+
auto-dismiss on a wall-clock timer started when the promise resolved, not when the toast became
|
|
92
|
+
visible — the one thing the rest of the timer work had already moved into the region. With a
|
|
93
|
+
`maxVisible` cap set, a promise that settled while its toast was still queued had the result spliced
|
|
94
|
+
out of the queue before anyone saw it: the user saved, it succeeded, and no toast appeared at all.
|
|
95
|
+
The settled duration is now handed to the region with the content, so it starts on promotion.
|
|
96
|
+
|
|
97
|
+
- **A toast carrying an `action` no longer auto-dismisses.** The overlay is the last child of `body`,
|
|
98
|
+
so the region is dead last in tab order; a keyboard user cannot cross a real page in the five
|
|
99
|
+
seconds the button was alive. An `action` toast now waits, and is always dismissible. Note that
|
|
100
|
+
a `durationMs` you pass alongside an `action` is discarded — the toast waits regardless — and
|
|
101
|
+
`dismissible: false` is discarded on any toast that cannot expire, not only on a `loading` one.
|
|
102
|
+
|
|
103
|
+
- **Hovering or focusing the region pauses every countdown**, resuming when the pointer or focus
|
|
104
|
+
leaves. A toast being read is not a toast that has been read. The pause is derived from both
|
|
105
|
+
sources rather than latched, so tabbing out of a region the pointer is still over does not
|
|
106
|
+
resume, moving focus between the action and the close button is not a leave, and a toast that
|
|
107
|
+
becomes visible under a stationary pointer — a burst past the cap, or a promise settling — is
|
|
108
|
+
banked rather than counted. A toast paused with almost nothing left resumes with at least 600ms, so
|
|
109
|
+
one hovered with
|
|
110
|
+
almost nothing left does not vanish as the pointer leaves.
|
|
111
|
+
|
|
112
|
+
- **A disabled accordion item's chevron did not look disabled.** It asked for a colour token this
|
|
113
|
+
library does not define, so the declaration was invalid at computed-value time and the chevron
|
|
114
|
+
inherited whatever colour surrounded it — while the label beside it greyed correctly. It reads the
|
|
115
|
+
disabled text colour now, like the label.
|
|
116
|
+
|
|
117
|
+
- **The `ds-banner` close button had no accessible name.** It announced as a bare "button", where
|
|
118
|
+
the same control on `ds-toast` and `ds-alert` already said "Dismiss". It says it now.
|
|
119
|
+
|
|
120
|
+
- **A long unbroken word in a toast overflowed the pill.** A URL or an id with no break
|
|
121
|
+
opportunity ran past the rounded edge instead of wrapping inside it.
|
|
122
|
+
|
|
123
|
+
- **Nothing that cannot expire can also be unclosable.** The rule is now that any toast with no
|
|
124
|
+
duration is dismissible, whatever you asked for — a `loading` variant, one carrying an `action`,
|
|
125
|
+
or an explicit `durationMs: 0`. A `loading` toast was created with `dismissible: false` and no
|
|
126
|
+
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
|
|
127
|
+
toasts that would have explained the hang.
|
|
128
|
+
|
|
129
|
+
## 0.11.2 — 2026-09-01
|
|
130
|
+
|
|
131
|
+
### Added
|
|
132
|
+
|
|
133
|
+
- **`PageUp` and `PageDown`.** Ten rows a press, which is the native `<select>` step and the APG
|
|
134
|
+
listbox example’s — a fixed number rather than a measured screenful, so the jump is the same
|
|
135
|
+
wherever the panel happens to be clipped. No picker had these.
|
|
136
|
+
|
|
137
|
+
- **`clear()` on `ds-select` and `ds-multi-select`.** `ds-autocomplete` has had it; the other two
|
|
138
|
+
offered only the in-trigger button, so an app with its own “reset filters” had to write the empty
|
|
139
|
+
value by hand and guess what empty means for that control. It does NOT move focus, deliberately:
|
|
140
|
+
the caller may be navigating away.
|
|
141
|
+
|
|
142
|
+
|
|
143
|
+
- **Panel header and footer slots.** The panel was a closed box between the filter row and the
|
|
144
|
+
options: "3 of 40 selected", a "clear all" button, a hint or a link under the list had nowhere to
|
|
145
|
+
go. `dsPanelHeaderTemplate` and `dsPanelFooterTemplate` fill a strip above and below, with
|
|
146
|
+
`count`, `total` and `query` in context. Both sit OUTSIDE the `listbox`, so nothing you put there
|
|
147
|
+
is counted as an option or breaks a reader's "N of M" position, and neither scrolls with the list —
|
|
148
|
+
the panel clips and the list is the scroller.
|
|
149
|
+
|
|
150
|
+
- **`dsGroupLabelTemplate`.** A group heading rendered its text and nothing else, so a count, a team
|
|
151
|
+
glyph or a second line was impossible. The heading ELEMENT stays the library's — it keeps the id the
|
|
152
|
+
group's `aria-labelledby` points at — and only its contents are yours.
|
|
153
|
+
|
|
154
|
+
- **The option row's geometry is tokens.** `--ds-option-gap`, `--ds-option-padding`,
|
|
155
|
+
`--ds-option-radius` and `--ds-option-row-gap`, plus `--ds-option-bg-color-active` for the
|
|
156
|
+
hover/keyboard fill. A denser panel meant re-declaring the row before, which is exactly how a second
|
|
157
|
+
copy of the panel ended up inside a component.
|
|
158
|
+
|
|
159
|
+
- **`searchPlaceholder` on `ds-autocomplete`.** Its `placeholder` was doing two jobs — the
|
|
160
|
+
empty-field caption and the hint for typing over a settled value. `ds-multi-select` already
|
|
161
|
+
separated them; now the name means one thing on both. Empty by default, so nothing moves.
|
|
162
|
+
|
|
163
|
+
- **The result count is announced.** A reader typed into the filter and heard nothing: no live region
|
|
164
|
+
existed in any picker. One is created per picker now, outside the listbox and empty at first — a
|
|
165
|
+
region created together with its text is the case screen readers reliably do not announce.
|
|
166
|
+
|
|
167
|
+
- **Type-ahead on `ds-select` and `ds-multi-select`.** Typing "ba" jumps to the first option starting
|
|
168
|
+
with "ba", the way a native `<select>` does, and repeating one letter cycles through the options
|
|
169
|
+
beginning with it. On a closed `ds-select` the jump commits, matching the native control.
|
|
170
|
+
`ds-autocomplete` is deliberately excluded: its trigger IS a text field, so typing there is the
|
|
171
|
+
filter and a jump would fight it.
|
|
172
|
+
|
|
173
|
+
- **`disabledReason` on an option, rendered by `ds-select`.** A disabled row said it could not be
|
|
174
|
+
picked and never why. On `ds-select` the reason reaches the row through `aria-describedby` and is
|
|
175
|
+
visually hidden — the row already looks disabled; the text is for whoever cannot see that. The
|
|
176
|
+
field is on the shared `DsOption`, so `SelectOption`, `MultiSelectOption` and `AutocompleteOption`
|
|
177
|
+
all accept it and it type-checks on all three pickers; `ds-multi-select` and `ds-autocomplete` do
|
|
178
|
+
not yet render it, so a reason set there is carried and not shown.
|
|
179
|
+
|
|
180
|
+
|
|
181
|
+
- **The keyboard cursor keeps its row in view.** On a list longer than the panel the arrows walked the
|
|
182
|
+
cursor out of sight — the reader pressed down and could not see where they were. All three pickers
|
|
183
|
+
scroll the active row into view now, on by default; `scrollActiveIntoView="false"` gives the scroll
|
|
184
|
+
position back to you. It uses `block: 'nearest'`, so a row that is already visible does not move and
|
|
185
|
+
the mouse is never fought.
|
|
186
|
+
|
|
187
|
+
- **`Home` and `End` on every picker.** They existed on `ds-select` alone, while ten other components
|
|
188
|
+
in the library already had them. The index arithmetic all three had written out separately — next,
|
|
189
|
+
previous, first, last, skipping disabled and wrapping — is one shared helper now, so the three
|
|
190
|
+
behave identically. It is internal: nothing new is exported.
|
|
191
|
+
|
|
192
|
+
- **`compareWith` on `ds-autocomplete`.** The component is generic over its value type but compared
|
|
193
|
+
with `===`, which is reference identity: a re-fetch that returned equal data as new objects silently
|
|
194
|
+
dropped the selection. Pass a comparator keyed on what identifies the value —
|
|
195
|
+
`[compareWith]="(a, b) => a?.id === b?.id"`. The default is unchanged, so string and number values
|
|
196
|
+
behave exactly as before. `ds-select` and `ds-multi-select` key on `string` and do not need it.
|
|
197
|
+
|
|
198
|
+
- **`loading`.** While options were being fetched the panel said "No matches", which is a lie the
|
|
199
|
+
consumer had no way to correct. It shows a spinner instead now, and the listbox reports
|
|
200
|
+
`aria-busy`. Spelled `booleanAttribute` to match `ds-button`, `ds-input` and `ds-loading-overlay`.
|
|
201
|
+
|
|
202
|
+
- **`opened` and `closed`.** There was no way to know a panel had opened, so a picker whose options
|
|
203
|
+
are fetched on demand had nowhere to start the request. `closed` is the name eight other components
|
|
204
|
+
already use; `opened` is its missing pair. They fire on the transition, not on every write, so
|
|
205
|
+
closing by Escape emits once rather than twice.
|
|
206
|
+
|
|
207
|
+
- **`filterWith` and `filterChange` — one input for both server-side search and a custom match.**
|
|
208
|
+
The query matcher was hardcoded to a case-insensitive substring of `label`: matching a second field,
|
|
209
|
+
ignoring diacritics or scoring fuzzily was impossible, and so was letting a server do the filtering.
|
|
210
|
+
`filterWith` takes a predicate for the first and the literal `'none'` for the second, where every
|
|
211
|
+
option handed in is rendered and `filterChange` reports what was typed. One input rather than two,
|
|
212
|
+
because they are one decision: who decides what the query matches.
|
|
213
|
+
|
|
214
|
+
- **`name`, `readOnly` and `clearable` on `ds-multi-select` and `ds-autocomplete`.** The last three
|
|
215
|
+
form-contract members that were `ds-select`'s alone. `name` reaches seven other controls in the
|
|
216
|
+
library, so the two pickers were the outliers; `readOnly` takes focus without opening, and carries
|
|
217
|
+
the same `readonly` binding alias `ds-select` has for signal forms; `clearable` uses the same button
|
|
218
|
+
and the same accessible name as `ds-select`'s.
|
|
219
|
+
|
|
220
|
+
|
|
221
|
+
- **`ds-table` row expansion: one-at-a-time, expand-all, and events.** The base feature shipped
|
|
222
|
+
already; these are the three edges it was missing. `expandMode="single"` collapses the open row
|
|
223
|
+
when another expander is clicked, so a detail panel cannot stack up down the page — enforced when
|
|
224
|
+
the user clicks, not on the binding, because `expandedIds` is the host's model to write and
|
|
225
|
+
rewriting it underneath would be the table arguing with its own consumer. `expandAllToggle` puts
|
|
226
|
+
a chevron in the expander column header, page-scoped when paginating exactly as select-all is.
|
|
227
|
+
`(rowExpanded)` and `(rowCollapsed)` name the row as it opens and closes, expand-all included,
|
|
228
|
+
which is where panel content gets lazy-loaded; a collapse the host writes into `expandedIds`
|
|
229
|
+
itself stays silent, and so does an id whose row is no longer in `data()` — an event carries a
|
|
230
|
+
row, and there is none to carry. Opening two rows or more now also reaches the table's live
|
|
231
|
+
region, which a full page of panels appearing from one keypress previously did not.
|
|
232
|
+
|
|
233
|
+
|
|
234
|
+
- **Column resizing works on a touch device, where the drag handle never could.** The handle
|
|
235
|
+
paints its line on `:hover` and `:focus-visible`; a coarse pointer produces neither, so it was
|
|
236
|
+
invisible — while `touch-action: none` still took the horizontal swipe that scrolls the table,
|
|
237
|
+
leaving a dead 8px strip at the right edge of every header. Under
|
|
238
|
+
`(hover: none) and (pointer: coarse)` the handle now stands down and width moves into the column
|
|
239
|
+
panel: each row carries −, + and Fit next to its visibility and order controls, and the panel
|
|
240
|
+
opens as a `ds-bottom-sheet` rather than a popover. The buttons render on desktop as well, where
|
|
241
|
+
the handle remains the primary route. All three routes share one step, so drag, arrow keys and
|
|
242
|
+
buttons move a column by the same amount, and all three clamp at the scroll viewport.
|
|
243
|
+
|
|
244
|
+
|
|
245
|
+
### Changed
|
|
246
|
+
|
|
247
|
+
- **Exported class member surface grew — only matters if you SUBCLASS a DS component.**
|
|
248
|
+
`SelectComponent`, `MultiSelectComponent`, `AutocompleteComponent`, `TableComponent`,
|
|
249
|
+
`LoadingOverlayComponent` and `ToastRegionComponent` all gained members for the inputs and outputs
|
|
250
|
+
above, and `DsPanelHeaderTemplateDirective`,
|
|
251
|
+
`DsPanelFooterTemplateDirective` and `DsGroupLabelTemplateDirective` are new classes.
|
|
252
|
+
Subclassing a DS component is unsupported but consumers do it, and a
|
|
253
|
+
member of yours that shares a name with one of ours stops the build. Rename yours, or add `override`
|
|
254
|
+
if you meant to replace ours — the compiler enumerates every collision, so building after the
|
|
255
|
+
upgrade is the whole check.
|
|
256
|
+
|
|
257
|
+
- **BREAKING for code that CONSTRUCTS a `ToastEntry`: `durationMs` is now a required
|
|
258
|
+
`readonly number`.** The field did not exist on the type before, so it arrives required rather
|
|
259
|
+
than widened: an object literal typed as `ToastEntry` — a test double, a hand-rolled region, a
|
|
260
|
+
store that holds toasts — stops compiling until it carries one. The entry has to know its own
|
|
261
|
+
duration now that the countdown belongs to the region rather than the service.
|
|
262
|
+
`ToastOptions.durationMs` is untouched — still optional, still `5000` by default, still `0` for a
|
|
263
|
+
loading toast — so a caller of `ToastService` writes nothing new.
|
|
264
|
+
|
|
265
|
+
- **BREAKING visually where a stack of toasts is part of the page: the newest toast enters at the
|
|
266
|
+
top of a top-anchored region.** Every toast was appended, so in a region resolving to a top
|
|
267
|
+
position — the default — the newest one landed at the BOTTOM of the stack, furthest from the
|
|
268
|
+
corner the stack grows out of, and the thing that had just happened was the last one you read. A
|
|
269
|
+
top position prepends now; a bottom position still appends. Either way the newest toast is the one
|
|
270
|
+
nearest the screen edge the region is anchored to.
|
|
271
|
+
|
|
272
|
+
- **`ds-select`'s option list caps 40px shorter.** The list's `max-height` was declared in
|
|
273
|
+
`ds-multi-select`'s own stylesheet; it sits in the shared panel partial now, so it reaches
|
|
274
|
+
`ds-select` and `ds-autocomplete` too. `ds-select`'s list was previously bounded only by the panel
|
|
275
|
+
cap `--ds-dropdown-panel-maxh` (320px) and now stops at `--picker-maxh` (280px) — roughly one
|
|
276
|
+
option row — which is the height the other two panels already used. `ds-autocomplete` had pinned
|
|
277
|
+
its panel to that value itself and does not move. Set `--picker-maxh` to take the height back, on
|
|
278
|
+
the panel where only that select should change or globally where all three should follow; the
|
|
279
|
+
panel cap is unchanged and is simply no longer what decides where a `ds-select` list stops.
|
|
280
|
+
|
|
281
|
+
- **`skeleton-mode` is gone from the inner `<table>` element of `ds-table` — only matters if you
|
|
282
|
+
reach in with `::ng-deep`.** The class was bound on that element, not the host, and nothing in the
|
|
283
|
+
library ever painted it, so a rule keyed on it was the only thing giving it meaning. If you have
|
|
284
|
+
one, key it off a class of your own on the host instead; if you do not, nothing about the rendered
|
|
285
|
+
table changes.
|
|
286
|
+
|
|
287
|
+
### Fixed
|
|
288
|
+
- **Dev-mode warnings no longer ship to production bundles.** They were guarded by
|
|
289
|
+
`isDevMode()`, which is a function CALL — a bundler cannot prove the branch dead, so all thirteen
|
|
290
|
+
warning sites and their message closures reached production builds. Each site is now guarded inline
|
|
291
|
+
with `typeof ngDevMode === 'undefined' || ngDevMode`, which `@angular/build` folds away whenever
|
|
292
|
+
script optimization is on, closures included. **Measured: 1 590 B gzip off an app using most of the
|
|
293
|
+
library, 827 B of it off a single `<ds-button>`.** Nothing changes for you — no API, no behaviour,
|
|
294
|
+
and the warnings still fire in development builds exactly as before.
|
|
295
|
+
|
|
296
|
+
- **A loading scrim stopped the pointer and let the keyboard walk straight under it.**
|
|
297
|
+
`ds-loading-overlay` paints an absolutely positioned scrim over its content, which intercepts
|
|
298
|
+
every pointer event — so a control behind it could not be clicked, and looked unavailable. Nothing
|
|
299
|
+
stopped focus: Tab reached the same control, Enter activated it, and `ds-table` with
|
|
300
|
+
`rowInteractive` would emit `(rowClicked)` for a row whose data the host was in the middle of
|
|
301
|
+
replacing. Neither `onRowClick` nor `onRowKey` consulted the loading state, and a row's
|
|
302
|
+
`tabindex` never did either. The overlay now marks the content it covers `inert` while loading,
|
|
303
|
+
which is the one mechanism that stops pointer and keyboard together and takes the covered controls
|
|
304
|
+
out of the accessibility tree; `aria-busy` stays on the host, so a reader is still told why.
|
|
305
|
+
`inertContent="false"` turns it off for a scrim that covers only PART of its content, and the
|
|
306
|
+
consumer then marks the covered subtree itself — `ds-table` does this, because its scrim starts
|
|
307
|
+
below the header and re-sorting during a refresh is exactly what puts the scrim up.
|
|
308
|
+
|
|
309
|
+
- **A toast queued behind `maxVisible` expired while it was still waiting.** The auto-dismiss
|
|
310
|
+
countdown started when `ToastService` was called, not when the toast reached the screen, so a
|
|
311
|
+
burst past the cap retired toasts that had never been visible — the more you fired at once, the
|
|
312
|
+
fewer were read, and the ones lost were the ones at the back. The countdown starts when the region
|
|
313
|
+
shows the toast now, promotion out of the queue included, so a queued toast gets its full duration
|
|
314
|
+
on screen. One gap remains: `ToastService.promise()` runs its own timers, so a promise toast held
|
|
315
|
+
behind the cap can still be removed before it is shown.
|
|
316
|
+
|
|
317
|
+
- **Dismissing a toast that was still queued promoted a different one instead of removing it.** The
|
|
318
|
+
id belonged to an entry that had not become visible yet, so the entry stayed in the queue and
|
|
319
|
+
another toast was pulled forward: the one you dismissed still appeared later, and one you had not
|
|
320
|
+
touched was hurried on screen ahead of its turn. A queued id is spliced out of the queue now and
|
|
321
|
+
nothing is promoted in its place.
|
|
322
|
+
|
|
323
|
+
- **A column resize handle announced no position and no limits.** The handle is a `role="separator"`,
|
|
324
|
+
which a screen reader presents as a slider, but an auto-sized column carried no `aria-valuenow` at
|
|
325
|
+
all — the user was handed a control with no current value and no way to hear how far it could go in
|
|
326
|
+
either direction. While the handle holds focus it now carries a measured `aria-valuenow` in px,
|
|
327
|
+
`aria-valuemin` of `48` and an `aria-valuemax` of the scroll viewport's width, which is the same
|
|
328
|
+
ceiling the drag, the arrow keys and the column-panel buttons clamp at. All three are present only
|
|
329
|
+
while the handle is focused.
|
|
330
|
+
|
|
331
|
+
- **A table's loading scrim slid off the table as it scrolled sideways.** `ds-loading-overlay` sat
|
|
332
|
+
inside the scroll container, and the scrim is `position: absolute; inset: 0` — so it was sized to a
|
|
333
|
+
single viewport of the table and then travelled with the content: at 400px of horizontal scroll it
|
|
334
|
+
sat 400px to the left of where it was needed, and every column the scroll had revealed was left
|
|
335
|
+
uncovered. The overlay wraps the scroll container now, so the scrim covers what is on screen at any
|
|
336
|
+
scroll offset.
|
|
337
|
+
|
|
338
|
+
- **A compact trigger showed one chip where several fitted.** `triggerDisplay="count"` and
|
|
339
|
+
`"labels"` make the trigger hug its content, so the width the chip fit measured was decided by the
|
|
340
|
+
chips it was about to cut — each pass shrank its own input and the split settled on one. The fit
|
|
341
|
+
reads the space AVAILABLE now, the trigger's parent, which no cut can move. `ds-autocomplete` gets
|
|
342
|
+
the same correction since both pickers measure through one helper, and a `width="fill"` trigger is
|
|
343
|
+
unaffected because there the two numbers are identical.
|
|
344
|
+
|
|
11
345
|
## 0.11.1 — 2026-08-31
|
|
12
346
|
|
|
13
347
|
### Added
|
|
@@ -198,6 +532,14 @@ While the package is on `0.x`, minor releases may contain breaking changes.
|
|
|
198
532
|
|
|
199
533
|
### Fixed
|
|
200
534
|
|
|
535
|
+
- **A compact trigger showed one chip where several fitted.** `triggerDisplay="count"` and
|
|
536
|
+
`"labels"` make the trigger hug its content, so the width the chip fit measured was decided by the
|
|
537
|
+
chips it was about to cut — each pass shrank its own input and the split settled on one. The fit
|
|
538
|
+
reads the space AVAILABLE now (the trigger's parent), which no cut can move. `ds-autocomplete` gets
|
|
539
|
+
the same correction, since both pickers measure through one helper, and a `width="fill"` trigger is
|
|
540
|
+
unaffected because there the two numbers are identical.
|
|
541
|
+
|
|
542
|
+
|
|
201
543
|
- **With the filter row hidden, there was no keyboard way to pick an option.** `Enter` and `Space`
|
|
202
544
|
were consumed by the trigger before the panel's own handler saw them, so the panel toggled shut
|
|
203
545
|
instead of selecting the active row: open, arrow down, Enter, nothing chosen. The trigger delegates
|
|
@@ -239,26 +581,6 @@ While the package is on `0.x`, minor releases may contain breaking changes.
|
|
|
239
581
|
its top-level items by index rather than by label, which is not unique.
|
|
240
582
|
|
|
241
583
|
|
|
242
|
-
- **Four published migration manifests were corrected, and a repo that upgraded before today may
|
|
243
|
-
be holding the result.** These files are executed: your upgrade tooling read them, acted and
|
|
244
|
-
reported done, so a defect in one is a defect in your codebase.
|
|
245
|
-
**`0.5.1#progress-variant-remap` certified the wrong component.** Its `verify` was the text
|
|
246
|
-
belonging to the badge item beside it, checking that chips render in their status colours — so
|
|
247
|
-
a `ds-progress` still binding `variant="warn"` or `variant="indeterminate"`, or TypeScript
|
|
248
|
-
still naming a removed `ProgressVariant` member, passed the check and shipped.
|
|
249
|
-
**Two items named too few locators to be found.**
|
|
250
|
-
`0.9.0#search-height-joins-field-scale` searched only `--ds-search-height`, so a short search
|
|
251
|
-
row pinned through `--hit-min` instead was never flagged; `0.10.1#fields-shared-base-class-members`
|
|
252
|
-
searched the bare base names, so a subclass written `extends` one of the internal field bases
|
|
253
|
-
went unfound and its `success` collision surfaced only at build.
|
|
254
|
-
**`0.10.1` also gained a delete row it never carried** — a modal body torn down on `(closed)`,
|
|
255
|
-
or held behind the open flag, purely so a re-opened `ds-date-picker` starts clean. The picker
|
|
256
|
-
clears itself now, and the teardown never fired reliably: re-opening inside the leave animation
|
|
257
|
-
cancels the close, so `closed` never comes.
|
|
258
|
-
`0.11.0#exported-class-members-grew` pointed its `detect` and `verify` at a base no consumer can
|
|
259
|
-
extend; corrected, with no consequence for anyone.
|
|
260
|
-
Re-run those items if your last upgrade crossed those versions.
|
|
261
|
-
|
|
262
584
|
### What you can now DELETE
|
|
263
585
|
|
|
264
586
|
None of this is required — skipping it leaves working code that is merely redundant. Each row is a
|
|
@@ -1227,17 +1549,6 @@ None of this is required — skipping it leaves working code that is merely redu
|
|
|
1227
1549
|
neither this token nor `--ds-radius-panel` — so only `--radius-md` itself moves it, and that moves
|
|
1228
1550
|
buttons, fields and tooltips with it.
|
|
1229
1551
|
|
|
1230
|
-
- **Two migration manifests were corrected and three more were written**, so re-read them if you
|
|
1231
|
-
subclass a DS component or upgrade across a version you skipped. `0.9.0`'s named no member collisions
|
|
1232
|
-
at all — the note that now fills the gap lists **fifteen** classes whose member surface had grown, plus
|
|
1233
|
-
four newly exported symbols that can shadow a local name — and `0.8.0`'s missed the private
|
|
1234
|
-
`saveLayout` that actually stopped a build (`restoreLayout` went in beside it). **`0.6.1`, `0.6.2` and
|
|
1235
|
-
`0.9.1` had no manifest at all**, and now every released version carries one: the auto-update planner
|
|
1236
|
-
prefers a manifest and otherwise re-derives the plan from changelog prose on every run, which is what
|
|
1237
|
-
an upgrade crossing those three used to do. `0.6.2`'s holds something actionable that no
|
|
1238
|
-
machine-readable file had ever stated — a `ds-bottom-sheet` with nothing focusable inside it stopped
|
|
1239
|
-
closing on Escape — which is exactly the kind a "just fixes" patch is assumed not to have.
|
|
1240
|
-
|
|
1241
1552
|
- **`ds-avatar` takes a `name`, and the rule that reads it is replaceable.** One binding now does both
|
|
1242
1553
|
jobs a caller used to wire by hand: it derives the initials and seeds the tint. **The tint hashes the
|
|
1243
1554
|
NAME, not the initials** — two letters collide wholesale, so Alice Brown and Adam Bell used to share a
|
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,17 @@ 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 are set with two injection tokens, NOT through `provideDsConfig`:
|
|
591
|
+
- `DS_TOAST_CONFIG` — `{ maxVisible?: number }`. Unset or `0` means unlimited; extras queue and appear as earlier ones dismiss.
|
|
592
|
+
- `DS_TOAST_POSITION` — `{ horizontalPosition?: 'left' | 'center' | 'right', verticalPosition?: 'top' | 'bottom', offset?: string }`. Defaults to `right` / `top` / `var(--space-6)`.
|
|
593
|
+
|
|
594
|
+
Both resolve **once, at the root injector**, when the service is first used. Providing either on a `Route` or a component has no effect, 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.
|
|
582
597
|
|
|
583
598
|
---
|
|
584
599
|
|
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
|