@wireweave/core 3.1.0-beta.7 → 3.1.0-beta.9

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.d.ts CHANGED
@@ -1,5 +1,5 @@
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, bd as WireframeDocument, aK as SourceLocation, aR as StateDeclaration, aS as StateGuard, a6 as InteractionEffect, a5 as InputType } from './types-BphXi5Tn.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 WidthValue } from './types-BphXi5Tn.js';
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
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';
@@ -333,6 +333,167 @@ declare class RepeatBudgetError extends Error {
333
333
  */
334
334
  declare function expandRepeats(document: WireframeDocument): WireframeDocument;
335
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
+
336
497
  /**
337
498
  * Node/document-level canonical `.wf` printing.
338
499
  *
@@ -1747,4 +1908,4 @@ declare function compileApp(document: AppDocument, options?: CompileAppOptions):
1747
1908
  */
1748
1909
  declare function linkAndCompileApp(manifest: AppManifest, modules: readonly AppModuleInput[], options?: CompileAppOptions): AppCompileResult;
1749
1910
 
1750
- 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, exportToFigma, exportToFigmaString, exportToJson, exportToJsonString, extractAllScreenFields, extractScreenFields, extractScreenTransitions, 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, walk, walkDocument, wrapInPreviewContainer };
1911
+ 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 };
package/dist/index.js CHANGED
@@ -432,6 +432,153 @@ function expandRepeats(document) {
432
432
  };
433
433
  }
434
434
 
435
+ // src/ast/filter-variant-scope.ts
436
+ function variantScope(node) {
437
+ const declared = node.when;
438
+ if (declared === void 0) return void 0;
439
+ const raw = Array.isArray(declared) ? declared : [declared];
440
+ const seen = /* @__PURE__ */ new Set();
441
+ const names = [];
442
+ for (const item of raw) {
443
+ if (typeof item !== "string") continue;
444
+ const name = item.trim();
445
+ if (name.length === 0 || seen.has(name)) continue;
446
+ seen.add(name);
447
+ names.push(name);
448
+ }
449
+ return names;
450
+ }
451
+ function childList(value) {
452
+ const children = value?.children;
453
+ return Array.isArray(children) ? children : void 0;
454
+ }
455
+ function asNode(value) {
456
+ return value !== null && typeof value === "object" && "type" in value ? value : void 0;
457
+ }
458
+ function filterChildList(children, variant) {
459
+ return children.flatMap((child) => {
460
+ const node = asNode(child);
461
+ if (node === void 0) return [child];
462
+ const kept = filterNode(node, variant);
463
+ return kept === void 0 ? [] : [kept];
464
+ });
465
+ }
466
+ function containsScope(node) {
467
+ if (node.when !== void 0) return true;
468
+ for (const child of childList(node) ?? []) {
469
+ const nested = asNode(child);
470
+ if (nested !== void 0 && containsScope(nested)) return true;
471
+ }
472
+ const fills = node.fills;
473
+ if (Array.isArray(fills)) {
474
+ for (const fill of fills) {
475
+ for (const child of childList(fill) ?? []) {
476
+ const nested = asNode(child);
477
+ if (nested !== void 0 && containsScope(nested)) return true;
478
+ }
479
+ }
480
+ }
481
+ return false;
482
+ }
483
+ function filterNode(node, variant) {
484
+ const scope = variantScope(node);
485
+ if (scope !== void 0) {
486
+ if (variant === void 0 || !scope.includes(variant)) return void 0;
487
+ }
488
+ const nested = containsScope(node);
489
+ if (scope === void 0 && !nested) return node;
490
+ const result = {};
491
+ for (const [key, value] of Object.entries(node)) {
492
+ if (key === "when") continue;
493
+ result[key] = value;
494
+ }
495
+ const children = childList(node);
496
+ if (children !== void 0) {
497
+ result.children = filterChildList(children, variant);
498
+ }
499
+ const fills = node.fills;
500
+ if (Array.isArray(fills)) {
501
+ result.fills = fills.map((fill) => {
502
+ const fillChildren = childList(fill);
503
+ if (fillChildren === void 0) return fill;
504
+ return {
505
+ ...fill,
506
+ children: filterChildList(fillChildren, variant)
507
+ };
508
+ });
509
+ }
510
+ return result;
511
+ }
512
+ function filterVariantScope(children, variant) {
513
+ if (!children.some((child) => containsScope(child))) return children;
514
+ return children.flatMap((child) => {
515
+ const kept = filterNode(child, variant);
516
+ return kept === void 0 ? [] : [kept];
517
+ });
518
+ }
519
+ function filterUnscopedPages(document) {
520
+ let changed = false;
521
+ const children = document.children.map((child) => {
522
+ if (child.type !== "Page" || child.variant !== void 0) return child;
523
+ const filtered = filterVariantScope(child.children, void 0);
524
+ if (filtered === child.children) return child;
525
+ changed = true;
526
+ return { ...child, children: filtered };
527
+ });
528
+ return changed ? { ...document, children } : document;
529
+ }
530
+
531
+ // src/ast/expand-variants.ts
532
+ function cloneNode3(value) {
533
+ if (Array.isArray(value)) return value.map(cloneNode3);
534
+ if (value === null || typeof value !== "object") return value;
535
+ const source = value;
536
+ const result = {};
537
+ for (const [key, item] of Object.entries(source)) {
538
+ result[key] = key === "loc" ? item : cloneNode3(item);
539
+ }
540
+ return result;
541
+ }
542
+ function variantNames(page) {
543
+ const declared = page.variants;
544
+ if (!Array.isArray(declared)) return [];
545
+ const seen = /* @__PURE__ */ new Set();
546
+ const names = [];
547
+ for (const raw of declared) {
548
+ if (typeof raw !== "string") continue;
549
+ const name = raw.trim();
550
+ if (name.length === 0 || seen.has(name)) continue;
551
+ seen.add(name);
552
+ names.push(name);
553
+ }
554
+ return names;
555
+ }
556
+ function hasVariants(document) {
557
+ return document.children.some((child) => child.type === "Page" && variantNames(child).length > 0);
558
+ }
559
+ function expandVariants(document) {
560
+ if (!hasVariants(document)) return filterUnscopedPages(document);
561
+ return {
562
+ ...document,
563
+ children: document.children.flatMap((child) => {
564
+ if (child.type !== "Page") return [child];
565
+ const names = variantNames(child);
566
+ if (names.length === 0) {
567
+ const filtered = filterVariantScope(child.children, void 0);
568
+ return [filtered === child.children ? child : { ...child, children: filtered }];
569
+ }
570
+ return names.map((variant, position) => {
571
+ const clone = cloneNode3(child);
572
+ delete clone.variants;
573
+ clone.variant = variant;
574
+ if (position > 0) delete clone.states;
575
+ clone.children = filterVariantScope(clone.children, variant);
576
+ return clone;
577
+ });
578
+ })
579
+ };
580
+ }
581
+
435
582
  // src/parser/generated-parser.js
