storybook-addon-md 0.1.0

package/dist/content.js

@@ -0,0 +1,188 @@
+import { readFile, realpath, stat } from 'node:fs/promises';
+import path from 'node:path';
+import glob from 'fast-glob';
+import { isMap, parseDocument } from 'yaml';
+import { unified } from 'unified';
+import remarkParse from 'remark-parse';
+import remarkGfm from 'remark-gfm';
+import remarkStringify from 'remark-stringify';
+import { visit } from 'unist-util-visit';
+const markdown = unified().use(remarkParse).use(remarkGfm).use(remarkStringify);
+const storyExtensions = ['tsx', 'ts', 'jsx', 'js'];
+export const slash = (value) => value.split(path.sep).join('/');
+export const fail = (source, message) => new Error(`[storybook-addon-md] ${source}: ${message}`);
+export async function localFile(file, root, source, kind) {
+    try {
+        const actual = await realpath(file);
+        const relative = path.relative(await realpath(root), actual);
+        if (relative.startsWith(`..${path.sep}`) || relative === '..' || path.isAbsolute(relative)) {
+            throw fail(source, `${kind} must be inside root: ${file}`);
+        }
+        if (!(await stat(actual)).isFile())
+            throw new Error('not a file');
+        return file;
+    }
+    catch (error) {
+        if (error instanceof Error && error.message.startsWith('[storybook-addon-md]'))
+            throw error;
+        throw Object.assign(fail(source, `missing ${kind}: ${file}`), { dependency: file });
+    }
+}
+export function parseMarkdown(text, source) {
+    const normalized = text.replace(/^\uFEFF/, '').replace(/\r\n/g, '\n');
+    if (!normalized.startsWith('---\n'))
+        return { body: normalized, metadata: {} };
+    const end = /^---\s*$/gm;
+    end.lastIndex = 4;
+    const closing = end.exec(normalized);
+    if (!closing)
+        throw fail(source, 'frontmatter must end with ---');
+    const yaml = parseDocument(normalized.slice(4, closing.index), { uniqueKeys: true });
+    if (yaml.errors.length)
+        throw fail(source, `invalid frontmatter: ${yaml.errors[0].message}`);
+    if (yaml.warnings.length)
+        throw fail(source, `invalid frontmatter: ${yaml.warnings[0].message}`);
+    if (yaml.contents && !isMap(yaml.contents))
+        throw fail(source, 'frontmatter must be a mapping');
+    let metadata;
+    try {
+        metadata = yaml.toJS({ maxAliasCount: 50 }) ?? {};
+        JSON.stringify(metadata, (_, value) => {
+            if (typeof value === 'number' && !Number.isFinite(value))
+                throw new Error('metadata numbers must be finite');
+            return value;
+        });
+    }
+    catch (error) {
+        throw fail(source, `invalid frontmatter: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (typeof metadata !== 'object' || Array.isArray(metadata)) {
+        throw fail(source, 'frontmatter must be a mapping');
+    }
+    for (const key of Object.keys(metadata)) {
+        if (!/^[a-z][a-z0-9_-]*$/.test(key))
+            throw fail(source, `frontmatter keys must be lowercase: ${key}`);
+    }
+    if ('title' in metadata && (typeof metadata.title !== 'string' || !metadata.title.trim())) {
+        throw fail(source, 'title must be a non-empty string');
+    }
+    if ('status' in metadata && (typeof metadata.status !== 'string' || !metadata.status.trim())) {
+        throw fail(source, 'status must be a non-empty string');
+    }
+    if ('tags' in metadata &&
+        (!Array.isArray(metadata.tags) ||
+            metadata.tags.some((tag) => typeof tag !== 'string' || !tag.trim()))) {
+        throw fail(source, 'tags must be an array of non-empty strings');
+    }
+    if ('stories' in metadata) {
+        const references = Array.isArray(metadata.stories) ? metadata.stories : [metadata.stories];
+        if (!references.length || references.some((ref) => typeof ref !== 'string' || !ref.trim())) {
+            throw fail(source, 'stories must be a relative path or a non-empty array of relative paths');
+        }
+    }
+    return { body: normalized.slice(closing.index + closing[0].length).replace(/^\n/, ''), metadata };
+}
+async function associations(file, metadata, root) {
+    if ('stories' in metadata) {
+        const references = Array.isArray(metadata.stories) ? metadata.stories : [metadata.stories];
+        return Promise.all([...new Set(references)].map(async (ref) => {
+            if (path.isAbsolute(ref) || !/\.stories\.[jt]sx?$/.test(ref)) {
+                throw fail(file, `stories must reference a relative .stories.js, .jsx, .ts, or .tsx file: ${ref}`);
+            }
+            return localFile(path.resolve(path.dirname(file), ref), root, file, 'story reference');
+        }));
+    }
+    if (!file.endsWith('.metadata.md'))
+        return [];
+    const base = file.slice(0, -'.metadata.md'.length);
+    const matches = [];
+    for (const extension of storyExtensions) {
+        const candidate = `${base}.stories.${extension}`;
+        if (await stat(candidate).then((value) => value.isFile(), () => false))
+            matches.push(candidate);
+    }
+    if (matches.length !== 1) {
+        throw Object.assign(fail(file, matches.length
+            ? 'ambiguous sibling stories; set stories explicitly'
+            : 'missing sibling story for .metadata.md; set stories explicitly or rename the Markdown file'), { dependencies: storyExtensions.map((extension) => `${base}.stories.${extension}`) });
+    }
+    return [await localFile(matches[0], root, file, 'story reference')];
+}
+export async function resolveAssets(body, file, root) {
+    const tree = markdown.parse(body);
+    const nodes = [];
+    visit(tree, (node) => {
+        if (node.type === 'image' || node.type === 'link' || node.type === 'definition')
+            nodes.push(node);
+    });
+    const assets = [];
+    for (const node of nodes) {
+        const url = node.url;
+        if (!url || /^(?:[a-z][a-z\d+.-]*:|\/|#|\?)/i.test(url))
+            continue;
+        const [, pathname, suffix = ''] = /^([^?#]*)(.*)$/.exec(url);
+        let decoded;
+        try {
+            decoded = decodeURIComponent(pathname);
+        }
+        catch {
+            throw fail(file, `invalid local URL: ${url}`);
+        }
+        const asset = await localFile(path.resolve(path.dirname(file), decoded), root, file, 'local asset');
+        const token = `SBMDASSET${assets.length}END`;
+        if (body.includes(token))
+            throw fail(file, `reserved asset token in content: ${token}`);
+        assets.push({ file: asset, suffix, token });
+        node.url = token;
+    }
+    return { markdown: markdown.stringify(tree), assets };
+}
+export async function discover({ root, patterns, exclude = [], output }) {
+    if (!Array.isArray(patterns) ||
+        !patterns.length ||
+        patterns.some((item) => typeof item !== 'string' ||
+            !item ||
+            path.isAbsolute(item) ||
+            item.split('/').includes('..'))) {
+        throw fail(root, 'patterns must be a non-empty array of globs relative to root');
+    }
+    if (!Array.isArray(exclude) ||
+        exclude.some((item) => typeof item !== 'string' ||
+            !item ||
+            path.isAbsolute(item) ||
+            item.split('/').includes('..'))) {
+        throw fail(root, 'exclude must be an array of globs relative to root');
+    }
+    const files = await glob(patterns, {
+        cwd: root,
+        absolute: true,
+        onlyFiles: true,
+        unique: true,
+        followSymbolicLinks: false,
+        ignore: [
+            ...exclude,
+            '**/node_modules/**',
+            '**/.git/**',
+            '**/storybook-static/**',
+            `${slash(path.relative(root, output))}/**`,
+        ],
+    });
+    return Promise.all(files
+        .sort()
+        .filter((file) => file.endsWith('.md'))
+        .map(async (file) => {
+        await localFile(file, root, file, 'Markdown file');
+        const { body, metadata } = parseMarkdown(await readFile(file, 'utf8'), file);
+        const stories = await associations(file, metadata, root);
+        const content = await resolveAssets(body, file, root);
+        return {
+            file,
+            source: slash(path.relative(root, file)),
+            title: metadata.title ??
+                `Documentation/${slash(path.relative(root, file)).replace(/\.md$/, '')}`,
+            metadata,
+            stories,
+            ...content,
+        };
+    }));
+}

package/dist/generator.d.ts

@@ -0,0 +1,16 @@
+import type { ContentOptions, DiscoveredDocument } from './content.js';
+export declare function writeChanged(file: string, content: string): Promise<void>;
+export declare function documentModule(document: DiscoveredDocument, output: string): string;
+export declare function generate(options: ContentOptions): Promise<{
+    markdown: string;
+    assets: {
+        file: string;
+        suffix: string;
+        token: string;
+    }[];
+    file: string;
+    source: string;
+    title: string;
+    metadata: import("./content.js").Frontmatter;
+    stories: string[];
+}[]>;

package/dist/generator.js

@@ -0,0 +1,98 @@
+import { mkdir, readFile, readdir, unlink, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { discover, fail, localFile, slash } from './content.js';
+const attribute = (value) => value.replace(/[&"<>\r\n]/g, (character) => `&#${character.charCodeAt(0)};`);
+const id = (value) => createHash('sha256').update(value).digest('hex').slice(0, 16);
+const specifier = (from, to) => {
+    const relative = slash(path.relative(from, to));
+    return relative.startsWith('.') ? relative : `./${relative}`;
+};
+const assetPath = (file, output) => {
+    if (!/[?#%]/.test(file))
+        return file;
+    const extension = path.extname(file);
+    return path.join(output, `asset-${id(file)}${/^\.[a-z0-9]+$/i.test(extension) ? extension : '.bin'}`);
+};
+export async function writeChanged(file, content) {
+    if ((await readFile(file, 'utf8').catch(() => null)) !== content)
+        await writeFile(file, content);
+}
+export function documentModule(document, output) {
+    const imports = document.assets.map((asset, index) => `import asset${index} from ${JSON.stringify(`${specifier(output, assetPath(asset.file, output))}?url&no-inline`)};`);
+    const expression = document.assets.reduce((value, asset, index) => `${value}.split(${JSON.stringify(asset.token)}).join(asset${index}.replace('?no-inline', '') + ${JSON.stringify(asset.suffix)})`, JSON.stringify(document.markdown));
+    return `${imports.join('\n')}\nexport default { source: ${JSON.stringify(document.source)}, metadata: JSON.parse(${JSON.stringify(JSON.stringify(document.metadata))}), markdown: ${expression} };\n`;
+}
+export async function generate(options) {
+    const { output, root, presentation, stylesheet } = options;
+    const documents = await discover(options);
+    if (presentation)
+        await localFile(presentation, root, presentation, 'presentation module');
+    if (stylesheet)
+        await localFile(stylesheet, root, stylesheet, 'stylesheet');
+    const files = new Map();
+    const assets = new Map();
+    const groups = new Map();
+    const titles = new Set();
+    for (const document of documents) {
+        for (const asset of document.assets) {
+            const target = assetPath(asset.file, output);
+            if (target !== asset.file)
+                assets.set(path.basename(target), await readFile(asset.file));
+        }
+        const moduleName = `content-${id(document.source)}.js`;
+        files.set(moduleName, documentModule(document, output));
+        if (!document.stories.length) {
+            const sidebarId = document.title
+                .toLowerCase()
+                .replace(/[^a-z0-9]+/g, '-')
+                .replace(/^-|-$/g, '');
+            if (!sidebarId || titles.has(sidebarId))
+                throw fail(document.file, `duplicate or empty sidebar title: ${document.title}`);
+            titles.add(sidebarId);
+            groups.set(`doc:${document.source}`, { title: document.title, documents: [moduleName] });
+        }
+        for (const story of document.stories) {
+            const key = `story:${slash(path.relative(root, story))}`;
+            if (!groups.has(key))
+                groups.set(key, { story, documents: [] });
+            groups.get(key).documents.push(moduleName);
+        }
+    }
+    for (const [key, group] of groups) {
+        const imports = [
+            "import { Meta } from '@storybook/addon-docs/blocks';",
+            "import { Documentation } from 'storybook-addon-md/runtime';",
+            "import './status.js';",
+            "import 'storybook-addon-md/styles.css';",
+            ...group.documents.map((name, index) => `import document${index} from './${name}';`),
+        ];
+        if (group.story)
+            imports.push(`import * as ComponentStories from ${JSON.stringify(specifier(output, group.story))};`);
+        if (presentation)
+            imports.push(`import * as presentation from ${JSON.stringify(specifier(output, presentation))};`);
+        if (stylesheet)
+            imports.push(`import ${JSON.stringify(specifier(output, stylesheet))};`);
+        const meta = group.story
+            ? '<Meta of={ComponentStories} name="Markdown" />'
+            : `<Meta title="${attribute(group.title)}" />`;
+        files.set(`page-${id(key)}.mdx`, `${imports.join('\n')}\n\n${meta}\n\n<Documentation documents={[${group.documents.map((_, index) => `document${index}`).join(', ')}]} attached={${Boolean(group.story)}} title={${JSON.stringify(group.title ?? '')}}${presentation ? ' presentation={presentation}' : ''} />\n`);
+    }
+    files.set('status.js', 'export {};\n');
+    await mkdir(output, { recursive: true });
+    for (const [name, content] of assets) {
+        const file = path.join(output, name);
+        const previous = await readFile(file).catch(() => null);
+        if (!previous?.equals(content))
+            await writeFile(file, content);
+    }
+    for (const [name, content] of files)
+        await writeChanged(path.join(output, name), content);
+    for (const name of await readdir(output)) {
+        if (/^(?:page-[a-f0-9]+\.mdx|content-[a-f0-9]+\.js|asset-[a-f0-9]+\.[a-z0-9]+)$/.test(name) &&
+            !files.has(name) &&
+            !assets.has(name))
+            await unlink(path.join(output, name));
+    }
+    return documents;
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export interface MarkdownOptions {
+    generatedDir?: string;
+    patterns: string[];
+    exclude?: string[];
+    stylesheet?: string;
+    root?: string;
+    presentation?: string;
+}

package/dist/index.js

@@ -0,0 +1 @@
+export {};

package/dist/preset.d.ts

@@ -0,0 +1,22 @@
+import type { UserConfig } from 'vite';
+import type { MarkdownOptions } from './index.js';
+import type { ContentOptions } from './content.js';
+type PresetOptions = MarkdownOptions & {
+    configDir: string;
+};
+type StoryEntry = string | {
+    directory: string;
+    files?: string;
+    titlePrefix?: string;
+};
+export declare function stories(existing: StoryEntry[] | undefined, options: PresetOptions): Promise<StoryEntry[]>;
+export declare function watchDocumentation(config: ContentOptions, { onError, onUpdate, }?: {
+    onError?: (error: Error) => void;
+    onUpdate?: () => void;
+}): {
+    ready: Promise<void>;
+    close(): Promise<void>;
+};
+export declare function viteFinal(config: UserConfig, options: PresetOptions): Promise<UserConfig>;
+export declare function webpackFinal(): void;
+export {};

package/dist/preset.js

@@ -0,0 +1,137 @@
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { watch } from 'chokidar';
+import glob from 'fast-glob';
+import picomatch from 'picomatch';
+import { generate, writeChanged } from './generator.js';
+import { fail, slash } from './content.js';
+const sessions = new Map();
+function settings(options) {
+    const configDir = path.resolve(options.configDir);
+    const root = path.resolve(configDir, options.root ?? '..');
+    const generatedDir = options.generatedDir ?? 'storybook-markdown-generated';
+    if (!/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/.test(generatedDir) ||
+        ['node_modules', 'storybook-static'].includes(generatedDir)) {
+        throw fail(configDir, 'generatedDir must be a visible folder name containing only letters, digits, hyphens or underscores');
+    }
+    return {
+        root,
+        output: path.join(process.cwd(), generatedDir, createHash('sha256').update(configDir).digest('hex').slice(0, 12)),
+        patterns: options.patterns,
+        exclude: options.exclude,
+        stylesheet: options.stylesheet ? path.resolve(root, options.stylesheet) : undefined,
+        presentation: options.presentation ? path.resolve(root, options.presentation) : undefined,
+    };
+}
+export async function stories(existing = [], options) {
+    const key = path.resolve(options.configDir);
+    if (!sessions.has(key)) {
+        const config = settings(options);
+        sessions.set(key, { config, ready: generate(config) });
+    }
+    const session = sessions.get(key);
+    await session.ready;
+    return [...existing, { directory: session.config.output, files: '*.mdx' }];
+}
+export function watchDocumentation(config, { onError = () => { }, onUpdate = () => { }, } = {}) {
+    const matchers = glob
+        .generateTasks(config.patterns, { ignore: config.exclude ?? [] })
+        .map((task) => ({
+        include: picomatch(task.positive),
+        exclude: picomatch(task.negative),
+    }));
+    const dependencies = new Set();
+    const configuredDependencies = [config.presentation, config.stylesheet].filter((file) => Boolean(file));
+    let timer;
+    let closed = false;
+    let queue = Promise.resolve();
+    const refresh = () => {
+        queue = queue.then(async () => {
+            if (closed)
+                return;
+            try {
+                const documents = await generate(config);
+                dependencies.clear();
+                for (const file of configuredDependencies)
+                    dependencies.add(file);
+                for (const document of documents) {
+                    for (const file of document.stories)
+                        dependencies.add(file);
+                    for (const asset of document.assets)
+                        dependencies.add(asset.file);
+                    if (document.file.endsWith('.metadata.md') && !('stories' in document.metadata)) {
+                        for (const extension of ['js', 'jsx', 'ts', 'tsx']) {
+                            dependencies.add(document.file.replace(/\.metadata\.md$/, `.stories.${extension}`));
+                        }
+                    }
+                }
+                onUpdate();
+            }
+            catch (caught) {
+                const error = caught instanceof Error ? caught : new Error(String(caught));
+                if ('dependencies' in error && Array.isArray(error.dependencies)) {
+                    for (const file of error.dependencies)
+                        if (typeof file === 'string')
+                            dependencies.add(file);
+                }
+                if ('dependency' in error && typeof error.dependency === 'string')
+                    dependencies.add(error.dependency);
+                await writeChanged(path.join(config.output, 'status.js'), `throw new Error(${JSON.stringify(error.message)});\n`);
+                onError(error);
+            }
+        });
+        return queue;
+    };
+    const watcher = watch(config.root, {
+        ignoreInitial: true,
+        ignored: (file) => file === config.output ||
+            /(?:^|[/\\])(?:node_modules|\.git|storybook-static)(?:[/\\]|$)/.test(file),
+        awaitWriteFinish: { stabilityThreshold: 100, pollInterval: 20 },
+    });
+    watcher.on('all', (event, file) => {
+        if (event === 'addDir' || event === 'unlinkDir')
+            return;
+        const relative = slash(path.relative(config.root, file));
+        const markdown = file.endsWith('.md') &&
+            matchers.some(({ include, exclude }) => include(relative) && !exclude(relative));
+        if (!markdown && !dependencies.has(file) && !configuredDependencies.includes(file))
+            return;
+        clearTimeout(timer);
+        timer = setTimeout(refresh, 80);
+    });
+    watcher.on('error', (error) => onError(error instanceof Error ? error : new Error(String(error))));
+    const ready = new Promise((resolve) => watcher.once('ready', () => refresh().then(resolve)));
+    return {
+        ready,
+        async close() {
+            closed = true;
+            clearTimeout(timer);
+            await watcher.close();
+            await queue;
+        },
+    };
+}
+export async function viteFinal(config, options) {
+    const session = sessions.get(path.resolve(options.configDir))?.config ?? settings(options);
+    return {
+        ...config,
+        plugins: [
+            ...(config.plugins ?? []),
+            {
+                name: 'storybook-addon-md',
+                configureServer(server) {
+                    const watcher = watchDocumentation(session, {
+                        onError(error) {
+                            server.config.logger.error(error.message);
+                            server.ws.send({ type: 'error', err: { message: error.message, stack: '' } });
+                        },
+                    });
+                    server.httpServer?.once('close', () => void watcher.close());
+                },
+            },
+        ],
+    };
+}
+export function webpackFinal() {
+    throw fail('builder', 'only @storybook/react-vite 10.6.0 with Vite 7 is supported');
+}

package/dist/runtime.d.ts

@@ -0,0 +1,10 @@
+import type { MarkdownDocument, LayoutProps, Presentation } from './types.js';
+export type { MarkdownDocument, LayoutProps, Presentation } from './types.js';
+export declare function DefaultMarkdownRenderer({ markdown }: MarkdownDocument): import("react").JSX.Element;
+export declare function DefaultLayout({ documents, title, attached, children, examples }: LayoutProps): import("react").JSX.Element;
+export declare function Documentation({ documents, title, attached, presentation, }: {
+    documents: MarkdownDocument[];
+    title: string;
+    attached?: boolean;
+    presentation?: Presentation;
+}): import("react").JSX.Element;

package/dist/runtime.js

@@ -0,0 +1,32 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useTheme } from 'storybook/theming';
+import { Markdown, Title, Primary, Controls, Stories, CodeOrSourceMdx, HeadersMdx, } from '@storybook/addon-docs/blocks';
+export function DefaultMarkdownRenderer({ markdown }) {
+    return (_jsx(Markdown, { options: {
+            disableParsingRawHTML: true,
+            overrides: { code: CodeOrSourceMdx, ...HeadersMdx, a: 'a' },
+        }, children: markdown }));
+}
+export function DefaultLayout({ documents, title, attached, children, examples }) {
+    const tags = [
+        ...new Set(documents.flatMap(({ metadata }) => Array.isArray(metadata.tags) ? metadata.tags : [])),
+    ];
+    const statuses = [
+        ...new Set(documents.flatMap(({ metadata }) => typeof metadata.status === 'string' ? [metadata.status] : [])),
+    ];
+    return (_jsxs(_Fragment, { children: [_jsx("div", { className: "storybook-addon-md-title", children: attached ? _jsx(Title, {}) : _jsx("h1", { children: title.split('/').at(-1) }) }), (tags.length > 0 || statuses.length > 0) && (_jsxs("ul", { className: "storybook-addon-md-tags", "aria-label": "Documentation tags", children: [tags.map((tag) => (_jsx("li", { className: "storybook-addon-md-tag", children: tag }, `tag:${tag}`))), statuses.map((status) => (_jsx("li", { className: "storybook-addon-md-tag", "data-status": status, children: status }, `status:${status}`)))] })), children, examples] }));
+}
+export function Documentation({ documents, title, attached = false, presentation = {}, }) {
+    const theme = useTheme();
+    const defaults = {
+        '--sbmd-native-color': theme.color.defaultText,
+        '--sbmd-native-link-color': theme.color.secondary,
+        '--sbmd-native-font-family': theme.typography.fonts.base,
+        '--sbmd-native-border-color': theme.appBorderColor,
+        '--sbmd-native-code-background': theme.background.content,
+    };
+    const Layout = presentation.Layout ?? DefaultLayout;
+    const Renderer = presentation.MarkdownRenderer ?? DefaultMarkdownRenderer;
+    const examples = attached ? (_jsxs(_Fragment, { children: [_jsx(Primary, {}), _jsx(Controls, {}), _jsx(Stories, { includePrimary: false })] })) : null;
+    return (_jsx("div", { className: "storybook-addon-md-page", style: defaults, children: _jsx(Layout, { documents: documents, title: title, attached: attached, examples: examples, children: documents.map((document) => (_jsx("div", { className: "storybook-addon-md", children: _jsx(Renderer, { ...document }) }, document.source))) }) }));
+}