hd-garden 0.13.2 → 0.14.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.agents/skills/garden-compose/SKILL.md +24 -0
- package/.agents/skills/garden-compose/references/colors.md +11 -0
- package/.agents/skills/garden-compose/references/composition-patterns.md +162 -0
- package/.agents/skills/garden-compose/references/examples.md +55 -0
- package/.agents/skills/garden-compose/references/frames.md +7 -0
- package/.agents/skills/garden-compose/references/layout-recipes.md +84 -0
- package/.agents/skills/garden-compose/references/rendering-model.md +120 -0
- package/.agents/skills/garden-compose/references/static-play.md +19 -0
- package/.agents/skills/garden-compose/references/visual-selection.md +38 -0
- package/.agents/skills/garden-compose/references/workflow.md +27 -0
- package/.agents/skills/garden-compose/scripts/_cli.mjs +12 -0
- package/.agents/skills/garden-compose/scripts/apply.mjs +2 -0
- package/.agents/skills/garden-compose/scripts/check.mjs +2 -0
- package/.agents/skills/garden-compose/scripts/prompt.mjs +2 -0
- package/.agents/skills/garden-compose/scripts/scan.mjs +2 -0
- package/.agents/skills/garden-post-review/SKILL.md +5 -16
- package/Makefile +12 -3
- package/README.en.md +10 -5
- package/README.md +10 -5
- package/app/admin/preview/[...path]/page.tsx +3 -15
- package/app/api/admin/ui/blocks/route.ts +1 -1
- package/app/components/AdminUiPanels.tsx +6 -3
- package/app/components/GardenContentGuide.tsx +7 -8
- package/app/components/MarkdownArticle.tsx +6 -47
- package/app/components/TableOfContents.tsx +0 -1
- package/app/components/UiStudio.tsx +29 -32
- package/app/components/garden/AuthorRich.tsx +5 -0
- package/app/components/garden/ComposePreview.tsx +9 -0
- package/app/components/garden/GardenBlock.tsx +12 -10
- package/app/components/garden/GardenFile.tsx +1 -1
- package/app/components/garden/blocks.tsx +9 -197
- package/app/components/garden/file-icons.tsx +1 -1
- package/app/components/garden/patterns.tsx +7 -65
- package/app/lib/content.ts +5 -22
- package/app/lib/heading-number.ts +2 -7
- package/app/lib/rehype-garden-blocks.mjs +30 -0
- package/app/lib/remark-garden.mjs +0 -4
- package/app/lib/ui-model.ts +8 -9
- package/app/styles/a2.css +17 -1
- package/bin/garden.mjs +43 -36
- package/docs/handbook/ai-writing.md +19 -22
- package/docs/handbook/components/compose.md +16 -7
- package/docs/handbook/components/image.md +1 -1
- package/docs/handbook/components/link-card.md +2 -2
- package/docs/handbook/components.md +5 -213
- package/docs/handbook/deploy.md +11 -0
- package/docs/handbook/en/ai-writing.md +17 -20
- package/docs/handbook/en/components/compose.md +15 -6
- package/docs/handbook/en/components/image.md +1 -1
- package/docs/handbook/en/components/link-card.md +2 -2
- package/docs/handbook/en/components.md +7 -215
- package/docs/handbook/en/deploy.md +11 -0
- package/docs/handbook/en/index.md +29 -53
- package/docs/handbook/en/reference/compose.md +77 -148
- package/docs/handbook/en/reference.md +6 -22
- package/docs/handbook/en/start.md +1 -1
- package/docs/handbook/en/workflow.md +20 -16
- package/docs/handbook/en/writing.md +2 -2
- package/docs/handbook/index.md +26 -47
- package/docs/handbook/reference/compose.md +79 -148
- package/docs/handbook/reference.md +6 -22
- package/docs/handbook/start.md +1 -1
- package/docs/handbook/workflow.md +20 -16
- package/docs/handbook/writing.md +2 -2
- package/editors/dist/typora/main.js +324 -330
- package/editors/dist/typora/style.css +4299 -11
- package/editors/dist/vscode/garden-ui-0.1.1.vsix +0 -0
- package/eslint.config.mjs +3 -0
- package/package.json +3 -2
- package/public/images/compose-resources/resource-015b41eb0f32.svg +1 -0
- package/public/images/compose-resources/resource-ecee6b47f015.svg +1 -0
- package/public/images/compose-resources/resource-fd51121b5e8c.svg +1 -0
- package/scripts/build-content.mjs +59 -141
- package/scripts/build-ui-preview.mjs +7 -5
- package/scripts/check-post.mjs +8 -104
- package/scripts/check-site.mjs +80 -0
- package/scripts/compose-style-reference.mjs +22 -0
- package/scripts/dev-server.mjs +114 -0
- package/scripts/editor-preview-css.mjs +14 -0
- package/scripts/file-preview.mjs +1 -1
- package/scripts/file-sizes.mjs +7 -7
- package/scripts/generated-cache.mjs +36 -0
- package/scripts/handbook-facts.mjs +10 -3
- package/scripts/image-sizes.mjs +6 -12
- package/scripts/link-assets.mjs +35 -10
- package/scripts/managed-skills.mjs +56 -0
- package/scripts/prepare-pages-output.mjs +1 -1
- package/scripts/site-guide.mjs +19 -0
- package/scripts/ui-cli.mjs +26 -33
- package/templates/garden-blocks.md +4 -180
- package/templates/garden-snippets.plist +2 -183
- package/templates/site/AGENTS.en.md +89 -0
- package/templates/site/AGENTS.md +72 -0
- package/templates/site/Makefile +12 -3
- package/templates/site/Makefile.en +12 -3
- package/templates/site/README.en.md +8 -1
- package/templates/site/README.md +8 -1
- package/templates/skills-en/garden-compose/SKILL.md +24 -0
- package/templates/skills-en/garden-post-review/SKILL.md +5 -16
- package/templates/workflows/pages.en.yml +11 -0
- package/templates/workflows/pages.yml +11 -0
- package/ui/compose/compose.css +54 -14
- package/ui/compose/contracts.mjs +16 -0
- package/ui/compose/dil.mjs +109 -48
- package/ui/compose/distribution.mjs +7 -0
- package/ui/compose/features.mjs +90 -0
- package/ui/compose/icons.mjs +8 -0
- package/ui/compose/index.mjs +2 -0
- package/ui/compose/inspect.mjs +11 -0
- package/ui/compose/markup.mjs +80 -23
- package/ui/compose/preview.mjs +13 -0
- package/ui/compose/prompt-catalog.mjs +15 -3
- package/ui/compose/render.mjs +46 -11
- package/ui/compose/scenes.mjs +10 -0
- package/ui/core/apply.mjs +12 -45
- package/ui/core/catalog.mjs +22 -32
- package/ui/core/cli-locale.mjs +8 -18
- package/ui/core/color.mjs +34 -0
- package/ui/core/compile.mjs +1 -8
- package/ui/core/demos.mjs +138 -108
- package/ui/core/fence.mjs +14 -70
- package/ui/core/fix-prompt.mjs +1 -3
- package/ui/core/garden-fence.mjs +3 -63
- package/ui/core/index.mjs +3 -5
- package/ui/core/parse.mjs +22 -8
- package/ui/core/scan.mjs +31 -43
- package/ui/core/starters.mjs +3 -3
- package/ui/core/static.mjs +36 -6
- package/ui/core/transform.mjs +64 -149
- package/ui/core/validate.mjs +20 -9
- package/ui/garden/article-content.mjs +98 -0
- package/ui/garden/catalog.mjs +21 -427
- package/ui/garden/check.mjs +18 -60
- package/ui/garden/file-block.mjs +1 -1
- package/ui/garden/file-paths.mjs +8 -6
- package/ui/garden/markdown-syntax.mjs +1 -1
- package/ui/garden/parse.mjs +19 -182
- package/ui/garden/relations.mjs +1 -1
- package/ui/garden/snippets.mjs +12 -153
- package/ui/garden/source-icon.mjs +17 -9
- package/ui/garden/word-count.mjs +16 -85
- package/ui/index.mjs +1 -5
- package/ui/preview/dist/garden-ui.css +4300 -11
- package/ui/preview/dist/garden-ui.esm.js +446 -418
- package/ui/preview/dist/garden-ui.iife.js +446 -418
- package/ui/preview/index.tsx +31 -98
- package/ui/preview/site-config.ts +4 -0
- package/ui/prompt/build.mjs +1 -4
- package/ui/prompt/recipes/code-walkthrough.md +17 -12
- package/ui/prompt/recipes/compare.md +14 -10
- package/ui/prompt/recipes/compose.md +3 -3
- package/ui/prompt/recipes/converter.md +17 -14
- package/ui/prompt/recipes/data-chart.md +9 -8
- package/ui/prompt/recipes/inspect-grid.md +9 -8
- package/ui/prompt/recipes/param-bench.md +17 -12
- package/ui/prompt/recipes/plan.md +4 -3
- package/ui/prompt/recipes/stepper.md +18 -16
- package/ui/prompt/recipes/trace.md +20 -18
- package/ui/prompt/rules.md +26 -133
- package/ui/prompt/studio.md +3 -18
- package/ui/react/CatalogPage.tsx +19 -21
- package/ui/react/recipes.ts +3 -3
- package/ui/react/runtime.tsx +23 -2
- package/ui/react/ui.css +17 -11
- package/vite.config.ts +46 -8
- package/.agents/skills/garden-interactive-chart/SKILL.md +0 -84
- package/.agents/skills/garden-interactive-chart/references/shell.html +0 -49
- package/.agents/skills/garden-interactive-chart/references/style.md +0 -61
- package/.agents/skills/garden-ui/SKILL.md +0 -125
- package/app/components/UiBlock.tsx +0 -23
- package/app/components/WidgetChart.tsx +0 -224
- package/app/lib/generated-content.ts +0 -385
- package/docs/handbook/components/card.md +0 -67
- package/docs/handbook/components/chart.md +0 -38
- package/docs/handbook/components/choice.md +0 -42
- package/docs/handbook/components/compare.md +0 -53
- package/docs/handbook/components/file.md +0 -29
- package/docs/handbook/components/html.md +0 -49
- package/docs/handbook/components/interactive.md +0 -48
- package/docs/handbook/components/list.md +0 -65
- package/docs/handbook/components/relations.md +0 -95
- package/docs/handbook/components/stat.md +0 -39
- package/docs/handbook/components/timeline.md +0 -37
- package/docs/handbook/en/components/card.md +0 -67
- package/docs/handbook/en/components/chart.md +0 -38
- package/docs/handbook/en/components/choice.md +0 -42
- package/docs/handbook/en/components/compare.md +0 -53
- package/docs/handbook/en/components/file.md +0 -29
- package/docs/handbook/en/components/html.md +0 -49
- package/docs/handbook/en/components/interactive.md +0 -44
- package/docs/handbook/en/components/list.md +0 -65
- package/docs/handbook/en/components/relations.md +0 -95
- package/docs/handbook/en/components/stat.md +0 -39
- package/docs/handbook/en/components/timeline.md +0 -37
- package/docs/handbook/en/reference/card.md +0 -85
- package/docs/handbook/en/reference/chart.md +0 -68
- package/docs/handbook/en/reference/choice.md +0 -69
- package/docs/handbook/en/reference/compare.md +0 -59
- package/docs/handbook/en/reference/file.md +0 -50
- package/docs/handbook/en/reference/html.md +0 -62
- package/docs/handbook/en/reference/interactive.md +0 -71
- package/docs/handbook/en/reference/list.md +0 -72
- package/docs/handbook/en/reference/relations.md +0 -113
- package/docs/handbook/en/reference/stat.md +0 -60
- package/docs/handbook/en/reference/timeline.md +0 -56
- package/docs/handbook/reference/card.md +0 -85
- package/docs/handbook/reference/chart.md +0 -68
- package/docs/handbook/reference/choice.md +0 -69
- package/docs/handbook/reference/compare.md +0 -59
- package/docs/handbook/reference/file.md +0 -50
- package/docs/handbook/reference/html.md +0 -62
- package/docs/handbook/reference/interactive.md +0 -71
- package/docs/handbook/reference/list.md +0 -72
- package/docs/handbook/reference/relations.md +0 -113
- package/docs/handbook/reference/stat.md +0 -60
- package/docs/handbook/reference/timeline.md +0 -56
- package/templates/skills-en/garden-interactive-chart/SKILL.md +0 -84
- package/templates/skills-en/garden-interactive-chart/references/shell.html +0 -49
- package/templates/skills-en/garden-interactive-chart/references/style.md +0 -61
- package/templates/skills-en/garden-ui/SKILL.md +0 -125
|
@@ -1,182 +1,113 @@
|
|
|
1
1
|
---
|
|
2
|
-
title: 组件参考 ·
|
|
2
|
+
title: 组件参考 · Compose
|
|
3
3
|
navTitle: compose
|
|
4
|
-
description:
|
|
4
|
+
description: 单一作者入口、可执行渲染契约与验证。
|
|
5
5
|
section: reference
|
|
6
6
|
order: 6
|
|
7
7
|
badge: compose
|
|
8
8
|
---
|
|
9
9
|
|
|
10
|
-
|
|
10
|
+
ZH: 统一使用 `garden compose`;以下按真实实现解释组合机制、内容边界与检查方法。完整属性按需运行 `npx garden ui schema`,不复制易过期的目录。
|
|
11
11
|
|
|
12
|
-
|
|
12
|
+
## One entry, component selection inside it
|
|
13
13
|
|
|
14
|
-
|
|
14
|
+
Use `garden compose`. Select by the reader's task, not by another fence name:
|
|
15
15
|
|
|
16
|
-
|
|
16
|
+
| Need | Compose structure |
|
|
17
|
+
| :--- | :--- |
|
|
18
|
+
| Reference material and takeaways | `resources/resource`, nested `point`, `reference` |
|
|
19
|
+
| Key results | `metric` with label, value, unit, caption, paragraphs and references |
|
|
20
|
+
| Time or stages | `timeline/event` |
|
|
21
|
+
| Alternatives and verdicts | `compare/item` |
|
|
22
|
+
| Icon-led editorial paragraphs | `icon-list/entry` or a small `icon` beside one shared text container |
|
|
23
|
+
| Download and preview | `files/file` or one `file src="…"` |
|
|
24
|
+
| Connected concepts | `relations/entity/edge`, stable ids; 3–6 entities |
|
|
25
|
+
| Rich selectable cards and replies | `choices/choice-option`, optional `none` option |
|
|
26
|
+
| Discrete bars and exact values | `plot/datum`; expandable data table |
|
|
27
|
+
| Parameter-dependent results | Play declarations, controls, `chart/bar/line`, `pie`, `table` |
|
|
28
|
+
| Article text and useful HTML | `markdown` and `html` content islands |
|
|
29
|
+
| Independent executable illustration | Play `sandbox` with literal html/css/js; isolated offline iframe |
|
|
17
30
|
|
|
18
|
-
|
|
31
|
+
The authoritative, demand-loaded catalog is `npx garden ui schema`: actual semantic fields, Play props/defaults/child contracts, icon names, safe HTML tags/attributes/CSS properties. `npx garden ui prompt` adds working recipes. `styleReference` also extracts current font/layout declarations, selectors, responsive conditions and source order from the installed stylesheets; it reports source defaults, not universal computed values. These are generated from the validators and actual styles; do not maintain a second exhaustive tag list. Static layout normalization is not a universal HTML/CSS API: inspect the normalized tree and output because some unsupported static layout attributes are ignored. Semantic unknown fields fail validation.
|
|
19
32
|
|
|
20
|
-
|
|
21
|
-
| :--- | :--- |
|
|
22
|
-
| `padding` / `gap` | `0`–`4`(4px × n) |
|
|
23
|
-
| `background` | `surface` `surface-secondary` `surface-accent` `surface-tip` `surface-muted` `transparent` |
|
|
24
|
-
| `radius` | `none` `sm` `md` `lg` `xl` `full` |
|
|
25
|
-
| `border` | `subtle` `strong`/`true` `none`/`false` |
|
|
26
|
-
| `size` | `sm` `md` `lg` `xl` |
|
|
27
|
-
| `tone` | `plain` `accent` `tip` `muted`(callout 另有 `note`/`warn`) |
|
|
28
|
-
| `align` | `start` `center` `end` `stretch` |
|
|
29
|
-
| `justify`(row) | `start` `center` `end` `between` `around` |
|
|
30
|
-
| `wrap`(row) | `wrap` `nowrap` |
|
|
33
|
+
图表的可运行示例见[Compose 活跃时段图](/garden/components/compose#ui-compose-chart-active-hours)。
|
|
31
34
|
|
|
32
|
-
##
|
|
35
|
+
## Relationships → hierarchy → layout → style → actual output
|
|
33
36
|
|
|
34
|
-
|
|
37
|
+
First identify what belongs together. A heading and all its paragraphs must share a container. Next choose columns and proportions, then alignments and typography. Only then add surfaces and decorative details.
|
|
35
38
|
|
|
36
|
-
|
|
37
|
-
| :--- | :--- |
|
|
38
|
-
| `frame` | `card`(默认)`band` `pill` `text`;也可用糖标签 `<band>` / `<pill>` |
|
|
39
|
-
| `padding` `gap` `radius` `border` `background` `size` `align` `tone` `id` `mark` | 共用 token;`mark="shield"` 画盾牌 |
|
|
39
|
+
A static `row` wraps by default. Its direct text/title/stack/card children share available width (`flex: 1 1 0`), whereas an icon is content-sized. A heading placed directly in that row is a sibling column, not the heading of a paragraph below the row. `align="center"` on a row changes more than vertical placement: theme rules also center text. A centered stack propagates text alignment. For an editorial list use explicit start alignment on children of a shared right-hand group; do not center each title independently.
|
|
40
40
|
|
|
41
|
-
|
|
41
|
+
Direct `row > stack` has 12px top padding in the current theme. A `group` is a width:100%, min-width:0 vertical container that shrinks beside the fixed icon and reads gap without that contextual padding; use it when icon and heading must begin on the same top line. Explicit `align="start"` survives normalization and emits data-align.
|
|
42
42
|
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
43
|
+
Nested paragraphs need separate `text` leaves or an article content island. Two unrelated top-level leaves do not establish a shared right column. Put a full-width divider **between rows**, not inside the right text container, if the rule must span the icon column too. `divider` and `separator` are real primitives, not text lines.
|
|
44
|
+
|
|
45
|
+
```garden compose
|
|
46
|
+
<figure frame="none">
|
|
47
|
+
<row wrap="nowrap" align="start" gap="4">
|
|
48
|
+
<icon name="book-open" size="xl"/>
|
|
49
|
+
<group gap="2">
|
|
50
|
+
<title align="start">Test heading — not article content</title>
|
|
51
|
+
<text align="start">Explicit test paragraph: the heading and this body share the same right column. Keep the author's complete text; do not shrink or summarize it to fit.</text>
|
|
52
|
+
<text align="start">A second independent test paragraph stays in that column.</text>
|
|
53
|
+
</group>
|
|
54
|
+
</row>
|
|
55
|
+
<divider/>
|
|
56
|
+
<row wrap="nowrap" align="start" gap="4">
|
|
57
|
+
<icon name="users" size="xl"/>
|
|
58
|
+
<group gap="2">
|
|
59
|
+
<title align="start">Second test heading</title>
|
|
60
|
+
<text align="start">Another test body, aligned with its heading rather than spanning the icon column.</text>
|
|
61
|
+
</group>
|
|
62
|
+
</row>
|
|
63
|
+
</figure>
|
|
64
|
+
```
|
|
49
65
|
|
|
50
|
-
|
|
66
|
+
For a native editorial list the same relationship is expressed with `icon-list` containing `entry icon="…" title="…"`, and multiple `text` children per entry. Native paragraph children are lowered to text strings: their nested text size/alignment/layout properties are not carried into the native scene. Use a generic layout with text size controls for such precision; do not assume identical nested styling contracts. Native scenes preserve the app's keyboard/selection/detail/file-preview behavior when rendered by the Garden article host. A standalone static export is a readable fallback, not an identical interactive host.
|
|
51
67
|
|
|
52
|
-
|
|
53
|
-
| :--- | :--- |
|
|
54
|
-
| `size` `align` | 共用 |
|
|
55
|
-
| `tone` | `text`:`plain` `muted` `accent` `tip`。`caption` 固定 muted。 |
|
|
68
|
+
## Typography and complete-theme context
|
|
56
69
|
|
|
57
|
-
|
|
70
|
+
Default body text inherits the **actual article's** family, size and line height. There is no universal pixel baseline. This includes ordinary static text, list bodies and native readable prose; changing the article typography configuration must propagate. Semantic headings, graph labels, values, captions and controls intentionally retain their hierarchy.
|
|
58
71
|
|
|
59
|
-
|
|
|
72
|
+
| Element/context | Actual source rule / intentional variation |
|
|
60
73
|
| :--- | :--- |
|
|
61
|
-
| `
|
|
62
|
-
|
|
|
63
|
-
|
|
|
74
|
+
| Static `text` and `title` | Inherit body size; title weight 600, line height 1.4. `size="sm"` .875em; `lg` 1.125em; `xl` 1.25em. `md` keeps the baseline. |
|
|
75
|
+
| Static outer figure title/caption | Source defaults 18px/14px, not ordinary body; actual cascade still matters. |
|
|
76
|
+
| Static inline caption | Own semantic style; `sm` 11px, `lg` 16px. Not a body substitute. |
|
|
77
|
+
| Native icon-list entry title/body | Title weight 600; body inherits article. Group heading uses `--fs-small`. |
|
|
78
|
+
| Native choice value | 22px; narrow rule 20px. Option body inherits article. |
|
|
79
|
+
| Native relation ring | Compact/context-dependent labels and line clamps; detail prose inherits article. Do not treat a ring label as a long paragraph. |
|
|
80
|
+
| Play components | Query schema defaults and complete theme. Their controls/KPI/graph semantics are not globally changed to body size. |
|
|
64
81
|
|
|
65
|
-
|
|
82
|
+
Use explicit variation only for a meaningful hierarchy. Never shrink body text globally to fit a screenshot or discard facts to avoid wrapping. Inspect actual computed styles with globals → tokens → article theme → shell in the real order, on desktop and narrow widths; base component CSS alone does not prove the final result.
|
|
66
83
|
|
|
67
|
-
|
|
84
|
+
## Markdown, safe HTML, and execution
|
|
68
85
|
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
```garden compose
|
|
72
|
-
<row gap={2}><box padding={2} radius="md" border="subtle"><title size="sm">甲</title></box><box padding={2} radius="md" background="surface-accent"><title size="sm">乙</title></box></row>
|
|
73
|
-
```
|
|
86
|
+
`text`, `title` and captions are inline contexts: `**bold**`, `_emphasis_`, backticks, `[links](https://example.com)`, `~~strike~~` and safe inline HTML such as `<u>underline</u>`. `<u>` is HTML, not standard Markdown.
|
|
74
87
|
|
|
75
|
-
|
|
76
|
-
| :--- | :--- |
|
|
77
|
-
| `box` | 通用容器;可设 padding / gap / background / radius |
|
|
78
|
-
| `card` | box 的卡面别名 |
|
|
79
|
-
| `stack` | 竖排 |
|
|
80
|
-
| `row` | 横排 |
|
|
81
|
-
| `columns` | 多列横排(默认可换行) |
|
|
82
|
-
| `grid` | 等分网格;cols 1–6 |
|
|
83
|
-
| `grid-item` | 网格格;span 跨列 |
|
|
84
|
-
| `group` | 语义分组容器 |
|
|
85
|
-
| `field` | 表单项分组 |
|
|
86
|
-
| `header` | 页眉区 |
|
|
87
|
-
| `footer` | 页脚区 |
|
|
88
|
-
| `figure` | 图示区 |
|
|
89
|
-
| `prose` | 长文段落区 |
|
|
90
|
-
| `divider` | 分隔线(自闭合) |
|
|
91
|
-
| `separator` | divider 别名 |
|
|
92
|
-
| `spacer` | 空白间距 |
|
|
93
|
-
| `band` | 通栏强调条(box frame=band) |
|
|
94
|
-
| `pill` | 胶囊(box frame=pill) |
|
|
95
|
-
|
|
96
|
-
### 文字
|
|
88
|
+
Use `markdown` or `html` islands for full paragraphs, lists, headings, blockquotes, code blocks, tables, images, details/summary and other allowlisted article content. The islands share the article Markdown/GFM and safe-HTML renderer; they are not arbitrary component trees. Static text outside islands is a lightweight layout shorthand, **not** the whole article block grammar. Play islands are literal content, not interpolated expressions. Keep state and expressions in Play component nodes outside them.
|
|
97
89
|
|
|
98
90
|
```garden compose
|
|
99
|
-
<
|
|
100
|
-
|
|
91
|
+
<figure frame="none">
|
|
92
|
+
<markdown>
|
|
93
|
+
### Explicit test content
|
|
101
94
|
|
|
102
|
-
|
|
103
|
-
| :--- | :--- |
|
|
104
|
-
| `title` | 短标题 |
|
|
105
|
-
| `text` | 正文 |
|
|
106
|
-
| `caption` | 次要说明(默认 muted) |
|
|
107
|
-
| `label` | 控件标签 |
|
|
108
|
-
| `badge` | 胶囊徽标 |
|
|
109
|
-
| `kpi` | 指标数字(自闭合) |
|
|
110
|
-
| `stat` | kpi 别名 |
|
|
111
|
-
| `icon` | 具名描边图标(自闭合) |
|
|
112
|
-
| `callout` | 提示条 |
|
|
113
|
-
| `kbd` | 键盘键帽 |
|
|
114
|
-
| `link` | 行内链接 |
|
|
115
|
-
| `intent` | 作者原话(不绘制) |
|
|
116
|
-
|
|
117
|
-
### 控件
|
|
95
|
+
**Bold**, _emphasis_, `code`, [link](https://example.com), ~~strike~~ and <u>underline</u>.
|
|
118
96
|
|
|
119
|
-
|
|
120
|
-
|
|
97
|
+
- A full Markdown list
|
|
98
|
+
- Another test item
|
|
99
|
+
|
|
100
|
+
<details><summary>Safe HTML details</summary><p>Useful article HTML can coexist with Markdown.</p></details>
|
|
101
|
+
</markdown>
|
|
102
|
+
</figure>
|
|
121
103
|
```
|
|
122
104
|
|
|
123
|
-
|
|
124
|
-
| :--- | :--- |
|
|
125
|
-
| `button` | 按钮快照 |
|
|
126
|
-
| `slider` | 滑杆快照 / play 可调 |
|
|
127
|
-
| `progress` | 进度条 |
|
|
128
|
-
| `meter` | 计量条 |
|
|
129
|
-
| `checkbox` | 复选框快照 |
|
|
130
|
-
| `radio` | 单选快照 |
|
|
131
|
-
| `toggle` | 开关快照 |
|
|
132
|
-
| `switch` | toggle 别名 |
|
|
133
|
-
| `input` | 单行输入快照 |
|
|
134
|
-
| `textarea` | 多行输入快照 |
|
|
135
|
-
| `select` | 下拉快照 |
|
|
136
|
-
| `tabs` | 选项卡容器 |
|
|
137
|
-
| `tab` | 单个选项卡 |
|
|
138
|
-
| `list` | 列表 |
|
|
139
|
-
| `list-item` | 列表项 |
|
|
140
|
-
| `table` | 表格 |
|
|
141
|
-
| `thead` | 表头 |
|
|
142
|
-
| `tbody` | 表体 |
|
|
143
|
-
| `tr` | 表行 |
|
|
144
|
-
| `th` | 表头格 |
|
|
145
|
-
| `td` | 表数据格 |
|
|
146
|
-
| `image` | 图片 |
|
|
147
|
-
| `avatar` | 头像占位 |
|
|
148
|
-
| `empty` | 空状态 |
|
|
149
|
-
| `option` | 分段选项快照 |
|
|
150
|
-
|
|
151
|
-
### 连接糖
|
|
105
|
+
Safe HTML supports allowlisted local `style` properties, including useful layout and typography; inspect the generated schema for the actual set. Unsupported tags/properties, events, unsafe URLs, executable scripts and network CSS functions report diagnostics. Do not expand the article allowlist into arbitrary execution. An intentional executable demo uses `sandbox` inside the **same Compose entry**, with literal html/css/js and no parent origin access. Sandbox layout is its own document, not inherited article prose.
|
|
152
106
|
|
|
153
|
-
|
|
154
|
-
<stack align="center" gap={1}><pill>起点</pill><arrow dir="down"/><band tone="accent" align="center"><title size="sm">枢纽</title></band></stack>
|
|
155
|
-
```
|
|
107
|
+
## Verification levels
|
|
156
108
|
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
| `lanes` | 泳道图 |
|
|
163
|
-
| `actor` | 泳道角色 |
|
|
164
|
-
| `message` | 泳道消息 |
|
|
165
|
-
| `steps` | 分步容器 |
|
|
166
|
-
| `step` | 一步 |
|
|
167
|
-
| `note` | 步骤展开说明 |
|
|
168
|
-
| `compare` | 对照卡组 |
|
|
169
|
-
| `item` | 对照项 |
|
|
170
|
-
| `code` | 代码快照 |
|
|
171
|
-
| `pre` | 预格式文本 |
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
## 图表示例
|
|
175
|
-
|
|
176
|
-
玩法级图表示例(静态八柱、融合权重滑杆)见 [说明图 · compose](/garden/components/compose#ui-compose-chart-active-hours)。
|
|
177
|
-
|
|
178
|
-
## 限制
|
|
179
|
-
|
|
180
|
-
- 嵌套约 10 层 / 约 220 节点。
|
|
181
|
-
- 只有白话、没有标签时报 `compose-uncompiled`。
|
|
182
|
-
- Play(`{@body}`、`{#if}` …)见仓库 `docs/compose-dil.md`;静态围栏里的控件标签画成默认态快照。
|
|
109
|
+
1. Run `npx garden ui check <file>` (and `npx garden check <file>` for real file paths). Preserve original text/resources and inspect diagnostics.
|
|
110
|
+
2. Parse/render the actual scene; confirm accepted properties survive normalization and meaningful content appears.
|
|
111
|
+
3. Inspect the complete-theme render: icon rail fixed, heading and **all** paragraphs share the same right edge/left edge, no centered headings or full-width body beneath a detached icon row, dividers outside rows, no unintended cards/arrows, no horizontal overflow.
|
|
112
|
+
4. Check desktop and narrow screenshots plus geometry/computed styles; exercise choices, relations, file previews, state updates and sandbox behavior when used.
|
|
113
|
+
5. A hand-authored passing scene proves engine capability, not that an independent model reliably produces it from a short prompt. Report those claims separately.
|
|
@@ -1,29 +1,13 @@
|
|
|
1
1
|
---
|
|
2
2
|
title: 组件参考
|
|
3
|
-
navTitle:
|
|
4
|
-
description:
|
|
3
|
+
navTitle: 组件参考
|
|
4
|
+
description: 组件参考
|
|
5
5
|
section: reference
|
|
6
6
|
order: 0
|
|
7
7
|
---
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
文章布局、富文本、语义场景与交互说明统一使用一个 `garden compose` 围栏。在入口内部选择并组合组件;普通 Markdown 已能表达清楚时不用增加组件。
|
|
10
10
|
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
| 组件 | 用途 |
|
|
16
|
-
| :--- | :--- |
|
|
17
|
-
| [`card`](/garden/reference/card) | 介绍一篇论文、一个项目或一组值得参考的公开工具。 |
|
|
18
|
-
| [`stat`](/garden/reference/stat) | 把 2~4 个关键数字、单位与一句说明并排摆出来。 |
|
|
19
|
-
| [`compare`](/garden/reference/compare) | 把两三种方案左右并列,或把不好的做法与更好的做法上下对照。 |
|
|
20
|
-
| [`timeline`](/garden/reference/timeline) | 按时间或阶段顺序排开版本演进、排查经过或关键节点。 |
|
|
21
|
-
| [`chart`](/garden/reference/chart) | 把一组算好的数字画成比例条形图,下方自带可展开的数据表。 |
|
|
22
|
-
| [`compose`](/garden/reference/compose) | 用卡片、箭头和注释画一张说明图;标签全表与共用 token。 |
|
|
23
|
-
| [`compose 图标`](/garden/reference/compose-icons) | 全部具名描边图标:字形 + 名字,按 A–Z 可扫。 |
|
|
24
|
-
| [`html`](/garden/reference/html) | 在沙盒中运行一段独立的网页小工具、画布动画或演示。 |
|
|
25
|
-
| [`interactive`](/garden/reference/interactive) | 让读者拖动滑杆或切换选项,实时看到公式和图表的计算结果。 |
|
|
26
|
-
| [`file`](/garden/reference/file) | 给读者提供一份或一组可下载的文件,支持在当前页展开预览。 |
|
|
27
|
-
| [`relations`](/garden/reference/relations) | 把三到六个要素排成环或中心辐射结构,画出谁影响谁、哪些是双向的。 |
|
|
28
|
-
| [`list`](/garden/reference/list) | 用线条图标配短句列出几条并列动作,或带小标题列出分步做法。 |
|
|
29
|
-
| [`choice`](/garden/reference/choice) | 给出两三个具体选项卡片,读者点选后看到对应的回应。 |
|
|
11
|
+
- [Compose](/garden/components/compose)
|
|
12
|
+
- [Compose reference](/garden/reference/compose)
|
|
13
|
+
- [Icons](/garden/reference/compose-icons)
|
package/docs/handbook/start.md
CHANGED
|
@@ -93,7 +93,7 @@ make check
|
|
|
93
93
|
|
|
94
94
|
## 5. 编辑器插件
|
|
95
95
|
|
|
96
|
-
写交互组件时,可以在 VS Code、Cursor 或 Typora 里插入想法、预览组件、打开清单,再把编译交给 `garden-
|
|
96
|
+
写交互组件时,可以在 VS Code、Cursor 或 Typora 里插入想法、预览组件、打开清单,再把编译交给 `garden-compose` skill。插件随 `hd-garden` 发布,不用自己编译。
|
|
97
97
|
|
|
98
98
|
`npx hd-garden init` 会把产物放到 `.garden/editors/`。终端可交互时分别询问是否安装 VS Code / Cursor 和 Typora。第一次 `npx garden sync` 如果还没问过,会再问一次。没有 TTY、`CI=1` 或 `GARDEN_SKIP_EDITORS=1` 时只打印提示。之后运行:
|
|
99
99
|
|
|
@@ -41,22 +41,17 @@ order: 40
|
|
|
41
41
|
| `missing-title` / `missing-description` | 错误 | Front Matter 缺少有效的 `title` 或 `description` |
|
|
42
42
|
| `unexpected-slug` | 错误 | Front Matter 中手写了 `slug` 字段(文件名即标识,删掉 `slug`) |
|
|
43
43
|
| `date-format` | 错误 | `date` 不是合法的 `YYYY-MM-DD`、`YYYY-MM-DD HH:mm:ss` 或带时区的 ISO 时间 |
|
|
44
|
-
| `missing-cover` / `missing-asset` | 错误 | `cover` 封面图、正文图片或 `
|
|
44
|
+
| `missing-cover` / `missing-asset` | 错误 | `cover` 封面图、正文图片或 Compose `file` 引用的本地文件不存在 |
|
|
45
45
|
| `heading-h1` / `heading-skip` | 错误 | 正文使用了 `#` 一级标题,或标题层级跳级(例如从 `##` 直接跳到 `####`) |
|
|
46
46
|
| `reference-heading` | 错误 | 正文写了 `## 参考` 或 `## 参考资料` 标题(应改放到 Front Matter 的 `references` 列表) |
|
|
47
47
|
| `callout-type` | 错误 | `> [!TYPE]` 使用了不支持的提示框类型 |
|
|
48
48
|
| `title-split` | 警告 | 标题包含 `丨` 分隔符,但分隔符左边或右边为空(应写成「主题丨副题」) |
|
|
49
49
|
| `diff-orphan` | 错误 | `diff` 代码块前面没有紧挨着的完整代码块 |
|
|
50
|
-
| `legacy-fence` | 错误 | 使用了旧版围栏名(如 `garden:stat`、`widget`、`embed`、`html garden`),需改为 `garden <name>` |
|
|
51
|
-
| `garden-idea` | 错误 | 非草稿文章里还有未编译的空白 `garden` 想法块 |
|
|
52
50
|
| `compose-uncompiled` | 错误 | 非草稿里的 `garden compose` 还是白话,没有编译成标记 |
|
|
53
51
|
| `compose-invalid` | 错误 | `garden compose` 的标记不合法:未知标签、没闭合,或写成了 YAML 槽 |
|
|
54
|
-
| `garden-name` | 错误 |
|
|
55
|
-
| `
|
|
56
|
-
| `
|
|
57
|
-
| `garden-file` / `file-outside` | 错误 | `garden file` 手写了 `resolved`、缺少有效的 `src` / `files`,或本地路径越出了 `content/` 目录 |
|
|
58
|
-
| `file-large` | 警告 | `garden file` 引用的单个本地文件体积超过 `5 MB` |
|
|
59
|
-
| `compare-long` | 错误 | `garden compare` 并排模式下单个对比格的正文超过约 60 字(带 `verdict` 的上下对照不受此限) |
|
|
52
|
+
| `garden-name` | 错误 | 作者组件围栏统一使用 `garden compose`。 |
|
|
53
|
+
| `compose-file` / `file-outside` | 错误 | Compose `file` 手写了 `resolved`、缺少有效的 `src` / `files`,或本地路径越出了 `content/` 目录 |
|
|
54
|
+
| `file-large` | 警告 | Compose `file` 引用的单个本地文件体积超过 `5 MB` |
|
|
60
55
|
| `interactive-trivial` / `steps-prose` | 错误 | `garden compose` 只有一次简单乘法,或步骤只是散文而没有状态变化 |
|
|
61
56
|
|
|
62
57
|
## 3. Git 提交前钩子与组件画廊
|
|
@@ -77,15 +72,14 @@ Garden 通过以下三种方式提供组件模板与智能辅助:
|
|
|
77
72
|
1. **新建文章自动附带速查表**:运行 `make new SLUG=xxx TITLE="..."` 创建文章时,生成的 `.md` 文件底部会自动带有一段 `<!-- 组件速查 ... -->` HTML 注释,列出想法块和各个组件的示例写法,复制需要的那块即可。这段注释不会显示在页面上,写完可以删掉。
|
|
78
73
|
2. **代码片段模板文件**:`hd-garden` 包内的 `templates/` 目录自带两份模板文件:
|
|
79
74
|
- `templates/garden-blocks.md`:想法块和内置组件的可复制 Markdown 模板。
|
|
80
|
-
- `templates/garden-snippets.plist
|
|
81
|
-
3. **安装 AI Agent 技能(`npx garden skill`)**:在站点目录运行 `npx garden skill`(`npx hd-garden init`
|
|
82
|
-
- `garden-
|
|
83
|
-
- `garden-interactive-chart`:根据文章数据编写 `interactive`、`chart`、`compose` 与 `html` 组件。
|
|
75
|
+
- `templates/garden-snippets.plist`: one Compose author entry; choose components inside the scene.
|
|
76
|
+
3. **安装 AI Agent 技能(`npx garden skill`)**:在站点目录运行 `npx garden skill`(`npx hd-garden init` 时也会自动执行),会把两个技能复制到站点根目录下的 `.agents/skills/`:
|
|
77
|
+
- `garden-compose`:把文章里的 Compose 意图编译成同一入口内的布局、内容与交互。
|
|
84
78
|
- `garden-post-review`:按排版与组件规范审阅整篇文章。
|
|
85
79
|
|
|
86
80
|
## 5. VS Code、Cursor 与 Typora 插件
|
|
87
81
|
|
|
88
|
-
Intelligent UI 插件是写交互组件的编辑器入口:插入一句想法、在编辑器里预览、打开组件清单,再把编译交给 `garden-
|
|
82
|
+
Intelligent UI 插件是写交互组件的编辑器入口:插入一句想法、在编辑器里预览、打开组件清单,再把编译交给 `garden-compose` skill。插件随 `hd-garden` 发布,站点不用从 `editors/vscode` 或 `editors/typora` 源码编译。
|
|
89
83
|
|
|
90
84
|
### 安装
|
|
91
85
|
|
|
@@ -110,7 +104,7 @@ Obsidian 插件这一轮不随包安装。
|
|
|
110
104
|
|
|
111
105
|
### 在编辑器里怎么用
|
|
112
106
|
|
|
113
|
-
1. **插入想法。** VS Code / Cursor:macOS 用 `Cmd+Alt+I`,Windows / Linux 用 `Ctrl+Alt+I`,或命令「插入 Garden 块」。Typora:输入 `/` 后选 `/garden`(下一层列表每一项有一张小预览图),或命令「插入 Garden 块」直接打开组件列表(Windows / Linux 默认 `Ctrl+Alt+I`,macOS 请到「设置 → 快捷键」里自己录,因为 Option 会改写按键)。插入的是不带组件名的 `garden` 围栏,正文说明要写成哪种组件、写上哪些事实,交给 `garden-
|
|
107
|
+
1. **插入想法。** VS Code / Cursor:macOS 用 `Cmd+Alt+I`,Windows / Linux 用 `Ctrl+Alt+I`,或命令「插入 Garden 块」。Typora:输入 `/` 后选 `/garden`(下一层列表每一项有一张小预览图),或命令「插入 Garden 块」直接打开组件列表(Windows / Linux 默认 `Ctrl+Alt+I`,macOS 请到「设置 → 快捷键」里自己录,因为 Option 会改写按键)。插入的是不带组件名的 `garden` 围栏,正文说明要写成哪种组件、写上哪些事实,交给 `garden-compose` skill 编译。
|
|
114
108
|
2. **预览。** 打开 Markdown 预览(Typora 里光标离开围栏即可)。`ui` 块画成和博客一样的组件,`intent` 块显示成想法卡片。点滑杆、按钮不会跳回源码。
|
|
115
109
|
3. **看组件清单。** VS Code / Cursor 里用「查看组件清单」,点「用它开始」把配方插进当前稿件。终端里的同一份清单:
|
|
116
110
|
|
|
@@ -119,4 +113,14 @@ Obsidian 插件这一轮不随包安装。
|
|
|
119
113
|
```
|
|
120
114
|
|
|
121
115
|
生成 `.garden/ui-catalog.html`。
|
|
122
|
-
4. **交给 skill 编译。** 「复制编译提示词」在中文站点得到 `编译这篇:<相对路径>`,在 `locale: en_US` 的站点得到 `Compile this post: <相对路径>`。把这句话发给装了 `garden-
|
|
116
|
+
4. **交给 skill 编译。** 「复制编译提示词」在中文站点得到 `编译这篇:<相对路径>`,在 `locale: en_US` 的站点得到 `Compile this post: <相对路径>`。把这句话发给装了 `garden-compose` skill 的 Agent。它会运行 `npx garden ui scan`,阅读 `npx garden ui prompt`,再用 `npx garden ui apply` 只替换这一块。插件本身不调用模型。写完用 `npx garden ui check` 或提交前钩子再查一遍。
|
|
117
|
+
|
|
118
|
+
|
|
119
|
+
## 本地严格检查
|
|
120
|
+
|
|
121
|
+
运行 `make check`:检查工作区所有文章的结构和全部 Compose/UI 块,包含草稿与未跟踪的新稿,不必先暂存。结构错误不会阻止 Compose 检查;有待编译/错误块时显示诊断和调用项目 `garden-compose` skill 的短指令,默认不生成提示词文件。不会调用 AI 或复制剪贴板。
|
|
122
|
+
|
|
123
|
+
`make check FILE=content/posts/文章.md` 只限制内容预检范围;通过后仍执行原来的全站 sync/build(引擎仓库保留 lint/test)。预检失败返回非零并跳过后续阶段。这是编译/校验,不是自动格式化或自动改稿。
|
|
124
|
+
|
|
125
|
+
|
|
126
|
+
`make check diff` 只检查 `content/` 下相对 HEAD 有改动的 Markdown(含已暂存、未暂存)和未跟踪新稿,读取工作区当前内容,去重、取重命名后的路径、跳过已删除文件。不会继续运行全站 sync/build/lint/tests,`make -j check diff` 也只执行一次改动检查。没有改动则成功退出;不在 Git 仓库或没有 HEAD 时明确报错,不回退全量。底层命令是 `garden verify --diff`。diff 模式优先于 FILE;不带 diff 的 `make check` 不变。
|
package/docs/handbook/writing.md
CHANGED
|
@@ -62,12 +62,12 @@ func openStore(path string) (*Store, error) {
|
|
|
62
62
|
}
|
|
63
63
|
```
|
|
64
64
|
|
|
65
|
-
```garden
|
|
65
|
+
```garden compose
|
|
66
66
|
和上一版比:打开存储时的模式从 ModeJournal 改成了 ModeWAL。
|
|
67
67
|
```
|
|
68
68
|
````
|
|
69
69
|
|
|
70
|
-
Agent 按 `garden-
|
|
70
|
+
Agent 按 `garden-compose` skill 会通过 `npx garden ui apply` 把这段想法替换成紧挨着完整代码的 `diff` 围栏(详见 [用 AI 写作](/garden/ai-writing))。页面渲染时会把这两段合成一个可切换 **「代码」** 和 **「对比上一版」** 的代码框,右上角的复制按钮始终复制新版完整代码:
|
|
71
71
|
|
|
72
72
|
```go
|
|
73
73
|
func openStore(path string) (*Store, error) {
|