@carto/meridian-ds 4.0.0 → 4.0.1-alpha.8b0892c.291

package/CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## Unreleased
 
+- feat(ai-metadata): serve custom-icon and theme-token knowledge to AI agents — new `meridian_list_icons` and `meridian_get_tokens` MCP tools (icons searchable by curated keywords; tokens projected straight from the composed theme: palette / typography / spacing / shape / breakpoints / shadows), plus surfaced List `direction`/`spacing` props [#463](https://github.com/CartoDB/meridian-ds/pull/463) [sc-559510] [sc-559550]
+
 ## 4.0
 
 ### 4.0.0

package/dist/{TablePaginationActions-XEVsnuDF.js → TablePaginationActions-BvKjTAmB.js}

@@ -1,7 +1,7 @@
 import { jsx, jsxs } from "react/jsx-runtime";
 import { forwardRef } from "react";
 import { styled, MenuItem as MenuItem$1, Tooltip, CircularProgress, IconButton as IconButton$1, Box } from "@mui/material";
-import { d as MENU_ITEM_SIZE_DENSE, M as MENU_ITEM_SIZE_EXTENDED, e as ICON_SIZE_LARGE, a as ICON_SIZE_MEDIUM, I as ICON_SIZE_SMALL } from "./palette-utils-F7dMdI2q.js";
+import { d as MENU_ITEM_SIZE_DENSE, M as MENU_ITEM_SIZE_EXTENDED, e as ICON_SIZE_LARGE, a as ICON_SIZE_MEDIUM, I as ICON_SIZE_SMALL } from "./palette-utils-d-9NY8qw.js";
 import { KeyboardArrowLeftOutlined, KeyboardArrowRightOutlined } from "@mui/icons-material";
 import { useIntl } from "react-intl";
 import { u as useImperativeIntl } from "./useImperativeIntl-BUw_LXAO.js";

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

@@ -32,6 +32,8 @@ function resolveBundlePath() {
 }
 var DOCS = [];
 var KNOWN = [];
+var ICONS = [];
+var TOKENS;
 var CONVENTIONS = "";
 var VERSION = "0.0.0";
 var TOOLS = [
@@ -80,6 +82,24 @@ var TOOLS = [
       properties: {},
       additionalProperties: false
     }
+  },
+  {
+    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.",
+    inputSchema: {
+      type: "object",
+      properties: {},
+      additionalProperties: false
+    }
+  },
+  {
+    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.",
+    inputSchema: {
+      type: "object",
+      properties: {},
+      additionalProperties: false
+    }
   }
 ];
 var find = (name) => DOCS.find((d) => d.name.toLowerCase() === String(name).toLowerCase());
@@ -250,10 +270,22 @@ Fetch any with meridian_get_examples(storyId):
   }
   return md;
 }
+function listIcons() {
+  return {
+    note: "Import from '@carto/meridian-ds/custom-icons' and render as <Name />. Match by name or keywords \u2014 there's no search tool.",
+    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
+  };
+}
 function callTool(name, args) {
   switch (name) {
     case "meridian_list_components":
       return listComponents();
+    case "meridian_list_icons":
+      return listIcons();
+    case "meridian_get_tokens":
+      return TOKENS ?? { error: "No tokens in this bundle." };
     case "meridian_get_component":
       return getComponent(String(args.name ?? ""));
     case "meridian_get_examples":
@@ -276,6 +308,8 @@ Flow:
 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) \u2014 when to use it, its decisionTree (conditions that point to a different component), and the high-value inherited MUI props worth knowing (curation.mui; some carry an aiHint). It also returns the example story ids.
 4. meridian_get_examples(name[, storyId]) \u2014 real, 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).
 
 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).
 
@@ -334,6 +368,8 @@ function load() {
   );
   DOCS = bundle.components;
   KNOWN = bundle.knownComponents ?? [];
