@wireweave/core 3.1.0-beta.1 → 3.1.0-beta.11
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/dist/index.cjs +13741 -7711
- package/dist/index.d.cts +733 -116
- package/dist/index.d.ts +733 -116
- package/dist/index.js +13691 -7710
- package/dist/parser.cjs +2290 -974
- package/dist/parser.d.cts +1 -1
- package/dist/parser.d.ts +1 -1
- package/dist/parser.js +2290 -974
- package/dist/renderer.cjs +7064 -4394
- package/dist/renderer.d.cts +439 -9
- package/dist/renderer.d.ts +439 -9
- package/dist/renderer.js +7053 -4394
- package/dist/spec.cjs +2885 -0
- package/dist/spec.d.cts +372 -0
- package/dist/spec.d.ts +372 -0
- package/dist/spec.js +2837 -0
- package/dist/{types-BDbXDhTp.d.cts → types-vhPCZpAW.d.cts} +294 -27
- package/dist/{types-BDbXDhTp.d.ts → types-vhPCZpAW.d.ts} +294 -27
- package/package.json +56 -13
package/dist/index.d.ts
CHANGED
|
@@ -1,7 +1,10 @@
|
|
|
1
|
-
import { h as AnyNode, A as AccordionNode, a as AlertNode, j as AvatarNode, B as BadgeNode, r as BreadcrumbNode, s as ButtonNode, C as CardNode, w as CheckboxNode, x as ColNode, z as ContainerComponentNode,
|
|
2
|
-
export { b as AlertVariant, c as AlignValue, d as AnchorPosition, e as AnnotationItemNode, f as AnnotationNode, g as AnnotationsNode, i as AppearanceProps, k as AvatarSize, l as AvatarSizeToken, m as BadgeSize, n as BadgeSizeToken, o as BadgeVariant, p as BaseNode, q as BreadcrumbItem, t as ButtonSize, u as ButtonSizeToken, v as ButtonVariant, y as CommonProps, F as
|
|
1
|
+
import { h as AnyNode, A as AccordionNode, a as AlertNode, j as AvatarNode, B as BadgeNode, r as BreadcrumbNode, s as ButtonNode, C as CardNode, w as CheckboxNode, x as ColNode, z as ComponentDefinitionNode, H as ComponentUseNode, I as ContainerComponentNode, J as ContainerNode, K as DataNode, L as DefinitionNode, N as DisplayNode, O as DividerComponentNode, P as DrawerNode, S as DropdownNode, T as FeedbackNode, V as FooterNode, W as GridNode, Z as HeaderNode, $ as IconNode, a2 as ImageNode, a3 as InputComponentNode, a4 as InputNode, aa as LayoutDefinitionNode, ab as LayoutNode, ac as LeafNode, ad as LinkNode, af as ListNode, ag as MainNode, aj as ModalNode, ao as NavNode, ap as NavigationNode, aq as NodeType, ar as OverlayNode, as as PageNode, at as PlaceholderNode, au as PopoverNode, ax as ProgressNode, ay as RadioNode, aB as RowNode, aC as SectionNode, aD as SelectNode, aG as SidebarNode, aI as SliderNode, aJ as SlotNode, aN as SpinnerNode, aV as SwitchNode, aX as TableNode, aY as TabsNode, a_ as TextContentNode, a$ as TextNode, b3 as TextareaNode, b5 as TitleNode, b6 as ToastNode, b8 as TooltipNode, be as WireframeDocument, aK as SourceLocation, aR as StateDeclaration, aS as StateGuard, a6 as InteractionEffect, a5 as InputType } from './types-vhPCZpAW.js';
|
|
2
|
+
export { b as AlertVariant, c as AlignValue, d as AnchorPosition, e as AnnotationItemNode, f as AnnotationNode, g as AnnotationsNode, i as AppearanceProps, k as AvatarSize, l as AvatarSizeToken, m as BadgeSize, n as BadgeSizeToken, o as BadgeVariant, p as BaseNode, q as BreadcrumbItem, t as ButtonSize, u as ButtonSizeToken, v as ButtonVariant, y as CommonProps, D as ComponentInputValue, E as ComponentParameter, F as ComponentParameterType, G as ComponentSlotFill, M as DirectionValue, Q as DrawerPosition, R as DropdownItemNode, U as FlexProps, X as GridProps, Y as GuardedOutcomeProps, _ as HeightValue, a0 as IconSize, a1 as IconSizeToken, a7 as InteractionHandler, a8 as InteractiveProps, a9 as JustifyValue, ae as ListItemNode, ah as MarkerColor, ai as MarkerNode, ak as NavBlockItem, al as NavChild, am as NavGroupNode, an as NavItem, av as Position, aw as PositionProps, az as RelativeNode, aA as RepeatNode, aE as SelectOption, aF as ShadowValue, aH as SizeProps, aL as SpacingProps, aM as SpacingValue, aO as SpinnerSize, aP as SpinnerSizeToken, aQ as StackNode, aT as StateValue, aU as StateValueType, aW as TabNode, aZ as TextAlign, b0 as TextSize, b1 as TextSizeToken, b2 as TextWeight, b4 as TitleLevel, b7 as ToastPosition, b9 as TooltipPosition, ba as TopLevelNode, bb as ValueWithUnit, bc as VariantScopedProps, bd as WidthValue } from './types-vhPCZpAW.js';
|
|
3
3
|
export { ExpectedToken, ParseError, ParseErrorInfo, ParseOptions, ParseResult, getErrors, isValid, parse, tryParse } from './parser.js';
|
|
4
|
-
|
|
4
|
+
import { SiteOptions } from './renderer.js';
|
|
5
|
+
export { AnnotationStyle, CanvasOptions, CanvasRenderResult, ENABLED_GUARD_ATTR, EXTERNAL_NAVIGATE_ATTR, HtmlRenderer, INERT_HREF, INTERACTIVE_ATTR_NAMES, IconData, IconElement, InteractiveAttrs, PageRenderResult, PlacedPage, RenderContext, RenderOptions, RenderResult, ShellMiss, SiteModel, SiteScreen, SiteShell, SvgRenderOptions, SvgRenderResult, TYPED_INTERACTION_ATTR, ThemeColors, ThemeConfig, VISIBLE_GUARD_ATTR, anchorIntent, buildSiteModel, createHtmlRenderer, darkTheme, defaultTheme, generateComponentStyles, generateStyles, getIconData, getTheme, guardedOutcomeAttrs, interactiveAttrs, layoutCanvas, lucideIcons, render, renderCanvas, renderIconSvg, renderPage, renderSite, renderToHtml, renderToSvg, renderUnknownIconSvg, resolvePageDimensions } from './renderer.js';
|
|
6
|
+
import { ComponentCategory } from './spec.js';
|
|
7
|
+
export { ATTRIBUTE_MAP, ATTRIBUTE_OVERRIDES, ATTRIBUTE_SPECS, AttributeOverride, AttributeSpec, AttributeValueType, BLOCK_NODE_SPECS, BOX_ATTRIBUTES, COMPONENT_MAP, COMPONENT_NAMES, COMPONENT_SPECS, COMPONENT_SPEC_BY_NAME, CONTAINER_ATTRIBUTES, ComponentSpec, ELEMENT_NODE_TYPE_MAP, GRAMMAR_BLOCK_NODE_TYPES, GRAMMAR_CHILD_KEYWORDS, GRAMMAR_ELEMENTS, GrammarBlockNodeType, GrammarElementName, GrammarNodeType, INTERACTIVE_ATTRIBUTES, LUCIDE_ICON_NAMES, NODE_TYPE_MAP, VALID_ATTRIBUTE_NAMES, VALID_COMPONENT_NAMES, attributeFor, getValidAttributes, isValidAttribute } from './spec.js';
|
|
5
8
|
|
|
6
9
|
/**
|
|
7
10
|
* Type guards for wireweave AST
|
|
@@ -16,6 +19,12 @@ declare function hasChildren(node: AnyNode): node is AnyNode & {
|
|
|
16
19
|
declare function isLeafNode(node: AnyNode): node is LeafNode;
|
|
17
20
|
declare function isLayoutNode(node: AnyNode): node is LayoutNode;
|
|
18
21
|
declare function isPageNode(node: AnyNode): node is PageNode;
|
|
22
|
+
/** A `layout` or `component` definition — a named tree, not a screen. */
|
|
23
|
+
declare function isDefinitionNode(node: AnyNode): node is DefinitionNode;
|
|
24
|
+
declare function isLayoutDefinitionNode(node: AnyNode): node is LayoutDefinitionNode;
|
|
25
|
+
declare function isComponentDefinitionNode(node: AnyNode): node is ComponentDefinitionNode;
|
|
26
|
+
declare function isComponentUseNode(node: AnyNode): node is ComponentUseNode;
|
|
27
|
+
declare function isSlotNode(node: AnyNode): node is SlotNode;
|
|
19
28
|
declare function isHeaderNode(node: AnyNode): node is HeaderNode;
|
|
20
29
|
declare function isMainNode(node: AnyNode): node is MainNode;
|
|
21
30
|
declare function isFooterNode(node: AnyNode): node is FooterNode;
|
|
@@ -95,10 +104,33 @@ declare function walk(node: AnyNode, callback: WalkCallback, parent?: AnyNode, d
|
|
|
95
104
|
/**
|
|
96
105
|
* Walk through a document's AST
|
|
97
106
|
*
|
|
107
|
+
* Covers every top-level child — pages *and* reuse definitions — because a walk
|
|
108
|
+
* is about visiting nodes, not about selecting screens.
|
|
109
|
+
*
|
|
98
110
|
* @param document - The wireframe document
|
|
99
111
|
* @param callback - Function called for each node
|
|
100
112
|
*/
|
|
101
113
|
declare function walkDocument(document: WireframeDocument, callback: WalkCallback): void;
|
|
114
|
+
/**
|
|
115
|
+
* The document's pages, in source order.
|
|
116
|
+
*
|
|
117
|
+
* A document's children are not all screens: `layout` and `component`
|
|
118
|
+
* definitions sit alongside `page` as top-level siblings. Anything that counts,
|
|
119
|
+
* indexes, renders or exports *screens* must select them through this helper
|
|
120
|
+
* rather than reading `document.children` directly — otherwise a definition
|
|
121
|
+
* silently becomes screen #0.
|
|
122
|
+
*
|
|
123
|
+
* @param document - The wireframe document
|
|
124
|
+
* @returns Only the `Page` children
|
|
125
|
+
*/
|
|
126
|
+
declare function documentPages(document: WireframeDocument): PageNode[];
|
|
127
|
+
/**
|
|
128
|
+
* The document's reuse definitions (`layout` / `component`), in source order.
|
|
129
|
+
*
|
|
130
|
+
* @param document - The wireframe document
|
|
131
|
+
* @returns Only the definition children
|
|
132
|
+
*/
|
|
133
|
+
declare function documentDefinitions(document: WireframeDocument): DefinitionNode[];
|
|
102
134
|
/**
|
|
103
135
|
* Find the first node matching a predicate
|
|
104
136
|
*
|
|
@@ -176,6 +208,292 @@ declare function contains(node: AnyNode, target: AnyNode): boolean;
|
|
|
176
208
|
*/
|
|
177
209
|
declare function getNodeTypes(node: AnyNode): Set<NodeType>;
|
|
178
210
|
|
|
211
|
+
/**
|
|
212
|
+
* Component parameter references (`"$name"`) — one traversal, one pattern.
|
|
213
|
+
*
|
|
214
|
+
* A component body may reference a declared parameter anywhere a string value
|
|
215
|
+
* sits: a top-level prop (`title "$name"`), a nested object (an interaction
|
|
216
|
+
* effect's `target`), or an element of an array (`effects[]`). Substitution at
|
|
217
|
+
* link time walks all three. Validation must walk exactly the same shape, or a
|
|
218
|
+
* reference that gets substituted is never checked — an undeclared name then
|
|
219
|
+
* survives as the literal string `"$too"` with no diagnostic.
|
|
220
|
+
*
|
|
221
|
+
* Both the linker and the document validator therefore share the traversal and
|
|
222
|
+
* the pattern defined here rather than re-deriving either.
|
|
223
|
+
*/
|
|
224
|
+
|
|
225
|
+
/**
|
|
226
|
+
* The parameter name a string value references, or `undefined` when the value
|
|
227
|
+
* is ordinary text.
|
|
228
|
+
*
|
|
229
|
+
* @param value - Any value; only whole-string references match.
|
|
230
|
+
* @returns The referenced name without its `$`, or `undefined`.
|
|
231
|
+
* @public
|
|
232
|
+
*/
|
|
233
|
+
declare function parameterReferenceName(value: unknown): string | undefined;
|
|
234
|
+
/**
|
|
235
|
+
* One `"$name"` reference found inside a component body.
|
|
236
|
+
*
|
|
237
|
+
* @public
|
|
238
|
+
*/
|
|
239
|
+
interface ComponentParameterReference {
|
|
240
|
+
/** Referenced parameter name, without its `$`. */
|
|
241
|
+
name: string;
|
|
242
|
+
/**
|
|
243
|
+
* Property key the reference was found under. Nested keys report the leaf
|
|
244
|
+
* key (`target`), which is what an author sees in the source text.
|
|
245
|
+
*/
|
|
246
|
+
key: string;
|
|
247
|
+
/** Nearest enclosing AST node, for diagnostic location and node type. */
|
|
248
|
+
node: AnyNode;
|
|
249
|
+
}
|
|
250
|
+
/**
|
|
251
|
+
* Every parameter reference reachable from a component's children.
|
|
252
|
+
*
|
|
253
|
+
* Mirrors link-time substitution exactly: it descends into arrays and plain
|
|
254
|
+
* objects as well as child nodes, and skips `loc` so a source location can
|
|
255
|
+
* never be mistaken for authored content. `ComponentUse` subtrees are skipped —
|
|
256
|
+
* a nested invocation's inputs belong to that component's own scope, and its
|
|
257
|
+
* body is validated where it is defined.
|
|
258
|
+
*
|
|
259
|
+
* @param children - The component definition's children.
|
|
260
|
+
* @returns References in traversal order.
|
|
261
|
+
* @public
|
|
262
|
+
* @example
|
|
263
|
+
* `collectParameterReferences(definition.children).map((item) => item.name)`
|
|
264
|
+
*/
|
|
265
|
+
declare function collectParameterReferences(children: readonly AnyNode[]): ComponentParameterReference[];
|
|
266
|
+
|
|
267
|
+
/**
|
|
268
|
+
* `repeat N { … }` expansion — folding syntax turned into the tree it denotes.
|
|
269
|
+
*
|
|
270
|
+
* ## Why this is a pass over the document, not a case in the renderer
|
|
271
|
+
*
|
|
272
|
+
* `repeat` has to disappear before anything *measures* the tree, not merely
|
|
273
|
+
* before something draws it. The renderer builds its anchor index up front:
|
|
274
|
+
* `HtmlRenderer.render` calls `buildAnchorPathMap(document)` before emitting a
|
|
275
|
+
* byte, and that map is keyed by **node object identity**. A `Repeat` expanded
|
|
276
|
+
* lazily inside `renderNode` would hand back copies the map has never seen, so
|
|
277
|
+
* every copy but the first would render without a `data-wf-path` and the anchor
|
|
278
|
+
* count would stop matching the index — the exact drift `anchor-path.ts` exists
|
|
279
|
+
* to prevent. Expanding the whole document first means the map, the markup, the
|
|
280
|
+
* DOM map and the UX rules all see one identical tree.
|
|
281
|
+
*
|
|
282
|
+
* It is equally deliberate that this is **not** in the parser. The AST keeps the
|
|
283
|
+
* `Repeat` node so the printer can write `repeat 6` back out; expanding at parse
|
|
284
|
+
* time would make `parse(print(parse(src)))` return six bodies where the source
|
|
285
|
+
* had one, breaking the round-trip law the corpus harness pins.
|
|
286
|
+
*
|
|
287
|
+
* ## Identity and source anchors
|
|
288
|
+
*
|
|
289
|
+
* Every copy is a fresh deep clone, never a shared reference — see above for why
|
|
290
|
+
* identity matters. Clones intentionally keep the `loc` of the body they came
|
|
291
|
+
* from: all six copies of `repeat 6 { … }` really do originate at one span of
|
|
292
|
+
* source, so pointing back at it is accurate, and it is the same thing component
|
|
293
|
+
* expansion already does. Uniqueness comes from position instead — anchor paths
|
|
294
|
+
* are child indices (`0.2.1`), so the copies land at distinct sibling indices
|
|
295
|
+
* automatically and no two share a path.
|
|
296
|
+
*/
|
|
297
|
+
|
|
298
|
+
/**
|
|
299
|
+
* Total node budget for one expansion.
|
|
300
|
+
*
|
|
301
|
+
* Nesting multiplies — `repeat 100 { repeat 100 { … } }` is ten thousand bodies
|
|
302
|
+
* — so a per-`repeat` cap on `N` would not bound the result. The budget is
|
|
303
|
+
* therefore on the **expanded total**, which is the quantity that actually costs
|
|
304
|
+
* anything, and it is checked as the tree is built so a runaway document stops
|
|
305
|
+
* early instead of being materialised and then rejected.
|
|
306
|
+
*
|
|
307
|
+
* The number is the page-complexity ceiling `ux-rules` already applies
|
|
308
|
+
* (`MAX_PAGE_ELEMENTS`, 50) times ten. Tying it to that constant rather than
|
|
309
|
+
* inventing a figure keeps one notion of "too big for a wireframe" in the
|
|
310
|
+
* codebase; the multiplier is headroom, so that a document merely worth warning
|
|
311
|
+
* about still renders — `tooManyPageElements` reports at 50 and this refuses at
|
|
312
|
+
* 500, leaving an order of magnitude in which a document is complained about
|
|
313
|
+
* but still drawn, and only past that is it refused outright.
|
|
314
|
+
*/
|
|
315
|
+
declare const REPEAT_EXPANSION_BUDGET = 500;
|
|
316
|
+
/** Thrown when an expansion would exceed {@link REPEAT_EXPANSION_BUDGET}. */
|
|
317
|
+
declare class RepeatBudgetError extends Error {
|
|
318
|
+
constructor(budget: number);
|
|
319
|
+
}
|
|
320
|
+
/**
|
|
321
|
+
* Replace every `repeat N { … }` in a document with `N` copies of its body.
|
|
322
|
+
*
|
|
323
|
+
* Idempotent by construction — the result contains no `Repeat` nodes, so a
|
|
324
|
+
* second application is a no-op. A document with no `repeat` is returned as-is,
|
|
325
|
+
* identity included, so the common case costs one traversal and no allocation.
|
|
326
|
+
*
|
|
327
|
+
* @param document - Parsed wireframe document
|
|
328
|
+
* @returns The document with all `repeat` nodes expanded
|
|
329
|
+
* @throws {RepeatBudgetError} when expansion exceeds {@link REPEAT_EXPANSION_BUDGET}
|
|
330
|
+
* @public
|
|
331
|
+
* @example
|
|
332
|
+
* `const drawable = expandRepeats(parse(source))`
|
|
333
|
+
*/
|
|
334
|
+
declare function expandRepeats(document: WireframeDocument): WireframeDocument;
|
|
335
|
+
|
|
336
|
+
/**
|
|
337
|
+
* `page … variants=[a, b, c]` expansion — one page turned into the screens it denotes.
|
|
338
|
+
*
|
|
339
|
+
* ## What a variant is, and why it is not a state
|
|
340
|
+
*
|
|
341
|
+
* A wireframe usually has to show a screen in several conditions: loading,
|
|
342
|
+
* empty, populated, failed. The language already has `states` for that, and it
|
|
343
|
+
* is the wrong tool: a `state` is a runtime value the site runtime flips and
|
|
344
|
+
* `visibleWhen` guards read, so *something in the wireframe has to flip it*.
|
|
345
|
+
* That something is a control the product does not have — a reviewer opening
|
|
346
|
+
* the artifact sees state-switching buttons among the real UI and cannot tell
|
|
347
|
+
* which is which. It also produces one board, so the conditions are only
|
|
348
|
+
* visible one at a time, and any block common to two conditions is written
|
|
349
|
+
* twice because a guard has no disjunction.
|
|
350
|
+
*
|
|
351
|
+
* A variant moves the same information from a toggle inside the screen to an
|
|
352
|
+
* axis of the document: `variants=[loading, empty, ready]` draws the page three
|
|
353
|
+
* times, side by side, with no switching UI in any of them. The artifact
|
|
354
|
+
* becomes the sheet of state-by-state boards a reviewer reads top to bottom,
|
|
355
|
+
* and the common blocks are shared because they are one authored body.
|
|
356
|
+
*
|
|
357
|
+
* ## Why this is a document pass, like `repeat`
|
|
358
|
+
*
|
|
359
|
+
* For the reason spelled out at length in `expand-repeats.ts`: the renderer
|
|
360
|
+
* builds `buildAnchorPathMap(document)` up front and keys it by **node object
|
|
361
|
+
* identity**. Two variant boards sharing one child tree would be two boards the
|
|
362
|
+
* map has seen once, so the second would render without `data-wf-path` and the
|
|
363
|
+
* anchor count would stop matching the index. Every variant is therefore a
|
|
364
|
+
* fresh deep clone, and `loc` is deliberately shared: all three boards really do
|
|
365
|
+
* originate at one span of source.
|
|
366
|
+
*
|
|
367
|
+
* Doing it here rather than in each renderer is also what keeps the surfaces
|
|
368
|
+
* agreeing. `render`'s canvas counts pages and `renderSite` builds a screen
|
|
369
|
+
* model; if each expanded on its own, a variant would be a canvas board and a
|
|
370
|
+
* site screen by two separate rules that could drift. They both run this pass
|
|
371
|
+
* and then count what it produced.
|
|
372
|
+
*
|
|
373
|
+
* And, as with `repeat`, this is deliberately **not** in the parser: the AST
|
|
374
|
+
* keeps `variants` so the printer writes it back out, and expanding at parse
|
|
375
|
+
* time would break the `parse(print(parse(src)))` round-trip law the corpus
|
|
376
|
+
* harness pins.
|
|
377
|
+
*/
|
|
378
|
+
|
|
379
|
+
/**
|
|
380
|
+
* Replace every page declaring `variants=` with one page per variant.
|
|
381
|
+
*
|
|
382
|
+
* Each produced page carries `variant` naming which one it is and no longer
|
|
383
|
+
* carries `variants`, so the result declares none and a second application is a
|
|
384
|
+
* no-op. A document with no variants is returned as-is, identity included, so
|
|
385
|
+
* the common case costs one scan and no allocation — the property every
|
|
386
|
+
* existing document relies on to render exactly as it did before.
|
|
387
|
+
*
|
|
388
|
+
* @param document - Parsed wireframe document
|
|
389
|
+
* @returns The document with all variant-bearing pages expanded
|
|
390
|
+
* @public
|
|
391
|
+
* @example
|
|
392
|
+
* `const drawable = expandVariants(parse(source))`
|
|
393
|
+
*/
|
|
394
|
+
declare function expandVariants(document: WireframeDocument): WireframeDocument;
|
|
395
|
+
|
|
396
|
+
/**
|
|
397
|
+
* `when=` filtering — dropping the elements a board does not draw.
|
|
398
|
+
*
|
|
399
|
+
* ## What `when` says, and why it is not a guard
|
|
400
|
+
*
|
|
401
|
+
* `visibleWhen` already answers "should this be on screen right now": the
|
|
402
|
+
* element is rendered onto every board, carries `data-wf-visible-when`, and the
|
|
403
|
+
* site runtime shows and hides it as state changes. `when` answers a different
|
|
404
|
+
* question — *which boards is this element part of at all* — and it answers it
|
|
405
|
+
* before anything renders. An element scoped to `loading` is not hidden on the
|
|
406
|
+
* `ready` board; it is absent from it, so no state change can bring it back and
|
|
407
|
+
* nothing in that board's markup refers to it.
|
|
408
|
+
*
|
|
409
|
+
* The two are therefore orthogonal, not alternatives, and this pass is careful
|
|
410
|
+
* to leave guards alone: it deletes `when` from the nodes it keeps and touches
|
|
411
|
+
* no other property, so `when=ready visibleWhen={…}` survives as a guard on the
|
|
412
|
+
* ready board. Collapsing them would lose the case the feature exists for.
|
|
413
|
+
*
|
|
414
|
+
* ## Why disjunction is the point
|
|
415
|
+
*
|
|
416
|
+
* A guard compares one state to one value, so a block belonging to two
|
|
417
|
+
* conditions could only be written twice. That is not a stylistic cost: the two
|
|
418
|
+
* copies are edited separately and drift, and a reviewer reading the sheet
|
|
419
|
+
* cannot tell whether a difference between them is intentional. `when=[loading,
|
|
420
|
+
* empty]` is the same block, authored once, drawn on both boards — the header
|
|
421
|
+
* shared by three states is one header, and it stays one.
|
|
422
|
+
*
|
|
423
|
+
* ## Why it runs inside variant expansion
|
|
424
|
+
*
|
|
425
|
+
* Filtering needs to know which board it is filtering *for*, and that fact
|
|
426
|
+
* exists only after `expandVariants` has turned one authored page into one page
|
|
427
|
+
* per name and stamped each with `page.variant`. Running as a separate pass
|
|
428
|
+
* afterwards would have to rediscover the same association by walking the
|
|
429
|
+
* document again; running before expansion would have no board to ask about.
|
|
430
|
+
* So the board is filtered at the moment it is cloned, while the name is in
|
|
431
|
+
* hand — see `expand-variants.ts`.
|
|
432
|
+
*
|
|
433
|
+
* ## The rule, stated once
|
|
434
|
+
*
|
|
435
|
+
* An element is drawn on a board **iff its `when` set contains that board's
|
|
436
|
+
* variant**. Everything else follows from that one sentence rather than from a
|
|
437
|
+
* list of cases:
|
|
438
|
+
*
|
|
439
|
+
* - No `when` at all → drawn on every board. This is what keeps every document
|
|
440
|
+
* written before the attribute existed rendering byte-for-byte as it did.
|
|
441
|
+
* - A board with no variant (a page that declared no `variants=`) matches no
|
|
442
|
+
* name, so *any* `when` filters the element out. That is the honest reading
|
|
443
|
+
* rather than a convenient one: the element declares membership in a board
|
|
444
|
+
* this page never declared, and drawing it anyway would make `when` mean
|
|
445
|
+
* "sometimes nothing", which is the silently-dropped-value failure the spec
|
|
446
|
+
* gates exist to prevent. `validate()` reports the same document, so the
|
|
447
|
+
* author is told rather than left to discover an empty board.
|
|
448
|
+
* - A parent that is filtered out takes its children with it, whatever they
|
|
449
|
+
* say. A child scoped to `ready` inside a parent scoped to `loading` cannot
|
|
450
|
+
* be drawn on either board — there is no board where both are present — and
|
|
451
|
+
* the contradiction is reported by `validate()` rather than resolved here.
|
|
452
|
+
*/
|
|
453
|
+
|
|
454
|
+
/**
|
|
455
|
+
* The variant names an element declares, trimmed, blanks and duplicates dropped.
|
|
456
|
+
*
|
|
457
|
+
* Both spellings collapse to the same set, because `when=loading` and
|
|
458
|
+
* `when=[loading]` denote the same membership and nothing downstream should
|
|
459
|
+
* have to know which the author typed.
|
|
460
|
+
*
|
|
461
|
+
* A `when` that is present but names nothing — `when=[]`, or a blank string —
|
|
462
|
+
* yields an empty set, which matches no board. It is deliberately not treated
|
|
463
|
+
* as "no `when`": the author wrote the attribute, and answering an empty list
|
|
464
|
+
* with "every board" would make the emptiest possible scope the widest one.
|
|
465
|
+
*/
|
|
466
|
+
declare function variantScope(node: AnyNode): string[] | undefined;
|
|
467
|
+
/**
|
|
468
|
+
* Drop from `children` everything not drawn on `variant`'s board.
|
|
469
|
+
*
|
|
470
|
+
* Identity-preserving: a subtree carrying no `when` anywhere is returned as the
|
|
471
|
+
* same array, so a board of a document that uses no scoping costs one scan.
|
|
472
|
+
*
|
|
473
|
+
* @param children - The board's children, already cloned by variant expansion
|
|
474
|
+
* @param variant - The board's variant name, or `undefined` for an unnamed board
|
|
475
|
+
* @returns The children this board draws
|
|
476
|
+
* @internal
|
|
477
|
+
*/
|
|
478
|
+
declare function filterVariantScope(children: AnyNode[], variant: string | undefined): AnyNode[];
|
|
479
|
+
/**
|
|
480
|
+
* Apply `when` filtering to every page of a document that expansion did not.
|
|
481
|
+
*
|
|
482
|
+
* Variant-bearing pages are filtered as they are cloned, inside
|
|
483
|
+
* `expandVariants`, because that is where the board's name exists. This covers
|
|
484
|
+
* the rest: a page that declared no `variants=` is still a board, an unnamed
|
|
485
|
+
* one, and an element scoped to a name it never declared is not drawn on it.
|
|
486
|
+
*
|
|
487
|
+
* Layout and component definitions are filtered through the pages that use
|
|
488
|
+
* them, not here — a definition has no board of its own, and scoping inside one
|
|
489
|
+
* resolves against whichever page pulled it in.
|
|
490
|
+
*
|
|
491
|
+
* @param document - A document whose variant-bearing pages are already expanded
|
|
492
|
+
* @returns The document with unnamed boards filtered
|
|
493
|
+
* @internal
|
|
494
|
+
*/
|
|
495
|
+
declare function filterUnscopedPages(document: WireframeDocument): WireframeDocument;
|
|
496
|
+
|
|
179
497
|
/**
|
|
180
498
|
* Node/document-level canonical `.wf` printing.
|
|
181
499
|
*
|
|
@@ -285,103 +603,6 @@ interface PreviewWrapperOptions {
|
|
|
285
603
|
*/
|
|
286
604
|
declare function wrapInPreviewContainer(html: string, viewport: ViewportSize, options?: PreviewWrapperOptions): string;
|
|
287
605
|
|
|
288
|
-
/**
|
|
289
|
-
* Types for Wireweave DSL Specification
|
|
290
|
-
*/
|
|
291
|
-
/**
|
|
292
|
-
* Attribute value type
|
|
293
|
-
*/
|
|
294
|
-
type AttributeValueType = 'boolean' | 'number' | 'string' | 'string[]' | 'enum';
|
|
295
|
-
/**
|
|
296
|
-
* Attribute definition
|
|
297
|
-
*/
|
|
298
|
-
interface AttributeSpec {
|
|
299
|
-
/** Attribute name */
|
|
300
|
-
name: string;
|
|
301
|
-
/** Value type */
|
|
302
|
-
type: AttributeValueType;
|
|
303
|
-
/** Enum values (if type is 'enum') */
|
|
304
|
-
values?: readonly string[];
|
|
305
|
-
/** Description for documentation */
|
|
306
|
-
description?: string;
|
|
307
|
-
}
|
|
308
|
-
/**
|
|
309
|
-
* Component category
|
|
310
|
-
*/
|
|
311
|
-
type ComponentCategory = 'layout' | 'grid' | 'container' | 'text' | 'input' | 'display' | 'data' | 'feedback' | 'overlay' | 'navigation' | 'annotation';
|
|
312
|
-
/**
|
|
313
|
-
* Component definition
|
|
314
|
-
*/
|
|
315
|
-
interface ComponentSpec {
|
|
316
|
-
/** Component name (lowercase, as used in DSL) */
|
|
317
|
-
name: string;
|
|
318
|
-
/** AST node type (PascalCase) */
|
|
319
|
-
nodeType: string;
|
|
320
|
-
/** Component category */
|
|
321
|
-
category: ComponentCategory;
|
|
322
|
-
/** Valid attributes for this component (names only, definitions in ATTRIBUTES) */
|
|
323
|
-
attributes: readonly string[];
|
|
324
|
-
/** Whether this component can have children */
|
|
325
|
-
hasChildren: boolean;
|
|
326
|
-
/** Description for documentation */
|
|
327
|
-
description?: string;
|
|
328
|
-
}
|
|
329
|
-
|
|
330
|
-
/**
|
|
331
|
-
* Wireweave DSL Component Definitions
|
|
332
|
-
*
|
|
333
|
-
* Complete list of all valid components in Wireweave DSL.
|
|
334
|
-
* Each component specifies its valid attributes.
|
|
335
|
-
*/
|
|
336
|
-
|
|
337
|
-
/**
|
|
338
|
-
* All valid components in Wireweave DSL
|
|
339
|
-
*/
|
|
340
|
-
declare const COMPONENT_SPECS: readonly ComponentSpec[];
|
|
341
|
-
/**
|
|
342
|
-
* Set of all valid component names for quick lookup
|
|
343
|
-
*/
|
|
344
|
-
declare const VALID_COMPONENT_NAMES: ReadonlySet<string>;
|
|
345
|
-
/**
|
|
346
|
-
* Map of component name to spec for quick lookup
|
|
347
|
-
*/
|
|
348
|
-
declare const COMPONENT_MAP: ReadonlyMap<string, ComponentSpec>;
|
|
349
|
-
/**
|
|
350
|
-
* Map of AST node type to spec for quick lookup
|
|
351
|
-
*/
|
|
352
|
-
declare const NODE_TYPE_MAP: ReadonlyMap<string, ComponentSpec>;
|
|
353
|
-
/**
|
|
354
|
-
* Get valid attributes for a component (by name or node type)
|
|
355
|
-
*/
|
|
356
|
-
declare function getValidAttributes(componentNameOrType: string): readonly string[] | undefined;
|
|
357
|
-
/**
|
|
358
|
-
* Check if an attribute is valid for a component
|
|
359
|
-
*/
|
|
360
|
-
declare function isValidAttribute(componentNameOrType: string, attributeName: string): boolean;
|
|
361
|
-
|
|
362
|
-
/**
|
|
363
|
-
* Wireweave DSL Attribute Definitions
|
|
364
|
-
*
|
|
365
|
-
* Complete list of all valid attributes in Wireweave DSL.
|
|
366
|
-
*/
|
|
367
|
-
|
|
368
|
-
/**
|
|
369
|
-
* All valid attributes in Wireweave DSL
|
|
370
|
-
*/
|
|
371
|
-
declare const ATTRIBUTE_SPECS: readonly AttributeSpec[];
|
|
372
|
-
/**
|
|
373
|
-
* Set of all valid attribute names for quick lookup
|
|
374
|
-
*/
|
|
375
|
-
declare const VALID_ATTRIBUTE_NAMES: ReadonlySet<string>;
|
|
376
|
-
/**
|
|
377
|
-
* Map of attribute name to spec for quick lookup
|
|
378
|
-
*/
|
|
379
|
-
declare const ATTRIBUTE_MAP: ReadonlyMap<string, AttributeSpec>;
|
|
380
|
-
/**
|
|
381
|
-
* Common attributes available to most components
|
|
382
|
-
*/
|
|
383
|
-
declare const COMMON_ATTRIBUTES: readonly string[];
|
|
384
|
-
|
|
385
606
|
/**
|
|
386
607
|
* Wireweave DSL Validation
|
|
387
608
|
*
|
|
@@ -981,6 +1202,84 @@ interface AnalysisOptions {
|
|
|
981
1202
|
*/
|
|
982
1203
|
declare function analyze(doc: WireframeDocument, options?: AnalysisOptions): AnalysisResult;
|
|
983
1204
|
|
|
1205
|
+
/** Overlay toggle is distinct from the typed boolean-state `toggle` effect. */
|
|
1206
|
+
type NormalizedInteractionEffect = InteractionEffect | {
|
|
1207
|
+
kind: 'toggle-overlay';
|
|
1208
|
+
target: string;
|
|
1209
|
+
} | {
|
|
1210
|
+
kind: 'legacy-action';
|
|
1211
|
+
action: string;
|
|
1212
|
+
};
|
|
1213
|
+
interface NormalizedInteractionHandler {
|
|
1214
|
+
event: 'click';
|
|
1215
|
+
guard?: StateGuard;
|
|
1216
|
+
effects: NormalizedInteractionEffect[];
|
|
1217
|
+
}
|
|
1218
|
+
interface NormalizedInteraction {
|
|
1219
|
+
screenIndex: number;
|
|
1220
|
+
source: 'screen' | 'layout';
|
|
1221
|
+
signature: string;
|
|
1222
|
+
handler: NormalizedInteractionHandler;
|
|
1223
|
+
/** Present when this entry came from a legacy scalar intent attribute. */
|
|
1224
|
+
legacyKind?: InteractionKind;
|
|
1225
|
+
trigger: {
|
|
1226
|
+
nodeType: NodeType;
|
|
1227
|
+
label?: string;
|
|
1228
|
+
loc?: SourceLocation;
|
|
1229
|
+
item?: {
|
|
1230
|
+
index: number;
|
|
1231
|
+
};
|
|
1232
|
+
};
|
|
1233
|
+
}
|
|
1234
|
+
type InteractionDiagnosticCode = 'invalid-state-declaration' | 'duplicate-state-declaration' | 'invalid-interaction-handler' | 'unknown-legacy-action';
|
|
1235
|
+
interface InteractionDiagnostic {
|
|
1236
|
+
code: InteractionDiagnosticCode;
|
|
1237
|
+
message: string;
|
|
1238
|
+
screenIndex?: number;
|
|
1239
|
+
source?: 'screen' | 'layout';
|
|
1240
|
+
loc?: SourceLocation;
|
|
1241
|
+
}
|
|
1242
|
+
interface InteractionModel {
|
|
1243
|
+
states: StateDeclaration[];
|
|
1244
|
+
interactions: NormalizedInteraction[];
|
|
1245
|
+
diagnostics: InteractionDiagnostic[];
|
|
1246
|
+
}
|
|
1247
|
+
/** Normalize a guard object emitted by the generic DSL object grammar. */
|
|
1248
|
+
declare function normalizeStateGuard(value: unknown): StateGuard | undefined;
|
|
1249
|
+
/**
|
|
1250
|
+
* Normalize the public `on=` shape. Malformed handlers are inert; diagnostics
|
|
1251
|
+
* are added by {@link collectInteractions}, where screen/source context exists.
|
|
1252
|
+
*/
|
|
1253
|
+
declare function normalizeInteractionHandlers(value: unknown): NormalizedInteractionHandler[];
|
|
1254
|
+
/** Stable payload shared by rendered DOM markers and the runtime registry. */
|
|
1255
|
+
declare function interactionSignature(handler: NormalizedInteractionHandler): string;
|
|
1256
|
+
/**
|
|
1257
|
+
* The canonical interaction/state source for graph extraction and renderSite.
|
|
1258
|
+
* Layout intent is expanded once per screen using that layout, so shared chrome
|
|
1259
|
+
* has the same reachable routes in both consumers.
|
|
1260
|
+
*
|
|
1261
|
+
* ## Components are read through the linker, never from here
|
|
1262
|
+
*
|
|
1263
|
+
* Screens and layouts are walked; `component` definitions are not. That is the
|
|
1264
|
+
* boundary, not an omission. A handler inside a definition is written against
|
|
1265
|
+
* the component's *parameters* — `target="$to"` — so before an invocation binds
|
|
1266
|
+
* its inputs there is no destination to record, only the name of one. Walking
|
|
1267
|
+
* definitions here would register `"$to"` as a route and invent a graph edge to
|
|
1268
|
+
* a screen that does not exist, and a component used twice with different
|
|
1269
|
+
* inputs is two different routes that a single walk of the definition cannot
|
|
1270
|
+
* tell apart.
|
|
1271
|
+
*
|
|
1272
|
+
* Binding those inputs is `linkApp`'s job: `expandComponentUse` substitutes the
|
|
1273
|
+
* invocation's inputs, fills its slots, and hands back a tree whose handlers
|
|
1274
|
+
* name real targets. So `linkAndCompileApp` — link, then compile — sees every
|
|
1275
|
+
* component interaction, while `renderSite(parse(src))` on a document that
|
|
1276
|
+
* never went through the linker leaves each invocation
|
|
1277
|
+
* `data-wf-component-unresolved` and contributes no interactions. Handlers
|
|
1278
|
+
* written directly on a screen or a layout work in both paths; only handlers
|
|
1279
|
+
* *inside a component definition* require the linked path.
|
|
1280
|
+
*/
|
|
1281
|
+
declare function collectInteractions(doc: WireframeDocument): InteractionModel;
|
|
1282
|
+
|
|
984
1283
|
/**
|
|
985
1284
|
* Types for the deterministic extraction module.
|
|
986
1285
|
*
|
|
@@ -1091,8 +1390,14 @@ interface ScreenFields {
|
|
|
1091
1390
|
}
|
|
1092
1391
|
/**
|
|
1093
1392
|
* A node in the screen-transition graph.
|
|
1393
|
+
*
|
|
1394
|
+
* `id` is the page's declared identifier — a stable slug an author opted into —
|
|
1395
|
+
* and `title` is its display heading. They are separate namespaces: `id` is what
|
|
1396
|
+
* a `navigate` target should key off, `title` is what a reader sees. Either can
|
|
1397
|
+
* be absent.
|
|
1094
1398
|
*/
|
|
1095
1399
|
interface TransitionScreen {
|
|
1400
|
+
id?: string;
|
|
1096
1401
|
title?: string;
|
|
1097
1402
|
index: number;
|
|
1098
1403
|
loc?: SourceLocation;
|
|
@@ -1103,20 +1408,32 @@ interface TransitionScreen {
|
|
|
1103
1408
|
interface TransitionEdge {
|
|
1104
1409
|
from: {
|
|
1105
1410
|
pageIndex: number;
|
|
1411
|
+
id?: string;
|
|
1106
1412
|
title?: string;
|
|
1107
1413
|
};
|
|
1108
1414
|
/**
|
|
1109
1415
|
* The destination page for a resolved `navigate` edge. Always `null` for
|
|
1110
1416
|
* `opens` / `toggles` / `action`, which are intra-page or opaque and never
|
|
1111
1417
|
* cross a page boundary.
|
|
1418
|
+
*
|
|
1419
|
+
* `id` / `title` mirror {@link TransitionScreen}: present when the page
|
|
1420
|
+
* declares them, so a consumer can address the destination by its stable slug
|
|
1421
|
+
* rather than by display text.
|
|
1112
1422
|
*/
|
|
1113
1423
|
to: {
|
|
1114
1424
|
pageIndex: number;
|
|
1425
|
+
id?: string;
|
|
1115
1426
|
title?: string;
|
|
1116
1427
|
} | null;
|
|
1117
1428
|
/** The raw target string as written in the DSL. */
|
|
1118
1429
|
target: string;
|
|
1119
1430
|
kind: InteractionKind;
|
|
1431
|
+
/** Typed event metadata; absent for legacy scalar interaction attributes. */
|
|
1432
|
+
event?: 'click';
|
|
1433
|
+
guard?: StateGuard;
|
|
1434
|
+
effect?: NormalizedInteractionEffect;
|
|
1435
|
+
/** A shared-layout edge is expanded once for every screen using that layout. */
|
|
1436
|
+
source?: 'screen' | 'layout';
|
|
1120
1437
|
/**
|
|
1121
1438
|
* What fired the transition. For a component node, `nodeType` is that node's
|
|
1122
1439
|
* type. For a menu item inside a nav/dropdown/breadcrumb, `nodeType` is the
|
|
@@ -1133,13 +1450,29 @@ interface TransitionEdge {
|
|
|
1133
1450
|
};
|
|
1134
1451
|
};
|
|
1135
1452
|
/**
|
|
1136
|
-
* Whether `target`
|
|
1137
|
-
* - `navigate`: a page whose
|
|
1453
|
+
* Whether `target` names a concrete destination for its kind:
|
|
1454
|
+
* - `navigate`: a page whose `id` matches `target`, or — failing that — whose
|
|
1455
|
+
* `title` matches it. Identifiers are consulted before display text; see
|
|
1456
|
+
* `extract/transitions.ts` for why. Also `true` for an `external` target: a
|
|
1457
|
+
* URL is a complete destination, it is simply not one of this document's
|
|
1458
|
+
* pages, which is why `to` is `null` there.
|
|
1138
1459
|
* - `opens` / `toggles`: a `Modal` / `Drawer` with `id === target` in the
|
|
1139
1460
|
* source page.
|
|
1140
1461
|
* - `action`: always `false` (an opaque handler id has no structural target).
|
|
1141
1462
|
*/
|
|
1142
1463
|
resolved: boolean;
|
|
1464
|
+
/**
|
|
1465
|
+
* Present, and always `true`, when a `navigate` target is a URL rather than
|
|
1466
|
+
* the name of a page (see `interaction/target.ts`). Such an edge leaves the
|
|
1467
|
+
* document: `to` is `null` because there is no page to point at, and it is
|
|
1468
|
+
* never {@link ScreenTransitionGraph.dangling | dangling} — an outbound link
|
|
1469
|
+
* is a destination the author meant, not a reference that failed to resolve.
|
|
1470
|
+
*
|
|
1471
|
+
* This is what separates an external link from an `action`: both have
|
|
1472
|
+
* `to === null`, but an `action` is an opaque handler with `resolved: false`,
|
|
1473
|
+
* while an external link is a real destination the browser can follow.
|
|
1474
|
+
*/
|
|
1475
|
+
external?: true;
|
|
1143
1476
|
}
|
|
1144
1477
|
/**
|
|
1145
1478
|
* The screen-transition graph derived from a whole document.
|
|
@@ -1148,11 +1481,21 @@ interface ScreenTransitionGraph {
|
|
|
1148
1481
|
screens: TransitionScreen[];
|
|
1149
1482
|
edges: TransitionEdge[];
|
|
1150
1483
|
/**
|
|
1151
|
-
* The subset of `navigate` edges whose target matched
|
|
1152
|
-
* (`resolved === false`, `to === null`)
|
|
1153
|
-
*
|
|
1484
|
+
* The subset of `navigate` edges whose target matched neither a page `id` nor
|
|
1485
|
+
* a page title and is not a URL (`resolved === false`, `to === null`) — a name
|
|
1486
|
+
* that was meant to be a screen and found none. This is the defect list: a
|
|
1487
|
+
* consumer reporting "broken transitions" counts exactly these. Intra-page
|
|
1488
|
+
* `opens` / `toggles` and opaque `action` edges are not page transitions and
|
|
1489
|
+
* never appear here, and neither do `external` links.
|
|
1154
1490
|
*/
|
|
1155
1491
|
dangling: TransitionEdge[];
|
|
1492
|
+
/**
|
|
1493
|
+
* The subset of `navigate` edges leaving the document — targets that are URLs
|
|
1494
|
+
* rather than page names ({@link TransitionEdge.external}). Kept apart from
|
|
1495
|
+
* `dangling` so a consumer can show outbound links without counting correct
|
|
1496
|
+
* authoring as breakage.
|
|
1497
|
+
*/
|
|
1498
|
+
external: TransitionEdge[];
|
|
1156
1499
|
}
|
|
1157
1500
|
|
|
1158
1501
|
/**
|
|
@@ -1174,6 +1517,9 @@ interface ScreenTransitionGraph {
|
|
|
1174
1517
|
declare function extractScreenFields(page: PageNode): ScreenFields;
|
|
1175
1518
|
/**
|
|
1176
1519
|
* Extract {@link ScreenFields} for every page in a document, in document order.
|
|
1520
|
+
*
|
|
1521
|
+
* Reuse definitions are skipped: a `layout` is not a screen and has no fields
|
|
1522
|
+
* of its own until a page is drawn inside it.
|
|
1177
1523
|
*/
|
|
1178
1524
|
declare function extractAllScreenFields(doc: WireframeDocument): ScreenFields[];
|
|
1179
1525
|
|
|
@@ -1191,27 +1537,60 @@ declare function extractAllScreenFields(doc: WireframeDocument): ScreenFields[];
|
|
|
1191
1537
|
* `nav ["…"]` array items and `nav { item … group { item … } }` block items
|
|
1192
1538
|
* (including grouped items), plus dropdown and breadcrumb items, are extracted.
|
|
1193
1539
|
* Item triggers carry the container's type in `trigger.nodeType` and the item's
|
|
1194
|
-
* position in `trigger.item.index`.
|
|
1540
|
+
* position in `trigger.item.index`. That position counts only elements that can
|
|
1541
|
+
* hold an intent — dividers and group headings are skipped, in every container
|
|
1542
|
+
* alike — because the index is the handle that points back at an edge's origin,
|
|
1543
|
+
* and an element incapable of producing an edge must not shift what the handle
|
|
1544
|
+
* addresses. `Tabs` items are plain strings without
|
|
1195
1545
|
* `InteractiveProps` and contribute no transition; their panel content is
|
|
1196
1546
|
* reached by normal node traversal.
|
|
1197
1547
|
*
|
|
1198
1548
|
* ## Resolution semantics
|
|
1199
1549
|
*
|
|
1200
|
-
* - **`navigate`** is a page transition. Its target
|
|
1201
|
-
*
|
|
1202
|
-
*
|
|
1203
|
-
*
|
|
1204
|
-
*
|
|
1205
|
-
*
|
|
1550
|
+
* - **`navigate`** is a page transition. Its trimmed target is matched, exactly
|
|
1551
|
+
* and case-sensitively, against **page `id` first and page `title` second**.
|
|
1552
|
+
*
|
|
1553
|
+
* Identifiers are how this DSL names a target: `opens` / `toggles` already
|
|
1554
|
+
* address a `Modal` or `Drawer` by its `id`, so a page addressed by `id` is
|
|
1555
|
+
* the same rule reaching the one container that had been left out — an author
|
|
1556
|
+
* learns one way to point at something, not two.
|
|
1557
|
+
*
|
|
1558
|
+
* The two are different kinds of name. An `id` is a stable identifier the
|
|
1559
|
+
* author opted into (`page "결제 내역" id=billing`); a `title` is display text
|
|
1560
|
+
* that is optional, need not be unique, and is expected to change as copy is
|
|
1561
|
+
* edited. Resolving identifiers first means rewording a heading cannot
|
|
1562
|
+
* silently turn every edge pointing at that screen into a dangling one. Title
|
|
1563
|
+
* matching stays as the fallback because it is how the corpus is written
|
|
1564
|
+
* today, and dropping it would strand every existing document.
|
|
1565
|
+
*
|
|
1566
|
+
* Consequences of that order, all deterministic:
|
|
1567
|
+
* - When one page's `id` equals another page's `title`, the `id` wins and the
|
|
1568
|
+
* title-named page is not reachable by that string. Identifiers always beat
|
|
1569
|
+
* labels; there is no positional tie-break to reason about.
|
|
1570
|
+
* - Within each namespace, duplicates resolve to the first page in document
|
|
1571
|
+
* order — the same rule the title namespace has always used.
|
|
1572
|
+
* - A target matching neither namespace is read by shape (see `isUrlTarget`).
|
|
1573
|
+
* A URL-shaped one — `navigate="/reset"`, `navigate="https://…"` — is an
|
|
1574
|
+
* {@link ScreenTransitionGraph.external | external} destination, not a
|
|
1575
|
+
* defect: the DSL documents `navigate` as a "URL or page" target, so the
|
|
1576
|
+
* author wrote something the DSL allows and there is no page to find.
|
|
1577
|
+
* Anything else is a name that should have matched a page and did not, and
|
|
1578
|
+
* only that is {@link ScreenTransitionGraph.dangling | dangling}. Counting
|
|
1579
|
+
* external links as dangling would report every correct outbound link as a
|
|
1580
|
+
* broken screen transition.
|
|
1206
1581
|
* - **`opens` / `toggles`** target an overlay *within the source page*, not
|
|
1207
1582
|
* another page, so their `to` is always `null`. They resolve when a `Modal`
|
|
1208
|
-
* or `Drawer` in the same page has `id === target`
|
|
1209
|
-
*
|
|
1583
|
+
* or `Drawer` in the same page has `id === target` — the overlay containers
|
|
1584
|
+
* are the only nodes these two kinds can address. Being intra-page, they
|
|
1585
|
+
* never appear in `dangling`.
|
|
1210
1586
|
* - **`action`** is an opaque handler id with no structural destination:
|
|
1211
1587
|
* `to === null`, `resolved === false`, and it is not `dangling`.
|
|
1212
1588
|
*
|
|
1213
1589
|
* Item `href` is a raw anchor, not a declared `navigate` intent, and is
|
|
1214
|
-
* excluded — consistent with node-level extraction.
|
|
1590
|
+
* excluded — consistent with node-level extraction. The HTML renderer draws the
|
|
1591
|
+
* same line: it emits the authored `href` and the declared intent side by side
|
|
1592
|
+
* as `data-navigate` / `data-opens` / `data-toggles` / `data-action`, so every
|
|
1593
|
+
* edge derived here has a counterpart a consumer of the markup can act on.
|
|
1215
1594
|
*/
|
|
1216
1595
|
|
|
1217
1596
|
/**
|
|
@@ -1311,4 +1690,242 @@ declare function getNodeSource(source: string, doc: WireframeDocument, path: str
|
|
|
1311
1690
|
*/
|
|
1312
1691
|
declare function buildDomTree(doc: WireframeDocument, pageIndexBase?: number): DomTreeNode[];
|
|
1313
1692
|
|
|
1314
|
-
|
|
1693
|
+
/**
|
|
1694
|
+
* What a `navigate` target names.
|
|
1695
|
+
*
|
|
1696
|
+
* The DSL documents `navigate` as pointing at "a URL or a page", so every target
|
|
1697
|
+
* is read one of two ways, and the reading decides everything downstream. A page
|
|
1698
|
+
* name resolves against the document and travels to the consumer as declared
|
|
1699
|
+
* intent; a URL is a destination the browser already knows how to reach, so it
|
|
1700
|
+
* belongs in the anchor and the document graph has nothing to say about it.
|
|
1701
|
+
*
|
|
1702
|
+
* The renderer and the transition extractor must read a target identically — the
|
|
1703
|
+
* renderer decides whether the value belongs in `href`, the extractor decides
|
|
1704
|
+
* whether an unmatched value is an authoring mistake. Two copies of that rule
|
|
1705
|
+
* would drift, and the moment they disagree one of the two starts calling
|
|
1706
|
+
* correct authoring a defect. So the rule lives here, below both, and neither
|
|
1707
|
+
* layer has to depend on the other to reach it.
|
|
1708
|
+
*/
|
|
1709
|
+
/**
|
|
1710
|
+
* Whether a `navigate` target is a URL rather than the name of a page.
|
|
1711
|
+
*
|
|
1712
|
+
* A URL is recognised by shape, not by resolving it:
|
|
1713
|
+
* - a path or protocol-relative reference — `/reset`, `//cdn.example.com/x`
|
|
1714
|
+
* - an in-page fragment or bare query — `#terms`, `?tab=2`
|
|
1715
|
+
* - anything opening with an RFC 3986 scheme — `https:`, `mailto:`, `tel:`
|
|
1716
|
+
*
|
|
1717
|
+
* A target containing whitespace is never a URL: a URL carrying a space is
|
|
1718
|
+
* invalid until the space is percent-encoded, whereas page titles are written
|
|
1719
|
+
* as prose and routinely contain spaces. Screening on that first is what keeps
|
|
1720
|
+
* an English heading like `"Note: draft"` from reading as a scheme.
|
|
1721
|
+
*
|
|
1722
|
+
* The remaining ambiguities are decided in favour of "page", because a page name
|
|
1723
|
+
* is the common case and the cost of the two mistakes is not symmetric: calling
|
|
1724
|
+
* a page a URL yields a link that goes nowhere, while calling a URL a page
|
|
1725
|
+
* yields an edge reported as unresolved — visible, not silent. So a
|
|
1726
|
+
* schemeless host (`www.example.com`) is a page name; authors write the scheme.
|
|
1727
|
+
*/
|
|
1728
|
+
declare function isUrlTarget(target: string | undefined): target is string;
|
|
1729
|
+
|
|
1730
|
+
/** A source file and exact span within it. */
|
|
1731
|
+
interface AppSourceSpan {
|
|
1732
|
+
sourceId: string;
|
|
1733
|
+
location: SourceLocation;
|
|
1734
|
+
}
|
|
1735
|
+
/** The two reusable definition kinds addressable by an app reference. */
|
|
1736
|
+
type AppDefinitionKind = 'layout' | 'component';
|
|
1737
|
+
/** Every stable, top-level node kind in a linked application. */
|
|
1738
|
+
type AppNodeKind = AppDefinitionKind | 'screen';
|
|
1739
|
+
/** A manifest entry assigning one module its stable application namespace. */
|
|
1740
|
+
interface AppManifestModule {
|
|
1741
|
+
id: string;
|
|
1742
|
+
namespace: string;
|
|
1743
|
+
location: SourceLocation;
|
|
1744
|
+
}
|
|
1745
|
+
/**
|
|
1746
|
+
* Core-owned manifest describing the modules that make up one application.
|
|
1747
|
+
* @public
|
|
1748
|
+
*/
|
|
1749
|
+
interface AppManifest {
|
|
1750
|
+
id: string;
|
|
1751
|
+
sourceId: string;
|
|
1752
|
+
modules: readonly AppManifestModule[];
|
|
1753
|
+
}
|
|
1754
|
+
/** A reference to a layout or component, local to the owner namespace by default. */
|
|
1755
|
+
interface AppReferenceInput {
|
|
1756
|
+
kind: AppDefinitionKind;
|
|
1757
|
+
id: string;
|
|
1758
|
+
namespace?: string;
|
|
1759
|
+
source: AppSourceSpan;
|
|
1760
|
+
}
|
|
1761
|
+
interface AppNodeInput<TNode> {
|
|
1762
|
+
/** Stable identifier within the module namespace and node kind. */
|
|
1763
|
+
id: string;
|
|
1764
|
+
node: TNode;
|
|
1765
|
+
source: AppSourceSpan;
|
|
1766
|
+
}
|
|
1767
|
+
/** A layout declaration and the reusable definitions it depends on. */
|
|
1768
|
+
interface AppLayoutInput extends AppNodeInput<LayoutDefinitionNode> {
|
|
1769
|
+
references?: readonly AppReferenceInput[];
|
|
1770
|
+
}
|
|
1771
|
+
/** A component declaration and the reusable definitions it depends on. */
|
|
1772
|
+
interface AppComponentInput extends AppNodeInput<ComponentDefinitionNode> {
|
|
1773
|
+
references?: readonly AppReferenceInput[];
|
|
1774
|
+
}
|
|
1775
|
+
/** A screen declaration and the layouts/components it consumes. */
|
|
1776
|
+
interface AppScreenInput extends AppNodeInput<PageNode> {
|
|
1777
|
+
references?: readonly AppReferenceInput[];
|
|
1778
|
+
}
|
|
1779
|
+
/**
|
|
1780
|
+
* One parsed Wireweave module supplied to the Core linker.
|
|
1781
|
+
* @public
|
|
1782
|
+
*/
|
|
1783
|
+
interface AppModuleInput {
|
|
1784
|
+
id: string;
|
|
1785
|
+
source: AppSourceSpan;
|
|
1786
|
+
layouts: readonly AppLayoutInput[];
|
|
1787
|
+
components: readonly AppComponentInput[];
|
|
1788
|
+
screens: readonly AppScreenInput[];
|
|
1789
|
+
}
|
|
1790
|
+
/** Opaque stable identity assigned by the linker. */
|
|
1791
|
+
type AppNodeId = string & {
|
|
1792
|
+
readonly __appNodeId: unique symbol;
|
|
1793
|
+
};
|
|
1794
|
+
/** Stable identity of one expanded component invocation. */
|
|
1795
|
+
type AppComponentInstanceId = string & {
|
|
1796
|
+
readonly __appComponentInstanceId: unique symbol;
|
|
1797
|
+
};
|
|
1798
|
+
/** A reference whose target has been resolved to stable app identity. */
|
|
1799
|
+
interface ResolvedAppReference {
|
|
1800
|
+
kind: AppDefinitionKind;
|
|
1801
|
+
id: string;
|
|
1802
|
+
namespace: string;
|
|
1803
|
+
targetId: AppNodeId;
|
|
1804
|
+
source: AppSourceSpan;
|
|
1805
|
+
}
|
|
1806
|
+
interface ResolvedAppNode<TKind extends AppNodeKind, TNode> {
|
|
1807
|
+
nodeId: AppNodeId;
|
|
1808
|
+
kind: TKind;
|
|
1809
|
+
id: string;
|
|
1810
|
+
moduleId: string;
|
|
1811
|
+
namespace: string;
|
|
1812
|
+
node: TNode;
|
|
1813
|
+
source: AppSourceSpan;
|
|
1814
|
+
references: readonly ResolvedAppReference[];
|
|
1815
|
+
}
|
|
1816
|
+
type ResolvedAppLayout = ResolvedAppNode<'layout', LayoutDefinitionNode>;
|
|
1817
|
+
type ResolvedAppComponent = ResolvedAppNode<'component', ComponentDefinitionNode>;
|
|
1818
|
+
type ResolvedAppScreen = ResolvedAppNode<'screen', PageNode>;
|
|
1819
|
+
/** Stable node-to-source mapping emitted in manifest order. */
|
|
1820
|
+
interface AppSourceMapEntry {
|
|
1821
|
+
nodeId: AppNodeId;
|
|
1822
|
+
source: AppSourceSpan;
|
|
1823
|
+
}
|
|
1824
|
+
/** One resolved module in a linked application document. */
|
|
1825
|
+
interface ResolvedAppModule {
|
|
1826
|
+
id: string;
|
|
1827
|
+
namespace: string;
|
|
1828
|
+
layouts: readonly ResolvedAppLayout[];
|
|
1829
|
+
components: readonly ResolvedAppComponent[];
|
|
1830
|
+
screens: readonly ResolvedAppScreen[];
|
|
1831
|
+
}
|
|
1832
|
+
/**
|
|
1833
|
+
* Core's dependency-closed representation of a multi-module application.
|
|
1834
|
+
* @public
|
|
1835
|
+
*/
|
|
1836
|
+
interface AppDocument {
|
|
1837
|
+
type: 'AppDocument';
|
|
1838
|
+
id: string;
|
|
1839
|
+
modules: readonly ResolvedAppModule[];
|
|
1840
|
+
layouts: readonly ResolvedAppLayout[];
|
|
1841
|
+
components: readonly ResolvedAppComponent[];
|
|
1842
|
+
screens: readonly ResolvedAppScreen[];
|
|
1843
|
+
sourceMap: readonly AppSourceMapEntry[];
|
|
1844
|
+
}
|
|
1845
|
+
/** Stable machine-readable linker diagnostic kinds. */
|
|
1846
|
+
type AppLinkDiagnosticCode = 'missing-module' | 'duplicate-module' | 'duplicate-namespace' | 'duplicate-definition' | 'duplicate-screen' | 'missing-reference' | 'cyclic-reference' | 'invalid-component-definition' | 'invalid-component-invocation';
|
|
1847
|
+
/**
|
|
1848
|
+
* A deterministic linker failure with the exact source span that caused it.
|
|
1849
|
+
* @public
|
|
1850
|
+
*/
|
|
1851
|
+
interface AppLinkDiagnostic {
|
|
1852
|
+
code: AppLinkDiagnosticCode;
|
|
1853
|
+
message: string;
|
|
1854
|
+
source: AppSourceSpan;
|
|
1855
|
+
}
|
|
1856
|
+
type AppLinkResult = {
|
|
1857
|
+
ok: true;
|
|
1858
|
+
document: AppDocument;
|
|
1859
|
+
diagnostics: readonly [];
|
|
1860
|
+
} | {
|
|
1861
|
+
ok: false;
|
|
1862
|
+
document: null;
|
|
1863
|
+
diagnostics: readonly AppLinkDiagnostic[];
|
|
1864
|
+
};
|
|
1865
|
+
|
|
1866
|
+
/**
|
|
1867
|
+
* Create the stable identity used by linked documents and source maps.
|
|
1868
|
+
* Each segment is encoded so punctuation in authored identifiers cannot collide.
|
|
1869
|
+
*
|
|
1870
|
+
* @public
|
|
1871
|
+
*/
|
|
1872
|
+
declare function createAppNodeId(namespace: string, kind: AppNodeKind, id: string): AppNodeId;
|
|
1873
|
+
/** Create the stable identity of an invocation from its owner and structural path. */
|
|
1874
|
+
declare function createAppComponentInstanceId(ownerId: AppNodeId, targetId: AppNodeId, path: readonly number[]): AppComponentInstanceId;
|
|
1875
|
+
/**
|
|
1876
|
+
* Link parsed Wireweave modules into one dependency-closed application document.
|
|
1877
|
+
* The function is pure and returns no document whenever validation finds an error.
|
|
1878
|
+
*
|
|
1879
|
+
* @public
|
|
1880
|
+
* @example
|
|
1881
|
+
* `const result = linkApp(manifest, modules)`
|
|
1882
|
+
*/
|
|
1883
|
+
declare function linkApp(manifest: AppManifest, modules: readonly AppModuleInput[]): AppLinkResult;
|
|
1884
|
+
|
|
1885
|
+
/**
|
|
1886
|
+
* Options for {@link compileApp}.
|
|
1887
|
+
*
|
|
1888
|
+
* Application artifacts always use neutral annotation styling. The option is
|
|
1889
|
+
* intentionally omitted here so every compiler caller gets the same wireframe
|
|
1890
|
+
* presentation while legacy render entry points keep their historical default.
|
|
1891
|
+
*
|
|
1892
|
+
* @public
|
|
1893
|
+
*/
|
|
1894
|
+
type CompileAppOptions = Omit<SiteOptions, 'annotationStyle'>;
|
|
1895
|
+
/** Result of linking modules and compiling the resulting application. @public */
|
|
1896
|
+
type AppCompileResult = {
|
|
1897
|
+
ok: true;
|
|
1898
|
+
document: AppDocument;
|
|
1899
|
+
html: string;
|
|
1900
|
+
diagnostics: readonly [];
|
|
1901
|
+
} | {
|
|
1902
|
+
ok: false;
|
|
1903
|
+
document: null;
|
|
1904
|
+
html: null;
|
|
1905
|
+
diagnostics: readonly AppLinkDiagnostic[];
|
|
1906
|
+
};
|
|
1907
|
+
/**
|
|
1908
|
+
* Compile one linked application into a deterministic, self-contained HTML document.
|
|
1909
|
+
*
|
|
1910
|
+
* The linker has already expanded component invocations and resolved shared
|
|
1911
|
+
* layouts. This function only projects those resolved nodes into the generic
|
|
1912
|
+
* site compositor, using stable app identities for layout names so modules
|
|
1913
|
+
* cannot collide.
|
|
1914
|
+
*
|
|
1915
|
+
* @public
|
|
1916
|
+
* @example
|
|
1917
|
+
* `const html = compileApp(linked.document)`
|
|
1918
|
+
*/
|
|
1919
|
+
declare function compileApp(document: AppDocument, options?: CompileAppOptions): string;
|
|
1920
|
+
/**
|
|
1921
|
+
* Link application modules and compile them when linking succeeds.
|
|
1922
|
+
*
|
|
1923
|
+
* Linker diagnostics remain explicit and no partial HTML is emitted on failure.
|
|
1924
|
+
*
|
|
1925
|
+
* @public
|
|
1926
|
+
* @example
|
|
1927
|
+
* `const result = linkAndCompileApp(manifest, modules)`
|
|
1928
|
+
*/
|
|
1929
|
+
declare function linkAndCompileApp(manifest: AppManifest, modules: readonly AppModuleInput[], options?: CompileAppOptions): AppCompileResult;
|
|
1930
|
+
|
|
1931
|
+
export { ANCHOR_LOC_ATTR, ANCHOR_PATH_ATTR, type AccessibilityMetrics, AccordionNode, AlertNode, type AnalysisOptions, type AnalysisResult, type AnchorEntry, AnyNode, type AppCompileResult, type AppComponentInput, type AppComponentInstanceId, type AppDefinitionKind, type AppDocument, type AppLayoutInput, type AppLinkDiagnostic, type AppLinkDiagnosticCode, type AppLinkResult, type AppManifest, type AppManifestModule, type AppModuleInput, type AppNodeId, type AppNodeKind, type AppReferenceInput, type AppScreenInput, type AppSourceMapEntry, type AppSourceSpan, type AttributeChange, AvatarNode, BadgeNode, BreadcrumbNode, ButtonNode, CardNode, CheckboxNode, ColNode, type CompileAppOptions, type ComplexityMetrics, ComponentCategory, ComponentDefinitionNode, type ComponentParameterReference, type ComponentStats, ComponentUseNode, ContainerComponentNode, ContainerNode, type ContentAnalysis, DEFAULT_VIEWPORT, DEVICE_PRESETS, DataNode, DefinitionNode, type DiffChangeType, type DiffOptions, type DiffResult, type DiffSummary, DisplayNode, DividerComponentNode, type DomTreeNode, DrawerNode, DropdownNode, type ExportOptions, FeedbackNode, type FigmaAutoLayout, type FigmaColor, type FigmaCounterAxisAlign, type FigmaExportResult, type FigmaLayoutMode, type FigmaNode, type FigmaNodeType, type FigmaPrimaryAxisAlign, type FigmaSize, type FigmaSizingMode, type FigmaSolidFill, type FigmaStroke, type FigmaTextAlign, type FigmaTextStyle, FooterNode, GridNode, HeaderNode, IconNode, ImageNode, InputComponentNode, InputNode, InputType, type InteractionDiagnostic, type InteractionDiagnosticCode, InteractionEffect, type InteractionKind, type InteractionModel, type JsonExportResult, type JsonNode, type LayoutAnalysis, LayoutDefinitionNode, LayoutNode, LeafNode, LinkNode, ListNode, MainNode, ModalNode, NavNode, NavigationNode, type NodeChange, type NodePredicate, NodeType, type NormalizedInteraction, type NormalizedInteractionEffect, type NormalizedInteractionHandler, OverlayNode, PageNode, PlaceholderNode, PopoverNode, type PreviewWrapperOptions, ProgressNode, REPEAT_EXPANSION_BUDGET, RadioNode, RepeatBudgetError, type ResolvedAppComponent, type ResolvedAppLayout, type ResolvedAppModule, type ResolvedAppReference, type ResolvedAppScreen, RowNode, type ScreenAction, type ScreenDisplay, type ScreenElement, type ScreenFields, type ScreenFieldsSummary, type ScreenInput, type ScreenTransitionGraph, SectionNode, SelectNode, SidebarNode, SiteOptions, SliderNode, SlotNode, SourceLocation, type SourceSlice, SpinnerNode, StateDeclaration, StateGuard, SwitchNode, TableNode, TabsNode, TextContentNode, TextNode, TextareaNode, TitleNode, ToastNode, TooltipNode, type TransitionEdge, type TransitionScreen, type TreeMetrics, type ValidationError, type ValidationOptions, type ValidationResult, type ViewportSize, type WalkCallback, WireframeDocument, analyze, areIdentical, buildAnchorIndex, buildDomTree, calculateViewportScale, cloneNode, collectInteractions, collectParameterReferences, compileApp, contains, countNodes, createAppComponentInstanceId, createAppNodeId, diff, documentDefinitions, documentPages, expandRepeats, expandVariants, exportToFigma, exportToFigmaString, exportToJson, exportToJsonString, extractAllScreenFields, extractScreenFields, extractScreenTransitions, filterUnscopedPages, filterVariantScope, find, findAll, findByType, formatWireframeCode, getAncestors, getChangeSummary, getDevicePresets, getMaxDepth, getNodeSource, getNodeTypes, getPageSource, getValidationErrors, hasChildren, importFromJson, interactionSignature, isAccordionNode, isAlertNode, isAvatarNode, isBadgeNode, isBreadcrumbNode, isButtonNode, isCardNode, isCheckboxNode, isColNode, isComponentDefinitionNode, isComponentUseNode, isContainerComponentNode, isContainerNode, isDataNode, isDefinitionNode, isDisplayNode, isDividerNode, isDrawerNode, isDropdownNode, isFeedbackNode, isFooterNode, isGridNode, isHeaderNode, isIconNode, isImageNode, isInputComponentNode, isInputNode, isLayoutDefinitionNode, isLayoutNode, isLeafNode, isLinkNode, isListNode, isMainNode, isModalNode, isNavNode, isNavigationNode, isNodeType, isOverlayNode, isPageNode, isPlaceholderNode, isPopoverNode, isProgressNode, isRadioNode, isRowNode, isSectionNode, isSelectNode, isSidebarNode, isSliderNode, isSlotNode, isSpinnerNode, isSwitchNode, isTableNode, isTabsNode, isTextContentNode, isTextNode, isTextareaNode, isTitleNode, isToastNode, isTooltipNode, isUrlTarget, isValidAst, isValidDevicePreset, linkAndCompileApp, linkApp, mapNodes, normalizeInteractionHandlers, normalizeStateGuard, parameterReferenceName, parseViewportString, printWireframe, resetFigmaIdCounter, resolveAnchor, resolveViewport, validate, variantScope, walk, walkDocument, wrapInPreviewContainer };
|