tsquare 0.3.0 → 0.3.2

package/CHANGELOG.md

@@ -0,0 +1,91 @@
+# Changelog
+
+## 0.3.2
+
+- **`grow` on Select**, like Input: `select "State" grow` fills the rest of a row. Sonnet wrote it in 5 of 9 eval runs, its only remaining mistake; with it, every stored Sonnet text output is valid.
+- **Docs:** a new [Embedding](docs/embedding.md) page for Notion, GitHub and your own site, and the Radio page shows radios side by side (`stack row` + `radio`).
+- **Tests and CI:** a test suite (`npm test`), run on Node 20, 22 and 24 for every pull request, plus a check that eval scores, docs and the skill match what's committed.
+- `CHANGELOG.md` is now included in the npm package.
+
+## 0.3.1
+
+### Older wireframes are upgraded in one step
+
+- All support for older syntax now lives in one module (`upgradeWireframe`, `upgradeSpec`), run before parsing. The parser, catalog and renderer only know the current language.
+- **Links made before 0.3.0 render again** when a comment follows an element on the same line (`screen phone "Home"   # main`): the comment moves onto its own line. Text you write or paste still gets the error, so new comments go on their own line.
+- `decodeWireframe` returns the upgraded text, so a decoded link always means what it did when it was made.
+
+### Better suggestions for unknown icons
+
+- Common guesses that aren't Lucide names now suggest what was meant: `compose` → `square-pen`, `call` → `phone`, `person` → `user`, `bag` → `shopping-bag`, `notification` → `bell`, `close` → `x`.
+- Among equally close matches, the usual directions come first: `chevron` suggests `chevron-right, chevron-left, chevron-down, chevron-up`.
+- On a list item, `trailingIcon=chevron` (or `toggle`, `avatar`…) says to write `trailing=chevron`, since that's a kind, not an icon.
+
+## 0.3.0
+
+### Renamed: `icon` is now `leadingIcon` on Button and ListItem
+
+Buttons and list items take an icon on either side, so the prop names now say which side:
+
+| Before | Now |
+|---|---|
+| `button "Download" icon=download` | `button "Download" leadingIcon=download` |
+| (not possible) | `button "Next" trailingIcon=chevron-right` |
+| `listitem "Inbox" leading=icon icon=inbox` | `listitem "Inbox" leadingIcon=inbox` |
+| `listitem "Delete" trailing=icon trailingIcon=trash-2` | `listitem "Delete" trailingIcon=trash-2` |
+
+- **Nothing breaks.** The old `icon=` spelling still works on both components, so existing files and shared render links render the same. `tsquare fmt` rewrites it to `leadingIcon=`. The prompt, the skill and the docs only teach the new names.
+- **Buttons can have a trailing icon**, for Next, external links or dropdowns. Both sides work together.
+- `leading` and `trailing` on ListItem stay as before. They pick what fills each side (`avatar`, `image`, `checkbox`, `chevron`, `badge`, `toggle`, …). An icon or text value implies its kind, so `leading=icon` and `trailing=icon` are optional.
+- `icon` stays as it is on TabBar items (`{label=Home icon=house}`) and on the Icon component.
+
+### Changed: comments go on their own line
+
+A line that starts with `#` is a comment. Anywhere else, `#` is ordinary text, so order numbers, tags and hex colors need no quotes:
+
+```tsquare
+# the orders page
+screen desktop "Orders"
+  table columns=[Order, Customer] data=[[#1001, Ana Torres], [#1002, Ben Lee]]
+```
+
+- **Why:** comments used to start at any `#` after a space. That cut off `[#1001, Ana Torres]` and broke the table, which happened to Sonnet in 3 of 4 eval runs. Across 160 eval outputs, models never wrote a comment.
+- **Upgrading:** a comment after an element on the same line (`screen phone "Home"   # main`) is now an error that tells you to move it to its own line. Nothing is dropped silently.
+
+### Clearer errors for props on the wrong component
+
+When a word or prop belongs to a different component, the error now says which one:
+
+```
+Input: fullWidth is a Button prop, not an Input one; an Input already fills its width (width=… sets a fixed one), so remove it
+Card has no prop "border": border is a Stack prop, not a Card one
+```
+
+A prop or list wrapped onto its own line says where it belongs, instead of "unknown component":
+
+```
+trailing=…: props go on the same line as their component; move it to the end of line 15
+a list must stay on one line; join this to line 6
+```
+
+### Playground
+
+- A CodeMirror editor: highlighting, autocomplete for components, options, props, Lucide icons and accent colors, and problems underlined on their line.
+- Light and dark themes.
+- Zoom and pan, zoom to a single screen, full screen and a resizable split.
+- Copy link: share link, SVG/PNG image links, Markdown and HTML snippets.
+- An examples gallery with thumbnails.
+
+### Library
+
+- `encodeWireframe` / `decodeWireframe` for share and render links.
+- `boardLayout()` returns the board size and each screen's position.
+
+### List items: a value implies its kind
+
+- `trailingIcon=trash-2` without `trailing=icon` used to render nothing, silently. Now the value implies the kind.
+- A value that contradicts an explicit kind is an error that names the fix, for example: `leadingIcon only shows with leading=icon (this item has leading=avatar); remove one of them`.
+
+### Examples
+
+- New: `sign-in`, `dashboard`, `checkout` and `states`.

