@frontmcp/ui 0.5.1 → 0.6.0

package/esm/tool-template/builder.d.ts

@@ -0,0 +1,213 @@
+/**
+ * Tool Template Builder
+ *
+ * Provides utilities for building and rendering tool UI templates
+ * with the MCP Bridge runtime.
+ *
+ * Supports multiple template types with auto-detection:
+ * - HTML strings and template builder functions
+ * - React components (imported or JSX strings)
+ * - MDX content (Markdown + JSX)
+ */
+import type { TemplateContext, TemplateBuilderFn, ToolUIConfig, ToolUITemplate } from '../runtime/types';
+import type { ThemeConfig, PlatformCapabilities, DeepPartial } from '../theme';
+/**
+ * Options for rendering a tool template
+ */
+export interface RenderTemplateOptions<In = Record<string, unknown>, Out = unknown> {
+    /** UI configuration from tool metadata */
+    ui: ToolUIConfig<In, Out>;
+    /** Tool name */
+    toolName: string;
+    /** Tool input arguments */
+    input: In;
+    /** Tool output (raw result from execute) */
+    output: Out;
+    /** Structured content (parsed output for widgets) */
+    structuredContent?: unknown;
+    /** Theme configuration */
+    theme?: DeepPartial<ThemeConfig>;
+    /** Platform capabilities */
+    platform?: PlatformCapabilities;
+}
+/**
+ * Result of rendering a tool template
+ */
+export interface RenderedTemplate {
+    /** Complete HTML document string */
+    html: string;
+    /** MIME type for the response */
+    mimeType: string;
+    /** OpenAI-specific metadata (if applicable) */
+    openaiMeta?: Record<string, unknown>;
+}
+/**
+ * Build template context from render options
+ */
+export declare function buildTemplateContext<In = Record<string, unknown>, Out = unknown>(input: In, output: Out, structuredContent?: unknown): TemplateContext<In, Out>;
+/**
+ * Execute a template builder function or return static template.
+ * This is used for simple HTML templates only.
+ */
+export declare function executeTemplate<In = Record<string, unknown>, Out = unknown>(template: TemplateBuilderFn<In, Out> | string, ctx: TemplateContext<In, Out>): string;
+/**
+ * Render a template using the appropriate renderer (auto-detected).
+ *
+ * This function detects the template type and routes to the appropriate
+ * renderer (HTML, React, or MDX).
+ *
+ * @param template - The template to render
+ * @param ctx - Template context with input/output/helpers
+ * @param options - Additional render options
+ * @returns Promise resolving to rendered HTML string
+ */
+export declare function renderTemplate<In = Record<string, unknown>, Out = unknown>(template: ToolUITemplate<In, Out>, ctx: TemplateContext<In, Out>, options?: {
+    hydrate?: boolean;
+    mdxComponents?: Record<string, any>;
+}): Promise<{
+    html: string;
+    rendererType: string;
+}>;
+/**
+ * Render a tool UI template to a complete HTML document (sync version).
+ *
+ * This is the sync entry point for rendering simple HTML tool UIs. It:
+ * 1. Builds the template context with input/output/helpers
+ * 2. Executes the template builder function
+ * 3. Wraps the content in a complete HTML document with MCP Bridge
+ * 4. Applies CSP and theme configuration
+ *
+ * Note: For React/MDX templates, use `renderToolTemplateAsync` instead.
+ *
+ * @param options - Render options
+ * @returns Rendered template with HTML and metadata
+ *
+ * @example
+ * ```typescript
+ * const result = renderToolTemplate({
+ *   ui: toolMetadata.ui,
+ *   toolName: 'get_weather',
+ *   input: { location: 'San Francisco' },
+ *   output: { temperature: 72, conditions: 'sunny' },
+ * });
+ *
+ * // Use result.html for the response body
+ * // Use result.mimeType for Content-Type header
+ * ```
+ */
+export declare function renderToolTemplate<In = Record<string, unknown>, Out = unknown>(options: RenderTemplateOptions<In, Out>): RenderedTemplate;
+/**
+ * Render a tool UI template to a complete HTML document (async version).
+ *
+ * This is the async entry point that supports all template types:
+ * - HTML strings and template builder functions
+ * - React components (imported or JSX strings)
+ * - MDX content (Markdown + JSX)
+ *
+ * The template type is auto-detected and the appropriate renderer is used.
+ *
+ * @param options - Render options
+ * @returns Promise resolving to rendered template with HTML and metadata
+ *
+ * @example React component
+ * ```typescript
+ * import { WeatherWidget } from './weather-widget.tsx';
+ *
+ * const result = await renderToolTemplateAsync({
+ *   ui: { template: WeatherWidget, hydrate: true },
+ *   toolName: 'get_weather',
+ *   input: { location: 'San Francisco' },
+ *   output: { temperature: 72, conditions: 'sunny' },
+ * });
+ * ```
+ *
+ * @example MDX content
+ * ```typescript
+ * const result = await renderToolTemplateAsync({
+ *   ui: {
+ *     template: `# Weather in {output.location}\nTemperature: {output.temperature}°F`,
+ *   },
+ *   toolName: 'get_weather',
+ *   input: { location: 'San Francisco' },
+ *   output: { temperature: 72, location: 'San Francisco' },
+ * });
+ * ```
+ */
+export declare function renderToolTemplateAsync<In = Record<string, unknown>, Out = unknown>(options: RenderTemplateOptions<In, Out>): Promise<RenderedTemplate & {
+    rendererType: string;
+}>;
+/**
+ * Create a typed template builder with automatic input/output typing.
+ *
+ * This is a convenience function that helps TypeScript infer the
+ * correct types for template builder functions.
+ *
+ * @example
+ * ```typescript
+ * interface WeatherInput {
+ *   location: string;
+ * }
+ *
+ * interface WeatherOutput {
+ *   temperature: number;
+ *   conditions: string;
+ * }
+ *
+ * const weatherTemplate = createTemplate<WeatherInput, WeatherOutput>((ctx) => `
+ *   <div class="p-4">
+ *     <h2>Weather in ${ctx.helpers.escapeHtml(ctx.input.location)}</h2>
+ *     <p>${ctx.output.temperature}°F - ${ctx.output.conditions}</p>
+ *   </div>
+ * `);
+ * ```
+ */
+export declare function createTemplate<In = Record<string, unknown>, Out = unknown>(builder: TemplateBuilderFn<In, Out>): TemplateBuilderFn<In, Out>;
+/**
+ * Create a ToolUIConfig with proper typing
+ *
+ * @example
+ * ```typescript
+ * const ui = createToolUI<WeatherInput, WeatherOutput>({
+ *   template: (ctx) => `<div>${ctx.output.temperature}°F</div>`,
+ *   csp: { connectDomains: ['https://api.weather.com'] },
+ *   widgetAccessible: true,
+ * });
+ * ```
+ */
+export declare function createToolUI<In = Record<string, unknown>, Out = unknown>(config: ToolUIConfig<In, Out>): ToolUIConfig<In, Out>;
+/**
+ * Create a container div with common styling
+ */
+export declare function container(content: string, className?: string): string;
+/**
+ * Create a heading element
+ */
+export declare function heading(text: string, level?: 1 | 2 | 3 | 4): string;
+/**
+ * Create a paragraph element
+ */
+export declare function paragraph(text: string, className?: string): string;
+/**
+ * Create a key-value display
+ */
+export declare function keyValue(key: string, value: string | number | boolean, className?: string): string;
+/**
+ * Create a simple data list
+ */
+export declare function dataList(items: Array<{
+    key: string;
+    value: string | number | boolean;
+}>): string;
+/**
+ * Create an error display
+ */
+export declare function errorDisplay(message: string, details?: string): string;
+/**
+ * Create a success display
+ */
+export declare function successDisplay(message: string, details?: string): string;
+/**
+ * Create a loading indicator
+ */
+export declare function loadingDisplay(message?: string): string;
+//# sourceMappingURL=builder.d.ts.map

