@khsura/sui-mcp 0.2.1 → 0.4.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.
@@ -10,5 +10,5 @@ components: SDialog, SMenu, STooltip, SSnackbar, SButton, SCard, SCardTitle, SCa
10
10
  - `SMenu` stays open on content clicks unless you add `close-on-content-click`.
11
11
  - `SDialog` has no background of its own; put an `SCard` inside. It has no Escape-key handling.
12
12
  - `SSnackbar` has no `color` prop. Without `timeout` it stays until `v-model` turns `false`, so give it a close action.
13
- - The snackbar is dark (`#424242`) in both themes. Give a text action button a light colour such as `color="warning"` or `color="#ffffff"`; `primary`, `secondary`, `success`, `info` and `error` text is below 4.5:1 on it (`primary` is 2.18:1).
13
+ - The snackbar is dark (`#424242`) in both themes. Give a text action button **no** `color`: it takes the snackbar's light text colour and is readable. Since 1.20.0 a preset `color` (`warning`, `primary`, ...) on a snackbar action uses a variant tuned to reach 4.5:1 on the snackbar, but it adds nothing over the default. A CSS colour (`color="#1976d2"`) is used as is, so pick a light one (`color="#ffffff"`). Before 1.20.0 an action without `color` kept the page's dark text colour and `primary`, `secondary`, `success`, `info` and `error` were below 4.5:1, so use `color="warning"` or a light CSS colour there.
14
14
  - All four teleport into the container `<SApp>` renders; they do not appear without it.
@@ -38,7 +38,7 @@
38
38
  <SSnackbar v-model="isSnackbarOpen" :timeout="SNACKBAR_TIMEOUT_MS">
39
39
  Project deleted.
40
40
  <template #action>
41
- <SButton variant="text" color="warning" @click="isSnackbarOpen = false">Close</SButton>
41
+ <SButton variant="text" @click="isSnackbarOpen = false">Close</SButton>
42
42
  </template>
43
43
  </SSnackbar>
44
44
  </SRow>
@@ -7,7 +7,7 @@ components: SLayout, SAppBar, SAppBarTitle, SNavigationDrawer, SMain, SFooter, S
7
7
  - Wrap the app in `<SApp>` once (App.vue) after `app.use(createSUI())`; this shell goes inside it.
8
8
  - `SLayout name="shell"` is a named layout, so **every** child needs `for="shell"`. A child without `for` joins the app-level layout and the offsets silently break.
9
9
  - Give the named layout a height (`height="100vh"` for a full page). Its drawer is `position: absolute` inside it.
10
- - Below the `md` breakpoint the drawer is temporary: it slides over the content, opens on an edge swipe and closes on an outside click. From `md` up it pushes `SMain`.
10
+ - Below the `md` breakpoint the drawer is temporary: it slides over the content and dims the layout behind it, opens on an edge swipe and closes on an outside click or a tap on the dimmed area. From `md` up it pushes `SMain`. It opens itself on desktop and closes itself on mobile at load, so starting the model from `useDisplay()` only avoids a first-frame flicker.
11
11
  - `activator` on the drawer only excludes the toggle button from outside-click handling; toggle `v-model` yourself.
12
12
  - `SAppBar` needs `position="fixed"` for `SMain` to get a top offset. It has no `prepend`/`append` slots; use `SSpacer` to push items apart.
13
13
  - Icon-only buttons need an `aria-label`.
