ezfw-core 1.0.40 → 1.0.41

package/islands/StaticHtmlRenderer.d.ts

@@ -66,9 +66,9 @@ export declare class StaticHtmlRenderer {
     /**
      * Render an island as a placeholder with hydration data
      *
-     * Islands are NOT pre-rendered because they use reactive state,
-     * computed properties, and methods that require proper `this` binding.
-     * Instead, we render a placeholder that will be hydrated on the client.
+     * Islands are pre-rendered as static HTML so search engines can index the content.
+     * The client will then hydrate to add interactivity (event handlers, reactive state).
+     * This approach gives us the best of both worlds: SEO + interactivity.
      */
     private renderIslandPlaceholder;
     /**

package/islands/StaticHtmlRenderer.js

@@ -0,0 +1,347 @@
+/**
+ * Ez Islands - Static HTML Renderer
+ *
+ * Renders component trees to HTML strings for SSR/SSG.
+ * Static components are fully rendered to HTML.
+ * Islands are rendered as placeholders with hydration data.
+ */
+import { analyzer } from './analyzer.js';
+// HTML void elements (self-closing)
+const VOID_ELEMENTS = new Set([
+    'area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input',
+    'link', 'meta', 'param', 'source', 'track', 'wbr'
+]);
+// Attributes that should be rendered as boolean
+const BOOLEAN_ATTRS = new Set([
+    'checked', 'disabled', 'readonly', 'required', 'autofocus',
+    'multiple', 'hidden', 'selected', 'open', 'novalidate'
+]);
+// Attributes to skip (handled specially or internal)
+const SKIP_ATTRS = new Set([
+    'eztype', 'items', 'template', 'props', 'bind', 'controller',
+    'load', 'state', 'island', 'static', 'onMount', 'onVisible',
+    'onDestroy', 'css', '_ezAfterRender', '_styleModule'
+]);
+// Event attributes to skip in static render
+const EVENT_ATTRS = new Set([
+    'onClick', 'onChange', 'onInput', 'onSubmit', 'onFocus', 'onBlur',
+    'onMouseEnter', 'onMouseLeave', 'onKeyDown', 'onKeyUp'
+]);
+let islandIdCounter = 0;
+/**
+ * Main static renderer class
+ */
+export class StaticHtmlRenderer {
+    analyzer;
+    constructor() {
+        this.analyzer = analyzer;
+    }
+    /**
+     * Render a page component to full HTML document
+     */
+    async renderPage(pageName, pageDefinition, context = {}) {
+        const ctx = {
+            registry: context.registry || new Map(),
+            styles: context.styles || new Set(),
+            islands: context.islands || [],
+            props: context.props || {},
+            serverData: context.serverData || {}
+        };
+        // Register the page component
+        ctx.registry.set(pageName, pageDefinition);
+        // Execute server-side load() if present
+        if (pageDefinition.load) {
+            const loadContext = {
+                params: ctx.props || {},
+                url: '/'
+            };
+            ctx.serverData = await pageDefinition.load(loadContext);
+        }
+        // Render the component tree
+        const bodyHtml = await this.renderComponent(pageName, ctx, ctx.serverData);
+        // Note: Hydration script is generated by ViteIslandsPlugin
+        // The plugin reads ctx.islands and generates the script
+        return bodyHtml;
+    }
+    /**
+     * Render a single component to HTML string
+     */
+    async renderComponent(name, ctx, props = {}) {
+        const definition = ctx.registry.get(name);
+        if (!definition) {
+            // Try to render as native HTML element
+            return this.renderNativeElement(name, props, ctx);
+        }
+        // Analyze the component
+        const analysis = this.analyzer.analyze(name, definition);
+        if (analysis.type === 'island') {
+            // Render as island placeholder
+            return this.renderIslandPlaceholder(name, definition, props, ctx);
+        }
+        // Render as static HTML
+        return this.renderStaticComponent(name, definition, props, ctx);
+    }
+    /**
+     * Render a static component to HTML
+     */
+    async renderStaticComponent(name, definition, props, ctx) {
+        let config;
+        // Get component config from template or items
+        if (definition.template) {
+            // Get controller state for SSR
+            let mockCtrl = null;
+            // Try to get controller from ez shim (set up by ViteIslandsPlugin)
+            const ez = globalThis.ez;
+            if (definition.controller && ez && ez.getControllerSync) {
+                mockCtrl = ez.getControllerSync(definition.controller);
+            }
+            else if (definition.state) {
+                // Fallback to component's own state
+                mockCtrl = { state: { ...definition.state } };
+            }
+            config = definition.template(props, mockCtrl, mockCtrl ? mockCtrl.state : null);
+        }
+        else if (definition.items) {
+            config = { items: definition.items };
+        }
+        else {
+            config = {};
+        }
+        // Merge definition-level properties
+        if (definition.cls) {
+            config.cls = this.mergeCls(config.cls, definition.cls);
+        }
+        if (definition.style) {
+            config.style = { ...definition.style, ...(config.style || {}) };
+        }
+        // Render the config tree
+        return this.renderConfig(config, ctx);
+    }
+    /**
+     * Render an island as a placeholder with hydration data
+     *
+     * Islands are pre-rendered as static HTML so search engines can index the content.
+     * The client will then hydrate to add interactivity (event handlers, reactive state).
+     * This approach gives us the best of both worlds: SEO + interactivity.
+     */
+    async renderIslandPlaceholder(name, definition, props, ctx) {
+        const islandId = `ez-island-${++islandIdCounter}`;
+        // Store island data for hydration
+        const islandData = {
+            id: islandId,
+            component: name,
+            props: this.serializableProps(props)
+        };
+        ctx.islands.push(islandData);
+        // Render the full static content (for SEO)
+        const staticContent = await this.renderStaticComponent(name, definition, props, ctx);
+        // Wrap in island container with data attributes for hydration
+        const propsJson = this.escapeAttr(JSON.stringify(islandData.props));
+        return `<div data-ez-island="${name}" data-ez-island-id="${islandId}" data-ez-props="${propsJson}">${staticContent}</div>`;
+    }
+    /**
+     * Render a config object to HTML
+     */
+    async renderConfig(config, ctx) {
+        if (!config)
+            return '';
+        const eztype = config.eztype || 'div';
+        // Check if it's a registered component
+        if (ctx.registry.has(eztype)) {
+            return this.renderComponent(eztype, ctx, config.props || {});
+        }
+        // Check if eztype starts with uppercase (custom component)
+        if (eztype[0] === eztype[0].toUpperCase() && eztype !== 'EzComponent') {
+            // Try to find in registry, otherwise treat as unknown
+            if (!ctx.registry.has(eztype)) {
+                console.warn(`Unknown component: ${eztype}`);
+                return `<!-- Unknown: ${eztype} -->`;
+            }
+        }
+        // Render as native HTML element
+        return this.renderNativeElement(eztype, config, ctx);
+    }
+    /**
+     * Render a native HTML element
+     */
+    async renderNativeElement(tag, config, ctx) {
+        // Handle EzComponent as div
+        const actualTag = tag === 'EzComponent' ? 'div' : tag.toLowerCase();
+        // Build attributes
+        const attrs = this.buildAttributes(config);
+        // Handle void elements
+        if (VOID_ELEMENTS.has(actualTag)) {
+            return `<${actualTag}${attrs}>`;
+        }
+        // Build children
+        let children = '';
+        if (config.text) {
+            children = this.escapeHtml(config.text);
+        }
+        else if (config.html) {
+            children = config.html; // Raw HTML, use with caution
+        }
+        else if (config.items && Array.isArray(config.items)) {
+            const childHtmls = await Promise.all(config.items
+                .filter(item => item != null)
+                .map(item => this.renderConfig(item, ctx)));
+            children = childHtmls.join('');
+        }
+        return `<${actualTag}${attrs}>${children}</${actualTag}>`;
+    }
+    /**
+     * Build HTML attributes string from config
+     */
+    buildAttributes(config) {
+        const parts = [];
+        // Handle class
+        if (config.cls) {
+            const classes = Array.isArray(config.cls)
+                ? config.cls.join(' ')
+                : config.cls;
+            if (classes) {
+                parts.push(`class="${this.escapeAttr(classes)}"`);
+            }
+        }
+        // Handle style
+        if (config.style && typeof config.style === 'object') {
+            const styleStr = Object.entries(config.style)
+                .map(([key, value]) => {
+                // Convert camelCase to kebab-case
+                const cssKey = key.replace(/([A-Z])/g, '-$1').toLowerCase();
+                return `${cssKey}: ${value}`;
+            })
+                .join('; ');
+            if (styleStr) {
+                parts.push(`style="${this.escapeAttr(styleStr)}"`);
+            }
+        }
+        // Handle other attributes
+        for (const [key, value] of Object.entries(config)) {
+            // Skip special attributes
+            if (SKIP_ATTRS.has(key) || EVENT_ATTRS.has(key))
+                continue;
+            if (key === 'cls' || key === 'style' || key === 'text' || key === 'html')
+                continue;
+            // Handle boolean attributes
+            if (BOOLEAN_ATTRS.has(key)) {
+                if (value) {
+                    parts.push(key);
+                }
+                continue;
+            }
+            // Handle regular attributes
+            if (value !== undefined && value !== null && typeof value !== 'function') {
+                // Convert camelCase to kebab-case for certain attrs
+                const attrName = this.toAttrName(key);
+                parts.push(`${attrName}="${this.escapeAttr(String(value))}"`);
+            }
+        }
+        return parts.length > 0 ? ' ' + parts.join(' ') : '';
+    }
+    /**
+     * Generate hydration script for islands
+     */
+    generateHydrationScript(islands) {
+        if (islands.length === 0)
+            return '';
+        const islandsJson = JSON.stringify(islands);
+        return `
+<script type="module">
+import { hydrateIslands } from '/ez/islands/runtime.js';
+window.__EZ_ISLANDS__ = ${islandsJson};
+hydrateIslands(window.__EZ_ISLANDS__);
+</script>`;
+    }
+    /**
+     * Convert camelCase to kebab-case for attribute names
+     */
+    toAttrName(key) {
+        // Special cases
+        if (key === 'className')
+            return 'class';
+        if (key === 'htmlFor')
+            return 'for';
+        if (key === 'tabIndex')
+            return 'tabindex';
+        if (key === 'maxLength')
+            return 'maxlength';
+        if (key === 'minLength')
+            return 'minlength';
+        // Keep data-* and aria-* as-is
+        if (key.startsWith('data') || key.startsWith('aria')) {
+            return key.replace(/([A-Z])/g, '-$1').toLowerCase();
+        }
+        return key.toLowerCase();
+    }
+    /**
+     * Escape HTML special characters
+     */
+    escapeHtml(str) {
+        return str
+            .replace(/&/g, '&amp;')
+            .replace(/</g, '&lt;')
+            .replace(/>/g, '&gt;');
+    }
+    /**
+     * Escape attribute value
+     */
+    escapeAttr(str) {
+        return str
+            .replace(/&/g, '&amp;')
+            .replace(/"/g, '&quot;')
+            .replace(/'/g, '&#39;')
+            .replace(/</g, '&lt;')
+            .replace(/>/g, '&gt;');
+    }
+    /**
+     * Merge class values
+     */
+    mergeCls(a, b) {
+        const classes = [];
+        if (a) {
+            classes.push(...(Array.isArray(a) ? a : [a]));
+        }
+        if (b) {
+            classes.push(...(Array.isArray(b) ? b : [b]));
+        }
+        return classes.join(' ');
+    }
+    /**
+     * Make props serializable (remove functions, etc.)
+     */
+    serializableProps(props) {
+        const result = {};
+        for (const [key, value] of Object.entries(props)) {
+            if (typeof value === 'function')
+                continue;
+            if (typeof value === 'object' && value !== null) {
+                result[key] = this.serializableProps(value);
+            }
+            else {
+                result[key] = value;
+            }
+        }
+        return result;
+    }
+    /**
+     * Reset island counter (for testing)
+     */
+    resetIslandCounter() {
+        islandIdCounter = 0;
+    }
+}
+// Export singleton
+export const staticHtmlRenderer = new StaticHtmlRenderer();
+/**
+ * Convenience function to render a component to HTML string
+ */
+export async function renderToString(name, definition, props = {}, registry) {
+    const ctx = {
+        registry: registry || new Map([[name, definition]]),
+        styles: new Set(),
+        islands: [],
+        props
+    };
+    return staticHtmlRenderer.renderComponent(name, ctx, props);
+}