@frontmcp/ui 0.5.0

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

@@ -0,0 +1,85 @@
+/**
+ * @file attribute-parser.ts
+ * @description Attribute parsing utilities for FrontMCP Web Components.
+ *
+ * Converts HTML attributes to typed options for component rendering.
+ * Handles boolean attributes, HTMX attributes, and kebab-to-camel case conversion.
+ *
+ * @example Attribute parsing
+ * ```typescript
+ * // variant="primary" -> { variant: 'primary' }
+ * // disabled -> { disabled: true }
+ * // disabled="false" -> { disabled: false }
+ * // hx-get="/api" -> { htmx: { get: '/api' } }
+ * ```
+ *
+ * @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 nested htmx option */
+    isHtmx?: boolean;
+    /** 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 }`
+ * - HTMX: `hx-get="/api"` -> `{ htmx: { get: '/api' } }`
+ * - 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 htmx and 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>;

package/src/web-components/core/attribute-parser.js

@@ -0,0 +1,189 @@
+"use strict";
+/**
+ * @file attribute-parser.ts
+ * @description Attribute parsing utilities for FrontMCP Web Components.
+ *
+ * Converts HTML attributes to typed options for component rendering.
+ * Handles boolean attributes, HTMX attributes, and kebab-to-camel case conversion.
+ *
+ * @example Attribute parsing
+ * ```typescript
+ * // variant="primary" -> { variant: 'primary' }
+ * // disabled -> { disabled: true }
+ * // disabled="false" -> { disabled: false }
+ * // hx-get="/api" -> { htmx: { get: '/api' } }
+ * ```
+ *
+ * @module @frontmcp/ui/web-components/core/attribute-parser
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseAttributeValue = parseAttributeValue;
+exports.kebabToCamel = kebabToCamel;
+exports.camelToKebab = camelToKebab;
+exports.getObservedAttributesFromSchema = getObservedAttributesFromSchema;
+exports.mergeAttributeIntoOptions = mergeAttributeIntoOptions;
+/**
+ * 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 }`
+ * - HTMX: `hx-get="/api"` -> `{ htmx: { get: '/api' } }`
+ * - 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
+ */
+function parseAttributeValue(attrName, value) {
+    // Skip internal fmcp attributes
+    if (attrName.startsWith('data-fmcp-')) {
+        return { key: null, value: undefined };
+    }
+    // Handle HTMX attributes (hx-* -> htmx.*)
+    if (attrName.startsWith('hx-')) {
+        const htmxKey = attrName.slice(3); // Remove 'hx-'
+        return {
+            key: htmxKey,
+            value: value ?? '',
+            isHtmx: true,
+        };
+    }
+    // Handle data attributes (data-* -> data.*)
+    if (attrName.startsWith('data-')) {
+        const dataKey = attrName.slice(5); // Remove 'data-'
+        return {
+            key: dataKey,
+            value: value ?? '',
+            isData: true,
+        };
+    }
+    // Convert kebab-case to camelCase
+    const camelName = kebabToCamel(attrName);
+    // Handle boolean attributes (presence = true)
+    if (value === null || value === '') {
+        return { key: camelName, value: true };
+    }
+    // Handle explicit boolean strings
+    if (value === 'true') {
+        return { key: camelName, value: true };
+    }
+    if (value === 'false') {
+        return { key: camelName, value: false };
+    }
+    // Handle numeric values
+    const numValue = Number(value);
+    if (!isNaN(numValue) && value.trim() !== '') {
+        return { key: camelName, value: numValue };
+    }
+    // Handle JSON values (for complex objects)
+    if (value.startsWith('{') || value.startsWith('[')) {
+        try {
+            return { key: camelName, value: JSON.parse(value) };
+        }
+        catch {
+            // Not valid JSON, treat as string
+        }
+    }
+    // Default: string value
+    return { key: camelName, value };
+}
+/**
+ * Convert kebab-case to camelCase.
+ *
+ * @param str - Kebab-case string
+ * @returns camelCase string
+ *
+ * @example
+ * kebabToCamel('full-width') // 'fullWidth'
+ * kebabToCamel('icon-before') // 'iconBefore'
+ */
+function kebabToCamel(str) {
+    return str.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+}
+/**
+ * Convert camelCase to kebab-case.
+ *
+ * @param str - camelCase string
+ * @returns kebab-case string
+ *
+ * @example
+ * camelToKebab('fullWidth') // 'full-width'
+ * camelToKebab('iconBefore') // 'icon-before'
+ */
+function camelToKebab(str) {
+    return str.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`);
+}
+/**
+ * Extract observable attribute names from a Zod schema.
+ *
+ * @param schema - Zod schema to extract keys from
+ * @returns Array of kebab-case attribute names
+ */
+function getObservedAttributesFromSchema(schema) {
+    const attributes = [];
+    // Extract keys from schema shape (Zod object schemas have a shape property)
+    const schemaAny = schema;
+    if (schemaAny.shape) {
+        for (const key of Object.keys(schemaAny.shape)) {
+            // Convert camelCase keys to kebab-case attributes
+            attributes.push(camelToKebab(key));
+        }
+    }
+    // Always include common attributes
+    const commonAttrs = ['class', 'id', 'style'];
+    attributes.push(...commonAttrs);
+    // Include HTMX attributes
+    const htmxAttrs = [
+        'hx-get',
+        'hx-post',
+        'hx-put',
+        'hx-delete',
+        'hx-patch',
+        'hx-target',
+        'hx-swap',
+        'hx-trigger',
+        'hx-confirm',
+        'hx-indicator',
+        'hx-push-url',
+        'hx-select',
+        'hx-vals',
+    ];
+    attributes.push(...htmxAttrs);
+    // Deduplicate
+    return [...new Set(attributes)];
+}
+/**
+ * Merge a parsed attribute into an options object.
+ *
+ * Handles nested objects for htmx and data attributes.
+ *
+ * @param options - Current options object
+ * @param parsed - Parsed attribute result
+ * @returns Updated options object
+ */
+function mergeAttributeIntoOptions(options, parsed) {
+    if (parsed.key === null || parsed.value === undefined) {
+        return options;
+    }
+    const result = { ...options };
+    if (parsed.isHtmx) {
+        // Merge into htmx nested object
+        const htmx = result['htmx'] ?? {};
+        htmx[parsed.key] = parsed.value;
+        result['htmx'] = htmx;
+    }
+    else if (parsed.isData) {
+        // Merge into data nested object
+        const data = result['data'] ?? {};
+        data[parsed.key] = String(parsed.value);
+        result['data'] = data;
+    }
+    else {
+        // Direct assignment
+        result[parsed.key] = parsed.value;
+    }
+    return result;
+}
+//# sourceMappingURL=attribute-parser.js.map

package/src/web-components/core/attribute-parser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attribute-parser.js","sourceRoot":"","sources":["../../../../src/web-components/core/attribute-parser.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * @file attribute-parser.ts\n * @description Attribute parsing utilities for FrontMCP Web Components.\n *\n * Converts HTML attributes to typed options for component rendering.\n * Handles boolean attributes, HTMX attributes, and kebab-to-camel case conversion.\n *\n * @example Attribute parsing\n * ```typescript\n * // variant=\"primary\" -> { variant: 'primary' }\n * // disabled -> { disabled: true }\n * // disabled=\"false\" -> { disabled: false }\n * // hx-get=\"/api\" -> { htmx: { get: '/api' } }\n * ```\n *\n * @module @frontmcp/ui/web-components/core/attribute-parser\n */\n\nimport type { ZodSchema } from 'zod';\n\n/**\n * Result of parsing an attribute value\n */\nexport interface ParsedAttribute {\n  /** The option key (camelCase) */\n  key: string | null;\n  /** The parsed value */\n  value: unknown;\n  /** Whether this is a nested htmx option */\n  isHtmx?: boolean;\n  /** Whether this is a data attribute */\n  isData?: boolean;\n}\n\n/**\n * Parse an HTML attribute into a typed option value.\n *\n * Attribute naming conventions:\n * - Simple: `variant=\"primary\"` -> `{ variant: 'primary' }`\n * - Boolean: `disabled` -> `{ disabled: true }`\n * - Boolean false: `disabled=\"false\"` -> `{ disabled: false }`\n * - HTMX: `hx-get=\"/api\"` -> `{ htmx: { get: '/api' } }`\n * - Data: `data-foo=\"bar\"` -> `{ data: { foo: 'bar' } }`\n *\n * @param attrName - The attribute name (kebab-case)\n * @param value - The attribute value (null for boolean attributes)\n * @returns Parsed attribute with key and typed value\n */\nexport function parseAttributeValue(attrName: string, value: string | null): ParsedAttribute {\n  // Skip internal fmcp attributes\n  if (attrName.startsWith('data-fmcp-')) {\n    return { key: null, value: undefined };\n  }\n\n  // Handle HTMX attributes (hx-* -> htmx.*)\n  if (attrName.startsWith('hx-')) {\n    const htmxKey = attrName.slice(3); // Remove 'hx-'\n    return {\n      key: htmxKey,\n      value: value ?? '',\n      isHtmx: true,\n    };\n  }\n\n  // Handle data attributes (data-* -> data.*)\n  if (attrName.startsWith('data-')) {\n    const dataKey = attrName.slice(5); // Remove 'data-'\n    return {\n      key: dataKey,\n      value: value ?? '',\n      isData: true,\n    };\n  }\n\n  // Convert kebab-case to camelCase\n  const camelName = kebabToCamel(attrName);\n\n  // Handle boolean attributes (presence = true)\n  if (value === null || value === '') {\n    return { key: camelName, value: true };\n  }\n\n  // Handle explicit boolean strings\n  if (value === 'true') {\n    return { key: camelName, value: true };\n  }\n  if (value === 'false') {\n    return { key: camelName, value: false };\n  }\n\n  // Handle numeric values\n  const numValue = Number(value);\n  if (!isNaN(numValue) && value.trim() !== '') {\n    return { key: camelName, value: numValue };\n  }\n\n  // Handle JSON values (for complex objects)\n  if (value.startsWith('{') || value.startsWith('[')) {\n    try {\n      return { key: camelName, value: JSON.parse(value) };\n    } catch {\n      // Not valid JSON, treat as string\n    }\n  }\n\n  // Default: string value\n  return { key: camelName, value };\n}\n\n/**\n * Convert kebab-case to camelCase.\n *\n * @param str - Kebab-case string\n * @returns camelCase string\n *\n * @example\n * kebabToCamel('full-width') // 'fullWidth'\n * kebabToCamel('icon-before') // 'iconBefore'\n */\nexport function kebabToCamel(str: string): string {\n  return str.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());\n}\n\n/**\n * Convert camelCase to kebab-case.\n *\n * @param str - camelCase string\n * @returns kebab-case string\n *\n * @example\n * camelToKebab('fullWidth') // 'full-width'\n * camelToKebab('iconBefore') // 'icon-before'\n */\nexport function camelToKebab(str: string): string {\n  return str.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`);\n}\n\n/**\n * Extract observable attribute names from a Zod schema.\n *\n * @param schema - Zod schema to extract keys from\n * @returns Array of kebab-case attribute names\n */\nexport function getObservedAttributesFromSchema<T>(schema: ZodSchema<T>): string[] {\n  const attributes: string[] = [];\n\n  // Extract keys from schema shape (Zod object schemas have a shape property)\n  const schemaAny = schema as { shape?: Record<string, unknown> };\n  if (schemaAny.shape) {\n    for (const key of Object.keys(schemaAny.shape)) {\n      // Convert camelCase keys to kebab-case attributes\n      attributes.push(camelToKebab(key));\n    }\n  }\n\n  // Always include common attributes\n  const commonAttrs = ['class', 'id', 'style'];\n  attributes.push(...commonAttrs);\n\n  // Include HTMX attributes\n  const htmxAttrs = [\n    'hx-get',\n    'hx-post',\n    'hx-put',\n    'hx-delete',\n    'hx-patch',\n    'hx-target',\n    'hx-swap',\n    'hx-trigger',\n    'hx-confirm',\n    'hx-indicator',\n    'hx-push-url',\n    'hx-select',\n    'hx-vals',\n  ];\n  attributes.push(...htmxAttrs);\n\n  // Deduplicate\n  return [...new Set(attributes)];\n}\n\n/**\n * Merge a parsed attribute into an options object.\n *\n * Handles nested objects for htmx and data attributes.\n *\n * @param options - Current options object\n * @param parsed - Parsed attribute result\n * @returns Updated options object\n */\nexport function mergeAttributeIntoOptions<T>(options: Partial<T>, parsed: ParsedAttribute): Partial<T> {\n  if (parsed.key === null || parsed.value === undefined) {\n    return options;\n  }\n\n  const result = { ...options } as Record<string, unknown>;\n\n  if (parsed.isHtmx) {\n    // Merge into htmx nested object\n    const htmx = (result['htmx'] as Record<string, unknown>) ?? {};\n    htmx[parsed.key] = parsed.value;\n    result['htmx'] = htmx;\n  } else if (parsed.isData) {\n    // Merge into data nested object\n    const data = (result['data'] as Record<string, string>) ?? {};\n    data[parsed.key] = String(parsed.value);\n    result['data'] = data;\n  } else {\n    // Direct assignment\n    result[parsed.key] = parsed.value;\n  }\n\n  return result as Partial<T>;\n}\n"]}

package/src/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
+ * - **HTMX Support**: hx-* attributes pass through to inner elements
+ *
+ * @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 {};