@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/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 and have drifted.** `ds-button` in particular is documented here with its pre-`color`×`variant` API and the pre-rename token names (`--ds-button-bg-color`, `-fg`), neither of which is current. The authoritative, auto-generated surfaces are the **Component API tables** and the **token reference** in `ds-docs` (extracted from source on every build, so they cannot go stale) — trust those first, and treat this file as prose about intent. Re-verified 2026-08-05; the sweep to reconcile it is tracked in `docs/todo.md`.
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 uses one label recipe for every variant, `oklch(from accent 70% 0.035 h)`. (History: the single `variant` axis was split into color × variant in 2026-06; `danger`→`error`, `link`→`text`, the old `ghost`→`outline`.)
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 = ''` (renders a letter mark + name; omit to project custom content)
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: `--primary`), `--ds-sidenav-item-label-color-active` (default: `--text-on-primary`), `--ds-sidenav-item-rail` (left rail, default: `--secondary`), `--ds-sidenav-item-radius`, `--ds-sidenav-alert-color`
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
- breadcrumbs?: {
442
- separator?: IconName;
443
- clickable?: boolean;
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
- Currently consumed by:
449
- - `<ds-breadcrumbs>` — `[separator]` / `[clickable]` inputs fall back to `breadcrumbs.separator` / `breadcrumbs.clickable` from config, then to `'chevronRight'` / `true`.
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
- Add more sections to `DsConfig` as we extract reusable defaults; the precedence chain is always: explicit input → config → component default.
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