svelte-docsmith 0.13.1 → 0.15.0

package/README.md

@@ -42,50 +42,54 @@ To add DocSmith to an existing SvelteKit app, install the package instead:
 npm install svelte-docsmith
 ```
 
-Peer dependencies: Svelte 5, SvelteKit 2, and Tailwind v4, set up the standard
-way in your app.
+Peer dependencies: Svelte 5, SvelteKit 2 or 3, and Tailwind v4, set up the
+standard way in your app.
 
 ## Setup
 
-Three small pieces, once.
+Two small pieces, once.
 
-**1. The markdown pipeline.** In `svelte.config.js`, one call bundles mdsvex,
-Shiki highlighting (dual light/dark themes, a generous language set, plain-text
-fallback for unknown languages), heading anchors, and the packaged page layout:
+**1. Vite.** Everything goes in `vite.config.ts`. DocSmith has two halves, both
+called `docsmith()`:
 
-```js
-// svelte.config.js
-import adapter from '@sveltejs/adapter-auto';
-import { vitePreprocess } from '@sveltejs/vite-plugin-svelte';
-import { docsmith } from 'svelte-docsmith/preprocess';
-
-export default {
-	extensions: ['.svelte', '.md'],
-	preprocess: [vitePreprocess(), docsmith()],
-	kit: { adapter: adapter() }
-};
-```
-
-**2. The Vite plugin.** In `vite.config.ts`, it scans your doc pages' frontmatter
-into the `svelte-docsmith/content` module (so the sidebar is derived from
-content, never hand-written), builds the search index, and powers `LiveExample`:
+- The **Vite plugin** (`svelte-docsmith/vite`) scans your doc pages' frontmatter
+  into the `svelte-docsmith/content` module (so the sidebar is derived from
+  content, never hand-written), builds the search index, and powers
+  `LiveExample`. It goes before `sveltekit()`.
+- The **markdown pipeline** (`svelte-docsmith/preprocess`) bundles mdsvex, Shiki
+  highlighting (dual light/dark themes, a generous language set, plain-text
+  fallback for unknown languages), heading anchors, and the packaged page layout.
 
 ```ts
 // vite.config.ts
+import adapter from '@sveltejs/adapter-auto';
 import { sveltekit } from '@sveltejs/kit/vite';
+import { vitePreprocess } from '@sveltejs/vite-plugin-svelte';
 import tailwindcss from '@tailwindcss/vite';
 import { docsmith } from 'svelte-docsmith/vite';
+import { docsmith as markdown } from 'svelte-docsmith/preprocess';
 import { defineConfig } from 'vite';
 
 export default defineConfig({
-	plugins: [docsmith(), tailwindcss(), sveltekit()]
+	plugins: [
+		docsmith(),
+		tailwindcss(),
+		sveltekit({
+			extensions: ['.svelte', '.md'],
+			preprocess: [vitePreprocess(), markdown()],
+			adapter: adapter()
+		})
+	]
 });
 ```
 
+On SvelteKit 2, `extensions` and `preprocess` go in `svelte.config.js` instead,
+and `sveltekit()` takes no options.
+
 By default it scans `src/routes/docs`; pass `docsmith({ content: 'src/routes/guide' })`
 to point elsewhere.
 
-**3. The stylesheet.** In your root `app.css`, once Tailwind v4 is set up the
+**2. The stylesheet.** In your root `app.css`, once Tailwind v4 is set up the
 standard way (`tailwindcss` + the `@tailwindcss/vite` plugin, stylesheet imported
 in the root layout), the whole style contract is one import:
 
@@ -157,8 +161,8 @@ plugin you already added:
 ```svelte
 <script>
 	import { LiveExample } from 'svelte-docsmith';
-	import Counter from '$lib/examples/counter.svelte';
-	import counterSource from '$lib/examples/counter.svelte?source';
+	import Counter from '#lib/examples/counter.svelte';
+	import counterSource from '#lib/examples/counter.svelte?source';
 </script>
 
 <LiveExample source={counterSource}>

package/dist/buildtime/archive.d.ts

