@frontmcp/ui 0.5.0 → 0.6.0

package/esm/validation/template-validator.d.ts

@@ -0,0 +1,143 @@
+/**
+ * Template Validator
+ *
+ * Validates Handlebars templates against Zod schemas to catch
+ * references to non-existent fields.
+ *
+ * @packageDocumentation
+ */
+import { z } from 'zod';
+/**
+ * Validation error types.
+ */
+export type ValidationErrorType = 'missing_field' | 'invalid_path' | 'type_mismatch';
+/**
+ * Validation warning types.
+ */
+export type ValidationWarningType = 'optional_field' | 'array_access' | 'deep_path' | 'dynamic_path';
+/**
+ * A validation error for a missing or invalid field.
+ */
+export interface TemplateValidationError {
+    /** Error type */
+    type: ValidationErrorType;
+    /** The invalid path (e.g., "output.city") */
+    path: string;
+    /** The full Handlebars expression */
+    expression: string;
+    /** Line number in template */
+    line: number;
+    /** Column position */
+    column: number;
+    /** Human-readable error message */
+    message: string;
+    /** Suggested similar paths */
+    suggestions: string[];
+}
+/**
+ * A validation warning (non-blocking).
+ */
+export interface TemplateValidationWarning {
+    /** Warning type */
+    type: ValidationWarningType;
+    /** The path that triggered the warning */
+    path: string;
+    /** The full Handlebars expression */
+    expression: string;
+    /** Line number in template */
+    line: number;
+    /** Human-readable warning message */
+    message: string;
+}
+/**
+ * Result of template validation.
+ */
+export interface TemplateValidationResult {
+    /** Whether the template is valid (no errors) */
+    valid: boolean;
+    /** Validation errors (missing fields, etc.) */
+    errors: TemplateValidationError[];
+    /** Validation warnings (optional fields, etc.) */
+    warnings: TemplateValidationWarning[];
+    /** All paths found in the template */
+    templatePaths: string[];
+    /** All valid paths from the schema */
+    schemaPaths: string[];
+}
+/**
+ * Options for template validation.
+ */
+export interface ValidateTemplateOptions {
+    /** Schema for input.* paths (optional) */
+    inputSchema?: z.ZodTypeAny;
+    /** Warn when accessing optional fields without {{#if}} guard */
+    warnOnOptional?: boolean;
+    /** Suggest similar paths for typos */
+    suggestSimilar?: boolean;
+    /** Maximum Levenshtein distance for suggestions */
+    maxSuggestionDistance?: number;
+    /** Tool name for error messages */
+    toolName?: string;
+}
+/**
+ * Validate a Handlebars template against an output schema.
+ *
+ * @param template - The Handlebars template string
+ * @param outputSchema - Zod schema for the output
+ * @param options - Validation options
+ * @returns Validation result with errors and warnings
+ *
+ * @example
+ * ```typescript
+ * const result = validateTemplate(
+ *   '<div>{{output.temperature}} in {{output.city}}</div>',
+ *   z.object({ temperature: z.number() })
+ * );
+ *
+ * if (!result.valid) {
+ *   console.warn('Template has issues:', result.errors);
+ * }
+ * ```
+ */
+export declare function validateTemplate(template: string, outputSchema: z.ZodTypeAny, options?: ValidateTemplateOptions): TemplateValidationResult;
+/**
+ * Format validation result as console warnings.
+ *
+ * @param result - Validation result
+ * @param toolName - Tool name for context
+ * @returns Formatted warning string
+ */
+export declare function formatValidationWarnings(result: TemplateValidationResult, toolName: string): string;
+/**
+ * Log validation warnings to console in development mode.
+ *
+ * @param result - Validation result
+ * @param toolName - Tool name for context
+ */
+export declare function logValidationWarnings(result: TemplateValidationResult, toolName: string): void;
+/**
+ * Validate template and throw if invalid.
+ *
+ * @param template - The template to validate
+ * @param outputSchema - Output schema
+ * @param toolName - Tool name for error message
+ * @throws Error if template has validation errors
+ */
+export declare function assertTemplateValid(template: string, outputSchema: z.ZodTypeAny, toolName: string): void;
+/**
+ * Quickly check if a template is valid against a schema.
+ *
+ * @param template - The template to validate
+ * @param outputSchema - Output schema
+ * @returns true if valid, false otherwise
+ */
+export declare function isTemplateValid(template: string, outputSchema: z.ZodTypeAny): boolean;
+/**
+ * Get missing fields from a template.
+ *
+ * @param template - The template to check
+ * @param outputSchema - Output schema
+ * @returns Array of missing field paths
+ */
+export declare function getMissingFields(template: string, outputSchema: z.ZodTypeAny): string[];
+//# sourceMappingURL=template-validator.d.ts.map

