@khsura/sui 1.18.3 → 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 (133) 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 +17 -96
  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/types/table.d.ts +45 -0
  79. package/@types/vite.config.d.ts +1 -0
  80. package/README.md +22 -31
  81. package/dist/base.css.map +1 -1
  82. package/dist/s-ui.css +1 -1
  83. package/dist/s-ui.js +3122 -2478
  84. package/dist/s-ui.umd.cjs +1 -1
  85. package/dist/styles/components/button/mixins.scss +5 -0
  86. package/dist/styles/components/form/_variables.scss +11 -0
  87. package/dist/styles/components/form/index.scss +1 -0
  88. package/dist/styles/components/index.scss +1 -0
  89. package/dist/styles/mixins/_app.scss +7 -0
  90. package/dist/styles/tools/_safeArea.scss +8 -0
  91. package/dist/styles/tools/index.scss +1 -0
  92. package/dist/sui-api.json +10128 -0
  93. package/package.json +30 -6
  94. package/sui-plugin/.claude-plugin/plugin.json +2 -2
  95. package/sui-plugin/README.md +24 -1
  96. package/sui-plugin/skills/sui-component/SKILL.md +13 -3
  97. package/sui-plugin/skills/sui-component/references/alert.md +30 -14
  98. package/sui-plugin/skills/sui-component/references/autocomplete.md +96 -34
  99. package/sui-plugin/skills/sui-component/references/badge.md +55 -29
  100. package/sui-plugin/skills/sui-component/references/breadcrumbs.md +33 -19
  101. package/sui-plugin/skills/sui-component/references/button.md +76 -37
  102. package/sui-plugin/skills/sui-component/references/calendar.md +64 -34
  103. package/sui-plugin/skills/sui-component/references/cards.md +142 -25
  104. package/sui-plugin/skills/sui-component/references/carousel.md +107 -42
  105. package/sui-plugin/skills/sui-component/references/chip.md +52 -28
  106. package/sui-plugin/skills/sui-component/references/date-picker.md +148 -61
  107. package/sui-plugin/skills/sui-component/references/dialog.md +60 -21
  108. package/sui-plugin/skills/sui-component/references/divider.md +15 -6
  109. package/sui-plugin/skills/sui-component/references/droppable.md +36 -16
  110. package/sui-plugin/skills/sui-component/references/expansion-panels.md +107 -30
  111. package/sui-plugin/skills/sui-component/references/form.md +483 -35
  112. package/sui-plugin/skills/sui-component/references/icon.md +30 -11
  113. package/sui-plugin/skills/sui-component/references/image.md +39 -17
  114. package/sui-plugin/skills/sui-component/references/layout.md +456 -69
  115. package/sui-plugin/skills/sui-component/references/list.md +223 -52
  116. package/sui-plugin/skills/sui-component/references/menu.md +64 -28
  117. package/sui-plugin/skills/sui-component/references/overlay.md +35 -16
  118. package/sui-plugin/skills/sui-component/references/progress.md +76 -26
  119. package/sui-plugin/skills/sui-component/references/sheet.md +46 -23
  120. package/sui-plugin/skills/sui-component/references/slide-group.md +77 -38
  121. package/sui-plugin/skills/sui-component/references/snackbar.md +48 -17
  122. package/sui-plugin/skills/sui-component/references/split-view.md +51 -12
  123. package/sui-plugin/skills/sui-component/references/stepper.md +58 -23
  124. package/sui-plugin/skills/sui-component/references/table.md +123 -55
  125. package/sui-plugin/skills/sui-component/references/tabs.md +78 -30
  126. package/sui-plugin/skills/sui-component/references/toggle-button-group.md +85 -39
  127. package/sui-plugin/skills/sui-component/references/toolbar.md +92 -33
  128. package/sui-plugin/skills/sui-component/references/tooltip.md +58 -20
  129. package/sui-plugin/skills/sui-component/references/window.md +89 -29
  130. package/sui-plugin/skills/sui-form/SKILL.md +23 -16
  131. package/sui-plugin/skills/sui-getting-started/SKILL.md +60 -44
  132. package/sui-plugin/skills/sui-layout/SKILL.md +3 -1
  133. package/sui-plugin/skills/sui-utilities/docs/classes.md +1 -1
@@ -6,15 +6,63 @@ Small floating label shown while hovering an activator. Built on the `SMenu` pos
6
6
 
7
7
  Types: `node_modules/@khsura/sui/@types/definitions/props/propsTooltip.d.ts`
8
8
 