436
583
  var peg$SyntaxError = class extends SyntaxError {
437
584
  constructor(message, expected, found, location) {
@@ -13118,6 +13265,16 @@ var ATTRIBUTE_SPECS = [
13118
13265
  type: "object[]",
13119
13266
  description: "Typed application state declarations owned by a page or shared layout"
13120
13267
  },
13268
+ {
13269
+ name: "variants",
13270
+ type: "string[]",
13271
+ description: "Named state variants of this page \u2014 each one renders the page again as a screen of its own"
13272
+ },
13273
+ {
13274
+ name: "when",
13275
+ type: "string[]",
13276
+ description: "Variant boards this element is drawn on \u2014 when=loading, or when=[loading, empty] for both"
13277
+ },
13121
13278
  {
13122
13279
  name: "id",
13123
13280
  type: "string",
@@ -13163,6 +13320,13 @@ var BOX_ATTRIBUTES = [
13163
13320
  // Guarded runtime outcomes
13164
13321
  "visibleWhen",
13165
13322
  "enabledWhen",
13323
+ // Build-time variant scope. Listed beside the guards because it reads like
13324
+ // them and is deliberately not one of them: a guard leaves the element in the
13325
+ // markup for the runtime to toggle, `when` decides whether the element is in
13326
+ // that board's markup at all. Every element takes it for the same reason
13327
+ // every element takes a guard — which boards a piece of a screen belongs to
13328
+ // is a property of the piece, not of what kind of piece it is.
13329
+ "when",
13166
13330
  // Spacing
13167
13331
  "p",
13168
13332
  "px",
@@ -13225,7 +13389,15 @@ var COMPONENT_METADATA = {
13225
13389
  // board that path renders *into* — nothing emits the attribute for it and
13226
13390
  // nothing would toggle it, so declaring it would let an author write a
13227
13391
  // guard on a page, pass `validate()`, and have the value silently dropped.
13228
- ...BOX_ATTRIBUTES.filter((name) => name !== "visibleWhen" && name !== "enabledWhen"),
13392
+ // `when` is filtered out alongside the guards, for a reason of its own: a
13393
+ // page *is* a board, so scoping one to a variant would be a board saying
13394
+ // which board it is drawn on. The axis a page declares is `variants`, and
13395
+ // `when` names positions along it — the two sit at different levels and a
13396
+ // page carrying both would be asking `expandVariants` to filter a page
13397
+ // against a name it is itself the source of.
13398
+ ...BOX_ATTRIBUTES.filter(
13399
+ (name) => name !== "visibleWhen" && name !== "enabledWhen" && name !== "when"
13400
+ ),
13229
13401
  ...CONTAINER_ATTRIBUTES,
13230
13402
  "id",
13231
13403
  "title",
@@ -13235,7 +13407,8 @@ var COMPONENT_METADATA = {
13235
13407
  "device",
13236
13408
  "centered",
13237
13409
  "uses",
13238
- "states"
13410
+ "states",
13411
+ "variants"
13239
13412
  ],
13240
13413
  hasChildren: true,
13241
13414
  description: "Root container for a wireframe page. Multiple pages in one .wf file lay out side-by-side on a canvas; use at(x, y) for explicit placement, or omit for auto-flow. Give it uses=<layout> to draw it inside a shared layout instead of restating the shell."
@@ -13910,6 +14083,8 @@ function pageTitle(page) {
13910
14083
  const title = page.title?.trim();
13911
14084
  return title !== void 0 && title.length > 0 ? title : void 0;
13912
14085
  }
14086
+ var VARIANT_SEPARATOR = "#";
14087
+ var variantName = (name, variant) => `${name}${VARIANT_SEPARATOR}${variant}`;
13913
14088
  function hasSlot(layout) {
13914
14089
  let found = false;
13915
14090
  for (const child of layout.children) {
@@ -13941,7 +14116,10 @@ function resolveShell(page, layouts) {
13941
14116
  function buildSiteModel(doc) {
13942
14117
  const pages = documentPages(doc);
13943
14118
  const layouts = layoutsByName(doc);
13944
- const screens = pages.map((page, index) => ({ index, page }));
14119
+ const screens = pages.map((page, index) => {
14120
+ const variant = page.variant?.trim();
14121
+ return variant !== void 0 && variant.length > 0 ? { index, page, variant } : { index, page };
14122
+ });
13945
14123
  const shells = [];
13946
14124
  const shellByName = /* @__PURE__ */ new Map();
13947
14125
  screens.forEach((screen) => {
@@ -13975,7 +14153,26 @@ function buildSiteModel(doc) {
13975
14153
  }
13976
14154
  }
13977
14155
  for (const screen of screens) {
13978
- const declared = [pageId(screen.page), pageTitle(screen.page)];
14156
+ if (screen.variant === void 0) continue;
14157
+ for (const declared of [pageId(screen.page), pageTitle(screen.page)]) {
14158
+ if (declared === void 0) continue;
14159
+ const owner = names.get(declared);
14160
+ if (owner === void 0) continue;
14161
+ const winner = screens[owner].page;
14162
+ if (pageId(winner) !== pageId(screen.page) || pageTitle(winner) !== pageTitle(screen.page)) {
14163
+ continue;
14164
+ }
14165
+ const qualified = variantName(declared, screen.variant);
14166
+ if (!names.has(qualified)) names.set(qualified, screen.index);
14167
+ }
14168
+ }
14169
+ for (const screen of screens) {
14170
+ const bare = [pageId(screen.page), pageTitle(screen.page)];
14171
+ const variant = screen.variant;
14172
+ const declared = variant === void 0 ? bare : [
14173
+ ...bare.map((name) => name === void 0 ? void 0 : variantName(name, variant)),
14174
+ ...bare
14175
+ ];
13979
14176
  screen.name = declared.find(
13980
14177
  (name) => name !== void 0 && names.get(name) === screen.index
13981
14178
  );
@@ -62527,7 +62724,8 @@ function wrapBoard(pageHtml, placed, prefix) {
62527
62724
  const { x, y, w, h, page } = placed;
62528
62725
  const positionStyle = `position: absolute; left: ${x}px; top: ${y}px; width: ${w}px; height: ${h}px;`;
62529
62726
  const titleAttr = page.title ? ` data-page-title="${escapeAttr(page.title)}"` : "";
62530
- const dataAttrs = ` data-page-x="${x}" data-page-y="${y}" data-page-w="${w}" data-page-h="${h}"${titleAttr}`;
62727
+ const variantAttr = page.variant ? ` data-wf-variant="${escapeAttr(page.variant)}"` : "";
62728
+ const dataAttrs = ` data-page-x="${x}" data-page-y="${y}" data-page-w="${w}" data-page-h="${h}"${titleAttr}${variantAttr}`;
62531
62729
  return `<div class="${prefix}-canvas-board" style="${positionStyle}"${dataAttrs}>
62532
62730
  ${pageHtml}
62533
62731
  </div>`;
@@ -63114,6 +63312,7 @@ function renderHostedScreen(screen, shell, make, prefix) {
63114
63312
  const marks = attrs([
63115
63313
  ["data-screen", String(screen.index)],
63116
63314
  ["data-screen-name", screen.name],
63315
+ ["data-wf-variant", screen.variant],
63117
63316
  [ID_SCOPE_ATTR, scope],
63118
63317
  ["data-wf-viewport-conflict", conflict]
63119
63318
  ]);
@@ -63127,6 +63326,7 @@ function renderStandaloneScreen(screen, make, prefix) {
63127
63326
  const marks = attrs([
63128
63327
  ["data-screen", String(screen.index)],
63129
63328
  ["data-screen-name", screen.name],
63329
+ ["data-wf-variant", screen.variant],
63130
63330
  [ID_SCOPE_ATTR, scope],
63131
63331
  ["data-wf-uses-unresolved", screen.miss?.uses],
63132
63332
  ["data-wf-uses-reason", screen.miss?.reason]
@@ -63195,7 +63395,7 @@ function compactRuntimeInteractions(model, interactions) {
63195
63395
  }
63196
63396
  function renderSite(document, options = {}) {
63197
63397
  const prefix = options.classPrefix ?? DEFAULT_PREFIX2;
63198
- document = expandRepeats(document);
63398
+ document = expandRepeats(expandVariants(document));
63199
63399
  const model = buildSiteModel(document);
63200
63400
  const interactionModel = collectInteractions(document);
63201
63401
  const make = (idScope) => new HtmlRenderer({
@@ -63264,6 +63464,7 @@ ${runtime}
63264
63464
 
63265
63465
  // src/renderer/index.ts
63266
63466
  function render(document, options = {}) {
63467
+ document = expandVariants(document);
63267
63468
  const isMultiPage = documentPages(document).length > 1;
63268
63469
  if (isMultiPage) {
63269
63470
  const result = renderCanvas(document, options);
@@ -63273,6 +63474,7 @@ function render(document, options = {}) {
63273
63474
  return renderer.render(document);
63274
63475
  }
63275
63476
  function renderToHtml(document, options = {}) {
63477
+ document = expandVariants(document);
63276
63478
  const { html, css } = render(document, options);
63277
63479
  const prefix = options.classPrefix ?? "wf";
63278
63480
  const isMultiPage = documentPages(document).length > 1;
@@ -63314,6 +63516,7 @@ ${html}
63314
63516
  </html>`;
63315
63517
  }
63316
63518
  function renderToSvg(document, options = {}) {
63519
+ document = expandVariants(document);
63317
63520
  const isMultiPage = documentPages(document).length > 1;
63318
63521
  let width = options.width ?? 800;
63319
63522
  let height = options.height ?? 600;
@@ -63426,6 +63629,63 @@ function checkDuplicateDeclarations(ast, addError) {
63426
63629
  }
63427
63630
  return true;
63428
63631
  }
63632
+ function checkVariantScopes(ast, addError) {
63633
+ const children = ast.children ?? [];
63634
+ for (let index = 0; index < children.length; index++) {
63635
+ const page = children[index];
63636
+ if (page?.type !== "Page") continue;
63637
+ const declared = new Set(
63638
+ (Array.isArray(page.variants) ? page.variants : []).filter((name) => typeof name === "string").map((name) => name.trim()).filter((name) => name.length > 0)
63639
+ );
63640
+ const visit = (node, path, inherited) => {
63641
+ const scope = variantScope(node);
63642
+ let reachable = inherited;
63643
+ if (scope !== void 0) {
63644
+ const unknown = scope.filter((name) => !declared.has(name));
63645
+ if (unknown.length > 0) {
63646
+ const message = declared.size === 0 ? `Unknown variant ${unknown.map((n) => `"${n}"`).join(", ")} in when= \u2014 this page declares no variants=, so the element is drawn on no board` : `Unknown variant ${unknown.map((n) => `"${n}"`).join(", ")} in when= \u2014 this page declares [${[...declared].join(", ")}]`;
63647
+ if (!addError({
63648
+ message,
63649
+ path,
63650
+ nodeType: node.type,
63651
+ attribute: "when",
63652
+ location: node.loc ? { line: node.loc.start.line, column: node.loc.start.column } : void 0
63653
+ })) {
63654
+ return false;
63655
+ }
63656
+ }
63657
+ const named = new Set(scope.filter((name) => declared.has(name)));
63658
+ reachable = inherited === void 0 ? named : new Set([...named].filter((n) => inherited.has(n)));
63659
+ if (unknown.length === 0 && inherited !== void 0 && reachable.size === 0) {
63660
+ if (!addError({
63661
+ message: `Contradictory when= [${scope.join(", ")}] \u2014 an enclosing element is scoped to [${[...inherited].join(", ")}], so no board draws both and this element is never rendered`,
63662
+ path,
63663
+ nodeType: node.type,
63664
+ attribute: "when",
63665
+ location: node.loc ? { line: node.loc.start.line, column: node.loc.start.column } : void 0
63666
+ })) {
63667
+ return false;
63668
+ }
63669
+ }
63670
+ }
63671
+ const kids = "children" in node && Array.isArray(node.children) ? node.children : [];
63672
+ for (let i = 0; i < kids.length; i++) {
63673
+ const child = kids[i];
63674
+ if (child && typeof child === "object" && "type" in child) {
63675
+ if (!visit(child, `${path}.children[${i}]`, reachable)) return false;
63676
+ }
63677
+ }
63678
+ return true;
63679
+ };
63680
+ for (let i = 0; i < page.children.length; i++) {
63681
+ const child = page.children[i];
63682
+ if (child && typeof child === "object" && "type" in child) {
63683
+ if (!visit(child, `pages[${index}].children[${i}]`, void 0)) return false;
63684
+ }
63685
+ }
63686
+ }
63687
+ return true;
63688
+ }
63429
63689
  function checkDuplicateElementIds(ast, addError) {
63430
63690
  const CONTEXT_OF = {
63431
63691
  Page: "page",
@@ -63706,6 +63966,7 @@ function validate(ast, options = {}) {
63706
63966
  }
63707
63967
  if (shouldContinue) shouldContinue = checkComponentContracts(ast, addError);
63708
63968
  if (shouldContinue) shouldContinue = checkDuplicateDeclarations(ast, addError);
63969
+ if (shouldContinue) shouldContinue = checkVariantScopes(ast, addError);
63709
63970
  if (shouldContinue) checkDuplicateElementIds(ast, addError);
63710
63971
  const valid = errors.length === 0;
63711
63972
  return {
@@ -65727,6 +65988,7 @@ export {
65727
65988
  documentDefinitions,
65728
65989
  documentPages,
65729
65990
  expandRepeats,
65991
+ expandVariants,
65730
65992
  exportToFigma,
65731
65993
  exportToFigmaString,
65732
65994
  exportToJson,
@@ -65734,6 +65996,8 @@ export {
65734
65996
  extractAllScreenFields,
65735
65997
  extractScreenFields,
65736
65998
  extractScreenTransitions,
65999
+ filterUnscopedPages,
66000
+ filterVariantScope,
65737
66001
  find,
65738
66002
  findAll,
65739
66003
  findByType,
@@ -65846,6 +66110,7 @@ export {
65846
66110
  resolveViewport,
65847
66111
  tryParse,
65848
66112
  validate,
66113
+ variantScope,
65849
66114
  walk,
65850
66115
  walkDocument,
65851
66116
  wrapInPreviewContainer
package/dist/parser.d.cts CHANGED
@@ -1,4 +1,4 @@
1
- import { aK as SourceLocation, bd as WireframeDocument } from './types-BphXi5Tn.cjs';
1
+ import { aK as SourceLocation, be as WireframeDocument } from './types-vhPCZpAW.cjs';
2
2
 
3
3
  /**
4
4
  * Parser module for wireweave
package/dist/parser.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- import { aK as SourceLocation, bd as WireframeDocument } from './types-BphXi5Tn.js';
1
+ import { aK as SourceLocation, be as WireframeDocument } from './types-vhPCZpAW.js';
2
2
 
3
3
  /**
4
4
  * Parser module for wireweave