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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.js CHANGED
@@ -432,6 +432,102 @@ function expandRepeats(document) {
432
432
  };
433
433
  }
434
434
 
435
+ // src/ast/filter-variant-scope.ts
436
+ function variantScope(node) {
437
+ const declared = node.when;
438
+ if (declared === void 0) return void 0;
439
+ const raw = Array.isArray(declared) ? declared : [declared];
440
+ const seen = /* @__PURE__ */ new Set();
441
+ const names = [];
442
+ for (const item of raw) {
443
+ if (typeof item !== "string") continue;
444
+ const name = item.trim();
445
+ if (name.length === 0 || seen.has(name)) continue;
446
+ seen.add(name);
447
+ names.push(name);
448
+ }
449
+ return names;
450
+ }
451
+ function childList(value) {
452
+ const children = value?.children;
453
+ return Array.isArray(children) ? children : void 0;
454
+ }
455
+ function asNode(value) {
456
+ return value !== null && typeof value === "object" && "type" in value ? value : void 0;
457
+ }
458
+ function filterChildList(children, variant) {
459
+ return children.flatMap((child) => {
460
+ const node = asNode(child);
461
+ if (node === void 0) return [child];
462
+ const kept = filterNode(node, variant);
463
+ return kept === void 0 ? [] : [kept];
464
+ });
465
+ }
466
+ function containsScope(node) {
467
+ if (node.when !== void 0) return true;
468
+ for (const child of childList(node) ?? []) {
469
+ const nested = asNode(child);
470
+ if (nested !== void 0 && containsScope(nested)) return true;
471
+ }
472
+ const fills = node.fills;
473
+ if (Array.isArray(fills)) {
474
+ for (const fill of fills) {
475
+ for (const child of childList(fill) ?? []) {
476
+ const nested = asNode(child);
477
+ if (nested !== void 0 && containsScope(nested)) return true;
478
+ }
479
+ }
480
+ }
481
+ return false;
482
+ }
483
+ function filterNode(node, variant) {
484
+ const scope = variantScope(node);
485
+ if (scope !== void 0) {
486
+ if (variant === void 0 || !scope.includes(variant)) return void 0;
487
+ }
488
+ const nested = containsScope(node);
489
+ if (scope === void 0 && !nested) return node;
490
+ const result = {};
491
+ for (const [key, value] of Object.entries(node)) {
492
+ if (key === "when") continue;
493
+ result[key] = value;
494
+ }
495
+ const children = childList(node);
496
+ if (children !== void 0) {
497
+ result.children = filterChildList(children, variant);
498
+ }
499
+ const fills = node.fills;
500
+ if (Array.isArray(fills)) {
501
+ result.fills = fills.map((fill) => {
502
+ const fillChildren = childList(fill);
503
+ if (fillChildren === void 0) return fill;
504
+ return {
505
+ ...fill,
506
+ children: filterChildList(fillChildren, variant)
507
+ };
508
+ });
509
+ }
510
+ return result;
511
+ }
512
+ function filterVariantScope(children, variant) {
513
+ if (!children.some((child) => containsScope(child))) return children;
514
+ return children.flatMap((child) => {
515
+ const kept = filterNode(child, variant);
516
+ return kept === void 0 ? [] : [kept];
517
+ });
518
+ }
519
+ function filterUnscopedPages(document) {
520
+ let changed = false;
521
+ const children = document.children.map((child) => {
522
+ if (child.type !== "Page" || child.variant !== void 0) return child;
523
+ const filtered = filterVariantScope(child.children, void 0);
524
+ if (filtered === child.children) return child;
525
+ changed = true;
526
+ return { ...child, children: filtered };
527
+ });
528
+ return changed ? { ...document, children } : document;
529
+ }
530
+
435
531
  // src/ast/expand-variants.ts
