@khsura/sui 1.19.0 → 1.20.0

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 (117) hide show
  1. package/@types/components/cards/sCardText.vue.d.ts +2 -2
  2. package/@types/components/datePicker/sDatePickerSwitch.vue.d.ts +2 -0
  3. package/@types/components/form/index.d.ts +1 -0
  4. package/@types/components/form/radio/sRadio.vue.d.ts +3 -0
  5. package/@types/components/form/sFormRow.vue.d.ts +18 -0
  6. package/@types/components/form/sInput.vue.d.ts +1 -0
  7. package/@types/components/form/sSelect.vue.d.ts +2 -0
  8. package/@types/components/layout/sNavigationDrawer.vue.d.ts +6 -6
  9. package/@types/components/progress/sProgressCircular.vue.d.ts +1 -0
  10. package/@types/components/progress/sProgressLinear.vue.d.ts +1 -0
  11. package/@types/components/sAutocomplete.vue.d.ts +3 -0
  12. package/@types/components/slideGroup/sSlideGroup.vue.d.ts +4 -1
  13. package/@types/components/table/sTable.vue.d.ts +2 -0
  14. package/@types/components/tabs/sTabs.vue.d.ts +2 -2
  15. package/@types/configs/app.d.ts +4 -0
  16. package/@types/configs/i18n.d.ts +3 -0
  17. package/@types/configs/provider.d.ts +1 -0
  18. package/@types/constants/color.d.ts +15 -0
  19. package/@types/constants/cssVariables.d.ts +4 -0
  20. package/@types/constants/datePicker.d.ts +7 -0
  21. package/@types/constants/i18n.d.ts +3 -0
  22. package/@types/constants/index.d.ts +3 -0
  23. package/@types/constants/keyboard.d.ts +12 -0
  24. package/@types/constants/listbox.d.ts +1 -0
  25. package/@types/constants/overlay.d.ts +5 -0
  26. package/@types/constants/tabs.d.ts +4 -0
  27. package/@types/definitions/props/core/propsLink.d.ts +2 -2
  28. package/@types/definitions/props/propsAutocomplete.d.ts +6 -0
  29. package/@types/definitions/props/propsInput.d.ts +1 -0
  30. package/@types/definitions/props/propsLink.d.ts +2 -2
  31. package/@types/definitions/props/propsProgressCircular.d.ts +2 -0
  32. package/@types/definitions/props/propsProgressLinear.d.ts +2 -0
  33. package/@types/definitions/props/propsSelect.d.ts +4 -0
  34. package/@types/definitions/props/propsSlideGroup.d.ts +4 -0
  35. package/@types/definitions/props/propsTable.d.ts +1 -0
  36. package/@types/definitions/props/propsTextarea.d.ts +3 -0
  37. package/@types/helpers/colorHelpers.d.ts +1 -1
  38. package/@types/helpers/createAppStore.d.ts +4 -0
  39. package/@types/lib/color.d.ts +21 -2
  40. package/@types/lib/index.d.ts +4 -0
  41. package/@types/lib/linkLocation.d.ts +9 -0
  42. package/@types/lib/overlayPlacement.d.ts +11 -0
  43. package/@types/lib/revealInScroller.d.ts +11 -0
  44. package/@types/lib/safeArea.d.ts +3 -0
  45. package/@types/playwright.visual.config.d.ts +3 -0
  46. package/@types/services/backgroundScrollService.d.ts +8 -2
  47. package/@types/services/datePicker/datePickerItemDateService.d.ts +1 -0
  48. package/@types/services/dialogService.d.ts +4 -8
  49. package/@types/services/fieldLayoutService.d.ts +19 -0
  50. package/@types/services/formInputService.d.ts +6 -0
  51. package/@types/services/index.d.ts +7 -0
  52. package/@types/services/linkService.d.ts +11 -1
  53. package/@types/services/listboxNavigationService.d.ts +20 -0
  54. package/@types/services/menuService.d.ts +2 -0
  55. package/@types/services/overlayFocusService.d.ts +10 -0
  56. package/@types/services/routerLinkService.d.ts +19 -0
  57. package/@types/services/scrollableFocusService.d.ts +10 -0
  58. package/@types/services/surfaceTextColorService.d.ts +8 -0
  59. package/@types/services/tabsService.d.ts +9 -0
  60. package/@types/store/index.d.ts +1 -0
  61. package/@types/store/scrollLockStore.d.ts +1 -0
  62. package/@types/tests/visual/constants/a11yAudit.d.ts +4 -0
  63. package/@types/tests/visual/constants/index.d.ts +4 -0
  64. package/@types/tests/visual/constants/resizeScroll.d.ts +10 -0
  65. package/@types/tests/visual/constants/storyRender.d.ts +5 -0
  66. package/@types/tests/visual/constants/visualMatrix.d.ts +20 -0
  67. package/@types/tests/visual/schemas/index.d.ts +1 -0
  68. package/@types/tests/visual/schemas/storyIndex.d.ts +17 -0
  69. package/@types/tests/visual/types/a11yAudit.d.ts +2 -0
  70. package/@types/tests/visual/types/index.d.ts +2 -0
  71. package/@types/tests/visual/types/visualStory.d.ts +8 -0
  72. package/@types/types/app.d.ts +2 -0
  73. package/@types/types/breadcrumbs.d.ts +2 -2
  74. package/@types/types/index.d.ts +2 -0
  75. package/@types/types/link.d.ts +20 -0
  76. package/@types/types/menu.d.ts +17 -0
  77. package/@types/types/safeArea.d.ts +1 -0
  78. package/@types/vite.config.d.ts +1 -0
  79. package/README.md +12 -0
  80. package/dist/base.css.map +1 -1
  81. package/dist/s-ui.css +1 -1
  82. package/dist/s-ui.js +3122 -2478
  83. package/dist/s-ui.umd.cjs +1 -1
  84. package/dist/styles/components/button/mixins.scss +5 -0
  85. package/dist/styles/components/form/_variables.scss +11 -0
  86. package/dist/styles/components/form/index.scss +1 -0
  87. package/dist/styles/components/index.scss +1 -0
  88. package/dist/styles/mixins/_app.scss +7 -0
  89. package/dist/styles/tools/_safeArea.scss +8 -0
  90. package/dist/styles/tools/index.scss +1 -0
  91. package/dist/sui-api.json +115 -5
  92. package/package.json +13 -3
  93. package/sui-plugin/.claude-plugin/plugin.json +1 -1
  94. package/sui-plugin/skills/sui-component/SKILL.md +11 -3
  95. package/sui-plugin/skills/sui-component/references/autocomplete.md +6 -1
  96. package/sui-plugin/skills/sui-component/references/breadcrumbs.md +3 -2
  97. package/sui-plugin/skills/sui-component/references/button.md +2 -2
  98. package/sui-plugin/skills/sui-component/references/cards.md +3 -3
  99. package/sui-plugin/skills/sui-component/references/date-picker.md +2 -1
  100. package/sui-plugin/skills/sui-component/references/dialog.md +3 -2
  101. package/sui-plugin/skills/sui-component/references/expansion-panels.md +1 -1
  102. package/sui-plugin/skills/sui-component/references/form.md +143 -95
  103. package/sui-plugin/skills/sui-component/references/image.md +3 -2
  104. package/sui-plugin/skills/sui-component/references/layout.md +7 -6
  105. package/sui-plugin/skills/sui-component/references/list.md +5 -2
  106. package/sui-plugin/skills/sui-component/references/menu.md +4 -1
  107. package/sui-plugin/skills/sui-component/references/progress.md +20 -18
  108. package/sui-plugin/skills/sui-component/references/slide-group.md +14 -12
  109. package/sui-plugin/skills/sui-component/references/snackbar.md +4 -2
  110. package/sui-plugin/skills/sui-component/references/table.md +8 -2
  111. package/sui-plugin/skills/sui-component/references/tabs.md +3 -0
  112. package/sui-plugin/skills/sui-component/references/tooltip.md +1 -0
  113. package/sui-plugin/skills/sui-component/references/window.md +5 -0
  114. package/sui-plugin/skills/sui-form/SKILL.md +20 -15
  115. package/sui-plugin/skills/sui-getting-started/SKILL.md +32 -7
  116. package/sui-plugin/skills/sui-layout/SKILL.md +3 -1
  117. package/sui-plugin/skills/sui-utilities/docs/classes.md +1 -1
