@khsura/sui-mcp 0.2.1 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.js CHANGED
@@ -166,12 +166,22 @@ var RULE_SNACKBAR_ACTION_CONTRAST = "snackbar-action-contrast";
166
166
  var RULE_BLOCK_BUTTONS_IN_ROW = "block-buttons-in-row";
167
167
  var RULE_CARD_TITLE_TEXT_ALIGN = "card-title-text-align";
168
168
  var RULE_DATE_PICKER_EMPTY_STRING = "date-picker-empty-string";
169
+ var RULE_FIELD_BUTTON_ROW = "field-button-row";
170
+ var RULE_FILL_HEIGHT_UNDER_APP = "fill-height-under-app";
171
+ /**
172
+ * The first `@khsura/sui` release with the M2 hardening fixes (SForm `novalidate`, SCheckbox label with
173
+ * `hide-details`, `''` as "no date", snackbar action colour, SCardTitle `s_textAlign__*`). Rules for
174
+ * those behaviours set it as `fixedIn`, so they only warn for projects on an older version.
175
+ */
176
+ var SUI_M2_FIXES_VERSION = "1.20.0";
169
177
  var RULE_TARGET_ANY_ELEMENT = "any-element";
170
178
  /** Recipe names an issue points to; the recipes are published under these exact names. */
171
179
  var RECIPE_APP_SHELL = "app-shell";
172
180
  var RECIPE_VALIDATED_FORM = "validated-form";
173
181
  var RECIPE_ACTIVATOR_OVERLAYS = "activator-overlays";
174
182
  var RECIPE_RESPONSIVE_GRID = "responsive-grid";
183
+ var RECIPE_FILTER_BAR = "filter-bar";
184
+ var RECIPE_CENTERED_PAGE = "centered-page";
175
185
  var ACTIVATOR_SLOT_NAME = "activator";
176
186
  var ACTIVATOR_ATTRS_KEY = "attrs";
177
187
  /** Overlays whose `#activator` slot passes `{ on, attrs }` for the caller to bind. */
@@ -182,10 +192,13 @@ var SLOT_PROP_ACTIVATOR_COMPONENTS = [
182
192
  ];
183
193
  /** STooltip wraps the activator in its own listening element and passes no slot props. */
184
194
  var SLOTLESS_ACTIVATOR_COMPONENTS = ["STooltip"];
195
+ /** `height: 100%`; a direct child of SApp with it grows into SApp's flex column (since 1.20.0). */
196
+ var HEIGHT_FILL_CLASS = "s_height--fill";
185
197
  var LAYOUT_COMPONENT = "SLayout";
186
198
  var LAYOUT_NAME_ATTRIBUTE = "name";
187
199
  var FORM_COMPONENT = "SForm";
188
200
  var RULES_ATTRIBUTE = "rules";