9
- ## Props
10
-
11
- | Prop | Type | Default | Description |
12
- |------|------|---------|-------------|
13
- | `location` | `string \| string[]` | `undefined` | `'top'`, `'bottom'`, `'left'`, `'right'`. **Unset = overlaps the activator** — always pass one |
14
- | `color` | `string` | `undefined` | Background. Use a CSS color (`'#333'`, `'rgb(...)'`); preset names are hidden by the default translucent background |
15
- | `offsetX` / `offsetY` | `number \| null` | `undefined` | Extra offset in px |
16
- | `position` | `'fixed' \| ...` | `undefined` | `'fixed'` = viewport-relative positioning |
17
- | `width` / `height` / `min*` / `max*` | `string \| number` | `undefined` | Tooltip dimensions |
9
+ <!-- generated:api:start STooltip -->
10
+ <!-- Generated from sui-api.json by `yarn sync:skills` (packages/app). Do not edit by hand. -->
11
+
12
+ **STooltip props**
13
+
14
+ | Prop | Type | Default | Required | Values |
15
+ | --- | --- | --- | --- | --- |
16
+ | `activator` | `string \| HTMLElement \| ComponentPublicInstance \| null` | — | no | — |
17
+ | `closeOnClick` | `boolean` | — | no | — |
18
+ | `closeOnContentClick` | `boolean` | — | no | — |
19
+ | `closeOnScroll` | `boolean` | — | no | — |
20
+ | `color` | `string` | — | no | — |
21
+ | `colorThreshold` | `number` | — | no | — |
22
+ | `contentClass` | `string \| string[] \| Record<string, boolean>` | — | no | — |
23
+ | `contentStyle` | `StyleValue` | — | no | — |
24
+ | `disabled` | `boolean \| null` | — | no | — |
25
+ | `height` | `string \| number \| null` | — | no | — |
26
+ | `location` | `LocationRaw` | — | no | — |
27
+ | `maxHeight` | `string \| number \| null` | — | no | — |
28
+ | `maxWidth` | `string \| number \| null` | — | no | — |
29
+ | `minHeight` | `string \| number \| null` | — | no | — |
30
+ | `minWidth` | `string \| number \| null` | — | no | — |
31
+ | `modelValue` | `boolean` | — | no | — |
32
+ | `offsetX` | `number \| null` | — | no | — |
33
+ | `offsetY` | `number \| null` | — | no | — |
34
+ | `opacity` | `string \| number` | — | no | — |
35
+ | `position` | `Position` | — | no | `absolute`, `fixed`, `relative`, `static`, `sticky` |
36
+ | `preventCloseOnClick` | `boolean` | — | no | — |
37
+ | `readonly` | `boolean \| null` | — | no | — |
38
+ | `screenPadding` | `number \| null` | — | no | — |
39
+ | `theme` | `AppThemeType` | — | no | `dark`, `light` |
40
+ | `width` | `string \| number \| null` | — | no | — |
41
+
42
+ **STooltip slots**
43
+
44
+ | Slot | Slot props |
45
+ | --- | --- |
46
+ | `activator` | `{}` |
47
+ | `default` | `{}` |
48
+
49
+ **STooltip events**
50
+
51
+ | Event | Payload |
52
+ | --- | --- |
53
+ | `update:modelValue` | `[value: boolean \| undefined]` |
54
+
55
+ <!-- generated:api:end STooltip -->
56
+
57
+ **STooltip notes**
58
+
59
+ - `location`: `'top'`, `'bottom'`, `'left'`, `'right'`. **Unset = overlaps the activator** — always pass one
60
+ - `color`: Background. Use a CSS color (`'#333'`, `'rgb(...)'`); preset names are hidden by the default translucent background
61
+ - `offsetX` / `offsetY`: Extra offset in px
62
+ - `position`: `'fixed'` = viewport-relative positioning
63
+ - `width` / `height` / `min*` / `max*`: Tooltip dimensions
64
+ - `activator` (slot): Hover target. STooltip wraps it in its own `<div>` that carries the hover/click listeners — do not bind anything
65
+ - `default` (slot): Tooltip content
18
66
 
19
67
  Other `SMenu` props are accepted by the types but are not meaningful for a tooltip.
20
68
 
@@ -22,17 +70,6 @@ Other `SMenu` props are accepted by the types but are not meaningful for a toolt
22
70
 
23
71
  `v-model: boolean` — optional; set by hover (and toggled by clicking the activator).
24
72
 
25
- ## Slots
26
-
27
- | Slot | Scoped data | Description |
28
- |------|-------------|-------------|
29
- | `activator` | **none** | Hover target. STooltip wraps it in its own `<div>` that carries the hover/click listeners — do not bind anything |
30
- | `default` | — | Tooltip content |
31
-
32
- ## Events
33
-
34
- None.
35
-
36
73
  ## Usage
37
74
 
