@wireweave/core 3.0.0 → 3.1.0-beta.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/README.md CHANGED
@@ -1,475 +1,139 @@
1
- <p align="center">
2
- <img src="https://docs.wireweave.org/assets/wireweave-core.svg" width="128" height="128" alt="Wireweave Core">
3
- </p>
1
+ # @wireweave/core
4
2
 
5
- <h1 align="center">@wireweave/core</h1>
3
+ The parser and renderer for the Wireweave wireframe DSL.
6
4
 
7
- <p align="center">Core parser and renderers for Wireweave DSL</p>
5
+ ## What it does
8
6
 
9
- ## Installation
7
+ `@wireweave/core` turns Wireweave's text-based DSL into an AST and back into visual output. It provides:
8
+
9
+ - **Parser** — a Peggy-generated parser that converts `.wf` / `.wireframe` source into a typed AST, with strict and error-recovering modes.
10
+ - **Renderers** — render the AST to HTML+CSS, a standalone HTML document, or SVG. Multi-page documents are auto-composed onto a bounded canvas; single-page documents render in legacy single-board mode.
11
+ - **Multi-page canvas** — `.wf` supports multiple pages positioned on a canvas (`page "..." at(x, y)`) with per-page `viewport` / `device` presets.
12
+ - **AST utilities** — type guards and traversal helpers (`walkDocument`, `find`, `findByType`, …).
13
+ - **Validation** — check AST nodes against the DSL specification.
14
+ - **Diff** — structurally compare two documents.
15
+ - **Export** — convert the AST to JSON or a Figma-compatible structure.
16
+ - **Analyze** — compute statistics plus accessibility, complexity, layout, and content metrics.
17
+
18
+ ## Install
10
19
 
11
20
  ```bash
12
- npm install @wireweave/core
13
- # or
14
- pnpm add @wireweave/core
15
- # or
16
- yarn add @wireweave/core
21
+ npm i @wireweave/core
17
22
  ```
18
23
 
19
- ## Quick Start
24
+ ## Usage
20
25
 
21
26
  ```typescript
22
- import { parse, render, renderToSvg, renderToHtml } from '@wireweave/core';
27
+ import { parse, render, renderToHtml, renderToSvg } from '@wireweave/core'
23
28
 
24
29
  const source = `
