@wireweave/core 3.1.0-beta.4 → 3.1.0-beta.6

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.
@@ -93,6 +93,7 @@ interface PositionProps {
93
93
  interface AppearanceProps {
94
94
  bg?: 'muted' | 'primary' | 'secondary';
95
95
  border?: boolean;
96
+ rounded?: boolean;
96
97
  }
97
98
  interface CommonProps extends SpacingProps, SizeProps, FlexProps, GridProps, PositionProps, AppearanceProps, GuardedOutcomeProps {
98
99
  }
@@ -159,7 +160,7 @@ interface InteractiveProps extends GuardedOutcomeProps {
159
160
  on?: InteractionHandler | InteractionHandler[];
160
161
  }
161
162
  /**
162
- * Wireframe Document — root node, holds pages and named layout definitions.
163
+ * Wireframe Document — root node, holds `Page`s and reuse definitions.
163
164
  *
164
165
  * Multi-page semantics:
165
166
  * - A document is a *canvas* of pages. `renderPage` consumes one page;
@@ -168,6 +169,23 @@ interface InteractiveProps extends GuardedOutcomeProps {
168
169
  * - The canvas itself (gap, layout) is a *renderer* concern, not part of
169
170
  * the DSL — see `CanvasOptions` in `renderer/types.ts`. Chrome / grid /
170
171
  * pan-zoom are host concerns and live entirely outside the renderer.
172
+ *
173
+ * A document child is not necessarily a page: `layout` and `component`
174
+ * definitions are top-level siblings of `page` (see {@link TopLevelNode}).
175
+ * They define trees to be reused, not screens to be drawn, so consumers that
176
+ * want screens must select them — {@link documentPages}.
177
+ *
178
+ * Two independent name scopes live at this level, and neither is enforced by
179
+ * the parser:
180
+ * - {@link PageNode.id} — what `navigate=` addresses.
181
+ * - the `name` of a {@link LayoutDefinitionNode} / {@link ComponentDefinitionNode}
182
+ * — what `uses=` addresses.
183
+ *
184
+ * A duplicate in either scope is a well-formed document that means something
185
+ * unintended (a second page with the same `id` is simply unreachable), so it
186
+ * is a diagnostic, not a parse error: reporting it belongs to `validation/`,
187
+ * where it can carry a location and still let the file be parsed, printed and
188
+ * edited. Resolution must therefore stay total in the presence of duplicates.
171
189
  */
172
190
  interface WireframeDocument extends BaseNode {
173
191
  type: 'Document';
@@ -187,7 +205,20 @@ interface WireframeDocument extends BaseNode {
187
205
  */
188
206
  interface PageNode extends BaseNode, CommonProps {
189
207
  type: 'Page';
190
- /** Stable address used by `navigate=`; distinct from the display title. */
208
+ /**
209
+ * Stable identifier this page is referenced by — the `id=home` attribute.
210
+ *
211
+ * This is the screen's *address*, as distinct from {@link PageNode.title},
212
+ * which is its *display name*. `navigate="home"` resolves against this, so
213
+ * renaming a title must not break a link. Same role the `id` on
214
+ * {@link ModalNode} / {@link DrawerNode} plays for `opens=` / `toggles=`,
215
+ * one scope up: those address an overlay within a page, this addresses a
216
+ * page within a document.
217
+ *
218
+ * Optional, and deliberately not enforced unique by the parser — see the
219
+ * note on {@link WireframeDocument} for where uniqueness is checked and what
220
+ * a duplicate costs.
221
+ */
191
222
  id?: string;
192
223
  title?: string | null;
193
224
  /** Center content both horizontally and vertically */
@@ -196,45 +227,79 @@ interface PageNode extends BaseNode, CommonProps {
196
227
  viewport?: string | number;
197
228
  /** Device preset (e.g., "iphone14", "desktop") */
198
229
  device?: string;
199
- /** Named layout shell that hosts this page's own children. */
230
+ /**
231
+ * Name of the `layout` this page is drawn inside — the `uses=app` attribute.
232
+ * Resolving it to a {@link LayoutDefinitionNode} is a renderer concern; the
233
+ * parser only records the reference.
234
+ */
200
235
  uses?: string;
201
236
  /** Application state declarations contributed by this screen module. */
202
237
  states?: StateDeclaration[];
203
238
  children: AnyNode[];
204
239
  }
205
240
  /**
206
- * A named page shell declared with `layout NAME { ... slot ... }`.
241
+ * Layout — a named shell defined once and referenced by pages (`uses=<name>`).
242
+ *
243
+ * A layout body is ordinary element content plus one {@link SlotNode} marking
244
+ * where a referencing page's own children belong:
207
245
  *
208
- * Layout definitions are top-level structure, not screens. The renderer
209
- * composes a page's children into the first slot when the page says
210
- * `uses=NAME`.
246
+ * ```wireframe
247
+ * layout app {
248
+ * header { title "Acme" }
249
+ * slot
250
+ * footer { text "© 2026" }
251
+ * }
252
+ * ```
253
+ *
254
+ * The node type is `'Layout'`; the interface is named `LayoutDefinitionNode`
255
+ * because `LayoutNode` already names the union of layout-*category* elements
256
+ * (page / header / main / footer / sidebar / section).
211
257
  */
212
258
  interface LayoutDefinitionNode extends BaseNode, CommonProps {
213
259
  type: 'Layout';
260
+ /** Grammar `Identifier` this layout is referenced by. */
214
261
  name: string;
215
262
  /** Application state declarations contributed by this shared layout module. */
216
263
  states?: StateDeclaration[];
217
264
  children: AnyNode[];
218
265
  }
219
- /** A named reusable component definition. */
266
+ /**
267
+ * Component — a named fragment defined once for reuse across pages.
268
+ *
269
+ * Definition and round-trip only: expanding a component into its use sites is
270
+ * a renderer concern, so nothing here describes instantiation.
271
+ */
220
272
  interface ComponentDefinitionNode extends BaseNode, CommonProps {
221
273
  type: 'Component';
274
+ /** Grammar `Identifier` this component is referenced by. */
222
275
  name: string;
276
+ /** Typed values every invocation must provide by name. */
223
277
  parameters?: ComponentParameter[];
224
278
  children: AnyNode[];
225
279
  }
280
+ /** Scalar input types supported by reusable component contracts. */
226
281
  type ComponentParameterType = 'string' | 'number' | 'boolean';
282
+ /** One named, required input declared by a reusable component. */
227
283
  interface ComponentParameter {
228
284
  name: string;
229
285
  valueType: ComponentParameterType;
230
286
  }
287
+ /** Values accepted by a component invocation. */
231
288
  type ComponentInputValue = string | number | boolean;
289
+ /** Content supplied to one named slot at a component use-site. */
232
290
  interface ComponentSlotFill {
233
291
  name: string;
234
292
  children: AnyNode[];
235
293
  loc?: SourceLocation;
236
294
  }
237
- /** An explicit reusable-component invocation. */
295
+ /**
296
+ * An explicit reusable-component invocation.
297
+ *
298
+ * This is intentionally separate from {@link PageNode.uses}: `uses=` remains
299
+ * the legacy page-layout reference, while `use` invokes a component fragment.
300
+ * The linker fills `instanceId`, `targetId`, and `children` after validating
301
+ * and expanding the invocation.
302
+ */
238
303
  interface ComponentUseNode extends BaseNode {
239
304
  type: 'ComponentUse';
240
305
  name: string;
@@ -245,9 +310,16 @@ interface ComponentUseNode extends BaseNode {
245
310
  targetId?: string;
246
311
  children?: AnyNode[];
247
312
  }
248
- /** Bare positional marker inside a layout or named marker inside a component. */
313
+ /**
314
+ * Slot — the position inside a {@link LayoutDefinitionNode} where a
315
+ * referencing page's own content is placed.
316
+ *
317
+ * A bare positional marker: no name, no block. Its position among its parent's
318
+ * `children` is the whole content of the node.
319
+ */
249
320
  interface SlotNode extends BaseNode, CommonProps {
250
321
  type: 'Slot';
322
+ /** Required for component slots; absent for the legacy layout slot. */
251
323
  name?: string;
252
324
  }
253
325
  interface HeaderNode extends BaseNode, CommonProps {
@@ -362,6 +434,8 @@ interface TextNode extends BaseNode, Omit<CommonProps, 'align'> {
362
434
  content: string;
363
435
  size?: TextSize;
364
436
  weight?: TextWeight;
437
+ /** Shorthand for `weight: 'bold'`; an explicit `weight` wins. */
438
+ bold?: boolean;
365
439
  align?: TextAlign;
366
440
  muted?: boolean;
367
441
  }
@@ -517,7 +591,8 @@ interface TableNode extends BaseNode, CommonProps {
517
591
  bordered?: boolean;
518
592
  hover?: boolean;
519
593
  }
520
- interface ListItemNode {
594
+ interface ListItemNode extends BaseNode {
595
+ type: 'ListItem';
521
596
  content: string;
522
597
  icon?: string;
523
598
  children?: ListItemNode[];
@@ -569,19 +644,17 @@ interface PopoverNode extends BaseNode, CommonProps {
569
644
  title?: string | null;
570
645
  children: AnyNode[];
571
646
  }
572
- interface DropdownItemNode extends InteractiveProps {
647
+ interface DropdownItemNode extends BaseNode, InteractiveProps {
648
+ type: 'DropdownItem';
573
649
  label: string;
574
650
  icon?: string;
575
651
  href?: string;
576
652
  danger?: boolean;
577
653
  disabled?: boolean;
578
654
  }
579
- interface DividerNode {
580
- type: 'divider';
581
- }
582
655
  interface DropdownNode extends BaseNode, CommonProps {
583
656
  type: 'Dropdown';
584
- items: (DropdownItemNode | DividerNode)[];
657
+ items: (DropdownItemNode | DividerComponentNode)[];
585
658
  }
586
659
  /** Nav item for array syntax: nav ["a", "b"] */
587
660
  interface NavItem extends InteractiveProps {
@@ -591,9 +664,15 @@ interface NavItem extends InteractiveProps {
591
664
  active?: boolean;
592
665
  disabled?: boolean;
593
666
  }
594
- /** Nav item for block syntax: item "label" icon="x" active */
595
- interface NavBlockItem extends InteractiveProps {
596
- type: 'item';
667
+ /**
668
+ * Nav item for block syntax: item "label" icon="x" active
669
+ *
670
+ * `NavItem` is the same shape written as an array entry, which carries no `type`
671
+ * because an array position needs no discriminant. Here the tag is load-bearing:
672
+ * a nav block holds items, groups and dividers in one list.
673
+ */
674
+ interface NavBlockItem extends BaseNode, InteractiveProps {
675
+ type: 'NavItem';
597
676
  label: string;
598
677
  icon?: string;
599
678
  href?: string;
@@ -601,18 +680,19 @@ interface NavBlockItem extends InteractiveProps {
601
680
  disabled?: boolean;
602
681
  }
603
682
  /** Nav group for block syntax: group "label" { ... } */
604
- interface NavGroupNode {
605
- type: 'group';
683
+ interface NavGroupNode extends BaseNode {
684
+ type: 'NavGroup';
606
685
  label: string;
607
- collapsed?: boolean;
608
- items: (NavBlockItem | NavDivider)[];
609
- }
610
- /** Divider inside nav block */
611
- interface NavDivider {
612
- type: 'divider';
686
+ items: (NavBlockItem | DividerComponentNode)[];
613
687
  }
614
- /** Nav child can be group, item, or divider */
615
- type NavChild = NavGroupNode | NavBlockItem | NavDivider;
688
+ /**
689
+ * Nav child can be group, item, or divider.
690
+ *
691
+ * The divider is the ordinary {@link DividerComponentNode}: `divider` means one
692
+ * thing in this DSL, and a separator written inside a nav block is the same
693
+ * element as one written between two cards.
694
+ */
695
+ type NavChild = NavGroupNode | NavBlockItem | DividerComponentNode;
616
696
  interface NavNode extends BaseNode, CommonProps {
617
697
  type: 'Nav';
618
698
  /** Items for array syntax */
@@ -713,7 +793,9 @@ interface AnnotationItemNode extends BaseNode {
713
793
  children: AnyNode[];
714
794
  }
715
795
  type LayoutNode = PageNode | HeaderNode | MainNode | FooterNode | SidebarNode | SectionNode;
796
+ /** A named tree defined once for reuse, rather than a screen to draw. */
716
797
  type DefinitionNode = LayoutDefinitionNode | ComponentDefinitionNode;
798
+ /** What a {@link WireframeDocument} can hold directly. */
717
799
  type TopLevelNode = PageNode | DefinitionNode;
718
800
  type GridNode = RowNode | ColNode | StackNode | RelativeNode;
719
801
  type ContainerComponentNode = CardNode | ModalNode | DrawerNode | AccordionNode;
@@ -730,4 +812,4 @@ type LeafNode = TextContentNode | InputComponentNode | ButtonNode | DisplayNode
730
812
  type AnyNode = ContainerNode | LeafNode;
731
813
  type NodeType = 'Document' | 'Page' | 'Layout' | 'Component' | 'ComponentUse' | 'Slot' | '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';
732
814
 
733
- export type { HeightValue 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, DividerNode as P, DrawerNode as Q, DrawerPosition as R, DropdownItemNode as S, DropdownNode as T, FeedbackNode as U, FlexProps as V, FooterNode as W, GridNode as X, GridProps as Y, GuardedOutcomeProps as Z, HeaderNode as _, AlertNode as a, TextContentNode as a$, IconNode as a0, IconSize as a1, IconSizeToken as a2, ImageNode as a3, InputComponentNode as a4, InputNode as a5, InputType as a6, InteractionEffect as a7, InteractionHandler as a8, InteractiveProps as a9, RadioNode as aA, RelativeNode as aB, RowNode as aC, SectionNode as aD, SelectNode as aE, SelectOption as aF, ShadowValue as aG, SidebarNode as aH, SizeProps as aI, SliderNode as aJ, SlotNode as aK, SourceLocation as aL, SpacingProps as aM, SpacingValue as aN, SpinnerNode as aO, SpinnerSize as aP, SpinnerSizeToken as aQ, StackNode as aR, StateDeclaration as aS, StateGuard as aT, StateValue as aU, StateValueType as aV, SwitchNode as aW, TabNode as aX, TableNode as aY, TabsNode as aZ, TextAlign as a_, JustifyValue as aa, LayoutDefinitionNode as ab, LayoutNode as ac, LeafNode as ad, LinkNode as ae, ListItemNode as af, ListNode as ag, MainNode as ah, MarkerColor as ai, MarkerNode as aj, ModalNode as ak, NavBlockItem as al, NavChild as am, NavDivider as an, NavGroupNode as ao, NavItem as ap, NavNode as aq, NavigationNode as ar, NodeType as as, OverlayNode as at, PageNode as au, PlaceholderNode as av, PopoverNode as aw, Position as ax, PositionProps as ay, ProgressNode as az, AlertVariant as b, TextNode as b0, TextSize as b1, TextSizeToken as b2, TextWeight as b3, TextareaNode as b4, TitleLevel as b5, TitleNode as b6, ToastNode as b7, ToastPosition as b8, TooltipNode as b9, TooltipPosition as ba, TopLevelNode as bb, ValueWithUnit 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 };
815
+ 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, TextSize 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, RowNode as aA, SectionNode as aB, SelectNode as aC, SelectOption as aD, ShadowValue as aE, SidebarNode as aF, SizeProps as aG, SliderNode as aH, SlotNode as aI, SourceLocation as aJ, SpacingProps as aK, SpacingValue as aL, SpinnerNode as aM, SpinnerSize as aN, SpinnerSizeToken as aO, StackNode as aP, StateDeclaration as aQ, StateGuard as aR, StateValue as aS, StateValueType as aT, SwitchNode as aU, TabNode as aV, TableNode as aW, TabsNode as aX, TextAlign as aY, TextContentNode as aZ, TextNode 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, TextSizeToken as b0, TextWeight as b1, TextareaNode as b2, TitleLevel as b3, TitleNode as b4, ToastNode as b5, ToastPosition as b6, TooltipNode as b7, TooltipPosition as b8, TopLevelNode as b9, ValueWithUnit as ba, WidthValue as bb, WireframeDocument as bc, 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 };
@@ -93,6 +93,7 @@ interface PositionProps {
93
93
  interface AppearanceProps {
94
94
  bg?: 'muted' | 'primary' | 'secondary';
95
95
  border?: boolean;
96
+ rounded?: boolean;
96
97
  }
97
98
  interface CommonProps extends SpacingProps, SizeProps, FlexProps, GridProps, PositionProps, AppearanceProps, GuardedOutcomeProps {
98
99
  }
@@ -159,7 +160,7 @@ interface InteractiveProps extends GuardedOutcomeProps {
159
160
  on?: InteractionHandler | InteractionHandler[];
160
161
  }
161
162
  /**
162
- * Wireframe Document — root node, holds pages and named layout definitions.
163
+ * Wireframe Document — root node, holds `Page`s and reuse definitions.
163
164
  *
164
165
  * Multi-page semantics:
165
166
  * - A document is a *canvas* of pages. `renderPage` consumes one page;
@@ -168,6 +169,23 @@ interface InteractiveProps extends GuardedOutcomeProps {
168
169
  * - The canvas itself (gap, layout) is a *renderer* concern, not part of
169
170
  * the DSL — see `CanvasOptions` in `renderer/types.ts`. Chrome / grid /
170
171
  * pan-zoom are host concerns and live entirely outside the renderer.
172
+ *
173
+ * A document child is not necessarily a page: `layout` and `component`
174
+ * definitions are top-level siblings of `page` (see {@link TopLevelNode}).
175
+ * They define trees to be reused, not screens to be drawn, so consumers that
176
+ * want screens must select them — {@link documentPages}.
177
+ *
178
+ * Two independent name scopes live at this level, and neither is enforced by
179
+ * the parser:
180
+ * - {@link PageNode.id} — what `navigate=` addresses.
181
+ * - the `name` of a {@link LayoutDefinitionNode} / {@link ComponentDefinitionNode}
182
+ * — what `uses=` addresses.
183
+ *
184
+ * A duplicate in either scope is a well-formed document that means something
185
+ * unintended (a second page with the same `id` is simply unreachable), so it
186
+ * is a diagnostic, not a parse error: reporting it belongs to `validation/`,
187
+ * where it can carry a location and still let the file be parsed, printed and
188
+ * edited. Resolution must therefore stay total in the presence of duplicates.
171
189
  */
172
190
  interface WireframeDocument extends BaseNode {
173
191
  type: 'Document';
@@ -187,7 +205,20 @@ interface WireframeDocument extends BaseNode {
187
205
  */
188
206
  interface PageNode extends BaseNode, CommonProps {
189
207
  type: 'Page';
190
- /** Stable address used by `navigate=`; distinct from the display title. */
208
+ /**
209
+ * Stable identifier this page is referenced by — the `id=home` attribute.
210
+ *
211
+ * This is the screen's *address*, as distinct from {@link PageNode.title},
212
+ * which is its *display name*. `navigate="home"` resolves against this, so
213
+ * renaming a title must not break a link. Same role the `id` on
214
+ * {@link ModalNode} / {@link DrawerNode} plays for `opens=` / `toggles=`,
215
+ * one scope up: those address an overlay within a page, this addresses a
216
+ * page within a document.
217
+ *
218
+ * Optional, and deliberately not enforced unique by the parser — see the
219
+ * note on {@link WireframeDocument} for where uniqueness is checked and what
220
+ * a duplicate costs.
221
+ */
191
222
  id?: string;
192
223
  title?: string | null;
193
224
  /** Center content both horizontally and vertically */
@@ -196,45 +227,79 @@ interface PageNode extends BaseNode, CommonProps {
196
227
  viewport?: string | number;
197
228
  /** Device preset (e.g., "iphone14", "desktop") */
198
229
  device?: string;
199
- /** Named layout shell that hosts this page's own children. */
230
+ /**
231
+ * Name of the `layout` this page is drawn inside — the `uses=app` attribute.
232
+ * Resolving it to a {@link LayoutDefinitionNode} is a renderer concern; the
233
+ * parser only records the reference.
234
+ */
200
235
  uses?: string;
201
236
  /** Application state declarations contributed by this screen module. */
202
237
  states?: StateDeclaration[];
203
238
  children: AnyNode[];
204
239
  }
205
240
  /**
206
- * A named page shell declared with `layout NAME { ... slot ... }`.
241
+ * Layout — a named shell defined once and referenced by pages (`uses=<name>`).
242
+ *
243
+ * A layout body is ordinary element content plus one {@link SlotNode} marking
244
+ * where a referencing page's own children belong:
207
245
  *
208
- * Layout definitions are top-level structure, not screens. The renderer
209
- * composes a page's children into the first slot when the page says
210
- * `uses=NAME`.
246
+ * ```wireframe
247
+ * layout app {
248
+ * header { title "Acme" }
249
+ * slot
250
+ * footer { text "© 2026" }
251
+ * }
252
+ * ```
253
+ *
254
+ * The node type is `'Layout'`; the interface is named `LayoutDefinitionNode`
255
+ * because `LayoutNode` already names the union of layout-*category* elements
256
+ * (page / header / main / footer / sidebar / section).
211
257
  */
212
258
  interface LayoutDefinitionNode extends BaseNode, CommonProps {
213
259
  type: 'Layout';
260
+ /** Grammar `Identifier` this layout is referenced by. */
214
261
  name: string;
215
262
  /** Application state declarations contributed by this shared layout module. */
216
263
  states?: StateDeclaration[];
217
264
  children: AnyNode[];
218
265
  }
219
- /** A named reusable component definition. */
266
+ /**
267
+ * Component — a named fragment defined once for reuse across pages.
268
+ *
269
+ * Definition and round-trip only: expanding a component into its use sites is
270
+ * a renderer concern, so nothing here describes instantiation.
271
+ */
220
272
  interface ComponentDefinitionNode extends BaseNode, CommonProps {
221
273
  type: 'Component';
274
+ /** Grammar `Identifier` this component is referenced by. */
222
275
  name: string;
276
+ /** Typed values every invocation must provide by name. */
223
277
  parameters?: ComponentParameter[];
224
278
  children: AnyNode[];
225
279
  }
280
+ /** Scalar input types supported by reusable component contracts. */
226
281
  type ComponentParameterType = 'string' | 'number' | 'boolean';
282
+ /** One named, required input declared by a reusable component. */
227
283
  interface ComponentParameter {
228
284
  name: string;
229
285
  valueType: ComponentParameterType;
230
286
  }
287
+ /** Values accepted by a component invocation. */
231
288
  type ComponentInputValue = string | number | boolean;
289
+ /** Content supplied to one named slot at a component use-site. */
232
290
  interface ComponentSlotFill {
233
291
  name: string;
234
292
  children: AnyNode[];
235
293
  loc?: SourceLocation;
236
294
  }
237
- /** An explicit reusable-component invocation. */
295
+ /**
296
+ * An explicit reusable-component invocation.
297
+ *
298
+ * This is intentionally separate from {@link PageNode.uses}: `uses=` remains
299
+ * the legacy page-layout reference, while `use` invokes a component fragment.
300
+ * The linker fills `instanceId`, `targetId`, and `children` after validating
301
+ * and expanding the invocation.
302
+ */
238
303
  interface ComponentUseNode extends BaseNode {
239
304
  type: 'ComponentUse';
240
305
  name: string;
@@ -245,9 +310,16 @@ interface ComponentUseNode extends BaseNode {
245
310
  targetId?: string;
246
311
  children?: AnyNode[];
247
312
  }
248
- /** Bare positional marker inside a layout or named marker inside a component. */
313
+ /**
314
+ * Slot — the position inside a {@link LayoutDefinitionNode} where a
315
+ * referencing page's own content is placed.
316
+ *
317
+ * A bare positional marker: no name, no block. Its position among its parent's
318
+ * `children` is the whole content of the node.
319
+ */
249
320
  interface SlotNode extends BaseNode, CommonProps {
250
321
  type: 'Slot';
322
+ /** Required for component slots; absent for the legacy layout slot. */
251
323
  name?: string;
252
324
  }
253
325
  interface HeaderNode extends BaseNode, CommonProps {
@@ -362,6 +434,8 @@ interface TextNode extends BaseNode, Omit<CommonProps, 'align'> {
362
434
  content: string;
363
435
  size?: TextSize;
364
436
  weight?: TextWeight;
437
+ /** Shorthand for `weight: 'bold'`; an explicit `weight` wins. */
438
+ bold?: boolean;
365
439
  align?: TextAlign;
366
440
  muted?: boolean;
367
441
  }
@@ -517,7 +591,8 @@ interface TableNode extends BaseNode, CommonProps {
517
591
  bordered?: boolean;
518
592
  hover?: boolean;
519
593
  }
520
- interface ListItemNode {
594
+ interface ListItemNode extends BaseNode {
595
+ type: 'ListItem';
521
596
  content: string;
522
597
  icon?: string;
523
598
  children?: ListItemNode[];
@@ -569,19 +644,17 @@ interface PopoverNode extends BaseNode, CommonProps {
569
644
  title?: string | null;
570
645
  children: AnyNode[];
571
646
  }
572
- interface DropdownItemNode extends InteractiveProps {
647
+ interface DropdownItemNode extends BaseNode, InteractiveProps {
648
+ type: 'DropdownItem';
573
649
  label: string;
574
650
  icon?: string;
575
651
  href?: string;
576
652
  danger?: boolean;
577
653
  disabled?: boolean;
578
654
  }
579
- interface DividerNode {
580
- type: 'divider';
581
- }
582
655
  interface DropdownNode extends BaseNode, CommonProps {
583
656
  type: 'Dropdown';
584
- items: (DropdownItemNode | DividerNode)[];
657
+ items: (DropdownItemNode | DividerComponentNode)[];
585
658
  }
586
659
  /** Nav item for array syntax: nav ["a", "b"] */
587
660
  interface NavItem extends InteractiveProps {
@@ -591,9 +664,15 @@ interface NavItem extends InteractiveProps {
591
664
  active?: boolean;
592
665
  disabled?: boolean;
593
666
  }
594
- /** Nav item for block syntax: item "label" icon="x" active */
595
- interface NavBlockItem extends InteractiveProps {
596
- type: 'item';
667
+ /**
668
+ * Nav item for block syntax: item "label" icon="x" active
669
+ *
670
+ * `NavItem` is the same shape written as an array entry, which carries no `type`
671
+ * because an array position needs no discriminant. Here the tag is load-bearing:
672
+ * a nav block holds items, groups and dividers in one list.
673
+ */
674
+ interface NavBlockItem extends BaseNode, InteractiveProps {
675
+ type: 'NavItem';
597
676
  label: string;
598
677
  icon?: string;
599
678
  href?: string;
@@ -601,18 +680,19 @@ interface NavBlockItem extends InteractiveProps {
601
680
  disabled?: boolean;
602
681
  }
603
682
  /** Nav group for block syntax: group "label" { ... } */
604
- interface NavGroupNode {
605
- type: 'group';
683
+ interface NavGroupNode extends BaseNode {
684
+ type: 'NavGroup';
606
685
  label: string;
607
- collapsed?: boolean;
608
- items: (NavBlockItem | NavDivider)[];
609
- }
610
- /** Divider inside nav block */
611
- interface NavDivider {
612
- type: 'divider';
686
+ items: (NavBlockItem | DividerComponentNode)[];
613
687
  }
614
- /** Nav child can be group, item, or divider */
615
- type NavChild = NavGroupNode | NavBlockItem | NavDivider;
688
+ /**
689
+ * Nav child can be group, item, or divider.
690
+ *
691
+ * The divider is the ordinary {@link DividerComponentNode}: `divider` means one
692
+ * thing in this DSL, and a separator written inside a nav block is the same
693
+ * element as one written between two cards.
694
+ */
695
+ type NavChild = NavGroupNode | NavBlockItem | DividerComponentNode;
616
696
  interface NavNode extends BaseNode, CommonProps {
617
697
  type: 'Nav';
618
698
  /** Items for array syntax */
@@ -713,7 +793,9 @@ interface AnnotationItemNode extends BaseNode {
713
793
  children: AnyNode[];
714
794
  }
715
795
  type LayoutNode = PageNode | HeaderNode | MainNode | FooterNode | SidebarNode | SectionNode;
796
+ /** A named tree defined once for reuse, rather than a screen to draw. */
716
797
  type DefinitionNode = LayoutDefinitionNode | ComponentDefinitionNode;
798
+ /** What a {@link WireframeDocument} can hold directly. */
717
799
  type TopLevelNode = PageNode | DefinitionNode;
718
800
  type GridNode = RowNode | ColNode | StackNode | RelativeNode;
719
801
  type ContainerComponentNode = CardNode | ModalNode | DrawerNode | AccordionNode;
@@ -730,4 +812,4 @@ type LeafNode = TextContentNode | InputComponentNode | ButtonNode | DisplayNode
730
812
  type AnyNode = ContainerNode | LeafNode;
731
813
  type NodeType = 'Document' | 'Page' | 'Layout' | 'Component' | 'ComponentUse' | 'Slot' | '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';
732
814
 
733
- export type { HeightValue 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, DividerNode as P, DrawerNode as Q, DrawerPosition as R, DropdownItemNode as S, DropdownNode as T, FeedbackNode as U, FlexProps as V, FooterNode as W, GridNode as X, GridProps as Y, GuardedOutcomeProps as Z, HeaderNode as _, AlertNode as a, TextContentNode as a$, IconNode as a0, IconSize as a1, IconSizeToken as a2, ImageNode as a3, InputComponentNode as a4, InputNode as a5, InputType as a6, InteractionEffect as a7, InteractionHandler as a8, InteractiveProps as a9, RadioNode as aA, RelativeNode as aB, RowNode as aC, SectionNode as aD, SelectNode as aE, SelectOption as aF, ShadowValue as aG, SidebarNode as aH, SizeProps as aI, SliderNode as aJ, SlotNode as aK, SourceLocation as aL, SpacingProps as aM, SpacingValue as aN, SpinnerNode as aO, SpinnerSize as aP, SpinnerSizeToken as aQ, StackNode as aR, StateDeclaration as aS, StateGuard as aT, StateValue as aU, StateValueType as aV, SwitchNode as aW, TabNode as aX, TableNode as aY, TabsNode as aZ, TextAlign as a_, JustifyValue as aa, LayoutDefinitionNode as ab, LayoutNode as ac, LeafNode as ad, LinkNode as ae, ListItemNode as af, ListNode as ag, MainNode as ah, MarkerColor as ai, MarkerNode as aj, ModalNode as ak, NavBlockItem as al, NavChild as am, NavDivider as an, NavGroupNode as ao, NavItem as ap, NavNode as aq, NavigationNode as ar, NodeType as as, OverlayNode as at, PageNode as au, PlaceholderNode as av, PopoverNode as aw, Position as ax, PositionProps as ay, ProgressNode as az, AlertVariant as b, TextNode as b0, TextSize as b1, TextSizeToken as b2, TextWeight as b3, TextareaNode as b4, TitleLevel as b5, TitleNode as b6, ToastNode as b7, ToastPosition as b8, TooltipNode as b9, TooltipPosition as ba, TopLevelNode as bb, ValueWithUnit 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 };
815
+ 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, TextSize 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, RowNode as aA, SectionNode as aB, SelectNode as aC, SelectOption as aD, ShadowValue as aE, SidebarNode as aF, SizeProps as aG, SliderNode as aH, SlotNode as aI, SourceLocation as aJ, SpacingProps as aK, SpacingValue as aL, SpinnerNode as aM, SpinnerSize as aN, SpinnerSizeToken as aO, StackNode as aP, StateDeclaration as aQ, StateGuard as aR, StateValue as aS, StateValueType as aT, SwitchNode as aU, TabNode as aV, TableNode as aW, TabsNode as aX, TextAlign as aY, TextContentNode as aZ, TextNode 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, TextSizeToken as b0, TextWeight as b1, TextareaNode as b2, TitleLevel as b3, TitleNode as b4, ToastNode as b5, ToastPosition as b6, TooltipNode as b7, TooltipPosition as b8, TopLevelNode as b9, ValueWithUnit as ba, WidthValue as bb, WireframeDocument as bc, 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 };