@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.
package/dist/index.js CHANGED
@@ -43,6 +43,7 @@ var LAYOUT_CHILD_NOTE = "**Layout child:** render it inside an `SLayout name=\"x
43
43
  var FAMILY_PURPOSES = {
44
44
  core: "core UI building block",
45
45
  layout: "app shell layout (SLayout and its named regions)",
46
+ avatar: "user avatar (image, initials or icon) or an overlapping group of them",
46
47
  badge: "status badge overlay",
47
48
  calendar: "calendar view",
48
49
  cards: "card container or one of its sections",
@@ -166,12 +167,39 @@ var RULE_SNACKBAR_ACTION_CONTRAST = "snackbar-action-contrast";
166
167
  var RULE_BLOCK_BUTTONS_IN_ROW = "block-buttons-in-row";
167
168
  var RULE_CARD_TITLE_TEXT_ALIGN = "card-title-text-align";
168
169
  var RULE_DATE_PICKER_EMPTY_STRING = "date-picker-empty-string";
170
+ var RULE_FIELD_BUTTON_ROW = "field-button-row";
171
+ var RULE_FILL_HEIGHT_UNDER_APP = "fill-height-under-app";
172
+ var RULE_AVATAR_IMAGE_IN_SLOT = "avatar-image-in-slot";
173
+ var RULE_AVATAR_TEXT_NOT_INITIALS = "avatar-text-not-initials";
174
+ var RULE_AVATAR_GROUP_CHILD = "avatar-group-child";
175
+ var RULE_PAGINATION_LENGTH_ROWS = "pagination-length-rows";
176
+ var RULE_PAGINATION_ZERO_BASED = "pagination-zero-based";
177
+ var RULE_SKELETON_LOADER_UNKNOWN_PRESET = "skeleton-loader-unknown-preset";
178
+ var RULE_SKELETON_LOADER_NEVER_HIDES = "skeleton-loader-never-hides";
179
+ var RULE_HIDDEN_LABEL_NO_VISIBLE_NAME = "hidden-label-no-visible-name";
180
+ var RULE_EMPTY_STATE_ACTION_EVENT = "empty-state-action-event";
181
+ var RULE_EMPTY_STATE_ACTION_WITHOUT_LISTENER = "empty-state-action-without-listener";
182
+ var RULE_EMPTY_STATE_OUTSIDE_NO_DATA_SLOT = "empty-state-outside-no-data-slot";
183
+ var RULE_NUMBER_INPUT_PREFERRED = "number-input-preferred";
184
+ var RULE_RAW_FILE_INPUT = "raw-file-input";
185
+ var RULE_FILE_INPUT_CHANGE_EVENT = "file-input-change-event";
186
+ var RULE_TABS_IN_SLIDE_GROUP = "tabs-in-slide-group";
187
+ var RULE_ROW_INSET_FROM_TEXT = "row-inset-from-text";
188
+ /**
189
+ * The first `@khsura/sui` release with the M2 hardening fixes (SForm `novalidate`, SCheckbox label with
190
+ * `hide-details`, `''` as "no date", snackbar action colour, SCardTitle `s_textAlign__*`). Rules for
191
+ * those behaviours set it as `fixedIn`, so they only warn for projects on an older version.
192
+ */
193
+ var SUI_M2_FIXES_VERSION = "1.20.0";
169
194
  var RULE_TARGET_ANY_ELEMENT = "any-element";
170
195
  /** Recipe names an issue points to; the recipes are published under these exact names. */
171
196
  var RECIPE_APP_SHELL = "app-shell";
172
197
  var RECIPE_VALIDATED_FORM = "validated-form";
173
198
  var RECIPE_ACTIVATOR_OVERLAYS = "activator-overlays";
174
199
  var RECIPE_RESPONSIVE_GRID = "responsive-grid";
200
+ var RECIPE_FILTER_BAR = "filter-bar";
201
+ var RECIPE_CENTERED_PAGE = "centered-page";
202
+ var RECIPE_TABBED_SECTIONS = "tabbed-sections";
175
203
  var ACTIVATOR_SLOT_NAME = "activator";
176
204
  var ACTIVATOR_ATTRS_KEY = "attrs";
177
205
  /** Overlays whose `#activator` slot passes `{ on, attrs }` for the caller to bind. */
@@ -182,10 +210,13 @@ var SLOT_PROP_ACTIVATOR_COMPONENTS = [
182
210
  ];
183
211
  /** STooltip wraps the activator in its own listening element and passes no slot props. */
184
212
  var SLOTLESS_ACTIVATOR_COMPONENTS = ["STooltip"];
213
+ /** `height: 100%`; a direct child of SApp with it grows into SApp's flex column (since 1.20.0). */
214
+ var HEIGHT_FILL_CLASS = "s_height--fill";
185
215
  var LAYOUT_COMPONENT = "SLayout";
186
216
  var LAYOUT_NAME_ATTRIBUTE = "name";
187
217
  var FORM_COMPONENT = "SForm";
188
218
  var RULES_ATTRIBUTE = "rules";
219
+ var BUTTON_COMPONENT = "SButton";
189
220
  var ACCESSIBLE_LABEL_ATTRIBUTES = [
190
221
  "aria-label",
191
222
  "aria-labelledby",
@@ -212,13 +243,30 @@ var NATIVE_VALIDATING_INPUT_TYPES = [
212
243
  "url",
213
244
  "number"
214
245
  ];
246
+ /** The numeric field (since 1.21.0); rules recommend it only when the resolved `sui-api.json` lists it. */
247
+ var NUMBER_INPUT_COMPONENT = "SNumberInput";
248
+ /** SInput's number-only props and what SNumberInput uses instead, for the migration hint. */
249
+ var NUMBER_INPUT_PROP_REPLACEMENTS = /* @__PURE__ */ new Map([
250
+ ["allow-decimal", "`:precision=\"2\"` (decimal places; whole numbers by default)"],
251
+ ["positive", "`:min` (`:min=\"1\"` for whole numbers above 0)"],
252
+ ["use-previous-value-when-exceeded", "nothing: SNumberInput clamps to `min` / `max` on blur"],
253
+ ["inputmode", "nothing: SNumberInput picks `numeric` or `decimal` from `min` and `precision`"]
254
+ ]);
215
255
  var HIDE_DETAILS_ATTRIBUTE = "hide-details";
256
+ var LABEL_ATTRIBUTE = "label";
257
+ var PLACEHOLDER_ATTRIBUTE = "placeholder";
258
+ var LABEL_WORD_PATTERN = /[\p{L}\p{N}]+/gu;
216
259
  /** Inputs whose only visible text is the `label` prop, which `hide-details` hides as well. */
217
260
  var HIDE_DETAILS_LABEL_COMPONENTS = ["SCheckbox"];
218
261
  var SNACKBAR_ACTION_SLOT_NAME = "action";
219
262
  var COLOR_ATTRIBUTE = "color";
220
263
  var VARIANT_ATTRIBUTE = "variant";
221
- /** Preset colours below 4.5:1 as text on the default `#424242` snackbar (primary is 2.18:1). */
264
+ /** Action variants that, before the M2 fix, kept the page's dark text colour on the dark snackbar when no `color` was set. */
265
+ var SNACKBAR_UNCOLOURED_ACTION_VARIANTS = ["text", "icon"];
266
+ /**
267
+ * Preset colours below 4.5:1 as text on the default `#424242` snackbar before `SUI_M2_FIXES_VERSION` (primary is
268
+ * 2.18:1). From that version a preset text colour inside the snackbar uses a variant tuned to the snackbar.
269
+ */
222
270
  var SNACKBAR_UNREADABLE_PRESET_COLORS = [
223
271
  "primary",
224
272
  "secondary",
@@ -226,9 +274,38 @@ var SNACKBAR_UNREADABLE_PRESET_COLORS = [
226
274
  "info",
227
275
  "error"
228
276
  ];
229
- var SNACKBAR_READABLE_ACTION_COLOR = "warning";
277
+ /** The theme's default `snackbar` colour, dark in both themes: CSS-colour actions are measured against it. */
278
+ var SNACKBAR_DEFAULT_BACKGROUND = "#424242";
279
+ var SNACKBAR_LIGHT_ACTION_COLOR_HINT = `\`color="warning"\` or a CSS colour such as \`color="#ffffff"\``;
230
280
  /** Components whose root is a `display: flex` row. */
231
281
  var FLEX_ROW_COMPONENTS = ["SCardActions"];
282
+ /** Text fields that render a label above their box and an error line under it. */
283
+ var LABELLED_FIELD_COMPONENTS = [
284
+ "SInput",
285
+ "SNumberInput",
286
+ "SSelect",
287
+ "SDatePickerInput",
288
+ "SAutocomplete",
289
+ "STextarea",
290
+ "SFileInput"
291
+ ];
292
+ var ROW_NO_OUTER_GUTTERS_PROP = "no-outer-gutters";
293
+ /** Native text elements whose left edge a grid beside them should line up with. */
294
+ var ROW_TEXT_SIBLING_TAGS = [
295
+ "h1",
296
+ "h2",
297
+ "h3",
298
+ "h4",
299
+ "h5",
300
+ "h6",
301
+ "p"
302
+ ];
303
+ /** Components that sit flush with the content edge, like text, so a grid beside them should line up too. */
304
+ var ROW_FLUSH_SIBLING_COMPONENTS = ["SBreadcrumbs"];
305
+ /** Wrappers that add no padding: a row inside one is still beside the wrapper's siblings. */
306
+ var ROW_TRANSPARENT_WRAPPERS = ["SForm", "form"];
307
+ /** Horizontal padding / margin utility classes: a text sibling carrying one is inset on purpose. */
308
+ var HORIZONTAL_INSET_CLASS_PATTERN = /^s_(?:pa|px|pl|ps|ma|mx|ml|ms)__/;
232
309
  /** `s_display__flex`, `s_display--md__inlineFlex`: the utility classes that make an element a flex row. */
233
310
  var FLEX_DISPLAY_CLASS_PATTERN = /^s_display(?:--[a-z]+)?__(?:flex|inlineFlex)$/;
234
311
  var FLEX_DISPLAY_STYLE_PATTERN = /(?:^|;)\s*display\s*:\s*(?:inline-)?flex\b/;
@@ -254,6 +331,72 @@ var MODEL_NAME_PLACEHOLDER = "__name__";
254
331
  /** `from: ''` in an object literal, or `startDate = ref('')` / `ref<string>("")`. */
255
332
  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*\\)`];
256
333
  var ACTIVATOR_BINDING_FIX = "Write `#activator=\"{ on, attrs }\"` and put both `v-on=\"on\"` and `v-bind=\"attrs\"` on the activator's root element.";
334
+ var AVATAR_TEXT_ATTRIBUTE = "text";
335
+ /** Elements that put a picture in an avatar's slot instead of its `image` prop. */
336
+ var AVATAR_SLOT_IMAGE_TAGS = ["img", "SImage"];
337
+ var WHITESPACE_CHARACTER_PATTERN = /\s/;
338
+ /** Children an SAvatarGroup accepts besides SAvatar: a `<slot>` that passes avatars through. */
339
+ var AVATAR_GROUP_PASSTHROUGH_TAGS = ["slot"];
340
+ var PAGINATION_LENGTH_ATTRIBUTE = "length";
341
+ /** A `:length` that counts rows, not pages: `items.length`, `rows.size`, `totalItems`, `itemsCount`, … */
342
+ var PAGINATION_ROW_COUNT_EXPRESSION = /(?:\.(?:length|size)|^(?:total|totalItems|totalRows|totalCount|totalRecords|itemsCount|itemCount|rowCount|rowsCount))\s*$/;
343
+ /** Signs that the expression already divides rows into pages: `Math.ceil(total / perPage)`, `total / 20`. */
344
+ var PAGINATION_PAGE_MATH_EXPRESSION = /\/|\bceil\b/;
345
+ /** A 0-based model, such as STable's `pageIndex`, given to SPagination's 1-based `v-model`. */
346
+ var PAGINATION_ZERO_BASED_MODEL = /index$/i;
347
+ var SKELETON_LOADER_TYPE_ATTRIBUTE = "type";
348
+ var SKELETON_LOADER_LOADING_ATTRIBUTE = "loading";
349
+ /** The presets SSkeletonLoader draws. The `type` prop is a plain string, so sui-api.json cannot list them. */
350
+ var SKELETON_LOADER_PRESETS = [
351
+ "text",
352
+ "heading",
353
+ "avatar",
354
+ "button",
355
+ "image",
356
+ "card",
357
+ "list-item",
358
+ "list-item-avatar",
359
+ "table-row",
360
+ "table"
361
+ ];
362
+ /** Vuetify VSkeletonLoader presets that SUI does not have, with the SUI `type` that draws the same thing. */
363
+ var SKELETON_LOADER_VUETIFY_PRESETS = {
364
+ paragraph: "text@3",
365
+ sentences: "text@2",
366
+ subtitle: "text",
367
+ article: "heading, text@3",
368
+ chip: "button",
369
+ actions: "button@2",
370
+ "list-item-two-line": "list-item-avatar",
371
+ "list-item-three-line": "list-item-avatar",
372
+ "list-item-avatar-two-line": "list-item-avatar",
373
+ "list-item-avatar-three-line": "list-item-avatar",
374
+ "card-avatar": "card",
375
+ "table-heading": "heading",
376
+ "table-thead": "table-row",
377
+ "table-tbody": "table-row@5",
378
+ "table-tfoot": "table-row"
379
+ };
380
+ var EMPTY_STATE_COMPONENT = "SEmptyState";
381
+ var EMPTY_STATE_ACTION_TEXT_ATTRIBUTE = "action-text";
382
+ /** The slot that replaces SEmptyState's built-in button. */
383
+ var EMPTY_STATE_ACTIONS_SLOT = "actions";
384
+ /** Listeners AI code writes for the action button: Vuetify's `click:action`, or a plain `click` on the whole block. */
385
+ var EMPTY_STATE_WRONG_ACTION_EVENTS = ["click:action", "click"];
386
+ /** Components whose no-data state takes an SEmptyState through the `noData` slot, never the default slot. */
387
+ var NO_DATA_SLOT_COMPONENTS = [
388
+ "STable",
389
+ "SSelect",
390
+ "SAutocomplete"
391
+ ];
392
+ var NO_DATA_SLOT_NAME = "noData";
393
+ /** A handler that opens a file input's picker through its template ref: `fileInput?.click()`, `$refs.file.click()`. */
394
+ var PICKER_CLICK_CALL_PATTERN = /[\w$.?]*\.click\(\s*\)/g;
395
+ /** The DOM event access AI code writes for a native file input's `change`: `$event.target.files`, `e.target`. */
396
+ var NATIVE_CHANGE_EVENT_ACCESS_PATTERN = /\.target\b|\$event\.files\b/;
397
+ /** Splits a member path such as `fileInput.value?.click` into its names. */
398
+ var MEMBER_PATH_SEPARATOR_PATTERN = /\?\.|\./;
399
+ var FILE_INPUT_EXAMPLE = "<SFileInput v-model=\"files\" label=\"Workbook\" accept=\".csv,.xlsx\" :rules=\"getFileInputRules({ maxSize: 5 * 1024 * 1024, accept: '.csv,.xlsx' })\" />";
257
400
  //#endregion
258
401
  //#region src/constants/recipes.ts
259
402
  /** Published recipe names; `validate_sui_template` issues point to these exact names. */
@@ -263,7 +406,10 @@ var RECIPE_NAMES = [
263
406
  "activator-overlays",
264
407
  "data-table",
265
408
  "responsive-grid",
266
- "theme-setup"
409
+ "theme-setup",
410
+ "filter-bar",
411
+ "centered-page",
412
+ "tabbed-sections"
267
413
  ];
268
414
  var RECIPES_DIRNAME = "recipes";
269
415
  /** Repo-relative folder that holds the recipe sources (Storybook renders the same files). */
@@ -317,6 +463,192 @@ var CONFIG_STATUS_UNCHANGED = "unchanged";
317
463
  var CONFIG_ACTION_WRITE = "write";
318
464
  var CONFIG_ACTION_PRINT = "print";
319
465
  //#endregion
466
+ //#region src/constants/componentAliases.ts
467
+ /**
468
+ * Component names from Vuetify, Quasar, Element and similar libraries that are not in @khsura/sui,
469
+ * with the SUI component(s) to use instead and a short hint. An empty `suiNames` means SUI has no
470
+ * equivalent yet. Keys are matched like component names (case, `-` and the `S` prefix are ignored),
471
+ * and an alias is never used when the name is a real component in the resolved `sui-api.json`.
472
+ */
473
+ var COMPONENT_ALIASES = {
474
+ SCol: {
475
+ suiNames: ["SColumn"],
476
+ hint: "The grid column is `SColumn`, inside an `SRow` (`:cols`, `:md`, … set its width)."
477
+ },
478
+ SCols: {
479
+ suiNames: ["SColumn"],
480
+ hint: "The grid column is `SColumn`, inside an `SRow`."
481
+ },
482
+ SColumns: {
483
+ suiNames: ["SColumn"],
484
+ hint: "The grid column is `SColumn`, one per column, inside an `SRow`."
485
+ },
486
+ STextField: {
487
+ suiNames: ["SInput"],
488
+ hint: "The text field is `SInput` (`label`, `type`, `rules`, `v-model`)."
489
+ },
490
+ STextInput: {
491
+ suiNames: ["SInput"],
492
+ hint: "The text field is `SInput` (`label`, `type`, `rules`, `v-model`)."
493
+ },
494
+ SInputText: {
495
+ suiNames: ["SInput"],
496
+ hint: "The text field is `SInput`."
497
+ },
498
+ SBtn: {
499
+ suiNames: ["SButton"],
500
+ hint: "The button is `SButton` (`variant`, `color`, `size`)."
501
+ },
502
+ SIconButton: {
503
+ suiNames: ["SButton"],
504
+ hint: "An icon-only button is `<SButton variant=\"icon\" aria-label=\"…\">` with an `SIcon` inside."
505
+ },
506
+ SBtnToggle: {
507
+ suiNames: ["SToggleButtonGroup", "SToggleButton"],
508
+ hint: "Use `SToggleButtonGroup` with `SToggleButton` children."
509
+ },
510
+ SDataTable: {
511
+ suiNames: ["STable"],
512
+ hint: "The data table is `STable` (`headers`, `items`, `item.<key>` slots)."
513
+ },
514
+ SSimpleTable: {
515
+ suiNames: ["STable"],
516
+ hint: "The table is `STable`."
517
+ },
518
+ STabsWindow: {
519
+ suiNames: ["SWindow"],
520
+ hint: "Tab content is an `SWindow` bound to the same `v-model` as `STabs`, with one `SWindowItem` per tab."
521
+ },
522
+ STabsWindowItem: {
523
+ suiNames: ["SWindowItem"],
524
+ hint: "Each tab panel is an `SWindowItem` inside an `SWindow`."
525
+ },
526
+ STabsItems: {
527
+ suiNames: ["SWindow"],
528
+ hint: "Tab content is an `SWindow` bound to the same `v-model` as `STabs`."
529
+ },
530
+ STabItem: {
531
+ suiNames: ["SWindowItem"],
532
+ hint: "Each tab panel is an `SWindowItem` inside an `SWindow`; the tab itself is `STab`."
533
+ },
534
+ STabPanels: {
535
+ suiNames: ["SWindow"],
536
+ hint: "Tab content is an `SWindow` bound to the same `v-model` as `STabs`."
537
+ },
538
+ STabPanel: {
539
+ suiNames: ["SWindowItem"],
540
+ hint: "Each tab panel is an `SWindowItem` inside an `SWindow`."
541
+ },
542
+ STabPane: {
543
+ suiNames: ["STab", "SWindowItem"],
544
+ hint: "Put an `STab` in `STabs` and its content in an `SWindowItem` inside an `SWindow`."
545
+ },
546
+ SModal: {
547
+ suiNames: ["SDialog"],
548
+ hint: "The modal is `SDialog`, opened from its `#activator` slot or a `v-model`."
549
+ },
550
+ SDrawer: {
551
+ suiNames: ["SNavigationDrawer"],
552
+ hint: "The side drawer is `SNavigationDrawer`, a child of `SLayout`."
553
+ },
554
+ SHeader: {
555
+ suiNames: ["SAppBar"],
556
+ hint: "The page header bar is `SAppBar`, a child of `SLayout`."
557
+ },
558
+ SPage: {
559
+ suiNames: ["SMain"],
560
+ hint: "The page content area is `SMain`, a child of `SLayout`."
561
+ },
562
+ SContent: {
563
+ suiNames: ["SMain"],
564
+ hint: "The page content area is `SMain`, a child of `SLayout`."
565
+ },
566
+ SToast: {
567
+ suiNames: ["SSnackbar"],
568
+ hint: "The toast is `SSnackbar` (`v-model`, `timeout`, `#action` slot)."
569
+ },
570
+ SNotification: {
571
+ suiNames: ["SSnackbar"],
572
+ hint: "A transient message is `SSnackbar`; a static one is `SAlert`."
573
+ },
574
+ SDropdown: {
575
+ suiNames: ["SMenu"],
576
+ hint: "The dropdown is `SMenu`, opened from its `#activator` slot."
577
+ },
578
+ SSpinner: {
579
+ suiNames: ["SProgressCircular"],
580
+ hint: "The spinner is `<SProgressCircular indeterminate />`."
581
+ },
582
+ SProgressBar: {
583
+ suiNames: ["SProgressLinear"],
584
+ hint: "The progress bar is `SProgressLinear`."
585
+ },
586
+ SToggle: {
587
+ suiNames: ["SSwitch"],
588
+ hint: "The on/off toggle is `SSwitch`."
589
+ },
590
+ SCombobox: {
591
+ suiNames: ["SAutocomplete"],
592
+ hint: "A searchable select is `SAutocomplete`."
593
+ },
594
+ SImg: {
595
+ suiNames: ["SImage"],
596
+ hint: "The image is `SImage`."
597
+ },
598
+ SCardHeader: {
599
+ suiNames: ["SCardTitle"],
600
+ hint: "The card heading is `SCardTitle` (with `SCardSubtitle` below it)."
601
+ },
602
+ SCardBody: {
603
+ suiNames: ["SCardText"],
604
+ hint: "The card body is `SCardText`."
605
+ },
606
+ SCardContent: {
607
+ suiNames: ["SCardText"],
608
+ hint: "The card body is `SCardText`."
609
+ },
610
+ SCardSection: {
611
+ suiNames: ["SCardText"],
612
+ hint: "The card body is `SCardText`."
613
+ },
614
+ SCardFooter: {
615
+ suiNames: ["SCardActions"],
616
+ hint: "The card footer with buttons is `SCardActions`."
617
+ },
618
+ SExpansionPanelTitle: {
619
+ suiNames: ["SExpansionPanelHeader"],
620
+ hint: "The clickable row of a panel is `SExpansionPanelHeader`."
621
+ },
622
+ SExpansionPanelText: {
623
+ suiNames: ["SExpansionPanelContent"],
624
+ hint: "The body of a panel is `SExpansionPanelContent`."
625
+ },
626
+ SAccordion: {
627
+ suiNames: ["SExpansionPanels"],
628
+ hint: "The accordion is `SExpansionPanels` with `SExpansionPanel` children."
629
+ },
630
+ SStepperItem: {
631
+ suiNames: ["SStepperStep"],
632
+ hint: "Each step is an `SStepperStep` inside `SStepper`."
633
+ }
634
+ };
635
+ //#endregion
636
+ //#region src/constants/semver.ts
637
+ /** `1.20.0`, `v1.20.0`, `1.20.0-beta.1`: major, minor, patch and an optional pre-release tag. */
638
+ var SEMVER_PATTERN = /^\s*v?(\d+)\.(\d+)\.(\d+)(?:-([\w.-]+))?(?:\+[\w.-]+)?\s*$/;
639
+ //#endregion
640
+ //#region src/constants/contrast.ts
641
+ /** `#rgb` or `#rrggbb` (case-insensitive): the hex digits. */
642
+ var HEX_COLOR_PATTERN = /^#([\da-f]{3}|[\da-f]{6})$/i;
643
+ var SRGB_LINEAR_DIVISOR = 12.92;
644
+ var SRGB_GAMMA_OFFSET = .055;
645
+ var SRGB_GAMMA_DIVISOR = 1.055;
646
+ var SRGB_GAMMA = 2.4;
647
+ var LUMINANCE_WEIGHT_RED = .2126;
648
+ var LUMINANCE_WEIGHT_GREEN = .7152;
649
+ var LUMINANCE_WEIGHT_BLUE = .0722;
650
+ var CONTRAST_FLARE = .05;
651
+ //#endregion
320
652
  //#region src/schemas/componentTools.schema.ts
321
653
  var getComponentApiInputSchema = z.object({ name: z.string().trim().min(1).describe("Component name: `SButton`, `s-button` or `button` (case-insensitive).") });
322
654
  //#endregion
@@ -549,6 +881,163 @@ var mergeMcpServerEntry = ({ existingText, serversKey, entryName, entry }) => {
549
881
  /** The snippet a user pastes into a config file they edit by hand. */
550
882
  var mcpServerSnippet = ({ serversKey, entryName, entry }) => serializeJson({ [serversKey]: { [entryName]: entry } });
551
883
  //#endregion
884
+ //#region src/lib/semver.ts
885
+ var parseVersion = (version) => {
886
+ const match = SEMVER_PATTERN.exec(version);
887
+ if (!match) return;
888
+ const [, major, minor, patch, preRelease] = match;
889
+ return {
890
+ core: [
891
+ Number(major),
892
+ Number(minor),
893
+ Number(patch)
894
+ ],
895
+ preRelease
896
+ };
897
+ };
898
+ /**
899
+ * Orders two semver strings: negative when `left` is older, positive when newer, 0 when equal.
900
+ * A pre-release sorts before its release (`1.20.0-beta.1` < `1.20.0`); pre-release tags compare as text.
901
+ * Returns `undefined` when either string is not a semver version.
902
+ */
903
+ var compareVersions = (left, right) => {
904
+ const leftVersion = parseVersion(left);
905
+ const rightVersion = parseVersion(right);
906
+ if (!leftVersion || !rightVersion) return;
907
+ const coreDifference = leftVersion.core.map((part, index) => part - rightVersion.core[index]).find((difference) => difference !== 0);
908
+ if (coreDifference !== void 0) return coreDifference;
909
+ if (leftVersion.preRelease === rightVersion.preRelease) return 0;
910
+ if (leftVersion.preRelease === void 0 || rightVersion.preRelease === void 0) return leftVersion.preRelease === void 0 ? 1 : -1;
911
+ return leftVersion.preRelease.localeCompare(rightVersion.preRelease);
912
+ };
913
+ /** True when `version` is `minimum` or newer; false when either is not a semver version. */
914
+ var isVersionAtLeast = (version, minimum) => (compareVersions(version, minimum) ?? -1) >= 0;
915
+ //#endregion
916
+ //#region src/lib/contrast.ts
917
+ /** `#rgb` / `#rrggbb` as `[r, g, b]` (0-255), or `undefined` for anything else (named colours, `rgb()`, bindings). */
918
+ var parseHexColor = (color) => {
919
+ const match = HEX_COLOR_PATTERN.exec(color.trim());
920
+ if (!match) return;
921
+ const [red, green, blue] = (match[1].length === 3 ? [...match[1]].map((digit) => digit + digit) : [
922
+ match[1].slice(0, 2),
923
+ match[1].slice(2, 4),
924
+ match[1].slice(4, 6)
925
+ ]).map((pair) => Number.parseInt(pair, 16));
926
+ return [
927
+ red,
928
+ green,
929
+ blue
930
+ ];
931
+ };
932
+ var linearizeChannel = (channel) => {
933
+ const ratio = channel / 255;
934
+ return ratio <= .04045 ? ratio / SRGB_LINEAR_DIVISOR : ((ratio + SRGB_GAMMA_OFFSET) / SRGB_GAMMA_DIVISOR) ** SRGB_GAMMA;
935
+ };
936
+ var relativeLuminance = ([red, green, blue]) => LUMINANCE_WEIGHT_RED * linearizeChannel(red) + LUMINANCE_WEIGHT_GREEN * linearizeChannel(green) + LUMINANCE_WEIGHT_BLUE * linearizeChannel(blue);
937
+ /** WCAG 2.x contrast ratio (1 to 21) between two hex colours, or `undefined` when either is not `#rgb`/`#rrggbb`. */
938
+ var getHexContrastRatio = (first, second) => {
939
+ const firstRgb = parseHexColor(first);
940
+ const secondRgb = parseHexColor(second);
941
+ if (!firstRgb || !secondRgb) return;
942
+ const firstLuminance = relativeLuminance(firstRgb);
943
+ const secondLuminance = relativeLuminance(secondRgb);
944
+ return (Math.max(firstLuminance, secondLuminance) + CONTRAST_FLARE) / (Math.min(firstLuminance, secondLuminance) + CONTRAST_FLARE);
945
+ };
946
+ //#endregion
947
+ //#region src/utils/componentName.ts
948
+ var NAME_SEPARATORS = /[\s_-]/g;
949
+ /** Lowercase key with separators removed: `SButton`, `s-button` and `sbutton` all map to `sbutton`. */
950
+ var toComponentKey = (name) => name.trim().toLowerCase().replaceAll(NAME_SEPARATORS, "");
951
+ /** Keys a query may refer to, most specific first: as typed, then with the `S` prefix added. */
952
+ var candidateComponentKeys = (query) => {
953
+ const queryKey = toComponentKey(query);
954
+ return [queryKey, `s${queryKey}`];
955
+ };
956
+ /** `SNavigationDrawer` → `Navigation drawer`. */
957
+ var humanizeComponentName = (name) => {
958
+ const sentence = name.replace(/^S(?=[A-Z])/, "").split(/(?=[A-Z])/).map((word) => word.toLowerCase()).join(" ");
959
+ return sentence.charAt(0).toUpperCase() + sentence.slice(1);
960
+ };
961
+ /** True for tags the validator treats as SUI components: `SButton` or `s-button`. Native tags such as `select` never match. */
962
+ var isSuiComponentTag = (tag) => SUI_PASCAL_TAG_PATTERN.test(tag) || SUI_KEBAB_TAG_PATTERN.test(tag);
963
+ /**
964
+ * True when the resolved `sui-api.json` lists the component, i.e. the installed `@khsura/sui` release has it. Rules
965
+ * that recommend a newer component check this, so a project on an older release is never told to use one it lacks.
966
+ */
967
+ var hasSuiComponent = (api, name) => api.components.some((component) => component.name === name);
968
+ //#endregion
969
+ //#region src/utils/templateAst.ts
970
+ var positionOf = (node) => ({
971
+ line: node.loc.start.line,
972
+ column: node.loc.start.column
973
+ });
974
+ var codeList = (names) => names.map((name) => `\`${name}\``).join(", ");
975
+ /** The argument of a directive when it is a static name (`:size`, `#header`); `undefined` for none or `[dynamic]`. */
976
+ var staticArgument = (argument) => argument?.type === NodeTypes.SIMPLE_EXPRESSION && argument.isStatic ? argument.content : void 0;
977
+ /** The source of a directive's value (`on` in `v-on="on"`), trimmed; `undefined` when it has none. */
978
+ var expressionSource = (directive) => {
979
+ const source = directive.exp?.loc.source.trim() ?? "";
980
+ return source.length ? source : void 0;
981
+ };
982
+ var isDirective = (prop) => prop.type === NodeTypes.DIRECTIVE;
983
+ /** True when `tag` names `componentName` in either case style: `SAppBar`, `s-app-bar`. */
984
+ var isComponentTag = (tag, componentName) => toComponentKey(tag) === toComponentKey(componentName);
985
+ var isOneOfComponentTags = (tag, componentNames) => componentNames.some((componentName) => isComponentTag(tag, componentName));
986
+ var childElementsOf = (element) => element.children.filter((child) => child.type === NodeTypes.ELEMENT);
987
+ /** `name="x"` or `:name="x"` / `v-bind:name="x"` on `element`; a quoted literal binding still has a static value. */
988
+ var findAttribute = (element, name) => {
989
+ for (const prop of element.props) {
990
+ if (!isDirective(prop)) {
991
+ if (prop.name === name) return {
992
+ node: prop,
993
+ staticValue: prop.value?.content,
994
+ isBound: false
995
+ };
996
+ continue;
997
+ }
998
+ if (prop.name === "bind" && staticArgument(prop.arg) === name) {
999
+ const literal = STRING_LITERAL_EXPRESSION.exec(expressionSource(prop) ?? "");
1000
+ return {
1001
+ node: prop,
1002
+ staticValue: literal?.[2],
1003
+ isBound: !literal
1004
+ };
1005
+ }
1006
+ }
1007
+ };
1008
+ /** `v-bind="object"`: it may carry any attribute, so presence checks cannot be sure. */
1009
+ var hasObjectSpread = (element) => element.props.some((prop) => isDirective(prop) && prop.name === "bind" && !prop.arg);
1010
+ /** Slots `element` fills: `v-slot` / `#name` on the element itself or on its direct `<template>` children. */
1011
+ var slotFills = (element) => {
1012
+ return [element, ...childElementsOf(element).filter((child) => child.tag === TEMPLATE_TAG)].flatMap((owner) => owner.props.filter(isDirective).filter((directive) => directive.name === DIRECTIVE_SLOT).map((directive) => ({
1013
+ directive,
1014
+ owner
1015
+ })));
1016
+ };
1017
+ var slotDirectives = (element) => slotFills(element).map((fill) => fill.directive);
1018
+ /** True when `element` has content between its tags (elements, text or `{{ }}`), not counting comments. */
1019
+ var hasChildContent = (element) => element.children.some((child) => child.type !== NodeTypes.COMMENT && (child.type !== NodeTypes.TEXT || child.content.trim() !== ""));
1020
+ /** Every element below `element`, depth first. */
1021
+ var descendantElementsOf = (element) => childElementsOf(element).flatMap((child) => [child, ...descendantElementsOf(child)]);
1022
+ /** A prop written in either case style: `hide-details`, `hideDetails`, `:hide-details`. */
1023
+ var findPropAttribute = (element, kebabName) => findAttribute(element, kebabName) ?? findAttribute(element, toCamelCase(kebabName));
1024
+ /** A boolean prop that is set and not statically `false` (`block`, `:block="true"`, `:block="isWide"`). */
1025
+ var isBooleanPropOn = (element, kebabName) => {
1026
+ const attribute = findPropAttribute(element, kebabName);
1027
+ if (!attribute) return false;
1028
+ return !isDirective(attribute.node) || expressionSource(attribute.node) !== "false";
1029
+ };
1030
+ /** The static `class` tokens of `element` (a plain `class` or a string-literal `:class`); bound classes are unknown. */
1031
+ var staticClassNames = (element) => element.props.flatMap((prop) => {
1032
+ if (!isDirective(prop)) return prop.name === "class" ? [prop.value?.content ?? ""] : [];
1033
+ const literal = prop.name === "bind" && staticArgument(prop.arg) === "class" ? STRING_LITERAL_EXPRESSION.exec(expressionSource(prop) ?? "") : null;
1034
+ return literal ? [literal[2]] : [];
1035
+ }).flatMap((value) => value.split(WHITESPACE_PATTERN)).filter(Boolean);
1036
+ //#endregion
1037
+ //#region src/utils/componentAliasMarkdown.ts
1038
+ /** `SUI equivalent: \`SColumn\`. <hint>`, or just the hint when SUI has no equivalent yet. */
1039
+ var formatComponentAlias = (alias) => alias.suiNames.length ? `SUI equivalent: ${codeList(alias.suiNames)}. ${alias.hint}` : alias.hint;
1040
+ //#endregion
552
1041
  //#region src/utils/componentMarkdown.ts
553
1042
  var OPTIONAL_TYPE_SUFFIX = / \| undefined$/;
554
1043
  var EMPTY_CELL = "—";
@@ -637,8 +1126,19 @@ var formatComponentApi = (resolved, component) => [
637
1126
  "",
638
1127
  formatNamedTypes(component.events, "Payload")
639
1128
  ].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.`;
1129
+ /** An unknown name: the other-library alias mapping first (when there is one), then the closest names. */
1130
+ var formatUnknownComponent = (resolved, query, suggestions, alias) => {
1131
+ const suggestionText = suggestions.map(inlineCode).join(", ");
1132
+ const listHint = `Call ${inlineCode(LIST_COMPONENTS_TOOL_NAME)} to see every component.`;
1133
+ if (alias) {
1134
+ const otherNames = suggestions.length ? ` Other close names: ${suggestionText}.` : "";
1135
+ return [
1136
+ formatSourceHeader(resolved),
1137
+ "",
1138
+ `Unknown component ${inlineCode(query)} (a name from another UI library). ${formatComponentAlias(alias)}${otherNames}`
1139
+ ].join("\n");
1140
+ }
1141
+ const hint = suggestions.length ? `Did you mean: ${suggestionText}?` : listHint;
642
1142
  return [
643
1143
  formatSourceHeader(resolved),
644
1144
  "",
@@ -654,23 +1154,6 @@ var formatComponentNeedsUpgrade = (resolved, bundled, componentName) => [
654
1154
  `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
1155
  ].join("\n");
656
1156
  //#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
1157
  //#region src/utils/componentPurpose.ts
675
1158
  var familyPurpose = (family) => Object.entries(FAMILY_PURPOSES).find(([familyName]) => familyName === family)?.[1] ?? "SUI component";
676
1159
  /**
@@ -718,72 +1201,6 @@ var formatTemplateValidation = (resolved, issues) => [
718
1201
  ...issues.length ? ["", ...issues.map((issue) => `- ${formatTemplateIssue(issue)}`)] : []
719
1202
  ].join("\n");
720
1203
  //#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
1204
  //#region src/utils/recipeMarkdown.ts
788
1205
  var recipeStoryUrl = (name) => `${LIVE_EXAMPLES_URL}${RECIPE_STORY_PATH_PREFIX}${name}`;
789
1206
  /** A fence one backtick longer than the longest backtick run in `code`, so the code can never close it early. */
@@ -819,19 +1236,36 @@ var formatUnknownRecipe = (query, names) => `Unknown recipe ${inlineCode(query)}
819
1236
  //#endregion
820
1237
  //#region src/services/componentCatalog.ts
821
1238
  var useComponentCatalogService = (api) => {
1239
+ const componentKeys = new Set(api.components.map((component) => toComponentKey(component.name)));
822
1240
  const listComponents = () => api.components.map((component) => ({
823
1241
  name: component.name,
824
1242
  family: component.family,
825
1243
  purpose: componentPurpose(component)
826
1244
  }));
827
- const suggestNames = (query) => {
1245
+ const suggestNames = (query, excludedNames = []) => {
828
1246
  const queryKeys = candidateComponentKeys(query);
829
1247
  const distanceTo = (name) => Math.min(...queryKeys.map((queryKey) => levenshteinDistance(queryKey, toComponentKey(name))));
830
- return api.components.map((component) => ({
1248
+ return api.components.filter((component) => !excludedNames.includes(component.name)).map((component) => ({
831
1249
  name: component.name,
832
1250
  distance: distanceTo(component.name)
833
1251
  })).sort((left, right) => left.distance - right.distance || left.name.localeCompare(right.name)).slice(0, 3).map((candidate) => candidate.name);
834
1252
  };
1253
+ /**
1254
+ * The other-library alias for a name that is not a component. An alias whose SUI targets are all
1255
+ * missing from this API version is skipped, so the Levenshtein suggestions answer instead.
1256
+ */
1257
+ const findAlias = (query) => {
1258
+ const queryKeys = candidateComponentKeys(query);
1259
+ const entry = Object.entries(COMPONENT_ALIASES).find(([alias]) => queryKeys.includes(toComponentKey(alias)));
1260
+ if (!entry) return;
1261
+ const [alias, { suiNames, hint }] = entry;
1262
+ const availableNames = suiNames.filter((name) => componentKeys.has(toComponentKey(name)));
1263
+ return suiNames.length && !availableNames.length ? void 0 : {
1264
+ alias,
1265
+ suiNames: availableNames,
1266
+ hint
1267
+ };
1268
+ };
835
1269
  const findComponent = (query) => {
836
1270
  for (const candidateKey of candidateComponentKeys(query)) {
837
1271
  const component = api.components.find((entry) => toComponentKey(entry.name) === candidateKey);
@@ -840,9 +1274,11 @@ var useComponentCatalogService = (api) => {
840
1274
  component
841
1275
  };
842
1276
  }
1277
+ const alias = findAlias(query);
843
1278
  return {
844
1279
  found: false,
845
- suggestions: suggestNames(query)
1280
+ suggestions: suggestNames(query, alias?.suiNames),
1281
+ alias
846
1282
  };
847
1283
  };
848
1284
  return {
@@ -997,7 +1433,7 @@ var serverInfo = {
997
1433
  name: SERVER_NAME,
998
1434
  version: {
999
1435
  name: "@khsura/sui-mcp",
1000
- version: "0.2.1",
1436
+ version: "0.4.0",
1001
1437
  repository: {
1002
1438
  "type": "git",
1003
1439
  "url": "git+https://github.com/khsura/sui.git",
@@ -1183,6 +1619,7 @@ var useGuideCatalogService = ({ sourceRoot = resolveGuideSourceRoot() } = {}) =>
1183
1619
  //#region src/services/behaviourRules.ts
1184
1620
  var nativeValidationInFormRule = {
1185
1621
  id: RULE_NATIVE_VALIDATION_IN_FORM,
1622
+ fixedIn: SUI_M2_FIXES_VERSION,
1186
1623
  check: ({ element, ancestors }) => {
1187
1624
  const typeAttribute = findAttribute(element, INPUT_TYPE_ATTRIBUTE);
1188
1625
  const inputType = typeAttribute?.staticValue?.toLowerCase();
@@ -1201,6 +1638,7 @@ var nativeValidationInFormRule = {
1201
1638
  };
1202
1639
  var hideDetailsHidesLabelRule = {
1203
1640
  id: RULE_HIDE_DETAILS_HIDES_LABEL,
1641
+ fixedIn: SUI_M2_FIXES_VERSION,
1204
1642
  check: ({ element }) => {
1205
1643
  const hideDetails = findPropAttribute(element, HIDE_DETAILS_ATTRIBUTE);
1206
1644
  if (!isOneOfComponentTags(element.tag, HIDE_DETAILS_LABEL_COMPONENTS) || !hideDetails || !isBooleanPropOn(element, "hide-details") || !findAttribute(element, "label")) return [];
@@ -1214,26 +1652,65 @@ var hideDetailsHidesLabelRule = {
1214
1652
  }];
1215
1653
  }
1216
1654
  };
1217
- var isUnreadableSnackbarAction = (button) => {
1655
+ var isUnreadablePresetAction = (button) => {
1656
+ const color = findAttribute(button, COLOR_ATTRIBUTE)?.staticValue;
1657
+ return findAttribute(button, "variant")?.staticValue === "text" && color !== void 0 && SNACKBAR_UNREADABLE_PRESET_COLORS.includes(color);
1658
+ };
1659
+ /** A text or icon action with a hex CSS colour below 4.5:1 on the default snackbar: used as is, in every version. */
1660
+ var lowContrastCssColorOf = (button) => {
1218
1661
  const color = findAttribute(button, COLOR_ATTRIBUTE)?.staticValue;
1219
1662
  const variant = findAttribute(button, VARIANT_ATTRIBUTE)?.staticValue;
1220
- return isComponentTag(button.tag, "SButton") && variant === "text" && color !== void 0 && SNACKBAR_UNREADABLE_PRESET_COLORS.includes(color);
1663
+ if (color === void 0 || variant === void 0 || !SNACKBAR_UNCOLOURED_ACTION_VARIANTS.includes(variant)) return;
1664
+ const contrast = getHexContrastRatio(color, SNACKBAR_DEFAULT_BACKGROUND);
1665
+ return contrast !== void 0 && contrast < 4.5 ? {
1666
+ color,
1667
+ contrast
1668
+ } : void 0;
1669
+ };
1670
+ /** A text or icon action with no colour at all: dark page text on the dark snackbar before the M2 fix. */
1671
+ var isUncolouredAction = (button) => {
1672
+ const variant = findAttribute(button, VARIANT_ATTRIBUTE)?.staticValue;
1673
+ return variant !== void 0 && SNACKBAR_UNCOLOURED_ACTION_VARIANTS.includes(variant) && !findAttribute(button, "color") && !staticClassNames(button).some((name) => name.startsWith("s_textColor__"));
1674
+ };
1675
+ var snackbarActionIssue = (button, hasSnackbarColorFix) => {
1676
+ const base = {
1677
+ ...positionOf(button),
1678
+ rule: RULE_SNACKBAR_ACTION_CONTRAST,
1679
+ severity: SEVERITY_WARNING,
1680
+ recipe: RECIPE_ACTIVATOR_OVERLAYS
1681
+ };
1682
+ const lowContrastCssColor = lowContrastCssColorOf(button);
1683
+ if (lowContrastCssColor) return {
1684
+ ...base,
1685
+ 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.`,
1686
+ 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}.`
1687
+ };
1688
+ if (hasSnackbarColorFix) return;
1689
+ if (isUnreadablePresetAction(button)) {
1690
+ const color = findAttribute(button, "color")?.staticValue ?? "";
1691
+ return {
1692
+ ...base,
1693
+ 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.`,
1694
+ fixHint: `Use a light colour: ${SNACKBAR_LIGHT_ACTION_COLOR_HINT}, or upgrade to ${SUI_M2_FIXES_VERSION} or later and remove \`color\`.`
1695
+ };
1696
+ }
1697
+ if (isUncolouredAction(button)) return {
1698
+ ...base,
1699
+ 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.`,
1700
+ fixHint: `Set a light colour: ${SNACKBAR_LIGHT_ACTION_COLOR_HINT}, or upgrade to ${SUI_M2_FIXES_VERSION} or later.`
1701
+ };
1221
1702
  };
1703
+ /**
1704
+ * A hex CSS colour below 4.5:1 on the snackbar always warns: the snackbar cannot adjust it. Before
1705
+ * `SUI_M2_FIXES_VERSION` a low-contrast preset colour or no colour at all warns too; from that version an action
1706
+ * without a colour takes the snackbar's light text colour and a preset colour uses a variant tuned to the snackbar.
1707
+ */
1222
1708
  var snackbarActionContrastRule = {
1223
1709
  id: RULE_SNACKBAR_ACTION_CONTRAST,
1224
- check: ({ element }) => {
1710
+ check: ({ element, apiVersion }) => {
1225
1711
  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
- });
1712
+ const hasSnackbarColorFix = isVersionAtLeast(apiVersion, SUI_M2_FIXES_VERSION);
1713
+ 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
1714
  }
1238
1715
  };
1239
1716
  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 +1732,30 @@ var blockButtonsInRowRule = {
1255
1732
  }];
1256
1733
  }
1257
1734
  };
1735
+ /** A text field whose label and error line are rendered, so its box sits between them. */
1736
+ var isDetailedField = (element) => isOneOfComponentTags(element.tag, LABELLED_FIELD_COMPONENTS) && !isBooleanPropOn(element, "hide-details");
1737
+ var fieldButtonRowRule = {
1738
+ id: RULE_FIELD_BUTTON_ROW,
1739
+ target: RULE_TARGET_ANY_ELEMENT,
1740
+ check: ({ element }) => {
1741
+ if (isComponentTag(element.tag, "SFormRow") || !isFlexRow(element)) return [];
1742
+ const children = childElementsOf(element);
1743
+ const field = children.find(isDetailedField);
1744
+ const button = children.find((child) => isComponentTag(child.tag, BUTTON_COMPONENT));
1745
+ if (!field || !button) return [];
1746
+ return [{
1747
+ ...positionOf(button),
1748
+ rule: RULE_FIELD_BUTTON_ROW,
1749
+ severity: SEVERITY_WARNING,
1750
+ 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.`,
1751
+ 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.",
1752
+ recipe: RECIPE_FILTER_BAR
1753
+ }];
1754
+ }
1755
+ };
1258
1756
  var cardTitleTextAlignRule = {
1259
1757
  id: RULE_CARD_TITLE_TEXT_ALIGN,
1758
+ fixedIn: SUI_M2_FIXES_VERSION,
1260
1759
  check: ({ element }) => {
1261
1760
  if (!isComponentTag(element.tag, "SCardTitle")) return [];
1262
1761
  return staticClassNames(element).flatMap((className) => {
@@ -1281,31 +1780,262 @@ var startsAsEmptyString = (modelPath, scriptSource) => {
1281
1780
  const escapedName = (modelPath.trim().split(MODEL_PATH_SEPARATOR).at(-1) ?? "").replaceAll(REGEX_SPECIAL_CHARACTERS, "\\$&");
1282
1781
  return EMPTY_STRING_INITIAL_PATTERNS.some((pattern) => new RegExp(pattern.replace(MODEL_NAME_PLACEHOLDER, escapedName)).test(scriptSource));
1283
1782
  };
1783
+ var datePickerEmptyStringRule = {
1784
+ id: RULE_DATE_PICKER_EMPTY_STRING,
1785
+ fixedIn: SUI_M2_FIXES_VERSION,
1786
+ check: ({ element, scriptSource }) => {
1787
+ const binding = isOneOfComponentTags(element.tag, DATE_PICKER_EMPTY_STRING_COMPONENTS) ? modelBinding(element) : void 0;
1788
+ const source = binding && isDirective(binding) ? expressionSource(binding) : binding?.value?.content;
1789
+ if (!binding || source === void 0) return [];
1790
+ const isEmptyLiteral = EMPTY_STRING_EXPRESSION.test(source) || !isDirective(binding) && source === "";
1791
+ const isEmptyInitial = MODEL_PATH_PATTERN.test(source) && startsAsEmptyString(source, scriptSource);
1792
+ if (!isEmptyLiteral && !isEmptyInitial) return [];
1793
+ return [{
1794
+ ...positionOf(binding),
1795
+ rule: RULE_DATE_PICKER_EMPTY_STRING,
1796
+ severity: SEVERITY_WARNING,
1797
+ 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.`,
1798
+ fixHint: "Start an empty date as `null` (type the model `string | null`); `''` is not treated as \"no date\".",
1799
+ recipe: RECIPE_VALIDATED_FORM
1800
+ }];
1801
+ }
1802
+ };
1803
+ var paginationLengthRowsRule = {
1804
+ id: RULE_PAGINATION_LENGTH_ROWS,
1805
+ check: ({ element }) => {
1806
+ const length = isComponentTag(element.tag, "SPagination") ? findPropAttribute(element, PAGINATION_LENGTH_ATTRIBUTE) : void 0;
1807
+ const source = length && isDirective(length.node) ? expressionSource(length.node) : void 0;
1808
+ if (!length || source === void 0 || !PAGINATION_ROW_COUNT_EXPRESSION.test(source) || PAGINATION_PAGE_MATH_EXPRESSION.test(source)) return [];
1809
+ return [{
1810
+ ...positionOf(length.node),
1811
+ rule: RULE_PAGINATION_LENGTH_ROWS,
1812
+ severity: SEVERITY_WARNING,
1813
+ message: `\`:length="${source}"\` on \`SPagination\` looks like a number of rows, but \`length\` is the number of pages: it would show one page per row.`,
1814
+ fixHint: "Pass the page count: `const pageCount = computed(() => Math.ceil(totalItems.value / itemsPerPage))`, then `<SPagination v-model=\"page\" :length=\"pageCount\" />`."
1815
+ }];
1816
+ }
1817
+ };
1818
+ var paginationZeroBasedRule = {
1819
+ id: RULE_PAGINATION_ZERO_BASED,
1820
+ check: ({ element }) => {
1821
+ const binding = isComponentTag(element.tag, "SPagination") ? modelBinding(element) : void 0;
1822
+ const source = binding && isDirective(binding) ? expressionSource(binding) : void 0;
1823
+ const lastSegment = source?.trim().split(MODEL_PATH_SEPARATOR).at(-1);
1824
+ if (!binding || !source || !MODEL_PATH_PATTERN.test(source) || !PAGINATION_ZERO_BASED_MODEL.test(lastSegment ?? "")) return [];
1825
+ return [{
1826
+ ...positionOf(binding),
1827
+ rule: RULE_PAGINATION_ZERO_BASED,
1828
+ severity: SEVERITY_WARNING,
1829
+ message: `\`${source}\` looks like a 0-based index (such as STable's \`pageIndex\`), but \`SPagination\`'s \`v-model\` is the page number starting at 1: page 1 would show as page 2.`,
1830
+ fixHint: "Keep a 1-based `page` ref for SPagination and derive the index where you need it: `const pageIndex = computed(() => page.value - 1)`."
1831
+ }];
1832
+ }
1833
+ };
1834
+ var skeletonLoaderPresetName = (part) => part.split("@")[0]?.trim() ?? "";
1835
+ var skeletonLoaderSuggestion = (name) => {
1836
+ const replacement = SKELETON_LOADER_VUETIFY_PRESETS[name];
1837
+ return replacement ? `\`${name}\` → \`${replacement}\`` : `\`${name}\``;
1838
+ };
1839
+ var skeletonLoaderUnknownPresetRule = {
1840
+ id: RULE_SKELETON_LOADER_UNKNOWN_PRESET,
1841
+ check: ({ element }) => {
1842
+ const type = isComponentTag(element.tag, "SSkeletonLoader") ? findPropAttribute(element, SKELETON_LOADER_TYPE_ATTRIBUTE) : void 0;
1843
+ const unknownNames = (type?.staticValue ?? "").split(",").map(skeletonLoaderPresetName).filter((name) => name !== "" && !SKELETON_LOADER_PRESETS.includes(name));
1844
+ if (!type || unknownNames.length === 0) return [];
1845
+ return [{
1846
+ ...positionOf(type.node),
1847
+ rule: RULE_SKELETON_LOADER_UNKNOWN_PRESET,
1848
+ severity: SEVERITY_ERROR,
1849
+ message: `\`SSkeletonLoader\` has no ${codeList(unknownNames)} preset: it is ignored, so nothing is drawn for it.`,
1850
+ fixHint: `Use SUI presets joined by commas, with \`@N\` to repeat one (\`type="avatar, text@3"\`): ${codeList(SKELETON_LOADER_PRESETS)}. Instead of ${unknownNames.map(skeletonLoaderSuggestion).join(", ")}.`
1851
+ }];
1852
+ }
1853
+ };
1854
+ var skeletonLoaderNeverHidesRule = {
1855
+ id: RULE_SKELETON_LOADER_NEVER_HIDES,
1856
+ check: ({ element }) => {
1857
+ const loading = isComponentTag(element.tag, "SSkeletonLoader") ? findPropAttribute(element, SKELETON_LOADER_LOADING_ATTRIBUTE) : void 0;
1858
+ if (!loading?.isBound || hasChildContent(element) || hasObjectSpread(element)) return [];
1859
+ return [{
1860
+ ...positionOf(loading.node),
1861
+ rule: RULE_SKELETON_LOADER_NEVER_HIDES,
1862
+ severity: SEVERITY_WARNING,
1863
+ message: "`SSkeletonLoader` has a bound `loading` but no content: with nothing to swap in, the skeleton stays on screen after loading ends.",
1864
+ fixHint: "Put the real content inside it: `<SSkeletonLoader type=\"card\" :loading=\"isLoading\"><SCard>…</SCard></SSkeletonLoader>`, or toggle it yourself with `v-if=\"isLoading\"` and a `v-else` sibling."
1865
+ }];
1866
+ }
1867
+ };
1284
1868
  /** Rules about behaviour and styling misuses that the component API alone cannot catch. */
1869
+ var fillHeightUnderAppRule = {
1870
+ id: RULE_FILL_HEIGHT_UNDER_APP,
1871
+ fixedIn: SUI_M2_FIXES_VERSION,
1872
+ check: ({ element }) => {
1873
+ if (!isComponentTag(element.tag, "SApp")) return [];
1874
+ return childElementsOf(element).filter((child) => staticClassNames(child).includes(HEIGHT_FILL_CLASS)).map((child) => ({
1875
+ ...positionOf(child),
1876
+ rule: RULE_FILL_HEIGHT_UNDER_APP,
1877
+ severity: SEVERITY_WARNING,
1878
+ 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.`,
1879
+ fixHint: "Upgrade @khsura/sui to 1.20.0 or later, or add `style=\"min-height: 100dvh\"` to this child.",
1880
+ recipe: RECIPE_CENTERED_PAGE
1881
+ }));
1882
+ }
1883
+ };
1884
+ var avatarTextNotInitialsRule = {
1885
+ id: RULE_AVATAR_TEXT_NOT_INITIALS,
1886
+ check: ({ element }) => {
1887
+ const textAttribute = isComponentTag(element.tag, "SAvatar") ? findAttribute(element, AVATAR_TEXT_ATTRIBUTE) : void 0;
1888
+ const text = textAttribute?.staticValue?.trim();
1889
+ if (!textAttribute || !text || text.length <= 3 && !WHITESPACE_CHARACTER_PATTERN.test(text)) return [];
1890
+ const initials = text.split(WHITESPACE_CHARACTER_PATTERN).filter(Boolean).map((word) => word.charAt(0).toUpperCase()).join("").slice(0, 3);
1891
+ return [{
1892
+ ...positionOf(textAttribute.node),
1893
+ rule: RULE_AVATAR_TEXT_NOT_INITIALS,
1894
+ severity: SEVERITY_WARNING,
1895
+ message: `\`text="${text}"\` on \`SAvatar\` is not initials: the avatar is a fixed-size circle, so a name is clipped to its first letters.`,
1896
+ fixHint: `Pass the initials and put the name in \`alt\`: \`<SAvatar text="${initials}" alt="${text}" />\`.`
1897
+ }];
1898
+ }
1899
+ };
1900
+ var labelWordsOf = (text) => (text.toLocaleLowerCase().match(LABEL_WORD_PATTERN) ?? []).filter((word) => word.length >= 3);
1901
+ /**
1902
+ * `hide-details` on a text field hides its `label` by design (it becomes the input's `aria-label`), so on screen only
1903
+ * the placeholder or a slot can say what the field is for. Warn when nothing visible does: no placeholder, or one that
1904
+ * shares no word with the label (`label="Search by name" placeholder="e.g. Anna"`). Bound values and slot content are
1905
+ * trusted.
1906
+ */
1907
+ var hiddenLabelNoVisibleNameRule = {
1908
+ id: RULE_HIDDEN_LABEL_NO_VISIBLE_NAME,
1909
+ check: ({ element }) => {
1910
+ const hideDetails = findPropAttribute(element, HIDE_DETAILS_ATTRIBUTE);
1911
+ const label = findAttribute(element, LABEL_ATTRIBUTE)?.staticValue;
1912
+ if (!isOneOfComponentTags(element.tag, LABELLED_FIELD_COMPONENTS) || !hideDetails || !isBooleanPropOn(element, "hide-details") || !label || childElementsOf(element).length > 0) return [];
1913
+ const placeholder = findAttribute(element, PLACEHOLDER_ATTRIBUTE);
1914
+ if (placeholder && placeholder.staticValue === void 0) return [];
1915
+ const placeholderWords = labelWordsOf(placeholder?.staticValue ?? "");
1916
+ if (labelWordsOf(label).some((word) => placeholderWords.includes(word))) return [];
1917
+ return [{
1918
+ ...positionOf(hideDetails.node),
1919
+ rule: RULE_HIDDEN_LABEL_NO_VISIBLE_NAME,
1920
+ severity: SEVERITY_WARNING,
1921
+ message: `\`hide-details\` on \`${element.tag}\` hides \`label="${label}"\` (it becomes the input's \`aria-label\`), and nothing visible names the field: ${placeholder ? `the placeholder "${placeholder.staticValue}" doesn't say what it is for` : "it has no placeholder"}.`,
1922
+ fixHint: `Keep the label visible by dropping \`hide-details\` (inside \`SFormRow\` the field still lines up with its buttons), or give it a placeholder that names it, e.g. \`placeholder="${label}"\`.`,
1923
+ recipe: RECIPE_FILTER_BAR
1924
+ }];
1925
+ }
1926
+ };
1927
+ /** The `v-on` / `@` directives on `element` with a static event name. */
1928
+ var eventListeners = (element) => element.props.filter(isDirective).filter((directive) => directive.name === "on").map((directive) => ({
1929
+ directive,
1930
+ event: staticArgument(directive.arg)
1931
+ }));
1932
+ var emptyStateActionEventRule = {
1933
+ id: RULE_EMPTY_STATE_ACTION_EVENT,
1934
+ check: ({ element }) => {
1935
+ if (!isComponentTag(element.tag, "SEmptyState")) return [];
1936
+ return eventListeners(element).filter(({ event }) => event !== void 0 && EMPTY_STATE_WRONG_ACTION_EVENTS.includes(event)).map(({ directive, event }) => ({
1937
+ ...positionOf(directive),
1938
+ rule: RULE_EMPTY_STATE_ACTION_EVENT,
1939
+ severity: SEVERITY_WARNING,
1940
+ message: `\`@${event ?? ""}\` on \`SEmptyState\` is not its action event: SEmptyState emits \`action\` from its button${event === "click" ? ", and a plain `@click` fires for a click anywhere in the block" : ", so this listener never fires"}.`,
1941
+ fixHint: `Listen to \`@action\`: \`<SEmptyState action-text="Create order" @action="${expressionSource(directive) ?? "onAction"}" />\`.`
1942
+ }));
1943
+ }
1944
+ };
1945
+ var emptyStateActionWithoutListenerRule = {
1946
+ id: RULE_EMPTY_STATE_ACTION_WITHOUT_LISTENER,
1947
+ check: ({ element }) => {
1948
+ const actionText = isComponentTag(element.tag, "SEmptyState") ? findPropAttribute(element, EMPTY_STATE_ACTION_TEXT_ATTRIBUTE) : void 0;
1949
+ const hasListener = eventListeners(element).some(({ event }) => event === void 0 || event === "action");
1950
+ const fillsActions = slotFills(element).some((fill) => staticArgument(fill.directive.arg) === EMPTY_STATE_ACTIONS_SLOT);
1951
+ if (!actionText || hasListener || fillsActions || hasObjectSpread(element)) return [];
1952
+ return [{
1953
+ ...positionOf(actionText.node),
1954
+ rule: RULE_EMPTY_STATE_ACTION_WITHOUT_LISTENER,
1955
+ severity: SEVERITY_WARNING,
1956
+ message: "`action-text` on `SEmptyState` renders a button, but nothing listens to its `action` event, so the button does nothing.",
1957
+ fixHint: "Add `@action=\"…\"`, or for navigation drop `action-text` and use the slot: `<SEmptyState title=\"No orders yet\"><template #actions><SButton color=\"primary\" to=\"/orders/new\">Create order</SButton></template></SEmptyState>`."
1958
+ }];
1959
+ }
1960
+ };
1961
+ var isFlushRowSibling = (element) => (ROW_TEXT_SIBLING_TAGS.includes(element.tag) || isOneOfComponentTags(element.tag, ROW_FLUSH_SIBLING_COMPONENTS)) && !staticClassNames(element).some((className) => HORIZONTAL_INSET_CLASS_PATTERN.test(className));
1962
+ /**
1963
+ * The elements beside `row`: its parent's other children, and, while the row sits in a wrapper that adds no
1964
+ * padding (`SForm`, `<form>`), that wrapper's siblings too.
1965
+ */
1966
+ var rowNeighbours = (row, ancestors) => {
1967
+ const neighbours = [];
1968
+ let current = row;
1969
+ for (const container of [...ancestors].reverse()) {
1970
+ neighbours.push(...childElementsOf(container).filter((child) => child !== current));
1971
+ if (!isOneOfComponentTags(container.tag, ROW_TRANSPARENT_WRAPPERS)) break;
1972
+ current = container;
1973
+ }
1974
+ return neighbours;
1975
+ };
1285
1976
  var behaviourRules = [
1286
1977
  nativeValidationInFormRule,
1287
1978
  hideDetailsHidesLabelRule,
1979
+ hiddenLabelNoVisibleNameRule,
1288
1980
  snackbarActionContrastRule,
1289
1981
  blockButtonsInRowRule,
1982
+ fieldButtonRowRule,
1290
1983
  cardTitleTextAlignRule,
1984
+ datePickerEmptyStringRule,
1985
+ fillHeightUnderAppRule,
1986
+ avatarTextNotInitialsRule,
1987
+ paginationLengthRowsRule,
1988
+ paginationZeroBasedRule,
1989
+ skeletonLoaderUnknownPresetRule,
1990
+ skeletonLoaderNeverHidesRule,
1991
+ emptyStateActionEventRule,
1992
+ emptyStateActionWithoutListenerRule,
1291
1993
  {
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 [];
1994
+ id: RULE_ROW_INSET_FROM_TEXT,
1995
+ check: ({ element, ancestors }) => {
1996
+ if (!isComponentTag(element.tag, "SRow") || hasObjectSpread(element)) return [];
1997
+ const hasOuterGuttersOff = isBooleanPropOn(element, ROW_NO_OUTER_GUTTERS_PROP);
1998
+ const flushSibling = isBooleanPropOn(element, "no-gutters") || hasOuterGuttersOff && !!findPropAttribute(element, "gap") ? void 0 : rowNeighbours(element, ancestors).find(isFlushRowSibling);
1999
+ if (!flushSibling) return [];
1300
2000
  return [{
1301
- ...positionOf(binding),
1302
- rule: RULE_DATE_PICKER_EMPTY_STRING,
2001
+ ...positionOf(element),
2002
+ rule: RULE_ROW_INSET_FROM_TEXT,
1303
2003
  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\".",
2004
+ message: hasOuterGuttersOff ? `\`SRow no-outer-gutters\` beside \`<${flushSibling.tag}>\`: the row no longer pads itself, but each SColumn still pads its content by 8px, so the columns start 8px inside it.` : `\`SRow\` beside \`<${flushSibling.tag}>\`: the row and each SColumn pad by 8px, so the columns start 16px inside it.`,
2005
+ fixHint: "Add `no-outer-gutters :gap=\"16\"` to the `SRow` (gap replaces the column padding), and separate stacked rows with `class=\"s_mt__4\"`. Keep the default padding only when the inset is intended.",
2006
+ recipe: RECIPE_RESPONSIVE_GRID
2007
+ }];
2008
+ }
2009
+ },
2010
+ {
2011
+ id: RULE_NUMBER_INPUT_PREFERRED,
2012
+ check: ({ element, api }) => {
2013
+ const typeAttribute = findAttribute(element, INPUT_TYPE_ATTRIBUTE);
2014
+ if (!isComponentTag(element.tag, "SInput") || typeAttribute?.staticValue?.toLowerCase() !== "number" || !hasSuiComponent(api, "SNumberInput")) return [];
2015
+ const replacements = [...NUMBER_INPUT_PROP_REPLACEMENTS].filter(([name]) => findPropAttribute(element, name)).map(([name, replacement]) => `\`${name}\` → ${replacement}`);
2016
+ return [{
2017
+ ...positionOf(typeAttribute.node),
2018
+ rule: RULE_NUMBER_INPUT_PREFERRED,
2019
+ severity: SEVERITY_WARNING,
2020
+ message: "`SInput type=\"number\"` has no step buttons or `precision`, and hides a value below `min`. `SNumberInput` is the numeric field: `number | null` v-model, +/- buttons and ArrowUp/ArrowDown, clamping on blur, spinbutton semantics and no browser validation bubble.",
2021
+ fixHint: `Use \`<SNumberInput v-model="quantity" label="Quantity" :min="0" />\` (same \`label\`, \`rules\`, \`hide-details\`, \`hide-error\`, \`min\`, \`max\`, \`suffix\`; add \`:step\`, \`:precision="2"\` for money).${replacements.length ? ` Replace ${replacements.join("; ")}.` : ""}`,
1306
2022
  recipe: RECIPE_VALIDATED_FORM
1307
2023
  }];
1308
2024
  }
2025
+ },
2026
+ {
2027
+ id: RULE_TABS_IN_SLIDE_GROUP,
2028
+ check: ({ element, ancestors }) => {
2029
+ if (!isComponentTag(element.tag, "STabs") || !ancestors.some((ancestor) => isComponentTag(ancestor.tag, "SSlideGroup"))) return [];
2030
+ return [{
2031
+ ...positionOf(element),
2032
+ rule: RULE_TABS_IN_SLIDE_GROUP,
2033
+ severity: SEVERITY_WARNING,
2034
+ message: "`STabs` inside `SSlideGroup`: STabs already keeps its tabs on one row that scrolls sideways, with an edge fade when they do not fit (or `wrap` for several rows).",
2035
+ fixHint: "Remove the `SSlideGroup` wrapper and use `<STabs v-model>` with `<STab :tab>` children directly.",
2036
+ recipe: RECIPE_TABBED_SECTIONS
2037
+ }];
2038
+ }
1309
2039
  }
1310
2040
  ];
1311
2041
  //#endregion
@@ -1425,34 +2155,136 @@ var iconButtonLabelRule = {
1425
2155
  }] : [];
1426
2156
  }
1427
2157
  };
1428
- var rawReplacement = (element) => {
2158
+ var rawReplacement = (element, api) => {
1429
2159
  if (element.tag !== "input") return RAW_TAG_REPLACEMENTS.get(element.tag);
1430
2160
  const inputType = findAttribute(element, INPUT_TYPE_ATTRIBUTE)?.staticValue?.toLowerCase();
1431
- if (inputType && NON_VISUAL_INPUT_TYPES.includes(inputType)) return;
2161
+ if (inputType && (NON_VISUAL_INPUT_TYPES.includes(inputType) || inputType === "file")) return;
2162
+ if (inputType === "number" && hasSuiComponent(api, "SNumberInput")) return NUMBER_INPUT_COMPONENT;
1432
2163
  return (inputType ? RAW_INPUT_TYPE_REPLACEMENTS.get(inputType) : void 0) ?? RAW_TAG_REPLACEMENTS.get("input");
1433
2164
  };
2165
+ var noRawReplacementRule = {
2166
+ id: RULE_NO_RAW_REPLACEMENT,
2167
+ target: RULE_TARGET_ANY_ELEMENT,
2168
+ check: ({ element, api }) => {
2169
+ const replacement = rawReplacement(element, api);
2170
+ if (!replacement) return [];
2171
+ return [{
2172
+ ...positionOf(element),
2173
+ rule: RULE_NO_RAW_REPLACEMENT,
2174
+ severity: SEVERITY_WARNING,
2175
+ message: `Raw \`<${element.tag}>\` bypasses SUI theming, sizing and validation.`,
2176
+ fixHint: `Use \`${replacement}\` instead.`,
2177
+ recipe: element.tag === "dialog" ? RECIPE_ACTIVATOR_OVERLAYS : RECIPE_VALIDATED_FORM
2178
+ }];
2179
+ }
2180
+ };
2181
+ var isFileInputElement = (element) => element.tag === "input" && findAttribute(element, "type")?.staticValue?.toLowerCase() === "file";
2182
+ /** Whether a listener in `scope` opens the picker through the ref: `@click="fileInput?.click()"`. */
2183
+ var opensPickerThroughRef = (scope, refName) => [scope, ...descendantElementsOf(scope)].some((candidate) => candidate.props.some((prop) => {
2184
+ if (!isDirective(prop) || prop.name !== "on") return false;
2185
+ return [...(expressionSource(prop) ?? "").matchAll(PICKER_CLICK_CALL_PATTERN)].some(([call]) => call.split(MEMBER_PATH_SEPARATOR_PATTERN).includes(refName));
2186
+ }));
2187
+ /**
2188
+ * A raw `<input type="file">`, often hidden and opened by a button's `ref.click()`. Only for a `@khsura/sui`
2189
+ * whose API has SFileInput, so a project on an older release is not told to use a component it lacks.
2190
+ */
2191
+ var rawFileInputRule = {
2192
+ id: RULE_RAW_FILE_INPUT,
2193
+ target: RULE_TARGET_ANY_ELEMENT,
2194
+ check: ({ element, ancestors, api }) => {
2195
+ if (!isFileInputElement(element) || !api.components.some((component) => component.name === "SFileInput")) return [];
2196
+ const refName = findAttribute(element, "ref")?.staticValue;
2197
+ const scope = ancestors[0] ?? element;
2198
+ const isButtonHack = !!refName && opensPickerThroughRef(scope, refName);
2199
+ return [{
2200
+ ...positionOf(element),
2201
+ rule: RULE_RAW_FILE_INPUT,
2202
+ severity: SEVERITY_WARNING,
2203
+ message: isButtonHack ? `A file \`<input>\` opened by a button's \`${refName}.click()\` has no label of its own, skips \`rules\` and the error line, and its chosen file is never shown or announced.` : "A raw `<input type=\"file\">` bypasses SUI theming, its label, `rules` and the error line.",
2204
+ fixHint: `Use \`${FILE_INPUT_EXAMPLE}\` (\`variant="dropzone"\` for a drop area). Its model is a \`File[]\` (\`null\` when empty): read \`files?.[0]\` for one file, or watch the model / listen to \`@change\`, which passes the files, not a DOM event.`,
2205
+ recipe: RECIPE_VALIDATED_FORM
2206
+ }];
2207
+ }
2208
+ };
2209
+ /** `@change` on SFileInput passes `File[] | null`; code written for a native input reads `$event.target.files`. */
2210
+ var fileInputChangeEventRule = {
2211
+ id: RULE_FILE_INPUT_CHANGE_EVENT,
2212
+ check: ({ element }) => {
2213
+ if (!isComponentTag(element.tag, "SFileInput")) return [];
2214
+ return element.props.filter((prop) => isDirective(prop) && prop.name === "on" && staticArgument(prop.arg) === "change" && NATIVE_CHANGE_EVENT_ACCESS_PATTERN.test(expressionSource(prop) ?? "")).map((listener) => ({
2215
+ ...positionOf(listener),
2216
+ rule: RULE_FILE_INPUT_CHANGE_EVENT,
2217
+ severity: SEVERITY_ERROR,
2218
+ message: "`SFileInput` emits `change` with the chosen files (`File[] | null`), not a DOM event, so `.target` / `$event.files` is `undefined`.",
2219
+ fixHint: "Bind `v-model=\"files\"` and read `files?.[0]`, or take the files from the event: `@change=\"(files) => upload(files?.[0])\"`."
2220
+ }));
2221
+ }
2222
+ };
2223
+ var avatarImageInSlotRule = {
2224
+ id: RULE_AVATAR_IMAGE_IN_SLOT,
2225
+ check: ({ element }) => {
2226
+ if (!isComponentTag(element.tag, "SAvatar")) return [];
2227
+ return descendantElementsOf(element).filter((child) => isOneOfComponentTags(child.tag, AVATAR_SLOT_IMAGE_TAGS)).map((image) => {
2228
+ const source = findAttribute(image, "src");
2229
+ const imageBinding = source && isDirective(source.node) ? `:image="${expressionSource(source.node) ?? ""}"` : `image="${source?.staticValue ?? "…"}"`;
2230
+ return {
2231
+ ...positionOf(image),
2232
+ rule: RULE_AVATAR_IMAGE_IN_SLOT,
2233
+ severity: SEVERITY_WARNING,
2234
+ message: `\`<${image.tag}>\` inside \`SAvatar\` replaces the avatar's own image: when it fails to load, the avatar shows a broken image instead of the initials or the icon.`,
2235
+ fixHint: `Pass the URL to the avatar and drop the \`<${image.tag}>\`: \`<SAvatar ${imageBinding} text="JD" alt="Jane Doe" />\`.`
2236
+ };
2237
+ });
2238
+ }
2239
+ };
2240
+ var isSlotFillTemplate = (template) => template.props.filter(isDirective).some((directive) => directive.name === DIRECTIVE_SLOT);
2241
+ /** Children the group cannot overlap or count as one avatar: anything but SAvatar or a passthrough `<slot>`, looking through `<template v-for>`. */
2242
+ var strayAvatarGroupChildren = (element) => childElementsOf(element).flatMap((child) => {
2243
+ if (child.tag === "template") return isSlotFillTemplate(child) ? [] : strayAvatarGroupChildren(child);
2244
+ return isComponentTag(child.tag, "SAvatar") || AVATAR_GROUP_PASSTHROUGH_TAGS.includes(child.tag) ? [] : [child];
2245
+ });
2246
+ var avatarGroupChildRule = {
2247
+ id: RULE_AVATAR_GROUP_CHILD,
2248
+ check: ({ element }) => {
2249
+ if (!isComponentTag(element.tag, "SAvatarGroup")) return [];
2250
+ return strayAvatarGroupChildren(element).map((child) => ({
2251
+ ...positionOf(child),
2252
+ rule: RULE_AVATAR_GROUP_CHILD,
2253
+ severity: SEVERITY_WARNING,
2254
+ message: `\`<${child.tag}>\` is a direct child of \`SAvatarGroup\`: the group only overlaps and rings \`SAvatar\` children, so a wrapper breaks the overlap and counts as one avatar for \`max\`.`,
2255
+ fixHint: "Put each `SAvatar` directly in the group: `<SAvatar v-for=\"member in members\" :key=\"member.id\" :image=\"member.photoUrl\" :alt=\"member.name\" />`. For a tooltip or a link, wrap the whole group, not each avatar."
2256
+ }));
2257
+ }
2258
+ };
2259
+ /** Elements in the default slot of `element`: its children outside a `#slot` template, looking through plain `<template>`s. */
2260
+ var defaultSlotElements = (element) => childElementsOf(element).flatMap((child) => {
2261
+ if (child.tag === "template") return isSlotFillTemplate(child) ? [] : defaultSlotElements(child);
2262
+ return [child, ...descendantElementsOf(child)];
2263
+ });
1434
2264
  /** Rules about how components fit together, beyond what one component's API says. */
1435
2265
  var compositionRules = [
1436
2266
  activatorBindingRule,
1437
2267
  layoutForRule,
1438
2268
  formRulesOutsideFormRule,
1439
2269
  iconButtonLabelRule,
2270
+ noRawReplacementRule,
2271
+ avatarImageInSlotRule,
2272
+ avatarGroupChildRule,
1440
2273
  {
1441
- id: RULE_NO_RAW_REPLACEMENT,
1442
- target: RULE_TARGET_ANY_ELEMENT,
2274
+ id: RULE_EMPTY_STATE_OUTSIDE_NO_DATA_SLOT,
1443
2275
  check: ({ element }) => {
1444
- const replacement = rawReplacement(element);
1445
- if (!replacement) return [];
1446
- return [{
1447
- ...positionOf(element),
1448
- rule: RULE_NO_RAW_REPLACEMENT,
1449
- severity: SEVERITY_WARNING,
1450
- message: `Raw \`<${element.tag}>\` bypasses SUI theming, sizing and validation.`,
1451
- fixHint: `Use \`${replacement}\` instead.`,
1452
- recipe: element.tag === "dialog" ? RECIPE_ACTIVATOR_OVERLAYS : RECIPE_VALIDATED_FORM
1453
- }];
2276
+ if (!isOneOfComponentTags(element.tag, NO_DATA_SLOT_COMPONENTS)) return [];
2277
+ return defaultSlotElements(element).filter((child) => isComponentTag(child.tag, EMPTY_STATE_COMPONENT)).map((emptyState) => ({
2278
+ ...positionOf(emptyState),
2279
+ rule: RULE_EMPTY_STATE_OUTSIDE_NO_DATA_SLOT,
2280
+ severity: SEVERITY_ERROR,
2281
+ message: `\`SEmptyState\` in the default slot of \`${element.tag}\` is never rendered: its no-data content goes in the \`#${NO_DATA_SLOT_NAME}\` slot.`,
2282
+ fixHint: `Wrap it in the slot template: \`<${element.tag} …><template #${NO_DATA_SLOT_NAME}><SEmptyState size="small" icon="mdi-inbox-outline" title="Nothing here yet" /></template></${element.tag}>\`.`
2283
+ }));
1454
2284
  }
1455
- }
2285
+ },
2286
+ rawFileInputRule,
2287
+ fileInputChangeEventRule
1456
2288
  ];
1457
2289
  //#endregion
1458
2290
  //#region src/services/templateRules.ts
@@ -1489,13 +2321,14 @@ var unknownComponentRule = {
1489
2321
  id: RULE_UNKNOWN_COMPONENT,
1490
2322
  check: ({ element, lookup }) => {
1491
2323
  if (lookup.found) return [];
1492
- const suggestion = lookup.suggestions.length ? `Did you mean ${codeList(lookup.suggestions)}? ` : "";
2324
+ const suggestion = lookup.suggestions.length ? `${lookup.alias ? "Other close names" : "Did you mean"} ${codeList(lookup.suggestions)}? ` : "";
2325
+ const aliasAdvice = lookup.alias ? `${formatComponentAlias(lookup.alias)} ` : "";
1493
2326
  return [{
1494
2327
  ...positionOf(element),
1495
2328
  rule: RULE_UNKNOWN_COMPONENT,
1496
2329
  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}.`
2330
+ 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.`,
2331
+ fixHint: `${aliasAdvice}${suggestion}Check the exact names with ${LIST_COMPONENTS_TOOL_NAME}.`
1499
2332
  }];
1500
2333
  }
1501
2334
  };
