sketchmark 1.0.3 → 1.1.1

package/README.md

@@ -60,15 +60,52 @@ a --> b label="greets"
 end
 `.trim();
 
-const instance = render({
-  container: document.getElementById('diagram'),
-  dsl,
-  renderer: 'svg',
-  svgOptions: { showTitle: true, theme: 'light', transparent: true },
-});
-```
-
----
+const instance = render({
+  container: document.getElementById('diagram'),
+  dsl,
+  renderer: 'svg',
+  svgOptions: { showTitle: true, theme: 'light', transparent: true },
+});
+```
+
+### Reusable UI Widgets
+
+```javascript
+import { SketchmarkCanvas, SketchmarkEditor } from 'sketchmark';
+
+const editor = new SketchmarkEditor({
+  container: document.getElementById('editor'),
+  value: `
+diagram
+box app label="App"
+box api label="API"
+app --> api
+end
+`.trim(),
+});
+
+const canvas = new SketchmarkCanvas({
+  container: document.getElementById('viewport'),
+});
+
+canvas.bindEditor(editor);
+```
+
+```javascript
+import { SketchmarkEmbed } from 'sketchmark';
+
+const embed = new SketchmarkEmbed({
+  container: document.getElementById('article-embed'),
+  dsl,
+  width: 960,
+  height: 540,
+  playStepDelay: 700,
+});
+```
+
+Use `SketchmarkCanvas` for the full playground-style surface, and `SketchmarkEmbed` for fixed-size embeds that clip overflow and follow animation targets as steps advance.
+
+---
 
 ## Framework Setup
 
@@ -363,22 +400,34 @@ a --> b label="HTTPS" stroke="#cc0000" stroke-width=2 color="#aa0000" font-size=
 
 ---
 
-## Groups
-
-Groups visually contain one or more nodes, tables, or nested groups.
-
-```
-group <id> [label="..."] [layout=row|column|grid] [gap=N] [padding=N]
-           [columns=N] [align=start|center|end]
-           [justify=start|center|end|space-between|space-around]
-           [theme=...] [fill="..."] [stroke="..."] [width=N] [height=N]
-{
-  box a label="Node A"
-  box b label="Node B"
-  # nested groups allowed:
-  group inner label="Inner Group" layout=row { box c label="C" }
-}
-```
+## Groups
+
+Groups visually contain one or more nodes, tables, charts, markdown blocks,
+or other groups by referencing their ids with `items=[...]`.
+
+```
+box a label="Node A"
+box b label="Node B"
+box c label="Node C"
+
+group inner label="Inner Group" layout=row items=[c]
+group outer label="Outer Group" layout=column items=[a,b,inner]
+```
+
+General form:
+
+```
+group <id> [label="..."] [layout=row|column|grid] [gap=N] [padding=N]
+           [columns=N] [align=start|center|end]
+           [justify=start|center|end|space-between|space-around]
+           [theme=...] [fill="..."] [stroke="..."] [width=N] [height=N]
+           [items=[id1,id2,...]]
+```
+
+- Groups are always declared at the top level.
+- `items` order is the visual child order.
+- Nested groups are created by referencing another group id from `items=[...]`.
+- All authored nodes, groups, tables, charts, and markdown blocks must have explicit ids.
 
 ### Group Properties
 
@@ -400,14 +449,13 @@ group <id> [label="..."] [layout=row|column|grid] [gap=N] [padding=N]
 
 #### `bare` keyword
 
-`bare` is an alias for a group with no visible border or fill:
-
-```
-bare myContainer {
-  box a label="Floating A"
-  box b label="Floating B"
-}
-```
+`bare` is an alias for a group with no visible border or fill:
+
+```
+box a label="Floating A"
+box b label="Floating B"
+bare myContainer layout=row items=[a,b]
+```
 
 ---
 
@@ -534,9 +582,9 @@ theme muted   fill="#f5f5f5" stroke="#999999" color="#444444"
 
 box client  label="Client"  theme=primary
 box server  label="Server"  theme=warning
-cylinder db label="DB"      theme=success
-group services label="Services" theme=muted { ... }
-```
+cylinder db label="DB"      theme=success
+group services label="Services" theme=muted items=[client,server,db]
+```
 
 ---
 
@@ -1062,8 +1110,8 @@ exportHTML(instance.svg, dslSource, { filename: 'diagram.html' });
 | `<-->` | Edge | `a <--> b` |
 | `--` | Edge | `a -- b` |
 | `---` | Edge | `a --- b` |
-| `group` | Group | `group myGroup label="Services" layout=column { ... }` |
-| `bare` | Group | `bare myWrap { ... }` |
+| `group` | Group | `group myGroup label="Services" layout=column items=[api,db]` |
+| `bare` | Group | `bare myWrap layout=row items=[a,b]` |
 | `table` | Table | `table myTable label="Users" { header Name Age }` |
 | `bar-chart` | Chart | `bar-chart sales label="Sales" data [...]` |
 | `line-chart` | Chart | `line-chart trend data [...]` |