@meistrari/tela-build 1.66.0 → 1.67.1

package/components/tela/rfc/rfc-flowchart.vue

@@ -0,0 +1,79 @@
+<script setup lang="ts">
+import { renderMermaidSVG } from 'beautiful-mermaid'
+
+const props = withDefaults(defineProps<{
+    content: string
+    label?: string
+    errorLabel?: string
+}>(), {
+    label: 'Flowchart',
+    errorLabel: 'Flowchart could not be rendered',
+})
+
+const result = computed(() => {
+    try {
+        const svg = renderMermaidSVG(props.content, {
+            bg: DT.colors.background.DEFAULT,
+            fg: DT.colors.text.primary,
+            line: DT.colors.border.strong,
+            accent: DT.colors.text.secondary,
+            muted: DT.colors.text.secondary,
+            surface: DT.colors.background.subtle,
+            border: DT.colors.border.DEFAULT,
+            font: 'Inter Variable',
+            padding: 32,
+            transparent: true,
+        }).replace(/\s*@import\s+url\([^)]*\);\s*/u, '')
+
+        return { svg, error: '' }
+    }
+    catch (error) {
+        return {
+            svg: '',
+            error: error instanceof Error ? error.message : props.errorLabel,
+        }
+    }
+})
+</script>
+
+<template>
+    <figure
+        flex="~ col" gap-12px
+        my-8px p-24px overflow-hidden
+        rounded-10px border-0.5px border bg
+    >
+        <div
+            v-if="result.svg"
+            role="img"
+            :aria-label="label"
+            w-full overflow-x-auto
+            data-rfc-flowchart
+            v-html="result.svg"
+        />
+
+        <div v-else flex="~ col" gap-12px>
+            <p body-12-medium text-secondary>
+                {{ errorLabel }}
+            </p>
+            <pre overflow-x-auto rounded-8px bg p-16px body-12-regular text-primary><code>{{ content }}</code></pre>
+            <p body-12-regular text-secondary>
+                {{ result.error }}
+            </p>
+        </div>
+
+        <figcaption body-12-medium text-primary>
+            {{ label }}
+        </figcaption>
+    </figure>
+</template>
+
+<style scoped>
+[data-rfc-flowchart] :deep(svg) {
+    display: block;
+    width: auto;
+    min-width: 100%;
+    max-width: none;
+    height: auto;
+    margin: 0 auto;
+}
+</style>

package/components/tela/rfc/rfc-heading.vue

@@ -0,0 +1,35 @@
+<script setup lang="ts">
+const props = withDefaults(defineProps<{
+    as?: 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6'
+    id?: string
+}>(), {
+    as: 'h2',
+})
+
+const isAnchored = computed(() => !!props.id && props.as !== 'h1')
+
+function scrollToSelf(event: MouseEvent) {
+    const target = event.currentTarget instanceof HTMLElement ? event.currentTarget.closest(props.as) : null
+
+    if (!target)
+        return
+
+    event.preventDefault()
+    target.scrollIntoView({ behavior: 'smooth', block: 'start' })
+    history.replaceState(history.state, '', `#${props.id}`)
+}
+</script>
+
+<template>
+    <component :is="as" :id="id">
+        <a
+            v-if="isAnchored"
+            :href="`#${id}`"
+            class="tela-rfc-heading-anchor"
+            @click="scrollToSelf"
+        >
+            <slot />
+        </a>
+        <slot v-else />
+    </component>
+</template>

package/components/tela/rfc/rfc-markdown.test.ts

@@ -0,0 +1,95 @@
+import { describe, expect, it } from 'vitest'
+
+import { flattenRfcToc, parseRfcMarkdown } from './rfc-markdown'
+
+describe('parseRfcMarkdown', () => {
+    it('extracts the title and a nested table of contents', async () => {
+        const document = await parseRfcMarkdown(`# Stateful workflow runs
+
+## Context
+
+Introductory copy.
+
+### Current behavior
+
+More detail.
+
+## Proposal
+`)
+
+        expect(document.title).toBe('Stateful workflow runs')
+        expect(document.toc).toEqual([
+            {
+                id: 'context',
+                depth: 2,
+                text: 'Context',
+                children: [
+                    {
+                        id: 'context-current-behavior',
+                        depth: 3,
+                        text: 'Current behavior',
+                    },
+                ],
+            },
+            {
+                id: 'proposal',
+                depth: 2,
+                text: 'Proposal',
+            },
+        ])
+
+        expect(flattenRfcToc(document.toc).map(link => link.text)).toEqual([
+            'Context',
+            'Current behavior',
+            'Proposal',
+        ])
+    })
+
+    it('keeps ASCII illustrations and promotes Mermaid fences to flowcharts', async () => {
+        const document = await parseRfcMarkdown(`# Diagrams
+
+\`\`\`ascii
++-------+     +--------+
+| Draft | --> | Review |
++-------+     +--------+
+\`\`\`
+
+\`\`\`mermaid
+flowchart LR
+    Draft --> Review
+\`\`\`
+`)
+
+        expect(document.tree.nodes).toContainEqual([
+            'pre',
+            { language: 'ascii' },
+            [
+                'code',
+                { class: 'language-ascii' },
+                '+-------+     +--------+\n| Draft | --> | Review |\n+-------+     +--------+',
+            ],
+        ])
+        expect(document.tree.nodes).toContainEqual([
+            'mermaid',
+            { content: 'flowchart LR\n    Draft --> Review\n' },
+        ])
+    })
+
+    it('treats raw HTML as text and removes custom component tags', async () => {
+        const document = await parseRfcMarkdown(`# Safe input
+
+<script>alert('nope')</script>
+
+::unsafe-component{onload="alert('nope')"}
+Hidden content
+::
+`)
+
+        expect(document.tree.nodes).toContainEqual([
+            'p',
+            {},
+            "<script>alert('nope')</script>",
+        ])
+        expect(document.tree.nodes.some(node => Array.isArray(node) && node[0] === 'unsafe-component')).toBe(false)
+    })
+})