@@ -37,9 +37,10 @@ export declare function freezeLastUpdated(text: string, date: string | undefined
  * Archiving copies the docs root and nothing else, so anything reached from
  * outside it keeps resolving to current code: a live example on an archived
  * page demonstrates the current library rather than the version the page
- * documents, with a green build and nothing said. Hence `$lib`, bare npm
- * specifiers and relative paths that climb out all count, while a relative
- * import landing inside the docs root is frozen along with the page.
+ * documents, with a green build and nothing said. Hence `$lib` (Kit 2), `#lib`
+ * (Kit 3), bare npm specifiers and relative paths that climb out all count,
+ * while a relative import landing inside the docs root is frozen along with
+ * the page.
  *
  * `svelte-docsmith` itself is never reported. An archived page importing the
  * authoring components is the expected shape, and those are covered by the

package/dist/buildtime/archive.js

@@ -85,9 +85,10 @@ function escapesRoot(specifier, depth) {
  * Archiving copies the docs root and nothing else, so anything reached from
  * outside it keeps resolving to current code: a live example on an archived
  * page demonstrates the current library rather than the version the page
- * documents, with a green build and nothing said. Hence `$lib`, bare npm
- * specifiers and relative paths that climb out all count, while a relative
- * import landing inside the docs root is frozen along with the page.
+ * documents, with a green build and nothing said. Hence `$lib` (Kit 2), `#lib`
+ * (Kit 3), bare npm specifiers and relative paths that climb out all count,
+ * while a relative import landing inside the docs root is frozen along with
+ * the page.
  *
  * `svelte-docsmith` itself is never reported. An archived page importing the
  * authoring components is the expected shape, and those are covered by the

package/dist/buildtime/markdown-layout.svelte.d.ts

@@ -7,8 +7,8 @@ export declare const pre: import("svelte").Component<{
 export declare const code: import("svelte").Component<{
     children: Snippet;
 }, {}, "">;
-export declare const h2: import("svelte").Component<import("../components/markdown/types.js").HeadingProps, {}, "">;
-export declare const h3: import("svelte").Component<import("../components/markdown/types.js").HeadingProps, {}, "">;
+export declare const h2: import("svelte").Component<import("../components/markdown/types.ts").HeadingProps, {}, "">;
+export declare const h3: import("svelte").Component<import("../components/markdown/types.ts").HeadingProps, {}, "">;
 export declare const table: import("svelte").Component<{
     children: Snippet;
 }, {}, "">;

package/dist/buildtime/paths.d.ts

@@ -10,3 +10,8 @@ export declare function urlFor(routesDir: string, dir: string): string;
  * base of `/docs`.
  */
 export declare function docsBaseFrom(routesDir: string, contentDir: string): string;
+/**
+ * A file's path relative to the app's working directory, with `/` separators:
+ * the path an author would type, for "Edit this page" links and error messages.
+ */
+export declare function relativeToCwd(file: string): string;

package/dist/buildtime/paths.js

@@ -21,3 +21,10 @@ export function urlFor(routesDir, dir) {
 export function docsBaseFrom(routesDir, contentDir) {
     return urlFor(routesDir, contentDir);
 }
+/**
+ * A file's path relative to the app's working directory, with `/` separators:
+ * the path an author would type, for "Edit this page" links and error messages.
+ */
+export function relativeToCwd(file) {
+    return path.relative(process.cwd(), file).split(path.sep).join('/');
+}

package/dist/buildtime/props/extract.d.ts

@@ -0,0 +1,19 @@
+import type { ExtractedProps } from '../../core/extracted-props.js';
+export interface ExtractResult {
+    props: ExtractedProps;
+    warnings: string[];
+    /** Files whose changes should re-extract this component. */
+    watchFiles: string[];
+}
+export interface PropsExtractorOptions {
+    /** Project root: where `tsconfig.json` is looked up. */
+    root: string;
+    /** tsconfig used to read prop types. Default: the root's `tsconfig.json`. */
+    tsconfig?: string;
+}
+export interface PropsExtractor {
+    extract(file: string): Promise<ExtractResult>;
+}
+export declare function createPropsExtractor(options: PropsExtractorOptions): PropsExtractor;
+/** `file-tree-item.svelte` → `FileTreeItem`. */
+export declare function componentName(file: string): string;

package/dist/buildtime/props/extract.js

@@ -0,0 +1,158 @@
+/**
+ * Props extraction for props imports (`Component.svelte?props`): merges what
+ * the source says (./parse.ts: destructured names, defaults, `$bindable()`)
+ * with what TypeScript says (./typescript.ts: types, optionality, JSDoc) into
+ * the `ExtractedProps` that `<PropsTable of={…}>` renders.
+ *
+ * Extraction never throws over one component. Anything it can't read becomes a
+ * warning naming the file, and the table shows what was found: untyped props
+ * by name only, a missing TypeScript install as names and defaults.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { marked } from 'marked';
+import { VERSION } from 'svelte/compiler';
+import { parseComponent } from './parse.js';
+import { createPropsTypeChecker, inNodeModules, loadPeers, mtimeOf, MISSING_PEERS } from './typescript.js';
+export function createPropsExtractor(options) {
+    let checker;
+    const getChecker = () => (checker ??= loadPeers().then((peers) => peers &&
+        createPropsTypeChecker(peers, {
+            ...options,
+            svelteVersion: VERSION
+        })));
+    // Props imports load concurrently (a page with five tables asks for five at
+    // once). Collect the requests made in the same tick and read them against
+    // one TypeScript program instead of rebuilding it per component.
+    let batch = [];
+    const flush = async () => {
+        const items = batch;
+        batch = [];
+        let results;
+        try {
+            const tsChecker = await getChecker();
+            results = tsChecker
+                ? tsChecker.read(items.map((item) => item.file))
+                : items.map(() => 'missing-peers');
+        }
+        catch (error) {
+            // Setting TypeScript up failed (a broken tsconfig, say). Report it on
+            // every waiting import rather than leaving them pending, and try again
+            // from scratch next time.
+            checker = undefined;
+            const failure = error instanceof Error ? error : new Error(String(error));
+            results = items.map(() => failure);
+        }
+        items.forEach((item, i) => item.done(results[i]));
+    };
+    const readTyped = (file) => new Promise((done) => {
+        if (batch.push({ file, done }) === 1)
+            setTimeout(flush, 0);
+    });
+    // Results stay valid until one of the files they were read from changes.
+    // The client and server builds both import every props module, so the
+    // second build is served from here.
+    const cache = new Map();
+    const stamp = mtimeOf;
+    return {
+        async extract(file) {
+            const cached = cache.get(file);
+            if (cached && cached.stamps.every(([f, time]) => stamp(f) === time))
+                return cached.result;
+            const result = await extractFresh(file);
+            cache.set(file, { stamps: result.watchFiles.map((f) => [f, stamp(f)]), result });
+            return result;
+        }
+    };
+    async function extractFresh(file) {
+        const warnings = [];
+        const rel = path.relative(options.root, file) || file;
+        const warn = (message) => warnings.push(`${rel}: ${message}`);
+        const extracted = {
+            name: componentName(file),
+            typeParameters: [],
+            props: [],
+            inherited: []
+        };
+        if (inNodeModules(file)) {
+            warn('reading a published package file. Published components usually have their ' +
+                'types stripped, so point the props import at the source instead.');
+        }
+        let parsed;
+        try {
+            parsed = parseComponent(fs.readFileSync(file, 'utf-8'), file);
+        }
+        catch (error) {
+            warn(`could not parse the component (${message(error)}).`);
+            return { props: extracted, warnings, watchFiles: [file] };
+        }
+        extracted.typeParameters = parsed.typeParameters;
+        if (!parsed.hasProps) {
+            warn('no `$props()` found, so the props table is empty.');
+            return { props: extracted, warnings, watchFiles: [file] };
+        }
+        let typed;
+        if (parsed.typed) {
+            const result = await readTyped(file);
+            if (result === 'missing-peers')
+                warn(MISSING_PEERS);
+            else if (result instanceof Error) {
+                warn(`could not read prop types (${result.message}). Showing names only.`);
+            }
+            else
+                typed = result;
+        }
+        else {
+            warn('`$props()` has no type annotation, so props show without types.');
+        }
+        const defaults = new Map(parsed.destructured.map((d) => [d.name, d]));
+        if (typed) {
+            for (const prop of typed.props) {
+                if (prop.internal)
+                    continue;
+                const destructured = defaults.get(prop.name);
+                const fallback = prop.defaultTag ?? destructured?.default;
+                extracted.props.push(clean({
+                    name: prop.name,
+                    type: prop.type,
+                    default: fallback,
+                    required: !prop.optional && fallback === undefined,
+                    bindable: destructured?.bindable ?? false,
+                    deprecated: prop.deprecated === undefined ? undefined : renderMarkdown(prop.deprecated),
+                    description: prop.description ? renderMarkdown(prop.description) : undefined
+                }));
+            }
+            extracted.inherited = typed.inherited;
+        }
+        else {
+            for (const d of parsed.destructured) {
+                extracted.props.push(clean({ name: d.name, default: d.default, required: false, bindable: d.bindable }));
+            }
+        }
+        return {
+            props: extracted,
+            warnings,
+            watchFiles: [...new Set([file, ...(typed?.files ?? [])])]
+        };
+    }
+}
+/** `file-tree-item.svelte` → `FileTreeItem`. */
+export function componentName(file) {
+    return path
+        .basename(file, '.svelte')
+        .split(/[^A-Za-z0-9]+/)
+        .filter(Boolean)
+        .map((word) => word[0].toUpperCase() + word.slice(1))
+        .join('');
+}
+function renderMarkdown(text) {
+    return marked.parse(text, { async: false, gfm: true })
+        .trim()
+        .replace(/^<p>([\s\S]*)<\/p>$/, (match, inner) => inner.includes('<p>') ? match : inner);
+}
+function clean(prop) {
+    return Object.fromEntries(Object.entries(prop).filter(([, value]) => value !== undefined));
+}
+function message(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/buildtime/props/parse.d.ts

@@ -0,0 +1,17 @@
+export interface DestructuredProp {
+    name: string;
+    /** Source text of the default value. */
+    default?: string;
+    bindable: boolean;
+}
+export interface ParsedComponent {
+    /** Whether the instance script calls `$props()` at all. */
+    hasProps: boolean;
+    /** Whether the `$props()` declaration carries a type annotation. */
+    typed: boolean;
+    /** Destructured props, in source order. Empty for `let props = $props()`. */
+    destructured: DestructuredProp[];
+    /** Type parameter names from `generics="…"`. */
+    typeParameters: string[];
+}
+export declare function parseComponent(code: string, filename: string): ParsedComponent;

package/dist/buildtime/props/parse.js

@@ -0,0 +1,108 @@
+/**
+ * The syntax half of props extraction: what can be read from a component's
+ * source without TypeScript. That is the `$props()` destructuring (names,
+ * default values, `$bindable()`) and the `generics`
+ * attribute. Types, optionality and descriptions come from ./typescript.ts.
+ */
+import { parse } from 'svelte/compiler';
+import { splitTopLevel } from '../../utils/type-text.js';
+export function parseComponent(code, filename) {
+    const ast = parse(code, { modern: true, filename });
+    const typeParameters = genericsOf(ast.instance?.attributes ?? [], code);
+    const empty = {
+        hasProps: false,
+        typed: false,
+        destructured: [],
+        typeParameters
+    };
+    if (!ast.instance)
+        return empty;
+    const declarator = findPropsDeclarator(ast.instance.content);
+    if (!declarator)
+        return empty;
+    const id = declarator.id;
+    const typed = Boolean(id.typeAnnotation);
+    if (id.type !== 'ObjectPattern')
+        return { ...empty, hasProps: true, typed };
+    const destructured = [];
+    for (const property of id.properties) {
+        // `...rest` is read from the type instead (inherited attributes).
+        if (property.type === 'RestElement')
+            continue;
+        const name = keyName(property.key);
+        if (name === undefined)
+            continue;
+        destructured.push({ name, ...defaultOf(property.value, code) });
+    }
+    return { hasProps: true, typed, destructured, typeParameters };
+}
+function findPropsDeclarator(node) {
+    let found;
+    walk(node, (n) => {
+        if (found)
+            return false;
+        if (n.type === 'VariableDeclarator' && isCall(n.init, '$props')) {
+            found = n;
+            return false;
+        }
+        return true;
+    });
+    return found;
+}
+function walk(node, visit) {
+    if (!visit(node))
+        return;
+    for (const value of Object.values(node)) {
+        if (Array.isArray(value)) {
+            for (const child of value)
+                if (isNode(child))
+                    walk(child, visit);
+        }
+        else if (isNode(value)) {
+            walk(value, visit);
+        }
+    }
+}
+function isNode(value) {
+    return typeof value === 'object' && value !== null && typeof value.type === 'string';
+}
+function isCall(node, callee) {
+    if (!node || node.type !== 'CallExpression')
+        return false;
+    const fn = node.callee;
+    return fn.type === 'Identifier' && fn.name === callee;
+}
+function keyName(key) {
+    if (key.type === 'Identifier')
+        return key.name;
+    if (key.type === 'Literal' && typeof key.value === 'string')
+        return key.value;
+    return undefined;
+}
+function defaultOf(value, code) {
+    if (value.type !== 'AssignmentPattern')
+        return { bindable: false };
+    const right = value.right;
+    if (isCall(right, '$bindable')) {
+        const [fallback] = right.arguments;
+        return { bindable: true, default: fallback ? source(fallback, code) : undefined };
+    }
+    return { bindable: false, default: source(right, code) };
+}
+function source(node, code) {
+    return code.slice(node.start, node.end);
+}
+/** `generics="T extends string, U = number"` → `['T', 'U']`. */
+function genericsOf(attributes, code) {
+    for (const attr of attributes) {
+        if (attr.type !== 'Attribute' || attr.name !== 'generics')
+            continue;
+        const [text] = attr.value;
+        if (!text || text.type !== 'Text')
+            return [];
+        return splitTopLevel(String(text.data ?? source(text, code)), ',')
+            .map((param) => /^\s*([A-Za-z_$][\w$]*)/.exec(param)?.[1])
+            .filter((name) => Boolean(name));
+    }
+    return [];
+}

package/dist/buildtime/props/typescript.d.ts

@@ -0,0 +1,54 @@
+import type TS from 'typescript';
+type Ts = typeof TS;
+type Svelte2tsx = typeof import('svelte2tsx').svelte2tsx;
+export interface TypedProp {
+    name: string;
+    type: string;
+    optional: boolean;
+    /** JSDoc description, as markdown. */
+    description?: string;
+    /** `@deprecated` text (`''` when the tag is bare). */
+    deprecated?: string;
+    /** `@default` text, which wins over the destructured default. */
+    defaultTag?: string;
+    /** Tagged `@internal`: left out of the table. */
+    internal: boolean;
+}
+export interface TypedInheritedAttributes {
+    kind: 'element' | 'type';
+    label: string;
+}
+export interface TypedComponent {
+    props: TypedProp[];
+    inherited: TypedInheritedAttributes[];
+    /** Project files the component imports, directly or not, for HMR. */
+    files: string[];
+}
+export interface PropsTypeChecker {
+    /**
+     * Read several components against one program: building the program is the
+     * expensive part, so concurrent props imports share it. Each entry is
+     * `undefined` when that component has no typed `$props()`, or the error it
+     * threw.
+     */
+    read(files: string[]): (TypedComponent | undefined | Error)[];
+}
+export declare const MISSING_PEERS: string;
+/** The optional peer dependencies, plus svelte2tsx's ambient shims. */
+export interface Peers {
+    ts: Ts;
+    svelte2tsx: Svelte2tsx;
+    shims: string[];
+}
+/** Load the optional peers once per process; `undefined` when not installed. */
+export declare function loadPeers(): Promise<Peers | undefined>;
+/** A file's modification time, or `-1` when it can't be read. */
+export declare function mtimeOf(file: string): number;
+/** Whether a path lies inside a `node_modules` directory, on any platform. */
+export declare function inNodeModules(file: string): boolean;
+export declare function createPropsTypeChecker({ ts, svelte2tsx, shims }: Peers, options: {
+    root: string;
+    tsconfig?: string;
+    svelteVersion: string;
+}): PropsTypeChecker;
+export {};