@@ -0,0 +1,11 @@
1
+ ---
2
+ title: Centered page
3
+ whenToUse: A page with one card centred in the viewport and no app bar or drawer, such as a login, sign-up, error or empty-state page.
4
+ components: SCard, SCardTitle, SCardText, SForm, SInput, SButton
5
+ ---
6
+
7
+ - Render the page as a **direct child of `SApp`**: App.vue is `<SApp><RouterView /></SApp>` and this component is the routed page (or put the `<div>` straight inside `<SApp>`).
8
+ - `SApp` is a flex column at least as tall as the viewport (`min-height: 100dvh`). A direct child with `s_height--fill` grows to fill it (since `@khsura/sui` 1.20.0), so `s_display__flex s_justify__center s_align__center` on that child centres the card vertically and horizontally.
9
+ - Do not add a `min-height: 100vh` wrapper: `SApp` already fills the viewport. Before 1.20.0, `s_height--fill` under `SApp` resolved to the content height and the card stuck to the top; use `style="min-height: 100dvh"` on the child there instead.
10
+ - Inside an app shell (`SLayout` / `SMain`), this pattern does not apply: `s_height--fill` only grows a **direct** child of `SApp`.
11
+ - `:max-width` plus `s_width--fill` makes the card full width on phones and capped on wider screens; `s_pa__4` keeps it off the screen edges.
@@ -0,0 +1,44 @@
1
+ <template>
2
+ <div class="s_display__flex s_justify__center s_align__center s_height--fill s_pa__4">
3
+ <SCard :max-width="420" :elevation="4" class="s_width--fill">
4
+ <SCardTitle>Sign in</SCardTitle>
5
+ <SCardText>
6
+ <SForm @submit.prevent="submit">
7
+ <SInput
8
+ v-model="form.email"
9
+ label="Email"
10
+ type="text"
11
+ inputmode="email"
12
+ autocomplete="email"
13
+ :rules="[required]"
14
+ />
15
+ <SInput
16
+ v-model="form.password"
17
+ label="Password"
18
+ type="password"
19
+ autocomplete="current-password"
20
+ :rules="[required]"
21
+ />
22
+ <SButton type="submit" color="primary" block class="s_mt__2">Sign in</SButton>
23
+ </SForm>
24
+ <p v-if="signedInEmail" class="s_text--body__2 s_mt__3" role="status">Signed in as {{ signedInEmail }}.</p>
25
+ </SCardText>
26
+ </SCard>
27
+ </div>
28
+ </template>
29
+
30
+ <script setup lang="ts">
31
+ import { reactive, ref } from 'vue'
32
+ import { SButton, SCard, SCardText, SCardTitle, SForm, SInput } from '@khsura/sui'
33
+
34
+ // A rule returns true to pass or an error string to fail.
35
+ const required = (value: unknown) => Boolean(value) || 'This field is required'
36
+ const form = reactive({ email: '', password: '' })
37
+ const signedInEmail = ref('')
38
+
39
+ const submit = () => {
40
+ if (form.email && form.password) {
41
+ signedInEmail.value = form.email
42
+ }
43
+ }
44
+ </script>
@@ -0,0 +1,12 @@
1
+ ---
2
+ title: Filter bar
3
+ whenToUse: A search field with its button, or a row of filter fields (date, select) with an Apply button above a list or table.
4
+ components: SFormRow, SForm, SInput, SDatePickerInput, SSelect, SButton, SCard, SCardText
5
+ ---
6
+
7
+ - Put fields and the buttons that act on them in an `SFormRow` (since 1.20.0), never a plain flex `<div>`. A field is a label, its box and a reserved error line, so in a plain flex row the button lines up with the label or floats above the fields; `SFormRow` lines each button up with the field box, with or without a label and while an error shows.
8
+ - `SFormRow` wraps on a phone: `SInput` takes the free width, `SSelect` and `SDatePickerInput` keep their own width (add `grow` / `block` to stretch them), buttons keep theirs. Do not add `block` to a button in the row.
9
+ - Keep the fields' error lines (no `hide-details`): the row and the button use them as the gap to the next row. A row whose fields all use `hide-details` adds the same gap below itself.
10
+ - Before 1.20.0 there is no `SFormRow`: put `hide-details` on the field in a flex row so it renders no label or error line, and give it a `placeholder` or `aria-label` instead.
11
+ - `SFormRow` has no outer padding, so the fields line up with the card heading and the text below. If you lay filters out with `SRow` / `SColumn` instead, add `no-outer-gutters :gap="16"` to the row: a default `SRow` pads itself and each column by 8px, so the fields start 16px inside the heading.
12
+ - A search runs on submit: make the button `type="submit"` inside an `SForm`, so Enter in the field searches too.
@@ -0,0 +1,70 @@
1
+ <template>
2
+ <SCard :max-width="720" class="s_mx__auto">
3
+ <SCardText>
4
+ <SForm ref="formRef" @submit.prevent="search">
5
+ <SFormRow>
6
+ <SInput v-model="filters.query" label="Search" :rules="[required]" />
7
+ <SButton type="submit" color="primary">Search</SButton>
8
+ </SFormRow>
9
+ <SFormRow>
10
+ <SDatePickerInput v-model="filters.from" label="From" type="date" />
11
+ <SDatePickerInput v-model="filters.to" label="To" type="date" />
12
+ <SSelect v-model="filters.status" label="Status" :items="statuses" />
13
+ <SButton color="primary" outlined @click="reset">Reset</SButton>
14
+ </SFormRow>
15
+ </SForm>
16
+ <p class="s_text--body__2">{{ summary }}</p>
17
+ </SCardText>
18
+ </SCard>
19
+ </template>
20
+
21
+ <script setup lang="ts">
22
+ import { computed, ref } from 'vue'
23
+ import {
24
+ type SelectItem,
25
+ SButton,
26
+ SCard,
27
+ SCardText,
28
+ SDatePickerInput,
29
+ SForm,
30
+ SFormRow,
31
+ SInput,
32
+ SSelect,
33
+ } from '@khsura/sui'
34
+
35
+ interface Filters {
36
+ query: string
37
+ from: string | null
38
+ to: string | null
39
+ status: string | null
40
+ }
41
+
42
+ const statuses: SelectItem[] = [
43
+ { text: 'Open', value: 'open' },
44
+ { text: 'Closed', value: 'closed' },
45
+ ]
46
+
47
+ const emptyFilters = (): Filters => ({ query: '', from: null, to: null, status: null })
48
+ // A rule returns true to pass or an error string to fail.
49
+ const required = (value: unknown) => Boolean(value) || 'Enter a search term'
50
+ const formRef = ref<InstanceType<typeof SForm> | null>(null)
51
+ const filters = ref<Filters>(emptyFilters())
52
+ const searchedFor = ref('')
53
+ const summary = computed(() => (searchedFor.value ? `Results for "${searchedFor.value}"` : 'No search yet'))
54
+
55
+ const search = () => {
56
+ // validate() returns true when the form HAS errors.
57
+ if (formRef.value?.validate()) {
58
+ return
59
+ }
60
+
61
+ // Replace with your API call.
62
+ searchedFor.value = filters.value.query
63
+ }
64
+
65
+ const reset = () => {
66
+ filters.value = emptyFilters()
67
+ searchedFor.value = ''
68
+ formRef.value?.resetValidation()
69
+ }
70
+ </script>
@@ -9,6 +9,7 @@ components: SContainer, SRow, SColumn, SCard, SCardTitle, SCardText, SImage, SBu
9
9
  - `cols` also takes `'auto'` (fit content) and `'grow'`.
