@khsura/sui-mcp 0.1.0 → 0.2.1
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 +9 -2
- package/dist/index.js +218 -11
- package/dist/recipes/activator-overlays.md +1 -0
- package/dist/recipes/activator-overlays.vue +1 -1
- package/dist/recipes/responsive-grid.md +4 -1
- package/dist/recipes/responsive-grid.vue +37 -2
- package/dist/recipes/validated-form.md +3 -1
- package/dist/recipes/validated-form.vue +10 -3
- package/dist/sui-api.json +2 -2
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -111,6 +111,12 @@ 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` |
|
|
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` |
|
|
114
120
|
|
|
115
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.
|
|
116
122
|
|
|
@@ -121,11 +127,12 @@ Future work: a `table-structure` rule (STable column keys and `item.<column>` sl
|
|
|
121
127
|
- 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
128
|
- Event listeners (`@x`, `v-on`), `v-bind="object"`, dynamic arguments (`:[name]`, `#[name]`) and dynamic values (`:size="x"`) are not checked.
|
|
123
129
|
- 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`.
|
|
130
|
+
- 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
131
|
- `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
132
|
- `icon-button-label` cannot see inside `v-bind="object"`, so a button with an object spread is assumed labelled.
|
|
133
|
+
- 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
134
|
|
|
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
|
|
135
|
+
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
136
|
|
|
130
137
|
## Where the guides come from
|
|
131
138
|
|
package/dist/index.js
CHANGED
|
@@ -150,7 +150,8 @@ var FALLTHROUGH_ATTRIBUTES = [
|
|
|
150
150
|
"autofocus",
|
|
151
151
|
"placeholder",
|
|
152
152
|
"alt",
|
|
153
|
-
"src"
|
|
153
|
+
"src",
|
|
154
|
+
"novalidate"
|
|
154
155
|
];
|
|
155
156
|
/** A bound expression that is just a string literal (`:size="'small'"`), so its value is still known statically. */
|
|
156
157
|
var STRING_LITERAL_EXPRESSION = /^\s*(['"`])([^'"`$\\]*)\1\s*$/;
|
|
@@ -159,11 +160,18 @@ var RULE_LAYOUT_FOR = "layout-for";
|
|
|
159
160
|
var RULE_FORM_RULES_OUTSIDE_FORM = "form-rules-outside-form";
|
|
160
161
|
var RULE_ICON_BUTTON_LABEL = "icon-button-label";
|
|
161
162
|
var RULE_NO_RAW_REPLACEMENT = "no-raw-replacement";
|
|
163
|
+
var RULE_NATIVE_VALIDATION_IN_FORM = "native-validation-in-form";
|
|
164
|
+
var RULE_HIDE_DETAILS_HIDES_LABEL = "hide-details-hides-label";
|
|
165
|
+
var RULE_SNACKBAR_ACTION_CONTRAST = "snackbar-action-contrast";
|
|
166
|
+
var RULE_BLOCK_BUTTONS_IN_ROW = "block-buttons-in-row";
|
|
167
|
+
var RULE_CARD_TITLE_TEXT_ALIGN = "card-title-text-align";
|
|
168
|
+
var RULE_DATE_PICKER_EMPTY_STRING = "date-picker-empty-string";
|
|
162
169
|
var RULE_TARGET_ANY_ELEMENT = "any-element";
|
|
163
170
|
/** Recipe names an issue points to; the recipes are published under these exact names. */
|
|
164
171
|
var RECIPE_APP_SHELL = "app-shell";
|
|
165
172
|
var RECIPE_VALIDATED_FORM = "validated-form";
|
|
166
173
|
var RECIPE_ACTIVATOR_OVERLAYS = "activator-overlays";
|
|
174
|
+
var RECIPE_RESPONSIVE_GRID = "responsive-grid";
|
|
167
175
|
var ACTIVATOR_SLOT_NAME = "activator";
|
|
168
176
|
var ACTIVATOR_ATTRS_KEY = "attrs";
|
|
169
177
|
/** Overlays whose `#activator` slot passes `{ on, attrs }` for the caller to bind. */
|
|
@@ -176,6 +184,7 @@ var SLOT_PROP_ACTIVATOR_COMPONENTS = [
|
|
|
176
184
|
var SLOTLESS_ACTIVATOR_COMPONENTS = ["STooltip"];
|
|
177
185
|
var LAYOUT_COMPONENT = "SLayout";
|
|
178
186
|
var LAYOUT_NAME_ATTRIBUTE = "name";
|
|
187
|
+
var FORM_COMPONENT = "SForm";
|
|
179
188
|
var RULES_ATTRIBUTE = "rules";
|
|
180
189
|
var ACCESSIBLE_LABEL_ATTRIBUTES = [
|
|
181
190
|
"aria-label",
|
|
@@ -198,6 +207,52 @@ var RAW_INPUT_TYPE_REPLACEMENTS = /* @__PURE__ */ new Map([["checkbox", "SCheckb
|
|
|
198
207
|
/** A bare JavaScript identifier (`props` in `#activator="props"`). */
|
|
199
208
|
var IDENTIFIER_PATTERN = /^[A-Za-z_$][\w$]*$/;
|
|
200
209
|
var WHITESPACE_PATTERN = /\s+/g;
|
|
210
|
+
var NATIVE_VALIDATING_INPUT_TYPES = [
|
|
211
|
+
"email",
|
|
212
|
+
"url",
|
|
213
|
+
"number"
|
|
214
|
+
];
|
|
215
|
+
var HIDE_DETAILS_ATTRIBUTE = "hide-details";
|
|
216
|
+
/** Inputs whose only visible text is the `label` prop, which `hide-details` hides as well. */
|
|
217
|
+
var HIDE_DETAILS_LABEL_COMPONENTS = ["SCheckbox"];
|
|
218
|
+
var SNACKBAR_ACTION_SLOT_NAME = "action";
|
|
219
|
+
var COLOR_ATTRIBUTE = "color";
|
|
220
|
+
var VARIANT_ATTRIBUTE = "variant";
|
|
221
|
+
/** Preset colours below 4.5:1 as text on the default `#424242` snackbar (primary is 2.18:1). */
|
|
222
|
+
var SNACKBAR_UNREADABLE_PRESET_COLORS = [
|
|
223
|
+
"primary",
|
|
224
|
+
"secondary",
|
|
225
|
+
"success",
|
|
226
|
+
"info",
|
|
227
|
+
"error"
|
|
228
|
+
];
|
|
229
|
+
var SNACKBAR_READABLE_ACTION_COLOR = "warning";
|
|
230
|
+
/** Components whose root is a `display: flex` row. */
|
|
231
|
+
var FLEX_ROW_COMPONENTS = ["SCardActions"];
|
|
232
|
+
/** `s_display__flex`, `s_display--md__inlineFlex`: the utility classes that make an element a flex row. */
|
|
233
|
+
var FLEX_DISPLAY_CLASS_PATTERN = /^s_display(?:--[a-z]+)?__(?:flex|inlineFlex)$/;
|
|
234
|
+
var FLEX_DISPLAY_STYLE_PATTERN = /(?:^|;)\s*display\s*:\s*(?:inline-)?flex\b/;
|
|
235
|
+
/** `s_textAlign__center`, `s_textAlign--md__center`. */
|
|
236
|
+
var TEXT_ALIGN_CLASS_PATTERN = /^s_textAlign(?:--[a-z]+)?__([a-z]+)$/;
|
|
237
|
+
/** The `justify` utility for each text-align value, which does centre a flex container's content. */
|
|
238
|
+
var TEXT_ALIGN_JUSTIFY_CLASSES = /* @__PURE__ */ new Map([
|
|
239
|
+
["left", "s_justify__start"],
|
|
240
|
+
["start", "s_justify__start"],
|
|
241
|
+
["center", "s_justify__center"],
|
|
242
|
+
["right", "s_justify__end"],
|
|
243
|
+
["end", "s_justify__end"]
|
|
244
|
+
]);
|
|
245
|
+
var DATE_PICKER_EMPTY_STRING_COMPONENTS = ["SDatePickerInput"];
|
|
246
|
+
/** `''` or `""` as a whole expression. */
|
|
247
|
+
var EMPTY_STRING_EXPRESSION = /^\s*(['"])\1\s*$/;
|
|
248
|
+
/** A dotted model path (`draft.from`, `startDate`) whose last segment can be looked up in the script. */
|
|
249
|
+
var MODEL_PATH_PATTERN = /^\s*[A-Za-z_$][\w$]*(?:\??\.[A-Za-z_$][\w$]*)*\s*$/;
|
|
250
|
+
var MODEL_PATH_SEPARATOR = /\??\./;
|
|
251
|
+
var REGEX_SPECIAL_CHARACTERS = /[$]/g;
|
|
252
|
+
/** Placeholder in the script patterns below, replaced by the model's last path segment. */
|
|
253
|
+
var MODEL_NAME_PLACEHOLDER = "__name__";
|
|
254
|
+
/** `from: ''` in an object literal, or `startDate = ref('')` / `ref<string>("")`. */
|
|
255
|
+
var EMPTY_STRING_INITIAL_PATTERNS = [`(?:^|[^\\w$.])${MODEL_NAME_PLACEHOLDER}\\s*:\\s*(['"])\\1`, `(?:^|[^\\w$.])${MODEL_NAME_PLACEHOLDER}\\s*=\\s*(?:ref|shallowRef)\\s*(?:<[^>]*>)?\\s*\\(\\s*(['"])\\1\\s*\\)`];
|
|
201
256
|
var ACTIVATOR_BINDING_FIX = "Write `#activator=\"{ on, attrs }\"` and put both `v-on=\"on\"` and `v-bind=\"attrs\"` on the activator's root element.";
|
|
202
257
|
//#endregion
|
|
203
258
|
//#region src/constants/recipes.ts
|
|
@@ -371,14 +426,19 @@ var toParseError = (error) => {
|
|
|
371
426
|
*/
|
|
372
427
|
var parseVueTemplate = (source) => {
|
|
373
428
|
const { descriptor, errors: sfcErrors } = parse$1(source);
|
|
374
|
-
if (Boolean(descriptor.template ?? descriptor.script ?? descriptor.scriptSetup))
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
|
|
429
|
+
if (Boolean(descriptor.template ?? descriptor.script ?? descriptor.scriptSetup)) {
|
|
430
|
+
const scriptSource = [descriptor.script, descriptor.scriptSetup].map((block) => block?.content ?? "").join("\n");
|
|
431
|
+
return {
|
|
432
|
+
root: descriptor.template?.ast ?? null,
|
|
433
|
+
errors: sfcErrors.map(toParseError),
|
|
434
|
+
scriptSource
|
|
435
|
+
};
|
|
436
|
+
}
|
|
378
437
|
const fragmentErrors = [];
|
|
379
438
|
return {
|
|
380
439
|
root: parse(source, { onError: (error) => fragmentErrors.push(toParseError(error)) }),
|
|
381
|
-
errors: fragmentErrors
|
|
440
|
+
errors: fragmentErrors,
|
|
441
|
+
scriptSource: ""
|
|
382
442
|
};
|
|
383
443
|
};
|
|
384
444
|
//#endregion
|
|
@@ -707,6 +767,22 @@ var slotFills = (element) => {
|
|
|
707
767
|
})));
|
|
708
768
|
};
|
|
709
769
|
var slotDirectives = (element) => slotFills(element).map((fill) => fill.directive);
|
|
770
|
+
/** Every element below `element`, depth first. */
|
|
771
|
+
var descendantElementsOf = (element) => childElementsOf(element).flatMap((child) => [child, ...descendantElementsOf(child)]);
|
|
772
|
+
/** A prop written in either case style: `hide-details`, `hideDetails`, `:hide-details`. */
|
|
773
|
+
var findPropAttribute = (element, kebabName) => findAttribute(element, kebabName) ?? findAttribute(element, toCamelCase(kebabName));
|
|
774
|
+
/** A boolean prop that is set and not statically `false` (`block`, `:block="true"`, `:block="isWide"`). */
|
|
775
|
+
var isBooleanPropOn = (element, kebabName) => {
|
|
776
|
+
const attribute = findPropAttribute(element, kebabName);
|
|
777
|
+
if (!attribute) return false;
|
|
778
|
+
return !isDirective(attribute.node) || expressionSource(attribute.node) !== "false";
|
|
779
|
+
};
|
|
780
|
+
/** The static `class` tokens of `element` (a plain `class` or a string-literal `:class`); bound classes are unknown. */
|
|
781
|
+
var staticClassNames = (element) => element.props.flatMap((prop) => {
|
|
782
|
+
if (!isDirective(prop)) return prop.name === "class" ? [prop.value?.content ?? ""] : [];
|
|
783
|
+
const literal = prop.name === "bind" && staticArgument(prop.arg) === "class" ? STRING_LITERAL_EXPRESSION.exec(expressionSource(prop) ?? "") : null;
|
|
784
|
+
return literal ? [literal[2]] : [];
|
|
785
|
+
}).flatMap((value) => value.split(WHITESPACE_PATTERN)).filter(Boolean);
|
|
710
786
|
//#endregion
|
|
711
787
|
//#region src/utils/recipeMarkdown.ts
|
|
712
788
|
var recipeStoryUrl = (name) => `${LIVE_EXAMPLES_URL}${RECIPE_STORY_PATH_PREFIX}${name}`;
|
|
@@ -921,7 +997,7 @@ var serverInfo = {
|
|
|
921
997
|
name: SERVER_NAME,
|
|
922
998
|
version: {
|
|
923
999
|
name: "@khsura/sui-mcp",
|
|
924
|
-
version: "0.1
|
|
1000
|
+
version: "0.2.1",
|
|
925
1001
|
repository: {
|
|
926
1002
|
"type": "git",
|
|
927
1003
|
"url": "git+https://github.com/khsura/sui.git",
|
|
@@ -1104,6 +1180,135 @@ var useGuideCatalogService = ({ sourceRoot = resolveGuideSourceRoot() } = {}) =>
|
|
|
1104
1180
|
}
|
|
1105
1181
|
});
|
|
1106
1182
|
//#endregion
|
|
1183
|
+
//#region src/services/behaviourRules.ts
|
|
1184
|
+
var nativeValidationInFormRule = {
|
|
1185
|
+
id: RULE_NATIVE_VALIDATION_IN_FORM,
|
|
1186
|
+
check: ({ element, ancestors }) => {
|
|
1187
|
+
const typeAttribute = findAttribute(element, INPUT_TYPE_ATTRIBUTE);
|
|
1188
|
+
const inputType = typeAttribute?.staticValue?.toLowerCase();
|
|
1189
|
+
const form = ancestors.filter((ancestor) => isComponentTag(ancestor.tag, FORM_COMPONENT)).at(-1);
|
|
1190
|
+
if (!typeAttribute || !inputType || !NATIVE_VALIDATING_INPUT_TYPES.includes(inputType) || !form) return [];
|
|
1191
|
+
if (findAttribute(form, "novalidate")) return [];
|
|
1192
|
+
return [{
|
|
1193
|
+
...positionOf(typeAttribute.node),
|
|
1194
|
+
rule: RULE_NATIVE_VALIDATION_IN_FORM,
|
|
1195
|
+
severity: SEVERITY_WARNING,
|
|
1196
|
+
message: `\`type="${inputType}"\` on \`${element.tag}\` inside \`SForm\` turns on the browser's own validation: on submit its bubble covers SUI's error text and blocks the submit handler.`,
|
|
1197
|
+
fixHint: inputType === "number" ? "Add `novalidate` to the `SForm` (it reaches the rendered `<form>`) and validate with `rules`." : `Use \`type="text" inputmode="${inputType}" autocomplete="${inputType}"\` and check the format with a rule, or add \`novalidate\` to the \`SForm\`.`,
|
|
1198
|
+
recipe: RECIPE_VALIDATED_FORM
|
|
1199
|
+
}];
|
|
1200
|
+
}
|
|
1201
|
+
};
|
|
1202
|
+
var hideDetailsHidesLabelRule = {
|
|
1203
|
+
id: RULE_HIDE_DETAILS_HIDES_LABEL,
|
|
1204
|
+
check: ({ element }) => {
|
|
1205
|
+
const hideDetails = findPropAttribute(element, HIDE_DETAILS_ATTRIBUTE);
|
|
1206
|
+
if (!isOneOfComponentTags(element.tag, HIDE_DETAILS_LABEL_COMPONENTS) || !hideDetails || !isBooleanPropOn(element, "hide-details") || !findAttribute(element, "label")) return [];
|
|
1207
|
+
return [{
|
|
1208
|
+
...positionOf(hideDetails.node),
|
|
1209
|
+
rule: RULE_HIDE_DETAILS_HIDES_LABEL,
|
|
1210
|
+
severity: SEVERITY_WARNING,
|
|
1211
|
+
message: `\`hide-details\` on \`${element.tag}\` hides its \`label\` as well as the error line, so the checkbox shows no text.`,
|
|
1212
|
+
fixHint: "Use `hide-error` to drop only the error line and keep the label.",
|
|
1213
|
+
recipe: RECIPE_VALIDATED_FORM
|
|
1214
|
+
}];
|
|
1215
|
+
}
|
|
1216
|
+
};
|
|
1217
|
+
var isUnreadableSnackbarAction = (button) => {
|
|
1218
|
+
const color = findAttribute(button, COLOR_ATTRIBUTE)?.staticValue;
|
|
1219
|
+
const variant = findAttribute(button, VARIANT_ATTRIBUTE)?.staticValue;
|
|
1220
|
+
return isComponentTag(button.tag, "SButton") && variant === "text" && color !== void 0 && SNACKBAR_UNREADABLE_PRESET_COLORS.includes(color);
|
|
1221
|
+
};
|
|
1222
|
+
var snackbarActionContrastRule = {
|
|
1223
|
+
id: RULE_SNACKBAR_ACTION_CONTRAST,
|
|
1224
|
+
check: ({ element }) => {
|
|
1225
|
+
if (!isComponentTag(element.tag, "SSnackbar")) return [];
|
|
1226
|
+
return slotFills(element).filter((fill) => staticArgument(fill.directive.arg) === SNACKBAR_ACTION_SLOT_NAME).flatMap((fill) => descendantElementsOf(fill.owner)).filter(isUnreadableSnackbarAction).map((button) => {
|
|
1227
|
+
const color = findAttribute(button, "color")?.staticValue ?? "";
|
|
1228
|
+
return {
|
|
1229
|
+
...positionOf(button),
|
|
1230
|
+
rule: RULE_SNACKBAR_ACTION_CONTRAST,
|
|
1231
|
+
severity: SEVERITY_WARNING,
|
|
1232
|
+
message: `A \`color="${color}"\` text button in the \`SSnackbar\` action is below 4.5:1 on the dark snackbar background, so the action is hard to read.`,
|
|
1233
|
+
fixHint: `Use a light colour: \`color="${SNACKBAR_READABLE_ACTION_COLOR}"\` or a CSS colour such as \`color="#ffffff"\`.`,
|
|
1234
|
+
recipe: RECIPE_ACTIVATOR_OVERLAYS
|
|
1235
|
+
};
|
|
1236
|
+
});
|
|
1237
|
+
}
|
|
1238
|
+
};
|
|
1239
|
+
var isFlexRow = (element) => isOneOfComponentTags(element.tag, FLEX_ROW_COMPONENTS) || staticClassNames(element).some((name) => FLEX_DISPLAY_CLASS_PATTERN.test(name)) || FLEX_DISPLAY_STYLE_PATTERN.test(findAttribute(element, "style")?.staticValue ?? "");
|
|
1240
|
+
var isBlockButton = (element) => isComponentTag(element.tag, "SButton") && isBooleanPropOn(element, "block");
|
|
1241
|
+
var blockButtonsInRowRule = {
|
|
1242
|
+
id: RULE_BLOCK_BUTTONS_IN_ROW,
|
|
1243
|
+
target: RULE_TARGET_ANY_ELEMENT,
|
|
1244
|
+
check: ({ element }) => {
|
|
1245
|
+
const blockButtons = childElementsOf(element).filter(isBlockButton);
|
|
1246
|
+
if (blockButtons.length < 2 || !isFlexRow(element)) return [];
|
|
1247
|
+
const [, secondButton] = blockButtons;
|
|
1248
|
+
return [{
|
|
1249
|
+
...positionOf(secondButton),
|
|
1250
|
+
rule: RULE_BLOCK_BUTTONS_IN_ROW,
|
|
1251
|
+
severity: SEVERITY_WARNING,
|
|
1252
|
+
message: `${blockButtons.length} \`block\` buttons sit side by side in one flex row; each is \`width: 100%\` and does not shrink, so the later ones are pushed off screen.`,
|
|
1253
|
+
fixHint: "Put each button in its own `SColumn` of an `SRow` (e.g. `:cols=\"6\"`), or drop `block` from buttons that share a row.",
|
|
1254
|
+
recipe: RECIPE_RESPONSIVE_GRID
|
|
1255
|
+
}];
|
|
1256
|
+
}
|
|
1257
|
+
};
|
|
1258
|
+
var cardTitleTextAlignRule = {
|
|
1259
|
+
id: RULE_CARD_TITLE_TEXT_ALIGN,
|
|
1260
|
+
check: ({ element }) => {
|
|
1261
|
+
if (!isComponentTag(element.tag, "SCardTitle")) return [];
|
|
1262
|
+
return staticClassNames(element).flatMap((className) => {
|
|
1263
|
+
const alignment = TEXT_ALIGN_CLASS_PATTERN.exec(className)?.[1];
|
|
1264
|
+
if (!alignment) return [];
|
|
1265
|
+
const justifyClass = TEXT_ALIGN_JUSTIFY_CLASSES.get(alignment);
|
|
1266
|
+
return [{
|
|
1267
|
+
...positionOf(findAttribute(element, "class")?.node ?? element),
|
|
1268
|
+
rule: RULE_CARD_TITLE_TEXT_ALIGN,
|
|
1269
|
+
severity: SEVERITY_WARNING,
|
|
1270
|
+
message: `\`${className}\` has no effect on \`SCardTitle\`: it is a flex container, so its text is placed by \`justify-content\`, not \`text-align\`.`,
|
|
1271
|
+
fixHint: justifyClass ? `Use \`${justifyClass}\` instead.` : "Use an `s_justify__*` class instead, or wrap the text in an element that has the `text-align` class."
|
|
1272
|
+
}];
|
|
1273
|
+
});
|
|
1274
|
+
}
|
|
1275
|
+
};
|
|
1276
|
+
/** The directive or `:model-value` binding that feeds the component's model. */
|
|
1277
|
+
var modelBinding = (element) => {
|
|
1278
|
+
return element.props.filter(isDirective).find((directive) => directive.name === "model" && !directive.arg) ?? findPropAttribute(element, "model-value")?.node;
|
|
1279
|
+
};
|
|
1280
|
+
var startsAsEmptyString = (modelPath, scriptSource) => {
|
|
1281
|
+
const escapedName = (modelPath.trim().split(MODEL_PATH_SEPARATOR).at(-1) ?? "").replaceAll(REGEX_SPECIAL_CHARACTERS, "\\$&");
|
|
1282
|
+
return EMPTY_STRING_INITIAL_PATTERNS.some((pattern) => new RegExp(pattern.replace(MODEL_NAME_PLACEHOLDER, escapedName)).test(scriptSource));
|
|
1283
|
+
};
|
|
1284
|
+
/** Rules about behaviour and styling misuses that the component API alone cannot catch. */
|
|
1285
|
+
var behaviourRules = [
|
|
1286
|
+
nativeValidationInFormRule,
|
|
1287
|
+
hideDetailsHidesLabelRule,
|
|
1288
|
+
snackbarActionContrastRule,
|
|
1289
|
+
blockButtonsInRowRule,
|
|
1290
|
+
cardTitleTextAlignRule,
|
|
1291
|
+
{
|
|
1292
|
+
id: RULE_DATE_PICKER_EMPTY_STRING,
|
|
1293
|
+
check: ({ element, scriptSource }) => {
|
|
1294
|
+
const binding = isOneOfComponentTags(element.tag, DATE_PICKER_EMPTY_STRING_COMPONENTS) ? modelBinding(element) : void 0;
|
|
1295
|
+
const source = binding && isDirective(binding) ? expressionSource(binding) : binding?.value?.content;
|
|
1296
|
+
if (!binding || source === void 0) return [];
|
|
1297
|
+
const isEmptyLiteral = EMPTY_STRING_EXPRESSION.test(source) || !isDirective(binding) && source === "";
|
|
1298
|
+
const isEmptyInitial = MODEL_PATH_PATTERN.test(source) && startsAsEmptyString(source, scriptSource);
|
|
1299
|
+
if (!isEmptyLiteral && !isEmptyInitial) return [];
|
|
1300
|
+
return [{
|
|
1301
|
+
...positionOf(binding),
|
|
1302
|
+
rule: RULE_DATE_PICKER_EMPTY_STRING,
|
|
1303
|
+
severity: SEVERITY_WARNING,
|
|
1304
|
+
message: isEmptyLiteral ? `\`${element.tag}\` gets \`''\` as its value: the picker opens on "Invalid date" and a grid of NaN.` : `\`${source}\` starts as \`''\` and is bound to \`${element.tag}\`: the picker opens on "Invalid date" and a grid of NaN.`,
|
|
1305
|
+
fixHint: "Start an empty date as `null` (type the model `string | null`); `''` is not treated as \"no date\".",
|
|
1306
|
+
recipe: RECIPE_VALIDATED_FORM
|
|
1307
|
+
}];
|
|
1308
|
+
}
|
|
1309
|
+
}
|
|
1310
|
+
];
|
|
1311
|
+
//#endregion
|
|
1107
1312
|
//#region src/services/compositionRules.ts
|
|
1108
1313
|
var compactExpression = (source) => source.replaceAll(WHITESPACE_PATTERN, "");
|
|
1109
1314
|
/** Values of the argument-less `v-on="…"` or `v-bind="…"` directives on `element`, whitespace removed. */
|
|
@@ -1314,7 +1519,7 @@ var unknownModelIssue = (component, modelProp, node) => {
|
|
|
1314
1519
|
fixHint: supported.length ? `Bind one of its model props instead: ${supported.map((prop) => prop === "modelValue" ? "`v-model`" : `\`v-model:${prop}\``).join(", ")}.` : `\`${component.name}\` supports no v-model; remove it.`
|
|
1315
1520
|
};
|
|
1316
1521
|
};
|
|
1317
|
-
/** The rules this validator runs, in order: API checks first, then the composition rules. */
|
|
1522
|
+
/** The rules this validator runs, in order: API checks first, then the composition and behaviour rules. */
|
|
1318
1523
|
var templateRules = [
|
|
1319
1524
|
unknownComponentRule,
|
|
1320
1525
|
{
|
|
@@ -1369,7 +1574,8 @@ var templateRules = [
|
|
|
1369
1574
|
});
|
|
1370
1575
|
}
|
|
1371
1576
|
},
|
|
1372
|
-
...compositionRules
|
|
1577
|
+
...compositionRules,
|
|
1578
|
+
...behaviourRules
|
|
1373
1579
|
];
|
|
1374
1580
|
//#endregion
|
|
1375
1581
|
//#region src/services/templateValidator.ts
|
|
@@ -1392,7 +1598,7 @@ var byPosition = (left, right) => left.line - right.line || left.column - right.
|
|
|
1392
1598
|
var useTemplateValidatorService = (api, rules = templateRules) => {
|
|
1393
1599
|
const catalog = useComponentCatalogService(api);
|
|
1394
1600
|
const validate = (code) => {
|
|
1395
|
-
const { root, errors } = parseVueTemplate(code);
|
|
1601
|
+
const { root, errors, scriptSource } = parseVueTemplate(code);
|
|
1396
1602
|
const ruleIssues = (root ? placedElements(root) : []).flatMap(({ element, ancestors }) => {
|
|
1397
1603
|
const applicableRules = rules.filter((rule) => appliesTo(rule, element.tag));
|
|
1398
1604
|
if (!applicableRules.length) return [];
|
|
@@ -1400,7 +1606,8 @@ var useTemplateValidatorService = (api, rules = templateRules) => {
|
|
|
1400
1606
|
element,
|
|
1401
1607
|
ancestors,
|
|
1402
1608
|
lookup: catalog.findComponent(element.tag),
|
|
1403
|
-
api
|
|
1609
|
+
api,
|
|
1610
|
+
scriptSource
|
|
1404
1611
|
};
|
|
1405
1612
|
return applicableRules.flatMap((rule) => rule.check(context));
|
|
1406
1613
|
});
|
|
@@ -10,4 +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
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="
|
|
41
|
+
<SButton variant="text" color="warning" @click="isSnackbarOpen = false">Close</SButton>
|
|
42
42
|
</template>
|
|
43
43
|
</SSnackbar>
|
|
44
44
|
</SRow>
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
title: Responsive grid
|
|
3
3
|
whenToUse: Cards or panels that stack on phones and sit side by side on wider screens.
|
|
4
|
-
components: SContainer, SRow, SColumn, SCard, SButton
|
|
4
|
+
components: SContainer, SRow, SColumn, SCard, SCardTitle, SCardText, SImage, SButton
|
|
5
5
|
---
|
|
6
6
|
|
|
7
7
|
- The 12-column grid is `SContainer` > `SRow` > `SColumn`. The column component is `SColumn`; there is no `SCol` and no `xl` prop.
|
|
@@ -9,3 +9,6 @@ components: SContainer, SRow, SColumn, SCard, SButton
|
|
|
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
|
+
- 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
|
+
- 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
|
+
- `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,5 +1,5 @@
|
|
|
1
1
|
<template>
|
|
2
|
-
<SContainer>
|
|
2
|
+
<SContainer class="s_py__4">
|
|
3
3
|
<SRow>
|
|
4
4
|
<SColumn :cols="12" :md="8">
|
|
5
5
|
<SCard class="s_pa__4" :height="160">
|
|
@@ -24,6 +24,22 @@
|
|
|
24
24
|
</SColumn>
|
|
25
25
|
</SRow>
|
|
26
26
|
|
|
27
|
+
<SRow>
|
|
28
|
+
<SColumn v-for="product in products" :key="product.name" :cols="12" :sm="6" :lg="3">
|
|
29
|
+
<SCard height="100%" outlined>
|
|
30
|
+
<SImage
|
|
31
|
+
:src="product.image"
|
|
32
|
+
:alt="product.name"
|
|
33
|
+
:aspect-ratio="IMAGE_ASPECT_RATIO"
|
|
34
|
+
height="auto"
|
|
35
|
+
object-fit="cover"
|
|
36
|
+
/>
|
|
37
|
+
<SCardTitle>{{ product.name }}</SCardTitle>
|
|
38
|
+
<SCardText>{{ product.description }}</SCardText>
|
|
39
|
+
</SCard>
|
|
40
|
+
</SColumn>
|
|
41
|
+
</SRow>
|
|
42
|
+
|
|
27
43
|
<SRow justify="spaceBetween" align="center">
|
|
28
44
|
<SColumn cols="auto">
|
|
29
45
|
<span class="s_text--subtitle__1">Showing 4 of 12</span>
|
|
@@ -36,7 +52,13 @@
|
|
|
36
52
|
</template>
|
|
37
53
|
|
|
38
54
|
<script setup lang="ts">
|
|
39
|
-
import { SButton, SCard, SColumn, SContainer, SRow } from '@khsura/sui'
|
|
55
|
+
import { SButton, SCard, SCardText, SCardTitle, SColumn, SContainer, SImage, SRow } from '@khsura/sui'
|
|
56
|
+
|
|
57
|
+
interface Product {
|
|
58
|
+
name: string
|
|
59
|
+
description: string
|
|
60
|
+
image: string
|
|
61
|
+
}
|
|
40
62
|
|
|
41
63
|
interface Stat {
|
|
42
64
|
label: string
|
|
@@ -49,4 +71,17 @@ const stats: Stat[] = [
|
|
|
49
71
|
{ label: 'Customers', value: '912' },
|
|
50
72
|
{ label: 'Refunds', value: '14' },
|
|
51
73
|
]
|
|
74
|
+
|
|
75
|
+
const IMAGE_ASPECT_RATIO = 4 / 3
|
|
76
|
+
|
|
77
|
+
const products: Product[] = [
|
|
78
|
+
{ name: 'Desk lamp', description: 'Warm light.', image: 'https://picsum.photos/seed/lamp/400/300' },
|
|
79
|
+
{
|
|
80
|
+
name: 'Wireless headphones with a long name',
|
|
81
|
+
description: 'A longer description that wraps onto several lines, so this card is the tallest in the row.',
|
|
82
|
+
image: 'https://picsum.photos/seed/headphones/400/300',
|
|
83
|
+
},
|
|
84
|
+
{ name: 'Notebook', description: 'Dotted pages.', image: 'https://picsum.photos/seed/notebook/400/300' },
|
|
85
|
+
{ name: 'Mug', description: 'Keeps coffee warm.', image: 'https://picsum.photos/seed/mug/400/300' },
|
|
86
|
+
]
|
|
52
87
|
</script>
|
|
@@ -8,6 +8,8 @@ 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
|
-
- `
|
|
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.
|
|
12
14
|
- `:loading` on the submit `SButton` disables it; do not also bind `:disabled`.
|
|
13
15
|
- For translated messages use `getFormInputModelValueRules({ t })` from `@khsura/sui` instead of inline rules.
|
|
@@ -4,7 +4,14 @@
|
|
|
4
4
|
<SCardText>
|
|
5
5
|
<SForm ref="formRef" @submit.prevent="submit">
|
|
6
6
|
<SInput v-model="form.name" label="Full name" :rules="[required]" />
|
|
7
|
-
<SInput
|
|
7
|
+
<SInput
|
|
8
|
+
v-model="form.email"
|
|
9
|
+
label="Email"
|
|
10
|
+
type="text"
|
|
11
|
+
inputmode="email"
|
|
12
|
+
autocomplete="email"
|
|
13
|
+
:rules="[required, email]"
|
|
14
|
+
/>
|
|
8
15
|
<SSelect v-model="form.role" label="Role" :items="roles" grow :rules="[required]" />
|
|
9
16
|
<SDatePickerInput v-model="form.startDate" label="Start date" type="date" block :rules="[required]" />
|
|
10
17
|
<SCheckbox v-model="form.acceptTerms" label="I accept the terms" :rules="[mustAccept]" />
|
|
@@ -34,7 +41,7 @@ interface AccountForm {
|
|
|
34
41
|
name: string
|
|
35
42
|
email: string
|
|
36
43
|
role: string | null
|
|
37
|
-
startDate: string
|
|
44
|
+
startDate: string | null
|
|
38
45
|
acceptTerms: boolean
|
|
39
46
|
}
|
|
40
47
|
|
|
@@ -53,7 +60,7 @@ const mustAccept = (value: unknown) => value === true || 'You must accept the te
|
|
|
53
60
|
const formRef = ref<InstanceType<typeof SForm> | null>(null)
|
|
54
61
|
const isSubmitting = ref(false)
|
|
55
62
|
const submittedName = ref('')
|
|
56
|
-
const form = ref<AccountForm>({ name: '', email: '', role: null, startDate:
|
|
63
|
+
const form = ref<AccountForm>({ name: '', email: '', role: null, startDate: null, acceptTerms: false })
|
|
57
64
|
|
|
58
65
|
const submit = async () => {
|
|
59
66
|
// validate() returns true when the form HAS errors.
|
package/dist/sui-api.json
CHANGED