hd-garden 0.11.0 → 0.12.0
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/app/lib/garden-docs-meta.ts +2 -0
- package/docs/handbook/components/compose.md +11 -231
- package/docs/handbook/en/components/compose.md +43 -272
- package/docs/handbook/en/reference/compose-icons.md +863 -0
- package/docs/handbook/en/reference/compose.md +153 -75
- package/docs/handbook/en/reference.md +1 -0
- package/docs/handbook/reference/compose-icons.md +863 -0
- package/docs/handbook/reference/compose.md +156 -78
- package/docs/handbook/reference.md +2 -1
- package/editors/dist/typora/main.js +233 -233
- package/editors/dist/vscode/garden-ui-0.1.0.vsix +0 -0
- package/package.json +1 -1
- package/scripts/gen-compose-handbook.mjs +427 -0
- package/scripts/gen-compose-icons.mjs +236 -0
- package/ui/compose/compose.css +530 -12
- package/ui/compose/icons.mjs +774 -0
- package/ui/compose/index.mjs +2 -1
- package/ui/compose/markup.mjs +392 -29
- package/ui/compose/parse.mjs +8 -1
- package/ui/compose/render.mjs +155 -17
- package/ui/compose/tokens.mjs +50 -0
- package/ui/preview/dist/garden-ui.esm.js +234 -234
- package/ui/preview/dist/garden-ui.iife.js +234 -234
|
@@ -1,105 +1,90 @@
|
|
|
1
1
|
---
|
|
2
|
-
title:
|
|
3
|
-
navTitle:
|
|
4
|
-
description: Write a
|
|
2
|
+
title: Diagrams (compose)
|
|
3
|
+
navTitle: Diagrams
|
|
4
|
+
description: Write a short plain-language structure; AI compiles it into a static diagram.
|
|
5
5
|
section: components
|
|
6
6
|
order: 36
|
|
7
7
|
badge: compose
|
|
8
8
|
---
|
|
9
9
|
|
|
10
|
-
|
|
10
|
+
To draw a structure diagram in a post, type `/garden` and pick **compose (idea)**. That inserts a `garden compose` fence. Write the structure in plain language, then ask the AI to compile the post. It keeps your words in `<intent>` and builds the diagram from Markdown leaves plus catalog tags.
|
|
11
11
|
|
|
12
12
|
## How to write
|
|
13
13
|
|
|
14
|
-
|
|
14
|
+
Describe the structure readers should see. Do not prescribe styles.
|
|
15
15
|
|
|
16
|
-
|
|
16
|
+
Cover four things:
|
|
17
17
|
|
|
18
|
-
- **How many
|
|
19
|
-
- **
|
|
20
|
-
- **
|
|
21
|
-
- **Which
|
|
18
|
+
- **How many blocks**: three columns, five layers top-to-bottom, or two rows.
|
|
19
|
+
- **What each block is called**: short labels that appear on the diagram. Put explanations on the line under the name.
|
|
20
|
+
- **What connects to what**: who reaches whom, fans out, or joins. If there is no order, say so.
|
|
21
|
+
- **Which block is the focus**: name it (“the middle column”, “the lower row”).
|
|
22
22
|
|
|
23
|
-
Do not
|
|
23
|
+
Do not specify colors, radii, pill chrome, weight, gaps, shadows, or full-bleed. Defaults own appearance.
|
|
24
24
|
|
|
25
|
-
|
|
25
|
+
**Every tag and shared token**: [compose reference](/garden/en/reference/compose). **Every icon name**: [compose icons](/garden/en/reference/compose-icons).
|
|
26
26
|
|
|
27
|
-
|
|
27
|
+
## Rewrite patterns
|
|
28
28
|
|
|
29
|
-
|
|
29
|
+
Two common mistakes: naming only a topic with no structure, or spending the fence on colors and padding.
|
|
30
30
|
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
Name the three columns, the items under each one, the middle link, and the focus:
|
|
31
|
+
**Three columns, middle joins**
|
|
34
32
|
|
|
35
33
|
````markdown
|
|
36
34
|
```garden compose
|
|
37
|
-
Three columns: User
|
|
38
|
-
Permission
|
|
39
|
-
Role sits in the middle and
|
|
35
|
+
Three columns: User under Alice, Bob; Role under admin, reviewer;
|
|
36
|
+
Permission under orders:read, orders:approve.
|
|
37
|
+
Role sits in the middle and joins users to permissions. Role is the focus.
|
|
40
38
|
```
|
|
41
39
|
````
|
|
42
40
|
|
|
43
|
-
**
|
|
44
|
-
|
|
45
|
-
Instead of "Draw SSO with nicer arrows and even spacing," state what reaches the hub first and which systems it branches out to:
|
|
41
|
+
**Hub, then fan out**
|
|
46
42
|
|
|
47
43
|
````markdown
|
|
48
44
|
```garden compose
|
|
49
|
-
The browser reaches the identity provider first, then
|
|
50
|
-
|
|
51
|
-
All three systems trust that provider. The identity provider is the focus.
|
|
45
|
+
The browser reaches the identity provider first, then fans out to HR, Finance, and Project.
|
|
46
|
+
All three trust the same IdP. The IdP is the focus.
|
|
52
47
|
```
|
|
53
48
|
````
|
|
54
49
|
|
|
55
|
-
**Top-
|
|
56
|
-
|
|
57
|
-
Instead of "Five full-width bands, color the second and fifth, thin arrows," list the five layer names, pick the two to highlight, and note whether every request walks them in order:
|
|
50
|
+
**Top-down layers**
|
|
58
51
|
|
|
59
52
|
````markdown
|
|
60
53
|
```garden compose
|
|
61
|
-
Five layers top to bottom:
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
Not every request walks all five in order.
|
|
54
|
+
Five layers top to bottom: browser, identity, BFF, business service, authorization.
|
|
55
|
+
Identity and authorization are the focus; the rest are paths through.
|
|
56
|
+
Not every request walks the whole stack in order.
|
|
65
57
|
```
|
|
66
58
|
````
|
|
67
59
|
|
|
68
|
-
**
|
|
69
|
-
|
|
70
|
-
Instead of "Two rows of two cards, then two more, unbolded titles," give the six short names, the one-line question under each, the two groups, and the non-sequential note:
|
|
60
|
+
**Several facets of one request**
|
|
71
61
|
|
|
72
62
|
````markdown
|
|
73
63
|
```garden compose
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
For business logic and storage, check Transport and Confidentiality. Not a strict sequence.
|
|
64
|
+
After the user sends a request, look at four facets: authentication, credential,
|
|
65
|
+
authorization, verification. Then transport and secrecy. No strict order among the six.
|
|
77
66
|
```
|
|
78
67
|
````
|
|
79
68
|
|
|
80
|
-
**Two
|
|
81
|
-
|
|
82
|
-
Instead of "Borderless text on top, grey pills below, hug the content," state which row is background and which row carries the point:
|
|
69
|
+
**Two rows to contrast**
|
|
83
70
|
|
|
84
71
|
````markdown
|
|
85
72
|
```garden compose
|
|
86
|
-
Top row is
|
|
87
|
-
Bottom row is the
|
|
88
|
-
|
|
73
|
+
Top row is delivery: understand → design → ship.
|
|
74
|
+
Bottom row is the exploration loop: hypothesize → cheap test → iterate or drop.
|
|
75
|
+
Top is background; the bottom row is the point.
|
|
89
76
|
```
|
|
90
77
|
````
|
|
91
78
|
|
|
92
|
-
##
|
|
93
|
-
|
|
94
|
-
**The diagrams below are only examples** showing the layout shapes `compose` can build. The sample topics (permissions, sign-in, APIs) are just filler text; replace them with your own subject when writing a post.
|
|
79
|
+
## Icons and surfaces
|
|
95
80
|
|
|
96
|
-
|
|
81
|
+
Use `<icon name="check-circle"/>` — not emoji. Combine `padding`, `background`, and `radius` for small chips; do not invent one-off tags per diagram.
|
|
97
82
|
|
|
98
|
-
|
|
83
|
+
## One sample
|
|
99
84
|
|
|
100
85
|
```garden compose
|
|
101
86
|
<intent>
|
|
102
|
-
Three columns: User
|
|
87
|
+
Three columns: User under Alice and Bob; Role under admin and reviewer; Permission under orders:read and orders:approve. Role joins the sides and should be seen first.
|
|
103
88
|
</intent>
|
|
104
89
|
<row align="center">
|
|
105
90
|
<stack align="center">
|
|
@@ -109,8 +94,8 @@ Three columns: User with Alice and Bob, Role with Administrator and Reviewer, Pe
|
|
|
109
94
|
</stack>
|
|
110
95
|
<band tone="accent" align="center">
|
|
111
96
|
<title>Role</title>
|
|
112
|
-
<text>
|
|
113
|
-
<text>
|
|
97
|
+
<text>admin</text>
|
|
98
|
+
<text>reviewer</text>
|
|
114
99
|
</band>
|
|
115
100
|
<stack align="center">
|
|
116
101
|
<title>Permission</title>
|
|
@@ -118,235 +103,21 @@ Three columns: User with Alice and Bob, Role with Administrator and Reviewer, Pe
|
|
|
118
103
|
<text>orders:approve</text>
|
|
119
104
|
</stack>
|
|
120
105
|
</row>
|
|
121
|
-
<join>Role
|
|
106
|
+
<join>Role joins users to permissions</join>
|
|
122
107
|
<text tone="muted" align="center">Concept: User ↔ Role ↔ Permission</text>
|
|
123
108
|
```
|
|
124
109
|
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
Flow into one highlighted band first, then branch to several targets at once with `<fan>`.
|
|
128
|
-
|
|
129
|
-
```garden compose
|
|
130
|
-
<intent>
|
|
131
|
-
The browser reaches the identity provider first. The identity provider then connects to HR, Finance, and Project at once. All three systems trust that same provider. The identity provider is the layer to see first.
|
|
132
|
-
</intent>
|
|
133
|
-
<stack align="center">
|
|
134
|
-
<pill>Browser</pill>
|
|
135
|
-
<arrow dir="down"/>
|
|
136
|
-
<band tone="accent" align="center">
|
|
137
|
-
<title>Identity Provider (IdP)</title>
|
|
138
|
-
<text>Verifies identity, keeps the session, and issues an assertion</text>
|
|
139
|
-
</band>
|
|
140
|
-
<fan n="3"/>
|
|
141
|
-
<row align="center">
|
|
142
|
-
<title>HR</title>
|
|
143
|
-
<title>Finance</title>
|
|
144
|
-
<title>Project</title>
|
|
145
|
-
</row>
|
|
146
|
-
<text tone="muted" align="center">All three systems trust the same identity provider</text>
|
|
147
|
-
</stack>
|
|
148
|
-
```
|
|
149
|
-
|
|
150
|
-
### Top-to-bottom layers
|
|
151
|
-
|
|
152
|
-
Vertical steps where the key layers use `<band>` and the pass-through hops stay plain text.
|
|
153
|
-
|
|
154
|
-
```garden compose
|
|
155
|
-
<intent>
|
|
156
|
-
Five layers from top to bottom: browser, identity service, BFF, business service, authorization decision. The identity service and the authorization decision are the two layers to emphasize. The others are the path. Not every request walks the layers in this order.
|
|
157
|
-
</intent>
|
|
158
|
-
<stack align="center">
|
|
159
|
-
<box frame="text" align="center">
|
|
160
|
-
<badge>1</badge>
|
|
161
|
-
<title>Browser / App</title>
|
|
162
|
-
<text>Cookie, session, OAuth client</text>
|
|
163
|
-
</box>
|
|
164
|
-
<arrow dir="down"/>
|
|
165
|
-
<band tone="accent" align="center">
|
|
166
|
-
<badge>2</badge>
|
|
167
|
-
<title>Identity service (IdP / IAM)</title>
|
|
168
|
-
<text>Passkey, MFA, OIDC, session management</text>
|
|
169
|
-
</band>
|
|
170
|
-
<arrow dir="down"/>
|
|
171
|
-
<box frame="text" align="center">
|
|
172
|
-
<badge>3</badge>
|
|
173
|
-
<title>BFF / API Gateway</title>
|
|
174
|
-
<text>Session check, token check, entry authorization</text>
|
|
175
|
-
</box>
|
|
176
|
-
<arrow dir="down"/>
|
|
177
|
-
<box frame="text" align="center">
|
|
178
|
-
<badge>4</badge>
|
|
179
|
-
<title>Business service</title>
|
|
180
|
-
<text>Orders, payments, accounts, resources</text>
|
|
181
|
-
</box>
|
|
182
|
-
<arrow dir="down"/>
|
|
183
|
-
<band tone="tip" align="center">
|
|
184
|
-
<badge>5</badge>
|
|
185
|
-
<title>Authorization decision</title>
|
|
186
|
-
<text>RBAC + ABAC + ReBAC + Policy Engine</text>
|
|
187
|
-
</band>
|
|
188
|
-
<text tone="muted" align="start">Duties, not a required hop order. The identity service is usually involved at login. The business service calls the decision system while handling the request.</text>
|
|
189
|
-
</stack>
|
|
190
|
-
```
|
|
191
|
-
|
|
192
|
-
### Multiple facets of one subject
|
|
193
|
-
|
|
194
|
-
Non-sequential aspects grouped into rows of `<box>` cards.
|
|
195
|
-
|
|
196
|
-
```garden compose
|
|
197
|
-
<intent>
|
|
198
|
-
The user wants to change an order address. Split that into authentication, credential, authorization, and verification, one question each. Then transport and confidentiality. These six are not a strict sequence.
|
|
199
|
-
</intent>
|
|
200
|
-
<stack align="center">
|
|
201
|
-
<title>The user calls an API</title>
|
|
202
|
-
<text tone="muted">Example: change an order address</text>
|
|
203
|
-
</stack>
|
|
204
|
-
<arrow dir="down"/>
|
|
205
|
-
<row>
|
|
206
|
-
<box>
|
|
207
|
-
<title>Authentication</title>
|
|
208
|
-
<text>Who are you?</text>
|
|
209
|
-
</box>
|
|
210
|
-
<box>
|
|
211
|
-
<title>Credential</title>
|
|
212
|
-
<text>How do you prove it?</text>
|
|
213
|
-
</box>
|
|
214
|
-
</row>
|
|
215
|
-
<row>
|
|
216
|
-
<box>
|
|
217
|
-
<title>Authorization</title>
|
|
218
|
-
<text>May you change this order?</text>
|
|
219
|
-
</box>
|
|
220
|
-
<box>
|
|
221
|
-
<title>Verification</title>
|
|
222
|
-
<text>Is the payload valid?</text>
|
|
223
|
-
</box>
|
|
224
|
-
</row>
|
|
225
|
-
<arrow dir="down"/>
|
|
226
|
-
<stack align="center">
|
|
227
|
-
<title>Business operation and storage</title>
|
|
228
|
-
</stack>
|
|
229
|
-
<row>
|
|
230
|
-
<box>
|
|
231
|
-
<title>Transport</title>
|
|
232
|
-
<text>Can the network be read, changed, or spoofed?</text>
|
|
233
|
-
</box>
|
|
234
|
-
<box>
|
|
235
|
-
<title>Confidentiality</title>
|
|
236
|
-
<text>Can a leaked secret still be read?</text>
|
|
237
|
-
</box>
|
|
238
|
-
</row>
|
|
239
|
-
<text tone="muted">Not a strict sequence. Transport covers the whole connection, and confidentiality can sit on both client and server.</text>
|
|
240
|
-
```
|
|
241
|
-
|
|
242
|
-
### Container with nested checks
|
|
243
|
-
|
|
244
|
-
A larger `<band>` or `<box>` holding a row of badges or a two-column checklist inside it.
|
|
245
|
-
|
|
246
|
-
```garden compose
|
|
247
|
-
<intent>
|
|
248
|
-
User intent goes through the agent, then a policy enforcement point, then the tool executor. The policy point holds four checks and is the layer to see first.
|
|
249
|
-
</intent>
|
|
250
|
-
<stack align="center">
|
|
251
|
-
<title>User Intent + Authorization</title>
|
|
252
|
-
<text tone="muted">Task, identity, and the scope that was granted</text>
|
|
253
|
-
<arrow dir="down"/>
|
|
254
|
-
<band align="center">
|
|
255
|
-
<title>Agent / LLM</title>
|
|
256
|
-
<text>Understands, plans, and proposes an action</text>
|
|
257
|
-
<row align="center">
|
|
258
|
-
<badge>Untrusted Context</badge>
|
|
259
|
-
<badge>Memory</badge>
|
|
260
|
-
<badge>Tool Results</badge>
|
|
261
|
-
</row>
|
|
262
|
-
</band>
|
|
263
|
-
<arrow dir="down"/>
|
|
264
|
-
<box align="center" mark="shield">
|
|
265
|
-
<title>Policy Enforcement Point</title>
|
|
266
|
-
<text tone="muted" align="center">Deterministic control, separate from the LLM</text>
|
|
267
|
-
<row align="center">
|
|
268
|
-
<text>Permission and resource scope</text>
|
|
269
|
-
<text>Argument checks</text>
|
|
270
|
-
</row>
|
|
271
|
-
<row align="center">
|
|
272
|
-
<text>Task-intent limits</text>
|
|
273
|
-
<text>Approval for risky actions</text>
|
|
274
|
-
</row>
|
|
275
|
-
</box>
|
|
276
|
-
<arrow dir="down"/>
|
|
277
|
-
<title>Tool Executor</title>
|
|
278
|
-
<text tone="muted">Least privilege, an audit record, and a way to stop</text>
|
|
279
|
-
</stack>
|
|
280
|
-
```
|
|
281
|
-
|
|
282
|
-
### Multi-actor sequence
|
|
283
|
-
|
|
284
|
-
Several actors passing messages back and forth across `<lanes>`.
|
|
285
|
-
|
|
286
|
-
```garden compose
|
|
287
|
-
<intent>
|
|
288
|
-
Three lanes (user, client, authorization server) and six steps for the authorization code with PKCE.
|
|
289
|
-
</intent>
|
|
290
|
-
<lanes>
|
|
291
|
-
<actor>User</actor>
|
|
292
|
-
<actor>Client</actor>
|
|
293
|
-
<actor>Authorization server</actor>
|
|
294
|
-
<message from="1" to="2" tone="forward">Click sign-in</message>
|
|
295
|
-
<message from="2" to="3" tone="forward">Authorization request + PKCE</message>
|
|
296
|
-
<message from="3" to="1" tone="back">Authenticate and approve</message>
|
|
297
|
-
<message from="3" to="2" tone="back">Redirect back with a code</message>
|
|
298
|
-
<message from="2" to="3" tone="forward">Code + verifier for a token</message>
|
|
299
|
-
<message from="3" to="2" tone="back">Return the token</message>
|
|
300
|
-
</lanes>
|
|
301
|
-
<text tone="muted">A sketch. The real flow also binds the browser redirect, the callback, and checks on the code and token.</text>
|
|
302
|
-
```
|
|
303
|
-
|
|
304
|
-
### Two-row contrast flow
|
|
305
|
-
|
|
306
|
-
Plain titles on top as background, a `<divider/>` in between, and muted pills on the bottom row for the loop that matters.
|
|
307
|
-
|
|
308
|
-
```garden compose
|
|
309
|
-
<intent>
|
|
310
|
-
The top row is delivery order: Understand, Design, Ship. The bottom row is the decision loop to emphasize: Hypothesize, Cheap test, Iterate or stop. The top row is background. The bottom row is the point.
|
|
311
|
-
</intent>
|
|
312
|
-
<row align="center">
|
|
313
|
-
<title align="center">Understand</title>
|
|
314
|
-
<arrow dir="right"/>
|
|
315
|
-
<title align="center">Design</title>
|
|
316
|
-
<arrow dir="right"/>
|
|
317
|
-
<title align="center">Ship</title>
|
|
318
|
-
</row>
|
|
319
|
-
<divider/>
|
|
320
|
-
<row align="center">
|
|
321
|
-
<pill tone="muted">Hypothesize</pill>
|
|
322
|
-
<arrow dir="right"/>
|
|
323
|
-
<pill tone="muted">Cheap test</pill>
|
|
324
|
-
<arrow dir="right"/>
|
|
325
|
-
<pill tone="muted">Iterate or stop</pill>
|
|
326
|
-
</row>
|
|
327
|
-
<text tone="muted">The second row is the decision loop that product discovery emphasizes.</text>
|
|
328
|
-
```
|
|
329
|
-
|
|
330
|
-
## Play mode
|
|
331
|
-
|
|
332
|
-
When a static diagram still needs reader-tunable parameters, keep the `garden compose` fence and write the same DIL shape:
|
|
110
|
+
## Play (tunable)
|
|
333
111
|
|
|
334
|
-
|
|
335
|
-
- `{@body const total = n * 24}` for derived values
|
|
336
|
-
- `{total}` / `value={n}` interpolation
|
|
337
|
-
- `{#if …}{:else}{/if}` and `{#each … as item, i}{/each}`
|
|
338
|
-
- Lowercase controls: `<slider>`, `<choice>`, `<button>`, `<pie>` / `<chart>`, `<stat>`
|
|
339
|
-
|
|
340
|
-
Legacy `garden interactive` and PascalCase `<State>` / `<Slider>` remain as compatibility only. See `docs/compose-dil.md` for the mapping.
|
|
112
|
+
Stay on `garden compose` and use DIL when readers need a dial. Mapping: repo `docs/compose-dil.md`.
|
|
341
113
|
|
|
342
114
|
```garden compose #compose-play-demo
|
|
343
|
-
caption:
|
|
115
|
+
caption: Twist seats; watch the monthly fee.
|
|
344
116
|
intent: |
|
|
345
|
-
Let the reader change seat count and
|
|
117
|
+
Let the reader change seat count and see price.
|
|
346
118
|
---
|
|
347
119
|
{@body const [seats, setSeats] = DIL.useState(3)}
|
|
348
120
|
{@body const total = seats * 24}
|
|
349
121
|
<slider min={1} max={12} value={seats} onChange={setSeats} label="Seats" />
|
|
350
122
|
<stat label="Monthly" value={total} unit="USD" />
|
|
351
123
|
```
|
|
352
|
-
|