38
75
  ```vue
@@ -61,5 +98,6 @@ None.
61
98
  | `disabled` to suppress the tooltip | Not supported — hover still opens it; use `v-if` on the tooltip |
62
99
 
63
100
  - The activator wrapper is a block `<div>`; wrap inline text if layout matters.
101
+ - Long text wraps at 320px (less on narrow screens), and the tooltip flips or shifts to stay 8px inside the viewport.
64
102
  - The app must be wrapped in `<SApp>` (tooltips teleport into its overlay container).
65
103
  - `opacity` appears in the prop types but has no effect.
@@ -4,35 +4,95 @@
4
4
 
5
5
  Shows one panel at a time with a slide transition, arrows and swipe. Use it for content and step panels; for image slideshows use [SCarousel](./carousel.md), which is built on it.
6
6
 
7
- ## SWindow props
8
-
9
- | Prop | Type | Default | Description |
10
- |------|------|---------|-------------|
11
- | `modelValue` (`v-model`) | `string \| number \| boolean` | — | `value` of the visible `SWindowItem`. When it names no item, the first item is selected and the model is updated to its value |
12
- | `mandatory` | `boolean` | — | Always keep an item selected |
13
- | `continuous` | `boolean` | — | Loop from last to first and back; without it the arrows stop at the ends |
14
- | `hideArrows` | `boolean` | — | Hide the prev/next arrows |
15
- | `touch` | `boolean \| TouchHandlers` | — | `true` enables swipe left/right; or pass your own handlers |
16
- | `noAnimation` | `boolean` | — | No slide transition |
17
- | `selectedClass` | `string` | — | Class added to the visible item |
18
- | `nextIcon` / `prevIcon` | `MaterialDesignIcon` | `'mdi-chevron-right'` / `'mdi-chevron-left'` | Arrow icons (needs `@mdi/font`) |
19
- | `color` | `string` | — | Arrow color |
20
- | `disabled` | `boolean` | — | Disable the arrows |
21
- | `tag` | `string` | `'div'` | Root element |
22
-
23
- ## SWindowItem props
24
-
25
- | Prop | Type | Description |
26
- |------|------|-------------|
27
- | `value` | `string \| number \| boolean` | Identifier matched against the window's `v-model` |
28
-
29
- ## Slots
30
-
31
- | Slot | Scope | Description |
32
- |------|-------|-------------|
33
- | `default` | `{ items, selected, select }` | The `SWindowItem`s. `select({ value })` or `select({ index })` changes the panel |
34
- | `prev` | `{ icon, click, disabled }` | Replace the previous arrow. Call `click()` to go back |
35
- | `next` | `{ icon, click }` | Replace the next arrow. Call `click()` to go forward |
7
+ <!-- generated:api:start SWindow -->
8
+ <!-- Generated from sui-api.json by `yarn sync:skills` (packages/app). Do not edit by hand. -->
9
+
10
+ **SWindow props**
11
+
12
+ | Prop | Type | Default | Required | Values |
13
+ | --- | --- | --- | --- | --- |
14
+ | `color` | `string` | — | no | — |
15
+ | `colorThreshold` | `number` | — | no | — |
16
+ | `continuous` | `boolean` | — | no | — |
17
+ | `disabled` | `boolean \| null` | — | no | — |
18
+ | `hideArrows` | `boolean` | — | no | — |
19
+ | `mandatory` | `boolean` | — | no | — |
20
+ | `modelValue` | `GroupItemValue` | — | no | — |
21
+ | `nextIcon` | `string` | `"mdi-chevron-right"` | no | — |
22
+ | `noAnimation` | `boolean` | — | no | — |
23
+ | `prevIcon` | `string` | `"mdi-chevron-left"` | no | — |
24
+ | `readonly` | `boolean \| null` | — | no | — |
25
+ | `selectedClass` | `string` | — | no | — |
26
+ | `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` |
27
+ | `theme` | `AppThemeType` | — | no | `dark`, `light` |
28
+ | `touch` | `boolean \| TouchHandlers` | — | no | — |
29
+
30
+ **SWindow slots**
31
+
32
+ | Slot | Slot props |
33
+ | --- | --- |
34
+ | `default` | `{ items: { value: GroupItemValue; readonly element: HTMLElement \| null; }[]; selected: { value: GroupItemValue \| undefined; id: number; }; select: (options: { value: GroupItemValue; index?: undefined; } \| { index: number; value?: undefined; }) => void; }` |
35
+ | `next` | `{ icon: string; click: () => void; }` |
36
+ | `prev` | `{ icon: string; click: () => void; disabled: boolean \| null \| undefined; }` |
37
+
38
+ **SWindow events**
39
+
40
+ | Event | Payload |
41
+ | --- | --- |
42
+ | `update:modelValue` | `[value: GroupItemValue \| undefined]` |
43
+
44
+ <!-- generated:api:end SWindow -->
45
+
46
+ **SWindow notes**
47
+
48
+ - `modelValue` (`v-model`): `value` of the visible `SWindowItem`. When it names no item, the first item is selected and the model is updated to its value
49
+ - `mandatory`: Always keep an item selected
50
+ - `continuous`: Loop from last to first and back; without it the arrows stop at the ends
51
+ - `hideArrows`: Hide the prev/next arrows
52
+ - `touch`: `true` enables swipe left/right; or pass your own handlers
53
+ - `noAnimation`: No slide transition
54
+ - `selectedClass`: Class added to the visible item
55
+ - `nextIcon` / `prevIcon`: Arrow icons (needs `@mdi/font`) (default: `'mdi-chevron-right'` / `'mdi-chevron-left'`)
56
+ - `color`: Arrow color
57
+ - `disabled`: Disable the arrows
58
+ - `tag`: Root element (default: `'div'`)
59
+ - `default` (slot): The `SWindowItem`s. `select({ value })` or `select({ index })` changes the panel
60
+ - `prev` (slot): Replace the previous arrow. Call `click()` to go back
61
+ - `next` (slot): Replace the next arrow. Call `click()` to go forward
62
+
63
+ <!-- generated:api:start SWindowItem -->
64
+ <!-- Generated from sui-api.json by `yarn sync:skills` (packages/app). Do not edit by hand. -->
65
+
66
+ **SWindowItem props**
67
+
68
+ | Prop | Type | Default | Required | Values |
69
+ | --- | --- | --- | --- | --- |
70
+ | `activeClass` | `string \| null` | — | no | — |
71
+ | `selected` | `boolean` | — | no | — |
72
+ | `value` | `string \| number \| boolean` | — | no | — |
73
+
74
+ **SWindowItem slots**
75
+
76
+ | Slot | Slot props |
77
+ | --- | --- |
78
+ | `default` | `{}` |
79
+
80
+ **SWindowItem events**
81
+
82
+ None.
83
+
84
+ <!-- generated:api:end SWindowItem -->
85
+
86
+ **SWindowItem notes**
87
+
88
+ - `value`: Identifier matched against the window's `v-model`
89
+
90
+ **Sizing**
91
+
92
+ - Without a `height`, `SWindow` takes the height of the active `SWindowItem`, so tab panels need no height. Set `height` only when every panel must be the same size (for example a fixed-height slideshow).
93
+ - `@khsura/sui` 1.19.0 and earlier rendered a window without `height` at 0 height (all items were absolutely positioned). On those versions set a `height`, or use `v-show` panels instead.
94
+
95
+ ## Template ref
36
96
 
37
97
  The component also exposes `goNext()` and `goPrev()` through a template ref.
38
98
 
@@ -18,15 +18,18 @@ Then generate a complete Vue SFC using these rules:
18
18
  **Form rules:**
19
19
 
20
20
  - Wrap everything in `<SForm ref="formRef" @submit.prevent="submit">` and validate in `submit` (see **SForm.validate()** below — its return value is inverted from what you'd expect)
21
+ - `SForm` renders `<form novalidate>`: the SUI `rules` are the only validation, so `type="email"`, `required` or `pattern` never pop the browser's own bubble over the SUI error. Validate emails with a rule. `:novalidate="false"` turns native validation back on. Before 1.20.0 `SForm` did not add `novalidate`; add it yourself there
22
+ - Every validated field reserves one line under itself for its error message, so the rhythm stays even when errors appear. For an action row (a field next to a button: a search bar, a filter bar), wrap the fields and buttons in `<SFormRow>`: each button lines up with the field box, with or without a label and while an error shows, and the row wraps on a phone. Never use a plain flex `<div>` there (the button lines up with the label); before 1.20.0, without `SFormRow`, put `hide-details` on the field. `SCheckbox` keeps its label with `hide-details` (before 1.20.0 it hid it; use `hide-error` there)
23
+ - Bind an empty `SDatePickerInput` as `''` or `null` — both mean "no date" (before 1.20.0 `''` opened on "Invalid date"; use `null` there)
21
24
  - Use `SInput` for text/email/password/number — always include `label` and `v-model`
22
- - Use `STextarea` for multi-line text (add `autogrow` if height should expand — all lowercase, not `auto-grow`)
23
- - Use `SSelect` for a plain single-value dropdown — `items` must be `SelectItem[]` or `string[]`. Type `SelectItem` from `@khsura/sui` (`text`, `value`, optional `disabled`). **SSelect has no `multiple`, `chips`, `clearable` or `placeholder`** — when you need any of those, use `SAutocomplete`.
25
+ - Use `STextarea` for multi-line text (add `autogrow` if height should expand — all lowercase, not `auto-grow`). For a character count use its `counter` prop (with `maxlength`: `12 / 200`), never a `<p>` after the field — that lands below the reserved error line, far from the field
26
+ - Use `SSelect` for a plain single-value dropdown — `items` must be `SelectItem[]` or `string[]`. Type `SelectItem` from `@khsura/sui` (`text`, `value`, optional `disabled`). It is outlined like `SInput` by default, never repeats its `label` inside the field (use `placeholder` for an empty-state hint) and is as wide as its longest option — add `grow` for full width. **SSelect has no `multiple`, `chips` or `clearable`** — when you need any of those, use `SAutocomplete`.
24
27
  - Use `SAutocomplete` for searchable, clearable or multi-select — same `items` shape, add `multiple chips closable-chips` for multi-select. **It has no `rules` and does not register with `SForm`** — check its value yourself in `submit`
25
- - Use `SCheckbox` for a single boolean — `label` prop, not slot. It has no `value`/`indeterminate`, so build checkbox groups from several boolean models
28
+ - Use `SCheckbox` for a single boolean — `label` prop, not slot. Its error line sits under the box and reserves the same space as under an input, and it keeps an 8px gap above the box (both dropped with `hide-details`). It has no `value`/`indeterminate`, so build checkbox groups from several boolean models
26
29
  - Use `SRadioGroup` with `<SRadio value="..." label="...">` children (slot-based); use `column` for vertical layout
27
30
  - Use `SSwitch` for on/off toggles — it never runs `rules`, shows no error and is not validated by `SForm`
28
- - Submit: `<SButton type="submit" color="primary" :loading="submitting">Submit</SButton>`
29
- - `:loading` on `SButton` implicitly disables it — do not also set `:disabled`
31
+ - Submit: `<SButton type="submit" color="primary" class="s_mt__2" :loading="submitting">Submit</SButton>` — `s_mt__2` keeps the last field's error message off the button
32
+ - `:loading` on `SButton` implicitly disables it — do not also bind `:disabled` to the submitting flag
30
33
 
31
34
  **Validation rules signature:** `(value: unknown) => true | string`
32
35
 
@@ -57,20 +60,24 @@ if (hasErrors) return
57
60
  - `v-model:error="hasError"` — `true` while any input has an error
58
61
  - `v-model:errors="messages"` — all current error strings
59
62
 
60
- Use them to disable the submit button; `resetValidation()` (exposed) clears every input's errors.
63
+ Use `v-model:error` to disable the submit button **only after a failed submit**: set `submitAttempted = true` in `submit` and bind `:disabled="submitAttempted && hasError"`; it re-enables as soon as every rule passes. Never disable it from page load (a disabled button gives no reason and cannot be focused), and keep the inline errors so users see why. `resetValidation()` (exposed) clears every input's errors.
61
64
 
62
65
  ---
63
66
 
64
67
  ## `hideDetails` vs `hideError`
65
68
 
66
- | Prop | Hides the label | Hides the error message | Red error frame |
67
- | ------------- | --------------- | ----------------------- | --------------------- |
68
- | _(neither)_ | no | no | shown |
69
- | `hideError` | no | **yes** | shown |
70
- | `hideDetails` | **yes** | **yes** | shown |
69
+ | Prop | Hides the label above the field | Hides the error message | Red error frame |
70
+ | ------------- | ------------------------------- | ----------------------- | --------------------- |
71
+ | _(neither)_ | no | no | shown |
72
+ | `hideError` | no | **yes** | shown |
73
+ | `hideDetails` | **yes** | **yes** | shown |
74
+
75
+ `SCheckbox` and `SRadio` labels are the control's own text, not a label above a field: `hideDetails` keeps them and only removes the error area.
71
76
 
72
77
  - Use **`hideError`** when you only want to drop the message line (dense tables, inline filters) but keep the label.
73
- - Use **`hideDetails`** only when the field should have no label either — it is not a "compact" switch.
78
+ - Use **`hideDetails`** only when the field should have no label either — it is not a "compact" switch. On `SCheckbox` the label is the only text, so `hideDetails` leaves a bare box ("Remember me" disappears); use `hideError` there.
79
+ - With `hideDetails` the hidden label still names the field (it becomes the control's `aria-label`). A field with no `label` at all needs `aria-label` (`ariaLabel` on SInput, STextarea, SSelect, SAutocomplete; on each SRadio without a `label`).
80
+ - Labels, ids and errors are wired for you: an `id` is generated when you don't pass one, and an invalid field gets `aria-invalid` and `aria-describedby` pointing at its error message. Don't add your own `<label for>` or `aria-describedby`.
74
81
  - The field frame turns red on error even with either flag set (`SInput`, `STextarea`, `SSelect`, `SCheckbox`, `SRadioGroup`, `SDatePickerInput`), so users can still see which field is invalid. Don't add your own `:deep()` error border.
75
82
 
76
83
  ---
@@ -141,13 +148,13 @@ Use this to choose the right component and props for each field.
141
148
  | Component | v-model | Key props | When to use |
142
149
  | ----------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
143
150
  | **SInput** | `string \| number` | `label`, `type` (`text` \| `email` \| `password` \| `number` \| `tel` \| `url` \| `search`), `placeholder`, `suffix`, `dense`, `readonly`, `max`/`min`, `maxlength`/`minlength`, `inputmode` (`numeric` \| `decimal` \| `email` \| `tel`), `positive` / `allowDecimal` (numbers), `size` | Single-line text, email, password, number |
144
- | **STextarea** | `string` | `label`, `placeholder`, `rows`, `cols`, `autogrow`, `resize`, `dense`, `tile`, `maxlength`/`minlength`, `readonly` | Multi-line text |
145
- | **SSelect** | `string \| number` | `items`: `SelectItem[]` or `string[]` (type from `@khsura/sui`: `text`, `value`, optional `disabled`). Also `label`, `dense`, `grow`, `text`, `divided`, `color`, `outlined`/`underlined`/`borderRadius`. **No** `multiple`/`chips`/`clearable`/`placeholder` | Single-value dropdown |
151
+ | **STextarea** | `string` | `label`, `placeholder`, `rows`, `cols`, `autogrow`, `resize`, `counter`, `dense`, `tile`, `maxlength`/`minlength`, `readonly` | Multi-line text |
152
+ | **SSelect** | `string \| number` | `items`: `SelectItem[]` or `string[]` (type from `@khsura/sui`: `text`, `value`, optional `disabled`). Also `label`, `placeholder`, `dense`, `grow`, `text`, `divided`, `color`, `outlined` (default `true`)/`underlined`/`borderRadius`. **No** `multiple`/`chips`/`clearable` | Single-value dropdown |
146
153
  | **SAutocomplete** | `any` or `any[]` | Same `items` as SSelect; + `multiple`, `chips`, `closableChips`, `clearable`, `placeholder`, `filter`, `filterMode`, `debounce`, `loading`, `allowUnlisted`, `delimiter`. `debounce` defaults to 500 ms. Events: **`@search-item`** (search text, for async options), **`@create-item`** (with `allowUnlisted`). No `rules`; `disabled` does not disable its text field | Searchable / multi / async select |
147
154
  | **SCheckbox** | `boolean` | `label`, `color`, `size` (`'default'` \| `'large'`), `block`, `bordered`, `readonly` | Single boolean |
148
155
  | **SRadioGroup** | `any` | Slot content: `<SRadio value="..." label="...">` children (no `items` prop). Props: `column`, `grow`, `color`, `name` | Single choice from list |
149
156
  | **SSwitch** | `boolean` | `label`, `color` | On/off toggle |
150
- | **SDatePickerInput** | `string` | `label`, `placeholder`, `type` (`'date'` \| `'month'` \| `'year'`), `min`/`max`, `dense`, `readonly`, `simple`, `tile`, `size`, `block` (off by default; `maxWidth` caps it), `carousel` (prev/next buttons that step the value by one day / month / year). Without `min`/`max` the selectable range is Jan 1 five years before today to Dec 31 five years after — pass `min` for birth dates | Date, month or year field with a picker popup |
157
+ | **SDatePickerInput** | `string \| null` | `label`, `placeholder`, `type` (`'date'` \| `'month'` \| `'year'`), `min`/`max`, `dense`, `readonly`, `simple`, `tile`, `size`, `block` (off by default; `maxWidth` caps it), `carousel` (prev/next buttons that step the value by one day / month / year). Without `min`/`max` the selectable range is Jan 1 five years before today to Dec 31 five years after — pass `min` for birth dates | Date, month or year field with a picker popup |
151
158
 
152
159
  **SelectItem** (SSelect, SAutocomplete): from `@khsura/sui` — `{ text: string, value: string | number | null | undefined, disabled?: boolean }` or plain `string`. Use `text` and `value`, not `title` or `label`.
153
160
 
@@ -169,7 +176,7 @@ For full props, slots, and events per component, read [form.md](../sui-component
169
176
  <SForm ref="formRef" @submit.prevent="submit">
170
177
  <SInput v-model="form.name" label="Full Name" :rules="[required]" />
171
178
 
172
- <SInput v-model="form.email" label="Email" type="email" :rules="[required, email]" />
179
+ <SInput v-model="form.email" label="Email" type="text" inputmode="email" autocomplete="email" :rules="[required, email]" />
173
180
 
174
181
  <SInput v-model="form.password" label="Password" type="password" :rules="[required, minLength(8)]" />
175
182
 
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: sui-getting-started
3
- description: Set up and configure @khsura/sui in a Vue 3 or Nuxt app. Use when installing @khsura/sui (GitHub Packages registry, .npmrc / .yarnrc.yml, read:packages token, CI auth), wiring createSUI and the SApp root, importing the stylesheets and @mdi/font icons, adding @khsura/sui-nuxt, overriding theme colors or switching dark mode with useTheme, setting app-wide component defaults, setting up vue-i18n for SUI messages and form rules, importing SUI TypeScript types, or looking up shared props, the component list, composables and common mistakes.
3
+ description: Set up and configure @khsura/sui in a Vue 3 or Nuxt app. Use when installing @khsura/sui (public npm, migrating off the old GitHub Packages registry), wiring createSUI and the SApp root, importing the stylesheets and @mdi/font icons, adding @khsura/sui-nuxt, overriding theme colors or switching dark mode with useTheme, setting app-wide component defaults, setting up vue-i18n for SUI messages and form rules, importing SUI TypeScript types, setting up the @khsura/sui-mcp MCP server for Claude Code, Cursor, VS Code or Windsurf, or looking up shared props, the component list, composables and common mistakes.
4
4
  ---
5
5
 
6
6
  # SUI — Getting Started in a consumer app
@@ -9,55 +9,38 @@ description: Set up and configure @khsura/sui in a Vue 3 or Nuxt app. Use when i
9
9
 
10
10
  ---
11
11
 
12
- ## 1. Install (GitHub Packages, not npmjs.com)
12
+ ## 1. Install (public npm)
13
13
 
14
- `@khsura/sui` is published to **`https://npm.pkg.github.com`**. A plain `yarn add @khsura/sui` / `npm i @khsura/sui` fails (404 / 401) until the `@khsura` scope points at that registry **and** a token is supplied.
14
+ `@khsura/sui` is published to the **public npm registry** — no registry config, `.npmrc` or token needed:
15
15
 
