@sakaniui/react 0.8.10 → 0.8.12

package/AGENTS.md

@@ -19,6 +19,11 @@ Editors can query the same data through the bundled MCP server
 (`npx -y @sakaniui/mcp`): `search_components`, `get_component`, `search_icons`,
 `check_code`, `check_usage`, `get_tokens`, `get_guide`, `check_compatibility`, `get_changelog`.
 
+**Object props have a shape.** A prop such as `columns`, `items`, `options`, `plans` or `data` takes an array
+of objects with exactly the fields listed under the prop's `shape` (required ones must be present, and
+`keyof T` means "a field of your own data type"). `check_code` verifies the field names of inline literals.
+Components with a pattern the types do not teach carry `recipes`: code that compiles.
+
 **Start from the example, check before you answer.** Every component has `example`: its imports and the
 element with each required prop filled in, type-checked against the release. Start from it instead of
 writing the element from memory. Never guess an icon name: find it with `search_icons` (icons are
@@ -147,6 +152,12 @@ CSS of a component into your own file.
 
 Format: **Use for** · **Why it is built this way** · **Not for / instead**.
 
+**Looking for a component by another name?** SakaniUI uses its own names. A *dialog* or *alert dialog* is
+`Modal`; a *snackbar* is `Toast`; a *dropdown menu* is `Menu`; a *navbar* or *app bar* is `TopBar`; a
+*date picker* is `Calendar`; a *loader* is `Spinner`; a *toggle* is `Switch`; a *banner* is `Announcement`;
+*autocomplete* is `Combobox`. There is no `Dialog`, `AlertDialog`, `Snackbar` or `Navbar`. Each component
+lists its other names under `aliases` in `manifest.json`, and `search_components` understands them.
+
 ### Actions
 - **Button** — Use for any action that does something. *Why:* 5 variants × 3 sizes mirror Figma 1:1;
   `loading` disables interaction so double-submits can't happen. *Not for* navigation → `Link`; icon-only →
@@ -206,7 +217,11 @@ Format: **Use for** · **Why it is built this way** · **Not for / instead**.
 ### Content and data
 - **Card** — a container surface for a unit of content, optionally with actions. Not a layout wrapper for
   everything.
-- **Table** — dense, comparable records. **StatCard** — one headline metric with trend. **ListItem** — a
+- **Table** — dense, comparable records. `Table<T>` is generic: every column's `key` must be a field of
+  your row type `T` (`keyof T & string`), so a column that is not data (a delete button, a menu) still
+  needs a key: give the row type an optional `never` field (`actions?: never`) and render the control in
+  `render`. Inventing a key that is not on the row type does not compile (see `recipes` in
+  `get_component("Table")` for code that does). **StatCard** — one headline metric with trend. **ListItem** — a
   row in a list. **Charts** — pick by question: trend over time → Line/Area; compare categories → Bar;
   part of whole → Pie/Donut (few slices only); progress to a target → Radial; compare several measures →
   Radar; drop-off → Funnel; intensity across two dimensions → Heatmap.

package/CHANGELOG.md

@@ -2,6 +2,41 @@
 
 All notable changes to `@sakaniui/react` are documented here.
 
+## 0.8.12
+
+Found while testing 0.8.11 in Claude Code: after writing correct code, the agent offered to wrap the
+delete button in "SakaniUI's Dialog/AlertDialog". Neither exists; the component is `Modal`. It named it
+from memory without looking it up.
+
+- **`aliases` in `manifest.json`**: the other names people use for a component, 250+ across 61 components
+  (dialog, alert dialog -> `Modal`; snackbar -> `Toast`; navbar, app bar -> `TopBar`; date picker ->
+  `Calendar`; loader -> `Spinner`; toggle -> `Switch`; autocomplete -> `Combobox`; dropzone ->
+  `FileUpload`; pricing table -> `PricingTableBlock`; ...). Hand-written; the build checks every one
+  points at a real component and never shadows a real name.
+- **MCP:** `search_components` ranks by alias ("dialog" finds `Modal` first; a plain exact name such as
+  "button" always wins). `get_component`, `check_usage` and `check_code` now say what the name is here:
+  *"Dialog is not exported by @sakaniui/react. In SakaniUI that is `Modal` (Confirmation dialog)."*
+- `AGENTS.md` lists the most common renamings.
+
+## 0.8.11
+
+Found by asking Claude Code, with the published 0.8.10 MCP server, to add a delete button to a table row:
+every tool call was correct and `IconButton` was used properly, but it put the button in a new `Table`
+column with `key: 'actions'`, which does not compile (`key` must be a field of the row type). The
+contract only said `columns: TableColumn<T>[]`.
+
+- **Object props now have a `shape`** in `manifest.json`: the fields of `TableColumn<T>`, `BreadcrumbItem`,
+  `PricingPlan`, `SelectOption`, chart data and 58 more (63 props), read from the shipped type
+  definitions, generics kept as declared (`key: keyof T & string`).
+- **`recipes`**: code for patterns the types do not teach, compiled on every build. First one: a `Table`
+  column that is not data (a delete button, a menu). The build also checks the opposite, that a column
+  key which is not on the row type really does not compile.
+- **MCP `check_code` checks inline object literals** against the shape: an unknown field (`title` for
+  `label`, `pct` for `percent`, with a suggestion), a missing required field (with the item index), and,
+  for a `Table`, a column `key` that is not a field of the `rows` written next to it. Spreads, identifiers
+  and anything it cannot read are left alone (0 errors on 685 real elements in three apps).
+- `AGENTS.md` explains the generic `Table` rule and the new `shape` and `recipes`.
+
 ## 0.8.10
 
 Readiness release: everything below was found by testing the package the way a new user, an editor

package/README.md

@@ -142,7 +142,7 @@ or `claude mcp add sakaniui -- cmd /c npx -y @sakaniui/mcp`). Needs Node.js 18 o
 The server is its own tiny package, [`@sakaniui/mcp`](https://www.npmjs.com/package/@sakaniui/mcp) (about 1 MB, starts in a couple of seconds; it does not install the component library). The copy bundled in `@sakaniui/react` (`npx -y -p @sakaniui/react sakaniui-mcp`) still works but downloads far more.
 
 Tools: `search_components`, `get_component` (with a type-checked `example`), `search_icons`,
-`check_code` (checks a whole snippet: imports, required props, values, icon names), `check_usage`,
+`check_code` (checks a whole snippet: imports, required props, values, icon names, and the field names of object props such as table columns), `check_usage`,
 `list_components`, `get_tokens`, `get_guide`, `check_compatibility` and `get_changelog`.
 
 - **Read-only.** It reads five fixed files from a `@sakaniui/react` install (package.json, the

package/bin/sakaniui-mcp.mjs

@@ -81,7 +81,7 @@ function unknownProp(c, name) {
   }
   // close spellings, plus the usual synonyms (leftIcon -> leadingIcon, onChange vs onValueChange is left to the list)
   const canon = (x) => x.toLowerCase().replace(/left|start|before|prefix/g, 'leading').replace(/right|end|after|suffix/g, 'trailing').replace(/colou?r|tone|kind|type/g, 'variant');
-  const near = c.props.map((p) => p.name).filter((p) => distance(p.toLowerCase(), name.toLowerCase()) <= 2 || canon(p) === canon(name));
+  const near = c.props.map((p) => p.name).filter((p) => similar(p, name) || canon(p) === canon(name));
   return { level: 'error', message: `"${name}" is not a ${c.name} prop${near.length ? ` (did you mean ${near.map((x) => `"${x}"`).join(', ')}?)` : ''}. ${c.name} accepts: ${c.props.map((p) => p.name).join(', ') || 'no props of its own'}.` };
 }
 
@@ -121,6 +121,22 @@ function propTooNew(c, p, value, installed = projectVersion) {
 
 /* ---------- helpers ---------- */
 const byName = new Map(manifest.components.map((c) => [c.name.toLowerCase(), c]));
+// Common names for components ("Dialog" -> Modal). Only used when a name is not found, and to rank search results.
+const norm = (x) => String(x).toLowerCase().replace(/[^a-z0-9]/g, '');
+const aliasIndex = new Map(); // normalized alias -> components
+for (const c of manifest.components) for (const a of c.aliases || []) { const k = norm(a); if (!aliasIndex.has(k)) aliasIndex.set(k, []); aliasIndex.get(k).push(c); }
+/** The real component(s) for a name that does not exist: "Dialog" -> [Modal]. */
+function byAlias(name) {
+  const k = norm(name);
+  const exact = aliasIndex.get(k) || aliasIndex.get(k.replace(/s$/, '')) || [];
+  return [...new Set(exact)].slice(0, 4);
+}
+const aliasHint = (name) => {
+  const hits = byAlias(name);
+  if (!hits.length) return '';
+  return ` ${hits.length === 1 ? `In SakaniUI that is \`${hits[0].name}\` (${hits[0].summary.replace(/\.$/, '')})` : `In SakaniUI that could be ${hits.map((h) => `\`${h.name}\``).join(' or ')}`}.`;
+};
+
 const brief = (c) => {
   const out = { name: c.name, kind: c.kind, category: c.category, import: c.import, since: c.since, summary: c.summary, requiredProps: c.contract.requiredProps };
   if (inInstalled(c) === false) out.availableInInstalled = false;
@@ -150,9 +166,19 @@ const verArg = (args, key) => {
 };
 const firstError = (...rs) => rs.find((r) => r.err);
 
-function score(c, terms) {
+function score(c, terms, phrase = '') {
   const hay = `${c.name} ${c.category ?? ''} ${c.summary} ${c.props.map((p) => p.name).join(' ')}`.toLowerCase();
   let s = 0;
+  // an alias is the name people use for this component: "dialog" finds Modal, "snackbar" finds Toast
+  const p = norm(phrase);
+  let aliasWords = 0;
+  for (const a of c.aliases || []) {
+    const na = norm(a);
+    if (na === p || na + 's' === p || na === p + 's') s += 60;
+    else if (na.length >= 4 && p.includes(na)) s += 25;
+    else if (!aliasWords && terms.length && a.toLowerCase().split(/[^a-z0-9]+/).some((w) => w.length >= 3 && terms.includes(w))) { s += 6; aliasWords = 1; } // loosely related: counts once
+  }
+  if (p && norm(c.name) === p) s += 100; // the real name always wins
   for (const t of terms) {
     if (c.name.toLowerCase() === t) s += 20;
     else if (c.name.toLowerCase().includes(t)) s += 8;
@@ -170,6 +196,16 @@ function distance(a, b) {
   return d[a.length][b.length];
 }
 
+/** `pct` for `percent`, `desc` for `description`: same first letter, every letter in order. */
+function isAbbreviation(short, full) {
+  const a = short.toLowerCase(), b = full.toLowerCase();
+  if (a.length < 2 || a.length >= b.length || a[0] !== b[0]) return false;
+  let i = 0;
+  for (const ch of b) if (ch === a[i]) i++;
+  return i === a.length;
+}
+const similar = (a, b) => distance(a.toLowerCase(), b.toLowerCase()) <= 2 || isAbbreviation(a, b) || isAbbreviation(b, a);
+
 function closest(name) {
   const n = name.toLowerCase();
   return manifest.components
@@ -424,7 +460,7 @@ function checkCode(source) {
       if (!c && !isUtility) {
         if (TYPE_LIKE.test(n.imported)) continue; // most likely a type export
         const near = closest(n.imported);
-        errors.push({ line: imp.line, message: `${n.imported} is not exported by @sakaniui/react.${near.length ? ` Did you mean: ${near.join(', ')}?` : ''} Use search_components.` });
+        errors.push({ line: imp.line, message: `${n.imported} is not exported by @sakaniui/react.${aliasHint(n.imported)}${near.length ? ` Did you mean: ${near.join(', ')}?` : ''} Use search_components.` });
       }
       if (c && inInstalled(c) === false) errors.push({ line: imp.line, message: `${c.name} was added in ${c.since}; the project has ${projectVersion}.` });
     }
@@ -454,6 +490,7 @@ function checkCode(source) {
         errors.push(at(`${a.name}=${JSON.stringify(a.value)} is not allowed. Use one of: ${p.values.map((x) => JSON.stringify(x)).join(', ')}.`));
       }
       { const tooNew = propTooNew(c, p, a.kind === 'string' ? a.value : undefined); if (tooNew) errors.push(at(tooNew)); }
+      for (const m of checkShape(c, p, a, new Map(el.attrs.map((x) => [x.name, x])))) errors.push(at(m));
       if (p.type === 'IconComponent') {
         if (a.kind === 'string') errors.push(at(`"${a.name}" takes an icon component, not a string: ${a.name}={IconName}.`));
         else if (a.kind === 'element' || a.kind === 'identifier') {
@@ -470,6 +507,89 @@ function checkCode(source) {
   return out;
 }
 
+/* ---------- literal shapes: field names inside inline object literals ---------- */
+/** Splits `text` at top-level commas (ignores commas inside brackets, braces, parentheses and strings). */
+function splitTopLevel(text) {
+  const parts = [];
+  let depth = 0, start = 0, quote = null;
+  for (let i = 0; i < text.length && parts.length < 2000; i++) {
+    const ch = text[i];
+    if (quote) { if (ch === '\\') i++; else if (ch === quote) quote = null; continue; }
+    if (ch === '"' || ch === "'" || ch === '`') { quote = ch; continue; }
+    if (ch === '{' || ch === '[' || ch === '(') depth++;
+    else if (ch === '}' || ch === ']' || ch === ')') depth--;
+    else if (ch === ',' && depth === 0) { parts.push(text.slice(start, i)); start = i + 1; }
+  }
+  parts.push(text.slice(start));
+  return parts.map((x) => x.trim()).filter(Boolean);
+}
+
+/** The keys written in an object literal `{ a: 1, 'b': 2, c, ...d }`. spread: it also contains `...x`. */
+function objectKeys(literal) {
+  const inner = literal.trim().slice(1, -1);
+  const keys = []; let spread = false;
+  for (const entry of splitTopLevel(inner)) {
+    if (entry.startsWith('...')) { spread = true; continue; }
+    const m = /^(?:'([^']+)'|"([^"]+)"|([A-Za-z_$][\w$]*))\s*(?::|\(|$)/.exec(entry);
+    if (m) keys.push(m[1] || m[2] || m[3]);
+    else spread = true; // computed key or something we cannot read: do not judge this object
+  }
+  return { keys, spread };
+}
+
+/** The object literals in an inline `[ {...}, {...} ]` (or a single `{...}`). Null when it is not an inline literal. */
+function inlineObjects(raw, collection) {
+  const t = raw.trim();
+  if (collection === 'array') {
+    if (!(t.startsWith('[') && t.endsWith(']'))) return null;
+    const items = splitTopLevel(t.slice(1, -1));
+    if (items.some((x) => !x.startsWith('{') || !x.endsWith('}'))) return items.filter((x) => x.startsWith('{') && x.endsWith('}')).length ? items.filter((x) => x.startsWith('{') && x.endsWith('}')) : null;
+    return items;
+  }
+  return t.startsWith('{') && t.endsWith('}') ? [t] : null;
+}
+
+/** Checks inline object literals against the prop's `shape`. Returns messages. */
+function checkShape(c, prop, attr, siblings) {
+  const sh = prop.shape;
+  if (!sh || attr.kind !== 'expression' || !attr.raw) return [];
+  const objs = inlineObjects(attr.raw, sh.collection);
+  if (!objs || !objs.length) return [];
+  const out = [];
+  const known = new Map(sh.fields.map((f) => [f.name, f]));
+  const list = sh.fields.map((f) => f.name + (f.required ? '' : '?')).join(', ');
+  objs.forEach((lit, idx) => {
+    const { keys, spread } = objectKeys(lit);
+    const where = sh.collection === 'array' ? `${prop.name}[${idx}]` : prop.name;
+    for (const k of keys) {
+      if (!known.has(k)) {
+        const near = sh.fields.map((f) => f.name).filter((f) => similar(f, k));
+        out.push(`${where}: "${k}" is not a field of ${sh.type}${near.length ? ` (did you mean "${near[0]}"?)` : ''}. Fields: ${list}.`);
+      }
+    }
+    if (!spread) for (const f of sh.fields) if (f.required && !keys.includes(f.name)) out.push(`${where}: missing required field "${f.name}" of ${sh.type}. Fields: ${list}.`);
+  });
+  // `key: keyof T`: the key must be a field of the rows given next to it (T[] sibling), when both are written inline
+  const keyField = sh.fields.find((f) => /^keyof T\b/.test(f.type));
+  if (keyField && sh.typeParameters && sh.typeParameters[0] === 'T') {
+    const rowsProp = c.props.find((p) => p.type === 'T[]');
+    const rowsAttr = rowsProp && siblings.get(rowsProp.name);
+    const rowObjs = rowsAttr && rowsAttr.kind === 'expression' ? inlineObjects(rowsAttr.raw || '', 'array') : null;
+    if (rowObjs && rowObjs.length) {
+      const rowKeys = new Set();
+      let rowsOpen = false;
+      for (const r of rowObjs) { const o = objectKeys(r); o.keys.forEach((k) => rowKeys.add(k)); if (o.spread) rowsOpen = true; }
+      if (!rowsOpen) {
+        for (const lit of objs) {
+          const kv = new RegExp(`(?:^|[{,\\s])${keyField.name}\\s*:\\s*['"]([^'"]+)['"]`).exec(lit);
+          if (kv && !rowKeys.has(kv[1])) out.push(`${prop.name}: ${keyField.name} "${kv[1]}" is not a field of the ${rowsProp.name} (${[...rowKeys].join(', ')}). It must be a key of the row type; for a column that is not data, add an optional field to the row type (see the recipe in get_component ${c.name}).`);
+        }
+      }
+    }
+  }
+  return out;
+}
+
 const READ_ONLY = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false };
 
 /* ---------- tools ---------- */
@@ -484,7 +604,7 @@ const tools = {
       const terms = q.value.toLowerCase().split(/\s+/).filter(Boolean);
       const hits = manifest.components
         .filter((c) => !k.value || c.kind === k.value)
-        .map((c) => [score(c, terms), c])
+        .map((c) => [score(c, terms, q.value), c])
         .filter(([s]) => s > 0)
         .sort((a, b) => b[0] - a[0])
         .slice(0, limit)
@@ -500,8 +620,10 @@ const tools = {
     run(args) {
       const n = strArg(args, 'name', { required: true }); if (n.err) return fail(n.err);
       const c = byName.get(n.value.toLowerCase());
-      if (!c) return fail(`No component named "${n.value}". Did you mean: ${closest(n.value).join(', ') || '(none close)'}? Use search_components.`);
+      if (!c) return fail(`No component named "${n.value}".${aliasHint(n.value)} ${closest(n.value).length ? `Did you mean: ${closest(n.value).join(', ')}? ` : ''}Use search_components.`.replace(/\s+/g, ' '));
       const out = { ...c, note: 'Native HTML attributes (className, style, aria-*, event handlers) are also accepted on the root element.' };
+      if (c.props.some((p) => p.shape)) out.shapeNote = 'A prop with a `shape` takes an object (or an array of objects) with exactly those fields; `required` fields must be present. In a generic shape, `keyof T & string` means the value must be a field of your own data type.';
+      if (c.recipes && c.recipes.length) out.recipeNote = 'See `recipes`: patterns the types alone do not teach, compiled against this release.';
       if (c.example) out.exampleNote = 'Start from `example`: it is type-checked against this release. Replace the placeholder text and values; keep the prop names and shapes.';
       if (c.props.some((p) => p.type === 'IconComponent')) out.iconNote = 'Icon props take the component itself (icon={IconTrash}), not an element. The example uses IconStar as a placeholder: find the real icon with search_icons.';
       if (inInstalled(c) === false) out.availableInInstalled = false;
@@ -564,7 +686,7 @@ const tools = {
       if (typeof props !== 'object' || Array.isArray(props)) return fail('"props" must be an object of prop name -> value.');
       if (Object.keys(props).length > 200) return fail('"props" has too many entries (max 200).');
       const c = byName.get(n.value.toLowerCase());
-      if (!c) return fail(`No component named "${n.value}". Did you mean: ${closest(n.value).join(', ') || '(none close)'}?`);
+      if (!c) return fail(`No component named "${n.value}".${aliasHint(n.value)} ${closest(n.value).length ? `Did you mean: ${closest(n.value).join(', ')}?` : ''}`.replace(/\s+/g, ' ').trim());
       const known = new Map(c.props.map((p) => [p.name, p]));
       const errors = [];
       const warnings = [];
@@ -688,7 +810,7 @@ function handle(msg) {
           protocolVersion: asked && PROTOCOL_VERSIONS.includes(asked) ? asked : PROTOCOL_VERSIONS[0],
           capabilities: { tools: { listChanged: false } },
           serverInfo: { name: 'sakaniui', title: 'SakaniUI', version: refVersion },
-          instructions: `SakaniUI ${refVersion}${projectVersion ? ` (project has ${projectVersion})` : ''}. Read-only reference. Look components up with search_components / get_component and start from their \`example\`; find icon names with search_icons (never guess them); run check_code on every snippet before you answer; style anything beyond props with the design tokens from get_tokens (CSS variables), not hard-coded colours or utility classes the project may not have; read get_guide when nothing fits.${note ? ` ${note}` : ''}`,
+          instructions: `SakaniUI ${refVersion}${projectVersion ? ` (project has ${projectVersion})` : ''}. Read-only reference. Look components up with search_components / get_component and start from their \`example\`; find icon names with search_icons (never guess them); search by the name you would normally use (dialog, snackbar, navbar, date picker) and it maps to the real component; run check_code on every snippet before you answer; style anything beyond props with the design tokens from get_tokens (CSS variables), not hard-coded colours or utility classes the project may not have; read get_guide when nothing fits.${note ? ` ${note}` : ''}`,
         } });
       }
       case 'ping':