@ids-group-ltd/ids-design-system 0.10.2 → 0.11.0
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 +415 -37
- package/components.md +19 -6
- package/fesm2022/ids-group-ltd-ids-design-system.mjs +572 -477
- package/fesm2022/ids-group-ltd-ids-design-system.mjs.map +1 -1
- package/migrations/0.1.0.json +2 -1
- package/migrations/0.10.0.json +209 -32
- package/migrations/0.10.1.json +33 -9
- package/migrations/0.10.2.json +88 -22
- package/migrations/0.10.3.json +90 -0
- package/migrations/0.11.0.json +216 -0
- package/migrations/0.2.0.json +22 -9
- package/migrations/0.2.1.json +2 -1
- package/migrations/0.2.2.json +2 -1
- package/migrations/0.3.0.json +16 -10
- package/migrations/0.4.0.json +38 -14
- package/migrations/0.5.0.json +49 -25
- package/migrations/0.5.1.json +75 -33
- package/migrations/0.6.0.json +6 -2
- package/migrations/0.6.1.json +19 -1
- package/migrations/0.6.2.json +3 -1
- package/migrations/0.6.3.json +13 -4
- package/migrations/0.7.0.json +45 -26
- package/migrations/0.7.1.json +57 -19
- package/migrations/0.8.0.json +50 -12
- package/migrations/0.9.0.json +142 -23
- package/migrations/0.9.1.json +2 -1
- package/package.json +2 -1
- package/styles/_field-group-segment.scss +3 -8
- package/styles/_focus.scss +28 -30
- package/styles/_link.scss +1 -2
- package/styles/_overlay-motion.scss +0 -1
- package/styles/_text-clip.scss +5 -10
- package/types/ids-group-ltd-ids-design-system.d.ts +129 -59
- package/migrations/AUTHORING.md +0 -273
package/components.md
CHANGED
|
@@ -112,6 +112,11 @@ The DS aggregate (`@use 'styles/ds'`) forwards the full stack: theme primitives
|
|
|
112
112
|
- Skeleton shimmer (`_skeleton-shimmer.scss`): drives the global `--skeleton-shimmer-x` keyframe used by `<ds-skeleton>` and table skeleton rows.
|
|
113
113
|
- Dropdown overlay (`_dropdown-overlay.scss`): styles the `.ds-dropdown-panel` class used by select/dropdown/combobox/date-picker CDK portals — these panels live outside the host's encapsulated tree, so the styles must be global.
|
|
114
114
|
|
|
115
|
+
**Two mixins for building your own composite controls.** `@use` the partial directly to reach the mixin; a mixin emits nothing until it is included.
|
|
116
|
+
|
|
117
|
+
- `@use 'styles/focus' as focus;` → `focus.owns-the-focus-ring($control)`. This partial IS part of the `styles/ds` aggregate — it also carries the base indicator and the `data-focus` switch — so reaching for the mixin adds no CSS. Include it in a shell that paints its own ring on `:focus-within`, naming the ONE control inside that must not paint the base indicator too. `outline: 0` cannot do this — the base indicator is a box-shadow — and a box-wide reset instead of a named control silences the tab stops inside the box (a clear button, a stepper arrow), which leaves a keyboard user unable to tell what has focus. See Foundations → Colour → Focus for the worked example.
|
|
118
|
+
- `@use 'styles/text-clip' as text-clip;` → `text-clip.single-line-ellipsis`. Mixin-only, so this partial is NOT part of the `styles/ds` aggregate and emits nothing on its own. A one-line label that truncates with an ellipsis. Use it instead of hand-writing `overflow: hidden; text-overflow: ellipsis`: with a line-height under the font's glyph box (Mulish measures 1.257em, so `--line-height-flat` and `--line-height-tight` both qualify) that `hidden` shaves the top and bottom off every glyph.
|
|
119
|
+
|
|
115
120
|
---
|
|
116
121
|
|
|
117
122
|
## Components
|
|
@@ -141,15 +146,19 @@ text rather than a state. Retune app-wide with `DS_CONFIG.field.stateIcons` (per
|
|
|
141
146
|
is not a validated field; where a search needs a label or an error line, use `ds-input`.
|
|
142
147
|
|
|
143
148
|
#### `<ds-button>` — `ButtonComponent`
|
|
144
|
-
Inputs: **two orthogonal axes** — `color: ButtonColor = 'primary'` (`'primary' | 'secondary' | 'tertiary' | 'neutral' | 'error' | 'success' | 'warning'`) and `variant: ButtonVariant = 'solid'` (`'solid' | 'tonal' | 'outline' | 'ghost' | 'text'`). Plus `size: DsSize | null = null` (unset resolves `DS_CONFIG.control.size`, then `md`), `type: 'button' | 'submit' | 'reset' = 'button'`, `disabled`, `loading`, `fullWidth`, `icon: IconName | null`.
|
|
149
|
+
Inputs: **two orthogonal axes** — `color: ButtonColor = 'primary'` (`'primary' | 'secondary' | 'tertiary' | 'neutral' | 'error' | 'success' | 'warning'`) and `variant: ButtonVariant = 'solid'` (`'solid' | 'tonal' | 'outline' | 'ghost' | 'text'`). Plus `size: DsSize | null = null` (unset resolves `DS_CONFIG.control.size`, then `md`), `type: 'button' | 'submit' | 'reset' = 'button'`, `disabled`, `loading`, `fullWidth`, `icon: IconName | null`. Plus the refusal pair below: `disabledReason`, and the field message inputs `hint` / `warning` / `error` / `messageIcon` / `reserveMessage` / `ariaDescribedBy`.
|
|
145
150
|
Axis meaning: **variant is loudness** (solid > tonal > outline/ghost/text), **color is hue** — every pair renders, and the UX-discouraged ones dev-warn (see `DISCOURAGED_COMBOS`). Only solid and tonal paint a fill: outline, ghost and text are TRANSPARENT, so they adopt the surface they sit on. Disabled splits by whether the fill can carry the state: `solid` and `tonal` keep `oklch(from accent 70% 0.035 h)`, while `outline`, `ghost` and `text` — the three with no fill of their own — mix the label toward the surface, `color-mix(in srgb, <label> 40%, var(--surface-default))`, because a fixed lightness cannot serve both themes. (History: the single `variant` axis was split into color × variant in 2026-06; `danger`→`error`, `link`→`text`, the old `ghost`→`outline`.)
|
|
146
151
|
Output: `(pressed): MouseEvent` — only fires when not disabled and not loading
|
|
147
|
-
Content slots: default (label / leading or trailing icon). For icon-only actions use `<ds-icon-button>`.
|
|
148
|
-
|
|
152
|
+
Content slots: default (label / leading or trailing icon), plus `[dsButtonSubtext]` for a projected second line. For icon-only actions use `<ds-icon-button>`.
|
|
153
|
+
**Saying WHY a button is refused, and the two kinds of refusal.** A greyed control that does not say why is a dead end, and until 0.10.4 the only way to explain one was a tooltip — mouse-only. Which input to reach for is decided by whether the user can lift the refusal on this screen:
|
|
154
|
+
- **Standing** (no permission, no integration — nothing here will change it): `disabledReason` beside `disabled`. The reason renders as a second line INSIDE the button, and setting it flips how the button is disabled — `aria-disabled="true"` instead of the native attribute, because a natively disabled button never takes focus and its description would never be announced (measured; Chrome's a11y tree reports name `"Approve invoice"`, description `"Needs the Finance role"`, state disabled). The click is swallowed in the handler instead, so `(pressed)` still never fires. Leave `disabledReason` unset and NOTHING changes: the native attribute stays, and so does every existing layout. Length is deliberately uncapped — the text wraps and the button grows.
|
|
155
|
+
- **Temporary** (the form is not filled in yet): do NOT disable the button at all. Leave it live, judge validity in the submit handler (the house rule for forms), and carry the text UNDER the button with `hint` / `warning` / `error` — the same three inputs the fields take, resolved by the same `resolveFieldMessage`, rendered by the same `ds-field-message`, with the same `messageIcon` and `reserveMessage` knobs and the same `DS_CONFIG.field.*` fallbacks. This is inheritance, not a copy: `hint`/`warning`/`error`/`messageIcon`/`reserveMessage` moved out of `DsFieldBase` into a new `DsMessageBase`, which `DsFieldBase` and `ButtonComponent` both extend — `errors`/`invalid`/`touched` stay on `DsFieldBase`, since a button has no validation state of its own.
|
|
156
|
+
Layout: a message-bearing button becomes a column (host class `with-message`), and because the host shrinks to fit, a message longer than the label widens the pair — button included, exactly as a field's control spans its own message. Without a message the host keeps the `inline-flex` box every existing layout was built against.
|
|
157
|
+
Tokens: `--ds-button-bg-color`, `--ds-button-bg-color-hover`, `--ds-button-bg-color-active`, `--ds-button-bg-color-disabled`, `--ds-button-label-color`, `--ds-button-label-color-disabled`, `--ds-button-border`, `--ds-button-radius`, `--ds-button-focus-shadow`, `--ds-button-pressed-shadow`, `--ds-button-shadow`, `--ds-button-shadow-hover`. The last two are the REST and hover shadow, both `none` by default — before them the only way to give a button a resting shadow was a deep selector into its inner `<button>`. `-shadow-hover` falls back to `-shadow`, so setting the resting one alone keeps the button steady under the pointer; focus and pressed keep their own hooks and still win while those states are on. For `variant="solid"`, `-bg-color-hover` / `-bg-color-active` / `-pressed-shadow` default to a `color-mix()` derivation of the resolved fill (88 % / 76 % + black — the theme's hover/pressed recipe), so overriding the fill alone retints the whole state set; tonal, outline, ghost and text keep explicit ramp defaults, so a full retint there means setting the state tokens too.
|
|
149
158
|
|
|
150
159
|
#### `<ds-icon-button>` — `IconButtonComponent`
|
|
151
160
|
Icon-only action with its own taxonomy, distinct from `ds-button`. `ariaLabel` is required (icon-only must be labelled for a11y).
|
|
152
|
-
Inputs: `icon: required IconName`, `ariaLabel: required string`, `variant: IconButtonVariant = 'standard'` (`'standard' | 'filled' | 'tonal' | 'outlined'`), `size: IconButtonSize = 'md'` (`'sm' | 'md' | 'lg'` = 32/40/48), `type: 'button' | 'submit' | 'reset' = 'button'`, `disabled: boolean = false`, `selected: boolean = false` (toggle — sets `aria-pressed`)
|
|
161
|
+
Inputs: `icon: required IconName`, `ariaLabel: required string`, `ariaDescribedBy: string | null = null` (point at text the page already shows — e.g. why the action is refused; icon-only leaves no room for a second line, which is why there is deliberately no `disabledReason` here), `variant: IconButtonVariant = 'standard'` (`'standard' | 'filled' | 'tonal' | 'outlined'`), `size: IconButtonSize = 'md'` (`'sm' | 'md' | 'lg'` = 32/40/48), `type: 'button' | 'submit' | 'reset' = 'button'`, `disabled: boolean = false`, `selected: boolean = false` (toggle — sets `aria-pressed`)
|
|
153
162
|
Output: `(pressed): MouseEvent` — fires when not disabled
|
|
154
163
|
Variant emphasis: `standard` chromeless (hover-reveal) · `filled` `--primary` · `tonal` `--primary-muted` · `outlined` bordered. `selected` renders the pressed/active fill.
|
|
155
164
|
Tokens: `--ds-icon-button-bg-color`, `--ds-icon-button-icon-color`, `--ds-icon-button-border`, `--ds-icon-button-bg-color-hover`, `--ds-icon-button-bg-color-active`, `--ds-icon-button-icon-color-hover`, `--ds-icon-button-radius`, `--ds-icon-button-focus-shadow`. `filled`/`selected` derive hover/active from the resolved bg, `standard`/`tonal`/`outlined` keep explicit ramp defaults.
|
|
@@ -277,8 +286,9 @@ The companion `<ds-toast-region>` lives inside the `ToastService` (see Services)
|
|
|
277
286
|
### Layout & navigation
|
|
278
287
|
|
|
279
288
|
#### `<ds-sidenav>` — `SidenavComponent`
|
|
280
|
-
Inputs: `collapsed: boolean = false`, `brand: string | null = null` (renders a letter mark + name; omit to project custom content, or set `DS_CONFIG.brand.name`), `logoLetter: string | null = null` (the mark's glyph; derived from `brand` when unset), `rail: boolean = true` (whether an active item draws its edge marker — turn it off here rather than painting `--ds-sidenav-item-rail` transparent)
|
|
289
|
+
Inputs: `collapsed: boolean = false`, `brand: string | null = null` (renders a letter mark + name; omit to project custom content, or set `DS_CONFIG.brand.name`), `logoLetter: string | null = null` (the mark's glyph; derived from `brand` when unset), `rail: boolean = true` (whether an active item draws its edge marker — turn it off here rather than painting `--ds-sidenav-item-rail` transparent), `brandRoute: string | readonly unknown[] | null = null`, `brandLinkLabel: string | null = null`
|
|
281
290
|
Content: default slot for groups/items + custom brand/footer rows
|
|
291
|
+
**The brand row leads home only if you say so.** `brandRoute` turns the mark + wordmark into one link; unset, the row stays a plain block. A logo that goes nowhere should not be a link, and whether a mark is a way home is an app's decision, not the DS's — so this is opt-in, like every other new capability here. The link announces itself as `"<brand>, home"` because a wordmark alone does not say where it goes; `brandLinkLabel` overrides that. Router targets only, and `RouterLink` is instantiated only inside the `@if`, so an app with no router provided still renders the sidenav. A collapse toggle projected into the row stays OUTSIDE the link — one control never nests inside another.
|
|
282
292
|
Tokens: `--ds-sidenav-bg-color`, `--ds-sidenav-border`, `--ds-sidenav-width`, `--ds-sidenav-width-collapsed`, `--ds-sidenav-mark-bg-color`, `--ds-sidenav-mark-label-color`
|
|
283
293
|
|
|
284
294
|
#### `<ds-sidenav-group>` — `SidenavGroupComponent`
|
|
@@ -289,6 +299,7 @@ When `expandable=true` renders header button with toggle + caret; collapses body
|
|
|
289
299
|
#### `<ds-sidenav-item>` — `SidenavItemComponent`
|
|
290
300
|
Inputs: `icon: IconName | null = null` (optional — falls back to `[icon]` slot), `label: required string`, `href: string = ''`, `routerLink: string | readonly unknown[] | null = null`, `active: boolean = false`, `badge: number | null = null`, `hasAlert: boolean = false`, `rail: boolean | null = null` (draws the active item's edge marker; unset follows the parent `ds-sidenav`)
|
|
291
301
|
Content slots: `[icon]` (custom icon when not using a DS IconName), `[trailing]` (right-aligned chrome — badges, indicators, kbd shortcuts)
|
|
302
|
+
**Three elements, decided by destination.** `routerLink` → an `<a [routerLink]>` with `routerLinkActive`; `href` → a plain `<a href>`; **neither → a `<button type="button">`**. Until 0.11.0 the last case fell back to `href="#"`, which navigates: it rewrites the URL and discards the scroll position on every click, which is how a sidenav SPECIMEN in these docs used to move the page under itself. An item that only emits `activate` is a button. Styling is identical across all three — the rules are class-based (`.item`) and the button's UA chrome is reset — so target the class, never the tag.
|
|
292
303
|
Tokens (on `:host`): `--ds-sidenav-item-label-color`, `--ds-sidenav-item-label-color-hover`, `--ds-sidenav-item-bg-color-hover`, `--ds-sidenav-item-bg-color-active` (default: `--accent-subtitle` — a wash, not a solid pill), `--ds-sidenav-item-label-color-active` (default: `--accent-strong`), `--ds-sidenav-item-bg-color-active-hover` (default: `--accent-muted`, deepening toward the accent), `--ds-sidenav-item-rail` (left rail, default: `--accent-strong`), `--ds-sidenav-item-radius`, `--ds-sidenav-alert-color`
|
|
293
304
|
|
|
294
305
|
#### `<ds-topbar>` — `TopBarComponent`
|
|
@@ -346,7 +357,8 @@ Content: label text (when `variant="label"`).
|
|
|
346
357
|
#### `<ds-card>` — `CardComponent`
|
|
347
358
|
Inputs: `elevation: 'flat' | 'raised' | 'hover' | 'interactive' = 'flat'`, `padding: 'none' | 'sm' | 'md' | 'lg' | null = null` (when `null`, no `padding-*` class is applied and the consumer controls padding via own CSS or `--ds-card-pad`)
|
|
348
359
|
Output: `(pressed): MouseEvent` — fires only when `elevation="interactive"`
|
|
349
|
-
Tokens: `--ds-card-bg-color`, `--ds-card-border`, `--ds-card-radius`, `--ds-card-pad`, `--ds-card-shadow`, `--ds-card-shadow-hover`, `--ds-card-focus-shadow`, `--ds-card-hover-lift`
|
|
360
|
+
Tokens: `--ds-card-bg-color`, `--ds-card-border`, `--ds-card-radius`, `--ds-card-pad`, `--ds-card-shadow`, `--ds-card-shadow-hover`, `--ds-card-focus-shadow`, `--ds-card-hover-lift`, `--ds-card-overflow`
|
|
361
|
+
Full-bleed child: a child whose background reaches the card edge paints square corners over the radius, and the host cannot fix it — the rounded box is the card's inner element. Set `--ds-card-overflow: clip` (`clip`, not `hidden`, so the card stays out of the scroll-container business). It is opt-in because a clipped card also cuts the focus ring off a child at its edge; where the clipped card holds focusable content, pair it with `data-focus="inset"`.
|
|
350
362
|
Convention tokens (consumer-side `.title` projected into the card slot — declared at `:root`, not on the host): `--card-title-fs` (default `var(--font-size-h4)` = 22px; MM brand steps down to `var(--font-size-h5)` = 18px). Consumer markup: `<h3 class="title">…</h3>`; local `.title` class reads the token via `font:` shorthand together with `--font-weight-bold` / `--line-height-snug` / `--font-heading`.
|
|
351
363
|
|
|
352
364
|
#### `<ds-accordion>` + `<ds-accordion-item>` — `AccordionComponent`, `AccordionItemComponent`
|
|
@@ -400,6 +412,7 @@ Selection is communicated via the `value` model. Keyboard: ArrowUp/Down, Enter/S
|
|
|
400
412
|
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`
|
|
401
413
|
Outputs: `(rowClick): T`, `(sortChange): SortChangeEvent` (`{ key, dir }`)
|
|
402
414
|
Column shape: `{ key: string, label: string, sortable?: boolean, align?: 'left' | 'right' | 'center', cell?: (row: T) => string }`
|
|
415
|
+
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.
|
|
403
416
|
Cell templates: `<ng-template dsCellTemplate="<colKey>" let-row>…</ng-template>` — `row` is typed `unknown`, narrow via a helper method on the host.
|
|
404
417
|
Content slots: `[empty]` (rendered when `data.length === 0`), `[bulk-actions]` (rendered in the bulk action bar when `selectable && some selected`)
|
|
405
418
|
Loading modes: `'skeleton'` replaces rows with shimmer placeholders driven by the global `--skeleton-shimmer-x` keyframe; `'overlay'` keeps existing rows visible behind a translucent layer with a centred spinner.
|