package/esm/validation/template-validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"template-validator.d.ts","sourceRoot":"","sources":["../../../src/validation/template-validator.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAoBxB;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG,eAAe,GAAG,cAAc,GAAG,eAAe,CAAC;AAErF;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG,gBAAgB,GAAG,cAAc,GAAG,WAAW,GAAG,cAAc,CAAC;AAErG;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,iBAAiB;IACjB,IAAI,EAAE,mBAAmB,CAAC;IAC1B,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,qCAAqC;IACrC,UAAU,EAAE,MAAM,CAAC;IACnB,8BAA8B;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,sBAAsB;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,mCAAmC;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,8BAA8B;IAC9B,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC,mBAAmB;IACnB,IAAI,EAAE,qBAAqB,CAAC;IAC5B,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,qCAAqC;IACrC,UAAU,EAAE,MAAM,CAAC;IACnB,8BAA8B;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,qCAAqC;IACrC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,gDAAgD;IAChD,KAAK,EAAE,OAAO,CAAC;IACf,+CAA+C;IAC/C,MAAM,EAAE,uBAAuB,EAAE,CAAC;IAClC,kDAAkD;IAClD,QAAQ,EAAE,yBAAyB,EAAE,CAAC;IACtC,sCAAsC;IACtC,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,sCAAsC;IACtC,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,0CAA0C;IAC1C,WAAW,CAAC,EAAE,CAAC,CAAC,UAAU,CAAC;IAC3B,gEAAgE;IAChE,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,sCAAsC;IACtC,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,mDAAmD;IACnD,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,mCAAmC;IACnC,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAMD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,CAAC,CAAC,UAAU,EAC1B,OAAO,GAAE,uBAA4B,GACpC,wBAAwB,CAsG1B;AA4HD;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,wBAAwB,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CA0CnG;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,wBAAwB,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAK9F;AAMD;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,CAAC,CAAC,UAAU,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAOxG;AAMD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,CAAC,CAAC,UAAU,GAAG,OAAO,CAGrF;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,CAAC,CAAC,UAAU,GAAG,MAAM,EAAE,CAGvF"}

package/esm/validation/wrapper.d.ts

