@meistrari/tela-build 1.65.0 → 1.65.1

package/lib/__tests__/doc-generator.test.ts

@@ -1,10 +1,10 @@
-import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { fileURLToPath } from 'node:url'
 import { dirname, join, resolve } from 'pathe'
 import matter from 'gray-matter'
 import { afterEach, describe, expect, it } from 'vitest'
-import { canonicalizeTypeString, compareCanonical, generateDocsToDirectory, resolveSiblingMdx } from '../doc-generator'
+import { canonicalizeTypeString, compareCanonical, generateDocsToDirectory, generateGroupSlug, generateTagName, parseMdxFile, resolveSiblingMdx } from '../doc-generator'
 import type { ComponentDoc } from '../doc-generator'
 import { TypeResolver } from '../type-resolver'
 
@@ -82,6 +82,73 @@ describe('generateDocsToDirectory', () => {
 
         expect(packageJson.files).toContain('docs')
     })
+
+    it('groups nested components by their source family', () => {
+        const outDir = mkdtempSync(join(tmpdir(), 'tela-build-docs-'))
+        tempDirs.push(outDir)
+
+        const makeComponent = (tagName: string, directory: string, path: string): ComponentDoc => ({
+            name: tagName,
+            tagName,
+            path,
+            directory,
+            description: '',
+            props: [],
+            events: [],
+            slots: [],
+        })
+        const components = [
+            makeComponent('TelaComplexTable', 'tela/complex-table', 'components/tela/complex-table/complex-table.vue'),
+            makeComponent('TelaComplexTableHeader', 'tela/complex-table/header', 'components/tela/complex-table/header/header.vue'),
+            makeComponent('TelaComplexBadge', 'tela/badge', 'components/tela/badge/complex-badge.vue'),
+        ]
+
+        generateDocsToDirectory(components.reverse(), new TypeResolver(outDir), outDir)
+
+        const skillMd = readFileSync(join(outDir, 'tela-build', 'SKILL.md'), 'utf-8')
+        const componentPage = readFileSync(join(outDir, 'tela-build', 'components', 'tela-complex-table.md'), 'utf-8')
+        const badgePage = readFileSync(join(outDir, 'tela-build', 'components', 'tela-badge.md'), 'utf-8')
+
+        expect(skillMd).toContain('[TelaComplexTable](components/tela-complex-table.md)')
+        expect(componentPage).toContain('## TelaComplexTable')
+        expect(componentPage).toContain('## TelaComplexTableHeader')
+        expect(badgePage).toContain('## TelaComplexBadge')
+        expect(existsSync(join(outDir, 'tela-build', 'components', 'tela-complex.md'))).toBe(false)
+    })
+})
+
+describe('nuxt-compatible component names', () => {
+    it.each([
+        ['metrics-card', 'tela/home', 'TelaHomeMetricsCard'],
+        ['hero-metrics-card', 'tela/details/hero', 'TelaDetailsHeroMetricsCard'],
+        ['index', 'tela/chat', 'TelaChat'],
+        ['index', 'tela/chat/command/mention', 'TelaChatCommandMention'],
+        ['sheet.client', 'tela/sheet', 'TelaSheet'],
+        ['sheet.server', 'tela/sheet', 'TelaSheet'],
+        ['avatar.global', 'tela/avatar', 'TelaAvatar'],
+        ['index.client', 'tela/chat', 'TelaChat'],
+        ['Item', 'tela/item/item', 'TelaItem'],
+        ['DropdownMenuSeparator', 'tela/dropdown-menu', 'TelaDropdownMenuSeparator'],
+        ['button', '', 'Button'],
+    ])('resolves %s in %s as %s', (fileName, directory, expected) => {
+        expect(generateTagName(fileName, directory)).toBe(expected)
+    })
+
+    it.each([
+        ['tela/DropdownMenu', 'tela-dropdown-menu'],
+        ['tela\\DropdownMenu', 'tela-dropdown-menu'],
+    ])('normalizes source family %s as %s', (directory, expected) => {
+        expect(generateGroupSlug({
+            name: 'TelaDropdownMenu',
+            tagName: 'TelaDropdownMenu',
+            path: 'components/tela/dropdown-menu/dropdown-menu.vue',
+            directory,
+            description: '',
+            props: [],
+            events: [],
+            slots: [],
+        })).toBe(expected)
+    })
 })
 
 // The extractors emit members in type-resolution order, which differs between
@@ -114,6 +181,35 @@ describe('resolveSiblingMdx', () => {
         expect(resolveSiblingMdx(join(dir, 'Collapsible.vue'))).toBe(join(dir, 'collapsible.mdx'))
     })
 
+    it('resolves an index component to its family MDX', () => {
+        const root = mkdtempSync(join(tmpdir(), 'tela-build-mdx-'))
+        const dir = join(root, 'chat')
+        tempDirs.push(root)
+        mkdirSync(dir)
+        writeFileSync(join(dir, 'index.vue'), '')
+        writeFileSync(join(dir, 'chat.mdx'), '')
+
+        expect(resolveSiblingMdx(join(dir, 'index.vue'))).toBe(join(dir, 'chat.mdx'))
+    })
+
+    it('resolves PascalCase component files to kebab-case MDX', () => {
+        const dir = makeComponentDir(['DropdownMenu.vue', 'dropdown-menu.mdx'])
+
+        expect(resolveSiblingMdx(join(dir, 'DropdownMenu.vue'))).toBe(join(dir, 'dropdown-menu.mdx'))
+    })
+
+    it('resolves Nuxt mode-suffixed components to unsuffixed MDX', () => {
+        const dir = makeComponentDir(['sheet.client.vue', 'sheet.mdx'])
+
+        expect(resolveSiblingMdx(join(dir, 'sheet.client.vue'))).toBe(join(dir, 'sheet.mdx'))
+    })
+
+    it('prefers an exact component MDX over normalized candidates', () => {
+        const dir = makeComponentDir(['DropdownMenu.vue', 'DropdownMenu.mdx', 'dropdown-menu.mdx'])
+
+        expect(resolveSiblingMdx(join(dir, 'DropdownMenu.vue'))).toBe(join(dir, 'DropdownMenu.mdx'))
+    })
+
     it('returns undefined when the component has no mdx', () => {
         const dir = makeComponentDir(['CollapsibleTrigger.vue', 'collapsible.mdx'])
 
@@ -125,6 +221,238 @@ describe('resolveSiblingMdx', () => {
     })
 })
 
