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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (82) hide show
  1. package/CHANGELOG.md +342 -31
  2. package/components.md +27 -12
  3. package/design-system.md +135 -1
  4. package/docs/agent/INDEX.md +98 -0
  5. package/docs/agent/domain/ds-w3w.md +10 -0
  6. package/docs/agent/feedback/ds-alert.md +9 -0
  7. package/docs/agent/feedback/ds-avatar-group.md +7 -0
  8. package/docs/agent/feedback/ds-avatar.md +6 -0
  9. package/docs/agent/feedback/ds-badge.md +7 -0
  10. package/docs/agent/feedback/ds-banner.md +10 -0
  11. package/docs/agent/feedback/ds-empty-state.md +7 -0
  12. package/docs/agent/feedback/ds-progress.md +7 -0
  13. package/docs/agent/feedback/ds-skeleton.md +6 -0
  14. package/docs/agent/feedback/ds-spinner.md +6 -0
  15. package/docs/agent/feedback/ds-stat.md +7 -0
  16. package/docs/agent/feedback/ds-status-dot.md +6 -0
  17. package/docs/agent/feedback/ds-tag.md +8 -0
  18. package/docs/agent/feedback/ds-toast.md +12 -0
  19. package/docs/agent/forms/ds-autocomplete.md +9 -0
  20. package/docs/agent/forms/ds-button.md +14 -0
  21. package/docs/agent/forms/ds-checkbox.md +6 -0
  22. package/docs/agent/forms/ds-date-picker.md +7 -0
  23. package/docs/agent/forms/ds-dropzone.md +10 -0
  24. package/docs/agent/forms/ds-icon-button.md +10 -0
  25. package/docs/agent/forms/ds-input.md +22 -0
  26. package/docs/agent/forms/ds-multi-select.md +6 -0
  27. package/docs/agent/forms/ds-number-stepper.md +8 -0
  28. package/docs/agent/forms/ds-radio.md +6 -0
  29. package/docs/agent/forms/ds-search.md +10 -0
  30. package/docs/agent/forms/ds-select.md +7 -0
  31. package/docs/agent/forms/ds-switch.md +6 -0
  32. package/docs/agent/forms/ds-textarea.md +9 -0
  33. package/docs/agent/forms/the-picker-family-ds-select-ds-multi-select-ds-autocomplete.md +21 -0
  34. package/docs/agent/foundations/global-helper-classes.md +18 -0
  35. package/docs/agent/foundations/grid.md +35 -0
  36. package/docs/agent/foundations/tokens.md +47 -0
  37. package/docs/agent/navigation/ds-app-layout.md +10 -0
  38. package/docs/agent/navigation/ds-auth-layout.md +9 -0
  39. package/docs/agent/navigation/ds-breadcrumbs.md +7 -0
  40. package/docs/agent/navigation/ds-divider.md +9 -0
  41. package/docs/agent/navigation/ds-page-footer.md +7 -0
  42. package/docs/agent/navigation/ds-page-header.md +8 -0
  43. package/docs/agent/navigation/ds-pagination.md +7 -0
  44. package/docs/agent/navigation/ds-sidenav-group.md +8 -0
  45. package/docs/agent/navigation/ds-sidenav-item.md +9 -0
  46. package/docs/agent/navigation/ds-sidenav.md +9 -0
  47. package/docs/agent/navigation/ds-stepper.md +6 -0
  48. package/docs/agent/navigation/ds-tabs.md +9 -0
  49. package/docs/agent/navigation/ds-topbar.md +8 -0
  50. package/docs/agent/overlays/ds-bottom-sheet.md +9 -0
  51. package/docs/agent/overlays/ds-drawer.md +9 -0
  52. package/docs/agent/overlays/ds-menu.md +8 -0
  53. package/docs/agent/overlays/ds-modal-card.md +6 -0
  54. package/docs/agent/overlays/ds-modal.md +8 -0
  55. package/docs/agent/overlays/ds-popover.md +6 -0
  56. package/docs/agent/overlays/ds-tooltip.md +8 -0
  57. package/docs/agent/platform/breadcrumbs-service.md +30 -0
  58. package/docs/agent/platform/ds-config.md +60 -0
  59. package/docs/agent/platform/ds-icon-registry.md +23 -0
  60. package/docs/agent/platform/toast-service.md +19 -0
  61. package/docs/agent/surfaces/ds-accordion.md +8 -0
  62. package/docs/agent/surfaces/ds-card.md +10 -0
  63. package/docs/agent/tables/ds-table.md +15 -0
  64. package/fesm2022/ids-group-ltd-ids-design-system.mjs +1530 -865
  65. package/fesm2022/ids-group-ltd-ids-design-system.mjs.map +1 -1
  66. package/migrations/0.11.0.json +0 -45
  67. package/migrations/0.11.1.json +9 -35
  68. package/migrations/0.11.2.json +158 -0
  69. package/migrations/0.11.3.json +152 -0
  70. package/migrations/0.2.0.json +17 -5
  71. package/migrations/0.4.0.json +1 -1
  72. package/migrations/0.7.1.json +3 -3
  73. package/migrations/0.9.0.json +2 -2
  74. package/package.json +1 -1
  75. package/styles/_dropdown-overlay.scss +50 -38
  76. package/styles/_ds-color.scss +31 -12
  77. package/styles/_tokens-charts.scss +2 -3
  78. package/styles/_tokens.scss +159 -322
  79. package/themes/README.md +35 -4
  80. package/themes/_base-palette.scss +35 -76
  81. package/themes/_semantic.scss +5 -2
  82. package/types/ids-group-ltd-ids-design-system.d.ts +424 -188
