sdocs 0.0.2 → 0.0.4

package/dist/client/router.svelte.js

@@ -0,0 +1,45 @@
+/** Hash-based router for sdocs. Uses #/Segment/Segment/... format. */
+/** Current hash path segments (reactive) */
+let currentPath = $state([]);
+/** Get the current path segments */
+export function getPath() {
+    return currentPath;
+}
+/** Navigate to a path */
+export function navigate(segments) {
+    const hash = segments.length > 0
+        ? '#/' + segments.map(encodeSegment).join('/')
+        : '#/';
+    window.location.hash = hash;
+}
+/** Parse hash into path segments */
+function parseHash() {
+    const hash = window.location.hash;
+    if (!hash || hash === '#' || hash === '#/')
+        return [];
+    const path = hash.startsWith('#/') ? hash.slice(2) : hash.slice(1);
+    return path.split('/').filter(Boolean).map(decodeSegment);
+}
+/** Encode a segment: spaces → hyphens */
+function encodeSegment(s) {
+    return s.replace(/\s+/g, '-');
+}
+/** Decode a segment: hyphens → spaces */
+function decodeSegment(s) {
+    return s.replace(/-/g, ' ');
+}
+/** Initialize the router — call once on app startup */
+export function initRouter() {
+    currentPath = parseHash();
+    window.addEventListener('hashchange', () => {
+        currentPath = parseHash();
+    });
+}
+/** Build a title path from meta.title (e.g. 'Demo / Button' → ['Demo', 'Button']) */
+export function titleToPath(title) {
+    return title.split('/').map((s) => s.trim()).filter(Boolean);
+}
+/** Build a hash string from a title path (for href attributes) */
+export function pathToHash(segments) {
+    return '#/' + segments.map(encodeSegment).join('/');
+}

package/dist/client/theme.css

@@ -0,0 +1,34 @@
+/* sdocs color system — semantic CSS variables */
+
+:root,
+[data-sdocs-theme="light"] {
+	--sdocs-bg: #ffffff;
+	--sdocs-bg-subtle: #f8fafc;
+	--sdocs-bg-hover: #f1f5f9;
+	--sdocs-border: #e2e8f0;
+	--sdocs-border-muted: #cbd5e1;
+	--sdocs-text: #475569;
+	--sdocs-text-secondary: #64748b;
+	--sdocs-text-muted: #94a3b8;
+	--sdocs-text-heading: #1e293b;
+	--sdocs-text-strong: #334155;
+	--sdocs-primary: #3b82f6;
+	--sdocs-primary-bg: rgba(59, 130, 246, 0.1);
+	--sdocs-shadow: rgba(0, 0, 0, 0.1);
+}
+
+[data-sdocs-theme="dark"] {
+	--sdocs-bg: #0f172a;
+	--sdocs-bg-subtle: #1e293b;
+	--sdocs-bg-hover: #334155;
+	--sdocs-border: #334155;
+	--sdocs-border-muted: #475569;
+	--sdocs-text: #cbd5e1;
+	--sdocs-text-secondary: #94a3b8;
+	--sdocs-text-muted: #64748b;
+	--sdocs-text-heading: #f1f5f9;
+	--sdocs-text-strong: #e2e8f0;
+	--sdocs-primary: #60a5fa;
+	--sdocs-primary-bg: rgba(96, 165, 250, 0.15);
+	--sdocs-shadow: rgba(0, 0, 0, 0.3);
+}

package/dist/client/tree-builder.d.ts

@@ -0,0 +1,30 @@
+import type { DocEntry } from '../types.js';
+export type TreeNodeType = 'folder' | 'group' | 'component' | 'page' | 'layout';
+export interface TreeNode {
+    name: string;
+    type: TreeNodeType;
+    /** Full path segments from root (for routing) */
+    path: string[];
+    /** Children nodes */
+    children: TreeNode[];
+    /** The doc entry (only for component/page/layout nodes) */
+    doc?: DocEntry;
+    /** Snippet names for component nodes (excludes Default) */
+    examples?: string[];
+    /** Whether this node should be expanded by default */
+    defaultExpanded?: boolean;
+}
+interface SidebarConfig {
+    order?: Record<string, string[]>;
+    open?: string[];
+}
+/** Build a tree from flat doc entries */
+export declare function buildTree(docs: DocEntry[], sidebar?: SidebarConfig): TreeNode[];
+/** Check if a path matches a tree node (for active state) */
+export declare function pathMatchesNode(currentPath: string[], node: TreeNode): boolean;
+/** Find the doc entry for a given path */
+export declare function findDocByPath(docs: DocEntry[], path: string[]): {
+    doc: DocEntry;
+    snippetName?: string;
+} | null;
+export {};