+describe('authored MDX guidance', () => {
+    it('uses the MDX structure to preserve guidance and remove Storybook controls and authored API', async () => {
+        const mdxDir = mkdtempSync(join(tmpdir(), 'tela-build-mdx-'))
+        const outDir = mkdtempSync(join(tmpdir(), 'tela-build-docs-'))
+        tempDirs.push(mdxDir, outDir)
+
+        const mdxPath = join(mdxDir, 'sample.mdx')
+        const mdx = [
+            'import { Meta, Canvas as Preview, ArgTypes, Controls } from \'@storybook/blocks\'',
+            'import * as Blocks from \'@storybook/blocks\'',
+            'import Storybook from \'@storybook/blocks\'',
+            'import Note from \'./note.vue\'',
+            'export const Template = () => <TelaBadge />',
+            '',
+            '# TelaSample',
+            '',
+            'Content after a JSX export remains.',
+            '',
+            '<Meta title="Sample" />',
+            '',
+            '## Rules',
+            '',
+            '- Prefer the canonical component.',
+            '',
+            '<Note>Keep non-Storybook JSX.</Note>',
+            '',
+            '### Interactive preview',
+            '',
+            '<Preview',
+            '  parameters={{ format: value => value > 0 ? \'/>\' : \'>\' }}',
+            '>',
+            '```vue',
+            '<TelaStorybookOnly />',
+            '```',
+            '</Preview>',
+            '',
+            'Before <Controls /> after.',
+            '<Blocks.Source />',
+            '<Storybook.Primary />',
+            '<Storybook />',
+            '',
+            '### Basic usage',
+            '',
+            '```vue',
+            '<TelaSample />',
+            '```',
+            '',
+            '### Literal Storybook syntax',
+            '',
+            '~~~mdx',
+            '<Meta title="literal" />',
+            '~~~',
+            '',
+            '| Purpose | Component |',
+            '| --- | --- |',
+            '| Sample | TelaSample |',
+            '',
+            '## Props',
+            '',
+            'Stale authored props.',
+            '',
+            '### Nested prop notes',
+            '',
+            'These must be removed with Props.',
+            '',
+            '## Slots',
+            '',
+            'The leading slot receives row context.',
+            '',
+            '## Events',
+            '',
+            'The update event fires after validation.',
+            '',
+            '## Emits',
+            '',
+            'Catch errors from async parent handlers.',
+            '',
+            '## API',
+            '',
+            '<ArgTypes of={SampleStories} />',
+            '',
+            '## Virtualization Props',
+            '',
+            'Keep semantic prop guidance.',
+            '',
+            '## Size Prop',
+            '',
+            'Keep focused size guidance.',
+            '',
+        ].join('\n')
+        writeFileSync(mdxPath, mdx, 'utf-8')
+
+        const stories = await parseMdxFile(mdxPath)
+        const component: ComponentDoc = {
+            name: 'TelaSample',
+            tagName: 'TelaSample',
+            path: 'components/tela/sample.vue',
+            directory: 'tela',
+            description: '',
+            props: [{ name: 'variant', required: false, type: 'string' }],
+            events: [{ name: 'update', type: 'string' }],
+            slots: [{ name: 'default', description: 'Sample content' }],
+            stories,
+        }
+
+        generateDocsToDirectory([component], new TypeResolver(outDir), outDir)
+        const page = readFileSync(join(outDir, 'tela-build', 'components', 'tela-sample.md'), 'utf-8')
+
+        expect(stories?.examples).toEqual([{ name: 'Basic usage', code: '<TelaSample />' }])
+        expect(page).toContain('### Usage guidance')
+        expect(page).toContain('Content after a JSX export remains.')
+        expect(page).toContain('#### Rules')
+        expect(page).toContain('- Prefer the canonical component.')
+        expect(page).toContain('<Note>Keep non-Storybook JSX.</Note>')
+        expect(page).toContain('<Meta title="literal" />')
+        expect(page).toMatch(/\| Purpose\s+\| Component\s+\|/)
+        expect(page).toContain('#### Virtualization Props')
+        expect(page).toContain('Keep semantic prop guidance.')
+        expect(page).toContain('#### Size Prop')
+        expect(page).toContain('Keep focused size guidance.')
+        expect(page.match(/<TelaSample \/>/g)).toHaveLength(1)
+        expect(page.match(/^### Props$/gm)).toHaveLength(1)
+        expect(page.match(/^### Events$/gm)).toHaveLength(1)
+        expect(page.match(/^### Event guidance$/gm)).toHaveLength(1)
+        expect(page).toContain('The update event fires after validation.')
+        expect(page).toContain('Catch errors from async parent handlers.')
+        expect(page.match(/^### Slots$/gm)).toHaveLength(1)
+        expect(page.match(/^### Slot guidance$/gm)).toHaveLength(1)
+        expect(page).toContain('The leading slot receives row context.')
+        expect(page).not.toContain('@storybook/blocks')
+        expect(page).not.toContain('<TelaStorybookOnly />')
+        expect(page).not.toContain('<Preview')
+        expect(page).not.toContain('<Controls')
+        expect(page).not.toContain('<Blocks.Source')
+        expect(page).not.toContain('<Storybook')
+        expect(page).toMatch(/Before\s+after\./)
+        expect(page).not.toContain('Stale authored props.')
+        expect(page).not.toContain('Nested prop notes')
+        expect(page).not.toContain('<ArgTypes')
+        expect(page.match(/^# TelaSample$/gm)).toHaveLength(1)
+    })
+
+    it('preserves authored event and slot semantics when extracted metadata is incomplete', async () => {
+        const mdxDir = mkdtempSync(join(tmpdir(), 'tela-build-mdx-'))
+        const outDir = mkdtempSync(join(tmpdir(), 'tela-build-docs-'))
+        tempDirs.push(mdxDir, outDir)
+        const mdxPath = join(mdxDir, 'sample.mdx')
+        writeFileSync(mdxPath, [
+            '# TelaSample',
+            '',
+            '## Events',
+            '',
+            '`loadMore` requires errors from async parent handlers to be caught.',
+            '',
+            '## Slots',
+            '',
+            '`leading` receives row data and loading state.',
+            '',
+            '```vue',
+            '<TelaSample />',
+            '```',
+        ].join('\n'))
+
+        const stories = await parseMdxFile(mdxPath)
+        const component: ComponentDoc = {
+            name: 'TelaSample',
+            tagName: 'TelaSample',
+            path: 'components/tela/sample.vue',
+            directory: 'tela',
+            description: '',
+            props: [],
+            events: [],
+            slots: [{ name: 'leading', description: '' }],
+            stories,
+        }
+        generateDocsToDirectory([component], new TypeResolver(outDir), outDir)
+        const page = readFileSync(join(outDir, 'tela-build', 'components', 'tela-sample.md'), 'utf-8')
+
+        expect(page).not.toContain('### Events\n')
+        expect(page).toContain('### Event guidance')
+        expect(page).toContain('requires errors from async parent handlers to be caught')
+        expect(page).toContain('### Slots')
+        expect(page).toContain('| `leading` | — |  |')
+        expect(page).toContain('### Slot guidance')
+        expect(page).toContain('receives row data and loading state')
+        expect(page.match(/<TelaSample \/>/g)).toHaveLength(1)
+        expect(page).not.toContain('### Examples')
+        expect(stories?.examples).toEqual([{ name: 'Slots', code: '<TelaSample />' }])
+    })
+
+    it('does not restore fenced examples removed with a Storybook subtree', async () => {
+        const dir = mkdtempSync(join(tmpdir(), 'tela-build-mdx-'))
+        tempDirs.push(dir)
+        const mdxPath = join(dir, 'sample.mdx')
+        writeFileSync(mdxPath, [
+            'import { Canvas } from \'@storybook/blocks\'',
+            '',
+            '# TelaSample',
+            '',
+            '## Interactive preview',
+            '',
+            '<Canvas>',
+            '```vue',
+            '<TelaStorybookOnly />',
+            '```',
+            '</Canvas>',
+        ].join('\n'))
+
+        const stories = await parseMdxFile(mdxPath)
+
+        expect(stories?.content).toBe('')
+        expect(stories?.examples).toEqual([])
+    })
+
+    it('preserves similarly named JSX not imported from Storybook', async () => {
+        const dir = mkdtempSync(join(tmpdir(), 'tela-build-mdx-'))
+        tempDirs.push(dir)
+        const mdxPath = join(dir, 'sample.mdx')
+        writeFileSync(mdxPath, [
+            'import Canvas from \'./canvas.vue\'',
+            '',
+            '# TelaSample',
+            '',
+            '<Canvas>Keep this content.</Canvas>',
+        ].join('\n'))
+
+        const stories = await parseMdxFile(mdxPath)
+
+        expect(stories?.content).toContain('<Canvas>Keep this content.</Canvas>')
+    })
+})
+
 describe('canonical ordering', () => {
     function makeDoc(overrides: Partial<ComponentDoc> = {}): ComponentDoc {
         return {

package/lib/doc-generator.ts

@@ -2,6 +2,15 @@
 import { join, resolve, relative, dirname, basename } from 'pathe'
 import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, unlinkSync } from 'node:fs'
 import { parse as parseVue } from 'vue-docgen-api'
+import { pascalCase, splitByCase } from 'scule'
+import ts from 'typescript'
+import { unified } from 'unified'
+import remarkParse from 'remark-parse'
+import remarkMdx from 'remark-mdx'
+import remarkGfm from 'remark-gfm'
+import remarkStringify from 'remark-stringify'
+import type { Code, Heading, Root, RootContent } from 'mdast'
+import type { MdxJsxFlowElement, MdxJsxTextElement, MdxjsEsm } from 'mdast-util-mdx'
 // Load glob dynamically for compatibility across versions (v8 vs v11)
 import { getTypeResolver } from './type-resolver'
 import type { TypeResolver } from './type-resolver'
@@ -29,9 +38,17 @@ export interface ComponentDoc {
     parseError?: string
 }
 
+export interface StoryExample {
+    name: string
+    code: string
+}
+
 export interface StoryDoc {
     title: string
-    examples: any[]
+    content: string
+    eventGuidance: string
+    slotGuidance: string
+    examples: StoryExample[]
     argTypes: any
 }
 
@@ -285,8 +302,8 @@ export async function collectComponentDocs(layerPath: string, appRootDir?: strin
         const fileName = basename(file, '.vue')
         const directory = relative(componentPath, dirname(file))
 
-        // Generate component tag name
-        const tagName = generateTagName(fileName)
+        // Match Nuxt's path-aware component auto-import name.
+        const tagName = generateTagName(fileName, directory)
 
         const componentDoc: ComponentDoc = {
             name: info.displayName || info.exportName || fileName,
@@ -355,99 +372,120 @@ async function globAsync(pattern: string, options: any): Promise<string[]> {
     return []
 }
 
-export function generateTagName(fileName: string): string {
-    // Convert file name to PascalCase tag name
-    // Components in tela/ directory should preserve the Tela prefix
-    // e.g., input -> TelaInput, button -> TelaButton
+const COMPONENT_MODE_REPLACEMENT = /(?:\.(?:client|server))?(?:\.global|\.island)*$/
 
-    let tagName: string
+/**
+ * Mirror Nuxt's directory-aware component naming. Directory segments prefix the
+ * file name, repeated suffixes are collapsed, `index.vue` resolves to its
+ * directory, and mode suffixes such as `.client.vue` are not part of the tag.
+ */
+export function generateTagName(fileName: string, directory: string): string {
+    const prefixParts = splitByCase(directory)
+    const normalizedFileName = fileName
+        .replace(COMPONENT_MODE_REPLACEMENT, '')
+        .replace(/^index$/i, '')
+    const fileNameParts = splitByCase(normalizedFileName)
+    const fileNamePartsContent = fileNameParts.join('/').toLowerCase()
+    const componentNameParts = prefixParts.flatMap(part => splitByCase(part))
+
+    let index = prefixParts.length - 1
+    const matchedSuffix: string[] = []
+    while (index >= 0) {
+        const prefixPart = prefixParts[index]
+        if (!prefixPart) {
+            index--
+            continue
+        }
 
-    // Check if the file already starts with 'tela-'
-    if (fileName.startsWith('tela-')) {
-    // Already has tela prefix, just convert to PascalCase
-        const parts = fileName.split('-')
-        tagName = parts.map(part =>
-            part.charAt(0).toUpperCase() + part.slice(1),
-        ).join('')
-    }
-    else {
-    // Add Tela prefix for components without it
-        const parts = fileName.split('-')
-        const componentName = parts.map(part =>
-            part.charAt(0).toUpperCase() + part.slice(1),
-        ).join('')
-        tagName = `Tela${componentName}`
+        matchedSuffix.unshift(...splitByCase(prefixPart).map(part => part.toLowerCase()))
+        const matchedSuffixContent = matchedSuffix.join('/')
+        const repeatedDirectory = prefixPart.toLowerCase() === fileNamePartsContent
+            && prefixParts[index + 1]
+            && prefixParts[index] === prefixParts[index + 1]
+
+        if (
+            fileNamePartsContent === matchedSuffixContent
+            || fileNamePartsContent.startsWith(`${matchedSuffixContent}/`)
+            || repeatedDirectory
+        ) {
+            componentNameParts.length = index
+        }
+        index--
     }
 
-    return tagName
+    return pascalCase([...componentNameParts, ...fileNameParts])
 }
 
 /**
- * Find the `.mdx` next to a component, matching the way the filesystem does
- * rather than the way one particular filesystem does.
- *
- * `components/tela/collapsible/Collapsible.vue` is documented by
- * `collapsible.mdx` — the casings differ. A plain `existsSync()` on the derived
- * `Collapsible.mdx` is true on macOS (case-insensitive APFS quietly resolves it)
- * and false on Linux, so CI generated that component with its examples missing
- * and reported the committed page as drift. Resolve through the directory
- * listing instead, so both platforms find the same file — and pick the
- * lowest-sorting candidate, because a case-sensitive filesystem is free to hold
- * several files that differ only in case.
+ * Resolve the authored MDX associated with a component using the same filename
+ * normalization as Nuxt component discovery. Family docs commonly use the
+ * directory name for `index.vue`, kebab-case for PascalCase component files,
+ * and omit `.client` / `.server` mode suffixes.
  */
 export function resolveSiblingMdx(vueFile: string): string | undefined {
-    const mdxPath = vueFile.replace(/\.vue$/, '.mdx')
-    const directory = dirname(mdxPath)
+    const directory = dirname(vueFile)
     if (!existsSync(directory)) {
         return undefined
     }
 
-    // Resolved against the listing rather than existsSync() on both branches:
-    // an exact-path probe reports a hit on macOS for a name that is not on disk,
-    // which would put the derived casing into the output on one platform and the
-    // real filename on the other.
-    const wanted = basename(mdxPath)
+    const fileName = basename(vueFile, '.vue')
+    const normalizedFileName = fileName.replace(COMPONENT_MODE_REPLACEMENT, '')
+    const normalizedCandidates = normalizedFileName.toLowerCase() === 'index'
+        ? [toKebabFromTag(basename(directory)), normalizedFileName, fileName]
+        : [fileName, normalizedFileName, toKebabFromTag(normalizedFileName)]
+    const candidates = [...new Set(normalizedCandidates.map(candidate => `${candidate}.mdx`))]
     const entries = readdirSync(directory).sort(compareCanonical)
-    const match = entries.find(entry => entry === wanted)
-        ?? entries.find(entry => entry.toLowerCase() === wanted.toLowerCase())
+
+    // Check every normalized candidate exactly before trying case-insensitive
+    // matches, so a fuzzy match cannot beat a deterministic Nuxt-style name.
+    const exactMatch = candidates
+        .map(candidate => entries.find(entry => entry === candidate))
+        .find(Boolean)
+    const caseInsensitiveMatch = candidates
+        .map(candidate => entries.find(entry => entry.toLowerCase() === candidate.toLowerCase()))
+        .find(Boolean)
+    const match = exactMatch ?? caseInsensitiveMatch
 
     return match ? join(directory, match) : undefined
 }
 
-export async function parseMdxFile(mdxPath: string): Promise<StoryDoc | undefined> {
-    try {
-        const content = readFileSync(mdxPath, 'utf-8')
-
-        // Extract title from the main heading
-        const titleMatch = content.match(/^#\s+(.+)$/m)
-        const title = titleMatch?.[1] ?? ''
-
-        // Extract code examples from ```vue blocks with better heading detection
-        const examples: any[] = []
-        const codeBlockRegex = /```vue\n([\s\S]*?)\n```/g
-        const matches = Array.from(content.matchAll(codeBlockRegex))
-
-        for (let i = 0; i < matches.length; i++) {
-            const match = matches[i]
-            const codeContent = match?.[1]?.trim()
-            const codeBlockStart = match?.index
-            if (!codeContent || codeBlockStart === undefined) {
-                continue
-            }
+type MdxContent = RootContent | MdxJsxFlowElement | MdxJsxTextElement | MdxjsEsm
+type MdxRoot = Omit<Root, 'children'> & { children: MdxContent[] }
+type MdxParent = MdxContent & { children: MdxContent[] }
 
-            // Find the closest heading before this code block
-            const beforeCode = content.substring(0, codeBlockStart)
-            const exampleName = findClosestHeading(beforeCode, i + 1)
+interface StorybookBindings {
+    names: Set<string>
+    namespaces: Set<string>
+}
 
-            examples.push({
-                name: exampleName,
-                code: codeContent,
-            })
-        }
+interface SanitizedMdx {
+    title: string
+    content: string
+    eventGuidance: string
+    slotGuidance: string
+    examples: StoryExample[]
+}
+
+const AUTHORED_API_SECTIONS = new Set(['api', 'emits', 'events', 'props', 'slots'])
+const mdxProcessor = unified()
+    .use(remarkParse)
+    .use(remarkMdx)
+    .use(remarkGfm)
+    .use(remarkStringify, {
+        bullet: '-',
+        fences: true,
+    })
+
+export async function parseMdxFile(mdxPath: string): Promise<StoryDoc | undefined> {
+    try {
+        const sanitized = sanitizeMdxContent(readFileSync(mdxPath, 'utf-8'))
 
         return {
-            title,
-            examples,
+            title: sanitized.title,
+            content: sanitized.content,
+            eventGuidance: sanitized.eventGuidance,
+            slotGuidance: sanitized.slotGuidance,
+            examples: sanitized.examples,
             argTypes: '',
         }
     }
@@ -457,39 +495,264 @@ export async function parseMdxFile(mdxPath: string): Promise<StoryDoc | undefine
     }
 }
 
-function findClosestHeading(textBeforeCode: string, exampleIndex: number): string {
-    // Split into lines and work backwards to find the closest heading
-    const lines = textBeforeCode.split('\n')
+function isMdxEsm(node: MdxContent): node is MdxjsEsm {
+    return node.type === 'mdxjsEsm'
+}
+
+function isMdxJsxElement(node: MdxContent): node is MdxJsxFlowElement | MdxJsxTextElement {
+    return node.type === 'mdxJsxFlowElement' || node.type === 'mdxJsxTextElement'
+}
+
+function isHeading(node: MdxContent): node is Heading {
+    return node.type === 'heading'
+}
+
+function isCode(node: MdxContent): node is Code {
+    return node.type === 'code'
+}
+
+function hasChildren(node: MdxContent): node is MdxParent {
+    return 'children' in node && Array.isArray(node.children)
+}
+
+function readNodeText(node: MdxContent): string {
+    if ('value' in node && typeof node.value === 'string')
+        return node.value
+    if (!hasChildren(node))
+        return ''
+    return node.children.map(readNodeText).join('')
+}
 
-    // Look for headings starting from the end (closest to code block)
-    for (let i = lines.length - 1; i >= 0; i--) {
-        const rawLine = lines[i]
-        if (!rawLine) {
+function collectStorybookBindings(nodes: MdxContent[]): StorybookBindings {
+    const bindings: StorybookBindings = {
+        names: new Set(),
+        namespaces: new Set(),
+    }
+
+    for (const node of nodes) {
+        if (!isMdxEsm(node))
             continue
+
+        const sourceFile = ts.createSourceFile('documentation.mtsx', node.value, ts.ScriptTarget.Latest, false, ts.ScriptKind.TSX)
+        for (const statement of sourceFile.statements) {
+            if (!ts.isImportDeclaration(statement)
+                || !ts.isStringLiteral(statement.moduleSpecifier)
+                || statement.moduleSpecifier.text !== '@storybook/blocks'
+                || !statement.importClause) {
+                continue
+            }
+
+            if (statement.importClause.name) {
+                bindings.names.add(statement.importClause.name.text)
+                bindings.namespaces.add(statement.importClause.name.text)
+            }
+
+            const namedBindings = statement.importClause.namedBindings
+            if (namedBindings && ts.isNamespaceImport(namedBindings)) {
+                bindings.namespaces.add(namedBindings.name.text)
+            }
+            else if (namedBindings && ts.isNamedImports(namedBindings)) {
+                for (const element of namedBindings.elements)
+                    bindings.names.add(element.name.text)
+            }
         }
-        const line = rawLine.trim()
+    }
+
+    return bindings
+}
+
+function isStorybookElement(node: MdxJsxFlowElement | MdxJsxTextElement, bindings: StorybookBindings): boolean {
+    if (!node.name)
+        return false
+    if (bindings.names.has(node.name))
+        return true
+
+    const separator = node.name.indexOf('.')
+    return separator > 0 && bindings.namespaces.has(node.name.slice(0, separator))
+}
+
+function removeMdxArtifacts(nodes: MdxContent[], storybookBindings: StorybookBindings): MdxContent[] {
+    const retained: MdxContent[] = []
 
-        // Check for markdown headings (### or ####)
-        const headingMatch = line.match(/^###?\s+(.+)/)
-        if (headingMatch) {
-            return headingMatch?.[1]?.trim() ?? `Example ${exampleIndex}`
+    for (const node of nodes) {
+        if (isMdxEsm(node) || (isMdxJsxElement(node) && isStorybookElement(node, storybookBindings)))
+            continue
+
+        if (hasChildren(node)) {
+            const children = removeMdxArtifacts(node.children, storybookBindings)
+            node.children.splice(0, node.children.length, ...children)
+            if (node.type === 'paragraph' && children.length === 0)
+                continue
         }
 
-        // Check for bold text that might be a heading (**text**)
-        const boldMatch = line.match(/^\*\*([^*]+)\*\*\s*$/)
-        if (boldMatch) {
-            return boldMatch?.[1]?.trim() ?? `Example ${exampleIndex}`
+        retained.push(node)
+    }
+
+    return retained
+}
+
+function stripFirstTitle(nodes: MdxContent[]): MdxContent[] {
+    let removed = false
+    return nodes.filter((node) => {
+        if (!removed && isHeading(node) && node.depth === 1) {
+            removed = true
+            return false
         }
+        return true
+    })
+}
+
+interface AuthoredApiSections {
+    content: MdxContent[]
+    eventGuidance: MdxContent[]
+    slotGuidance: MdxContent[]
+}
 
-        // If we hit a higher level heading (## or #), stop looking
-        // This prevents us from going too far up the document
-        if (line.match(/^##?\s+/) && !line.match(/^###/)) {
-            break
+function extractAuthoredApiSections(nodes: MdxContent[]): AuthoredApiSections {
+    const sections: AuthoredApiSections = {
+        content: [],
+        eventGuidance: [],
+        slotGuidance: [],
+    }
+    let index = 0
+
+    while (index < nodes.length) {
+        const node = nodes[index]
+        if (!node) {
+            index++
+            continue
         }
+
+        if (!isHeading(node)) {
+            sections.content.push(node)
+            index++
+            continue
+        }
+
+        const sectionName = readNodeText(node).trim().toLowerCase()
+        if (!AUTHORED_API_SECTIONS.has(sectionName)) {
+            sections.content.push(node)
+            index++
+            continue
+        }
+
+        const sectionDepth = node.depth
+        const sectionContent: MdxContent[] = []
+        index++
+        while (index < nodes.length) {
+            const candidate = nodes[index]
+            if (candidate && isHeading(candidate) && candidate.depth <= sectionDepth)
+                break
+            if (candidate)
+                sectionContent.push(candidate)
+            index++
+        }
+
+        if (sectionName === 'events' || sectionName === 'emits')
+            sections.eventGuidance.push(...sectionContent)
+        else if (sectionName === 'slots')
+            sections.slotGuidance.push(...sectionContent)
     }
 
-    // Fallback to generic name
-    return `Example ${exampleIndex}`
+    return sections
+}
+
+function stripEmptyHeadings(nodes: MdxContent[]): MdxContent[] {
+    return nodes.filter((node, index) => {
+        if (!isHeading(node))
+            return true
+
+        const boundary = nodes.findIndex((candidate, candidateIndex) =>
+            candidateIndex > index && isHeading(candidate) && candidate.depth <= node.depth)
+        const sectionEnd = boundary === -1 ? nodes.length : boundary
+        return nodes.slice(index + 1, sectionEnd).some(candidate => !isHeading(candidate))
+    })
+}
+
+function collectVueExamples(nodes: MdxContent[], initialHeading = '', startingIndex = 0): StoryExample[] {
+    const examples: StoryExample[] = []
+    let currentHeading = initialHeading
+
+    const visit = (children: MdxContent[]): void => {
+        for (const node of children) {
+            if (isHeading(node))
+                currentHeading = readNodeText(node).trim()
+            if (isCode(node) && node.lang?.toLowerCase() === 'vue' && node.value.trim()) {
+                examples.push({
+                    name: currentHeading || `Example ${startingIndex + examples.length + 1}`,
+                    code: node.value.trim(),
+                })
+            }
+            if (hasChildren(node))
+                visit(node.children)
+        }
+    }
+
+    visit(nodes)
+    return examples
+}
+
+function shiftHeadingDepth(depth: Heading['depth'], offset: number): Heading['depth'] {
+    const shifted = Math.min(6, depth + offset)
+    if (shifted === 1)
+        return 1
+    if (shifted === 2)
+        return 2
+    if (shifted === 3)
+        return 3
+    if (shifted === 4)
+        return 4
+    if (shifted === 5)
+        return 5
+    return 6
+}
+
+function shiftHeadings(nodes: MdxContent[], offset: number): void {
+    for (const node of nodes) {
+        if (isHeading(node))
+            node.depth = shiftHeadingDepth(node.depth, offset)
+        if (hasChildren(node))
+            shiftHeadings(node.children, offset)
+    }
+}
+
+function stringifyGuidance(nodes: MdxContent[]): string {
+    const content = stripEmptyHeadings(nodes)
+    if (content.length === 0)
+        return ''
+
+    shiftHeadings(content, 1)
+    const tree: MdxRoot = { type: 'root', children: content }
+    return mdxProcessor.stringify(tree).trim()
+}
+
+function sanitizeMdxContent(source: string): SanitizedMdx {
+    const tree: MdxRoot = mdxProcessor.parse(source)
+    const titleNode = tree.children.find(node => isHeading(node) && node.depth === 1)
+    const title = titleNode && isHeading(titleNode) ? readNodeText(titleNode).trim() : ''
+    const storybookBindings = collectStorybookBindings(tree.children)
+
+    tree.children = removeMdxArtifacts(tree.children, storybookBindings)
+    tree.children = stripFirstTitle(tree.children)
+    const authoredApi = extractAuthoredApiSections(tree.children)
+    tree.children = stripEmptyHeadings(authoredApi.content)
+
+    const contentExamples = collectVueExamples(tree.children)
+    const eventExamples = collectVueExamples(authoredApi.eventGuidance, 'Events', contentExamples.length)
+    const slotExamples = collectVueExamples(
+        authoredApi.slotGuidance,
+        'Slots',
+        contentExamples.length + eventExamples.length,
+    )
+    shiftHeadings(tree.children, 2)
+
+    return {
+        title,
+        content: mdxProcessor.stringify(tree).trim(),
+        eventGuidance: stringifyGuidance(authoredApi.eventGuidance),
+        slotGuidance: stringifyGuidance(authoredApi.slotGuidance),
+        examples: [...contentExamples, ...eventExamples, ...slotExamples],
+    }
 }
 
 export function generateMarkdown(componentDocs: ComponentDoc[], typeResolver: TypeResolver): string {
@@ -677,11 +940,10 @@ export function generateDocsToDirectory(componentDocs: ComponentDoc[], typeResol
         mkdirSync(supportingDir, { recursive: true })
     }
 
-    // Group components by family (e.g., tela-dropdown-*) → tela-dropdown.md
+    // Group components by their source family (e.g., tela/complex-table/* → tela-complex-table.md).
     const groups = new Map<string, ComponentDoc[]>()
     for (const comp of componentDocs.map(canonicalizeComponentDoc)) {
-        const kebab = toKebabFromTag(comp.tagName)
-        const group = toGroupSlugFromKebab(kebab)
+        const group = generateGroupSlug(comp)
         if (!groups.has(group))
             groups.set(group, [])
         groups.get(group)!.push(comp)
@@ -807,9 +1069,16 @@ function generateSingleComponentMarkdown(comp: ComponentDoc, typeResolver: TypeR
         lines.push('')
     }
 
+    if (comp.stories?.content) {
+        lines.push('### Usage guidance')
+        lines.push('')
+        lines.push(comp.stories.content)
+        lines.push('')
+    }
+
     // Props
     if (comp.props && comp.props.length > 0) {
-        lines.push('## Props')
+        lines.push('### Props')
         lines.push('')
         lines.push('```typescript')
         lines.push('interface Props {')
@@ -833,7 +1102,7 @@ function generateSingleComponentMarkdown(comp: ComponentDoc, typeResolver: TypeR
 
     // Events
     if (comp.events && comp.events.length > 0) {
-        lines.push('## Events')
+        lines.push('### Events')
         lines.push('')
         lines.push('| Event | Type | Description |')
         lines.push('|------:|:-----|:------------|')
@@ -846,9 +1115,16 @@ function generateSingleComponentMarkdown(comp: ComponentDoc, typeResolver: TypeR
         lines.push('')
     }
 
+    if (comp.stories?.eventGuidance) {
+        lines.push('### Event guidance')
+        lines.push('')
+        lines.push(comp.stories.eventGuidance)
+        lines.push('')
+    }
+
     // Slots
     if (comp.slots && comp.slots.length > 0) {
-        lines.push('## Slots')
+        lines.push('### Slots')
         lines.push('')
         lines.push('| Slot | Scoped Props | Description |')
         lines.push('|-----:|:-------------|:------------|')
@@ -861,12 +1137,21 @@ function generateSingleComponentMarkdown(comp: ComponentDoc, typeResolver: TypeR
         lines.push('')
     }
 
-    // Examples (from MDX)
-    if (comp.stories && comp.stories.examples && comp.stories.examples.length > 0) {
-        lines.push('## Examples')
+    if (comp.stories?.slotGuidance) {
+        lines.push('### Slot guidance')
+        lines.push('')
+        lines.push(comp.stories.slotGuidance)
+        lines.push('')
+    }
+
+    if (!comp.stories?.content
+        && !comp.stories?.eventGuidance
+        && !comp.stories?.slotGuidance
+        && comp.stories?.examples.length) {
+        lines.push('### Examples')
         lines.push('')
         comp.stories.examples.forEach((ex: any) => {
-            lines.push(`### ${ex.name}`)
+            lines.push(`#### ${ex.name}`)
             lines.push('')
             lines.push('```vue')
             lines.push(ex.code)
@@ -979,12 +1264,11 @@ function renderPantryFrontmatter(pantry: SkillPantryMetadata): string[] {
     return lines
 }
 
-function toGroupSlugFromKebab(kebab: string): string {
-    const parts = kebab.split('-').filter(Boolean)
-    if (parts.length <= 2)
-        return kebab
-    // Prefer first two parts (e.g., tela-dropdown), otherwise fallback to entire kebab
-    return `${parts[0]}-${parts[1]}`
+export function generateGroupSlug(comp: ComponentDoc): string {
+    const directoryParts = comp.directory.split(/[\\/]/).filter(Boolean)
+    if (directoryParts.length > 1)
+        return directoryParts.slice(0, 2).map(toKebabFromTag).join('-')
+    return toKebabFromTag(comp.tagName)
 }
 
 function toTitleFromGroupSlug(groupSlug: string): string {

package/package.json

@@ -1,85 +1,89 @@
 {
-  "name": "@meistrari/tela-build",
-  "version": "1.65.0",
-  "type": "module",
-  "files": [
-    "app.config.ts",
-    "components",
-    "components.json",
-    "composables",
-    "css",
-    "docs",
-    "lib",
-    "modules",
-    "nuxt.config.ts",
-    "plugins",
-    "public",
-    "tsconfig.json",
-    "types",
-    "unocss.config.ts",
-    "utils"
-  ],
-  "main": "./nuxt.config.ts",
-  "scripts": {
-    "postinstall": "nuxt prepare",
-    "generate-docs": "bun scripts/generate-docs.ts"
-  },
-  "dependencies": {
-    "@floating-ui/vue": "1.1.5",
-    "@fontsource-variable/geist-mono": "^5.2.7",
-    "@fontsource-variable/inter": "^5.2.8",
-    "@iconify-json/ph": "1.2.2",
-    "@internationalized/date": "3.6.0",
-    "@internationalized/number": "3.6.0",
-    "@number-flow/vue": "^0.3.2",
-    "@nuxt/icon": "^1.9.0",
-    "@nuxtjs/color-mode": "^3.5.2",
-    "@nuxtjs/tailwindcss": "6.12.2",
-    "@unocss/nuxt": "66.5.12",
-    "@unocss/transformer-directives": "66.5.12",
-    "@vueuse/components": "12.8.2",
-    "@vueuse/core": "12.8.2",
-    "@vueuse/nuxt": "12.8.2",
-    "class-variance-authority": "0.7.0",
-    "clsx": "2.1.1",
-    "glob": "11.0.0",
-    "gsap": "3.12.5",
-    "import-in-the-middle": "1.11.2",
-    "lucide-vue-next": "0.456.0",
-    "motion": "10.16.4",
-    "motion-v": "2.3.0",
-    "nitropack": "2.9.7",
-    "number-flow": "0.4.1",
-    "nuxt-svgo": "4.2.6",
-    "pathe": "1.1.2",
-    "pdfjs-dist": "4.10.38",
-    "radix-vue": "1.9.17",
-    "reka-ui": "2.3.0",
-    "resize-observer-polyfill": "1.5.1",
-    "shiki": "2.5.0",
-    "tailwind-merge": "2.5.4",
-    "tailwindcss-animate": "1.0.7",
-    "ts-morph": "22.0.0",
-    "typescript": "5.8.2",
-    "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"
-  },
-  "devDependencies": {
-    "@nuxt/kit": "3.17.7",
-    "@types/node": "18.19.79",
-    "fs-extra": "11.2.0",
-    "gray-matter": "4.0.3",
-    "remark-gfm": "4.0.0",
-    "remark-parse": "11.0.0",
-    "remark-stringify": "11.0.0",
-    "nuxt": "3.17.7",
-    "unified": "11.0.0"
-  }
+    "name": "@meistrari/tela-build",
+    "version": "1.65.1",
+    "type": "module",
+    "files": [
+        "app.config.ts",
+        "components",
+        "components.json",
+        "composables",
+        "css",
+        "docs",
+        "lib",
+        "modules",
+        "nuxt.config.ts",
+        "plugins",
+        "public",
+        "tsconfig.json",
+        "types",
+        "unocss.config.ts",
+        "utils"
+    ],
+    "main": "./nuxt.config.ts",
+    "scripts": {
+        "postinstall": "nuxt prepare",
+        "generate-docs": "bun scripts/generate-docs.ts"
+    },
+    "dependencies": {
+        "@floating-ui/vue": "1.1.5",
+        "@fontsource-variable/geist-mono": "^5.2.7",
+        "@fontsource-variable/inter": "^5.2.8",
+        "@iconify-json/ph": "1.2.2",
+        "@internationalized/date": "3.6.0",
+        "@internationalized/number": "3.6.0",
+        "@number-flow/vue": "^0.3.2",
+        "@nuxt/icon": "^1.9.0",
+        "@types/mdast": "4.0.4",
+        "@nuxtjs/color-mode": "^3.5.2",
+        "@nuxtjs/tailwindcss": "6.12.2",
+        "@unocss/nuxt": "66.5.12",
+        "@unocss/transformer-directives": "66.5.12",
+        "@vueuse/components": "12.8.2",
+        "@vueuse/core": "12.8.2",
+        "@vueuse/nuxt": "12.8.2",
+        "class-variance-authority": "0.7.0",
+        "clsx": "2.1.1",
+        "glob": "11.0.0",
+        "gsap": "3.12.5",
+        "import-in-the-middle": "1.11.2",
+        "lucide-vue-next": "0.456.0",
+        "mdast-util-mdx": "3.0.0",
+        "motion": "10.16.4",
+        "motion-v": "2.3.0",
+        "nitropack": "2.9.7",
+        "number-flow": "0.4.1",
+        "nuxt-svgo": "4.2.6",
+        "pathe": "1.1.2",
+        "pdfjs-dist": "4.10.38",
+        "radix-vue": "1.9.17",
+        "reka-ui": "2.3.0",
+        "remark-gfm": "4.0.0",
+        "remark-mdx": "3.1.1",
+        "remark-parse": "11.0.0",
+        "remark-stringify": "11.0.0",
+        "resize-observer-polyfill": "1.5.1",
+        "scule": "1.3.0",
+        "shiki": "2.5.0",
+        "tailwind-merge": "2.5.4",
+        "tailwindcss-animate": "1.0.7",
+        "ts-morph": "22.0.0",
+        "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"
+    },
+    "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"
+    }
 }