package/README.md

@@ -50,7 +50,7 @@ A wireframe can be embedded anywhere an image works (Notion, GitHub, docs sites)
 ![Login](https://tsquare.dev/svg/zNYwxDsIwEAT7vGJ…)
 ```
 
-The playground's **Copy link** menu makes these. The text is compressed into the URL, not encrypted, so anyone with the link can read it; see [privacy](https://tsquare.dev/privacy). `encodeWireframe` and `decodeWireframe` in the library produce and read the same links.
+The playground's **Copy link** menu makes these; [Embedding](docs/embedding.md) has the steps for Notion, GitHub and your own site. The text is compressed into the URL, not encrypted, so anyone with the link can read it; see [privacy](https://tsquare.dev/privacy). `encodeWireframe` and `decodeWireframe` in the library produce and read the same links.
 
 ## The language
 

package/dist/catalog.d.ts

@@ -341,6 +341,7 @@ export declare const componentDefinitions: {
             label: z.ZodOptional<z.ZodNullable<z.ZodString>>;
             value: z.ZodOptional<z.ZodNullable<z.ZodString>>;
             placeholder: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            grow: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
             width: z.ZodOptional<z.ZodNullable<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>>;
         }, z.core.$strip>;
         slots: never[];
@@ -864,6 +865,7 @@ export declare const catalog: import("@json-render/core").Catalog<{
                 label: z.ZodOptional<z.ZodNullable<z.ZodString>>;
                 value: z.ZodOptional<z.ZodNullable<z.ZodString>>;
                 placeholder: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+                grow: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
                 width: z.ZodOptional<z.ZodNullable<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>>;
             }, z.core.$strip>;
             slots: never[];
@@ -1035,21 +1037,3 @@ export declare function listItemEnds(p: {
     leading: string | undefined;
     trailing: string | undefined;
 };
-/**
- * Props renamed in 0.3.0, still accepted under their old names so existing
- * wireframes and render URLs keep working. The prompt, docs and autocomplete
- * only teach the new names, and `tsquare fmt` rewrites the old ones.
- */
-export declare const RENAMED_PROPS: Record<string, Record<string, string>>;
-/** Rewrites renamed props to their current names, in place. Safe to call more than once. */
-export declare function upgradeRenamedProps(spec: {
-    elements: Record<string, {
-        type: string;
-        props?: Record<string, unknown>;
-    }>;
-}): {
-    elements: Record<string, {
-        type: string;
-        props?: Record<string, unknown>;
-    }>;
-};

package/dist/chunks/{chunk-46MGJLGB.js → chunk-X46EDSCQ.js}

@@ -139,8 +139,25 @@ function iconNode(name) {
   return table[pascal(name)];
 }
 var isIcon = (name) => iconNode(name) !== void 0;
-function suggestIcons(name, limit = 3) {
+var GUESSES = {
+  call: ["phone"],
+  compose: ["square-pen", "pencil"],
+  person: ["user"],
+  bag: ["shopping-bag"],
+  notification: ["bell"],
+  notifications: ["bell"],
+  profile: ["user", "circle-user"],
+  envelope: ["mail"],
+  close: ["x"]
+};
+var DIRECTIONS = ["right", "left", "down", "up"];
+var directionRank = (n) => {
+  const i = DIRECTIONS.indexOf(n.split("-").pop());
+  return i < 0 ? DIRECTIONS.length : i;
+};
+function suggestIcons(name, limit = 4) {
   const q = name.toLowerCase().replace(/[_ ]/g, "-");
+  const guessed = GUESSES[q] ?? [];
   const words = q.split("-").filter((w) => w.length > 2);
   const maxEdits = Math.max(1, Math.floor(q.length / 3));
   const scored = [];
@@ -152,7 +169,8 @@ function suggestIcons(name, limit = 3) {
     const score = Math.min(wordScore, d <= maxEdits ? 3 * d / q.length : Infinity);
     if (score < Infinity) scored.push([n, score]);
   }
-  return scored.sort((a, b) => a[1] - b[1] || a[0].localeCompare(b[0])).slice(0, limit).map(([n]) => n);
+  const close = scored.sort((a, b) => a[1] - b[1] || directionRank(a[0]) - directionRank(b[0]) || a[0].localeCompare(b[0])).map(([n]) => n);
+  return [.../* @__PURE__ */ new Set([...guessed, ...close])].slice(0, limit);
 }
 function unknownIconMessage(name) {
   const close = suggestIcons(name);
@@ -415,6 +433,7 @@ var componentDefinitions = {
       label: o(z.string()),
       value: o(z.string()),
       placeholder: o(z.string()),
+      grow: o(z.boolean()).describe("Fill the remaining space in a row"),
       width: o(z.union([z.number(), z.string()])).describe("Fixed width, e.g. 320. Default fills the space.")
     }),
     slots: [],
@@ -514,23 +533,6 @@ function listItemEnds(p) {
     trailing: p.trailing ?? (p.trailingIcon ? "icon" : p.trailingText ? "text" : void 0)
   };
 }
-var RENAMED_PROPS = {
-  Button: { icon: "leadingIcon" },
-  ListItem: { icon: "leadingIcon" }
-};
-function upgradeRenamedProps(spec) {
-  for (const el of Object.values(spec.elements)) {
-    const renames = RENAMED_PROPS[el.type];
-    if (!renames || !el.props) continue;
-    for (const [from, to] of Object.entries(renames)) {
-      if (from in el.props) {
-        if (!(to in el.props)) el.props[to] = el.props[from];
-        delete el.props[from];
-      }
-    }
-  }
-  return spec;
-}
 
 // src/components.tsx
 import React, { Children, cloneElement, isValidElement } from "react";
@@ -1052,7 +1054,7 @@ function Input({ element, dir }) {
 }
 function Select({ element, dir }) {
   const p = element.props;
-  return /* @__PURE__ */ jsxs(Box, { style: { flexDirection: "column", gap: 6, ...fieldWidth(p.width, dir) }, children: [
+  return /* @__PURE__ */ jsxs(Box, { style: { flexDirection: "column", gap: 6, ...fieldWidth(p.width, dir), ...p.grow ? { flexGrow: 1 } : {} }, children: [
     /* @__PURE__ */ jsx(FieldLabel, { text: p.label }),
     /* @__PURE__ */ jsxs(Field, { children: [
       /* @__PURE__ */ jsx(Box, { style: { flexGrow: 1, color: p.value ? theme.ink : theme.muted }, children: p.value ?? p.placeholder ?? "Select\u2026" }),
@@ -1629,7 +1631,7 @@ function parseWireframeText(source) {
         if (t.kind !== "sym" && (c.isSym("=", 1) || c.isSym(":", 1))) {
           c.next();
           c.next();
-          const key = RENAMED_PROPS[info.name]?.[t.value] ?? t.value;
+          const key = t.value;
           if (!(key in info.props)) {
             const elsewhere = belongsElsewhere(info.name, key, true);
             issues.push({ line: lineNo, message: `${info.name} has no prop "${key}"` + (elsewhere ? `: ${elsewhere}` : "") + ` (its props: ${Object.keys(info.props).join(", ")})` });
@@ -1687,6 +1689,122 @@ function parseWireframeText(source) {
   return { spec: root ? { root, elements } : null, issues, lines };
 }
 
+// src/upgrade.ts
+var RENAMED_PROPS = {
+  Button: { icon: "leadingIcon" },
+  ListItem: { icon: "leadingIcon" }
+};
+var RENAMED_BY_WORD = new Map(Object.entries(RENAMED_PROPS).map(([type, renames]) => [type.toLowerCase(), renames]));
+function upgradeWireframe(text, options = {}) {
+  const lines = text.replace(/\r\n?/g, "\n").split("\n");
+  const out = [];
+  for (const line of lines) {
+    const trimmed = line.trim();
+    const component = trimmed.match(/^([A-Za-z][\w-]*)/)?.[1];
+    if (!component || trimmed.startsWith("```")) {
+      out.push(line);
+      continue;
+    }
+    const tokens = scanLine(line, component.length + (line.length - line.trimStart().length));
+    let upgraded = line;
+    let comment = "";
+    if (options.fromLink) {
+      const hash = tokens.find((t) => t.kind === "word" && t.depth === 0 && upgraded[t.start] === "#" && !t.afterEquals);
+      if (hash && !fillsMainText(component, tokens, hash)) {
+        comment = upgraded.slice(hash.start).trimEnd();
+        upgraded = upgraded.slice(0, hash.start).trimEnd();
+      }
+    }
+    const renames = RENAMED_BY_WORD.get(component.toLowerCase().replace(/[-_]/g, ""));
+    if (renames) {
+      for (const t of [...tokens].reverse()) {
+        if (t.kind === "key" && t.depth === 0 && t.start < upgraded.length && renames[t.text]) {
+          upgraded = upgraded.slice(0, t.start) + renames[t.text] + upgraded.slice(t.start + t.text.length);
+        }
+      }
+    }
+    if (comment) out.push(line.slice(0, line.length - line.trimStart().length) + comment);
+    out.push(upgraded);
+  }
+  return out.join("\n");
+}
+function upgradeSpec(spec) {
+  for (const el of Object.values(spec.elements)) {
+    const renames = RENAMED_PROPS[el.type];
+    if (!renames || !el.props) continue;
+    for (const [from, to] of Object.entries(renames)) {
+      if (from in el.props) {
+        if (!(to in el.props)) el.props[to] = el.props[from];
+        delete el.props[from];
+      }
+    }
+  }
+  return spec;
+}
+var PLAIN_WORD_MAIN_TEXT = ["avatar", "icon"];
+function fillsMainText(component, tokens, hash) {
+  if (!PLAIN_WORD_MAIN_TEXT.includes(component.toLowerCase())) return false;
+  for (const t of tokens) {
+    if (t === hash) return true;
+    if (t.depth > 0 || t.afterEquals || t.kind === "key") continue;
+    return false;
+  }
+  return false;
+}
+function scanLine(line, from) {
+  const tokens = [];
+  let depth = 0;
+  let afterEquals = false;
+  let i = from;
+  while (i < line.length) {
+    const c = line[i];
+    if (c === " " || c === "	") {
+      i++;
+      continue;
+    }
+    if (c === '"' || c === "'") {
+      let j2 = i + 1;
+      while (j2 < line.length && line[j2] !== c) j2 += line[j2] === "\\" ? 2 : 1;
+      tokens.push({ kind: "string", text: line.slice(i, j2 + 1), start: i, depth, afterEquals });
+      afterEquals = false;
+      i = j2 + 1;
+      continue;
+    }
+    if (c === "[" || c === "{") {
+      depth++;
+      afterEquals = false;
+      i++;
+      continue;
+    }
+    if (c === "]" || c === "}") {
+      depth = Math.max(0, depth - 1);
+      afterEquals = false;
+      i++;
+      continue;
+    }
+    if (c === ",") {
+      afterEquals = false;
+      i++;
+      continue;
+    }
+    if (c === "=" || c === ":") {
+      afterEquals = true;
+      i++;
+      continue;
+    }
+    let j = i;
+    while (j < line.length && !` 	,=[]{}":`.includes(line[j])) j++;
+    const text = line.slice(i, j);
+    let k = j;
+    while (line[k] === " " || line[k] === "	") k++;
+    const isKey = !afterEquals && (line[k] === "=" || line[k] === ":");
+    tokens.push({ kind: isKey ? "key" : "word", text, start: i, depth, afterEquals });
+    afterEquals = false;
+    i = j;
+  }
+  return tokens;
+}
+
 // src/render.ts
 import { readFile } from "node:fs/promises";
 import { createRequire } from "node:module";