436
532
  function cloneNode3(value) {
437
533
  if (Array.isArray(value)) return value.map(cloneNode3);
@@ -461,18 +557,22 @@ function hasVariants(document) {
461
557
  return document.children.some((child) => child.type === "Page" && variantNames(child).length > 0);
462
558
  }
463
559
  function expandVariants(document) {
464
- if (!hasVariants(document)) return document;
560
+ if (!hasVariants(document)) return filterUnscopedPages(document);
465
561
  return {
466
562
  ...document,
467
563
  children: document.children.flatMap((child) => {
468
564
  if (child.type !== "Page") return [child];
469
565
  const names = variantNames(child);
470
- if (names.length === 0) return [child];
566
+ if (names.length === 0) {
567
+ const filtered = filterVariantScope(child.children, void 0);
568
+ return [filtered === child.children ? child : { ...child, children: filtered }];
569
+ }
471
570
  return names.map((variant, position) => {
472
571
  const clone = cloneNode3(child);
473
572
  delete clone.variants;
474
573
  clone.variant = variant;
475
574
  if (position > 0) delete clone.states;
575
+ clone.children = filterVariantScope(clone.children, variant);
476
576
  return clone;
477
577
  });
478
578
  })
@@ -13170,6 +13270,11 @@ var ATTRIBUTE_SPECS = [
13170
13270
  type: "string[]",
13171
13271
  description: "Named state variants of this page \u2014 each one renders the page again as a screen of its own"
13172
13272
  },
13273
+ {
13274
+ name: "when",
13275
+ type: "string[]",
13276
+ description: "Variant boards this element is drawn on \u2014 when=loading, or when=[loading, empty] for both"
13277
+ },
13173
13278
  {
13174
13279
  name: "id",
13175
13280
  type: "string",
@@ -13215,6 +13320,13 @@ var BOX_ATTRIBUTES = [
13215
13320
  // Guarded runtime outcomes
13216
13321
  "visibleWhen",
13217
13322
  "enabledWhen",
13323
+ // Build-time variant scope. Listed beside the guards because it reads like
13324
+ // them and is deliberately not one of them: a guard leaves the element in the
13325
+ // markup for the runtime to toggle, `when` decides whether the element is in
13326
+ // that board's markup at all. Every element takes it for the same reason
13327
+ // every element takes a guard — which boards a piece of a screen belongs to
13328
+ // is a property of the piece, not of what kind of piece it is.
13329
+ "when",
13218
13330
  // Spacing
13219
13331
  "p",
13220
13332
  "px",
@@ -13277,7 +13389,15 @@ var COMPONENT_METADATA = {
13277
13389
  // board that path renders *into* — nothing emits the attribute for it and
13278
13390
  // nothing would toggle it, so declaring it would let an author write a
13279
13391
  // guard on a page, pass `validate()`, and have the value silently dropped.
13280
- ...BOX_ATTRIBUTES.filter((name) => name !== "visibleWhen" && name !== "enabledWhen"),
13392
+ // `when` is filtered out alongside the guards, for a reason of its own: a
13393
+ // page *is* a board, so scoping one to a variant would be a board saying
13394
+ // which board it is drawn on. The axis a page declares is `variants`, and
13395
+ // `when` names positions along it — the two sit at different levels and a
13396
+ // page carrying both would be asking `expandVariants` to filter a page
13397
+ // against a name it is itself the source of.
13398
+ ...BOX_ATTRIBUTES.filter(
13399
+ (name) => name !== "visibleWhen" && name !== "enabledWhen" && name !== "when"
13400
+ ),
13281
13401
  ...CONTAINER_ATTRIBUTES,
13282
13402
  "id",
13283
13403
  "title",
@@ -63509,6 +63629,63 @@ function checkDuplicateDeclarations(ast, addError) {
63509
63629
  }
63510
63630
  return true;
63511
63631
  }
63632
+ function checkVariantScopes(ast, addError) {
63633
+ const children = ast.children ?? [];
63634
+ for (let index = 0; index < children.length; index++) {
63635
+ const page = children[index];
63636
+ if (page?.type !== "Page") continue;
63637
+ const declared = new Set(
63638
+ (Array.isArray(page.variants) ? page.variants : []).filter((name) => typeof name === "string").map((name) => name.trim()).filter((name) => name.length > 0)
63639
+ );
63640
+ const visit = (node, path, inherited) => {
63641
+ const scope = variantScope(node);
63642
+ let reachable = inherited;
63643
+ if (scope !== void 0) {
63644
+ const unknown = scope.filter((name) => !declared.has(name));
63645
+ if (unknown.length > 0) {
63646
+ const message = declared.size === 0 ? `Unknown variant ${unknown.map((n) => `"${n}"`).join(", ")} in when= \u2014 this page declares no variants=, so the element is drawn on no board` : `Unknown variant ${unknown.map((n) => `"${n}"`).join(", ")} in when= \u2014 this page declares [${[...declared].join(", ")}]`;
63647
+ if (!addError({
63648
+ message,
63649
+ path,
63650
+ nodeType: node.type,
63651
+ attribute: "when",
63652
+ location: node.loc ? { line: node.loc.start.line, column: node.loc.start.column } : void 0
63653
+ })) {
63654
+ return false;
63655
+ }
63656
+ }
63657
+ const named = new Set(scope.filter((name) => declared.has(name)));
63658
+ reachable = inherited === void 0 ? named : new Set([...named].filter((n) => inherited.has(n)));
63659
+ if (unknown.length === 0 && inherited !== void 0 && reachable.size === 0) {
63660
+ if (!addError({
63661
+ message: `Contradictory when= [${scope.join(", ")}] \u2014 an enclosing element is scoped to [${[...inherited].join(", ")}], so no board draws both and this element is never rendered`,
63662
+ path,
63663
+ nodeType: node.type,
63664
+ attribute: "when",
63665
+ location: node.loc ? { line: node.loc.start.line, column: node.loc.start.column } : void 0
63666
+ })) {
63667
+ return false;
63668
+ }
63669
+ }
63670
+ }
63671
+ const kids = "children" in node && Array.isArray(node.children) ? node.children : [];
63672
+ for (let i = 0; i < kids.length; i++) {
63673
+ const child = kids[i];
63674
+ if (child && typeof child === "object" && "type" in child) {
63675
+ if (!visit(child, `${path}.children[${i}]`, reachable)) return false;
63676
+ }
63677
+ }
63678
+ return true;
63679
+ };
63680
+ for (let i = 0; i < page.children.length; i++) {
63681
+ const child = page.children[i];
63682
+ if (child && typeof child === "object" && "type" in child) {
63683
+ if (!visit(child, `pages[${index}].children[${i}]`, void 0)) return false;
63684
+ }
63685
+ }
63686
+ }
63687
+ return true;
63688
+ }
63512
63689
  function checkDuplicateElementIds(ast, addError) {
63513
63690
  const CONTEXT_OF = {
63514
63691
  Page: "page",
@@ -63789,6 +63966,7 @@ function validate(ast, options = {}) {
63789
63966
  }
63790
63967
  if (shouldContinue) shouldContinue = checkComponentContracts(ast, addError);
63791
63968
  if (shouldContinue) shouldContinue = checkDuplicateDeclarations(ast, addError);
63969
+ if (shouldContinue) shouldContinue = checkVariantScopes(ast, addError);
63792
63970
  if (shouldContinue) checkDuplicateElementIds(ast, addError);
63793
63971
  const valid = errors.length === 0;
63794
63972
  return {
@@ -65818,6 +65996,8 @@ export {
65818
65996
  extractAllScreenFields,
65819
65997
  extractScreenFields,
65820
65998
  extractScreenTransitions,
65999
+ filterUnscopedPages,
66000
+ filterVariantScope,
65821
66001
  find,
65822
66002
  findAll,
65823
66003
  findByType,
@@ -65930,6 +66110,7 @@ export {
65930
66110
  resolveViewport,
65931
66111
  tryParse,
65932
66112
  validate,
66113
+ variantScope,
65933
66114
  walk,
65934
66115
  walkDocument,
65935
66116
  wrapInPreviewContainer
package/dist/parser.d.cts CHANGED
@@ -1,4 +1,4 @@
1
- import { aK as SourceLocation, bd as WireframeDocument } from './types-DfiCKOPE.cjs';
1
+ import { aK as SourceLocation, be as WireframeDocument } from './types-vhPCZpAW.cjs';
2
2
 
3
3
  /**
4
4
  * Parser module for wireweave
package/dist/parser.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- import { aK as SourceLocation, bd as WireframeDocument } from './types-DfiCKOPE.js';
1
+ import { aK as SourceLocation, be as WireframeDocument } from './types-vhPCZpAW.js';
2
2
 
3
3
  /**
4
4
  * Parser module for wireweave
package/dist/renderer.cjs CHANGED
@@ -87,6 +87,102 @@ function documentDefinitions(document) {
87
87
  );
88
88
  }
89
89
 
90
+ // src/ast/filter-variant-scope.ts
91
+ function variantScope(node) {
92
+ const declared = node.when;
93
+ if (declared === void 0) return void 0;
94
+ const raw = Array.isArray(declared) ? declared : [declared];
95
+ const seen = /* @__PURE__ */ new Set();
96
+ const names = [];
97
+ for (const item of raw) {
98
+ if (typeof item !== "string") continue;
99
+ const name = item.trim();
100
+ if (name.length === 0 || seen.has(name)) continue;
101
+ seen.add(name);
102
+ names.push(name);
103
+ }
104
+ return names;
105
+ }
106
+ function childList(value) {
107
+ const children = value?.children;
108
+ return Array.isArray(children) ? children : void 0;
109
+ }
110
+ function asNode(value) {
111
+ return value !== null && typeof value === "object" && "type" in value ? value : void 0;
112
+ }
113
+ function filterChildList(children, variant) {
114
+ return children.flatMap((child) => {
115
+ const node = asNode(child);
116
+ if (node === void 0) return [child];
117
+ const kept = filterNode(node, variant);
118
+ return kept === void 0 ? [] : [kept];
119
+ });
120
+ }
121
+ function containsScope(node) {
122
+ if (node.when !== void 0) return true;
123
+ for (const child of childList(node) ?? []) {
124
+ const nested = asNode(child);
125
+ if (nested !== void 0 && containsScope(nested)) return true;
126
+ }
127
+ const fills = node.fills;
128
+ if (Array.isArray(fills)) {
129
+ for (const fill of fills) {
130
+ for (const child of childList(fill) ?? []) {
131
+ const nested = asNode(child);
132
+ if (nested !== void 0 && containsScope(nested)) return true;
133
+ }
134
+ }
135
+ }
136
+ return false;
137
+ }
138
+ function filterNode(node, variant) {
139
+ const scope = variantScope(node);
140
+ if (scope !== void 0) {
141
+ if (variant === void 0 || !scope.includes(variant)) return void 0;
142
+ }
143
+ const nested = containsScope(node);
144
+ if (scope === void 0 && !nested) return node;
145
+ const result = {};
146
+ for (const [key, value] of Object.entries(node)) {
147
+ if (key === "when") continue;
148
+ result[key] = value;
149
+ }
150
+ const children = childList(node);
151
+ if (children !== void 0) {
152
+ result.children = filterChildList(children, variant);
153
+ }
154
+ const fills = node.fills;
155
+ if (Array.isArray(fills)) {
156
+ result.fills = fills.map((fill) => {
157
+ const fillChildren = childList(fill);
158
+ if (fillChildren === void 0) return fill;
159
+ return {
160
+ ...fill,
161
+ children: filterChildList(fillChildren, variant)
162
+ };
163
+ });
164
+ }
165
+ return result;
166
+ }
167
+ function filterVariantScope(children, variant) {
168
+ if (!children.some((child) => containsScope(child))) return children;
169
+ return children.flatMap((child) => {
170
+ const kept = filterNode(child, variant);
171
+ return kept === void 0 ? [] : [kept];
172
+ });
173
+ }
174
+ function filterUnscopedPages(document) {
175
+ let changed = false;
176
+ const children = document.children.map((child) => {
177
+ if (child.type !== "Page" || child.variant !== void 0) return child;
178
+ const filtered = filterVariantScope(child.children, void 0);
179
+ if (filtered === child.children) return child;
180
+ changed = true;
181
+ return { ...child, children: filtered };
182
+ });
183
+ return changed ? { ...document, children } : document;
184
+ }
185
+
90
186
  // src/ast/expand-variants.ts
91
187
  function cloneNode(value) {
92
188
  if (Array.isArray(value)) return value.map(cloneNode);
@@ -116,18 +212,22 @@ function hasVariants(document) {
116
212
  return document.children.some((child) => child.type === "Page" && variantNames(child).length > 0);
117
213
  }
118
214
  function expandVariants(document) {
119
- if (!hasVariants(document)) return document;
215
+ if (!hasVariants(document)) return filterUnscopedPages(document);
120
216
  return {
121
217
  ...document,
122
218
  children: document.children.flatMap((child) => {
123
219
  if (child.type !== "Page") return [child];
124
220
  const names = variantNames(child);
125
- if (names.length === 0) return [child];
221
+ if (names.length === 0) {
222
+ const filtered = filterVariantScope(child.children, void 0);
223
+ return [filtered === child.children ? child : { ...child, children: filtered }];
224
+ }
126
225
  return names.map((variant, position) => {
127
226
  const clone = cloneNode(child);
128
227
  delete clone.variants;
129
228
  clone.variant = variant;
130
229
  if (position > 0) delete clone.states;
230
+ clone.children = filterVariantScope(clone.children, variant);
131
231
  return clone;
132
232
  });
133
233
  })
@@ -2828,6 +2928,11 @@ var ATTRIBUTE_SPECS = [
2828
2928
  type: "string[]",
2829
2929
  description: "Named state variants of this page \u2014 each one renders the page again as a screen of its own"
2830
2930
  },
2931
+ {
2932
+ name: "when",
2933
+ type: "string[]",
2934
+ description: "Variant boards this element is drawn on \u2014 when=loading, or when=[loading, empty] for both"
2935
+ },
2831
2936
  {
2832
2937
  name: "id",
2833
2938
  type: "string",
@@ -2873,6 +2978,13 @@ var BOX_ATTRIBUTES = [
2873
2978
  // Guarded runtime outcomes
2874
2979
  "visibleWhen",
2875
2980
  "enabledWhen",
2981
+ // Build-time variant scope. Listed beside the guards because it reads like
2982
+ // them and is deliberately not one of them: a guard leaves the element in the
2983
+ // markup for the runtime to toggle, `when` decides whether the element is in
2984
+ // that board's markup at all. Every element takes it for the same reason
2985
+ // every element takes a guard — which boards a piece of a screen belongs to
2986
+ // is a property of the piece, not of what kind of piece it is.
2987
+ "when",
2876
2988
  // Spacing
2877
2989
  "p",
2878
2990
  "px",
@@ -2935,7 +3047,15 @@ var COMPONENT_METADATA = {
2935
3047
  // board that path renders *into* — nothing emits the attribute for it and
2936
3048
  // nothing would toggle it, so declaring it would let an author write a
2937
3049
  // guard on a page, pass `validate()`, and have the value silently dropped.
2938
- ...BOX_ATTRIBUTES.filter((name) => name !== "visibleWhen" && name !== "enabledWhen"),
3050
+ // `when` is filtered out alongside the guards, for a reason of its own: a
3051
+ // page *is* a board, so scoping one to a variant would be a board saying
3052
+ // which board it is drawn on. The axis a page declares is `variants`, and
3053
+ // `when` names positions along it — the two sit at different levels and a
3054
+ // page carrying both would be asking `expandVariants` to filter a page
3055
+ // against a name it is itself the source of.
3056
+ ...BOX_ATTRIBUTES.filter(
3057
+ (name) => name !== "visibleWhen" && name !== "enabledWhen" && name !== "when"
3058
+ ),
2939
3059
  ...CONTAINER_ATTRIBUTES,
2940
3060
  "id",
2941
3061
  "title",
@@ -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-DfiCKOPE.cjs';
1
+ import { be as WireframeDocument, h as AnyNode, as as PageNode, H as ComponentUseNode, aa as LayoutDefinitionNode, a8 as InteractiveProps, Y as GuardedOutcomeProps } from './types-vhPCZpAW.cjs';
2
2
 
3
3
  /**
4
4
  * Renderer type definitions for wireweave
@@ -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-DfiCKOPE.js';
1
+ import { be as WireframeDocument, h as AnyNode, as as PageNode, H as ComponentUseNode, aa as LayoutDefinitionNode, a8 as InteractiveProps, Y as GuardedOutcomeProps } from './types-vhPCZpAW.js';
2
2
 
3
3
  /**
4
4
  * Renderer type definitions for wireweave
package/dist/renderer.js CHANGED
@@ -33,6 +33,102 @@ 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
+
36
132
  // src/ast/expand-variants.ts
37
133
  function cloneNode(value) {
38
134
  if (Array.isArray(value)) return value.map(cloneNode);
@@ -62,18 +158,22 @@ function hasVariants(document) {
62
158
  return document.children.some((child) => child.type === "Page" && variantNames(child).length > 0);
63
159
  }
64
160
  function expandVariants(document) {
65
- if (!hasVariants(document)) return document;
161
+ if (!hasVariants(document)) return filterUnscopedPages(document);
66
162
  return {
67
163
  ...document,
68
164
  children: document.children.flatMap((child) => {
69
165
  if (child.type !== "Page") return [child];
70
166
  const names = variantNames(child);
71
- if (names.length === 0) return [child];
167
+ if (names.length === 0) {
168
+ const filtered = filterVariantScope(child.children, void 0);
169
+ return [filtered === child.children ? child : { ...child, children: filtered }];
170
+ }
72
171
  return names.map((variant, position) => {
73
172
  const clone = cloneNode(child);
74
173
  delete clone.variants;
75
174
  clone.variant = variant;
76
175
  if (position > 0) delete clone.states;
176
+ clone.children = filterVariantScope(clone.children, variant);
77
177
  return clone;
78
178
  });
79
179
  })
@@ -2774,6 +2874,11 @@ var ATTRIBUTE_SPECS = [
2774
2874
  type: "string[]",
2775
2875
  description: "Named state variants of this page \u2014 each one renders the page again as a screen of its own"
2776
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
+ },
2777
2882
  {
2778
2883
  name: "id",
2779
2884
  type: "string",
@@ -2819,6 +2924,13 @@ var BOX_ATTRIBUTES = [
2819
2924
  // Guarded runtime outcomes
2820
2925
  "visibleWhen",
2821
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",
2822
2934
  // Spacing
2823
2935
  "p",
2824
2936
  "px",
@@ -2881,7 +2993,15 @@ var COMPONENT_METADATA = {
2881
2993
  // board that path renders *into* — nothing emits the attribute for it and
2882
2994
  // nothing would toggle it, so declaring it would let an author write a
2883
2995
  // guard on a page, pass `validate()`, and have the value silently dropped.
2884
- ...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
+ ),
2885
3005
  ...CONTAINER_ATTRIBUTES,
2886
3006
  "id",
2887
3007
  "title",
package/dist/spec.cjs CHANGED
@@ -2171,6 +2171,11 @@ var ATTRIBUTE_SPECS = [
2171
2171
  type: "string[]",
2172
2172
  description: "Named state variants of this page \u2014 each one renders the page again as a screen of its own"
2173
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
+ },
2174
2179
  {
2175
2180
  name: "id",
2176
2181
  type: "string",
@@ -2216,6 +2221,13 @@ var BOX_ATTRIBUTES = [
2216
2221
  // Guarded runtime outcomes
2217
2222
  "visibleWhen",
2218
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",
2219
2231
  // Spacing
2220
2232
  "p",
2221
2233
  "px",
@@ -2278,7 +2290,15 @@ var COMPONENT_METADATA = {
2278
2290
  // board that path renders *into* — nothing emits the attribute for it and
2279
2291
  // nothing would toggle it, so declaring it would let an author write a
2280
2292
  // guard on a page, pass `validate()`, and have the value silently dropped.
2281
- ...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
+ ),
2282
2302
  ...CONTAINER_ATTRIBUTES,
2283
2303
  "id",
2284
2304
  "title",