@@ -0,0 +1,97 @@
+/**
+ * @file wrapper.ts
+ * @description Validation wrapper utilities for component input validation.
+ *
+ * Provides functions to validate component options against Zod schemas
+ * and return either the validated data or an error box HTML string.
+ *
+ * @example
+ * ```typescript
+ * import { validateOptions } from '@frontmcp/ui';
+ * import { z } from 'zod';
+ *
+ * const schema = z.object({ variant: z.enum(['primary', 'secondary']) });
+ *
+ * const result = validateOptions(options, {
+ *   componentName: 'Button',
+ *   schema,
+ * });
+ *
+ * if (!result.success) return result.error; // Returns error box HTML
+ *
+ * // Use result.data safely
+ * ```
+ *
+ * @module @frontmcp/ui/validation/wrapper
+ */
+import { type ZodSchema } from 'zod';
+/**
+ * Configuration for validation
+ */
+export interface ValidationConfig {
+    /** Name of the component being validated */
+    componentName: string;
+    /** Zod schema to validate against */
+    schema: ZodSchema;
+}
+/**
+ * Result of validation - either success with data or failure with error HTML
+ */
+export type ValidationResult<T> = {
+    success: true;
+    data: T;
+} | {
+    success: false;
+    error: string;
+};
+/**
+ * Validates input against a Zod schema
+ *
+ * Returns either:
+ * - `{ success: true, data: T }` with validated/parsed data
+ * - `{ success: false, error: string }` with error box HTML
+ *
+ * @param options - The options object to validate
+ * @param config - Validation configuration (component name and schema)
+ * @returns ValidationResult with either data or error HTML
+ *
+ * @example
+ * ```typescript
+ * const result = validateOptions({ variant: 'invalid' }, {
+ *   componentName: 'Button',
+ *   schema: ButtonOptionsSchema,
+ * });
+ *
+ * if (!result.success) {
+ *   return result.error; // Error box HTML
+ * }
+ *
+ * // result.data is typed and validated
+ * ```
+ */
+export declare function validateOptions<T>(options: unknown, config: ValidationConfig): ValidationResult<T>;
+/**
+ * Higher-order function to wrap a component function with validation
+ *
+ * Creates a new function that validates the options before calling the
+ * original component. If validation fails, returns the error box HTML
+ * instead of calling the component.
+ *
+ * @param componentFn - The original component function
+ * @param config - Validation configuration
+ * @returns Wrapped function that validates before calling
+ *
+ * @example
+ * ```typescript
+ * const buttonImpl = (text: string, opts: ButtonOptions) => `<button>...</button>`;
+ *
+ * const button = withValidation(buttonImpl, {
+ *   componentName: 'Button',
+ *   schema: ButtonOptionsSchema,
+ * });
+ *
+ * // button() now validates options before rendering
+ * ```
+ */
+export declare function withValidation<TInput, TOptions>(componentFn: (input: TInput, options: TOptions) => string, config: ValidationConfig): (input: TInput, options: unknown) => string;
+//# sourceMappingURL=wrapper.d.ts.map

package/esm/validation/wrapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wrapper.d.ts","sourceRoot":"","sources":["../../../src/validation/wrapper.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,KAAK,CAAC;AAOrC;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,4CAA4C;IAC5C,aAAa,EAAE,MAAM,CAAC;IACtB,qCAAqC;IACrC,MAAM,EAAE,SAAS,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,MAAM,gBAAgB,CAAC,CAAC,IAAI;IAAE,OAAO,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,CAAC,CAAA;CAAE,GAAG;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAiBjG;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,gBAAgB,GAAG,gBAAgB,CAAC,CAAC,CAAC,CAiBlG;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,QAAQ,EAC7C,WAAW,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,KAAK,MAAM,EACzD,MAAM,EAAE,gBAAgB,GACvB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,KAAK,MAAM,CAU7C"}

package/esm/web-components/core/attribute-parser.d.ts