@@ -1711,8 +1829,19 @@ var SpecError = class extends Error {
   }
   issues;
 };
+function listItemKindHint(el, path) {
+  const prop = path[0];
+  if (el.type !== "ListItem" || path.length !== 1 || prop !== "leadingIcon" && prop !== "trailingIcon") return void 0;
+  const side = prop === "leadingIcon" ? "leading" : "trailing";
+  const value = String(el.props?.[prop]);
+  let schema = componentDefinitions.ListItem.props.shape[side];
+  while (schema && ["optional", "nullable", "default"].includes(schema.def?.type)) schema = schema.def.innerType;
+  const kinds = schema?.options ?? [];
+  if (value === "icon" || !kinds.includes(value)) return void 0;
+  return `${value} is a ${side} kind, not an icon name: write ${side}=${value} instead of ${prop}=${value}`;
+}
 function checkSpec(spec) {
-  upgradeRenamedProps(spec);
+  upgradeSpec(spec);
   const issues = [];
   const result = catalog.validate(spec);
   if (!result.success) {
@@ -1738,7 +1867,7 @@ function checkSpec(spec) {
       const parsed = def.props.safeParse(el.props ?? {});
       if (!parsed.success) {
         for (const i of parsed.error.issues) {
-          issues.push(`${id}.props${i.path.length ? "." + i.path.join(".") : ""}: ${i.message}`);
+          issues.push(`${id}.props${i.path.length ? "." + i.path.join(".") : ""}: ${listItemKindHint(el, i.path) ?? i.message}`);
         }
       }
       for (const key of Object.keys(el.props ?? {})) {
@@ -1826,7 +1955,7 @@ function boardSize(spec) {
   return { width, height };
 }
 async function renderWireframeSvg(spec, opts = {}) {
-  upgradeRenamedProps(spec);
+  upgradeSpec(spec);
   if (!opts.skipValidation) {
     const issues = checkSpec(spec);
     if (issues.length) throw new SpecError(issues);
@@ -1849,7 +1978,7 @@ async function renderWireframePng(spec, opts = {}) {
 
 // src/compile.ts
 function compileWireframe(source) {
-  const parsed = parseWireframeText(source);
+  const parsed = parseWireframeText(upgradeWireframe(source));
   const issues = [...parsed.issues];
   if (parsed.spec) {
     for (const msg of checkSpec(parsed.spec)) {
@@ -2110,6 +2239,9 @@ export {
   PRIMARY_PROP,
   bareWords,
   parseWireframeText,
+  RENAMED_PROPS,
+  upgradeWireframe,
+  upgradeSpec,
   checkSpec,
   boardLayout,
   boardSize,

package/dist/cli.js

@@ -6,7 +6,7 @@ import {
   printWireframeText,
   renderWireframe,
   wireframePrompt
-} from "./chunks/chunk-46MGJLGB.js";
+} from "./chunks/chunk-X46EDSCQ.js";
 
 // src/cli.ts
 import { readFile, writeFile } from "node:fs/promises";

package/dist/icons.d.ts

@@ -4,9 +4,8 @@ export declare const iconNames: string[];
 export declare function iconNode(name: string): any;
 export declare const isIcon: (name: string) => boolean;
 /**
- * Close matches for an unknown name: near spellings ("serach" → search) and names that
- * share a word with it ("cart" → shopping-cart, "call" → phone-call).
- * There are no synonyms: "notification" won't find bell.
+ * Close matches for an unknown name: known guesses ("compose" → square-pen), near spellings
+ * ("serach" → search) and names that share a word with it ("cart" → shopping-cart).
  */
 export declare function suggestIcons(name: string, limit?: number): string[];
 export declare function unknownIconMessage(name: string): string;

package/dist/index.d.ts

@@ -3,6 +3,7 @@ export { renderWireframe, compileWireframe, formatIssues, WireframeError, type C
 export { wireframePrompt, repairPrompt } from "./prompt.js";
 export { printWireframeText as formatWireframe } from "./print.js";
 export { encodeWireframe, decodeWireframe, MAX_SHARED_TEXT } from "./share.js";
+export { upgradeWireframe, upgradeSpec, RENAMED_PROPS, type UpgradeOptions } from "./upgrade.js";
 export { renderWireframeSvg, renderWireframePng, checkSpec, boardSize, boardLayout, type BoardItem, type RenderWireframeOptions } from "./render.js";
 export { parseWireframeText, type TextIssue, type ParseResult } from "./text.js";
 export { catalog, componentDefinitions } from "./catalog.js";

package/dist/index.js

@@ -1,5 +1,6 @@
 import {
   DEVICES,
+  RENAMED_PROPS,
   WireframeError,
   boardLayout,
   boardSize,
@@ -16,8 +17,10 @@ import {
   renderWireframeSvg,
   repairPrompt,
   theme,
+  upgradeSpec,
+  upgradeWireframe,
   wireframePrompt
-} from "./chunks/chunk-46MGJLGB.js";
+} from "./chunks/chunk-X46EDSCQ.js";
 
 // src/share.ts
 import { deflateRawSync, inflateRawSync } from "node:zlib";
@@ -27,11 +30,13 @@ function encodeWireframe(text) {
 }
 function decodeWireframe(data) {
   if (!data.startsWith("z")) throw new Error(`unknown encoding "${data.slice(0, 1)}" (expected a "z" prefix)`);
-  return inflateRawSync(Buffer.from(data.slice(1), "base64url"), { maxOutputLength: MAX_SHARED_TEXT }).toString("utf8");
+  const text = inflateRawSync(Buffer.from(data.slice(1), "base64url"), { maxOutputLength: MAX_SHARED_TEXT }).toString("utf8");
+  return upgradeWireframe(text, { fromLink: true });
 }
 export {
   DEVICES,
   MAX_SHARED_TEXT,
+  RENAMED_PROPS,
   WireframeError,
   boardLayout,
   boardSize,
@@ -50,5 +55,7 @@ export {
   renderWireframeSvg,
   repairPrompt,
   theme,
+  upgradeSpec,
+  upgradeWireframe,
   wireframePrompt
 };

package/dist/playground/index.js

@@ -11,7 +11,7 @@ import {
   renderWireframePng,
   renderWireframeSvg,
   wireframePrompt
-} from "../chunks/chunk-46MGJLGB.js";
+} from "../chunks/chunk-X46EDSCQ.js";
 
 // src/playground/index.ts
 import { createServer } from "node:http";
@@ -242,18 +242,26 @@ var EXAMPLES = {
     checkbox "Checked" checked
     checkbox "Unchecked"`,
   Radio: `board
-  screen custom width=300 height=130
+  screen custom width=380 height=230
     radio "Selected" checked
     radio "Not selected"
-    radio "Not selected"`,
+    radio "Not selected"
+    text "Side by side: put them in a row" sm muted
+    stack row gap=20
+      radio "Standard" checked
+      radio "Express"
+      radio "Pickup"`,
   Toggle: `board
   screen custom width=300 height=100
     toggle "On" on
     toggle "Off" off`,
   Select: `board
-  screen custom width=320 height=170
+  screen custom width=380 height=260
     select "Country" value="Mexico"
-    select "Size" placeholder="Choose one" width=160`,
+    select "Size" placeholder="Choose one" width=160
+    stack row gap=12
+      input "City" placeholder="Monterrey" grow
+      select "State" value="Nuevo Le\xF3n" grow`,
   NavBar: `board
   screen custom width=380 height=240 padding=0 gap=0
     navbar "leading=menu" leading=menu actions=[search, bell]