package/dist/client/tree-builder.js

@@ -0,0 +1,162 @@
+/** Build a tree from flat doc entries */
+export function buildTree(docs, sidebar) {
+    const root = [];
+    const folderMap = new Map();
+    for (const doc of docs) {
+        const title = doc.meta.title ?? 'Untitled';
+        const segments = title.split('/').map((s) => s.trim()).filter(Boolean);
+        if (segments.length === 0)
+            continue;
+        const kind = doc.kind;
+        const itemName = segments[segments.length - 1];
+        const folderSegments = segments.slice(0, -1);
+        // Ensure all parent folders exist
+        let parent = root;
+        const currentPath = [];
+        for (let i = 0; i < folderSegments.length; i++) {
+            let segName = folderSegments[i];
+            const isGroup = i === 0 && segName.startsWith(':');
+            if (isGroup)
+                segName = segName.slice(1);
+            currentPath.push(segName);
+            const key = currentPath.join('/');
+            let folder = folderMap.get(key);
+            if (!folder) {
+                folder = {
+                    name: segName,
+                    type: isGroup ? 'group' : 'folder',
+                    path: [...currentPath],
+                    children: [],
+                    defaultExpanded: isGroup || sidebar?.open?.includes(segName),
+                };
+                folderMap.set(key, folder);
+                parent.push(folder);
+            }
+            parent = folder.children;
+        }
+        // Create the item node
+        const itemPath = [...currentPath, itemName];
+        if (kind === 'component') {
+            const examples = doc.snippets
+                ?.filter((s) => s.name !== 'Default')
+                .map((s) => s.name) ?? [];
+            const componentNode = {
+                name: itemName,
+                type: 'component',
+                path: itemPath,
+                children: [],
+                doc,
+                examples,
+            };
+            // Add "Docs" child
+            componentNode.children.push({
+                name: 'Docs',
+                type: 'component',
+                path: itemPath,
+                children: [],
+                doc,
+            });
+            // Add example children
+            for (const ex of examples) {
+                componentNode.children.push({
+                    name: ex,
+                    type: 'component',
+                    path: [...itemPath, ex],
+                    children: [],
+                    doc,
+                });
+            }
+            parent.push(componentNode);
+        }
+        else {
+            parent.push({
+                name: itemName,
+                type: kind,
+                path: itemPath,
+                children: [],
+                doc,
+            });
+        }
+    }
+    // Apply ordering
+    if (sidebar?.order) {
+        applyOrder(root, 'root', sidebar.order);
+    }
+    return root;
+}
+/** Apply sort order to children at each level */
+function applyOrder(nodes, folderKey, orderConfig) {
+    const order = orderConfig[folderKey];
+    if (order) {
+        sortByOrder(nodes, order);
+    }
+    else {
+        // Default: alphabetical
+        nodes.sort((a, b) => a.name.localeCompare(b.name));
+    }
+    // Recurse into folders/groups
+    for (const node of nodes) {
+        if (node.children.length > 0 && (node.type === 'folder' || node.type === 'group')) {
+            const childKey = folderKey === 'root' ? node.name : `${folderKey}/${node.name}`;
+            applyOrder(node.children, childKey, orderConfig);
+        }
+    }
+}
+/** Sort nodes by explicit order, with * as wildcard for the rest */
+function sortByOrder(nodes, order) {
+    const wildcardIndex = order.indexOf('*');
+    const before = wildcardIndex >= 0 ? order.slice(0, wildcardIndex) : order;
+    const after = wildcardIndex >= 0 ? order.slice(wildcardIndex + 1) : [];
+    const named = new Map();
+    const rest = [];
+    for (const node of nodes) {
+        if (before.includes(node.name) || after.includes(node.name)) {
+            named.set(node.name, node);
+        }
+        else {
+            rest.push(node);
+        }
+    }
+    // Rest sorted alphabetically
+    rest.sort((a, b) => a.name.localeCompare(b.name));
+    nodes.length = 0;
+    for (const name of before) {
+        const node = named.get(name);
+        if (node)
+            nodes.push(node);
+    }
+    nodes.push(...rest);
+    for (const name of after) {
+        const node = named.get(name);
+        if (node)
+            nodes.push(node);
+    }
+}
+/** Check if a path matches a tree node (for active state) */
+export function pathMatchesNode(currentPath, node) {
+    if (node.path.length !== currentPath.length)
+        return false;
+    return node.path.every((seg, i) => seg === currentPath[i]);
+}
+/** Find the doc entry for a given path */
+export function findDocByPath(docs, path) {
+    if (path.length === 0)
+        return null;
+    for (const doc of docs) {
+        const title = doc.meta.title ?? '';
+        const segments = title.split('/').map((s) => s.trim()).filter(Boolean);
+        // Exact match → component docs view
+        if (segments.length === path.length && segments.every((s, i) => s === path[i])) {
+            return { doc };
+        }
+        // One extra segment → example
+        if (segments.length === path.length - 1 && segments.every((s, i) => s === path[i])) {
+            const snippetName = path[path.length - 1];
+            const hasSnippet = doc.snippets?.some((s) => s.name === snippetName);
+            if (hasSnippet) {
+                return { doc, snippetName };
+            }
+        }
+    }
+    return null;
+}

