@khsura/sui 1.18.3 → 1.20.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (133) hide show
  1. package/@types/components/cards/sCardText.vue.d.ts +2 -2
  2. package/@types/components/datePicker/sDatePickerSwitch.vue.d.ts +2 -0
  3. package/@types/components/form/index.d.ts +1 -0
  4. package/@types/components/form/radio/sRadio.vue.d.ts +3 -0
  5. package/@types/components/form/sFormRow.vue.d.ts +18 -0
  6. package/@types/components/form/sInput.vue.d.ts +1 -0
  7. package/@types/components/form/sSelect.vue.d.ts +2 -0
  8. package/@types/components/layout/sNavigationDrawer.vue.d.ts +6 -6
  9. package/@types/components/progress/sProgressCircular.vue.d.ts +1 -0
  10. package/@types/components/progress/sProgressLinear.vue.d.ts +1 -0
  11. package/@types/components/sAutocomplete.vue.d.ts +3 -0
  12. package/@types/components/slideGroup/sSlideGroup.vue.d.ts +4 -1
  13. package/@types/components/table/sTable.vue.d.ts +17 -96
  14. package/@types/components/tabs/sTabs.vue.d.ts +2 -2
  15. package/@types/configs/app.d.ts +4 -0
  16. package/@types/configs/i18n.d.ts +3 -0
  17. package/@types/configs/provider.d.ts +1 -0
  18. package/@types/constants/color.d.ts +15 -0
  19. package/@types/constants/cssVariables.d.ts +4 -0
  20. package/@types/constants/datePicker.d.ts +7 -0
  21. package/@types/constants/i18n.d.ts +3 -0
  22. package/@types/constants/index.d.ts +3 -0
  23. package/@types/constants/keyboard.d.ts +12 -0
  24. package/@types/constants/listbox.d.ts +1 -0
  25. package/@types/constants/overlay.d.ts +5 -0
  26. package/@types/constants/tabs.d.ts +4 -0
  27. package/@types/definitions/props/core/propsLink.d.ts +2 -2
  28. package/@types/definitions/props/propsAutocomplete.d.ts +6 -0
  29. package/@types/definitions/props/propsInput.d.ts +1 -0
  30. package/@types/definitions/props/propsLink.d.ts +2 -2
  31. package/@types/definitions/props/propsProgressCircular.d.ts +2 -0
  32. package/@types/definitions/props/propsProgressLinear.d.ts +2 -0
  33. package/@types/definitions/props/propsSelect.d.ts +4 -0
  34. package/@types/definitions/props/propsSlideGroup.d.ts +4 -0
  35. package/@types/definitions/props/propsTable.d.ts +1 -0
  36. package/@types/definitions/props/propsTextarea.d.ts +3 -0
  37. package/@types/helpers/colorHelpers.d.ts +1 -1
  38. package/@types/helpers/createAppStore.d.ts +4 -0
  39. package/@types/lib/color.d.ts +21 -2
  40. package/@types/lib/index.d.ts +4 -0
  41. package/@types/lib/linkLocation.d.ts +9 -0
  42. package/@types/lib/overlayPlacement.d.ts +11 -0
  43. package/@types/lib/revealInScroller.d.ts +11 -0
  44. package/@types/lib/safeArea.d.ts +3 -0
  45. package/@types/playwright.visual.config.d.ts +3 -0
  46. package/@types/services/backgroundScrollService.d.ts +8 -2
  47. package/@types/services/datePicker/datePickerItemDateService.d.ts +1 -0
  48. package/@types/services/dialogService.d.ts +4 -8
  49. package/@types/services/fieldLayoutService.d.ts +19 -0
  50. package/@types/services/formInputService.d.ts +6 -0
  51. package/@types/services/index.d.ts +7 -0
  52. package/@types/services/linkService.d.ts +11 -1
  53. package/@types/services/listboxNavigationService.d.ts +20 -0
  54. package/@types/services/menuService.d.ts +2 -0
  55. package/@types/services/overlayFocusService.d.ts +10 -0
  56. package/@types/services/routerLinkService.d.ts +19 -0
  57. package/@types/services/scrollableFocusService.d.ts +10 -0
  58. package/@types/services/surfaceTextColorService.d.ts +8 -0
  59. package/@types/services/tabsService.d.ts +9 -0
  60. package/@types/store/index.d.ts +1 -0
  61. package/@types/store/scrollLockStore.d.ts +1 -0
  62. package/@types/tests/visual/constants/a11yAudit.d.ts +4 -0
  63. package/@types/tests/visual/constants/index.d.ts +4 -0
  64. package/@types/tests/visual/constants/resizeScroll.d.ts +10 -0
  65. package/@types/tests/visual/constants/storyRender.d.ts +5 -0
  66. package/@types/tests/visual/constants/visualMatrix.d.ts +20 -0
  67. package/@types/tests/visual/schemas/index.d.ts +1 -0
  68. package/@types/tests/visual/schemas/storyIndex.d.ts +17 -0
  69. package/@types/tests/visual/types/a11yAudit.d.ts +2 -0
  70. package/@types/tests/visual/types/index.d.ts +2 -0
  71. package/@types/tests/visual/types/visualStory.d.ts +8 -0
  72. package/@types/types/app.d.ts +2 -0
  73. package/@types/types/breadcrumbs.d.ts +2 -2
  74. package/@types/types/index.d.ts +2 -0
  75. package/@types/types/link.d.ts +20 -0
  76. package/@types/types/menu.d.ts +17 -0
  77. package/@types/types/safeArea.d.ts +1 -0
  78. package/@types/types/table.d.ts +45 -0
  79. package/@types/vite.config.d.ts +1 -0
  80. package/README.md +22 -31
  81. package/dist/base.css.map +1 -1
  82. package/dist/s-ui.css +1 -1
  83. package/dist/s-ui.js +3122 -2478
  84. package/dist/s-ui.umd.cjs +1 -1
  85. package/dist/styles/components/button/mixins.scss +5 -0
  86. package/dist/styles/components/form/_variables.scss +11 -0
  87. package/dist/styles/components/form/index.scss +1 -0
  88. package/dist/styles/components/index.scss +1 -0
  89. package/dist/styles/mixins/_app.scss +7 -0
  90. package/dist/styles/tools/_safeArea.scss +8 -0
  91. package/dist/styles/tools/index.scss +1 -0
  92. package/dist/sui-api.json +10128 -0
  93. package/package.json +30 -6
  94. package/sui-plugin/.claude-plugin/plugin.json +2 -2
  95. package/sui-plugin/README.md +24 -1
  96. package/sui-plugin/skills/sui-component/SKILL.md +13 -3
  97. package/sui-plugin/skills/sui-component/references/alert.md +30 -14
  98. package/sui-plugin/skills/sui-component/references/autocomplete.md +96 -34
  99. package/sui-plugin/skills/sui-component/references/badge.md +55 -29
  100. package/sui-plugin/skills/sui-component/references/breadcrumbs.md +33 -19
  101. package/sui-plugin/skills/sui-component/references/button.md +76 -37
  102. package/sui-plugin/skills/sui-component/references/calendar.md +64 -34
  103. package/sui-plugin/skills/sui-component/references/cards.md +142 -25
  104. package/sui-plugin/skills/sui-component/references/carousel.md +107 -42
  105. package/sui-plugin/skills/sui-component/references/chip.md +52 -28
  106. package/sui-plugin/skills/sui-component/references/date-picker.md +148 -61
  107. package/sui-plugin/skills/sui-component/references/dialog.md +60 -21
  108. package/sui-plugin/skills/sui-component/references/divider.md +15 -6
  109. package/sui-plugin/skills/sui-component/references/droppable.md +36 -16
  110. package/sui-plugin/skills/sui-component/references/expansion-panels.md +107 -30
  111. package/sui-plugin/skills/sui-component/references/form.md +483 -35
  112. package/sui-plugin/skills/sui-component/references/icon.md +30 -11
  113. package/sui-plugin/skills/sui-component/references/image.md +39 -17
  114. package/sui-plugin/skills/sui-component/references/layout.md +456 -69
  115. package/sui-plugin/skills/sui-component/references/list.md +223 -52
  116. package/sui-plugin/skills/sui-component/references/menu.md +64 -28
  117. package/sui-plugin/skills/sui-component/references/overlay.md +35 -16
  118. package/sui-plugin/skills/sui-component/references/progress.md +76 -26
  119. package/sui-plugin/skills/sui-component/references/sheet.md +46 -23
  120. package/sui-plugin/skills/sui-component/references/slide-group.md +77 -38
  121. package/sui-plugin/skills/sui-component/references/snackbar.md +48 -17
  122. package/sui-plugin/skills/sui-component/references/split-view.md +51 -12
  123. package/sui-plugin/skills/sui-component/references/stepper.md +58 -23
  124. package/sui-plugin/skills/sui-component/references/table.md +123 -55
  125. package/sui-plugin/skills/sui-component/references/tabs.md +78 -30
  126. package/sui-plugin/skills/sui-component/references/toggle-button-group.md +85 -39
  127. package/sui-plugin/skills/sui-component/references/toolbar.md +92 -33
  128. package/sui-plugin/skills/sui-component/references/tooltip.md +58 -20
  129. package/sui-plugin/skills/sui-component/references/window.md +89 -29
  130. package/sui-plugin/skills/sui-form/SKILL.md +23 -16
  131. package/sui-plugin/skills/sui-getting-started/SKILL.md +60 -44
  132. package/sui-plugin/skills/sui-layout/SKILL.md +3 -1
  133. package/sui-plugin/skills/sui-utilities/docs/classes.md +1 -1