@@ -0,0 +1,82 @@
+/**
+ * @file attribute-parser.ts
+ * @description Attribute parsing utilities for FrontMCP Web Components.
+ *
+ * Converts HTML attributes to typed options for component rendering.
+ * Handles boolean attributes and kebab-to-camel case conversion.
+ *
+ * @example Attribute parsing
+ * ```typescript
+ * // variant="primary" -> { variant: 'primary' }
+ * // disabled -> { disabled: true }
+ * // disabled="false" -> { disabled: false }
+ * ```
+ *
+ * @module @frontmcp/ui/web-components/core/attribute-parser
+ */
+import type { ZodSchema } from 'zod';
+/**
+ * Result of parsing an attribute value
+ */
+export interface ParsedAttribute {
+    /** The option key (camelCase) */
+    key: string | null;
+    /** The parsed value */
+    value: unknown;
+    /** Whether this is a data attribute */
+    isData?: boolean;
+}
+/**
+ * Parse an HTML attribute into a typed option value.
+ *
+ * Attribute naming conventions:
+ * - Simple: `variant="primary"` -> `{ variant: 'primary' }`
+ * - Boolean: `disabled` -> `{ disabled: true }`
+ * - Boolean false: `disabled="false"` -> `{ disabled: false }`
+ * - Data: `data-foo="bar"` -> `{ data: { foo: 'bar' } }`
+ *
+ * @param attrName - The attribute name (kebab-case)
+ * @param value - The attribute value (null for boolean attributes)
+ * @returns Parsed attribute with key and typed value
+ */
+export declare function parseAttributeValue(attrName: string, value: string | null): ParsedAttribute;
+/**
+ * Convert kebab-case to camelCase.
+ *
+ * @param str - Kebab-case string
+ * @returns camelCase string
+ *
+ * @example
+ * kebabToCamel('full-width') // 'fullWidth'
+ * kebabToCamel('icon-before') // 'iconBefore'
+ */
+export declare function kebabToCamel(str: string): string;
+/**
+ * Convert camelCase to kebab-case.
+ *
+ * @param str - camelCase string
+ * @returns kebab-case string
+ *
+ * @example
+ * camelToKebab('fullWidth') // 'full-width'
+ * camelToKebab('iconBefore') // 'icon-before'
+ */
+export declare function camelToKebab(str: string): string;
+/**
+ * Extract observable attribute names from a Zod schema.
+ *
+ * @param schema - Zod schema to extract keys from
+ * @returns Array of kebab-case attribute names
+ */
+export declare function getObservedAttributesFromSchema<T>(schema: ZodSchema<T>): string[];
+/**
+ * Merge a parsed attribute into an options object.
+ *
+ * Handles nested objects for data attributes.
+ *
+ * @param options - Current options object
+ * @param parsed - Parsed attribute result
+ * @returns Updated options object
+ */
+export declare function mergeAttributeIntoOptions<T>(options: Partial<T>, parsed: ParsedAttribute): Partial<T>;
+//# sourceMappingURL=attribute-parser.d.ts.map

package/esm/web-components/core/attribute-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attribute-parser.d.ts","sourceRoot":"","sources":["../../../../src/web-components/core/attribute-parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,KAAK,CAAC;AAErC;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,iCAAiC;IACjC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,uBAAuB;IACvB,KAAK,EAAE,OAAO,CAAC;IACf,uCAAuC;IACvC,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,eAAe,CAiD3F;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED;;;;;GAKG;AACH,wBAAgB,+BAA+B,CAAC,CAAC,EAAE,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,MAAM,EAAE,CAkBjF;AAED;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,CAAC,CAAC,CAkBrG"}

package/esm/web-components/core/base-element.d.ts

