@frontmcp/ui 0.5.0 → 0.6.0

package/esm/dependency/template-loader.d.ts

@@ -0,0 +1,204 @@
+/**
+ * Template Loader
+ *
+ * Handles loading templates from various sources:
+ * - Inline strings
+ * - File paths
+ * - CDN URLs
+ *
+ * Supports caching for URL templates with ETag validation.
+ *
+ * @packageDocumentation
+ */
+import { type TemplateMode, type TemplateSource, type TemplateFormat, type ResolvedTemplate, type UrlFetchResult } from './types';
+/**
+ * Get the URL cache (for testing/debugging).
+ */
+export declare function getUrlCache(): Map<string, UrlFetchResult>;
+/**
+ * Clear the URL cache.
+ */
+export declare function clearUrlCache(): void;
+/**
+ * Detect the source type of a template string.
+ *
+ * @param template - Template string (inline content, file path, or URL)
+ * @returns TemplateSource discriminated union
+ *
+ * @example
+ * ```typescript
+ * detectTemplateSource('https://cdn.example.com/widget.html')
+ * // => { type: 'url', url: 'https://cdn.example.com/widget.html' }
+ *
+ * detectTemplateSource('./widgets/chart.tsx')
+ * // => { type: 'file', path: './widgets/chart.tsx' }
+ *
+ * detectTemplateSource('<div>{{output.data}}</div>')
+ * // => { type: 'inline', content: '<div>{{output.data}}</div>' }
+ * ```
+ */
+export declare function detectTemplateSource(template: string): TemplateSource;
+/**
+ * Check if a template mode is file-based (file or URL).
+ */
+export declare function isFileBasedTemplate(mode: TemplateMode): boolean;
+/**
+ * Validate that a URL is allowed for template fetching.
+ * Only HTTPS URLs are allowed.
+ *
+ * @param url - URL to validate
+ * @throws Error if URL is not HTTPS
+ */
+export declare function validateTemplateUrl(url: string): void;
+/**
+ * Detect template format from a URL.
+ *
+ * @param url - URL to detect format from
+ * @returns Detected template format
+ */
+export declare function detectFormatFromUrl(url: string): TemplateFormat;
+/**
+ * Options for fetching a template from URL.
+ */
+export interface FetchTemplateOptions {
+    /**
+     * Request timeout in milliseconds.
+     * @default 30000 (30 seconds)
+     */
+    timeout?: number;
+    /**
+     * Whether to skip cache and always fetch fresh.
+     * @default false
+     */
+    skipCache?: boolean;
+    /**
+     * Custom headers to include in the request.
+     */
+    headers?: Record<string, string>;
+}
+/**
+ * Fetch a template from a URL with ETag caching support.
+ *
+ * @param url - HTTPS URL to fetch from
+ * @param options - Fetch options
+ * @returns Fetched content with metadata
+ * @throws Error if URL is not HTTPS or fetch fails
+ *
+ * @example
+ * ```typescript
+ * const result = await fetchTemplateFromUrl('https://cdn.example.com/widget.html');
+ * console.log(result.content); // Template HTML
+ * console.log(result.etag);    // "abc123" (for cache validation)
+ * ```
+ */
+export declare function fetchTemplateFromUrl(url: string, options?: FetchTemplateOptions): Promise<UrlFetchResult>;
+/**
+ * Options for reading a template from file.
+ */
+export interface ReadTemplateOptions {
+    /**
+     * Base path for resolving relative file paths.
+     * @default process.cwd()
+     */
+    basePath?: string;
+    /**
+     * File encoding.
+     * @default 'utf-8'
+     */
+    encoding?: BufferEncoding;
+}
+/**
+ * Read a template from a file path.
+ *
+ * @param filePath - Relative or absolute file path
+ * @param options - Read options
+ * @returns Template content
+ * @throws Error if file cannot be read
+ *
+ * @example
+ * ```typescript
+ * const content = await readTemplateFromFile('./widgets/chart.tsx');
+ * console.log(content); // File contents
+ *
+ * const content2 = await readTemplateFromFile('./widgets/chart.tsx', {
+ *   basePath: '/app/src',
+ * });
+ * ```
+ */
+export declare function readTemplateFromFile(filePath: string, options?: ReadTemplateOptions): Promise<string>;
+/**
+ * Resolve a file path to an absolute path.
+ *
+ * @param filePath - Relative or absolute file path
+ * @param basePath - Base path for resolving relative paths
+ * @returns Absolute file path
+ */
+export declare function resolveFilePath(filePath: string, basePath?: string): string;
+/**
+ * Options for resolving a template.
+ */
+export interface ResolveTemplateOptions {
+    /**
+     * Base path for resolving relative file paths.
+     * @default process.cwd()
+     */
+    basePath?: string;
+    /**
+     * Whether to skip URL cache.
+     * @default false
+     */
+    skipCache?: boolean;
+    /**
+     * Request timeout for URL fetches in milliseconds.
+     * @default 30000
+     */
+    timeout?: number;
+    /**
+     * Override the detected format.
+     */
+    format?: TemplateFormat;
+}
+/**
+ * Resolve a template from any source (inline, file, or URL).
+ *
+ * This is the main entry point for loading templates. It:
+ * 1. Detects the source type (inline, file, URL)
+ * 2. Loads the content from the appropriate source
+ * 3. Detects the format from file extension
+ * 4. Computes content hash for caching
+ *
+ * @param template - Template string (inline content, file path, or URL)
+ * @param options - Resolution options
+ * @returns Resolved template with content and metadata
+ *
+ * @example
+ * ```typescript
+ * // Inline template
+ * const inline = await resolveTemplate('<div>{{output}}</div>');
+ *
+ * // File template
+ * const file = await resolveTemplate('./widgets/chart.tsx', {
+ *   basePath: '/app/src',
+ * });
+ *
+ * // URL template
+ * const url = await resolveTemplate('https://cdn.example.com/widget.html');
+ * ```
+ */
+export declare function resolveTemplate(template: string, options?: ResolveTemplateOptions): Promise<ResolvedTemplate>;
+/**
+ * Check if a resolved template needs re-fetching based on cache state.
+ * Only applicable for URL templates.
+ *
+ * @param resolved - Previously resolved template
+ * @returns true if the template should be re-fetched
+ */
+export declare function needsRefetch(resolved: ResolvedTemplate): boolean;
+/**
+ * Invalidate a cached URL template.
+ *
+ * @param url - URL to invalidate
+ * @returns true if the entry was removed
+ */
+export declare function invalidateUrlCache(url: string): boolean;
+//# sourceMappingURL=template-loader.d.ts.map