package/components/tela/rfc/rfc-markdown.ts

@@ -0,0 +1,92 @@
+import type { ComarkTree } from 'comark'
+import type { TocLink } from 'comark/plugins/toc'
+
+import { parse } from 'comark'
+import mermaid from 'comark/plugins/mermaid'
+import security from 'comark/plugins/security'
+import toc from 'comark/plugins/toc'
+import { textContent } from 'comark/utils'
+
+const allowedTags = [
+    'a',
+    'blockquote',
+    'br',
+    'code',
+    'del',
+    'em',
+    'h1',
+    'h2',
+    'h3',
+    'h4',
+    'h5',
+    'h6',
+    'hr',
+    'img',
+    'input',
+    'li',
+    'mermaid',
+    'ol',
+    'p',
+    'pre',
+    's',
+    'strong',
+    'table',
+    'tbody',
+    'td',
+    'th',
+    'thead',
+    'tr',
+    'ul',
+]
+
+const rfcPlugins = [
+    mermaid(),
+    toc({ depth: 3, searchDepth: 3 }),
+    security({
+        allowedTags,
+        allowedProtocols: ['http', 'https', 'mailto'],
+        allowDataImages: false,
+    }),
+] as const
+
+export interface ParsedRfcDocument {
+    tree: ComarkTree
+    title: string
+    toc: TocLink[]
+}
+
+export interface FlatRfcTocLink extends Omit<TocLink, 'children'> {
+    children?: TocLink[]
+}
+
+function documentTitle(tree: ComarkTree): string {
+    const titleHeading = tree.nodes.find(node => Array.isArray(node) && node[0] === 'h1')
+    const headingText = titleHeading ? textContent(titleHeading).trim() : ''
+
+    if (headingText)
+        return headingText
+
+    const frontmatterTitle = tree.frontmatter.title
+
+    return typeof frontmatterTitle === 'string' ? frontmatterTitle.trim() : ''
+}
+
+export async function parseRfcMarkdown(markdown: string): Promise<ParsedRfcDocument> {
+    const tree = await parse(markdown, {
+        html: false,
+        plugins: rfcPlugins,
+    })
+
+    return {
+        tree,
+        title: documentTitle(tree),
+        toc: tree.meta.toc.links,
+    }
+}
+
+export function flattenRfcToc(links: TocLink[]): FlatRfcTocLink[] {
+    return links.flatMap(link => [
+        link,
+        ...flattenRfcToc(link.children ?? []),
+    ])
+}

package/components/tela/rfc/rfc-pre.vue

@@ -0,0 +1,46 @@
+<script setup lang="ts">
+import type { ComarkElement } from 'comark'
+
+const props = withDefaults(defineProps<{
+    code?: string
+    language?: string
+    // eslint-disable-next-line vue/prop-name-casing -- Comark passes the element node as `__node`
+    __node?: ComarkElement
+}>(), {
+    code: '',
+    language: '',
+})
+
+function nodeText(node: unknown): string {
+    if (typeof node === 'string')
+        return node
+
+    if (!Array.isArray(node))
+        return ''
+
+    return node.slice(2).map(nodeText).join('')
+}
+
+function nodeLanguage(node: ComarkElement | undefined): string {
+    if (!node)
+        return ''
+
+    const [, nodeProps, ...children] = node
+
+    if (typeof nodeProps?.language === 'string')
+        return nodeProps.language
+
+    const codeChild = children.find((child): child is ComarkElement => Array.isArray(child) && child[0] === 'code')
+    const codeClass = codeChild?.[1]?.class
+    const match = typeof codeClass === 'string' ? codeClass.match(/language-(\S+)/) : null
+
+    return match?.[1] ?? ''
+}
+
+const code = computed(() => (props.code || nodeText(props.__node)).trimEnd())
+const language = computed(() => props.language || nodeLanguage(props.__node) || 'text')
+</script>
+
+<template>
+    <TelaCodeBlock :code="code" :language="language" class="my-16px" />
+</template>

package/components/tela/rfc/rfc.mdx

