sveld 0.26.2 → 0.27.0

package/lib/writer/WriterMarkdown.js

@@ -1,65 +0,0 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-const MarkdownWriterBase_1 = require("./MarkdownWriterBase");
-const Writer_1 = __importDefault(require("./Writer"));
-/**
- * Markdown writer that extends Writer for file operations.
- *
- * Combines file writing capabilities from Writer with markdown
- * generation capabilities from MarkdownWriterBaseImpl. Supports
- * callbacks for monitoring document construction.
- *
- * @example
- * ```ts
- * const writer = new WriterMarkdown({
- *   onAppend: (type, doc) => {
- *     console.log(`Appended ${type} to markdown`);
- *   }
- * });
- * writer.append("h1", "Title");
- * await writer.write("./docs.md", writer.end());
- * ```
- */
-class WriterMarkdown extends Writer_1.default {
-    onAppend;
-    markdownBase;
-    /**
-     * Creates a new WriterMarkdown instance.
-     *
-     * @param options - Markdown writer options including append callback
-     */
-    constructor(options) {
-        super({ parser: "markdown", printWidth: 80 });
-        this.onAppend = options.onAppend;
-        this.markdownBase = new MarkdownWriterBase_1.MarkdownWriterBaseImpl();
-    }
-    get source() {
-        return this.markdownBase.source;
-    }
-    get hasToC() {
-        return this.markdownBase.hasToC;
-    }
-    get toc() {
-        return this.markdownBase.toc;
-    }
-    appendLineBreaks() {
-        this.markdownBase.appendLineBreaks();
-        return this;
-    }
-    append(type, raw) {
-        this.markdownBase.append(type, raw);
-        this.onAppend?.call(this, type, this);
-        return this;
-    }
-    tableOfContents() {
-        this.markdownBase.tableOfContents();
-        return this;
-    }
-    end() {
-        return this.markdownBase.end();
-    }
-}
-exports.default = WriterMarkdown;

package/lib/writer/markdown-format-utils.js

