@khsura/sui-mcp 0.1.0 → 0.3.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/README.md +17 -6
- package/dist/guides/packages/app/docs/classes.md +1 -1
- package/dist/guides/plugins/sui-plugin/skills/sui-getting-started/SKILL.md +32 -7
- package/dist/index.js +697 -92
- package/dist/recipes/activator-overlays.md +1 -0
- package/dist/recipes/activator-overlays.vue +1 -1
- package/dist/recipes/app-shell.md +1 -1
- package/dist/recipes/centered-page.md +11 -0
- package/dist/recipes/centered-page.vue +44 -0
- package/dist/recipes/filter-bar.md +11 -0
- package/dist/recipes/filter-bar.vue +70 -0
- package/dist/recipes/responsive-grid.md +4 -1
- package/dist/recipes/responsive-grid.vue +37 -2
- package/dist/recipes/validated-form.md +6 -2
- package/dist/recipes/validated-form.vue +28 -8
- package/dist/sui-api.json +115 -5
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -81,12 +81,12 @@ The server sends these instructions when a client connects:
|
|
|
81
81
|
| Tool | What it returns |
|
|
82
82
|
| --- | --- |
|
|
83
83
|
| `list_components` | Every component with its family and a one-line purpose. |
|
|
84
|
-
| `get_component_api` | Props (type, default, required, allowed values), slots and events of one component as markdown. Accepts `SButton`, `s-button` or `button`. Adds the activator-pattern note (SDialog, SMenu,
|
|
84
|
+
| `get_component_api` | Props (type, default, required, allowed values), slots and events of one component as markdown. Accepts `SButton`, `s-button` or `button`. Adds the activator-pattern note (SDialog, SMenu, SSnackbar), the STooltip activator note (no slot props to bind), or the layout-child note (SAppBar, SNavigationDrawer, SMain, SFooter, SBottomNavigation). Unknown names return an error with the three closest names; a name from another UI library (`SCol`, `STextField`, `SBtn`, `SDataTable`, `STabsWindow`, `SAvatar`, …) gets its SUI equivalent and a hint first. A component that only the bundled (newer) API has returns an error saying the project needs a newer `@khsura/sui`. |
|
|
85
85
|
| `list_guides` | The setup guide topics with what each covers. |
|
|
86
86
|
| `get_guide` | One setup guide as markdown: `installation` (Vue and Nuxt, styles, `@mdi/font`), `theming` (theme colors, dark mode), `component-defaults`, `display` (`useDisplay` breakpoints), `i18n`, `common-mistakes`. Unknown topics return an error with the topic list. |
|
|
87
87
|
| `validate_sui_template` | Checks a `.vue` SFC or bare template fragment against the API and the composition rules below. Returns a summary line, then `line:col [rule] message — fix: hint — recipe: name` per issue (the recipe part only when one applies). Issues are a normal result, not a tool error. |
|
|
88
88
|
| `list_recipes` | The tested, copy-ready recipes with when to use each. |
|
|
89
|
-
| `get_recipe` | One recipe: its notes, the full Vue SFC in a ```` ```vue ```` block and the link to its live Storybook story. Names: `app-shell`, `validated-form`, `activator-overlays`, `data-table`, `responsive-grid`, `theme-setup`. Unknown names return an error with the name list. |
|
|
89
|
+
| `get_recipe` | One recipe: its notes, the full Vue SFC in a ```` ```vue ```` block and the link to its live Storybook story. Names: `app-shell`, `validated-form`, `activator-overlays`, `data-table`, `responsive-grid`, `theme-setup`, `filter-bar`, `centered-page`. Unknown names return an error with the name list. |
|
|
90
90
|
| `ping` | Health check. |
|
|
91
91
|
|
|
92
92
|
## Example prompts
|
|
@@ -102,7 +102,7 @@ The server sends these instructions when a client connects:
|
|
|
102
102
|
| Rule | Severity | What it catches | Recipe |
|
|
103
103
|
| --- | --- | --- | --- |
|
|
104
104
|
| `parse-error` | error | Template syntax errors. | — |
|
|
105
|
-
| `unknown-component` | error | An `S*` / `s-*` tag that does not exist, with the closest names. | — |
|
|
105
|
+
| `unknown-component` | error | An `S*` / `s-*` tag that does not exist, with the closest names. A name from another UI library gets its SUI equivalent first (the alias map in `src/constants/componentAliases.ts`); an alias stops applying once that name is a real component in `sui-api.json`. | — |
|
|
106
106
|
| `unknown-prop` | error | Static attributes, `:prop` / `v-bind:prop`, and `v-model` / `v-model:prop` targets the component does not have (kebab and camel case both accepted). | — |
|
|
107
107
|
| `invalid-enum-value` | error | A static value, or a quoted literal binding, outside an enum prop's values. | — |
|
|
108
108
|
| `unknown-slot` | error | `#name` / `v-slot:name` the component does not have. | — |
|
|
@@ -111,8 +111,18 @@ The server sends these instructions when a client connects:
|
|
|
111
111
|
| `form-rules-outside-form` | warning | An `S*` input with `rules` / `:rules` and no enclosing SForm: rules only run on value change, so untouched fields pass on submit. | `validated-form` |
|
|
112
112
|
| `icon-button-label` | warning | An SButton whose only content is an SIcon and that has no `aria-label`, `aria-labelledby` or `title`. | `app-shell` |
|
|
113
113
|
| `no-raw-replacement` | warning | Raw `<button>`, `<input>` (not `type="hidden"`), `<select>`, `<textarea>` or `<dialog>`, with the SUI component to use (`<input type="checkbox">` → SCheckbox, `radio` → SRadioGroup). | `validated-form`, `activator-overlays` for `<dialog>` |
|
|
114
|
+
| `native-validation-in-form` | warning | `type="email"`, `url` or `number` on an `S*` input inside an SForm without `novalidate`: the browser validates on submit and its bubble covers SUI's error text. The fix hint suggests `type="text" inputmode="email"` (or `novalidate` for numbers). Only before 1.20.0 (`fixedIn`). | `validated-form` |
|
|
115
|
+
| `hide-details-hides-label` | warning | `hide-details` on an SCheckbox that has a `label`: it hides the label too, so the checkbox shows no text. Use `hide-error`. Only before 1.20.0 (`fixedIn`). | `validated-form` |
|
|
116
|
+
| `snackbar-action-contrast` | warning | A `variant="text"` or `variant="icon"` SButton in an SSnackbar `#action` slot with a hex CSS `color` below 4.5:1 on the dark `#424242` snackbar (a CSS colour is used as is). Before 1.20.0 it also reports a `variant="text"` action with `color="primary"` (or `secondary`, `success`, `info`, `error`) and a text or icon action with no `color`, which kept the page's dark text colour there; from 1.20.0 an action without `color` takes the snackbar text colour and preset colours use a variant tuned to the snackbar. | `activator-overlays` |
|
|
117
|
+
| `block-buttons-in-row` | warning | Two or more `block` SButtons as siblings in a flex row (`s_display__flex` / `s_display--*__flex`, an inline `display: flex`, or SCardActions): `block` does not shrink, so later buttons are pushed off screen. | `responsive-grid` |
|
|
118
|
+
| `field-button-row` | warning | A text field (`SInput`, `SSelect`, `SDatePickerInput`, `SAutocomplete`, `STextarea`) without `hide-details` and an `SButton` as siblings in a flex row: the button lines up with the field's label, not its box. Use `SFormRow` (1.20.0+); recipe `filter-bar`. |
|
|
119
|
+
| `card-title-text-align` | warning | An `s_textAlign__*` class on SCardTitle, which is a flex container, so the class has no effect. The fix hint names the matching `s_justify__*` class. Only before 1.20.0 (`fixedIn`). | — |
|
|
120
|
+
| `date-picker-empty-string` | warning | An SDatePickerInput whose `v-model` / `:model-value` is `''`, or whose model starts as `''` in the SFC script (`x = ref('')`, `{ x: '' }`): the picker opens on "Invalid date". Start it as `null`. Only before 1.20.0 (`fixedIn`). | `validated-form` |
|
|
121
|
+
| `fill-height-under-app` | warning | `s_height--fill` on a direct child of `SApp`: before 1.20.0 it resolves to the content height (SApp only has a min-height), so a card centred inside it sticks to the top. Points to the `centered-page` recipe. Skipped from `@khsura/sui` 1.20.0, where that child grows to fill SApp. |
|
|
114
122
|
|
|
115
|
-
|
|
123
|
+
Rules for behaviours that a component fix removed carry a `fixedIn` version: the engine skips them when the resolved `sui-api.json` version is that version or newer, so a project on an older `@khsura/sui` still gets the warning. A `version` that is not semver keeps every rule on.
|
|
124
|
+
|
|
125
|
+
Recipe names are stable (`app-shell`, `validated-form`, `activator-overlays`, `data-table`, `responsive-grid`, `theme-setup`, `filter-bar`, `centered-page`); `get_recipe` serves the recipes under these names.
|
|
116
126
|
|
|
117
127
|
Future work: a `table-structure` rule (STable column keys and `item.<column>` slot names, per `packages/app/docs/components/table.md`) is waiting on complete STable slot data in `sui-api.json`.
|
|
118
128
|
|
|
@@ -121,11 +131,12 @@ Future work: a `table-structure` rule (STable column keys and `item.<column>` sl
|
|
|
121
131
|
- Global and common native attributes (`class`, `style`, `id`, `key`, `ref`, `role`, `type`, `href`, …), `aria-*`, `data-*` and `on*` listeners fall through to the component's root element, so they are never unknown props. The list is in `src/constants/templateValidator.ts`.
|
|
122
132
|
- Event listeners (`@x`, `v-on`), `v-bind="object"`, dynamic arguments (`:[name]`, `#[name]`) and dynamic values (`:size="x"`) are not checked.
|
|
123
133
|
- Components whose `sui-api.json` entry lists no slots (slots that could not be extracted, such as STable's `item.<column>`) skip the slot check.
|
|
124
|
-
- Non-SUI tags (`RouterLink`, …) are ignored, and native elements are only checked by `no-raw-replacement`.
|
|
134
|
+
- Non-SUI tags (`RouterLink`, …) are ignored, and native elements are only checked by `no-raw-replacement` and (as the parent of a button row) `block-buttons-in-row`.
|
|
125
135
|
- `layout-for` does not require `for` when there is no enclosing SLayout in the submitted code (the layout lives in a parent file) or the enclosing SLayout has no `name` (children without `for` join the app-level layout, which is correct). A child with `app`, a bound `:for` and a bound `:name` are not compared.
|
|
126
136
|
- `icon-button-label` cannot see inside `v-bind="object"`, so a button with an object spread is assumed labelled.
|
|
137
|
+
- The behaviour rules only read static values: a bound `:type`, `:color` or `:class` object, and a flex row made by a scoped CSS class, are not checked. `date-picker-empty-string` finds the model's initial value by its last path segment (`form.from` → `from: ''`) in the submitted SFC's script; models initialised elsewhere (a store, a prop) are not checked.
|
|
127
138
|
|
|
128
|
-
The API rules live in `src/services/templateRules.ts` and the composition rules in `src/services/compositionRules.ts`, as `{ id, target?, check(context) }` objects over the Vue template AST, independent of MCP, so more rules (or an eslint plugin) can reuse them. A rule sees the element, its ancestors and the
|
|
139
|
+
The API rules live in `src/services/templateRules.ts` and the composition rules in `src/services/compositionRules.ts`, the behaviour rules in `src/services/behaviourRules.ts`, as `{ id, target?, check(context) }` objects over the Vue template AST, independent of MCP, so more rules (or an eslint plugin) can reuse them. A rule sees the element, its ancestors, the catalog lookup and the SFC's script source; `target: 'any-element'` runs it on native elements too.
|
|
129
140
|
|
|
130
141
|
## Where the guides come from
|
|
131
142
|
|
|
@@ -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
|
---
|
|
@@ -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
|
|
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: {
|
|
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` / `
|
|
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
|
|
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/.
|