@@ -0,0 +1,131 @@
+import { Meta } from '@storybook/blocks';
+
+<Meta title="Layout/RFC" tags={['new']} />
+
+# TelaRfc
+
+A full-page template for reading technical RFCs. Pass one plain Markdown string and the component renders a centered document column with a fixed table of contents generated from the document headings.
+
+Fenced code blocks render through `TelaCodeBlock` (line numbers and copy action); `ascii` blocks stay plain text so illustrations are preserved exactly. Fenced `mermaid` blocks render as flowcharts and fall back to their source when the diagram is invalid.
+
+## Intent
+
+`TelaRfc` is for an engineer or reviewer who needs to understand a proposal, keep their place in a long document, and inspect architecture diagrams without leaving the reading flow. It should feel precise and calm, like a well-typeset technical memo.
+
+- **Signature:** the table of contents stays fixed at the right of the viewport, tracks the active heading, and surfaces the document title once it scrolls away.
+- **Depth:** borders-only, matching a technical document rather than a card dashboard.
+- **Typography:** the same prose scale as the Tela Build docs site — `heading-h2/h3/h4-semibold` titles, `body-16-regular` secondary prose — on a centered 760px reading column.
+- **Spacing:** 32px before each H2, 28px before H3, and 12px between paragraphs and list groups.
+
+## Basic usage
+
+```vue
+<script setup lang="ts">
+const markdown = `# Stateful workflow runs
+
+This RFC proposes durable state between workflow steps.
+
+## Context
+
+Today every step reconstructs the state it needs.
+
+### Current flow
+
+\`\`\`ascii
++---------+     +---------+     +--------+
+| Trigger | --> | Resolve | --> | Action |
++---------+     +---------+     +--------+
+\`\`\`
+
+## Proposal
+
+Persist a versioned state envelope after each successful step.
+
+\`\`\`mermaid
+flowchart LR
+    Trigger --> Resolve
+    Resolve --> Persist
+    Persist --> Action
+\`\`\`
+
+## Alternatives considered
+
+- Rebuild state for every step
+- Keep state only in worker memory
+
+## Rollout
+
+1. Add the state envelope behind a flag
+2. Migrate internal workflows
+3. Enable it for new workflows
+`
+</script>
+
+<template>
+  <TelaRfc :markdown="markdown" />
+</template>
+```
+
+## Markdown contract
+
+Use one H1 for the RFC title. H2, H3, and H4 headings populate the table of contents; deeper headings remain in the document but do not make the navigation unnecessarily dense. Consumers do not render `TelaTableOfContents` separately: `TelaRfc` owns it and derives its items from the Markdown.
+
+Standard CommonMark and GFM content is supported, including:
+
+- paragraphs, emphasis, links, images, and blockquotes
+- ordered, unordered, nested, and task lists
+- tables and horizontal rules
+- inline code and fenced code blocks
+- `ascii` fenced blocks for monospaced illustrations
+- `mermaid` fenced blocks for flowcharts
+- optional YAML frontmatter, which is parsed as document metadata and not rendered as prose
+
+Raw HTML is displayed as text. Custom Markdown component tags are removed. Links are limited to relative URLs plus HTTP, HTTPS, and mailto protocols, and data-URL images are disabled.
+
+## Anatomy
+
+```
+TelaRfc                                      ← full-viewport scroll container
+└─ centered reading column                   ← 760px, mx-auto
+   ├─ TelaTableOfContents                        ← fixed at the right, built in
+   └─ article
+      └─ parsed Markdown
+         ├─ headings (H2+ wrapped in a `#` anchor link)
+         ├─ prose, lists, tables
+         ├─ code blocks → TelaCodeBlock
+         └─ TelaRfcFlowchart
+```
+
+Below 1511px the table of contents is hidden and the document keeps the full reading column; headings remain addressable through their native fragment anchors.
+
+## Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `markdown` | `string` | required | Plain Markdown source for the RFC. |
+| `tocLabel` | `string` | `'On this page'` | Accessible label for the built-in table of contents. |
+| `emptyLabel` | `string` | `'No RFC content'` | Empty-state copy. |
+| `errorLabel` | `string` | `'Unable to render this RFC'` | Parser-error fallback copy. |
+
+## Slots
+
+| Slot | Scope | Description |
+| --- | --- | --- |
+| `empty` | — | Replaces the default empty state. |
+
+## Behavior and accessibility
+
+- The RFC shell is the only vertical scroll container and occupies `100dvh`.
+- TOC links are native fragment links and heading targets have a scroll margin.
+- H2–H6 headings wrap their text in a fragment link that reveals a `#` on hover and smooth-scrolls within the RFC container.
+- The active H2–H4 section is exposed with `aria-current="location"`.
+- Flowcharts expose `role="img"` with an accessible label and always retain a readable source fallback.
+- Images and wide code blocks stay within the reading column and scroll horizontally when necessary.
+
+## Rules
+
+1. Pass the source Markdown unchanged; do not pre-render it to HTML.
+2. Use exactly one H1 when the document has a visible title.
+3. Use H2 for major RFC sections and H3/H4 for subsections so the generated TOC remains meaningful.
+4. Tag text diagrams as `ascii` and rendered flowcharts as `mermaid`.
+5. Keep primary RFC content in Markdown; the table of contents is derived automatically.