package/dist/commands/build.d.ts

@@ -0,0 +1 @@
+export declare function buildCommand(): Promise<void>;

package/dist/commands/build.js

@@ -0,0 +1,38 @@
+import { resolve } from 'node:path';
+import { build } from 'vite';
+import { svelte } from '@sveltejs/vite-plugin-svelte';
+import { loadConfig } from '../config.js';
+import { sdocsPlugin } from '../vite.js';
+import { generateBuildFiles, cleanBuildFiles } from '../app-gen.js';
+export async function buildCommand() {
+    const cwd = process.cwd();
+    const config = await loadConfig(cwd);
+    console.log('[sdocs] Building static site...');
+    // Generate .sdocs/ with entry + preview HTML files
+    const { sdocsDir, inputs } = await generateBuildFiles(config, cwd);
+    const inputCount = Object.keys(inputs).length;
+    console.log(`[sdocs] Generated ${inputCount} page(s) (1 main + ${inputCount - 1} previews)`);
+    // Resolve include patterns to absolute paths
+    const absoluteIncludes = config.include.map((p) => resolve(cwd, p));
+    try {
+        await build({
+            configFile: false,
+            root: sdocsDir,
+            plugins: [
+                svelte(),
+                sdocsPlugin({ ...config, include: absoluteIncludes, _buildMode: true }),
+            ],
+            build: {
+                outDir: resolve(cwd, 'dist'),
+                emptyOutDir: true,
+                rollupOptions: {
+                    input: inputs,
+                },
+            },
+        });
+        console.log(`[sdocs] Build complete → dist/`);
+    }
+    finally {
+        await cleanBuildFiles(cwd);
+    }
+}

package/dist/commands/dev.d.ts

@@ -0,0 +1 @@
+export declare function devCommand(): Promise<void>;

package/dist/commands/dev.js

@@ -0,0 +1,40 @@
+import { resolve } from 'node:path';
+import { createServer } from 'vite';
+import { svelte } from '@sveltejs/vite-plugin-svelte';
+import { loadConfig } from '../config.js';
+import { sdocsPlugin } from '../vite.js';
+import { generateDevFiles, cleanBuildFiles } from '../app-gen.js';
+export async function devCommand() {
+    const cwd = process.cwd();
+    const config = await loadConfig(cwd);
+    console.log('[sdocs] Starting dev server...');
+    // Generate .sdocs/ temp directory with entry files
+    const sdocsDir = await generateDevFiles(config, cwd);
+    // Resolve include patterns to absolute paths (relative to cwd, not .sdocs/)
+    const absoluteIncludes = config.include.map((p) => resolve(cwd, p));
+    const server = await createServer({
+        configFile: false,
+        root: sdocsDir,
+        plugins: [
+            svelte(),
+            sdocsPlugin({ ...config, include: absoluteIncludes }),
+        ],
+        server: {
+            port: config.port,
+            open: config.open,
+            fs: {
+                allow: [cwd],
+            },
+        },
+    });
+    await server.listen();
+    server.printUrls();
+    // Cleanup on exit
+    const cleanup = async () => {
+        await server.close();
+        await cleanBuildFiles(cwd);
+        process.exit(0);
+    };
+    process.on('SIGINT', cleanup);
+    process.on('SIGTERM', cleanup);
+}

package/dist/commands/init.d.ts

@@ -0,0 +1 @@
+export declare function initCommand(): Promise<void>;

package/dist/commands/init.js

