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

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.
@@ -1,10 +1,12 @@
1
- import { b1 as WireframeDocument, h as AnyNode, al as PageNode, a2 as LayoutDefinitionNode } from './types-BDaNyWMR.cjs';
1
+ import { be as WireframeDocument, h as AnyNode, au as PageNode, H as ComponentUseNode, ab as LayoutDefinitionNode, a9 as InteractiveProps } from './types-Bb3NSNUs.cjs';
2
2
 
3
3
  /**
4
4
  * Renderer type definitions for wireweave
5
5
  *
6
6
  * Provides types for rendering options, themes, and context
7
7
  */
8
+ /** Annotation presentation used by the renderer. */
9
+ type AnnotationStyle = 'legacy' | 'neutral';
8
10
  interface RenderOptions {
9
11
  /** Theme variant */
10
12
  theme?: 'light' | 'dark';
@@ -18,6 +20,8 @@ interface RenderOptions {
18
20
  classPrefix?: string;
19
21
  /** Background color (e.g., '#ffffff', 'transparent') */
20
22
  background?: string;
23
+ /** Explicit neutral mode preserves the historical presentation by default. */
24
+ annotationStyle?: AnnotationStyle;
21
25
  /**
22
26
  * Emit source-anchor attributes (`data-wf-path` / `data-wf-loc`) on each
23
27
  * rendered component element, enabling DOM ↔ AST ↔ source mapping. Default
@@ -264,6 +268,8 @@ declare class HtmlRenderer extends BaseRenderer {
264
268
  protected renderNode(node: AnyNode): string;
265
269
  /** Render the first slot with the supplied page content, if any. */
266
270
  protected renderSlot(): string;
271
+ /** Render one linked component invocation with its stable instance marker. */
272
+ protected renderComponentUse(node: ComponentUseNode): string;
267
273
  /** Render nodes without adding a page frame, optionally filling a slot. */
268
274
  renderFragment(nodes: AnyNode[], slotContent?: string | null): string;
269
275
  /**
@@ -386,7 +392,7 @@ declare function createHtmlRenderer(options?: RenderOptions): HtmlRenderer;
386
392
  * @param prefix - CSS class prefix (default: 'wf')
387
393
  * @returns Complete CSS string
388
394
  */
389
- declare function generateStyles(theme: ThemeConfig, prefix?: string): string;
395
+ declare function generateStyles(theme: ThemeConfig, prefix?: string, annotationStyle?: AnnotationStyle): string;
390
396
 
391
397
  /**
392
398
  * Component-specific CSS styles for wireweave
@@ -400,7 +406,7 @@ declare function generateStyles(theme: ThemeConfig, prefix?: string): string;
400
406
  /**
401
407
  * Generate all component-specific CSS styles
402
408
  */
403
- declare function generateComponentStyles(_theme: ThemeConfig, prefix?: string): string;
409
+ declare function generateComponentStyles(_theme: ThemeConfig, prefix?: string, annotationStyle?: AnnotationStyle): string;
404
410
 
405
411
  /**
406
412
  * Page renderer — single-Page primitive.
@@ -516,13 +522,105 @@ interface SiteModel {
516
522
  /** Build the page/shell/name model shared by the site renderer and runtime. */
517
523
  declare function buildSiteModel(doc: WireframeDocument): SiteModel;
518
524
 
519
- interface SiteOptions extends Pick<RenderOptions, 'theme' | 'classPrefix' | 'background'> {
525
+ interface SiteOptions extends Pick<RenderOptions, 'theme' | 'classPrefix' | 'background' | 'annotationStyle'> {
520
526
  title?: string;
521
527
  entry?: string;
522
528
  }
523
529
  /** Render pages and their optional named layouts as one self-contained site. */
524
530
  declare function renderSite(document: WireframeDocument, options?: SiteOptions): string;
525
531
 
532
+ /**
533
+ * Interaction intent → HTML attributes.
534
+ *
535
+ * `navigate` / `opens` / `toggles` / `action` are the declared interaction
536
+ * intent of a wireframe element (see {@link InteractiveProps}). They are the
537
+ * only structural link between screens, so every consumer of rendered
538
+ * output — the studio runtime, the transition graph, a prototype harness —
539
+ * finds them by these four `data-*` names.
540
+ *
541
+ * This module is their single owner. The attribute names are written down
542
+ * exactly once, here; renderers ask for the record and never spell the names
543
+ * themselves. Before this existed the block was copy-pasted into five
544
+ * renderers, and the sixth (`navigation.ts`) simply never got a copy — nav,
545
+ * tab and breadcrumb items parsed their interaction intent and then dropped it
546
+ * on the floor, which is the failure mode this module exists to make
547
+ * impossible to repeat.
548
+ *
549
+ * `__tests__/renderer-interactive.test.ts` enforces the single-owner property:
550
+ * it fails if any other file under `src/renderer/` spells one of these names.
551
+ */
552
+
553
+ /** The `data-*` attribute name carrying each interaction kind. */
554
+ declare const INTERACTIVE_ATTR_NAMES: readonly ["data-navigate", "data-opens", "data-toggles", "data-action"];
555
+ /** Internal: the shape of {@link InteractiveAttrs}'s keys. Consumers use that. */
556
+ type InteractiveAttrName = (typeof INTERACTIVE_ATTR_NAMES)[number];
557
+ /**
558
+ * Marks a `data-navigate` whose target is a URL rather than a page name.
559
+ *
560
+ * Only elements that are not anchors ever carry it: an anchor puts a URL in its
561
+ * `href` and emits no `data-navigate` at all, so there is nothing left to
562
+ * qualify. A button or a current-page `<span>` has no `href` to move the target
563
+ * into, so the URL travels in the data attribute — and without this marker every
564
+ * consumer would have to re-derive, from the string, the thing the renderer
565
+ * already worked out.
566
+ *
567
+ * That re-derivation is the point. {@link isUrlTarget} is a TypeScript predicate;
568
+ * the site runtime is generated JavaScript. A second copy of the rule over there
569
+ * is a drift surface by construction, and the two copies disagreeing means the
570
+ * runtime starts hunting for a screen named `https://…`. So the judgment is made
571
+ * once, here, at render time, and shipped as a fact the runtime only reads.
572
+ *
573
+ * The single-owner gate in `__tests__/renderer-interactive.test.ts` covers this
574
+ * name for free: it contains `data-navigate`, so any other file under
575
+ * `src/renderer/` that spells it is already an offender.
576
+ */
577
+ declare const EXTERNAL_NAVIGATE_ATTR = "data-navigate-external";
578
+ /** Typed runtime markers, owned beside the legacy interaction attributes. */
579
+ declare const TYPED_INTERACTION_ATTR = "data-wf-on";
580
+ declare const VISIBLE_GUARD_ATTR = "data-wf-visible-when";
581
+ declare const ENABLED_GUARD_ATTR = "data-wf-enabled-when";
582
+ /**
583
+ * Attribute record for one element; absent intents stay `undefined`.
584
+ *
585
+ * The marker is boolean because it carries no value of its own — it qualifies
586
+ * the target next to it. `buildAttrsString` renders `true` as `name="name"`,
587
+ * which is the form that survives the XML parsing of an SVG `foreignObject`.
588
+ */
589
+ type InteractiveAttrs = Record<InteractiveAttrName, string | undefined> & Record<typeof EXTERNAL_NAVIGATE_ATTR, true | undefined> & Record<typeof TYPED_INTERACTION_ATTR | typeof VISIBLE_GUARD_ATTR | typeof ENABLED_GUARD_ATTR, string | undefined>;
590
+ /**
591
+ * The `href` and interaction attributes of an element rendered as an `<a>`.
592
+ *
593
+ * An anchor is the one element with two channels that can carry a destination,
594
+ * so it is the one element where they can contradict each other — and it is the
595
+ * only place the choice between them has to be made. Both halves of that choice
596
+ * are decided here so a renderer never has to know the rule:
597
+ *
598
+ * - An authored `href` is the anchor and is left exactly as written.
599
+ * - Otherwise a URL-shaped `navigate` (see {@link isUrlTarget}) becomes the
600
+ * `href`, and no `data-navigate` goes out beside it. A URL is not a screen:
601
+ * emitting both would hand a consumer two destinations for one element and
602
+ * send a runtime hunting for a screen named `https://…`.
603
+ * - Otherwise the `navigate` target names a page. The anchor stays inert `#` —
604
+ * `href="교환소 지도"` is a broken relative link — and the intent travels as
605
+ * `data-navigate` for the consumer that knows what pages are.
606
+ *
607
+ * When an `href` *and* a URL-shaped `navigate` are both authored, both are
608
+ * emitted unchanged: the element already has its destination, and quietly
609
+ * dropping the second one would hide a contradiction only the author can settle.
610
+ * Naming that conflict belongs to validation, not to rendering.
611
+ *
612
+ * Elements that are not anchors keep {@link interactiveAttrs}: with no `href` to
613
+ * move it into, a URL-shaped target has only the data attribute to travel in,
614
+ * and dropping it there would discard what the author wrote. Those are the
615
+ * elements {@link EXTERNAL_NAVIGATE_ATTR} exists for.
616
+ */
617
+ declare function anchorIntent(node: Partial<InteractiveProps> & {
618
+ href?: string;
619
+ }): {
620
+ href: string;
621
+ attrs: InteractiveAttrs;
622
+ };
623
+
526
624
  /**
527
625
  * Lucide Icons Data
528
626
  *
@@ -605,4 +703,4 @@ declare function renderToHtml(document: WireframeDocument, options?: RenderOptio
605
703
  */
606
704
  declare function renderToSvg(document: WireframeDocument, options?: SvgRenderOptions): SvgRenderResult;
607
705
 
608
- export { type CanvasOptions, type CanvasRenderResult, HtmlRenderer, type IconData, type IconElement, type PageRenderResult, type PlacedPage, type RenderContext, type RenderOptions, type RenderResult, type ShellMiss, type SiteModel, type SiteOptions, type SiteScreen, type SiteShell, type SvgRenderOptions, type SvgRenderResult, type ThemeColors, type ThemeConfig, buildSiteModel, createHtmlRenderer, darkTheme, defaultTheme, generateComponentStyles, generateStyles, getIconData, getTheme, layoutCanvas, lucideIcons, render, renderCanvas, renderIconSvg, renderPage, renderSite, renderToHtml, renderToSvg, renderUnknownIconSvg, resolvePageDimensions };
706
+ export { type AnnotationStyle, type CanvasOptions, type CanvasRenderResult, HtmlRenderer, type IconData, type IconElement, type InteractiveAttrs, type PageRenderResult, type PlacedPage, type RenderContext, type RenderOptions, type RenderResult, type ShellMiss, type SiteModel, type SiteOptions, type SiteScreen, type SiteShell, type SvgRenderOptions, type SvgRenderResult, type ThemeColors, type ThemeConfig, anchorIntent, buildSiteModel, createHtmlRenderer, darkTheme, defaultTheme, generateComponentStyles, generateStyles, getIconData, getTheme, layoutCanvas, lucideIcons, render, renderCanvas, renderIconSvg, renderPage, renderSite, renderToHtml, renderToSvg, renderUnknownIconSvg, resolvePageDimensions };
@@ -1,10 +1,12 @@
1
- import { b1 as WireframeDocument, h as AnyNode, al as PageNode, a2 as LayoutDefinitionNode } from './types-BDaNyWMR.js';
1
+ import { be as WireframeDocument, h as AnyNode, au as PageNode, H as ComponentUseNode, ab as LayoutDefinitionNode, a9 as InteractiveProps } from './types-Bb3NSNUs.js';
2
2
 
3
3
  /**
4
4
  * Renderer type definitions for wireweave
5
5
  *
6
6
  * Provides types for rendering options, themes, and context
7
7
  */
8
+ /** Annotation presentation used by the renderer. */
9
+ type AnnotationStyle = 'legacy' | 'neutral';
8
10
  interface RenderOptions {
9
11
  /** Theme variant */
10
12
  theme?: 'light' | 'dark';
@@ -18,6 +20,8 @@ interface RenderOptions {
18
20
  classPrefix?: string;
19
21
  /** Background color (e.g., '#ffffff', 'transparent') */
20
22
  background?: string;
23
+ /** Explicit neutral mode preserves the historical presentation by default. */
24
+ annotationStyle?: AnnotationStyle;
21
25
  /**
22
26
  * Emit source-anchor attributes (`data-wf-path` / `data-wf-loc`) on each
23
27
  * rendered component element, enabling DOM ↔ AST ↔ source mapping. Default
@@ -264,6 +268,8 @@ declare class HtmlRenderer extends BaseRenderer {
264
268
  protected renderNode(node: AnyNode): string;
265
269
  /** Render the first slot with the supplied page content, if any. */
266
270
  protected renderSlot(): string;
271
+ /** Render one linked component invocation with its stable instance marker. */
272
+ protected renderComponentUse(node: ComponentUseNode): string;
267
273
  /** Render nodes without adding a page frame, optionally filling a slot. */
268
274
  renderFragment(nodes: AnyNode[], slotContent?: string | null): string;
269
275
  /**
@@ -386,7 +392,7 @@ declare function createHtmlRenderer(options?: RenderOptions): HtmlRenderer;
386
392
  * @param prefix - CSS class prefix (default: 'wf')
387
393
  * @returns Complete CSS string
388
394
  */
389
- declare function generateStyles(theme: ThemeConfig, prefix?: string): string;
395
+ declare function generateStyles(theme: ThemeConfig, prefix?: string, annotationStyle?: AnnotationStyle): string;
390
396
 
391
397
  /**
392
398
  * Component-specific CSS styles for wireweave
@@ -400,7 +406,7 @@ declare function generateStyles(theme: ThemeConfig, prefix?: string): string;
400
406
  /**
401
407
  * Generate all component-specific CSS styles
402
408
  */
403
- declare function generateComponentStyles(_theme: ThemeConfig, prefix?: string): string;
409
+ declare function generateComponentStyles(_theme: ThemeConfig, prefix?: string, annotationStyle?: AnnotationStyle): string;
404
410
 
405
411
  /**
406
412
  * Page renderer — single-Page primitive.
@@ -516,13 +522,105 @@ interface SiteModel {
516
522
  /** Build the page/shell/name model shared by the site renderer and runtime. */
517
523
  declare function buildSiteModel(doc: WireframeDocument): SiteModel;
518
524
 
519
- interface SiteOptions extends Pick<RenderOptions, 'theme' | 'classPrefix' | 'background'> {
525
+ interface SiteOptions extends Pick<RenderOptions, 'theme' | 'classPrefix' | 'background' | 'annotationStyle'> {
520
526
  title?: string;
521
527
  entry?: string;
522
528
  }
523
529
  /** Render pages and their optional named layouts as one self-contained site. */
524
530
  declare function renderSite(document: WireframeDocument, options?: SiteOptions): string;
525
531
 
532
+ /**
533
+ * Interaction intent → HTML attributes.
534
+ *
535
+ * `navigate` / `opens` / `toggles` / `action` are the declared interaction
536
+ * intent of a wireframe element (see {@link InteractiveProps}). They are the
537
+ * only structural link between screens, so every consumer of rendered
538
+ * output — the studio runtime, the transition graph, a prototype harness —
539
+ * finds them by these four `data-*` names.
540
+ *
541
+ * This module is their single owner. The attribute names are written down
542
+ * exactly once, here; renderers ask for the record and never spell the names
543
+ * themselves. Before this existed the block was copy-pasted into five
544
+ * renderers, and the sixth (`navigation.ts`) simply never got a copy — nav,
545
+ * tab and breadcrumb items parsed their interaction intent and then dropped it
546
+ * on the floor, which is the failure mode this module exists to make
547
+ * impossible to repeat.
548
+ *
549
+ * `__tests__/renderer-interactive.test.ts` enforces the single-owner property:
550
+ * it fails if any other file under `src/renderer/` spells one of these names.
551
+ */
552
+
553
+ /** The `data-*` attribute name carrying each interaction kind. */
554
+ declare const INTERACTIVE_ATTR_NAMES: readonly ["data-navigate", "data-opens", "data-toggles", "data-action"];
555
+ /** Internal: the shape of {@link InteractiveAttrs}'s keys. Consumers use that. */
556
+ type InteractiveAttrName = (typeof INTERACTIVE_ATTR_NAMES)[number];
557
+ /**
558
+ * Marks a `data-navigate` whose target is a URL rather than a page name.
559
+ *
560
+ * Only elements that are not anchors ever carry it: an anchor puts a URL in its
561
+ * `href` and emits no `data-navigate` at all, so there is nothing left to
562
+ * qualify. A button or a current-page `<span>` has no `href` to move the target
563
+ * into, so the URL travels in the data attribute — and without this marker every
564
+ * consumer would have to re-derive, from the string, the thing the renderer
565
+ * already worked out.
566
+ *
567
+ * That re-derivation is the point. {@link isUrlTarget} is a TypeScript predicate;
568
+ * the site runtime is generated JavaScript. A second copy of the rule over there
569
+ * is a drift surface by construction, and the two copies disagreeing means the
570
+ * runtime starts hunting for a screen named `https://…`. So the judgment is made
571
+ * once, here, at render time, and shipped as a fact the runtime only reads.
572
+ *
573
+ * The single-owner gate in `__tests__/renderer-interactive.test.ts` covers this
574
+ * name for free: it contains `data-navigate`, so any other file under
575
+ * `src/renderer/` that spells it is already an offender.
576
+ */
577
+ declare const EXTERNAL_NAVIGATE_ATTR = "data-navigate-external";
578
+ /** Typed runtime markers, owned beside the legacy interaction attributes. */
579
+ declare const TYPED_INTERACTION_ATTR = "data-wf-on";
580
+ declare const VISIBLE_GUARD_ATTR = "data-wf-visible-when";
581
+ declare const ENABLED_GUARD_ATTR = "data-wf-enabled-when";
582
+ /**
583
+ * Attribute record for one element; absent intents stay `undefined`.
584
+ *
585
+ * The marker is boolean because it carries no value of its own — it qualifies
586
+ * the target next to it. `buildAttrsString` renders `true` as `name="name"`,
587
+ * which is the form that survives the XML parsing of an SVG `foreignObject`.
588
+ */
589
+ type InteractiveAttrs = Record<InteractiveAttrName, string | undefined> & Record<typeof EXTERNAL_NAVIGATE_ATTR, true | undefined> & Record<typeof TYPED_INTERACTION_ATTR | typeof VISIBLE_GUARD_ATTR | typeof ENABLED_GUARD_ATTR, string | undefined>;
590
+ /**
591
+ * The `href` and interaction attributes of an element rendered as an `<a>`.
592
+ *
593
+ * An anchor is the one element with two channels that can carry a destination,
594
+ * so it is the one element where they can contradict each other — and it is the
595
+ * only place the choice between them has to be made. Both halves of that choice
596
+ * are decided here so a renderer never has to know the rule:
597
+ *
598
+ * - An authored `href` is the anchor and is left exactly as written.
599
+ * - Otherwise a URL-shaped `navigate` (see {@link isUrlTarget}) becomes the
600
+ * `href`, and no `data-navigate` goes out beside it. A URL is not a screen:
601
+ * emitting both would hand a consumer two destinations for one element and
602
+ * send a runtime hunting for a screen named `https://…`.
603
+ * - Otherwise the `navigate` target names a page. The anchor stays inert `#` —
604
+ * `href="교환소 지도"` is a broken relative link — and the intent travels as
605
+ * `data-navigate` for the consumer that knows what pages are.
606
+ *
607
+ * When an `href` *and* a URL-shaped `navigate` are both authored, both are
608
+ * emitted unchanged: the element already has its destination, and quietly
609
+ * dropping the second one would hide a contradiction only the author can settle.
610
+ * Naming that conflict belongs to validation, not to rendering.
611
+ *
612
+ * Elements that are not anchors keep {@link interactiveAttrs}: with no `href` to
613
+ * move it into, a URL-shaped target has only the data attribute to travel in,
614
+ * and dropping it there would discard what the author wrote. Those are the
615
+ * elements {@link EXTERNAL_NAVIGATE_ATTR} exists for.
616
+ */
617
+ declare function anchorIntent(node: Partial<InteractiveProps> & {
618
+ href?: string;
619
+ }): {
620
+ href: string;
621
+ attrs: InteractiveAttrs;
622
+ };
623
+
526
624
  /**
527
625
  * Lucide Icons Data
528
626
  *
@@ -605,4 +703,4 @@ declare function renderToHtml(document: WireframeDocument, options?: RenderOptio
605
703
  */
606
704
  declare function renderToSvg(document: WireframeDocument, options?: SvgRenderOptions): SvgRenderResult;
607
705
 
608
- export { type CanvasOptions, type CanvasRenderResult, HtmlRenderer, type IconData, type IconElement, type PageRenderResult, type PlacedPage, type RenderContext, type RenderOptions, type RenderResult, type ShellMiss, type SiteModel, type SiteOptions, type SiteScreen, type SiteShell, type SvgRenderOptions, type SvgRenderResult, type ThemeColors, type ThemeConfig, buildSiteModel, createHtmlRenderer, darkTheme, defaultTheme, generateComponentStyles, generateStyles, getIconData, getTheme, layoutCanvas, lucideIcons, render, renderCanvas, renderIconSvg, renderPage, renderSite, renderToHtml, renderToSvg, renderUnknownIconSvg, resolvePageDimensions };
706
+ export { type AnnotationStyle, type CanvasOptions, type CanvasRenderResult, HtmlRenderer, type IconData, type IconElement, type InteractiveAttrs, type PageRenderResult, type PlacedPage, type RenderContext, type RenderOptions, type RenderResult, type ShellMiss, type SiteModel, type SiteOptions, type SiteScreen, type SiteShell, type SvgRenderOptions, type SvgRenderResult, type ThemeColors, type ThemeConfig, anchorIntent, buildSiteModel, createHtmlRenderer, darkTheme, defaultTheme, generateComponentStyles, generateStyles, getIconData, getTheme, layoutCanvas, lucideIcons, render, renderCanvas, renderIconSvg, renderPage, renderSite, renderToHtml, renderToSvg, renderUnknownIconSvg, resolvePageDimensions };