gonia 0.0.1

package/README.md

@@ -0,0 +1,119 @@
+# Gonia
+
+A lightweight, SSR-first reactive UI library for building web applications with HTML-based templates and declarative directives.
+
+## Features
+
+- **SSR-First Architecture** - Server-side rendering with seamless client hydration
+- **Declarative Directives** - Vue-inspired template syntax (`c-text`, `c-for`, `c-if`, etc.)
+- **Fine-Grained Reactivity** - Efficient updates without virtual DOM diffing
+- **Zero Dependencies** - Core library has no runtime dependencies (linkedom for SSR only)
+- **TypeScript Native** - Full type safety with excellent IDE support
+
+## Installation
+
+```bash
+pnpm add gonia
+```
+
+## Quick Start
+
+### Server-Side Rendering
+
+```typescript
+import { render, registerDirective } from 'gonia/server';
+import { text, show, cfor, cif, cclass } from 'gonia';
+
+// Create directive registry
+const registry = new Map();
+registerDirective(registry, 'text', text);
+registerDirective(registry, 'show', show);
+registerDirective(registry, 'for', cfor);
+registerDirective(registry, 'if', cif);
+registerDirective(registry, 'class', cclass);
+
+// Render HTML with state
+const html = await render(
+  '<ul><li c-for="item in items" c-text="item"></li></ul>',
+  { items: ['Apple', 'Banana', 'Cherry'] },
+  registry
+);
+```
+
+### Client-Side Hydration
+
+```typescript
+import { hydrate } from 'gonia/client';
+import { directive } from 'gonia';
+
+// Import directives (registers globally)
+import './directives/my-app.js';
+
+// Hydrate when DOM is ready
+hydrate();
+```
+
+### Creating a Component Directive
+
+```typescript
+import { directive, Directive } from 'gonia';
+
+const myApp: Directive = ($element, $state) => {
+  // Initialize state
+  $state.count = 0;
+
+  // Define methods
+  $state.increment = () => {
+    $state.count++;
+  };
+};
+
+myApp.$inject = ['$element', '$state'];
+
+// Register with scope: true to create isolated state
+directive('my-app', myApp, { scope: true });
+```
+
+```html
+<my-app>
+  <p c-text="count"></p>
+  <button c-on="click: increment">+1</button>
+</my-app>
+```
+
+## Directives
+
+| Directive | Description | Example |
+|-----------|-------------|---------|
+| `c-text` | Set text content | `<span c-text="message"></span>` |
+| `c-show` | Toggle visibility | `<div c-show="isVisible">...</div>` |
+| `c-if` | Conditional render | `<p c-if="hasError">Error!</p>` |
+| `c-for` | Loop iteration | `<li c-for="item in items">...</li>` |
+| `c-class` | Dynamic classes | `<div c-class="{ active: isActive }">` |
+| `c-model` | Two-way binding | `<input c-model="name">` |
+| `c-on` | Event handling | `<button c-on="click: handleClick">` |
+
+## Vite Integration
+
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite';
+import { gonia } from 'gonia/vite';
+
+export default defineConfig({
+  plugins: [gonia()]
+});
+```
+
+## Documentation
+
+See the [docs](./docs) folder for detailed documentation:
+
+- [Getting Started](./docs/getting-started.md)
+- [Directives Reference](./docs/directives.md)
+- [SSR Guide](./docs/ssr.md)
+- [Reactivity](./docs/reactivity.md)
+
+## License
+
+MIT

package/dist/client/hydrate.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Client-side hydration and runtime directive binding.
+ *
+ * @packageDocumentation
+ */
+import { Directive, Context } from '../types.js';
+/**
+ * Registry of directives by name.
+ */
+export type DirectiveRegistry = Map<string, Directive<any>>;
+/**
+ * Service registry for dependency injection.
+ */
+export type ServiceRegistry = Map<string, unknown>;
+/**
+ * Set context for an element (used by directives that create child contexts).
+ *
+ * @internal
+ */
+export declare function setElementContext(el: Element, ctx: Context): void;
+/**
+ * Register a directive in the registry.
+ *
+ * @remarks
+ * If called after hydration, scans the DOM for any elements using
+ * this directive and processes them immediately.
+ *
+ * @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;
+export declare function init(registry?: DirectiveRegistry): Promise<void>;
+/**
+ * Hydrate server-rendered HTML.
+ *
+ * @remarks
+ * Alias for {@link init}. Use when hydrating SSR output.
+ */
+export declare const hydrate: typeof init;
+/**
+ * Mount the framework on client-rendered HTML.
+ *
+ * @remarks
+ * Alias for {@link init}. Use for pure client-side rendering.
+ */
+export declare const mount: typeof init;

package/dist/client/hydrate.js

@@ -0,0 +1,445 @@
+/**
+ * Client-side hydration and runtime directive binding.
+ *
+ * @packageDocumentation
+ */
+import { Mode, DirectivePriority, getDirective, getDirectiveNames } from '../types.js';
+import { createContext } from '../context.js';
+import { processNativeSlot } from '../directives/slot.js';
+import { getLocalState, registerProvider, resolveFromProviders, registerDIProviders, resolveFromDIProviders } from '../providers.js';
+import { FOR_PROCESSED_ATTR } from '../directives/for.js';
+import { findParentScope, createElementScope, getElementScope } from '../scope.js';
+import { getInjectables } from '../inject.js';
+// Built-in directives
+import { text } from '../directives/text.js';
+import { show } from '../directives/show.js';
+import { cclass } from '../directives/class.js';
+import { model } from '../directives/model.js';
+import { on } from '../directives/on.js';
+import { cfor } from '../directives/for.js';
+import { cif } from '../directives/if.js';
+/** Cached selector string */
+let cachedSelector = null;
+/** Whether init() has been called */
+let initialized = false;
+/** Registered services */
+let services = new Map();
+/** Context cache by element */
+const contextCache = new WeakMap();
+/** Default registry with built-in directives */
+let defaultRegistry = null;
+/**
+ * Get the default directive registry with built-in directives.
+ *
+ * @internal
+ */
+function getDefaultRegistry() {
+    if (!defaultRegistry) {
+        defaultRegistry = new Map();
+        defaultRegistry.set('text', text);
+        defaultRegistry.set('show', show);
+        defaultRegistry.set('class', cclass);
+        defaultRegistry.set('model', model);
+        defaultRegistry.set('on', on);
+        defaultRegistry.set('for', cfor);
+        defaultRegistry.set('if', cif);
+    }
+    return defaultRegistry;
+}
+/**
+ * Build a CSS selector for all registered directives.
+ *
+ * @internal
+ */
+function getSelector(registry) {
+    if (!cachedSelector) {
+        const directiveSelectors = [];
+        for (const name of registry.keys()) {
+            directiveSelectors.push(`[c-${name}]`);
+        }
+        // Also match native <slot> elements
+        directiveSelectors.push('slot');
+        cachedSelector = directiveSelectors.join(',');
+    }
+    return cachedSelector;
+}
+/**
+ * Get directives for an element, sorted by priority (highest first).
+ *
+ * @internal
+ */
+function getDirectivesForElement(el, registry) {
+    const directives = [];
+    for (const [name, directive] of registry) {
+        const attr = el.getAttribute(`c-${name}`);
+        if (attr !== null) {
+            directives.push({ name, directive, expr: attr });
+        }
+    }
+    // Sort by priority (higher first)
+    directives.sort((a, b) => {
+        const priorityA = a.directive.priority ?? DirectivePriority.NORMAL;
+        const priorityB = b.directive.priority ?? DirectivePriority.NORMAL;
+        return priorityB - priorityA;
+    });
+    return directives;
+}
+/**
+ * Get or create context for an element.
+ *
+ * @remarks
+ * Walks up the DOM to find the nearest ancestor with a cached context,
+ * then creates a context using the nearest scope.
+ *
+ * @internal
+ */
+function getContextForElement(el) {
+    // Check cache first
+    const cached = contextCache.get(el);
+    if (cached)
+        return cached;
+    // Walk up to find nearest context
+    let current = el.parentElement;
+    while (current) {
+        const parentCtx = contextCache.get(current);
+        if (parentCtx) {
+            const ctx = parentCtx.child({});
+            contextCache.set(el, ctx);
+            return ctx;
+        }
+        current = current.parentElement;
+    }
+    // Find nearest scope or create empty one
+    const scope = findParentScope(el, true) ?? createElementScope(el);
+    const ctx = createContext(Mode.CLIENT, scope);
+    contextCache.set(el, ctx);
+    return ctx;
+}
+/**
+ * Set context for an element (used by directives that create child contexts).
+ *
+ * @internal
+ */
+export function setElementContext(el, ctx) {
+    contextCache.set(el, ctx);
+}
+/**
+ * Resolve dependencies for a directive based on its $inject array.
+ *
+ * @internal
+ */
+function resolveDependencies(directive, expr, el, ctx) {
+    const inject = getInjectables(directive);
+    return inject.map(name => {
+        switch (name) {
+            case '$expr':
+                return expr;
+            case '$element':
+                return el;
+            case '$eval':
+                return ctx.eval.bind(ctx);
+            case '$state':
+                // Find nearest ancestor scope (including self)
+                return findParentScope(el, true) ?? getLocalState(el);
+            case '$rootState':
+                // Deprecated: same as $state now (scoped state)
+                return findParentScope(el, true) ?? getLocalState(el);
+            case '$mode':
+                return Mode.CLIENT;
+            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}`);
+            }
+        }
+    });
+}
+/**
+ * Process directives on a single element.
+ * Returns a promise if any directive is async, otherwise void.
+ * Directives on the same element are processed sequentially to handle dependencies.
+ *
+ * @internal
+ */
+function processElement(el, registry) {
+    // Skip elements already processed by c-for (they have their own child scope)
+    if (el.hasAttribute(FOR_PROCESSED_ATTR)) {
+        return;
+    }
+    // Handle native <slot> elements
+    if (el.tagName === 'SLOT') {
+        processNativeSlot(el);
+        return;
+    }
+    const directives = getDirectivesForElement(el, registry);
+    if (directives.length === 0)
+        return;
+    const ctx = getContextForElement(el);
+    // Process directives sequentially, handling async ones properly
+    let chain;
+    for (const { directive, expr } of directives) {
+        const processDirective = () => {
+            const args = resolveDependencies(directive, expr, el, ctx);
+            const result = directive(...args);
+            // Register as provider if directive declares $context
+            if (directive.$context?.length) {
+                const state = getLocalState(el);
+                registerProvider(el, directive, state);
+            }
+            return result;
+        };
+        // STRUCTURAL directives (like c-for) take ownership of the element.
+        // They remove the original and handle other directives on clones themselves.
+        const isStructural = directive.priority === DirectivePriority.STRUCTURAL;
+        if (chain instanceof Promise) {
+            // Previous directive was async, chain this one after it
+            chain = chain.then(() => {
+                const result = processDirective();
+                return result instanceof Promise ? result : undefined;
+            });
+        }
+        else {
+            // Previous directive was sync (or this is the first)
+            const result = processDirective();
+            if (result instanceof Promise) {
+                chain = result;
+            }
+        }
+        if (isStructural) {
+            break;
+        }
+    }
+    return chain;
+}
+/**
+ * Process a node and its descendants for directives.
+ * Returns a promise that resolves when all async directives complete.
+ *
+ * @internal
+ */
+function processNode(node, selector, registry) {
+    const matches = node.matches?.(selector) ? [node] : [];
+    const descendants = [...(node.querySelectorAll?.(selector) ?? [])];
+    const promises = [];
+    for (const el of [...matches, ...descendants]) {
+        const result = processElement(el, registry);
+        if (result instanceof Promise) {
+            promises.push(result);
+        }
+    }
+    if (promises.length > 0) {
+        return Promise.all(promises).then(() => { });
+    }
+}
+/**
+ * Register a directive in the registry.
+ *
+ * @remarks
+ * If called after hydration, scans the DOM for any elements using
+ * this directive and processes them immediately.
+ *
+ * @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);
+    cachedSelector = null;
+    if (document.body && initialized) {
+        const selector = `[c-${name}]`;
+        for (const el of document.querySelectorAll(selector)) {
+            processElement(el, 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);
+}
+/**
+ * Initialize the client-side framework.
+ *
+ * @remarks
+ * Processes all existing elements with directive attributes, then
+ * sets up a MutationObserver to handle dynamically added elements.
+ * Works for both SSR hydration and pure client-side rendering.
+ *
+ * State is now scoped per custom element. Each element with `scope: true`
+ * creates its own state that child elements inherit via prototype chain.
+ *
+ * @param registry - The directive registry
+ *
+ * @example
+ * ```ts
+ * const registry = new Map();
+ * registry.set('text', textDirective);
+ *
+ * init(registry);
+ * ```
+ */
+/**
+ * Extract template attributes from an element.
+ *
+ * @internal
+ */
+function getTemplateAttrs(el) {
+    const attrs = {
+        children: el.innerHTML
+    };
+    for (const attr of el.attributes) {
+        attrs[attr.name] = attr.value;
+    }
+    return attrs;
+}
+/**
+ * Process custom element directives (those with templates).
+ * Directives with templates are web components and must be processed before
+ * attribute directives so their content is rendered first.
+ *
+ * Order for each element:
+ * 1. Create scope (if scope: true)
+ * 2. Call directive function (if fn exists) - initializes state
+ * 3. Render template with (props, state) - can use initialized state
+ * 4. Child directives are processed later by main hydration
+ *
+ * @internal
+ */
+async function processDirectiveElements() {
+    for (const name of getDirectiveNames()) {
+        const registration = getDirective(name);
+        if (!registration) {
+            continue;
+        }
+        const { fn, options } = registration;
+        // Only process directives with templates (web components),
+        // scope: true, or provide (DI overrides)
+        if (!options.template && !options.scope && !options.provide) {
+            continue;
+        }
+        // Find all elements matching this directive's tag name
+        const elements = document.querySelectorAll(name);
+        for (const el of elements) {
+            // Skip if already processed
+            if (getElementScope(el)) {
+                continue;
+            }
+            // 1. Create scope if needed
+            let scope = {};
+            if (options.scope) {
+                const parentScope = findParentScope(el);
+                scope = createElementScope(el, parentScope);
+            }
+            else {
+                scope = findParentScope(el, true) ?? {};
+            }
+            // 2. Register DI providers if present (for descendants)
+            if (options.provide) {
+                registerDIProviders(el, options.provide);
+            }
+            // 3. Call directive function if present (initializes state)
+            if (fn) {
+                const ctx = createContext(Mode.CLIENT, scope);
+                const inject = getInjectables(fn);
+                const args = inject.map((dep) => {
+                    switch (dep) {
+                        case '$element':
+                            return el;
+                        case '$state':
+                            return scope;
+                        case '$eval':
+                            return ctx.eval.bind(ctx);
+                        default:
+                            return undefined;
+                    }
+                });
+                const result = fn(...args);
+                if (result instanceof Promise) {
+                    await result;
+                }
+            }
+            // 4. Render template if present (can query DOM for <template> elements etc)
+            if (options.template) {
+                const attrs = getTemplateAttrs(el);
+                let html;
+                if (typeof options.template === 'string') {
+                    html = options.template;
+                }
+                else {
+                    const result = options.template(attrs, el);
+                    html = result instanceof Promise ? await result : result;
+                }
+                el.innerHTML = html;
+            }
+        }
+    }
+}
+export async function init(registry) {
+    const reg = registry ?? getDefaultRegistry();
+    cachedSelector = null;
+    // Process custom element directives first (those with templates or scope)
+    // This ensures templates are rendered and scopes exist before child directives run
+    await processDirectiveElements();
+    const selector = getSelector(reg);
+    // Process existing elements synchronously, collecting promises from async directives.
+    // Note: We collect elements first, but some may be removed during processing
+    // (e.g., c-for removes its template). Check isConnected before processing.
+    const elements = document.querySelectorAll(selector);
+    const promises = [];
+    for (const el of elements) {
+        if (!el.isConnected) {
+            continue;
+        }
+        const result = processElement(el, reg);
+        if (result instanceof Promise) {
+            promises.push(result);
+        }
+    }
+    // Wait for any async directives to complete
+    if (promises.length > 0) {
+        await Promise.all(promises);
+    }
+    // Set up MutationObserver for dynamic elements
+    const observer = new MutationObserver((mutations) => {
+        for (const mutation of mutations) {
+            for (const node of mutation.addedNodes) {
+                if (node.nodeType !== Node.ELEMENT_NODE)
+                    continue;
+                processNode(node, selector, reg);
+            }
+        }
+    });
+    observer.observe(document.body, { childList: true, subtree: true });
+    initialized = true;
+}
+/**
+ * Hydrate server-rendered HTML.
+ *
+ * @remarks
+ * Alias for {@link init}. Use when hydrating SSR output.
+ */
+export const hydrate = init;
+/**
+ * Mount the framework on client-rendered HTML.
+ *
+ * @remarks
+ * Alias for {@link init}. Use for pure client-side rendering.
+ */
+export const mount = init;