@@ -1,158 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.EVENT_TABLE_HEADER = exports.SLOT_TABLE_HEADER = exports.PROP_TABLE_HEADER = exports.MD_TYPE_UNDEFINED = exports.WHITESPACE_REGEX = exports.BACKTICK_REGEX = void 0;
-exports.formatPropType = formatPropType;
-exports.escapeHtml = escapeHtml;
-exports.formatPropValue = formatPropValue;
-exports.formatPropDescription = formatPropDescription;
-exports.formatSlotProps = formatSlotProps;
-exports.formatSlotFallback = formatSlotFallback;
-exports.formatEventDetail = formatEventDetail;
-const writer_ts_definitions_core_1 = require("./writer-ts-definitions-core");
-exports.BACKTICK_REGEX = /`/g;
-exports.WHITESPACE_REGEX = /\s+/g;
-exports.MD_TYPE_UNDEFINED = "--";
-exports.PROP_TABLE_HEADER = "| Prop name | Required | Kind | Reactive | Type | Default value | Description |\n| :- | :- | :- | :- |\n";
-exports.SLOT_TABLE_HEADER = "| Slot name | Default | Props | Fallback |\n| :- | :- | :- | :- |\n";
-exports.EVENT_TABLE_HEADER = "| Event name | Type | Detail | Description |\n| :- | :- | :- | :- |\n";
-const PIPE_REGEX = /\|/g;
-const LT_REGEX = /</g;
-const GT_REGEX = />/g;
-const NEWLINE_REGEX = /\n/g;
-/**
- * Formats a prop type for display in markdown tables.
- *
- * Escapes pipe characters to prevent breaking markdown table syntax
- * and wraps the type in a code block.
- *
- * @param type - The type string to format
- * @returns Formatted type string or MD_TYPE_UNDEFINED if type is undefined
- *
- * @example
- * ```ts
- * formatPropType("string | number") // Returns: "<code>string &#124; number</code>"
- * formatPropType(undefined)         // Returns: "--"
- * ```
- */
-function formatPropType(type) {
-    if (type === undefined)
-        return exports.MD_TYPE_UNDEFINED;
-    return `<code>${type.replace(PIPE_REGEX, "&#124;")}</code>`;
-}
-/**
- * Escapes HTML special characters in text.
- *
- * Converts `<` to `&lt;` and `>` to `&gt;` to prevent HTML injection
- * and ensure proper rendering in markdown.
- *
- * @param text - The text to escape
- * @returns The escaped text
- *
- * @example
- * ```ts
- * escapeHtml("<div>") // Returns: "&lt;div&gt;"
- * ```
- */
-function escapeHtml(text) {
-    return text.replace(LT_REGEX, "&lt;").replace(GT_REGEX, "&gt;");
-}
-/**
- * Formats a prop default value for display in markdown tables.
- *
- * Escapes backticks and pipe characters, and wraps the value in a code block.
- *
- * @param value - The default value string to format
- * @returns Formatted value string or MD_TYPE_UNDEFINED if value is undefined
- *
- * @example
- * ```ts
- * formatPropValue("'hello'")  // Returns: "<code>'hello'</code>"
- * formatPropValue("`test`")   // Returns: "<code>\\`test\\`</code>"
- * ```
- */
-function formatPropValue(value) {
-    if (value === undefined)
-        return exports.MD_TYPE_UNDEFINED;
-    return `<code>${value.replace(exports.BACKTICK_REGEX, "\\`").replace(PIPE_REGEX, "&#124;")}</code>`;
-}
-/**
- * Formats a prop description for display in markdown tables.
- *
- * Escapes HTML characters and converts newlines to `<br />` tags
- * for proper rendering in markdown tables.
- *
- * @param description - The description string to format
- * @returns Formatted description or MD_TYPE_UNDEFINED if description is empty
- *
- * @example
- * ```ts
- * formatPropDescription("Line 1\nLine 2")
- * // Returns: "Line 1<br />Line 2"
- * ```
- */
-function formatPropDescription(description) {
-    if (description === undefined || description.trim().length === 0)
-        return exports.MD_TYPE_UNDEFINED;
-    return escapeHtml(description).replace(NEWLINE_REGEX, "<br />");
-}
-/**
- * Formats slot props for display in markdown tables.
- *
- * Converts TypeScript type definitions to a single-line format
- * and wraps them in a code block. Returns MD_TYPE_UNDEFINED for
- * empty or undefined props.
- *
- * @param props - The slot props type string
- * @returns Formatted props string or MD_TYPE_UNDEFINED
- *
- * @example
- * ```ts
- * formatSlotProps("{ title: string }") // Returns: "<code>{ title: string }</code>"
- * formatSlotProps("{}")                 // Returns: "--"
- * ```
- */
-function formatSlotProps(props) {
-    if (props === undefined || props === "{}")
-        return exports.MD_TYPE_UNDEFINED;
-    return formatPropType((0, writer_ts_definitions_core_1.formatTsProps)(props).replace(NEWLINE_REGEX, " "));
-}
-/**
- * Formats slot fallback content for display in markdown tables.
- *
- * Escapes HTML and converts newlines to `<br />` tags, then wraps
- * in a code block.
- *
- * @param fallback - The fallback content string
- * @returns Formatted fallback string or MD_TYPE_UNDEFINED if undefined
- *
- * @example
- * ```ts
- * formatSlotFallback("<p>Default</p>")
- * // Returns: "<code>&lt;p&gt;Default&lt;/p&gt;</code>"
- * ```
- */
-function formatSlotFallback(fallback) {
-    if (fallback === undefined)
-        return exports.MD_TYPE_UNDEFINED;
-    return formatPropType(escapeHtml(fallback).replace(NEWLINE_REGEX, "<br />"));
-}
-/**
- * Formats event detail type for display in markdown tables.
- *
- * Converts the detail type to a single-line format and wraps it
- * in a code block.
- *
- * @param detail - The event detail type string
- * @returns Formatted detail string or MD_TYPE_UNDEFINED if undefined
- *
- * @example
- * ```ts
- * formatEventDetail("{ value: string }")
- * // Returns: "<code>{ value: string }</code>"
- * ```
- */
-function formatEventDetail(detail) {
-    if (detail === undefined)
-        return exports.MD_TYPE_UNDEFINED;
-    return formatPropType(detail.replace(NEWLINE_REGEX, " "));
-}

package/lib/writer/markdown-render-utils.js

@@ -1,89 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.renderComponentsToMarkdown = renderComponentsToMarkdown;
-const markdown_format_utils_1 = require("./markdown-format-utils");
-const writer_ts_definitions_core_1 = require("./writer-ts-definitions-core");
-/**
- * Renders component documentation to a markdown document.
- * This shared function is used by both writeMarkdown and writeMarkdownCore.
- */
-function renderComponentsToMarkdown(document, components) {
-    document.append("h1", "Component Index");
-    document.append("h2", "Components").tableOfContents();
-    document.append("divider");
-    const keys = Array.from(components.keys()).sort();
-    for (const key of keys) {
-        const component = components.get(key);
-        if (!component)
-            continue;
-        renderComponent(document, component);
-    }
-}
-/**
- * Renders a section conditionally - if items exist, calls renderFn, otherwise renders "None."
- */
-function renderSectionIfNotEmpty(document, items, renderFn, emptyMessage) {
-    if (items.length > 0) {
-        renderFn();
-    }
-    else {
-        document.append("p", emptyMessage ?? "None.");
-    }
-}
-/**
- * Renders a single component's documentation to the markdown document.
- *
- * @param document - The markdown document to append to
- * @param component - The component documentation to render
- */
-function renderComponent(document, component) {
-    document.append("h2", `\`${component.moduleName}\``);
-    /**
-     * Render typedefs section if the component has any type definitions.
-     */
-    if (component.typedefs.length > 0) {
-        document.append("h3", "Types").append("raw", `\`\`\`ts\n${(0, writer_ts_definitions_core_1.getTypeDefs)({
-            typedefs: component.typedefs,
-        })}\n\`\`\`\n\n`);
-    }
-    /**
-     * Render props section with a table of all component props.
-     * Props are sorted with reactive props first, then constants last.
-     */
-    document.append("h3", "Props");
-    renderSectionIfNotEmpty(document, component.props, () => {
-        document.append("raw", markdown_format_utils_1.PROP_TABLE_HEADER);
-        const sortedProps = [...component.props].sort((a) => {
-            if (a.reactive)
-                return -1;
-            if (a.constant)
-                return 1;
-            return 0;
-        });
-        for (const prop of sortedProps) {
-            document.append("raw", `| ${prop.name} | ${prop.isRequired ? "Yes" : "No"} | ${`<code>${prop.kind}</code>`} | ${prop.reactive ? "Yes" : "No"} | ${(0, markdown_format_utils_1.formatPropType)(prop.type)} | ${(0, markdown_format_utils_1.formatPropValue)(prop.value)} | ${(0, markdown_format_utils_1.formatPropDescription)(prop.description)} |\n`);
-        }
-    });
-    /**
-     * Render slots section with a table of all component slots.
-     * Includes slot name, default status, props, and fallback content.
-     */
-    document.append("h3", "Slots");
-    renderSectionIfNotEmpty(document, component.slots, () => {
-        document.append("raw", markdown_format_utils_1.SLOT_TABLE_HEADER);
-        for (const slot of component.slots) {
-            document.append("raw", `| ${slot.default ? markdown_format_utils_1.MD_TYPE_UNDEFINED : slot.name} | ${slot.default ? "Yes" : "No"} | ${(0, markdown_format_utils_1.formatSlotProps)(slot.slot_props)} | ${(0, markdown_format_utils_1.formatSlotFallback)(slot.fallback)} |\n`);
-        }
-    });
-    /**
-     * Render events section with a table of all component events.
-     * Includes event name, type (dispatched/forwarded), detail type, and description.
-     */
-    document.append("h3", "Events");
-    renderSectionIfNotEmpty(document, component.events, () => {
-        document.append("raw", markdown_format_utils_1.EVENT_TABLE_HEADER);
-        for (const event of component.events) {
-            document.append("raw", `| ${event.name} | ${event.type} | ${event.type === "dispatched" ? (0, markdown_format_utils_1.formatEventDetail)(event.detail) : markdown_format_utils_1.MD_TYPE_UNDEFINED} | ${(0, markdown_format_utils_1.formatPropDescription)(event.description)} |\n`);
-        }
-    });
-}

