@wireweave/core 3.0.1-beta.0 → 3.0.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/README.md CHANGED
@@ -1,476 +1,122 @@
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
37
  `
33
38
 
34
- // Parse DSL to AST
39
+ // Parse DSL into an AST
35
40
  const doc = parse(source)
36
41
 
37
- // Render to HTML + CSS
42
+ // Render to HTML fragment + CSS
38
43
  const { html, css } = render(doc)
39
44
 
40
- // Render to complete HTML document
45
+ // Render to a standalone HTML document
41
46
  const fullHtml = renderToHtml(doc)
42
47
 
43
- // Render to SVG
48
+ // Render to SVG (multi-page docs auto-compose onto a canvas)
44
49
  const { svg, width, height } = renderToSvg(doc)
45
50
  ```
46
51
 
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.
52
+ ### Multi-page canvas
178
53
 
179
54
  ```typescript
180
- import { parse, areIdentical } from '@wireweave/core'
181
-
182
- const doc1 = parse('page { text "Hello" }')
183
- const doc2 = parse('page { text "Hello" }')
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
+ `)
184
63
 
185
- console.log(areIdentical(doc1, doc2)) // true
64
+ const { svg } = renderToSvg(doc) // viewBox sized to the canvas bounding box
186
65
  ```
187
66
 
188
- #### `getChangeSummary(oldDoc: WireframeDocument, newDoc: WireframeDocument): string`
189
-
190
- Returns a human-readable summary of changes.
67
+ ### Analyze, diff, and export
191
68
 
192
69
  ```typescript
193
- import { parse, getChangeSummary } from '@wireweave/core'
70
+ import { parse, analyze, diff, exportToJson, exportToFigma } from '@wireweave/core'
194
71
 
195
- const oldDoc = parse('page { text "A" }')
196
- const newDoc = parse('page { text "B" }')
72
+ const a = parse(sourceA)
73
+ const b = parse(sourceB)
197
74
 
198
- console.log(getChangeSummary(oldDoc, newDoc))
199
- // "Modified 1 component(s)."
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
200
79
  ```
201
80
 
202
- ### Export
203
-
204
- #### `exportToJson(doc: WireframeDocument, options?: ExportOptions): JsonExportResult`
205
-
206
- Exports wireframe to JSON format.
207
-
208
- ```typescript
209
- import { parse, exportToJson } from '@wireweave/core'
210
-
211
- const doc = parse('page { card { text "Hello" } }')
212
- const result = exportToJson(doc)
213
-
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'] }
218
- ```
219
-
220
- #### `exportToJsonString(doc: WireframeDocument, options?: ExportOptions): string`
221
-
222
- Exports wireframe to JSON string.
223
-
224
- ```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.
81
+ ### Walk the AST
234
82
 
235
83
  ```typescript
236
- import { parse, exportToFigma } from '@wireweave/core'
84
+ import { parse, walkDocument, findByType, isButtonNode } from '@wireweave/core'
237
85
 
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'
86
+ const doc = parse(source)
255
87
 
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}`)
88
+ walkDocument(doc, (node) => {
89
+ if (isButtonNode(node)) {
90
+ console.log(node.content)
91
+ }
259
92
  })
260
- ```
261
-
262
- #### `find(node: ASTNode, predicate: (n: ASTNode) => boolean): ASTNode | undefined`
263
-
264
- Finds the first node matching the predicate.
265
-
266
- ```typescript
267
- import { find } from '@wireweave/core/ast'
268
-
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'
278
-
279
- const buttons = findAll(doc.children[0], (n) => n.type === 'Button')
280
- ```
281
-
282
- #### `findByType<T>(node: ASTNode, type: string): T[]`
283
-
284
- Finds all nodes of a specific type.
285
-
286
- ```typescript
287
- import { findByType } from '@wireweave/core/ast'
288
- import type { ButtonNode } from '@wireweave/core'
289
-
290
- const buttons = findByType<ButtonNode>(doc.children[0], 'Button')
291
- ```
292
-
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`
302
-
303
- Creates a deep copy of a node.
304
-
305
- ## Type Definitions
306
-
307
- ### WireframeDocument
308
-
309
- ```typescript
310
- interface WireframeDocument {
311
- type: 'Document'
312
- children: PageNode[]
313
- }
314
- ```
315
93
 