package/package.json CHANGED
@@ -1,20 +1,33 @@
1
1
  {
2
2
  "name": "@khsura/sui",
3
- "version": "1.18.3",
3
+ "version": "1.20.0",
4
+ "repository": {
5
+ "type": "git",
6
+ "url": "git+https://github.com/khsura/sui.git",
7
+ "directory": "packages/app"
8
+ },
9
+ "homepage": "https://sui.surakh.com/",
4
10
  "type": "module",
5
11
  "scripts": {
6
12
  "prebuild": "yarn g:rimraf dist && yarn g:rimraf @types && yarn g:rimraf .claude-plugin && yarn g:rimraf sui-plugin",
7
13
  "build:style": "yarn g:sass styles/index.scss dist/base.css",
8
14
  "build:type": "yarn g:vue-tsc -p tsconfig.build.json && yarn g:tsc-alias -p tsconfig.build.json",
9
15
  "build:plugin": "cp -R ../../.claude-plugin . && cp -R ../../plugins/sui-plugin .",
10
- "build": "yarn prebuild && yarn build:type && yarn g:vite build && yarn build:style && cp -R styles dist/styles && yarn build:plugin",
16
+ "build": "yarn prebuild && yarn build:type && yarn g:vite build && yarn build:api && yarn sync:skills && yarn build:style && cp -R styles dist/styles && yarn build:plugin",
11
17
  "lint": "yarn g:eslint",
12
18
  "stylelint": "yarn g:stylelint ./**/*.{vue,css,scss}",
13
19
  "test": "yarn g:vitest run --project unit",
14
20
  "test-storybook": "yarn g:vitest --project storybook",
21
+ "test:consumer": "bash scripts/consumerSmoke/runConsumerSmoke.sh",
22
+ "test:visual": "bash scripts/visual/runVisualInDocker.sh",
23
+ "test:visual:update": "bash scripts/visual/runVisualInDocker.sh --update",
24
+ "test:visual:container": "storybook build --quiet && playwright test -c playwright.visual.config.ts",
15
25
  "release": "yarn g:publish",
16
26
  "storybook:dev": "storybook dev --port 6006",
17
- "storybook:build": "storybook build"
27
+ "storybook:build": "storybook build",
28
+ "build:api": "yarn g:vite-node scripts/apiMetadata/generateApiMetadata.ts",
29
+ "sync:skills": "yarn g:vite-node scripts/apiMetadata/syncSkillTables.ts",
30
+ "check:skills": "yarn g:vite-node scripts/apiMetadata/syncSkillTables.ts --check"
18
31
  },
19
32
  "files": [
20
33
  "dist",
@@ -22,6 +35,10 @@
22
35
  ".claude-plugin",
23
36
  "sui-plugin"
24
37
  ],
38
+ "publishConfig": {
39
+ "access": "public",
40
+ "registry": "https://registry.npmjs.org/"
41
+ },
25
42
  "main": "./dist/s-ui.umd.cjs",
26
43
  "module": "./dist/s-ui.js",
27
44
  "types": "./@types/index.d.ts",
@@ -46,11 +63,16 @@
46
63
  "@vueuse/core": "^14.3.0",
47
64
  "dayjs": "^1.11.21",
48
65
  "uuid": "^14.0.1",
49
- "vue": "^3.5.39",
50
66
  "vue-i18n": "^11.4.6",
51
67
  "zod": "^4.4.3"
52
68
  },
