@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.
- package/@types/components/cards/sCardText.vue.d.ts +2 -2
- package/@types/components/datePicker/sDatePickerSwitch.vue.d.ts +2 -0
- package/@types/components/form/index.d.ts +1 -0
- package/@types/components/form/radio/sRadio.vue.d.ts +3 -0
- package/@types/components/form/sFormRow.vue.d.ts +18 -0
- package/@types/components/form/sInput.vue.d.ts +1 -0
- package/@types/components/form/sSelect.vue.d.ts +2 -0
- package/@types/components/layout/sNavigationDrawer.vue.d.ts +6 -6
- package/@types/components/progress/sProgressCircular.vue.d.ts +1 -0
- package/@types/components/progress/sProgressLinear.vue.d.ts +1 -0
- package/@types/components/sAutocomplete.vue.d.ts +3 -0
- package/@types/components/slideGroup/sSlideGroup.vue.d.ts +4 -1
- package/@types/components/table/sTable.vue.d.ts +17 -96
- package/@types/components/tabs/sTabs.vue.d.ts +2 -2
- package/@types/configs/app.d.ts +4 -0
- package/@types/configs/i18n.d.ts +3 -0
- package/@types/configs/provider.d.ts +1 -0
- package/@types/constants/color.d.ts +15 -0
- package/@types/constants/cssVariables.d.ts +4 -0
- package/@types/constants/datePicker.d.ts +7 -0
- package/@types/constants/i18n.d.ts +3 -0
- package/@types/constants/index.d.ts +3 -0
- package/@types/constants/keyboard.d.ts +12 -0
- package/@types/constants/listbox.d.ts +1 -0
- package/@types/constants/overlay.d.ts +5 -0
- package/@types/constants/tabs.d.ts +4 -0
- package/@types/definitions/props/core/propsLink.d.ts +2 -2
- package/@types/definitions/props/propsAutocomplete.d.ts +6 -0
- package/@types/definitions/props/propsInput.d.ts +1 -0
- package/@types/definitions/props/propsLink.d.ts +2 -2
- package/@types/definitions/props/propsProgressCircular.d.ts +2 -0
- package/@types/definitions/props/propsProgressLinear.d.ts +2 -0
- package/@types/definitions/props/propsSelect.d.ts +4 -0
- package/@types/definitions/props/propsSlideGroup.d.ts +4 -0
- package/@types/definitions/props/propsTable.d.ts +1 -0
- package/@types/definitions/props/propsTextarea.d.ts +3 -0
- package/@types/helpers/colorHelpers.d.ts +1 -1
- package/@types/helpers/createAppStore.d.ts +4 -0
- package/@types/lib/color.d.ts +21 -2
- package/@types/lib/index.d.ts +4 -0
- package/@types/lib/linkLocation.d.ts +9 -0
- package/@types/lib/overlayPlacement.d.ts +11 -0
- package/@types/lib/revealInScroller.d.ts +11 -0
- package/@types/lib/safeArea.d.ts +3 -0
- package/@types/playwright.visual.config.d.ts +3 -0
- package/@types/services/backgroundScrollService.d.ts +8 -2
- package/@types/services/datePicker/datePickerItemDateService.d.ts +1 -0
- package/@types/services/dialogService.d.ts +4 -8
- package/@types/services/fieldLayoutService.d.ts +19 -0
- package/@types/services/formInputService.d.ts +6 -0
- package/@types/services/index.d.ts +7 -0
- package/@types/services/linkService.d.ts +11 -1
- package/@types/services/listboxNavigationService.d.ts +20 -0
- package/@types/services/menuService.d.ts +2 -0
- package/@types/services/overlayFocusService.d.ts +10 -0
- package/@types/services/routerLinkService.d.ts +19 -0
- package/@types/services/scrollableFocusService.d.ts +10 -0
- package/@types/services/surfaceTextColorService.d.ts +8 -0
- package/@types/services/tabsService.d.ts +9 -0
- package/@types/store/index.d.ts +1 -0
- package/@types/store/scrollLockStore.d.ts +1 -0
- package/@types/tests/visual/constants/a11yAudit.d.ts +4 -0
- package/@types/tests/visual/constants/index.d.ts +4 -0
- package/@types/tests/visual/constants/resizeScroll.d.ts +10 -0
- package/@types/tests/visual/constants/storyRender.d.ts +5 -0
- package/@types/tests/visual/constants/visualMatrix.d.ts +20 -0
- package/@types/tests/visual/schemas/index.d.ts +1 -0
- package/@types/tests/visual/schemas/storyIndex.d.ts +17 -0
- package/@types/tests/visual/types/a11yAudit.d.ts +2 -0
- package/@types/tests/visual/types/index.d.ts +2 -0
- package/@types/tests/visual/types/visualStory.d.ts +8 -0
- package/@types/types/app.d.ts +2 -0
- package/@types/types/breadcrumbs.d.ts +2 -2
- package/@types/types/index.d.ts +2 -0
- package/@types/types/link.d.ts +20 -0
- package/@types/types/menu.d.ts +17 -0
- package/@types/types/safeArea.d.ts +1 -0
- package/@types/types/table.d.ts +45 -0
- package/@types/vite.config.d.ts +1 -0
- package/README.md +22 -31
- package/dist/base.css.map +1 -1
- package/dist/s-ui.css +1 -1
- package/dist/s-ui.js +3122 -2478
- package/dist/s-ui.umd.cjs +1 -1
- package/dist/styles/components/button/mixins.scss +5 -0
- package/dist/styles/components/form/_variables.scss +11 -0
- package/dist/styles/components/form/index.scss +1 -0
- package/dist/styles/components/index.scss +1 -0
- package/dist/styles/mixins/_app.scss +7 -0
- package/dist/styles/tools/_safeArea.scss +8 -0
- package/dist/styles/tools/index.scss +1 -0
- package/dist/sui-api.json +10128 -0
- package/package.json +30 -6
- package/sui-plugin/.claude-plugin/plugin.json +2 -2
- package/sui-plugin/README.md +24 -1
- package/sui-plugin/skills/sui-component/SKILL.md +13 -3
- package/sui-plugin/skills/sui-component/references/alert.md +30 -14
- package/sui-plugin/skills/sui-component/references/autocomplete.md +96 -34
- package/sui-plugin/skills/sui-component/references/badge.md +55 -29
- package/sui-plugin/skills/sui-component/references/breadcrumbs.md +33 -19
- package/sui-plugin/skills/sui-component/references/button.md +76 -37
- package/sui-plugin/skills/sui-component/references/calendar.md +64 -34
- package/sui-plugin/skills/sui-component/references/cards.md +142 -25
- package/sui-plugin/skills/sui-component/references/carousel.md +107 -42
- package/sui-plugin/skills/sui-component/references/chip.md +52 -28
- package/sui-plugin/skills/sui-component/references/date-picker.md +148 -61
- package/sui-plugin/skills/sui-component/references/dialog.md +60 -21
- package/sui-plugin/skills/sui-component/references/divider.md +15 -6
- package/sui-plugin/skills/sui-component/references/droppable.md +36 -16
- package/sui-plugin/skills/sui-component/references/expansion-panels.md +107 -30
- package/sui-plugin/skills/sui-component/references/form.md +483 -35
- package/sui-plugin/skills/sui-component/references/icon.md +30 -11
- package/sui-plugin/skills/sui-component/references/image.md +39 -17
- package/sui-plugin/skills/sui-component/references/layout.md +456 -69
- package/sui-plugin/skills/sui-component/references/list.md +223 -52
- package/sui-plugin/skills/sui-component/references/menu.md +64 -28
- package/sui-plugin/skills/sui-component/references/overlay.md +35 -16
- package/sui-plugin/skills/sui-component/references/progress.md +76 -26
- package/sui-plugin/skills/sui-component/references/sheet.md +46 -23
- package/sui-plugin/skills/sui-component/references/slide-group.md +77 -38
- package/sui-plugin/skills/sui-component/references/snackbar.md +48 -17
- package/sui-plugin/skills/sui-component/references/split-view.md +51 -12
- package/sui-plugin/skills/sui-component/references/stepper.md +58 -23
- package/sui-plugin/skills/sui-component/references/table.md +123 -55
- package/sui-plugin/skills/sui-component/references/tabs.md +78 -30
- package/sui-plugin/skills/sui-component/references/toggle-button-group.md +85 -39
- package/sui-plugin/skills/sui-component/references/toolbar.md +92 -33
- package/sui-plugin/skills/sui-component/references/tooltip.md +58 -20
- package/sui-plugin/skills/sui-component/references/window.md +89 -29
- package/sui-plugin/skills/sui-form/SKILL.md +23 -16
- package/sui-plugin/skills/sui-getting-started/SKILL.md +60 -44
- package/sui-plugin/skills/sui-layout/SKILL.md +3 -1
- 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
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
|
15
|
-
|
|
|
16
|
-
| `
|
|
17
|
-
| `
|
|
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
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
|
13
|
-
|
|
|
14
|
-
| `
|
|
15
|
-
| `
|
|
16
|
-
| `
|
|
17
|
-
| `
|
|
18
|
-
| `
|
|
19
|
-
| `
|
|
20
|
-
| `
|
|
21
|
-
| `
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
|
26
|
-
|
|
27
|
-
| `
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
|
34
|
-
| `
|
|
35
|
-
| `next` | `{ icon
|
|
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
|
|
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
|
|
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
|
|
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
|
|
69
|
-
| `hideError` | no
|
|
70
|
-
| `hideDetails` | **yes**
|
|
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
|
|
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`
|
|
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 (
|
|
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 (
|
|
12
|
+
## 1. Install (public npm)
|
|
13
13
|
|
|
14
|
-
`@khsura/sui` is published to
|
|
14
|
+
`@khsura/sui` is published to the **public npm registry** — no registry config, `.npmrc` or token needed:
|
|
15
15
|
|
|
16
|
-
|
|
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
|
-
|
|
20
|
+
Component docs and live examples: **Storybook at https://sui.surakh.com/**
|
|
33
21
|
|
|
34
|
-
###
|
|
22
|
+
### Migrating from GitHub Packages
|
|
35
23
|
|
|
36
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
32
|
+
### Vue version — 3.5.41 or newer
|
|
46
33
|
|
|
47
|
-
|
|
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
|
-
|
|
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
|
-
```
|
|
57
|
-
|
|
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
|
-
|
|
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)
|
|
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: {
|
|
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` / `
|
|
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
|
-
| `
|
|
345
|
-
|
|
|
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
|
|
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
|
-
-
|
|
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
|
---
|