316
- ### PageNode
317
-
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
-
331
- - `type: string` - Node type (e.g., 'Button', 'Card')
332
- - `location?: Location` - Source location info
333
- - Spacing: `p`, `px`, `py`, `pt`, `pr`, `pb`, `pl`, `m`, `mx`, `my`, `mt`, `mr`, `mb`, `ml`
334
- - Size: `w`, `h`
335
-
336
- ### Component-Specific Properties
337
-
338
- ```typescript
339
- // Button
340
- interface ButtonNode {
341
- type: 'Button'
342
- content: string
343
- primary?: boolean
344
- secondary?: boolean
345
- outline?: boolean
346
- ghost?: boolean
347
- danger?: boolean
348
- disabled?: boolean
349
- }
350
-
351
- // Input
352
- interface InputNode {
353
- type: 'Input'
354
- label?: string
355
- placeholder?: string
356
- inputType?: 'text' | 'email' | 'password' | 'search' | 'tel' | 'url' | 'number'
357
- required?: boolean
358
- disabled?: boolean
359
- }
360
-
361
- // Card
362
- interface CardNode {
363
- type: 'Card'
364
- title?: string
365
- children: ASTNode[]
366
- }
367
-
368
- // Col
369
- interface ColNode {
370
- type: 'Col'
371
- span?: number
372
- sm?: number
373
- md?: number
374
- lg?: number
375
- xl?: number
376
- children: ASTNode[]
377
- }
378
- ```
379
-
380
- ## DSL Syntax Reference
381
-
382
- ### Page Structure
383
-
384
- ```
385
- page "Title" {
386
- header { }
387
- main { }
388
- footer { }
389
- sidebar { }
390
- aside { }
391
- }
392
- ```
393
-
394
- ### Layout
395
-
396
- ```
397
- // Grid columns (12-column system)
398
- row {
399
- col span=6 { } // 50% width
400
- col span=6 { } // 50% width
401
- }
402
-
403
- // Responsive breakpoints
404
- col span=12 sm=6 md=4 lg=3 xl=2 { }
405
-
406
- // Flexbox
407
- row flex justify=center align=center gap=4 wrap { }
408
- // justify: start, end, center, between, around, evenly
409
- // align: start, end, center, stretch, baseline
410
- // direction: row, row-reverse, column, column-reverse
94
+ const buttons = findByType(doc.children[0], 'Button')
411
95
  ```
412
96
 
413
- ### Spacing Scale
97
+ ## Main API
414
98
 
415
- Values use a 4px base: `1 = 4px`, `2 = 8px`, `4 = 16px`, etc.
99
+ | Export | Description |
100
+ | --------------------------------------------------------------- | --------------------------------------------------------------------------- |
101
+ | `parse(source, options?)` | Parse DSL into a `WireframeDocument`; throws `ParseError` on syntax errors. |
102
+ | `tryParse` / `isValid` / `getErrors` | Error-recovering parse, boolean check, and error list. |
103
+ | `render(doc, options?)` | Render to `{ html, css }`. Auto canvas mode for multi-page docs. |
104
+ | `renderToHtml(doc, options?)` | Render to a complete standalone HTML document string. |
105
+ | `renderToSvg(doc, options?)` | Render to `{ svg, width, height }` using `foreignObject` (HTML+CSS in SVG). |
106
+ | `renderPage` / `renderCanvas` / `layoutCanvas` | Explicit single-page / multi-page composition primitives. |
107
+ | `validate` / `isValidAst` / `getValidationErrors` | Validate AST nodes against the DSL spec. |
108
+ | `analyze(doc, options?)` | Statistics plus accessibility, complexity, layout, and content metrics. |
109
+ | `diff(oldDoc, newDoc, options?)` | Structural diff; also `areIdentical`, `getChangeSummary`. |
110
+ | `exportToJson` / `importFromJson` / `exportToFigma` | Format conversion to/from JSON and to Figma. |
111
+ | `walkDocument` / `walk` / `find` / `findAll` / `findByType` | AST traversal helpers. |
112
+ | `resolveViewport` / `DEVICE_PRESETS` / `wrapInPreviewContainer` | Viewport sizing, device presets, preview scaling. |
113
+ | AST types + `is*` guards | `WireframeDocument`, `AnyNode`, node types, and type guards. |
416
114
 
417
- ```
418
- card p=4 m=2 { } // padding: 16px, margin: 8px
419
- button mt=4 mb=2 // margin-top: 16px, margin-bottom: 8px
420
- ```
115
+ Subpath entries are available for `@wireweave/core/parser` and `@wireweave/core/renderer`.
421
116
 
422
- ### Size
117
+ The build runs `build:grammar` (Peggy) before the TypeScript build to regenerate the parser from `src/grammar/wireframe.peggy`.
423
118
 
424
- ```
425
- image w=400 h=300 // width: 400px, height: 300px
426
- card w=full // width: 100%
427
- ```
428
-
429
- ### Comments
430
-
431
- ```
432
- // Single line comment
433
-
434
- /* Multi-line
435
- comment */
436
-
437
- page {
438
- // Comment inside block
439
- text "Hello"
440
- }
441
- ```
442
-
443
- ## Error Handling
444
-
445
- ```typescript
446
- import { parse } from '@wireweave/core'
447
-
448
- try {
449
- const doc = parse('page { invalid }')
450
- } catch (error) {
451
- if (error.name === 'ParseError') {
452
- console.log(error.message)
453
- // "Syntax error at line 1, column 8: ..."
454
- console.log(error.location)
455
- // { start: { line: 1, column: 8 }, end: { ... } }
456
- }
457
- }
458
- ```
459
-
460
- ## Browser Support
461
-
462
- The core library works in both Node.js and browser environments. For browser usage:
463
-
464
- ```html
465
- <script type="module">
466
- import { parse, render } from '@wireweave/core'
467
-
468
- const doc = parse('page { text "Hello" }')
469
- const { html, css } = render(doc)
470
-
471
- document.body.innerHTML = `<style>${css}</style>${html}`
472
- </script>
473
- ```
119
+ Part of the [Wireweave monorepo](https://github.com/wireweave/wireweave).
474
120
 
475
121
  ## License
476
122