+  ICONS = bundle.icons ?? [];
+  TOKENS = bundle.tokens;
   CONVENTIONS = bundle.conventions;
   VERSION = bundle.version;
   process.stderr.write(

package/dist/components/index.js

@@ -2,12 +2,12 @@ import { jsx, jsxs, Fragment } from "react/jsx-runtime";
 import React, { forwardRef, useState, useRef, useEffect, useMemo, createElement, Fragment as Fragment$1, useCallback, useImperativeHandle, createContext, useContext } from "react";
 import { styled, Button as Button$1, Box, CircularProgress as CircularProgress$1, Tooltip, Popper, Grow, Paper, ClickAwayListener, MenuList as MenuList$1, MenuItem, ButtonGroup as ButtonGroup$1, TextField, InputAdornment, FormControl, InputLabel, FormHelperText, Select, Checkbox, Link as Link$1, ListItemText as ListItemText$1, IconButton as IconButton$1, ToggleButtonGroup as ToggleButtonGroup$1, Stack, Autocomplete as Autocomplete$1, Divider, ListItemIcon as ListItemIcon$1, createFilterOptions, alpha, useTheme, Toolbar as Toolbar$1, AppBar as AppBar$1, Dialog as Dialog$1, Chip as Chip$1, DialogTitle as DialogTitle$1, DialogContent as DialogContent$1, Fade, AlertTitle, Alert as Alert$2, DialogActions as DialogActions$1, Slide, Accordion, AccordionSummary, AccordionDetails, Avatar as Avatar$1, Menu as Menu$2, useMediaQuery, Portal, Snackbar as Snackbar$1, List as List$2, ListItemButton as ListItemButton$1, ListItem as ListItem$1, ListSubheader as ListSubheader$1, Typography as Typography$1, Popover } from "@mui/material";
 import { ListItemAvatar, ListItemSecondaryAction } from "@mui/material";
-import { T as Typography, I as ICON_SIZE_SMALL, a as ICON_SIZE_MEDIUM, M as MENU_ITEM_SIZE_EXTENDED, b as MENU_ITEM_SIZE_DEFAULT, c as MENU_LIST_MAX_SIZE, d as MENU_ITEM_SIZE_DENSE, A as APPBAR_SIZE, e as ICON_SIZE_LARGE, N as NOTIFICATION_DURATION_IN_MS, L as LIST_MAX_SIZE, f as LIST_ITEM_SIZE_DENSE, g as LIST_ITEM_SIZE_DEFAULT, h as LIST_OVERSCAN_ITEMS_COUNT, F as FontWeight, r as resolvePalettePath } from "../palette-utils-F7dMdI2q.js";
+import { T as Typography, I as ICON_SIZE_SMALL, a as ICON_SIZE_MEDIUM, M as MENU_ITEM_SIZE_EXTENDED, b as MENU_ITEM_SIZE_DEFAULT, c as MENU_LIST_MAX_SIZE, d as MENU_ITEM_SIZE_DENSE, A as APPBAR_SIZE, e as ICON_SIZE_LARGE, N as NOTIFICATION_DURATION_IN_MS, L as LIST_MAX_SIZE, f as LIST_ITEM_SIZE_DENSE, g as LIST_ITEM_SIZE_DEFAULT, h as LIST_OVERSCAN_ITEMS_COUNT, F as FontWeight, r as resolvePalettePath } from "../palette-utils-d-9NY8qw.js";
 import { OpenInNewOutlined, VisibilityOffOutlined, VisibilityOutlined, Cancel, ContentCopyOutlined, AddCircleOutlineOutlined, MenuOutlined, MoreVertOutlined, HelpOutline, ErrorOutline, ArrowBackOutlined, CloseOutlined, Check, TodayOutlined, StopCircleOutlined, ArrowUpwardOutlined } from "@mui/icons-material";
 import { F as ForwardedComponent$1 } from "../ArrowDown-Bho9Ssnw.js";
 import * as ReactWindow from "react-window";
-import { u as useTranslationWithFallback, I as IconButton, M as MenuItem$1, g as getThemeColor, e as ellipsisStyles, S as SVG_SELECTOR } from "../TablePaginationActions-XEVsnuDF.js";
-import { T } from "../TablePaginationActions-XEVsnuDF.js";
+import { u as useTranslationWithFallback, I as IconButton, M as MenuItem$1, g as getThemeColor, e as ellipsisStyles, S as SVG_SELECTOR } from "../TablePaginationActions-BvKjTAmB.js";
+import { T } from "../TablePaginationActions-BvKjTAmB.js";
 import { F as ForwardedComponent, a as ForwardedComponent$2, b as ForwardedComponent$3, c as ForwardedComponent$4 } from "../Search-DXfTNnxj.js";
 import "cartocolor";
 import { Controlled, UnControlled } from "react-codemirror2";

package/dist/conventions.md

@@ -21,6 +21,7 @@ Meridian is the source of truth: when an existing codebase pattern contradicts M
 - Source icons from Meridian's custom-icons first, then `@mui/icons-material`;
   add a local SVG only when neither has an equivalent. Don't duplicate an icon
   the design system already ships.
+- Find the right custom icon with `meridian_list_icons` — match by name or keyword (e.g. "warehouse" → `Bigquery`), import it from `@carto/meridian-ds/custom-icons`, and render `<Name />`. Every icon shares one prop type, `CustomIconProps` (MUI `SvgIconProps` — `color`/`fontSize`/`sx` — plus `width`/`height`).
 - Use the standard icon sizes — small 12px, medium (default) 18px, large 24px;
   a value off this scale (e.g. 16, 20) needs design sign-off. Prefer the
   outlined variants.
@@ -47,7 +48,7 @@ Meridian is the source of truth: when an existing codebase pattern contradicts M
 
 ## Styling
 
-- Use theme tokens, never hardcoded values: colors from the palette (`text.*`, `background.*`, `divider`, semantic `*.main`) and spacing from the theme spacing scale — no raw hex/rgb or pixel literals for color or spacing. Use integer steps on the spacing scale (`theme.spacing(n)`, or `sx` numeric spacing like `px: 2` / `mt: 3` which resolve to it) — not fractional steps or raw px.
+- Use theme tokens, never hardcoded values: colors from the palette (`text.*`, `background.*`, `divider`, semantic `*.main`) and spacing from the theme spacing scale — no raw hex/rgb or pixel literals for color or spacing. Use integer steps on the spacing scale (`theme.spacing(n)`, or `sx` numeric spacing like `px: 2` / `mt: 3` which resolve to it) — not fractional steps or raw px. Get the exact values — palette keys, spacing base, type ramp, `shape.borderRadius`, breakpoints, shadows — from `meridian_get_tokens`.
 - Text uses `<Typography variant=…>` (with the `weight` prop for emphasis), never hardcoded `fontSize`/`fontWeight`/`lineHeight`/`fontFamily`.
 - Meridian's type scale is custom and does not match MUI defaults (e.g. `body2`/`caption` differ from MUI's sizes, and there are Meridian-only variants like `code1`/`code2`/`code3` and `overlineDelicate`). Pick the variant by role from Typography's variant list (`meridian_get_examples('Typography')`) — don't assume a px size or map px → variant yourself.
 - `sx` is the right tool for one-off layout/spacing on primitives (`Box`/`Grid`/`Stack`), not the deprecated MUI system props