@@ -0,0 +1,197 @@
+/**
+ * @file base-element.ts
+ * @description Base class for all FrontMCP Web Components.
+ *
+ * Provides a foundation for creating Custom Elements with:
+ * - Zod schema validation
+ * - Attribute-to-option mapping
+ * - Property setters for React/Vue compatibility
+ * - Batched rendering via queueMicrotask
+ * - Light DOM (no Shadow DOM) for Tailwind compatibility
+ *
+ * @example Creating a custom element
+ * ```typescript
+ * import { FmcpElement } from '@frontmcp/ui/web-components';
+ * import { ButtonOptionsSchema, type ButtonOptions } from '@frontmcp/ui/components';
+ * import { button } from '@frontmcp/ui/components';
+ *
+ * class FmcpButton extends FmcpElement<ButtonOptions> {
+ *   protected readonly config = {
+ *     name: 'button',
+ *     schema: ButtonOptionsSchema,
+ *     defaults: { variant: 'primary', size: 'md' },
+ *   };
+ *
+ *   static get observedAttributes() {
+ *     return getObservedAttributesFromSchema(ButtonOptionsSchema);
+ *   }
+ *
+ *   protected renderHtml(options: ButtonOptions, content: string): string {
+ *     return button(content, options);
+ *   }
+ * }
+ *
+ * customElements.define('fmcp-button', FmcpButton);
+ * ```
+ *
+ * @module @frontmcp/ui/web-components/core/base-element
+ */
+import type { ZodSchema } from 'zod';
+declare const HTMLElementBase: {
+    new (): HTMLElement;
+    prototype: HTMLElement;
+};
+/**
+ * Configuration for FmcpElement subclasses
+ */
+export interface FmcpElementConfig<TOptions> {
+    /** Component name (used in error messages) */
+    name: string;
+    /** Zod schema for validation */
+    schema: ZodSchema<TOptions>;
+    /** Default option values */
+    defaults?: Partial<TOptions>;
+}
+/**
+ * Custom event detail for fmcp:render event
+ */
+export interface FmcpRenderEventDetail<TOptions = unknown> {
+    options: TOptions;
+}
+/**
+ * Base class for all FrontMCP Web Components.
+ *
+ * Key features:
+ * - **Light DOM**: Renders directly to innerHTML (no Shadow DOM)
+ * - **Attribute Parsing**: Converts HTML attributes to typed options
+ * - **Property Setters**: React/Vue can set properties directly
+ * - **Zod Validation**: Invalid options render error box
+ * - **Batched Rendering**: Multiple changes batch via queueMicrotask
+ *
+ * @typeParam TOptions - The component's options type (from Zod schema)
+ *
+ * @example Usage in HTML
+ * ```html
+ * <fmcp-button variant="primary" disabled>
+ *   Click Me
+ * </fmcp-button>
+ * ```
+ *
+ * @example Usage in React
+ * ```tsx
+ * <fmcp-button
+ *   variant="primary"
+ *   onClick={handleClick}
+ * >
+ *   Click Me
+ * </fmcp-button>
+ * ```
+ */
+export declare abstract class FmcpElement<TOptions> extends HTMLElementBase {
+    /**
+     * Configuration provided by subclass.
+     * Must include component name, Zod schema, and optional defaults.
+     */
+    protected abstract readonly config: FmcpElementConfig<TOptions>;
+    /** Internal options state */
+    protected _options: Partial<TOptions>;
+    /** Content passed as children (captured on connect) */
+    protected _content: string;
+    /** Whether component has been connected to DOM */
+    private _connected;
+    /** Whether a render is pending (for batching) */
+    private _pendingRender;
+    /** Whether initial render has completed */
+    private _initialRenderComplete;
+    /**
+     * Called when element is added to DOM.
+     * Captures content, parses attributes, and renders.
+     *
+     * Supports SSR hydration via `data-ssr` attribute:
+     * - If `data-ssr` is present, content was pre-rendered by server
+     * - Web component adopts existing content without re-rendering
+     * - This enables progressive enhancement for LLM platforms
+     */
+    connectedCallback(): void;
+    /**
+     * Called when element is removed from DOM.
+     */
+    disconnectedCallback(): void;
+    /**
+     * Called when an observed attribute changes.
+     * Updates options and schedules re-render.
+     */
+    attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
+    /**
+     * Set all options at once (React pattern).
+     *
+     * @example
+     * ```typescript
+     * const el = document.querySelector('fmcp-button');
+     * el.options = { variant: 'danger', size: 'lg' };
+     * ```
+     */
+    set options(value: Partial<TOptions>);
+    /**
+     * Get current options.
+     */
+    get options(): Partial<TOptions>;
+    /**
+     * Parse all current attributes into options.
+     */
+    private _parseAttributes;
+    /**
+     * Update a single option from an attribute change.
+     */
+    private _updateOptionFromAttribute;
+    /**
+     * Schedule a render on next microtask.
+     * Batches multiple attribute/property changes.
+     */
+    protected _scheduleRender(): void;
+    /**
+     * Perform the actual render.
+     * Validates options and updates innerHTML.
+     */
+    private _render;
+    /**
+     * Generate HTML for the component.
+     * Subclasses must implement this to render their specific HTML.
+     *
+     * @param options - Validated options
+     * @param content - Original innerHTML content
+     * @returns HTML string to render
+     */
+    protected abstract renderHtml(options: TOptions, content: string): string;
+    /**
+     * Force an immediate re-render.
+     *
+     * @example
+     * ```typescript
+     * el.options = { loading: true };
+     * el.refresh(); // Force immediate render
+     * ```
+     */
+    refresh(): void;
+    /**
+     * Get the first child element (the actual rendered component).
+     *
+     * @typeParam T - Expected element type
+     * @returns The first child element or null
+     *
+     * @example
+     * ```typescript
+     * const button = el.getInnerElement<HTMLButtonElement>();
+     * button?.focus();
+     * ```
+     */
+    getInnerElement<T extends Element = Element>(): T | null;
+    /**
+     * Update content and re-render.
+     *
+     * @param content - New content string
+     */
+    setContent(content: string): void;
+}
+export {};
+//# sourceMappingURL=base-element.d.ts.map

