@ids-group-ltd/ids-design-system 0.11.0 → 0.11.1

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.
Files changed (47) hide show
  1. package/CHANGELOG.md +1164 -1011
  2. package/components.md +49 -26
  3. package/design-system.md +18 -18
  4. package/fesm2022/ids-group-ltd-ids-design-system.mjs +527 -116
  5. package/fesm2022/ids-group-ltd-ids-design-system.mjs.map +1 -1
  6. package/migrations/0.10.0.json +19 -19
  7. package/migrations/0.10.1.json +20 -7
  8. package/migrations/0.10.2.json +8 -8
  9. package/migrations/0.10.3.json +2 -2
  10. package/migrations/0.11.0.json +12 -12
  11. package/migrations/0.11.1.json +305 -0
  12. package/migrations/0.2.2.json +1 -1
  13. package/migrations/0.3.0.json +1 -1
  14. package/migrations/0.5.1/badge-statuses.md +1 -3
  15. package/migrations/0.5.1.json +1 -1
  16. package/migrations/0.6.3.json +1 -1
  17. package/migrations/0.7.1.json +3 -3
  18. package/migrations/0.8.0.json +5 -5
  19. package/migrations/0.9.0.json +10 -9
  20. package/migrations/0.9.1.json +2 -2
  21. package/migrations/README.md +34 -52
  22. package/package.json +1 -1
  23. package/styles/_dropdown-overlay.scss +35 -13
  24. package/styles/_ds-color.scss +3 -3
  25. package/styles/_field-box.scss +2 -6
  26. package/styles/_field-label.scss +5 -10
  27. package/styles/_field-state.scss +3 -2
  28. package/styles/_focus.scss +0 -2
  29. package/styles/_layout-utils.scss +2 -2
  30. package/styles/_overlay-motion.scss +2 -3
  31. package/styles/_press.scss +3 -5
  32. package/styles/_reset.scss +0 -1
  33. package/styles/_scrollbar.scss +1 -3
  34. package/styles/_status.scss +1 -2
  35. package/styles/_surface-motion.scss +3 -4
  36. package/styles/_text-clip.scss +1 -1
  37. package/styles/_theme-activation.scss +1 -1
  38. package/styles/_tokens-charts.scss +1 -3
  39. package/styles/_tokens.scss +4 -3
  40. package/styles/_typography.scss +2 -2
  41. package/themes/README.md +3 -3
  42. package/themes/_base-palette.scss +2 -2
  43. package/themes/_semantic.scss +2 -2
  44. package/themes/dark/_palette.scss +1 -2
  45. package/themes/light/_palette.scss +1 -1
  46. package/themes/light/_theme.scss +1 -1
  47. package/types/ids-group-ltd-ids-design-system.d.ts +274 -49
package/components.md CHANGED
@@ -6,12 +6,13 @@
6
6
  > which type role where, how a page is composed) see `design-system.md`, which carries
7
7
  > the rules this catalogue deliberately does not.
8
8
  >