package/esm/dependency/template-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"template-loader.d.ts","sourceRoot":"","sources":["../../../src/dependency/template-loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,OAAO,EAGL,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,KAAK,cAAc,EACpB,MAAM,SAAS,CAAC;AAajB;;GAEG;AACH,wBAAgB,WAAW,IAAI,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,CAEzD;AAED;;GAEG;AACH,wBAAgB,aAAa,IAAI,IAAI,CAEpC;AAMD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,cAAc,CAarE;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAE/D;AAMD;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAMrD;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,CAG/D;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,oBAAoB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,oBAAyB,GAAG,OAAO,CAAC,cAAc,CAAC,CA6DnH;AA+BD;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;OAGG;IACH,QAAQ,CAAC,EAAE,cAAc,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE,mBAAwB,GAAG,OAAO,CAAC,MAAM,CAAC,CAwB/G;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,GAAE,MAAsB,GAAG,MAAM,CAE1F;AAMD;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,MAAM,CAAC,EAAE,cAAc,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAsB,eAAe,CACnC,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,gBAAgB,CAAC,CAiD3B;AASD;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,gBAAgB,GAAG,OAAO,CAyBhE;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAEvD"}

package/esm/dependency/template-processor.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Template Processor
+ *
+ * Processes resolved templates through format-specific rendering pipelines:
+ * - HTML: Handlebars → Output
+ * - Markdown: Handlebars → marked → HTML
+ * - MDX: Handlebars → MDX Renderer → HTML
+ * - React: Pass-through (data via props, needs bundling)
+ *
+ * @packageDocumentation
+ */
+import type { ResolvedTemplate, TemplateProcessingOptions, ProcessedTemplate, TemplateFormat } from './types';
+/**
+ * Clear the Handlebars renderer cache.
+ * Useful for testing.
+ */
+export declare function clearHandlebarsCache(): void;
+/**
+ * Check if marked is available.
+ */
+export declare function isMarkedAvailable(): Promise<boolean>;
+/**
+ * Process a resolved template through the appropriate rendering pipeline.
+ *
+ * Processing differs by format:
+ * - **HTML**: Apply Handlebars if {{...}} present → Return HTML
+ * - **Markdown**: Apply Handlebars → Parse with marked → Return HTML
+ * - **MDX**: Apply Handlebars → Render with MDX renderer → Return HTML
+ * - **React**: Return as-is (data passed via props, needs bundling)
+ *
+ * @param resolved - Resolved template from template-loader
+ * @param options - Processing options with context data
+ * @returns Processed template ready for rendering
+ *
+ * @example HTML template
+ * ```typescript
+ * const resolved = await resolveTemplate('./weather.html');
+ * const result = await processTemplate(resolved, {
+ *   context: {
+ *     input: { city: 'Seattle' },
+ *     output: { temperature: 72, conditions: 'Sunny' },
+ *   },
+ * });
+ * // result.html = '<div>72°F in Seattle</div>'
+ * ```
+ *
+ * @example Markdown template
+ * ```typescript
+ * const resolved = await resolveTemplate('./report.md');
+ * const result = await processTemplate(resolved, {
+ *   context: {
+ *     input: {},
+ *     output: { title: 'Q4 Report', items: [...] },
+ *   },
+ * });
+ * // result.html = '<h1>Q4 Report</h1>...'
+ * ```
+ */
+export declare function processTemplate(resolved: ResolvedTemplate, options: TemplateProcessingOptions): Promise<ProcessedTemplate>;
+/**
+ * Process multiple templates in parallel.
+ *
+ * @param items - Array of resolved templates with their options
+ * @returns Array of processed templates
+ */
+export declare function processTemplates(items: Array<{
+    resolved: ResolvedTemplate;
+    options: TemplateProcessingOptions;
+}>): Promise<ProcessedTemplate[]>;
+/**
+ * Check if a template format requires Handlebars processing.
+ *
+ * @param format - Template format
+ * @returns true if Handlebars can be applied
+ */
+export declare function supportsHandlebars(format: TemplateFormat): boolean;
+/**
+ * Check if a template format produces HTML output.
+ *
+ * @param format - Template format
+ * @returns true if the format produces HTML
+ */
+export declare function producesHtml(format: TemplateFormat): boolean;
+/**
+ * Check if a template format requires bundling.
+ *
+ * @param format - Template format
+ * @returns true if the format needs to be bundled
+ */
+export declare function requiresBundling(format: TemplateFormat): boolean;
+/**
+ * Process an HTML template with Handlebars.
+ *
+ * @param content - HTML template content
+ * @param context - Processing context
+ * @param helpers - Custom Handlebars helpers
+ * @returns Processed HTML
+ */
+export declare function processHtmlTemplate(content: string, context: TemplateProcessingOptions['context'], helpers?: TemplateProcessingOptions['handlebarsHelpers']): Promise<string>;
+/**
+ * Process a Markdown template with Handlebars and marked.
+ *
+ * @param content - Markdown template content
+ * @param context - Processing context
+ * @param helpers - Custom Handlebars helpers
+ * @returns Processed HTML
+ */
+export declare function processMarkdownTemplate(content: string, context: TemplateProcessingOptions['context'], helpers?: TemplateProcessingOptions['handlebarsHelpers']): Promise<string>;
+/**
+ * Process an MDX template with Handlebars and MDX renderer.
+ *
+ * @param content - MDX template content
+ * @param context - Processing context
+ * @param helpers - Custom Handlebars helpers
+ * @returns Processed HTML
+ */
+export declare function processMdxTemplate(content: string, context: TemplateProcessingOptions['context'], helpers?: TemplateProcessingOptions['handlebarsHelpers']): Promise<string>;
+//# sourceMappingURL=template-processor.d.ts.map

