smol.js 0.1.0

package/src/component.ts

@@ -0,0 +1,154 @@
+import type { SmolComponentConfig, SmolElement, SmolContext } from './types';
+import { render, renderToString, isTemplateResult } from './html';
+
+/**
+ * Create a custom Web Component
+ * 
+ * This function creates a custom element class and automatically registers it.
+ * It handles Shadow DOM, lifecycle callbacks, and template rendering.
+ * 
+ * @example
+ * ```ts
+ * // my-button.html
+ * // <button><slot>Button</slot></button>
+ * 
+ * // my-button.css
+ * // button { padding: 0.5rem 1rem; }
+ * 
+ * import { smolComponent, html } from 'smol.js';
+ * import styles from './my-button.css?inline';
+ * import template from './my-button.html?smol';
+ * 
+ * smolComponent({
+ *   tag: 'my-button',
+ *   observedAttributes: ['variant'],
+ *   
+ *   styles,
+ *   
+ *   template(ctx) {
+ *     return template(html);
+ *   }
+ * });
+ * ```
+ */
+export function smolComponent(config: SmolComponentConfig): typeof HTMLElement {
+    const {
+        tag,
+        mode = 'open',
+        observedAttributes = [],
+        styles = '',
+        template,
+        connected,
+        disconnected,
+        attributeChanged
+    } = config;
+
+    // Validate tag name
+    if (!tag.includes('-')) {
+        throw new Error(`Custom element tag names must contain a hyphen: "${tag}"`);
+    }
+
+    class SmolCustomElement extends HTMLElement implements SmolElement {
+        declare shadowRoot: ShadowRoot;
+
+        static get observedAttributes() {
+            return observedAttributes;
+        }
+
+        constructor() {
+            super();
+
+            // Check if Shadow DOM already exists (from SSR Declarative Shadow DOM)
+            if (!this.shadowRoot) {
+                this.attachShadow({ mode });
+            }
+
+            // Inject styles if provided
+            if (styles && this.shadowRoot) {
+                const styleElement = document.createElement('style');
+                styleElement.textContent = styles;
+                this.shadowRoot.appendChild(styleElement);
+            }
+        }
+
+        connectedCallback() {
+            // Call user-defined connected lifecycle FIRST
+            // This allows setup of signals and reactive state before first render
+            if (connected) {
+                connected.call(this);
+            }
+
+            // Then render the component
+            this.render();
+        }
+
+        disconnectedCallback() {
+            // Call user-defined disconnected lifecycle
+            if (disconnected) {
+                disconnected.call(this);
+            }
+        }
+
+        attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null) {
+            // Re-render on attribute change
+            if (this.isConnected) {
+                this.render();
+            }
+
+            // Call user-defined attribute changed lifecycle
+            if (attributeChanged) {
+                attributeChanged.call(this, name, oldValue, newValue);
+            }
+        }
+
+        /**
+         * Render the component template
+         */
+        render(): void {
+            if (!template || !this.shadowRoot) {
+                return;
+            }
+
+            const ctx: SmolContext = {
+                emit: this.emit.bind(this),
+                render: this.render.bind(this),
+                // Add element as context (for accessing attributes, etc.)
+                element: this
+            };
+
+            const result = template.call(this, ctx);
+
+            if (!result) {
+                return;
+            }
+
+            if (typeof result === 'string') {
+                this.shadowRoot.innerHTML = result;
+            } else if (isTemplateResult(result)) {
+                render(result, this.shadowRoot);
+            }
+        }
+
+        /**
+         * Emit a custom event
+         */
+        emit(name: string, detail?: any): void {
+            this.dispatchEvent(new CustomEvent(name, {
+                detail,
+                bubbles: true,
+                composed: true
+            }));
+        }
+    }
+
+    // Store config and tag name on the class for SSR
+    (SmolCustomElement as any)._smolConfig = config;
+    (SmolCustomElement as any)._smolTag = tag;
+
+    // Auto-register the custom element
+    if (!customElements.get(tag)) {
+        customElements.define(tag, SmolCustomElement);
+    }
+
+    return SmolCustomElement;
+}

package/src/css.ts

@@ -0,0 +1,25 @@
+/**
+ * Tagged template literal for CSS styles
+ * 
+ * @example
+ * ```ts
+ * const styles = css`
+ *   :host {
+ *     display: block;
+ *   }
+ * `;
+ * ```
+ */
+export function css(strings: TemplateStringsArray, ...values: any[]): string {
+    let result = '';
+
+    for (let i = 0; i < strings.length; i++) {
+        result += strings[i];
+
+        if (i < values.length) {
+            result += String(values[i]);
+        }
+    }
+
+    return result.trim();
+}

