@ids-group-ltd/ids-design-system 0.14.0 → 0.14.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (244) hide show
  1. package/CHANGELOG.md +573 -4
  2. package/components.md +103 -62
  3. package/design-system.md +2 -0
  4. package/docs/agent/INDEX.md +5 -4
  5. package/docs/agent/charts/column-series-component.md +1 -1
  6. package/docs/agent/charts/ds-bar-chart.md +4 -3
  7. package/docs/agent/charts/ds-chart.md +1 -1
  8. package/docs/agent/charts/ds-column-chart.md +3 -3
  9. package/docs/agent/charts/ds-config.md +3 -1
  10. package/docs/agent/charts/ds-funnel-chart.md +3 -3
  11. package/docs/agent/charts/ds-heatmap-chart.md +1 -1
  12. package/docs/agent/charts/ds-line-chart.md +3 -3
  13. package/docs/agent/charts/ds-pie-chart.md +5 -4
  14. package/docs/agent/charts/ds-scatter-chart.md +1 -1
  15. package/docs/agent/charts/ds-waterfall-chart.md +1 -1
  16. package/docs/agent/charts/line-series-component.md +1 -1
  17. package/docs/agent/feedback/ds-alert.md +1 -0
  18. package/docs/agent/feedback/ds-badge.md +1 -1
  19. package/docs/agent/feedback/ds-banner.md +1 -0
  20. package/docs/agent/feedback/ds-description-list.md +3 -0
  21. package/docs/agent/feedback/ds-skeleton.md +2 -2
  22. package/docs/agent/feedback/ds-tag.md +1 -1
  23. package/docs/agent/forms/ds-autocomplete.md +2 -2
  24. package/docs/agent/forms/ds-button.md +1 -1
  25. package/docs/agent/forms/ds-color-picker.md +1 -1
  26. package/docs/agent/forms/ds-date-picker.md +2 -2
  27. package/docs/agent/forms/ds-filter-bar.md +1 -1
  28. package/docs/agent/forms/ds-icon-button.md +1 -1
  29. package/docs/agent/forms/ds-input.md +1 -1
  30. package/docs/agent/forms/ds-multi-select.md +2 -2
  31. package/docs/agent/forms/ds-otp-input.md +1 -1
  32. package/docs/agent/forms/ds-search.md +2 -2
  33. package/docs/agent/forms/ds-split-button.md +1 -1
  34. package/docs/agent/forms/ds-textarea.md +2 -2
  35. package/docs/agent/foundations/tokens.md +1 -1
  36. package/docs/agent/navigation/ds-app-layout.md +2 -2
  37. package/docs/agent/navigation/ds-auth-layout.md +4 -4
  38. package/docs/agent/navigation/ds-page-header.md +1 -1
  39. package/docs/agent/navigation/ds-pagination.md +1 -1
  40. package/docs/agent/navigation/ds-tabs.md +1 -0
  41. package/docs/agent/overlays/ds-tooltip.md +3 -3
  42. package/docs/agent/platform/ds-config.md +2 -3
  43. package/docs/agent/platform/ds-intl.md +33 -0
  44. package/docs/agent/surfaces/ds-accordion.md +2 -2
  45. package/docs/agent/tables/ds-table.md +3 -3
  46. package/fesm2022/ids-group-ltd-ids-design-system-components-accordion.mjs +9 -5
  47. package/fesm2022/ids-group-ltd-ids-design-system-components-accordion.mjs.map +1 -1
  48. package/fesm2022/ids-group-ltd-ids-design-system-components-alert.mjs +21 -10
  49. package/fesm2022/ids-group-ltd-ids-design-system-components-alert.mjs.map +1 -1
  50. package/fesm2022/ids-group-ltd-ids-design-system-components-app-layout.mjs +9 -5
  51. package/fesm2022/ids-group-ltd-ids-design-system-components-app-layout.mjs.map +1 -1
  52. package/fesm2022/ids-group-ltd-ids-design-system-components-auth-layout.mjs +8 -8
  53. package/fesm2022/ids-group-ltd-ids-design-system-components-auth-layout.mjs.map +1 -1
  54. package/fesm2022/ids-group-ltd-ids-design-system-components-autocomplete.mjs +15 -8
  55. package/fesm2022/ids-group-ltd-ids-design-system-components-autocomplete.mjs.map +1 -1
  56. package/fesm2022/ids-group-ltd-ids-design-system-components-avatar-group.mjs +5 -3
  57. package/fesm2022/ids-group-ltd-ids-design-system-components-avatar-group.mjs.map +1 -1
  58. package/fesm2022/ids-group-ltd-ids-design-system-components-avatar.mjs +5 -10
  59. package/fesm2022/ids-group-ltd-ids-design-system-components-avatar.mjs.map +1 -1
  60. package/fesm2022/ids-group-ltd-ids-design-system-components-badge.mjs +12 -8
  61. package/fesm2022/ids-group-ltd-ids-design-system-components-badge.mjs.map +1 -1
  62. package/fesm2022/ids-group-ltd-ids-design-system-components-banner.mjs +21 -10
  63. package/fesm2022/ids-group-ltd-ids-design-system-components-banner.mjs.map +1 -1
  64. package/fesm2022/ids-group-ltd-ids-design-system-components-bar-chart.mjs +53 -30
  65. package/fesm2022/ids-group-ltd-ids-design-system-components-bar-chart.mjs.map +1 -1
  66. package/fesm2022/ids-group-ltd-ids-design-system-components-bottom-sheet.mjs +7 -6
  67. package/fesm2022/ids-group-ltd-ids-design-system-components-bottom-sheet.mjs.map +1 -1
  68. package/fesm2022/ids-group-ltd-ids-design-system-components-breadcrumbs.mjs +4 -3
  69. package/fesm2022/ids-group-ltd-ids-design-system-components-breadcrumbs.mjs.map +1 -1
  70. package/fesm2022/ids-group-ltd-ids-design-system-components-button.mjs +4 -4
  71. package/fesm2022/ids-group-ltd-ids-design-system-components-button.mjs.map +1 -1
  72. package/fesm2022/ids-group-ltd-ids-design-system-components-chart-data-table.mjs +5 -3
  73. package/fesm2022/ids-group-ltd-ids-design-system-components-chart-data-table.mjs.map +1 -1
  74. package/fesm2022/ids-group-ltd-ids-design-system-components-chart-legend.mjs +20 -6
  75. package/fesm2022/ids-group-ltd-ids-design-system-components-chart-legend.mjs.map +1 -1
  76. package/fesm2022/ids-group-ltd-ids-design-system-components-chart-tooltip.mjs +198 -44
  77. package/fesm2022/ids-group-ltd-ids-design-system-components-chart-tooltip.mjs.map +1 -1
  78. package/fesm2022/ids-group-ltd-ids-design-system-components-chart.mjs +248 -142
  79. package/fesm2022/ids-group-ltd-ids-design-system-components-chart.mjs.map +1 -1
  80. package/fesm2022/ids-group-ltd-ids-design-system-components-color-picker.mjs +9 -5
  81. package/fesm2022/ids-group-ltd-ids-design-system-components-color-picker.mjs.map +1 -1
  82. package/fesm2022/ids-group-ltd-ids-design-system-components-column-chart.mjs +28 -25
  83. package/fesm2022/ids-group-ltd-ids-design-system-components-column-chart.mjs.map +1 -1
  84. package/fesm2022/ids-group-ltd-ids-design-system-components-date-picker.mjs +16 -9
  85. package/fesm2022/ids-group-ltd-ids-design-system-components-date-picker.mjs.map +1 -1
  86. package/fesm2022/ids-group-ltd-ids-design-system-components-description-list.mjs +5 -3
  87. package/fesm2022/ids-group-ltd-ids-design-system-components-description-list.mjs.map +1 -1
  88. package/fesm2022/ids-group-ltd-ids-design-system-components-drawer.mjs +7 -4
  89. package/fesm2022/ids-group-ltd-ids-design-system-components-drawer.mjs.map +1 -1
  90. package/fesm2022/ids-group-ltd-ids-design-system-components-dropzone.mjs +12 -6
  91. package/fesm2022/ids-group-ltd-ids-design-system-components-dropzone.mjs.map +1 -1
  92. package/fesm2022/ids-group-ltd-ids-design-system-components-empty-state.mjs +2 -2
  93. package/fesm2022/ids-group-ltd-ids-design-system-components-empty-state.mjs.map +1 -1
  94. package/fesm2022/ids-group-ltd-ids-design-system-components-filter-bar.mjs +13 -7
  95. package/fesm2022/ids-group-ltd-ids-design-system-components-filter-bar.mjs.map +1 -1
  96. package/fesm2022/ids-group-ltd-ids-design-system-components-funnel-chart.mjs +64 -43
  97. package/fesm2022/ids-group-ltd-ids-design-system-components-funnel-chart.mjs.map +1 -1
  98. package/fesm2022/ids-group-ltd-ids-design-system-components-heatmap-chart.mjs +56 -12
  99. package/fesm2022/ids-group-ltd-ids-design-system-components-heatmap-chart.mjs.map +1 -1
  100. package/fesm2022/ids-group-ltd-ids-design-system-components-icon-button.mjs +3 -3
  101. package/fesm2022/ids-group-ltd-ids-design-system-components-icon-button.mjs.map +1 -1
  102. package/fesm2022/ids-group-ltd-ids-design-system-components-input.mjs +5 -4
  103. package/fesm2022/ids-group-ltd-ids-design-system-components-input.mjs.map +1 -1
  104. package/fesm2022/ids-group-ltd-ids-design-system-components-line-chart.mjs +32 -29
  105. package/fesm2022/ids-group-ltd-ids-design-system-components-line-chart.mjs.map +1 -1
  106. package/fesm2022/ids-group-ltd-ids-design-system-components-modal.mjs +26 -13
  107. package/fesm2022/ids-group-ltd-ids-design-system-components-modal.mjs.map +1 -1
  108. package/fesm2022/ids-group-ltd-ids-design-system-components-multi-select.mjs +17 -10
  109. package/fesm2022/ids-group-ltd-ids-design-system-components-multi-select.mjs.map +1 -1
  110. package/fesm2022/ids-group-ltd-ids-design-system-components-number-stepper.mjs +5 -4
  111. package/fesm2022/ids-group-ltd-ids-design-system-components-number-stepper.mjs.map +1 -1
  112. package/fesm2022/ids-group-ltd-ids-design-system-components-otp-input.mjs +13 -7
  113. package/fesm2022/ids-group-ltd-ids-design-system-components-otp-input.mjs.map +1 -1
  114. package/fesm2022/ids-group-ltd-ids-design-system-components-page-header.mjs +2 -2
  115. package/fesm2022/ids-group-ltd-ids-design-system-components-page-header.mjs.map +1 -1
  116. package/fesm2022/ids-group-ltd-ids-design-system-components-pagination.mjs +15 -8
  117. package/fesm2022/ids-group-ltd-ids-design-system-components-pagination.mjs.map +1 -1
  118. package/fesm2022/ids-group-ltd-ids-design-system-components-password-rules.mjs +12 -11
  119. package/fesm2022/ids-group-ltd-ids-design-system-components-password-rules.mjs.map +1 -1
  120. package/fesm2022/ids-group-ltd-ids-design-system-components-pie-chart.mjs +62 -25
  121. package/fesm2022/ids-group-ltd-ids-design-system-components-pie-chart.mjs.map +1 -1
  122. package/fesm2022/ids-group-ltd-ids-design-system-components-scatter-chart.mjs +49 -12
  123. package/fesm2022/ids-group-ltd-ids-design-system-components-scatter-chart.mjs.map +1 -1
  124. package/fesm2022/ids-group-ltd-ids-design-system-components-search.mjs +9 -6
  125. package/fesm2022/ids-group-ltd-ids-design-system-components-search.mjs.map +1 -1
  126. package/fesm2022/ids-group-ltd-ids-design-system-components-select.mjs +6 -3
  127. package/fesm2022/ids-group-ltd-ids-design-system-components-select.mjs.map +1 -1
  128. package/fesm2022/ids-group-ltd-ids-design-system-components-sidenav-footer.mjs +4 -2
  129. package/fesm2022/ids-group-ltd-ids-design-system-components-sidenav-footer.mjs.map +1 -1
  130. package/fesm2022/ids-group-ltd-ids-design-system-components-sidenav.mjs +5 -3
  131. package/fesm2022/ids-group-ltd-ids-design-system-components-sidenav.mjs.map +1 -1
  132. package/fesm2022/ids-group-ltd-ids-design-system-components-skeleton.mjs +20 -6
  133. package/fesm2022/ids-group-ltd-ids-design-system-components-skeleton.mjs.map +1 -1
  134. package/fesm2022/ids-group-ltd-ids-design-system-components-slider.mjs +6 -5
  135. package/fesm2022/ids-group-ltd-ids-design-system-components-slider.mjs.map +1 -1
  136. package/fesm2022/ids-group-ltd-ids-design-system-components-spinner.mjs +5 -3
  137. package/fesm2022/ids-group-ltd-ids-design-system-components-spinner.mjs.map +1 -1
  138. package/fesm2022/ids-group-ltd-ids-design-system-components-split-button.mjs +9 -6
  139. package/fesm2022/ids-group-ltd-ids-design-system-components-split-button.mjs.map +1 -1
  140. package/fesm2022/ids-group-ltd-ids-design-system-components-stepper.mjs +6 -4
  141. package/fesm2022/ids-group-ltd-ids-design-system-components-stepper.mjs.map +1 -1
  142. package/fesm2022/ids-group-ltd-ids-design-system-components-table-columns.mjs +16 -13
  143. package/fesm2022/ids-group-ltd-ids-design-system-components-table-columns.mjs.map +1 -1
  144. package/fesm2022/ids-group-ltd-ids-design-system-components-table-export.mjs +9 -6
  145. package/fesm2022/ids-group-ltd-ids-design-system-components-table-export.mjs.map +1 -1
  146. package/fesm2022/ids-group-ltd-ids-design-system-components-table.mjs +48 -22
  147. package/fesm2022/ids-group-ltd-ids-design-system-components-table.mjs.map +1 -1
  148. package/fesm2022/ids-group-ltd-ids-design-system-components-tabs.mjs +68 -6
  149. package/fesm2022/ids-group-ltd-ids-design-system-components-tabs.mjs.map +1 -1
  150. package/fesm2022/ids-group-ltd-ids-design-system-components-tag.mjs +9 -5
  151. package/fesm2022/ids-group-ltd-ids-design-system-components-tag.mjs.map +1 -1
  152. package/fesm2022/ids-group-ltd-ids-design-system-components-textarea.mjs +63 -10
  153. package/fesm2022/ids-group-ltd-ids-design-system-components-textarea.mjs.map +1 -1
  154. package/fesm2022/ids-group-ltd-ids-design-system-components-time-picker.mjs +12 -10
  155. package/fesm2022/ids-group-ltd-ids-design-system-components-time-picker.mjs.map +1 -1
  156. package/fesm2022/ids-group-ltd-ids-design-system-components-toast.mjs +8 -6
  157. package/fesm2022/ids-group-ltd-ids-design-system-components-toast.mjs.map +1 -1
  158. package/fesm2022/ids-group-ltd-ids-design-system-components-tooltip.mjs +78 -6
  159. package/fesm2022/ids-group-ltd-ids-design-system-components-tooltip.mjs.map +1 -1
  160. package/fesm2022/ids-group-ltd-ids-design-system-components-w3w.mjs +5 -3
  161. package/fesm2022/ids-group-ltd-ids-design-system-components-w3w.mjs.map +1 -1
  162. package/fesm2022/ids-group-ltd-ids-design-system-components-waterfall-chart.mjs +36 -21
  163. package/fesm2022/ids-group-ltd-ids-design-system-components-waterfall-chart.mjs.map +1 -1
  164. package/fesm2022/ids-group-ltd-ids-design-system-components.mjs +355 -81
  165. package/fesm2022/ids-group-ltd-ids-design-system-components.mjs.map +1 -1
  166. package/fesm2022/ids-group-ltd-ids-design-system-core.mjs +362 -3
  167. package/fesm2022/ids-group-ltd-ids-design-system-core.mjs.map +1 -1
  168. package/fesm2022/ids-group-ltd-ids-design-system.mjs +1 -1
  169. package/fesm2022/ids-group-ltd-ids-design-system.mjs.map +1 -1
  170. package/migrations/0.10.0.json +1 -1
  171. package/migrations/0.10.1.json +1 -1
  172. package/migrations/0.14.0.json +28 -4
  173. package/migrations/0.14.1.json +856 -0
  174. package/migrations/0.14.2.json +427 -0
  175. package/package.json +1 -1
  176. package/schematics/check-overrides/index.cjs +56 -0
  177. package/schematics/check-overrides/scan.cjs +74 -0
  178. package/schematics/check-overrides/schema.json +19 -0
  179. package/schematics/check-overrides/surface.json +2333 -0
  180. package/schematics/collection.json +5 -0
  181. package/styles/_chart-frame.scss +34 -12
  182. package/styles/_chart-interactive.scss +43 -9
  183. package/styles/_chart-motion.scss +139 -16
  184. package/styles/_field-box.scss +12 -0
  185. package/styles/_overlay-motion.scss +12 -4
  186. package/styles/_tokens-charts.scss +1 -1
  187. package/styles/_tokens.scss +19 -4
  188. package/types/ids-group-ltd-ids-design-system-components-accordion.d.ts +11 -2
  189. package/types/ids-group-ltd-ids-design-system-components-alert.d.ts +4 -0
  190. package/types/ids-group-ltd-ids-design-system-components-app-layout.d.ts +5 -2
  191. package/types/ids-group-ltd-ids-design-system-components-auth-layout.d.ts +5 -5
  192. package/types/ids-group-ltd-ids-design-system-components-autocomplete.d.ts +7 -4
  193. package/types/ids-group-ltd-ids-design-system-components-avatar-group.d.ts +2 -0
  194. package/types/ids-group-ltd-ids-design-system-components-avatar.d.ts +5 -3
  195. package/types/ids-group-ltd-ids-design-system-components-badge.d.ts +6 -2
  196. package/types/ids-group-ltd-ids-design-system-components-banner.d.ts +4 -0
  197. package/types/ids-group-ltd-ids-design-system-components-bar-chart.d.ts +41 -19
  198. package/types/ids-group-ltd-ids-design-system-components-breadcrumbs.d.ts +2 -0
  199. package/types/ids-group-ltd-ids-design-system-components-button.d.ts +2 -2
  200. package/types/ids-group-ltd-ids-design-system-components-chart-data-table.d.ts +2 -0
  201. package/types/ids-group-ltd-ids-design-system-components-chart-legend.d.ts +8 -1
  202. package/types/ids-group-ltd-ids-design-system-components-chart-tooltip.d.ts +34 -6
  203. package/types/ids-group-ltd-ids-design-system-components-chart.d.ts +189 -121
  204. package/types/ids-group-ltd-ids-design-system-components-color-picker.d.ts +6 -2
  205. package/types/ids-group-ltd-ids-design-system-components-column-chart.d.ts +17 -17
  206. package/types/ids-group-ltd-ids-design-system-components-date-picker.d.ts +9 -3
  207. package/types/ids-group-ltd-ids-design-system-components-description-list.d.ts +3 -1
  208. package/types/ids-group-ltd-ids-design-system-components-drawer.d.ts +2 -0
  209. package/types/ids-group-ltd-ids-design-system-components-dropzone.d.ts +3 -0
  210. package/types/ids-group-ltd-ids-design-system-components-filter-bar.d.ts +9 -4
  211. package/types/ids-group-ltd-ids-design-system-components-funnel-chart.d.ts +34 -20
  212. package/types/ids-group-ltd-ids-design-system-components-heatmap-chart.d.ts +36 -7
  213. package/types/ids-group-ltd-ids-design-system-components-input.d.ts +2 -0
  214. package/types/ids-group-ltd-ids-design-system-components-line-chart.d.ts +21 -18
  215. package/types/ids-group-ltd-ids-design-system-components-modal.d.ts +2 -0
  216. package/types/ids-group-ltd-ids-design-system-components-multi-select.d.ts +11 -6
  217. package/types/ids-group-ltd-ids-design-system-components-number-stepper.d.ts +2 -0
  218. package/types/ids-group-ltd-ids-design-system-components-otp-input.d.ts +6 -2
  219. package/types/ids-group-ltd-ids-design-system-components-pagination.d.ts +6 -2
  220. package/types/ids-group-ltd-ids-design-system-components-password-rules.d.ts +2 -0
  221. package/types/ids-group-ltd-ids-design-system-components-pie-chart.d.ts +41 -17
  222. package/types/ids-group-ltd-ids-design-system-components-scatter-chart.d.ts +28 -7
  223. package/types/ids-group-ltd-ids-design-system-components-search.d.ts +7 -3
  224. package/types/ids-group-ltd-ids-design-system-components-select.d.ts +3 -2
  225. package/types/ids-group-ltd-ids-design-system-components-sidenav-footer.d.ts +2 -0
  226. package/types/ids-group-ltd-ids-design-system-components-sidenav.d.ts +3 -1
  227. package/types/ids-group-ltd-ids-design-system-components-skeleton.d.ts +5 -1
  228. package/types/ids-group-ltd-ids-design-system-components-slider.d.ts +2 -0
  229. package/types/ids-group-ltd-ids-design-system-components-spinner.d.ts +6 -4
  230. package/types/ids-group-ltd-ids-design-system-components-split-button.d.ts +5 -2
  231. package/types/ids-group-ltd-ids-design-system-components-stepper.d.ts +2 -0
  232. package/types/ids-group-ltd-ids-design-system-components-table-export.d.ts +1 -0
  233. package/types/ids-group-ltd-ids-design-system-components-table.d.ts +15 -6
  234. package/types/ids-group-ltd-ids-design-system-components-tabs.d.ts +15 -2
  235. package/types/ids-group-ltd-ids-design-system-components-tag.d.ts +6 -2
  236. package/types/ids-group-ltd-ids-design-system-components-textarea.d.ts +24 -4
  237. package/types/ids-group-ltd-ids-design-system-components-time-picker.d.ts +3 -0
  238. package/types/ids-group-ltd-ids-design-system-components-toast.d.ts +3 -0
  239. package/types/ids-group-ltd-ids-design-system-components-tooltip.d.ts +10 -1
  240. package/types/ids-group-ltd-ids-design-system-components-w3w.d.ts +2 -0
  241. package/types/ids-group-ltd-ids-design-system-components-waterfall-chart.d.ts +18 -7
  242. package/types/ids-group-ltd-ids-design-system-components.d.ts +75 -25
  243. package/types/ids-group-ltd-ids-design-system-core.d.ts +421 -11
  244. package/types/ids-group-ltd-ids-design-system.d.ts +3 -3
