@ids-group-ltd/ids-design-system 0.10.0 → 0.10.2

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
@@ -120,13 +120,29 @@ Every entry below names its exported class (`ButtonComponent`, `TableComponent<T
120
120
 
121
121
  **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
122
 
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`.
123
+ > **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
124
 
125
125
  ### Form & input
126
126
 
127
+ **Shared by every field** (input, textarea, select, multi-select, autocomplete, date/time/colour picker,
128
+ checkbox, radio, radio-group, switch, slider, segmented, OTP): `label`, `hint`, `error`, `warning`,
129
+ `errors`, `invalid`, `touched`, `reserveMessage` — and one message line under the control that renders
130
+ whichever of them wins. The ladder is error → errors → warning → advisory errors → success → hint.
131
+
132
+ `error`, `warning` and `success` lead that line with a glyph; `hint` does not, because it is the resting
133
+ text rather than a state. Retune app-wide with `DS_CONFIG.field.stateIcons` (per state, independent —
134
+ `false` removes one, an `IconName` replaces it, `stateIcons: false` removes all four), or per field with
135
+ `messageIcon: IconName | false | null`, which wins over the config. Spacing hooks:
136
+ `--ds-field-message-icon-gap`, `--ds-field-message-icon-offset`.
137
+
138
+ **`ds-search` is deliberately NOT on that list.** It binds to a form like the others — `[formControl]`,
139
+ `formControlName`, `[(ngModel)]`, signal forms, plus its own `[(value)]` — and it takes `disabled` and
140
+ `hidden`, but it renders no message row and therefore takes none of the message inputs. A toolbar filter
141
+ is not a validated field; where a search needs a label or an error line, use `ds-input`.
142
+
127
143
  #### `<ds-button>` — `ButtonComponent`
128
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`.
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`.)
145
+ 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
146
  Output: `(pressed): MouseEvent` — only fires when not disabled and not loading
131
147
  Content slots: default (label / leading or trailing icon). For icon-only actions use `<ds-icon-button>`.
132
148
  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 +203,11 @@ Inputs: `options: readonly ComboboxOption<T>[]` (`{ value: T, label: string }`),
187
203
  In multi mode, selected values render as `<ds-tag closable>` chips above the trigger.
188
204
 
189
205
  #### `<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`
206
+ Pre-styled search input with built-in icon. A form control, but not a field: no label, no message row.
207
+ 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
208
  Output: `(submitted): string` — emits the current value on Enter / form submit
209
+ Methods: `clear()` — empties the field, drops an armed keystroke and publishes `''` at once, which writing `''` into `value` does not; `focus()`.
210
+ 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
211
 
194
212
  #### `<ds-date-picker>` — `DatePickerComponent`
195
213
  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 +277,7 @@ The companion `<ds-toast-region>` lives inside the `ToastService` (see Services)
259
277
  ### Layout & navigation
260
278
 
261
279
  #### `<ds-sidenav>` — `SidenavComponent`
262
- Inputs: `collapsed: boolean = false`, `brand: string = ''` (renders a letter mark + name; omit to project custom content)
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)
263
281
  Content: default slot for groups/items + custom brand/footer rows
264
282
  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
283
 
@@ -269,15 +287,28 @@ Content slots: default (items); `[ds-group-icon]` (custom group icon when not us
269
287
  When `expandable=true` renders header button with toggle + caret; collapses body when not expanded.
270
288
 
271
289
  #### `<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`
290
+ 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
291
  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`
292
+ 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
293
 
276
294
  #### `<ds-topbar>` — `TopBarComponent`
277
295
  No inputs.
278
296
  Content slots: `[title]`, `[breadcrumbs]`, `[search]`, `[actions]`. Sits at `--topbar-h` height.
279
297
  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
298
 
299
+ #### `<ds-app-layout>` — `AppLayoutComponent`
300
+ 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'`
301
+ Content slots: `[sidenav]`, `[topbar]`, default (the page)
302
+ Reads: `railId` and the read-only `railOverlay` signal, for a consumer-built burger; `dsRailTrigger` wires one for you.
303
+ 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`
304
+ It owns the app's scroll CONTAINER, so a screen that needs to move the scroll calls `LayoutScrollService` rather than touching `window`.
305
+
306
+ #### `<ds-auth-layout>` — `AuthLayoutComponent`
307
+ 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'`
308
+ 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)
309
+ 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`
310
+ `landmark="main"` only when the page has no other `<main>`; the sign-in card is not automatically the document's main landmark.
311
+
281
312
  #### `<ds-page-header>` — `PageHeaderComponent`
282
313
  Inputs: `eyebrow: string = ''`, `title: required string`, `subtitle: string = ''`, `compact: boolean = false`, `divider: boolean = false`, `metaDivider: boolean = false`
283
314
  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 +467,43 @@ bootstrapApplication(AppComponent, {
436
467
 
437
468
  `DsConfig` shape (see `src/lib/config/ds-config.ts`):
438
469
 
470
+ Twelve sections. `src/lib/config/ds-config.ts` is the source of truth — each key carries its own
471
+ doc comment there, including why it is an app-level decision at all.
472
+
439
473
  ```ts
440
474
  interface DsConfig {
441
- breadcrumbs?: {
442
- separator?: IconName;
443
- clickable?: boolean;
475
+ field?: {
476
+ reserveMessage?: boolean; // keep a message line of space when empty
477
+ errorMessages?: Record<string, string>; // fallback text per validation-error kind
478
+ stateIcons?: false | { // the message line's leading glyph, per state
479
+ error?: IconName | false; // default: `error`
480
+ warning?: IconName | false; // default: `warn`
481
+ success?: IconName | false; // default: `success`
482
+ hint?: IconName | false; // default: NONE — hint is not a state
483
+ };
444
484
  };
485
+ control?: { size?: DsSize }; // every control on the field-height contract
486
+ card?: { elevation?: CardElevation; padding?: CardPadding };
487
+ table?: { stickyScrollbar?: boolean; bordered?: boolean };
488
+ modal?: { dividers?: boolean }; // reaches a ModalService confirm, which has no host to bind
489
+ icon?: { size?: number };
490
+ badge?: { withDot?: boolean };
491
+ breadcrumbs?: { separator?: IconName; clickable?: boolean };
492
+ datePicker?: { locale?: string; dateFormat?: string; firstDayOfWeek?: number };
493
+ timePicker?: { format?: '24h' | '12h' };
494
+ avatar?: { initials?: (name: string) => string };
495
+ brand?: { name?: string; logoLetter?: string; tagline?: string };
445
496
  }
446
497
  ```
447
498
 
448
- Currently consumed by:
449
- - `<ds-breadcrumbs>` — `[separator]` / `[clickable]` inputs fall back to `breadcrumbs.separator` / `breadcrumbs.clickable` from config, then to `'chevronRight'` / `true`.
499
+ Precedence is always: **explicit input → config → component default.** A component publishes what it
500
+ resolved as a public readback (`sizeResolved()`, `dividersResolved()`, …) so a host can read the
501
+ effective value rather than re-deriving the chain.
450
502
 
451
- Add more sections to `DsConfig` as we extract reusable defaults; the precedence chain is always: explicit input → config → component default.
503
+ **Call `provideDsConfig` once per injector.** Two calls in the same `providers` array do NOT merge —
504
+ both resolve their parent with `skipSelf`, so the later wins and the earlier is silently lost. Merging
505
+ happens across injector LEVELS: a route or component inherits the app's config and overrides only the
506
+ keys it names.
452
507
 
453
508
  ---
454
509