package/src/html-module.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Type declarations for importing HTML templates with ?smol query parameter
+ * 
+ * This allows TypeScript to recognize .html?smol imports
+ */
+
+declare module '*.html?smol' {
+    import type { TemplateResult } from './types';
+
+    /**
+     * Imported HTML template function
+     * Takes the html tagged template function and returns a TemplateResult
+     */
+    const template: (html: (strings: TemplateStringsArray, ...values: any[]) => TemplateResult) => TemplateResult;
+    export default template;
+}

package/src/html.ts

@@ -0,0 +1,178 @@
+import type { TemplateResult } from './types';
+
+/**
+ * Tagged template literal for HTML templates
+ * 
+ * @example
+ * ```ts
+ * const template = html`<div>${value}</div>`;
+ * ```
+ */
+export function html(strings: TemplateStringsArray, ...values: any[]): TemplateResult {
+    return {
+        strings,
+        values,
+        _isTemplateResult: true
+    };
+}
+
+/**
+ * Check if a value is a TemplateResult
+ */
+export function isTemplateResult(value: any): value is TemplateResult {
+    return value && value._isTemplateResult === true;
+}
+
+/**
+ * Render a template result to an HTML string
+ * Used for SSR or initial rendering
+ */
+export function renderToString(template: TemplateResult): string {
+    let result = '';
+
+    for (let i = 0; i < template.strings.length; i++) {
+        result += template.strings[i];
+
+        if (i < template.values.length) {
+            const value = template.values[i];
+            result += stringifyValue(value);
+        }
+    }
+
+    return result;
+}
+
+/**
+ * Convert a value to a string for HTML output
+ */
+function stringifyValue(value: any): string {
+    if (value == null) {
+        return '';
+    }
+
+    if (isTemplateResult(value)) {
+        return renderToString(value);
+    }
+
+    if (Array.isArray(value)) {
+        return value.map(stringifyValue).join('');
+    }
+
+    if (typeof value === 'boolean') {
+        return value ? '' : '';
+    }
+
+    if (typeof value === 'function') {
+        // Skip functions (likely event handlers)
+        return '';
+    }
+
+    return escapeHtml(String(value));
+}
+
+/**
+ * Escape HTML special characters
+ */
+function escapeHtml(unsafe: string): string {
+    return unsafe
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#039;');
+}
+
+/**
+ * Render a template to a DOM node
+ * This handles event listeners, attributes, and text content
+ * IMPORTANT: Preserves existing <style> elements in shadow DOM
+ */
+export function render(template: TemplateResult, container: HTMLElement | ShadowRoot): void {
+    // CRITICAL FIX: Preserve existing style elements before wiping innerHTML
+    const existingStyles = Array.from(container.querySelectorAll('style'));
+
+    // Build HTML first, replacing expressions with markers
+    let html = '';
+    const markers: Array<{ index: number; value: any; type: string }> = [];
+    let markerIndex = 0;
+
+    for (let i = 0; i < template.strings.length; i++) {
+        const str = template.strings[i];
+        html += str;
+
+        if (i < template.values.length) {
+            const value = template.values[i];
+
+            // Detect what kind of binding this is based on the preceding text
+            const lastPart = str.trim();
+
+            // Event handler: @event=${handler}
+            if (lastPart.endsWith('@click=') || lastPart.endsWith('@change=') || lastPart.includes('@')) {
+                markers.push({ index: markerIndex, value, type: 'event' });
+                html += `"__smol_event_${markerIndex}__"`;
+                markerIndex++;
+            }
+            // Boolean attribute: ?disabled=${bool}
+            else if (lastPart.endsWith('?disabled=') || lastPart.endsWith('?checked=') || lastPart.includes('?')) {
+                markers.push({ index: markerIndex, value, type: 'boolean' });
+                html += `"__smol_bool_${markerIndex}__"`;
+                markerIndex++;
+            }
+            // Regular interpolation
+            else {
+                html += stringifyValue(value);
+            }
+        }
+    }
+
+    // Set innerHTML (this wipes everything including styles)
+    container.innerHTML = html;
+
+    // Re-add the preserved style elements at the beginning
+    existingStyles.forEach(style => {
+        container.insertBefore(style, container.firstChild);
+    });
+
+    // Attach event listeners and handle boolean attributes
+    markers.forEach(marker => {
+        if (marker.type === 'event') {
+            // Find elements with event markers
+            const markerAttr = `__smol_event_${marker.index}__`;
+            const walker = document.createTreeWalker(container, NodeFilter.SHOW_ELEMENT);
+
+            let node;
+            while ((node = walker.nextNode())) {
+                const element = node as Element;
+                for (const attr of Array.from(element.attributes)) {
+                    if (attr.value === markerAttr) {
+                        const eventName = attr.name.replace('@', '');
+                        element.removeAttribute(attr.name);
+
+                        if (typeof marker.value === 'function') {
+                            element.addEventListener(eventName, marker.value as EventListener);
+                        }
+                    }
+                }
+            }
+        } else if (marker.type === 'boolean') {
+            // Handle boolean attributes
+            const markerAttr = `__smol_bool_${marker.index}__`;
+            const walker = document.createTreeWalker(container, NodeFilter.SHOW_ELEMENT);
+
+            let node;
+            while ((node = walker.nextNode())) {
+                const element = node as Element;
+                for (const attr of Array.from(element.attributes)) {
+                    if (attr.value === markerAttr) {
+                        const attrName = attr.name.replace('?', '');
+                        element.removeAttribute(attr.name);
+
+                        if (marker.value) {
+                            element.setAttribute(attrName, '');
+                        }
+                    }
+                }
+            }
+        }
+    });
+}

