hd-garden 0.13.3 → 0.14.2

package/docs/handbook/en/reference/html.md

@@ -1,62 +0,0 @@
----
-title: Component reference · html
-navTitle: html
-description: Run a self-contained HTML, CSS, and JavaScript demo inside a sandboxed iframe.
-section: reference
-order: 7
-badge: html
----
-
-[← Component reference](/garden/en/reference) · [Usage: html](/garden/en/components/html)
-
-## Examples
-
-```garden html
-title: Character Count Widget
-code: |
-  <!doctype html>
-  <html lang="en">
-  <head>
-    <meta charset="utf-8" />
-    <style>
-      body { margin: 0; padding: 16px 18px; font: 14px/1.6 system-ui, sans-serif; color: #1b1a18; background: #faf9f5; }
-      input { width: 100%; box-sizing: border-box; padding: 8px 10px; border: 1px solid #d5d1c8; border-radius: 6px; font: inherit; background: #fff; color: #1b1a18; }
-      .meta { margin-top: 10px; color: #6e6b64; font-variant-numeric: tabular-nums; }
-      strong { color: #1b1a18; }
-    </style>
-  </head>
-  <body>
-    <input id="txt" value="Keep your posts in a Git repository and push to deploy." aria-label="Sample text input" />
-    <div class="meta">Characters: <strong id="count">55</strong></div>
-    <script>
-      const input = document.getElementById("txt");
-      const count = document.getElementById("count");
-      input.addEventListener("input", () => { count.textContent = String(input.value.length); });
-    </script>
-  </body>
-  </html>
-```
-
-## Syntax
-
-````markdown
-```garden html
-src:     # either this or code, path
-code: |  # either this or src, HTML
-title:   # recommended, frame title
-```
-````
-
-## Fields
-
-Fence header: ` ```garden html ` (snippet trigger `;ghtml`). Invalid YAML or unknown top-level keys report `garden-yaml` on the block.
-
-| Field | Required | Default | Allowed Values & Limits | Description |
-| :--- | :--- | :--- | :--- | :--- |
-| `src` | Either `src` or `code` | none | relative path (e.g. `./demo.html`) | Path to a standalone `.html` file inside the post's sidecar directory |
-| `code` | Either `code` or `src` | HTML body below `---` or `""` | multiline HTML string | Inline HTML markup (runs inside a sandboxed `iframe` and resizes to fit its content when `<script>` is present; HTML can also be placed below a `---` separator) |
-| `title` | Recommended | `"HTML"` | string | Frame header title and accessible `iframe` title |
-
-## Limits & errors
-
-- Apart from the shared `garden-yaml`, this component has no error codes of its own; values marked "not checked" in the table never report an error.

package/docs/handbook/en/reference/interactive.md

@@ -1,71 +0,0 @@
----
-title: Component reference · interactive
-navTitle: interactive
-description: Let readers drag sliders or switches to recalculate formulas and charts in real time.
-section: reference
-order: 8
-badge: interactive
----
-
-[← Component reference](/garden/en/reference) · [Usage: interactive](/garden/en/components/interactive)
-
-## Examples
-
-```garden interactive #reading-time
-caption: "Example: estimate reading time from word count, reading speed, and image count. Numbers are illustrative only."
----
-<State words={6000} speed={400} images={8} />
-<Let textMinutes={round(words / speed)} />
-<Let imageMinutes={round(images * 12 / 60)} />
-<Let parts={[{ part: "Prose", minutes: textMinutes }, { part: "Images", minutes: imageMinutes }]} />
-
-<Slider bind="words" label="Word count" min={1000} max={20000} step={500} unit="words" />
-<Slider bind="speed" label="Reading speed" min={200} max={800} step={50} unit="wpm" />
-<Slider bind="images" label="Image count" min={0} max={30} step={1} unit="images" />
-
-<Stat label="Example: estimated reading time" value={textMinutes + imageMinutes} unit="min" hint="Counting 12 seconds per image" />
-<Chart data={parts} x={part} yLabel="min">
-  <Bar y={minutes} label="Example" />
-</Chart>
-```
-
-## Syntax
-
-````markdown
-```garden interactive #<id>
-caption:               # required, default reading
-intent: |              # optional, original idea
-expect:                # optional, assertions
----                    # tags go below
-<State ... />          # required, state
-<Let ... />            # optional, derived values
-<Slider bind="..." />  # input control
-<Stat ... />           # output
-```
-````
-
-## Fields
-
-Fence header: ` ```garden interactive #<id> ` (snippet trigger `;ginteractive`). YAML metadata goes above `---` and declarative UI tags go below `---` (run `npx garden ui catalog` to inspect all internal tags in `.garden/ui-catalog.html`); invalid YAML or unknown top-level keys report `garden-yaml` on the block.
-
-| Field or Tag | Required | Default | Allowed Values & Limits | Description |
-| :--- | :--- | :--- | :--- | :--- |
-| `#<id>` / `id` | Required | none | lowercase letters, digits, hyphens `^[a-z0-9]+(?:-[a-z0-9]+)*$`, unique per post; missing or invalid reports `ui-id` | Written on the fence line (such as `#reading-time`) or in the YAML header |
-| `caption` | Required | none | non-empty one-sentence takeaway string; missing or empty reports `ui-caption` | States the conclusion visible in the default state |
-| `intent` | Optional | none | string (non-string reports `ui-header`; modified `intent` without recompiling reports a `ui-stale` warning) | Original natural-language prompt this block was compiled from |
-| `expect` | Optional | none | `{ given: {...}, <name>: <expected> }[]` (non-array reports `ui-header`; malformed or failing assertion reports `ui-expect`) | Numeric assertions verified by `npx garden ui check` (use `{ value, tol }` for approximate values) |
-| `<State />` | Required | none | lowercase-initial prop names with number, string, or boolean literal defaults (invalid name, duplicate name, or non-literal reports `ui-prop`) | Declares mutable state variables and default values, e.g. `<State words={6000} />` |
-| `<Let />` | Optional | none | expression props (unknown identifier or disallowed syntax reports `ui-expr`, cyclic dependency reports `ui-cycle`, evaluation failure reports `ui-eval`, single-multiplication-only block reports `interactive-trivial`) | Computes derived numbers, arrays, or objects from state |
-| `<Data />` | Optional | none | `name` (valid identifier) and `src` (`.csv` or `.json` inside the post's sidecar directory; out-of-bounds, missing, or invalid file reports `ui-data`) | Loads a sidecar data file |
-| `<Slider />` / `<Stepper />` / `<Toggle />` | At least one input control | `Slider`: `scale="linear"`, `snap="none"` (`"pow2"` when `scale="log"` and bounds are powers of 2); `Stepper`: `step={1}` | `bind` must reference a declared state variable of matching type (otherwise `ui-bind`); `max <= min`, `scale="log"` with `min <= 0`, or default outside `min..max` reports `ui-prop` | Input controls bound to numeric or boolean state |
-| `<Choice />` / `<Checklist />` / `<Button />` | Optional input controls | `Button`: `tone="plain"` | `<Choice>` `options` must have `2` to `8` items (outside `2`–`8` reports `ui-limit`, default not in `options` reports `ui-prop`); `<Checklist>` `items` must have `1` to `30` items (outside `1`–`30` reports `ui-limit`); `<Button>` requires exactly one of `set` or `reset` (otherwise `ui-prop`) | Segmented/dropdown selector, interactive checklist, and state button |
-| `<Stack />` / `<Columns />` / `<Tabs />` / `<Steps />` | Optional layout containers | `Stack`: `gap={3}`, `direction="col"`; `Columns`: `gap={3}`, `min={220}`; `Steps`: `autoplay={false}` | `gap` `0`–`4` integer, `Columns.min` `160`–`400`, `Steps.autoplay` `false` or `>= 800` (violation reports `ui-prop`); `<Columns>` max `4` children, `<Tabs>` `2`–`6` `<Tab>` children, `<Steps>` `2`–`24` `<Step>` children (outside limits reports `ui-limit`, wrong child tag reports `ui-children`, prose-only steps with no state changes report `steps-prose`) | Layout containers (for `<Each>` over `200` items, only the first `200` are shown with no `ui-limit`; total expanded elements across the block max `200`, exceeding reports `ui-limit`) |
-| `<Stat />` / `<Meter />` / `<Chart />` / `<Pie />` | At least one output view | `Stat`: `tone="plain"`, `size="md"`; `Meter`: `tone="accent"`; `Chart`: `samples={64}`, `yScale="linear"`, `height={200}` | `<Meter>` `parts` max `5` segments, `<Pie>` `1`–`8` `<Slice>` children, `<Chart>` `1`–`4` series children and `data` max `2000` rows (exceeding reports `ui-limit`); `<Chart>` `samples` `2`–`200` and `height` `120`–`480` (outside range reports `ui-prop`) | Displays computed metrics, progress meters, donut charts, and function/data charts |
-| `<Table />` / `<Grid />` / `<Image />` / `<Code />` / `<Diagram />` / `<Sandbox />` | Optional display views | none | `<Table>` max `50` rows, `<Grid>` `cols` max `16` columns and `1`–`16` `<Row>` children, `<Image>` max `12` `<Hotspot>` children, `<Code>` max `60` lines, `<Sandbox>` `html` max `12000` chars and `css`/`js` max `8000` chars each (exceeding reports `ui-limit`; unknown tag reports `ui-component`; headings, code fences, HTML, or Markdown images in the body report `ui-markdown`; JSX syntax or spread props report `ui-syntax`) | Tables, inspection grids, hotspot images, code walkthroughs, Mermaid state diagrams, and self-contained sandboxes |
-
-## Limits & errors
-
-- Header: `ui-id` (missing or malformed id), `ui-caption` (missing caption), `ui-header` (`intent` not a string or `expect` not a list), `ui-expect` (malformed or failing assertion), `ui-stale` (warning: the idea changed but was not recompiled).
-- Tags: `ui-prop`, `ui-expr`, `ui-cycle`, `ui-eval`, `ui-data`, `ui-bind`, `ui-limit`, `ui-children`, `ui-component`, `ui-markdown`, `ui-syntax`; see the table above for what triggers each.
-- Whole block: `interactive-trivial` (a single simple multiplication), `steps-prose` (steps that are only prose, with no state change).
-- Run `npx garden ui check` to get a fix prompt.

package/docs/handbook/en/reference/list.md

@@ -1,72 +0,0 @@
----
-title: Component reference · list
-navTitle: list
-description: Pair line icons with short observations in a compact card, or add headings and multi-paragraph notes for divided steps.
-section: reference
-order: 11
-badge: list
----
-
-[← Component reference](/garden/en/reference) · [Usage: list](/garden/en/components/list)
-
-## Examples
-
-```garden list
-items:
-  - icon: search
-    text: Searches for this month's title
-  - icon: eye
-    text: Reads 3 reviews
-  - icon: heart
-    text: Saves the event page
-  - icon: chat
-    text: Asks in the group chat whether listening only is fine
-```
-
-```garden list
-items:
-  - icon: flask
-    title: "Experiment 1: is one book a month too much?"
-    text:
-      - Pick a novella and a long novel for the first two meetings, and record how many people finish.
-      - If the share drops clearly, read only the first half next time.
-  - icon: chat
-    title: "Experiment 2: how do we get first-timers talking?"
-    text:
-      - Open half of the meetings with one sentence from each person, and the other half with free discussion.
-      - Compare how often first-timers speak.
-  - icon: bell
-    title: "Experiment 3: how early should the reminder go out?"
-    text:
-      - Send the reminder three days before one meeting and one day before another, and compare turnout.
-```
-
-## Syntax
-
-````markdown
-```garden list
-title:      # optional, heading
-items:      # required, items
-  - icon:   # optional, one of 23 icons
-    title:  # optional, switches layout
-    text:   # recommended, description
-caption:    # optional, caption
-```
-````
-
-## Fields
-
-Fence header: ` ```garden list ` (snippet trigger `;glist`). Invalid YAML or unknown top-level keys report `garden-yaml` on the block.
-
-| Field | Required | Default | Allowed Values & Limits | Description |
-| :--- | :--- | :--- | :--- | :--- |
-| `title` | Optional | none | string | Heading above the list |
-| `items` | Required | `[]` | object or string array | List entries; renders as a compact icon card when no item has `title`, or a divided step list when any item has `title` |
-| `items[].icon` | Optional | none (draws no icon) | one of the 23 built-in icon names: `search`, `eye`, `heart`, `chat`, `shield`, `wallet`, `bell`, `check`, `x`, `star`, `flag`, `clock`, `idea`, `book`, `link`, `user`, `chart`, `gear`, `file`, `pin`, `flask`, `target`, `question` | Line icon name (unknown names render nothing) |
-| `items[].title` | Optional | none (compact row layout) | string | Item heading; switches the block to the divided step layout |
-| `items[].text` | Recommended | `[]` | string or string[] | Item body text; each array element renders as its own paragraph |
-| `caption` | Optional | none | string | Caption below the list |
-
-## Limits & errors
-
-- Apart from the shared `garden-yaml`, this component has no error codes of its own; values marked "not checked" in the table never report an error.

package/docs/handbook/en/reference/relations.md

@@ -1,113 +0,0 @@
----
-title: Component reference · relations
-navTitle: relations
-description: Place 3 to 6 elements on an ellipse or around a center node and connect them with solid or dashed, one-way or two-way labeled links.
-section: reference
-order: 10
-badge: relations
----
-
-[← Component reference](/garden/en/reference) · [Usage: relations](/garden/en/components/relations)
-
-## Examples
-
-```garden relations
-items:
-  - title: Pick
-    text: Choose this month's book
-  - title: Read
-    text: Finish the agreed chapters each week
-  - title: Talk
-    text: Meet and share views
-  - title: Review
-    text: Note what to change next time
-links:
-  - from: 1
-    to: 2
-  - from: 2
-    to: 3
-  - from: 3
-    to: 4
-  - from: 4
-    to: 1
-  - from: 3
-    to: 1
-    style: dashed
-    label: shapes the pick
-  - from: 2
-    to: 4
-    style: dashed
-caption: The four steps feed each other instead of running once in a fixed order.
-```
-
-```garden relations
-items:
-  - title: Organiser
-    text: Sends one notice a month
-  - title: Members
-    text: Eight to ten neighbours
-  - title: Venue
-    text: Café or library
-  - title: Reading list
-    text: Members take turns to nominate
-center: Organiser
-links:
-  - from: 1
-    to: 2
-    label: invites
-  - from: 1
-    to: 3
-    label: books
-  - from: 1
-    to: 4
-    label: collects
-  - from: 2
-    to: 4
-    style: dashed
-    direction: both
-    label: nominate
-caption: The organiser sits in the center and links to the other three; members and the list shape each other.
-```
-
-## Syntax
-
-````markdown
-```garden relations
-title:          # optional, aria only
-items:          # required, 3–6
-  - title:      # required, name
-    text:       # optional, short note
-center:         # optional, # or title
-links:          # optional, list
-  - from:       # required, # or title
-    to:         # required, not from
-    style:      # solid | dashed
-    direction:  # one | both
-    label:      # optional, short label
-caption:        # optional, caption
-```
-````
-
-## Fields
-
-Fence header: ` ```garden relations ` (snippet trigger `;grel`). Nodes have no emphasis or accent option—every element carries equal visual weight; ` ```mermaid ` fences are supported for any other diagram, and `garden list` covers one-pass steps. Invalid YAML or unknown top-level keys report `garden-yaml` on the block.
-
-| Field | Required | Default | Allowed Values & Limits | Description |
-| :--- | :--- | :--- | :--- | :--- |
-| `title` | Optional | `"Relationship diagram"` for `aria-label` (no visible heading) | string | Heading above the diagram |
-| `items` | Required | none | object[], strictly `3` to `6` items (fewer than `3` or more than `6` items reports `garden-relations`) | Elements in the diagram; when `center` is omitted, all items are spaced evenly on an ellipse starting at the top (12 o'clock), clockwise |
-| `items[].title` | Required | `""` | string | Node heading (`links` and `center` reference items by 1-based number or exact `title`) |
-| `items[].text` | Optional | `""` | string | Short note below the node heading |
-| `center` | Optional | none (all items on the outer ellipse) | `1..N` (1-based number) or exact item `title` (an unknown index or title reports `garden-relations`) | Placed between `items` and `links`: puts that element in the middle and spaces the remaining elements evenly on the outer ring starting at the top, clockwise; no auto-detection |
-| `links` | Optional | `[]` | object[] (non-array or entry with unknown keys reports `garden-relations`) | Directed or bidirectional links between elements; neighbour outer-ring links bow outward while others run straight through the middle; write a repeating loop by listing each step (`1->2`, `2->3`, `3->4`, `4->1`) |
-| `links[].from` | Required | none | `1..N` (1-based number) or exact item `title`, cannot equal `to` (missing, unknown target, or `from === to` reports `garden-relations`) | Source element |
-| `links[].to` | Required | none | `1..N` (1-based number) or exact item `title`, cannot equal `from` (missing, unknown target, or `from === to` reports `garden-relations`) | Target element |
-| `links[].style` | Optional | `"solid"` | `"solid"` \| `"dashed"` (any other value reports `garden-relations`) | Solid line (`→` / `↔`) or dashed line (`⇢` / `⇠⇢`) |
-| `links[].direction` | Optional | `"one"` | `"one"` \| `"both"` (any other value reports `garden-relations`) | One-way arrow toward `to` or arrowheads on both ends |
-| `links[].label` | Optional | `""` | short string (non-string value reports `garden-relations`) | Short label along the line (dodges line crossings; when it does not fit on its line it becomes a circled number listed under the graph, e.g. `① limits: Budget → Venue`) |
-| `caption` | Optional | none | string | Caption below the diagram |
-
-## Limits & errors
-
-- `garden-relations`: fewer than 3 or more than 6 `items`; `center` matches no item; `links` is not a list or an entry has unknown keys; `from` / `to` missing, unknown or equal; a wrong `style` or `direction`; a `label` that is not a string.
-- For more elements or branches, use a ```` ```mermaid ```` flowchart; for one-pass steps, use `garden list`.

package/docs/handbook/en/reference/stat.md

@@ -1,60 +0,0 @@
----
-title: Component reference · stat
-navTitle: stat
-description: Display 2 to 4 key numbers, units, and short captions side by side.
-section: reference
-order: 2
-badge: stat
----
-
-[← Component reference](/garden/en/reference) · [Usage: stat](/garden/en/components/stat)
-
-## Examples
-
-```garden stat
-items:
-  - label: Reading Column
-    value: "740"
-    unit: px
-    caption: Default prose column width
-  - label: Wide Figure Limit
-    value: "1040"
-    unit: px
-    caption: Extends up to 150px on each side
-  - label: Wide Table Limit
-    value: "1340"
-    unit: px
-    caption: Extends up to 300px on each side
-```
-
-## Syntax
-
-````markdown
-```garden stat
-items:        # for several, 2–4 suggested
-  - label:    # required, label
-    value:    # required, number
-    unit:     # optional, unit
-    caption:  # optional, short note
-    text:     # optional, extra text
-    source:   # optional, source URL
-```
-````
-
-## Fields
-
-Fence header: ` ```garden stat ` (snippet trigger `;gstat`). Place multiple figures in `items`, or place fields at the top level for a single figure; invalid YAML or unknown top-level keys report `garden-yaml` on the block.
-
-| Field | Required | Default | Allowed Values & Limits | Description |
-| :--- | :--- | :--- | :--- | :--- |
-| `items` | Required for multiple figures | `[top-level object]` | object[] (`2` to `4` items recommended, not checked) | List of stat items displayed side by side; when omitted, top-level fields render as a single stat item |
-| `label` | Required | `""` | string | Metric name shown above the number |
-| `value` | Required | `""` | string or number | Primary figure rendered in large tabular type |
-| `unit` | Optional | none | string | Unit shown immediately to the right of `value` |
-| `caption` | Optional | none | string | Short note below the figure |
-| `text` | Optional | none | string | Additional explanatory text |
-| `source` | Optional | none | URL, `{ url, site?, icon? }`, or array | Source attribution chip (`site` defaults to the URL hostname without `www.`) |
-
-## Limits & errors
-
-- Apart from the shared `garden-yaml`, this component has no error codes of its own; values marked "not checked" in the table never report an error.

package/docs/handbook/en/reference/timeline.md

@@ -1,56 +0,0 @@
----
-title: Component reference · timeline
-navTitle: timeline
-description: Order release milestones, incident steps, or build stages along a vertical sequence.
-section: reference
-order: 4
-badge: timeline
----
-
-[← Component reference](/garden/en/reference) · [Usage: timeline](/garden/en/components/timeline)
-
-## Examples
-
-```garden timeline
-title: Static Publishing Pipeline Stages
-items:
-  - date: Step 1
-    title: Sync Content and Assets
-    text: Run `npx garden sync` to validate Front Matter, copy image attachments, and generate the search index and RSS feed.
-  - date: Step 2
-    title: Build Static Site Output
-    text: Run `STATIC_EXPORT=1 npx garden build` to prerender every route into `dist/client/`.
-  - date: Step 3
-    title: Validate Output and Deploy
-    text: Run `npm run pages:validate` to confirm `index.html` exists and no `.env`, source directories, `.map` or `.md` files, or symlinks were included, then publish to GitHub Pages.
-```
-
-## Syntax
-
-````markdown
-```garden timeline
-title:       # optional, heading
-items:       # required, in order
-  - date:    # optional, date
-    title:   # required, heading
-    text:    # optional, description
-    source:  # optional, source URL
-```
-````
-
-## Fields
-
-Fence header: ` ```garden timeline ` (snippet trigger `;gtimeline`). Invalid YAML or unknown top-level keys report `garden-yaml` on the block.
-
-| Field | Required | Default | Allowed Values & Limits | Description |
-| :--- | :--- | :--- | :--- | :--- |
-| `title` | Optional | none | string | Heading above the timeline |
-| `items` | Required | `[]` | object[] (at least `2` items recommended, not checked) | Ordered list of steps or milestones |
-| `items[].date` | Optional | none | string | Timestamp, year, or stage label above the item title |
-| `items[].title` | Required | `""` | string | Step heading |
-| `items[].text` | Optional | none | string | Detailed explanation for the step |
-| `items[].source` | Optional | none | URL, `{ url, site?, icon? }`, or array | Source attribution chip appended to the step text (`site` defaults to the URL hostname without `www.`) |
-
-## Limits & errors
-
-- Apart from the shared `garden-yaml`, this component has no error codes of its own; values marked "not checked" in the table never report an error.

package/docs/handbook/reference/card.md

@@ -1,85 +0,0 @@
----
-title: 组件参考 · card
-navTitle: card
-description: 介绍一篇论文、一个项目或一组值得参考的公开工具。
-section: reference
-order: 1
-badge: card
----
-
-[← 组件参考](/garden/reference) · [用法：知识卡片](/garden/components/card)
-
-## 示例
-
-```garden card
-title: SQLite WAL 写入模式
-url: https://www.sqlite.org/wal.html
-meta: 文档说明 · sqlite.org
-description: 把修改先顺序追加到预写日志，读操作继续访问原数据库页，减少读写互斥等待。
-points:
-  - 写入只追加到 `-wal` 文件末尾，不需要在事务提交时原地覆盖数据页。
-  - 读事务记录当前末尾偏移量即可看到一致快照，不会阻塞并发写入。
-  - 后台 Checkpoint 按阈值将日志页分批写回主库文件。
-```
-
-```garden card
-cards:
-  - url: https://openlibrary.org/
-    title: Open Library：每本书一个页面
-    description: Internet Archive 维护的开放图书目录，可以查版本、借阅电子书。
-    image: /images/garden/ref-card-book.svg
-    alt: 一本合上的书
-    source:
-      - https://openlibrary.org/
-    takeaway: "**可借鉴：** 选书时直接贴书的页面链接，大家看到的是同一个版本。"
-  - url: https://www.gutenberg.org/
-    title: Project Gutenberg：公版电子书
-    description: 收录已进入公有领域的电子书，可以免费下载。
-    image: /images/garden/ref-card-lamp.svg
-    alt: 一盏台灯
-    source:
-      - https://www.gutenberg.org/
-      - https://en.wikipedia.org/wiki/Project_Gutenberg
-    takeaway: "**可借鉴：** 偶尔选一本公版书，没买书的人也能马上加入。"
-```
-
-## 字段写法
-
-````markdown
-```garden card
-title:        # 建议填，标题
-url:          # 可选，标题链接
-meta:         # 可选，副标题
-description:  # 摘要（或 text）
-points:       # 要点列表（或 items）
-image:        # 可选，缩略图
-alt:          # 可选，替代文本
-source:       # 可选，来源网址
-site:         # 可选，站点名
-takeaway:     # 可选，底部结论
-cards:        # 多卡模式，每项同上
-  - url:      # 卡片链接
-```
-````
-
-## 字段
-
-围栏写 ` ```garden card `（编辑器代码片段触发词 `;gcard`）。单张卡片直接在顶层写字段，多张横向资源行卡用 `cards` 数组；YAML 语法错误或顶层含未知键名时整块报 `garden-yaml` 错误。
-
-| 字段 | 是否必填 | 默认值 | 取值与限制 | 说明 |
-| :--- | :--- | :--- | :--- | :--- |
-| `title` | 建议填写 | 同 `url` | 字符串 | 卡片标题；未填时回退显示 `url` |
-| `url` | 可选 | `""` | 完整 `https://` 或 `http://` 网址 | 标题跳转的外链；未填时标题渲染为纯文本 |
-| `meta` | 可选 | 无 | 字符串 | 标题下方的副标题或来源说明 |
-| `description` | 与 `points`、`cards` 至少填一项 | `""` | 字符串（别名 `text`） | 摘要段落，支持行内加粗与代码 |
-| `points` | 与 `description`、`cards` 至少填一项 | `[]` | 字符串数组或 `{ title, text? }[]`（别名 `items`；建议 `2`～`4` 条要点，不做校验） | 摘要下方的编号要点列表 |
-| `image` | 可选 | 无 | 图片路径或 Data URL | 卡片缩略图 |
-| `alt` | 可选 | 同 `title` | 字符串 | 缩略图替代文本 |
-| `source` | 可选 | 无 | 单个网址、`{ url, site?, icon? }` 或数组 | 跟在 `description` 后的来源胶囊；多个来源自动折叠为首域名加 `+N`（如 `gutenberg.org +1`）。`icon` 默认优先使用构建期下载到的站点 Favicon，其次取可注册域名主体的首字母大写（如 `en.wikipedia.org` 取 `W`，`bbc.co.uk` 取 `B`） |
-| `site` | 可选 | `url` 去掉 `www.` 后的域名 | 字符串 | 来源站点显示名称 |
-| `takeaway` | 可选 | 无 | 字符串 | 卡片底部带顶部分隔线的启发或结论（如 `"**可借鉴：** ……"`） |
-| `cards` | 多卡模式必填 | 无 | 对象数组 | 多张横向资源行卡，每项支持 `url`、`title`、`description`（或 `text`）、`image`、`alt`、`meta`、`source`、`takeaway` |
-
-## 限制与报错
-
-- 除通用的 `garden-yaml` 外，本组件没有专属报错代码；表里写「不做校验」的建议值不会报错。

package/docs/handbook/reference/chart.md

@@ -1,68 +0,0 @@
----
-title: 组件参考 · chart
-navTitle: chart
-description: 把一组算好的数字画成比例条形图，下方自带可展开的数据表。
-section: reference
-order: 5
-badge: chart
----
-
-[← 组件参考](/garden/reference) · [用法：条形图表](/garden/components/chart)
-
-## 示例
-
-```garden chart
-title: 三种版面区域的宽度上限
-xLabel: 版面区域
-yLabel: 最大宽度
-unit: px
-data:
-  - x: 普通正文列
-    y: 740
-  - x: 宽幅配图区
-    y: 1040
-  - x: 多列宽表格
-    y: 1340
-caption: 点击「查看数据表」可展开完整数值表格。
-```
-
-## 字段写法
-
-````markdown
-```garden chart
-type:       # 可选，只有 bar
-title:      # 建议填，标题
-data:       # 与 series 二选一
-  - x:      # 名称
-    y:      # 数值
-    label:  # 可选，数值标签
-x:          # 配合 series 的标签
-series:     # 与 data 二选一
-  - name:   # 可选，序列名
-    data:   # 数值数组
-unit:       # 可选，单位
-xLabel:     # 可选，表头第一列
-yLabel:     # 可选，表头第二列
-caption:    # 可选，图注
-```
-````
-
-## 字段
-
-围栏写 ` ```garden chart `（编辑器代码片段触发词 `;gchart`）。可以用 `data: [{ x, y, label? }]` 写行数据，也可以用 `x` + `series` 写列数据；YAML 语法错误或顶层含未知键名时整块报 `garden-yaml` 错误。
-
-| 字段 | 是否必填 | 默认值 | 取值与限制 | 说明 |
-| :--- | :--- | :--- | :--- | :--- |
-| `title` | 建议填写 | 无障碍标签默认 `"图表"`（不渲染可视标题） | 字符串 | 图表上方标题 |
-| `data` | 与 `series` 二选一 | `[]` | `{ x, y, label? }[]`（建议至少 `2` 项、以 `2`～`8` 项为宜，不做校验） | 条目数组：`x` 为左侧名称，`y` 为数值，`label` 默认拼接 `y` 与 `unit` |
-| `series` | 与 `data` 二选一 | 无 | `{ name?, data: number[] }[]`（建议至少 `2` 个数值点，不做校验） | 配合 `x`（标签数组）使用的数值序列，取 `series[0].data` 渲染条形 |
-| `x` | 可选 | `["1", "2", ...]`（按序号递增） | 字符串或字符串数组 | 配合 `series` 时为各项标签数组；单独写字符串且未填 `xLabel` 时作为数据表首列表头 |
-| `type` | 可选 | `"bar"` | `"bar"` | 图表类型（水平条形图） |
-| `unit` | 可选 | `""` | 字符串 | 未显式填写 `data[].label` 时在数值右侧追加的单位 |
-| `xLabel` | 可选 | 字符串 `x` 或 `"项目"` | 字符串 | 可展开数据表第一列的表头 |
-| `yLabel` | 可选 | `"数值"` | 字符串 | 可展开数据表第二列的表头 |
-| `caption` | 可选 | 无 | 字符串 | 图表底部的图注 |
-
-## 限制与报错
-
-- 除通用的 `garden-yaml` 外，本组件没有专属报错代码；表里写「不做校验」的建议值不会报错。

package/docs/handbook/reference/choice.md

@@ -1,69 +0,0 @@
----
-title: 组件参考 · choice
-navTitle: choice
-description: 给出两三个具体选项卡片，读者点选后看到对应的回应。
-section: reference
-order: 12
-badge: choice
----
-
-[← 组件参考](/garden/reference) · [用法：选择卡](/garden/components/choice)
-
-## 示例
-
-```garden choice
-title: 下个月在哪里见面？
-items:
-  - icon: idea
-    value: ¥40 / 人
-    text: 街角咖啡馆，含一杯饮料
-    label: 更看重氛围
-    reply: 选了咖啡馆。我们会提前订好靠窗的长桌。
-  - icon: book
-    value: 免费
-    text: 社区图书馆活动室，需提前预约
-    label: 更看重安静
-    reply: 选了图书馆。我们会在月初提交预约。
-none:
-  label: 都不合适 / 说不清
-  reply: 没关系，我们会在群里再列几个场地。
-caption: 示意交互，场地和价格均为虚构。
-```
-
-## 字段写法
-
-````markdown
-```garden choice
-title:      # 可选，问题
-items:      # 必填，建议 2–3 项
-  - icon:   # 可选，23 个图标名之一
-    value:  # 建议填，醒目数字
-    text:   # 建议填，一句说明
-    label:  # 可选，偏好标签
-    reply:  # 可选，选中后的回应
-none:       # 可选，兜底按钮
-  label:    # 按钮文字
-  reply:    # 可选，回应
-caption:    # 可选，图注
-```
-````
-
-## 字段
-
-围栏写 ` ```garden choice `（编辑器代码片段触发词 `;gchoice`）。整组作为无障碍单选组（`role="radiogroup"`）渲染，支持键盘方向键切换；桌面端并排排列，窄屏下自动改为单列纵向堆叠。YAML 语法错误或顶层含未知键名时整块报 `garden-yaml` 错误。
-
-| 字段 | 是否必填 | 默认值 | 取值与限制 | 说明 |
-| :--- | :--- | :--- | :--- | :--- |
-| `title` | 可选 | `""` | 字符串 | 选项卡片上方的问题或标题 |
-| `items` | 必填 | `[]` | 对象数组（建议 `2`～`3` 项，不做校验） | 选项卡片列表 |
-| `items[].icon` | 可选 | 无（不绘制图标） | 23 个内置图标名之一 | 卡片顶部的线条图标（与 `garden list` 共用同一套 23 个图标名） |
-| `items[].value` | 建议填写 | 无 | 字符串或数字 | 卡片上醒目显示的价格、数字或短结论 |
-| `items[].text` | 建议填写 | 无 | 字符串 | 选项的一句话说明 |
-| `items[].label` | 可选 | 无 | 字符串 | 卡片底部带圆点的偏好标签（如「更看重氛围」） |
-| `items[].reply` | 可选 | `""` | 字符串 | 点选该卡片后在整组下方展开的回应文字 |
-| `none` | 可选 | 无 | `{ label: string, reply?: string }` | 卡片下方整行宽度的兜底文字按钮（如「都不合适 / 说不清」）及选中后的回应 |
-| `caption` | 可选 | 无 | 字符串 | 组件底部的图注 |
-
-## 限制与报错
-
-- 除通用的 `garden-yaml` 外，本组件没有专属报错代码；表里写「不做校验」的建议值不会报错。