16
- **Token:** a GitHub personal access token (classic) with the **`read:packages`** scope. Keep it in an environment variable (`NPM_GITHUB_TOKEN` below) — never commit it.
17
-
18
- ### Yarn 4 (Berry) — `.yarnrc.yml`
19
-
20
- ```yaml
21
- npmScopes:
22
- khsura:
23
- npmRegistryServer: "https://npm.pkg.github.com"
24
- npmAlwaysAuth: true
25
- npmAuthToken: "${NPM_GITHUB_TOKEN}"
26
-
27
- # optional: read the token from a git-ignored file instead of the shell
28
- injectEnvironmentFiles:
29
- - .env.yarn?
16
+ ```bash
17
+ npm i @khsura/sui @mdi/font # or: yarn add / pnpm add
30
18
  ```
31
19
 
32
- `.env.yarn` (add it to `.gitignore`): `NPM_GITHUB_TOKEN=ghp_xxx`
20
+ Component docs and live examples: **Storybook at https://sui.surakh.com/**
33
21
 
34
- ### npm / pnpm — project `.npmrc`
22
+ ### Migrating from GitHub Packages
35
23
 
36
- ```ini
37
- @khsura:registry=https://npm.pkg.github.com
38
- //npm.pkg.github.com/:_authToken=${NPM_GITHUB_TOKEN}
39
- ```
24
+ Older versions were published to GitHub Packages. If your project still points the `@khsura` scope there, remove that config, or installs keep hitting the old registry (404 / 401 for new versions):
40
25
 
41
- The `.npmrc` with the `${...}` placeholder is safe to commit; the token itself is not.
26
+ - `.npmrc` (npm / pnpm): delete the `@khsura:registry=...` line that points at GitHub Packages, and its matching `:_authToken=...` line.
27
+ - `.yarnrc.yml` (Yarn 4): delete the `npmScopes.khsura` block (`npmRegistryServer`, `npmAlwaysAuth`, `npmAuthToken`).
28
+ - CI: the GitHub token secret your install step used for SUI is no longer needed.
42
29
 
43
- ### CI
30
+ `vue` is a **peer dependency** (`^3.5.41`): the app provides it. `vue-i18n` and `dayjs` come in as dependencies of `@khsura/sui`. `@mdi/font` is **not** included — install it yourself (see step 3). `vue-router` is **optional**: with it, `to` props render a `router-link`; without it, they render a plain `<a href>`.
44
31
 
45
- Expose the token as an env var from a secret — the config files above read it:
32
+ ### Vue version — 3.5.41 or newer
46
33
 
47
- ```yaml
48
- # GitHub Actions
49
- - run: yarn install --immutable # or npm ci / pnpm install --frozen-lockfile
50
- env:
51
- NPM_GITHUB_TOKEN: ${{ secrets.NPM_GITHUB_TOKEN }}
52
- ```
34
+ Use **Vue 3.5.41 or newer** in the app — it is the peer range, so npm reports a peer conflict on an older Vue. If the app pins or locks `vue` at 3.5.40 or older, upgrade it (`npm i vue@^3.5.41`). Don't add a second copy of Vue.
53
35
 
54
- Then install:
36
+ Vue 3.5.40 and older have a template compiler bug (fixed in vuejs/core#11682). It hits an element in a `v-for` over a constant array that has `:key` and `v-show` and no other dynamic binding: its `v-show` never updates. The usual case is a tab panel per section, and the tabs look broken even though `STabs` updates its `v-model`:
55
37
 
56
- ```bash
57
- yarn add @khsura/sui @mdi/font # or: npm i / pnpm add
38
+ ```vue
39
+ <!-- With Vue ≤ 3.5.40 and a `const sections = [...]`, the panels never switch -->
40
+ <section v-for="section in sections" v-show="activeTab === section.key" :key="section.key">
58
41
  ```