@@ -0,0 +1,41 @@
+import { writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { findConfigFile } from '../config.js';
+const DEFAULT_CONFIG = `/** @type {import('sdocs').SdocsConfig} */
+export default {
+	// Glob pattern(s) to find sdoc files
+	// include: ['./src/**/*.sdoc', './src/**/*.sdocx'],
+
+	// Dev server port (default: 5174)
+	// port: 5174,
+
+	// Open browser on start (default: false)
+	// open: false,
+
+	// CSS loaded in preview iframes
+	// css: './src/styles/global.css',
+	// Or named stylesheets:
+	// css: { light: './src/styles/light.css', dark: './src/styles/dark.css' },
+
+	// Sidebar logo text (default: 'sdocs')
+	// logo: 'sdocs',
+
+	// Sidebar configuration
+	// sidebar: {
+	// 	order: { root: ['Components', '*', 'Documentation'] },
+	// 	open: ['Components'],
+	// },
+};
+`;
+export async function initCommand() {
+    const cwd = process.cwd();
+    const existing = findConfigFile(cwd);
+    if (existing) {
+        console.log(`[sdocs] Config already exists: ${existing}`);
+        return;
+    }
+    const configPath = resolve(cwd, 'sdocs.config.js');
+    await writeFile(configPath, DEFAULT_CONFIG);
+    console.log('[sdocs] Created sdocs.config.js');
+}

package/dist/commands/preview.d.ts

@@ -0,0 +1 @@
+export declare function previewCommand(): Promise<void>;

package/dist/commands/preview.js

@@ -0,0 +1,25 @@
+import { resolve } from 'node:path';
+import { existsSync } from 'node:fs';
+import { preview } from 'vite';
+import { loadConfig } from '../config.js';
+export async function previewCommand() {
+    const cwd = process.cwd();
+    const config = await loadConfig(cwd);
+    const distDir = resolve(cwd, 'dist');
+    if (!existsSync(distDir)) {
+        console.error('[sdocs] No dist/ folder found. Run `sdocs build` first.');
+        process.exit(1);
+    }
+    console.log('[sdocs] Serving built site...');
+    const server = await preview({
+        configFile: false,
+        build: {
+            outDir: distDir,
+        },
+        preview: {
+            port: config.port,
+            open: config.open,
+        },
+    });
+    server.printUrls();
+}

package/dist/config.d.ts

@@ -0,0 +1,7 @@
+import type { SdocsConfig, ResolvedSdocsConfig } from './types.js';
+/** Find the config file path in the given directory */
+export declare function findConfigFile(root: string): string | null;
+/** Load and resolve the sdocs config with defaults */
+export declare function loadConfig(root: string): Promise<ResolvedSdocsConfig>;
+/** Merge user config with defaults */
+export declare function resolveConfig(userConfig: SdocsConfig): ResolvedSdocsConfig;

package/dist/config.js

@@ -0,0 +1,57 @@
+import { pathToFileURL } from 'node:url';
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+const CONFIG_NAMES = ['sdocs.config.ts', 'sdocs.config.mjs', 'sdocs.config.js'];
+const DEFAULTS = {
+    include: ['./src/**/*.sdoc', './src/**/*.sdocx'],
+    port: 5174,
+    open: false,
+    css: null,
+    logo: 'sdocs',
+    sidebar: {
+        order: {},
+        open: [],
+    },
+};
+/** Find the config file path in the given directory */
+export function findConfigFile(root) {
+    for (const name of CONFIG_NAMES) {
+        const fullPath = resolve(root, name);
+        if (existsSync(fullPath))
+            return fullPath;
+    }
+    return null;
+}
+/** Load and resolve the sdocs config with defaults */
+export async function loadConfig(root) {
+    const configPath = findConfigFile(root);
+    if (!configPath)
+        return { ...DEFAULTS };
+    const userConfig = await importConfig(configPath);
+    return resolveConfig(userConfig);
+}
+/** Import a config file (supports .js, .mjs, .ts via Vite) */
+async function importConfig(configPath) {
+    // Use dynamic import with file:// URL for ESM compatibility
+    const mod = await import(pathToFileURL(configPath).href);
+    return mod.default ?? mod;
+}
+/** Merge user config with defaults */
+export function resolveConfig(userConfig) {
+    const include = userConfig.include
+        ? Array.isArray(userConfig.include)
+            ? userConfig.include
+            : [userConfig.include]
+        : DEFAULTS.include;
+    return {
+        include,
+        port: userConfig.port ?? DEFAULTS.port,
+        open: userConfig.open ?? DEFAULTS.open,
+        css: userConfig.css ?? DEFAULTS.css,
+        logo: userConfig.logo ?? DEFAULTS.logo,
+        sidebar: {
+            order: userConfig.sidebar?.order ?? DEFAULTS.sidebar.order,
+            open: userConfig.sidebar?.open ?? DEFAULTS.sidebar.open,
+        },
+    };
+}

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-export { default as Sdocs } from './Sdocs.svelte';
-export type { ControlType, ArgType, ArgTypes, CssPropType, CssProps, DocMeta, Example, DocFile, SdocsProps } from './types.js';
+export { sdocsPlugin } from './vite.js';
+export type { SdocsConfig, ResolvedSdocsConfig, SdocMeta, DocEntry, ParsedProp, ParsedMethod, ParsedState, ParsedCssProp, ComponentData, ExtractedSnippet, } from './types.js';

package/dist/index.js

@@ -1,4 +1 @@
-// Main component
-export { default as Sdocs } from './Sdocs.svelte';
-// Note: Vite plugin is exported separately from 'sdocs/vite'
-// to avoid bundling Node.js code into client builds
+export { sdocsPlugin } from './vite.js';

package/dist/server/discovery.d.ts

@@ -0,0 +1,6 @@
+/** Discover all .sdoc/.sdocx files matching the include patterns */
+export declare function discoverDocFiles(include: string[], root: string): Promise<string[]>;
+/** Determine the sdoc kind from the file path */
+export declare function getSdocKind(filePath: string): 'component' | 'page' | 'layout';
+/** Get the absolute path for a relative import */
+export declare function resolveImportPath(importPath: string, fromFile: string): string;

package/dist/server/discovery.js

@@ -0,0 +1,24 @@
+import { glob } from 'tinyglobby';
+import { resolve } from 'node:path';
+/** Discover all .sdoc/.sdocx files matching the include patterns */
+export async function discoverDocFiles(include, root) {
+    const files = await glob(include, {
+        cwd: root,
+        absolute: true,
+    });
+    return files.sort();
+}
+/** Determine the sdoc kind from the file path */
+export function getSdocKind(filePath) {
+    const name = filePath.split('/').pop() ?? '';
+    if (name.includes('.page.'))
+        return 'page';
+    if (name.includes('.layout.'))
+        return 'layout';
+    return 'component';
+}
+/** Get the absolute path for a relative import */
+export function resolveImportPath(importPath, fromFile) {
+    const dir = fromFile.substring(0, fromFile.lastIndexOf('/'));
+    return resolve(dir, importPath);
+}

package/dist/server/highlighter.d.ts

@@ -0,0 +1,4 @@
+/** Highlight source code and return HTML */
+export declare function highlight(code: string, lang?: string): Promise<string>;
+/** Dispose the highlighter (for cleanup) */
+export declare function disposeHighlighter(): Promise<void>;

package/dist/server/highlighter.js

@@ -0,0 +1,31 @@
+import { createHighlighter } from 'shiki';
+let highlighterPromise = null;
+/** Get or create the shared Shiki highlighter instance */
+async function getHighlighter() {
+    if (!highlighterPromise) {
+        highlighterPromise = createHighlighter({
+            themes: ['github-light', 'github-dark'],
+            langs: ['svelte', 'typescript', 'javascript', 'css', 'html'],
+        });
+    }
+    return highlighterPromise;
+}
+/** Highlight source code and return HTML */
+export async function highlight(code, lang = 'svelte') {
+    const highlighter = await getHighlighter();
+    return highlighter.codeToHtml(code, {
+        lang,
+        themes: {
+            light: 'github-light',
+            dark: 'github-dark',
+        },
+    });
+}
+/** Dispose the highlighter (for cleanup) */
+export async function disposeHighlighter() {
+    if (highlighterPromise) {
+        const highlighter = await highlighterPromise;
+        highlighter.dispose();
+        highlighterPromise = null;
+    }
+}

package/dist/server/meta-parser.d.ts

@@ -0,0 +1,11 @@
+import type { SdocMeta } from '../types.js';
+interface MetaParseResult {
+    meta: SdocMeta;
+    componentPath: string | null;
+    imports: string[];
+}
+/** Extract meta and imports from a .sdoc file */
+export declare function parseDocFile(filePath: string): Promise<MetaParseResult>;
+/** Parse meta from .sdoc source */
+export declare function parseDocSource(source: string, filePath: string): MetaParseResult;
+export {};