package/esm/dependency/template-processor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"template-processor.d.ts","sourceRoot":"","sources":["../../../src/dependency/template-processor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EACV,gBAAgB,EAChB,yBAAyB,EACzB,iBAAiB,EACjB,cAAc,EAEf,MAAM,SAAS,CAAC;AA2FjB;;;GAGG;AACH,wBAAgB,oBAAoB,IAAI,IAAI,CAI3C;AAwCD;;GAEG;AACH,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,OAAO,CAAC,CAO1D;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAsB,eAAe,CACnC,QAAQ,EAAE,gBAAgB,EAC1B,OAAO,EAAE,yBAAyB,GACjC,OAAO,CAAC,iBAAiB,CAAC,CAyF5B;AAED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,KAAK,CAAC;IAAE,QAAQ,EAAE,gBAAgB,CAAC;IAAC,OAAO,EAAE,yBAAyB,CAAA;CAAE,CAAC,GAC/E,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAE9B;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAElE;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAE5D;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAEhE;AAMD;;;;;;;GAOG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,yBAAyB,CAAC,SAAS,CAAC,EAC7C,OAAO,CAAC,EAAE,yBAAyB,CAAC,mBAAmB,CAAC,GACvD,OAAO,CAAC,MAAM,CAAC,CAcjB;AAED;;;;;;;GAOG;AACH,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,yBAAyB,CAAC,SAAS,CAAC,EAC7C,OAAO,CAAC,EAAE,yBAAyB,CAAC,mBAAmB,CAAC,GACvD,OAAO,CAAC,MAAM,CAAC,CAkBjB;AAED;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,yBAAyB,CAAC,SAAS,CAAC,EAC7C,OAAO,CAAC,EAAE,yBAAyB,CAAC,mBAAmB,CAAC,GACvD,OAAO,CAAC,MAAM,CAAC,CAwBjB"}