59
42
 
60
- `vue`, `vue-i18n` and `dayjs` come in as dependencies of `@khsura/sui`. `@mdi/font` is **not** included — install it yourself (see step 3).
43
+ Upgrade Vue. If you can't, render the panels with `SWindow` / `SWindowItem` bound to the same model (it sizes itself to the active panel; on `@khsura/sui` 1.19.0 and earlier give `SWindow` a `height` or it renders at 0 height), or move `:key` to a wrapping `<template v-for="section in sections" :key="section.key">` and keep `v-show` on the element inside it.
61
44
 
62
45
  ---
63
46
 
@@ -94,6 +77,16 @@ import { SApp } from '@khsura/sui'
94
77
 
95
78
  Import components where you use them (Vue): `import { SButton, SCard } from '@khsura/sui'`.
96
79
 
80
+ ### iPhone notch and home indicator — `viewport-fit=cover`
81
+
82
+ For a full-screen app on iPhone (a PWA, a Capacitor/Cordova shell, a web view), opt in to the safe areas in `index.html` (Nuxt: `app.head.meta` in `nuxt.config.ts`):
83
+
84
+ ```html
85
+ <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />
86
+ ```
87
+
88
+ `SApp` then reads `env(safe-area-inset-*)` into `--s-safe-area-top|right|bottom|left`, and these components pad by them: a fixed `SAppBar` (below the notch, plus the side insets in landscape; `SMain` and a desktop drawer start below it), `SBottomNavigation` (grows above the home indicator), the mobile `SNavigationDrawer` (top, bottom and the side it opens from), a `fullscreen` `SDialog` (all sides) and `SSnackbar` (above the home indicator, or below the notch with `location="top"`). Without `viewport-fit=cover`, on desktop and on Android the insets are `0px` and nothing changes. Don't add your own `env(safe-area-inset-*)` padding to these components: it would double the inset. Content you place at a screen edge yourself can use the same variables, e.g. `padding-bottom: var(--s-safe-area-bottom)`.
89
+
97
90
  ---
