@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
@@ -98,5 +98,6 @@ Other `SMenu` props are accepted by the types but are not meaningful for a toolt
98
98
  | `disabled` to suppress the tooltip | Not supported — hover still opens it; use `v-if` on the tooltip |
99
99
 
100
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.
101
102
  - The app must be wrapped in `<SApp>` (tooltips teleport into its overlay container).
102
103
  - `opacity` appears in the prop types but has no effect.
@@ -87,6 +87,11 @@ None.
87
87
 
88
88
  - `value`: Identifier matched against the window's `v-model`
89
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
+
90
95
  ## Template ref
91
96
 
92
97
  The component also exposes `goNext()` and `goPrev()` through a template ref.
@@ -18,17 +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
- - **No `type="email"`, `type="url"` or `type="number"` inside `SForm`** unless the form has `novalidate`: those types make the browser validate on submit, its bubble covers SUI's error text and the submit handler never runs. For email/URL write `type="text" inputmode="email" autocomplete="email"` (or `url`) and check the format with a rule. For a number field keep `type="number"` (SInput writes a `number`) and add `novalidate`: `<SForm ref="formRef" novalidate @submit.prevent="submit">`
23
- - Start an empty `SDatePickerInput` model as `null` (type it `string | null`), never `''` — `''` opens the picker on "Invalid date" and a grid of NaN
24
- - Use `STextarea` for multi-line text (add `autogrow` if height should expand — all lowercase, not `auto-grow`)
25
- - 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`.
26
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`
27
- - 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
28
29
  - Use `SRadioGroup` with `<SRadio value="..." label="...">` children (slot-based); use `column` for vertical layout
29
30
  - Use `SSwitch` for on/off toggles — it never runs `rules`, shows no error and is not validated by `SForm`
30
- - Submit: `<SButton type="submit" color="primary" :loading="submitting">Submit</SButton>`
31
- - `: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
32
33
 
33
34
  **Validation rules signature:** `(value: unknown) => true | string`
34
35
 
@@ -59,20 +60,24 @@ if (hasErrors) return
59
60
  - `v-model:error="hasError"` — `true` while any input has an error
60
61
  - `v-model:errors="messages"` — all current error strings
61
62
 
62
- 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.
63
64
 
64
65
  ---
65
66
 
66
67
  ## `hideDetails` vs `hideError`
67
68
 
68
- | Prop | Hides the label | Hides the error message | Red error frame |
69
- | ------------- | --------------- | ----------------------- | --------------------- |
70
- | _(neither)_ | no | no | shown |
71
- | `hideError` | no | **yes** | shown |
72
- | `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.
73
76
 
74
77
  - Use **`hideError`** when you only want to drop the message line (dense tables, inline filters) but keep the label.
75
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`.
76
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.
77
82
 
78
83
  ---
@@ -143,8 +148,8 @@ Use this to choose the right component and props for each field.
143
148
  | Component | v-model | Key props | When to use |
144
149
  | ----------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
145
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 |
146
- | **STextarea** | `string` | `label`, `placeholder`, `rows`, `cols`, `autogrow`, `resize`, `dense`, `tile`, `maxlength`/`minlength`, `readonly` | Multi-line text |
147
- | **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 |
148
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 |
149
154
  | **SCheckbox** | `boolean` | `label`, `color`, `size` (`'default'` \| `'large'`), `block`, `bordered`, `readonly` | Single boolean |
150
155
  | **SRadioGroup** | `any` | Slot content: `<SRadio value="..." label="...">` children (no `items` prop). Props: `column`, `grow`, `color`, `name` | Single choice from list |
@@ -27,7 +27,20 @@ Older versions were published to GitHub Packages. If your project still points t
27
27
  - `.yarnrc.yml` (Yarn 4): delete the `npmScopes.khsura` block (`npmRegistryServer`, `npmAlwaysAuth`, `npmAuthToken`).
28
28
  - CI: the GitHub token secret your install step used for SUI is no longer needed.
29
29
 
30
- `vue`, `vue-i18n` and `dayjs` come in as dependencies of `@khsura/sui`. `@mdi/font` is **not** included — install it yourself (see step 3).
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>`.
31
+
32
+ ### Vue version — 3.5.41 or newer
33
+
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.
35
+
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`:
37
+
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">
41
+ ```
42
+
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.
31
44
 