10
10
  - `SRow justify` values are camelCase: `spaceBetween`, `spaceAround`. `align` is the cross axis.
11
11
  - Use `gap`, `dense` or `no-gutters` on `SRow` to change spacing instead of overriding margins.
12
+ - **A grid next to a heading or paragraph needs `no-outer-gutters` and `:gap` to line up.** By default `SRow` pads itself by half a gutter (8px) and each `SColumn` pads its content by another half, so the first card starts 16px inside the heading above it. `no-outer-gutters` drops the row's padding; `:gap` replaces the columns' padding with a gap between them (column widths account for it). With only `no-outer-gutters`, the cards still start 8px in. Separate stacked rows with a margin (`class="s_mt__4"`), since a gap row has no outer padding.
12
13
  - Equal-height cards: columns in one `SRow` line already share a height, so give each `SCard` `height="100%"`. Do not make the card `display: flex; flex-direction: column` to stretch it: `SImage` is `height: 100%` by default and shrinks in a flex column, so the images end up with different heights. Give `SImage` `:aspect-ratio` and `height="auto"` so it keeps its ratio.
13
14
  - Two or more `block` buttons in one flex row overflow: `block` is `width: 100%` and does not shrink. Put each in its own `SColumn` instead.
14
15
  - `SContainer` adds side padding only. Add top and bottom spacing yourself (`class="s_py__4"`) so the first card is not flush with the top of the viewport.
@@ -1,6 +1,10 @@
1
1
  <template>
2
2
  <SContainer class="s_py__4">
