@ids-group-ltd/ids-design-system 0.10.1 → 0.10.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 +433 -14
- package/components.md +73 -13
- package/fesm2022/ids-group-ltd-ids-design-system.mjs +348 -143
- package/fesm2022/ids-group-ltd-ids-design-system.mjs.map +1 -1
- package/migrations/0.10.0.json +420 -44
- package/migrations/0.10.1.json +80 -16
- package/migrations/0.10.2.json +482 -0
- package/migrations/0.10.3.json +73 -0
- package/migrations/0.2.0.json +32 -8
- package/migrations/0.3.0.json +19 -3
- package/migrations/0.4.0.json +50 -11
- package/migrations/0.5.0.json +93 -24
- package/migrations/0.5.1.json +106 -29
- package/migrations/0.6.0.json +2 -1
- package/migrations/0.6.2.json +33 -3
- package/migrations/0.6.3.json +19 -3
- package/migrations/0.7.0.json +77 -25
- package/migrations/0.7.1.json +84 -8
- package/migrations/0.8.0.json +46 -10
- package/migrations/0.9.0.json +284 -35
- package/migrations/AUTHORING.md +125 -12
- package/migrations/README.md +62 -5
- package/package.json +1 -1
- package/styles/_dropdown-overlay.scss +4 -3
- package/styles/_field-group-segment.scss +4 -0
- package/styles/_focus.scss +36 -22
- package/styles/_text-clip.scss +12 -0
- package/themes/_semantic.scss +20 -3
- package/types/ids-group-ltd-ids-design-system.d.ts +187 -68
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
|
|
@@ -120,13 +125,29 @@ Every entry below names its exported class (`ButtonComponent`, `TableComponent<T
|
|
|
120
125
|
|
|
121
126
|
**The `--ds-*` token contract, once for every component below.** Every public `--ds-<component>-*` token is READ WITH A FALLBACK and never declared by the component, so a consumer's value always wins and always inherits: set it on the host (`ds-button { --ds-button-bg-color: teal }`), on any ancestor, at `:root`, or inline. Unset tokens fall through to the component's own default, so there is nothing to opt into and nothing to reset. Two consequences worth stating: a token set at `:root` reaches EVERY instance — scope per instance or per section and keep theme-wide re-skins at role level (`--primary`, `--ds-radius-control`) — and where a component derives one value from another (a hover fill mixed from the resolved background), overriding the source retunes the derived states with it. Individual entries below therefore note only what DEVIATES from this: a derived state, a variant-specific default, a token that beats a size class.
|
|
122
127
|
|
|
123
|
-
> **Token and API lists below are hand-maintained
|
|
128
|
+
> **Token and API lists below are hand-maintained, so treat this file as prose about intent.** The authoritative surfaces are the **Component API tables** and the **token reference** in `ds-docs`, both extracted from source on every build, so they cannot go stale — trust those first, and read this file for the reasoning a generated table cannot carry. Where the two disagree, the generated one is right. Reconciled 2026-08-21 (the `ds-button` section named here as drifted had already been rewritten; that note was itself out of date).
|
|
124
129
|
|
|
125
130
|
### Form & input
|
|
126
131
|
|
|
132
|
+
**Shared by every field** (input, textarea, select, multi-select, autocomplete, date/time/colour picker,
|
|
133
|
+
checkbox, radio, radio-group, switch, slider, segmented, OTP): `label`, `hint`, `error`, `warning`,
|
|
134
|
+
`errors`, `invalid`, `touched`, `reserveMessage` — and one message line under the control that renders
|
|
135
|
+
whichever of them wins. The ladder is error → errors → warning → advisory errors → success → hint.
|
|
136
|
+
|
|
137
|
+
`error`, `warning` and `success` lead that line with a glyph; `hint` does not, because it is the resting
|
|
138
|
+
text rather than a state. Retune app-wide with `DS_CONFIG.field.stateIcons` (per state, independent —
|
|
139
|
+
`false` removes one, an `IconName` replaces it, `stateIcons: false` removes all four), or per field with
|
|
140
|
+
`messageIcon: IconName | false | null`, which wins over the config. Spacing hooks:
|
|
141
|
+
`--ds-field-message-icon-gap`, `--ds-field-message-icon-offset`.
|
|
142
|
+
|
|
143
|
+
**`ds-search` is deliberately NOT on that list.** It binds to a form like the others — `[formControl]`,
|
|
144
|
+
`formControlName`, `[(ngModel)]`, signal forms, plus its own `[(value)]` — and it takes `disabled` and
|
|
145
|
+
`hidden`, but it renders no message row and therefore takes none of the message inputs. A toolbar filter
|
|
146
|
+
is not a validated field; where a search needs a label or an error line, use `ds-input`.
|
|
147
|
+
|
|
127
148
|
#### `<ds-button>` — `ButtonComponent`
|
|
128
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`.
|
|
129
|
-
Axis meaning: **variant is loudness** (solid > tonal > outline/ghost/text), **color is hue** — every pair renders, and the UX-discouraged ones dev-warn (see `DISCOURAGED_COMBOS`). Only solid and tonal paint a fill: outline, ghost and text are TRANSPARENT, so they adopt the surface they sit on. Disabled
|
|
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`.)
|
|
130
151
|
Output: `(pressed): MouseEvent` — only fires when not disabled and not loading
|
|
131
152
|
Content slots: default (label / leading or trailing icon). For icon-only actions use `<ds-icon-button>`.
|
|
132
153
|
Tokens: `--ds-button-bg-color`, `--ds-button-bg-color-hover`, `--ds-button-bg-color-active`, `--ds-button-bg-color-disabled`, `--ds-button-label-color`, `--ds-button-label-color-disabled`, `--ds-button-border`, `--ds-button-radius`, `--ds-button-focus-shadow`, `--ds-button-pressed-shadow`. For `variant="solid"`, `-bg-color-hover` / `-bg-color-active` / `-pressed-shadow` default to a `color-mix()` derivation of the resolved fill (88 % / 76 % + black — the theme's hover/pressed recipe), so overriding the fill alone retints the whole state set; tonal, outline, ghost and text keep explicit ramp defaults, so a full retint there means setting the state tokens too.
|
|
@@ -187,9 +208,11 @@ Inputs: `options: readonly ComboboxOption<T>[]` (`{ value: T, label: string }`),
|
|
|
187
208
|
In multi mode, selected values render as `<ds-tag closable>` chips above the trigger.
|
|
188
209
|
|
|
189
210
|
#### `<ds-search>` — `SearchComponent`
|
|
190
|
-
Pre-styled search input with built-in icon.
|
|
191
|
-
Inputs: `value: model<string>`, `placeholder: string = 'Search'`, `shortcut: string = ''` (rendered as a hint pill, e.g. `⌘K`), `showIcon: boolean = true`
|
|
211
|
+
Pre-styled search input with built-in icon. A form control, but not a field: no label, no message row.
|
|
212
|
+
Inputs: `value: model<string>`, `placeholder: string = 'Search'`, `shortcut: string = ''` (rendered as a hint pill, e.g. `⌘K`), `showIcon: boolean = true`, `clearable: boolean = false`, `ariaLabel: string = ''`, `disabled: boolean = false`, `hidden: boolean = false`, `size: DsSize | null = null`, `debounce: number = 0` (ms held before `value` updates; clearing, Enter and `clear()` all skip the timer)
|
|
192
213
|
Output: `(submitted): string` — emits the current value on Enter / form submit
|
|
214
|
+
Methods: `clear()` — empties the field, drops an armed keystroke and publishes `''` at once, which writing `''` into `value` does not; `focus()`.
|
|
215
|
+
Binds through `NG_VALUE_ACCESSOR`, taking the CVA plumbing without `DsFieldBase` — so `hint` / `error` / `warning` / `errors` / `invalid` / `touched` / `reserveMessage` / `messageIcon` are NOT inputs here.
|
|
193
216
|
|
|
194
217
|
#### `<ds-date-picker>` — `DatePickerComponent`
|
|
195
218
|
Inputs: `mode: 'single' | 'range' = 'single'`, `size: 'sm' | 'md' | 'lg' = 'md'`, `value: model<Date | RangeValue | null>` (`RangeValue = [Date | null, Date | null]`), `placeholder: string = 'Select date'`, `label: string = ''`, `hint: string = ''`, `required: boolean = false`, `optional: boolean = false`
|
|
@@ -259,7 +282,7 @@ The companion `<ds-toast-region>` lives inside the `ToastService` (see Services)
|
|
|
259
282
|
### Layout & navigation
|
|
260
283
|
|
|
261
284
|
#### `<ds-sidenav>` — `SidenavComponent`
|
|
262
|
-
Inputs: `collapsed: boolean = false`, `brand: string =
|
|
285
|
+
Inputs: `collapsed: boolean = false`, `brand: string | null = null` (renders a letter mark + name; omit to project custom content, or set `DS_CONFIG.brand.name`), `logoLetter: string | null = null` (the mark's glyph; derived from `brand` when unset), `rail: boolean = true` (whether an active item draws its edge marker — turn it off here rather than painting `--ds-sidenav-item-rail` transparent)
|
|
263
286
|
Content: default slot for groups/items + custom brand/footer rows
|
|
264
287
|
Tokens: `--ds-sidenav-bg-color`, `--ds-sidenav-border`, `--ds-sidenav-width`, `--ds-sidenav-width-collapsed`, `--ds-sidenav-mark-bg-color`, `--ds-sidenav-mark-label-color`
|
|
265
288
|
|
|
@@ -269,15 +292,28 @@ Content slots: default (items); `[ds-group-icon]` (custom group icon when not us
|
|
|
269
292
|
When `expandable=true` renders header button with toggle + caret; collapses body when not expanded.
|
|
270
293
|
|
|
271
294
|
#### `<ds-sidenav-item>` — `SidenavItemComponent`
|
|
272
|
-
Inputs: `icon: IconName | null = null` (optional — falls back to `[icon]` slot), `label: required string`, `href: string = ''`, `routerLink: string | readonly unknown[] | null = null`, `active: boolean = false`, `badge: number | null = null`, `hasAlert: boolean = false`
|
|
295
|
+
Inputs: `icon: IconName | null = null` (optional — falls back to `[icon]` slot), `label: required string`, `href: string = ''`, `routerLink: string | readonly unknown[] | null = null`, `active: boolean = false`, `badge: number | null = null`, `hasAlert: boolean = false`, `rail: boolean | null = null` (draws the active item's edge marker; unset follows the parent `ds-sidenav`)
|
|
273
296
|
Content slots: `[icon]` (custom icon when not using a DS IconName), `[trailing]` (right-aligned chrome — badges, indicators, kbd shortcuts)
|
|
274
|
-
Tokens (on `:host`): `--ds-sidenav-item-label-color`, `--ds-sidenav-item-label-color-hover`, `--ds-sidenav-item-bg-color-hover`, `--ds-sidenav-item-bg-color-active` (default: `--
|
|
297
|
+
Tokens (on `:host`): `--ds-sidenav-item-label-color`, `--ds-sidenav-item-label-color-hover`, `--ds-sidenav-item-bg-color-hover`, `--ds-sidenav-item-bg-color-active` (default: `--accent-subtitle` — a wash, not a solid pill), `--ds-sidenav-item-label-color-active` (default: `--accent-strong`), `--ds-sidenav-item-bg-color-active-hover` (default: `--accent-muted`, deepening toward the accent), `--ds-sidenav-item-rail` (left rail, default: `--accent-strong`), `--ds-sidenav-item-radius`, `--ds-sidenav-alert-color`
|
|
275
298
|
|
|
276
299
|
#### `<ds-topbar>` — `TopBarComponent`
|
|
277
300
|
No inputs.
|
|
278
301
|
Content slots: `[title]`, `[breadcrumbs]`, `[search]`, `[actions]`. Sits at `--topbar-h` height.
|
|
279
302
|
Tokens (on `:host`): `--ds-topbar-height`, `--ds-topbar-bg-color`, `--ds-topbar-border`, `--ds-topbar-title-text-color`, plus the `--ds-topbar-crumb-*` set for the breadcrumb row. **The topbar owns no bottom gap** — it has no margin token and sets no margin; spacing to the next block belongs to the page or to `ds-app-layout`'s content padding. (This paragraph previously documented a `--ds-topbar-margin-b` that has never existed in the shipped component.)
|
|
280
303
|
|
|
304
|
+
#### `<ds-app-layout>` — `AppLayoutComponent`
|
|
305
|
+
Inputs: `topbarSpan: 'content' | 'full' = 'content'`, `railOpen: model<boolean> = false` (the overlay rail below `--bp-lg`), `railLabel: string = 'Navigation'`, `restoreScroll: boolean = false`, `restoreScrollTimeout: number = 2000` (ms), `scrollReset: 'path' | 'always' | 'never' = 'path'`
|
|
306
|
+
Content slots: `[sidenav]`, `[topbar]`, default (the page)
|
|
307
|
+
Reads: `railId` and the read-only `railOverlay` signal, for a consumer-built burger; `dsRailTrigger` wires one for you.
|
|
308
|
+
Tokens: `--ds-app-layout-pad-x`, `--ds-app-layout-pad-y`, `--ds-app-layout-content-max-width`, `--ds-app-layout-height`, `--ds-app-layout-rail-bg-color`, `--ds-app-layout-rail-shadow`, `--ds-app-layout-scrim-color`
|
|
309
|
+
It owns the app's scroll CONTAINER, so a screen that needs to move the scroll calls `LayoutScrollService` rather than touching `window`.
|
|
310
|
+
|
|
311
|
+
#### `<ds-auth-layout>` — `AuthLayoutComponent`
|
|
312
|
+
Inputs: `brand: string | null = null`, `logoLetter: string | null = null`, `tagline: string | null = null` (all three fall back to `DS_CONFIG.brand`), `cardElevation: CardElevation = 'raised'`, `cardPadding: CardPadding = 'lg'`, `landmark: 'main' | 'none' = 'none'`
|
|
313
|
+
Content slots: `[brand]` (replaces the whole mark row), `[dsBrandName]` (the name beside the generated mark), default (the card body), `[dsAuthSupport]` (the line under the card)
|
|
314
|
+
Tokens: `--ds-auth-layout-min-height`, `--ds-auth-layout-bg-color`, `--ds-auth-layout-gap`, `--ds-auth-layout-pad-block`, `--ds-auth-layout-card-max-width`, `--ds-auth-layout-mark-size`, `--ds-auth-layout-mark-radius`, `--ds-auth-layout-mark-bg-color`, `--ds-auth-layout-mark-label-color`
|
|
315
|
+
`landmark="main"` only when the page has no other `<main>`; the sign-in card is not automatically the document's main landmark.
|
|
316
|
+
|
|
281
317
|
#### `<ds-page-header>` — `PageHeaderComponent`
|
|
282
318
|
Inputs: `eyebrow: string = ''`, `title: required string`, `subtitle: string = ''`, `compact: boolean = false`, `divider: boolean = false`, `metaDivider: boolean = false`
|
|
283
319
|
Content slots: `[breadcrumbs]`, `[title-badge]` (sits next to the title text), `[actions]` (right edge of title row), `[meta]` (under the title row), `[tabs]` (under the meta row)
|
|
@@ -436,19 +472,43 @@ bootstrapApplication(AppComponent, {
|
|
|
436
472
|
|
|
437
473
|
`DsConfig` shape (see `src/lib/config/ds-config.ts`):
|
|
438
474
|
|
|
475
|
+
Twelve sections. `src/lib/config/ds-config.ts` is the source of truth — each key carries its own
|
|
476
|
+
doc comment there, including why it is an app-level decision at all.
|
|
477
|
+
|
|
439
478
|
```ts
|
|
440
479
|
interface DsConfig {
|
|
441
|
-
|
|
442
|
-
|
|
443
|
-
|
|
480
|
+
field?: {
|
|
481
|
+
reserveMessage?: boolean; // keep a message line of space when empty
|
|
482
|
+
errorMessages?: Record<string, string>; // fallback text per validation-error kind
|
|
483
|
+
stateIcons?: false | { // the message line's leading glyph, per state
|
|
484
|
+
error?: IconName | false; // default: `error`
|
|
485
|
+
warning?: IconName | false; // default: `warn`
|
|
486
|
+
success?: IconName | false; // default: `success`
|
|
487
|
+
hint?: IconName | false; // default: NONE — hint is not a state
|
|
488
|
+
};
|
|
444
489
|
};
|
|
490
|
+
control?: { size?: DsSize }; // every control on the field-height contract
|
|
491
|
+
card?: { elevation?: CardElevation; padding?: CardPadding };
|
|
492
|
+
table?: { stickyScrollbar?: boolean; bordered?: boolean };
|
|
493
|
+
modal?: { dividers?: boolean }; // reaches a ModalService confirm, which has no host to bind
|
|
494
|
+
icon?: { size?: number };
|
|
495
|
+
badge?: { withDot?: boolean };
|
|
496
|
+
breadcrumbs?: { separator?: IconName; clickable?: boolean };
|
|
497
|
+
datePicker?: { locale?: string; dateFormat?: string; firstDayOfWeek?: number };
|
|
498
|
+
timePicker?: { format?: '24h' | '12h' };
|
|
499
|
+
avatar?: { initials?: (name: string) => string };
|
|
500
|
+
brand?: { name?: string; logoLetter?: string; tagline?: string };
|
|
445
501
|
}
|
|
446
502
|
```
|
|
447
503
|
|
|
448
|
-
|
|
449
|
-
|
|
504
|
+
Precedence is always: **explicit input → config → component default.** A component publishes what it
|
|
505
|
+
resolved as a public readback (`sizeResolved()`, `dividersResolved()`, …) so a host can read the
|
|
506
|
+
effective value rather than re-deriving the chain.
|
|
450
507
|
|
|
451
|
-
|
|
508
|
+
**Call `provideDsConfig` once per injector.** Two calls in the same `providers` array do NOT merge —
|
|
509
|
+
both resolve their parent with `skipSelf`, so the later wins and the earlier is silently lost. Merging
|
|
510
|
+
happens across injector LEVELS: a route or component inherits the app's config and overrides only the
|
|
511
|
+
keys it names.
|
|
452
512
|
|
|
453
513
|
---
|
|
454
514
|
|