package/src/hydrate-client.ts

@@ -0,0 +1,17 @@
+import { hydrateAll } from './hydrate';
+
+/**
+ * Client-only auto-hydration setup
+ * This file should only be imported in client-side code, not SSR
+ */
+
+if (typeof window !== 'undefined') {
+    if (document.readyState === 'loading') {
+        document.addEventListener('DOMContentLoaded', () => {
+            hydrateAll();
+        });
+    } else {
+        // DOM already loaded
+        hydrateAll();
+    }
+}

package/src/hydrate.ts

@@ -0,0 +1,102 @@
+import type { SmolElement } from './types';
+
+/**
+ * Hydration utilities for SSR-rendered components
+ * 
+ * Hydration attaches JavaScript behavior to server-rendered HTML
+ * without destroying and recreating the DOM.
+ */
+
+/**
+ * Check if a component was server-rendered (has Declarative Shadow DOM)
+ */
+export function isServerRendered(element: HTMLElement): boolean {
+    return element.shadowRoot !== null && !element.shadowRoot.mode;
+}
+
+/**
+ * Hydrate a server-rendered component
+ * 
+ * This attaches event listeners and sets up reactivity
+ * without re-rendering the component.
+ */
+export function hydrateComponent(element: SmolElement): void {
+    // If not server-rendered, skip hydration
+    if (!element.shadowRoot) {
+        return;
+    }
+
+    // Mark as hydrated to prevent full re-render
+    (element as any)._hydrated = true;
+
+    // The component's connected callback will handle:
+    // 1. Setting up reactive state
+    // 2. Subscribing to state changes
+    // 3. Calling render() - but render() should check _hydrated flag
+
+    // After hydration, attach event listeners
+    attachEventListeners(element);
+}
+
+/**
+ * Attach event listeners to a hydrated component
+ * 
+ * This walks the shadow DOM and finds elements with data-smol-event attributes
+ * that were set during SSR.
+ */
+function attachEventListeners(element: SmolElement): void {
+    if (!element.shadowRoot) return;
+
+    // Find all elements with event listener markers
+    const walker = document.createTreeWalker(
+        element.shadowRoot,
+        NodeFilter.SHOW_ELEMENT
+    );
+
+    const elementsWithEvents: Array<{ element: Element; events: Map<string, string> }> = [];
+
+    let node;
+    while ((node = walker.nextNode())) {
+        const el = node as Element;
+        const events = new Map<string, string>();
+
+        // Check for data-smol-* attributes that mark event listeners
+        for (const attr of Array.from(el.attributes)) {
+            if (attr.name.startsWith('data-smol-event-')) {
+                const eventName = attr.name.replace('data-smol-event-', '');
+                events.set(eventName, attr.value);
+            }
+        }
+
+        if (events.size > 0) {
+            elementsWithEvents.push({ element: el, events });
+        }
+    }
+
+    // Attach event listeners
+    // Note: The actual handler functions need to be retrieved from the component's config
+    // This is a simplified version - in production, you'd serialize handler references
+    elementsWithEvents.forEach(({ element: el, events }) => {
+        events.forEach((handlerId, eventName) => {
+            // In a full implementation, you'd look up the handler by handlerId
+            // For now, this is a placeholder
+            console.warn(`Hydration: Found event listener ${eventName} but handler lookup not implemented`);
+        });
+    });
+}
+
+/**
+ * Hydrate all smol components on the page
+ * 
+ * Call this after the page loads to hydrate all server-rendered components.
+ */
+export function hydrateAll(): void {
+    const allElements = document.querySelectorAll('*');
+
+    allElements.forEach(element => {
+        // Check if this is a custom element (has a hyphen in the tag name)
+        if (element.tagName.includes('-') && element.shadowRoot) {
+            hydrateComponent(element as SmolElement);
+        }
+    });
+}

package/src/index.ts

