@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/renderer.js CHANGED
@@ -33,6 +33,153 @@ function documentDefinitions(document) {
33
33
  );
34
34
  }
35
35
 
36
+ // src/ast/filter-variant-scope.ts
37
+ function variantScope(node) {
38
+ const declared = node.when;
39
+ if (declared === void 0) return void 0;
40
+ const raw = Array.isArray(declared) ? declared : [declared];
41
+ const seen = /* @__PURE__ */ new Set();
42
+ const names = [];
43
+ for (const item of raw) {
44
+ if (typeof item !== "string") continue;
45
+ const name = item.trim();
46
+ if (name.length === 0 || seen.has(name)) continue;
47
+ seen.add(name);
48
+ names.push(name);
49
+ }
50
+ return names;
51
+ }
52
+ function childList(value) {
53
+ const children = value?.children;
54
+ return Array.isArray(children) ? children : void 0;
55
+ }
56
+ function asNode(value) {
57
+ return value !== null && typeof value === "object" && "type" in value ? value : void 0;
58
+ }
59
+ function filterChildList(children, variant) {
60
+ return children.flatMap((child) => {
61
+ const node = asNode(child);
62
+ if (node === void 0) return [child];
63
+ const kept = filterNode(node, variant);
64
+ return kept === void 0 ? [] : [kept];
65
+ });
66
+ }
67
+ function containsScope(node) {
68
+ if (node.when !== void 0) return true;
69
+ for (const child of childList(node) ?? []) {
70
+ const nested = asNode(child);
71
+ if (nested !== void 0 && containsScope(nested)) return true;
72
+ }
73
+ const fills = node.fills;
74
+ if (Array.isArray(fills)) {
75
+ for (const fill of fills) {
76
+ for (const child of childList(fill) ?? []) {
77
+ const nested = asNode(child);
78
+ if (nested !== void 0 && containsScope(nested)) return true;
79
+ }
80
+ }
81
+ }
82
+ return false;
83
+ }
84
+ function filterNode(node, variant) {
85
+ const scope = variantScope(node);
86
+ if (scope !== void 0) {
87
+ if (variant === void 0 || !scope.includes(variant)) return void 0;
88
+ }
89
+ const nested = containsScope(node);
90
+ if (scope === void 0 && !nested) return node;
91
+ const result = {};
92
+ for (const [key, value] of Object.entries(node)) {
93
+ if (key === "when") continue;
94
+ result[key] = value;
95
+ }
96
+ const children = childList(node);
97
+ if (children !== void 0) {
98
+ result.children = filterChildList(children, variant);
99
+ }
100
+ const fills = node.fills;
101
+ if (Array.isArray(fills)) {
102
+ result.fills = fills.map((fill) => {
103
+ const fillChildren = childList(fill);
104
+ if (fillChildren === void 0) return fill;
105
+ return {
106
+ ...fill,
107
+ children: filterChildList(fillChildren, variant)
108
+ };
109
+ });
110
+ }
111
+ return result;
112
+ }
113
+ function filterVariantScope(children, variant) {
114
+ if (!children.some((child) => containsScope(child))) return children;
115
+ return children.flatMap((child) => {
116
+ const kept = filterNode(child, variant);
117
+ return kept === void 0 ? [] : [kept];
118
+ });
119
+ }
120
+ function filterUnscopedPages(document) {
121
+ let changed = false;
122
+ const children = document.children.map((child) => {
123
+ if (child.type !== "Page" || child.variant !== void 0) return child;
124
+ const filtered = filterVariantScope(child.children, void 0);
125
+ if (filtered === child.children) return child;
126
+ changed = true;
127
+ return { ...child, children: filtered };
128
+ });
129
+ return changed ? { ...document, children } : document;
130
+ }
131
+
132
+ // src/ast/expand-variants.ts
133
+ function cloneNode(value) {
134
+ if (Array.isArray(value)) return value.map(cloneNode);
135
+ if (value === null || typeof value !== "object") return value;
136
+ const source = value;
137
+ const result = {};
138
+ for (const [key, item] of Object.entries(source)) {
139
+ result[key] = key === "loc" ? item : cloneNode(item);
140
+ }
141
+ return result;
142
+ }
143
+ function variantNames(page) {
144
+ const declared = page.variants;
145
+ if (!Array.isArray(declared)) return [];
146
+ const seen = /* @__PURE__ */ new Set();
147
+ const names = [];
148
+ for (const raw of declared) {
149
+ if (typeof raw !== "string") continue;
150
+ const name = raw.trim();
151
+ if (name.length === 0 || seen.has(name)) continue;
152
+ seen.add(name);
153
+ names.push(name);
154
+ }
155
+ return names;
156
+ }
157
+ function hasVariants(document) {
158
+ return document.children.some((child) => child.type === "Page" && variantNames(child).length > 0);
159
+ }
160
+ function expandVariants(document) {
161
+ if (!hasVariants(document)) return filterUnscopedPages(document);
162
+ return {
163
+ ...document,
164
+ children: document.children.flatMap((child) => {
165
+ if (child.type !== "Page") return [child];
166
+ const names = variantNames(child);
167
+ if (names.length === 0) {
168
+ const filtered = filterVariantScope(child.children, void 0);
169
+ return [filtered === child.children ? child : { ...child, children: filtered }];
170
+ }
171
+ return names.map((variant, position) => {
172
+ const clone = cloneNode(child);
173
+ delete clone.variants;
174
+ clone.variant = variant;
175
+ if (position > 0) delete clone.states;
176
+ clone.children = filterVariantScope(clone.children, variant);
177
+ return clone;
178
+ });
179
+ })
180
+ };
181
+ }
182
+
36
183
  // src/renderer/types.ts