201
+ var BUTTON_COMPONENT = "SButton";
189
202
  var ACCESSIBLE_LABEL_ATTRIBUTES = [
190
203
  "aria-label",
191
204
  "aria-labelledby",
@@ -218,7 +231,12 @@ var HIDE_DETAILS_LABEL_COMPONENTS = ["SCheckbox"];
218
231
  var SNACKBAR_ACTION_SLOT_NAME = "action";
219
232
  var COLOR_ATTRIBUTE = "color";
220
233
  var VARIANT_ATTRIBUTE = "variant";
221
- /** Preset colours below 4.5:1 as text on the default `#424242` snackbar (primary is 2.18:1). */
234
+ /** Action variants that, before the M2 fix, kept the page's dark text colour on the dark snackbar when no `color` was set. */
235
+ var SNACKBAR_UNCOLOURED_ACTION_VARIANTS = ["text", "icon"];
236
+ /**
237
+ * Preset colours below 4.5:1 as text on the default `#424242` snackbar before `SUI_M2_FIXES_VERSION` (primary is
238
+ * 2.18:1). From that version a preset text colour inside the snackbar uses a variant tuned to the snackbar.
239
+ */
222
240
  var SNACKBAR_UNREADABLE_PRESET_COLORS = [
223
241
  "primary",
224
242
  "secondary",
@@ -226,9 +244,19 @@ var SNACKBAR_UNREADABLE_PRESET_COLORS = [
226
244
  "info",
227
245
  "error"
228
246
  ];
229
- var SNACKBAR_READABLE_ACTION_COLOR = "warning";
247
+ /** The theme's default `snackbar` colour, dark in both themes: CSS-colour actions are measured against it. */
248
+ var SNACKBAR_DEFAULT_BACKGROUND = "#424242";
249
+ var SNACKBAR_LIGHT_ACTION_COLOR_HINT = `\`color="warning"\` or a CSS colour such as \`color="#ffffff"\``;
230
250
  /** Components whose root is a `display: flex` row. */
231
251
  var FLEX_ROW_COMPONENTS = ["SCardActions"];
252
+ /** Text fields that render a label above their box and an error line under it. */
253
+ var LABELLED_FIELD_COMPONENTS = [
254
+ "SInput",
255
+ "SSelect",
256
+ "SDatePickerInput",
257
+ "SAutocomplete",
258
+ "STextarea"
259
+ ];
232
260
  /** `s_display__flex`, `s_display--md__inlineFlex`: the utility classes that make an element a flex row. */
233
261
  var FLEX_DISPLAY_CLASS_PATTERN = /^s_display(?:--[a-z]+)?__(?:flex|inlineFlex)$/;
234
262
  var FLEX_DISPLAY_STYLE_PATTERN = /(?:^|;)\s*display\s*:\s*(?:inline-)?flex\b/;
@@ -263,7 +291,9 @@ var RECIPE_NAMES = [
263
291
  "activator-overlays",
264
292
  "data-table",
265
293
  "responsive-grid",
266
- "theme-setup"
294
+ "theme-setup",
295
+ "filter-bar",
296
+ "centered-page"
267
297
  ];
268
298
  var RECIPES_DIRNAME = "recipes";
269
299
  /** Repo-relative folder that holds the recipe sources (Storybook renders the same files). */
@@ -316,6 +346,194 @@ var CONFIG_STATUS_UPDATED = "updated";
316
346
  var CONFIG_STATUS_UNCHANGED = "unchanged";
317
347
  var CONFIG_ACTION_WRITE = "write";
318
348
  var CONFIG_ACTION_PRINT = "print";
349
+ /**
350
+ * Component names from Vuetify, Quasar, Element and similar libraries that are not in @khsura/sui,
351
+ * with the SUI component(s) to use instead and a short hint. An empty `suiNames` means SUI has no
352
+ * equivalent yet. Keys are matched like component names (case, `-` and the `S` prefix are ignored),
353
+ * and an alias is never used when the name is a real component in the resolved `sui-api.json`.
354
+ */
355
+ var COMPONENT_ALIASES = {
356
+ SCol: {
357
+ suiNames: ["SColumn"],
358
+ hint: "The grid column is `SColumn`, inside an `SRow` (`:cols`, `:md`, … set its width)."
359
+ },
360
+ SCols: {
361
+ suiNames: ["SColumn"],
362
+ hint: "The grid column is `SColumn`, inside an `SRow`."
363
+ },
364
+ SColumns: {
365
+ suiNames: ["SColumn"],
366
+ hint: "The grid column is `SColumn`, one per column, inside an `SRow`."
367
+ },
368
+ STextField: {
369
+ suiNames: ["SInput"],
370
+ hint: "The text field is `SInput` (`label`, `type`, `rules`, `v-model`)."
371
+ },
372
+ STextInput: {
373
+ suiNames: ["SInput"],
374
+ hint: "The text field is `SInput` (`label`, `type`, `rules`, `v-model`)."
375
+ },
376
+ SInputText: {
377
+ suiNames: ["SInput"],
378
+ hint: "The text field is `SInput`."
379
+ },
380
+ SBtn: {
381
+ suiNames: ["SButton"],
382
+ hint: "The button is `SButton` (`variant`, `color`, `size`)."
383
+ },
384
+ SIconButton: {
385
+ suiNames: ["SButton"],
386
+ hint: "An icon-only button is `<SButton variant=\"icon\" aria-label=\"…\">` with an `SIcon` inside."
387
+ },
388
+ SBtnToggle: {
389
+ suiNames: ["SToggleButtonGroup", "SToggleButton"],
390
+ hint: "Use `SToggleButtonGroup` with `SToggleButton` children."
391
+ },
392
+ SDataTable: {
393
+ suiNames: ["STable"],
394
+ hint: "The data table is `STable` (`headers`, `items`, `item.<key>` slots)."
395
+ },
396
+ SSimpleTable: {
397
+ suiNames: ["STable"],
398
+ hint: "The table is `STable`."
399
+ },
400
+ STabsWindow: {
401
+ suiNames: ["SWindow"],
402
+ hint: "Tab content is an `SWindow` bound to the same `v-model` as `STabs`, with one `SWindowItem` per tab."
403
+ },
404
+ STabsWindowItem: {
405
+ suiNames: ["SWindowItem"],
406
+ hint: "Each tab panel is an `SWindowItem` inside an `SWindow`."
407
+ },
408
+ STabsItems: {
409
+ suiNames: ["SWindow"],
410
+ hint: "Tab content is an `SWindow` bound to the same `v-model` as `STabs`."
411
+ },
412
+ STabItem: {
413
+ suiNames: ["SWindowItem"],
414
+ hint: "Each tab panel is an `SWindowItem` inside an `SWindow`; the tab itself is `STab`."
415
+ },
416
+ STabPanels: {
417
+ suiNames: ["SWindow"],
418
+ hint: "Tab content is an `SWindow` bound to the same `v-model` as `STabs`."
419
+ },
420
+ STabPanel: {
421
+ suiNames: ["SWindowItem"],
422
+ hint: "Each tab panel is an `SWindowItem` inside an `SWindow`."
423
+ },
424
+ STabPane: {
425
+ suiNames: ["STab", "SWindowItem"],
426
+ hint: "Put an `STab` in `STabs` and its content in an `SWindowItem` inside an `SWindow`."
427
+ },
428
+ SAvatar: {
429
+ suiNames: [],
430
+ hint: "There is no avatar component yet (planned for M3). For a photo use `<SImage src=\"…\" :aspect-ratio=\"1\" object-fit=\"cover\" :width=\"40\" style=\"border-radius: 50%\" />`; for initials use a fixed-size element with `border-radius: 50%`, a background colour and centred text."
431
+ },
432
+ SModal: {
433
+ suiNames: ["SDialog"],
434
+ hint: "The modal is `SDialog`, opened from its `#activator` slot or a `v-model`."
435
+ },
436
+ SDrawer: {
437
+ suiNames: ["SNavigationDrawer"],
438
+ hint: "The side drawer is `SNavigationDrawer`, a child of `SLayout`."
439
+ },
440
+ SHeader: {
441
+ suiNames: ["SAppBar"],
442
+ hint: "The page header bar is `SAppBar`, a child of `SLayout`."
443
+ },
444
+ SPage: {
445
+ suiNames: ["SMain"],
446
+ hint: "The page content area is `SMain`, a child of `SLayout`."
447
+ },
448
+ SContent: {
449
+ suiNames: ["SMain"],
450
+ hint: "The page content area is `SMain`, a child of `SLayout`."
451
+ },
452
+ SToast: {
453
+ suiNames: ["SSnackbar"],
454
+ hint: "The toast is `SSnackbar` (`v-model`, `timeout`, `#action` slot)."
455
+ },
456
+ SNotification: {
457
+ suiNames: ["SSnackbar"],
458
+ hint: "A transient message is `SSnackbar`; a static one is `SAlert`."
459
+ },
460
+ SDropdown: {
461
+ suiNames: ["SMenu"],
462
+ hint: "The dropdown is `SMenu`, opened from its `#activator` slot."
463
+ },
464
+ SSpinner: {
465
+ suiNames: ["SProgressCircular"],
466
+ hint: "The spinner is `<SProgressCircular indeterminate />`."
467
+ },
468
+ SProgressBar: {
469
+ suiNames: ["SProgressLinear"],
470
+ hint: "The progress bar is `SProgressLinear`."
471
+ },
472
+ SToggle: {
473
+ suiNames: ["SSwitch"],
474
+ hint: "The on/off toggle is `SSwitch`."
475
+ },
476
+ SCombobox: {
477
+ suiNames: ["SAutocomplete"],
478
+ hint: "A searchable select is `SAutocomplete`."
479
+ },
480
+ SImg: {
481
+ suiNames: ["SImage"],
482
+ hint: "The image is `SImage`."
483
+ },
484
+ SCardHeader: {
485
+ suiNames: ["SCardTitle"],
486
+ hint: "The card heading is `SCardTitle` (with `SCardSubtitle` below it)."
487
+ },
488
+ SCardBody: {
489
+ suiNames: ["SCardText"],
490
+ hint: "The card body is `SCardText`."
491
+ },
492
+ SCardContent: {
493
+ suiNames: ["SCardText"],
494
+ hint: "The card body is `SCardText`."
495
+ },
496
+ SCardSection: {
497
+ suiNames: ["SCardText"],
498
+ hint: "The card body is `SCardText`."
499
+ },
500
+ SCardFooter: {
501
+ suiNames: ["SCardActions"],
502
+ hint: "The card footer with buttons is `SCardActions`."
503
+ },
504
+ SExpansionPanelTitle: {
505
+ suiNames: ["SExpansionPanelHeader"],
506
+ hint: "The clickable row of a panel is `SExpansionPanelHeader`."
507
+ },
508
+ SExpansionPanelText: {
509
+ suiNames: ["SExpansionPanelContent"],
510
+ hint: "The body of a panel is `SExpansionPanelContent`."
511
+ },
512
+ SAccordion: {
513
+ suiNames: ["SExpansionPanels"],
514
+ hint: "The accordion is `SExpansionPanels` with `SExpansionPanel` children."
515
+ },
516
+ SStepperItem: {
517
+ suiNames: ["SStepperStep"],
518
+ hint: "Each step is an `SStepperStep` inside `SStepper`."
519
+ }
520
+ };
521
+ //#endregion
522
+ //#region src/constants/semver.ts
523
+ /** `1.20.0`, `v1.20.0`, `1.20.0-beta.1`: major, minor, patch and an optional pre-release tag. */
524
+ var SEMVER_PATTERN = /^\s*v?(\d+)\.(\d+)\.(\d+)(?:-([\w.-]+))?(?:\+[\w.-]+)?\s*$/;
525
+ //#endregion
526
+ //#region src/constants/contrast.ts
527
+ /** `#rgb` or `#rrggbb` (case-insensitive): the hex digits. */
528
+ var HEX_COLOR_PATTERN = /^#([\da-f]{3}|[\da-f]{6})$/i;
529
+ var SRGB_LINEAR_DIVISOR = 12.92;
530
+ var SRGB_GAMMA_OFFSET = .055;
531
+ var SRGB_GAMMA_DIVISOR = 1.055;
532
+ var SRGB_GAMMA = 2.4;
533
+ var LUMINANCE_WEIGHT_RED = .2126;
534
+ var LUMINANCE_WEIGHT_GREEN = .7152;
535
+ var LUMINANCE_WEIGHT_BLUE = .0722;
536
+ var CONTRAST_FLARE = .05;
319
537
  //#endregion
320
538
  //#region src/schemas/componentTools.schema.ts
321
539
  var getComponentApiInputSchema = z.object({ name: z.string().trim().min(1).describe("Component name: `SButton`, `s-button` or `button` (case-insensitive).") });
@@ -549,6 +767,156 @@ var mergeMcpServerEntry = ({ existingText, serversKey, entryName, entry }) => {
549
767
  /** The snippet a user pastes into a config file they edit by hand. */
550
768
  var mcpServerSnippet = ({ serversKey, entryName, entry }) => serializeJson({ [serversKey]: { [entryName]: entry } });
551
769
  //#endregion
770
+ //#region src/lib/semver.ts
771
+ var parseVersion = (version) => {
772
+ const match = SEMVER_PATTERN.exec(version);
773
+ if (!match) return;
774
+ const [, major, minor, patch, preRelease] = match;
775
+ return {
776
+ core: [
777
+ Number(major),
778
+ Number(minor),
779
+ Number(patch)
780
+ ],
781
+ preRelease
782
+ };
783
+ };
784
+ /**
785
+ * Orders two semver strings: negative when `left` is older, positive when newer, 0 when equal.
786
+ * A pre-release sorts before its release (`1.20.0-beta.1` < `1.20.0`); pre-release tags compare as text.
787
+ * Returns `undefined` when either string is not a semver version.
788
+ */
789
+ var compareVersions = (left, right) => {
790
+ const leftVersion = parseVersion(left);
791
+ const rightVersion = parseVersion(right);
792
+ if (!leftVersion || !rightVersion) return;
793
+ const coreDifference = leftVersion.core.map((part, index) => part - rightVersion.core[index]).find((difference) => difference !== 0);
794
+ if (coreDifference !== void 0) return coreDifference;
795
+ if (leftVersion.preRelease === rightVersion.preRelease) return 0;
796
+ if (leftVersion.preRelease === void 0 || rightVersion.preRelease === void 0) return leftVersion.preRelease === void 0 ? 1 : -1;
797
+ return leftVersion.preRelease.localeCompare(rightVersion.preRelease);
798
+ };
799
+ /** True when `version` is `minimum` or newer; false when either is not a semver version. */
800
+ var isVersionAtLeast = (version, minimum) => (compareVersions(version, minimum) ?? -1) >= 0;
801
+ //#endregion
802
+ //#region src/lib/contrast.ts
803
+ /** `#rgb` / `#rrggbb` as `[r, g, b]` (0-255), or `undefined` for anything else (named colours, `rgb()`, bindings). */
804
+ var parseHexColor = (color) => {
805
+ const match = HEX_COLOR_PATTERN.exec(color.trim());
806
+ if (!match) return;
807
+ const [red, green, blue] = (match[1].length === 3 ? [...match[1]].map((digit) => digit + digit) : [
808
+ match[1].slice(0, 2),
809
+ match[1].slice(2, 4),
810
+ match[1].slice(4, 6)
811
+ ]).map((pair) => Number.parseInt(pair, 16));
812
+ return [
813
+ red,
814
+ green,
815
+ blue
816
+ ];
817
+ };
818
+ var linearizeChannel = (channel) => {
819
+ const ratio = channel / 255;
820
+ return ratio <= .04045 ? ratio / SRGB_LINEAR_DIVISOR : ((ratio + SRGB_GAMMA_OFFSET) / SRGB_GAMMA_DIVISOR) ** SRGB_GAMMA;
821
+ };
822
+ var relativeLuminance = ([red, green, blue]) => LUMINANCE_WEIGHT_RED * linearizeChannel(red) + LUMINANCE_WEIGHT_GREEN * linearizeChannel(green) + LUMINANCE_WEIGHT_BLUE * linearizeChannel(blue);
823
+ /** WCAG 2.x contrast ratio (1 to 21) between two hex colours, or `undefined` when either is not `#rgb`/`#rrggbb`. */
824
+ var getHexContrastRatio = (first, second) => {
825
+ const firstRgb = parseHexColor(first);
826
+ const secondRgb = parseHexColor(second);
827
+ if (!firstRgb || !secondRgb) return;
828
+ const firstLuminance = relativeLuminance(firstRgb);
829
+ const secondLuminance = relativeLuminance(secondRgb);
830
+ return (Math.max(firstLuminance, secondLuminance) + CONTRAST_FLARE) / (Math.min(firstLuminance, secondLuminance) + CONTRAST_FLARE);
831
+ };
832
+ //#endregion
833
+ //#region src/utils/componentName.ts
834
+ var NAME_SEPARATORS = /[\s_-]/g;
835
+ /** Lowercase key with separators removed: `SButton`, `s-button` and `sbutton` all map to `sbutton`. */
836
+ var toComponentKey = (name) => name.trim().toLowerCase().replaceAll(NAME_SEPARATORS, "");
837
+ /** Keys a query may refer to, most specific first: as typed, then with the `S` prefix added. */
838
+ var candidateComponentKeys = (query) => {
839
+ const queryKey = toComponentKey(query);
840
+ return [queryKey, `s${queryKey}`];
841
+ };
842
+ /** `SNavigationDrawer` → `Navigation drawer`. */
843
+ var humanizeComponentName = (name) => {
844
+ const sentence = name.replace(/^S(?=[A-Z])/, "").split(/(?=[A-Z])/).map((word) => word.toLowerCase()).join(" ");
845
+ return sentence.charAt(0).toUpperCase() + sentence.slice(1);
846
+ };
847
+ /** True for tags the validator treats as SUI components: `SButton` or `s-button`. Native tags such as `select` never match. */
848
+ var isSuiComponentTag = (tag) => SUI_PASCAL_TAG_PATTERN.test(tag) || SUI_KEBAB_TAG_PATTERN.test(tag);
849
+ //#endregion
850
+ //#region src/utils/templateAst.ts
851
+ var positionOf = (node) => ({
852
+ line: node.loc.start.line,
853
+ column: node.loc.start.column
854
+ });
855
+ var codeList = (names) => names.map((name) => `\`${name}\``).join(", ");
856
+ /** The argument of a directive when it is a static name (`:size`, `#header`); `undefined` for none or `[dynamic]`. */
857
+ var staticArgument = (argument) => argument?.type === NodeTypes.SIMPLE_EXPRESSION && argument.isStatic ? argument.content : void 0;
858
+ /** The source of a directive's value (`on` in `v-on="on"`), trimmed; `undefined` when it has none. */
859
+ var expressionSource = (directive) => {
860
+ const source = directive.exp?.loc.source.trim() ?? "";
861
+ return source.length ? source : void 0;
862
+ };
863
+ var isDirective = (prop) => prop.type === NodeTypes.DIRECTIVE;
864
+ /** True when `tag` names `componentName` in either case style: `SAppBar`, `s-app-bar`. */
865
+ var isComponentTag = (tag, componentName) => toComponentKey(tag) === toComponentKey(componentName);
866
+ var isOneOfComponentTags = (tag, componentNames) => componentNames.some((componentName) => isComponentTag(tag, componentName));
867
+ var childElementsOf = (element) => element.children.filter((child) => child.type === NodeTypes.ELEMENT);
868
+ /** `name="x"` or `:name="x"` / `v-bind:name="x"` on `element`; a quoted literal binding still has a static value. */
869
+ var findAttribute = (element, name) => {
870
+ for (const prop of element.props) {
871
+ if (!isDirective(prop)) {
872
+ if (prop.name === name) return {
873
+ node: prop,
874
+ staticValue: prop.value?.content,
875
+ isBound: false
876
+ };
877
+ continue;
878
+ }
879
+ if (prop.name === "bind" && staticArgument(prop.arg) === name) {
880
+ const literal = STRING_LITERAL_EXPRESSION.exec(expressionSource(prop) ?? "");
881
+ return {
882
+ node: prop,
883
+ staticValue: literal?.[2],
884
+ isBound: !literal
885
+ };
886
+ }
887
+ }
888
+ };
889
+ /** `v-bind="object"`: it may carry any attribute, so presence checks cannot be sure. */
890
+ var hasObjectSpread = (element) => element.props.some((prop) => isDirective(prop) && prop.name === "bind" && !prop.arg);
891
+ /** Slots `element` fills: `v-slot` / `#name` on the element itself or on its direct `<template>` children. */
892
+ var slotFills = (element) => {
893
+ return [element, ...childElementsOf(element).filter((child) => child.tag === TEMPLATE_TAG)].flatMap((owner) => owner.props.filter(isDirective).filter((directive) => directive.name === DIRECTIVE_SLOT).map((directive) => ({
894
+ directive,
895
+ owner
896
+ })));
897
+ };
898
+ var slotDirectives = (element) => slotFills(element).map((fill) => fill.directive);
899
+ /** Every element below `element`, depth first. */
900
+ var descendantElementsOf = (element) => childElementsOf(element).flatMap((child) => [child, ...descendantElementsOf(child)]);
901
+ /** A prop written in either case style: `hide-details`, `hideDetails`, `:hide-details`. */
902
+ var findPropAttribute = (element, kebabName) => findAttribute(element, kebabName) ?? findAttribute(element, toCamelCase(kebabName));
903
+ /** A boolean prop that is set and not statically `false` (`block`, `:block="true"`, `:block="isWide"`). */
904
+ var isBooleanPropOn = (element, kebabName) => {
905
+ const attribute = findPropAttribute(element, kebabName);
906
+ if (!attribute) return false;
907
+ return !isDirective(attribute.node) || expressionSource(attribute.node) !== "false";
908
+ };
909
+ /** The static `class` tokens of `element` (a plain `class` or a string-literal `:class`); bound classes are unknown. */
910
+ var staticClassNames = (element) => element.props.flatMap((prop) => {
911
+ if (!isDirective(prop)) return prop.name === "class" ? [prop.value?.content ?? ""] : [];
912
+ const literal = prop.name === "bind" && staticArgument(prop.arg) === "class" ? STRING_LITERAL_EXPRESSION.exec(expressionSource(prop) ?? "") : null;
913
+ return literal ? [literal[2]] : [];
914
+ }).flatMap((value) => value.split(WHITESPACE_PATTERN)).filter(Boolean);
915
+ //#endregion
916
+ //#region src/utils/componentAliasMarkdown.ts
917
+ /** `SUI equivalent: \`SColumn\`. <hint>`, or just the hint when SUI has no equivalent yet. */
918
+ var formatComponentAlias = (alias) => alias.suiNames.length ? `SUI equivalent: ${codeList(alias.suiNames)}. ${alias.hint}` : alias.hint;
919
+ //#endregion
552
920
  //#region src/utils/componentMarkdown.ts
553
921
  var OPTIONAL_TYPE_SUFFIX = / \| undefined$/;
554
922
  var EMPTY_CELL = "—";
@@ -637,8 +1005,19 @@ var formatComponentApi = (resolved, component) => [
637
1005
  "",
638
1006
  formatNamedTypes(component.events, "Payload")
639
1007
  ].join("\n");
640
- var formatUnknownComponent = (resolved, query, suggestions) => {
641
- const hint = suggestions.length ? `Did you mean: ${suggestions.map(inlineCode).join(", ")}?` : `Call ${inlineCode(LIST_COMPONENTS_TOOL_NAME)} to see every component.`;
1008
+ /** An unknown name: the other-library alias mapping first (when there is one), then the closest names. */
1009
+ var formatUnknownComponent = (resolved, query, suggestions, alias) => {
1010
+ const suggestionText = suggestions.map(inlineCode).join(", ");
1011
+ const listHint = `Call ${inlineCode(LIST_COMPONENTS_TOOL_NAME)} to see every component.`;
1012
+ if (alias) {
1013
+ const otherNames = suggestions.length ? ` Other close names: ${suggestionText}.` : "";
1014
+ return [
1015
+ formatSourceHeader(resolved),
1016
+ "",
1017
+ `Unknown component ${inlineCode(query)} (a name from another UI library). ${formatComponentAlias(alias)}${otherNames}`
1018
+ ].join("\n");
1019
+ }
1020
+ const hint = suggestions.length ? `Did you mean: ${suggestionText}?` : listHint;
642
1021
  return [
643
1022
  formatSourceHeader(resolved),
644
1023
  "",
@@ -654,23 +1033,6 @@ var formatComponentNeedsUpgrade = (resolved, bundled, componentName) => [
654
1033
  `Upgrade first (for example \`yarn up @khsura/sui\` or \`npm install @khsura/sui@latest\`), or build the UI from components this version has (call ${inlineCode(LIST_COMPONENTS_TOOL_NAME)}).`
655
1034
  ].join("\n");
656
1035
  //#endregion
657
- //#region src/utils/componentName.ts
658
- var NAME_SEPARATORS = /[\s_-]/g;
659
- /** Lowercase key with separators removed: `SButton`, `s-button` and `sbutton` all map to `sbutton`. */
660
- var toComponentKey = (name) => name.trim().toLowerCase().replaceAll(NAME_SEPARATORS, "");
661
- /** Keys a query may refer to, most specific first: as typed, then with the `S` prefix added. */
662
- var candidateComponentKeys = (query) => {
663
- const queryKey = toComponentKey(query);
664
- return [queryKey, `s${queryKey}`];
665
- };
666
- /** `SNavigationDrawer` → `Navigation drawer`. */
667
- var humanizeComponentName = (name) => {
668
- const sentence = name.replace(/^S(?=[A-Z])/, "").split(/(?=[A-Z])/).map((word) => word.toLowerCase()).join(" ");
669
- return sentence.charAt(0).toUpperCase() + sentence.slice(1);
670
- };
671
- /** True for tags the validator treats as SUI components: `SButton` or `s-button`. Native tags such as `select` never match. */
672
- var isSuiComponentTag = (tag) => SUI_PASCAL_TAG_PATTERN.test(tag) || SUI_KEBAB_TAG_PATTERN.test(tag);
673
- //#endregion
674
1036
  //#region src/utils/componentPurpose.ts
675
1037
  var familyPurpose = (family) => Object.entries(FAMILY_PURPOSES).find(([familyName]) => familyName === family)?.[1] ?? "SUI component";
676
1038
  /**
@@ -718,72 +1080,6 @@ var formatTemplateValidation = (resolved, issues) => [
718
1080
  ...issues.length ? ["", ...issues.map((issue) => `- ${formatTemplateIssue(issue)}`)] : []
719
1081
  ].join("\n");
720
1082
  //#endregion
721
- //#region src/utils/templateAst.ts
722
- var positionOf = (node) => ({
723
- line: node.loc.start.line,
724
- column: node.loc.start.column
725
- });
726
- var codeList = (names) => names.map((name) => `\`${name}\``).join(", ");
727
- /** The argument of a directive when it is a static name (`:size`, `#header`); `undefined` for none or `[dynamic]`. */
728
- var staticArgument = (argument) => argument?.type === NodeTypes.SIMPLE_EXPRESSION && argument.isStatic ? argument.content : void 0;
729
- /** The source of a directive's value (`on` in `v-on="on"`), trimmed; `undefined` when it has none. */
730
- var expressionSource = (directive) => {
731
- const source = directive.exp?.loc.source.trim() ?? "";
732
- return source.length ? source : void 0;
733
- };
734
- var isDirective = (prop) => prop.type === NodeTypes.DIRECTIVE;
735
- /** True when `tag` names `componentName` in either case style: `SAppBar`, `s-app-bar`. */
736
- var isComponentTag = (tag, componentName) => toComponentKey(tag) === toComponentKey(componentName);
737
- var isOneOfComponentTags = (tag, componentNames) => componentNames.some((componentName) => isComponentTag(tag, componentName));
738
- var childElementsOf = (element) => element.children.filter((child) => child.type === NodeTypes.ELEMENT);
739
- /** `name="x"` or `:name="x"` / `v-bind:name="x"` on `element`; a quoted literal binding still has a static value. */
740
- var findAttribute = (element, name) => {
741
- for (const prop of element.props) {
742
- if (!isDirective(prop)) {
743
- if (prop.name === name) return {
744
- node: prop,
745
- staticValue: prop.value?.content,
746
- isBound: false
747
- };
748
- continue;
749
- }
750
- if (prop.name === "bind" && staticArgument(prop.arg) === name) {
751
- const literal = STRING_LITERAL_EXPRESSION.exec(expressionSource(prop) ?? "");
752
- return {
753
- node: prop,
754
- staticValue: literal?.[2],
755
- isBound: !literal
756
- };
757
- }
758
- }
759
- };
760
- /** `v-bind="object"`: it may carry any attribute, so presence checks cannot be sure. */
761
- var hasObjectSpread = (element) => element.props.some((prop) => isDirective(prop) && prop.name === "bind" && !prop.arg);
762
- /** Slots `element` fills: `v-slot` / `#name` on the element itself or on its direct `<template>` children. */
763
- var slotFills = (element) => {
764
- return [element, ...childElementsOf(element).filter((child) => child.tag === TEMPLATE_TAG)].flatMap((owner) => owner.props.filter(isDirective).filter((directive) => directive.name === DIRECTIVE_SLOT).map((directive) => ({
765
- directive,
766
- owner
767
- })));
768
- };
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);
786
- //#endregion
787
1083
  //#region src/utils/recipeMarkdown.ts
788
1084
  var recipeStoryUrl = (name) => `${LIVE_EXAMPLES_URL}${RECIPE_STORY_PATH_PREFIX}${name}`;
789
1085
  /** A fence one backtick longer than the longest backtick run in `code`, so the code can never close it early. */
@@ -819,19 +1115,36 @@ var formatUnknownRecipe = (query, names) => `Unknown recipe ${inlineCode(query)}
819
1115
  //#endregion
820
1116
  //#region src/services/componentCatalog.ts
821
1117
  var useComponentCatalogService = (api) => {
1118
+ const componentKeys = new Set(api.components.map((component) => toComponentKey(component.name)));
822
1119
  const listComponents = () => api.components.map((component) => ({
823
1120
  name: component.name,
824
1121
  family: component.family,
825
1122
  purpose: componentPurpose(component)
826
1123
  }));
827
- const suggestNames = (query) => {
1124
+ const suggestNames = (query, excludedNames = []) => {
828
1125
  const queryKeys = candidateComponentKeys(query);
829
1126
  const distanceTo = (name) => Math.min(...queryKeys.map((queryKey) => levenshteinDistance(queryKey, toComponentKey(name))));
830
- return api.components.map((component) => ({
1127
+ return api.components.filter((component) => !excludedNames.includes(component.name)).map((component) => ({
831
1128
  name: component.name,
832
1129
  distance: distanceTo(component.name)
833
1130
  })).sort((left, right) => left.distance - right.distance || left.name.localeCompare(right.name)).slice(0, 3).map((candidate) => candidate.name);
834
1131
  };
1132
+ /**
1133
+ * The other-library alias for a name that is not a component. An alias whose SUI targets are all
1134
+ * missing from this API version is skipped, so the Levenshtein suggestions answer instead.
1135
+ */
1136
+ const findAlias = (query) => {
1137
+ const queryKeys = candidateComponentKeys(query);
1138
+ const entry = Object.entries(COMPONENT_ALIASES).find(([alias]) => queryKeys.includes(toComponentKey(alias)));
1139
+ if (!entry) return;
1140
+ const [alias, { suiNames, hint }] = entry;
1141
+ const availableNames = suiNames.filter((name) => componentKeys.has(toComponentKey(name)));
1142
+ return suiNames.length && !availableNames.length ? void 0 : {
1143
+ alias,
1144
+ suiNames: availableNames,
1145
+ hint
1146
+ };
1147
+ };
835
1148
  const findComponent = (query) => {
836
1149
  for (const candidateKey of candidateComponentKeys(query)) {
837
1150
  const component = api.components.find((entry) => toComponentKey(entry.name) === candidateKey);
@@ -840,9 +1153,11 @@ var useComponentCatalogService = (api) => {
840
1153
  component
841
1154
  };
842
1155
  }
1156
+ const alias = findAlias(query);
843
1157
  return {
844
1158
  found: false,
845
- suggestions: suggestNames(query)
1159
+ suggestions: suggestNames(query, alias?.suiNames),
1160
+ alias
846
1161
  };
847
1162
  };
848
1163
  return {
@@ -997,7 +1312,7 @@ var serverInfo = {
997
1312
  name: SERVER_NAME,
998
1313
  version: {
999
1314
  name: "@khsura/sui-mcp",
1000
- version: "0.2.1",
1315
+ version: "0.3.0",
1001
1316
  repository: {
1002
1317
  "type": "git",
1003
1318
  "url": "git+https://github.com/khsura/sui.git",
@@ -1183,6 +1498,7 @@ var useGuideCatalogService = ({ sourceRoot = resolveGuideSourceRoot() } = {}) =>
1183
1498
  //#region src/services/behaviourRules.ts
1184
1499
  var nativeValidationInFormRule = {
1185
1500
  id: RULE_NATIVE_VALIDATION_IN_FORM,
1501
+ fixedIn: SUI_M2_FIXES_VERSION,
1186
1502
  check: ({ element, ancestors }) => {
1187
1503
  const typeAttribute = findAttribute(element, INPUT_TYPE_ATTRIBUTE);
1188
1504
  const inputType = typeAttribute?.staticValue?.toLowerCase();
@@ -1201,6 +1517,7 @@ var nativeValidationInFormRule = {
1201
1517
  };
1202
1518
  var hideDetailsHidesLabelRule = {
1203
1519
  id: RULE_HIDE_DETAILS_HIDES_LABEL,
1520
+ fixedIn: SUI_M2_FIXES_VERSION,
1204
1521
  check: ({ element }) => {
1205
1522
  const hideDetails = findPropAttribute(element, HIDE_DETAILS_ATTRIBUTE);
1206
1523
  if (!isOneOfComponentTags(element.tag, HIDE_DETAILS_LABEL_COMPONENTS) || !hideDetails || !isBooleanPropOn(element, "hide-details") || !findAttribute(element, "label")) return [];
@@ -1214,26 +1531,65 @@ var hideDetailsHidesLabelRule = {
1214
1531
  }];
1215
1532
  }
1216
1533
  };
1217
- var isUnreadableSnackbarAction = (button) => {
1534
+ var isUnreadablePresetAction = (button) => {
1535
+ const color = findAttribute(button, COLOR_ATTRIBUTE)?.staticValue;
1536
+ return findAttribute(button, "variant")?.staticValue === "text" && color !== void 0 && SNACKBAR_UNREADABLE_PRESET_COLORS.includes(color);
1537
+ };
1538
+ /** A text or icon action with a hex CSS colour below 4.5:1 on the default snackbar: used as is, in every version. */
1539
+ var lowContrastCssColorOf = (button) => {
1218
1540
  const color = findAttribute(button, COLOR_ATTRIBUTE)?.staticValue;
1219
1541
  const variant = findAttribute(button, VARIANT_ATTRIBUTE)?.staticValue;
1220
- return isComponentTag(button.tag, "SButton") && variant === "text" && color !== void 0 && SNACKBAR_UNREADABLE_PRESET_COLORS.includes(color);
1542
+ if (color === void 0 || variant === void 0 || !SNACKBAR_UNCOLOURED_ACTION_VARIANTS.includes(variant)) return;
1543
+ const contrast = getHexContrastRatio(color, SNACKBAR_DEFAULT_BACKGROUND);
1544
+ return contrast !== void 0 && contrast < 4.5 ? {
1545
+ color,
1546
+ contrast
1547
+ } : void 0;
1221
1548
  };
1549
+ /** A text or icon action with no colour at all: dark page text on the dark snackbar before the M2 fix. */
1550
+ var isUncolouredAction = (button) => {
1551
+ const variant = findAttribute(button, VARIANT_ATTRIBUTE)?.staticValue;
1552
+ return variant !== void 0 && SNACKBAR_UNCOLOURED_ACTION_VARIANTS.includes(variant) && !findAttribute(button, "color") && !staticClassNames(button).some((name) => name.startsWith("s_textColor__"));
1553
+ };
1554
+ var snackbarActionIssue = (button, hasSnackbarColorFix) => {
1555
+ const base = {
1556
+ ...positionOf(button),
1557
+ rule: RULE_SNACKBAR_ACTION_CONTRAST,
1558
+ severity: SEVERITY_WARNING,
1559
+ recipe: RECIPE_ACTIVATOR_OVERLAYS
1560
+ };
1561
+ const lowContrastCssColor = lowContrastCssColorOf(button);
1562
+ if (lowContrastCssColor) return {
1563
+ ...base,
1564
+ message: `A \`color="${lowContrastCssColor.color}"\` action in the \`SSnackbar\` is ${lowContrastCssColor.contrast.toFixed(2)}:1 on the dark snackbar background (below 4.5:1), so the action is hard to read. A CSS colour is used as is.`,
1565
+ fixHint: hasSnackbarColorFix ? "Remove `color` (an action without a colour uses the snackbar text colour), or use a light CSS colour such as `color=\"#ffffff\"`." : `Use a light colour: ${SNACKBAR_LIGHT_ACTION_COLOR_HINT}.`
1566
+ };
1567
+ if (hasSnackbarColorFix) return;
1568
+ if (isUnreadablePresetAction(button)) {
1569
+ const color = findAttribute(button, "color")?.staticValue ?? "";
1570
+ return {
1571
+ ...base,
1572
+ message: `Before @khsura/sui ${SUI_M2_FIXES_VERSION}, 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.`,
1573
+ fixHint: `Use a light colour: ${SNACKBAR_LIGHT_ACTION_COLOR_HINT}, or upgrade to ${SUI_M2_FIXES_VERSION} or later and remove \`color\`.`
1574
+ };
1575
+ }
1576
+ if (isUncolouredAction(button)) return {
1577
+ ...base,
1578
+ message: `Before @khsura/sui ${SUI_M2_FIXES_VERSION}, a text or icon button without \`color\` in the \`SSnackbar\` action keeps the page's dark text colour (about 1.3:1 on the dark snackbar), so the action is hard to read.`,
1579
+ fixHint: `Set a light colour: ${SNACKBAR_LIGHT_ACTION_COLOR_HINT}, or upgrade to ${SUI_M2_FIXES_VERSION} or later.`
1580
+ };
1581
+ };
1582
+ /**
1583
+ * A hex CSS colour below 4.5:1 on the snackbar always warns: the snackbar cannot adjust it. Before
1584
+ * `SUI_M2_FIXES_VERSION` a low-contrast preset colour or no colour at all warns too; from that version an action
1585
+ * without a colour takes the snackbar's light text colour and a preset colour uses a variant tuned to the snackbar.
1586
+ */
1222
1587
  var snackbarActionContrastRule = {
1223
1588
  id: RULE_SNACKBAR_ACTION_CONTRAST,
1224
- check: ({ element }) => {
1589
+ check: ({ element, apiVersion }) => {
1225
1590
  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
- });
1591
+ const hasSnackbarColorFix = isVersionAtLeast(apiVersion, SUI_M2_FIXES_VERSION);
1592
+ return slotFills(element).filter((fill) => staticArgument(fill.directive.arg) === SNACKBAR_ACTION_SLOT_NAME).flatMap((fill) => descendantElementsOf(fill.owner)).filter((descendant) => isComponentTag(descendant.tag, BUTTON_COMPONENT)).flatMap((button) => snackbarActionIssue(button, hasSnackbarColorFix) ?? []);
1237
1593
  }
1238
1594
  };
1239
1595
  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 ?? "");
@@ -1255,8 +1611,30 @@ var blockButtonsInRowRule = {
1255
1611
  }];