98
91
 
99
92
  ## 3. Styles and icons
@@ -112,7 +105,7 @@ Import components where you use them (Vue): `import { SButton, SCard } from '@kh
112
105
 
113
106
  ## 4. Nuxt — `@khsura/sui-nuxt`
114
107
 
115
- `@khsura/sui-nuxt` is a Nuxt module (Nuxt ≥ 4) published to the **same GitHub Packages registry**, so the registry/token setup above covers it.
108
+ `@khsura/sui-nuxt` is a Nuxt module (Nuxt ≥ 4) under the same `@khsura` scope; install it the same way.
116
109
 
117
110
  ```bash
118
111
  yarn add @khsura/sui @khsura/sui-nuxt @mdi/font
@@ -169,7 +162,8 @@ app.use(
169
162
  ```
170
163
 
171
164
  - **`presetColors` keys:** `primary`, `secondary`, `success`, `info`, `warning`, `important`, `error` — usable as `color="..."` on components. Extra keys you add become usable too.
172
- - **`appColors` keys:** `appBar`, `title`, `text`, `secondaryText`, `anchor`, `background`, `card`, `button`, `switch`, `border`, `disabled`, `snackbar`, `inputPlaceholderShown`, `textErrorHover`.
165
+ - **`appColors` keys:** `appBar`, `title`, `text`, `secondaryText`, `anchor`, `background`, `card`, `button`, `switch`, `border`, `disabled`, `snackbar`, `inputPlaceholderShown`, `textErrorHover`, `textError`, `focusRing`.
166
+ - **Contrast:** each preset's text colour (`--s-color-<name>--text`) is the light or dark theme `text` colour with the higher WCAG contrast ratio. Pick preset values that reach 4.5:1 with one of them; `getContrastRatio` is not exported, so check with any contrast tool. `textError` (form error text) must reach 4.5:1 and `focusRing` 3:1 on `background` and `card`.
173
167
  - Use **opaque hex** values (`#ffc107`). An alpha hex (`#ffc10799`) looks washed out everywhere; for translucency use `color-mix(in srgb, #{s_getPresetColor('warning')} 60%, transparent)` in SCSS.
174
168
 
175
169
  ### Dark mode — `useTheme()`
@@ -194,7 +188,7 @@ Set a prop once for every instance instead of repeating it (or overriding classe
194
188
  app.use(
195
189
  createSUI({
196
190
  components: {
197
- SSelect: { outlined: true },
191
+ SSelect: { grow: true },
198
192
  SButton: { color: 'primary', size: 'small' },
199
193
  SInput: { dense: true },
200
194
  },
@@ -295,7 +289,7 @@ Available on most components (check the component's reference when unsure):
295
289
  | `disabled` | `boolean` | Disable interaction |
296
290
  | `width` / `height` / `maxWidth` / `minWidth` | `string \| number` | Dimensions |
297
291
  | `tag` | `string` | Override root element |
298
- | `href` / `to` | `string` / `RouteLocationRaw` | Render as `<a>` / `router-link` |
292
+ | `href` / `to` | `string` / `LinkLocation` | Render as `<a>` / `router-link` (`to` falls back to `<a href>` without vue-router) |
299
293
 
300
294
  ---
301
295
 
@@ -341,8 +335,8 @@ Directives (`v-scroll`, `v-resize`) and utility classes: **sui-utilities**.
341
335
 
342
336
  | ❌ | ✅ |
343
337
  |---|---|
344
- | `yarn add @khsura/sui` with no registry config → 404/401 | Point `@khsura` at `https://npm.pkg.github.com` and supply a `read:packages` token (step 1) |
345
- | Token pasted into a committed `.npmrc` / `.yarnrc.yml` | `${NPM_GITHUB_TOKEN}` placeholder + env var / CI secret |
338
+ | `npm i @khsura/sui` → 404/401 | A leftover `@khsura` scope override still points at GitHub Packages — remove it from `.npmrc` / `.yarnrc.yml` (step 1, *Migrating from GitHub Packages*) |
339
+ | Tab panels (`v-for` + `:key` + `v-show`) never switch although `STabs` updates its model | Vue 3.5.40 or older: upgrade to Vue 3.5.41 or newer (step 1, *Vue version*) |
346
340
  | Icons render as empty boxes | Load `@mdi/font` — `import '@mdi/font/css/materialdesignicons.css'` (Vue) or `css: ['@mdi/font/css/materialdesignicons.css']` (Nuxt) |
347
341
  | Only `style.css` (or only `base.css`) imported | Import both in plain Vue; the Nuxt module loads them |
348
342
  | No `<SApp>` root → no colors, dialogs/menus never show | Wrap the app in `<SApp>` |
@@ -354,16 +348,38 @@ Directives (`v-scroll`, `v-resize`) and utility classes: **sui-utilities**.
354
348
  | `SMenu` without `location` opens on top of its button | `location="bottom"` |
355
349
  | Named `SLayout` with un-`for`ed children | `for` on every child, or `name`/`for` on none |
356
350
  | Items as `{ title, value }` / `{ label, id }` | `{ text, value }` or plain strings |
357
- | `SSelect multiple / chips / clearable / placeholder` | `SAutocomplete` |
351
+ | `SSelect multiple / chips / clearable` | `SAutocomplete` |
358
352
  | Rule returns `false` | Return a message string |
359
353
  | `if (!formRef.value.validate()) return` | `validate()` returns `true` when there **are** errors |
360
- | `hideDetails` to hide just the error | `hideError` (`hideDetails` hides the label too) |
354
+ | `hideDetails` to hide just the error | `hideError` (`hideDetails` hides the label above a field too; `SCheckbox`/`SRadio` keep their own label) |
361
355
  | Unknown props (`SDialog title`, `persistent-hint`, `app`) | Silently ignored — check `@types/definitions/props` |
362
356
  | `:deep(.s_*) { … !important }` | A prop, a `createSUI({ components })` default, or theme colors |
363
357
  | `alpha` hex in `presetColors` | Opaque hex + `color-mix()` where you need translucency |
364
358
 
365
359
  ---
366
360
 
361
+ ## AI tooling — the SUI MCP server
362
+
363
+ `@khsura/sui-mcp` is a local stdio MCP server that answers from the `@khsura/sui` version the project installs. Set it up from the app's folder:
364
+
365
+ ```bash
366
+ npx -y @khsura/sui-mcp config # detects Claude Code / Cursor / VS Code / Windsurf and writes the config
367
+ npx -y @khsura/sui-mcp config --dry-run # print the planned changes only
368
+ npx -y @khsura/sui-mcp config --client cursor
369
+ ```
370
+
371
+ It merges a `sui` entry (`{ "command": "npx", "args": ["-y", "@khsura/sui-mcp"] }`) into `.mcp.json` (Claude Code), `.cursor/mcp.json` (Cursor) or `.vscode/mcp.json` (VS Code, under `servers` with `"type": "stdio"`), keeping other servers. For Windsurf it prints the snippet for `~/.codeium/windsurf/mcp_config.json`. Restart the client afterwards.
372
+
373
+ When the server is connected:
374
+
375
+ - Call `get_component_api` before using a component you have not checked; it reports the project's version. If it says the component needs a newer `@khsura/sui`, upgrade or pick another component.
376
+ - Start common patterns (app shell, validated form, activator overlays, data table, responsive grid, theme setup, filter bar, centered page) from `get_recipe`.
377
+ - Run `validate_sui_template` on every template you write and fix every error before finishing.
378
+
379
+ Per-client snippets: the package README at https://www.npmjs.com/package/@khsura/sui-mcp and the **AI / MCP** page at https://sui.surakh.com/.
380
+
381
+ ---
382
+
367
383
  ## Related skills
368
384
 
369
385
  Use the installed plugin rather than copying these files into a project (`.claude/skills/`) — copies go stale when SUI updates.
@@ -24,7 +24,9 @@ Then generate a complete Vue SFC using these rules:
24
24
  - `SMain for="app"` — wraps all page content
25
25
  - `SFooter for="app"` — optional bottom bar
26
26
  - `SBottomNavigation for="app" v-model="activeNav" :height="56" active-class="…"` — mobile bottom tabs. Set `height` (it collapses without one) and `active-class` (there is no active styling otherwise)
27
- - Below the `md` breakpoint the drawer becomes a mobile overlay; toggle it with `v-model`
27
+ - The drawer opens itself on desktop and closes itself below the `md` breakpoint, at mount and on resize (unless `persistent`). On mobile it is an overlay with a scrim: toggle it with `v-model`; a tap on the scrim closes it
28
+ - `SApp` already fills the viewport height (`100dvh`) and `SAppBar` already insets its content from the edges — don't add a `min-height: 100vh` wrapper or app bar padding
29
+ - Centred page without an app shell (login, error page): make the page root a **direct child of `SApp`** with `s_display__flex s_justify__center s_align__center s_height--fill`. A direct child with `s_height--fill` grows to fill `SApp`, so the card is centred vertically (since `@khsura/sui` 1.20.0; on older versions `height: 100%` resolves to auto there, so put `style="min-height: 100dvh"` on that child). Start from the `centered-page` recipe
28
30
  - Keep one app-level `SLayout`. A nested/secondary `SLayout` does not offset its `SMain` for a drawer and `permanent` has no effect there — use the grid or `SSplitView` inside pages instead
29
31
  - `SDivider` in a flex column collapses to zero width (it's an `<hr>` with auto margins) — give it `width: 100%` / `align-self: stretch`
30
32
  - Use `SSpacer` inside `SAppBar` to push items right
@@ -390,7 +390,7 @@ Adds a Material Design box shadow. Maps to the same values as the `elevation` co
390
390
 
391
391
  | Class | CSS |
392
392
  |-------|-----|
393
- | `s_height--fill` | `height: 100%` |
393
+ | `s_height--fill` | `height: 100%`. On a direct child of `SApp` it also sets `flex: 1 1 auto`, so the child fills the viewport-tall app (a percentage height of a `min-height` parent would resolve to auto) |
394
394
  | `s_width--fill` | `width: 100%` |
395
395
 
396
396
  ---