@@ -0,0 +1,33 @@
+// smol.js - Minimal Web Component Library
+// Zero dependencies, tree-shakable, standards-based
+
+// Core component creation
+export { smolComponent } from './component';
+
+// Services and dependency injection
+export { smolService, inject, clearServices } from './service';
+
+// Reactivity primitives
+export { smolSignal, computed, effect } from './signal';
+export { smolState } from './state';
+
+// Template helpers
+export { html, render, renderToString, isTemplateResult } from './html';
+export { css } from './css';
+
+// SSR utilities
+export { renderComponentToString, ssr } from './ssr';
+
+// Hydration utilities
+export { hydrateComponent, hydrateAll } from './hydrate';
+
+// TypeScript types
+export type {
+    SmolComponentConfig,
+    SmolContext,
+    SmolElement,
+    TemplateResult,
+    Signal,
+    State,
+    SmolServiceConfig
+} from './types';

package/src/service.ts

@@ -0,0 +1,67 @@
+import type { SmolServiceConfig } from './types';
+
+// Global service registry
+const serviceRegistry = new Map<string, any>();
+
+/**
+ * Create a service (singleton by default)
+ * 
+ * Services provide shared functionality across components.
+ * 
+ * @example
+ * ```ts
+ * const ApiService = smolService({
+ *   name: 'ApiService',
+ *   factory: () => ({
+ *     async fetchData(url: string) {
+ *       const res = await fetch(url);
+ *       return res.json();
+ *     }
+ *   })
+ * });
+ * 
+ * // Use in component:
+ * const api = inject('ApiService');
+ * ```
+ */
+export function smolService<T>(config: SmolServiceConfig<T>): T {
+    const { name, factory, singleton = true } = config;
+
+    if (singleton) {
+        // Return existing instance if available
+        if (serviceRegistry.has(name)) {
+            return serviceRegistry.get(name);
+        }
+
+        // Create and store new instance
+        const instance = factory();
+        serviceRegistry.set(name, instance);
+        return instance;
+    }
+
+    // Always create new instance for non-singletons
+    return factory();
+}
+
+/**
+ * Inject a service by name
+ * 
+ * @example
+ * ```ts
+ * const api = inject<ApiService>('ApiService');
+ * ```
+ */
+export function inject<T = any>(name: string): T {
+    if (!serviceRegistry.has(name)) {
+        throw new Error(`Service "${name}" not found. Did you forget to create it with smolService()?`);
+    }
+
+    return serviceRegistry.get(name);
+}
+
+/**
+ * Clear all services (useful for testing)
+ */
+export function clearServices(): void {
+    serviceRegistry.clear();
+}

package/src/signal.ts

@@ -0,0 +1,89 @@
+import type { Signal } from './types';
+
+/**
+ * Create a reactive signal
+ * 
+ * Signals are lightweight reactive primitives that notify subscribers when their value changes.
+ * 
+ * @example
+ * ```ts
+ * const count = smolSignal(0);
+ * 
+ * // Subscribe to changes
+ * count.subscribe((value) => console.log('Count:', value));
+ * 
+ * // Update value
+ * count.value = 1; // logs "Count: 1"
+ * ```
+ */
+export function smolSignal<T>(initialValue: T): Signal<T> {
+    let _value = initialValue;
+    const _subscribers = new Set<(value: T) => void>();
+
+    const signal: Signal<T> = {
+        get value() {
+            return _value;
+        },
+
+        set value(newValue: T) {
+            if (_value !== newValue) {
+                _value = newValue;
+                _subscribers.forEach(fn => fn(_value));
+            }
+        },
+
+        subscribe(fn: (value: T) => void): () => void {
+            _subscribers.add(fn);
+
+            // Return unsubscribe function
+            return () => {
+                _subscribers.delete(fn);
+            };
+        },
+
+        _subscribers
+    };
+
+    return signal;
+}
+
+/**
+ * Create a computed signal that derives its value from other signals
+ * 
+ * @example
+ * ```ts
+ * const count = smolSignal(0);
+ * const doubled = computed(() => count.value * 2);
+ * ```
+ */
+export function computed<T>(fn: () => T): Signal<T> {
+    const signal = smolSignal<T>(fn());
+
+    // Note: This is a simplified version
+    // A production version would track dependencies automatically
+
+    return signal;
+}
+
+/**
+ * Create an effect that runs when signals change
+ * 
+ * @example
+ * ```ts
+ * const count = smolSignal(0);
+ * 
+ * effect(() => {
+ *   console.log('Count is:', count.value);
+ * });
+ * ```
+ */
+export function effect(fn: () => void): () => void {
+    // Run immediately
+    fn();
+
+    // Note: This is a simplified version
+    // A production version would track signal dependencies and re-run when they change
+
+    // Return cleanup function
+    return () => { };
+}