package/components/tela/rfc/rfc.vue

@@ -0,0 +1,329 @@
+<script setup lang="ts">
+import { ComarkRenderer } from '@comark/vue'
+
+import RfcFlowchart from './rfc-flowchart.vue'
+import RfcHeading from './rfc-heading.vue'
+import RfcPre from './rfc-pre.vue'
+import { flattenRfcToc, parseRfcMarkdown } from './rfc-markdown'
+import type { ParsedRfcDocument } from './rfc-markdown'
+
+const props = withDefaults(defineProps<{
+    markdown: string
+    tocLabel?: string
+    emptyLabel?: string
+    errorLabel?: string
+}>(), {
+    tocLabel: 'On this page',
+    emptyLabel: 'No RFC content',
+    errorLabel: 'Unable to render this RFC',
+})
+
+defineSlots<{
+    empty: () => unknown
+}>()
+
+type HeadingTag = 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6'
+
+function heading(as: HeadingTag) {
+    return defineComponent({
+        inheritAttrs: false,
+        setup: (_, { attrs, slots }) => () => h(RfcHeading, { ...attrs, as }, slots),
+    })
+}
+
+const markdownComponents = {
+    a: 'a',
+    blockquote: 'blockquote',
+    br: 'br',
+    code: 'code',
+    del: 'del',
+    em: 'em',
+    h1: heading('h1'),
+    h2: heading('h2'),
+    h3: heading('h3'),
+    h4: heading('h4'),
+    h5: heading('h5'),
+    h6: heading('h6'),
+    hr: 'hr',
+    img: 'img',
+    input: 'input',
+    li: 'li',
+    mermaid: RfcFlowchart,
+    ol: 'ol',
+    p: 'p',
+    pre: RfcPre,
+    s: 's',
+    strong: 'strong',
+    table: 'table',
+    tbody: 'tbody',
+    td: 'td',
+    th: 'th',
+    thead: 'thead',
+    tr: 'tr',
+    ul: 'ul',
+}
+
+const scrollContainerRef = ref<HTMLElement | null>(null)
+const articleRef = ref<HTMLElement | null>(null)
+const parsedDocument = shallowRef<ParsedRfcDocument | null>(null)
+const parseError = ref('')
+const isParsing = ref(true)
+
+const tocLinks = computed(() => parsedDocument.value?.toc ?? [])
+const tocItems = computed(() => flattenRfcToc(tocLinks.value).map(link => ({
+    id: link.id,
+    text: link.text,
+    level: link.depth,
+})))
+const isEmpty = computed(() => !props.markdown.trim())
+
+let parseRevision = 0
+
+async function updateMarkdown(markdown: string) {
+    const revision = ++parseRevision
+
+    isParsing.value = parsedDocument.value === null
+    parseError.value = ''
+
+    try {
+        const document = await parseRfcMarkdown(markdown)
+
+        if (revision !== parseRevision)
+            return
+
+        parsedDocument.value = document
+    }
+    catch (error) {
+        if (revision !== parseRevision)
+            return
+
+        parseError.value = error instanceof Error ? error.message : props.errorLabel
+    }
+    finally {
+        if (revision === parseRevision)
+            isParsing.value = false
+    }
+}
+
+watch(() => props.markdown, updateMarkdown, { immediate: true })
+</script>
+
+<template>
+    <main
+        ref="scrollContainerRef"
+        data-tela-rfc
+        h-dvh w-full overflow-y-auto bg
+    >
+        <div
+            :aria-busy="isParsing"
+            class="mx-auto w-full max-w-760px px-20px pb-64px pt-24px min-[821px]:px-40px min-[821px]:pb-80px min-[821px]:pt-80px"
+        >
+            <TelaTableOfContents
+                v-if="tocItems.length"
+                :items="tocItems"
+                :label="tocLabel"
+                :content-root="articleRef"
+                :scroll-root="scrollContainerRef"
+            />
+
+            <article ref="articleRef" data-rfc-document min-w-0>
+                <div v-if="isParsing" role="status" flex="~ col" gap-16px aria-live="polite">
+                    <TelaSkeleton h-36px w-72% rounded-8px />
+                    <TelaSkeleton h-20px w-full rounded-4px />
+                    <TelaSkeleton h-20px w-88% rounded-4px />
+                    <TelaSkeleton h-220px w-full rounded-12px />
+                </div>
+
+                <slot v-else-if="isEmpty" name="empty">
+                    <div py-80px text-center>
+                        <p body-14-regular text-secondary>
+                            {{ emptyLabel }}
+                        </p>
+                    </div>
+                </slot>
+
+                <div v-else-if="parseError" flex="~ col" gap-16px>
+                    <p body-14-medium text-primary>
+                        {{ errorLabel }}
+                    </p>
+                    <pre overflow-x-auto rounded-10px border-0.5px border bg p-20px body-14-regular text-primary><code>{{ markdown }}</code></pre>
+                </div>
+
+                <ComarkRenderer
+                    v-else-if="parsedDocument"
+                    :tree="parsedDocument.tree"
+                    :components="markdownComponents"
+                />
+            </article>
+        </div>
+    </main>
+</template>
+
+<style scoped>
+[data-rfc-document] :deep(h1),
+[data-rfc-document] :deep(h2),
+[data-rfc-document] :deep(h3),
+[data-rfc-document] :deep(h4),
+[data-rfc-document] :deep(h5),
+[data-rfc-document] :deep(h6) {
+    --at-apply: 'text-primary';
+    scroll-margin-top: 24px;
+}
+
+[data-rfc-document] :deep(h1) {
+    --at-apply: 'heading-h2-semibold';
+    margin: 0 0 8px;
+}
+
+[data-rfc-document] :deep(h2) {
+    --at-apply: 'heading-h3-semibold';
+    margin: 32px 0 8px;
+}
+
+[data-rfc-document] :deep(h3) {
+    --at-apply: 'heading-h4-semibold';
+    margin: 28px 0 8px;
+}
+
+[data-rfc-document] :deep(h4),
+[data-rfc-document] :deep(h5),
+[data-rfc-document] :deep(h6) {
+    --at-apply: 'heading-h5-semibold';
+    margin: 24px 0 8px;
+}
+
+[data-rfc-document] :deep(.tela-rfc-heading-anchor) {
+    color: inherit;
+    font: inherit;
+    text-decoration: none;
+}
+
+[data-rfc-document] :deep(.tela-rfc-heading-anchor::after) {
+    --at-apply: 'text-secondary';
+    content: '#';
+    margin-left: 6px;
+    opacity: 0;
+    transition: opacity 150ms ease;
+}
+
+[data-rfc-document] :deep(.tela-rfc-heading-anchor:hover::after),
+[data-rfc-document] :deep(.tela-rfc-heading-anchor:focus-visible::after) {
+    opacity: 1;
+}
+
+[data-rfc-document] :deep(p) {
+    --at-apply: 'body-16-regular leading-24px text-secondary';
+    margin: 0 0 12px;
+}
+
+[data-rfc-document] :deep(strong) {
+    --at-apply: 'font-580';
+}
+
+[data-rfc-document] :deep(a) {
+    --at-apply: 'text-primary';
+    text-decoration: underline;
+    text-underline-offset: 2px;
+}
+
+[data-rfc-document] :deep(a:focus-visible) {
+    outline: 2px solid currentColor;
+    outline-offset: 2px;
+}
+
+[data-rfc-document] :deep(ul),
+[data-rfc-document] :deep(ol) {
+    margin: 12px 0 12px;
+    padding-left: 20px;
+    list-style: disc;
+}
+
+[data-rfc-document] :deep(p + ul),
+[data-rfc-document] :deep(p + ol) {
+    margin-top: 0;
+}
+
+[data-rfc-document] :deep(p:has(+ ul)),
+[data-rfc-document] :deep(p:has(+ ol)) {
+    margin-bottom: 0;
+}
+
+[data-rfc-document] :deep(ol) {
+    list-style: decimal;
+}
+
+[data-rfc-document] :deep(li) {
+    --at-apply: 'body-16-regular text-secondary';
+    margin: 8px 0;
+}
+
+[data-rfc-document] :deep(li > ul),
+[data-rfc-document] :deep(li > ol) {
+    margin-top: 8px;
+    margin-bottom: 0;
+}
+
+[data-rfc-document] :deep(blockquote) {
+    --at-apply: 'text-secondary border';
+    margin: 24px 0;
+    padding-left: 16px;
+    border-left: 0.5px solid;
+}
+
+[data-rfc-document] :deep(blockquote p:last-child) {
+    margin-bottom: 0;
+}
+
+[data-rfc-document] :deep(code) {
+    --at-apply: 'bg-muted rounded-4px text-secondary';
+    font-family: 'Geist Mono Variable', monospace;
+    font-size: 12.5px;
+    padding: 0 4px;
+}
+
+[data-rfc-document] :deep(pre code) {
+    background: transparent;
+    border-radius: 0;
+    padding: 0;
+    font-size: inherit;
+}
+
+[data-rfc-document] :deep(hr) {
+    --at-apply: 'bg-border';
+    border: none;
+    height: 0.5px;
+    margin: 32px 0;
+}
+
+[data-rfc-document] :deep(table) {
+    width: 100%;
+    border-collapse: collapse;
+    margin: 16px 0;
+}
+
+[data-rfc-document] :deep(th) {
+    --at-apply: 'body-12-medium text-secondary border-b-0.5px border';
+    text-align: left;
+    padding: 8px;
+}
+
+[data-rfc-document] :deep(td) {
+    --at-apply: 'body-14-regular text-primary border-b-0.5px border';
+    padding: 8px;
+}
+
+[data-rfc-document] :deep(img) {
+    --at-apply: 'border';
+    display: block;
+    max-width: 100%;
+    height: auto;
+    margin: 24px auto;
+    border-width: 0.5px;
+    border-style: solid;
+    border-radius: 10px;
+}
+
+[data-rfc-document] :deep(input[type='checkbox']) {
+    margin-right: 8px;
+}
+</style>