@@ -47,6 +47,11 @@
47
47
  opacity: variables.$s_button--focus__opacity;
48
48
  }
49
49
 
50
+ // A visible ring for keyboard focus (the tint above alone is too faint to see)
51
+ &:focus-visible {
52
+ @include mixins.s_focusRing();
53
+ }
54
+
50
55
  // except for touch devices
51
56
  @media (hover: hover) {
52
57
  &:hover::before {
@@ -0,0 +1,11 @@
1
+ @use 'sass:map';
2
+ @use '../../variables';
3
+
4
+ // Height of the label above a text field box (SInput, SSelect, SDatePickerInput, SAutocomplete, STextarea):
5
+ // one line of the 'caption' typography plus the label's vertical padding.
6
+ $s_field__labelHeight: calc(
7
+ #{map.get(map.get(variables.$s_headings, 'caption'), 'line-height')} + #{variables.$s_spacer * 2}
8
+ ) !default;
9
+
10
+ // Minimum height of the reserved details (error) line under a field box.
11
+ $s_formInputError__minHeight: variables.$s_spacer * 7 !default;
@@ -0,0 +1 @@
1
+ @forward './variables';
@@ -1,6 +1,7 @@
1
1
  @forward './appBar';
2
2
  @forward './button';
3
3
  @forward './cards';
4
+ @forward './form';
4
5
  @forward './icon';
5
6
  @forward './layout';
6
7
  @forward './list';
@@ -1,5 +1,12 @@
1
1
  @use '../tools';
2
2
 
3
+ // Keyboard focus indicator: a 2px ring in the theme's `focusRing` colour, which reaches 3:1 on the app
4
+ // background and cards in light and dark. Use it under :focus-visible so a mouse click leaves no ring.
5
+ @mixin s_focusRing($offset: 2px) {
6
+ outline: 2px solid tools.s_getAppColor('focusRing');
7
+ outline-offset: $offset;
8
+ }
9
+
3
10
  @mixin s_disabled($isText: false) {
4
11
  color: tools.s_getAppColor('text');
5
12
  pointer-events: none;
@@ -0,0 +1,8 @@
1
+ // The iPhone notch / home-indicator inset on one side. SApp sets `--s-safe-area-<side>` from
2
+ // `env(safe-area-inset-<side>)`, so a story or test can override it; outside SApp `env()` applies directly.
3
+ // Without a safe area (desktop, Android, no `viewport-fit=cover`) it resolves to 0px.
4
+ @function s_safeAreaInset($side) {
5
+ // a unitless 0 would be invalid wherever the inset ends up inside calc()
6
+ // stylelint-disable-next-line length-zero-no-unit
7
+ @return var(--s-safe-area-#{$side}, env(safe-area-inset-#{$side}, 0px));
8
+ }
@@ -1,2 +1,3 @@
1
1
  @forward './breakpoint';
2
2
  @forward './color';
3
+ @forward './safeArea';
package/dist/sui-api.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "package": "@khsura/sui",
3
- "version": "1.19.0",
4
- "generatedAt": "2026-11-21T07:20:17.214Z",
3
+ "version": "1.20.0",
4
+ "generatedAt": "2026-11-22T03:01:49.821Z",
5
5
  "components": [
6
6
  {
7
7
  "name": "SAlert",
@@ -621,6 +621,12 @@
621
621
  "required": false,
622
622
  "description": ""
623
623
  },
624
+ {
625
+ "name": "ariaLabel",
626
+ "type": "string | null | undefined",
627
+ "required": false,
628
+ "description": ""
629
+ },
624
630
  {
625
631
  "name": "autocomplete",
626
632
  "type": "string | undefined",
@@ -634,6 +640,13 @@
634
640
  "required": false,
635
641
  "description": ""
636
642
  },
643
+ {
644
+ "name": "clearAriaLabel",
645
+ "type": "string | undefined",
646
+ "required": false,
647
+ "default": "\"Clear\"",
648
+ "description": ""
649
+ },
637
650
  {
638
651
  "name": "clearable",
639
652
  "type": "boolean | undefined",
@@ -762,6 +775,13 @@
762
775
  "required": false,
763
776
  "description": ""
764
777
  },
778
+ {
779
+ "name": "loadingAriaLabel",
780
+ "type": "string | undefined",
781
+ "required": false,
782
+ "default": "\"Loading\"",
783
+ "description": ""
784
+ },
765
785
  {
766
786
  "name": "location",
767
787
  "type": "LocationRaw",
@@ -1551,7 +1571,7 @@
1551
1571
  },
1552
1572
  {
1553
1573
  "name": "to",
1554
- "type": "string | it | et | null | undefined",
1574
+ "type": "LinkLocation | null | undefined",
1555
1575
  "required": false,
1556
1576
  "description": ""
1557
1577
  },
@@ -2118,7 +2138,7 @@
2118
2138
  },
2119
2139
  {
2120
2140
  "name": "to",
2121
- "type": "string | it | et | null | undefined",
2141
+ "type": "LinkLocation | null | undefined",
2122
2142
  "required": false,
2123
2143
  "description": ""
2124
2144
  },
@@ -4685,6 +4705,20 @@
4685
4705
  "slots": [],
4686
4706
  "events": []
4687
4707
  },
4708
+ {
4709
+ "name": "SFormRow",
4710
+ "family": "form",
4711
+ "file": "components/form/sFormRow.vue",
4712
+ "props": [],
4713
+ "slots": [
4714
+ {
4715
+ "name": "default",
4716
+ "type": "any",
4717
+ "description": "The fields and buttons of the row."
4718
+ }
4719
+ ],
4720
+ "events": []
4721
+ },
4688
4722
  {
4689
4723
  "name": "SIcon",
4690
4724
  "family": "core",
@@ -4845,6 +4879,12 @@
4845
4879
  "required": false,
4846
4880
  "description": ""
4847
4881
  },
4882
+ {
4883
+ "name": "ariaLabel",
4884
+ "type": "string | undefined",
4885
+ "required": false,
4886
+ "description": ""
4887
+ },
4848
4888
  {
4849
4889
  "name": "ariaLabelledby",
4850
4890
  "type": "string | undefined",
@@ -5384,7 +5424,7 @@
5384
5424
  },
5385
5425
  {
5386
5426
  "name": "to",
5387
- "type": "string | it | et | null | undefined",
5427
+ "type": "LinkLocation | null | undefined",
5388
5428
  "required": false,
5389
5429
  "description": ""
5390
5430
  }
@@ -6128,6 +6168,13 @@
6128
6168
  "family": "progress",
6129
6169
  "file": "components/progress/sProgressCircular.vue",
6130
6170
  "props": [
6171
+ {
6172
+ "name": "ariaLabel",
6173
+ "type": "string | undefined",
6174
+ "required": false,
6175
+ "default": "\"Loading\"",
6176
+ "description": "Accessible name of the progress bar. Defaults to `'Loading'`; name what is loading when you can."
6177
+ },
6131
6178
  {
6132
6179
  "name": "color",
6133
6180
  "type": "string | null | undefined",
@@ -6192,6 +6239,13 @@
6192
6239
  "family": "progress",
6193
6240
  "file": "components/progress/sProgressLinear.vue",
6194
6241
  "props": [
6242
+ {
6243
+ "name": "ariaLabel",
6244
+ "type": "string | undefined",
6245
+ "required": false,
6246
+ "default": "\"Loading\"",
6247
+ "description": "Accessible name of the progress bar. Defaults to `'Loading'`; name what is loading when you can."
6248
+ },
6195
6249
  {
6196
6250
  "name": "backgroundColor",
6197
6251
  "type": "string | null | undefined",
@@ -6264,6 +6318,12 @@
6264
6318
  "required": false,
6265
6319
  "description": ""
6266
6320
  },
6321
+ {
6322
+ "name": "ariaLabel",
6323
+ "type": "string | null | undefined",
6324
+ "required": false,
6325
+ "description": "Accessible name for a radio without a visible `label` (for example an icon-only option)."
6326
+ },
6267
6327
  {
6268
6328
  "name": "borderRadius",
6269
6329
  "type": "number | \"tile\" | \"rounded\" | `${number}em` | `${number}px` | `${number}rem` | `${number}%` | `${number}vh` | `${number}vw` | null | undefined",
@@ -6599,6 +6659,12 @@
6599
6659
  "required": false,
6600
6660
  "description": ""
6601
6661
  },
6662
+ {
6663
+ "name": "ariaLabel",
6664
+ "type": "string | null | undefined",
6665
+ "required": false,
6666
+ "description": "Accessible name when there is no visible `label` (otherwise the label names the field)."
6667
+ },
6602
6668
  {
6603
6669
  "name": "borderRadius",
6604
6670
  "type": "number | \"tile\" | \"rounded\" | `${number}em` | `${number}px` | `${number}rem` | `${number}%` | `${number}vh` | `${number}vw` | null | undefined",
@@ -6783,8 +6849,15 @@
6783
6849
  "name": "outlined",
6784
6850
  "type": "boolean | null | undefined",
6785
6851
  "required": false,
6852
+ "default": "true",
6786
6853
  "description": ""
6787
6854
  },
6855
+ {
6856
+ "name": "placeholder",
6857
+ "type": "string | null | undefined",
6858
+ "required": false,
6859
+ "description": "Text shown in the field while nothing is selected. The label is never repeated inside the field."
6860
+ },
6788
6861
  {
6789
6862
  "name": "position",
6790
6863
  "type": "Position",
@@ -7172,6 +7245,20 @@
7172
7245
  "required": false,
7173
7246
  "description": ""
7174
7247
  },
7248
+ {
7249
+ "name": "nextAriaLabel",
7250
+ "type": "string | undefined",
7251
+ "required": false,
7252
+ "default": "\"Next\"",
7253
+ "description": "Accessible name of the next arrow button. Defaults to `'Next'`."
7254
+ },
7255
+ {
7256
+ "name": "prevAriaLabel",
7257
+ "type": "string | undefined",
7258
+ "required": false,
7259
+ "default": "\"Previous\"",
7260
+ "description": "Accessible name of the previous arrow button. Defaults to `'Previous'`."
7261
+ },
7175
7262
  {
7176
7263
  "name": "scrollable",
7177
7264
  "type": "boolean | null | undefined",
@@ -8113,6 +8200,12 @@
8113
8200
  "required": false,
8114
8201
  "description": ""
8115
8202
  },
8203
+ {
8204
+ "name": "loadingText",
8205
+ "type": "string | undefined",
8206
+ "required": false,
8207
+ "description": ""
8208
+ },
8116
8209
  {
8117
8210
  "name": "multiSort",
8118
8211
  "type": "boolean | undefined",
@@ -8254,6 +8347,11 @@
8254
8347
  "type": "any",
8255
8348
  "description": "Label of the items-per-page selector in the pagination."
8256
8349
  },
8350
+ {
8351
+ "name": "loadingData",
8352
+ "type": "any",
8353
+ "description": "Shown instead of the rows while `loading` is set and `items` is still empty."
8354
+ },
8257
8355
  {
8258
8356
  "name": "noData",
8259
8357
  "type": "any",
@@ -8495,6 +8593,12 @@
8495
8593
  "family": "form",
8496
8594
  "file": "components/form/sTextarea.vue",
8497
8595
  "props": [
8596
+ {
8597
+ "name": "ariaLabel",
8598
+ "type": "string | undefined",
8599
+ "required": false,
8600
+ "description": ""
8601
+ },
8498
8602
  {
8499
8603
  "name": "ariaLabelledby",
8500
8604
  "type": "string | undefined",
@@ -8536,6 +8640,12 @@
8536
8640
  "default": "20",
8537
8641
  "description": ""
8538
8642
  },
8643
+ {
8644
+ "name": "counter",
8645
+ "type": "boolean | undefined",
8646
+ "required": false,
8647
+ "description": "Shows the character count (`12 / 200` with `maxlength`) at the right of the error line, right under the field."
8648
+ },
8539
8649
  {
8540
8650
  "name": "dense",
8541
8651
  "type": "boolean | undefined",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@khsura/sui",
3
- "version": "1.19.0",
3
+ "version": "1.20.0",
4
4
  "repository": {
5
5
  "type": "git",
6
6
  "url": "git+https://github.com/khsura/sui.git",
@@ -18,6 +18,10 @@
18
18
  "stylelint": "yarn g:stylelint ./**/*.{vue,css,scss}",
19
19
  "test": "yarn g:vitest run --project unit",
20
20
  "test-storybook": "yarn g:vitest --project storybook",
21
+ "test:consumer": "bash scripts/consumerSmoke/runConsumerSmoke.sh",
22
+ "test:visual": "bash scripts/visual/runVisualInDocker.sh",
23
+ "test:visual:update": "bash scripts/visual/runVisualInDocker.sh --update",
24
+ "test:visual:container": "storybook build --quiet && playwright test -c playwright.visual.config.ts",
21
25
  "release": "yarn g:publish",
22
26
  "storybook:dev": "storybook dev --port 6006",
23
27
  "storybook:build": "storybook build",
@@ -59,11 +63,16 @@
59
63
  "@vueuse/core": "^14.3.0",
60
64
  "dayjs": "^1.11.21",
61
65
  "uuid": "^14.0.1",
62
- "vue": "^3.5.39",
63
66
  "vue-i18n": "^11.4.6",
64
67
  "zod": "^4.4.3"
65
68
  },
69
+ "peerDependencies": {
70
+ "vue": "^3.5.41"
71
+ },
66
72
  "devDependencies": {
73
+ "@axe-core/playwright": "4.14.0",
74
+ "@mdi/font": "6.5.95",
75
+ "@playwright/test": "1.61.1",
67
76
  "@storybook/addon-a11y": "^10.4.6",
68
77
  "@storybook/addon-docs": "^10.4.6",
69
78
  "@storybook/addon-links": "^10.4.6",
@@ -76,9 +85,10 @@
76
85
  "eslint-plugin-storybook": "10.4.6",
77
86
  "http-server": "^14.1.1",
78
87
  "lodash.merge": "^4.6.2",
79
- "playwright": "^1.61.1",
88
+ "playwright": "1.61.1",
80
89
  "storybook": "^10.4.6",
81
90
  "vitest": "^4.1.9",
91
+ "vue": "^3.5.41",
82
92
  "vue-component-meta": "^3.3.6"
83
93
  }
84
94
  }
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "sui-plugin",
3
3
  "description": "Skills for building Vue 3 / Nuxt apps with @khsura/sui — setup (npm install, styles, icons, theming, i18n), per-component references, forms, layouts and utilities",
4
- "version": "1.9.0",
4
+ "version": "1.26.0",
5
5
  "author": {
6
6
  "name": "Sura Kh",
7
7
  "email": "sura0111@gmail.com"
@@ -34,7 +34,7 @@ All components import from `@khsura/sui`. App setup (registry, `SApp`, styles, `
34
34
  | `SDivider` | [references/divider.md](references/divider.md) |
35
35
  | `SDroppable` | [references/droppable.md](references/droppable.md) |
36
36
  | `SExpansionPanels`, `SExpansionPanel`, `SExpansionPanelHeader`, `SExpansionPanelContent` | [references/expansion-panels.md](references/expansion-panels.md) |
37
- | `SForm`, `SInput`, `STextarea`, `SSelect`, `SCheckbox`, `SRadioGroup`, `SRadio`, `SSwitch` | [references/form.md](references/form.md) (and the **sui-form** skill) |
37
+ | `SForm`, `SFormRow`, `SInput`, `STextarea`, `SSelect`, `SCheckbox`, `SRadioGroup`, `SRadio`, `SSwitch` | [references/form.md](references/form.md) (and the **sui-form** skill) |
38
38
  | `SIcon` | [references/icon.md](references/icon.md) |
39
39
  | `SImage` | [references/image.md](references/image.md) |
40
40
  | `SApp`, `SLayout`, `SAppBar`, `SNavigationDrawer`, `SMain`, `SFooter`, `SBottomNavigation`, `SContainer`, `SRow`, `SColumn`, `SSpacer` | [references/layout.md](references/layout.md) (and the **sui-layout** skill) |
@@ -107,7 +107,7 @@ Popups teleport into the container rendered by `<SApp>` — without `SApp` at th
107
107
 
108
108
  | Prop | Renders | For |
109
109
  |---|---|---|
110
- | `to` | `router-link` | internal route |
110
+ | `to` | `router-link` (plain `<a href>` without vue-router) | internal route |
111
111
  | `href` | `<a>` | external URL (`target`, `rel` go with it) |
112
112
  | neither | `div` or `tag` | not a link |
113
113
 
@@ -130,6 +130,14 @@ Navigating from `@click` renders a `div` — no middle-click, "copy link", or li
130
130
  | `var(--s-color-surface-variant)` | `color-mix(in srgb, #{s_getAppColor('text')} 8%, transparent)` |
131
131
 
132
132
  - **`s_getPresetColor` keys:** `primary`, `secondary`, `success`, `info`, `warning`, `important`, `error` (+ any you add in `createSUI({ themes })`)
133
- - **`s_getAppColor` keys:** `appBar`, `title`, `text`, `secondaryText`, `anchor`, `background`, `card`, `button`, `switch`, `border`, `disabled`, `snackbar`, `inputPlaceholderShown`, `textErrorHover`
133
+ - **`s_getAppColor` keys:** `appBar`, `title`, `text`, `secondaryText`, `anchor`, `background`, `card`, `button`, `switch`, `border`, `disabled`, `snackbar`, `inputPlaceholderShown`, `textErrorHover`, `textError`, `focusRing`
134
134
 
135
135
  The variables are set on `<SApp>`, so they only resolve inside it. More helpers: **sui-utilities**.
136
+
137
+ ## Accessibility
138
+
139
+ - **Icon-only buttons need `aria-label`:** `<SButton variant="icon" aria-label="Close"><SIcon icon="mdi-close" /></SButton>`. Without it the button has no name (axe `button-name`, critical). The same goes for a link that wraps only an image.
140
+ - **Text on a colour is picked by WCAG contrast** (light or dark theme text, whichever contrasts more). Don't hard-code `color: white` on `color="success"` chips; the default `success` (`#2e7d32`) and light `secondary` (`#cc4125`) already reach 4.5:1 with their text. Passing `colorThreshold` switches back to the old YIQ brightness rule. A preset used as text (`color` on a text button, an outlined chip, `s_textColor__<name>`) is drawn with `--s-color-<name>--readable`, adjusted to 4.5:1 on the background and cards.
141
+ - **Keyboard:** SSelect and SAutocomplete are comboboxes (arrow keys move the highlighted option, Enter picks, Esc closes), STabs uses arrow keys / Home / End with one Tab stop, SRadioGroup uses native radio arrow keys, editable SStepper steps are buttons. Don't add your own `@keydown` handlers or `tabindex` for these.
142
+ - **Focus ring:** components draw a 2px `focusRing` outline under `:focus-visible`. Don't remove it with `outline: none`; for your own focusable element use `@include s_focusRing();`.
143
+ - SProgressCircular / SProgressLinear are named `Loading` by default; pass `aria-label` to say what loads. Full checklist: `docs/a11y.md` in the package and https://sui.surakh.com/.
@@ -15,8 +15,10 @@ Types: `node_modules/@khsura/sui/@types/definitions/props/propsAutocomplete.d.ts
15
15
  | --- | --- | --- | --- | --- |
16
16
  | `activator` | `string \| HTMLElement \| ComponentPublicInstance \| null` | — | no | — |
17
17
  | `allowUnlisted` | `boolean` | — | no | — |
18
+ | `ariaLabel` | `string \| null` | — | no | — |
18
19
  | `autocomplete` | `string` | `"off"` | no | — |
19
20
  | `chips` | `boolean` | — | no | — |
21
+ | `clearAriaLabel` | `string` | `"Clear"` | no | — |
20
22
  | `clearable` | `boolean` | — | no | — |
21
23
  | `closableChips` | `boolean` | — | no | — |
22
24
  | `closeOnClick` | `boolean` | — | no | — |
@@ -37,6 +39,7 @@ Types: `node_modules/@khsura/sui/@types/definitions/props/propsAutocomplete.d.ts
37
39
  | `items` | `string[] \| SelectItem[]` | — | no | — |
38
40
  | `label` | `string \| null` | — | no | — |
39
41
  | `loading` | `boolean` | — | no | — |
42
+ | `loadingAriaLabel` | `string` | `"Loading"` | no | — |
40
43
  | `location` | `LocationRaw` | `"bottom"` | no | — |
41
44
  | `maxHeight` | `string \| number \| null` | — | no | — |
42
45
  | `maxWidth` | `string \| number \| null` | — | no | — |
@@ -91,7 +94,7 @@ None.
91
94
  - `hideDetails`: Hide the label
92
95
  - `placeholder`: Input placeholder
93
96
  - `autocomplete`: Native `autocomplete` attribute
94
- - `size`: Preset size
97
+ - `size`: Input font size, as on `SInput` (`large` 1.25rem, `extra` 1.5rem, never below 16px)
95
98
  - `location`: Dropdown position (flips automatically)
96
99
  - `offsetX` / `offsetY`: Dropdown offset
97
100
  - `update:modelValue` (event): Selection changed
@@ -165,3 +168,5 @@ const searchUsers = async (query: string) => {
165
168
  - Single mode, no chips: the selected item's text is shown in the input itself.
166
169
  - Selected items keep their labels when `items` is replaced (async results), so chips don't go blank.
167
170
  - Toggling `multiple` at runtime drops a single value when switching back to single mode.
171
+ - The list opens on the roomier side of the field and stays 8px inside the viewport (shifted left near the right edge); no placement workaround needed.
172
+ - A long option stays on one line and ends in an ellipsis; its full text is in the option's `title`. No custom item slot needed for long labels.
@@ -43,7 +43,7 @@ None.
43
43
  ```ts
44
44
  interface BreadcrumbsItem {
45
45
  text: string | number
46
- to?: RouteLocationRaw // renders router-link
46
+ to?: LinkLocation // renders router-link (plain <a href> without vue-router)
47
47
  href?: string // renders <a>
48
48
  disabled?: boolean // renders plain <span>
49
49
  link?: boolean // declared on the type, not used by the component
@@ -77,4 +77,5 @@ Each item renders as `router-link` if `to` is set, else `<a>` if `href` is set,
77
77
  - The **last item is disabled automatically** (current page) unless you set `disabled: false` on it explicitly.
78
78
  - Disabled items ignore `color`.
79
79
  - Pass `to` or `href` per item, not both — `to` wins.
80
- - `to` requires vue-router in the app.
80
+ - vue-router is optional: without it a `to` item renders a plain `<a href>`; use a path, not a route `name`.
81
+ - The first crumb starts at the content edge (no list indent), so it lines up with the cards below. Older versions inherited a 1.5em `<ol>` indent; don't add a negative margin.
@@ -36,7 +36,7 @@ Types: `node_modules/@khsura/sui/@types/definitions/props/propsButton.d.ts`
36
36
  | `tag` | `"a" \| "button" \| null` | `"button"` | no | `a`, `button` |
37
37
  | `target` | `"_blank" \| "_self" \| "_parent" \| "_top"` | — | no | `_blank`, `_parent`, `_self`, `_top` |
38
38
  | `theme` | `AppThemeType` | — | no | `dark`, `light` |
39
- | `to` | `string \| it \| et \| null` | — | no | — |
39
+ | `to` | `LinkLocation \| null` | — | no | — |
40
40
  | `type` | `ButtonTypeType` | — | no | `button`, `reset`, `submit` |
41
41
  | `underlined` | `boolean \| null` | — | no | — |
42
42
  | `value` | `string \| number \| boolean` | — | no | — |
@@ -73,7 +73,7 @@ Types: `node_modules/@khsura/sui/@types/definitions/props/propsButton.d.ts`
73
73
  - `underlined`: Underlined style
74
74
  - `borderRadius`: Custom radius (`8`, `'8px'`, `'1rem'`, ...)
75
75
  - `href`: Renders an `<a href>`
76
- - `to`: Renders a `router-link` (needs vue-router)
76
+ - `to`: Renders a `router-link` when the app uses vue-router; without it, a plain `<a href>` (a route given by `name` gets no `href`, so pass a path)
77
77
  - `target`: Only applied with `href`
78
78
  - `rel`: Only applied with `href`
79
79
  - `tag`: Root tag when neither `href` nor `to` is set
@@ -32,7 +32,7 @@ Types: `node_modules/@khsura/sui/@types/definitions/props/propsCard.d.ts`
32
32
  | `tag` | `HtmlTagName \| null` | — | no | `a`, `abbr`, `acronym`, `address`, `applet`, `area`, `article`, `aside`, `audio`, `b`, `base`, `basefont`, `bdi`, `bdo`, `big`, `blockquote`, `body`, `br`, `button`, `canvas`, `caption`, `center`, `cite`, `code`, `col`, `colgroup`, `data`, `datalist`, `dd`, `del`, `details`, `dfn`, `dialog`, `dir`, `div`, `dl`, `dt`, `em`, `embed`, `fieldset`, `figcaption`, `figure`, `font`, `footer`, `form`, `frame`, `frameset`, `h1`, `h1> to <h6`, `h2`, `h3`, `h4`, `h5`, `h6`, `head`, `header`, `hr`, `html`, `i`, `iframe`, `img`, `input`, `ins`, `kbd`, `label`, `legend`, `li`, `link`, `main`, `map`, `mark`, `meta`, `meter`, `nav`, `noframes`, `noscript`, `object`, `ol`, `optgroup`, `option`, `output`, `p`, `param`, `picture`, `pre`, `progress`, `q`, `rp`, `rt`, `ruby`, `s`, `samp`, `script`, `section`, `select`, `small`, `source`, `span`, `strike`, `strong`, `style`, `sub`, `summary`, `sup`, `svg`, `table`, `tbody`, `td`, `template`, `textarea`, `tfoot`, `th`, `thead`, `time`, `title`, `tr`, `track`, `tt`, `u`, `ul`, `var`, `video`, `wbr` |
33
33
  | `target` | `"_blank" \| "_self" \| "_parent" \| "_top"` | — | no | `_blank`, `_parent`, `_self`, `_top` |
34
34
  | `theme` | `AppThemeType` | — | no | `dark`, `light` |
35
- | `to` | `string \| it \| et \| null` | — | no | — |
35
+ | `to` | `LinkLocation \| null` | — | no | — |
36
36
  | `underlined` | `boolean \| null` | — | no | — |
37
37
  | `width` | `string \| number \| null` | — | no | — |
38
38
 
@@ -59,7 +59,7 @@ None.
59
59
  - `borderRadius`: Border radius override
60
60
  - `tag`: Root element (ignored when `href`/`to` is set) (default: `'div'`)
61
61
  - `href`: Render as `<a>`
62
- - `to`: Render as `router-link` (takes precedence over `href`)
62
+ - `to`: Render as `router-link` (takes precedence over `href`; plain `<a href>` without vue-router)
63
63
  - `target`: Link target
64
64
  - `rel`: Link rel
65
65
  - `width` / `height`: Dimensions
@@ -86,7 +86,7 @@ Each takes only `tag` (default `'div'`) and a `default` slot. No events.
86
86
 
87
87
  Spacing between adjacent title → subtitle → text is tightened automatically.
88
88
 
89
- `SCardTitle` is a flex row, so `s_textAlign__center` on it has no effect. Centre its content with `s_justify__center` (`s_justify__end` for right).
89
+ `SCardTitle` is a flex row (so it can hold an icon, `SSpacer` and buttons). The `s_textAlign__*` classes, responsive ones included, also set the matching `justify-content` on it, so `class="s_textAlign__center"` centres the title. `s_justify__center` works too. A long title wraps between words; a single word wider than the card is split. (Before 1.20.0 `SCardTitle` ignored `s_textAlign__*`, so use `s_justify__*` there, and split titles at any letter.)
90
90
 
91
91
  <!-- generated:api:start SCardTitle -->
92
92
  <!-- Generated from sui-api.json by `yarn sync:skills` (packages/app). Do not edit by hand. -->
@@ -186,13 +186,14 @@ None.
186
186
  - `min` / `max`: Bounds for the popup and carousel buttons (default: ±5 years around `today` (picker))
187
187
  - `rules`: Validation rules
188
188
  - `hideDetails`: Hide label and error area
189
+ - Model: `''` and `null` both mean no date (before 1.20.0 `''` opened the picker on "Invalid date"; use `null` there). The picker stays 8px inside the viewport: above the field near the bottom, shifted left near the right edge
189
190
  - `hideError`: Hide the error message
190
191
  - `id`: Input id (default: auto)
191
192
  - `disabled` / `readonly`: Native input states; disable carousel buttons
192
193
  - `size`: Field size (font never below 16px)
193
194
  - `simple`: Borderless field
194
195
  - `tile`: Square corners
195
- - `block`: Stretch to container width (otherwise hugs the value)
196
+ - `block`: Stretch to container width (otherwise hugs the value). Never wider than its container: in a narrow column it shrinks like `SInput`, keeps the calendar button and ends the value in an ellipsis
196
197
  - `width` / `maxWidth` / `minWidth`: Field size; the popup stays 280px wide
197
198
  - `carousel`: Prev/next buttons stepping one day / month / year
198
199
  - `carouselPrevIcon` / `carouselNextIcon`: Button icons (default: `'mdi-chevron-left'` / `'mdi-chevron-right'`)
@@ -61,7 +61,7 @@ Types: `node_modules/@khsura/sui/@types/definitions/props/propsDialog.d.ts`
61
61
  - `zIndex`: z-index of the overlay layer
62
62
  - `disabled`: Passed to the activator via `attrs` (disables the trigger)
63
63
  - `width` / `height`: Content dimensions
64
- - `maxWidth` / `maxHeight` / `minWidth` / `minHeight`: Constraints (max-height defaults to 90% when not fullscreen)
64
+ - `maxWidth` / `maxHeight` / `minWidth` / `minHeight`: Constraints (max-height defaults to 90% when not fullscreen). `width`, `maxWidth` and `maxHeight` are capped at the viewport, so `:max-width="420"` still leaves a 12px gutter on a phone
65
65
  - `activator` (slot): Trigger. Bind **both** `v-on="on"` and `v-bind="attrs"`
66
66
  - `default` (slot): Dialog content
67
67
 
@@ -116,5 +116,6 @@ None — use `v-model`.
116
116
  | `persistent` with no close button | Always provide an explicit close action |
117
117
 
118
118
  - The app must be wrapped in `<SApp>`: dialogs teleport into the overlay container `SApp` renders.
119
- - There is no Escape-key handling and no `close` event.
119
+ - Keyboard and screen readers are handled: the content has `role="dialog"` and `aria-modal="true"`, focus moves into the dialog on open, Tab stays inside it, Esc closes it (not when `persistent`), and focus returns to the activator on close. Esc with a menu open inside the dialog closes only the menu. There is no `close` event — watch `v-model`.
120
+ - A `fullscreen` dialog pads by the iPhone safe-area insets on all sides and fills them with the card colour (needs `viewport-fit=cover`, see the getting-started skill). Don't add your own `env(safe-area-inset-*)` padding to it.
120
121
  - `borderless`, `scrollableBackground` and `closeOnClick` appear in the prop types but currently have no effect — do not rely on them.
@@ -81,7 +81,7 @@ None.
81
81
 
82
82
  ## SExpansionPanelHeader
83
83
 
84
- Clickable row that toggles its panel.
84
+ Clickable row that toggles its panel. Its text starts at the same 16px inset as `SExpansionPanelContent`, and the chevron sits 16px from the right edge, so header and content line up without extra padding classes. (Older versions indented the header text 8px more than the content.)
85
85
 
86
86
  <!-- generated:api:start SExpansionPanelHeader -->
87
87
  <!-- Generated from sui-api.json by `yarn sync:skills` (packages/app). Do not edit by hand. -->