3
- <SRow>
3
+ <h1 class="s_text--h5 s_mb__2">Dashboard</h1>
4
+ <p class="s_text--body__2 s_mb__4">Every row below starts and ends in line with this heading and paragraph.</p>
5
+
6
+ <!-- no-outer-gutters + gap: the grid lines up with the text around it (see the recipe notes). -->
7
+ <SRow no-outer-gutters :gap="GRID_GAP">
4
8
  <SColumn :cols="12" :md="8">
5
9
  <SCard class="s_pa__4" :height="160">
6
10
  <h2 class="s_text--h6">Main panel</h2>
@@ -15,7 +19,7 @@
15
19
  </SColumn>
16
20
  </SRow>
17
21
 
18
- <SRow>
22
+ <SRow no-outer-gutters :gap="GRID_GAP" class="s_mt__4">
19
23
  <SColumn v-for="stat in stats" :key="stat.label" :cols="12" :sm="6" :lg="3">
20
24
  <SCard class="s_pa__4" outlined>
21
25
  <div class="s_text--caption">{{ stat.label }}</div>
@@ -24,7 +28,7 @@
24
28
  </SColumn>
25
29
  </SRow>
26
30
 
27
- <SRow>
31
+ <SRow no-outer-gutters :gap="GRID_GAP" class="s_mt__4">
28
32
  <SColumn v-for="product in products" :key="product.name" :cols="12" :sm="6" :lg="3">
29
33
  <SCard height="100%" outlined>
30
34
  <SImage
@@ -40,7 +44,7 @@
40
44
  </SColumn>
41
45
  </SRow>
42
46
 
43
- <SRow justify="spaceBetween" align="center">
47
+ <SRow no-outer-gutters :gap="GRID_GAP" justify="spaceBetween" align="center" class="s_mt__4">
44
48
  <SColumn cols="auto">
45
49
  <span class="s_text--subtitle__1">Showing 4 of 12</span>
46
50
  </SColumn>
@@ -73,6 +77,8 @@ const stats: Stat[] = [
73
77
  ]
74
78
 
75
79
  const IMAGE_ASPECT_RATIO = 4 / 3
80
+ // The space between columns (and between wrapped lines), in px: one grid gutter.
81
+ const GRID_GAP = 16
76
82
 