package/components/tela/table-of-contents/table-of-contents.mdx

@@ -0,0 +1,81 @@
+import { Meta } from '@storybook/blocks';
+
+<Meta title="Components/Table of Contents" tags={['new']} />
+
+# TelaTableOfContents
+
+A viewport-fixed in-page table of contents (the same one used by the Tela Build docs site) that tracks the current heading and scrolls to native fragment targets. It can discover headings from an article or receive an explicit item list, and it hides itself below 1511px.
+
+## Basic usage
+
+By default it discovers H2 and H3 elements in the first `article`. Remount it when a client-side route changes so it discovers the new document.
+
+```vue
+<article>
+  <h1 id="proposal">Proposal</h1>
+  <h2 id="context">Context</h2>
+  <h3 id="constraints">Constraints</h3>
+</article>
+
+<TelaTableOfContents :key="$route.path" />
+```
+
+## Supplied items and contained scrolling
+
+Pass `items` when the headings are already known (for example from a parsed Markdown tree), `contentRoot` when the headings live in a specific element, and `scrollRoot` when that element scrolls inside the viewport.
+
+```vue
+<script setup lang="ts">
+const scrollRoot = ref<HTMLElement | null>(null)
+const contentRoot = ref<HTMLElement | null>(null)
+
+const items = [
+  { id: 'context', text: 'Context', level: 2 },
+  { id: 'constraints', text: 'Constraints', level: 3 },
+  { id: 'proposal', text: 'Proposal', level: 2 },
+]
+</script>
+
+<template>
+  <main ref="scrollRoot" h-dvh overflow-y-auto>
+    <div mx-auto max-w-760px>
+      <TelaTableOfContents
+        :items="items"
+        :content-root="contentRoot"
+        :scroll-root="scrollRoot"
+      />
+
+      <article ref="contentRoot">
+        <h2 id="context">Context</h2>
+        <h3 id="constraints">Constraints</h3>
+        <h2 id="proposal">Proposal</h2>
+      </article>
+    </div>
+  </main>
+</template>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `items` | `{ id: string, text: string, level: number }[]` | discovered | Explicit ordered heading list. |
+| `label` | `string` | `undefined` | Accessible navigation label. Falls back to the document title, then “Table of contents”. |
+| `contentRoot` | `HTMLElement \| null` | first matching article | Element containing the target headings. |
+| `scrollRoot` | `HTMLElement \| null` | viewport | Scroll container used for active-heading observation and scroll-to-top behavior. |
+| `articleSelector` | `string` | `'article'` | Fallback selector used when `contentRoot` is not supplied. |
+| `headingSelector` | `string` | `'h2[id], h3[id]'` | Headings discovered when `items` is not supplied. |
+| `titleSelector` | `string` | `'h1[id]'` | Title shown above the list after the document title scrolls away. |
+
+## Events
+
+| Event | Payload | Description |
+| --- | --- | --- |
+| `select` | `{ id, text, level }` | Emitted after a TOC item is selected. |
+
+## Behavior and accessibility
+
+- Links retain native fragment URLs and expose the tracked section with `aria-current="location"`.
+- Selecting a link scrolls smoothly and updates the URL hash without adding history entries.
+- The title control leaves the tab order while hidden and returns to the top of the current scroll root.
+- The navigation is hidden below 1511px; the document keeps its native heading anchors.

package/components/tela/table-of-contents/table-of-contents.vue

@@ -0,0 +1,235 @@
+<script setup lang="ts">
+interface TableOfContentsItem {
+    id: string
+    text: string
+    level: number
+}
+
+const props = withDefaults(defineProps<{
+    items?: TableOfContentsItem[]
+    label?: string
+    contentRoot?: HTMLElement | null
+    scrollRoot?: HTMLElement | null
+    articleSelector?: string
+    headingSelector?: string
+    titleSelector?: string
+}>(), {
+    articleSelector: 'article',
+    headingSelector: 'h2[id], h3[id]',
+    titleSelector: 'h1[id]',
+})
+
+const emit = defineEmits<{
+    select: [item: TableOfContentsItem]
+}>()
+
+const discoveredItems = ref<TableOfContentsItem[]>([])
+const activeId = ref('')
+const pageTitle = ref('')
+const showPageTitle = ref(false)
+
+const displayedItems = computed(() => props.items ?? discoveredItems.value)
+const ariaLabel = computed(() => props.label || pageTitle.value || 'Table of contents')
+const minimumLevel = computed(() => Math.min(...displayedItems.value.map(item => item.level)))
+
+const indentClasses = ['', 'pl-12px', 'pl-24px', 'pl-36px']
+
+let headingObserver: IntersectionObserver | undefined
+let titleObserver: IntersectionObserver | undefined
+let manualClickId: string | undefined
+let manualClickTimeout: ReturnType<typeof setTimeout> | undefined
+let retryTimeout: ReturnType<typeof setTimeout> | undefined
+
+function getContentRoot() {
+    return props.contentRoot ?? document.querySelector<HTMLElement>(props.articleSelector)
+}
+
+function extractItems(contentRoot: HTMLElement) {
+    return [...contentRoot.querySelectorAll<HTMLElement>(props.headingSelector)]
+        .map(element => ({
+            id: element.id,
+            text: element.textContent?.trim() ?? '',
+            level: Number(element.tagName[1]),
+        }))
+        .filter(item => item.id && item.text)
+}
+
+function getHeadingElement(contentRoot: HTMLElement, id: string) {
+    return [...contentRoot.querySelectorAll<HTMLElement>('[id]')].find(element => element.id === id)
+}
+
+function updateActiveHeading(contentRoot: HTMLElement) {
+    if (manualClickId)
+        return
+
+    const rootTop = props.scrollRoot?.getBoundingClientRect().top ?? 0
+    const activationTop = rootTop + window.innerHeight * 0.2
+    const headingElements = displayedItems.value
+        .map(item => getHeadingElement(contentRoot, item.id))
+        .filter((element): element is HTMLElement => !!element)
+    const current = headingElements
+        .filter(element => element.getBoundingClientRect().top <= activationTop)
+        .at(-1)
+
+    activeId.value = current?.id || headingElements[0]?.id || ''
+}
+
+function disconnectObservers() {
+    headingObserver?.disconnect()
+    titleObserver?.disconnect()
+    headingObserver = undefined
+    titleObserver = undefined
+}
+
+function observe(attempts = 0) {
+    clearTimeout(retryTimeout)
+    disconnectObservers()
+
+    const contentRoot = getContentRoot()
+
+    if (!contentRoot) {
+        if (attempts < 20)
+            retryTimeout = setTimeout(() => observe(attempts + 1), 100)
+
+        return
+    }
+
+    const nextItems = props.items ?? extractItems(contentRoot)
+
+    if (props.items === undefined)
+        discoveredItems.value = nextItems
+
+    const headingElements = nextItems
+        .map(item => getHeadingElement(contentRoot, item.id))
+        .filter((element): element is HTMLElement => !!element)
+
+    if (!nextItems.length || headingElements.length < nextItems.length) {
+        if (attempts < 20)
+            retryTimeout = setTimeout(() => observe(attempts + 1), 100)
+
+        if (!headingElements.length)
+            return
+    }
+
+    activeId.value = nextItems[0]?.id ?? ''
+
+    if (typeof IntersectionObserver === 'undefined')
+        return
+
+    headingObserver = new IntersectionObserver(() => updateActiveHeading(contentRoot), {
+        root: props.scrollRoot ?? null,
+        rootMargin: '-20% 0px -70% 0px',
+        threshold: [0, 1],
+    })
+
+    for (const element of headingElements)
+        headingObserver.observe(element)
+
+    updateActiveHeading(contentRoot)
+
+    const title = contentRoot.querySelector<HTMLElement>(props.titleSelector)
+
+    pageTitle.value = title?.textContent?.trim() ?? ''
+    showPageTitle.value = false
+
+    if (title) {
+        titleObserver = new IntersectionObserver(([entry]) => {
+            const rootTop = props.scrollRoot?.getBoundingClientRect().top ?? 0
+
+            showPageTitle.value = !!entry && !entry.isIntersecting && entry.boundingClientRect.top < rootTop
+        }, {
+            root: props.scrollRoot ?? null,
+            threshold: 0,
+        })
+        titleObserver.observe(title)
+    }
+}
+
+function itemClass(item: TableOfContentsItem) {
+    const depth = Math.max(0, item.level - minimumLevel.value)
+
+    return [
+        indentClasses[Math.min(depth, indentClasses.length - 1)],
+        activeId.value === item.id ? 'text-primary' : 'text-tertiary hover:text-secondary',
+    ]
+}
+
+function scrollToHeading(item: TableOfContentsItem) {
+    const contentRoot = getContentRoot()
+    const element = contentRoot ? getHeadingElement(contentRoot, item.id) : undefined
+
+    if (!element)
+        return
+
+    clearTimeout(manualClickTimeout)
+    manualClickId = item.id
+    activeId.value = item.id
+
+    element.scrollIntoView({ behavior: 'smooth', block: 'start' })
+    history.replaceState(history.state, '', `#${item.id}`)
+    emit('select', item)
+
+    manualClickTimeout = setTimeout(() => {
+        manualClickId = undefined
+    }, 1000)
+}
+
+function scrollToTop() {
+    (props.scrollRoot ?? window).scrollTo({ top: 0, behavior: 'smooth' })
+}
+
+function cleanup() {
+    disconnectObservers()
+    clearTimeout(manualClickTimeout)
+    clearTimeout(retryTimeout)
+    manualClickId = undefined
+}
+
+onMounted(() => observe())
+onBeforeUnmount(cleanup)
+
+watch([
+    () => props.items,
+    () => props.contentRoot,
+    () => props.scrollRoot,
+], async () => {
+    await nextTick()
+    observe()
+}, { flush: 'post' })
+</script>
+
+<template>
+    <aside
+        v-if="displayedItems.length"
+        class="fixed top-0 w-340px h-screen overflow-y-auto no-scrollbar py-80px pr-48px pl-16px flex flex-col gap-12px select-none [@media(max-width:1510px)]:hidden right-[calc(60px+var(--scrollbar-width,0px))]"
+    >
+        <Motion
+            as="button"
+            type="button"
+            class="text-left body-14-medium text-primary truncate shrink-0 hover:text-secondary"
+            :initial="false"
+            :animate="{ opacity: showPageTitle ? 1 : 0 }"
+            :transition="{ ease: 'easeOut', duration: 0.15 }"
+            :style="{ pointerEvents: showPageTitle ? 'auto' : 'none' }"
+            :tabindex="showPageTitle ? 0 : -1"
+            :aria-hidden="!showPageTitle"
+            @click="scrollToTop"
+        >
+            {{ pageTitle }}
+        </Motion>
+
+        <nav :aria-label="ariaLabel" class="flex flex-col gap-6px">
+            <a
+                v-for="item in displayedItems"
+                :key="item.id"
+                :href="`#${item.id}`"
+                class="body-14-regular break-words transition-colors duration-150"
+                :class="itemClass(item)"
+                :aria-current="activeId === item.id ? 'location' : undefined"
+                @click.prevent="scrollToHeading(item)"
+            >
+                {{ item.text }}
+            </a>
+        </nav>
+    </aside>
+</template>

