@carto/meridian-ds 5.1.4-alpha.f781449.339 → 5.2.0

package/CHANGELOG.md

@@ -2,10 +2,19 @@
 
 ## Unreleased
 
-- feat(ai-metadata): one-call get_component lookups, minified MCP payloads and design-review conventions [sc-578601] [sc-578639] [#563](https://github.com/CartoDB/meridian-ds/pull/563)
-
 ## 5.0
 
+### 5.2.0
+
+- feat(dialog): export useScrollBorders hook for scroll-edge borders [sc-578988] [#564](https://github.com/CartoDB/meridian-ds/pull/564)
+- feat(button): `tooltip` on Button and SplitButton — shown on hover even while disabled, and linked as the button's description; with it set, the button renders inside a wrapper span [sc-579530] [#563](https://github.com/CartoDB/meridian-ds/pull/563)
+- feat(icon-button): logs a dev-only `console.error` when an IconButton has no accessible name — test setups that fail on `console.error` need a `tooltip` or `aria-label` on those buttons [sc-579530] [#563](https://github.com/CartoDB/meridian-ds/pull/563)
+- feat(eslint-rules): new `@carto/meridian-ds/eslint-rules` export — Meridian's design rules as `no-restricted-syntax` entries plus generated MUI restricted imports, for `.eslintrc` or flat config; `SPACING_STEPS` exported from `@carto/meridian-ds/theme` [sc-579313] [#563](https://github.com/CartoDB/meridian-ds/pull/563)
+- feat(ai-metadata): leaner MCP — minified results, compact catalogs (`list_icons` is now plain text; `list_components` lists family members by name), `get_component` takes `names` and returns `example`/`moreExamples`/`propTypes` instead of `description`/`examples.stories` [sc-578601] [sc-578984] [#563](https://github.com/CartoDB/meridian-ds/pull/563)
+- feat(ai-metadata): conventions absorb the generic design-review rules; decision trees point list filters at FilterDropdown [sc-578639] [sc-580037] [#563](https://github.com/CartoDB/meridian-ds/pull/563)
+- feat(ai-metadata): Meridian's own rendering per curated story — `meridian_get_screenshot(storyId)` and new `meridian_get_anatomy(storyId)`, shipped in `dist/stories/` [sc-580343] [#568](https://github.com/CartoDB/meridian-ds/pull/568)
+- chore(stories): stories follow Meridian's design rules, enforced by lint [sc-579467] [#563](https://github.com/CartoDB/meridian-ds/pull/563)
+
 ### 5.1.3
 
 - fix(ai-metadata): allow fractional spacing steps; give design team ownership of design-system paths [sc-577069] [#558](https://github.com/CartoDB/meridian-ds/pull/558)

package/dist/bin/meridian-ds-mcp.js

@@ -33,14 +33,17 @@ function resolveBundlePath() {
 var DOCS = [];
 var KNOWN = [];
 var ICONS = [];
+var ICONS_TEXT = "";
 var TOKENS;
 var SCREENSHOTS = {};
+var STORY_REFS = {};
+var DIST_DIR = "";
 var CONVENTIONS = "";
 var VERSION = "0.0.0";
 var TOOLS = [
   {
     name: "meridian_list_components",
-    description: "List all Meridian components with their description and keywords, plus a family signal where relevant (`subComponents` for a compound component, `variants` for sibling components chosen between \u2014 each with a one-line description). Start here: the catalog is small, so read it and pick the component whose description/keywords match your need. Rows flagged `documented: false` are not yet curated (no when-to-use/decisionTree/prop guidance): most still have example stories via get_examples; a few are known-only \u2014 real, importable components with no stories yet, for which get_component/get_examples just point at the type declarations.",
+    description: "The Meridian component catalog \u2014 start here. Each row has a description and keywords, plus by name: `subComponents` (parts it's composed with), `variants` (siblings chosen between) and `relatedExports` (hooks/utils/constants). Pick by meaning (there's no search tool), then call meridian_get_component. `documented: false` marks components with no curation yet \u2014 lean on meridian_get_examples and the .d.ts for those.",
     inputSchema: {
       type: "object",
       properties: {},
@@ -49,7 +52,7 @@ var TOOLS = [
   },
   {
     name: "meridian_get_component",
-    description: "Curation for one component (or several, via `names`): when to use it, its decisionTree (when to reach for a different component), any limitations (capabilities it lacks vs. similar components \u2014 check before downgrading from one), and the high-value inherited MUI props (curation.mui, some with an aiHint). Own props, types, and JSDoc are NOT here \u2014 read the shipped .d.ts (the propTypes field gives the exact command). The lead usage story ships its code inline (`examples.stories[0].code`) \u2014 call meridian_get_examples only for other stories. For a not-yet-curated component (`documented: false`) it returns a note + .d.ts pointer in place of curation \u2014 plus its example stories when any exist (a known-only component has none, so rely on the .d.ts). Sub-components and variants (`DialogHeader`, `MultipleAutocomplete`, \u2026) have no standalone catalog entry \u2014 `meridian_get_component`/`meridian_get_examples` on them return a pointer to the parent (check its `curation.subComponents`/`curation.variants`).",
+    description: "Everything to use a component, in one call: when to use it, its decisionTree (when another component fits better), limitations, high-value inherited MUI props (`curation.mui`), family members with descriptions, and the lead usage story's code (`example.code`; `moreExamples` counts the rest, via meridian_get_examples). Own props/types/JSDoc ship in the .d.ts files listed in `propTypes`. Pass `names` for several components at once. A family member's name (e.g. `DialogHeader`) returns a pointer to its parent.",
     inputSchema: {
       type: "object",
       properties: {
@@ -65,7 +68,7 @@ var TOOLS = [
   },
   {
     name: "meridian_get_examples",
-    description: "Real, copy-able example code (per Storybook story, with imports), shipped in the package. With no storyId: the lead usage story and the notable stories in full, plus an 'Other Stories' list (name + id) of the rest. Pass a storyId (from that list or meridian_get_component) to get just that story's full code. Sub-components and variants (`DialogHeader`, `MultipleAutocomplete`, \u2026) have no standalone catalog entry \u2014 `meridian_get_component`/`meridian_get_examples` on them return a pointer to the parent (check its `curation.subComponents`/`curation.variants`).",
+    description: "Copy-able example code from a component's stories. With no storyId: the lead usage story and the notable stories in full, plus an index (name + id) of the rest. With a storyId: just that story. Family member names point to their parent, as in meridian_get_component.",
     inputSchema: {
       type: "object",
       properties: {
@@ -81,7 +84,7 @@ var TOOLS = [
   },
   {
     name: "meridian_get_conventions",
-    description: "Mandatory system-wide Meridian rules to apply whenever generating or editing UI (component selection, a11y, i18n, styling/theme tokens, props, examples). Call this once per session BEFORE writing code and follow it \u2014 these rules are not repeated in the per-component data.",
+    description: `Mandatory system-wide Meridian rules (component choice, a11y, i18n, styling/tokens, props, examples). Call once per session BEFORE writing UI code and follow them \u2014 the per-component data doesn't repeat them. Skip it if your context already has the "Meridian usage conventions" doc (e.g. a skill loaded it).`,
     inputSchema: {
       type: "object",
       properties: {},
@@ -90,7 +93,7 @@ var TOOLS = [
   },
   {
     name: "meridian_list_icons",
-    description: "List every Meridian custom icon by name, with search keywords where curated (e.g. Bigquery \u2192 warehouse/database). There's no search tool \u2014 match by meaning against the name + keywords. Import the one you pick from '@carto/meridian-ds/custom-icons' and render it as `<Name />`. All icons share one prop type (CustomIconProps): MUI SvgIconProps \u2014 `color`, `fontSize`, `sx`, \u2026 \u2014 plus `width`/`height`; the result's `props` field has the details and the .d.ts pointer. Prefer a Meridian custom icon over an ad-hoc SVG or a MUI icon.",
+    description: "Every Meridian custom icon by name, with search keywords where curated (e.g. `Bigquery: warehouse, database`). Match by meaning; import from '@carto/meridian-ds/custom-icons' and render `<Name />`. Prefer these over an ad-hoc SVG or a MUI icon.",
     inputSchema: {
       type: "object",
       properties: {},
@@ -99,7 +102,7 @@ var TOOLS = [
   },
   {
     name: "meridian_get_tokens",
-    description: "The design tokens (exact values) to reference instead of hardcoding: palette (semantic text/background/action/divider, the intents, and the color scales), the typography ramp (per-variant fontSize/fontWeight/lineHeight/letterSpacing), spacing base, shape.borderRadius, breakpoints, and shadows. Use these with the rules in meridian_get_conventions (which says to use tokens, not raw hex/px) \u2014 this tool supplies the actual values. Projected from the theme, so it always matches the installed Meridian version. These are theme-level tokens (the global palette/type/spacing scale); for a component's internal spacing (e.g. Button padding, List row gap) use meridian_get_component, not this.",
+    description: "Exact theme token values to use instead of hardcoding: palette, typography ramp, spacing base, shape.borderRadius, breakpoints and shadows \u2014 projected from the installed version's theme. Theme-level only: a component's internal spacing comes from meridian_get_component.",
     inputSchema: {
       type: "object",
       properties: {},
@@ -108,17 +111,32 @@ var TOOLS = [
   },
   {
     name: "meridian_get_screenshot",
-    description: "Returns the filesystem path to a labeled reference screenshot. name='icons' is a grid of EVERY custom icon (each glyph captioned with its import name). Read that image to visually confirm an icon you shortlisted from meridian_list_icons, or to match one in a design you're implementing, then use its exact name. Deliberately returns a path (not an inline image) \u2014 portable, cheap per call, and reusable by a consumer app's picker. Requires a runtime that can read images (e.g. Claude Code); headless/non-multimodal callers can skip it. Call with no name to list the available screenshots.",
+    description: "Path to a reference image. name='icons' is a grid of every custom icon captioned with its import name. Any curated component's story id (e.g. 'components-alert--layout', from meridian_get_component's `example.id` or meridian_get_examples) returns Meridian's own rendering of that story at 1280\xD7800 \u2014 compare it with your build to tell an app composing a component wrong from Meridian rendering it wrong. Needs an image-capable runtime. Omit name to list the labeled screenshots.",
     inputSchema: {
       type: "object",
       properties: {
         name: {
           type: "string",
-          description: "Which screenshot to return (e.g. 'icons'). Omit to list the available ones."
+          description: "'icons', or a story id. Omit to list the labeled screenshots."
         }
       },
       additionalProperties: false
     }
+  },
+  {
+    name: "meridian_get_anatomy",
+    description: "Slot geometry of Meridian's own rendering of a story: each MUI component instance with its box, and its slots' boxes (e.g. Alert `icon`/`message`/`action`) relative to that instance, so they compare across widths. Matches meridian_get_screenshot for the same story id. Use it to measure where a component's parts should sit.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        storyId: {
+          type: "string",
+          description: "A curated component's story id, e.g. 'components-alert--layout'."
+        }
+      },
+      required: ["storyId"],
+      additionalProperties: false
+    }
   }
 ];
 var find = (name) => DOCS.find((d) => d.name.toLowerCase() === String(name).toLowerCase());
@@ -132,10 +150,9 @@ function notFound(name) {
     error: `No Meridian component named "${name}" (check the spelling). See meridian_list_components for the catalog.`
   };
 }
-function dtsFindRecipe(...names) {
-  const root = "find node_modules/@carto/meridian-ds/dist/types";
-  const clauses = names.map((n) => `-name '${n}.d.ts'`);
-  return names.length > 1 ? `${root} \\( ${clauses.join(" -o ")} \\)` : `${root} ${clauses[0]}`;
+var DTS_ROOT = "node_modules/@carto/meridian-ds/dist/types";
+function dtsFindRecipe(name) {
+  return `find ${DTS_ROOT} -name '${name}.d.ts'`;
 }
 function familyParent(name) {
   const lc = String(name).toLowerCase();
@@ -160,22 +177,6 @@ function partitionExamples(examples) {
   const inShown = new Set(shown);
   return { shown, rest: examples.filter((e) => !inShown.has(e)) };
 }
-function exampleStories(examples) {
-  const { shown, rest } = partitionExamples(examples);
-  const leadId = shown[0]?.id;
-  const ordered = [
-    ...shown,
-    ...rest.filter((e) => e.summary),
-    ...rest.filter((e) => !e.summary)
-  ];
-  return ordered.map((e) => ({
-    id: e.id,
-    name: titleize(e.name),
-    ...e.id === leadId ? { lead: true } : {},
-    ...e.summary ? { summary: e.summary } : {},
-    ...e.id === leadId ? { code: e.code } : {}
-  }));
-}
 function listComponents() {
   return DOCS.map((d) => ({
     name: d.name,
@@ -185,20 +186,14 @@ function listComponents() {
     // examples + the .d.ts are still available. Documented rows omit the flag.
     ...d.documented ? {} : { documented: false },
     keywords: d.curation.keywords ?? [],
-    // Family signal: the parts a compound component is composed with, and the
-    // sibling variants chosen between — each as { name, description } (same shape
-    // as get_component) so an agent can pick a family member while scanning.
-    ...d.curation.subComponents?.length ? { subComponents: d.curation.subComponents } : {},
-    ...d.curation.variants?.length ? { variants: d.curation.variants } : {},
-    // The public hooks/utils/constants that ship with this component — name,
-    // kind, and description (same as subComponents/variants, so an agent can pick
-    // one while scanning without a get_component round-trip). get_component adds
-    // `import` (the entry point — constant across the family, so omitted here).
+    // Family members and related exports by name only; get_component carries
+    // their descriptions.
+    ...d.curation.subComponents?.length ? { subComponents: d.curation.subComponents.map(subName) } : {},
+    ...d.curation.variants?.length ? { variants: d.curation.variants.map(subName) } : {},
     ...d.curation.relatedExports?.length ? {
       relatedExports: d.curation.relatedExports.map((e) => ({
         name: relatedName(e),
-        ...typeof e === "object" && e.kind ? { kind: e.kind } : {},
-        ...typeof e === "object" && e.description ? { description: e.description } : {}
+        ...typeof e === "object" && e.kind ? { kind: e.kind } : {}
       }))
     } : {}
   }));
@@ -206,30 +201,35 @@ function listComponents() {
 function getComponent(name) {
   const doc = find(name);
   if (!doc) return familyRedirect(name) ?? notFound(name);
-  const parts = (doc.curation.subComponents ?? []).map(subName);
-  const dtsGlob = dtsFindRecipe(doc.name, ...parts);
-  const compound = parts.length > 0 ? `${doc.name} is a compound component \u2014 compose it with its parts: ${parts.join(", ")}. ` : "";
   const parent = doc.documented ? void 0 : familyParent(doc.name);
-  const sourceHint = doc.examples.length ? "Use the examples below and its type declarations" : "No example stories ship for it either \u2014 rely on its type declarations (the propTypes recipe below)";
+  const sourceHint = doc.examples.length ? "Use its example and type declarations" : "No example stories ship for it either \u2014 rely on its type declarations";
   const note = doc.documented ? void 0 : `${parent ? `${doc.name} is a ${parent.role} of ${parent.parent} \u2014 compose it within ${parent.parent} (see meridian_get_component('${parent.parent}')). ` : ""}Not yet curated: no when-to-use / decisionTree / keywords / promoted-prop guidance for this component. ${sourceHint} \u2014 and still prefer it over a bare MUI equivalent.`;
+  const { keywords: _keywords, relatedExports, ...curation } = doc.curation;
+  const lead = partitionExamples(doc.examples).shown[0];
   return {
     name: doc.name,
-    description: doc.description,
     documented: doc.documented,
     ...note ? { note } : {},
-    curation: doc.curation,
-    // Own props/types/JSDoc aren't in the bundle by design; point a headless
-    // agent at the shipped .d.ts (no IDE/hover assumed) — for the root and, for a
-    // compound component, every part. Promoted inherited MUI props, when curated,
-    // are already in `curation.mui` above.
-    propTypes: `${compound}Own props, exact types, and JSDoc are not in this payload \u2014 they ship as TypeScript declarations. Read them from the installed package: \`${dtsGlob}\`. Import from '@carto/meridian-ds/components'.`,
-    examples: doc.examples.length ? {
-      note: "Stories are ordered by copy-value; the flagged lead (with its code) is the starting point. Call meridian_get_examples(name, storyId) for any other story.",
-      stories: exampleStories(doc.examples)
-    } : {
-      note: "No example stories ship for this component yet \u2014 read its props from the .d.ts (see propTypes above).",
-      stories: []
-    }
+    curation: {
+      ...curation,
+      ...relatedExports?.length ? {
+        relatedExports: relatedExports.map((e) => {
+          if (typeof e !== "object") return e;
+          const { import: _import, ...rest } = e;
+          return rest;
+        })
+      } : {}
+    },
+    // The .d.ts files holding own props/types/JSDoc — the root and, for a compound
+    // component, every part — globbed under the install path.
+    propTypes: [
+      doc.name,
+      ...(doc.curation.subComponents ?? []).map(subName)
+    ].map((n) => `${DTS_ROOT}/**/${n}.d.ts`),
+    ...lead ? {
+      example: { id: lead.id, name: titleize(lead.name), code: lead.code },
+      ...doc.examples.length > 1 ? { moreExamples: doc.examples.length - 1 } : {}
+    } : {}
   };
 }
 function titleize(name) {
@@ -290,35 +290,70 @@ Fetch any with meridian_get_examples(storyId):
   }
   return md;
 }
+var SCOPE_HINT = {
+  element: " (cropped to the story root)",
+  page: " (full page, with portaled content)"
+};
 function getScreenshot(name) {
   const available = Object.keys(SCREENSHOTS);
+  const story = STORY_REFS[name];
+  if (story)
+    return {
+      path: path.join(DIST_DIR, story.image),
+      ...story.scope && { scope: story.scope },
+      hint: `Meridian's rendering of ${name} at 1280\xD7800${story.scope ? SCOPE_HINT[story.scope] : ""}. meridian_get_anatomy('${name}') gives its slot boxes.`
+    };
   const shot = name ? SCREENSHOTS[name] : void 0;
   if (!shot || !fs.existsSync(shot.path))
     return name ? {
-      error: `No screenshot named "${name}". Available: ${available.join(", ") || "(none \u2014 run `yarn metadata:screenshots` and rebuild)"}.`
+      error: `No screenshot named "${name}". Available: ${available.join(", ") || "(none \u2014 run `yarn metadata:screenshots` and rebuild)"}, or a curated component's story id (see meridian_get_examples).`
     } : { available };
   return { path: shot.path, count: shot.count, hint: shot.hint };
 }
-function listIcons() {
+function getAnatomy(storyId) {
+  const ref = STORY_REFS[storyId];
+  if (!ref)
+    return {
+      error: `No reference rendering for "${storyId}". Use a curated component's story id (see meridian_get_examples).`
+    };
+  if (!ref.anatomy)
+    return {
+      error: `No anatomy captured for "${storyId}" yet; meridian_get_screenshot('${storyId}') still has its image.`
+    };
   return {
-    note: "Import from '@carto/meridian-ds/custom-icons' and render as <Name />. Match by name or keywords \u2014 there's no search tool. To see the glyphs, call meridian_get_screenshot({name:'icons'}) and Read the returned image path.",
-    props: "Every icon is an identical forwardRef component sharing one prop type, CustomIconProps: MUI SvgIconProps \u2014 color, fontSize ('small'|'medium'|'large'|'inherit'), sx, htmlColor, titleAccess \u2014 plus width/height (number|string) to override the fontSize-based size. Prefer color/fontSize for theming/sizing; width/height only for a specific px size. The exact type ships at node_modules/@carto/meridian-ds/dist/types/custom-icons/types.d.ts (the per-icon <Name>.d.ts is identical boilerplate \u2014 no icon-specific props).",
-    count: ICONS.length,
-    icons: ICONS
+    storyId,
+    ...JSON.parse(
+      fs.readFileSync(path.join(DIST_DIR, ref.anatomy), "utf8")
+    )
   };
 }
+function renderIcons() {
+  const lines = ICONS.map(
+    (i) => i.keywords?.length ? `${i.name}: ${i.keywords.join(", ")}` : i.name
+  );
+  return [
+    `${ICONS.length} Meridian custom icons. Import from '@carto/meridian-ds/custom-icons' and render as <Name />. Match by name or keywords \u2014 there's no search tool. To see the glyphs, call meridian_get_screenshot({name:'icons'}) and Read the returned image path.`,
+    "Props: every icon is an identical forwardRef component sharing one prop type, CustomIconProps: MUI SvgIconProps \u2014 color, fontSize ('small'|'medium'|'large'|'inherit'), sx, htmlColor, titleAccess \u2014 plus width/height (number|string) to override the fontSize-based size. Prefer color/fontSize for theming/sizing; width/height only for a specific px size. The exact type ships at node_modules/@carto/meridian-ds/dist/types/custom-icons/types.d.ts.",
+    "Icons (Name: keywords):",
+    ...lines
+  ].join("\n");
+}
 function callTool(name, args) {
   switch (name) {
     case "meridian_list_components":
       return listComponents();
     case "meridian_list_icons":
-      return listIcons();
+      return ICONS_TEXT;
     case "meridian_get_tokens":
       return TOKENS ?? { error: "No tokens in this bundle." };
     case "meridian_get_screenshot":
       return getScreenshot(String(args.name ?? ""));
+    case "meridian_get_anatomy":
+      return getAnatomy(String(args.storyId ?? args.name ?? ""));
     case "meridian_get_component":
-      return Array.isArray(args.names) ? args.names.map((n) => getComponent(String(n))) : getComponent(String(args.name ?? ""));
+      if (Array.isArray(args.names))
+        return args.names.map((n) => getComponent(String(n)));
+      return getComponent(String(args.names ?? args.name ?? ""));
     case "meridian_get_examples":
       return getComponentExamples(
         String(args.name ?? ""),
@@ -330,22 +365,15 @@ function callTool(name, args) {
       throw new Error(`Unknown tool: ${name}`);
   }
 }
-var SERVER_INSTRUCTIONS = `Meridian Design System knowledge for writing React UI in an app that depends on @carto/meridian-ds.
+var SERVER_INSTRUCTIONS = `Meridian Design System knowledge for writing React UI with @carto/meridian-ds.
 
-REQUIRED FIRST STEP: before writing or editing ANY Meridian UI, call meridian_get_conventions once and follow it for the rest of the session. These are mandatory cross-cutting rules (component selection, a11y, i18n, styling/theme tokens, props, examples) that the per-component data does NOT repeat \u2014 skipping them produces off-spec code.
+REQUIRED FIRST STEP: before writing or editing any Meridian UI, have the conventions in context and follow them for the rest of the session \u2014 the per-component data doesn't repeat those rules. Call meridian_get_conventions once, unless your context already has the "Meridian usage conventions" doc (e.g. a skill loaded it).
 
-Flow:
-1. meridian_get_conventions \u2014 read first; apply throughout the session.
-2. meridian_list_components \u2014 read the (small) catalog and pick by description + keywords. There is no search tool; match by meaning (the model already knows "picker" \u2248 "dropdown" \u2248 "select").
-3. meridian_get_component(name), or {names: [...]} for several at once \u2014 when to use it, its decisionTree (conditions that point to a different component), the high-value inherited MUI props worth knowing (curation.mui; some carry an aiHint), and the lead usage story's code plus the other story ids.
-4. meridian_get_examples(name[, storyId]) \u2014 more copy-able example code. With no storyId: the lead usage story and the notable stories in full plus a list of the rest; pass a storyId for one story's full code.
-5. meridian_list_icons \u2014 when you need an icon, list the custom icons and match by name/keyword; import from '@carto/meridian-ds/custom-icons' and render as <Name />.
-6. meridian_get_tokens \u2014 exact palette/typography/spacing/shape/breakpoint/shadow values to use instead of hardcoding (the conventions say use tokens; this gives the values).
-7. meridian_get_screenshot \u2014 a labeled reference image (name='icons' \u2192 every icon); Read the returned path to visually confirm a shortlisted icon or match one from a design (image-capable runtimes only).
+Then: meridian_list_components to pick \u2192 meridian_get_component (\`names: [...]\` for several; includes the lead example) \u2192 meridian_get_examples only for other stories. Icons: meridian_list_icons. Exact token values: meridian_get_tokens. Meridian's own rendering of a story, for design QA: meridian_get_screenshot(storyId) + meridian_get_anatomy(storyId).
 
-Three tiers of components, by how much each carries (all are real and importable \u2014 always prefer one over a bare MUI equivalent): CURATED (most) have full when-to-use / decisionTree / promoted-prop guidance; LISTED (flagged "documented": false, with example stories) carry no curation yet \u2014 lean on get_examples + the .d.ts; KNOWN (flagged "documented": false, no stories) are real components not yet documented \u2014 get_component/get_examples point you at their type declarations (.d.ts).
+Component tiers \u2014 all real and importable; prefer any of them over a bare MUI equivalent: CURATED (most) have full guidance; LISTED (\`documented: false\`, with stories) have no curation \u2014 use the examples + .d.ts; KNOWN (\`documented: false\`, no stories) have only the .d.ts.
 
-Exact own props, types, and JSDoc are NOT served here \u2014 they ship as TypeScript declarations in the installed package. Read them with: find node_modules/@carto/meridian-ds/dist/types -name '<Component>.d.ts'. Import the component from '@carto/meridian-ds/components'. Prefer a Meridian component over a bare MUI one whenever one exists.`;
+Own props, types and JSDoc ship as TypeScript declarations: find node_modules/@carto/meridian-ds/dist/types -name '<Component>.d.ts'. Import components from '@carto/meridian-ds/components'.`;
 function send(msg) {
   process.stdout.write(JSON.stringify(msg) + "\n");
 }
@@ -401,6 +429,7 @@ function load() {
   DOCS = bundle.components;
   KNOWN = bundle.knownComponents ?? [];
   ICONS = bundle.icons ?? [];
+  ICONS_TEXT = renderIcons();
   TOKENS = bundle.tokens;
   SCREENSHOTS = Object.fromEntries(
     Object.entries(bundle.screenshots ?? {}).map(([key, s]) => [
@@ -412,6 +441,8 @@ function load() {
       }
     ])
   );
+  DIST_DIR = path.dirname(bundlePath);
+  STORY_REFS = bundle.storyReferences ?? {};
   CONVENTIONS = bundle.conventions;
   VERSION = bundle.version;
   process.stderr.write(

package/dist/components/index.cjs

@@ -7,7 +7,7 @@ const paletteUtils = require("../palette-utils-NhMBL9rx.cjs");
 const iconsMaterial = require("@mui/icons-material");
 const ArrowDown = require("../ArrowDown-84Oc8r9k.cjs");
 const ReactWindow = require("react-window");
-const utils = require("../utils-B2bWHJl-.cjs");
+const utils = require("../utils-CKBWUAeM.cjs");
 const Search = require("../Search-BsaXrSzs.cjs");
 require("cartocolor");
 const reactCodemirror2 = require("react-codemirror2");
@@ -72,6 +72,21 @@ const ScreenReaderOnly = material.styled("span")(() => ({
   whiteSpace: "nowrap",
   border: 0
 }));
+const idCounter = {};
+function uniqueId(prefix = "$lodash$") {
+  if (!idCounter[prefix]) {
+    idCounter[prefix] = 0;
+  }
+  const id = ++idCounter[prefix];
+  if (prefix === "$lodash$") {
+    return `${id}`;
+  }
+  return `${prefix}${id}`;
+}
+const TooltipAnchor = material.styled("span")({
+  display: "inline-flex",
+  "&[data-full-width]": { display: "flex", width: "100%" }
+});
 const loadingIndicator = /* @__PURE__ */ jsxRuntime.jsx(material.CircularProgress, { size: 18, color: "inherit" });
 function _Button({
   children,
@@ -84,6 +99,8 @@ function _Button({
   showExternalIcon = true,
   screenReaderText,
   "aria-describedby": ariaDescribedby,
+  tooltip,
+  tooltipPlacement = "top",
   ...otherProps
 }, ref) {
   const screenReaderTextValue = utils.useTranslationWithFallback(
@@ -92,7 +109,12 @@ function _Button({
   );
   const isExternalLink = otherProps.href && external;
   const isCenterLoading = loading && loadingPosition === void 0;
-  return /* @__PURE__ */ jsxRuntime.jsx(
+  const [tooltipId] = React.useState(() => uniqueId("button-tooltip-"));
+  const describedBy = [
+    isExternalLink ? "external-hint" : ariaDescribedby,
+    tooltip ? tooltipId : void 0
+  ].filter(Boolean).join(" ") || void 0;
+  const button = /* @__PURE__ */ jsxRuntime.jsx(
     material.Button,
     {
       loading,
@@ -108,7 +130,7 @@ function _Button({
         rel: "noopener noreferrer"
       },
       ref,
-      "aria-describedby": isExternalLink ? "external-hint" : ariaDescribedby,
+      ...describedBy && { "aria-describedby": describedBy },
       children: /* @__PURE__ */ jsxRuntime.jsxs(
         paletteUtils.Typography,
         {
@@ -125,20 +147,14 @@ function _Button({
       )
     }
   );
+  if (tooltip === void 0 || tooltip === null) return button;
+  return /* @__PURE__ */ jsxRuntime.jsx(material.Tooltip, { title: tooltip, placement: tooltipPlacement, describeChild: true, children: /* @__PURE__ */ jsxRuntime.jsxs(TooltipAnchor, { "data-full-width": otherProps.fullWidth || void 0, children: [
+    button,
+    /* @__PURE__ */ jsxRuntime.jsx("span", { hidden: true, id: tooltipId, children: tooltip })
+  ] }) });
 }
 const Button = React.forwardRef(_Button);
 Button.displayName = "Button";
-const idCounter = {};
-function uniqueId(prefix = "$lodash$") {
-  if (!idCounter[prefix]) {
-    idCounter[prefix] = 0;
-  }
-  const id = ++idCounter[prefix];
-  if (prefix === "$lodash$") {
-    return `${id}`;
-  }
-  return `${prefix}${id}`;
-}
 const ButtonGroup = material.styled(material.ButtonGroup)(({ theme, size }) => ({
   "& .MuiButton-root:last-child": {
     padding: 0,
@@ -148,6 +164,7 @@ const ButtonGroup = material.styled(material.ButtonGroup)(({ theme, size }) => (
 function SplitButton({
   options,
   disabled,
+  tooltip,
   loading,
   loadingPosition,
   onClick,
@@ -202,6 +219,7 @@ function SplitButton({
             Button,
             {
               disabled,
+              tooltip,
               loading,
               loadingPosition,
               onClick: handleClick,
@@ -1605,17 +1623,11 @@ function createAutocompleteGroupByList({
   });
   return result;
 }
-const warnDeprecatedGroupBy = /* @__PURE__ */ (() => {
-  const shownWarnings = /* @__PURE__ */ new Set();
-  return (componentName) => {
-    if (process.env.NODE_ENV !== "production" && !shownWarnings.has(componentName)) {
-      shownWarnings.add(componentName);
-      console.warn(
-        `${componentName}: The \`groupBy\` prop is deprecated because it breaks virtualization. Use \`createAutocompleteGroupByList\` instead.`
-      );
-    }
-  };
-})();
+const warnDeprecatedGroupBy = (componentName) => utils.warnOnce({
+  key: `${componentName}:groupBy`,
+  level: "warn",
+  message: `${componentName}: The \`groupBy\` prop is deprecated because it breaks virtualization. Use \`createAutocompleteGroupByList\` instead.`
+});
 function _Autocomplete({
   disabled,
   loading,
@@ -3676,14 +3688,52 @@ function DialogHeader({
     children && /* @__PURE__ */ jsxRuntime.jsx(DividerBottom, {})
   ] });
 }
-function computeScrollBorders(node, hasFooterAlert) {
+function computeScrollBorders({
+  node,
+  keepBottomBorder
+}) {
   const atBottom = Math.abs(node.scrollHeight - node.clientHeight - node.scrollTop) < 1;
   const atTop = node.scrollTop === 0;
   return {
     showTop: !atTop,
-    showBottom: !atBottom || Boolean(hasFooterAlert)
+    showBottom: !atBottom || Boolean(keepBottomBorder)
   };
 }
+function useScrollBorders({
+  keepBottomBorder
+} = {}) {
+  const theme = material.useTheme();
+  const [node, setNode] = React.useState(null);
+  const updateBorders = React.useCallback(
+    (element) => {
+      const { showTop, showBottom } = computeScrollBorders({
+        node: element,
+        keepBottomBorder
+      });
+      const borderStyle = `1px solid ${theme.palette.divider}`;
+      element.style.borderTop = showTop ? borderStyle : "none";
+      element.style.borderBottom = showBottom ? borderStyle : "none";
+    },
+    [theme.palette.divider, keepBottomBorder]
+  );
+  const onScroll = React.useCallback(
+    (event) => updateBorders(event.currentTarget),
+    [updateBorders]
+  );
+  React.useEffect(() => {
+    if (!node) return;
+    updateBorders(node);
+  }, [node, updateBorders]);
+  React.useEffect(() => {
+    if (!node || typeof ResizeObserver === "undefined") return;
+    const resizeObserver = new ResizeObserver(() => {
+      updateBorders(node);
+    });
+    resizeObserver.observe(node);
+    return () => resizeObserver.disconnect();
+  }, [node, updateBorders]);
+  return { ref: setNode, onScroll };
+}
 const Content$5 = material.styled(material.DialogContent, {
   shouldForwardProp: (prop) => ![
     "scrollableContent",
@@ -3738,45 +3788,31 @@ function _DialogContent({
   onScroll,
   ...props
 }, ref) {
-  const theme = material.useTheme();
   const [contentRef, setContentRef] = React.useState(null);
   React.useImperativeHandle(
     ref,
     () => contentRef,
     [contentRef]
   );
-  const updateBorders = React.useCallback(
+  const { ref: scrollBordersRef, onScroll: updateScrollBorders } = useScrollBorders({ keepBottomBorder: hasFooterAlert });
+  const setRefs = React.useCallback(
     (node) => {
-      const { showTop, showBottom } = computeScrollBorders(node, hasFooterAlert);
-      const borderStyle = `1px solid ${theme.palette.divider}`;
-      node.style.borderTop = showTop ? borderStyle : "none";
-      node.style.borderBottom = showBottom ? borderStyle : "none";
+      setContentRef(node);
+      scrollBordersRef(node);
     },
-    [theme.palette.divider, hasFooterAlert]
+    [scrollBordersRef]
   );
   const handleScroll = React.useCallback(
     (event) => {
-      updateBorders(event.target);
+      updateScrollBorders(event);
       onScroll == null ? void 0 : onScroll(event);
     },
-    [updateBorders, onScroll]
+    [updateScrollBorders, onScroll]
   );
-  React.useEffect(() => {
-    if (!contentRef) return;
-    updateBorders(contentRef);
-  }, [contentRef, updateBorders]);
-  React.useEffect(() => {
-    if (!contentRef || typeof ResizeObserver === "undefined") return;
-    const resizeObserver = new ResizeObserver(() => {
-      updateBorders(contentRef);
-    });
-    resizeObserver.observe(contentRef);
-    return () => resizeObserver.disconnect();
-  }, [contentRef, updateBorders]);
   return /* @__PURE__ */ jsxRuntime.jsx(
     Content$5,
     {
-      ref: setContentRef,
+      ref: setRefs,
       onScroll: handleScroll,
       scrollableContent,
       withGutter,
@@ -8191,3 +8227,4 @@ exports.useAutocompleteRenderOption = useAutocompleteRenderOption;
 exports.useCodeAreaAutocompletion = useCodeAreaAutocompletion;
 exports.useCopyValue = useCopyValue;
 exports.useListContextProps = useListContextProps;
+exports.useScrollBorders = useScrollBorders;