package/lib/writer/writer-json.js

@@ -1,119 +0,0 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.default = writeJson;
-const node_path_1 = __importDefault(require("node:path"));
-const path_1 = require("../path");
-const Writer_1 = require("./Writer");
-/**
- * Transforms and sorts component documentation for JSON output.
- *
- * Normalizes file paths and sorts components alphabetically by module name.
- *
- * @param components - Map of component documentation
- * @param inputDir - The input directory for normalizing paths
- * @returns Sorted array of component documentation with normalized paths
- *
- * @example
- * ```ts
- * // Input: components with relative paths
- * // Output: components with normalized absolute paths, sorted by name
- * ```
- */
-function transformAndSortComponents(components, inputDir) {
-    return Array.from(components, ([_moduleName, component]) => ({
-        ...component,
-        filePath: (0, path_1.normalizeSeparators)(node_path_1.default.join(inputDir, node_path_1.default.normalize(component.filePath))),
-    })).sort((a, b) => a.moduleName.localeCompare(b.moduleName));
-}
-/**
- * Writes individual JSON files for each component.
- *
- * Creates a separate `.api.json` file for each component in the
- * specified output directory. Used when `outDir` is specified.
- *
- * @param components - Map of component documentation
- * @param options - Write options including output directory
- *
- * @example
- * ```ts
- * await writeJsonComponents(components, {
- *   inputDir: "./src",
- *   outDir: "./dist"
- * });
- * // Creates: dist/Button.api.json, dist/Input.api.json, etc.
- * ```
- */
-async function writeJsonComponents(components, options) {
-    const output = transformAndSortComponents(components, options.inputDir);
-    await Promise.all(output.map((c) => {
-        const outFile = node_path_1.default.resolve(node_path_1.default.join(options.outDir || "", `${c.moduleName}.api.json`));
-        const writer = (0, Writer_1.createJsonWriter)();
-        console.log(`created ${outFile}"\n`);
-        return writer.write(outFile, JSON.stringify(c));
-    }));
-}
-/**
- * Writes component documentation to a single JSON file.
- *
- * Creates a JSON file containing all components with metadata.
- * Used when `outDir` is not specified.
- *
- * @param components - Map of component documentation
- * @param options - Write options including output file path
- *
- * @example
- * ```ts
- * await writeJsonLocal(components, {
- *   inputDir: "./src",
- *   outFile: "components.api.json"
- * });
- * // Creates: components.api.json with all component docs
- * ```
- */
-async function writeJsonLocal(components, options) {
-    const output = {
-        total: components.size,
-        components: transformAndSortComponents(components, options.inputDir),
-    };
-    const output_path = node_path_1.default.join(process.cwd(), options.outFile);
-    const writer = (0, Writer_1.createJsonWriter)();
-    await writer.write(output_path, JSON.stringify(output));
-    console.log(`created "${options.outFile}".\n`);
-}
-/**
- * Writes component documentation to JSON format.
- *
- * Can write either:
- * - Individual JSON files per component (when `outDir` is specified)
- * - A single combined JSON file (when only `outFile` is specified)
- *
- * @param components - Map of component documentation to write
- * @param options - Write options including output directory or file
- * @returns A promise that resolves when all files have been written
- *
- * @example
- * ```ts
- * // Write individual files:
- * await writeJson(components, {
- *   inputDir: "./src",
- *   outDir: "./dist"
- * });
- *
- * // Write single file:
- * await writeJson(components, {
- *   inputDir: "./src",
- *   outFile: "components.api.json"
- * });
- * ```
- */
-async function writeJson(components, options) {
-    if (options.outDir) {
-        await writeJsonComponents(components, options);
-    }
-    else {
-        await writeJsonLocal(components, options);
-    }
-}

