@wireweave/core 4.0.0-beta.0 → 4.0.0-beta.13
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 +17 -462
- package/dist/app.cjs +50 -0
- package/dist/app.d.cts +488 -0
- package/dist/app.d.ts +488 -0
- package/dist/app.js +1 -0
- package/dist/chunk-3RWGG5EC.js +18042 -0
- package/dist/chunk-4TMDPWPR.cjs +186 -0
- package/dist/chunk-4UZBGIGJ.cjs +4359 -0
- package/dist/chunk-5DGRIQDU.cjs +824 -0
- package/dist/chunk-ETV4XYOV.cjs +5 -0
- package/dist/chunk-FS6A6EJ4.js +4345 -0
- package/dist/chunk-IMUVIIJR.cjs +18051 -0
- package/dist/chunk-JJWAFHSV.js +821 -0
- package/dist/chunk-MD6MNOEQ.cjs +2884 -0
- package/dist/chunk-PKBMQBKP.js +5 -0
- package/dist/chunk-R5WBZWBC.js +180 -0
- package/dist/chunk-V3HVWC7C.js +2874 -0
- package/dist/chunk-XYACLXXF.js +51484 -0
- package/dist/chunk-ZPHNXJRY.cjs +51590 -0
- package/dist/index-BGU_4N4W.d.ts +240 -0
- package/dist/index-BlNYFaZd.d.cts +337 -0
- package/dist/index-Cx4-VXVS.d.ts +337 -0
- package/dist/index-DyXaMSgd.d.cts +240 -0
- package/dist/index.cjs +1844 -58238
- package/dist/index.d.cts +556 -102
- package/dist/index.d.ts +556 -102
- package/dist/index.js +1163 -58104
- package/dist/interaction.cjs +26 -0
- package/dist/interaction.d.cts +3 -0
- package/dist/interaction.d.ts +3 -0
- package/dist/interaction.js +1 -0
- package/dist/parser.cjs +34 -6611
- package/dist/parser.d.cts +11 -2
- package/dist/parser.d.ts +11 -2
- package/dist/parser.js +1 -6585
- package/dist/renderer.cjs +119 -50537
- package/dist/renderer.d.cts +348 -123
- package/dist/renderer.d.ts +348 -123
- package/dist/renderer.js +3 -50499
- package/dist/spec.cjs +94 -0
- package/dist/spec.d.cts +301 -0
- package/dist/spec.d.ts +301 -0
- package/dist/spec.js +1 -0
- package/dist/{types-hEr_afgw.d.cts → types-CGRi1k2N.d.cts} +307 -27
- package/dist/{types-hEr_afgw.d.ts → types-CGRi1k2N.d.ts} +307 -27
- package/dist/types-Dkgr0Wyc.d.cts +75 -0
- package/dist/types-Dkgr0Wyc.d.ts +75 -0
- package/dist/v4-types-2ORUg6To.d.cts +137 -0
- package/dist/v4-types-2ORUg6To.d.ts +137 -0
- package/package.json +112 -35
package/dist/index.d.cts
CHANGED
|
@@ -1,7 +1,15 @@
|
|
|
1
|
-
import { A as AnyNode, a as AccordionNode, b as AlertNode, c as AvatarNode, B as BadgeNode, d as BreadcrumbNode, e as ButtonNode,
|
|
2
|
-
export {
|
|
3
|
-
export { ExpectedToken, ParseError, ParseErrorInfo, ParseOptions, ParseResult, getErrors, isValid, parse, tryParse } from './parser.cjs';
|
|
4
|
-
export {
|
|
1
|
+
import { A as AnyNode, a as AccordionNode, b as AlertNode, c as AvatarNode, B as BadgeNode, d as BreadcrumbNode, e as ButtonNode, f as CardNode, g as CheckboxNode, h as ColNode, i as ComponentDefinitionNode, C as ComponentUseNode, j as ContainerComponentNode, k as ContainerNode, D as DataNode, l as DefinitionNode, m as DisplayNode, n as DividerComponentNode, o as DrawerNode, p as DropdownNode, F as FeedbackNode, q as FooterNode, r as GridNode, H as HeaderNode, s as IconNode, t as ImageNode, u as InputComponentNode, v as InputNode, L as LayoutDefinitionNode, w as LayoutNode, x as LeafNode, y as LinkNode, z as ListNode, M as MainNode, E as ModalNode, N as NavNode, J as NavigationNode, K as NodeType, O as OverlayNode, P as PageNode, Q as PlaceholderNode, R as PopoverNode, T as ProgressNode, U as RadioNode, V as RowNode, X as SectionNode, Y as SelectNode, Z as SidebarNode, _ as SliderNode, $ as SlotNode, a0 as SpinnerNode, a1 as SwitchNode, a2 as TableNode, a3 as TabsNode, a4 as TextContentNode, a5 as TextNode, a6 as TextareaNode, a7 as TitleNode, a8 as ToastNode, a9 as TooltipNode, W as WireframeDocument, S as SourceLocation } from './types-CGRi1k2N.cjs';
|
|
2
|
+
export { aa as AlertVariant, ab as AlignValue, ac as AnchorPosition, ad as AnnotationItemNode, ae as AnnotationNode, af as AnnotationsNode, ag as AppearanceProps, ah as AvatarSize, ai as AvatarSizeToken, aj as BadgeSize, ak as BadgeSizeToken, al as BadgeVariant, am as BaseNode, an as BreadcrumbItem, ao as ButtonSize, ap as ButtonSizeToken, aq as ButtonVariant, ar as CommonProps, as as ComponentInputValue, at as ComponentParameter, au as ComponentParameterType, av as ComponentSlotFill, aw as DirectionValue, ax as DrawerPosition, ay as DropdownItemNode, az as FlexProps, aA as GridProps, G as GuardedOutcomeProps, aB as HeightValue, aC as IconSize, aD as IconSizeToken, aE as InputType, aF as InteractionEffect, aG as InteractionHandler, I as InteractiveProps, aH as JustifyValue, aI as ListItemNode, aJ as MarkerColor, aK as MarkerNode, aL as NavBlockItem, aM as NavChild, aN as NavGroupNode, aO as NavItem, aP as Position, aQ as PositionProps, aR as RelativeNode, aS as RepeatNode, aT as SelectOption, aU as ShadowValue, aV as SizeProps, aW as SpacingProps, aX as SpacingValue, aY as SpinnerSize, aZ as SpinnerSizeToken, a_ as StackNode, a$ as StateDeclaration, b0 as StateGuard, b1 as StateValue, b2 as StateValueType, b3 as TabNode, b4 as TextAlign, b5 as TextSize, b6 as TextSizeToken, b7 as TextWeight, b8 as TitleLevel, b9 as ToastPosition, ba as TooltipPosition, bb as TopLevelNode, bc as ValueWithUnit, bd as VariantScopedProps, be as WidthValue } from './types-CGRi1k2N.cjs';
|
|
3
|
+
export { ExpectedToken, ParseError, ParseErrorInfo, ParseOptions, ParseResult, getErrors, getV4SourceSpan, isValid, parse, parseV4, tryParse, tryParseV4 } from './parser.cjs';
|
|
4
|
+
export { ENABLED_GUARD_ATTR, EXTERNAL_NAVIGATE_ATTR, HtmlRenderer, INERT_HREF, INTERACTIVE_ATTR_NAMES, IconData, IconElement, InteractiveAttrs, PlacedPage, ShellMiss, SiteModel, SiteScreen, SiteShell, TYPED_INTERACTION_ATTR, VISIBLE_GUARD_ATTR, anchorIntent, buildSiteModel, createHtmlRenderer, generateComponentStyles, generateStyles, getIconData, guardedOutcomeAttrs, interactiveAttrs, layoutCanvas, lucideIcons, render, renderCanvas, renderIconSvg, renderPage, renderToHtml, renderToSvg, renderUnknownIconSvg, resolvePageDimensions } from './renderer.cjs';
|
|
5
|
+
export { ATTRIBUTE_MAP, ATTRIBUTE_OVERRIDES, ATTRIBUTE_SPECS, BLOCK_NODE_SPECS, BOX_ATTRIBUTES, COMPONENT_MAP, COMPONENT_NAMES, COMPONENT_SPECS, COMPONENT_SPEC_BY_NAME, CONTAINER_ATTRIBUTES, 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.cjs';
|
|
6
|
+
import { C as ComponentCategory } from './types-Dkgr0Wyc.cjs';
|
|
7
|
+
export { A as AttributeOverride, a as AttributeSpec, b as AttributeValueType, c as ComponentSpec } from './types-Dkgr0Wyc.cjs';
|
|
8
|
+
import { S as ScreenFields, a as ScreenTransitionGraph } from './index-BlNYFaZd.cjs';
|
|
9
|
+
export { I as InteractionDiagnostic, b as InteractionDiagnosticCode, c as InteractionKind, d as InteractionModel, N as NormalizedInteraction, e as NormalizedInteractionEffect, f as NormalizedInteractionHandler, g as ScreenAction, h as ScreenDisplay, i as ScreenElement, j as ScreenFieldsSummary, k as ScreenInput, T as TransitionEdge, l as TransitionScreen, m as collectInteractions, n as interactionSignature, o as isUrlTarget, p as normalizeInteractionHandlers, q as normalizeStateGuard } from './index-BlNYFaZd.cjs';
|
|
10
|
+
export { AppArtifact, AppBundle, AppCompileResult, AppComponentInput, AppComponentInstanceId, AppDefinitionKind, AppDocument, AppLayoutInput, AppLinkDiagnostic, AppLinkDiagnosticCode, AppLinkResult, AppManifest, AppManifestModule, AppModuleInput, AppNodeId, AppNodeKind, AppReferenceInput, AppResult, AppScreenInput, AppSourceMapEntry, AppSourceSpan, CompileAppOptions, CreateAppBundleOptions, Diagnostic, InstanceStep, LinkedApp, LinkedIdentity, ResolvedAppComponent, ResolvedAppLayout, ResolvedAppModule, ResolvedAppReference, ResolvedAppScreen, RuntimeBrowserEffect, RuntimeInput, RuntimeSnapshot, RuntimeTrace, ScreenReference, SourceMapEntry, advanceClock, compileApp, createAppBundle, createAppComponentInstanceId, createAppNodeId, createRuntime, linkAndCompileApp, linkApp, reduceEvent, renderSite as renderAppSite, resetRuntime } from './app.cjs';
|
|
11
|
+
export { A as AnnotationStyle, C as CanvasOptions, c as CanvasRenderResult, P as PageRenderResult, R as RenderContext, a as RenderOptions, b as RenderResult, e as SiteOptions, S as SvgRenderOptions, d as SvgRenderResult, f as ThemeColors, T as ThemeConfig, g as darkTheme, h as defaultTheme, i as getTheme, r as renderSite } from './index-DyXaMSgd.cjs';
|
|
12
|
+
export { C as CanonicalDefinition, c as CanonicalModule, d as CanonicalNode, e as CanonicalParameter, f as CanonicalPrimitive, g as CanonicalSymbol, h as CanonicalUse, P as ParsedDocument, i as V4Diagnostic, j as V4ParseError, a as V4ParseOptions, b as V4ParseResult, V as V4SourceSpan } from './v4-types-2ORUg6To.cjs';
|
|
5
13
|
|
|
6
14
|
/**
|
|
7
15
|
* Type guards for wireweave AST
|
|
@@ -16,6 +24,12 @@ declare function hasChildren(node: AnyNode): node is AnyNode & {
|
|
|
16
24
|
declare function isLeafNode(node: AnyNode): node is LeafNode;
|
|
17
25
|
declare function isLayoutNode(node: AnyNode): node is LayoutNode;
|
|
18
26
|
declare function isPageNode(node: AnyNode): node is PageNode;
|
|
27
|
+
/** A `layout` or `component` definition — a named tree, not a screen. */
|
|
28
|
+
declare function isDefinitionNode(node: AnyNode): node is DefinitionNode;
|
|
29
|
+
declare function isLayoutDefinitionNode(node: AnyNode): node is LayoutDefinitionNode;
|
|
30
|
+
declare function isComponentDefinitionNode(node: AnyNode): node is ComponentDefinitionNode;
|
|
31
|
+
declare function isComponentUseNode(node: AnyNode): node is ComponentUseNode;
|
|
32
|
+
declare function isSlotNode(node: AnyNode): node is SlotNode;
|
|
19
33
|
declare function isHeaderNode(node: AnyNode): node is HeaderNode;
|
|
20
34
|
declare function isMainNode(node: AnyNode): node is MainNode;
|
|
21
35
|
declare function isFooterNode(node: AnyNode): node is FooterNode;
|
|
@@ -95,10 +109,33 @@ declare function walk(node: AnyNode, callback: WalkCallback, parent?: AnyNode, d
|
|
|
95
109
|
/**
|
|
96
110
|
* Walk through a document's AST
|
|
97
111
|
*
|
|
112
|
+
* Covers every top-level child — pages *and* reuse definitions — because a walk
|
|
113
|
+
* is about visiting nodes, not about selecting screens.
|
|
114
|
+
*
|
|
98
115
|
* @param document - The wireframe document
|
|
99
116
|
* @param callback - Function called for each node
|
|
100
117
|
*/
|
|
101
118
|
declare function walkDocument(document: WireframeDocument, callback: WalkCallback): void;
|
|
119
|
+
/**
|
|
120
|
+
* The document's pages, in source order.
|
|
121
|
+
*
|
|
122
|
+
* A document's children are not all screens: `layout` and `component`
|
|
123
|
+
* definitions sit alongside `page` as top-level siblings. Anything that counts,
|
|
124
|
+
* indexes, renders or exports *screens* must select them through this helper
|
|
125
|
+
* rather than reading `document.children` directly — otherwise a definition
|
|
126
|
+
* silently becomes screen #0.
|
|
127
|
+
*
|
|
128
|
+
* @param document - The wireframe document
|
|
129
|
+
* @returns Only the `Page` children
|
|
130
|
+
*/
|
|
131
|
+
declare function documentPages(document: WireframeDocument): PageNode[];
|
|
132
|
+
/**
|
|
133
|
+
* The document's reuse definitions (`layout` / `component`), in source order.
|
|
134
|
+
*
|
|
135
|
+
* @param document - The wireframe document
|
|
136
|
+
* @returns Only the definition children
|
|
137
|
+
*/
|
|
138
|
+
declare function documentDefinitions(document: WireframeDocument): DefinitionNode[];
|
|
102
139
|
/**
|
|
103
140
|
* Find the first node matching a predicate
|
|
104
141
|
*
|
|
@@ -176,6 +213,328 @@ declare function contains(node: AnyNode, target: AnyNode): boolean;
|
|
|
176
213
|
*/
|
|
177
214
|
declare function getNodeTypes(node: AnyNode): Set<NodeType>;
|
|
178
215
|
|
|
216
|
+
/**
|
|
217
|
+
* Component parameter references (`"$name"`) — one traversal, one pattern.
|
|
218
|
+
*
|
|
219
|
+
* A component body may reference a declared parameter anywhere a string value
|
|
220
|
+
* sits: a top-level prop (`title "$name"`), a nested object (an interaction
|
|
221
|
+
* effect's `target`), or an element of an array (`effects[]`). Substitution at
|
|
222
|
+
* link time walks all three. Validation must walk exactly the same shape, or a
|
|
223
|
+
* reference that gets substituted is never checked — an undeclared name then
|
|
224
|
+
* survives as the literal string `"$too"` with no diagnostic.
|
|
225
|
+
*
|
|
226
|
+
* Both the linker and the document validator therefore share the traversal and
|
|
227
|
+
* the pattern defined here rather than re-deriving either.
|
|
228
|
+
*/
|
|
229
|
+
|
|
230
|
+
/**
|
|
231
|
+
* The parameter name a string value references, or `undefined` when the value
|
|
232
|
+
* is ordinary text.
|
|
233
|
+
*
|
|
234
|
+
* @param value - Any value; only whole-string references match.
|
|
235
|
+
* @returns The referenced name without its `$`, or `undefined`.
|
|
236
|
+
* @public
|
|
237
|
+
*/
|
|
238
|
+
declare function parameterReferenceName(value: unknown): string | undefined;
|
|
239
|
+
/**
|
|
240
|
+
* One `"$name"` reference found inside a component body.
|
|
241
|
+
*
|
|
242
|
+
* @public
|
|
243
|
+
*/
|
|
244
|
+
interface ComponentParameterReference {
|
|
245
|
+
/** Referenced parameter name, without its `$`. */
|
|
246
|
+
name: string;
|
|
247
|
+
/**
|
|
248
|
+
* Property key the reference was found under. Nested keys report the leaf
|
|
249
|
+
* key (`target`), which is what an author sees in the source text.
|
|
250
|
+
*/
|
|
251
|
+
key: string;
|
|
252
|
+
/** Nearest enclosing AST node, for diagnostic location and node type. */
|
|
253
|
+
node: AnyNode;
|
|
254
|
+
}
|
|
255
|
+
/**
|
|
256
|
+
* Every parameter reference reachable from a component's children.
|
|
257
|
+
*
|
|
258
|
+
* Mirrors link-time substitution exactly: it descends into arrays and plain
|
|
259
|
+
* objects as well as child nodes, and skips `loc` so a source location can
|
|
260
|
+
* never be mistaken for authored content. `ComponentUse` subtrees are skipped —
|
|
261
|
+
* a nested invocation's inputs belong to that component's own scope, and its
|
|
262
|
+
* body is validated where it is defined.
|
|
263
|
+
*
|
|
264
|
+
* @param children - The component definition's children.
|
|
265
|
+
* @returns References in traversal order.
|
|
266
|
+
* @public
|
|
267
|
+
* @example
|
|
268
|
+
* `collectParameterReferences(definition.children).map((item) => item.name)`
|
|
269
|
+
*/
|
|
270
|
+
declare function collectParameterReferences(children: readonly AnyNode[]): ComponentParameterReference[];
|
|
271
|
+
|
|
272
|
+
/**
|
|
273
|
+
* `repeat N { … }` expansion — folding syntax turned into the tree it denotes.
|
|
274
|
+
*
|
|
275
|
+
* ## Why this is a pass over the document, not a case in the renderer
|
|
276
|
+
*
|
|
277
|
+
* `repeat` has to disappear before anything *measures* the tree, not merely
|
|
278
|
+
* before something draws it. The renderer builds its anchor index up front:
|
|
279
|
+
* `HtmlRenderer.render` calls `buildAnchorPathMap(document)` before emitting a
|
|
280
|
+
* byte, and that map is keyed by **node object identity**. A `Repeat` expanded
|
|
281
|
+
* lazily inside `renderNode` would hand back copies the map has never seen, so
|
|
282
|
+
* every copy but the first would render without a `data-wf-path` and the anchor
|
|
283
|
+
* count would stop matching the index — the exact drift `anchor-path.ts` exists
|
|
284
|
+
* to prevent. Expanding the whole document first means the map, the markup, the
|
|
285
|
+
* DOM map and the UX rules all see one identical tree.
|
|
286
|
+
*
|
|
287
|
+
* It is equally deliberate that this is **not** in the parser. The AST keeps the
|
|
288
|
+
* `Repeat` node so the printer can write `repeat 6` back out; expanding at parse
|
|
289
|
+
* time would make `parse(print(parse(src)))` return six bodies where the source
|
|
290
|
+
* had one, breaking the round-trip law the corpus harness pins.
|
|
291
|
+
*
|
|
292
|
+
* ## Identity and source anchors
|
|
293
|
+
*
|
|
294
|
+
* Every copy is a fresh deep clone, never a shared reference — see above for why
|
|
295
|
+
* identity matters. Clones intentionally keep the `loc` of the body they came
|
|
296
|
+
* from: all six copies of `repeat 6 { … }` really do originate at one span of
|
|
297
|
+
* source, so pointing back at it is accurate, and it is the same thing component
|
|
298
|
+
* expansion already does. Uniqueness comes from position instead — anchor paths
|
|
299
|
+
* are child indices (`0.2.1`), so the copies land at distinct sibling indices
|
|
300
|
+
* automatically and no two share a path.
|
|
301
|
+
*/
|
|
302
|
+
|
|
303
|
+
/**
|
|
304
|
+
* Total node budget for one expansion.
|
|
305
|
+
*
|
|
306
|
+
* Nesting multiplies — `repeat 100 { repeat 100 { … } }` is ten thousand bodies
|
|
307
|
+
* — so a per-`repeat` cap on `N` would not bound the result. The budget is
|
|
308
|
+
* therefore on the **expanded total**, which is the quantity that actually costs
|
|
309
|
+
* anything, and it is checked as the tree is built so a runaway document stops
|
|
310
|
+
* early instead of being materialised and then rejected.
|
|
311
|
+
*
|
|
312
|
+
* The number is the page-complexity ceiling `ux-rules` already applies
|
|
313
|
+
* (`MAX_PAGE_ELEMENTS`, 50) times ten. Tying it to that constant rather than
|
|
314
|
+
* inventing a figure keeps one notion of "too big for a wireframe" in the
|
|
315
|
+
* codebase; the multiplier is headroom, so that a document merely worth warning
|
|
316
|
+
* about still renders — `tooManyPageElements` reports at 50 and this refuses at
|
|
317
|
+
* 500, leaving an order of magnitude in which a document is complained about
|
|
318
|
+
* but still drawn, and only past that is it refused outright.
|
|
319
|
+
*/
|
|
320
|
+
declare const REPEAT_EXPANSION_BUDGET = 500;
|
|
321
|
+
/** Thrown when an expansion would exceed {@link REPEAT_EXPANSION_BUDGET}. */
|
|
322
|
+
declare class RepeatBudgetError extends Error {
|
|
323
|
+
constructor(budget: number);
|
|
324
|
+
}
|
|
325
|
+
/**
|
|
326
|
+
* Replace every `repeat N { … }` in a document with `N` copies of its body.
|
|
327
|
+
*
|
|
328
|
+
* Idempotent by construction — the result contains no `Repeat` nodes, so a
|
|
329
|
+
* second application is a no-op. A document with no `repeat` is returned as-is,
|
|
330
|
+
* identity included, so the common case costs one traversal and no allocation.
|
|
331
|
+
*
|
|
332
|
+
* @param document - Parsed wireframe document
|
|
333
|
+
* @returns The document with all `repeat` nodes expanded
|
|
334
|
+
* @throws {RepeatBudgetError} when expansion exceeds {@link REPEAT_EXPANSION_BUDGET}
|
|
335
|
+
* @public
|
|
336
|
+
* @example
|
|
337
|
+
* `const drawable = expandRepeats(parse(source))`
|
|
338
|
+
*/
|
|
339
|
+
declare function expandRepeats(document: WireframeDocument): WireframeDocument;
|
|
340
|
+
|
|
341
|
+
/**
|
|
342
|
+
* `page … variants=[a, b, c]` expansion — one page turned into the screens it denotes.
|
|
343
|
+
*
|
|
344
|
+
* ## What a variant is, and why it is not a state
|
|
345
|
+
*
|
|
346
|
+
* A wireframe usually has to show a screen in several conditions: loading,
|
|
347
|
+
* empty, populated, failed. The language already has `states` for that, and it
|
|
348
|
+
* is the wrong tool: a `state` is a runtime value the site runtime flips and
|
|
349
|
+
* `visibleWhen` guards read, so *something in the wireframe has to flip it*.
|
|
350
|
+
* That something is a control the product does not have — a reviewer opening
|
|
351
|
+
* the artifact sees state-switching buttons among the real UI and cannot tell
|
|
352
|
+
* which is which. It also produces one board, so the conditions are only
|
|
353
|
+
* visible one at a time, and any block common to two conditions is written
|
|
354
|
+
* twice because a guard has no disjunction.
|
|
355
|
+
*
|
|
356
|
+
* A variant moves the same information from a toggle inside the screen to an
|
|
357
|
+
* axis of the document: `variants=[loading, empty, ready]` draws the page three
|
|
358
|
+
* times, side by side, with no switching UI in any of them. The artifact
|
|
359
|
+
* becomes the sheet of state-by-state boards a reviewer reads top to bottom,
|
|
360
|
+
* and the common blocks are shared because they are one authored body.
|
|
361
|
+
*
|
|
362
|
+
* ## Why this is a document pass, like `repeat`
|
|
363
|
+
*
|
|
364
|
+
* For the reason spelled out at length in `expand-repeats.ts`: the renderer
|
|
365
|
+
* builds `buildAnchorPathMap(document)` up front and keys it by **node object
|
|
366
|
+
* identity**. Two variant boards sharing one child tree would be two boards the
|
|
367
|
+
* map has seen once, so the second would render without `data-wf-path` and the
|
|
368
|
+
* anchor count would stop matching the index. Every variant is therefore a
|
|
369
|
+
* fresh deep clone, and `loc` is deliberately shared: all three boards really do
|
|
370
|
+
* originate at one span of source.
|
|
371
|
+
*
|
|
372
|
+
* Doing it here rather than in each renderer is also what keeps the surfaces
|
|
373
|
+
* agreeing. `render`'s canvas counts pages and `renderSite` builds a screen
|
|
374
|
+
* model; if each expanded on its own, a variant would be a canvas board and a
|
|
375
|
+
* site screen by two separate rules that could drift. They both run this pass
|
|
376
|
+
* and then count what it produced.
|
|
377
|
+
*
|
|
378
|
+
* And, as with `repeat`, this is deliberately **not** in the parser: the AST
|
|
379
|
+
* keeps `variants` so the printer writes it back out, and expanding at parse
|
|
380
|
+
* time would break the `parse(print(parse(src)))` round-trip law the corpus
|
|
381
|
+
* harness pins.
|
|
382
|
+
*/
|
|
383
|
+
|
|
384
|
+
/**
|
|
385
|
+
* Replace every page declaring `variants=` with one page per variant.
|
|
386
|
+
*
|
|
387
|
+
* Each produced page carries `variant` naming which one it is and no longer
|
|
388
|
+
* carries `variants`, so the result declares none and a second application is a
|
|
389
|
+
* no-op. A document with no variants is returned as-is, identity included, so
|
|
390
|
+
* the common case costs one scan and no allocation — the property every
|
|
391
|
+
* existing document relies on to render exactly as it did before.
|
|
392
|
+
*
|
|
393
|
+
* @param document - Parsed wireframe document
|
|
394
|
+
* @returns The document with all variant-bearing pages expanded
|
|
395
|
+
* @public
|
|
396
|
+
* @example
|
|
397
|
+
* `const drawable = expandVariants(parse(source))`
|
|
398
|
+
*/
|
|
399
|
+
declare function expandVariants(document: WireframeDocument): WireframeDocument;
|
|
400
|
+
|
|
401
|
+
/**
|
|
402
|
+
* `when=` filtering — dropping the elements a board does not draw.
|
|
403
|
+
*
|
|
404
|
+
* ## What `when` says, and why it is not a guard
|
|
405
|
+
*
|
|
406
|
+
* `visibleWhen` already answers "should this be on screen right now": the
|
|
407
|
+
* element is rendered onto every board, carries `data-wf-visible-when`, and the
|
|
408
|
+
* site runtime shows and hides it as state changes. `when` answers a different
|
|
409
|
+
* question — *which boards is this element part of at all* — and it answers it
|
|
410
|
+
* before anything renders. An element scoped to `loading` is not hidden on the
|
|
411
|
+
* `ready` board; it is absent from it, so no state change can bring it back and
|
|
412
|
+
* nothing in that board's markup refers to it.
|
|
413
|
+
*
|
|
414
|
+
* The two are therefore orthogonal, not alternatives, and this pass is careful
|
|
415
|
+
* to leave guards alone: it deletes `when` from the nodes it keeps and touches
|
|
416
|
+
* no other property, so `when=ready visibleWhen={…}` survives as a guard on the
|
|
417
|
+
* ready board. Collapsing them would lose the case the feature exists for.
|
|
418
|
+
*
|
|
419
|
+
* ## Why disjunction is the point
|
|
420
|
+
*
|
|
421
|
+
* A guard compares one state to one value, so a block belonging to two
|
|
422
|
+
* conditions could only be written twice. That is not a stylistic cost: the two
|
|
423
|
+
* copies are edited separately and drift, and a reviewer reading the sheet
|
|
424
|
+
* cannot tell whether a difference between them is intentional. `when=[loading,
|
|
425
|
+
* empty]` is the same block, authored once, drawn on both boards — the header
|
|
426
|
+
* shared by three states is one header, and it stays one.
|
|
427
|
+
*
|
|
428
|
+
* ## Why it runs inside variant expansion
|
|
429
|
+
*
|
|
430
|
+
* Filtering needs to know which board it is filtering *for*, and that fact
|
|
431
|
+
* exists only after `expandVariants` has turned one authored page into one page
|
|
432
|
+
* per name and stamped each with `page.variant`. Running as a separate pass
|
|
433
|
+
* afterwards would have to rediscover the same association by walking the
|
|
434
|
+
* document again; running before expansion would have no board to ask about.
|
|
435
|
+
* So the board is filtered at the moment it is cloned, while the name is in
|
|
436
|
+
* hand — see `expand-variants.ts`.
|
|
437
|
+
*
|
|
438
|
+
* ## The rule, stated once
|
|
439
|
+
*
|
|
440
|
+
* An element is drawn on a board **iff its `when` set contains that board's
|
|
441
|
+
* variant**. Everything else follows from that one sentence rather than from a
|
|
442
|
+
* list of cases:
|
|
443
|
+
*
|
|
444
|
+
* - No `when` at all → drawn on every board. This is what keeps every document
|
|
445
|
+
* written before the attribute existed rendering byte-for-byte as it did.
|
|
446
|
+
* - A board with no variant (a page that declared no `variants=`) matches no
|
|
447
|
+
* name, so *any* `when` filters the element out. That is the honest reading
|
|
448
|
+
* rather than a convenient one: the element declares membership in a board
|
|
449
|
+
* this page never declared, and drawing it anyway would make `when` mean
|
|
450
|
+
* "sometimes nothing", which is the silently-dropped-value failure the spec
|
|
451
|
+
* gates exist to prevent. `validate()` reports the same document, so the
|
|
452
|
+
* author is told rather than left to discover an empty board.
|
|
453
|
+
* - A parent that is filtered out takes its children with it, whatever they
|
|
454
|
+
* say. A child scoped to `ready` inside a parent scoped to `loading` cannot
|
|
455
|
+
* be drawn on either board — there is no board where both are present — and
|
|
456
|
+
* the contradiction is reported by `validate()` rather than resolved here.
|
|
457
|
+
*/
|
|
458
|
+
|
|
459
|
+
/**
|
|
460
|
+
* The variant names an element declares, trimmed, blanks and duplicates dropped.
|
|
461
|
+
*
|
|
462
|
+
* Both spellings collapse to the same set, because `when=loading` and
|
|
463
|
+
* `when=[loading]` denote the same membership and nothing downstream should
|
|
464
|
+
* have to know which the author typed.
|
|
465
|
+
*
|
|
466
|
+
* A `when` that is present but names nothing — `when=[]`, or a blank string —
|
|
467
|
+
* yields an empty set, which matches no board. It is deliberately not treated
|
|
468
|
+
* as "no `when`": the author wrote the attribute, and answering an empty list
|
|
469
|
+
* with "every board" would make the emptiest possible scope the widest one.
|
|
470
|
+
*/
|
|
471
|
+
declare function variantScope(node: AnyNode): string[] | undefined;
|
|
472
|
+
/**
|
|
473
|
+
* Drop from `children` everything not drawn on `variant`'s board.
|
|
474
|
+
*
|
|
475
|
+
* Identity-preserving: a subtree carrying no `when` anywhere is returned as the
|
|
476
|
+
* same array, so a board of a document that uses no scoping costs one scan.
|
|
477
|
+
*
|
|
478
|
+
* @param children - The board's children, already cloned by variant expansion
|
|
479
|
+
* @param variant - The board's variant name, or `undefined` for an unnamed board
|
|
480
|
+
* @returns The children this board draws
|
|
481
|
+
* @internal
|
|
482
|
+
*/
|
|
483
|
+
declare function filterVariantScope(children: AnyNode[], variant: string | undefined): AnyNode[];
|
|
484
|
+
/**
|
|
485
|
+
* Apply `when` filtering to every page of a document that expansion did not.
|
|
486
|
+
*
|
|
487
|
+
* Variant-bearing pages are filtered as they are cloned, inside
|
|
488
|
+
* `expandVariants`, because that is where the board's name exists. This covers
|
|
489
|
+
* the rest: a page that declared no `variants=` is still a board, an unnamed
|
|
490
|
+
* one, and an element scoped to a name it never declared is not drawn on it.
|
|
491
|
+
*
|
|
492
|
+
* Layout and component definitions are filtered through the pages that use
|
|
493
|
+
* them, not here — a definition has no board of its own, and scoping inside one
|
|
494
|
+
* resolves against whichever page pulled it in.
|
|
495
|
+
*
|
|
496
|
+
* @param document - A document whose variant-bearing pages are already expanded
|
|
497
|
+
* @returns The document with unnamed boards filtered
|
|
498
|
+
* @internal
|
|
499
|
+
*/
|
|
500
|
+
declare function filterUnscopedPages(document: WireframeDocument): WireframeDocument;
|
|
501
|
+
|
|
502
|
+
/**
|
|
503
|
+
* Node/document-level canonical `.wf` printing.
|
|
504
|
+
*
|
|
505
|
+
* See `src/printer/index.ts` for the canonical-form rules and the documented
|
|
506
|
+
* non-round-trippable cases. Every branch here mirrors one element rule in
|
|
507
|
+
* `src/grammar/wireframe.peggy`; printed output is always valid parser input.
|
|
508
|
+
*/
|
|
509
|
+
|
|
510
|
+
/**
|
|
511
|
+
* Print a parsed {@link WireframeDocument} to canonical `.wf` DSL text.
|
|
512
|
+
*
|
|
513
|
+
* The output is deterministic (a pure function of the AST structure), is
|
|
514
|
+
* always valid `parse` input, and satisfies the round-trip laws documented in
|
|
515
|
+
* `src/printer/index.ts`. An empty document prints as an empty string;
|
|
516
|
+
* otherwise the text ends with exactly one trailing newline.
|
|
517
|
+
*
|
|
518
|
+
* @public
|
|
519
|
+
* @example
|
|
520
|
+
* ```ts
|
|
521
|
+
* const doc = parse('page "Login" { button "Sign in" primary }')
|
|
522
|
+
* const canonical = printWireframe(doc)
|
|
523
|
+
* // 'page "Login" {\n button "Sign in" primary\n}\n'
|
|
524
|
+
* ```
|
|
525
|
+
*/
|
|
526
|
+
declare function printWireframe(doc: WireframeDocument): string;
|
|
527
|
+
/**
|
|
528
|
+
* Parse `.wf` source and reprint it in canonical form.
|
|
529
|
+
*
|
|
530
|
+
* Comments are discarded (the parser drops them before the AST). Reformatting
|
|
531
|
+
* already-canonical text is the identity.
|
|
532
|
+
*
|
|
533
|
+
* @public
|
|
534
|
+
* @throws {ParseError} When `source` contains syntax errors.
|
|
535
|
+
*/
|
|
536
|
+
declare function formatWireframeCode(source: string): string;
|
|
537
|
+
|
|
179
538
|
/**
|
|
180
539
|
* Device viewport presets for wireweave
|
|
181
540
|
*
|
|
@@ -249,103 +608,6 @@ interface PreviewWrapperOptions {
|
|
|
249
608
|
*/
|
|
250
609
|
declare function wrapInPreviewContainer(html: string, viewport: ViewportSize, options?: PreviewWrapperOptions): string;
|
|
251
610
|
|
|
252
|
-
/**
|
|
253
|
-
* Types for Wireweave DSL Specification
|
|
254
|
-
*/
|
|
255
|
-
/**
|
|
256
|
-
* Attribute value type
|
|
257
|
-
*/
|
|
258
|
-
type AttributeValueType = 'boolean' | 'number' | 'string' | 'string[]' | 'enum';
|
|
259
|
-
/**
|
|
260
|
-
* Attribute definition
|
|
261
|
-
*/
|
|
262
|
-
interface AttributeSpec {
|
|
263
|
-
/** Attribute name */
|
|
264
|
-
name: string;
|
|
265
|
-
/** Value type */
|
|
266
|
-
type: AttributeValueType;
|
|
267
|
-
/** Enum values (if type is 'enum') */
|
|
268
|
-
values?: readonly string[];
|
|
269
|
-
/** Description for documentation */
|
|
270
|
-
description?: string;
|
|
271
|
-
}
|
|
272
|
-
/**
|
|
273
|
-
* Component category
|
|
274
|
-
*/
|
|
275
|
-
type ComponentCategory = 'layout' | 'grid' | 'container' | 'text' | 'input' | 'display' | 'data' | 'feedback' | 'overlay' | 'navigation' | 'annotation';
|
|
276
|
-
/**
|
|
277
|
-
* Component definition
|
|
278
|
-
*/
|
|
279
|
-
interface ComponentSpec {
|
|
280
|
-
/** Component name (lowercase, as used in DSL) */
|
|
281
|
-
name: string;
|
|
282
|
-
/** AST node type (PascalCase) */
|
|
283
|
-
nodeType: string;
|
|
284
|
-
/** Component category */
|
|
285
|
-
category: ComponentCategory;
|
|
286
|
-
/** Valid attributes for this component (names only, definitions in ATTRIBUTES) */
|
|
287
|
-
attributes: readonly string[];
|
|
288
|
-
/** Whether this component can have children */
|
|
289
|
-
hasChildren: boolean;
|
|
290
|
-
/** Description for documentation */
|
|
291
|
-
description?: string;
|
|
292
|
-
}
|
|
293
|
-
|
|
294
|
-
/**
|
|
295
|
-
* Wireweave DSL Component Definitions
|
|
296
|
-
*
|
|
297
|
-
* Complete list of all valid components in Wireweave DSL.
|
|
298
|
-
* Each component specifies its valid attributes.
|
|
299
|
-
*/
|
|
300
|
-
|
|
301
|
-
/**
|
|
302
|
-
* All valid components in Wireweave DSL
|
|
303
|
-
*/
|
|
304
|
-
declare const COMPONENT_SPECS: readonly ComponentSpec[];
|
|
305
|
-
/**
|
|
306
|
-
* Set of all valid component names for quick lookup
|
|
307
|
-
*/
|
|
308
|
-
declare const VALID_COMPONENT_NAMES: ReadonlySet<string>;
|
|
309
|
-
/**
|
|
310
|
-
* Map of component name to spec for quick lookup
|
|
311
|
-
*/
|
|
312
|
-
declare const COMPONENT_MAP: ReadonlyMap<string, ComponentSpec>;
|
|
313
|
-
/**
|
|
314
|
-
* Map of AST node type to spec for quick lookup
|
|
315
|
-
*/
|
|
316
|
-
declare const NODE_TYPE_MAP: ReadonlyMap<string, ComponentSpec>;
|
|
317
|
-
/**
|
|
318
|
-
* Get valid attributes for a component (by name or node type)
|
|
319
|
-
*/
|
|
320
|
-
declare function getValidAttributes(componentNameOrType: string): readonly string[] | undefined;
|
|
321
|
-
/**
|
|
322
|
-
* Check if an attribute is valid for a component
|
|
323
|
-
*/
|
|
324
|
-
declare function isValidAttribute(componentNameOrType: string, attributeName: string): boolean;
|
|
325
|
-
|
|
326
|
-
/**
|
|
327
|
-
* Wireweave DSL Attribute Definitions
|
|
328
|
-
*
|
|
329
|
-
* Complete list of all valid attributes in Wireweave DSL.
|
|
330
|
-
*/
|
|
331
|
-
|
|
332
|
-
/**
|
|
333
|
-
* All valid attributes in Wireweave DSL
|
|
334
|
-
*/
|
|
335
|
-
declare const ATTRIBUTE_SPECS: readonly AttributeSpec[];
|
|
336
|
-
/**
|
|
337
|
-
* Set of all valid attribute names for quick lookup
|
|
338
|
-
*/
|
|
339
|
-
declare const VALID_ATTRIBUTE_NAMES: ReadonlySet<string>;
|
|
340
|
-
/**
|
|
341
|
-
* Map of attribute name to spec for quick lookup
|
|
342
|
-
*/
|
|
343
|
-
declare const ATTRIBUTE_MAP: ReadonlyMap<string, AttributeSpec>;
|
|
344
|
-
/**
|
|
345
|
-
* Common attributes available to most components
|
|
346
|
-
*/
|
|
347
|
-
declare const COMMON_ATTRIBUTES: readonly string[];
|
|
348
|
-
|
|
349
611
|
/**
|
|
350
612
|
* Wireweave DSL Validation
|
|
351
613
|
*
|
|
@@ -945,4 +1207,196 @@ interface AnalysisOptions {
|
|
|
945
1207
|
*/
|
|
946
1208
|
declare function analyze(doc: WireframeDocument, options?: AnalysisOptions): AnalysisResult;
|
|
947
1209
|
|
|
948
|
-
|
|
1210
|
+
/**
|
|
1211
|
+
* E3 — Screen field extraction.
|
|
1212
|
+
*
|
|
1213
|
+
* `extractScreenFields(page)` walks a single parsed page and structures its
|
|
1214
|
+
* contents into the SSOT Screen skeleton slots (title / UI 요소·입력 필드 /
|
|
1215
|
+
* 표시 데이터 / 전이). Purely deterministic — no prose generation.
|
|
1216
|
+
*/
|
|
1217
|
+
|
|
1218
|
+
/**
|
|
1219
|
+
* Extract the structured field set from a single page.
|
|
1220
|
+
*
|
|
1221
|
+
* Iterates every real component node below the page (the page node itself is
|
|
1222
|
+
* excluded), classifying each by its {@link ComponentCategory}. Pseudo-nodes
|
|
1223
|
+
* that are not real AST components (e.g. nav block `item` / `group` entries)
|
|
1224
|
+
* are skipped.
|
|
1225
|
+
*/
|
|
1226
|
+
declare function extractScreenFields(page: PageNode): ScreenFields;
|
|
1227
|
+
/**
|
|
1228
|
+
* Extract {@link ScreenFields} for every page in a document, in document order.
|
|
1229
|
+
*
|
|
1230
|
+
* Reuse definitions are skipped: a `layout` is not a screen and has no fields
|
|
1231
|
+
* of its own until a page is drawn inside it.
|
|
1232
|
+
*/
|
|
1233
|
+
declare function extractAllScreenFields(doc: WireframeDocument): ScreenFields[];
|
|
1234
|
+
|
|
1235
|
+
/**
|
|
1236
|
+
* E1 — Screen transition graph derivation.
|
|
1237
|
+
*
|
|
1238
|
+
* `extractScreenTransitions(doc)` derives the page-to-page navigation graph from
|
|
1239
|
+
* every interactive node in a multi-page document. Purely deterministic.
|
|
1240
|
+
*
|
|
1241
|
+
* ## Trigger sources
|
|
1242
|
+
*
|
|
1243
|
+
* A transition can be fired by a component node (a `Button`, `Link`, `Card`…)
|
|
1244
|
+
* or by a **menu item** inside a nav / dropdown / breadcrumb container. Nav
|
|
1245
|
+
* menus are the primary transition source in a multi-screen wireframe, so both
|
|
1246
|
+
* `nav ["…"]` array items and `nav { item … group { item … } }` block items
|
|
1247
|
+
* (including grouped items), plus dropdown and breadcrumb items, are extracted.
|
|
1248
|
+
* Item triggers carry the container's type in `trigger.nodeType` and the item's
|
|
1249
|
+
* position in `trigger.item.index`. That position counts only elements that can
|
|
1250
|
+
* hold an intent — dividers and group headings are skipped, in every container
|
|
1251
|
+
* alike — because the index is the handle that points back at an edge's origin,
|
|
1252
|
+
* and an element incapable of producing an edge must not shift what the handle
|
|
1253
|
+
* addresses. `Tabs` items are plain strings without
|
|
1254
|
+
* `InteractiveProps` and contribute no transition; their panel content is
|
|
1255
|
+
* reached by normal node traversal.
|
|
1256
|
+
*
|
|
1257
|
+
* ## Resolution semantics
|
|
1258
|
+
*
|
|
1259
|
+
* - **`navigate`** is a page transition. Its trimmed target is matched, exactly
|
|
1260
|
+
* and case-sensitively, against **page `id` first and page `title` second**.
|
|
1261
|
+
*
|
|
1262
|
+
* Identifiers are how this DSL names a target: `opens` / `toggles` already
|
|
1263
|
+
* address a `Modal` or `Drawer` by its `id`, so a page addressed by `id` is
|
|
1264
|
+
* the same rule reaching the one container that had been left out — an author
|
|
1265
|
+
* learns one way to point at something, not two.
|
|
1266
|
+
*
|
|
1267
|
+
* The two are different kinds of name. An `id` is a stable identifier the
|
|
1268
|
+
* author opted into (`page "결제 내역" id=billing`); a `title` is display text
|
|
1269
|
+
* that is optional, need not be unique, and is expected to change as copy is
|
|
1270
|
+
* edited. Resolving identifiers first means rewording a heading cannot
|
|
1271
|
+
* silently turn every edge pointing at that screen into a dangling one. Title
|
|
1272
|
+
* matching stays as the fallback because it is how the corpus is written
|
|
1273
|
+
* today, and dropping it would strand every existing document.
|
|
1274
|
+
*
|
|
1275
|
+
* Consequences of that order, all deterministic:
|
|
1276
|
+
* - When one page's `id` equals another page's `title`, the `id` wins and the
|
|
1277
|
+
* title-named page is not reachable by that string. Identifiers always beat
|
|
1278
|
+
* labels; there is no positional tie-break to reason about.
|
|
1279
|
+
* - Within each namespace, duplicates resolve to the first page in document
|
|
1280
|
+
* order — the same rule the title namespace has always used.
|
|
1281
|
+
* - A target matching neither namespace is read by shape (see `isUrlTarget`).
|
|
1282
|
+
* A URL-shaped one — `navigate="/reset"`, `navigate="https://…"` — is an
|
|
1283
|
+
* {@link ScreenTransitionGraph.external | external} destination, not a
|
|
1284
|
+
* defect: the DSL documents `navigate` as a "URL or page" target, so the
|
|
1285
|
+
* author wrote something the DSL allows and there is no page to find.
|
|
1286
|
+
* Anything else is a name that should have matched a page and did not, and
|
|
1287
|
+
* only that is {@link ScreenTransitionGraph.dangling | dangling}. Counting
|
|
1288
|
+
* external links as dangling would report every correct outbound link as a
|
|
1289
|
+
* broken screen transition.
|
|
1290
|
+
* - **`opens` / `toggles`** target an overlay *within the source page*, not
|
|
1291
|
+
* another page, so their `to` is always `null`. They resolve when a `Modal`
|
|
1292
|
+
* or `Drawer` in the same page has `id === target` — the overlay containers
|
|
1293
|
+
* are the only nodes these two kinds can address. Being intra-page, they
|
|
1294
|
+
* never appear in `dangling`.
|
|
1295
|
+
* - **`action`** is an opaque handler id with no structural destination:
|
|
1296
|
+
* `to === null`, `resolved === false`, and it is not `dangling`.
|
|
1297
|
+
*
|
|
1298
|
+
* Item `href` is a raw anchor, not a declared `navigate` intent, and is
|
|
1299
|
+
* excluded — consistent with node-level extraction. The HTML renderer draws the
|
|
1300
|
+
* same line: it emits the authored `href` and the declared intent side by side
|
|
1301
|
+
* as `data-navigate` / `data-opens` / `data-toggles` / `data-action`, so every
|
|
1302
|
+
* edge derived here has a counterpart a consumer of the markup can act on.
|
|
1303
|
+
*/
|
|
1304
|
+
|
|
1305
|
+
/**
|
|
1306
|
+
* Derive the screen-transition graph for a whole document.
|
|
1307
|
+
*/
|
|
1308
|
+
declare function extractScreenTransitions(doc: WireframeDocument): ScreenTransitionGraph;
|
|
1309
|
+
|
|
1310
|
+
/**
|
|
1311
|
+
* Deterministic source-anchor path scheme.
|
|
1312
|
+
*
|
|
1313
|
+
* A single implementation of "which node sits at which path" that BOTH the
|
|
1314
|
+
* renderer's anchor injection and the extract module's anchor index share, so
|
|
1315
|
+
* the DOM attributes and the AST index can never drift apart.
|
|
1316
|
+
*
|
|
1317
|
+
* ## Path scheme
|
|
1318
|
+
*
|
|
1319
|
+
* A path is a dot-joined chain of zero-based indices whose first segment is the
|
|
1320
|
+
* page's index in the document (`0`, `1`, …) and whose remaining segments are
|
|
1321
|
+
* child ordinals within {@link anchorChildNodes}. Example: page `0`, its 3rd
|
|
1322
|
+
* child's 2nd child → `0.2.1`.
|
|
1323
|
+
*
|
|
1324
|
+
* ## Anchor children
|
|
1325
|
+
*
|
|
1326
|
+
* Only the structural container types whose HTML renderer dispatches their
|
|
1327
|
+
* `AnyNode[]` `children` back through `renderNode` are descended into. This is
|
|
1328
|
+
* the exact set that receives an anchor attribute during rendering; leaf and
|
|
1329
|
+
* custom-traversal nodes (Table cells, List items, Nav/Tabs/Breadcrumb entries,
|
|
1330
|
+
* Annotation items) are not part of the anchor tree. Keeping the walk in lock
|
|
1331
|
+
* step with `renderNode` dispatch is what makes the anchor count in the HTML
|
|
1332
|
+
* equal to the size of the index for any document.
|
|
1333
|
+
*/
|
|
1334
|
+
|
|
1335
|
+
/** DOM attribute carrying a node's page-relative index path. */
|
|
1336
|
+
declare const ANCHOR_PATH_ATTR = "data-wf-path";
|
|
1337
|
+
/** DOM attribute carrying a node's source offset range (`start-end`). */
|
|
1338
|
+
declare const ANCHOR_LOC_ATTR = "data-wf-loc";
|
|
1339
|
+
|
|
1340
|
+
/**
|
|
1341
|
+
* DOM ↔ AST ↔ source mapping.
|
|
1342
|
+
*
|
|
1343
|
+
* The rendered HTML carries `data-wf-path` / `data-wf-loc` anchors (opt-in via
|
|
1344
|
+
* the renderer's `sourceAnchors` option). This module is the inverse: it turns
|
|
1345
|
+
* an anchor path back into its AST node and its DSL source slice, so a host
|
|
1346
|
+
* (dashboard editor) can implement "click a rendered element → select its
|
|
1347
|
+
* source" and "render a DOM-tree panel" without re-parsing.
|
|
1348
|
+
*
|
|
1349
|
+
* The path scheme is shared with the renderer (`ast/anchor-path`), so an index
|
|
1350
|
+
* built here is guaranteed to line up with the anchors the renderer emitted.
|
|
1351
|
+
*/
|
|
1352
|
+
|
|
1353
|
+
/** An entry in the anchor index: a node, its path, and its source location. */
|
|
1354
|
+
interface AnchorEntry {
|
|
1355
|
+
path: string;
|
|
1356
|
+
node: AnyNode;
|
|
1357
|
+
loc?: SourceLocation;
|
|
1358
|
+
}
|
|
1359
|
+
/** A slice of the original DSL source, both raw and trimmed. */
|
|
1360
|
+
interface SourceSlice {
|
|
1361
|
+
/** The exact substring spanned by the node/page location. */
|
|
1362
|
+
text: string;
|
|
1363
|
+
/** `text` with surrounding whitespace removed. */
|
|
1364
|
+
trimmed: string;
|
|
1365
|
+
loc: SourceLocation;
|
|
1366
|
+
}
|
|
1367
|
+
/** A node in the panel-ready DOM tree, mirroring the anchored render tree. */
|
|
1368
|
+
interface DomTreeNode {
|
|
1369
|
+
path: string;
|
|
1370
|
+
nodeType: NodeType;
|
|
1371
|
+
category?: ComponentCategory;
|
|
1372
|
+
label?: string;
|
|
1373
|
+
children: DomTreeNode[];
|
|
1374
|
+
}
|
|
1375
|
+
/**
|
|
1376
|
+
* Build a `path → { node, loc }` index for every anchored node in the document.
|
|
1377
|
+
* The keys are exactly the `data-wf-path` values the renderer emits.
|
|
1378
|
+
*/
|
|
1379
|
+
declare function buildAnchorIndex(doc: WireframeDocument, pageIndexBase?: number): Map<string, AnchorEntry>;
|
|
1380
|
+
/**
|
|
1381
|
+
* Resolve an anchor path (a `data-wf-path` value) to its AST node, or
|
|
1382
|
+
* `undefined` if the path is malformed or out of range.
|
|
1383
|
+
*/
|
|
1384
|
+
declare function resolveAnchor(doc: WireframeDocument, path: string, pageIndexBase?: number): AnyNode | undefined;
|
|
1385
|
+
/**
|
|
1386
|
+
* The DSL source slice for a page, by its document index. `undefined` if the
|
|
1387
|
+
* index is out of range or the page carries no location (unparsed input).
|
|
1388
|
+
*/
|
|
1389
|
+
declare function getPageSource(source: string, doc: WireframeDocument, pageIndex: number): SourceSlice | undefined;
|
|
1390
|
+
/**
|
|
1391
|
+
* The DSL source slice for any anchored node, by its path. `undefined` if the
|
|
1392
|
+
* path does not resolve or the node carries no location.
|
|
1393
|
+
*/
|
|
1394
|
+
declare function getNodeSource(source: string, doc: WireframeDocument, path: string, pageIndexBase?: number): SourceSlice | undefined;
|
|
1395
|
+
/**
|
|
1396
|
+
* Build a panel-ready DOM tree — one root per page — mirroring the anchored
|
|
1397
|
+
* render tree. Each node carries its anchor path so a host can cross-highlight
|
|
1398
|
+
* between the tree panel and the rendered canvas.
|
|
1399
|
+
*/
|
|
1400
|
+
declare function buildDomTree(doc: WireframeDocument, pageIndexBase?: number): DomTreeNode[];
|
|
1401
|
+
|
|
1402
|
+
export { ANCHOR_LOC_ATTR, ANCHOR_PATH_ATTR, type AccessibilityMetrics, AccordionNode, AlertNode, type AnalysisOptions, type AnalysisResult, type AnchorEntry, AnyNode, type AttributeChange, AvatarNode, BadgeNode, BreadcrumbNode, ButtonNode, CardNode, CheckboxNode, ColNode, 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, type JsonExportResult, type JsonNode, type LayoutAnalysis, LayoutDefinitionNode, LayoutNode, LeafNode, LinkNode, ListNode, MainNode, ModalNode, NavNode, NavigationNode, type NodeChange, type NodePredicate, NodeType, OverlayNode, PageNode, PlaceholderNode, PopoverNode, type PreviewWrapperOptions, ProgressNode, REPEAT_EXPANSION_BUDGET, RadioNode, RepeatBudgetError, RowNode, ScreenFields, ScreenTransitionGraph, SectionNode, SelectNode, SidebarNode, SliderNode, SlotNode, SourceLocation, type SourceSlice, SpinnerNode, SwitchNode, TableNode, TabsNode, TextContentNode, TextNode, TextareaNode, TitleNode, ToastNode, TooltipNode, type TreeMetrics, type ValidationError, type ValidationOptions, type ValidationResult, type ViewportSize, type WalkCallback, WireframeDocument, analyze, areIdentical, buildAnchorIndex, buildDomTree, calculateViewportScale, cloneNode, collectParameterReferences, contains, countNodes, 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, 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, isValidAst, isValidDevicePreset, mapNodes, parameterReferenceName, parseViewportString, printWireframe, resetFigmaIdCounter, resolveAnchor, resolveViewport, validate, variantScope, walk, walkDocument, wrapInPreviewContainer };
|