@khsura/sui-mcp 0.2.1 → 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 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, STooltip, SSnackbar) or the layout-child note (SAppBar, SNavigationDrawer, SMain, SFooter, SBottomNavigation). Unknown names return an error with the three closest names. A component that only the bundled (newer) API has returns an error saying the project needs a newer `@khsura/sui`. |
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,14 +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). | `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`. | `validated-form` |
116
- | `snackbar-action-contrast` | warning | A `variant="text"` SButton with `color="primary"` (or `secondary`, `success`, `info`, `error`) in an SSnackbar `#action` slot: below 4.5:1 on the dark `#424242` snackbar. | `activator-overlays` |
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
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
- | `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. | — |
119
- | `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`. | `validated-form` |
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. |
120
122
 
121
- Recipe names are stable (`app-shell`, `validated-form`, `activator-overlays`, `data-table`, `responsive-grid`, `theme-setup`); `get_recipe` serves the recipes under these names.
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.
122
126
 
123
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`.
124
128
 
@@ -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`, `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/.