gonia 0.0.1

package/dist/reactivity.js

@@ -0,0 +1,219 @@
+/**
+ * Fine-grained reactivity system using Proxies.
+ *
+ * @remarks
+ * Each directive becomes its own effect, tracking only the state it accesses.
+ * Changes trigger only the affected effects - no component re-renders, no diffing.
+ *
+ * @packageDocumentation
+ */
+let activeEffect = null;
+let activeScope = null;
+const targetMap = new WeakMap();
+const effectDeps = new Map();
+export function createEffectScope() {
+    const scope = {
+        _effects: [],
+        active: true,
+        run(fn) {
+            const prevScope = activeScope;
+            activeScope = scope;
+            try {
+                return fn();
+            }
+            finally {
+                activeScope = prevScope;
+            }
+        },
+        stop() {
+            if (scope.active) {
+                for (const stopFn of scope._effects) {
+                    stopFn();
+                }
+                scope._effects.length = 0;
+                scope.active = false;
+            }
+        }
+    };
+    return scope;
+}
+/**
+ * Register an effect's stop function with the active scope.
+ *
+ * @internal
+ */
+function registerWithScope(stopFn) {
+    if (activeScope && activeScope.active) {
+        activeScope._effects.push(stopFn);
+    }
+}
+/**
+ * Make an object deeply reactive.
+ *
+ * @remarks
+ * Property access is tracked when inside an effect. Mutations trigger
+ * all effects that depend on the changed property.
+ *
+ * @typeParam T - Object type
+ * @param target - The object to make reactive
+ * @returns A reactive proxy of the object
+ *
+ * @example
+ * ```ts
+ * const state = reactive({ count: 0 });
+ * effect(() => console.log(state.count));
+ * state.count = 1; // logs: 1
+ * ```
+ */
+export function reactive(target) {
+    return new Proxy(target, {
+        get(obj, key, receiver) {
+            track(obj, key);
+            const value = Reflect.get(obj, key, receiver);
+            if (value !== null && typeof value === 'object') {
+                return reactive(value);
+            }
+            return value;
+        },
+        set(obj, key, value, receiver) {
+            const oldValue = Reflect.get(obj, key, receiver);
+            const result = Reflect.set(obj, key, value, receiver);
+            if (oldValue !== value) {
+                trigger(obj, key);
+            }
+            return result;
+        },
+        deleteProperty(obj, key) {
+            const hadKey = key in obj;
+            const result = Reflect.deleteProperty(obj, key);
+            if (hadKey) {
+                trigger(obj, key);
+            }
+            return result;
+        }
+    });
+}
+/**
+ * Track a dependency: the active effect depends on target[key].
+ *
+ * @internal
+ */
+function track(target, key) {
+    if (!activeEffect)
+        return;
+    let depsMap = targetMap.get(target);
+    if (!depsMap) {
+        depsMap = new Map();
+        targetMap.set(target, depsMap);
+    }
+    let deps = depsMap.get(key);
+    if (!deps) {
+        deps = new Set();
+        depsMap.set(key, deps);
+    }
+    deps.add(activeEffect);
+    let trackedDeps = effectDeps.get(activeEffect);
+    if (!trackedDeps) {
+        trackedDeps = new Set();
+        effectDeps.set(activeEffect, trackedDeps);
+    }
+    trackedDeps.add(deps);
+}
+/**
+ * Trigger effects that depend on target[key].
+ *
+ * @internal
+ */
+function trigger(target, key) {
+    const depsMap = targetMap.get(target);
+    if (!depsMap)
+        return;
+    const deps = depsMap.get(key);
+    if (deps) {
+        const effectsToRun = [...deps];
+        effectsToRun.forEach(effect => effect());
+    }
+}
+/**
+ * Create a reactive effect.
+ *
+ * @remarks
+ * The function runs immediately, tracking dependencies.
+ * It re-runs automatically whenever those dependencies change.
+ *
+ * @param fn - The effect function to run
+ * @returns A cleanup function to stop the effect
+ *
+ * @example
+ * ```ts
+ * const state = reactive({ count: 0 });
+ * const stop = effect(() => {
+ *   console.log('Count:', state.count);
+ * });
+ * state.count = 1; // logs: Count: 1
+ * stop(); // effect no longer runs
+ * ```
+ */
+export function effect(fn) {
+    const run = () => {
+        cleanup(run);
+        activeEffect = run;
+        fn();
+        activeEffect = null;
+    };
+    run();
+    const stopFn = () => cleanup(run);
+    registerWithScope(stopFn);
+    return stopFn;
+}
+/**
+ * Remove an effect from all dependency sets.
+ *
+ * @internal
+ */
+function cleanup(effectFn) {
+    const trackedDeps = effectDeps.get(effectFn);
+    if (trackedDeps) {
+        for (const deps of trackedDeps) {
+            deps.delete(effectFn);
+        }
+        trackedDeps.clear();
+    }
+}
+/**
+ * Create a child reactive scope.
+ *
+ * @remarks
+ * Used by structural directives like c-for to create per-item contexts.
+ * The child scope inherits from the parent, with additions taking precedence.
+ *
+ * @typeParam T - Parent object type
+ * @param parent - The parent reactive object
+ * @param additions - Additional properties for this scope
+ * @returns A new reactive scope that inherits from parent
+ *
+ * @example
+ * ```ts
+ * const parent = reactive({ items: [1, 2, 3] });
+ * const child = createScope(parent, { item: 1, index: 0 });
+ * child.item;  // 1
+ * child.items; // [1, 2, 3] (from parent)
+ * ```
+ */
+export function createScope(parent, additions) {
+    const scope = reactive({ ...additions });
+    return new Proxy(scope, {
+        get(target, key, receiver) {
+            if (key in target) {
+                return Reflect.get(target, key, receiver);
+            }
+            return parent[key];
+        },
+        set(target, key, value, receiver) {
+            if (key in target) {
+                return Reflect.set(target, key, value, receiver);
+            }
+            return Reflect.set(parent, key, value);
+        }
+    });
+}