package/esm/web-components/core/base-element.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-element.d.ts","sourceRoot":"","sources":["../../../../src/web-components/core/base-element.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,KAAK,CAAC;AAOrC,QAAA,MAAM,eAAe;;;CAWoB,CAAC;AAE1C;;GAEG;AACH,MAAM,WAAW,iBAAiB,CAAC,QAAQ;IACzC,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,gCAAgC;IAChC,MAAM,EAAE,SAAS,CAAC,QAAQ,CAAC,CAAC;IAC5B,4BAA4B;IAC5B,QAAQ,CAAC,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC;CAC9B;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB,CAAC,QAAQ,GAAG,OAAO;IACvD,OAAO,EAAE,QAAQ,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,8BAAsB,WAAW,CAAC,QAAQ,CAAE,SAAQ,eAAe;IACjE;;;OAGG;IACH,SAAS,CAAC,QAAQ,CAAC,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC,QAAQ,CAAC,CAAC;IAEhE,6BAA6B;IAC7B,SAAS,CAAC,QAAQ,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAM;IAE3C,uDAAuD;IACvD,SAAS,CAAC,QAAQ,SAAM;IAExB,kDAAkD;IAClD,OAAO,CAAC,UAAU,CAAS;IAE3B,iDAAiD;IACjD,OAAO,CAAC,cAAc,CAAS;IAE/B,2CAA2C;IAC3C,OAAO,CAAC,sBAAsB,CAAS;IAMvC;;;;;;;;OAQG;IACH,iBAAiB,IAAI,IAAI;IA8BzB;;OAEG;IACH,oBAAoB,IAAI,IAAI;IAI5B;;;OAGG;IACH,wBAAwB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI;IAe9F;;;;;;;;OAQG;IACH,IAAI,OAAO,CAAC,KAAK,EAAE,OAAO,CAAC,QAAQ,CAAC,EAGnC;IAED;;OAEG;IACH,IAAI,OAAO,IAAI,OAAO,CAAC,QAAQ,CAAC,CAE/B;IAMD;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAMxB;;OAEG;IACH,OAAO,CAAC,0BAA0B;IASlC;;;OAGG;IACH,SAAS,CAAC,eAAe,IAAI,IAAI;IAYjC;;;OAGG;IACH,OAAO,CAAC,OAAO;IAyCf;;;;;;;OAOG;IACH,SAAS,CAAC,QAAQ,CAAC,UAAU,CAAC,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM;IAMzE;;;;;;;;OAQG;IACI,OAAO,IAAI,IAAI;IAMtB;;;;;;;;;;;OAWG;IACI,eAAe,CAAC,CAAC,SAAS,OAAO,GAAG,OAAO,KAAK,CAAC,GAAG,IAAI;IAI/D;;;;OAIG;IACI,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;CAIzC"}