package/docs/interfaces.md

@@ -187,11 +187,14 @@ Before building a new page from scratch, check for an existing **layout template
 | --- | --- | --- |
 | `TelaHome` (`home.vue`) | Root index / list / dashboard pages with a sidebar rail. | `components/tela/home/home.mdx` |
 | `TelaDetails` (`details.vue`) | Full-screen detail / record pages and fullscreen modals. | `components/tela/details/details.mdx` |
+| `TelaRfc` (`rfc.vue`) | Full-screen technical proposals rendered from Markdown, with generated section navigation and diagram support. | `components/tela/rfc/rfc.mdx` |
 
 **`TelaHome`** — a flex-row shell: a sticky `TelaSidebar` beside a scrolling `TelaHomeContent` column that stacks a page title, a metric-card row (`TelaHomeMetrics`), a filter toolbar (`TelaHomeToolbar`), and a data table. It does **not** own scroll — the sidebar pins itself (`sticky top-0 h-screen`) and the page scrolls as one, no `overflow` container or height hack. Expandable detail rows are an opt-in enhancement.
 
 **`TelaDetails`** — a sticky `TelaHeader` + a single scroll container + a primary content column beside a sticky context column, with an optional confirm footer. Two documented variants — a two-column body, and a hero header above the body.
 