package/lib/writer/writer-markdown-core.js

@@ -1,44 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.BrowserWriterMarkdown = void 0;
-exports.writeMarkdownCore = writeMarkdownCore;
-const MarkdownWriterBase_1 = require("./MarkdownWriterBase");
-const markdown_render_utils_1 = require("./markdown-render-utils");
-/**
- * Browser-compatible WriterMarkdown that doesn't extend Writer.
- *
- * This class is designed for browser environments where file system operations
- * are not available. It extends MarkdownWriterBaseImpl directly instead of
- * Writer to avoid Node.js dependencies.
- *
- * @example
- * ```ts
- * const writer = new BrowserWriterMarkdown({
- *   onAppend: (type, doc) => {
- *     console.log(`Appended ${type} to document`);
- *   }
- * });
- * ```
- */
-class BrowserWriterMarkdown extends MarkdownWriterBase_1.MarkdownWriterBaseImpl {
-    onAppend;
-    constructor(options) {
-        super();
-        this.onAppend = options.onAppend;
-    }
-    append(type, raw) {
-        super.append(type, raw);
-        this.onAppend?.call(this, type, this);
-        return this;
-    }
-}
-exports.BrowserWriterMarkdown = BrowserWriterMarkdown;
-function writeMarkdownCore(components, options) {
-    const document = new BrowserWriterMarkdown({
-        onAppend: (type, document) => {
-            options?.onAppend?.call(null, type, document, components);
-        },
-    });
-    (0, markdown_render_utils_1.renderComponentsToMarkdown)(document, components);
-    return document.end();
-}