package/dist/client/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Client-side hydration and mounting utilities.
+ *
+ * @packageDocumentation
+ */
+export { init, hydrate, mount, registerDirective, setElementContext } from './hydrate.js';
+export type { DirectiveRegistry } from './hydrate.js';

package/dist/client/index.js

@@ -0,0 +1,6 @@
+/**
+ * Client-side hydration and mounting utilities.
+ *
+ * @packageDocumentation
+ */
+export { init, hydrate, mount, registerDirective, setElementContext } from './hydrate.js';

package/dist/context.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Context creation and management.
+ *
+ * @packageDocumentation
+ */
+import { Mode, Context } from './types.js';
+export type { Context };
+/**
+ * Create an evaluation context for directives.
+ *
+ * @remarks
+ * Uses {@link findRoots} to only access state keys that the expression
+ * actually references, enabling precise dependency tracking with the
+ * reactive system.
+ *
+ * Supports scoped values via `get()` for things like $component, $renderingChain.
+ * Create child contexts with `child()` for nested scopes.
+ *
+ * @param mode - Execution mode (server or client)
+ * @param state - The reactive state object
+ * @param scope - Optional scoped values (for context-specific data)
+ * @returns A new context
+ *
+ * @example
+ * ```ts
+ * const state = reactive({ user: { name: 'Alice' } });
+ * const ctx = createContext(Mode.CLIENT, state);
+ * ctx.eval('user.name' as Expression); // 'Alice'
+ *
+ * const childCtx = ctx.child({ $component: el });
+ * childCtx.get('$component'); // el
+ * ```
+ */
+export declare function createContext(mode: Mode, state: Record<string, unknown>, scope?: Record<string, unknown>): Context;
+/**
+ * Create a child context with additional bindings.
+ *
+ * @deprecated Use ctx.child() instead
+ */
+export declare function createChildContext(parent: Context, additions: Record<string, unknown>): Context;