@openuji/speculator 0.1.0 → 0.3.0

package/dist/browser.d.cts

@@ -0,0 +1,259 @@
+import MarkdownIt from 'markdown-it';
+
+/**
+ * Service responsible for processing data-format attributes and markdown content.
+ */
+declare class FormatProcessor {
+    private readonly markdownOptions;
+    constructor(markdownOptions?: MarkdownOptions);
+    /**
+     * Convert content based on the specified format.
+     */
+    processContent(content: string, format: DataFormat): string;
+    /**
+     * Process an element with a data-format attribute.
+     */
+    process(element: Element, stats: ProcessingStats, warnings: string[]): void;
+}
+
+/**
+ * Service responsible for handling data-include attributes.
+ */
+declare class IncludeProcessor {
+    private readonly baseUrl;
+    private readonly fileLoader;
+    private readonly formatProcessor;
+    constructor(baseUrl: string | undefined, fileLoader: FileLoader, formatProcessor: FormatProcessor);
+    process(element: Element, stats: ProcessingStats, warnings: string[]): Promise<void>;
+    private resolveFilePath;
+}
+
+/**
+ * Abstraction over DOM parsing and serialization, allowing custom implementations.
+ */
+interface HtmlRenderer {
+    parse(html: string): Element;
+    serialize(element: Element): string;
+}
+/**
+ * Default DOM-based implementation using DOMParser.
+ */
+declare class DOMHtmlRenderer implements HtmlRenderer {
+    parse(html: string): Element;
+    serialize(element: Element): string;
+}
+
+/**
+ * Configuration options for Speculator
+ */
+interface SpeculatorOptions {
+    /** Base URL for resolving relative file paths */
+    baseUrl?: string;
+    /** Custom file loader function */
+    fileLoader?: FileLoader;
+    /** Markdown parsing options */
+    markdownOptions?: MarkdownOptions;
+    postprocess?: PostprocessOptions;
+    includeProcessor?: IncludeProcessor;
+    formatProcessor?: FormatProcessor;
+    htmlRenderer?: HtmlRenderer;
+}
+/**
+ * File loader function type
+ */
+type FileLoader = (path: string) => Promise<string>;
+/**
+ * Markdown parsing options
+ */
+interface MarkdownOptions {
+    /** Enable GitHub Flavored Markdown */
+    gfm?: boolean;
+    /** Enable line breaks */
+    breaks?: boolean;
+    /** Enable smart typography */
+    smartypants?: boolean;
+    /** Generate header IDs */
+    headerIds?: boolean;
+    /** Custom renderer extensions */
+    extensions?: Array<MarkdownIt.PluginSimple | [MarkdownIt.PluginWithOptions<any>, any]>;
+}
+/**
+ * Processing result for a single element
+ */
+interface ProcessingResult {
+    /** The processed HTML element */
+    element: Element;
+    /** Any warnings encountered during processing */
+    warnings: string[];
+    /** Processing statistics */
+    stats: ProcessingStats;
+}
+interface HtmlProcessingResult {
+    /** The processed HTML element */
+    html: string;
+    /** Any warnings encountered during processing */
+    warnings: string[];
+    /** Processing statistics */
+    stats: ProcessingStats;
+}
+/**
+ * Processing statistics
+ */
+interface ProcessingStats {
+    /** Number of elements processed */
+    elementsProcessed: number;
+    /** Number of files included */
+    filesIncluded: number;
+    /** Number of markdown blocks converted */
+    markdownBlocks: number;
+    /** Processing time in milliseconds */
+    processingTime: number;
+}
+/**
+ * Supported data formats
+ */
+type DataFormat = 'markdown' | 'text' | 'html';
+/**
+ * Error thrown during rendering
+ */
+declare class SpeculatorError extends Error {
+    readonly element?: Element | undefined;
+    readonly path?: string | undefined;
+    constructor(message: string, element?: Element | undefined, path?: string | undefined);
+}
+type XrefQuery = {
+    /** Unique identifier returned with results (internal use). */
+    id?: string;
+    /** The term to resolve. */
+    term: string;
+    /** Optional list of spec shortnames to constrain the search. */
+    specs?: string[];
+    /** Additional context for the lookup (unused for now). */
+    context?: string;
+};
+type XrefResult = {
+    href: string;
+    text?: string;
+    cite?: string;
+};
+interface XrefResolver {
+    /**
+     * Resolve a batch of xref queries. The returned map is keyed by the query's
+     * `id` if provided, otherwise by the query term.
+     */
+    resolveBatch(queries: XrefQuery[]): Promise<Map<string, XrefResult[]>>;
+}
+interface XrefOptions {
+    specs?: string[];
+    resolver: XrefResolver;
+}
+interface BiblioEntry {
+    id: string;
+    title?: string;
+    href?: string;
+    publisher?: string;
+    date?: string;
+    status?: string;
+}
+interface BiblioOptions {
+    /** Optional local entries (used in later steps). */
+    entries?: Record<string, BiblioEntry>;
+}
+interface IdlOptions {
+    enable?: boolean;
+}
+interface TocOptions {
+    /** CSS selector for the ToC mount point (default: '#toc'). */
+    selector?: string;
+    enabled?: boolean;
+}
+interface DiagnosticsOptions {
+    /** Suppress link warnings within elements having this class. */
+    suppressClass?: string;
+    /** Enable duplicate-id and missing-href checks (default true). */
+    idsAndLinks?: boolean;
+}
+interface BoilerplateOptions {
+    conformance?: boolean | {
+        title?: string;
+        id?: string;
+        content?: string;
+    };
+    security?: boolean | {
+        title?: string;
+        id?: string;
+        content?: string;
+    };
+    privacy?: boolean | {
+        title?: string;
+        id?: string;
+        content?: string;
+    };
+    mount?: 'end' | 'before-references' | 'after-toc';
+}
+interface PostprocessOptions {
+    xref?: XrefOptions | XrefOptions[];
+    biblio?: BiblioOptions;
+    idl?: IdlOptions;
+    toc?: TocOptions;
+    diagnostics?: DiagnosticsOptions;
+    boilerplate?: BoilerplateOptions;
+}
+
+/**
+ * Main Speculator renderer class
+ */
+declare class Speculator {
+    private readonly includeProcessor;
+    private readonly formatProcessor;
+    private readonly htmlRenderer;
+    private readonly postprocessOptions;
+    private readonly postprocessor;
+    constructor(options?: SpeculatorOptions);
+    /**
+     * Process a single DOM element
+     */
+    processElement(element: Element): Promise<ProcessingResult>;
+    /**
+     * Process an entire document
+     */
+    renderDocument(container: Element): Promise<ProcessingResult>;
+    /**
+     * Process HTML string and return processed HTML
+     */
+    renderHTML(inputHtml: string): Promise<HtmlProcessingResult>;
+}
+
+declare function createMarkdownRenderer(options?: MarkdownOptions): MarkdownIt;
+declare function parseMarkdown(markdown: string, options?: MarkdownOptions, env?: Record<string, any>): string;
+
+/**
+ * Default file loader for Node.js environments
+ */
+declare const nodeFileLoader: FileLoader;
+/**
+ * Default file loader for browser environments
+ */
+declare const browserFileLoader: FileLoader;
+/**
+ * Creates a file loader that tries multiple loaders in sequence
+ */
+declare function createFallbackFileLoader(loaders: FileLoader[]): FileLoader;
+/**
+ * Auto-detects the appropriate file loader for the current environment
+ */
+declare function getDefaultFileLoader(): FileLoader;
+
+/**
+ * Xref resolver that queries the public ReSpec xref database.
+ *
+ * The fetch implementation is injectable to allow easy testing.
+ */
+declare class RespecXrefResolver implements XrefResolver {
+    private readonly fetchFn;
+    private readonly endpoint;
+    constructor(fetchFn?: typeof fetch, endpoint?: string);
+    resolveBatch(queries: XrefQuery[]): Promise<Map<string, XrefResult[]>>;
+}
+
+export { DOMHtmlRenderer, type DataFormat, type FileLoader, FormatProcessor, type HtmlRenderer, IncludeProcessor, type MarkdownOptions, type ProcessingResult, type ProcessingStats, RespecXrefResolver, Speculator, SpeculatorError, type SpeculatorOptions, browserFileLoader, createFallbackFileLoader, createMarkdownRenderer, getDefaultFileLoader, nodeFileLoader, parseMarkdown };