package/lib/writer/writer-markdown.js

@@ -1,46 +0,0 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.default = writeMarkdown;
-const node_path_1 = require("node:path");
-const markdown_render_utils_1 = require("./markdown-render-utils");
-const WriterMarkdown_1 = __importDefault(require("./WriterMarkdown"));
-/**
- * Writes component documentation to a markdown file.
- *
- * Renders all components to markdown format and optionally writes
- * the result to a file. Returns the markdown string regardless of
- * whether it was written to disk.
- *
- * @param components - Map of component documentation to render
- * @param options - Write options including output file and callbacks
- * @returns A promise that resolves to the generated markdown string
- *
- * @example
- * ```ts
- * const markdown = await writeMarkdown(components, {
- *   outFile: "COMPONENTS.md",
- *   write: true,
- *   onAppend: (type, doc) => {
- *     console.log(`Appended ${type}`);
- *   }
- * });
- * ```
- */
-async function writeMarkdown(components, options) {
-    const write = options?.write !== false;
-    const document = new WriterMarkdown_1.default({
-        onAppend: (type, document) => {
-            options.onAppend?.call(null, type, document, components);
-        },
-    });
-    (0, markdown_render_utils_1.renderComponentsToMarkdown)(document, components);
-    if (write) {
-        const outFile = (0, node_path_1.join)(process.cwd(), options.outFile);
-        await document.write(outFile, document.end());
-        console.log(`created "${options.outFile}".`);
-    }
-    return document.end();
-}