package/components.md CHANGED
@@ -41,7 +41,7 @@ Loaded via `@use 'styles/tokens';` (when the consumer also `@use 'styles/ds';` t
41
41
  - Error (destructive, was --danger): `--error`, `--error-hover`, `--error-pressed`, `--error-subtle`, `--error-muted`, `--error-border`, `--error-text` + HSL channels `--error-h/s/l`
42
42
  - Status: `--success`, `--success-hover`, `--success-subtle`, `--success-muted`, `--success-border`, `--success-text`
43
43
  - Status (warning/info): same shape with prefix swapped
44
- - Status pills: the DS ships no predefined status keys — consumers register their own vocabulary (e.g. `planning`, `confirmed`) and wire colours per key via `@use 'styles/status'` (`status.define(...)` / `status.semantic-preset`), which sets `--ds-badge-bg-color` / `--ds-badge-label-color` / `--ds-status-dot-color` per `[data-status]`. Full guide (model, worked example, migration from factory statuses): [`migrations/0.5.1/badge-statuses.md`](migrations/0.5.1/badge-statuses.md)
44
+ - Status pills: the DS ships no predefined status keys — consumers register their own vocabulary (e.g. `planning`, `confirmed`) and wire colours per key via `@use 'styles/status'` (`status.define(...)` / `status.semantic-preset`), which sets `--ds-badge-bg-color` / `--ds-badge-label-color` / `--ds-status-dot-color` per `[data-status]`. Full guide (model, worked example, migration from factory statuses): [`migrations/0.5.1/badge-statuses.md`](migrations/0.5.1/badge-statuses.md). `--ds-badge-font-size` sets the label size (default `--font-size-xs`; a `count` badge re-resolves it at `--font-size-2xs`, so the token reaches both).
45
45
 
46
46
  **Geometry:**
47
47
  - Spacing: `--space-0`, `--space-px`, `--space-0-5` (2px), `--space-1` (4px), `--space-1-5` (6px), `--space-2` (8px), `--space-2-5` (10px), `--space-3` (12px), `--space-4` (16px), `--space-5` (20px), `--space-6` (24px), `--space-8` (32px), `--space-10` (40px), `--space-12` (48px), `--space-14` (56px), `--space-16` (64px), `--space-20` (80px), `--space-24` (96px), `--space-32` (128px)
@@ -155,6 +155,8 @@ text rather than a state. Retune app-wide with `DS_CONFIG.field.stateIcons` (per
155
155
  `hidden`, but it renders no message row and therefore takes none of the message inputs. A toolbar filter
156
156
  is not a validated field; where a search needs a label or an error line, use `ds-input`.
157
157
 
158
+ **Shared box tokens.** `--ds-field-border-color`, `--ds-field-border-color-hover`, `--ds-field-border-color-focus`, `--ds-field-text-color`, `--ds-field-placeholder-color` and `--ds-field-font-size` sit UNDER each field's own token the way `--ds-field-height` and `--ds-field-label-*` do: `--ds-input-border`, `--ds-select-border-color-focus` or `--ds-autocomplete-text-color` still wins where set, and the family value fills in everywhere it is not. They reach input, textarea, select, multi-select, autocomplete and search. The date, time and colour pickers, the number stepper and the OTP cells keep their own `--ds-<component>-*` tokens and do not read the family.
159
+
158
160
  #### `<ds-button>` — `ButtonComponent`
159
161
  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'`, `align: ButtonAlign = 'center'` (`'center' | 'between'`; `'between'` pushes the label and a trailing icon to opposite edges, and only shows once something widens the button past its contents), `disabled`, `loading`, `fullWidth`, `icon: IconName | null`, and the destination pair `routerLink: DsRouterLink = null` (a path, a command array or a `UrlTree`) / `href: string = ''`, with the modifiers `fragment` / `queryParams` / `queryParamsHandling` (routerLink-only) and `target` / `rel` (either link), plus `routerLinkActiveOptions` and `ariaCurrent`. Plus the refusal pair below: `disabledReason`, and the field message inputs `hint` / `warning` / `error` / `messageIcon` / `reserveMessage` / `ariaDescribedBy`.
160
162
  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`.)
@@ -168,7 +170,7 @@ Content slots: default (label / leading or trailing icon), plus `[dsButtonSubtex
168
170
  - **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.
169
171
  - **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.
170
172
  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.
171
- 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-color`, `--ds-button-border-color-disabled`, `--ds-button-border-width`, `--ds-button-radius`, `--ds-button-pressed-shadow`, `--ds-button-shadow`, `--ds-button-shadow-hover`. The focus ring is not a button token — set `--focus-ring-color`, `--focus-ring-width` or `--focus-ring-offset` on the button's own scope. 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.
173
+ 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-color`, `--ds-button-border-color-hover`, `--ds-button-border-color-active`, `--ds-button-border-color-disabled`, `--ds-button-border-width`, `--ds-button-radius`, `--ds-button-pressed-shadow`, `--ds-button-shadow`, `--ds-button-shadow-hover`. The focus ring is not a button token — set `--focus-ring-color`, `--focus-ring-width` or `--focus-ring-offset` on the button's own scope. 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. `-border-color-hover` falls back to the rest border and `-border-color-active` to the hover one, so an outline button's edge stays put until one of them is set. 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.
172
174
 
173
175
  <!-- inputs:ds-button -->
174
176
  All inputs: `hint: string = ''`, `error: string = ''`, `warning: string = ''`, `reserveMessage: boolean | null = null`, `messageIcon: IconName | false | null = null`, `color: ButtonColor = 'primary'`, `variant: 'solid' | 'tonal' | 'ghost' | 'outline' | 'text' = 'solid'`, `align: 'center' | 'between' = 'center'`, `size: 'sm' | 'md' | 'lg' = null`, `routerLink: DsRouterLink = null`, `href: string = ''`, `fragment: string | undefined`, `queryParams: Params | null | undefined`, `queryParamsHandling: QueryParamsHandling | null | undefined`, `target: string | undefined`, `rel: string | undefined`, `routerLinkActiveOptions: { exact: boolean } | IsActiveMatchOptions`, `ariaCurrent: 'page' | 'step' | 'location' | 'date' | 'time' | 'true'`, `type: 'button' | 'submit' | 'reset' = 'button'`, `disabled: boolean = false`, `loading: boolean = false`, `fullWidth: boolean = false`, `ariaLabel: string | null = null`, `icon: IconName | null = null`, `trailingIcon: IconName | null = null`, `ariaHasPopup: 'true' | 'menu' | 'listbox' | 'tree' | 'grid' | 'dialog' = null`, `ariaExpanded: boolean | null = null`, `ariaControls: string | null = null`, `disabledReason: string = ''`, `ariaDescribedBy: string | null = null`
@@ -179,7 +181,7 @@ Icon-only action with its own taxonomy, distinct from `ds-button`. `ariaLabel` i
179
181
  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`)
180
182
  Output: `(pressed): MouseEvent` — fires when not disabled
181
183
  Variant emphasis: `standard` chromeless (hover-reveal) · `filled` `--primary` · `tonal` `--primary-muted` · `outlined` bordered. `selected` renders the pressed/active fill.
182
- 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`. The focus ring is not an icon-button token — set `--focus-ring-color`, `--focus-ring-width` or `--focus-ring-offset` on its own scope. `filled`/`selected` derive hover/active from the resolved bg, `standard`/`tonal`/`outlined` keep explicit ramp defaults.
184
+ Tokens: `--ds-icon-button-bg-color`, `--ds-icon-button-icon-color`, `--ds-icon-button-border`, `--ds-icon-button-border-hover`, `--ds-icon-button-border-active`, `--ds-icon-button-bg-color-hover`, `--ds-icon-button-bg-color-active`, `--ds-icon-button-icon-color-hover`, `--ds-icon-button-radius`. The focus ring is not an icon-button token — set `--focus-ring-color`, `--focus-ring-width` or `--focus-ring-offset` on its own scope. `filled`/`selected` derive hover/active from the resolved bg, `standard`/`tonal`/`outlined` keep explicit ramp defaults. `-border-hover` falls back to `-border` and `-border-active` to `-border-hover`, so the border stays put until one of them is set.
183
185
 
184
186
  <!-- inputs:ds-icon-button -->
185
187
  All inputs: `icon: required IconName`, `ariaLabel: required string`, `ariaDescribedBy: string | null = null`, `variant: 'standard' | 'filled' | 'tonal' | 'outlined' = 'standard'`, `color: ButtonColor = 'primary'`, `size: 'sm' | 'md' | 'lg' = null`, `type: 'button' | 'submit' | 'reset' = 'button'`, `disabled: boolean = false`, `selected: boolean = false`, `ariaExpanded: boolean | null = null`, `ariaControls: string | null = null`
@@ -202,7 +204,7 @@ Example:
202
204
  </ds-input>
203
205
  ```
204
206
 
205
- Tokens: `--ds-input-bg-color`, `--ds-input-border`, `--ds-input-border-hover`, `--ds-input-border-focus`, `--ds-input-text-color`, `--ds-input-placeholder`, `--ds-input-radius`, `--ds-input-padding-x`, `--ds-input-padding-y`, `--ds-input-focus-shadow`, `--ds-input-border-error`, `--ds-input-bg-color-error`, `--ds-input-border-success`, `--ds-input-bg-color-disabled`
207
+ Tokens: `--ds-input-bg-color`, `--ds-input-border`, `--ds-input-border-hover`, `--ds-input-border-focus`, `--ds-input-text-color`, `--ds-input-placeholder`, `--ds-input-radius`, `--ds-input-padding-x`, `--ds-input-padding-y`, `--ds-input-focus-shadow`, `--ds-input-border-error`, `--ds-input-bg-color-error`, `--ds-input-border-success`, `--ds-input-bg-color-disabled`, `--ds-input-font-size` (also read by `ds-textarea`)
206
208
 
207
209
  <!-- inputs:ds-input -->
208
210
  All inputs: `hint: string = ''`, `error: string = ''`, `warning: string = ''`, `reserveMessage: boolean | null = null`, `messageIcon: IconName | false | null = null`, `errors: readonly DsFieldError[] = []`, `invalid: boolean = false`, `touched: boolean = false`, `hidden: boolean = false`, `value: string = ''`, `type: InputType = 'text'`, `size: 'sm' | 'md' | 'lg' = null`, `label: string = ''`, `placeholder: string = ''`, `disabled: boolean = false`, `readOnly: boolean = false`, `readonlyBinding: boolean = false`, `success: string = ''`, `loading: boolean = false`, `required: boolean = false`, `optional: boolean = false`, `name: string | null = null`, `min: number | null = null`, `max: number | null = null`, `step: number | null = null`, `autocomplete: string | null = null`, `autofocus: boolean = false`, `ariaLabel: string | null = null`, `ariaDescribedBy: string | null = null`, `maxLength: number | null = null`, `minLength: number | null = null`, `pattern: readonly RegExp[] = []`, `enterKeyHint: 'enter' | 'done' | 'go' | 'next' | 'previous' | 'search' | 'send' | null = null`, `inputMode: | 'none'
@@ -219,12 +221,12 @@ All inputs: `hint: string = ''`, `error: string = ''`, `warning: string = ''`, `
219
221
  #### `<ds-textarea>` — `TextareaComponent`
220
222
  Multi-line counterpart to `<ds-input>` — same wrapper/states, reuses the `--ds-input-*` token family. No prefix/suffix slots.
221
223
  Inputs: `value: model<string>`, `size: 'sm' | 'md' | 'lg' = 'md'`, `label`, `hint`, `placeholder`, `disabled`, `invalid`, `required`, `optional: boolean = false`, `name`, `rows: number = 3`
222
- Tokens: same `--ds-input-*` family as `<ds-input>` (textarea overrides `--ds-input-padding-y` to `--space-3` for vertical breathing room).
224
+ Tokens: same `--ds-input-*` family as `<ds-input>`, `--ds-input-font-size` included (textarea overrides `--ds-input-padding-y` to `--space-3` for vertical breathing room).
223
225
  New: `autosize: boolean = false` (grows with content; forces `resize='none'`), `minRows`/`maxRows: number | null = null`, `resize: 'none' | 'vertical' | 'horizontal' | 'both' = 'vertical'`.
224
226
  Methods: `focus(options?)`, `selectionStart` / `selectionEnd` (reads), `setSelectionRange(start, end, direction?)`, `select()` - all forwarded to the native `<textarea>`, so an editor toolbar never queries the component's DOM. A value written through `value` lands a microtask later and moves the caret to the end; set a range after `value.set(...)` from a `setTimeout`.
225
227
 
226
228
  <!-- inputs:ds-textarea -->
227
- All inputs: `hint: string = ''`, `error: string = ''`, `warning: string = ''`, `reserveMessage: boolean | null = null`, `messageIcon: IconName | false | null = null`, `errors: readonly DsFieldError[] = []`, `invalid: boolean = false`, `touched: boolean = false`, `hidden: boolean = false`, `value: string = ''`, `size: 'sm' | 'md' | 'lg' = null`, `label: string = ''`, `placeholder: string = ''`, `disabled: boolean = false`, `readOnly: boolean = false`, `readonlyBinding: boolean = false`, `success: string = ''`, `required: boolean = false`, `optional: boolean = false`, `rows: number = 3`, `name: string | null = null`, `autosize: boolean = false`, `minRows: number | null = null`, `maxRows: number | null = null`, `resize: 'none' | 'vertical' | 'horizontal' | 'both' = 'vertical'`, `ariaLabel: string | null = null`, `maxLength: number | null = null`, `minLength: number | null = null`, `pattern: readonly RegExp[] = []`
229
+ All inputs: `hint: string = ''`, `error: string = ''`, `warning: string = ''`, `reserveMessage: boolean | null = null`, `messageIcon: IconName | false | null = null`, `errors: readonly DsFieldError[] = []`, `invalid: boolean = false`, `touched: boolean = false`, `hidden: boolean = false`, `value: string = ''`, `size: 'sm' | 'md' | 'lg' = null`, `label: string = ''`, `placeholder: string = ''`, `disabled: boolean = false`, `readOnly: boolean = false`, `readonlyBinding: boolean = false`, `success: string = ''`, `required: boolean = false`, `optional: boolean = false`, `rows: number = 3`, `name: string | null = null`, `autosize: boolean = false`, `minRows: number | null = null`, `maxRows: number | null = null`, `resize: 'none' | 'vertical' | 'horizontal' | 'both' = 'vertical'`, `ariaLabel: string | null = null`, `maxLength: number | null = null`, `maxLengthMode: 'hard' | 'soft' = 'hard'`, `minLength: number | null = null`, `pattern: readonly RegExp[] = []`
228
230
  <!-- /inputs -->
229
231
 
230
232
  #### `<ds-number-stepper>` — `NumberStepperComponent`
@@ -291,39 +293,39 @@ All inputs: `hint: string = ''`, `error: string = ''`, `warning: string = ''`, `
291
293
  <!-- /inputs -->
292
294
 
293
295
  #### `<ds-multi-select>` — `MultiSelectComponent`
294
- 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`
296
+ Inputs: `value: model<string[]>`, `options: readonly MultiSelectItem[]`, `placeholder: string | null = null` (unset: `DS_INTL.picker.placeholder`), `searchPlaceholder: string | null = null` (unset: `DS_INTL.picker.filterPlaceholder`), `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`
295
297
 
296
298
  <!-- inputs:ds-multi-select -->
297
- All inputs: `hint: string = ''`, `error: string = ''`, `warning: string = ''`, `reserveMessage: boolean | null = null`, `messageIcon: IconName | false | null = null`, `errors: readonly DsFieldError[] = []`, `invalid: boolean = false`, `touched: boolean = false`, `hidden: boolean = false`, `value: string[] = []`, `options: readonly MultiSelectItem[] = []`, `placeholder: string = 'Select…'`, `searchPlaceholder: string = 'Filter…'`, `searchable: boolean | number | null = null`, `name: string | null = null`, `panelClass: string | readonly string[] = []`, `readOnly: boolean = false`, `readonlyBinding: boolean = false`, `clearable: boolean = false`, `filterWith: ((option: MultiSelectOption, query: string) => boolean) | 'none'`, `loading: boolean = false`, `scrollActiveIntoView: boolean = true`, `maxVisibleChips: number | 'fit' | 'all' | null = null`, `disabled: boolean = false`, `success: string = ''`, `ariaLabel: string | null = null`, `width: 'fill' | 'content' = 'fill'`, `size: 'sm' | 'md' | 'lg' = null`, `triggerDisplay: 'full' | 'count' | 'labels' = 'full'`, `label: string = ''`, `required: boolean = false`, `optional: boolean = false`, `selectAll: boolean | 'group' | 'both' = false`
299
+ All inputs: `hint: string = ''`, `error: string = ''`, `warning: string = ''`, `reserveMessage: boolean | null = null`, `messageIcon: IconName | false | null = null`, `errors: readonly DsFieldError[] = []`, `invalid: boolean = false`, `touched: boolean = false`, `hidden: boolean = false`, `value: string[] = []`, `options: readonly MultiSelectItem[] = []`, `placeholder: string | null = null`, `searchPlaceholder: string | null = null`, `searchable: boolean | number | null = null`, `name: string | null = null`, `panelClass: string | readonly string[] = []`, `readOnly: boolean = false`, `readonlyBinding: boolean = false`, `clearable: boolean = false`, `filterWith: ((option: MultiSelectOption, query: string) => boolean) | 'none'`, `loading: boolean = false`, `scrollActiveIntoView: boolean = true`, `maxVisibleChips: number | 'fit' | 'all' | null = null`, `disabled: boolean = false`, `success: string = ''`, `ariaLabel: string | null = null`, `width: 'fill' | 'content' = 'fill'`, `size: 'sm' | 'md' | 'lg' = null`, `triggerDisplay: 'full' | 'count' | 'labels' = 'full'`, `label: string = ''`, `required: boolean = false`, `optional: boolean = false`, `selectAll: boolean | 'group' | 'both' = false`
298
300
  <!-- /inputs -->
299
301
 
300
302
  #### `<ds-autocomplete>` — `AutocompleteComponent<T>`
301
303
  Type-ahead picker, generic on the option value.
302
- 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`
304
+ Inputs: `options: readonly AutocompleteItem<T>[]`, `value: model<T | readonly T[] | null>`, `multiple: boolean = false`, `placeholder: string | null = null` (unset: `DS_INTL.picker.placeholder`), `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`
303
305
  Output: `(create): string` — the typed text, when `allowCreate` is on and nothing matched.
304
306
  In multiple mode the selection renders as chips above the trigger.
305
307
 
306
308
  <!-- inputs:ds-autocomplete -->
307
- All inputs: `hint: string = ''`, `error: string = ''`, `warning: string = ''`, `reserveMessage: boolean | null = null`, `messageIcon: IconName | false | null = null`, `errors: readonly DsFieldError[] = []`, `invalid: boolean = false`, `touched: boolean = false`, `hidden: boolean = false`, `options: readonly AutocompleteItem<T>[] = []`, `value: T | readonly T[] | null = null`, `multiple: boolean = false`, `showChevron: boolean = true`, `maxVisibleChips: number | 'fit' | 'all' | null = null`, `size: 'sm' | 'md' | 'lg' = null`, `width: 'fill' | 'content' = 'fill'`, `valueOverflow: 'ellipsis' | 'wrap' = 'ellipsis'`, `placeholder: string = 'Select…'`, `disabled: boolean = false`, `success: string = ''`, `allowCreate: boolean = false`, `label: string = ''`, `compareWith: (a: T | null, b: T | null) => boolean`, `name: string | null = null`, `panelClass: string | readonly string[] = []`, `readOnly: boolean = false`, `readonlyBinding: boolean = false`, `clearable: boolean = false`, `searchPlaceholder: string = ''`, `filterWith: ((option: AutocompleteOption<T>, query: string) => boolean) | 'none'`, `loading: boolean = false`, `scrollActiveIntoView: boolean = true`, `required: boolean = false`, `optional: boolean = false`, `ariaLabel: string | null = null`
309
+ All inputs: `hint: string = ''`, `error: string = ''`, `warning: string = ''`, `reserveMessage: boolean | null = null`, `messageIcon: IconName | false | null = null`, `errors: readonly DsFieldError[] = []`, `invalid: boolean = false`, `touched: boolean = false`, `hidden: boolean = false`, `options: readonly AutocompleteItem<T>[] = []`, `value: T | readonly T[] | null = null`, `multiple: boolean = false`, `showChevron: boolean = true`, `maxVisibleChips: number | 'fit' | 'all' | null = null`, `size: 'sm' | 'md' | 'lg' = null`, `width: 'fill' | 'content' = 'fill'`, `valueOverflow: 'ellipsis' | 'wrap' = 'ellipsis'`, `placeholder: string | null = null`, `disabled: boolean = false`, `success: string = ''`, `allowCreate: boolean = false`, `label: string = ''`, `compareWith: (a: T | null, b: T | null) => boolean`, `name: string | null = null`, `panelClass: string | readonly string[] = []`, `readOnly: boolean = false`, `readonlyBinding: boolean = false`, `clearable: boolean = false`, `searchPlaceholder: string = ''`, `filterWith: ((option: AutocompleteOption<T>, query: string) => boolean) | 'none'`, `loading: boolean = false`, `scrollActiveIntoView: boolean = true`, `required: boolean = false`, `optional: boolean = false`, `ariaLabel: string | null = null`
308
310
  <!-- /inputs -->
309
311
 
310
312
  #### `<ds-search>` — `SearchComponent`
311
313
  Pre-styled search input with built-in icon. A form control, but not a field: no label, no message row.
312
- 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)
314
+ Inputs: `value: model<string>`, `placeholder: string | null = null` (unset: `DS_INTL.search.placeholder`), `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)
313
315
  Output: `(submitted): string` — emits the current value on Enter / form submit
314
316
  Methods: `clear()` — empties the field, drops an armed keystroke and publishes `''` at once, which writing `''` into `value` does not; `focus()`, `blur()`.
315
317
  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.
316
318
 
317
319
  <!-- inputs:ds-search -->
318
- All inputs: `hidden: boolean = false`, `value: string = ''`, `placeholder: string = 'Search'`, `shortcut: string = ''`, `showIcon: boolean = true`, `clearable: boolean = false`, `ariaLabel: string = ''`, `disabled: boolean = false`, `size: 'sm' | 'md' | 'lg' = null`, `debounce: number = 0`
320
+ All inputs: `hidden: boolean = false`, `value: string = ''`, `placeholder: string | null = null`, `shortcut: string = ''`, `showIcon: boolean = true`, `clearable: boolean = false`, `ariaLabel: string = ''`, `disabled: boolean = false`, `size: 'sm' | 'md' | 'lg' = null`, `debounce: number = 0`
319
321
  <!-- /inputs -->
320
322
 
321
323
  #### `<ds-date-picker>` — `DatePickerComponent`
322
- Inputs: `mode: 'single' | 'range' = 'single'`, `size: 'sm' | 'md' | 'lg' = 'md'`, `value: model<Date | DateRangeValue | null>` (`DateRangeValue = [Date | null, Date | null]`), `placeholder: string = 'Select date'`, `label: string = ''`, `hint: string = ''`, `required: boolean = false`, `optional: boolean = false`
324
+ Inputs: `mode: 'single' | 'range' = 'single'`, `size: 'sm' | 'md' | 'lg' = 'md'`, `value: model<Date | DateRangeValue | null>` (`DateRangeValue = [Date | null, Date | null]`), `placeholder: string | null = null` (unset: `DS_INTL.datePicker.placeholder`), `label: string = ''`, `hint: string = ''`, `required: boolean = false`, `optional: boolean = false`
323
325
  Trigger button opens a CDK overlay calendar; selecting a day in `'single'` closes the panel, in `'range'` it closes after the second pick.
324
326
 
325
327
  <!-- inputs:ds-date-picker -->
326
- All inputs: `hint: string = ''`, `error: string = ''`, `warning: string = ''`, `reserveMessage: boolean | null = null`, `messageIcon: IconName | false | null = null`, `errors: readonly DsFieldError[] = []`, `invalid: boolean = false`, `touched: boolean = false`, `hidden: boolean = false`, `mode: 'single' | 'range' = 'single'`, `size: 'sm' | 'md' | 'lg' = null`, `fullWidth: boolean = false`, `value: Date | DateRangeValue | null = null`, `placeholder: string = 'Select date'`, `label: string = ''`, `required: boolean = false`, `optional: boolean = false`, `panelClass: string | readonly string[] = []`, `disabled: boolean = false`, `success: string = ''`, `ariaLabel: string | null = null`, `minYear: number`, `maxYear: number`, `minDate: Date | null = null`, `maxDate: Date | null = null`, `disabledDate: ((date: Date) => boolean) | null = null`, `presets: readonly DatePickerPreset[] = []`, `locale: string | null = null`, `dateFormat: string | null = null`, `firstDayOfWeek: number | null = null`, `defaultDate: Date | null = null`, `allowInput: boolean = true`
328
+ All inputs: `hint: string = ''`, `error: string = ''`, `warning: string = ''`, `reserveMessage: boolean | null = null`, `messageIcon: IconName | false | null = null`, `errors: readonly DsFieldError[] = []`, `invalid: boolean = false`, `touched: boolean = false`, `hidden: boolean = false`, `mode: 'single' | 'range' = 'single'`, `size: 'sm' | 'md' | 'lg' = null`, `fullWidth: boolean = false`, `value: Date | DateRangeValue | null = null`, `placeholder: string | null = null`, `label: string = ''`, `required: boolean = false`, `optional: boolean = false`, `panelClass: string | readonly string[] = []`, `disabled: boolean = false`, `success: string = ''`, `ariaLabel: string | null = null`, `minYear: number`, `maxYear: number`, `minDate: Date | null = null`, `maxDate: Date | null = null`, `disabledDate: ((date: Date) => boolean) | null = null`, `presets: readonly DatePickerPreset[] = []`, `locale: string | null = null`, `dateFormat: string | null = null`, `firstDayOfWeek: number | null = null`, `defaultDate: Date | null = null`, `allowInput: boolean = true`
327
329
  <!-- /inputs -->
328
330
 
329
331
  #### `<ds-dropzone>` — `DropzoneComponent`
@@ -346,7 +348,7 @@ All inputs: `ariaLabel: string | null = null`
346
348
  #### `<ds-split-button>` — `SplitButtonComponent`
347
349
 
348
350
  <!-- inputs:ds-split-button -->
349
- All inputs: `label: string = ''`, `variant: 'primary' | 'outline' = 'primary'`, `icon: IconName | null = null`, `disabled: boolean = false`, `menuItems: readonly SplitButtonItem[] = []`, `menuLabel: string = 'More actions'`
351
+ All inputs: `label: string = ''`, `variant: 'primary' | 'outline' = 'primary'`, `icon: IconName | null = null`, `disabled: boolean = false`, `menuItems: readonly SplitButtonItem[] = []`, `menuLabel: string | null = null`
350
352
  <!-- /inputs -->
351
353
 
352
354
  #### `<ds-toggle-button>` — `ToggleButtonComponent`
@@ -358,7 +360,7 @@ All inputs: `pressed: boolean = false`, `icon: string = ''`, `disabled: boolean
358
360
  #### `<ds-color-picker>` — `ColorPickerComponent`
359
361
 
360
362
  <!-- inputs:ds-color-picker -->
361
- All inputs: `hint: string = ''`, `error: string = ''`, `warning: string = ''`, `reserveMessage: boolean | null = null`, `messageIcon: IconName | false | null = null`, `errors: readonly DsFieldError[] = []`, `invalid: boolean = false`, `touched: boolean = false`, `hidden: boolean = false`, `value: string = '#2F54FF'`, `presets: readonly string[]`, `panelClass: string | readonly string[] = []`, `disabled: boolean = false`, `ariaLabel: string = 'Choose colour'`, `success: string = ''`
363
+ All inputs: `hint: string = ''`, `error: string = ''`, `warning: string = ''`, `reserveMessage: boolean | null = null`, `messageIcon: IconName | false | null = null`, `errors: readonly DsFieldError[] = []`, `invalid: boolean = false`, `touched: boolean = false`, `hidden: boolean = false`, `value: string = '#2F54FF'`, `presets: readonly string[]`, `panelClass: string | readonly string[] = []`, `disabled: boolean = false`, `ariaLabel: string | null = null`, `success: string = ''`
362
364
  <!-- /inputs -->
363
365
 
364
366
  #### `<ds-field-group>` — `FieldGroupComponent`
@@ -370,7 +372,7 @@ All inputs: `hint: string = ''`, `error: string = ''`, `warning: string = ''`, `
370
372
  #### `<ds-otp-input>` — `OtpInputComponent`
371
373
 
372
374
  <!-- inputs:ds-otp-input -->
373
- All inputs: `hint: string = ''`, `error: string = ''`, `warning: string = ''`, `reserveMessage: boolean | null = null`, `messageIcon: IconName | false | null = null`, `errors: readonly DsFieldError[] = []`, `invalid: boolean = false`, `touched: boolean = false`, `hidden: boolean = false`, `value: string = ''`, `length: number = 6`, `mode: 'numeric' | 'alphanumeric' = 'numeric'`, `mask: boolean = false`, `disabled: boolean = false`, `success: string = ''`, `ariaLabel: string = 'Verification code'`
375
+ All inputs: `hint: string = ''`, `error: string = ''`, `warning: string = ''`, `reserveMessage: boolean | null = null`, `messageIcon: IconName | false | null = null`, `errors: readonly DsFieldError[] = []`, `invalid: boolean = false`, `touched: boolean = false`, `hidden: boolean = false`, `value: string = ''`, `length: number = 6`, `mode: 'numeric' | 'alphanumeric' = 'numeric'`, `mask: boolean = false`, `disabled: boolean = false`, `success: string = ''`, `ariaLabel: string | null = null`
374
376
  <!-- /inputs -->
375
377
 
376
378
  #### `<ds-password-rules>` — `PasswordRulesComponent`
@@ -406,7 +408,7 @@ All inputs: `hint: string = ''`, `error: string = ''`, `warning: string = ''`, `
406
408
  #### `<ds-filter-bar>` — `FilterBarComponent`
407
409
 
408
410
  <!-- inputs:ds-filter-bar -->
409
- All inputs: `moreLabel: string = 'more'`, `panelLabel: string = 'More filters'`, `triggerSize: 'sm' | 'md' | 'lg' = 'md'`
411
+ All inputs: `moreLabel: string | null = null`, `panelLabel: string | null = null`, `triggerSize: 'sm' | 'md' | 'lg' = 'md'`
410
412
  <!-- /inputs -->
411
413
 
412
414
  #### `<ng-template[dsFilterItem]>` — `FilterItemDirective`
@@ -422,7 +424,7 @@ Inputs: `status: DsStatusKey` (consumer-registered status key; colours wired via
422
424
  Content: label text. Use for status pills, counts, lifecycle markers.
423
425
 
424
426
  <!-- inputs:ds-badge -->
425
- All inputs: `status: DsStatusKey`, `withDot: boolean | null = null`, `solid: boolean = false`, `count: number | null = null`, `max: number = 99`, `countLabel: string = 'notifications'`
427
+ All inputs: `status: DsStatusKey`, `withDot: boolean | null = null`, `solid: boolean = false`, `count: number | null = null`, `max: number = 99`, `countLabel: string | null = null`
426
428
  <!-- /inputs -->
427
429
 
428
430
  #### `<ds-status-dot>` — `StatusDotComponent`
@@ -438,7 +440,7 @@ Output: `(closed): void` — emits when the close button is pressed
438
440
  Content: label.
439
441
 
440
442
  <!-- inputs:ds-tag -->
441
- All inputs: `variant: 'solid' | 'neutral' = 'solid'`, `closable: boolean = false`, `interactive: boolean = false`, `selected: boolean = false`, `closeLabel: string = 'Remove'`
443
+ All inputs: `variant: 'solid' | 'neutral' = 'solid'`, `closable: boolean = false`, `interactive: boolean = false`, `selected: boolean = false`, `closeLabel: string | null = null`
442
444
  <!-- /inputs -->
443
445
 
444
446
  #### `<ds-avatar>` — `AvatarComponent`
@@ -478,10 +480,10 @@ All inputs: `size: 'sm' | 'md' | 'lg' = 'md'`
478
480
  <!-- /inputs -->
479
481
 
480
482
  #### `<ds-skeleton>` — `SkeletonComponent`
481
- Inputs: `width?: string`, `height?: string`, `circle: boolean = false`, `inline: boolean = false`. Shimmer animation requires the global `_skeleton-shimmer.scss` (already pulled in by `ds.scss`).
483
+ Inputs: `width?: string`, `height?: string`, `circle: boolean = false`, `inline: boolean = false`, `shimmer: boolean = true` (`false` draws a still block of the same shape, for a space held for something that is not loading yet). The wave advances in `--ds-skeleton-wave-steps` steps per pass (default `68`: twenty a second over the default `--ds-skeleton-wave-duration`); more is smoother and costs a main-thread update each. Shimmer animation requires the global `_skeleton-shimmer.scss` (already pulled in by `ds.scss`).
482
484
 
483
485
  <!-- inputs:ds-skeleton -->
484
- All inputs: `width: string | undefined`, `height: string | undefined`, `circle: boolean = false`, `inline: boolean = false`
486
+ All inputs: `width: string | undefined`, `height: string | undefined`, `circle: boolean = false`, `inline: boolean = false`, `shimmer: boolean = true`
485
487
  <!-- /inputs -->
486
488
 
487
489
  #### `<ds-stat>` — `StatComponent`
@@ -506,6 +508,7 @@ Output: `(closed): void`
506
508
  Content slots: default (body text), `[actions]` (trailing CTAs)
507
509
  - `layout="stacked"` (default): actions wrap onto a new line, indented under the body. Use for multiple-line messages or multiple CTAs.
508
510
  - `layout="row"`: actions sit at the right edge, vertically centred with the body. Use for one-line messages with a single trailing CTA.
511
+ - `announce: boolean | null = null` resolves input → `DS_CONFIG.banner.announce` → `false`. Dev mode warns once per instance in two cases: an `error` / `warning` / `severe` banner left unbound while the key is unset (ends when the key is set, `true` or `false`), and an `info` / `success` / `neutral` banner that announces only because the key is `true` (ends at an `[announce]` binding). Neither message reaches a production build.
509
512
 
510
513
  <!-- inputs:ds-banner -->
511
514
  All inputs: `variant: BannerVariant = 'info'`, `title: string = ''`, `dismissible: boolean = false`, `icon: IconName | null = null`, `compact: boolean = false`, `layout: 'stacked' | 'row' = 'stacked'`, `accentRail: boolean = true`, `announce: boolean | null = null`
@@ -516,6 +519,7 @@ Inline message, `ds-banner`'s smaller twin — same anatomy, sized for placement
516
519
  Inputs: `variant: 'info' | 'success' | 'warning' | 'error' | 'neutral' = 'info'`, `title: string = ''`, `dismissible: boolean = false`, `icon: IconName | null = null` (variant-derived default)
517
520
  Output: `(closed): void`
518
521
  Content slots: default (body text), `[actions]` (trailing CTAs)
522
+ - `announce` follows `DS_CONFIG.alert.announce` with the same two dev warnings as `ds-banner`, prefixed `[ds-alert]`.
519
523
 
520
524
  <!-- inputs:ds-alert -->
521
525
  All inputs: `variant: 'info' | 'success' | 'warning' | 'error' | 'neutral' = 'info'`, `title: string = ''`, `dismissible: boolean = false`, `icon: IconName | null = null`, `announce: boolean | null = null`
@@ -571,6 +575,8 @@ All inputs: `nodes: readonly TreeNode[] = []`, `expandedIds: Set<string>`, `sele
571
575
  <!-- /inputs -->
572
576
 
573
577
  #### `<ds-description-list>` — `DescriptionListComponent`
578
+ **A horizontal list stacks when a value would get too narrow.** Each item is a wrapping flex row: once the list is narrower than label width + column gap + `--ds-description-list-value-min-width` (14rem), every item puts its label above its value at once, and the switch follows `--ds-description-list-label-width` by itself. A standalone `ds-description-item` switches the same way at its own width. In a parent that sizes to its content (inline-block, float, absolute position, a flex row item with an auto basis, an `auto` grid track) a list whose widest value is under the minimum stacks; give it a width there. `orientation="stacked"` stacks at every width.
579
+ Tokens: `--ds-description-list-label-width`, `--ds-description-list-column-gap`, `--ds-description-list-row-gap`, `--ds-description-list-value-min-width`
574
580
 
575
581
  <!-- inputs:ds-description-list -->
576
582
  All inputs: `orientation: 'horizontal' | 'stacked' = 'horizontal'`
@@ -620,30 +626,30 @@ Content slots: `[title]`, `[breadcrumbs]`, `[search]`, `[actions]`. Sits at `--t
620
626
  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.
621
627
 
622
628
  #### `<ds-app-layout>` — `AppLayoutComponent`
623
- 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'`
629
+ Inputs: `topbarSpan: 'content' | 'full' = 'content'`, `railOpen: model<boolean> = false` (the overlay rail below `--bp-lg`), `railLabel: string | null = null` (unset: `DS_INTL.appLayout.railLabel`), `restoreScroll: boolean = false`, `restoreScrollTimeout: number = 2000` (ms), `scrollReset: 'path' | 'always' | 'never' = 'path'`
624
630
  Content slots: `[sidenav]`, `[topbar]`, default (the page)
625
631
  Reads: `railId` and the read-only `railOverlay` signal, for a consumer-built burger; `dsRailTrigger` wires one for you.
626
632
  Tokens: `--ds-app-layout-padding-x`, `--ds-app-layout-padding-y`, `--ds-app-layout-content-max-width`, `--ds-app-layout-height`, `--ds-app-layout-rail-bg-color`, `--ds-app-layout-rail-shadow`, `--ds-app-layout-scrim-color`
627
633
  It owns the app's scroll CONTAINER, so a screen that needs to move the scroll calls `AppLayoutScrollService` rather than touching `window`.
628
634
 
629
635
  <!-- inputs:ds-app-layout -->
630
- All inputs: `topbarSpan: 'content' | 'full' = 'content'`, `railOpen: boolean = false`, `railLabel: string = 'Navigation'`, `restoreScroll: boolean = false`, `restoreScrollTimeout: number = 2000`, `scrollReset: 'path' | 'never' | 'always' = 'path'`
636
+ All inputs: `topbarSpan: 'content' | 'full' = 'content'`, `railOpen: boolean = false`, `railLabel: string | null = null`, `restoreScroll: boolean = false`, `restoreScrollTimeout: number = 2000`, `scrollReset: 'path' | 'never' | 'always' = 'path'`
631
637
  <!-- /inputs -->
632
638
 
633
639
  #### `<ds-auth-layout>` — `AuthLayoutComponent`
634
- Inputs: `brand: string | null = null`, `logoLetter: string | null = null`, `tagline: string | null = null` (all three fall back to `DS_CONFIG.brand`), `cardElevation: CardElevation = 'raised'`, `cardPadding: CardPadding = 'lg'`, `landmark: 'main' | 'none' = 'none'`
640
+ Inputs: `brand: string | null = null`, `logoLetter: string | null = null`, `tagline: string | null = null` (all three fall back to `DS_CONFIG.brand`), `cardElevation: CardElevation = 'raised'`, `cardPadding: CardPadding = 'lg'`, `landmark: 'main' | 'none' = 'main'`
635
641
  Content slots: `[brand]` (replaces the whole mark row), `[dsBrandName]` (the name beside the generated mark), default (the card body), `[dsAuthSupport]` (the line under the card)
636
- Tokens: `--ds-auth-layout-min-height`, `--ds-auth-layout-bg-color`, `--ds-auth-layout-gap`, `--ds-auth-layout-padding-block`, `--ds-auth-layout-card-max-width`, `--ds-auth-layout-mark-size`, `--ds-auth-layout-mark-radius`, `--ds-auth-layout-mark-bg-color`, `--ds-auth-layout-mark-label-color`
637
- `landmark="main"` only when the page has no other `<main>`; the sign-in card is not automatically the document's main landmark.
642
+ Tokens: `--ds-auth-layout-min-height`, `--ds-auth-layout-bg-color`, `--ds-auth-layout-gap`, `--ds-auth-layout-padding-block`, `--ds-auth-layout-card-max-width`, `--ds-auth-layout-mark-size`, `--ds-auth-layout-mark-radius`, `--ds-auth-layout-mark-bg-color`, `--ds-auth-layout-mark-label-color`, `--ds-auth-layout-mark-font-size`, `--ds-auth-layout-brand-name-font-size`, `--ds-auth-layout-brand-max-height`
643
+ `landmark="none"` when the page already has a `<main>` (inside `ds-app-layout`, for one); by default the card is the page's main landmark.
638
644
 
639
645
  <!-- inputs:ds-auth-layout -->
640
- All inputs: `brand: string | null = null`, `logoLetter: string | null = null`, `tagline: string | null = null`, `cardElevation: 'flat' | 'raised' | 'hover' | 'interactive' = 'raised'`, `cardPadding: 'none' | 'sm' | 'md' | 'lg' = 'lg'`, `landmark: 'main' | 'none' = 'none'`
646
+ All inputs: `brand: string | null = null`, `logoLetter: string | null = null`, `tagline: string | null = null`, `cardElevation: 'flat' | 'raised' | 'hover' | 'interactive' = 'raised'`, `cardPadding: 'none' | 'sm' | 'md' | 'lg' = 'lg'`, `landmark: 'main' | 'none' = 'main'`
641
647
  <!-- /inputs -->
642
648
 
643
649
  #### `<ds-page-header>` — `PageHeaderComponent`
644
650
  Inputs: `eyebrow: string = ''`, `title: required string`, `subtitle: string = ''`, `compact: boolean = false`, `divider: boolean = false`, `metaDivider: boolean = false`
645
651
  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)
646
- 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-font-size` (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)`.
652
+ 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-font-size` (default `--font-size-h3`; `compact` flips to `--font-size-h4`), `--ds-page-header-subtitle-font-size` (default `--font-size-s`). 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)`.
647
653
 
648
654
  <!-- inputs:ds-page-header -->
649
655
  All inputs: `eyebrow: string = ''`, `title: string = ''`, `subtitle: string = ''`, `compact: boolean = false`, `divider: boolean = false`, `metaDivider: boolean = false`
@@ -669,6 +675,7 @@ All inputs: `items: BreadcrumbItem[] | null = null`, `separator: IconName | null
669
675
  Container holds `<ds-tab label="…">` children.
670
676
  Tabs inputs: `selectedIndex: model<number> = 0`, `variant: 'line' | 'pills' = 'line'`
671
677
  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.
678
+ `scrollable` scrolls a horizontal strip inside its own box and, while tabs lie beyond an edge, shows a previous/next arrow on that side that turns the strip by a page (hidden at its own edge; no arrows on a strip that fits). The arrows are pointer affordances outside the tab order and hidden from assistive technology, since arrow keys already bring the selected tab into view.
672
679
  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-padding-x`, `--ds-tab-padding-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).
673
680
 
674
681
  <!-- inputs:ds-tabs -->
@@ -683,7 +690,7 @@ All inputs: `steps: readonly string[] = []`, `current: number = 0`, `labelPositi
683
690
  <!-- /inputs -->
684
691
 
685
692
  #### `<ds-pagination>` — `PaginationComponent`
686
- Inputs: `total: required number`, `pageSize: model<number> = 10`, `currentPage: model<number> = 1`, `pageSizeOptions: number[] = [10, 25, 50, 100]`, `showLabel: boolean = true`, `size: DsSize | null = null` (unset resolves `DS_CONFIG.pagination.size`, then `DS_CONFIG.control.size`, then `sm`), `layout: PaginationLayout | null = null` (`'grouped' | 'spread'`; unset resolves `DS_CONFIG.pagination.layout`, then `'grouped'`; `'spread'` gives the nav full width and pushes the label and the controls to opposite edges), `loading: boolean = false` (every control disables, the range label is masked with a `ds-skeleton` so a stale `total` is never quoted, and the nav reports `aria-busy`). Inside `ds-table` `size` and `layout` arrive as `paginationSize` / `paginationLayout`, and `loading` is set from `loading="skeleton"`.
693
+ Inputs: `total: required number`, `pageSize: model<number> = 10`, `currentPage: model<number> = 1`, `pageSizeOptions: number[] = [10, 25, 50, 100]`, `showLabel: boolean = true`, `size: DsSize | null = null` (unset resolves `DS_CONFIG.pagination.size`, then `DS_CONFIG.control.size`, then `sm`), `layout: PaginationLayout | null = null` (`'grouped' | 'spread'`; unset resolves `DS_CONFIG.pagination.layout`, then `'grouped'`; `'spread'` gives the nav full width and pushes the label and the controls to opposite edges), `loading: boolean = false` (every control disables, the range label is masked with a `ds-skeleton` so a stale `total` is never quoted, and the nav reports `aria-busy`). Inside `ds-table` `size` and `layout` arrive as `paginationSize` / `paginationLayout`, and `loading` is set from `loading="skeleton"`. With `total` at 0 the label is `DS_INTL.pagination.range(0, 0, 0)`, `Showing 0 of 0` by default, and every page button is disabled with none marked current.
687
694
  Outputs: `(currentPageChange): number`, `(pageSizeChange): number`
688
695
 
689
696
  <!-- inputs:ds-pagination -->
@@ -744,10 +751,10 @@ All inputs: `elevation: 'flat' | 'raised' | 'hover' | 'interactive' = null`, `pa
744
751
  <!-- /inputs -->
745
752
 
746
753
  #### `<ds-accordion>` + `<ds-accordion-item>` — `AccordionComponent`, `AccordionItemComponent`
747
- 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).
754
+ 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). `chevron: 'right' | 'down' = 'right'` on `<ds-accordion>` sets every item's chevron: `right` turns down when an item opens, `down` turns up. Header geometry and type are tokens on the item (`--ds-accordion-header-padding`, `-header-gap`, `-header-font-family` / `-font-size` / `-font-weight` / `-line-height`, `-header-hover-text-color`) and so is the body padding (`--ds-accordion-body-padding`); both padding tokens take the CSS shorthand, as `--ds-card-padding` does.
748
755
 
749
756
  <!-- inputs:ds-accordion -->
750
- All inputs: `multiple: boolean = true`
757
+ All inputs: `multiple: boolean = true`, `chevron: 'right' | 'down' = 'right'`
751
758
  <!-- /inputs -->
752
759
 
753
760
  ---
@@ -804,9 +811,9 @@ All inputs: `align: 'start' | 'end' = 'start'`, `placement: 'top' | 'bottom' | '
804
811
  <!-- /inputs -->
805
812
 
806
813
  #### `[dsTooltip]` — `TooltipDirective`
807
- Attribute directive. Apply to any focusable element.
808
- Inputs: `dsTooltip: string = ''` (the text; empty disables), `dsTooltipPlacement: 'top' | 'bottom' | 'left' | 'right' = 'top'`, `dsTooltipDelay: number = 120` (ms)
809
- Renders `<ds-tooltip-panel>` via CDK overlay on hover / focus; hides on leave / blur.
814
+ Attribute directive. Apply to any focusable element; with `dsTooltipWhenClipped` also to a label that cannot take focus.
815
+ Inputs: `dsTooltip: string = ''` (the text; empty disables), `dsTooltipPlacement: 'top' | 'bottom' | 'left' | 'right' = 'top'`, `dsTooltipDelay: number = 120` (ms), `dsTooltipWhenClipped` (open only while the host shows less text than it holds; an empty `dsTooltip` then discloses the host's own text)
816
+ Renders `<ds-tooltip-panel>` via CDK overlay on hover / focus; hides on leave / blur. A `dsTooltipWhenClipped` host that cannot take focus (a label inside a button, a cell of a clickable row) also opens when keyboard focus lands on its nearest focusable ancestor, and closes on that ancestor's blur, click or any key; a mouse click opens nothing, and of several clipped hosts in one ancestor only the first in document order opens. A clipped tip whose text the host already contains sets no `aria-describedby` (the text is in the DOM already); a `dsTooltip` that says more than the host, and a plain `dsTooltip`, describe the focused element. A plain `dsTooltip` on a non-focusable element stays hover-only: put an info tooltip on its own focusable element, not inside a button. The panel wraps a value with no break opportunity (a file name, an id) inside its max width.
810
817
 
811
818
  <!-- inputs:[dsTooltip] -->
812
819
  All inputs: `dsTooltip: string = ''`, `dsTooltipPlacement: 'top' | 'bottom' | 'left' | 'right' = 'top'`, `dsTooltipDelay: number = 120`, `dsTooltipWhenClipped: boolean = false`
@@ -837,11 +844,11 @@ Opening a row: give one column `link: (row) => <route target> | null` and its va
837
844
  Cell templates: `<ng-template dsCellTemplate="<colKey>" [dsCellTemplateOf]="rows" let-row>…</ng-template>` — bound to the same rows as `[data]`, `dsCellTemplateOf` types `row` as `T` under strict templates (a field typo is a compile error) and is never read at runtime. Without it `row` is `unknown`; narrow via a helper method on the host. `CellTemplateContext<T>` (`$implicit` and `row`) is exported.
838
845
  Content slots: `[empty]` (rendered when `data.length === 0`), `[bulk-actions]` (rendered in the bulk action bar when `selectable && some selected`)
839
846
  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; under `'skeleton'` the footer pager takes `loading` as well - its controls disable and its range label is masked, so it never quotes the previous query's count. `'overlay'` leaves the pager live, like the header.
840
- Footer pager: `pageSizeOptions`, `showPageSize`, `showLabel`, `paginationSize: DsSize | null = null` and `paginationLayout: PaginationLayout | null = null` are the embedded `ds-pagination`'s own inputs forwarded one-to-one; the last two unset resolve `DS_CONFIG.pagination.size` (then `DS_CONFIG.control.size`, then `sm`) and `DS_CONFIG.pagination.layout` (then `'grouped'`), so an app whose every pager wants `md` / `spread` says it once in the config.
841
- 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-font-size: 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-padding-x/y`. (Renamed 2026-06: `--ds-table-header-*` → `--ds-table-head-*`, matching the tokens reference.)
847
+ Footer pager: `pageSizeOptions`, `showPageSize`, `showLabel`, `paginationSize: DsSize | null = null` and `paginationLayout: PaginationLayout | null = null` are the embedded `ds-pagination`'s own inputs forwarded one-to-one; the last two unset resolve `DS_CONFIG.pagination.size` (then `DS_CONFIG.control.size`, then `sm`) and `DS_CONFIG.pagination.layout` (then `'grouped'`), so an app whose every pager wants `md` / `spread` says it once in the config. A paged table with no rows announces its empty state's text (`[empty]` or `emptyTemplate`); with none it announces `rangeAnnouncement(0, 0, 0)`, `Showing 0 of 0` by default.
848
+ 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-font-size: 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-padding-x/y`, `--ds-table-utility-column-width` (the column the column picker and the row-actions ⋮ ride in; default `--space-6`, the buttons' own size, so the column is as wide as its padding makes it) and `--ds-table-utility-column-padding-x` (one length for both sides; default the cell padding chain), `--ds-table-footer-padding-y` / `-top` / `-bottom` (the pagination footer's block padding; default `--space-3`). (Renamed 2026-06: `--ds-table-header-*` → `--ds-table-head-*`, matching the tokens reference.)
842
849
 
843
850
  <!-- inputs:ds-table -->
844
- All inputs: `data: required readonly T[]`, `rowId: ((row: T) => string) | null = null`, `columns: required readonly TableColumn<T>[]`, `selectable: boolean = false`, `bordered: boolean | null = null`, `loading: boolean | 'skeleton' | 'overlay' = false`, `stickyHeader: boolean = true`, `maxHeight: string | null = null`, `density: 'default' | 'compact' = 'default'`, `zebra: boolean = false`, `animateHeight: boolean = false`, `selectedIds: Set<string>`, `sortKey: string | null = null`, `sortDirection: 'asc' | 'desc' = null`, `sortingOrder: SortDirection[]`, `sortAnnouncement: (label: string, dir: SortDirection) => string`, `rangeAnnouncement: (first: number, last: number, total: number) => string`, `skeletonRows: number = 5`, `caption: string = ''`, `rowInteractive: boolean = false`, `activeRowId: string | null = null`, `filterQuery: string = ''`, `columnFilters: Map<string, ReadonlySet<string>>`, `persistLayout: boolean = false`, `storageKey: string = ''`, `stickyScrollbar: boolean | null = null`, `pageSize: number | null = null`, `page: number = 1`, `pageSizeOptions: number[]`, `showPageSize: boolean = true`, `showLabel: boolean = true`, `paginationSize: 'sm' | 'md' | 'lg' = null`, `paginationLayout: 'grouped' | 'spread' = null`, `total: number | null = null`, `scrollToTopOnPageChange: boolean = false`, `sortMode: 'client' | 'server' | 'none' = null`, `filterMode: 'client' | 'server' | 'none' = null`, `columnFilterOptions: ReadonlyMap<string, readonly string[]>`, `stickyScrollbarOffset: string | null = null`, `stickyFirstColumn: boolean = false`, `virtualScroll: boolean = false`, `virtualRowSize: number = 44`, `lazy: boolean = false`, `rowActions: readonly TableRowAction<T>[] = []`, `cellTemplateMap: Record<string, TemplateRef<{ $implicit: unknown; row: unknown }>> = {}`, `emptyTemplate: TemplateRef<unknown> | null = null`, `expandableRows: boolean = false`, `expandedIds: Set<string>`, `expandMode: 'multiple' | 'single' = 'multiple'`, `expandAllToggle: boolean = false`, `rowExpandTemplate: TemplateRef<{
851
+ All inputs: `data: required readonly T[]`, `rowId: ((row: T) => string) | null = null`, `columns: required readonly TableColumn<T>[]`, `selectable: boolean = false`, `bordered: boolean | null = null`, `loading: boolean | 'skeleton' | 'overlay' = false`, `stickyHeader: boolean = true`, `maxHeight: string | null = null`, `density: 'default' | 'compact' = 'default'`, `zebra: boolean = false`, `animateHeight: boolean = false`, `selectedIds: Set<string>`, `sortKey: string | null = null`, `sortDirection: 'asc' | 'desc' = null`, `sortingOrder: SortDirection[]`, `sortAnnouncement: ((label: string, dir: SortDirection) => string) | null = null`, `rangeAnnouncement: ((first: number, last: number, total: number) => string) | null = null`, `skeletonRows: number = 5`, `caption: string = ''`, `rowInteractive: boolean = false`, `activeRowId: string | null = null`, `filterQuery: string = ''`, `columnFilters: Map<string, ReadonlySet<string>>`, `persistLayout: boolean = false`, `storageKey: string = ''`, `stickyScrollbar: boolean | null = null`, `pageSize: number | null = null`, `page: number = 1`, `pageSizeOptions: number[]`, `showPageSize: boolean = true`, `showLabel: boolean = true`, `paginationSize: 'sm' | 'md' | 'lg' = null`, `paginationLayout: 'grouped' | 'spread' = null`, `total: number | null = null`, `scrollToTopOnPageChange: boolean = false`, `sortMode: 'client' | 'server' | 'none' = null`, `filterMode: 'client' | 'server' | 'none' = null`, `columnFilterOptions: ReadonlyMap<string, readonly string[]>`, `stickyScrollbarOffset: string | null = null`, `stickyFirstColumn: boolean = false`, `virtualScroll: boolean = false`, `virtualRowSize: number = 44`, `lazy: boolean = false`, `rowActions: readonly TableRowAction<T>[] = []`, `cellTemplateMap: Record<string, TemplateRef<{ $implicit: unknown; row: unknown }>> = {}`, `emptyTemplate: TemplateRef<unknown> | null = null`, `expandableRows: boolean = false`, `expandedIds: Set<string>`, `expandMode: 'multiple' | 'single' = 'multiple'`, `expandAllToggle: boolean = false`, `rowExpandTemplate: TemplateRef<{
845
852
  $implicit: unknown;
846
853
  row: unknown;
847
854
  }> | null = null`
@@ -876,28 +883,29 @@ All inputs: `dsTableExport: boolean = true`, `exportFilename: string = 'table.cs
876
883
  ### Charts
877
884
 
878
885
  #### `<ds-bar-chart>` — `BarChartComponent`
879
- Inputs: `data: readonly BarChartRow[]` (required), `max: number | null = null` (track length is relative to this; null uses the largest value, so the longest row always fills its track — a max BELOW the largest value is allowed and its bar clips at the track edge), `caption: string | null = null`, `summary: string | null = null` (accessible name; generated from the data when omitted), `dataTable: 'none' | 'toggle' | 'visible' = 'none'` (`'toggle'` renders a closed `<details>`; `'none'` is only correct when the same numbers are already in the DOM nearby), `showPercent: boolean = true`, `loading: boolean = false`, `emptyText: string = 'No data'`, `error: boolean = false`, `errorText: string = 'Could not load the data'`, `valueFormat: (value: number) => string`, `interactive: boolean = false`, `tooltip: 'item' | 'none' = 'item'`, `staggerMs: number = 0`
886
+ Inputs: `data: readonly BarChartRow[]` (required), `max: number | null = null` (track length is relative to this; null uses the largest value, so the longest row always fills its track — a max BELOW the largest value is allowed and its bar clips at the track edge), `caption: string | null = null`, `summary: string | null = null` (accessible name; generated from the data when omitted), `dataTable: 'none' | 'toggle' | 'visible' = 'none'` (`'toggle'` renders a closed `<details>`; `'none'` is only correct when the same numbers are already in the DOM nearby), `showPercent: boolean = true`, `loading: boolean = false`, `emptyText: string = 'No data'`, `error: boolean = false`, `errorText: string = 'Could not load the data'`, `valueFormat: (value: number) => string`, `interactive: boolean = false`, `tooltip: 'item' | 'none' = 'item'`, `staggerMs: number = 40`
880
887
  Output: `(rowClicked): BarChartRow` — emits the clicked row.
881
888
  Interaction: `interactive: boolean = false` turns on the affordance — pointer cursor, hover tint and the keyboard route. `dimOthers: boolean = false` is a SEPARATE opt-in that fades every other mark while one is hovered or focused; off by default, because the fade costs the separation between the faded marks (dE 14.8 -> 2.1 at the default dim opacity) — it buys loudness for one mark and pays for it with the rest. The output fires whether or not it is set. The keyboard route is ONE tab stop for the whole chart, not one per mark: arrows walk the marks, Home and End reach the extremes, and the ends wrap. `tooltip: 'item' | 'none' = 'item'` opens a panel for the hovered, tapped or focused mark; a tap latches it until the next tap outside. Project an `<ng-template #dsChartTooltip let-tip>` to replace its contents — `tip` is `{ category: string; entries: { label, value, formatted, color }[] }`.
882
- Motion: marks that leave finish leaving before marks that arrive start. `staggerMs: number = 0` spaces the arrivals; `40` is the documented step and the total is capped at 300ms. Every duration is a `--ds-motion-chart-*` role, so `prefers-reduced-motion` zeroes them with nothing per chart.
889
+ Motion: marks that leave finish leaving before marks that arrive start. A bar grows out of the value axis, then its value rises in. `staggerMs: number = 40` spaces the arrivals, narrowed so a series finishes arriving within 260ms; `0` brings every mark in at once. Every duration is a `--ds-motion-chart-*` role, so `prefers-reduced-motion` shows every mark at once, delays included.
883
890
  States: `loading` draws skeleton marks at the real count; `error` shows `errorText` in place of the plot, which is a different claim from an empty `data` showing `emptyText`.
884
891
  Row: `BarChartRow = { label: string; value: number; percent?: number; color?: string }`. `percent` is derived from `value / max` when omitted.
885
892
  `value` may be a `[low, high]` pair instead of a number: the bar spans between its own ends rather than from zero, which compares a duration and its PLACEMENT at once, and the ends may be written either way round. `target` draws a tick across the bar at one reading; `ranges` paints qualitative bands behind it, given as their upper bounds in ascending order. Together they are the bullet chart, which is a bar with two extras rather than a chart type. The bands take one neutral hue at rising opacity, never the series palette. Tokens: `--ds-bar-chart-band-color`, `--ds-bar-chart-target-color`, `--ds-bar-chart-target-width`, `--ds-bar-chart-target-overhang`.
886
893
  Colour: the rows are ONE series, so they all take `--ds-chart-series-default-color`. Set `color` on the single row the reader should land on, usually to `var(--ds-chart-series-accent-color)`. There is no accent flag — the accent is a colour, so a boolean would only be a less flexible way of setting one. Do NOT reach for `--ds-chart-series-1-color` … `-8-color` here: those separate series from one another, and a bar chart's rows are not separate series.
894
+ Segments: `segments?: BarChartSegment[]` divides a row's bar into parts sized against their own sum; each takes the categorical palette in order and gets its own nested row in the data table. `highlighted: string | null = null` names one segment by `id` (or its position as a string) and fades every other part in every row to `--ds-chart-dim-opacity` — the same input the series marks take.
887
895
  Behaviour: a non-finite value draws no bar and prints `—`; a negative value clamps to an empty bar; a share too small for one decimal prints `<0.1%` rather than `0.0%`.
888
896
  Rhythm: a label belongs to the bar under it, so `--ds-bar-chart-label-gap` is deliberately much smaller than `--ds-bar-chart-row-gap`. Level the two and the eye starts grouping a bar with the label BELOW it, which reads every row off by one.
889
897
  Tokens: `--ds-bar-chart-track-color`, `--ds-bar-chart-track-height`, `--ds-bar-chart-row-gap`, `--ds-bar-chart-label-gap`.
890
898
 
891
899
  <!-- inputs:ds-bar-chart -->
892
- All inputs: `data: required readonly BarChartRow[]`, `max: number | null = null`, `frame: 'auto' | 'none' = null`, `tooltipLingerMs: number | null = null`, `caption: string | null = null`, `summary: string | null = null`, `dataTable: 'toggle' | 'visible' | 'none' = null`, `partOfWhole: boolean = false`, `showPercent: boolean = true`, `loading: boolean = false`, `emptyText: string | null = null`, `error: boolean = false`, `errorText: string | null = null`, `valueFormat: ChartValueFormat | null = null`, `interactive: boolean = false`, `pinOnClick: boolean = false`, `dimOthers: boolean = false`, `staggerMs: number = 0`, `tooltip: 'item' | 'none' = 'item'`
900
+ All inputs: `data: required readonly BarChartRow[]`, `max: number | null = null`, `frame: 'auto' | 'none' = null`, `tooltipLingerMs: number | null = null`, `caption: string | null = null`, `summary: string | null = null`, `dataTable: 'toggle' | 'visible' | 'none' = null`, `partOfWhole: boolean = false`, `showPercent: boolean = true`, `loading: boolean = false`, `emptyText: string | null = null`, `error: boolean = false`, `errorText: string | null = null`, `valueFormat: ChartValueFormat | null = null`, `pinOnClick: boolean | null = null`, `interactive: boolean = false`, `dimOthers: boolean = false`, `highlighted: string | null = null`, `staggerMs: number = 40`, `tooltip: 'item' | 'none' = 'item'`
893
901
  <!-- /inputs -->
894
902
 
895
903
  #### `<ds-column-chart>` — `ColumnChartComponent`
896
904
  Vertical columns for a short series read left to right — months, stages, teams — measured against one value axis whose ticks snap to round numbers.
897
- Inputs: `data: readonly ColumnChartPoint[]` (required), `showValues: boolean = true` (each column prints its own value above itself), `tickCount: number = 5` (a hint: ticks snap to a round step, so an axis asked for three ends up with five and one asked for ten stops at eight), `caption: string | null = null`, `summary: string | null = null`, `dataTable: 'none' | 'toggle' | 'visible' = 'none'`, `loading: boolean = false`, `emptyText: string = 'No data'`, `error: boolean = false`, `errorText: string = 'Could not load the data'`, `valueFormat: (value: number) => string`, `interactive: boolean = false`, `tooltip: 'item' | 'none' = 'item'`, `staggerMs: number = 0`, `thresholds: readonly ChartThreshold[] = []`
905
+ Inputs: `data: readonly ColumnChartPoint[]` (required), `showValues: boolean = true` (each column prints its own value above itself), `tickCount: number = 5` (a hint: ticks snap to a round step, so an axis asked for three ends up with five and one asked for ten stops at eight), `caption: string | null = null`, `summary: string | null = null`, `dataTable: 'none' | 'toggle' | 'visible' = 'none'`, `loading: boolean = false`, `emptyText: string = 'No data'`, `error: boolean = false`, `errorText: string = 'Could not load the data'`, `valueFormat: (value: number) => string`, `interactive: boolean = false`, `tooltip: 'item' | 'none' = 'item'`, `staggerMs: number = 40`, `thresholds: readonly ChartThreshold[] = []`
898
906
  Output: `(pointClicked): ColumnChartPoint` — same contract as `ds-bar-chart`'s `rowClicked`.
899
907
  Interaction: `interactive: boolean = false` turns on the affordance — pointer cursor, hover tint and the keyboard route. `dimOthers: boolean = false` is a SEPARATE opt-in that fades every other mark while one is hovered or focused; off by default, because the fade costs the separation between the faded marks (dE 14.8 -> 2.1 at the default dim opacity) — it buys loudness for one mark and pays for it with the rest. The output fires whether or not it is set. The keyboard route is ONE tab stop for the whole chart, not one per mark: arrows walk the marks, Home and End reach the extremes, and the ends wrap. `tooltip: 'item' | 'none' = 'item'` opens a panel for the hovered, tapped or focused mark; a tap latches it until the next tap outside. Project an `<ng-template #dsChartTooltip let-tip>` to replace its contents — `tip` is `{ category: string; entries: { label, value, formatted, color }[] }`.
900
- Motion: marks that leave finish leaving before marks that arrive start. `staggerMs: number = 0` spaces the arrivals; `40` is the documented step and the total is capped at 300ms. Every duration is a `--ds-motion-chart-*` role, so `prefers-reduced-motion` zeroes them with nothing per chart.
908
+ Motion: marks that leave finish leaving before marks that arrive start. A column grows out of its baseline, then its value rises in. `staggerMs: number = 40` spaces the arrivals, narrowed so a series finishes arriving within 260ms; `0` brings every mark in at once. Every duration is a `--ds-motion-chart-*` role, so `prefers-reduced-motion` shows every mark at once, delays included.
901
909
  States: `loading` draws skeleton marks at the real count; `error` shows `errorText` in place of the plot, which is a different claim from an empty `data` showing `emptyText`.
902
910
  Point: `ColumnChartPoint = { label: string; value: number; color?: string }`
903
911
  Thresholds: `ChartThreshold = { value: number; label?: string; color?: string; to?: number; dash?: 'solid' | 'dashed' | 'dotted' }` draws a target, a budget or an SLA across the plot, behind the columns. ONE number, not a coordinate pair; `to` makes the same object a band between two readings, in either order; `dash` defaults to `'dashed'`. A threshold widens the value axis to hold it, and is named in the generated description, so a target above every column is neither drawn off the plot nor left unsaid.
@@ -905,33 +913,34 @@ Colour: the categorical palette by position — `--ds-chart-series-1-color` onwa
905
913
  Tokens: `--ds-column-chart-plot-height`, `--ds-column-chart-column-width` (share of its own cell), `--ds-column-chart-column-max-width` (the cap that stops a five-column chart drawing slabs wider than their labels), `--ds-column-chart-column-gap`, `--ds-column-chart-grid-line-color`, `--ds-column-chart-value-space` (headroom for the value printed above a full-height column), `--ds-column-chart-axis-width` (the tick-label column; widen it for a `valueFormat` that prints longer ticks, which are clipped rather than wrapped). Reference lines take `--ds-chart-threshold-color`, `--ds-chart-threshold-band-opacity`, `--ds-chart-threshold-dashed-pattern` and `--ds-chart-threshold-dotted-pattern`.
906
914
 
907
915
  <!-- inputs:ds-column-chart -->
908
- All inputs: `data: required readonly ColumnChartPoint[] | readonly ColumnChartSeries[]`, `stack: 'none' | 'grouped' | 'stacked' | 'normalized' = 'none'`, `thresholds: readonly ChartThreshold[] = []`, `showValues: boolean = true`, `tickCount: number = 5`, `frame: 'auto' | 'none' = null`, `tooltipLingerMs: number | null = null`, `caption: string | null = null`, `summary: string | null = null`, `dataTable: 'toggle' | 'visible' | 'none' = null`, `partOfWhole: boolean = false`, `loading: boolean = false`, `emptyText: string | null = null`, `error: boolean = false`, `errorText: string | null = null`, `valueFormat: ChartValueFormat | null = null`, `interactive: boolean = false`, `pinOnClick: boolean = false`, `dimOthers: boolean = false`, `staggerMs: number = 0`, `tooltip: 'item' | 'none' = 'item'`, `tooltipAnchor: 'mark' | 'cell' = 'mark'`
916
+ All inputs: `data: required readonly ColumnChartPoint[] | readonly ColumnChartSeries[]`, `stack: 'none' | 'grouped' | 'stacked' | 'normalized' = 'none'`, `thresholds: readonly ChartThreshold[] = []`, `showValues: boolean = true`, `tickCount: number = 5`, `frame: 'auto' | 'none' = null`, `tooltipLingerMs: number | null = null`, `caption: string | null = null`, `summary: string | null = null`, `dataTable: 'toggle' | 'visible' | 'none' = null`, `partOfWhole: boolean = false`, `loading: boolean = false`, `emptyText: string | null = null`, `error: boolean = false`, `errorText: string | null = null`, `valueFormat: ChartValueFormat | null = null`, `interactive: boolean = false`, `pinOnClick: boolean | null = null`, `dimOthers: boolean = false`, `staggerMs: number = 40`, `tooltip: 'item' | 'none' = 'item'`, `tooltipAnchor: 'mark' | 'cell' = 'mark'`
909
917
  <!-- /inputs -->
910
918
 
911
919
  #### `<ds-pie-chart>` — `PieChartComponent`
912
920
  A ring that splits one total into its parts, with the middle free for the total or a headline figure of your own.
913
- Inputs: `data: readonly PieChartSlice[]` (required), `centerValue: string | null = null`, `centerLabel: string | null = null`, `legend: 'end' | 'bottom' | 'none' = 'end'`, `maxSlices: number | null = null`, `otherLabel: string = 'Other'`, `innerRadius: number = 0.68`, `caption: string | null = null`, `summary: string | null = null`, `dataTable: 'none' | 'toggle' | 'visible' = 'none'`, `loading: boolean = false`, `emptyText: string = 'No data'`, `error: boolean = false`, `errorText: string = 'Could not load the data'`, `valueFormat: (value: number) => string`, `interactive: boolean = false`, `tooltip: 'item' | 'none' = 'item'`, `staggerMs: number = 0`
921
+ Inputs: `data: readonly PieChartSlice[]` (required), `centerValue: string | null = null`, `centerLabel: string | null = null`, `legend: 'end' | 'bottom' | 'none' = 'end'`, `maxSlices: number | null = null`, `otherLabel: string | null = null` (unset: `DS_INTL.chart.other`), `innerRadius: number = 0.68`, `caption: string | null = null`, `summary: string | null = null`, `dataTable: 'none' | 'toggle' | 'visible' = 'none'`, `loading: boolean = false`, `emptyText: string = 'No data'`, `error: boolean = false`, `errorText: string = 'Could not load the data'`, `valueFormat: (value: number) => string`, `interactive: boolean = false`, `tooltip: 'item' | 'none' = 'item'`, `staggerMs: number = 0`
914
922
  Output: `(sliceClicked): PieChartSlice`
915
923
  Interaction: `interactive: boolean = false` turns on the affordance — pointer cursor, hover tint and the keyboard route. `dimOthers: boolean = false` is a SEPARATE opt-in that fades every other mark while one is hovered or focused; off by default, because the fade costs the separation between the faded marks (dE 14.8 -> 2.1 at the default dim opacity) — it buys loudness for one mark and pays for it with the rest. The output fires whether or not it is set. The keyboard route is ONE tab stop for the whole chart, not one per mark: arrows walk the marks, Home and End reach the extremes, and the ends wrap. `tooltip: 'item' | 'none' = 'item'` opens a panel for the hovered, tapped or focused mark; a tap latches it until the next tap outside. Project an `<ng-template #dsChartTooltip let-tip>` to replace its contents — `tip` is `{ category: string; entries: { label, value, formatted, color }[] }`.
916
- Motion: the RING fades as one object rather than slice by slice — arcs share their edges, and fading them one at a time lets the background through every seam. `staggerMs` is accepted for parity with the other four charts and has no effect here, because there is nothing to stagger. Marks that leave finish leaving before marks that arrive start. `staggerMs: number = 0` spaces the arrivals; `40` is the documented step and the total is capped at 300ms. Every duration is a `--ds-motion-chart-*` role, so `prefers-reduced-motion` zeroes them with nothing per chart.
924
+ Motion: the RING turns into place as one object rather than slice by slice - arcs share their edges, and moving them one at a time lets the background through every seam. The legend swatches and the centre follow once it has landed. `staggerMs` is accepted for parity with the other charts and has no effect here, because there is nothing to stagger. Marks that leave finish leaving before marks that arrive start. Every duration is a `--ds-motion-chart-*` role, so `prefers-reduced-motion` shows the ring at once.
917
925
  States: `loading` draws skeleton marks at the real count; `error` shows `errorText` in place of the plot, which is a different claim from an empty `data` showing `emptyText`.
918
926
  Slice: `PieChartSlice = { id: string; label: string; value: number; slot?: number }`. `slot` is a 1-based palette slot: pinning a slice keeps every other slice's colour where it is when one is filtered out of `data`; left off, the colour follows the index and the whole ring repaints.
919
927
  Colour: slices ARE different things, so this is the chart the categorical palette exists for — `--ds-chart-series-1-color` … `--ds-chart-series-8-color`.
928
+ Legend: an entry under the pointer or holding keyboard focus takes a tint and the primary text colour, and the other slices fade whatever `dimOthers` says - naming a slice in the legend singles it out the way every chart legend singles out its series.
920
929
  Behaviour: percentages use largest-remainder rounding, so a legend's shares add up to exactly 100 and a real non-zero slice never prints `0%`.
921
930
  `maxSlices` caps the legend: past it the smallest slices are summed into one named by `otherLabel`, which takes the neutral eighth palette slot. Off by default, because grouping changes what the chart says. The kept slices stay in the order given rather than being re-sorted by value, and the total is unchanged — the tail is summed, never dropped. A limit below 2 is ignored.
922
931
  `innerRadius: 0` closes the hole into a pie, and the centre content goes with it: `centerValue` and `centerLabel` render only where there is a hole to hold them. A value outside [0, 1) falls back to the default rather than drawing nothing. The centre box is held to the square that fits inside the hole with a 56% floor, so a long value can overhang the ring; a halo of the chart's own background carries it there.
923
- Tokens: `--ds-pie-chart-size`, `--ds-pie-chart-gap`, `--ds-pie-chart-swatch-size`, `--ds-pie-chart-legend-row-gap`, `--ds-pie-chart-legend-row-height`, `--ds-pie-chart-outline-width` (the placeholder ring drawn when there is no data and when every slice is zero).
932
+ Tokens: `--ds-pie-chart-size`, `--ds-pie-chart-gap`, `--ds-pie-chart-swatch-size`, `--ds-pie-chart-legend-row-gap`, `--ds-pie-chart-legend-row-height`, `--ds-chart-legend-hover-bg-color` and `--ds-chart-legend-hover-text-color` (shared with every chart legend), `--ds-pie-chart-outline-width` (the placeholder ring drawn when there is no data and when every slice is zero).
924
933
 
925
934
  <!-- inputs:ds-pie-chart -->
926
- All inputs: `data: required readonly PieChartSlice[]`, `centerValue: string | null = null`, `centerLabel: string | null = null`, `legend: 'end' | 'bottom' | 'none' = 'end'`, `maxSlices: number | null = null`, `otherLabel: string = 'Other'`, `innerRadius: number = 0.68`, `frame: 'auto' | 'none' = null`, `tooltipLingerMs: number | null = null`, `caption: string | null = null`, `summary: string | null = null`, `dataTable: 'toggle' | 'visible' | 'none' = null`, `partOfWhole: boolean = true`, `loading: boolean = false`, `emptyText: string | null = null`, `error: boolean = false`, `errorText: string | null = null`, `valueFormat: ChartValueFormat | null = null`, `interactive: boolean = false`, `pinOnClick: boolean = false`, `dimOthers: boolean = false`, `staggerMs: number = 0`, `tooltip: 'item' | 'none' = 'item'`
935
+ All inputs: `data: required readonly PieChartSlice[]`, `centerValue: string | null = null`, `centerLabel: string | null = null`, `legend: 'end' | 'bottom' | 'none' = 'end'`, `maxSlices: number | null = null`, `otherLabel: string | null = null`, `innerRadius: number = 0.68`, `frame: 'auto' | 'none' = null`, `tooltipLingerMs: number | null = null`, `caption: string | null = null`, `summary: string | null = null`, `dataTable: 'toggle' | 'visible' | 'none' = null`, `partOfWhole: boolean = true`, `loading: boolean = false`, `emptyText: string | null = null`, `error: boolean = false`, `errorText: string | null = null`, `valueFormat: ChartValueFormat | null = null`, `pinOnClick: boolean | null = null`, `interactive: boolean = false`, `dimOthers: boolean = false`, `staggerMs: number = 0`, `tooltip: 'item' | 'none' = 'item'`
927
936
  <!-- /inputs -->
928
937
 
929
938
  #### `<ds-funnel-chart>` — `FunnelChartComponent`
930
939
  Stages of a journey, drawn top to bottom in the order you give them — they are never sorted, because the order is the meaning.
931
- Inputs: `data: readonly FunnelChartStage[]` (required), `shape: 'taper' | 'width' | 'area' = 'area'`, `showTable: boolean = true` (the aligned stage table under the funnel: value, share of the first stage, and how much fell away since the stage above), `caption: string | null = null`, `summary: string | null = null`, `dataTable: 'none' | 'toggle' | 'visible' = 'none'`, `loading: boolean = false`, `emptyText: string = 'No data'`, `error: boolean = false`, `errorText: string = 'Could not load the data'`, `valueFormat: (value: number) => string`, `interactive: boolean = false`, `tooltip: 'item' | 'none' = 'item'`, `staggerMs: number = 0`
940
+ Inputs: `data: readonly FunnelChartStage[]` (required), `shape: 'taper' | 'width' | 'area' = 'area'`, `showTable: boolean = true` (the aligned stage table under the funnel: value, share of the first stage, and how much fell away since the stage above), `caption: string | null = null`, `summary: string | null = null`, `dataTable: 'none' | 'toggle' | 'visible' = 'none'`, `loading: boolean = false`, `emptyText: string = 'No data'`, `error: boolean = false`, `errorText: string = 'Could not load the data'`, `valueFormat: (value: number) => string`, `interactive: boolean = false`, `tooltip: 'item' | 'none' = 'item'`, `staggerMs: number = 60`
932
941
  Output: `(stageClicked): FunnelChartStage`
933
942
  Interaction: `interactive: boolean = false` turns on the affordance — pointer cursor, hover tint and the keyboard route. `dimOthers: boolean = false` is a SEPARATE opt-in that fades every other mark while one is hovered or focused; off by default, because the fade costs the separation between the faded marks (dE 14.8 -> 2.1 at the default dim opacity) — it buys loudness for one mark and pays for it with the rest. The output fires whether or not it is set. The keyboard route is ONE tab stop for the whole chart, not one per mark: arrows walk the marks, Home and End reach the extremes, and the ends wrap. `tooltip: 'item' | 'none' = 'item'` opens a panel for the hovered, tapped or focused mark; a tap latches it until the next tap outside. Project an `<ng-template #dsChartTooltip let-tip>` to replace its contents — `tip` is `{ category: string; entries: { label, value, formatted, color }[] }`.
934
- Motion: marks that leave finish leaving before marks that arrive start. `staggerMs: number = 0` spaces the arrivals; `40` is the documented step and the total is capped at 300ms. Every duration is a `--ds-motion-chart-*` role, so `prefers-reduced-motion` zeroes them with nothing per chart.
943
+ Motion: marks that leave finish leaving before marks that arrive start. Stages rise in from the top, and each table row follows its stage. `staggerMs: number = 60` spaces the arrivals, narrowed so a series finishes arriving within 260ms; `0` brings every mark in at once. Every duration is a `--ds-motion-chart-*` role, so `prefers-reduced-motion` shows every mark at once, delays included.
935
944
  States: `loading` draws skeleton marks at the real count; `error` shows `errorText` in place of the plot, which is a different claim from an empty `data` showing `emptyText`.
936
945
  Stage: `FunnelChartStage = { id: string; label: string; value: number }`
937
946
  Shape: `'area'` is the default — the fixed silhouette with the stage boundaries moved so each band's AREA is proportional to its value, the honest encoding that still leaves a labellable tail. `'width'` reads every boundary straight off the values, which collapses the tail of a steep funnel below a labellable width. `'taper'` encodes NOTHING: the silhouette is fixed whatever the data, so editing the values moves the table and never the shape — reach for it only where the numbers are read from the table.
@@ -940,7 +949,7 @@ Colour: the stages are one quantity draining, not N categories, so they take the
940
949
  Tokens: `--ds-funnel-chart-stage-height`, `--ds-funnel-chart-stage-gap`, `--ds-funnel-chart-row-gap`.
941
950
 
942
951
  <!-- inputs:ds-funnel-chart -->
943
- All inputs: `data: required readonly FunnelChartStage[]`, `shape: 'taper' | 'width' | 'area' = 'area'`, `showTable: boolean = true`, `frame: 'auto' | 'none' = null`, `tooltipLingerMs: number | null = null`, `caption: string | null = null`, `summary: string | null = null`, `dataTable: 'toggle' | 'visible' | 'none' = null`, `drop: 'relative' | 'absolute' | 'none' = 'relative'`, `loading: boolean = false`, `emptyText: string | null = null`, `error: boolean = false`, `errorText: string | null = null`, `valueFormat: ChartValueFormat | null = null`, `interactive: boolean = false`, `pinOnClick: boolean = false`, `dimOthers: boolean = false`, `staggerMs: number = 0`, `tooltip: 'item' | 'none' = 'item'`
952
+ All inputs: `data: required readonly FunnelChartStage[]`, `shape: 'taper' | 'width' | 'area' = 'area'`, `showTable: boolean = true`, `frame: 'auto' | 'none' = null`, `tooltipLingerMs: number | null = null`, `caption: string | null = null`, `summary: string | null = null`, `dataTable: 'toggle' | 'visible' | 'none' = null`, `drop: 'relative' | 'absolute' | 'none' = 'relative'`, `loading: boolean = false`, `emptyText: string | null = null`, `error: boolean = false`, `errorText: string | null = null`, `valueFormat: ChartValueFormat | null = null`, `pinOnClick: boolean | null = null`, `interactive: boolean = false`, `dimOthers: boolean = false`, `staggerMs: number = 60`, `tooltip: 'item' | 'none' = 'item'`
944
953
  <!-- /inputs -->
945
954
 
946
955
  #### `<ds-heatmap-chart>` — `HeatmapChartComponent`
@@ -957,7 +966,7 @@ The grid scrolls sideways below its natural width rather than crushing the cells
957
966
  Tokens: `--ds-heatmap-chart-cell-size`, `--ds-heatmap-chart-cell-gap`, `--ds-heatmap-chart-cell-radius`, `--ds-heatmap-chart-label-color`, `--ds-heatmap-chart-label-font-size`, `--ds-heatmap-chart-missing-color`, `--ds-heatmap-chart-focus-color`, `--ds-heatmap-chart-focus-width`.
958
967
 
959
968
  <!-- inputs:ds-heatmap-chart -->
960
- All inputs: `columns: readonly string[] = []`, `data: readonly HeatmapChartRow[] = []`, `caption: string | null = null`, `min: number | null = null`, `max: number | null = null`, `showValues: boolean = false`, `interactive: boolean = false`, `dimOthers: boolean = false`, `frame: 'auto' | 'none' = null`, `loading: boolean = false`, `error: boolean = false`, `emptyText: string | null = null`, `errorText: string | null = null`, `valueFormat: ChartValueFormat | null = null`, `tooltip: 'item' | 'none' = 'item'`
969
+ All inputs: `columns: readonly string[] = []`, `data: readonly HeatmapChartRow[] = []`, `caption: string | null = null`, `min: number | null = null`, `max: number | null = null`, `showValues: boolean = false`, `interactive: boolean = false`, `dimOthers: boolean = false`, `pinOnClick: boolean | null = null`, `frame: 'auto' | 'none' = null`, `loading: boolean = false`, `error: boolean = false`, `emptyText: string | null = null`, `errorText: string | null = null`, `valueFormat: ChartValueFormat | null = null`, `tooltip: 'item' | 'none' = 'item'`, `staggerMs: number = 40`
961
970
  <!-- /inputs -->
962
971
 
963
972
  #### `<ds-scatter-chart>` — `ScatterChartComponent`
@@ -974,7 +983,7 @@ The budget is a gate, not a paragraph: the decimator is fed 100 000 readings and
974
983
  Tokens: `--ds-scatter-chart-grid-line-color`, `--ds-scatter-chart-axis-line-color`, `--ds-scatter-chart-axis-label-color`, `--ds-scatter-chart-axis-font-size`, `--ds-scatter-chart-dot-radius`, `--ds-scatter-chart-dot-opacity`, `--ds-scatter-chart-focus-color`, `--ds-scatter-chart-focus-width`.
975
984
 
976
985
  <!-- inputs:ds-scatter-chart -->
977
- All inputs: `data: readonly ScatterChartSeries[] = []`, `xLabel: string | null = null`, `yLabel: string | null = null`, `decimator: 'minMax' | 'lttb' | 'none' = 'minMax'`, `tickCount: number = 5`, `caption: string | null = null`, `summary: string | null = null`, `interactive: boolean = false`, `frame: 'auto' | 'none' = null`, `dataTable: 'toggle' | 'visible' | 'none' = null`, `loading: boolean = false`, `error: boolean = false`, `emptyText: string | null = null`, `errorText: string | null = null`, `valueFormat: ChartValueFormat | null = null`, `tooltip: 'item' | 'none' = 'item'`, `dimOthers: boolean = false`
986
+ All inputs: `data: readonly ScatterChartSeries[] = []`, `xLabel: string | null = null`, `yLabel: string | null = null`, `decimator: 'minMax' | 'lttb' | 'none' = 'minMax'`, `tickCount: number = 5`, `caption: string | null = null`, `summary: string | null = null`, `interactive: boolean = false`, `frame: 'auto' | 'none' = null`, `dataTable: 'toggle' | 'visible' | 'none' = null`, `loading: boolean = false`, `error: boolean = false`, `emptyText: string | null = null`, `errorText: string | null = null`, `valueFormat: ChartValueFormat | null = null`, `tooltip: 'item' | 'none' = 'item'`, `dimOthers: boolean = false`, `pinOnClick: boolean | null = null`
978
987
  <!-- /inputs -->
979
988
 
980
989
  #### `<ds-waterfall-chart>` — `WaterfallChartComponent`
@@ -991,15 +1000,15 @@ Built on `<ds-chart>` with a column series and a waterfall-specific mark project
991
1000
  Tokens: `--ds-waterfall-chart-connector-color`, `--ds-waterfall-chart-skeleton-height`.
992
1001
 
993
1002
  <!-- inputs:ds-waterfall-chart -->
994
- All inputs: `data: readonly WaterfallChartBar[] = []`, `showValues: boolean = true`, `showConnectors: boolean = true`, `caption: string | null = null`, `summary: string | null = null`, `tickCount: number = 5`, `interactive: boolean = false`, `frame: 'auto' | 'none' = null`, `dataTable: 'toggle' | 'visible' | 'none' = null`, `loading: boolean = false`, `error: boolean = false`, `emptyText: string | null = null`, `errorText: string | null = null`, `valueFormat: ChartValueFormat | null = null`
1003
+ All inputs: `data: readonly WaterfallChartBar[] = []`, `showValues: boolean = true`, `showConnectors: boolean = true`, `caption: string | null = null`, `summary: string | null = null`, `tickCount: number = 5`, `interactive: boolean = false`, `frame: 'auto' | 'none' = null`, `dataTable: 'toggle' | 'visible' | 'none' = null`, `loading: boolean = false`, `error: boolean = false`, `emptyText: string | null = null`, `errorText: string | null = null`, `valueFormat: ChartValueFormat | null = null`, `pinOnClick: boolean | null = null`, `staggerMs: number = 40`
995
1004
  <!-- /inputs -->
996
1005
 
997
1006
  #### `<ds-line-chart>` — `LineChartComponent`
998
1007
  One or more series plotted over a shared set of categories.
999
- Inputs: `categories: readonly string[]` (required), `series: readonly LineChartSeries[]` (required), `yAxisMode: 'aligned' | 'exact' | 'dual-grid' | 'split' = 'aligned'`, `curve: 'linear' | 'step' | 'smooth' = 'linear'`, `stack: 'none' | 'stacked' | 'normalized' = 'none'`, `showMarkers: boolean = true`, `gaps: 'break' | 'zero' = 'break'`, `tickCount: number = 5`, `caption: string | null = null`, `summary: string | null = null`, `dataTable: 'none' | 'toggle' | 'visible' = 'none'`, `loading: boolean = false`, `emptyText: string = 'No data'`, `error: boolean = false`, `errorText: string = 'Could not load the data'`, `valueFormat: (value: number) => string`, `interactive: boolean = false`, `tooltip: 'item' | 'axis' | 'none' = 'axis'`, `patterns: boolean = false`, `staggerMs: number = 0`, `legendFilters: boolean = false`, `hiddenSeries: readonly string[] = []` (two-way), `rescaleOnHide: boolean = false`, `noVisibleSeriesText: string = 'All series are hidden'`
1008
+ Inputs: `categories: readonly string[]` (required), `series: readonly LineChartSeries[]` (required), `yAxisMode: 'aligned' | 'exact' | 'dual-grid' | 'split' = 'aligned'`, `curve: 'linear' | 'step' | 'smooth' = 'linear'`, `stack: 'none' | 'stacked' | 'normalized' = 'none'`, `showMarkers: boolean = true`, `gaps: 'break' | 'zero' = 'break'`, `tickCount: number = 5`, `caption: string | null = null`, `summary: string | null = null`, `dataTable: 'none' | 'toggle' | 'visible' = 'none'`, `loading: boolean = false`, `emptyText: string = 'No data'`, `error: boolean = false`, `errorText: string = 'Could not load the data'`, `valueFormat: (value: number) => string`, `interactive: boolean = false`, `tooltip: 'item' | 'axis' | 'none' = 'axis'`, `patterns: boolean = false`, `staggerMs: number = 40`, `legendFilters: boolean = false`, `hiddenSeries: readonly string[] = []` (two-way), `rescaleOnHide: boolean = false`, `noVisibleSeriesText: string | null = null` (unset: `DS_INTL.chart.noVisibleSeries`)
1000
1009
  Output: `(pointClicked): LineChartReading` — the reading that was clicked or activated. Fires whether or not `interactive` is set.
1001
1010
  Interaction: a pointer moving over the plot picks the CATEGORY under it — a band paints behind every series and `tooltip="axis"`, the default here, names every series at that category. Tabbing reaches ONE marker per series; arrows walk that series' readings, and a focused marker's tooltip names its own series alone. A tap picks a category and latches the panel until the next tap outside; markers carry a transparent hit stroke of 24px, or 44px under `(pointer: coarse)`. `dimOthers` is the same separate opt-in as on the other four, and here it is the legend hover that drives it.
1002
- Legend: drawn whenever there is more than one series. `legendFilters` turns each entry into a checkbox that hides its series, `hiddenSeries` is two-way so a page can drive it from a URL parameter, and hovering an entry dims the others and thickens the one hovered. **The axis does not move when a series is hidden** unless `rescaleOnHide` says so — a silent rescale turns a period-over-period comparison into a different claim. Hiding every series replaces the plot with `noVisibleSeriesText` on a `role="status"` line, legend still rendered.
1011
+ Legend: drawn whenever there is more than one series. `legendFilters` turns each entry into a checkbox that hides its series, `hiddenSeries` is two-way so a page can drive it from a URL parameter, and hovering or focusing an entry tints it, dims the others and thickens the one hovered. **The axis does not move when a series is hidden** unless `rescaleOnHide` says so — a silent rescale turns a period-over-period comparison into a different claim. Hiding every series replaces the plot with `noVisibleSeriesText` on a `role="status"` line, legend still rendered.
1003
1012
  Second channel: `patterns` gives every series a dash of its own, in palette-slot order, with slot 1 left solid. Off by default — the shipped palette clears the colour-blind separation threshold on its own, so this is for monochrome print, a retuned palette, or a reader who asks for it.
1004
1013
  Series: `LineChartSeries = { id: string; label: string; data: readonly (number | null)[]; axis?: 'primary' | 'secondary'; area?: boolean; slot?: number }`. A `null` is a missing reading and `gaps` decides what it draws — `'break'` leaves a hole in the line, `'zero'` plants a point on the baseline. `area` fills the band between the line and its axis baseline. `slot` pins a palette slot, so hiding one series leaves every other series' colour alone.
1005
1014
  `yAxisMode` only matters once a series sets `axis: 'secondary'`, and every name says what is done to the GRIDLINES: `'aligned'` shares one set and rounds the secondary step up, so that series stops short of the top; `'exact'` shares the gridlines but ends the secondary axis on its largest reading, so it uses the full height and its labels are not round; `'dual-grid'` scales and grids each axis on its own; `'split'` draws two plots one above the other, sharing the category axis. `curve` decides what is drawn BETWEEN two readings: `'linear'` asserts nothing, `'step'` holds each reading to the next, `'smooth'` is a monotone cubic that draws no peak the data lacks. `stack` decides how several series share the axis: `'stacked'` starts each where the one below it ended, `'normalized'` divides by the category's own total so the axis reads in shares. Only a series with `area: true` fills, and stacking runs per axis.
@@ -1008,11 +1017,13 @@ Colour: series ARE different things, so the categorical palette applies — `--d
1008
1017
  Tokens: `--ds-line-chart-plot-height`, `--ds-line-chart-line-width`, `--ds-line-chart-dot-radius`, `--ds-line-chart-area-opacity`, `--ds-line-chart-swatch-size`, `--ds-line-chart-grid-line-color`, `--ds-line-chart-axis-line-color`, `--ds-line-chart-axis-label-color`, `--ds-line-chart-axis-font-size`, `--ds-line-chart-annotation-color`, `--ds-line-chart-annotation-font-size`, `--ds-line-chart-annotation-font-weight`, `--ds-line-chart-annotation-halo-color`, `--ds-line-chart-annotation-halo-width`.
1009
1018
 
1010
1019
  <!-- inputs:ds-line-chart -->
1011
- All inputs: `categories: required readonly string[]`, `series: required readonly LineChartSeries[]`, `yAxisMode: 'aligned' | 'exact' | 'dual-grid' | 'split' = 'aligned'`, `showMarkers: boolean = true`, `outline: boolean = true`, `annotations: readonly LineChartAnnotation[] = []`, `interactive: boolean = false`, `pinOnClick: boolean = false`, `dimOthers: boolean = false`, `gaps: 'break' | 'zero' = 'break'`, `curve: 'linear' | 'step' | 'smooth' = 'linear'`, `stack: 'none' | 'stacked' | 'normalized' = 'none'`, `yAxisLabel: string | null = null`, `secondaryAxisLabel: string | null = null`, `tickCount: number = 5`, `frame: 'auto' | 'none' = null`, `tooltipLingerMs: number | null = null`, `caption: string | null = null`, `summary: string | null = null`, `dataTable: 'toggle' | 'visible' | 'none' = null`, `max: number | null = null`, `maxSecondary: number | null = null`, `loading: boolean = false`, `emptyText: string | null = null`, `error: boolean = false`, `errorText: string | null = null`, `valueFormat: ChartValueFormat | null = null`, `hiddenSeries: readonly string[] = []`, `rescaleOnHide: boolean = false`, `legendFilters: boolean = false`, `legendMode: 'toggle' | 'isolate' = 'isolate'`, `noVisibleSeriesText: string = 'All series are hidden'`, `patterns: boolean = false`, `staggerMs: number = 0`, `tooltip: 'item' | 'axis' | 'none' = 'axis'`, `tooltipAnchor: 'point' | 'pointer' = 'point'`
1020
+ All inputs: `categories: required readonly string[]`, `series: required readonly LineChartSeries[]`, `yAxisMode: 'aligned' | 'exact' | 'dual-grid' | 'split' = 'aligned'`, `showMarkers: boolean = true`, `outline: boolean = true`, `annotations: readonly LineChartAnnotation[] = []`, `interactive: boolean = false`, `pinOnClick: boolean | null = null`, `dimOthers: boolean = false`, `gaps: 'break' | 'zero' = 'break'`, `curve: 'linear' | 'step' | 'smooth' = 'linear'`, `stack: 'none' | 'stacked' | 'normalized' = 'none'`, `yAxisLabel: string | null = null`, `secondaryAxisLabel: string | null = null`, `tickCount: number = 5`, `frame: 'auto' | 'none' = null`, `tooltipLingerMs: number | null = null`, `caption: string | null = null`, `summary: string | null = null`, `dataTable: 'toggle' | 'visible' | 'none' = null`, `max: number | null = null`, `maxSecondary: number | null = null`, `loading: boolean = false`, `emptyText: string | null = null`, `error: boolean = false`, `errorText: string | null = null`, `valueFormat: ChartValueFormat | null = null`, `hiddenSeries: readonly string[] = []`, `rescaleOnHide: boolean = false`, `legendFilters: boolean = false`, `legendMode: 'toggle' | 'isolate' = 'isolate'`, `noVisibleSeriesText: string | null = null`, `patterns: boolean = false`, `staggerMs: number = 40`, `tooltip: 'item' | 'axis' | 'none' = 'axis'`, `tooltipAnchor: 'point' | 'pointer' = 'point'`
1012
1021
  <!-- /inputs -->
1013
1022
 
1014
1023
  #### Chart defaults — what `DS_CONFIG` decides once
1015
- Four chart inputs resolve through `DS_CONFIG.chart` because they are one decision per APP, not per plot: `valueFormat` (a number reads one way in a product; a formatter passed per chart drifts as soon as there are two screens), `dataTable` (whether the numbers behind a plot have a non-visual route is an accessibility policy), `emptyText` and `errorText` (copy, and the place localisation lands). Precedence is the input, then the config, then the built-in — so binding one on a single chart still wins.
1024
+ Five chart inputs resolve through `DS_CONFIG.chart` because they are one decision per APP, not per plot: `valueFormat` (a number reads one way in a product; a formatter passed per chart drifts as soon as there are two screens), `dataTable` (whether the numbers behind a plot have a non-visual route is an accessibility policy), `frame`, `tooltipLingerMs` and `pinOnClick` (default `true`: a click holds a mark, with a pin disc on it, until a second click, Escape or a press elsewhere). `DS_CONFIG.chart.hoverDelayMs` (default `500`) is how long a resting pointer waits before any chart answers it; once a chart has answered, the next mark answers at once until the pointer leaves it, and focus, a tap and a pinning click answer at once. Precedence is the input, then the config, then the built-in — so binding one on a single chart still wins. The empty and error copy is wording, so it lives in `DS_INTL.chart.empty` / `.error`; the number locale is `DsConfig.locale`.
1025
+
1026
+ `DS_CONFIG.chart.rendering` decides how charts build on a long page and is off by default: every chart draws as soon as it is created. With `deferUntilVisible: true` each chart shows a still placeholder of its own shape until it comes within `visibleMargin` (default `'10% 0px'`) of the viewport; `buildAheadWhileIdle` (default `true`) builds the charts within `buildAheadMargin` (default `'100% 0px'`) while the page is idle; `frameBudgetMs` (default `8`) caps how long one task spends building; `skipWhileOffscreen` (default `true`) lets the browser skip a built chart's rendering off screen through `content-visibility: auto`. Until a deferred chart is built a screen reader meets its caption only.
1016
1027
 
1017
1028
  ```ts
1018
1029
  providers: [provideDsConfig({ chart: { valueFormat: v => v.toLocaleString('de-DE'), dataTable: 'visible' } })]
@@ -1045,7 +1056,7 @@ All inputs: `columns: readonly string[] = []`, `rows: readonly ChartDataRow[] =
1045
1056
  #### `<ds-chart>` — `ChartComponent`
1046
1057
 
1047
1058
  <!-- inputs:ds-chart -->
1048
- All inputs: `categories: readonly string[] = []`, `tickCount: number = 5`, `min: number | null = null`, `max: number | null = null`, `cursor: 'none' | 'category' = 'none'`, `cursorPin: boolean = false`, `tooltipLingerMs: number | null = null`, `maxSecondary: number | null = null`, `plotHeight: number = 240`, `axisGutter: number = 46`, `valueSpace: number = 20`, `caption: string | null = null`, `interactive: boolean = false`, `summary: string | null = null`, `frame: 'auto' | 'none' = null`, `loading: boolean = false`, `emptyText: string | null = null`, `error: boolean = false`, `errorText: string | null = null`, `valueFormat: ChartValueFormat | null = null`, `secondaryAxisMode: 'aligned' | 'exact' | 'dual-grid' | 'split' = 'aligned'`, `axisColor: string | null = null`, `secondaryAxisColor: string | null = null`, `axisLabel: string | null = null`, `secondaryAxisLabel: string | null = null`, `tooltipTemplate: TemplateRef<{
1059
+ All inputs: `categories: readonly string[] = []`, `tickCount: number = 5`, `min: number | null = null`, `max: number | null = null`, `cursor: 'none' | 'category' | 'auto' = 'auto'`, `cursorPin: boolean | null = null`, `tooltipLingerMs: number | null = null`, `maxSecondary: number | null = null`, `plotHeight: number = 240`, `axisGutter: number = 46`, `valueSpace: number = 20`, `caption: string | null = null`, `interactive: boolean = false`, `summary: string | null = null`, `frame: 'auto' | 'none' = null`, `loading: boolean = false`, `emptyText: string | null = null`, `error: boolean = false`, `errorText: string | null = null`, `valueFormat: ChartValueFormat | null = null`, `secondaryAxisMode: 'aligned' | 'exact' | 'dual-grid' | 'split' = 'aligned'`, `axisColor: string | null = null`, `secondaryAxisColor: string | null = null`, `axisLabel: string | null = null`, `secondaryAxisLabel: string | null = null`, `tooltipTemplate: TemplateRef<{
1049
1060
  $implicit: ChartTooltipContext;
1050
1061
  }> | null = null`, `tooltipExtraGap: number = 0`
1051
1062
  <!-- /inputs -->
@@ -1053,13 +1064,13 @@ All inputs: `categories: readonly string[] = []`, `tickCount: number = 5`, `min:
1053
1064
  #### `<g[dsColumnSeries]>` — `ColumnSeriesComponent`
1054
1065
 
1055
1066
  <!-- inputs:g[dsColumnSeries] -->
1056
- All inputs: `data: readonly ColumnSeriesPoint[] = []`, `showValues: boolean = true`, `interactive: boolean = false`, `pinOnClick: boolean = false`, `dimOthers: boolean = false`, `staggerMs: number = 0`, `partOfWhole: boolean = false`, `tooltip: 'item' | 'none' = 'item'`, `tooltipAnchor: 'mark' | 'cell' = 'mark'`, `tooltipLingerMs: number = 0`, `valueFormat: ChartValueFormat`, `columnWidthRatio: number = 0.8`, `slot: number = 0`, `slotCount: number = 1`, `offsets: readonly ChartStackOffset[] | null = null`, `seriesColor: string | null = null`, `seriesFill: 'solid' | 'hatched' = null`, `seriesLabel: string | null = null`, `seriesKey: string | null = null`, `highlighted: string | null = null`
1067
+ All inputs: `data: readonly ColumnSeriesPoint[] = []`, `showValues: boolean = true`, `interactive: boolean = false`, `pinOnClick: boolean | null = null`, `dimOthers: boolean = false`, `staggerMs: number = 40`, `partOfWhole: boolean = false`, `tooltip: 'item' | 'none' = 'item'`, `tooltipAnchor: 'mark' | 'cell' = 'mark'`, `tooltipLingerMs: number = 0`, `valueFormat: ChartValueFormat`, `columnWidthRatio: number = 0.8`, `slot: number = 0`, `slotCount: number = 1`, `offsets: readonly ChartStackOffset[] | null = null`, `axis: 'primary' | 'secondary' = 'primary'`, `seriesColor: string | null = null`, `seriesFill: 'solid' | 'hatched' = null`, `seriesLabel: string | null = null`, `seriesKey: string | null = null`, `highlighted: string | null = null`
1057
1068
  <!-- /inputs -->
1058
1069
 
1059
1070
  #### `<g[dsLineSeries]>` — `LineSeriesComponent`
1060
1071
 
1061
1072
  <!-- inputs:g[dsLineSeries] -->
1062
- All inputs: `data: readonly LineSeriesData[] = []`, `showMarkers: boolean = true`, `outline: boolean = true`, `interactive: boolean = false`, `pinOnClick: boolean = false`, `dimOthers: boolean = false`, `highlighted: string | null = null`, `patterns: readonly string[] = []`, `stacked: boolean = false`, `staggerMs: number = 0`, `gaps: 'break' | 'zero' = 'break'`, `curve: 'linear' | 'step' | 'smooth' = 'linear'`, `tooltip: 'item' | 'axis' | 'none' = 'item'`, `tooltipAnchor: 'reading' | 'pointer' = 'reading'`, `tooltipLingerMs: number = 0`, `valueFormat: ChartValueFormat`
1073
+ All inputs: `data: readonly LineSeriesData[] = []`, `showMarkers: boolean = true`, `outline: boolean = true`, `interactive: boolean = false`, `pinOnClick: boolean | null = null`, `dimOthers: boolean = false`, `highlighted: string | null = null`, `patterns: readonly string[] = []`, `stacked: boolean = false`, `staggerMs: number = 40`, `gaps: 'break' | 'zero' = 'break'`, `curve: 'linear' | 'step' | 'smooth' = 'linear'`, `tooltip: 'item' | 'axis' | 'none' = 'item'`, `tooltipAnchor: 'reading' | 'pointer' = 'reading'`, `tooltipLingerMs: number = 0`, `valueFormat: ChartValueFormat`
1063
1074
  <!-- /inputs -->
1064
1075
 
1065
1076
  #### `<g[dsSeriesAnnotation]>` — `SeriesAnnotationComponent`
@@ -1145,11 +1156,12 @@ bootstrapApplication(AppComponent, {
1145
1156
 
1146
1157
  `DsConfig` shape (the exported `DsConfig` type is the full contract):
1147
1158
 
1148
- Eighteen sections. The exported `DsConfig` type is the source of truth — each key carries its own
1159
+ Eighteen sections and one top-level `locale`. The exported `DsConfig` type is the source of truth — each key carries its own
1149
1160
  doc comment there, including why it is an app-level decision at all.
1150
1161
 
1151
1162
  ```ts
1152
1163
  interface DsConfig {
1164
+ locale?: string; // BCP-47; default LOCALE_ID
1153
1165
  field?: {
1154
1166
  reserveMessage?: boolean; // keep a message line of space when empty
1155
1167
  errorMessages?: Record<string, string>; // fallback text per validation-error kind
@@ -1184,6 +1196,35 @@ both resolve their parent with `skipSelf`, so the later wins and the earlier is
1184
1196
  happens across injector LEVELS: a route or component inherits the app's config and overrides only the
1185
1197
  keys it names.
1186
1198
 
1199
+ #### `DS_INTL` / `provideDsIntl(overrides)`
1200
+
1201
+ `DS_INTL` holds every string the library renders itself: picker rows and chips, clear and dismiss
1202
+ buttons, pager and table announcements, chart descriptions and annex headers. It is a `Signal<DsIntl>`
1203
+ holding the English defaults (`DS_INTL_DEFAULTS`) until an app provides its own.
1204
+
1205
+ ```ts
1206
+ import { LOCALE_ID } from '@angular/core';
1207
+ import { provideDsIntl } from '@ids-group-ltd/ids-design-system';
1208
+
1209
+ providers: [
1210
+ { provide: LOCALE_ID, useValue: 'ru' },
1211
+ provideDsIntl({ picker: { selectAll: 'Выбрать все', clearSelection: 'Очистить выбор' } }),
1212
+ ]
1213
+ ```
1214
+
1215
+ - **Object or factory.** An object is one fixed language. A factory returning a signal switches
1216
+ language at runtime, and runs in an injection context, so it can inject the app's own language
1217
+ service:
1218
+ `provideDsIntl(() => { const i18n = inject(I18n); return computed(() => i18n.dictionary().ds); })`.
1219
+ - **Section-wise merge across levels.** A route or component `provideDsIntl` inherits the one above
1220
+ it and overrides only the keys it names. Like `provideDsConfig`, call it once per injector.
1221
+ - **Precedence: input → `DS_INTL`.** A text input on the element (`placeholder`, `moreLabel`,
1222
+ `sortAnnouncement`, …) still wins; those inputs default to `null` and publish a `…Resolved`
1223
+ readback holding the effective text.
1224
+ - **Numbers and dates are not words.** They follow `DsConfig.locale`, then `LOCALE_ID`: chart values
1225
+ and percentages, `ds-date-picker`, `ds-dropzone` file sizes. An app that localizes sets both, once,
1226
+ at the root.
1227
+
1187
1228
  ---
1188
1229
 
1189
1230
  ## Services