+**`TelaRfc`** — a centered long-form reading column with a built-in fixed `TelaTableOfContents` (H2–H4) at the right. It accepts plain Markdown directly, renders fenced code through `TelaCodeBlock`, renders fenced Mermaid flowcharts, and hides the TOC below 1511px.
+
 This table is the source of truth for layout templates. Rules:
 
 - If a layout fits the surface, use it. Don't hand-roll an equivalent.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@meistrari/tela-build",
-    "version": "1.66.0",
+    "version": "1.67.1",
     "type": "module",
     "files": [
         "app.config.ts",
@@ -25,6 +25,7 @@
         "generate-docs": "bun scripts/generate-docs.ts"
     },
     "dependencies": {
+        "@comark/vue": "0.5.1",
         "@floating-ui/vue": "1.1.5",
         "@fontsource-variable/geist-mono": "^5.2.7",
         "@fontsource-variable/inter": "^5.2.8",
@@ -41,8 +42,10 @@
         "@vueuse/components": "12.8.2",
         "@vueuse/core": "12.8.2",
         "@vueuse/nuxt": "12.8.2",
+        "beautiful-mermaid": "1.1.3",
         "class-variance-authority": "0.7.0",
         "clsx": "2.1.1",
+        "comark": "0.5.1",
         "glob": "11.0.0",
         "gsap": "3.12.5",
         "import-in-the-middle": "1.11.2",
@@ -70,20 +73,21 @@
         "typescript": "5.8.2",
         "unified": "11.0.5",
         "unocss": "66.5.12",
-        "vue": "3.5.17",
         "vue-component-meta": "3.0.8",
         "vue-docgen-api": "4.78.0",
         "vue-input-otp": "0.3.2",
         "vue-router": "4.5.0"
     },
     "peerDependencies": {
-        "nuxt": "^3.17.0 || ^4.0.0"
+        "nuxt": "^3.17.0 || ^4.0.0",
+        "vue": "^3.5.13"
     },
     "devDependencies": {
         "@nuxt/kit": "3.17.7",
         "@types/node": "18.19.79",
         "fs-extra": "11.2.0",
         "gray-matter": "4.0.3",
-        "nuxt": "3.17.7"
+        "nuxt": "3.17.7",
+        "vue": "3.5.17"
     }
 }