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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.cjs CHANGED
@@ -75,6 +75,7 @@ __export(src_exports, {
75
75
  documentDefinitions: () => documentDefinitions,
76
76
  documentPages: () => documentPages,
77
77
  expandRepeats: () => expandRepeats,
78
+ expandVariants: () => expandVariants,
78
79
  exportToFigma: () => exportToFigma,
79
80
  exportToFigmaString: () => exportToFigmaString,
80
81
  exportToJson: () => exportToJson,
@@ -634,6 +635,53 @@ function expandRepeats(document) {
634
635
  };
635
636
  }
636
637
 
638
+ // src/ast/expand-variants.ts
639
+ function cloneNode3(value) {
640
+ if (Array.isArray(value)) return value.map(cloneNode3);
641
+ if (value === null || typeof value !== "object") return value;
642
+ const source = value;
643
+ const result = {};
644
+ for (const [key, item] of Object.entries(source)) {
645
+ result[key] = key === "loc" ? item : cloneNode3(item);
646
+ }
647
+ return result;
648
+ }
649
+ function variantNames(page) {
650
+ const declared = page.variants;
651
+ if (!Array.isArray(declared)) return [];
652
+ const seen = /* @__PURE__ */ new Set();
653
+ const names = [];
654
+ for (const raw of declared) {
655
+ if (typeof raw !== "string") continue;
656
+ const name = raw.trim();
657
+ if (name.length === 0 || seen.has(name)) continue;
658
+ seen.add(name);
659
+ names.push(name);
660
+ }
661
+ return names;
662
+ }
663
+ function hasVariants(document) {
664
+ return document.children.some((child) => child.type === "Page" && variantNames(child).length > 0);
665
+ }
666
+ function expandVariants(document) {
667
+ if (!hasVariants(document)) return document;
668
+ return {
669
+ ...document,
670
+ children: document.children.flatMap((child) => {
671
+ if (child.type !== "Page") return [child];
672
+ const names = variantNames(child);
673
+ if (names.length === 0) return [child];
674
+ return names.map((variant, position) => {
675
+ const clone = cloneNode3(child);
676
+ delete clone.variants;
677
+ clone.variant = variant;
678
+ if (position > 0) delete clone.states;
679
+ return clone;
680
+ });
681
+ })
682
+ };
683
+ }
684
+
637
685
  // src/parser/generated-parser.js
638
686
  var peg$SyntaxError = class extends SyntaxError {
639
687
  constructor(message, expected, found, location) {
@@ -13320,6 +13368,11 @@ var ATTRIBUTE_SPECS = [
13320
13368
  type: "object[]",
13321
13369
  description: "Typed application state declarations owned by a page or shared layout"
13322
13370
  },
13371
+ {
13372
+ name: "variants",
13373
+ type: "string[]",
13374
+ description: "Named state variants of this page \u2014 each one renders the page again as a screen of its own"
13375
+ },
13323
13376
  {
13324
13377
  name: "id",
13325
13378
  type: "string",
@@ -13437,7 +13490,8 @@ var COMPONENT_METADATA = {
13437
13490
  "device",
13438
13491
  "centered",
13439
13492
  "uses",
13440
- "states"
13493
+ "states",
13494
+ "variants"
13441
13495
  ],
13442
13496
  hasChildren: true,
13443
13497
  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."
@@ -14112,6 +14166,8 @@ function pageTitle(page) {
14112
14166
  const title = page.title?.trim();
14113
14167
  return title !== void 0 && title.length > 0 ? title : void 0;
14114
14168
  }
14169
+ var VARIANT_SEPARATOR = "#";
14170
+ var variantName = (name, variant) => `${name}${VARIANT_SEPARATOR}${variant}`;
14115
14171
  function hasSlot(layout) {
14116
14172
  let found = false;
14117
14173
  for (const child of layout.children) {
@@ -14143,7 +14199,10 @@ function resolveShell(page, layouts) {
14143
14199
  function buildSiteModel(doc) {
14144
14200
  const pages = documentPages(doc);
14145
14201
  const layouts = layoutsByName(doc);
14146
- const screens = pages.map((page, index) => ({ index, page }));
14202
+ const screens = pages.map((page, index) => {
14203
+ const variant = page.variant?.trim();
14204
+ return variant !== void 0 && variant.length > 0 ? { index, page, variant } : { index, page };
14205
+ });
14147
14206
  const shells = [];
14148
14207
  const shellByName = /* @__PURE__ */ new Map();
14149
14208
  screens.forEach((screen) => {
@@ -14177,7 +14236,26 @@ function buildSiteModel(doc) {
14177
14236
  }
14178
14237
  }
14179
14238
  for (const screen of screens) {
14180
- const declared = [pageId(screen.page), pageTitle(screen.page)];
14239
+ if (screen.variant === void 0) continue;
14240
+ for (const declared of [pageId(screen.page), pageTitle(screen.page)]) {
14241
+ if (declared === void 0) continue;
14242
+ const owner = names.get(declared);
14243
+ if (owner === void 0) continue;
14244
+ const winner = screens[owner].page;
14245
+ if (pageId(winner) !== pageId(screen.page) || pageTitle(winner) !== pageTitle(screen.page)) {
14246
+ continue;
14247
+ }
14248
+ const qualified = variantName(declared, screen.variant);
14249
+ if (!names.has(qualified)) names.set(qualified, screen.index);
14250
+ }
14251
+ }
14252
+ for (const screen of screens) {
14253
+ const bare = [pageId(screen.page), pageTitle(screen.page)];
14254
+ const variant = screen.variant;
14255
+ const declared = variant === void 0 ? bare : [
14256
+ ...bare.map((name) => name === void 0 ? void 0 : variantName(name, variant)),
14257
+ ...bare
14258
+ ];
14181
14259
  screen.name = declared.find(
14182
14260
  (name) => name !== void 0 && names.get(name) === screen.index
14183
14261
  );
@@ -62729,7 +62807,8 @@ function wrapBoard(pageHtml, placed, prefix) {
62729
62807
  const { x, y, w, h, page } = placed;
62730
62808
  const positionStyle = `position: absolute; left: ${x}px; top: ${y}px; width: ${w}px; height: ${h}px;`;
62731
62809
  const titleAttr = page.title ? ` data-page-title="${escapeAttr(page.title)}"` : "";
62732
- const dataAttrs = ` data-page-x="${x}" data-page-y="${y}" data-page-w="${w}" data-page-h="${h}"${titleAttr}`;
62810
+ const variantAttr = page.variant ? ` data-wf-variant="${escapeAttr(page.variant)}"` : "";
62811
+ const dataAttrs = ` data-page-x="${x}" data-page-y="${y}" data-page-w="${w}" data-page-h="${h}"${titleAttr}${variantAttr}`;
62733
62812
  return `<div class="${prefix}-canvas-board" style="${positionStyle}"${dataAttrs}>
62734
62813
  ${pageHtml}
62735
62814
  </div>`;
@@ -63316,6 +63395,7 @@ function renderHostedScreen(screen, shell, make, prefix) {
63316
63395
  const marks = attrs([
63317
63396
  ["data-screen", String(screen.index)],
63318
63397
  ["data-screen-name", screen.name],
63398
+ ["data-wf-variant", screen.variant],
63319
63399
  [ID_SCOPE_ATTR, scope],
63320
63400
  ["data-wf-viewport-conflict", conflict]
63321
63401
  ]);
@@ -63329,6 +63409,7 @@ function renderStandaloneScreen(screen, make, prefix) {
63329
63409
  const marks = attrs([
63330
63410
  ["data-screen", String(screen.index)],
63331
63411
  ["data-screen-name", screen.name],
63412
+ ["data-wf-variant", screen.variant],
63332
63413
  [ID_SCOPE_ATTR, scope],
63333
63414
  ["data-wf-uses-unresolved", screen.miss?.uses],
63334
63415
  ["data-wf-uses-reason", screen.miss?.reason]
@@ -63397,7 +63478,7 @@ function compactRuntimeInteractions(model, interactions) {
63397
63478
  }
63398
63479
  function renderSite(document, options = {}) {
63399
63480
  const prefix = options.classPrefix ?? DEFAULT_PREFIX2;
63400
- document = expandRepeats(document);
63481
+ document = expandRepeats(expandVariants(document));
63401
63482
  const model = buildSiteModel(document);
63402
63483
  const interactionModel = collectInteractions(document);
63403
63484
  const make = (idScope) => new HtmlRenderer({
@@ -63466,6 +63547,7 @@ ${runtime}
63466
63547
 
63467
63548
  // src/renderer/index.ts
63468
63549
  function render(document, options = {}) {
63550
+ document = expandVariants(document);
63469
63551
  const isMultiPage = documentPages(document).length > 1;
63470
63552
  if (isMultiPage) {
63471
63553
  const result = renderCanvas(document, options);
@@ -63475,6 +63557,7 @@ function render(document, options = {}) {
63475
63557
  return renderer.render(document);
63476
63558
  }
63477
63559
  function renderToHtml(document, options = {}) {
63560
+ document = expandVariants(document);
63478
63561
  const { html, css } = render(document, options);
63479
63562
  const prefix = options.classPrefix ?? "wf";
63480
63563
  const isMultiPage = documentPages(document).length > 1;
@@ -63516,6 +63599,7 @@ ${html}
63516
63599
  </html>`;
63517
63600
  }
63518
63601
  function renderToSvg(document, options = {}) {
63602
+ document = expandVariants(document);
63519
63603
  const isMultiPage = documentPages(document).length > 1;
63520
63604
  let width = options.width ?? 800;
63521
63605
  let height = options.height ?? 600;
@@ -65930,6 +66014,7 @@ function linkAndCompileApp(manifest, modules, options = {}) {
65930
66014
  documentDefinitions,
65931
66015
  documentPages,
65932
66016
  expandRepeats,
66017
+ expandVariants,
65933
66018
  exportToFigma,
65934
66019
  exportToFigmaString,
65935
66020
  exportToJson,
package/dist/index.d.cts 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.cjs';
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.cjs';
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-DfiCKOPE.cjs';
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-DfiCKOPE.cjs';
3
3
  export { ExpectedToken, ParseError, ParseErrorInfo, ParseOptions, ParseResult, getErrors, isValid, parse, tryParse } from './parser.cjs';
4
4
  import { SiteOptions } from './renderer.cjs';
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.cjs';
@@ -333,6 +333,66 @@ 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
+
336
396
  /**
337
397
  * Node/document-level canonical `.wf` printing.
338
398
  *
@@ -1747,4 +1807,4 @@ declare function compileApp(document: AppDocument, options?: CompileAppOptions):
1747
1807
  */
1748
1808
  declare function linkAndCompileApp(manifest: AppManifest, modules: readonly AppModuleInput[], options?: CompileAppOptions): AppCompileResult;
1749
1809
 
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 };
1810
+ 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, 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 };
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, bd as WireframeDocument, aK as SourceLocation, aR as StateDeclaration, aS as StateGuard, a6 as InteractionEffect, a5 as InputType } from './types-DfiCKOPE.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-DfiCKOPE.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,66 @@ 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
+
336
396
  /**
337
397
  * Node/document-level canonical `.wf` printing.
338
398
  *
@@ -1747,4 +1807,4 @@ declare function compileApp(document: AppDocument, options?: CompileAppOptions):
1747
1807
  */
1748
1808
  declare function linkAndCompileApp(manifest: AppManifest, modules: readonly AppModuleInput[], options?: CompileAppOptions): AppCompileResult;
1749
1809
 
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 };
1810
+ 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, 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 };
package/dist/index.js CHANGED
@@ -432,6 +432,53 @@ function expandRepeats(document) {
432
432
  };
433
433
  }
434
434
 
435
+ // src/ast/expand-variants.ts
436
+ function cloneNode3(value) {
437
+ if (Array.isArray(value)) return value.map(cloneNode3);
438
+ if (value === null || typeof value !== "object") return value;
439
+ const source = value;
440
+ const result = {};
441
+ for (const [key, item] of Object.entries(source)) {
442
+ result[key] = key === "loc" ? item : cloneNode3(item);
443
+ }
444
+ return result;
445
+ }
446
+ function variantNames(page) {
447
+ const declared = page.variants;
448
+ if (!Array.isArray(declared)) return [];
449
+ const seen = /* @__PURE__ */ new Set();
450
+ const names = [];
451
+ for (const raw of declared) {
452
+ if (typeof raw !== "string") continue;
453
+ const name = raw.trim();
454
+ if (name.length === 0 || seen.has(name)) continue;
455
+ seen.add(name);
456
+ names.push(name);
457
+ }
458
+ return names;
459
+ }
460
+ function hasVariants(document) {
461
+ return document.children.some((child) => child.type === "Page" && variantNames(child).length > 0);
462
+ }
463
+ function expandVariants(document) {
464
+ if (!hasVariants(document)) return document;
465
+ return {
466
+ ...document,
467
+ children: document.children.flatMap((child) => {
468
+ if (child.type !== "Page") return [child];
469
+ const names = variantNames(child);
470
+ if (names.length === 0) return [child];
471
+ return names.map((variant, position) => {
472
+ const clone = cloneNode3(child);
473
+ delete clone.variants;
474
+ clone.variant = variant;
475
+ if (position > 0) delete clone.states;
476
+ return clone;
477
+ });
478
+ })
479
+ };
480
+ }
481
+
435
482
  // src/parser/generated-parser.js
436
483
  var peg$SyntaxError = class extends SyntaxError {
437
484
  constructor(message, expected, found, location) {
@@ -13118,6 +13165,11 @@ var ATTRIBUTE_SPECS = [
13118
13165
  type: "object[]",
13119
13166
  description: "Typed application state declarations owned by a page or shared layout"
13120
13167
  },
13168
+ {
13169
+ name: "variants",
13170
+ type: "string[]",
13171
+ description: "Named state variants of this page \u2014 each one renders the page again as a screen of its own"
13172
+ },
13121
13173
  {
13122
13174
  name: "id",
13123
13175
  type: "string",
@@ -13235,7 +13287,8 @@ var COMPONENT_METADATA = {
13235
13287
  "device",
13236
13288
  "centered",
13237
13289
  "uses",
13238
- "states"
13290
+ "states",
13291
+ "variants"
13239
13292
  ],
13240
13293
  hasChildren: true,
13241
13294
  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 +13963,8 @@ function pageTitle(page) {
13910
13963
  const title = page.title?.trim();
13911
13964
  return title !== void 0 && title.length > 0 ? title : void 0;
13912
13965
  }
13966
+ var VARIANT_SEPARATOR = "#";
13967
+ var variantName = (name, variant) => `${name}${VARIANT_SEPARATOR}${variant}`;
13913
13968
  function hasSlot(layout) {
13914
13969
  let found = false;
13915
13970
  for (const child of layout.children) {
@@ -13941,7 +13996,10 @@ function resolveShell(page, layouts) {
13941
13996
  function buildSiteModel(doc) {
13942
13997
  const pages = documentPages(doc);
13943
13998
  const layouts = layoutsByName(doc);
13944
- const screens = pages.map((page, index) => ({ index, page }));
13999
+ const screens = pages.map((page, index) => {
14000
+ const variant = page.variant?.trim();
14001
+ return variant !== void 0 && variant.length > 0 ? { index, page, variant } : { index, page };
14002
+ });
13945
14003
  const shells = [];
13946
14004
  const shellByName = /* @__PURE__ */ new Map();
13947
14005
  screens.forEach((screen) => {
@@ -13975,7 +14033,26 @@ function buildSiteModel(doc) {
13975
14033
  }
13976
14034
  }
13977
14035
  for (const screen of screens) {
13978
- const declared = [pageId(screen.page), pageTitle(screen.page)];
14036
+ if (screen.variant === void 0) continue;
14037
+ for (const declared of [pageId(screen.page), pageTitle(screen.page)]) {
14038
+ if (declared === void 0) continue;
14039
+ const owner = names.get(declared);
14040
+ if (owner === void 0) continue;
14041
+ const winner = screens[owner].page;
14042
+ if (pageId(winner) !== pageId(screen.page) || pageTitle(winner) !== pageTitle(screen.page)) {
14043
+ continue;
14044
+ }
14045
+ const qualified = variantName(declared, screen.variant);
14046
+ if (!names.has(qualified)) names.set(qualified, screen.index);
14047
+ }
14048
+ }
14049
+ for (const screen of screens) {
14050
+ const bare = [pageId(screen.page), pageTitle(screen.page)];
14051
+ const variant = screen.variant;
14052
+ const declared = variant === void 0 ? bare : [
14053
+ ...bare.map((name) => name === void 0 ? void 0 : variantName(name, variant)),
14054
+ ...bare
14055
+ ];
13979
14056
  screen.name = declared.find(
13980
14057
  (name) => name !== void 0 && names.get(name) === screen.index
13981
14058
  );
@@ -62527,7 +62604,8 @@ function wrapBoard(pageHtml, placed, prefix) {
62527
62604
  const { x, y, w, h, page } = placed;
62528
62605
  const positionStyle = `position: absolute; left: ${x}px; top: ${y}px; width: ${w}px; height: ${h}px;`;
62529
62606
  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}`;
62607
+ const variantAttr = page.variant ? ` data-wf-variant="${escapeAttr(page.variant)}"` : "";
62608
+ const dataAttrs = ` data-page-x="${x}" data-page-y="${y}" data-page-w="${w}" data-page-h="${h}"${titleAttr}${variantAttr}`;
62531
62609
  return `<div class="${prefix}-canvas-board" style="${positionStyle}"${dataAttrs}>
62532
62610
  ${pageHtml}
62533
62611
  </div>`;
@@ -63114,6 +63192,7 @@ function renderHostedScreen(screen, shell, make, prefix) {
63114
63192
  const marks = attrs([
63115
63193
  ["data-screen", String(screen.index)],
63116
63194
  ["data-screen-name", screen.name],
63195
+ ["data-wf-variant", screen.variant],
63117
63196
  [ID_SCOPE_ATTR, scope],
63118
63197
  ["data-wf-viewport-conflict", conflict]
63119
63198
  ]);
@@ -63127,6 +63206,7 @@ function renderStandaloneScreen(screen, make, prefix) {
63127
63206
  const marks = attrs([
63128
63207
  ["data-screen", String(screen.index)],
63129
63208
  ["data-screen-name", screen.name],
63209
+ ["data-wf-variant", screen.variant],
63130
63210
  [ID_SCOPE_ATTR, scope],
63131
63211
  ["data-wf-uses-unresolved", screen.miss?.uses],
63132
63212
  ["data-wf-uses-reason", screen.miss?.reason]
@@ -63195,7 +63275,7 @@ function compactRuntimeInteractions(model, interactions) {
63195
63275
  }
63196
63276
  function renderSite(document, options = {}) {
63197
63277
  const prefix = options.classPrefix ?? DEFAULT_PREFIX2;
63198
- document = expandRepeats(document);
63278
+ document = expandRepeats(expandVariants(document));
63199
63279
  const model = buildSiteModel(document);
63200
63280
  const interactionModel = collectInteractions(document);
63201
63281
  const make = (idScope) => new HtmlRenderer({
@@ -63264,6 +63344,7 @@ ${runtime}
63264
63344
 
63265
63345
  // src/renderer/index.ts
63266
63346
  function render(document, options = {}) {
63347
+ document = expandVariants(document);
63267
63348
  const isMultiPage = documentPages(document).length > 1;
63268
63349
  if (isMultiPage) {
63269
63350
  const result = renderCanvas(document, options);
@@ -63273,6 +63354,7 @@ function render(document, options = {}) {
63273
63354
  return renderer.render(document);
63274
63355
  }
63275
63356
  function renderToHtml(document, options = {}) {
63357
+ document = expandVariants(document);
63276
63358
  const { html, css } = render(document, options);
63277
63359
  const prefix = options.classPrefix ?? "wf";
63278
63360
  const isMultiPage = documentPages(document).length > 1;
@@ -63314,6 +63396,7 @@ ${html}
63314
63396
  </html>`;
63315
63397
  }
63316
63398
  function renderToSvg(document, options = {}) {
63399
+ document = expandVariants(document);
63317
63400
  const isMultiPage = documentPages(document).length > 1;
63318
63401
  let width = options.width ?? 800;
63319
63402
  let height = options.height ?? 600;
@@ -65727,6 +65810,7 @@ export {
65727
65810
  documentDefinitions,
65728
65811
  documentPages,
65729
65812
  expandRepeats,
65813
+ expandVariants,
65730
65814
  exportToFigma,
65731
65815
  exportToFigmaString,
65732
65816
  exportToJson,
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, bd as WireframeDocument } from './types-DfiCKOPE.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, bd as WireframeDocument } from './types-DfiCKOPE.js';
2
2
 
3
3
  /**
4
4
  * Parser module for wireweave
package/dist/renderer.cjs CHANGED
@@ -87,6 +87,53 @@ function documentDefinitions(document) {
87
87
  );
88
88
  }
89
89
 
90
+ // src/ast/expand-variants.ts
91
+ function cloneNode(value) {
92
+ if (Array.isArray(value)) return value.map(cloneNode);
93
+ if (value === null || typeof value !== "object") return value;
94
+ const source = value;
95
+ const result = {};
96
+ for (const [key, item] of Object.entries(source)) {
97
+ result[key] = key === "loc" ? item : cloneNode(item);
98
+ }
99
+ return result;
100
+ }
101
+ function variantNames(page) {
102
+ const declared = page.variants;
103
+ if (!Array.isArray(declared)) return [];
104
+ const seen = /* @__PURE__ */ new Set();
105
+ const names = [];
106
+ for (const raw of declared) {
107
+ if (typeof raw !== "string") continue;
108
+ const name = raw.trim();
109
+ if (name.length === 0 || seen.has(name)) continue;
110
+ seen.add(name);
111
+ names.push(name);
112
+ }
113
+ return names;
114
+ }
115
+ function hasVariants(document) {
116
+ return document.children.some((child) => child.type === "Page" && variantNames(child).length > 0);
117
+ }
118
+ function expandVariants(document) {
119
+ if (!hasVariants(document)) return document;
120
+ return {
121
+ ...document,
122
+ children: document.children.flatMap((child) => {
123
+ if (child.type !== "Page") return [child];
124
+ const names = variantNames(child);
125
+ if (names.length === 0) return [child];
126
+ return names.map((variant, position) => {
127
+ const clone = cloneNode(child);
128
+ delete clone.variants;
129
+ clone.variant = variant;
130
+ if (position > 0) delete clone.states;
131
+ return clone;
132
+ });
133
+ })
134
+ };
135
+ }
136
+
90
137
  // src/renderer/types.ts
91
138
  var defaultTheme = {
92
139
  colors: {
@@ -2341,13 +2388,13 @@ var RepeatBudgetError = class extends Error {
2341
2388
  this.name = "RepeatBudgetError";
2342
2389
  }
2343
2390
  };
2344
- function cloneNode(value) {
2345
- if (Array.isArray(value)) return value.map(cloneNode);
2391
+ function cloneNode2(value) {
2392
+ if (Array.isArray(value)) return value.map(cloneNode2);
2346
2393
  if (value === null || typeof value !== "object") return value;
2347
2394
  const source = value;
2348
2395
  const result = {};
2349
2396
  for (const [key, item] of Object.entries(source)) {
2350
- result[key] = key === "loc" ? item : cloneNode(item);
2397
+ result[key] = key === "loc" ? item : cloneNode2(item);
2351
2398
  }
2352
2399
  return result;
2353
2400
  }
@@ -2375,7 +2422,7 @@ function expandOne(node, budget) {
2375
2422
  for (const expanded of expandOne(child, budget)) {
2376
2423
  budget.remaining -= 1;
2377
2424
  if (budget.remaining < 0) throw new RepeatBudgetError(REPEAT_EXPANSION_BUDGET);
2378
- result.push(cloneNode(expanded));
2425
+ result.push(cloneNode2(expanded));
2379
2426
  }
2380
2427
  }
2381
2428
  }
@@ -2776,6 +2823,11 @@ var ATTRIBUTE_SPECS = [
2776
2823
  type: "object[]",
2777
2824
  description: "Typed application state declarations owned by a page or shared layout"
2778
2825
  },
2826
+ {
2827
+ name: "variants",
2828
+ type: "string[]",
2829
+ description: "Named state variants of this page \u2014 each one renders the page again as a screen of its own"
2830
+ },
2779
2831
  {
2780
2832
  name: "id",
2781
2833
  type: "string",
@@ -2893,7 +2945,8 @@ var COMPONENT_METADATA = {
2893
2945
  "device",
2894
2946
  "centered",
2895
2947
  "uses",
2896
- "states"
2948
+ "states",
2949
+ "variants"
2897
2950
  ],
2898
2951
  hasChildren: true,
2899
2952
  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."
@@ -3507,6 +3560,8 @@ function pageTitle(page) {
3507
3560
  const title = page.title?.trim();
3508
3561
  return title !== void 0 && title.length > 0 ? title : void 0;
3509
3562
  }
3563
+ var VARIANT_SEPARATOR = "#";
3564
+ var variantName = (name, variant) => `${name}${VARIANT_SEPARATOR}${variant}`;
3510
3565
  function hasSlot(layout) {
3511
3566
  let found = false;
3512
3567
  for (const child of layout.children) {
@@ -3538,7 +3593,10 @@ function resolveShell(page, layouts) {
3538
3593
  function buildSiteModel(doc) {
3539
3594
  const pages = documentPages(doc);
3540
3595
  const layouts = layoutsByName(doc);
3541
- const screens = pages.map((page, index) => ({ index, page }));
3596
+ const screens = pages.map((page, index) => {
3597
+ const variant = page.variant?.trim();
3598
+ return variant !== void 0 && variant.length > 0 ? { index, page, variant } : { index, page };
3599
+ });
3542
3600
  const shells = [];
3543
3601
  const shellByName = /* @__PURE__ */ new Map();
3544
3602
  screens.forEach((screen) => {
@@ -3572,7 +3630,26 @@ function buildSiteModel(doc) {
3572
3630
  }
3573
3631
  }
3574
3632
  for (const screen of screens) {
3575
- const declared = [pageId(screen.page), pageTitle(screen.page)];
3633
+ if (screen.variant === void 0) continue;
3634
+ for (const declared of [pageId(screen.page), pageTitle(screen.page)]) {
3635
+ if (declared === void 0) continue;
3636
+ const owner = names.get(declared);
3637
+ if (owner === void 0) continue;
3638
+ const winner = screens[owner].page;
3639
+ if (pageId(winner) !== pageId(screen.page) || pageTitle(winner) !== pageTitle(screen.page)) {
3640
+ continue;
3641
+ }
3642
+ const qualified = variantName(declared, screen.variant);
3643
+ if (!names.has(qualified)) names.set(qualified, screen.index);
3644
+ }
3645
+ }
3646
+ for (const screen of screens) {
3647
+ const bare = [pageId(screen.page), pageTitle(screen.page)];
3648
+ const variant = screen.variant;
3649
+ const declared = variant === void 0 ? bare : [
3650
+ ...bare.map((name) => name === void 0 ? void 0 : variantName(name, variant)),
3651
+ ...bare
3652
+ ];
3576
3653
  screen.name = declared.find(
3577
3654
  (name) => name !== void 0 && names.get(name) === screen.index
3578
3655
  );
@@ -52124,7 +52201,8 @@ function wrapBoard(pageHtml, placed, prefix) {
52124
52201
  const { x, y, w, h, page } = placed;
52125
52202
  const positionStyle = `position: absolute; left: ${x}px; top: ${y}px; width: ${w}px; height: ${h}px;`;
52126
52203
  const titleAttr = page.title ? ` data-page-title="${escapeAttr(page.title)}"` : "";
52127
- const dataAttrs = ` data-page-x="${x}" data-page-y="${y}" data-page-w="${w}" data-page-h="${h}"${titleAttr}`;
52204
+ const variantAttr = page.variant ? ` data-wf-variant="${escapeAttr(page.variant)}"` : "";
52205
+ const dataAttrs = ` data-page-x="${x}" data-page-y="${y}" data-page-w="${w}" data-page-h="${h}"${titleAttr}${variantAttr}`;
52128
52206
  return `<div class="${prefix}-canvas-board" style="${positionStyle}"${dataAttrs}>
52129
52207
  ${pageHtml}
52130
52208
  </div>`;
@@ -52711,6 +52789,7 @@ function renderHostedScreen(screen, shell, make, prefix) {
52711
52789
  const marks = attrs([
52712
52790
  ["data-screen", String(screen.index)],
52713
52791
  ["data-screen-name", screen.name],
52792
+ ["data-wf-variant", screen.variant],
52714
52793
  [ID_SCOPE_ATTR, scope],
52715
52794
  ["data-wf-viewport-conflict", conflict]
52716
52795
  ]);
@@ -52724,6 +52803,7 @@ function renderStandaloneScreen(screen, make, prefix) {
52724
52803
  const marks = attrs([
52725
52804
  ["data-screen", String(screen.index)],
52726
52805
  ["data-screen-name", screen.name],
52806
+ ["data-wf-variant", screen.variant],
52727
52807
  [ID_SCOPE_ATTR, scope],
52728
52808
  ["data-wf-uses-unresolved", screen.miss?.uses],
52729
52809
  ["data-wf-uses-reason", screen.miss?.reason]
@@ -52792,7 +52872,7 @@ function compactRuntimeInteractions(model, interactions) {
52792
52872
  }
52793
52873
  function renderSite(document, options = {}) {
52794
52874
  const prefix = options.classPrefix ?? DEFAULT_PREFIX2;
52795
- document = expandRepeats(document);
52875
+ document = expandRepeats(expandVariants(document));
52796
52876
  const model = buildSiteModel(document);
52797
52877
  const interactionModel = collectInteractions(document);
52798
52878
  const make = (idScope) => new HtmlRenderer({
@@ -52861,6 +52941,7 @@ ${runtime}
52861
52941
 
52862
52942
  // src/renderer/index.ts
52863
52943
  function render(document, options = {}) {
52944
+ document = expandVariants(document);
52864
52945
  const isMultiPage = documentPages(document).length > 1;
52865
52946
  if (isMultiPage) {
52866
52947
  const result = renderCanvas(document, options);
@@ -52870,6 +52951,7 @@ function render(document, options = {}) {
52870
52951
  return renderer.render(document);
52871
52952
  }
52872
52953
  function renderToHtml(document, options = {}) {
52954
+ document = expandVariants(document);
52873
52955
  const { html, css } = render(document, options);
52874
52956
  const prefix = options.classPrefix ?? "wf";
52875
52957
  const isMultiPage = documentPages(document).length > 1;
@@ -52911,6 +52993,7 @@ ${html}
52911
52993
  </html>`;
52912
52994
  }
52913
52995
  function renderToSvg(document, options = {}) {
52996
+ document = expandVariants(document);
52914
52997
  const isMultiPage = documentPages(document).length > 1;
52915
52998
  let width = options.width ?? 800;
52916
52999
  let height = options.height ?? 600;
@@ -1,4 +1,4 @@
1
- import { bd as WireframeDocument, h as AnyNode, as as PageNode, H as ComponentUseNode, aa as LayoutDefinitionNode, a8 as InteractiveProps, Y as GuardedOutcomeProps } from './types-BphXi5Tn.cjs';
1
+ import { bd as WireframeDocument, h as AnyNode, as as PageNode, H as ComponentUseNode, aa as LayoutDefinitionNode, a8 as InteractiveProps, Y as GuardedOutcomeProps } from './types-DfiCKOPE.cjs';
2
2
 
3
3
  /**
4
4
  * Renderer type definitions for wireweave
@@ -587,6 +587,15 @@ interface SiteScreen {
587
587
  /** Position in `documentPages(doc)`. This is the screen's DOM key. */
588
588
  index: number;
589
589
  page: PageNode;
590
+ /**
591
+ * The variant this screen draws, when its page came from a `variants=` list.
592
+ *
593
+ * Read off the page rather than derived here: `expandVariants` has already
594
+ * turned one variant-bearing page into one page per variant by the time a
595
+ * model is built, so each of those pages is a screen like any other and this
596
+ * only records which one it is.
597
+ */
598
+ variant?: string;
590
599
  /** Name of the shell this screen is composed into, when it has one. */
591
600
  shell?: string;
592
601
  /** Set when `uses=` was declared and could not be honoured. */
@@ -1,4 +1,4 @@
1
- import { bd as WireframeDocument, h as AnyNode, as as PageNode, H as ComponentUseNode, aa as LayoutDefinitionNode, a8 as InteractiveProps, Y as GuardedOutcomeProps } from './types-BphXi5Tn.js';
1
+ import { bd as WireframeDocument, h as AnyNode, as as PageNode, H as ComponentUseNode, aa as LayoutDefinitionNode, a8 as InteractiveProps, Y as GuardedOutcomeProps } from './types-DfiCKOPE.js';
2
2
 
3
3
  /**
4
4
  * Renderer type definitions for wireweave
@@ -587,6 +587,15 @@ interface SiteScreen {
587
587
  /** Position in `documentPages(doc)`. This is the screen's DOM key. */
588
588
  index: number;
589
589
  page: PageNode;
590
+ /**
591
+ * The variant this screen draws, when its page came from a `variants=` list.
592
+ *
593
+ * Read off the page rather than derived here: `expandVariants` has already
594
+ * turned one variant-bearing page into one page per variant by the time a
595
+ * model is built, so each of those pages is a screen like any other and this
596
+ * only records which one it is.
597
+ */
598
+ variant?: string;
590
599
  /** Name of the shell this screen is composed into, when it has one. */
591
600
  shell?: string;
592
601
  /** Set when `uses=` was declared and could not be honoured. */
package/dist/renderer.js CHANGED
@@ -33,6 +33,53 @@ function documentDefinitions(document) {
33
33
  );
34
34
  }
35
35
 
36
+ // src/ast/expand-variants.ts
37
+ function cloneNode(value) {
38
+ if (Array.isArray(value)) return value.map(cloneNode);
39
+ if (value === null || typeof value !== "object") return value;
40
+ const source = value;
41
+ const result = {};
42
+ for (const [key, item] of Object.entries(source)) {
43
+ result[key] = key === "loc" ? item : cloneNode(item);
44
+ }
45
+ return result;
46
+ }
47
+ function variantNames(page) {
48
+ const declared = page.variants;
49
+ if (!Array.isArray(declared)) return [];
50
+ const seen = /* @__PURE__ */ new Set();
51
+ const names = [];
52
+ for (const raw of declared) {
53
+ if (typeof raw !== "string") continue;
54
+ const name = raw.trim();
55
+ if (name.length === 0 || seen.has(name)) continue;
56
+ seen.add(name);
57
+ names.push(name);
58
+ }
59
+ return names;
60
+ }
61
+ function hasVariants(document) {
62
+ return document.children.some((child) => child.type === "Page" && variantNames(child).length > 0);
63
+ }
64
+ function expandVariants(document) {
65
+ if (!hasVariants(document)) return document;
66
+ return {
67
+ ...document,
68
+ children: document.children.flatMap((child) => {
69
+ if (child.type !== "Page") return [child];
70
+ const names = variantNames(child);
71
+ if (names.length === 0) return [child];
72
+ return names.map((variant, position) => {
73
+ const clone = cloneNode(child);
74
+ delete clone.variants;
75
+ clone.variant = variant;
76
+ if (position > 0) delete clone.states;
77
+ return clone;
78
+ });
79
+ })
80
+ };
81
+ }
82
+
36
83
  // src/renderer/types.ts
37
84
  var defaultTheme = {
38
85
  colors: {
@@ -2287,13 +2334,13 @@ var RepeatBudgetError = class extends Error {
2287
2334
  this.name = "RepeatBudgetError";
2288
2335
  }
2289
2336
  };
2290
- function cloneNode(value) {
2291
- if (Array.isArray(value)) return value.map(cloneNode);
2337
+ function cloneNode2(value) {
2338
+ if (Array.isArray(value)) return value.map(cloneNode2);
2292
2339
  if (value === null || typeof value !== "object") return value;
2293
2340
  const source = value;
2294
2341
  const result = {};
2295
2342
  for (const [key, item] of Object.entries(source)) {
2296
- result[key] = key === "loc" ? item : cloneNode(item);
2343
+ result[key] = key === "loc" ? item : cloneNode2(item);
2297
2344
  }
2298
2345
  return result;
2299
2346
  }
@@ -2321,7 +2368,7 @@ function expandOne(node, budget) {
2321
2368
  for (const expanded of expandOne(child, budget)) {
2322
2369
  budget.remaining -= 1;
2323
2370
  if (budget.remaining < 0) throw new RepeatBudgetError(REPEAT_EXPANSION_BUDGET);
2324
- result.push(cloneNode(expanded));
2371
+ result.push(cloneNode2(expanded));
2325
2372
  }
2326
2373
  }
2327
2374
  }
@@ -2722,6 +2769,11 @@ var ATTRIBUTE_SPECS = [
2722
2769
  type: "object[]",
2723
2770
  description: "Typed application state declarations owned by a page or shared layout"
2724
2771
  },
2772
+ {
2773
+ name: "variants",
2774
+ type: "string[]",
2775
+ description: "Named state variants of this page \u2014 each one renders the page again as a screen of its own"
2776
+ },
2725
2777
  {
2726
2778
  name: "id",
2727
2779
  type: "string",
@@ -2839,7 +2891,8 @@ var COMPONENT_METADATA = {
2839
2891
  "device",
2840
2892
  "centered",
2841
2893
  "uses",
2842
- "states"
2894
+ "states",
2895
+ "variants"
2843
2896
  ],
2844
2897
  hasChildren: true,
2845
2898
  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."
@@ -3453,6 +3506,8 @@ function pageTitle(page) {
3453
3506
  const title = page.title?.trim();
3454
3507
  return title !== void 0 && title.length > 0 ? title : void 0;
3455
3508
  }
3509
+ var VARIANT_SEPARATOR = "#";
3510
+ var variantName = (name, variant) => `${name}${VARIANT_SEPARATOR}${variant}`;
3456
3511
  function hasSlot(layout) {
3457
3512
  let found = false;
3458
3513
  for (const child of layout.children) {
@@ -3484,7 +3539,10 @@ function resolveShell(page, layouts) {
3484
3539
  function buildSiteModel(doc) {
3485
3540
  const pages = documentPages(doc);
3486
3541
  const layouts = layoutsByName(doc);
3487
- const screens = pages.map((page, index) => ({ index, page }));
3542
+ const screens = pages.map((page, index) => {
3543
+ const variant = page.variant?.trim();
3544
+ return variant !== void 0 && variant.length > 0 ? { index, page, variant } : { index, page };
3545
+ });
3488
3546
  const shells = [];
3489
3547
  const shellByName = /* @__PURE__ */ new Map();
3490
3548
  screens.forEach((screen) => {
@@ -3518,7 +3576,26 @@ function buildSiteModel(doc) {
3518
3576
  }
3519
3577
  }
3520
3578
  for (const screen of screens) {
3521
- const declared = [pageId(screen.page), pageTitle(screen.page)];
3579
+ if (screen.variant === void 0) continue;
3580
+ for (const declared of [pageId(screen.page), pageTitle(screen.page)]) {
3581
+ if (declared === void 0) continue;
3582
+ const owner = names.get(declared);
3583
+ if (owner === void 0) continue;
3584
+ const winner = screens[owner].page;
3585
+ if (pageId(winner) !== pageId(screen.page) || pageTitle(winner) !== pageTitle(screen.page)) {
3586
+ continue;
3587
+ }
3588
+ const qualified = variantName(declared, screen.variant);
3589
+ if (!names.has(qualified)) names.set(qualified, screen.index);
3590
+ }
3591
+ }
3592
+ for (const screen of screens) {
3593
+ const bare = [pageId(screen.page), pageTitle(screen.page)];
3594
+ const variant = screen.variant;
3595
+ const declared = variant === void 0 ? bare : [
3596
+ ...bare.map((name) => name === void 0 ? void 0 : variantName(name, variant)),
3597
+ ...bare
3598
+ ];
3522
3599
  screen.name = declared.find(
3523
3600
  (name) => name !== void 0 && names.get(name) === screen.index
3524
3601
  );
@@ -52070,7 +52147,8 @@ function wrapBoard(pageHtml, placed, prefix) {
52070
52147
  const { x, y, w, h, page } = placed;
52071
52148
  const positionStyle = `position: absolute; left: ${x}px; top: ${y}px; width: ${w}px; height: ${h}px;`;
52072
52149
  const titleAttr = page.title ? ` data-page-title="${escapeAttr(page.title)}"` : "";
52073
- const dataAttrs = ` data-page-x="${x}" data-page-y="${y}" data-page-w="${w}" data-page-h="${h}"${titleAttr}`;
52150
+ const variantAttr = page.variant ? ` data-wf-variant="${escapeAttr(page.variant)}"` : "";
52151
+ const dataAttrs = ` data-page-x="${x}" data-page-y="${y}" data-page-w="${w}" data-page-h="${h}"${titleAttr}${variantAttr}`;
52074
52152
  return `<div class="${prefix}-canvas-board" style="${positionStyle}"${dataAttrs}>
52075
52153
  ${pageHtml}
52076
52154
  </div>`;
@@ -52657,6 +52735,7 @@ function renderHostedScreen(screen, shell, make, prefix) {
52657
52735
  const marks = attrs([
52658
52736
  ["data-screen", String(screen.index)],
52659
52737
  ["data-screen-name", screen.name],
52738
+ ["data-wf-variant", screen.variant],
52660
52739
  [ID_SCOPE_ATTR, scope],
52661
52740
  ["data-wf-viewport-conflict", conflict]
52662
52741
  ]);
@@ -52670,6 +52749,7 @@ function renderStandaloneScreen(screen, make, prefix) {
52670
52749
  const marks = attrs([
52671
52750
  ["data-screen", String(screen.index)],
52672
52751
  ["data-screen-name", screen.name],
52752
+ ["data-wf-variant", screen.variant],
52673
52753
  [ID_SCOPE_ATTR, scope],
52674
52754
  ["data-wf-uses-unresolved", screen.miss?.uses],
52675
52755
  ["data-wf-uses-reason", screen.miss?.reason]
@@ -52738,7 +52818,7 @@ function compactRuntimeInteractions(model, interactions) {
52738
52818
  }
52739
52819
  function renderSite(document, options = {}) {
52740
52820
  const prefix = options.classPrefix ?? DEFAULT_PREFIX2;
52741
- document = expandRepeats(document);
52821
+ document = expandRepeats(expandVariants(document));
52742
52822
  const model = buildSiteModel(document);
52743
52823
  const interactionModel = collectInteractions(document);
52744
52824
  const make = (idScope) => new HtmlRenderer({
@@ -52807,6 +52887,7 @@ ${runtime}
52807
52887
 
52808
52888
  // src/renderer/index.ts
52809
52889
  function render(document, options = {}) {
52890
+ document = expandVariants(document);
52810
52891
  const isMultiPage = documentPages(document).length > 1;
52811
52892
  if (isMultiPage) {
52812
52893
  const result = renderCanvas(document, options);
@@ -52816,6 +52897,7 @@ function render(document, options = {}) {
52816
52897
  return renderer.render(document);
52817
52898
  }
52818
52899
  function renderToHtml(document, options = {}) {
52900
+ document = expandVariants(document);
52819
52901
  const { html, css } = render(document, options);
52820
52902
  const prefix = options.classPrefix ?? "wf";
52821
52903
  const isMultiPage = documentPages(document).length > 1;
@@ -52857,6 +52939,7 @@ ${html}
52857
52939
  </html>`;
52858
52940
  }
52859
52941
  function renderToSvg(document, options = {}) {
52942
+ document = expandVariants(document);
52860
52943
  const isMultiPage = documentPages(document).length > 1;
52861
52944
  let width = options.width ?? 800;
52862
52945
  let height = options.height ?? 600;
package/dist/spec.cjs CHANGED
@@ -2166,6 +2166,11 @@ var ATTRIBUTE_SPECS = [
2166
2166
  type: "object[]",
2167
2167
  description: "Typed application state declarations owned by a page or shared layout"
2168
2168
  },
2169
+ {
2170
+ name: "variants",
2171
+ type: "string[]",
2172
+ description: "Named state variants of this page \u2014 each one renders the page again as a screen of its own"
2173
+ },
2169
2174
  {
2170
2175
  name: "id",
2171
2176
  type: "string",
@@ -2283,7 +2288,8 @@ var COMPONENT_METADATA = {
2283
2288
  "device",
2284
2289
  "centered",
2285
2290
  "uses",
2286
- "states"
2291
+ "states",
2292
+ "variants"
2287
2293
  ],
2288
2294
  hasChildren: true,
2289
2295
  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."
package/dist/spec.js CHANGED
@@ -2119,6 +2119,11 @@ var ATTRIBUTE_SPECS = [
2119
2119
  type: "object[]",
2120
2120
  description: "Typed application state declarations owned by a page or shared layout"
2121
2121
  },
2122
+ {
2123
+ name: "variants",
2124
+ type: "string[]",
2125
+ description: "Named state variants of this page \u2014 each one renders the page again as a screen of its own"
2126
+ },
2122
2127
  {
2123
2128
  name: "id",
2124
2129
  type: "string",
@@ -2236,7 +2241,8 @@ var COMPONENT_METADATA = {
2236
2241
  "device",
2237
2242
  "centered",
2238
2243
  "uses",
2239
- "states"
2244
+ "states",
2245
+ "variants"
2240
2246
  ],
2241
2247
  hasChildren: true,
2242
2248
  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."
@@ -235,6 +235,37 @@ interface PageNode extends BaseNode, CommonProps {
235
235
  uses?: string;
236
236
  /** Application state declarations contributed by this screen module. */
237
237
  states?: StateDeclaration[];
238
+ /**
239
+ * Named state variants of this screen — `variants=[loading, empty, ready]`.
240
+ *
241
+ * Each name draws the page again as a screen of its own, so a document
242
+ * declaring three variants renders three independent boards rather than one
243
+ * board with a toggle in it. That is the whole difference from {@link states}:
244
+ * a state is a runtime value the site runtime flips and guards read, so the
245
+ * transitions between states have to exist as UI somewhere; a variant is an
246
+ * axis of the *artifact*, so the states appear side by side and nothing in
247
+ * the wireframe has to offer a way to switch between them. A reviewer of a
248
+ * variant sheet never mistakes a state-switching control for a product
249
+ * feature, because there is none to mistake.
250
+ *
251
+ * Deliberately page-local, where `states` is collected document-wide: a
252
+ * variant only means anything relative to the page it varies, and a document
253
+ * scope would make one page's variant list multiply every other page's
254
+ * screens. Names are free-form identifiers — the language fixes no vocabulary
255
+ * of states, because which states a screen has is a property of that screen.
256
+ */
257
+ variants?: string[];
258
+ /**
259
+ * Which variant this page *is* — set by `expandVariants`, never by an author.
260
+ *
261
+ * The authored `variants` list and this are the two ends of the same
262
+ * expansion: a page carries the list before it, and each page it expands into
263
+ * carries one name from that list and no list. The printer therefore only
264
+ * writes `variants`, and a document that has been expanded prints back as the
265
+ * boards it became rather than as the fold it came from — the same asymmetry
266
+ * `repeat` has between its node and its copies.
267
+ */
268
+ variant?: string;
238
269
  children: AnyNode[];
239
270
  }
240
271
  /**
@@ -235,6 +235,37 @@ interface PageNode extends BaseNode, CommonProps {
235
235
  uses?: string;
236
236
  /** Application state declarations contributed by this screen module. */
237
237
  states?: StateDeclaration[];
238
+ /**
239
+ * Named state variants of this screen — `variants=[loading, empty, ready]`.
240
+ *
241
+ * Each name draws the page again as a screen of its own, so a document
242
+ * declaring three variants renders three independent boards rather than one
243
+ * board with a toggle in it. That is the whole difference from {@link states}:
244
+ * a state is a runtime value the site runtime flips and guards read, so the
245
+ * transitions between states have to exist as UI somewhere; a variant is an
246
+ * axis of the *artifact*, so the states appear side by side and nothing in
247
+ * the wireframe has to offer a way to switch between them. A reviewer of a
248
+ * variant sheet never mistakes a state-switching control for a product
249
+ * feature, because there is none to mistake.
250
+ *
251
+ * Deliberately page-local, where `states` is collected document-wide: a
252
+ * variant only means anything relative to the page it varies, and a document
253
+ * scope would make one page's variant list multiply every other page's
254
+ * screens. Names are free-form identifiers — the language fixes no vocabulary
255
+ * of states, because which states a screen has is a property of that screen.
256
+ */
257
+ variants?: string[];
258
+ /**
259
+ * Which variant this page *is* — set by `expandVariants`, never by an author.
260
+ *
261
+ * The authored `variants` list and this are the two ends of the same
262
+ * expansion: a page carries the list before it, and each page it expands into
263
+ * carries one name from that list and no list. The printer therefore only
264
+ * writes `variants`, and a document that has been expanded prints back as the
265
+ * boards it became rather than as the fold it came from — the same asymmetry
266
+ * `repeat` has between its node and its copies.
267
+ */
268
+ variant?: string;
238
269
  children: AnyNode[];
239
270
  }
240
271
  /**
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@wireweave/core",
3
- "version": "3.1.0-beta.7",
3
+ "version": "3.1.0-beta.8",
4
4
  "description": "Core parser and renderer for wireweave",
5
5
  "type": "module",
6
6
  "sideEffects": false,