@@ -0,0 +1,8 @@
1
+ <!-- GENERATED by tools/split-agent-catalogue.mjs from components.md. Do not edit. -->
2
+ # `<ds-page-header>` — `PageHeaderComponent`
3
+
4
+ Group: Layout & navigation
5
+
6
+ Inputs: `eyebrow: string = ''`, `title: required string`, `subtitle: string = ''`, `compact: boolean = false`, `divider: boolean = false`, `metaDivider: boolean = false`
7
+ 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)
8
+ Tokens: `--ds-page-header-eyebrow-text-color`, `--ds-page-header-title-text-color`, `--ds-page-header-subtitle-text-color`, `--ds-page-header-meta-text-color`, `--ds-page-header-meta-icon-color`, `--ds-page-header-divider`, `--ds-page-header-title-fs` (default `--font-size-h3`; `compact` flips to `--font-size-h4`). The page-header does NOT own its bottom gap — the parent page `:host` owns spacing via `display: flex; flex-direction: column; gap: var(--space-4)`.
@@ -0,0 +1,7 @@
1
+ <!-- GENERATED by tools/split-agent-catalogue.mjs from components.md. Do not edit. -->
2
+ # `<ds-pagination>` — `PaginationComponent`
3
+
4
+ Group: Layout & navigation
5
+
6
+ Inputs: `total: required number`, `pageSize: model<number> = 10`, `currentPage: model<number> = 1`, `pageSizeOptions: number[] = [10, 25, 50, 100]`, `showLabel: boolean = true`
7
+ Outputs: `(currentPageChange): number`, `(pageSizeChange): number`
@@ -0,0 +1,8 @@
1
+ <!-- GENERATED by tools/split-agent-catalogue.mjs from components.md. Do not edit. -->
2
+ # `<ds-sidenav-group>` — `SidenavGroupComponent`
3
+
4
+ Group: Layout & navigation
5
+
6
+ Inputs: `label: string = ''`, `icon: IconName | null = null`, `expandable: boolean = false`, `expanded: model<boolean> = true`
7
+ Content slots: default (items); `[ds-group-icon]` (custom group icon when not using a DS IconName)
8
+ When `expandable=true` renders header button with toggle + caret; collapses body when not expanded.
@@ -0,0 +1,9 @@
1
+ <!-- GENERATED by tools/split-agent-catalogue.mjs from components.md. Do not edit. -->
2
+ # `<ds-sidenav-item>` — `SidenavItemComponent`
3
+
4
+ Group: Layout & navigation
5
+
6
+ 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`)
7
+ Content slots: `[icon]` (custom icon when not using a DS IconName), `[trailing]` (right-aligned chrome — badges, indicators, kbd shortcuts)
8
+ **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.
9
+ 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`
@@ -0,0 +1,9 @@
1
+ <!-- GENERATED by tools/split-agent-catalogue.mjs from components.md. Do not edit. -->
2
+ # `<ds-sidenav>` — `SidenavComponent`
3
+
4
+ Group: Layout & navigation
5
+
6
+ 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`
7
+ Content: default slot for groups/items + custom brand/footer rows
8
+ **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.
9
+ 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`
@@ -0,0 +1,6 @@
1
+ <!-- GENERATED by tools/split-agent-catalogue.mjs from components.md. Do not edit. -->
2
+ # `<ds-stepper>` — `StepperComponent`
3
+
4
+ Group: Layout & navigation
5
+
6
+ Inputs: `steps: readonly string[] = []`, `current: number = 0`. Horizontal step indicator with done/active/upcoming nodes.
@@ -0,0 +1,9 @@
1
+ <!-- GENERATED by tools/split-agent-catalogue.mjs from components.md. Do not edit. -->
2
+ # `<ds-tabs>` + `<ds-tab>` — `TabsComponent`, `TabComponent`
3
+
4
+ Group: Layout & navigation
5
+
6
+ Container holds `<ds-tab label="…">` children.
7
+ Tabs inputs: `selectedIndex: model<number> = 0`, `variant: 'line' | 'pills' = 'line'`
8
+ Tab inputs: `label: required string`, `icon: IconName | null = null`, `count: number | null = null`, `disabled: boolean = false`. The tab's projected content renders in the active panel.
9
+ Tokens: `--ds-tab-label-color`, `--ds-tab-label-color-hover`, `--ds-tab-label-color-active`, `--ds-tab-indicator-color`, `--ds-tab-indicator-width`, `--ds-tab-pad-x`, `--ds-tab-pad-y`, `--ds-tabs-divider`, `--ds-tabs-pills-bg-color`, `--ds-tab-pill-bg-color-hover` (inactive hover, defaults to `var(--primary-subtle)`), `--ds-tab-pill-bg-color-active` (defaults to `var(--surface-default)` — elevated card), `--ds-tab-pill-bg-color-active-hover` (defaults to `var(--primary-subtle)`), `--ds-tab-pill-label-color-active` (defaults to `var(--primary-strong)`), `--ds-tab-pill-radius` (defaults to `var(--radius-md)` — same as buttons/inputs; override per-instance to `var(--radius-pill)` for fully round pills).
@@ -0,0 +1,8 @@
1
+ <!-- GENERATED by tools/split-agent-catalogue.mjs from components.md. Do not edit. -->
2
+ # `<ds-topbar>` — `TopBarComponent`
3
+
4
+ Group: Layout & navigation
5
+
6
+ No inputs.
7
+ Content slots: `[title]`, `[breadcrumbs]`, `[search]`, `[actions]`. Sits at `--topbar-h` height.
8
+ 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.
@@ -0,0 +1,9 @@
1
+ <!-- GENERATED by tools/split-agent-catalogue.mjs from components.md. Do not edit. -->
2
+ # `<ds-bottom-sheet>` — `BottomSheetComponent`
3
+
4
+ Group: Overlay
5
+
6
+ Mobile-first panel anchored to the bottom edge (touch equivalent of drawer/modal). Drag-down on the grab strip, scrim tap, or Esc dismisses; body scroll locks while open; caps width + centres on wide viewports.
7
+ Inputs: `open: model<boolean> = false`, `title: string = ''`
8
+ Output: `(closed): void`
9
+ Content slots: default (body), `[actions]` (footer).
@@ -0,0 +1,9 @@
1
+ <!-- GENERATED by tools/split-agent-catalogue.mjs from components.md. Do not edit. -->
2
+ # `<ds-drawer>` — `DrawerComponent`
3
+
4
+ Group: Overlay
5
+
6
+ Side panel (no `side` input — always anchored right).
7
+ Inputs: `open: model<boolean> = false`, `size: 'md' | 'lg' = 'md'`, `title: string = ''`
8
+ Output: `(closed): void`
9
+ Content slots: `[drawer-body]`, `[drawer-footer]`.
@@ -0,0 +1,8 @@
1
+ <!-- GENERATED by tools/split-agent-catalogue.mjs from components.md. Do not edit. -->
2
+ # `<ds-menu>` + `<ds-menu-item>` — `MenuComponent`, `MenuItemComponent`
3
+
4
+ Group: Overlay
5
+
6
+ Menu is a container. Item inputs: `icon: IconName | null = null`, `disabled: boolean = false`, `danger: boolean = false`. Output: `(pressed): MouseEvent`. Content: label text; supports `[icon]` content slot for custom icons.
7
+
8
+ ---
@@ -0,0 +1,6 @@
1
+ <!-- GENERATED by tools/split-agent-catalogue.mjs from components.md. Do not edit. -->
2
+ # `<ds-modal-card>` — `ModalCardComponent`
3
+
4
+ Group: Overlay
5
+
6
+ The visual card the `<ds-modal>` host renders inside its backdrop. Exposed as a separate selector for cases where you need custom positioning (e.g. inside a drawer) without re-implementing the dialog chrome. Inputs: `size`, `danger`, `title: required`, `showClose: boolean = true`. Output: `(closed)`. Slots: `[body]`, `[impact]`, `[actions]`.
@@ -0,0 +1,8 @@
1
+ <!-- GENERATED by tools/split-agent-catalogue.mjs from components.md. Do not edit. -->
2
+ # `<ds-modal>` — `ModalComponent`
3
+
4
+ Group: Overlay
5
+
6
+ Inputs: `open: model<boolean> = false`, `size: 'sm' | 'md' | 'lg' = 'md'`, `danger: boolean = false`, `title: required string`
7
+ Output: `(closed): void` — fires on backdrop click, close button, or `open` being set to false. `(confirmed)` is declared on the component but no internal handler emits it; treat it as not implemented and emit confirmation from the consumer-side action button instead.
8
+ Content slots: `[body]`, `[impact]` (highlighted strip under the body for destructive consequences), `[actions]` (footer button row). Backdrop click + close button close the dialog.
@@ -0,0 +1,6 @@
1
+ <!-- GENERATED by tools/split-agent-catalogue.mjs from components.md. Do not edit. -->
2
+ # `<ds-popover>` — `PopoverComponent`
3
+
4
+ Group: Overlay
5
+
6
+ Floating panel anchored to a trigger via CDK overlay. Input: `align: 'start' | 'end' = 'start'` — controls overlay alignment relative to the trigger (`start` = left-edge anchored, `end` = right-edge anchored). Open via the component method `toggle(triggerElement)` (or `close()`), and project the panel body inside a `<ng-template #panel>` (read internally via `viewChild`).
@@ -0,0 +1,8 @@
1
+ <!-- GENERATED by tools/split-agent-catalogue.mjs from components.md. Do not edit. -->
2
+ # `[dsTooltip]` — `TooltipDirective`
3
+
4
+ Group: Overlay
5
+
6
+ Attribute directive. Apply to any focusable element.
7
+ Inputs: `dsTooltip: string = ''` (the text; empty disables), `dsTooltipPlacement: 'top' | 'bottom' | 'left' | 'right' = 'top'`, `dsTooltipDelay: number = 120` (ms)
8
+ Renders `<ds-tooltip-panel>` via CDK overlay on hover / focus; hides on leave / blur.
@@ -0,0 +1,30 @@
1
+ <!-- GENERATED by tools/split-agent-catalogue.mjs from components.md. Do not edit. -->
2
+ # `BreadcrumbsService`
3
+
4
+ Section: Services
5
+
6
+ `@Injectable({ providedIn: 'root' })`. Signal-based state primitive — apps push crumbs, `<ds-breadcrumbs>` reads from here when its `[items]` input is omitted.
7
+
8
+ ```ts
9
+ private readonly crumbs = inject(BreadcrumbsService);
10
+ // signal-readable items
11
+ this.crumbs.items() // -> BreadcrumbItem[]
12
+ // mutators
13
+ this.crumbs.set([{ label: 'Overview', href: '/workspaces' }, { label: 'Detail' }]);
14
+ this.crumbs.push({ label: 'Extra' });
15
+ this.crumbs.replaceLast({ label: 'Renamed' });
16
+ this.crumbs.pop();
17
+ this.crumbs.clear();
18
+ ```
19
+
20
+ **Two ways to feed it:**
21
+
22
+ 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).
23
+
24
+ 2. **Route-driven** — annotate routes with `data.breadcrumb` and run a Router→Service bridge once at app bootstrap. `breadcrumb` accepts:
25
+ - `string` → `{ label: string, href: <built-from-url> }`
26
+ - `BreadcrumbItem`
27
+ - `BreadcrumbItem[]`
28
+ - `(snap: ActivatedRouteSnapshot) => string | BreadcrumbItem | BreadcrumbItem[]`
29
+
30
+ Mix-and-match: route bridge sets a base trail, page effect overrides with a richer version when its data is ready.
@@ -0,0 +1,60 @@
1
+ <!-- GENERATED by tools/split-agent-catalogue.mjs from components.md. Do not edit. -->
2
+ # `DS_CONFIG` / `provideDsConfig(config)`
3
+
4
+ Section: App config
5
+
6
+ Inject `DS_CONFIG` token (default factory returns `{}`) to set library-wide defaults that consumer-level component inputs can still override.
7
+
8
+ ```ts
9
+ import { provideDsConfig } from '@ids-group-ltd/ids-design-system';
10
+
11
+ bootstrapApplication(AppComponent, {
12
+ providers: [
13
+ provideDsConfig({
14
+ breadcrumbs: { separator: 'chevronRight', clickable: true },
15
+ }),
16
+ ],
17
+ });
18
+ ```
19
+
20
+ `DsConfig` shape (the exported `DsConfig` type is the full contract):
21
+
22
+ Twelve sections. The exported `DsConfig` type is the source of truth — each key carries its own
23
+ doc comment there, including why it is an app-level decision at all.
24
+
25
+ ```ts
26
+ interface DsConfig {
27
+ field?: {
28
+ reserveMessage?: boolean; // keep a message line of space when empty
29
+ errorMessages?: Record<string, string>; // fallback text per validation-error kind
30
+ stateIcons?: false | { // the message line's leading glyph, per state
31
+ error?: IconName | false; // default: `error`
32
+ warning?: IconName | false; // default: `warn`
33
+ success?: IconName | false; // default: `success`
34
+ hint?: IconName | false; // default: NONE — hint is not a state
35
+ };
36
+ };
37
+ control?: { size?: DsSize }; // every control on the field-height contract
38
+ card?: { elevation?: CardElevation; padding?: CardPadding };
39
+ table?: { stickyScrollbar?: boolean; bordered?: boolean };
40
+ modal?: { dividers?: boolean }; // reaches a ModalService confirm, which has no host to bind
41
+ icon?: { size?: number };
42
+ badge?: { withDot?: boolean };
43
+ breadcrumbs?: { separator?: IconName; clickable?: boolean };
44
+ datePicker?: { locale?: string; dateFormat?: string; firstDayOfWeek?: number };
45
+ timePicker?: { format?: '24h' | '12h' };
46
+ avatar?: { initials?: (name: string) => string };
47
+ brand?: { name?: string; logoLetter?: string; tagline?: string };
48
+ }
49
+ ```
50
+
51
+ Precedence is always: **explicit input → config → component default.** A component publishes what it
52
+ resolved as a public readback (`sizeResolved()`, `dividersResolved()`, …) so a host can read the
53
+ effective value rather than re-deriving the chain.
54
+
55
+ **Call `provideDsConfig` once per injector.** Two calls in the same `providers` array do NOT merge —
56
+ both resolve their parent with `skipSelf`, so the later wins and the earlier is silently lost. Merging
57
+ happens across injector LEVELS: a route or component inherits the app's config and overrides only the
58
+ keys it names.
59
+
60
+ ---
@@ -0,0 +1,23 @@
1
+ <!-- GENERATED by tools/split-agent-catalogue.mjs from components.md. Do not edit. -->
2
+ # `DS_ICON_REGISTRY` / `provideDsIcons(icons)`
3
+
4
+ Section: Icons
5
+
6
+ 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).
7
+
8
+ ```ts
9
+ import { provideDsIcons } from '@ids-group-ltd/ids-design-system';
10
+
11
+ bootstrapApplication(AppComponent, {
12
+ providers: [
13
+ provideDsIcons({
14
+ 'cloud-upload': '<path d="M7 18a5 5 0 1 1 .9-9.9 …"/><path d="M12 21V11"/>',
15
+ shield: '<path d="M12 3 4 6v6c0 5 …"/>',
16
+ }),
17
+ ],
18
+ });
19
+ ```
20
+
21
+ Lookup order: built-in `ICONS` first, then the consumer registry. Names that collide with built-ins are ignored — fork the DS source if you need to override a built-in.
22
+
23
+ ---
@@ -0,0 +1,19 @@
1
+ <!-- GENERATED by tools/split-agent-catalogue.mjs from components.md. Do not edit. -->
2
+ # `ToastService`
3
+
4
+ Section: Services
5
+
6
+ `@Injectable({ providedIn: 'root' })`. Inject and call:
7
+ - `show(opts: ToastOptions): ToastRef` — `{ title?, body, variant?: 'info' | 'success' | 'warning' | 'error' | 'loading', dismissible?, icon?, action?: ToastAction, durationMs? = 5000 }`. Returns `{ id, dismiss() }`. `durationMs: 0` (and any negative) means it never auto-dismisses, and it is counted from the moment the toast becomes VISIBLE, not from the call — a toast queued behind `maxVisible` keeps its full time on screen. A `loading` toast is forced to 0 and discards a supplied `durationMs`.
8
+ - `promise<T>(source: Promise<T>, messages: ToastPromiseMessages): Promise<T>` — shows a `loading` toast, then patches it in place to `success` or `error` when `source` settles. Returns `source` itself, so an un-`catch`ed call still produces an unhandled rejection. The settled toast dismisses after a hard-coded 4s (success) or 6s (error), counted from the moment it becomes visible and not overridable; `dismissAll()` cancels it like any other.
9
+ - `dismissAll(): void`
10
+
11
+ Defaults are set with two injection tokens, NOT through `provideDsConfig`:
12
+ - `DS_TOAST_CONFIG` — `{ maxVisible?: number }`. Unset or `0` means unlimited; extras queue and appear as earlier ones dismiss.
13
+ - `DS_TOAST_POSITION` — `{ horizontalPosition?: 'left' | 'center' | 'right', verticalPosition?: 'top' | 'bottom', offset?: string }`. Defaults to `right` / `top` / `var(--space-6)`.
14
+
15
+ Both resolve **once, at the root injector**, when the service is first used. Providing either on a `Route` or a component has no effect, and the position cannot change after the first `show()`.
16
+
17
+ On first `show()` the service lazily creates a CDK overlay and mounts a `<ds-toast-region>` into it. **Do not place `<ds-toast-region>` yourself** — the service only ever talks to the instance it created, so a hand-placed one is an invisible empty box that never receives a toast, with no warning. It appears in the generated API table only because the extractor lists every exported component.
18
+
19
+ ---
@@ -0,0 +1,8 @@
1
+ <!-- GENERATED by tools/split-agent-catalogue.mjs from components.md. Do not edit. -->
2
+ # `<ds-accordion>` + `<ds-accordion-item>` — `AccordionComponent`, `AccordionItemComponent`
3
+
4
+ Group: Surfaces
5
+
6
+ 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).
7
+
8
+ ---
@@ -0,0 +1,10 @@
1
+ <!-- GENERATED by tools/split-agent-catalogue.mjs from components.md. Do not edit. -->
2
+ # `<ds-card>` — `CardComponent`
3
+
4
+ Group: Surfaces
5
+
6
+ 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`)
7
+ Output: `(pressed): MouseEvent` — fires only when `elevation="interactive"`
8
+ 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`
9
+ 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"`.
10
+ 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`.
@@ -0,0 +1,15 @@
1
+ <!-- GENERATED by tools/split-agent-catalogue.mjs from components.md. Do not edit. -->
2
+ # `<ds-table>` — `TableComponent<T extends { id: string }>`
3
+
4
+ Group: Tables
5
+
6
+ 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`
7
+ Outputs: `(rowClicked): T`, `(sortChange): SortChangeEvent` (`{ key, dir }`)
8
+ Column shape: `{ key: string, label: string, sortable?: boolean, align?: 'left' | 'right' | 'center', cell?: (row: T) => string }`
9
+ 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.
10
+ Cell templates: `<ng-template dsCellTemplate="<colKey>" let-row>…</ng-template>` — `row` is typed `unknown`, narrow via a helper method on the host.
11
+ Content slots: `[empty]` (rendered when `data.length === 0`), `[bulk-actions]` (rendered in the bulk action bar when `selectable && some selected`)
12
+ 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.
13
+ Tokens: `--ds-table-border: var(--border-default)`, `--ds-table-radius: var(--radius-md)`, `--ds-table-bg-color`, `--ds-table-head-text-color: var(--text-secondary)`, `--ds-table-head-bg-color: var(--surface-secondary)`, `--ds-table-head-fs: var(--font-size-xs)`, `--ds-table-row-hover-bg-color`, `--ds-table-row-selected-bg-color`, `--ds-table-divider`, `--ds-table-sort-active-icon-color`, `--ds-table-cell-pad-x/y`. (Renamed 2026-06: `--ds-table-header-*` → `--ds-table-head-*`, matching the tokens reference.)
14
+
15
+ ---