69
+ "peerDependencies": {
70
+ "vue": "^3.5.41"
71
+ },
53
72
  "devDependencies": {
73
+ "@axe-core/playwright": "4.14.0",
74
+ "@mdi/font": "6.5.95",
75
+ "@playwright/test": "1.61.1",
54
76
  "@storybook/addon-a11y": "^10.4.6",
55
77
  "@storybook/addon-docs": "^10.4.6",
56
78
  "@storybook/addon-links": "^10.4.6",
@@ -63,8 +85,10 @@
63
85
  "eslint-plugin-storybook": "10.4.6",
64
86
  "http-server": "^14.1.1",
65
87
  "lodash.merge": "^4.6.2",
66
- "playwright": "^1.61.1",
88
+ "playwright": "1.61.1",
67
89
  "storybook": "^10.4.6",
68
- "vitest": "^4.1.9"
90
+ "vitest": "^4.1.9",
91
+ "vue": "^3.5.41",
92
+ "vue-component-meta": "^3.3.6"
69
93
  }
70
94
  }
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "sui-plugin",
3
- "description": "Skills for building Vue 3 / Nuxt apps with @khsura/sui — setup (GitHub Packages, styles, icons, theming, i18n), per-component references, forms, layouts and utilities",
4
- "version": "1.5.2",
3
+ "description": "Skills for building Vue 3 / Nuxt apps with @khsura/sui — setup (npm install, styles, icons, theming, i18n), per-component references, forms, layouts and utilities",
4
+ "version": "1.26.0",
5
5
  "author": {
6
6
  "name": "Sura Kh",
7
7
  "email": "sura0111@gmail.com"
@@ -2,6 +2,8 @@
2
2
 
3
3
  Claude Code plugin that gives Claude expert knowledge of the **`@khsura/sui`** Vue 3 component framework. Install it in an app that uses `@khsura/sui` (Vue or Nuxt) and Claude can set the library up, and generate idiomatic SUI components, forms, and layouts for you.
4
4
 
5
+ The library itself installs from the public npm registry (`npm i @khsura/sui` / `yarn add @khsura/sui`). Component docs and live examples: [Storybook — sui.surakh.com](https://sui.surakh.com/).
6
+
5
7
  ## Install
6
8
 
7
9
  ```
@@ -30,11 +32,32 @@ Or add to your project's `.claude/settings.json`:
30
32
  }
31
33
  ```
32
34
 
35
+ ## Pair it with the SUI MCP server
36
+
37
+ The skills teach Claude how SUI works; [`@khsura/sui-mcp`](../../packages/mcp/README.md) gives any AI client (Claude Code, Cursor, VS Code, Windsurf) the exact component API of the `@khsura/sui` version your project installs, tested recipes, and a template validator. Set it up from your app's folder:
38
+
39
+ ```bash
40
+ npx -y @khsura/sui-mcp config # detects your client and writes its MCP config
41
+ npx -y @khsura/sui-mcp config --dry-run # show the planned changes first
42
+ ```
43
+
44
+ For Claude Code this adds a `sui` server to the project's `.mcp.json`:
45
+
46
+ ```json
47
+ {
48
+ "mcpServers": {
49
+ "sui": { "command": "npx", "args": ["-y", "@khsura/sui-mcp"] }
50
+ }
51
+ }
52
+ ```
53
+
54
+ With both installed, Claude checks `get_component_api` before using an unfamiliar component, starts from `get_recipe` for common patterns, and runs `validate_sui_template` on the templates it writes. Per-client snippets: the [MCP README](../../packages/mcp/README.md) and the **AI / MCP** page in [Storybook](https://sui.surakh.com/).
55
+
33
56
  ## Skills
34
57
 
35
58
  | Skill | When to use |
36
59
  | --- | --- |
37
- | [`sui-getting-started`](./skills/sui-getting-started/SKILL.md) | Installing `@khsura/sui` from GitHub Packages, `SApp` + `createSUI`, styles and `@mdi/font`, Nuxt module, theme colors / dark mode, component defaults, vue-i18n, types, common mistakes. |
60
+ | [`sui-getting-started`](./skills/sui-getting-started/SKILL.md) | Installing `@khsura/sui` from npm (and migrating off GitHub Packages), setting up the SUI MCP server, `SApp` + `createSUI`, styles and `@mdi/font`, Nuxt module, theme colors / dark mode, component defaults, vue-i18n, types, common mistakes. |
38
61
  | [`sui-component`](./skills/sui-component/SKILL.md) | Using a specific component (`SButton`, `SCard`, `STable`, …) — routes to one per-family reference in `references/` with props, slots, events, examples and gotchas. |
39
62
  | [`sui-form`](./skills/sui-form/SKILL.md) | Building validated forms with `SInput`, `SSelect`, `SCheckbox`, etc., including `rules` validation. |
40
63
  | [`sui-layout`](./skills/sui-layout/SKILL.md) | Scaffolding app shells with `SLayout`, `SAppBar`, `SNavigationDrawer`, `SMain`, `SFooter`, `SBottomNavigation`. |
@@ -10,6 +10,8 @@ Help the user use this SUI component: $ARGUMENTS
10
10
  2. Give the import, the props you use, and a complete working example built from the reference.
11
11
  3. If a prop isn't in the reference, check `node_modules/@khsura/sui/@types/definitions/props/props<Component>.d.ts` before using it. Never guess — unknown props are silently ignored.
12
12
 
13
+ In each reference, the props / slots / events tables between `generated:api` markers are generated from the package's `sui-api.json`, so they list every prop with its exact type. The **notes** list under each table and the prose around it explain behaviour and gotchas.
14
+
13
15
  All components import from `@khsura/sui`. App setup (registry, `SApp`, styles, `@mdi/font`): **sui-getting-started**.
14
16
 
15
17
  ---
@@ -32,7 +34,7 @@ All components import from `@khsura/sui`. App setup (registry, `SApp`, styles, `
32
34
  | `SDivider` | [references/divider.md](references/divider.md) |
33
35
  | `SDroppable` | [references/droppable.md](references/droppable.md) |
34
36
  | `SExpansionPanels`, `SExpansionPanel`, `SExpansionPanelHeader`, `SExpansionPanelContent` | [references/expansion-panels.md](references/expansion-panels.md) |
35
- | `SForm`, `SInput`, `STextarea`, `SSelect`, `SCheckbox`, `SRadioGroup`, `SRadio`, `SSwitch` | [references/form.md](references/form.md) (and the **sui-form** skill) |
37
+ | `SForm`, `SFormRow`, `SInput`, `STextarea`, `SSelect`, `SCheckbox`, `SRadioGroup`, `SRadio`, `SSwitch` | [references/form.md](references/form.md) (and the **sui-form** skill) |
36
38
  | `SIcon` | [references/icon.md](references/icon.md) |
37
39
  | `SImage` | [references/image.md](references/image.md) |
38
40
  | `SApp`, `SLayout`, `SAppBar`, `SNavigationDrawer`, `SMain`, `SFooter`, `SBottomNavigation`, `SContainer`, `SRow`, `SColumn`, `SSpacer` | [references/layout.md](references/layout.md) (and the **sui-layout** skill) |
@@ -105,7 +107,7 @@ Popups teleport into the container rendered by `<SApp>` — without `SApp` at th
105
107
 
106
108
  | Prop | Renders | For |
107
109
  |---|---|---|
108
- | `to` | `router-link` | internal route |
110
+ | `to` | `router-link` (plain `<a href>` without vue-router) | internal route |
109
111
  | `href` | `<a>` | external URL (`target`, `rel` go with it) |
110
112
  | neither | `div` or `tag` | not a link |
111
113
 
@@ -128,6 +130,14 @@ Navigating from `@click` renders a `div` — no middle-click, "copy link", or li
128
130
  | `var(--s-color-surface-variant)` | `color-mix(in srgb, #{s_getAppColor('text')} 8%, transparent)` |
129
131
 
130
132
  - **`s_getPresetColor` keys:** `primary`, `secondary`, `success`, `info`, `warning`, `important`, `error` (+ any you add in `createSUI({ themes })`)
131
- - **`s_getAppColor` keys:** `appBar`, `title`, `text`, `secondaryText`, `anchor`, `background`, `card`, `button`, `switch`, `border`, `disabled`, `snackbar`, `inputPlaceholderShown`, `textErrorHover`
133
+ - **`s_getAppColor` keys:** `appBar`, `title`, `text`, `secondaryText`, `anchor`, `background`, `card`, `button`, `switch`, `border`, `disabled`, `snackbar`, `inputPlaceholderShown`, `textErrorHover`, `textError`, `focusRing`
132
134
 
133
135
  The variables are set on `<SApp>`, so they only resolve inside it. More helpers: **sui-utilities**.
136
+
137
+ ## Accessibility
138
+
139
+ - **Icon-only buttons need `aria-label`:** `<SButton variant="icon" aria-label="Close"><SIcon icon="mdi-close" /></SButton>`. Without it the button has no name (axe `button-name`, critical). The same goes for a link that wraps only an image.
140
+ - **Text on a colour is picked by WCAG contrast** (light or dark theme text, whichever contrasts more). Don't hard-code `color: white` on `color="success"` chips; the default `success` (`#2e7d32`) and light `secondary` (`#cc4125`) already reach 4.5:1 with their text. Passing `colorThreshold` switches back to the old YIQ brightness rule. A preset used as text (`color` on a text button, an outlined chip, `s_textColor__<name>`) is drawn with `--s-color-<name>--readable`, adjusted to 4.5:1 on the background and cards.
141
+ - **Keyboard:** SSelect and SAutocomplete are comboboxes (arrow keys move the highlighted option, Enter picks, Esc closes), STabs uses arrow keys / Home / End with one Tab stop, SRadioGroup uses native radio arrow keys, editable SStepper steps are buttons. Don't add your own `@keydown` handlers or `tabindex` for these.
142
+ - **Focus ring:** components draw a 2px `focusRing` outline under `:focus-visible`. Don't remove it with `outline: none`; for your own focusable element use `@include s_focusRing();`.
143
+ - SProgressCircular / SProgressLinear are named `Loading` by default; pass `aria-label` to say what loads. Full checklist: `docs/a11y.md` in the package and https://sui.surakh.com/.
@@ -6,27 +6,43 @@ Simple colored message box (flex row, vertically centered, rounded). It has no i
6
6
 
7
7
  Types: `node_modules/@khsura/sui/@types/definitions/props/propsAlert.d.ts`
8
8
 
9
- ## Props
9
+ <!-- generated:api:start SAlert -->
10
+ <!-- Generated from sui-api.json by `yarn sync:skills` (packages/app). Do not edit by hand. -->
10
11
 
11
- | Prop | Type | Default | Description |
12
- |------|------|---------|-------------|
13
- | `color` | `string` | `undefined` | Preset name or CSS color (default background = theme `card` color) |
14
- | `colorThreshold` | `number` | `undefined` | Luminance threshold for automatic light/dark text |
15
- | `size` | `'mini' \| 'small' \| 'default' \| 'large' \| 'extra'` | `'default'` | Padding, font size and min-height |
16
- | `dense` | `boolean` | `false` | Smaller padding and min-height |
17
- | `minHeight` | `number` | computed from `size` | Min height in px |
18
- | `fixedHeight` | `boolean` | `false` | `height: 100%; overflow: hidden`, and render even when empty (reserves space) |
12
+ **SAlert props**
19
13
 
20
- ## Slots
14
+ | Prop | Type | Default | Required | Values |
15
+ | --- | --- | --- | --- | --- |
16
+ | `color` | `string` | — | no | — |
17
+ | `colorThreshold` | `number` | — | no | — |
18
+ | `dense` | `boolean` | — | no | — |
19
+ | `fixedHeight` | `boolean` | — | no | — |
20
+ | `minHeight` | `number` | — | no | — |
21
+ | `size` | `SizePropertyType` | — | no | `default`, `extra`, `large`, `mini`, `small` |
22
+ | `theme` | `AppThemeType` | — | no | `dark`, `light` |
21
23
 
22
- | Slot | Description |
23
- |------|-------------|
24
- | `default` | Alert content. **If empty, nothing is rendered** (unless `fixedHeight`) |
24
+ **SAlert slots**
25
25
 
26
- ## Events
26
+ | Slot | Slot props |
27
+ | --- | --- |
28
+ | `default` | `{}` |
29
+
30
+ **SAlert events**
27
31
 
28
32
  None.
29
33
 
34
+ <!-- generated:api:end SAlert -->
35
+
36
+ **SAlert notes**
37
+
38
+ - `color`: Preset name or CSS color (default background = theme `card` color)
39
+ - `colorThreshold`: Luminance threshold for automatic light/dark text
40
+ - `size`: Padding, font size and min-height (default: `'default'`)
41
+ - `dense`: Smaller padding and min-height
42
+ - `minHeight`: Min height in px (default: computed from `size`)
43
+ - `fixedHeight`: `height: 100%; overflow: hidden`, and render even when empty (reserves space)
44
+ - `default` (slot): Alert content. **If empty, nothing is rendered** (unless `fixedHeight`)
45
+
30
46
  ## Usage
31
47
 
32
48
  ```vue
@@ -6,32 +6,100 @@ Searchable dropdown input with filtering, multiple selection, chips, free-text e
6
6
 
7
7
  Types: `node_modules/@khsura/sui/@types/definitions/props/propsAutocomplete.d.ts`
8
8
 
9
- ## Props
10
-
11
- | Prop | Type | Default | Description |
12
- |------|------|---------|-------------|
13
- | `modelValue` (`v-model`) | `string \| number \| null` (or an array of them when `multiple`) | `undefined` | Selected item `value`(s) |
14
- | `items` | `SelectItem[] \| string[]` | `undefined` | Options |
15
- | `multiple` | `boolean` | `false` | Multi-select; model becomes an array |
16
- | `chips` | `boolean` | `false` | Show selected items as chips |
17
- | `closableChips` | `boolean` | `false` | × icon on each selected item (works with or without `chips`) |
18
- | `allowUnlisted` | `boolean` | `false` | Allow typed values not in `items`; adds an `Add "…"` row and emits `createItem` |
19
- | `filterMode` | `'start' \| 'contains' \| 'exact' \| 'none'` | `'contains'` | Built-in, case-insensitive filter |
20
- | `filter` | `(item: SelectItem, queryText: string) => boolean` | `undefined` | Custom filter (overrides `filterMode` unless it is `'none'`) |
21
- | `debounce` | `number` (ms) | `500` | Delay before `searchItem` is emitted |
22
- | `delimiter` | `string \| string[] \| RegExp` | `undefined` | Keys that commit the typed text (like Enter) |
23
- | `loading` | `boolean` | `false` | Show a spinner (hides the clear button) |
24
- | `clearable` | `boolean` | `false` | Clear button when a value is set |
25
- | `divided` | `boolean` | `false` | Dividers between list items |
26
- | `dense` | `boolean` | `false` | Dense list |
27
- | `label` | `string \| null` | `undefined` | Label above the field |
28
- | `id` | `string` | auto | Input id (label `for`) |
29
- | `hideDetails` | `boolean` | `undefined` | Hide the label |
30
- | `placeholder` | `string` | `undefined` | Input placeholder |
31
- | `autocomplete` | `'on' \| 'off'` | `undefined` | Native `autocomplete` attribute |
32
- | `size` | `'mini' \| 'small' \| 'default' \| 'large' \| 'extra'` | `undefined` | Preset size |
33
- | `location` | `LocationRaw` | `'bottom'` | Dropdown position (flips automatically) |
34
- | `offsetX` / `offsetY` | `number \| null` | `undefined` | Dropdown offset |
9
+ <!-- generated:api:start SAutocomplete -->
10
+ <!-- Generated from sui-api.json by `yarn sync:skills` (packages/app). Do not edit by hand. -->
11
+
12
+ **SAutocomplete props**
13
+
14
+ | Prop | Type | Default | Required | Values |
15
+ | --- | --- | --- | --- | --- |
16
+ | `activator` | `string \| HTMLElement \| ComponentPublicInstance \| null` | — | no | — |
17
+ | `allowUnlisted` | `boolean` | — | no | — |
18
+ | `ariaLabel` | `string \| null` | — | no | — |
19
+ | `autocomplete` | `string` | `"off"` | no | — |
20
+ | `chips` | `boolean` | — | no | — |
21
+ | `clearAriaLabel` | `string` | `"Clear"` | no | — |
22
+ | `clearable` | `boolean` | — | no | — |
23
+ | `closableChips` | `boolean` | — | no | — |
24
+ | `closeOnClick` | `boolean` | — | no | — |
25
+ | `closeOnContentClick` | `boolean` | — | no | — |
26
+ | `closeOnScroll` | `boolean` | — | no | — |
27
+ | `contentClass` | `string \| string[] \| Record<string, boolean>` | — | no | — |
28
+ | `contentStyle` | `StyleValue` | — | no | — |
29
+ | `debounce` | `number` | `500` | no | — |
30
+ | `delimiter` | `string \| RegExp \| string[]` | — | no | — |
31
+ | `dense` | `boolean` | — | no | — |
32
+ | `disabled` | `boolean \| null` | — | no | — |
33
+ | `divided` | `boolean` | — | no | — |
34
+ | `filter` | `((item: SelectItem, queryText: string) => boolean)` | — | no | — |
35
+ | `filterMode` | `"start" \| "contains" \| "exact" \| "none"` | `"contains"` | no | `contains`, `exact`, `none`, `start` |
36
+ | `height` | `string \| number \| null` | — | no | — |
37
+ | `hideDetails` | `boolean` | — | no | — |
38
+ | `id` | `string` | — | no | — |
39
+ | `items` | `string[] \| SelectItem[]` | — | no | — |
40
+ | `label` | `string \| null` | — | no | — |
41
+ | `loading` | `boolean` | — | no | — |
42
+ | `loadingAriaLabel` | `string` | `"Loading"` | no | — |
43
+ | `location` | `LocationRaw` | `"bottom"` | no | — |
44
+ | `maxHeight` | `string \| number \| null` | — | no | — |
45
+ | `maxWidth` | `string \| number \| null` | — | no | — |
46
+ | `minHeight` | `string \| number \| null` | — | no | — |
47
+ | `minWidth` | `string \| number \| null` | — | no | — |
48
+ | `modelValue` | `(AutocompleteModelType<T> & (AutocompleteModelType<T> \| null))` | — | no | — |
49
+ | `multiple` | `T` | — | no | — |
50
+ | `name` | `string` | — | no | — |
51
+ | `offsetX` | `number \| null` | — | no | — |
52
+ | `offsetY` | `number \| null` | — | no | — |
53
+ | `onUpdateSearchInput` | `((value: string) => void)` | — | no | — |
54
+ | `placeholder` | `string` | — | no | — |
55
+ | `position` | `Position` | — | no | `absolute`, `fixed`, `relative`, `static`, `sticky` |
56
+ | `preventCloseOnClick` | `boolean` | — | no | — |
57
+ | `readonly` | `boolean \| null` | — | no | — |
58
+ | `screenPadding` | `number \| null` | — | no | — |
59
+ | `size` | `SizePropertyType` | — | no | `default`, `extra`, `large`, `mini`, `small` |
60
+ | `width` | `string \| number \| null` | — | no | — |
61
+
62
+ **SAutocomplete slots**
63
+
64
+ None.
65
+
66
+ **SAutocomplete events**
67
+
68
+ | Event | Payload |
69
+ | --- | --- |
70
+ | `createItem` | `[SelectItem]` |
71
+ | `searchItem` | `[string]` |
72
+ | `update:modelValue` | `[value: AutocompleteModelType<T> \| null \| undefined]` |
73
+
74
+ <!-- generated:api:end SAutocomplete -->
75
+
76
+ **SAutocomplete notes**
77
+
78
+ - `modelValue` (`v-model`): Selected item `value`(s)
79
+ - `items`: Options
80
+ - `multiple`: Multi-select; model becomes an array (default: `false`)
81
+ - `chips`: Show selected items as chips
82
+ - `closableChips`: × icon on each selected item (works with or without `chips`)
83
+ - `allowUnlisted`: Allow typed values not in `items`; adds an `Add "…"` row and emits `createItem`
84
+ - `filterMode`: Built-in, case-insensitive filter
85
+ - `filter`: Custom filter (overrides `filterMode` unless it is `'none'`)
86
+ - `debounce`: Delay before `searchItem` is emitted
87
+ - `delimiter`: Keys that commit the typed text (like Enter)
88
+ - `loading`: Show a spinner (hides the clear button)
89
+ - `clearable`: Clear button when a value is set
90
+ - `divided`: Dividers between list items
91
+ - `dense`: Dense list
92
+ - `label`: Label above the field
93
+ - `id`: Input id (label `for`) (default: auto)
94
+ - `hideDetails`: Hide the label
95
+ - `placeholder`: Input placeholder
96
+ - `autocomplete`: Native `autocomplete` attribute
97
+ - `size`: Input font size, as on `SInput` (`large` 1.25rem, `extra` 1.5rem, never below 16px)
98
+ - `location`: Dropdown position (flips automatically)
99
+ - `offsetX` / `offsetY`: Dropdown offset
100
+ - `update:modelValue` (event): Selection changed
101
+ - `searchItem` (`@search-item`) (event): Current query, `debounce` ms after the last keydown — use for async search
102
+ - `createItem` (`@create-item`) (event): An unlisted value was added (`allowUnlisted`)
35
103
 
36
104
  `name` and `disabled` are typed but have no effect (see Gotchas). There is **no `rules` prop**.
37
105
 
@@ -44,14 +112,6 @@ interface SelectItem {
44
112
  // string[] items use the string as both text and value
45
113
  ```
46
114
 
47
- ## Events
48
-
49
- | Event | Payload | Description |
50
- |-------|---------|-------------|
51
- | `update:modelValue` | value or value[] | Selection changed |
52
- | `searchItem` (`@search-item`) | `string` | Current query, `debounce` ms after the last keydown — use for async search |
53
- | `createItem` (`@create-item`) | `SelectItem` | An unlisted value was added (`allowUnlisted`) |
54
-
55
115
  ## Usage
56
116
 
57
117
  ```vue
@@ -108,3 +168,5 @@ const searchUsers = async (query: string) => {
108
168
  - Single mode, no chips: the selected item's text is shown in the input itself.
109
169
  - Selected items keep their labels when `items` is replaced (async results), so chips don't go blank.
110
170
  - Toggling `multiple` at runtime drops a single value when switching back to single mode.
171
+ - The list opens on the roomier side of the field and stays 8px inside the viewport (shifted left near the right edge); no placement workaround needed.
172
+ - A long option stays on one line and ends in an ellipsis; its full text is in the option's `title`. No custom item slot needed for long labels.
@@ -6,38 +6,64 @@ Overlays a small notification indicator on another element. Supports number/text
6
6
 
7
7
  Types: `node_modules/@khsura/sui/@types/definitions/props/propsBadge.d.ts`
8
8
 
9
- ## Props
10
-
11
- | Prop | Type | Default | Description |
12
- |------|------|---------|-------------|
13
- | `value` | `boolean` | `undefined` (falsy) | Show the badge. **No default — the badge is hidden unless you pass `value`** |
14
- | `content` | `string \| number` | `undefined` | Text/number inside the badge. Falsy values (`0`, `''`) render an empty badge |
15
- | `icon` | `MaterialDesignIcon` | `undefined` | MDI icon inside the badge (wins over `content`) |
16
- | `label` | `string` | `undefined` | `aria-label` of the badge (`role="status"`, `aria-live="polite"`) |
17
- | `color` | `string` | `undefined` (primary) | Preset name or CSS color for the badge background |
18
- | `colorThreshold` | `number` | `undefined` | Contrast threshold for auto text color |
19
- | `theme` | `AppThemeType` | `undefined` | Per-component theme override |
20
- | `dot` | `boolean` | `undefined` | Dot mode — 9px circle, ignores `content`/`icon` |
21
- | `overlap` | `boolean` | `undefined` | Pull the badge further onto the child's corner |
22
- | `inline` | `boolean` | `undefined` | Render next to the content instead of absolutely positioned |
23
- | `bottom` | `boolean` | `undefined` | Position at the bottom |
24
- | `left` | `boolean` | `undefined` | Position on the left (with `inline`, badge renders before the content) |
25
- | `tile` | `boolean` | `undefined` | Square corners |
26
- | `offsetX` | `string \| number` | `undefined` | Horizontal offset (replaces the built-in spacer) |
27
- | `offsetY` | `string \| number` | `undefined` | Vertical offset |
28
- | `transitionName` | `STransition` | `undefined` | Named transition for show/hide |
29
-
30
- ## Slots
31
-
32
- | Slot | Description |
33
- |------|-------------|
34
- | `default` | The element the badge wraps |
35
- | `badge` | Custom badge content — overrides `content`, `icon` and `dot` content |
36
-
37
- ## Events
9
+ <!-- generated:api:start SBadge -->
10
+ <!-- Generated from sui-api.json by `yarn sync:skills` (packages/app). Do not edit by hand. -->
11
+
12
+ **SBadge props**
13
+
14
+ | Prop | Type | Default | Required | Values |
15
+ | --- | --- | --- | --- | --- |
16
+ | `bottom` | `boolean` | — | no | — |
17
+ | `color` | `string` | — | no | — |
18
+ | `colorThreshold` | `number` | — | no | — |
19
+ | `content` | `string \| number` | — | no | — |
20
+ | `dot` | `boolean` | — | no | — |
21
+ | `icon` | `string` | — | no | — |
22
+ | `inline` | `boolean` | — | no | — |
23
+ | `label` | `string` | — | no | — |
24
+ | `left` | `boolean` | — | no | — |
25
+ | `offsetX` | `string \| number` | — | no | — |
26
+ | `offsetY` | `string \| number` | — | no | — |
27
+ | `overlap` | `boolean` | — | no | — |
28
+ | `theme` | `AppThemeType` | — | no | `dark`, `light` |
29
+ | `tile` | `boolean` | — | no | — |
30
+ | `transitionName` | `STransition` | — | no | — |
31
+ | `value` | `boolean` | — | no | — |
32
+
33
+ **SBadge slots**
34
+
35
+ | Slot | Slot props |
36
+ | --- | --- |
37
+ | `badge` | `{}` |
38
+ | `default` | `{}` |
39
+
40
+ **SBadge events**
38
41
 
39
42
  None.
40
43
 
44
+ <!-- generated:api:end SBadge -->
45
+
46
+ **SBadge notes**
47
+
48
+ - `value`: Show the badge. **No default — the badge is hidden unless you pass `value`** (default: `undefined` (falsy))
49
+ - `content`: Text/number inside the badge. Falsy values (`0`, `''`) render an empty badge
50
+ - `icon`: MDI icon inside the badge (wins over `content`)
51
+ - `label`: `aria-label` of the badge (`role="status"`, `aria-live="polite"`)
52
+ - `color`: Preset name or CSS color for the badge background (default: `undefined` (primary))
53
+ - `colorThreshold`: Contrast threshold for auto text color
54
+ - `theme`: Per-component theme override
55
+ - `dot`: Dot mode — 9px circle, ignores `content`/`icon`
56
+ - `overlap`: Pull the badge further onto the child's corner
57
+ - `inline`: Render next to the content instead of absolutely positioned
58
+ - `bottom`: Position at the bottom
59
+ - `left`: Position on the left (with `inline`, badge renders before the content)
60
+ - `tile`: Square corners
61
+ - `offsetX`: Horizontal offset (replaces the built-in spacer)
62
+ - `offsetY`: Vertical offset
63
+ - `transitionName`: Named transition for show/hide
64
+ - `default` (slot): The element the badge wraps
65
+ - `badge` (slot): Custom badge content — overrides `content`, `icon` and `dot` content
66
+
41
67
  ## Usage
42
68
 
43
69
  ```vue
@@ -6,21 +6,44 @@ Navigation trail showing the current page's location in a hierarchy. Renders a `
6
6
 
7
7
  Types: `node_modules/@khsura/sui/@types/definitions/props/propsBreadcrumbs.d.ts`
8
8
 
9
- ## Props
9
+ <!-- generated:api:start SBreadcrumbs -->
10
+ <!-- Generated from sui-api.json by `yarn sync:skills` (packages/app). Do not edit by hand. -->
10
11
 
11
- | Prop | Type | Default | Description |
12
- |------|------|---------|-------------|
13
- | `items` | `BreadcrumbsItem[]` | `undefined` | Breadcrumb entries |
14
- | `divider` | `string` | `'/'` | Separator text between items |
15
- | `large` | `boolean` | `false` | Larger text |
16
- | `color` | `string \| null` | `undefined` | Text color of the enabled (link) items |
12
+ **SBreadcrumbs props**
13
+
14
+ | Prop | Type | Default | Required | Values |
15
+ | --- | --- | --- | --- | --- |
16
+ | `color` | `string \| null` | — | no | — |
17
+ | `divider` | `string` | `"/"` | no | — |
18
+ | `items` | `BreadcrumbsItem[]` | — | no | — |
19
+ | `large` | `boolean` | — | no | — |
20
+
21
+ **SBreadcrumbs slots**
22
+
23
+ | Slot | Slot props |
24
+ | --- | --- |
25
+ | `custom-divider` | `{}` |
26
+
27
+ **SBreadcrumbs events**
28
+
29
+ None.
30
+
31
+ <!-- generated:api:end SBreadcrumbs -->
32
+
33
+ **SBreadcrumbs notes**
34
+
35
+ - `items`: Breadcrumb entries
36
+ - `divider`: Separator text between items
37
+ - `large`: Larger text
38
+ - `color`: Text color of the enabled (link) items
39
+ - `custom-divider` (slot): Replaces the divider text
17
40
 
18
41
  ### BreadcrumbsItem
19
42
 
20
43
  ```ts
21
44
  interface BreadcrumbsItem {
22
45
  text: string | number
23
- to?: RouteLocationRaw // renders router-link
46
+ to?: LinkLocation // renders router-link (plain <a href> without vue-router)
24
47
  href?: string // renders <a>
25
48
  disabled?: boolean // renders plain <span>
26
49
  link?: boolean // declared on the type, not used by the component
@@ -29,16 +52,6 @@ interface BreadcrumbsItem {
29
52
 
30
53
  Each item renders as `router-link` if `to` is set, else `<a>` if `href` is set, else `<span>`. A disabled item is always a `<span>`.
31
54
 
32
- ## Slots
33
-
34
- | Slot | Scoped data | Description |
35
- |------|-------------|-------------|
36
- | `custom-divider` | — | Replaces the divider text |
37
-
38
- ## Events
39
-
40
- None.
41
-
42
55
  ## Usage
43
56
 
44
57
  ```vue
@@ -64,4 +77,5 @@ None.
64
77
  - The **last item is disabled automatically** (current page) unless you set `disabled: false` on it explicitly.
65
78
  - Disabled items ignore `color`.
66
79
  - Pass `to` or `href` per item, not both — `to` wins.
67
- - `to` requires vue-router in the app.
80
+ - vue-router is optional: without it a `to` item renders a plain `<a href>`; use a path, not a route `name`.
81
+ - The first crumb starts at the content edge (no list indent), so it lines up with the cards below. Older versions inherited a 1.5em `<ol>` indent; don't add a negative margin.