9
- > **Where it overlaps with generated output:** ds-docs extracts a Component API table and
9
+ > **Where it overlaps with generated output:** the documentation site
10
+ > (https://ids-ds.proto.ids-group.co.uk/) carries a generated Component API table and
10
11
  > a token reference from source on every build, and those cannot go stale. Where this file
11
- > and ds-docs disagree, ds-docs is right — prefer it for exact inputs and token names, and
12
+ > and the generated tables disagree, the generated ones are right — prefer them for exact inputs and token names, and
12
13
  > use this catalogue for orientation. Each entry shows the selector, the key inputs/outputs/slots, and the public CSS custom properties that consumers can override.
13
14
  >
14
- > **Import path:** `import { ButtonComponent, … } from 'ds'` (the library publishes as `ds`; consumer apps add a `paths` mapping in their `tsconfig.json` or install the built `dist/ds` package).
15
+ > **Import path:** `import { ButtonComponent, … } from '@ids-group-ltd/ids-design-system'`.
15
16
  >
16
17
  > **Templating note:** every component is standalone with `ViewEncapsulation.Emulated`. Pass classes on the host element to scope local tweaks; override DS tokens at the host level (`ds-xxx { --ds-xxx-…: … }`) — defaults are declared on `:host` (or the root class) so consumer overrides cascade in.
17
18
 
@@ -45,7 +46,7 @@ Loaded via `@use 'styles/tokens';` (when the consumer also `@use 'styles/ds';` t
45
46
 
46
47
  **Typography:**
47
48
  - Families: `--font-sans`, `--font-mono`, `--font-display`, `--font-heading`
48
- - Weights: `--font-weight-regular` 400, `--font-weight-medium` 500, `--font-weight-semibold` 600, `--font-weight-bold` 700, `--font-weight-extrabold` 800 (overridden to 700 in brand-mm)
49
+ - Weights: `--font-weight-regular` 400, `--font-weight-medium` 500, `--font-weight-semibold` 600, `--font-weight-bold` 700, `--font-weight-extrabold` 800 (a brand overlay may step this down to 700)
49
50
  - Sizes: `--font-size-display` 64, `--font-size-h1` 48, `--font-size-h2` 36, `--font-size-h3` 28, `--font-size-h4` 22, `--font-size-h5` 18, `--font-size-h5-strong` 20, `--font-size-l` 18, `--font-size-m` 16, `--font-size-s` 14, `--font-size-xs` 12, `--font-size-2xs` 11, `--font-size-3xs` 10, `--font-size-4xs` 9, `--font-size-mono` 13
50
51
  - Line heights: `--line-height-tight` 1.1, `--line-height-snug` 1.25, `--line-height-base` 1.4, `--line-height-loose` 1.6, `--line-height-flat` 1
51
52
  - Letter spacing: `--letter-spacing-tight`, `--letter-spacing-snug`, `--letter-spacing-normal`, `--letter-spacing-wide`, `--letter-spacing-wider`
@@ -68,7 +69,7 @@ Loaded via `@use 'styles/tokens';` (when the consumer also `@use 'styles/ds';` t
68
69
 
69
70
  ### Grid
70
71
 
71
- Responsive 4-tier page grid loaded via `@use 'styles/ds'` (or directly via `@use '../../ds/src/lib/styles/page-grid';`). One column-count per breakpoint, gutters and margins scale with the viewport, container caps on the widest tier and stays fluid below.
72
+ Responsive 4-tier page grid loaded via `@use 'styles/ds'` (or directly via `@use 'styles/page-grid';`). One column-count per breakpoint, gutters and margins scale with the viewport, container caps on the widest tier and stays fluid below.
72
73
 
73
74
  | Tier | Range | Cols | Gutter | Margin | Container cap |
74
75
  | ------------ | ------------- | ---- | ------------- | -------------- | ------------------------ |
@@ -88,7 +89,7 @@ Responsive 4-tier page grid loaded via `@use 'styles/ds'` (or directly via `@use
88
89
  - Snap to columns, not pixels. Canonical two-column splits: 8+4, 6+6, 9+3. Never 7+5.
89
90
  - Sidenav lives OUTSIDE the grid. Reserve its rail (collapsed 64px / open 240px via `--sidenav-w` / `--sidenav-w-collapsed`), then start `.page-grid` in the remaining width.
90
91
  - Prose caps at 720px via `--col-cap-text` regardless of grid width.
91
- - 8+4 is canonical for record-detail pages (main + meta sidebar); 9+3 is reserved for kit / track-plan picker rails.
92
+ - 8+4 is canonical for record-detail pages (main + meta sidebar); 9+3 is reserved for a narrow picker or filter rail.
92
93
 
93
94
  **Markup example:**
94
95
 
@@ -121,11 +122,11 @@ The DS aggregate (`@use 'styles/ds'`) forwards the full stack: theme primitives
121
122
 
122
123
  ## Components
123
124
 
124
- Every entry below names its exported class (`ButtonComponent`, `TableComponent<T>`, …). Those names are exported for typing, DI, `viewChild` and template refs — **not as an extension point: subclassing a DS component is unsupported.** Any minor release may add members to a class, and a subclass that happens to have used one of those names breaks on it (TS4114 "must have an 'override' modifier", or TS2416 when the signature differs) — DS 0.6.3 added ~76 members to `TableComponent` alone. Compose instead: wrap the component, project into its slots, retune it through its `--ds-*` tokens. If you subclass anyway, treat every upgrade as potentially build-breaking — the changelog flags the risk (see `migrations/AUTHORING.md`), it does not avoid it.
125
+ Every entry below names its exported class (`ButtonComponent`, `TableComponent<T>`, …). Those names are exported for typing, DI, `viewChild` and template refs — **not as an extension point: subclassing a DS component is unsupported.** Any minor release may add members to a class, and a subclass that happens to have used one of those names breaks on it (TS4114 "must have an 'override' modifier", or TS2416 when the signature differs) — DS 0.6.3 added ~76 members to `TableComponent` alone. Compose instead: wrap the component, project into its slots, retune it through its `--ds-*` tokens. If you subclass anyway, treat every upgrade as potentially build-breaking — the changelog flags the risk, it does not avoid it.
125
126
 
126
127
  **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.
127
128
 
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).
129
+ > **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** on the documentation site, both generated from the source of each release, 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.
129
130
 
130
131
  ### Form & input
131
132
 
@@ -147,12 +148,12 @@ is not a validated field; where a search needs a label or an error line, use `ds
147
148
 
148
149
  #### `<ds-button>` — `ButtonComponent`
149
150
  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`.
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`.)
151
+ Axis meaning: **variant is loudness** (solid > tonal > outline/ghost/text), **color is hue** — every pair renders, and the UX-discouraged ones dev-warn with the reason. 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`.)
151
152
  Output: `(pressed): MouseEvent` — only fires when not disabled and not loading
152
153
  Content slots: default (label / leading or trailing icon), plus `[dsButtonSubtext]` for a projected second line. For icon-only actions use `<ds-icon-button>`.
153
154
  **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
155
  - **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
+ - **Temporary** (the form is not filled in yet): do NOT disable the button at all. Leave it live, judge validity in the submit handler, and carry the text UNDER the button with `hint` / `warning` / `error` — the same three inputs the fields take, resolved and rendered by the same `ds-field-message` row the fields use, with the same `messageIcon` and `reserveMessage` knobs and the same `DS_CONFIG.field.*` fallbacks. Those inputs live on an internal shared base class that `ButtonComponent` and every field extend, so the behaviour cannot drift apart. What it does NOT take is `errors` / `invalid` / `touched`: a button has no validation state of its own.
156
157
  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
158
  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.
158
159
 
@@ -202,21 +203,43 @@ Inputs: `checked: model<boolean>`, `disabled: boolean = false`, `name: string =
202
203
  #### `<ds-switch>` — `SwitchComponent`
203
204
  Inputs: `checked: model<boolean>`, `disabled: boolean = false`, `name: string | null = null`, `variant: 'default' | 'success' | 'error' = 'default'`, `inputId: string | null = null`
204
205
 
206
+ #### The picker family — `<ds-select>`, `<ds-multi-select>`, `<ds-autocomplete>`
207
+ Five rules hold across all three: one meaning per member name, difference only where a reason is stated, one panel implementation (`.dropdown-panel` / `.dropdown-list`), no library-invented string without a slot to replace it, and one way to clip a line.
208
+
209
+ Shared inputs: `options` (flat items, groups, or a mix), `value: model`, `placeholder`, `size: DsSize | null = null`, `width: DsControlWidth = 'fill'` (`'fill' | 'content'`), `label`, `disabled`, `required`, `optional`, `success`, `ariaLabel`.
210
+
211
+ Shared option shape: `DsOption<T> = { label, value, disabled? }` and `DsOptionGroup<T> = { label, options, disabled? }`, with `DsOptionItem<T>` the union. Each picker re-exports it under its own name (`SelectItem`, `MultiSelectItem`, `AutocompleteItem<T>`), so one array literal fits all three.
212
+
213
+ Shared slots — content-projected directives, each a `<ng-template>`:
214
+ - `[dsOptionTemplate]` — the option row, on all three
215
+ - `[dsChipTemplate]` — a selected chip, on multi-select and autocomplete
216
+ - `[dsPickerTrigger]` — replaces the trigger, on all three
217
+ - `[dsEmptyTemplate]` — the "no matches" state, on all three
218
+ - `[dsCreateTemplate]` — the "create «…»" row, on autocomplete
219
+
220
+ Shared panel tokens — the three pickers portal their panel out of the component, so these are declared on the host and forwarded onto the pane; a per-instance `ds-select { --ds-dropdown-panel-radius: 8px }` reaches it. `--ds-dropdown-panel-bg-color`, `-radius`, `-maxh`, `-minw`, `-maxw` (the last two bound the panel in `width="content"`). Each picker's own `--ds-<name>-panel-bg-color` / `-radius` / `-maxh` is an ALIAS of the shared one and still works.
221
+
222
+ Shared option tokens, painting the row inside any of the three panels: `--ds-option-selected-bg-color`, `-hover`, `--ds-option-selected-label-color`, `--ds-option-check-color`. `ds-select` and `ds-autocomplete` mark the selection with the check glyph these paint; `ds-multi-select` uses a checkbox and answers to `--ds-multi-select-check-bg-color` instead.
223
+
205
224
  #### `<ds-select>` — `SelectComponent`
206
- Inputs: `value: model<string>`, `options: SelectItem[]` (`SelectOption | SelectOptionGroup`, where `SelectOption = { label, value, disabled? }` and `SelectOptionGroup = { label, options: SelectOption[], disabled? }`), `placeholder: string = ''`, `size: 'sm' | 'md' | 'lg' = 'md'`, `label: string = ''`, `disabled: boolean = false`, `invalid: boolean = false`, `required: boolean = false`, `optional: boolean = false`, `name: string | null = null`
207
- Renders trigger + CDK overlay panel; keyboard support: ArrowUp/Down, Enter/Space, Home/End, Escape — skipping group-header labels. Pass a mix of flat `SelectOption`s and `SelectOptionGroup`s to render `<optgroup>`-style sections; existing flat-list consumers keep working unchanged. Type guard `isSelectOptionGroup(item)` is re-exported.
225
+ Inputs: `value: model<string>`, `options: SelectItem[]`, `placeholder: string = ''`, `size`, `width`, `label`, `disabled`, `readOnly`, `readonly` (an alias of `readOnly`, because signal forms binds by name), `success`, `required`, `optional`, `clearable`, `name: string | null = null`, `ariaLabel`
226
+ Trigger plus a CDK overlay panel. Keyboard: ArrowUp/Down, Enter/Space, Home/End, Escape, skipping group headers. `isSelectOptionGroup(item)` is re-exported as a type guard.
227
+
228
+ #### `<ds-multi-select>` — `MultiSelectComponent`
229
+ Inputs: `value: model<string[]>`, `options: readonly MultiSelectItem[]`, `placeholder: string = 'Select…'`, `searchPlaceholder: string = 'Filter…'`, `searchable: boolean | number | null = null` (`true` always shows the filter row, `false` never, a NUMBER shows it once the option count reaches it), `selectAll: boolean | 'group' | 'both' = false` (`'group'` puts a row per group, `'both'` adds a global row beside them), `triggerDisplay: DsTriggerDisplay = 'full'` (`'full' | 'count' | 'labels'`), `maxVisibleChips: number | 'fit' | 'all' | null = null` (a NUMBER is a ceiling, not an exact count — fewer fit when the trigger is narrow), `width`, `size`, `label`, `disabled`, `success`, `required`, `optional`, `ariaLabel`
208
230
 
209
- #### `<ds-combobox>` — `ComboboxComponent<T>`
210
- Searchable select with typeahead. Generic on the option value type `T`.
211
- Inputs: `options: readonly ComboboxOption<T>[]` (`{ value: T, label: string }`), `value: model<T | readonly T[] | null>`, `multiple: boolean = false`, `placeholder: string = 'Select…'`
212
- In multi mode, selected values render as `<ds-tag closable>` chips above the trigger.
231
+ #### `<ds-autocomplete>` — `AutocompleteComponent<T>`
232
+ Type-ahead picker, generic on the option value.
233
+ Inputs: `options: readonly AutocompleteItem<T>[]`, `value: model<T | readonly T[] | null>`, `multiple: boolean = false`, `placeholder: string = 'Select…'`, `showChevron: boolean = true`, `valueOverflow: AutocompleteValueOverflow = 'ellipsis'` (`'ellipsis' | 'wrap'` — a settled single value clips rather than growing the trigger), `maxVisibleChips`, `allowCreate: boolean = false`, `width`, `size`, `label`, `disabled`, `success`, `required`, `optional`, `ariaLabel`
234
+ Output: `(create): string` — the typed text, when `allowCreate` is on and nothing matched.
235
+ In multiple mode the selection renders as chips above the trigger.
213
236
 
214
237
  #### `<ds-search>` — `SearchComponent`
215
238
  Pre-styled search input with built-in icon. A form control, but not a field: no label, no message row.
216
239
  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)
217
240
  Output: `(submitted): string` — emits the current value on Enter / form submit
218
241
  Methods: `clear()` — empties the field, drops an armed keystroke and publishes `''` at once, which writing `''` into `value` does not; `focus()`.
219
- Binds through `NG_VALUE_ACCESSOR`, taking the CVA plumbing without `DsFieldBase` — so `hint` / `error` / `warning` / `errors` / `invalid` / `touched` / `reserveMessage` / `messageIcon` are NOT inputs here.
242
+ Binds through `NG_VALUE_ACCESSOR`, taking the value plumbing without the field-message layer — so `hint` / `error` / `warning` / `errors` / `invalid` / `touched` / `reserveMessage` / `messageIcon` are NOT inputs here.
220
243
 
221
244
  #### `<ds-date-picker>` — `DatePickerComponent`
222
245
  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`
@@ -299,13 +322,13 @@ When `expandable=true` renders header button with toggle + caret; collapses body
299
322
  #### `<ds-sidenav-item>` — `SidenavItemComponent`
300
323
  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`)
301
324
  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.
325
+ **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. 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.
303
326
  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`
304
327
 
305
328
  #### `<ds-topbar>` — `TopBarComponent`
306
329
  No inputs.
307
330
  Content slots: `[title]`, `[breadcrumbs]`, `[search]`, `[actions]`. Sits at `--topbar-h` height.
308
- 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.)
331
+ 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.
309
332
 
310
333
  #### `<ds-app-layout>` — `AppLayoutComponent`
311
334
  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'`
@@ -359,7 +382,7 @@ Inputs: `elevation: 'flat' | 'raised' | 'hover' | 'interactive' = 'flat'`, `padd
359
382
  Output: `(pressed): MouseEvent` — fires only when `elevation="interactive"`
360
383
  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
384
  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"`.
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`.
385
+ 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; a brand can step it down to `var(--font-size-h5)`). 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`.
363
386
 
364
387
  #### `<ds-accordion>` + `<ds-accordion-item>` — `AccordionComponent`, `AccordionItemComponent`
365
388
  Accordion is a thin wrapper that rounds + borders its children. Item inputs: `title: string = ''`, `expanded: model<boolean> = false`. Content slots on item: default (body), `[badge]` (rendered next to the title in the header).
@@ -437,14 +460,14 @@ All built-in icons (kebab-case where indicated, camelCase otherwise — DS uses
437
460
 
438
461
  `search` `plus` `minus` `check` `x` `chevronDown` `chevronRight` `chevronLeft` `chevronUp` `arrowRight` `arrowUp` `arrowDown` `info` `warn` `error` `success` `bell` `settings` `user` `users` `home` `calendar` `truck` `box` `map` `activity` `folder` `edit` `external` `trash` `copy` `download` `upload` `eye` `filter` `sort` `sortAsc` `sortDesc` `grid` `list` `moreH` `moreV` `link` `flag` `star` `inbox` `archive` `clock` `refresh` `play` `pause` `cmd` `paperclip` `file` `image` `lock` `logout` `help` `pin` `bookmark` `sparkle` `layers` `chart` `gauge` `package` `git` `sun` `moon` `save` `rotate` `qr` `globe` `phone` `bin` `pen` `smile` `frown` `mail` `eye-off` `check-circle` `drag`
439
462
 
440
- Adding icons to DS: edit `src/lib/icons/icons.data.ts`; SVG paths render inside `<svg viewBox="0 0 24 24" fill="none" stroke="currentColor">`. For consumer-side icons without forking DS, use `provideDsIcons(…)` below.
463
+ Icons render inside `<svg viewBox="0 0 24 24" fill="none" stroke="currentColor">`. For consumer-side icons without forking DS, use `provideDsIcons(…)` below.
441
464
 
442
465
  #### `DS_ICON_REGISTRY` / `provideDsIcons(icons)`
443
466
 
444
467
  Consumer apps can register additional icons without forking DS. Each entry maps a name to the raw SVG body — everything that goes *inside* `<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75">`. Typically one or more `<path>` / `<circle>` / `<rect>` elements with no `stroke`/`fill` of their own (the host SVG paints them).
445
468
 
446
469
  ```ts
447
- import { provideDsIcons } from 'ds';
470
+ import { provideDsIcons } from '@ids-group-ltd/ids-design-system';
448
471
 
449
472
  bootstrapApplication(AppComponent, {
450
473
  providers: [
@@ -467,7 +490,7 @@ Lookup order: built-in `ICONS` first, then the consumer registry. Names that col
467
490
  Inject `DS_CONFIG` token (default factory returns `{}`) to set library-wide defaults that consumer-level component inputs can still override.
468
491
 
469
492
  ```ts
470
- import { provideDsConfig } from 'ds';
493
+ import { provideDsConfig } from '@ids-group-ltd/ids-design-system';
471
494
 
472
495
  bootstrapApplication(AppComponent, {
473
496
  providers: [
@@ -478,9 +501,9 @@ bootstrapApplication(AppComponent, {
478
501
  });
479
502
  ```
480
503
 
481
- `DsConfig` shape (see `src/lib/config/ds-config.ts`):
504
+ `DsConfig` shape (the exported `DsConfig` type is the full contract):
482
505
 
483
- Twelve sections. `src/lib/config/ds-config.ts` is the source of truth — each key carries its own
506
+ Twelve sections. The exported `DsConfig` type is the source of truth — each key carries its own
484
507
  doc comment there, including why it is an app-level decision at all.
485
508
 
486
509
  ```ts
@@ -542,7 +565,7 @@ this.crumbs.clear();
542
565
 
543
566
  1. **Programmatic** — each page calls `this.crumbs.set(...)` (e.g. inside `effect(() => …)` when the page model resolves). Use when crumb labels depend on data the page already has loaded (a program name, a campaign title).
544
567
 
545
- 2. **Route-driven** — annotate routes with `data.breadcrumb` and run a Router→Service bridge once at app bootstrap. Example bridge lives at `app/core/breadcrumbs/breadcrumbs-route.bootstrap.ts` in this repo. `breadcrumb` accepts:
568
+ 2. **Route-driven** — annotate routes with `data.breadcrumb` and run a Router→Service bridge once at app bootstrap. `breadcrumb` accepts:
546
569
  - `string` → `{ label: string, href: <built-from-url> }`
547
570
  - `BreadcrumbItem`
548
571
  - `BreadcrumbItem[]`
package/design-system.md CHANGED
@@ -3,7 +3,8 @@
3
3
  > **This file is the HOW.** Which spacing goes between what, which type role a piece of
4
4
  > text takes, where a value belongs and where a literal is a bug. For the WHAT — the
5
5
  > inventory of components, their inputs and their tokens — see `components.md`, and
6
- > prefer the ds-docs Component API and token reference, which are extracted from source
6
+ > prefer the Component API and token reference on the documentation site
7
+ > (https://ids-ds.proto.ids-group.co.uk/), which are generated from source
7
8
  > on every build and cannot go stale.
8
9
  >
9
10
  > **Audience: whoever composes a screen, human or agent.** Knowing the 639 tokens is not
@@ -139,10 +140,9 @@ the next reader of your CSS.
139
140
  Measured by which property each one actually lands on, across every component that uses one:
140
141
 
141
142
  - **`--<status>`** — the saturated one: `border-color`, the fill of a solid button, and the
142
- `color` of a MARKER — a required asterisk, an icon badge's glyph. Every one of the eight
143
- `color: var(--error)` declarations in the library is a marker of that kind, six of them the
144
- `.req` asterisk, and the other two an icon sitting on an `--error-subtitle` tint. **That
145
- glyph-on-tint pair is the pattern to copy**, and the reason not to put prose in this member:
143
+ `color` of a MARKER — a required asterisk, an icon badge's glyph. Every `color: var(--error)`
144
+ declaration in this library lands on a marker of that kind: an asterisk, or a glyph sitting on an
145
+ `--error-subtitle` tint. **That glyph-on-tint pair is the pattern to copy**, and the reason not to put prose in this member:
146
146
  it is contrast-checked as a large glyph, not as text.
147
147
  - **`--<status>-text`** — `color`, on a light surface. This is the contrast-safe member, and the
148
148
  one you want for a message.
@@ -193,7 +193,7 @@ and `--ds-motion-exit-*`, which is deliberately FASTER than its entrance.
193
193
 
194
194
  ### Transition properties, not `all`
195
195
 
196
- Measured: `background-color` (20), `transform` (12), `color` (10), `border-color` (5),
196
+ In this library: `background-color` (20), `transform` (12), `color` (10), `border-color` (5),
197
197
  `opacity` (2). Nothing in the library transitions `all`, and only three places transition a
198
198
  `width` — animating a layout property costs a reflow per frame. Prefer `transform` and
199
199
  `opacity`; if you find yourself animating `height`, the answer is usually a `grid-template-rows`
@@ -219,11 +219,11 @@ anything with an exit.
219
219
 
220
220
  ### Labels are sentence case
221
221
 
222
- Measured: of 57 multi-word labels across the docs' own specimens, **45 are sentence case**. The
222
+ Most multi-word labels in this system already are, and the
223
223
  apparent exceptions are not exceptions — they are acronyms and notation the case rule does not
224
224
  touch (`Site URL`, `Project ID`, `Date (en-US, Sunday-first)`). So: capitalise the first word
225
- and whatever is a proper noun or an acronym, and nothing else. `Asset register`, not
226
- `Asset Register`. No trailing colon: the field's shape already says a value follows.
225
+ and whatever is a proper noun or an acronym, and nothing else. `Order history`, not
226
+ `Order History`. No trailing colon: the field's shape already says a value follows.
227
227
 
228
228
  Mark the exception, not the rule. `required` is the default expectation in most forms, so
229
229
  `ds-input` and its siblings carry an `optional` input that renders "(optional)" rather than
@@ -238,19 +238,19 @@ told the user nothing in four different ways. The pattern's own worked examples
238
238
 
239
239
  | Variant | Title says the SITUATION | Body says the NEXT STEP or the CAUSE |
240
240
  | --- | --- | --- |
241
- | `none` | "No asset allocated yet" | "Pick from the asset register to start building this Sub-record." |
242
- | `error` | "Couldn't load resource allocations" | "Network error — the request timed out after 30 seconds." |
243
- | `locked` | "You don't have access to this Logistics plan" | "Logistics plans are restricted to Logistics and Producer roles. Ask Alex Park or your team lead." |
241
+ | `none` | "No items in this order yet" | "Add a product from the catalogue to start building it." |
242
+ | `error` | "Couldn't load the order lines" | "Network error — the request timed out after 30 seconds." |
243
+ | `locked` | "You don't have access to this warehouse" | "Warehouses are restricted to the Operations and Manager roles. Ask your workspace admin." |
244
244
 
245
- Three things to copy from those: the title is a **statement, not a label** — "No asset
246
- allocated yet", never "Empty"; the error body names a **concrete** cause with the number in it,
245
+ Three things to copy from those: the title is a **statement, not a label** — "No items
246
+ in this order yet", never "Empty"; the error body names a **concrete** cause with the number in it,
247
247
  not "Something went wrong"; and the locked body names **who can unblock them**, because a
248
248
  permission wall with no next step is a dead end.
249
249
 
250
250
  ### A message says what happened, what follows, and what to do
251
251
 
252
- The library holds itself to this. All 15 messages it prints are tagged with the component that
253
- printed them (`[ds-table] …`), 7 of 15 state the consequence with a plain "so", and 5 name the
252
+ The library holds itself to this. Every message it prints is tagged with the component that
253
+ printed it (`[ds-table] …`), states the consequence, and where there is one names the
254
254
  fix outright:
255
255
 
256
256
  > `[ds-table] lazy needs virtualScroll: without a window there is no range to fetch, so every
@@ -309,8 +309,8 @@ internals.
309
309
  ## 8. Where the rest lives
310
310
 
311
311
  The decisions this file does NOT make are the ones about which COMPONENT to reach for, and they
312
- have their own home: ds-docs `Practice → Do / Don't` (modal vs drawer, button hierarchy, table
312
+ have their own home: the documentation site's `Practice → Do / Don't` (modal vs drawer, button hierarchy, table
313
313
  density, badge proliferation, status without colour, tooltips vs banners) and
314
314
  `Practice → Token Discipline` (the token-vs-literal rule, in worked pairs). The component
315
- inventory is `components.md`; the generated Component API and token reference in ds-docs are
315
+ inventory is `components.md`; the generated Component API and token reference on the documentation site are
316
316
  extracted from source on every build and are the only surfaces that cannot go stale.