@@ -1597,16 +2430,19 @@ var byPosition = (left, right) => left.line - right.line || left.column - right.
1597
2430
  /** Validates SUI usage in a `.vue` SFC or template fragment against one `sui-api.json`. */
1598
2431
  var useTemplateValidatorService = (api, rules = templateRules) => {
1599
2432
  const catalog = useComponentCatalogService(api);
2433
+ const apiVersion = api.version;
2434
+ const activeRules = rules.filter((rule) => !rule.fixedIn || !isVersionAtLeast(apiVersion, rule.fixedIn));
1600
2435
  const validate = (code) => {
1601
2436
  const { root, errors, scriptSource } = parseVueTemplate(code);
1602
2437
  const ruleIssues = (root ? placedElements(root) : []).flatMap(({ element, ancestors }) => {
1603
- const applicableRules = rules.filter((rule) => appliesTo(rule, element.tag));
2438
+ const applicableRules = activeRules.filter((rule) => appliesTo(rule, element.tag));
1604
2439
  if (!applicableRules.length) return [];
1605
2440
  const context = {
1606
2441
  element,
1607
2442
  ancestors,
1608
2443
  lookup: catalog.findComponent(element.tag),
1609
2444
  api,
2445
+ apiVersion,
1610
2446
  scriptSource
1611
2447
  };
1612
2448
  return applicableRules.flatMap((rule) => rule.check(context));
@@ -1745,13 +2581,13 @@ var findInBundled = (resolved, name, loadBundledSuiApi) => {
1745
2581
  };
1746
2582
  var registerGetComponentApiTool = (server, loadSuiApi, loadBundledSuiApi) => {
1747
2583
  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.",
2584
+ 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
2585
  inputSchema: getComponentApiInputSchema
1750
2586
  }, ({ name }) => withSuiApi(loadSuiApi, (resolved) => {
1751
2587
  const lookup = useComponentCatalogService(resolved.api).findComponent(name);
1752
2588
  if (lookup.found) return textResult(formatComponentApi(resolved, lookup.component));
1753
2589
  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);
2590
+ return newer ? textResult(formatComponentNeedsUpgrade(resolved, newer.bundled, newer.component.name), true) : textResult(formatUnknownComponent(resolved, name, lookup.suggestions, lookup.alias), true);
1755
2591
  }));
1756
2592
  };
1757
2593
  //#endregion
@@ -1799,7 +2635,7 @@ var registerValidateSuiTemplateTool = (server, loadSuiApi) => {
1799
2635
  //#region src/handlers/getRecipe.ts
1800
2636
  var registerGetRecipeTool = (server, recipeSourceOptions) => {
1801
2637
  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.",
2638
+ 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, tabbed-sections. Unknown names return the name list.",
1803
2639
  inputSchema: getRecipeInputSchema
1804
2640
  }, ({ name }) => {
1805
2641
  try {
@@ -1813,7 +2649,7 @@ var registerGetRecipeTool = (server, recipeSourceOptions) => {
1813
2649
  //#endregion
1814
2650
  //#region src/handlers/listRecipes.ts
1815
2651
  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." }, () => {
2652
+ 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
2653
  try {
1818
2654
  return textResult(formatRecipeList(useRecipeCatalogService(recipeSourceOptions).listRecipes()));
1819
2655
  } catch (error) {