37
184
  var defaultTheme = {
38
185
  colors: {
@@ -2287,13 +2434,13 @@ var RepeatBudgetError = class extends Error {
2287
2434
  this.name = "RepeatBudgetError";
2288
2435
  }
2289
2436
  };
2290
- function cloneNode(value) {
2291
- if (Array.isArray(value)) return value.map(cloneNode);
2437
+ function cloneNode2(value) {
2438
+ if (Array.isArray(value)) return value.map(cloneNode2);
2292
2439
  if (value === null || typeof value !== "object") return value;
2293
2440
  const source = value;
2294
2441
  const result = {};
2295
2442
  for (const [key, item] of Object.entries(source)) {
2296
- result[key] = key === "loc" ? item : cloneNode(item);
2443
+ result[key] = key === "loc" ? item : cloneNode2(item);
2297
2444
  }
2298
2445
  return result;
2299
2446
  }
@@ -2321,7 +2468,7 @@ function expandOne(node, budget) {
2321
2468
  for (const expanded of expandOne(child, budget)) {
2322
2469
  budget.remaining -= 1;
2323
2470
  if (budget.remaining < 0) throw new RepeatBudgetError(REPEAT_EXPANSION_BUDGET);
2324
- result.push(cloneNode(expanded));
2471
+ result.push(cloneNode2(expanded));
2325
2472
  }
2326
2473
  }
2327
2474
  }
@@ -2722,6 +2869,16 @@ var ATTRIBUTE_SPECS = [
2722
2869
  type: "object[]",
2723
2870
  description: "Typed application state declarations owned by a page or shared layout"
2724
2871
  },
2872
+ {
2873
+ name: "variants",
2874
+ type: "string[]",
2875
+ description: "Named state variants of this page \u2014 each one renders the page again as a screen of its own"
2876
+ },
2877
+ {
2878
+ name: "when",
2879
+ type: "string[]",
2880
+ description: "Variant boards this element is drawn on \u2014 when=loading, or when=[loading, empty] for both"
2881
+ },
2725
2882
  {
2726
2883
  name: "id",
2727
2884
  type: "string",
@@ -2767,6 +2924,13 @@ var BOX_ATTRIBUTES = [
2767
2924
  // Guarded runtime outcomes
2768
2925
  "visibleWhen",
2769
2926
  "enabledWhen",
2927
+ // Build-time variant scope. Listed beside the guards because it reads like
2928
+ // them and is deliberately not one of them: a guard leaves the element in the
2929
+ // markup for the runtime to toggle, `when` decides whether the element is in
2930
+ // that board's markup at all. Every element takes it for the same reason
2931
+ // every element takes a guard — which boards a piece of a screen belongs to
2932
+ // is a property of the piece, not of what kind of piece it is.
2933
+ "when",
2770
2934
  // Spacing
2771
2935
  "p",
2772
2936
  "px",
@@ -2829,7 +2993,15 @@ var COMPONENT_METADATA = {
2829
2993
  // board that path renders *into* — nothing emits the attribute for it and
2830
2994
  // nothing would toggle it, so declaring it would let an author write a
2831
2995
  // guard on a page, pass `validate()`, and have the value silently dropped.
2832
- ...BOX_ATTRIBUTES.filter((name) => name !== "visibleWhen" && name !== "enabledWhen"),
2996
+ // `when` is filtered out alongside the guards, for a reason of its own: a
2997
+ // page *is* a board, so scoping one to a variant would be a board saying
2998
+ // which board it is drawn on. The axis a page declares is `variants`, and
2999
+ // `when` names positions along it — the two sit at different levels and a
3000
+ // page carrying both would be asking `expandVariants` to filter a page
3001
+ // against a name it is itself the source of.
3002
+ ...BOX_ATTRIBUTES.filter(
3003
+ (name) => name !== "visibleWhen" && name !== "enabledWhen" && name !== "when"
3004
+ ),
2833
3005
  ...CONTAINER_ATTRIBUTES,
2834
3006
  "id",
2835
3007
  "title",
@@ -2839,7 +3011,8 @@ var COMPONENT_METADATA = {
2839
3011
  "device",
2840
3012
  "centered",
2841
3013
  "uses",
2842
- "states"
3014
+ "states",
3015
+ "variants"
2843
3016
  ],
2844
3017
  hasChildren: true,
2845
3018
  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 +3626,8 @@ function pageTitle(page) {
3453
3626
  const title = page.title?.trim();
3454
3627
  return title !== void 0 && title.length > 0 ? title : void 0;
3455
3628
  }
3629
+ var VARIANT_SEPARATOR = "#";
3630
+ var variantName = (name, variant) => `${name}${VARIANT_SEPARATOR}${variant}`;
3456
3631
  function hasSlot(layout) {
3457
3632
  let found = false;
3458
3633
  for (const child of layout.children) {
@@ -3484,7 +3659,10 @@ function resolveShell(page, layouts) {
3484
3659
  function buildSiteModel(doc) {
3485
3660
  const pages = documentPages(doc);
3486
3661
  const layouts = layoutsByName(doc);
3487
- const screens = pages.map((page, index) => ({ index, page }));
3662
+ const screens = pages.map((page, index) => {
3663
+ const variant = page.variant?.trim();
3664
+ return variant !== void 0 && variant.length > 0 ? { index, page, variant } : { index, page };
3665
+ });
3488
3666
  const shells = [];
3489
3667
  const shellByName = /* @__PURE__ */ new Map();
3490
3668
  screens.forEach((screen) => {
@@ -3518,7 +3696,26 @@ function buildSiteModel(doc) {
3518
3696
  }
3519
3697
  }
3520
3698
  for (const screen of screens) {
3521
- const declared = [pageId(screen.page), pageTitle(screen.page)];
3699
+ if (screen.variant === void 0) continue;
3700
+ for (const declared of [pageId(screen.page), pageTitle(screen.page)]) {
3701
+ if (declared === void 0) continue;
3702
+ const owner = names.get(declared);
3703
+ if (owner === void 0) continue;
3704
+ const winner = screens[owner].page;
3705
+ if (pageId(winner) !== pageId(screen.page) || pageTitle(winner) !== pageTitle(screen.page)) {
3706
+ continue;
3707
+ }
3708
+ const qualified = variantName(declared, screen.variant);
3709
+ if (!names.has(qualified)) names.set(qualified, screen.index);
3710
+ }
3711
+ }
3712
+ for (const screen of screens) {
3713
+ const bare = [pageId(screen.page), pageTitle(screen.page)];
3714
+ const variant = screen.variant;
3715
+ const declared = variant === void 0 ? bare : [
3716
+ ...bare.map((name) => name === void 0 ? void 0 : variantName(name, variant)),
3717
+ ...bare
3718
+ ];
3522
3719
  screen.name = declared.find(
3523
3720
  (name) => name !== void 0 && names.get(name) === screen.index
3524
3721
  );
@@ -52070,7 +52267,8 @@ function wrapBoard(pageHtml, placed, prefix) {
52070
52267
  const { x, y, w, h, page } = placed;
52071
52268
  const positionStyle = `position: absolute; left: ${x}px; top: ${y}px; width: ${w}px; height: ${h}px;`;
52072
52269
  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}`;
52270
+ const variantAttr = page.variant ? ` data-wf-variant="${escapeAttr(page.variant)}"` : "";
52271
+ const dataAttrs = ` data-page-x="${x}" data-page-y="${y}" data-page-w="${w}" data-page-h="${h}"${titleAttr}${variantAttr}`;
52074
52272
  return `<div class="${prefix}-canvas-board" style="${positionStyle}"${dataAttrs}>
52075
52273
  ${pageHtml}
52076
52274
  </div>`;
@@ -52657,6 +52855,7 @@ function renderHostedScreen(screen, shell, make, prefix) {
52657
52855
  const marks = attrs([
52658
52856
  ["data-screen", String(screen.index)],
52659
52857
  ["data-screen-name", screen.name],
52858
+ ["data-wf-variant", screen.variant],
52660
52859
  [ID_SCOPE_ATTR, scope],
52661
52860
  ["data-wf-viewport-conflict", conflict]
52662
52861
  ]);
@@ -52670,6 +52869,7 @@ function renderStandaloneScreen(screen, make, prefix) {
52670
52869
  const marks = attrs([
52671
52870
  ["data-screen", String(screen.index)],
52672
52871
  ["data-screen-name", screen.name],
52872
+ ["data-wf-variant", screen.variant],
52673
52873
  [ID_SCOPE_ATTR, scope],
52674
52874
  ["data-wf-uses-unresolved", screen.miss?.uses],
52675
52875
  ["data-wf-uses-reason", screen.miss?.reason]
@@ -52738,7 +52938,7 @@ function compactRuntimeInteractions(model, interactions) {
52738
52938
  }
52739
52939
  function renderSite(document, options = {}) {
52740
52940
  const prefix = options.classPrefix ?? DEFAULT_PREFIX2;
52741
- document = expandRepeats(document);
52941
+ document = expandRepeats(expandVariants(document));
52742
52942
  const model = buildSiteModel(document);
52743
52943
  const interactionModel = collectInteractions(document);
52744
52944
  const make = (idScope) => new HtmlRenderer({
@@ -52807,6 +53007,7 @@ ${runtime}
52807
53007
 
52808
53008
  // src/renderer/index.ts
52809
53009
  function render(document, options = {}) {
53010
+ document = expandVariants(document);
52810
53011
  const isMultiPage = documentPages(document).length > 1;
52811
53012
  if (isMultiPage) {
52812
53013
  const result = renderCanvas(document, options);
@@ -52816,6 +53017,7 @@ function render(document, options = {}) {
52816
53017
  return renderer.render(document);
52817
53018
  }
52818
53019
  function renderToHtml(document, options = {}) {
53020
+ document = expandVariants(document);
52819
53021
  const { html, css } = render(document, options);
52820
53022
  const prefix = options.classPrefix ?? "wf";
52821
53023
  const isMultiPage = documentPages(document).length > 1;
@@ -52857,6 +53059,7 @@ ${html}
52857
53059
  </html>`;
52858
53060
  }
52859
53061
  function renderToSvg(document, options = {}) {
53062
+ document = expandVariants(document);
52860
53063
  const isMultiPage = documentPages(document).length > 1;
52861
53064
  let width = options.width ?? 800;
52862
53065
  let height = options.height ?? 600;
package/dist/spec.cjs CHANGED
@@ -2166,6 +2166,16 @@ 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
+ },
2174
+ {
2175
+ name: "when",
2176
+ type: "string[]",
2177
+ description: "Variant boards this element is drawn on \u2014 when=loading, or when=[loading, empty] for both"
2178
+ },
2169
2179
  {
2170
2180
  name: "id",
2171
2181
  type: "string",
@@ -2211,6 +2221,13 @@ var BOX_ATTRIBUTES = [
2211
2221
  // Guarded runtime outcomes
2212
2222
  "visibleWhen",
2213
2223
  "enabledWhen",
2224
+ // Build-time variant scope. Listed beside the guards because it reads like
2225
+ // them and is deliberately not one of them: a guard leaves the element in the
2226
+ // markup for the runtime to toggle, `when` decides whether the element is in
2227
+ // that board's markup at all. Every element takes it for the same reason
2228
+ // every element takes a guard — which boards a piece of a screen belongs to
2229
+ // is a property of the piece, not of what kind of piece it is.
2230
+ "when",
2214
2231
  // Spacing
2215
2232
  "p",
2216
2233
  "px",
@@ -2273,7 +2290,15 @@ var COMPONENT_METADATA = {
2273
2290
  // board that path renders *into* — nothing emits the attribute for it and
2274
2291
  // nothing would toggle it, so declaring it would let an author write a
2275
2292
  // guard on a page, pass `validate()`, and have the value silently dropped.
2276
- ...BOX_ATTRIBUTES.filter((name) => name !== "visibleWhen" && name !== "enabledWhen"),
2293
+ // `when` is filtered out alongside the guards, for a reason of its own: a
2294
+ // page *is* a board, so scoping one to a variant would be a board saying
2295
+ // which board it is drawn on. The axis a page declares is `variants`, and
2296
+ // `when` names positions along it — the two sit at different levels and a
2297
+ // page carrying both would be asking `expandVariants` to filter a page
2298
+ // against a name it is itself the source of.
2299
+ ...BOX_ATTRIBUTES.filter(
2300
+ (name) => name !== "visibleWhen" && name !== "enabledWhen" && name !== "when"
2301
+ ),
2277
2302
  ...CONTAINER_ATTRIBUTES,
2278
2303
  "id",
2279
2304
  "title",
@@ -2283,7 +2308,8 @@ var COMPONENT_METADATA = {
2283
2308
  "device",
2284
2309
  "centered",
2285
2310
  "uses",
2286
- "states"
2311
+ "states",
2312
+ "variants"
2287
2313
  ],
2288
2314
  hasChildren: true,
2289
2315
  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,16 @@ 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
+ },
2127
+ {
2128
+ name: "when",
2129
+ type: "string[]",
2130
+ description: "Variant boards this element is drawn on \u2014 when=loading, or when=[loading, empty] for both"
2131
+ },
2122
2132
  {
2123
2133
  name: "id",
2124
2134
  type: "string",
@@ -2164,6 +2174,13 @@ var BOX_ATTRIBUTES = [
2164
2174
  // Guarded runtime outcomes
2165
2175
  "visibleWhen",
2166
2176
  "enabledWhen",
2177
+ // Build-time variant scope. Listed beside the guards because it reads like
2178
+ // them and is deliberately not one of them: a guard leaves the element in the
2179
+ // markup for the runtime to toggle, `when` decides whether the element is in
2180
+ // that board's markup at all. Every element takes it for the same reason
2181
+ // every element takes a guard — which boards a piece of a screen belongs to
2182
+ // is a property of the piece, not of what kind of piece it is.
2183
+ "when",
2167
2184
  // Spacing
2168
2185
  "p",
2169
2186
  "px",
@@ -2226,7 +2243,15 @@ var COMPONENT_METADATA = {
2226
2243
  // board that path renders *into* — nothing emits the attribute for it and
2227
2244
  // nothing would toggle it, so declaring it would let an author write a
2228
2245
  // guard on a page, pass `validate()`, and have the value silently dropped.
2229
- ...BOX_ATTRIBUTES.filter((name) => name !== "visibleWhen" && name !== "enabledWhen"),
2246
+ // `when` is filtered out alongside the guards, for a reason of its own: a
2247
+ // page *is* a board, so scoping one to a variant would be a board saying
2248
+ // which board it is drawn on. The axis a page declares is `variants`, and
2249
+ // `when` names positions along it — the two sit at different levels and a
2250
+ // page carrying both would be asking `expandVariants` to filter a page
2251
+ // against a name it is itself the source of.
2252
+ ...BOX_ATTRIBUTES.filter(
2253
+ (name) => name !== "visibleWhen" && name !== "enabledWhen" && name !== "when"
2254
+ ),
2230
2255
  ...CONTAINER_ATTRIBUTES,
2231
2256
  "id",
2232
2257
  "title",
@@ -2236,7 +2261,8 @@ var COMPONENT_METADATA = {
2236
2261
  "device",
2237
2262
  "centered",
2238
2263
  "uses",
2239
- "states"
2264
+ "states",
2265
+ "variants"
2240
2266
  ],
2241
2267
  hasChildren: true,
2242
2268
  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."
@@ -95,7 +95,7 @@ interface AppearanceProps {
95
95
  border?: boolean;
96
96
  rounded?: boolean;
97
97
  }
98
- interface CommonProps extends SpacingProps, SizeProps, FlexProps, GridProps, PositionProps, AppearanceProps, GuardedOutcomeProps {
98
+ interface CommonProps extends SpacingProps, SizeProps, FlexProps, GridProps, PositionProps, AppearanceProps, GuardedOutcomeProps, VariantScopedProps {
99
99
  }
100
100
  /**
101
101
  * Interactive properties for components that can trigger actions.
@@ -121,6 +121,38 @@ interface GuardedOutcomeProps {
121
121
  visibleWhen?: StateGuard;
122
122
  enabledWhen?: StateGuard;
123
123
  }
124
+ /**
125
+ * Which variant boards an element is drawn on — `when=loading`, `when=[a, b]`.
126
+ *
127
+ * Deliberately **not** a member of {@link GuardedOutcomeProps}, though the two
128
+ * read alike. A guarded outcome is a runtime fact: the element exists on every
129
+ * board, the renderer emits `data-wf-visible-when`, and the site runtime turns
130
+ * it on and off as state changes. `when` is a build-time fact: the element is
131
+ * *absent* from the markup of every board it does not name, so nothing can
132
+ * toggle it back and no state change reaches it.
133
+ *
134
+ * They are therefore orthogonal rather than alternatives, and one element may
135
+ * carry both — `section when=ready visibleWhen={ state=open, equals=true }`
136
+ * means "only on the ready board, and there only while `open`". Folding `when`
137
+ * into the guarded-outcome interface would say the two are one concept, and the
138
+ * first author to write both would find the pair collapsing into whichever the
139
+ * renderer read last.
140
+ */
141
+ interface VariantScopedProps {
142
+ /**
143
+ * The variant name, or names, this element belongs to.
144
+ *
145
+ * A list is a disjunction: `when=[loading, empty]` draws the element on the
146
+ * loading board and on the empty board. That is the whole reason the list
147
+ * form exists — a `visibleWhen` guard has only `equals`, so a block two
148
+ * conditions share had to be written once per condition, and a header common
149
+ * to three states was three copies that could drift apart.
150
+ *
151
+ * Absent means "every board", which is what keeps documents that declare no
152
+ * variants rendering exactly as they did.
153
+ */
154
+ when?: string | string[];
155
+ }
124
156
  type InteractionEffect = {
125
157
  kind: 'navigate';
126
158
  target: string;
@@ -235,6 +267,37 @@ interface PageNode extends BaseNode, CommonProps {
235
267
  uses?: string;
236
268
  /** Application state declarations contributed by this screen module. */
237
269
  states?: StateDeclaration[];
270
+ /**
271
+ * Named state variants of this screen — `variants=[loading, empty, ready]`.
272
+ *
273
+ * Each name draws the page again as a screen of its own, so a document
274
+ * declaring three variants renders three independent boards rather than one
275
+ * board with a toggle in it. That is the whole difference from {@link states}:
276
+ * a state is a runtime value the site runtime flips and guards read, so the
277
+ * transitions between states have to exist as UI somewhere; a variant is an
278
+ * axis of the *artifact*, so the states appear side by side and nothing in
279
+ * the wireframe has to offer a way to switch between them. A reviewer of a
280
+ * variant sheet never mistakes a state-switching control for a product
281
+ * feature, because there is none to mistake.
282
+ *
283
+ * Deliberately page-local, where `states` is collected document-wide: a
284
+ * variant only means anything relative to the page it varies, and a document
285
+ * scope would make one page's variant list multiply every other page's
286
+ * screens. Names are free-form identifiers — the language fixes no vocabulary
287
+ * of states, because which states a screen has is a property of that screen.
288
+ */
289
+ variants?: string[];
290
+ /**
291
+ * Which variant this page *is* — set by `expandVariants`, never by an author.
292
+ *
293
+ * The authored `variants` list and this are the two ends of the same
294
+ * expansion: a page carries the list before it, and each page it expands into
295
+ * carries one name from that list and no list. The printer therefore only
296
+ * writes `variants`, and a document that has been expanded prints back as the
297
+ * boards it became rather than as the fold it came from — the same asymmetry
298
+ * `repeat` has between its node and its copies.
299
+ */
300
+ variant?: string;
238
301
  children: AnyNode[];
239
302
  }
240
303
  /**
@@ -830,4 +893,4 @@ type LeafNode = TextContentNode | InputComponentNode | ButtonNode | DisplayNode
830
893
  type AnyNode = ContainerNode | LeafNode;
831
894
  type NodeType = 'Document' | 'Page' | 'Layout' | 'Component' | 'ComponentUse' | 'Slot' | 'Repeat' | 'Header' | 'Main' | 'Footer' | 'Sidebar' | 'Section' | 'Row' | 'Col' | 'Stack' | 'Relative' | 'Card' | 'Modal' | 'Drawer' | 'Accordion' | 'Text' | 'Title' | 'Link' | 'Input' | 'Textarea' | 'Select' | 'Checkbox' | 'Radio' | 'Switch' | 'Slider' | 'Button' | 'Image' | 'Placeholder' | 'Avatar' | 'Badge' | 'Icon' | 'Table' | 'List' | 'Alert' | 'Toast' | 'Progress' | 'Spinner' | 'Tooltip' | 'Popover' | 'Dropdown' | 'Nav' | 'Tabs' | 'Breadcrumb' | 'Divider' | 'Marker' | 'Annotations' | 'AnnotationItem';
832
895
 
833
- export type { IconNode as $, AccordionNode as A, BadgeNode as B, CardNode as C, ComponentInputValue as D, ComponentParameter as E, ComponentParameterType as F, ComponentSlotFill as G, ComponentUseNode as H, ContainerComponentNode as I, ContainerNode as J, DataNode as K, DefinitionNode as L, DirectionValue as M, DisplayNode as N, DividerComponentNode as O, DrawerNode as P, DrawerPosition as Q, DropdownItemNode as R, DropdownNode as S, FeedbackNode as T, FlexProps as U, FooterNode as V, GridNode as W, GridProps as X, GuardedOutcomeProps as Y, HeaderNode as Z, HeightValue as _, AlertNode as a, TextNode as a$, IconSize as a0, IconSizeToken as a1, ImageNode as a2, InputComponentNode as a3, InputNode as a4, InputType as a5, InteractionEffect as a6, InteractionHandler as a7, InteractiveProps as a8, JustifyValue as a9, RepeatNode as aA, RowNode as aB, SectionNode as aC, SelectNode as aD, SelectOption as aE, ShadowValue as aF, SidebarNode as aG, SizeProps as aH, SliderNode as aI, SlotNode as aJ, SourceLocation as aK, SpacingProps as aL, SpacingValue as aM, SpinnerNode as aN, SpinnerSize as aO, SpinnerSizeToken as aP, StackNode as aQ, StateDeclaration as aR, StateGuard as aS, StateValue as aT, StateValueType as aU, SwitchNode as aV, TabNode as aW, TableNode as aX, TabsNode as aY, TextAlign as aZ, TextContentNode as a_, LayoutDefinitionNode as aa, LayoutNode as ab, LeafNode as ac, LinkNode as ad, ListItemNode as ae, ListNode as af, MainNode as ag, MarkerColor as ah, MarkerNode as ai, ModalNode as aj, NavBlockItem as ak, NavChild as al, NavGroupNode as am, NavItem as an, NavNode as ao, NavigationNode as ap, NodeType as aq, OverlayNode as ar, PageNode as as, PlaceholderNode as at, PopoverNode as au, Position as av, PositionProps as aw, ProgressNode as ax, RadioNode as ay, RelativeNode as az, AlertVariant as b, TextSize as b0, TextSizeToken as b1, TextWeight as b2, TextareaNode as b3, TitleLevel as b4, TitleNode as b5, ToastNode as b6, ToastPosition as b7, TooltipNode as b8, TooltipPosition as b9, TopLevelNode as ba, ValueWithUnit as bb, WidthValue as bc, WireframeDocument as bd, AlignValue as c, AnchorPosition as d, AnnotationItemNode as e, AnnotationNode as f, AnnotationsNode as g, AnyNode as h, AppearanceProps as i, AvatarNode as j, AvatarSize as k, AvatarSizeToken as l, BadgeSize as m, BadgeSizeToken as n, BadgeVariant as o, BaseNode as p, BreadcrumbItem as q, BreadcrumbNode as r, ButtonNode as s, ButtonSize as t, ButtonSizeToken as u, ButtonVariant as v, CheckboxNode as w, ColNode as x, CommonProps as y, ComponentDefinitionNode as z };
896
+ export type { IconNode as $, AccordionNode as A, BadgeNode as B, CardNode as C, ComponentInputValue as D, ComponentParameter as E, ComponentParameterType as F, ComponentSlotFill as G, ComponentUseNode as H, ContainerComponentNode as I, ContainerNode as J, DataNode as K, DefinitionNode as L, DirectionValue as M, DisplayNode as N, DividerComponentNode as O, DrawerNode as P, DrawerPosition as Q, DropdownItemNode as R, DropdownNode as S, FeedbackNode as T, FlexProps as U, FooterNode as V, GridNode as W, GridProps as X, GuardedOutcomeProps as Y, HeaderNode as Z, HeightValue as _, AlertNode as a, TextNode as a$, IconSize as a0, IconSizeToken as a1, ImageNode as a2, InputComponentNode as a3, InputNode as a4, InputType as a5, InteractionEffect as a6, InteractionHandler as a7, InteractiveProps as a8, JustifyValue as a9, RepeatNode as aA, RowNode as aB, SectionNode as aC, SelectNode as aD, SelectOption as aE, ShadowValue as aF, SidebarNode as aG, SizeProps as aH, SliderNode as aI, SlotNode as aJ, SourceLocation as aK, SpacingProps as aL, SpacingValue as aM, SpinnerNode as aN, SpinnerSize as aO, SpinnerSizeToken as aP, StackNode as aQ, StateDeclaration as aR, StateGuard as aS, StateValue as aT, StateValueType as aU, SwitchNode as aV, TabNode as aW, TableNode as aX, TabsNode as aY, TextAlign as aZ, TextContentNode as a_, LayoutDefinitionNode as aa, LayoutNode as ab, LeafNode as ac, LinkNode as ad, ListItemNode as ae, ListNode as af, MainNode as ag, MarkerColor as ah, MarkerNode as ai, ModalNode as aj, NavBlockItem as ak, NavChild as al, NavGroupNode as am, NavItem as an, NavNode as ao, NavigationNode as ap, NodeType as aq, OverlayNode as ar, PageNode as as, PlaceholderNode as at, PopoverNode as au, Position as av, PositionProps as aw, ProgressNode as ax, RadioNode as ay, RelativeNode as az, AlertVariant as b, TextSize as b0, TextSizeToken as b1, TextWeight as b2, TextareaNode as b3, TitleLevel as b4, TitleNode as b5, ToastNode as b6, ToastPosition as b7, TooltipNode as b8, TooltipPosition as b9, TopLevelNode as ba, ValueWithUnit as bb, VariantScopedProps as bc, WidthValue as bd, WireframeDocument as be, AlignValue as c, AnchorPosition as d, AnnotationItemNode as e, AnnotationNode as f, AnnotationsNode as g, AnyNode as h, AppearanceProps as i, AvatarNode as j, AvatarSize as k, AvatarSizeToken as l, BadgeSize as m, BadgeSizeToken as n, BadgeVariant as o, BaseNode as p, BreadcrumbItem as q, BreadcrumbNode as r, ButtonNode as s, ButtonSize as t, ButtonSizeToken as u, ButtonVariant as v, CheckboxNode as w, ColNode as x, CommonProps as y, ComponentDefinitionNode as z };
@@ -95,7 +95,7 @@ interface AppearanceProps {
95
95
  border?: boolean;
96
96
  rounded?: boolean;
97
97
  }
98
- interface CommonProps extends SpacingProps, SizeProps, FlexProps, GridProps, PositionProps, AppearanceProps, GuardedOutcomeProps {
98
+ interface CommonProps extends SpacingProps, SizeProps, FlexProps, GridProps, PositionProps, AppearanceProps, GuardedOutcomeProps, VariantScopedProps {
99
99
  }
100
100
  /**
101
101
  * Interactive properties for components that can trigger actions.
@@ -121,6 +121,38 @@ interface GuardedOutcomeProps {
121
121
  visibleWhen?: StateGuard;
122
122
  enabledWhen?: StateGuard;
123
123
  }
124
+ /**
125
+ * Which variant boards an element is drawn on — `when=loading`, `when=[a, b]`.
126
+ *
127
+ * Deliberately **not** a member of {@link GuardedOutcomeProps}, though the two
128
+ * read alike. A guarded outcome is a runtime fact: the element exists on every
129
+ * board, the renderer emits `data-wf-visible-when`, and the site runtime turns
130
+ * it on and off as state changes. `when` is a build-time fact: the element is
131
+ * *absent* from the markup of every board it does not name, so nothing can
132
+ * toggle it back and no state change reaches it.
133
+ *
134
+ * They are therefore orthogonal rather than alternatives, and one element may
135
+ * carry both — `section when=ready visibleWhen={ state=open, equals=true }`
136
+ * means "only on the ready board, and there only while `open`". Folding `when`
137
+ * into the guarded-outcome interface would say the two are one concept, and the
138
+ * first author to write both would find the pair collapsing into whichever the
139
+ * renderer read last.
140
+ */
141
+ interface VariantScopedProps {
142
+ /**
143
+ * The variant name, or names, this element belongs to.
144
+ *
145
+ * A list is a disjunction: `when=[loading, empty]` draws the element on the
146
+ * loading board and on the empty board. That is the whole reason the list
147
+ * form exists — a `visibleWhen` guard has only `equals`, so a block two
148
+ * conditions share had to be written once per condition, and a header common
149
+ * to three states was three copies that could drift apart.
150
+ *
151
+ * Absent means "every board", which is what keeps documents that declare no
152
+ * variants rendering exactly as they did.
153
+ */
154
+ when?: string | string[];
155
+ }
124
156
  type InteractionEffect = {
125
157
  kind: 'navigate';
126
158
  target: string;
@@ -235,6 +267,37 @@ interface PageNode extends BaseNode, CommonProps {
235
267
  uses?: string;
236
268
  /** Application state declarations contributed by this screen module. */
237
269
  states?: StateDeclaration[];
270
+ /**
271
+ * Named state variants of this screen — `variants=[loading, empty, ready]`.
272
+ *
273
+ * Each name draws the page again as a screen of its own, so a document
274
+ * declaring three variants renders three independent boards rather than one
275
+ * board with a toggle in it. That is the whole difference from {@link states}:
276
+ * a state is a runtime value the site runtime flips and guards read, so the
277
+ * transitions between states have to exist as UI somewhere; a variant is an
278
+ * axis of the *artifact*, so the states appear side by side and nothing in
279
+ * the wireframe has to offer a way to switch between them. A reviewer of a
280
+ * variant sheet never mistakes a state-switching control for a product
281
+ * feature, because there is none to mistake.
282
+ *
283
+ * Deliberately page-local, where `states` is collected document-wide: a
284
+ * variant only means anything relative to the page it varies, and a document
285
+ * scope would make one page's variant list multiply every other page's
286
+ * screens. Names are free-form identifiers — the language fixes no vocabulary
287
+ * of states, because which states a screen has is a property of that screen.
288
+ */
289
+ variants?: string[];
290
+ /**
291
+ * Which variant this page *is* — set by `expandVariants`, never by an author.
292
+ *
293
+ * The authored `variants` list and this are the two ends of the same
294
+ * expansion: a page carries the list before it, and each page it expands into
295
+ * carries one name from that list and no list. The printer therefore only
296
+ * writes `variants`, and a document that has been expanded prints back as the
297
+ * boards it became rather than as the fold it came from — the same asymmetry
298
+ * `repeat` has between its node and its copies.
299
+ */
300
+ variant?: string;
238
301
  children: AnyNode[];
239
302
  }
240
303
  /**
@@ -830,4 +893,4 @@ type LeafNode = TextContentNode | InputComponentNode | ButtonNode | DisplayNode
830
893
  type AnyNode = ContainerNode | LeafNode;
831
894
  type NodeType = 'Document' | 'Page' | 'Layout' | 'Component' | 'ComponentUse' | 'Slot' | 'Repeat' | 'Header' | 'Main' | 'Footer' | 'Sidebar' | 'Section' | 'Row' | 'Col' | 'Stack' | 'Relative' | 'Card' | 'Modal' | 'Drawer' | 'Accordion' | 'Text' | 'Title' | 'Link' | 'Input' | 'Textarea' | 'Select' | 'Checkbox' | 'Radio' | 'Switch' | 'Slider' | 'Button' | 'Image' | 'Placeholder' | 'Avatar' | 'Badge' | 'Icon' | 'Table' | 'List' | 'Alert' | 'Toast' | 'Progress' | 'Spinner' | 'Tooltip' | 'Popover' | 'Dropdown' | 'Nav' | 'Tabs' | 'Breadcrumb' | 'Divider' | 'Marker' | 'Annotations' | 'AnnotationItem';
832
895
 
833
- export type { IconNode as $, AccordionNode as A, BadgeNode as B, CardNode as C, ComponentInputValue as D, ComponentParameter as E, ComponentParameterType as F, ComponentSlotFill as G, ComponentUseNode as H, ContainerComponentNode as I, ContainerNode as J, DataNode as K, DefinitionNode as L, DirectionValue as M, DisplayNode as N, DividerComponentNode as O, DrawerNode as P, DrawerPosition as Q, DropdownItemNode as R, DropdownNode as S, FeedbackNode as T, FlexProps as U, FooterNode as V, GridNode as W, GridProps as X, GuardedOutcomeProps as Y, HeaderNode as Z, HeightValue as _, AlertNode as a, TextNode as a$, IconSize as a0, IconSizeToken as a1, ImageNode as a2, InputComponentNode as a3, InputNode as a4, InputType as a5, InteractionEffect as a6, InteractionHandler as a7, InteractiveProps as a8, JustifyValue as a9, RepeatNode as aA, RowNode as aB, SectionNode as aC, SelectNode as aD, SelectOption as aE, ShadowValue as aF, SidebarNode as aG, SizeProps as aH, SliderNode as aI, SlotNode as aJ, SourceLocation as aK, SpacingProps as aL, SpacingValue as aM, SpinnerNode as aN, SpinnerSize as aO, SpinnerSizeToken as aP, StackNode as aQ, StateDeclaration as aR, StateGuard as aS, StateValue as aT, StateValueType as aU, SwitchNode as aV, TabNode as aW, TableNode as aX, TabsNode as aY, TextAlign as aZ, TextContentNode as a_, LayoutDefinitionNode as aa, LayoutNode as ab, LeafNode as ac, LinkNode as ad, ListItemNode as ae, ListNode as af, MainNode as ag, MarkerColor as ah, MarkerNode as ai, ModalNode as aj, NavBlockItem as ak, NavChild as al, NavGroupNode as am, NavItem as an, NavNode as ao, NavigationNode as ap, NodeType as aq, OverlayNode as ar, PageNode as as, PlaceholderNode as at, PopoverNode as au, Position as av, PositionProps as aw, ProgressNode as ax, RadioNode as ay, RelativeNode as az, AlertVariant as b, TextSize as b0, TextSizeToken as b1, TextWeight as b2, TextareaNode as b3, TitleLevel as b4, TitleNode as b5, ToastNode as b6, ToastPosition as b7, TooltipNode as b8, TooltipPosition as b9, TopLevelNode as ba, ValueWithUnit as bb, WidthValue as bc, WireframeDocument as bd, AlignValue as c, AnchorPosition as d, AnnotationItemNode as e, AnnotationNode as f, AnnotationsNode as g, AnyNode as h, AppearanceProps as i, AvatarNode as j, AvatarSize as k, AvatarSizeToken as l, BadgeSize as m, BadgeSizeToken as n, BadgeVariant as o, BaseNode as p, BreadcrumbItem as q, BreadcrumbNode as r, ButtonNode as s, ButtonSize as t, ButtonSizeToken as u, ButtonVariant as v, CheckboxNode as w, ColNode as x, CommonProps as y, ComponentDefinitionNode as z };
896
+ export type { IconNode as $, AccordionNode as A, BadgeNode as B, CardNode as C, ComponentInputValue as D, ComponentParameter as E, ComponentParameterType as F, ComponentSlotFill as G, ComponentUseNode as H, ContainerComponentNode as I, ContainerNode as J, DataNode as K, DefinitionNode as L, DirectionValue as M, DisplayNode as N, DividerComponentNode as O, DrawerNode as P, DrawerPosition as Q, DropdownItemNode as R, DropdownNode as S, FeedbackNode as T, FlexProps as U, FooterNode as V, GridNode as W, GridProps as X, GuardedOutcomeProps as Y, HeaderNode as Z, HeightValue as _, AlertNode as a, TextNode as a$, IconSize as a0, IconSizeToken as a1, ImageNode as a2, InputComponentNode as a3, InputNode as a4, InputType as a5, InteractionEffect as a6, InteractionHandler as a7, InteractiveProps as a8, JustifyValue as a9, RepeatNode as aA, RowNode as aB, SectionNode as aC, SelectNode as aD, SelectOption as aE, ShadowValue as aF, SidebarNode as aG, SizeProps as aH, SliderNode as aI, SlotNode as aJ, SourceLocation as aK, SpacingProps as aL, SpacingValue as aM, SpinnerNode as aN, SpinnerSize as aO, SpinnerSizeToken as aP, StackNode as aQ, StateDeclaration as aR, StateGuard as aS, StateValue as aT, StateValueType as aU, SwitchNode as aV, TabNode as aW, TableNode as aX, TabsNode as aY, TextAlign as aZ, TextContentNode as a_, LayoutDefinitionNode as aa, LayoutNode as ab, LeafNode as ac, LinkNode as ad, ListItemNode as ae, ListNode as af, MainNode as ag, MarkerColor as ah, MarkerNode as ai, ModalNode as aj, NavBlockItem as ak, NavChild as al, NavGroupNode as am, NavItem as an, NavNode as ao, NavigationNode as ap, NodeType as aq, OverlayNode as ar, PageNode as as, PlaceholderNode as at, PopoverNode as au, Position as av, PositionProps as aw, ProgressNode as ax, RadioNode as ay, RelativeNode as az, AlertVariant as b, TextSize as b0, TextSizeToken as b1, TextWeight as b2, TextareaNode as b3, TitleLevel as b4, TitleNode as b5, ToastNode as b6, ToastPosition as b7, TooltipNode as b8, TooltipPosition as b9, TopLevelNode as ba, ValueWithUnit as bb, VariantScopedProps as bc, WidthValue as bd, WireframeDocument as be, AlignValue as c, AnchorPosition as d, AnnotationItemNode as e, AnnotationNode as f, AnnotationsNode as g, AnyNode as h, AppearanceProps as i, AvatarNode as j, AvatarSize as k, AvatarSizeToken as l, BadgeSize as m, BadgeSizeToken as n, BadgeVariant as o, BaseNode as p, BreadcrumbItem as q, BreadcrumbNode as r, ButtonNode as s, ButtonSize as t, ButtonSizeToken as u, ButtonVariant as v, CheckboxNode as w, ColNode as x, CommonProps as y, ComponentDefinitionNode as z };
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.9",
4
4
  "description": "Core parser and renderer for wireweave",
5
5
  "type": "module",
6
6
  "sideEffects": false,