@ids-group-ltd/ids-design-system 0.10.3 → 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.
- package/CHANGELOG.md +1376 -904
- package/components.md +61 -30
- package/design-system.md +18 -18
- package/fesm2022/ids-group-ltd-ids-design-system.mjs +992 -486
- package/fesm2022/ids-group-ltd-ids-design-system.mjs.map +1 -1
- package/migrations/0.1.0.json +2 -1
- package/migrations/0.10.0.json +219 -42
- package/migrations/0.10.1.json +50 -13
- package/migrations/0.10.2.json +90 -24
- package/migrations/0.10.3.json +22 -5
- package/migrations/0.11.0.json +216 -0
- package/migrations/0.11.1.json +305 -0
- package/migrations/0.2.0.json +22 -9
- package/migrations/0.2.1.json +2 -1
- package/migrations/0.2.2.json +3 -2
- package/migrations/0.3.0.json +16 -10
- package/migrations/0.4.0.json +38 -14
- package/migrations/0.5.0.json +49 -25
- package/migrations/0.5.1/badge-statuses.md +1 -3
- package/migrations/0.5.1.json +75 -33
- package/migrations/0.6.0.json +6 -2
- package/migrations/0.6.1.json +19 -1
- package/migrations/0.6.2.json +3 -1
- package/migrations/0.6.3.json +13 -4
- package/migrations/0.7.0.json +45 -26
- package/migrations/0.7.1.json +58 -20
- package/migrations/0.8.0.json +53 -15
- package/migrations/0.9.0.json +147 -27
- package/migrations/0.9.1.json +4 -3
- package/migrations/README.md +34 -52
- package/package.json +2 -1
- package/styles/_dropdown-overlay.scss +35 -13
- package/styles/_ds-color.scss +3 -3
- package/styles/_field-box.scss +2 -6
- package/styles/_field-label.scss +5 -10
- package/styles/_field-state.scss +3 -2
- package/styles/_focus.scss +0 -2
- package/styles/_layout-utils.scss +2 -2
- package/styles/_link.scss +1 -2
- package/styles/_overlay-motion.scss +2 -4
- package/styles/_press.scss +3 -5
- package/styles/_reset.scss +0 -1
- package/styles/_scrollbar.scss +1 -3
- package/styles/_status.scss +1 -2
- package/styles/_surface-motion.scss +3 -4
- package/styles/_text-clip.scss +1 -1
- package/styles/_theme-activation.scss +1 -1
- package/styles/_tokens-charts.scss +1 -3
- package/styles/_tokens.scss +4 -3
- package/styles/_typography.scss +2 -2
- package/themes/README.md +3 -3
- package/themes/_base-palette.scss +2 -2
- package/themes/_semantic.scss +2 -2
- package/themes/dark/_palette.scss +1 -2
- package/themes/light/_palette.scss +1 -1
- package/themes/light/_theme.scss +1 -1
- package/types/ids-group-ltd-ids-design-system.d.ts +403 -108
- package/migrations/AUTHORING.md +0 -273
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:**
|
|
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
|
|
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 '
|
|
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 (
|
|
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 '
|
|
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
|
|
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
|
|
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**
|
|
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
|
|
|
@@ -146,15 +147,19 @@ text rather than a state. Retune app-wide with `DS_CONFIG.field.stateIcons` (per
|
|
|
146
147
|
is not a validated field; where a search needs a label or an error line, use `ds-input`.
|
|
147
148
|
|
|
148
149
|
#### `<ds-button>` — `ButtonComponent`
|
|
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`.
|
|
150
|
-
Axis meaning: **variant is loudness** (solid > tonal > outline/ghost/text), **color is hue** — every pair renders, and the UX-discouraged ones dev-warn
|
|
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`.
|
|
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
|
-
Content slots: default (label / leading or trailing icon). For icon-only actions use `<ds-icon-button>`.
|
|
153
|
-
|
|
153
|
+
Content slots: default (label / leading or trailing icon), plus `[dsButtonSubtext]` for a projected second line. For icon-only actions use `<ds-icon-button>`.
|
|
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:
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
154
159
|
|
|
155
160
|
#### `<ds-icon-button>` — `IconButtonComponent`
|
|
156
161
|
Icon-only action with its own taxonomy, distinct from `ds-button`. `ariaLabel` is required (icon-only must be labelled for a11y).
|
|
157
|
-
Inputs: `icon: required IconName`, `ariaLabel: required string`, `variant: IconButtonVariant = 'standard'` (`'standard' | 'filled' | 'tonal' | 'outlined'`), `size: IconButtonSize = 'md'` (`'sm' | 'md' | 'lg'` = 32/40/48), `type: 'button' | 'submit' | 'reset' = 'button'`, `disabled: boolean = false`, `selected: boolean = false` (toggle — sets `aria-pressed`)
|
|
162
|
+
Inputs: `icon: required IconName`, `ariaLabel: required string`, `ariaDescribedBy: string | null = null` (point at text the page already shows — e.g. why the action is refused; icon-only leaves no room for a second line, which is why there is deliberately no `disabledReason` here), `variant: IconButtonVariant = 'standard'` (`'standard' | 'filled' | 'tonal' | 'outlined'`), `size: IconButtonSize = 'md'` (`'sm' | 'md' | 'lg'` = 32/40/48), `type: 'button' | 'submit' | 'reset' = 'button'`, `disabled: boolean = false`, `selected: boolean = false` (toggle — sets `aria-pressed`)
|
|
158
163
|
Output: `(pressed): MouseEvent` — fires when not disabled
|
|
159
164
|
Variant emphasis: `standard` chromeless (hover-reveal) · `filled` `--primary` · `tonal` `--primary-muted` · `outlined` bordered. `selected` renders the pressed/active fill.
|
|
160
165
|
Tokens: `--ds-icon-button-bg-color`, `--ds-icon-button-icon-color`, `--ds-icon-button-border`, `--ds-icon-button-bg-color-hover`, `--ds-icon-button-bg-color-active`, `--ds-icon-button-icon-color-hover`, `--ds-icon-button-radius`, `--ds-icon-button-focus-shadow`. `filled`/`selected` derive hover/active from the resolved bg, `standard`/`tonal`/`outlined` keep explicit ramp defaults.
|
|
@@ -198,21 +203,43 @@ Inputs: `checked: model<boolean>`, `disabled: boolean = false`, `name: string =
|
|
|
198
203
|
#### `<ds-switch>` — `SwitchComponent`
|
|
199
204
|
Inputs: `checked: model<boolean>`, `disabled: boolean = false`, `name: string | null = null`, `variant: 'default' | 'success' | 'error' = 'default'`, `inputId: string | null = null`
|
|
200
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
|
+
|
|
201
224
|
#### `<ds-select>` — `SelectComponent`
|
|
202
|
-
Inputs: `value: model<string>`, `options: SelectItem[]
|
|
203
|
-
|
|
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`
|
|
204
230
|
|
|
205
|
-
#### `<ds-
|
|
206
|
-
|
|
207
|
-
Inputs: `options: readonly
|
|
208
|
-
|
|
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.
|
|
209
236
|
|
|
210
237
|
#### `<ds-search>` — `SearchComponent`
|
|
211
238
|
Pre-styled search input with built-in icon. A form control, but not a field: no label, no message row.
|
|
212
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)
|
|
213
240
|
Output: `(submitted): string` — emits the current value on Enter / form submit
|
|
214
241
|
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
|
|
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.
|
|
216
243
|
|
|
217
244
|
#### `<ds-date-picker>` — `DatePickerComponent`
|
|
218
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`
|
|
@@ -282,8 +309,9 @@ The companion `<ds-toast-region>` lives inside the `ToastService` (see Services)
|
|
|
282
309
|
### Layout & navigation
|
|
283
310
|
|
|
284
311
|
#### `<ds-sidenav>` — `SidenavComponent`
|
|
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)
|
|
312
|
+
Inputs: `collapsed: boolean = false`, `brand: string | null = null` (renders a letter mark + name; omit to project custom content, or set `DS_CONFIG.brand.name`), `logoLetter: string | null = null` (the mark's glyph; derived from `brand` when unset), `rail: boolean = true` (whether an active item draws its edge marker — turn it off here rather than painting `--ds-sidenav-item-rail` transparent), `brandRoute: string | readonly unknown[] | null = null`, `brandLinkLabel: string | null = null`
|
|
286
313
|
Content: default slot for groups/items + custom brand/footer rows
|
|
314
|
+
**The brand row leads home only if you say so.** `brandRoute` turns the mark + wordmark into one link; unset, the row stays a plain block. A logo that goes nowhere should not be a link, and whether a mark is a way home is an app's decision, not the DS's — so this is opt-in, like every other new capability here. The link announces itself as `"<brand>, home"` because a wordmark alone does not say where it goes; `brandLinkLabel` overrides that. Router targets only, and `RouterLink` is instantiated only inside the `@if`, so an app with no router provided still renders the sidenav. A collapse toggle projected into the row stays OUTSIDE the link — one control never nests inside another.
|
|
287
315
|
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`
|
|
288
316
|
|
|
289
317
|
#### `<ds-sidenav-group>` — `SidenavGroupComponent`
|
|
@@ -294,12 +322,13 @@ When `expandable=true` renders header button with toggle + caret; collapses body
|
|
|
294
322
|
#### `<ds-sidenav-item>` — `SidenavItemComponent`
|
|
295
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`)
|
|
296
324
|
Content slots: `[icon]` (custom icon when not using a DS IconName), `[trailing]` (right-aligned chrome — badges, indicators, kbd shortcuts)
|
|
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.
|
|
297
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`
|
|
298
327
|
|
|
299
328
|
#### `<ds-topbar>` — `TopBarComponent`
|
|
300
329
|
No inputs.
|
|
301
330
|
Content slots: `[title]`, `[breadcrumbs]`, `[search]`, `[actions]`. Sits at `--topbar-h` height.
|
|
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.
|
|
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.
|
|
303
332
|
|
|
304
333
|
#### `<ds-app-layout>` — `AppLayoutComponent`
|
|
305
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'`
|
|
@@ -351,8 +380,9 @@ Content: label text (when `variant="label"`).
|
|
|
351
380
|
#### `<ds-card>` — `CardComponent`
|
|
352
381
|
Inputs: `elevation: 'flat' | 'raised' | 'hover' | 'interactive' = 'flat'`, `padding: 'none' | 'sm' | 'md' | 'lg' | null = null` (when `null`, no `padding-*` class is applied and the consumer controls padding via own CSS or `--ds-card-pad`)
|
|
353
382
|
Output: `(pressed): MouseEvent` — fires only when `elevation="interactive"`
|
|
354
|
-
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`
|
|
355
|
-
|
|
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`
|
|
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"`.
|
|
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`.
|
|
356
386
|
|
|
357
387
|
#### `<ds-accordion>` + `<ds-accordion-item>` — `AccordionComponent`, `AccordionItemComponent`
|
|
358
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).
|
|
@@ -405,6 +435,7 @@ Selection is communicated via the `value` model. Keyboard: ArrowUp/Down, Enter/S
|
|
|
405
435
|
Inputs: `data: required readonly T[]`, `columns: required readonly TableColumn<T>[]`, `selectable: boolean = false`, `bordered: boolean = false` (opt-in outer border + radius; off by default so tables flush inside `<ds-card padding="none">` don't double-border), `loading: false | 'skeleton' | 'overlay' = false`, `stickyHeader: boolean = true`, `selectedIds: model<Set<string>>`, `sortKey: model<string | null>`, `sortDir: model<SortDir>` (`'asc' | 'desc' | null`), `skeletonRows: number = 5`
|
|
406
436
|
Outputs: `(rowClick): T`, `(sortChange): SortChangeEvent` (`{ key, dir }`)
|
|
407
437
|
Column shape: `{ key: string, label: string, sortable?: boolean, align?: 'left' | 'right' | 'center', cell?: (row: T) => string }`
|
|
438
|
+
Opening a row: give one column `link: (row) => <route target> | null` and its value renders as a real `<a>` — visible without hovering, in the tab order as a link, and Ctrl/Cmd-clickable, none of which a clickable `<tr>` can do. `null` for a row leaves that cell as plain text, so a partly-reachable list stays one column; external URLs go through a `[dsCellTemplate]` instead, since `link` takes Angular route targets only. It composes with `rowInteractive` (the link stops its click from reaching the row), but the two together cost **two tab stops per row** — on a long list prefer the link alone. `interactive: true` only tints a cell on row hover, which a keyboard or touch user never sees; prefer `link` wherever the row actually leads somewhere.
|
|
408
439
|
Cell templates: `<ng-template dsCellTemplate="<colKey>" let-row>…</ng-template>` — `row` is typed `unknown`, narrow via a helper method on the host.
|
|
409
440
|
Content slots: `[empty]` (rendered when `data.length === 0`), `[bulk-actions]` (rendered in the bulk action bar when `selectable && some selected`)
|
|
410
441
|
Loading modes: `'skeleton'` replaces rows with shimmer placeholders driven by the global `--skeleton-shimmer-x` keyframe; `'overlay'` keeps existing rows visible behind a translucent layer with a centred spinner.
|
|
@@ -429,14 +460,14 @@ All built-in icons (kebab-case where indicated, camelCase otherwise — DS uses
|
|
|
429
460
|
|
|
430
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`
|
|
431
462
|
|
|
432
|
-
|
|
463
|
+
Icons render inside `<svg viewBox="0 0 24 24" fill="none" stroke="currentColor">`. For consumer-side icons without forking DS, use `provideDsIcons(…)` below.
|
|
433
464
|
|
|
434
465
|
#### `DS_ICON_REGISTRY` / `provideDsIcons(icons)`
|
|
435
466
|
|
|
436
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).
|
|
437
468
|
|
|
438
469
|
```ts
|
|
439
|
-
import { provideDsIcons } from '
|
|
470
|
+
import { provideDsIcons } from '@ids-group-ltd/ids-design-system';
|
|
440
471
|
|
|
441
472
|
bootstrapApplication(AppComponent, {
|
|
442
473
|
providers: [
|
|
@@ -459,7 +490,7 @@ Lookup order: built-in `ICONS` first, then the consumer registry. Names that col
|
|
|
459
490
|
Inject `DS_CONFIG` token (default factory returns `{}`) to set library-wide defaults that consumer-level component inputs can still override.
|
|
460
491
|
|
|
461
492
|
```ts
|
|
462
|
-
import { provideDsConfig } from '
|
|
493
|
+
import { provideDsConfig } from '@ids-group-ltd/ids-design-system';
|
|
463
494
|
|
|
464
495
|
bootstrapApplication(AppComponent, {
|
|
465
496
|
providers: [
|
|
@@ -470,9 +501,9 @@ bootstrapApplication(AppComponent, {
|
|
|
470
501
|
});
|
|
471
502
|
```
|
|
472
503
|
|
|
473
|
-
`DsConfig` shape (
|
|
504
|
+
`DsConfig` shape (the exported `DsConfig` type is the full contract):
|
|
474
505
|
|
|
475
|
-
Twelve sections. `
|
|
506
|
+
Twelve sections. The exported `DsConfig` type is the source of truth — each key carries its own
|
|
476
507
|
doc comment there, including why it is an app-level decision at all.
|
|
477
508
|
|
|
478
509
|
```ts
|
|
@@ -534,7 +565,7 @@ this.crumbs.clear();
|
|
|
534
565
|
|
|
535
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).
|
|
536
567
|
|
|
537
|
-
2. **Route-driven** — annotate routes with `data.breadcrumb` and run a Router→Service bridge once at app bootstrap.
|
|
568
|
+
2. **Route-driven** — annotate routes with `data.breadcrumb` and run a Router→Service bridge once at app bootstrap. `breadcrumb` accepts:
|
|
538
569
|
- `string` → `{ label: string, href: <built-from-url> }`
|
|
539
570
|
- `BreadcrumbItem`
|
|
540
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
|
|
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
|
|
143
|
-
|
|
144
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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. `
|
|
226
|
-
`
|
|
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
|
|
242
|
-
| `error` | "Couldn't load
|
|
243
|
-
| `locked` | "You don't have access to this
|
|
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
|
|
246
|
-
|
|
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.
|
|
253
|
-
printed
|
|
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:
|
|
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
|
|
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.
|