a2ui-render-in-dsh 0.1.2 → 0.2.0

package/lib/index.js

@@ -5919,7 +5919,7 @@ var KNOWN_COMPONENTS = /* @__PURE__ */ new Set([
 ]);
 var CATALOG_DOC = `# a2ui_render authoring guide
 
-Forms: each question = one field; options -> MultipleChoice/Select; free answers -> TextField (multiline for long); offering suggestions? ALSO add a TextField for a custom answer; several questions = ONE card, ONE submit Button labeled with the action ("\u63D0\u4EA4", "\u786E\u8BA4\u5EFA\u6863"). Multiple items or several charts = ONE call with a Grid. Display-only cards (no Button) are fine. ALWAYS accompany the card with 1-3 sentences of normal prose in your reply (the takeaway, what to look at, or caveats) \u2014 a bare card with no text reads as unfinished; but never restate the card's data in text.
+Forms: each question = one field; options -> MultipleChoice/Select; free answers -> TextField (multiline for long); offering suggestions? ALSO add a TextField for a custom answer; several questions = ONE card, ONE submit Button labeled with the action ("\u63D0\u4EA4", "\u786E\u8BA4\u5EFA\u6863"). Multiple items or several charts = ONE call with a Grid. Display-only cards (no Button) are fine. Pair every card with 1-3 sentences of prose (takeaway/caveats) \u2014 never restate its data in text.
 
 ## Components (adjacency list; MUST include id "root"; only these names render)
 Layout:
@@ -5928,20 +5928,20 @@ Layout:
 - Card {children, title?} \xB7 List {children, direction?} \xB7 Divider {}
 - Tabs {tabs: ["\u540D"\u2026], children, bind?} \u2014 one child per tab; dataset switching / grouping
 - When {value: {"path": "/x"}, equals?, includes?, notEmpty?, children} \u2014 children render only when the bound value matches; use for follow-up fields (e.g. reason box when choice includes "\u5176\u4ED6")
-- Wizard {steps: ["\u6B65\u9AA4\u540D"\u2026], children, submitLabel?} \u2014 multi-step form: one child (a Column of fields) per step, built-in \u4E0A\u4E00\u6B65/\u4E0B\u4E00\u6B65/progress, the last step's submit sends ALL collected fields at once; use when a form has 5+ questions
+- Wizard {steps: ["\u6B65\u9AA4\u540D"\u2026], children, submitLabel?} \u2014 multi-step form: one child (Column of fields) per step, built-in prev/next/progress, last step submits ALL fields; use for 5+ questions
 Content (Chart/Mermaid/Image auto-get fullscreen zoom; don't oversize):
 - Text {text, variant?: "h1"|"h2"|"h3"|"body"|"caption"|"strong"}
-- Markdown {text} \u2014 rich long-form text (headings, bold/italic, links, lists, quotes, fenced code, $...$ math); USE instead of stacking Text components for any multi-paragraph explanation inside a card
+- Markdown {text} \u2014 rich long-form (headings, bold/italic, links, lists, quotes, fenced code, $...$ math); use for any multi-paragraph text instead of stacked Texts
 - Image {url, alt?, width?, height?} \xB7 Tag {text, color?: "blue"|"green"|"red"|"orange"|"gray"}
 - Icon {name, size?, color?} \u2014 check x plus minus warning info star heart calendar clock location user search settings mail phone home file link download upload play music image cart tag gift trophy fire bolt sun moon cloud thumbs-up
 - Math {tex, block?} \u2014 KaTeX. ALL math notation goes here, matrices included: never raw arrays like [[2,1],[0,3]] in Text \u2014 write {"tex": "\\\\begin{pmatrix}2&1\\\\\\\\0&3\\\\end{pmatrix}", "block": true} (row sep \\\\\\\\). Equation above its Anim when animating.
 - Mermaid {code, caption?} \u2014 flowchart ("graph TD; A[\u5F00\u59CB]-->B{\u5224\u65AD}"), mindmap, sequenceDiagram, gantt, pie, stateDiagram
 - Chart {option, height?, functions?, params?, xMin?, xMax?, yClip?} \u2014 ECharts (viewers get a PNG-download button). Data mode: standard option verbatim. Function mode: functions=[{"expr":"tan(x)","name"?}], xMin/xMax (\xB110), yClip (10); sampled automatically, asymptotes break \u2014 NEVER hand-enumerate curve points. Ops: + - * / ^ %, sin cos tan cot sec csc asin acos atan sinh cosh tanh sqrt cbrt abs exp ln log2 log10 floor ceil round sign min max pow atan2, pi/e, x. params: {"mu":{"path":"/mu"}} injects bound values as constants \u2014 pair with Slider for live curves.
-- Table {columns, rows, caption?, sortable?, filter?, pageSize?} \u2014 any 2+ item attribute comparison beats prose. Interactive by default: click-to-sort headers, auto filter box and pagination on long data, copy/CSV export built in. Dict binding: rows={"source":{"k1":[[\u2026]],\u2026},"pick":{"path":"/k"}} + a Select/Tabs on that path switches datasets live.
+- Table {columns, rows, caption?, sortable?, filter?, pageSize?} \u2014 for any 2+ item comparison; sort/filter/pagination/copy/CSV are automatic. Dict binding: rows={"source":{"k1":[[\u2026]],\u2026},"pick":{"path":"/k"}} + a Select/Tabs on that path switches datasets live.
 - Stat {label, value, unit?, trend?, hint?} \u2014 KPI tile ("+12%" green / "-3%" red); several in a Grid
 - Steps {items: [{title, description?, status?: "done"|"current"|"pending"}]} \u2014 linear procedures; Mermaid flowchart only when it BRANCHES
 - Progress {value, max?, label?} \xB7 Timeline {items: [{time?, title, description?}]} (past events; Steps = to-dos)
-- CodeBlock {code, language?, title?} \u2014 always for code snippets
+- CodeBlock {code, language?, title?} \u2014 ALWAYS for code, including quiz/form stems: compose Text(\u9898\u5E72) + CodeBlock(\u4EE3\u7801) + inputs; NEVER inline code in a Text prop
 - Video {url, poster?\u2026} \xB7 Audio {url, title?} \xB7 Flashcard {front, back} \xB7 Countdown {to?: "2026-09-01 10:00", seconds?, label?}
 - Map {data: [{name: "\u5E7F\u4E1C", value: 100}\u2026], title?, unit?, height?} \u2014 China province choropleth (regional sales/distribution); province names in Chinese
 - ImageCompare {before, after} \u2014 drag-divider image comparison (before/after, A/B)
@@ -5955,15 +5955,15 @@ Interaction:
 - Select {options, bind, label?, placeholder?, multiple?, maxAllowedSelections?, disabled?} \u2014 dropdown; single stores value, multiple stores array
 - Rate {bind, label?, max?, disabled?} \u2014 stars 1..max (5)
 - Slider {bind, label?, min?, max?, step?, unit?, disabled?} \u2014 numbers in a range; parameter exploration with Chart params
-- Calc {expr, inputs: {name: {"path": "/x"}\u2026}, out, digits?} \u2014 invisible derived number written at out; chainable (one Calc's out feeds another's inputs). digits rounds DISPLAY values only \u2014 omit on intermediate results (rates, ratios) to keep full precision
+- Calc {expr, inputs: {name: {"path": "/x"}\u2026}, out, digits?} \u2014 invisible derived number written at out; chainable. digits rounds display only \u2014 omit on intermediates to keep precision
 - CheckBox {label, bind, disabled?} \xB7 TextField {label?, placeholder?, multiline?, kind?: "text"|"number"|"date"|"time", bind, disabled?}
-- Upload {bind?, label?, max?} \u2014 image picker; chosen images are SENT TO YOU with the submission (screenshots, photos, receipts \u2014 use whenever seeing an image would help)
-- Calendar {bind, label?, min?, max?} \u2014 month-view date picker (friendlier than kind:"date" for choosing among nearby dates)
+- Upload {bind?, label?, max?} \u2014 image picker; chosen images are SENT TO YOU with the submission (use whenever seeing an image helps)
+- Calendar {bind, label?, min?, max?, range?} \u2014 month-view date picker; range: true picks start+end (value ["\u8D77","\u6B62"])
 - RankList {items: ["\u9009\u9879"\u2026], bind, label?} \u2014 user reorders by priority; submits the ordered list
 - Signature {label?} \u2014 handwritten signature pad; the drawing is sent to you as an image
 - EditableTable {columns, rows, bind, label?} \u2014 user edits cells, the whole grid submits at bind
-- Suggestions {items: ["\u8FFD\u95EE1", "\u8FFD\u95EE2"\u2026]} \u2014 tappable follow-up questions below an answer; tapping sends that question as the user's message. ADD 2-4 to display-only cards when natural next questions exist
-Preselect by seeding dataModel at bind paths; disable via disabled on a control or an option.
+- Suggestions {items: ["\u8FFD\u95EE1"\u2026]} \u2014 tappable follow-ups; a tap sends that question as the user's message. ADD 2-4 to display-only cards
+Preselect by seeding dataModel at bind paths; disable via disabled on a control or option. Any input takes required: true \u2014 submit is blocked (field highlighted) until filled; give required fields labels.
 
 ## Reactivity
 Bindings are live: inputs write bind paths, every {"path"} display binding updates instantly.
@@ -5974,7 +5974,7 @@ Bindings are live: inputs write bind paths, every {"path"} display binding updat
 Seed every bound path in dataModel.
 
 ## Scenario map
-Input collection -> form (TextField/kind date|time|number, MultipleChoice 2-7 options, Select for long lists, CheckBox, Rate). Decisions -> Grid Cards + Table; lone confirm Button gets submit:true. Data -> Chart (trend/rank/share) + Stat tiles + Table. Learning -> MultipleChoice quizzes (options may be formulas), Math, Chart functions (+Slider), Anim, mindmap, Flashcard, CodeBlock. Procedures -> Steps (Timeline for history, Progress for completion, gantt/Table for schedules). Entertainment -> Grid recommendation cards, Rate, polls via MultipleChoice.
+Input collection -> form (TextField/kind date|time|number, MultipleChoice 2-7 options, Select for long lists, CheckBox, Rate). Decisions -> Grid Cards + Table; lone confirm Button gets submit:true. Data -> Chart (trend/rank/share) + Stat tiles + Table; regional -> Map. Learning -> MultipleChoice quizzes (options may be formulas), Math, Chart functions (+Slider), Anim, mindmap, Flashcard; \u8BFB\u4EE3\u7801\u9898 = Text(\u9898\u5E72) + CodeBlock(\u4EE3\u7801) + TextField. Procedures -> Steps (Timeline for history, Progress for completion, gantt/Table for schedules). Entertainment -> Grid recommendation cards, Rate, polls via MultipleChoice.
 
 ## Inline math
 Any text prop (Text, option labels/descriptions, Table cells, Steps, Flashcard, Anim notes) embeds formulas with $...$, e.g. option {"label": "$\\\\frac{x^2}{2}+C$"}. Math component = display equations; $...$ = math inside sentences/choices. In math quizzes, option labels with fractions/roots/integrals/exponents SHOULD be $...$ formulas (e.g. {"label": "$3x^2$"}), not Unicode approximations.
@@ -5983,15 +5983,15 @@ Any text prop (Text, option labels/descriptions, Table cells, Steps, Flashcard,
 "bind" = write path WITHOUT leading slash ("answer", "form/name"). Display reads use {"path": "/answer"} (WITH slash). Avoid literal string props starting with "/".
 
 ## Submission
-Button click sends a plain-language user message: button label + chosen values ("\u63D0\u4EA4\u7B54\u6848\uFF1AB\u3001C"; multi-line for forms); MultipleChoice arrives as option LABELS. action.event.context optional (touched fields auto-included); entries may be literals or {"path": "/x", "label": "\u540D"}. Locking (submitMode "once", default): cards WITH inputs lock after submit and stay recorded; input-less cards' buttons are query buttons, always clickable; per-Button submit: true|false overrides; "multi" never locks. After an interactive card, end your turn with one short line; a plain typed reply also counts as the answer. Uploaded images/signatures arrive attached to the submission message. Users can hit \u91CD\u65B0\u586B\u5199 on a locked card \u2014 the corrected submission is prefixed \uFF08\u4FEE\u6B63\uFF09.
+Button click sends a plain-language user message: button label + chosen values ("\u63D0\u4EA4\u7B54\u6848\uFF1AB\u3001C"; multi-line for forms); MultipleChoice arrives as option LABELS. action.event.context optional (touched fields auto-included); entries may be literals or {"path": "/x", "label": "\u540D"}. Locking (submitMode "once", default): cards WITH inputs lock after submit and stay recorded; input-less cards' buttons are query buttons, always clickable; per-Button submit: true|false overrides; "multi" never locks. A plain typed reply also counts as the answer. Uploads/signatures arrive attached to the submission. \u91CD\u65B0\u586B\u5199 unlocks a locked card; corrections arrive prefixed \uFF08\u4FEE\u6B63\uFF09.
 
 ## Updating a rendered card
-a2ui_render returns a surfaceId. Call a2ui_update {surfaceId, components?, dataModel?} to change that card IN PLACE \u2014 replace/add components by id, overwrite dataModel keys. Use for long-task progress (render a Progress card first, then update /percent as you work), corrections, and appending results \u2014 never render a duplicate card for the same content. Cards render progressively while you stream \u2014 no need to keep them small.
+a2ui_render returns a surfaceId. Call a2ui_update {surfaceId, components?, dataModel?} to change that card IN PLACE \u2014 replace/add components by id, overwrite dataModel keys. Use for long-task progress, corrections, appended results \u2014 never render a duplicate card. Cards stream progressively; don't shrink them.
 
 ## Example (quiz)
 components=[{"id":"root","component":"Column","children":["q","opts","btn"]},{"id":"q","component":"Text","variant":"h3","text":"\u2026\u9898\u76EE\u2026"},{"id":"opts","component":"MultipleChoice","bind":"answer","maxAllowedSelections":1,"options":[{"label":"A\u2026","value":"A"},{"label":"B\u2026","value":"B"}]},{"id":"btn","component":"Button","label":"\u63D0\u4EA4\u7B54\u6848","variant":"primary","action":{"event":{"name":"submit"}}}]
 dataModel={"answer":[]}`;