77
83
  const products: Product[] = [
78
84
  { name: 'Desk lamp', description: 'Warm light.', image: 'https://picsum.photos/seed/lamp/400/300' },
@@ -0,0 +1,11 @@
1
+ ---
2
+ title: Tabbed sections
3
+ whenToUse: A settings, detail or help page split into a few sections the user switches between with tabs, which must still work on a 375px phone.
4
+ components: SCard, SCardText, STabs, STab
5
+ ---
6
+
7
+ - Use the plain setup: `<STabs v-model="activeTab">` with one `<STab :tab="value">` per section, rendered with `v-for` from an array. Don't add `shrink`, `cols`, `SSlideGroup` or `overflow-x: auto`: `STabs` already keeps the tabs on one row.
8
+ - When the tabs do not fit (a phone, a narrow card), the row scrolls sideways. The end that hides tabs fades out, so it is visibly scrollable (swipe it) instead of looking clipped, and the selected tab is always scrolled fully into view. When every tab fits, there is no fade. Add `show-arrows` for scroll arrows at the hidden ends, or set `wrap` to flow the tabs onto several rows instead.
9
+ - `STabs` renders only the tab buttons. Render each panel yourself with `v-show="activeTab === value"` (keeps panel state when switching) and give it `role="tabpanel"`.
10
+ - Keep labels short (one or two words). Long labels still work, they just mean more scrolling on a phone; never truncate them with CSS.
11
+ - Keyboard: the selected tab is the single Tab stop; the arrow keys, Home and End move between tabs.
@@ -0,0 +1,30 @@
1
+ <template>
2
+ <div class="s_pa__4">
3
+ <SCard :max-width="720">
4
+ <STabs v-model="activeSection">
5
+ <STab v-for="section in sections" :key="section.value" :tab="section.value">{{ section.label }}</STab>
6
+ </STabs>
7
+ <SCardText>
8
+ <div v-for="section in sections" v-show="activeSection === section.value" :key="section.value" role="tabpanel">
9
+ <h2 class="s_text--h6 s_mb__2">{{ section.label }}</h2>
10
+ <p class="s_text--body__2">{{ section.description }}</p>
11
+ </div>
12
+ </SCardText>
13
+ </SCard>
14
+ </div>
15
+ </template>
16
+
17
+ <script setup lang="ts">
18
+ import { ref } from 'vue'
19
+ import { SCard, SCardText, STab, STabs } from '@khsura/sui'
20
+
21
+ const sections = [
22
+ { value: 'getting-started', label: 'Getting started', description: 'Create a workspace and invite your team.' },
23
+ { value: 'billing', label: 'Billing', description: 'Plans, invoices and payment methods.' },
24
+ { value: 'account', label: 'Account', description: 'Your profile, password and sign-in methods.' },
25
+ { value: 'notifications', label: 'Notifications', description: 'Choose which emails and alerts you receive.' },
26
+ { value: 'security', label: 'Security', description: 'Two-factor authentication and active sessions.' },
27
+ ]
28
+
29
+ const activeSection = ref('getting-started')
30
+ </script>
@@ -34,3 +34,4 @@ createApp(App)
34
34
  - Options are deep-merged with the defaults, so pass only what you change.
35
35
  - `presetColors` keys: `primary`, `secondary`, `success`, `info`, `warning`, `important`, `error` (extra keys become usable as `color`). Use opaque hex values.
36
36
  - `useTheme()` returns `{ theme, setTheme }`. Toggle with `setTheme(theme.value === 'dark' ? 'light' : 'dark')`; `setTheme(null)` follows the OS. There is no `toggleTheme()`.
37
+ - The swatch row is `SRow no-outer-gutters :gap="8"`: `no-outer-gutters` drops the row's own 8px padding so the buttons start in line with the paragraph above them.
@@ -4,7 +4,8 @@
4
4
  <SCardText>
5
5
  <SSwitch v-model="isDark" label="Dark mode" />
6
6
  <p class="s_text--body__2 s_mb__2">Preset colors from the active theme:</p>
7
- <SRow :gap="8">
7
+ <!-- no-outer-gutters: the buttons start in line with the paragraph above (SRow pads itself by default). -->
8
+ <SRow no-outer-gutters :gap="8">
8
9
  <SButton v-for="color in PRESET_COLOR_NAMES" :key="color" :color="color" size="small">{{ color }}</SButton>
9
10
  </SRow>
10
11
  </SCardText>
@@ -8,8 +8,10 @@ components: SForm, SInput, SSelect, SDatePickerInput, SCheckbox, SButton, SCard,
8
8
  - A rule is `(value: unknown) => true | string`. Return an error string to fail; returning `false` shows no message.
9
9
  - Put inputs with `rules` inside `SForm` so `validate()` checks them. `SAutocomplete` and `SSwitch` never run rules; check them yourself in `submit`.
10
10
  - `SSelect` items are `SelectItem[]` (`{ text, value }`) or `string[]`. It has no `multiple`/`clearable`/`placeholder`; use `SAutocomplete` for those.
11
- - Do not put `type="email"`, `url` or `number` on an input inside `SForm`: the browser then validates on submit, its bubble covers SUI's error text and the submit handler never runs. Use `type="text"` with `inputmode="email"` and `autocomplete="email"` and check the format with a rule. For a number field keep `type="number"` (SInput then writes a number) and add `novalidate` to the `SForm`.
12
- - `SDatePickerInput type="date"` writes `'YYYY-MM-DD'`. Start an empty date as `null`, never `''`: `''` opens the picker on "Invalid date". Add `block` to it and `grow` to `SSelect` so they fill the form width like `SInput`.
13
- - `hide-details` hides the `label` too (on `SCheckbox` it is the only text). Use `hide-error` to drop just the error line.
14
- - `:loading` on the submit `SButton` disables it; do not also bind `:disabled`.
11
+ - `SForm` renders `<form novalidate>`, so `type="email"`, `url` or `number` on an input never shows the browser's own bubble over SUI's error text: check the format with a rule. Add `inputmode` and `autocomplete` (e.g. `autocomplete="email"`) for the mobile keyboard and autofill. Before 1.20.0 `SForm` did not add `novalidate`: there the browser validated on submit and blocked the submit handler, so add `novalidate` to the `SForm` yourself.
12
+ - `SDatePickerInput type="date"` writes `'YYYY-MM-DD'`. Start an empty date as `null`; `''` also means no date (before 1.20.0 `''` opened the picker on "Invalid date", so keep `null` if you support older versions). Add `block` to it and `grow` to `SSelect` so they fill the form width like `SInput`.
13
+ - `hide-details` hides a text field's label above the field and its error line; `SCheckbox` keeps its own label. Use `hide-error` to drop just the error line. Before 1.20.0 `hide-details` also hid the `SCheckbox` label (its only text), so use `hide-error` there.
14
+ - Disable the submit button only **after a failed submit, while errors remain**: bind `v-model:error="hasErrors"` on `SForm`, set `submitAttempted = true` at the start of `submit`, and put `:disabled="submitAttempted && hasErrors"` on the button. It re-enables as soon as every rule passes, because each field re-validates when its value changes. Do not disable it from page load: a disabled button gives no reason and cannot be focused. Keep the inline error messages, they tell the user why it is disabled.
15
+ - `:loading` on the submit `SButton` already disables it; do not bind `:disabled` to `isSubmitting` as well.
16
+ - Give the submit button `class="s_mt__2"`: a field's error line ends right where the next element starts, so without it the last error message sits on the button.
15
17
  - For translated messages use `getFormInputModelValueRules({ t })` from `@khsura/sui` instead of inline rules.
@@ -2,7 +2,7 @@
2
2
  <SCard :max-width="560" class="s_mx__auto">
3
3
  <SCardTitle>Create account</SCardTitle>
4
4
  <SCardText>
5
- <SForm ref="formRef" @submit.prevent="submit">
5
+ <SForm ref="formRef" v-model:error="hasErrors" @submit.prevent="submit">
6
6
  <SInput v-model="form.name" label="Full name" :rules="[required]" />
7
7
  <SInput
8
8
  v-model="form.email"
@@ -15,7 +15,16 @@
15
15
  <SSelect v-model="form.role" label="Role" :items="roles" grow :rules="[required]" />
16
16
  <SDatePickerInput v-model="form.startDate" label="Start date" type="date" block :rules="[required]" />
17
17
  <SCheckbox v-model="form.acceptTerms" label="I accept the terms" :rules="[mustAccept]" />
18
- <SButton type="submit" color="primary" block :loading="isSubmitting">Create account</SButton>
18
+ <SButton
19
+ type="submit"
20
+ color="primary"
21
+ block
22
+ class="s_mt__2"
23
+ :loading="isSubmitting"
24
+ :disabled="submitAttempted && hasErrors"
25
+ >
26
+ Create account
27
+ </SButton>
19
28
  </SForm>
20
29
  <p v-if="submittedName" class="s_text--body__2 s_mt__3">Account created for {{ submittedName }}.</p>
21
30
  </SCardText>
@@ -59,14 +68,18 @@ const email = (value: unknown) => (typeof value === 'string' && EMAIL_PATTERN.te
59
68
  const mustAccept = (value: unknown) => value === true || 'You must accept the terms'
60
69
  const formRef = ref<InstanceType<typeof SForm> | null>(null)
61
70
  const isSubmitting = ref(false)
71
+ // Kept in sync by SForm (v-model:error): true while any field shows an error.
72
+ const hasErrors = ref(false)
73
+ // The button stays enabled until the first submit, so a user can always try and see why it fails.
74
+ const submitAttempted = ref(false)
62
75
  const submittedName = ref('')
63
76
  const form = ref<AccountForm>({ name: '', email: '', role: null, startDate: null, acceptTerms: false })
64
77
 
65
78
  const submit = async () => {
66
- // validate() returns true when the form HAS errors.
67
- const hasErrors = formRef.value?.validate()
79
+ submitAttempted.value = true
68
80
 
69
- if (hasErrors) {
81
+ // validate() returns true when the form HAS errors.
82
+ if (formRef.value?.validate()) {
70
83
  return
71
84
  }
72
85