32
45
  ---
33
46
 
@@ -64,6 +77,16 @@ import { SApp } from '@khsura/sui'
64
77
 
65
78
  Import components where you use them (Vue): `import { SButton, SCard } from '@khsura/sui'`.
66
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
+
67
90
  ---
68
91
 
69
92
  ## 3. Styles and icons
@@ -139,7 +162,8 @@ app.use(
139
162
  ```
140
163
 
141
164
  - **`presetColors` keys:** `primary`, `secondary`, `success`, `info`, `warning`, `important`, `error` — usable as `color="..."` on components. Extra keys you add become usable too.
142
- - **`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`.
143
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.
144
168
 
145
169
  ### Dark mode — `useTheme()`
@@ -164,7 +188,7 @@ Set a prop once for every instance instead of repeating it (or overriding classe
164
188
  app.use(
165
189
  createSUI({
166
190
  components: {
167
- SSelect: { outlined: true },
191
+ SSelect: { grow: true },
168
192
  SButton: { color: 'primary', size: 'small' },
169
193
  SInput: { dense: true },
170
194
  },
@@ -265,7 +289,7 @@ Available on most components (check the component's reference when unsure):
265
289
  | `disabled` | `boolean` | Disable interaction |
266
290
  | `width` / `height` / `maxWidth` / `minWidth` | `string \| number` | Dimensions |
267
291
  | `tag` | `string` | Override root element |
268
- | `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) |
269
293
 
270
294
  ---
271
295
 
@@ -312,6 +336,7 @@ Directives (`v-scroll`, `v-resize`) and utility classes: **sui-utilities**.
312
336
  | ❌ | ✅ |
313
337
  |---|---|
314
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*) |
315
340
  | Icons render as empty boxes | Load `@mdi/font` — `import '@mdi/font/css/materialdesignicons.css'` (Vue) or `css: ['@mdi/font/css/materialdesignicons.css']` (Nuxt) |
316
341
  | Only `style.css` (or only `base.css`) imported | Import both in plain Vue; the Nuxt module loads them |
317
342
  | No `<SApp>` root → no colors, dialogs/menus never show | Wrap the app in `<SApp>` |
@@ -323,10 +348,10 @@ Directives (`v-scroll`, `v-resize`) and utility classes: **sui-utilities**.
323
348
  | `SMenu` without `location` opens on top of its button | `location="bottom"` |
324
349
  | Named `SLayout` with un-`for`ed children | `for` on every child, or `name`/`for` on none |
325
350
  | Items as `{ title, value }` / `{ label, id }` | `{ text, value }` or plain strings |
326
- | `SSelect multiple / chips / clearable / placeholder` | `SAutocomplete` |
351
+ | `SSelect multiple / chips / clearable` | `SAutocomplete` |
327
352
  | Rule returns `false` | Return a message string |
328
353
  | `if (!formRef.value.validate()) return` | `validate()` returns `true` when there **are** errors |
329
- | `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) |
330
355
  | Unknown props (`SDialog title`, `persistent-hint`, `app`) | Silently ignored — check `@types/definitions/props` |
331
356
  | `:deep(.s_*) { … !important }` | A prop, a `createSUI({ components })` default, or theme colors |
332
357
  | `alpha` hex in `presetColors` | Opaque hex + `color-mix()` where you need translucency |
@@ -348,7 +373,7 @@ It merges a `sui` entry (`{ "command": "npx", "args": ["-y", "@khsura/sui-mcp"]
348
373
  When the server is connected:
349
374
 
350
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.
351
- - Start common patterns (app shell, validated form, activator overlays, data table, responsive grid, theme setup) from `get_recipe`.
376
+ - Start common patterns (app shell, validated form, activator overlays, data table, responsive grid, theme setup, filter bar, centered page) from `get_recipe`.
352
377
  - Run `validate_sui_template` on every template you write and fix every error before finishing.
353
378
 
354
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/.
@@ -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
  ---