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.
@@ -1,105 +1,90 @@
1
1
  ---
2
- title: Explanation diagram (compose)
3
- navTitle: compose
4
- description: Write a few plain sentences in a post and let the AI assemble a static diagram.
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
- When a post needs a structure diagram, type `/garden` and pick `compose`. That inserts a `garden compose` fence. Write the structure in plain language inside the fence, then ask the AI to compile the post. Your sentence stays inside `<intent>`, and the AI fills in Markdown leaves and component tags to render a static diagram.
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
- Write the structure you want the reader to see. Do not describe the look.
14
+ Describe the structure readers should see. Do not prescribe styles.
15
15
 
16
- Four things:
16
+ Cover four things:
17
17
 
18
- - **How many parts**: three columns side by side, five layers top to bottom, or two rows.
19
- - **Short names**: the words shown on the diagram. Put the explanation on the line below, not inside the title.
20
- - **Who connects to whom**: what goes to what first, where one box fans out, or where sides meet. If there is no order, say "not a strict sequence."
21
- - **Which part is the point**: name it directly, such as "the middle column is the focus" or "the bottom row is the point."
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 write colors, rounded corners, grey pills, font weights, spacing, shadows, or full-width rules. Component defaults handle the look. Every tag is listed in [Component reference · compose](/garden/en/reference/compose).
23
+ Do not specify colors, radii, pill chrome, weight, gaps, shadows, or full-bleed. Defaults own appearance.
24
24
 
25
- ## Best practices
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
- Two things usually go wrong in an intent fence: naming only a topic with no structure, or spending the sentence on colors, corner radii, and font weights. Below are five common structures showing what to avoid and how to write the fence instead.
27
+ ## Rewrite patterns
28
28
 
29
- **Three columns joined in the middle**
29
+ Two common mistakes: naming only a topic with no structure, or spending the fence on colors and padding.
30
30
 
31
- Writing only "Draw a permissions diagram" gives no columns or names; writing "Three equal columns, light grey rounded box in the middle, lighter font weight" only describes styling.
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 has Alice and Bob; Role has Administrator and Reviewer;
38
- Permission has orders:read and orders:approve.
39
- Role sits in the middle and connects users to permissions. Role is the focus.
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
- **Converge, then fan out**
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 connects to
50
- HR, Finance, and Project at once.
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-to-bottom layers**
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: Browser, Identity Service, BFF,
62
- Business Service, Authorization Decision.
63
- Identity Service and Authorization Decision are the focus; the rest are the path.
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
- **Multiple facets of one subject**
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
- When a user sends a request, check four things first: Authentication (who you are),
75
- Credential (how you prove it), Authorization (whether you may), Validation (whether data is valid).
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-row contrast flow**
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 standard delivery: Understand -> Design -> Ship.
87
- Bottom row is the discovery loop: Hypothesize -> Cheap test -> Iterate or drop.
88
- The top row is background; the bottom row is the point.
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
- ## Capability examples
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
- ### Three columns joined in the middle
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
- Two outer lists linked through a middle column, pulled together at the bottom with `<join>`.
83
+ ## One sample
99
84
 
100
85
  ```garden compose
101
86
  <intent>
102
- Three columns: User with Alice and Bob, Role with Administrator and Reviewer, Permission with orders:read and orders:approve. Role sits in the middle and connects users to permissions. Role is the layer to see first.
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>Administrator</text>
113
- <text>Reviewer</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 connects users and permissions</join>
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
- ### Converge, then fan out
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
- - `{@body const [n, setN] = DIL.useState(3)}` for state
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: Drag seats to see the monthly bill.
115
+ caption: Twist seats; watch the monthly fee.
344
116
  intent: |
345
- Let the reader change seat count and watch the total.
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
-