@sakaniui/react 0.8.10 → 0.8.11

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
@@ -206,7 +211,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,25 @@
 
 All notable changes to `@sakaniui/react` are documented here.
 
+## 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'}.` };
 }
 
@@ -170,6 +170,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
@@ -454,6 +464,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 +481,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 ---------- */
@@ -502,6 +596,8 @@ const tools = {
       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.`);
       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;