-var RENDER_DESCRIPTION = "Render a UI card (A2UI) inline in the chat. Judge EVERY reply semantically from user intent (they never say \u5361\u7247/\u56FE\u8868/\u52A8\u753B): (1) UTILITY \u2014 would a card serve any of UI's three purposes better than prose? ACT \u64CD\u4F5C: the user must answer/choose/fill/adjust/rate/confirm -> form. BROWSE \u6D4F\u89C8: the user wants to see/scan data or many items \u2014 statistics, rankings, distributions, trends, comparisons, or picking among several recommended items \u2014 movies/products/places/plans -> one Card per item in a Grid, or a Table (\u770B/\u67E5/\u5BF9\u6BD4/\u63A8\u8350\u51E0\u4E2A IS a card ask; dated or approximate data never cancels the card \u2014 chart the best you know, label the period, caveat in prose). UNDERSTAND \u7406\u89E3: structure, notation or MOTION aids comprehension \u2014 math, code, flows, schedules, stepwise processes, what-if exploration, and anything that unfolds over time (algorithms, simulations, physical processes) -> step animation. FEEDBACK \u53CD\u9988: before starting multi-step work (3+ tool steps), render a Progress/Steps card, a2ui_update it as steps complete, and put the final results in the card \u2014 never as a markdown table in prose. None of these (opinions, narration, short answers, translations, chat) -> prose. (2) FORM \u2014 fit each part and compose freely in one card: input->form, comparison->table, trend->chart, regional data->map, math->formula, code->code block, procedure->steps, relations->diagram, watchable process->animation, what-if->sliders+live chart. Cards PAIR with prose, never replace it: give your takeaway/analysis in 1-3 sentences of normal text and keep structured content in the card; don't duplicate data in both. Before your FIRST call in a conversation, call a2ui_catalog and follow it \u2014 never guess component names. After an interactive card, end your turn; the submission arrives as a plain-language user message.";
+var RENDER_DESCRIPTION = "Render a UI card (A2UI) inline in the chat. Judge EVERY reply from user intent (they never say \u5361\u7247/\u56FE\u8868): would a card serve any of UI's FOUR purposes better than prose? ACT \u64CD\u4F5C: user must answer/choose/fill/adjust/confirm -> form card. BROWSE \u6D4F\u89C8: user wants to see/scan data or items \u2014 statistics, rankings, distributions, trends, comparisons, multi-item recommendations -> chart/table/map/Grid of item cards; \u770B/\u67E5/\u5BF9\u6BD4/\u63A8\u8350\u51E0\u4E2A IS a card ask, and dated or approximate data never cancels the card \u2014 chart the best known, label the period, caveat in prose. UNDERSTAND \u7406\u89E3: structure, notation or motion aids comprehension \u2014 math, code, flows, what-if exploration, and time-unfolding processes (algorithms, simulations) -> step animation. FEEDBACK \u53CD\u9988: before multi-step work (3+ tool steps), render a Progress/Steps card, a2ui_update it as steps complete, final results into the card (not markdown tables in prose). None of the four (opinions, narration, short answers, translations, chat) -> prose. Compose freely \u2014 one card can mix form/chart/table/formula parts. Cards PAIR with prose: 1-3 sentences of takeaway as normal text, structured content in the card, no duplication. Call a2ui_catalog BEFORE your first render in a conversation \u2014 never guess component names. After an interactive card, end your turn; the submission arrives as a plain-language user message.";
 var CATALOG_DESCRIPTION = "Returns the full component catalog and authoring rules for a2ui_render. Call ONCE before your first render in a conversation; the result stays in context \u2014 call again only if it is no longer visible.";
 function apply(ctx) {
   ctx.tools.register(defineTool({
@@ -6045,13 +6045,21 @@ function apply(ctx) {
       }
       const byId = new Map(components.filter((n) => n !== null && typeof n === "object" && n.id !== void 0).map((n) => [n.id, n]));
       const reachable = /* @__PURE__ */ new Set();
+      const missing = /* @__PURE__ */ new Set();
       const queue = ["root"];
       while (queue.length > 0) {
         const id = queue.pop();
         if (reachable.has(id)) continue;
         reachable.add(id);
         const node = byId.get(id);
-        for (const child of Array.isArray(node?.children) ? node.children : []) queue.push(child);
+        if (node === void 0) {
+          missing.add(id);
+          continue;
+        }
+        for (const child of Array.isArray(node.children) ? node.children : []) queue.push(child);
+      }
+      if (missing.size > 0) {
+        throw new Error(`a2ui_render: children reference undefined component id(s) ${[...missing].map((id) => `"${id}"`).join(", ")} \u2014 define them or fix the reference.`);
       }
       const orphans = [...byId.keys()].filter((id) => !reachable.has(id));
       if (orphans.length > 0) {
@@ -6070,7 +6078,7 @@ function apply(ctx) {
   }));
   ctx.tools.register(defineTool({
     name: "a2ui_update",
-    description: "Update a card you previously rendered, IN PLACE: pass the surfaceId returned by a2ui_render, plus replacement/new components (matched by id) and/or dataModel value changes. Use for progress updates during long tasks, corrections, and appending content \u2014 instead of rendering a duplicate card.",
+    description: "Update a rendered card IN PLACE by its surfaceId (from a2ui_render): components replace/add by id, dataModel overwrites keys. For progress, corrections, appended results \u2014 never render a duplicate card.",
     parameters: {
       surfaceId: { type: "string", required: true, description: "The surfaceId returned by the a2ui_render call to update." },
       components: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "a2ui-render-in-dsh",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "A2UI interactive cards for the dsh web UI: the agent renders clickable interfaces (quizzes, forms, product cards) via @ant-design/x-card, and user interactions flow back to the agent as answers.",
   "author": "sondge <fengshangjie@lilybearing.com>",
   "license": "MIT",
@@ -52,15 +52,18 @@
   "scripts": {
     "build": "node scripts/build.mjs",
     "watch": "node scripts/build.mjs --watch",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build",
+    "test": "node test/run.mjs"
   },
   "devDependencies": {
     "@ant-design/x-card": "^2.9.0",
     "@deepseek-ai/dsh-tools": "^0.1.1-rc.2",
     "echarts": "^6.1.0",
     "esbuild": "^0.25.0",
+    "jsdom": "^30.0.1",
     "katex": "^0.18.4",
     "mermaid": "^11.17.0",
+    "playwright": "^1.62.1",
     "react": "^18.2.0",
     "react-dom": "^18.2.0"
   },
@@ -75,6 +78,5 @@
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"
-  },
-  "dependencies": {}
+  }
 }