package/dist/browser.d.ts

@@ -0,0 +1,259 @@
+import MarkdownIt from 'markdown-it';
+
+/**
+ * Service responsible for processing data-format attributes and markdown content.
+ */
+declare class FormatProcessor {
+    private readonly markdownOptions;
+    constructor(markdownOptions?: MarkdownOptions);
+    /**
+     * Convert content based on the specified format.
+     */
+    processContent(content: string, format: DataFormat): string;
+    /**
+     * Process an element with a data-format attribute.
+     */
+    process(element: Element, stats: ProcessingStats, warnings: string[]): void;
+}
+
+/**
+ * Service responsible for handling data-include attributes.
+ */
+declare class IncludeProcessor {
+    private readonly baseUrl;
+    private readonly fileLoader;
+    private readonly formatProcessor;
+    constructor(baseUrl: string | undefined, fileLoader: FileLoader, formatProcessor: FormatProcessor);
+    process(element: Element, stats: ProcessingStats, warnings: string[]): Promise<void>;
+    private resolveFilePath;
+}
+
+/**
+ * Abstraction over DOM parsing and serialization, allowing custom implementations.
+ */
+interface HtmlRenderer {
+    parse(html: string): Element;
+    serialize(element: Element): string;
+}
+/**
+ * Default DOM-based implementation using DOMParser.
+ */
+declare class DOMHtmlRenderer implements HtmlRenderer {
+    parse(html: string): Element;
+    serialize(element: Element): string;
+}
+
+/**
+ * Configuration options for Speculator
+ */
+interface SpeculatorOptions {
+    /** Base URL for resolving relative file paths */
+    baseUrl?: string;
+    /** Custom file loader function */
+    fileLoader?: FileLoader;
+    /** Markdown parsing options */
+    markdownOptions?: MarkdownOptions;
+    postprocess?: PostprocessOptions;
+    includeProcessor?: IncludeProcessor;
+    formatProcessor?: FormatProcessor;
+    htmlRenderer?: HtmlRenderer;
+}
+/**
+ * File loader function type
+ */
+type FileLoader = (path: string) => Promise<string>;
+/**
+ * Markdown parsing options
+ */
+interface MarkdownOptions {
+    /** Enable GitHub Flavored Markdown */
+    gfm?: boolean;
+    /** Enable line breaks */
+    breaks?: boolean;
+    /** Enable smart typography */
+    smartypants?: boolean;
+    /** Generate header IDs */
+    headerIds?: boolean;
+    /** Custom renderer extensions */
+    extensions?: Array<MarkdownIt.PluginSimple | [MarkdownIt.PluginWithOptions<any>, any]>;
+}
+/**
+ * Processing result for a single element
+ */
+interface ProcessingResult {
+    /** The processed HTML element */
+    element: Element;
+    /** Any warnings encountered during processing */
+    warnings: string[];
+    /** Processing statistics */
+    stats: ProcessingStats;
+}
+interface HtmlProcessingResult {
+    /** The processed HTML element */
+    html: string;
+    /** Any warnings encountered during processing */
+    warnings: string[];
+    /** Processing statistics */
+    stats: ProcessingStats;
+}
+/**
+ * Processing statistics
+ */
+interface ProcessingStats {
+    /** Number of elements processed */
+    elementsProcessed: number;
+    /** Number of files included */
+    filesIncluded: number;
+    /** Number of markdown blocks converted */
+    markdownBlocks: number;
+    /** Processing time in milliseconds */
+    processingTime: number;
+}
+/**
+ * Supported data formats
+ */
+type DataFormat = 'markdown' | 'text' | 'html';
+/**
+ * Error thrown during rendering
+ */
+declare class SpeculatorError extends Error {
+    readonly element?: Element | undefined;
+    readonly path?: string | undefined;
+    constructor(message: string, element?: Element | undefined, path?: string | undefined);
+}
+type XrefQuery = {
+    /** Unique identifier returned with results (internal use). */
+    id?: string;
+    /** The term to resolve. */
+    term: string;
+    /** Optional list of spec shortnames to constrain the search. */
+    specs?: string[];
+    /** Additional context for the lookup (unused for now). */
+    context?: string;
+};
+type XrefResult = {
+    href: string;
+    text?: string;
+    cite?: string;
+};
+interface XrefResolver {
+    /**
+     * Resolve a batch of xref queries. The returned map is keyed by the query's
+     * `id` if provided, otherwise by the query term.
+     */
+    resolveBatch(queries: XrefQuery[]): Promise<Map<string, XrefResult[]>>;
+}
+interface XrefOptions {
+    specs?: string[];
+    resolver: XrefResolver;
+}
+interface BiblioEntry {
+    id: string;
+    title?: string;
+    href?: string;
+    publisher?: string;
+    date?: string;
+    status?: string;
+}
+interface BiblioOptions {
+    /** Optional local entries (used in later steps). */
+    entries?: Record<string, BiblioEntry>;
+}
+interface IdlOptions {
+    enable?: boolean;
+}
+interface TocOptions {
+    /** CSS selector for the ToC mount point (default: '#toc'). */
+    selector?: string;
+    enabled?: boolean;
+}
+interface DiagnosticsOptions {
+    /** Suppress link warnings within elements having this class. */
+    suppressClass?: string;
+    /** Enable duplicate-id and missing-href checks (default true). */
+    idsAndLinks?: boolean;
+}
+interface BoilerplateOptions {
+    conformance?: boolean | {
+        title?: string;
+        id?: string;
+        content?: string;
+    };
+    security?: boolean | {
+        title?: string;
+        id?: string;
+        content?: string;
+    };
+    privacy?: boolean | {
+        title?: string;
+        id?: string;
+        content?: string;
+    };
+    mount?: 'end' | 'before-references' | 'after-toc';
+}
+interface PostprocessOptions {
+    xref?: XrefOptions | XrefOptions[];
+    biblio?: BiblioOptions;
+    idl?: IdlOptions;
+    toc?: TocOptions;
+    diagnostics?: DiagnosticsOptions;
+    boilerplate?: BoilerplateOptions;
+}
+
+/**
+ * Main Speculator renderer class
+ */
+declare class Speculator {
+    private readonly includeProcessor;
+    private readonly formatProcessor;
+    private readonly htmlRenderer;
+    private readonly postprocessOptions;
+    private readonly postprocessor;
+    constructor(options?: SpeculatorOptions);
+    /**
+     * Process a single DOM element
+     */
+    processElement(element: Element): Promise<ProcessingResult>;
+    /**
+     * Process an entire document
+     */
+    renderDocument(container: Element): Promise<ProcessingResult>;
+    /**
+     * Process HTML string and return processed HTML
+     */
+    renderHTML(inputHtml: string): Promise<HtmlProcessingResult>;
+}
+
+declare function createMarkdownRenderer(options?: MarkdownOptions): MarkdownIt;
+declare function parseMarkdown(markdown: string, options?: MarkdownOptions, env?: Record<string, any>): string;
+
+/**
+ * Default file loader for Node.js environments
+ */
+declare const nodeFileLoader: FileLoader;
+/**
+ * Default file loader for browser environments
+ */
+declare const browserFileLoader: FileLoader;
+/**
+ * Creates a file loader that tries multiple loaders in sequence
+ */
+declare function createFallbackFileLoader(loaders: FileLoader[]): FileLoader;
+/**
+ * Auto-detects the appropriate file loader for the current environment
+ */
+declare function getDefaultFileLoader(): FileLoader;
+
+/**
+ * Xref resolver that queries the public ReSpec xref database.
+ *
+ * The fetch implementation is injectable to allow easy testing.
+ */
+declare class RespecXrefResolver implements XrefResolver {
+    private readonly fetchFn;
+    private readonly endpoint;
+    constructor(fetchFn?: typeof fetch, endpoint?: string);
+    resolveBatch(queries: XrefQuery[]): Promise<Map<string, XrefResult[]>>;
+}
+
+export { DOMHtmlRenderer, type DataFormat, type FileLoader, FormatProcessor, type HtmlRenderer, IncludeProcessor, type MarkdownOptions, type ProcessingResult, type ProcessingStats, RespecXrefResolver, Speculator, SpeculatorError, type SpeculatorOptions, browserFileLoader, createFallbackFileLoader, createMarkdownRenderer, getDefaultFileLoader, nodeFileLoader, parseMarkdown };

package/dist/browser.js

@@ -0,0 +1,28 @@
+import {
+  DOMHtmlRenderer,
+  FormatProcessor,
+  IncludeProcessor,
+  RespecXrefResolver,
+  Speculator,
+  SpeculatorError,
+  browserFileLoader,
+  createFallbackFileLoader,
+  createMarkdownRenderer,
+  getDefaultFileLoader,
+  nodeFileLoader,
+  parseMarkdown
+} from "./chunk-U4GQ6EOV.js";
+export {
+  DOMHtmlRenderer,
+  FormatProcessor,
+  IncludeProcessor,
+  RespecXrefResolver,
+  Speculator,
+  SpeculatorError,
+  browserFileLoader,
+  createFallbackFileLoader,
+  createMarkdownRenderer,
+  getDefaultFileLoader,
+  nodeFileLoader,
+  parseMarkdown
+};