25
- page "Hello" {
30
+ page "Home" {
26
31
  card p=4 {
27
32
  title "Welcome"
28
- text "Hello, wireweave!"
33
+ text "Hello, Wireweave!"
29
34
  button "Get Started" primary
30
35
  }
31
36
  }
32
- `;
33
-
34
- // Parse DSL to AST
35
- const doc = parse(source);
36
-
37
- // Render to HTML + CSS
38
- const { html, css } = render(doc);
39
-
40
- // Render to complete HTML document
41
- const fullHtml = renderToHtml(doc);
42
-
43
- // Render to SVG
44
- const { svg, width, height } = renderToSvg(doc);
45
- ```
46
-
47
- ## API Reference
48
-
49
- ### Parser
50
-
51
- #### `parse(source: string): WireframeDocument`
52
-
53
- Parses wireframe DSL source code into an AST (Abstract Syntax Tree).
54
-
55
- ```typescript
56
- import { parse } from '@wireweave/core';
57
-
58
- const doc = parse('page { text "Hello" }');
59
- console.log(doc.children[0].type); // 'Page'
60
- ```
61
-
62
- **Throws**: `ParseError` if the source contains syntax errors.
63
-
64
- ### HTML Renderer
65
-
66
- #### `render(doc: WireframeDocument, options?: RenderOptions): RenderResult`
67
-
68
- Renders the AST to HTML and CSS.
69
-
70
- ```typescript
71
- import { parse, render } from '@wireweave/core';
72
-
73
- const doc = parse('page { card { text "Hello" } }');
74
- const { html, css } = render(doc);
75
- ```
76
-
77
- **Options**:
78
- | Option | Type | Default | Description |
79
- |--------|------|---------|-------------|
80
- | `theme` | `'light' \| 'dark'` | `'light'` | Color theme |
81
-
82
- **Returns**: `{ html: string, css: string }`
83
-
84
- #### `renderToHtml(doc: WireframeDocument, options?: RenderOptions): string`
85
-
86
- Renders the AST to a complete HTML document with embedded CSS.
87
-
88
- ```typescript
89
- import { parse, renderToHtml } from '@wireweave/core';
90
-
91
- const doc = parse('page "Test" { text "Hello" }');
92
- const html = renderToHtml(doc, { theme: 'dark' });
93
- // Returns: <!DOCTYPE html><html>...</html>
94
- ```
95
-
96
- ### SVG Renderer
97
-
98
- #### `renderToSvg(doc: WireframeDocument, options?: SvgRenderOptions): SvgRenderResult`
99
-
100
- Renders the AST to SVG format.
101
-
102
- ```typescript
103
- import { parse, renderToSvg } from '@wireweave/core';
104
-
105
- const doc = parse('page { button "Click" primary }');
106
- const { svg, width, height } = renderToSvg(doc, {
107
- width: 800,
108
- padding: 20
109
- });
110
- ```
111
-
112
- **Options**:
113
- | Option | Type | Default | Description |
114
- |--------|------|---------|-------------|
115
- | `width` | `number` | `1200` | SVG width in pixels |
116
- | `padding` | `number` | `24` | Padding around content |
117
- | `theme` | `'light' \| 'dark'` | `'light'` | Color theme |
118
-
119
- **Returns**: `{ svg: string, width: number, height: number }`
120
-
121
- ### Analysis
122
-
123
- #### `analyze(doc: WireframeDocument, options?: AnalysisOptions): AnalysisResult`
124
-
125
- Analyzes a wireframe document and returns comprehensive statistics.
126
-
127
- ```typescript
128
- import { parse, analyze } from '@wireweave/core';
129
-
130
- const doc = parse('page { card { text "Hello" button "Click" } }');
131
- const result = analyze(doc);
132
-
133
- console.log(result.summary);
134
- // { totalComponents: 4, uniqueTypes: 4, mostUsedType: 'Page', ... }
135
-
136
- console.log(result.tree);
137
- // { totalNodes: 4, maxDepth: 3, avgDepth: 2, ... }
138
-
139
- console.log(result.accessibility);
140
- // { score: 100, imagesWithAlt: 0, inputsWithLabels: 0, ... }
141
-
142
- console.log(result.complexity);
143
- // { score: 2, level: 'simple', interactiveElements: 1, ... }
144
- ```
145
-
146
- **Options**:
147
- | Option | Type | Default | Description |
148
- |--------|------|---------|-------------|
149
- | `includeComponentBreakdown` | `boolean` | `true` | Include component statistics |
150
- | `includeAccessibility` | `boolean` | `true` | Include accessibility metrics |
151
- | `includeComplexity` | `boolean` | `true` | Include complexity analysis |
152
- | `includeLayout` | `boolean` | `true` | Include layout analysis |
153
- | `includeContent` | `boolean` | `true` | Include content analysis |
154
-
155
- ### Diff (Document Comparison)
156
-
157
- #### `diff(oldDoc: WireframeDocument, newDoc: WireframeDocument, options?: DiffOptions): DiffResult`
158
-
159
- Compares two wireframe documents and returns detailed differences.
160
-
161
- ```typescript
162
- import { parse, diff } from '@wireweave/core';
163
-
164
- const oldDoc = parse('page { text "Hello" }');
165
- const newDoc = parse('page { text "Hello" button "Click" }');
166
-
167
- const result = diff(oldDoc, newDoc);
168
-
169
- console.log(result.identical); // false
170
- console.log(result.description); // "Added 1 component(s): Button."
171
- console.log(result.summary);
172
- // { addedCount: 1, removedCount: 0, changedCount: 0, ... }
173
- ```
174
-
175
- #### `areIdentical(oldDoc: WireframeDocument, newDoc: WireframeDocument): boolean`
176
-
177
- Quick check if two documents are identical.
178
-
179
- ```typescript
180
- import { parse, areIdentical } from '@wireweave/core';
181
-
182
- const doc1 = parse('page { text "Hello" }');
183
- const doc2 = parse('page { text "Hello" }');
184
-
185
- console.log(areIdentical(doc1, doc2)); // true
186
- ```
187
-
188
- #### `getChangeSummary(oldDoc: WireframeDocument, newDoc: WireframeDocument): string`
189
-
190
- Returns a human-readable summary of changes.
191
-
192
- ```typescript
193
- import { parse, getChangeSummary } from '@wireweave/core';
194
-
195
- const oldDoc = parse('page { text "A" }');
196
- const newDoc = parse('page { text "B" }');
37
+ `
197
38
 
198
- console.log(getChangeSummary(oldDoc, newDoc));
199
- // "Modified 1 component(s)."
200
- ```
201
-
202
- ### Export
203
-
204
- #### `exportToJson(doc: WireframeDocument, options?: ExportOptions): JsonExportResult`
39
+ // Parse DSL into an AST
40
+ const doc = parse(source)
205
41
 
206
- Exports wireframe to JSON format.
207
-
208
- ```typescript
209
- import { parse, exportToJson } from '@wireweave/core';
42
+ // Render to HTML fragment + CSS
43
+ const { html, css } = render(doc)
210
44
 
211
- const doc = parse('page { card { text "Hello" } }');
212
- const result = exportToJson(doc);
45
+ // Render to a standalone HTML document
46
+ const fullHtml = renderToHtml(doc)
213
47
 
214
- console.log(result.version); // "1.0.0"
215
- console.log(result.pages); // [{ type: 'page', children: [...] }]
216
- console.log(result.metadata);
217
- // { exportedAt: '...', nodeCount: 3, componentTypes: ['card', 'page', 'text'] }
48
+ // Render to SVG (multi-page docs auto-compose onto a canvas)
49
+ const { svg, width, height } = renderToSvg(doc)
218
50
  ```
219
51
 
220
- #### `exportToJsonString(doc: WireframeDocument, options?: ExportOptions): string`
221
-
222
- Exports wireframe to JSON string.
52
+ ### Multi-page canvas
223
53
 
224
54
  ```typescript
225
- import { parse, exportToJsonString } from '@wireweave/core';
226
-
227
- const doc = parse('page { text "Hello" }');
228
- const json = exportToJsonString(doc, { prettyPrint: true });
229
- ```
230
-
231
- #### `exportToFigma(doc: WireframeDocument): FigmaExportResult`
232
-
233
- Exports wireframe to Figma-compatible format.
234
-
235
- ```typescript
236
- import { parse, exportToFigma } from '@wireweave/core';
237
-
238
- const doc = parse('page { card { text "Hello" } }');
239
- const result = exportToFigma(doc);
240
-
241
- console.log(result.document); // Figma-compatible node tree
242
- console.log(result.componentMappings);
243
- // { page: 'CANVAS', card: 'FRAME', text: 'TEXT' }
244
- ```
245
-
246
- ### AST Utilities
247
-
248
- #### `walk(node: ASTNode, callback: WalkCallback): void`
249
-
250
- Traverses the AST tree depth-first.
251
-
252
- ```typescript
253
- import { parse } from '@wireweave/core';
254
- import { walk } from '@wireweave/core/ast';
55
+ const doc = parse(`
56
+ page "Login" at(0, 0) viewport=mobile {
57
+ button "Sign in" primary
58
+ }
59
+ page "Home" at(420, 0) viewport=mobile {
60
+ text "Welcome back"
61
+ }
62
+ `)
255
63
 
256
- const doc = parse('page { card { text "A" text "B" } }');
257
- walk(doc.children[0], (node, parent, depth) => {
258
- console.log(`${node.type} at depth ${depth}`);
259
- });
64
+ const { svg } = renderToSvg(doc) // viewBox sized to the canvas bounding box
260
65
  ```
261
66
 
262
- #### `find(node: ASTNode, predicate: (n: ASTNode) => boolean): ASTNode | undefined`
263
-
264
- Finds the first node matching the predicate.
67
+ ### Analyze, diff, and export
265
68
 
266
69
  ```typescript
267
- import { find } from '@wireweave/core/ast';
70
+ import { parse, analyze, diff, exportToJson, exportToFigma } from '@wireweave/core'
268
71
 
269
- const button = find(doc.children[0], n => n.type === 'Button');
270
- ```
271
-
272
- #### `findAll(node: ASTNode, predicate: (n: ASTNode) => boolean): ASTNode[]`
273
-
274
- Finds all nodes matching the predicate.
275
-
276
- ```typescript
277
- import { findAll } from '@wireweave/core/ast';
72
+ const a = parse(sourceA)
73
+ const b = parse(sourceB)
278
74
 
279
- const buttons = findAll(doc.children[0], n => n.type === 'Button');
75
+ const stats = analyze(a) // totals, accessibility score, complexity, layout, content
76
+ const changes = diff(a, b) // added / removed / changed / moved nodes
77
+ const json = exportToJson(a) // serializable AST
78
+ const figma = exportToFigma(a) // Figma-compatible node tree
280
79
  ```
281
80
 
282
- #### `findByType<T>(node: ASTNode, type: string): T[]`
283
-
284
- Finds all nodes of a specific type.
81
+ ### Print back to canonical DSL
285
82
 
286
83
  ```typescript
287
- import { findByType } from '@wireweave/core/ast';
288
- import type { ButtonNode } from '@wireweave/core';
84
+ import { parse, printWireframe, formatWireframeCode } from '@wireweave/core'
289
85
 
290
- const buttons = findByType<ButtonNode>(doc.children[0], 'Button');
86
+ const doc = parse(source)
87
+ const canonical = printWireframe(doc) // deterministic canonical `.wf` text
88
+ const formatted = formatWireframeCode(source) // parse + reprint in one step
291
89
  ```
292
90
 
293
- #### `countNodes(node: ASTNode): number`
294
-
295
- Counts all nodes in the tree.
296
-
297
- #### `getMaxDepth(node: ASTNode): number`
298
-
299
- Returns the maximum nesting depth.
300
-
301
- #### `cloneNode<T>(node: T): T`
91
+ The printer emits a single canonical form (fixed indentation, attribute
92
+ ordering, quoting, blank-line policy) with round-trip guarantees:
93
+ `parse(printWireframe(doc))` is structurally equivalent to `doc`, printing is
94
+ idempotent, and already-canonical text reprints byte-identical. Comments are
95
+ not preserved (the parser drops them before the AST).
302
96
 
303
- Creates a deep copy of a node.
304
-
305
- ## Type Definitions
306
-
307
- ### WireframeDocument
97
+ ### Walk the AST
308
98
 
309
99
  ```typescript
310
- interface WireframeDocument {
311
- type: 'Document';
312
- children: PageNode[];
313
- }
314
- ```
100
+ import { parse, walkDocument, findByType, isButtonNode } from '@wireweave/core'
315
101
 
316
- ### PageNode
102
+ const doc = parse(source)
317
103
 
318
- ```typescript
319
- interface PageNode {
320
- type: 'Page';
321
- title?: string;
322
- children: ASTNode[];
323
- // ... spacing attributes
324
- }
325
- ```
326
-
327
- ### Common Node Properties
328
-
329
- All nodes include:
330
- - `type: string` - Node type (e.g., 'Button', 'Card')
331
- - `location?: Location` - Source location info
332
- - Spacing: `p`, `px`, `py`, `pt`, `pr`, `pb`, `pl`, `m`, `mx`, `my`, `mt`, `mr`, `mb`, `ml`
333
- - Size: `w`, `h`
334
-
335
- ### Component-Specific Properties
336
-
337
- ```typescript
338
- // Button
339
- interface ButtonNode {
340
- type: 'Button';
341
- content: string;
342
- primary?: boolean;
343
- secondary?: boolean;
344
- outline?: boolean;
345
- ghost?: boolean;
346
- danger?: boolean;
347
- disabled?: boolean;
348
- }
349
-
350
- // Input
351
- interface InputNode {
352
- type: 'Input';
353
- label?: string;
354
- placeholder?: string;
355
- inputType?: 'text' | 'email' | 'password' | 'search' | 'tel' | 'url' | 'number';
356
- required?: boolean;
357
- disabled?: boolean;
358
- }
359
-
360
- // Card
361
- interface CardNode {
362
- type: 'Card';
363
- title?: string;
364
- children: ASTNode[];
365
- }
366
-
367
- // Col
368
- interface ColNode {
369
- type: 'Col';
370
- span?: number;
371
- sm?: number;
372
- md?: number;
373
- lg?: number;
374
- xl?: number;
375
- children: ASTNode[];
376
- }
377
- ```
378
-
379
- ## DSL Syntax Reference
380
-
381
- ### Page Structure
382
-
383
- ```
384
- page "Title" {
385
- header { }
386
- main { }
387
- footer { }
388
- sidebar { }
389
- aside { }
390
- }
391
- ```
392
-
393
- ### Layout
394
-
395
- ```
396
- // Grid columns (12-column system)
397
- row {
398
- col span=6 { } // 50% width
399
- col span=6 { } // 50% width
400
- }
401
-
402
- // Responsive breakpoints
403
- col span=12 sm=6 md=4 lg=3 xl=2 { }
404
-
405
- // Flexbox
406
- row flex justify=center align=center gap=4 wrap { }
407
- // justify: start, end, center, between, around, evenly
408
- // align: start, end, center, stretch, baseline
409
- // direction: row, row-reverse, column, column-reverse
410
- ```
411
-
412
- ### Spacing Scale
413
-
414
- Values use a 4px base: `1 = 4px`, `2 = 8px`, `4 = 16px`, etc.
415
-
416
- ```
417
- card p=4 m=2 { } // padding: 16px, margin: 8px
418
- button mt=4 mb=2 // margin-top: 16px, margin-bottom: 8px
419
- ```
420
-
421
- ### Size
422
-
423
- ```
424
- image w=400 h=300 // width: 400px, height: 300px
425
- card w=full // width: 100%
426
- ```
427
-
428
- ### Comments
429
-
430
- ```
431
- // Single line comment
432
-
433
- /* Multi-line
434
- comment */
435
-
436
- page {
437
- // Comment inside block
438
- text "Hello"
439
- }
440
- ```
441
-
442
- ## Error Handling
443
-
444
- ```typescript
445
- import { parse } from '@wireweave/core';
446
-
447
- try {
448
- const doc = parse('page { invalid }');
449
- } catch (error) {
450
- if (error.name === 'ParseError') {
451
- console.log(error.message);
452
- // "Syntax error at line 1, column 8: ..."
453
- console.log(error.location);
454
- // { start: { line: 1, column: 8 }, end: { ... } }
104
+ walkDocument(doc, (node) => {
105
+ if (isButtonNode(node)) {
106
+ console.log(node.content)
455
107
  }
456
- }
108
+ })
109
+
110
+ const buttons = findByType(doc.children[0], 'Button')
457
111
  ```
458
112
 
459
- ## Browser Support
113
+ ## Main API
460
114
 
461
- The core library works in both Node.js and browser environments. For browser usage:
115
+ | Export | Description |
116
+ | --------------------------------------------------------------- | --------------------------------------------------------------------------- |
117
+ | `parse(source, options?)` | Parse DSL into a `WireframeDocument`; throws `ParseError` on syntax errors. |
118
+ | `tryParse` / `isValid` / `getErrors` | Error-recovering parse, boolean check, and error list. |
119
+ | `printWireframe` / `formatWireframeCode` | Canonical `.wf` printer — AST → deterministic DSL text (round-trip safe). |
120
+ | `render(doc, options?)` | Render to `{ html, css }`. Auto canvas mode for multi-page docs. |
121
+ | `renderToHtml(doc, options?)` | Render to a complete standalone HTML document string. |
122
+ | `renderToSvg(doc, options?)` | Render to `{ svg, width, height }` using `foreignObject` (HTML+CSS in SVG). |
123
+ | `renderPage` / `renderCanvas` / `layoutCanvas` | Explicit single-page / multi-page composition primitives. |
124
+ | `validate` / `isValidAst` / `getValidationErrors` | Validate AST nodes against the DSL spec. |
125
+ | `analyze(doc, options?)` | Statistics plus accessibility, complexity, layout, and content metrics. |
126
+ | `diff(oldDoc, newDoc, options?)` | Structural diff; also `areIdentical`, `getChangeSummary`. |
127
+ | `exportToJson` / `importFromJson` / `exportToFigma` | Format conversion to/from JSON and to Figma. |
128
+ | `walkDocument` / `walk` / `find` / `findAll` / `findByType` | AST traversal helpers. |
129
+ | `resolveViewport` / `DEVICE_PRESETS` / `wrapInPreviewContainer` | Viewport sizing, device presets, preview scaling. |
130
+ | AST types + `is*` guards | `WireframeDocument`, `AnyNode`, node types, and type guards. |
462
131
 
463
- ```html
464
- <script type="module">
465
- import { parse, render } from '@wireweave/core';
132
+ Subpath entries are available for `@wireweave/core/parser` and `@wireweave/core/renderer`.
466
133
 
467
- const doc = parse('page { text "Hello" }');
468
- const { html, css } = render(doc);
134
+ The build runs `build:grammar` (Peggy) before the TypeScript build to regenerate the parser from `src/grammar/wireframe.peggy`.
469
135
 
470
- document.body.innerHTML = `<style>${css}</style>${html}`;
471
- </script>
472
- ```
136
+ Part of the [Wireweave monorepo](https://github.com/wireweave/wireweave).
473
137
 
474
138
  ## License
475
139