package/esm/web-components/core/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @file core/index.ts
+ * @description Core utilities for FrontMCP Web Components.
+ *
+ * @module @frontmcp/ui/web-components/core
+ */
+export { FmcpElement, type FmcpElementConfig, type FmcpRenderEventDetail } from './base-element';
+export { parseAttributeValue, kebabToCamel, camelToKebab, getObservedAttributesFromSchema, mergeAttributeIntoOptions, type ParsedAttribute, } from './attribute-parser';
+//# sourceMappingURL=index.d.ts.map

package/esm/web-components/core/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/web-components/core/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,WAAW,EAAE,KAAK,iBAAiB,EAAE,KAAK,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AAEjG,OAAO,EACL,mBAAmB,EACnB,YAAY,EACZ,YAAY,EACZ,+BAA+B,EAC/B,yBAAyB,EACzB,KAAK,eAAe,GACrB,MAAM,oBAAoB,CAAC"}

package/esm/web-components/elements/fmcp-alert.d.ts

@@ -0,0 +1,46 @@
+/**
+ * @file fmcp-alert.ts
+ * @description FrontMCP Alert Web Component.
+ *
+ * A custom element wrapper around the alert() HTML function.
+ *
+ * @example Basic usage
+ * ```html
+ * <fmcp-alert variant="success">Operation completed!</fmcp-alert>
+ * <fmcp-alert variant="danger" title="Error">Something went wrong</fmcp-alert>
+ * ```
+ *
+ * @example Dismissible alert
+ * ```html
+ * <fmcp-alert variant="info" dismissible>
+ *   Click X to dismiss
+ * </fmcp-alert>
+ * ```
+ *
+ * @module @frontmcp/ui/web-components/elements/fmcp-alert
+ */
+import { FmcpElement, type FmcpElementConfig } from '../core';
+import { type AlertOptions } from '../../components/alert';
+/**
+ * FmcpAlert Web Component
+ */
+export declare class FmcpAlert extends FmcpElement<AlertOptions> {
+    protected readonly config: FmcpElementConfig<AlertOptions>;
+    static get observedAttributes(): string[];
+    protected renderHtml(options: AlertOptions, content: string): string;
+    set variant(value: AlertOptions['variant']);
+    get variant(): AlertOptions['variant'];
+    set alertTitle(value: string | undefined);
+    get alertTitle(): string | undefined;
+    set showIcon(value: boolean);
+    get showIcon(): boolean;
+    set dismissible(value: boolean);
+    get dismissible(): boolean;
+    set actions(value: string | undefined);
+    get actions(): string | undefined;
+}
+/**
+ * Register the fmcp-alert custom element.
+ */
+export declare function registerFmcpAlert(): void;
+//# sourceMappingURL=fmcp-alert.d.ts.map

package/esm/web-components/elements/fmcp-alert.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fmcp-alert.d.ts","sourceRoot":"","sources":["../../../../src/web-components/elements/fmcp-alert.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,WAAW,EAAE,KAAK,iBAAiB,EAAmC,MAAM,SAAS,CAAC;AAC/F,OAAO,EAAS,KAAK,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAGlE;;GAEG;AACH,qBAAa,SAAU,SAAQ,WAAW,CAAC,YAAY,CAAC;IACtD,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC,YAAY,CAAC,CAOxD;IAEF,MAAM,KAAK,kBAAkB,IAAI,MAAM,EAAE,CAExC;IAED,SAAS,CAAC,UAAU,CAAC,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM;IAKpE,IAAI,OAAO,CAAC,KAAK,EAAE,YAAY,CAAC,SAAS,CAAC,EAGzC;IACD,IAAI,OAAO,IAAI,YAAY,CAAC,SAAS,CAAC,CAErC;IAED,IAAI,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAGvC;IACD,IAAI,UAAU,IAAI,MAAM,GAAG,SAAS,CAEnC;IAED,IAAI,QAAQ,CAAC,KAAK,EAAE,OAAO,EAG1B;IACD,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED,IAAI,WAAW,CAAC,KAAK,EAAE,OAAO,EAG7B;IACD,IAAI,WAAW,IAAI,OAAO,CAEzB;IAED,IAAI,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAGpC;IACD,IAAI,OAAO,IAAI,MAAM,GAAG,SAAS,CAEhC;CACF;AAED;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,IAAI,CAIxC"}