1256
1612
  }
1257
1613
  };
1614
+ /** A text field whose label and error line are rendered, so its box sits between them. */
1615
+ var isDetailedField = (element) => isOneOfComponentTags(element.tag, LABELLED_FIELD_COMPONENTS) && !isBooleanPropOn(element, "hide-details");
1616
+ var fieldButtonRowRule = {
1617
+ id: RULE_FIELD_BUTTON_ROW,
1618
+ target: RULE_TARGET_ANY_ELEMENT,
1619
+ check: ({ element }) => {
1620
+ if (isComponentTag(element.tag, "SFormRow") || !isFlexRow(element)) return [];
1621
+ const children = childElementsOf(element);
1622
+ const field = children.find(isDetailedField);
1623
+ const button = children.find((child) => isComponentTag(child.tag, BUTTON_COMPONENT));
1624
+ if (!field || !button) return [];
1625
+ return [{
1626
+ ...positionOf(button),
1627
+ rule: RULE_FIELD_BUTTON_ROW,
1628
+ severity: SEVERITY_WARNING,
1629
+ message: `\`${field.tag}\` and an \`SButton\` share a flex row: the field is a label, its box and an error line, so the button lines up with the label instead of the field box.`,
1630
+ fixHint: "Use `<SFormRow>` instead of the flex element (@khsura/sui 1.20.0+); it lines each button up with the field box. On an older version put `hide-details` on the field.",
1631
+ recipe: RECIPE_FILTER_BAR
1632
+ }];
1633
+ }
1634
+ };
1258
1635
  var cardTitleTextAlignRule = {
1259
1636
  id: RULE_CARD_TITLE_TEXT_ALIGN,
1637
+ fixedIn: SUI_M2_FIXES_VERSION,
1260
1638
  check: ({ element }) => {
1261
1639
  if (!isComponentTag(element.tag, "SCardTitle")) return [];
1262
1640
  return staticClassNames(element).flatMap((className) => {
@@ -1281,15 +1659,16 @@ var startsAsEmptyString = (modelPath, scriptSource) => {
1281
1659
  const escapedName = (modelPath.trim().split(MODEL_PATH_SEPARATOR).at(-1) ?? "").replaceAll(REGEX_SPECIAL_CHARACTERS, "\\$&");
1282
1660
  return EMPTY_STRING_INITIAL_PATTERNS.some((pattern) => new RegExp(pattern.replace(MODEL_NAME_PLACEHOLDER, escapedName)).test(scriptSource));
1283
1661
  };
1284
- /** Rules about behaviour and styling misuses that the component API alone cannot catch. */
1285
1662
  var behaviourRules = [
1286
1663
  nativeValidationInFormRule,
1287
1664
  hideDetailsHidesLabelRule,
1288
1665
  snackbarActionContrastRule,
1289
1666
  blockButtonsInRowRule,
1667
+ fieldButtonRowRule,
1290
1668
  cardTitleTextAlignRule,
1291
1669
  {
1292
1670
  id: RULE_DATE_PICKER_EMPTY_STRING,
1671
+ fixedIn: SUI_M2_FIXES_VERSION,
1293
1672
  check: ({ element, scriptSource }) => {
1294
1673
  const binding = isOneOfComponentTags(element.tag, DATE_PICKER_EMPTY_STRING_COMPONENTS) ? modelBinding(element) : void 0;
1295
1674
  const source = binding && isDirective(binding) ? expressionSource(binding) : binding?.value?.content;
@@ -1306,6 +1685,21 @@ var behaviourRules = [
1306
1685
  recipe: RECIPE_VALIDATED_FORM
1307
1686
  }];
1308
1687
  }
1688
+ },
1689
+ {
1690
+ id: RULE_FILL_HEIGHT_UNDER_APP,
1691
+ fixedIn: SUI_M2_FIXES_VERSION,
1692
+ check: ({ element }) => {
1693
+ if (!isComponentTag(element.tag, "SApp")) return [];
1694
+ return childElementsOf(element).filter((child) => staticClassNames(child).includes(HEIGHT_FILL_CLASS)).map((child) => ({
1695
+ ...positionOf(child),
1696
+ rule: RULE_FILL_HEIGHT_UNDER_APP,
1697
+ severity: SEVERITY_WARNING,
1698
+ message: `\`${HEIGHT_FILL_CLASS}\` on a direct child of \`SApp\` resolves to the content height before @khsura/sui 1.20.0 (SApp only has a min-height), so content centred inside it sticks to the top.`,
1699
+ fixHint: "Upgrade @khsura/sui to 1.20.0 or later, or add `style=\"min-height: 100dvh\"` to this child.",
1700
+ recipe: RECIPE_CENTERED_PAGE
1701
+ }));
1702
+ }
1309
1703
  }
1310
1704
  ];
1311
1705
  //#endregion
@@ -1489,13 +1883,14 @@ var unknownComponentRule = {
1489
1883
  id: RULE_UNKNOWN_COMPONENT,
1490
1884
  check: ({ element, lookup }) => {
1491
1885
  if (lookup.found) return [];
1492
- const suggestion = lookup.suggestions.length ? `Did you mean ${codeList(lookup.suggestions)}? ` : "";
1886
+ const suggestion = lookup.suggestions.length ? `${lookup.alias ? "Other close names" : "Did you mean"} ${codeList(lookup.suggestions)}? ` : "";
1887
+ const aliasAdvice = lookup.alias ? `${formatComponentAlias(lookup.alias)} ` : "";
1493
1888
  return [{
1494
1889
  ...positionOf(element),
1495
1890
  rule: RULE_UNKNOWN_COMPONENT,
1496
1891
  severity: SEVERITY_ERROR,
1497
- message: `\`${element.tag}\` is not a @khsura/sui component.`,
1498
- fixHint: `${suggestion}Check the exact names with ${LIST_COMPONENTS_TOOL_NAME}.`
1892
+ message: lookup.alias ? `\`${element.tag}\` is not a @khsura/sui component (it is a name from another UI library).` : `\`${element.tag}\` is not a @khsura/sui component.`,
1893
+ fixHint: `${aliasAdvice}${suggestion}Check the exact names with ${LIST_COMPONENTS_TOOL_NAME}.`
1499
1894
  }];
1500
1895
  }
1501
1896
  };
@@ -1597,16 +1992,19 @@ var byPosition = (left, right) => left.line - right.line || left.column - right.
1597
1992
  /** Validates SUI usage in a `.vue` SFC or template fragment against one `sui-api.json`. */
1598
1993
  var useTemplateValidatorService = (api, rules = templateRules) => {
1599
1994
  const catalog = useComponentCatalogService(api);
1995
+ const apiVersion = api.version;
1996
+ const activeRules = rules.filter((rule) => !rule.fixedIn || !isVersionAtLeast(apiVersion, rule.fixedIn));
1600
1997
  const validate = (code) => {
1601
1998
  const { root, errors, scriptSource } = parseVueTemplate(code);
1602
1999
  const ruleIssues = (root ? placedElements(root) : []).flatMap(({ element, ancestors }) => {
1603
- const applicableRules = rules.filter((rule) => appliesTo(rule, element.tag));
2000
+ const applicableRules = activeRules.filter((rule) => appliesTo(rule, element.tag));
1604
2001
  if (!applicableRules.length) return [];
1605
2002
  const context = {
1606
2003
  element,
1607
2004
  ancestors,
1608
2005
  lookup: catalog.findComponent(element.tag),
1609
2006
  api,
2007
+ apiVersion,
1610
2008
  scriptSource
1611
2009
  };
1612
2010
  return applicableRules.flatMap((rule) => rule.check(context));
@@ -1745,13 +2143,13 @@ var findInBundled = (resolved, name, loadBundledSuiApi) => {
1745
2143
  };
1746
2144
  var registerGetComponentApiTool = (server, loadSuiApi, loadBundledSuiApi) => {
1747
2145
  server.registerTool(GET_COMPONENT_API_TOOL_NAME, {
1748
- description: "Returns the props, slots and events of one @khsura/sui component as markdown, with usage notes for activator and layout-child components. Unknown names return the closest matches; a component that only a newer @khsura/sui has says so.",
2146
+ description: "Returns the props, slots and events of one @khsura/sui component as markdown, with usage notes for activator and layout-child components. Unknown names return the SUI equivalent of a name from another UI library (SCol, STextField, SBtn, …) and the closest matches; a component that only a newer @khsura/sui has says so.",
1749
2147
  inputSchema: getComponentApiInputSchema
1750
2148
  }, ({ name }) => withSuiApi(loadSuiApi, (resolved) => {
1751
2149
  const lookup = useComponentCatalogService(resolved.api).findComponent(name);
1752
2150
  if (lookup.found) return textResult(formatComponentApi(resolved, lookup.component));
1753
2151
  const newer = findInBundled(resolved, name, loadBundledSuiApi);
1754
- return newer ? textResult(formatComponentNeedsUpgrade(resolved, newer.bundled, newer.component.name), true) : textResult(formatUnknownComponent(resolved, name, lookup.suggestions), true);
2152
+ return newer ? textResult(formatComponentNeedsUpgrade(resolved, newer.bundled, newer.component.name), true) : textResult(formatUnknownComponent(resolved, name, lookup.suggestions, lookup.alias), true);
1755
2153
  }));
1756
2154
  };
1757
2155
  //#endregion
@@ -1799,7 +2197,7 @@ var registerValidateSuiTemplateTool = (server, loadSuiApi) => {
1799
2197
  //#region src/handlers/getRecipe.ts
1800
2198
  var registerGetRecipeTool = (server, recipeSourceOptions) => {
1801
2199
  server.registerTool(GET_RECIPE_TOOL_NAME, {
1802
- description: "Returns one tested @khsura/sui recipe: its notes (the rules it relies on) and the full copy-ready Vue SFC, plus a link to the live Storybook example. Names: app-shell, validated-form, activator-overlays, data-table, responsive-grid, theme-setup. Unknown names return the name list.",
2200
+ description: "Returns one tested @khsura/sui recipe: its notes (the rules it relies on) and the full copy-ready Vue SFC, plus a link to the live Storybook example. Names: app-shell, validated-form, activator-overlays, data-table, responsive-grid, theme-setup, filter-bar, centered-page. Unknown names return the name list.",
1803
2201
  inputSchema: getRecipeInputSchema
1804
2202
  }, ({ name }) => {
1805
2203
  try {
@@ -1813,7 +2211,7 @@ var registerGetRecipeTool = (server, recipeSourceOptions) => {
1813
2211
  //#endregion
1814
2212
  //#region src/handlers/listRecipes.ts
1815
2213
  var registerListRecipesTool = (server, recipeSourceOptions) => {
1816
- server.registerTool(LIST_RECIPES_TOOL_NAME, { description: "Lists the tested, copy-ready @khsura/sui recipes (app shell, validated form, dialog/menu/tooltip/snackbar activators, data table, responsive grid, theme and dark mode) with when to use each and the name to pass to get_recipe. Start a page from a recipe instead of composing SUI components from scratch." }, () => {
2214
+ server.registerTool(LIST_RECIPES_TOOL_NAME, { description: "Lists the tested, copy-ready @khsura/sui recipes (app shell, validated form, dialog/menu/tooltip/snackbar activators, data table, responsive grid, theme and dark mode, filter bar, centered login-style page) with when to use each and the name to pass to get_recipe. Start a page from a recipe instead of composing SUI components from scratch." }, () => {
1817
2215
  try {
1818
2216
  return textResult(formatRecipeList(useRecipeCatalogService(recipeSourceOptions).listRecipes()));
1819
2217
  } catch (error) {