package/dist/scope.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Scope management for element state.
+ *
+ * @packageDocumentation
+ */
+import { Directive, DirectiveOptions } from './types.js';
+/**
+ * Create a new scope for an element.
+ *
+ * @param el - The element to create scope for
+ * @param parentScope - Optional parent scope to inherit from via prototype
+ * @returns The new reactive scope
+ */
+export declare function createElementScope(el: Element, parentScope?: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Get the scope for an element.
+ *
+ * @param el - The element
+ * @returns The element's scope, or undefined if none
+ */
+export declare function getElementScope(el: Element): Record<string, unknown> | undefined;
+/**
+ * Find the nearest ancestor scope by walking up the DOM tree.
+ *
+ * @param el - The element to start from
+ * @param includeSelf - Whether to check the element itself (default: false)
+ * @returns The nearest scope, or undefined if none found
+ */
+export declare function findParentScope(el: Element, includeSelf?: boolean): Record<string, unknown> | undefined;
+/**
+ * Remove scope for an element (cleanup).
+ *
+ * @param el - The element
+ */
+export declare function removeElementScope(el: Element): void;
+/**
+ * Register a directive as a custom element.
+ *
+ * @param name - The custom element name (must contain hyphen)
+ * @param fn - The directive function
+ * @param options - Directive options
+ */
+export declare function registerDirectiveElement(name: string, fn: Directive<any>, options: DirectiveOptions): void;

package/dist/scope.js

@@ -0,0 +1,112 @@
+/**
+ * Scope management for element state.
+ *
+ * @packageDocumentation
+ */
+import { reactive } from './reactivity.js';
+import { createContext } from './context.js';
+import { Mode } from './types.js';
+import { getInjectables } from './inject.js';
+/** WeakMap to store element scopes */
+const elementScopes = new WeakMap();
+/**
+ * Create a new scope for an element.
+ *
+ * @param el - The element to create scope for
+ * @param parentScope - Optional parent scope to inherit from via prototype
+ * @returns The new reactive scope
+ */
+export function createElementScope(el, parentScope) {
+    let scope;
+    if (parentScope) {
+        // Create new object with parent as prototype
+        scope = reactive(Object.create(parentScope));
+    }
+    else {
+        scope = reactive({});
+    }
+    elementScopes.set(el, scope);
+    return scope;
+}
+/**
+ * Get the scope for an element.
+ *
+ * @param el - The element
+ * @returns The element's scope, or undefined if none
+ */
+export function getElementScope(el) {
+    return elementScopes.get(el);
+}
+/**
+ * Find the nearest ancestor scope by walking up the DOM tree.
+ *
+ * @param el - The element to start from
+ * @param includeSelf - Whether to check the element itself (default: false)
+ * @returns The nearest scope, or undefined if none found
+ */
+export function findParentScope(el, includeSelf = false) {
+    let current = includeSelf ? el : el.parentElement;
+    while (current) {
+        const scope = elementScopes.get(current);
+        if (scope) {
+            return scope;
+        }
+        current = current.parentElement;
+    }
+    return undefined;
+}
+/**
+ * Remove scope for an element (cleanup).
+ *
+ * @param el - The element
+ */
+export function removeElementScope(el) {
+    elementScopes.delete(el);
+}
+/**
+ * Register a directive as a custom element.
+ *
+ * @param name - The custom element name (must contain hyphen)
+ * @param fn - The directive function
+ * @param options - Directive options
+ */
+export function registerDirectiveElement(name, 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+fn, options) {
+    // Don't re-register if already defined
+    if (customElements.get(name)) {
+        return;
+    }
+    customElements.define(name, class extends HTMLElement {
+        connectedCallback() {
+            // Find parent scope for prototype chain
+            const parentScope = findParentScope(this);
+            // Create this element's scope
+            const scope = createElementScope(this, parentScope);
+            // Create context for expression evaluation
+            const ctx = createContext(Mode.CLIENT, scope);
+            // Resolve dependencies and call directive
+            const inject = getInjectables(fn);
+            const args = inject.map((dep) => {
+                switch (dep) {
+                    case '$element':
+                        return this;
+                    case '$state':
+                        return scope;
+                    case '$eval':
+                        return ctx.eval.bind(ctx);
+                    default:
+                        return undefined;
+                }
+            });
+            const result = fn(...args);
+            // Handle async directives
+            if (result instanceof Promise) {
+                result.catch(err => console.error(`Error in ${name}:`, err));
+            }
+        }
+        disconnectedCallback() {
+            removeElementScope(this);
+        }
+    });
+}

package/dist/server/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Server-side rendering utilities.
+ *
+ * @packageDocumentation
+ */
+export { render, registerDirective } from './render.js';
+export type { DirectiveRegistry } from './render.js';

package/dist/server/index.js

@@ -0,0 +1,6 @@
+/**
+ * Server-side rendering utilities.
+ *
+ * @packageDocumentation
+ */
+export { render, registerDirective } from './render.js';

package/dist/server/render.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Server-side rendering with MutationObserver-based directive indexing.
+ *
+ * @packageDocumentation
+ */
+import { Directive } from '../types.js';
+/**
+ * Registry of directives by name.
+ */
+export type DirectiveRegistry = Map<string, Directive>;
+/**
+ * Service registry for dependency injection.
+ */
+export type ServiceRegistry = Map<string, unknown>;
+/**
+ * Register a directive in the registry.
+ *
+ * @remarks
+ * Invalidates the cached selector so it will be rebuilt on next render.
+ *
+ * @param registry - The directive registry
+ * @param name - Directive name (without c- prefix)
+ * @param fn - The directive function
+ */
+export declare function registerDirective(registry: DirectiveRegistry, name: string, fn: Directive): void;
+/**
+ * Register a service for dependency injection.
+ *
+ * @param name - Service name (used in $inject arrays)
+ * @param service - The service instance
+ */
+export declare function registerService(name: string, service: unknown): void;
+/**
+ * Render HTML with directives on the server.
+ *
+ * @remarks
+ * Uses MutationObserver to index elements with directive attributes
+ * as they are parsed, then executes directives to produce the final HTML.
+ * Directive attributes are preserved in output for client hydration.
+ * Directives are processed in tree order (parents before children),
+ * with priority used only for multiple directives on the same element.
+ *
+ * @param html - The HTML template string
+ * @param state - The state object to use for expression evaluation
+ * @param registry - The directive registry
+ * @returns The rendered HTML string
+ *
+ * @example
+ * ```ts
+ * const registry = new Map();
+ * registry.set('text', textDirective);
+ *
+ * const html = await render(
+ *   '<span c-text="user.name"></span>',
+ *   { user: { name: 'Alice' } },
+ *   registry
+ * );
+ * // '<span c-text="user.name">Alice</span>'
+ * ```
+ */
+export declare function render(html: string, state: Record<string, unknown>, registry: DirectiveRegistry): Promise<string>;

package/dist/server/render.js

@@ -0,0 +1,243 @@
+/**
+ * Server-side rendering with MutationObserver-based directive indexing.
+ *
+ * @packageDocumentation
+ */
+import { parseHTML } from 'linkedom';
+import { Mode, DirectivePriority } from '../types.js';
+import { createContext } from '../context.js';
+import { processNativeSlot } from '../directives/slot.js';
+import { getLocalState, registerProvider, resolveFromProviders, resolveFromDIProviders } from '../providers.js';
+import { FOR_PROCESSED_ATTR, FOR_TEMPLATE_ATTR } from '../directives/for.js';
+import { IF_PROCESSED_ATTR } from '../directives/if.js';
+/** Registered services */
+let services = new Map();
+const selectorCache = new WeakMap();
+/**
+ * Build a CSS selector for all registered directives.
+ *
+ * @internal
+ */
+function getSelector(registry) {
+    let selector = selectorCache.get(registry);
+    if (!selector) {
+        const directiveSelectors = [...registry.keys()].map(n => `[c-${n}]`);
+        // Also match native <slot> elements
+        directiveSelectors.push('slot');
+        selector = directiveSelectors.join(',');
+        selectorCache.set(registry, selector);
+    }
+    return selector;
+}
+/**
+ * Register a directive in the registry.
+ *
+ * @remarks
+ * Invalidates the cached selector so it will be rebuilt on next render.
+ *
+ * @param registry - The directive registry
+ * @param name - Directive name (without c- prefix)
+ * @param fn - The directive function
+ */
+export function registerDirective(registry, name, fn) {
+    registry.set(name, fn);
+    selectorCache.delete(registry);
+}
+/**
+ * Register a service for dependency injection.
+ *
+ * @param name - Service name (used in $inject arrays)
+ * @param service - The service instance
+ */
+export function registerService(name, service) {
+    services.set(name, service);
+}
+/**
+ * Resolve dependencies for a directive based on its $inject array.
+ *
+ * @internal
+ */
+function resolveDependencies(directive, expr, el, ctx, rootState) {
+    const inject = directive.$inject ?? ['$expr', '$element', '$eval'];
+    return inject.map(name => {
+        switch (name) {
+            case '$expr':
+                return expr;
+            case '$element':
+                return el;
+            case '$eval':
+                return ctx.eval.bind(ctx);
+            case '$state':
+                return getLocalState(el) ?? rootState;
+            case '$rootState':
+                return rootState;
+            case '$mode':
+                return Mode.SERVER;
+            default: {
+                // Look up in ancestor DI providers first (provide option)
+                const diProvided = resolveFromDIProviders(el, name);
+                if (diProvided !== undefined) {
+                    return diProvided;
+                }
+                // Look up in global services registry
+                const service = services.get(name);
+                if (service !== undefined) {
+                    return service;
+                }
+                // Look up in ancestor context providers ($context)
+                const contextProvided = resolveFromProviders(el, name);
+                if (contextProvided !== undefined) {
+                    return contextProvided;
+                }
+                throw new Error(`Unknown injectable: ${name}`);
+            }
+        }
+    });
+}
+/**
+ * Render HTML with directives on the server.
+ *
+ * @remarks
+ * Uses MutationObserver to index elements with directive attributes
+ * as they are parsed, then executes directives to produce the final HTML.
+ * Directive attributes are preserved in output for client hydration.
+ * Directives are processed in tree order (parents before children),
+ * with priority used only for multiple directives on the same element.
+ *
+ * @param html - The HTML template string
+ * @param state - The state object to use for expression evaluation
+ * @param registry - The directive registry
+ * @returns The rendered HTML string
+ *
+ * @example
+ * ```ts
+ * const registry = new Map();
+ * registry.set('text', textDirective);
+ *
+ * const html = await render(
+ *   '<span c-text="user.name"></span>',
+ *   { user: { name: 'Alice' } },
+ *   registry
+ * );
+ * // '<span c-text="user.name">Alice</span>'
+ * ```
+ */
+export async function render(html, state, registry) {
+    const { document, MutationObserver } = parseHTML('<!DOCTYPE html><html><body></body></html>');
+    const index = [];
+    const selector = getSelector(registry);
+    const observer = new MutationObserver((mutations) => {
+        for (const mutation of mutations) {
+            for (const node of mutation.addedNodes) {
+                if (node.nodeType !== 1)
+                    continue;
+                const el = node;
+                const matches = el.matches(selector) ? [el] : [];
+                const descendants = [...el.querySelectorAll(selector)];
+                for (const match of [...matches, ...descendants]) {
+                    // Handle native <slot> elements
+                    if (match.tagName === 'SLOT') {
+                        index.push({
+                            el: match,
+                            name: 'slot',
+                            directive: null,
+                            expr: '',
+                            priority: DirectivePriority.NORMAL,
+                            isNativeSlot: true
+                        });
+                        continue;
+                    }
+                    for (const [name, directive] of registry) {
+                        const attr = match.getAttribute(`c-${name}`);
+                        if (attr !== null) {
+                            index.push({
+                                el: match,
+                                name,
+                                directive,
+                                expr: attr,
+                                priority: directive.priority ?? DirectivePriority.NORMAL
+                            });
+                        }
+                    }
+                }
+            }
+        }
+    });
+    observer.observe(document.body, { childList: true, subtree: true });
+    document.body.innerHTML = html;
+    await new Promise(r => setTimeout(r, 0));
+    const ctx = createContext(Mode.SERVER, state);
+    const processed = new Set();
+    // Process directives in rounds until no new elements are added
+    let hasMore = true;
+    while (hasMore) {
+        // Group by element, preserving tree order from the index
+        const elementOrder = [];
+        const byElement = new Map();
+        for (const item of index) {
+            if (processed.has(item.el))
+                continue;
+            if (!byElement.has(item.el)) {
+                elementOrder.push(item.el);
+                byElement.set(item.el, []);
+            }
+            byElement.get(item.el).push(item);
+        }
+        if (elementOrder.length === 0) {
+            hasMore = false;
+            break;
+        }
+        // Process elements in tree order
+        for (const el of elementOrder) {
+            // Skip elements that were removed (e.g., by c-for cloning)
+            if (!el.isConnected) {
+                processed.add(el);
+                continue;
+            }
+            // Skip elements already processed by structural directives (c-for, c-if)
+            // These elements have their own scoped processing
+            if (el.hasAttribute(FOR_PROCESSED_ATTR) || el.hasAttribute(IF_PROCESSED_ATTR)) {
+                processed.add(el);
+                continue;
+            }
+            // Skip template elements with c-for - these are template wrappers created by c-for
+            // and should not be processed as directives (they're for client hydration)
+            if (el.tagName === 'TEMPLATE' && el.hasAttribute('c-for')) {
+                processed.add(el);
+                continue;
+            }
+            // Skip template content elements - these are inside template wrappers
+            // and their directives are processed by c-for when rendering items
+            if (el.hasAttribute(FOR_TEMPLATE_ATTR)) {
+                processed.add(el);
+                continue;
+            }
+            processed.add(el);
+            const directives = byElement.get(el);
+            // Sort directives on this element by priority (higher first)
+            directives.sort((a, b) => b.priority - a.priority);
+            for (const item of directives) {
+                // Check if element was disconnected by a previous directive (e.g., c-for replacing it)
+                if (!item.el.isConnected) {
+                    break;
+                }
+                if (item.isNativeSlot) {
+                    processNativeSlot(item.el);
+                }
+                else {
+                    const args = resolveDependencies(item.directive, item.expr, item.el, ctx, state);
+                    await item.directive(...args);
+                    // Register as context provider if directive declares $context
+                    if (item.directive.$context?.length) {
+                        const localState = getLocalState(item.el);
+                        registerProvider(item.el, item.directive, localState);
+                    }
+                }
+            }
+            // Let observer catch new elements
+            await new Promise(r => setTimeout(r, 0));
+        }
+    }
+    observer.disconnect();
+    return document.body.innerHTML;
+}