WORK-124
ID:WORK-124Status:done

Create @refrakt-md/vue renderer with ADR-008 component interface

The Nuxt adapter currently renders all runes via renderToHtml() (identity transform only). To support Vue component overrides — where theme or site authors provide custom Vue components for specific runes — we need a @refrakt-md/vue renderer package that dispatches on typeof/data-rune and provides the ADR-008 framework-native interface (props + named slots).

Priority:mediumComplexity:complexSource:ADR-008
main View source

Criteria completion

Criteria completion: 12 of 12 (100%) checked; history from Apr 6 to Apr 60%25%50%75%100%Apr 6Apr 6

Relationships

Implements 1
Related 3
Branches 3
main current done
claude/file-naming-convention-LJdwR donechangeset-release/main doneclaude/align-sidenav-styling-4MuxV done
History 4
  1. e900a90
    Created (done)by bjornolofandersson
  2. f262d7b
    Content editedby Claude
  3. 8b43c1d
    • ☑ New `packages/vue/` package exists with `@refrakt-md/vue` name
    • ☑ Exports a `Renderer` component that recursively renders a `RendererNode` tree
    • ☑ Renderer dispatches on `typeof` attribute to select registered component overrides (falls back to generic HTML element)
    • ☑ Uses `extractComponentInterface` from `@refrakt-md/transform` to partition children into properties, refs, and anonymous content
    • ☑ Property values passed as named Vue props to component overrides
    • ☑ Top-level refs passed as Vue named slots
    • ☑ Original `tag` object passed as prop alongside extracted props (hybrid per ADR-008 Option 4)
    • ☑ Exports a component registry mechanism (similar to `@refrakt-md/svelte`'s registry)
    • ☑ Exports an `elements` override mechanism for HTML element-level overrides (Table, Pre, etc.)
    • ☑ Nuxt adapter can use the Vue renderer instead of `renderToHtml()` for pages with component overrides
    • ☑ TypeScript compiles cleanly
    • ☑ Test suite covers extraction, dispatch, and fallback rendering
    by Claude
  4. 4cfe47c
    Created (draft)by Claude
    Add work items for ADR-008 multi-framework renderer support

Acceptance Criteria

  • New packages/vue/ package exists with @refrakt-md/vue name
  • Exports a Renderer component that recursively renders a RendererNode tree
  • Renderer dispatches on typeof attribute to select registered component overrides (falls back to generic HTML element)
  • Uses extractComponentInterface from @refrakt-md/transform to partition children into properties, refs, and anonymous content
  • Property values passed as named Vue props to component overrides
  • Top-level refs passed as Vue named slots
  • Original tag object passed as prop alongside extracted props (hybrid per ADR-008 Option 4)
  • Exports a component registry mechanism (similar to @refrakt-md/svelte's registry)
  • Exports an elements override mechanism for HTML element-level overrides (Table, Pre, etc.)
  • Nuxt adapter can use the Vue renderer instead of renderToHtml() for pages with component overrides
  • TypeScript compiles cleanly
  • Test suite covers extraction, dispatch, and fallback rendering

Approach

Mirror the architecture of @refrakt-md/svelte:

  • Renderer.vue — recursive component that walks the renderable tree
  • registry.ts — typeof name → Vue component mapping
  • elements.ts — HTML element name → Vue component mapping (for Table, Pre, etc.)
  • theme.ts — VueTheme interface (manifest + layouts + components + elements)

Vue has native named slots, making it the most natural fit after Svelte. The renderer uses <component :is> for dynamic dispatch with v-bind for props and <template #name> for named slot content.

The extraction logic is already framework-agnostic (extractComponentInterface in @refrakt-md/transform). The Vue-specific work is:

  1. Converting extracted refs into named slot content via Vue's <template #name> syntax
  2. Passing scalar props via v-bind
  3. Recursive rendering with <component :is> for dynamic dispatch

References

  • ADR-008 — Framework-native component interface for rune overrides
  • WORK-117 — Framework-agnostic extraction logic (done)
  • WORK-119 — Svelte renderer extraction (done, reference implementation)
  • packages/svelte/src/Renderer.svelte — Svelte renderer (reference)
  • packages/nuxt/ — Nuxt adapter (consumer of this package)

Resolution

Completed: 2026-04-06

Branch: claude/implement-spec-030-F0LFn

What was done

  • Created packages/vue/ with full ADR-008 component interface
  • Renderer.ts — Vue 3 defineComponent using h() render function for recursive tree rendering
  • Component overrides dispatched via data-rune, receiving:
    • Properties as named Vue props
    • Named refs as Vue named slots (pre-rendered HTML via innerHTML)
    • Anonymous children as default slot
    • Original tag as escape-hatch prop
  • Element overrides: Table (scrollable wrapper), Pre (rf-codeblock structure)
  • Registry + elements + VueTheme type exports
  • 20 tests using @vue/server-renderer SSR rendering

Notes

  • Used defineComponent + h() render functions instead of .vue SFC to avoid needing vue-tsc/vite in the build
  • Named slots use Vue's native slot mechanism: h(Component, props, { slotName: () => vnode })
  • All 2022 tests pass (20 new)