package/esm/tool-template/builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builder.d.ts","sourceRoot":"","sources":["../../../src/tool-template/builder.ts"],"names":[],"mappings":"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"}

package/esm/tool-template/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Tool Template Module
+ *
+ * Provides utilities for building and rendering tool UI templates
+ * that work across multiple host environments (OpenAI, Claude, ext-apps).
+ *
+ * Supports multiple template formats with auto-detection:
+ * - HTML strings and template builder functions
+ * - React components (imported from .tsx files)
+ * - JSX strings (transpiled at runtime with SWC)
+ * - MDX content (Markdown + JSX)
+ *
+ * @module @frontmcp/ui/tool-template
+ */
+export { type RenderTemplateOptions, type RenderedTemplate, buildTemplateContext, executeTemplate, renderToolTemplate, renderTemplate, renderToolTemplateAsync, createTemplate, createToolUI, container, heading, paragraph, keyValue, dataList, errorDisplay, successDisplay, loadingDisplay, } from './builder';
+//# sourceMappingURL=index.d.ts.map

package/esm/tool-template/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/tool-template/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAEL,KAAK,qBAAqB,EAC1B,KAAK,gBAAgB,EAErB,oBAAoB,EACpB,eAAe,EACf,kBAAkB,EAElB,cAAc,EACd,uBAAuB,EAEvB,cAAc,EACd,YAAY,EAEZ,SAAS,EACT,OAAO,EACP,SAAS,EACT,QAAQ,EACR,QAAQ,EACR,YAAY,EACZ,cAAc,EACd,cAAc,GACf,MAAM,WAAW,CAAC"}