package/esm/web-components/elements/fmcp-badge.d.ts

@@ -0,0 +1,47 @@
+/**
+ * @file fmcp-badge.ts
+ * @description FrontMCP Badge Web Component.
+ *
+ * A custom element wrapper around the badge() HTML function.
+ *
+ * @example Basic usage
+ * ```html
+ * <fmcp-badge>Default</fmcp-badge>
+ * <fmcp-badge variant="success">Active</fmcp-badge>
+ * <fmcp-badge variant="danger" pill>Error</fmcp-badge>
+ * ```
+ *
+ * @example Removable badge
+ * ```html
+ * <fmcp-badge removable>Tag</fmcp-badge>
+ * ```
+ *
+ * @module @frontmcp/ui/web-components/elements/fmcp-badge
+ */
+import { FmcpElement, type FmcpElementConfig } from '../core';
+import { type BadgeOptions } from '../../components/badge';
+/**
+ * FmcpBadge Web Component
+ */
+export declare class FmcpBadge extends FmcpElement<BadgeOptions> {
+    protected readonly config: FmcpElementConfig<BadgeOptions>;
+    static get observedAttributes(): string[];
+    protected renderHtml(options: BadgeOptions, content: string): string;
+    set variant(value: BadgeOptions['variant']);
+    get variant(): BadgeOptions['variant'];
+    set size(value: BadgeOptions['size']);
+    get size(): BadgeOptions['size'];
+    set pill(value: boolean);
+    get pill(): boolean;
+    set dot(value: boolean);
+    get dot(): boolean;
+    set removable(value: boolean);
+    get removable(): boolean;
+    set icon(value: string | undefined);
+    get icon(): string | undefined;
+}
+/**
+ * Register the fmcp-badge custom element.
+ */
+export declare function registerFmcpBadge(): void;
+//# sourceMappingURL=fmcp-badge.d.ts.map

package/esm/web-components/elements/fmcp-badge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fmcp-badge.d.ts","sourceRoot":"","sources":["../../../../src/web-components/elements/fmcp-badge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,WAAW,EAAE,KAAK,iBAAiB,EAAmC,MAAM,SAAS,CAAC;AAC/F,OAAO,EAAS,KAAK,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAGlE;;GAEG;AACH,qBAAa,SAAU,SAAQ,WAAW,CAAC,YAAY,CAAC;IACtD,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC,YAAY,CAAC,CAOxD;IAEF,MAAM,KAAK,kBAAkB,IAAI,MAAM,EAAE,CAExC;IAED,SAAS,CAAC,UAAU,CAAC,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM;IAKpE,IAAI,OAAO,CAAC,KAAK,EAAE,YAAY,CAAC,SAAS,CAAC,EAGzC;IACD,IAAI,OAAO,IAAI,YAAY,CAAC,SAAS,CAAC,CAErC;IAED,IAAI,IAAI,CAAC,KAAK,EAAE,YAAY,CAAC,MAAM,CAAC,EAGnC;IACD,IAAI,IAAI,IAAI,YAAY,CAAC,MAAM,CAAC,CAE/B;IAED,IAAI,IAAI,CAAC,KAAK,EAAE,OAAO,EAGtB;IACD,IAAI,IAAI,IAAI,OAAO,CAElB;IAED,IAAI,GAAG,CAAC,KAAK,EAAE,OAAO,EAGrB;IACD,IAAI,GAAG,IAAI,OAAO,CAEjB;IAED,IAAI,SAAS,CAAC,KAAK,EAAE,OAAO,EAG3B;IACD,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED,IAAI,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAGjC;IACD,IAAI,IAAI,IAAI,MAAM,GAAG,SAAS,CAE7B;CACF;AAED;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,IAAI,CAIxC"}