smol.js 0.1.0

package/src/ssr.ts

@@ -0,0 +1,158 @@
+import type { SmolElement } from './types';
+import { renderToString } from './html';
+
+/**
+ * Render a component to an HTML string with Declarative Shadow DOM
+ * This is used for server-side rendering (SSR)
+ * 
+ * @example
+ * ```ts
+ * const html = renderComponentToString(MyCounter, { initialCount: 0 });
+ * // Returns: <my-counter><template shadowrootmode="open">...</template></my-counter>
+ * ```
+ */
+export function renderComponentToString(
+    ComponentClass: typeof HTMLElement,
+    attributes: Record<string, string> = {}
+): string {
+    // Create a temporary instance (without actually connecting to DOM)
+    const instance = new ComponentClass() as SmolElement;
+
+    // Set attributes if provided
+    Object.entries(attributes).forEach(([key, value]) => {
+        instance.setAttribute(key, value);
+    });
+
+    // Get the tag name from the constructor
+    const tagName = (ComponentClass as any)._smolTag || 'unknown-element';
+
+    // Get the template and styles
+    const config = (ComponentClass as any)._smolConfig;
+    const styles = config?.styles || '';
+
+    // Manually call the lifecycle to initialize state
+    if (config?.connected) {
+        config.connected.call(instance);
+    }
+
+    // Render the template
+    let templateHTML = '';
+    if (config?.template) {
+        const ctx = {
+            emit: instance.emit.bind(instance),
+            render: () => { },
+            element: instance
+        };
+        const result = config.template.call(instance, ctx);
+
+        if (typeof result === 'string') {
+            templateHTML = result;
+        } else if (result && result._isTemplateResult) {
+            templateHTML = renderToString(result);
+        }
+    }
+
+    // Build the Declarative Shadow DOM
+    if (globalThis.document && templateHTML) {
+        // Parse the template HTML
+        const template = document.createElement('template');
+        template.innerHTML = templateHTML;
+
+        // Recursively find and render nested components
+        expandNestedComponents(template.content);
+
+        templateHTML = template.innerHTML;
+    }
+
+    const shadowContent = `
+    ${styles ? `<style>${styles}</style>` : ''}
+    ${templateHTML}
+  `.trim();
+
+    // Build attribute string
+    const attrString = Object.entries(attributes)
+        .map(([key, value]) => `${key}="${escapeAttr(value)}"`)
+        .join(' ');
+
+    // Return the complete HTML with Declarative Shadow DOM
+    return `
+<${tagName}${attrString ? ' ' + attrString : ''}>
+  <template shadowrootmode="open">
+    ${shadowContent}
+  </template>
+</${tagName}>
+  `.trim();
+}
+
+/**
+ * Escape attribute values
+ */
+function escapeAttr(value: string): string {
+    return value
+        .replace(/&/g, '&amp;')
+        .replace(/"/g, '&quot;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;');
+}
+
+/**
+ * Server-side render utility
+ * Renders multiple components to HTML
+ */
+export function ssr(components: Array<{
+    component: typeof HTMLElement;
+    attributes?: Record<string, string>;
+}>): string {
+    return components
+        .map(({ component, attributes }) => renderComponentToString(component, attributes))
+        .join('\n');
+}
+
+/**
+ * Recursively expand nested components
+ */
+function expandNestedComponents(node: Node | DocumentFragment): void {
+    const children = Array.from(node.childNodes);
+
+    children.forEach(child => {
+        if (child.nodeType === 1) { // ELEMENT_NODE
+            const element = child as HTMLElement;
+            const tagName = element.tagName.toLowerCase();
+
+            // Check if it's a registered custom element
+            // We use globalThis to access the polyfilled registry in SSR
+            if (globalThis.customElements && tagName.includes('-')) {
+                const ComponentClass = customElements.get(tagName);
+
+                if (ComponentClass) {
+                    // Get attributes
+                    const attributes: Record<string, string> = {};
+                    Array.from(element.attributes).forEach(attr => {
+                        attributes[attr.name] = attr.value;
+                    });
+
+                    // Render the nested component
+                    const rendered = renderComponentToString(ComponentClass as typeof HTMLElement, attributes);
+
+                    // Replace the element with the rendered HTML (which includes the tag)
+                    // Since we can't easily replace outerHTML in a fragment with a string,
+                    // we create a temporary container
+                    const temp = document.createElement('div');
+                    temp.innerHTML = rendered;
+
+                    // Replace the child with the new rendered node
+                    const newChild = temp.firstElementChild;
+                    if (newChild) {
+                        element.replaceWith(newChild);
+                        // No need to recurse into newChild because renderComponentToString
+                        // already handled its recursion internally
+                        return;
+                    }
+                }
+            }
+
+            // Recurse for normal elements
+            expandNestedComponents(element);
+        }
+    });
+}

package/src/state.ts

@@ -0,0 +1,67 @@
+import type { State } from './types';
+
+/**
+ * Create a reactive state object using Proxy
+ * 
+ * Unlike signals, state objects are reactive objects that track changes to any property.
+ * 
+ * @example
+ * ```ts
+ * const state = smolState({
+ *   count: 0,
+ *   name: 'John'
+ * });
+ * 
+ * state.subscribe(() => {
+ *   console.log('State changed:', state.data);
+ * });
+ * 
+ * state.data.count++; // triggers subscribers
+ * ```
+ */
+export function smolState<T extends object>(initialValue: T): State<T> {
+    const _subscribers = new Set<() => void>();
+
+    const notify = () => {
+        _subscribers.forEach(fn => fn());
+    };
+
+    const data = new Proxy(initialValue, {
+        set(target, property, value) {
+            const oldValue = (target as any)[property];
+
+            if (oldValue !== value) {
+                (target as any)[property] = value;
+                notify();
+            }
+
+            return true;
+        },
+
+        deleteProperty(target, property) {
+            if (property in target) {
+                delete (target as any)[property];
+                notify();
+            }
+
+            return true;
+        }
+    });
+
+    const state: State<T> = {
+        data,
+
+        subscribe(fn: () => void): () => void {
+            _subscribers.add(fn);
+
+            // Return unsubscribe function
+            return () => {
+                _subscribers.delete(fn);
+            };
+        },
+
+        _subscribers
+    };
+
+    return state;
+}

package/src/types.ts

@@ -0,0 +1,91 @@
+// Core TypeScript type definitions for smol.js
+
+export interface SmolComponentConfig {
+    /** The custom element tag name (must contain a hyphen) */
+    tag: string;
+
+    /** Shadow DOM mode */
+    mode?: 'open' | 'closed';
+
+    /** List of attributes to observe for changes */
+    observedAttributes?: string[];
+
+    /** Component styles (use css`` tagged template) */
+    styles?: string;
+
+    /** Template function that returns HTML */
+    template?: (this: SmolElement, ctx: SmolContext) => string | TemplateResult;
+
+    /** Lifecycle: element connected to DOM */
+    connected?: (this: SmolElement) => void;
+
+    /** Lifecycle: element disconnected from DOM */
+    disconnected?: (this: SmolElement) => void;
+
+    /** Lifecycle: observed attribute changed */
+    attributeChanged?: (this: SmolElement, name: string, oldValue: string | null, newValue: string | null) => void;
+}
+
+export interface SmolContext {
+    /** Emit a custom event */
+    emit: (name: string, detail?: any) => void;
+
+    /** Trigger a re-render */
+    render: () => void;
+
+    /** Access to element properties */
+    [key: string]: any;
+}
+
+export interface SmolElement extends HTMLElement {
+    /** Trigger a re-render of the component */
+    render(): void;
+
+    /** Emit a custom event from the component */
+    emit(name: string, detail?: any): void;
+
+    /** Access to the shadow root */
+    readonly shadowRoot: ShadowRoot;
+}
+
+export interface TemplateResult {
+    strings: TemplateStringsArray;
+    values: any[];
+    _isTemplateResult: true;
+}
+
+export interface Signal<T> {
+    /** Get the current value */
+    get value(): T;
+
+    /** Set a new value */
+    set value(newValue: T);
+
+    /** Subscribe to value changes */
+    subscribe(fn: (value: T) => void): () => void;
+
+    /** Internal subscribers */
+    _subscribers: Set<(value: T) => void>;
+}
+
+export interface State<T extends object> {
+    /** The proxied state object */
+    data: T;
+
+    /** Subscribe to any state change */
+    subscribe(fn: () => void): () => void;
+
+    /** Internal subscribers */
+    _subscribers: Set<() => void>;
+}
+
+export interface SmolServiceConfig<T> {
+    /** Unique service name */
+    name: string;
+
+    /** Factory function to create the service */
+    factory: () => T;
+
+    /** Whether this is a singleton (default: true) */
+    singleton?: boolean;
+}

package/src/vite-plugin-smol-templates.ts

@@ -0,0 +1,85 @@
+import type { Plugin } from 'vite';
+import { readFileSync } from 'node:fs';
+
+
+/**
+ * Vite plugin for importing HTML templates as smol.js template functions
+ * 
+ * This plugin allows you to write your component templates in separate .html files
+ * and import them into your components.
+ * 
+ * @example
+ * ```typescript
+ * import template from './my-component.html?smol';
+ * 
+ * smolComponent({
+ *   tag: 'my-component',
+ *   template(ctx) {
+ *     return template(html);
+ *   }
+ * });
+ * ```
+ */
+export function smolTemplatePlugin(): Plugin {
+    return {
+        name: 'vite-plugin-smol-templates',
+        enforce: 'pre',
+
+        async resolveId(id: string, importer?: string) {
+            // Only handle .html files with ?smol query
+            if (id.includes('.html?smol')) {
+                const cleanId = id.replace('?smol', '');
+                const resolved = await this.resolve(cleanId, importer);
+
+                if (resolved) {
+                    return resolved.id + '?smol';
+                }
+            }
+            return null;
+        },
+
+        load(id: string) {
+            // Check if this is an HTML template with ?smol query
+            if (!id.includes('.html?smol')) {
+                return null;
+            }
+
+            // Remove query parameter to get the actual file path
+            const filePath = id.replace(/\?smol$/, '');
+
+            try {
+                // Read the HTML file content
+                const htmlContent = readFileSync(filePath, 'utf-8');
+
+                // Transform the HTML into a JavaScript module
+                // The template will be a function that takes the html tagged template function
+                // and returns a TemplateResult
+
+                // We need to preserve ${} interpolations as actual template literal placeholders
+                // while escaping backticks in the HTML content
+                const escapedContent = htmlContent
+                    .replace(/\\/g, '\\\\')  // Escape backslashes
+                    .replace(/`/g, '\\`');   // Escape backticks
+
+                // Create a function that uses 'with' to execute the template literal
+                // We use new Function to avoid strict mode limitations on 'with'
+                // and to allow dynamic variable resolution from the context
+                const templateBody = `with(context) { return html\`${escapedContent}\`; }`;
+
+                const code = `
+                    export default function(html, context = {}) {
+                        return new Function('html', 'context', ${JSON.stringify(templateBody)})(html, context);
+                    }
+                `;
+
+                return {
+                    code,
+                    map: null
+                };
+            } catch (error) {
+                this.error(`Failed to load HTML template: ${filePath}\n${error}`);
+                return null;
+            }
+        }
+    };
+}

package/src/vite.ts

@@ -0,0 +1,4 @@
+// Export the Vite plugin for external HTML templates
+// This is in a separate entry point to avoid bundling Node.js dependencies
+// into the browser-facing library
+export { smolTemplatePlugin } from './vite-plugin-smol-templates.js';