gonia 0.3.4 → 0.3.6

package/README.md

@@ -4,9 +4,9 @@ A lightweight, SSR-first reactive UI library for building web applications with
 
 ## Features
 
-- **SSR-First Architecture** - Server-side rendering with seamless client hydration
-- **Declarative Directives** - Vue-inspired template syntax (`g-text`, `g-for`, `g-if`, etc.)
-- **Fine-Grained Reactivity** - Efficient updates without virtual DOM diffing
+- **[SSR-First Architecture](./docs/ssr.md)** - Server-side rendering with seamless client hydration
+- **[Declarative Directives](./docs/directives.md)** - Vue-inspired template syntax (`g-text`, `g-for`, `g-if`, etc.)
+- **[Fine-Grained Reactivity](./docs/reactivity.md)** - 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
 
@@ -55,6 +55,8 @@ hydrate();
 
 ### Creating a Component Directive
 
+Directives receive their dependencies through [dependency injection](./docs/directives.md#dependency-injection) — parameter names like `$element` and `$scope` tell the framework what to provide:
+
 ```typescript
 import { directive, Directive } from 'gonia';
 

package/dist/async.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Shared utilities for async directive handling.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Thrown by `$fallback()` to signal that the directive wants fallback rendering.
+ * The framework catches this at the directive execution boundary.
+ */
+export declare class FallbackSignal {
+    readonly isFallbackSignal = true;
+}
+/**
+ * Detect whether a function is async (declared with `async` keyword).
+ *
+ * @param fn - The function to check
+ * @returns true if fn is an AsyncFunction
+ */
+export declare function isAsyncFunction(fn: Function): boolean;
+/**
+ * Generate a unique ID for streaming placeholders.
+ *
+ * @returns A unique string ID like "g-async-0", "g-async-1", etc.
+ */
+export declare function generateAsyncId(): string;
+/**
+ * Reset the async ID counter. For testing only.
+ */
+export declare function resetAsyncIdCounter(): void;

package/dist/async.js

@@ -0,0 +1,37 @@
+/**
+ * Shared utilities for async directive handling.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Thrown by `$fallback()` to signal that the directive wants fallback rendering.
+ * The framework catches this at the directive execution boundary.
+ */
+export class FallbackSignal {
+    isFallbackSignal = true;
+}
+/**
+ * Detect whether a function is async (declared with `async` keyword).
+ *
+ * @param fn - The function to check
+ * @returns true if fn is an AsyncFunction
+ */
+export function isAsyncFunction(fn) {
+    return fn.constructor.name === 'AsyncFunction';
+}
+/** Counter for generating unique streaming IDs */
+let asyncIdCounter = 0;
+/**
+ * Generate a unique ID for streaming placeholders.
+ *
+ * @returns A unique string ID like "g-async-0", "g-async-1", etc.
+ */
+export function generateAsyncId() {
+    return `g-async-${asyncIdCounter++}`;
+}
+/**
+ * Reset the async ID counter. For testing only.
+ */
+export function resetAsyncIdCounter() {
+    asyncIdCounter = 0;
+}

package/dist/client/hydrate.js

@@ -4,6 +4,7 @@
  * @packageDocumentation
  */
 import { Mode, DirectivePriority, getDirective, getDirectiveNames } from '../types.js';
+import { isAsyncFunction, FallbackSignal } from '../async.js';
 import { createContext } from '../context.js';
 import { processNativeSlot } from '../directives/slot.js';
 import { getLocalState, registerProvider, registerDIProviders } from '../providers.js';
@@ -369,8 +370,8 @@ function getCustomElementSelector() {
         if (!registration)
             continue;
         const { options } = registration;
-        // Only include directives with templates, scope, provide, or using
-        if (options.template || options.scope || options.provide || options.using) {
+        // Only include directives with templates, scope, provide, using, or fallback
+        if (options.template || options.scope || options.provide || options.using || options.fallback) {
             selectors.push(name);
         }
     }
@@ -433,31 +434,148 @@ async function processDirectiveElements() {
         if (options.provide) {
             registerDIProviders(el, options.provide);
         }
-        // 3. Call directive function if present (initializes state)
-        if (fn) {
-            const ctx = createContext(Mode.CLIENT, scope);
-            const config = createClientResolverConfig(el, () => scope, services);
-            const args = resolveInjectables(fn, '', el, ctx.eval.bind(ctx), config, options.using);
-            const result = fn(...args);
-            if (result instanceof Promise) {
-                await result;
-            }
+        // Async directive handling
+        const fnIsAsync = fn && isAsyncFunction(fn);
+        const hasFallback = options.fallback !== undefined;
+        const asyncState = el.getAttribute('data-g-async');
+        if (fnIsAsync && hasFallback) {
+            await processAsyncDirectiveElement(el, fn, options, scope, asyncState);
         }
-        // 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 {
+            // 3. Call directive function if present (initializes state)
+            if (fn) {
+                const ctx = createContext(Mode.CLIENT, scope);
+                const config = createClientResolverConfig(el, () => scope, services);
+                const args = resolveInjectables(fn, '', el, ctx.eval.bind(ctx), config, options.using);
+                const result = fn(...args);
+                if (result instanceof Promise) {
+                    await result;
+                }
             }
-            else {
-                const result = options.template(attrs, el);
-                html = result instanceof Promise ? await result : result;
+            // 4. Render template if present (can query DOM for <template> elements etc)
+            if (options.template) {
+                if (el.hasAttribute('data-g-prerendered')) {
+                    el.removeAttribute('data-g-prerendered');
+                }
+                else {
+                    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;
+                }
             }
-            el.innerHTML = html;
         }
     }
 }
+/**
+ * Process an async directive element based on its SSR state.
+ *
+ * @internal
+ */
+async function processAsyncDirectiveElement(el, fn, options, scope, asyncState) {
+    const ctx = createContext(Mode.CLIENT, scope);
+    const config = createClientResolverConfig(el, () => scope, services);
+    const args = resolveInjectables(fn, '', el, ctx.eval.bind(ctx), config, options.using);
+    if (asyncState === 'loaded') {
+        // SSR already rendered the template — just run fn for reactivity setup
+        try {
+            await fn(...args);
+        }
+        catch (e) {
+            if (e instanceof FallbackSignal) {
+                await renderClientFallback(el, options);
+                el.setAttribute('data-g-async', 'pending');
+                return;
+            }
+        }
+        if (el.hasAttribute('data-g-prerendered')) {
+            el.removeAttribute('data-g-prerendered');
+        }
+        if (fn.$context?.length) {
+            const state = getLocalState(el);
+            registerProvider(el, fn, state);
+        }
+    }
+    else if (asyncState === 'pending' || asyncState === 'streaming' || asyncState === 'timeout') {
+        // SSR rendered fallback — run fn, swap to template on success
+        const ok = await runAsyncAndSwap(el, fn, args, options);
+        if (!ok)
+            return;
+        el.removeAttribute('data-g-async-id');
+    }
+    else {
+        // Pure client (no SSR attribute) — render fallback first, then swap
+        await renderClientFallback(el, options);
+        el.setAttribute('data-g-async', 'pending');
+        await runAsyncAndSwap(el, fn, args, options);
+    }
+}
+/**
+ * Run an async directive function, swap to template on success, and register provider.
+ * Returns false if the fn threw FallbackSignal or an error.
+ *
+ * @internal
+ */
+async function runAsyncAndSwap(el, fn, args, options) {
+    try {
+        await fn(...args);
+    }
+    catch (e) {
+        if (e instanceof FallbackSignal)
+            return false;
+        el.setAttribute('data-g-async', 'error');
+        return false;
+    }
+    await renderTemplateSwap(el, options);
+    el.setAttribute('data-g-async', 'loaded');
+    if (fn.$context?.length) {
+        const state = getLocalState(el);
+        registerProvider(el, fn, state);
+    }
+    return true;
+}
+/**
+ * Swap element content to its template.
+ *
+ * @internal
+ */
+async function renderTemplateSwap(el, options) {
+    if (!options.template)
+        return;
+    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;
+}
+/**
+ * Render fallback content for an async directive on the client.
+ *
+ * @internal
+ */
+async function renderClientFallback(el, options) {
+    if (!options.fallback)
+        return;
+    if (typeof options.fallback === 'string') {
+        el.innerHTML = options.fallback;
+    }
+    else {
+        const attrs = getTemplateAttrs(el);
+        const result = options.fallback(attrs, el);
+        el.innerHTML = result instanceof Promise ? await result : result;
+    }
+}
 export async function init(registry) {
     const reg = registry ?? getDefaultRegistry();
     cachedSelector = null;
@@ -498,6 +616,12 @@ export async function init(registry) {
         }
     });
     observer.observe(document.body, { childList: true, subtree: true });
+    // Streaming hydration hook: called by inline scripts from renderStream()
+    if (typeof window !== 'undefined') {
+        window.__gonia_hydrate = (el) => {
+            processNode(el, selector, reg);
+        };
+    }
     initialized = true;
 }
 /**

package/dist/directives/for.js

@@ -95,6 +95,27 @@ function removeSSRItems(templateEl) {
         sibling = next;
     }
 }
+/**
+ * Set up a reactive effect that re-renders loop items when dependencies change.
+ *
+ * @internal
+ */
+function setupReactiveLoop(templateContent, parent, templateWrapper, parsed, $eval, $scope) {
+    let renderedElements = [];
+    let scope = null;
+    effect(() => {
+        if (scope) {
+            scope.stop();
+        }
+        for (const el of renderedElements) {
+            el.remove();
+        }
+        scope = createEffectScope();
+        scope.run(() => {
+            renderedElements = renderItems(templateContent, parent, templateWrapper, parsed, $eval, $scope, Mode.CLIENT);
+        });
+    });
+}
 /**
  * Iterate over array or object items.
  *
@@ -154,21 +175,7 @@ export const cfor = function cfor($expr, $element, $eval, $scope, $mode) {
         }
         // Remove SSR-rendered items
         removeSSRItems(templateWrapper);
-        // Set up reactive loop
-        let renderedElements = [];
-        let scope = null;
-        effect(() => {
-            if (scope) {
-                scope.stop();
-            }
-            for (const el of renderedElements) {
-                el.remove();
-            }
-            scope = createEffectScope();
-            scope.run(() => {
-                renderedElements = renderItems(templateContent, parent, templateWrapper, parsed, $eval, $scope, Mode.CLIENT);
-            });
-        });
+        setupReactiveLoop(templateContent, parent, templateWrapper, parsed, $eval, $scope);
     }
     else {
         // Fresh client render: element has g-for attribute directly
@@ -179,21 +186,7 @@ export const cfor = function cfor($expr, $element, $eval, $scope, $mode) {
         templateContent.removeAttribute('g-for');
         templateWrapper.content.appendChild(templateContent);
         parent.replaceChild(templateWrapper, $element);
-        // Set up reactive loop
-        let renderedElements = [];
-        let scope = null;
-        effect(() => {
-            if (scope) {
-                scope.stop();
-            }
-            for (const el of renderedElements) {
-                el.remove();
-            }
-            scope = createEffectScope();
-            scope.run(() => {
-                renderedElements = renderItems(templateContent, parent, templateWrapper, parsed, $eval, $scope, Mode.CLIENT);
-            });
-        });
+        setupReactiveLoop(templateContent, parent, templateWrapper, parsed, $eval, $scope);
     }
 };
 cfor.$inject = ['$expr', '$element', '$eval', '$scope', '$mode'];

package/dist/index.d.ts

@@ -8,7 +8,8 @@
  * @packageDocumentation
  */
 export { Mode, Expression, Context, Directive, directive, getDirective, getDirectiveNames, clearDirectives, configureDirective } from './types.js';
-export type { DirectiveMeta } from './types.js';
+export type { DirectiveMeta, RenderOptions, FallbackOption } from './types.js';
+export { isAsyncFunction, FallbackSignal } from './async.js';
 export { createContext, createChildContext } from './context.js';
 export { reactive, effect, createScope, createEffectScope } from './reactivity.js';
 export type { EffectScope } from './reactivity.js';

package/dist/index.js

@@ -8,6 +8,7 @@
  * @packageDocumentation
  */
 export { Mode, directive, getDirective, getDirectiveNames, clearDirectives, configureDirective } from './types.js';
+export { isAsyncFunction, FallbackSignal } from './async.js';
 export { createContext, createChildContext } from './context.js';
 export { reactive, effect, createScope, createEffectScope } from './reactivity.js';
 export { createTemplateRegistry, createMemoryRegistry, createServerRegistry } from './templates.js';

package/dist/inject.js

@@ -11,6 +11,7 @@
  *
  * @packageDocumentation
  */
+import { FallbackSignal } from './async.js';
 /**
  * Check if a value is a ContextKey.
  */
@@ -87,6 +88,12 @@ function parseFunctionParams(fn) {
 export function resolveDependencies(fn, expr, element, evalFn, config, using) {
     const inject = getInjectables(fn);
     const args = inject.map(dep => {
+        if (dep.startsWith('_')) {
+            if (process.env.NODE_ENV !== 'production') {
+                console.warn(`Injectable '${dep}' starts with underscore — passing undefined.`);
+            }
+            return undefined;
+        }
         switch (dep) {
             case '$expr':
                 return expr;
@@ -100,6 +107,8 @@ export function resolveDependencies(fn, expr, element, evalFn, config, using) {
                 return config.resolveRootState?.() ?? config.resolveState();
             case '$mode':
                 return config.mode;
+            case '$fallback':
+                return () => { throw new FallbackSignal(); };
             default: {
                 // Look up in custom resolver (services, providers, etc.)
                 if (config.resolveCustom) {

package/dist/scope.js

@@ -109,6 +109,8 @@ export function removeElementScope(el) {
 export function registerDirectiveElement(name, 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 fn, options) {
+    if (typeof customElements === 'undefined')
+        return;
     // Don't re-register if already defined
     if (customElements.get(name)) {
         return;

package/dist/server/async-render.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Async directive rendering utilities for server-side rendering.
+ *
+ * @packageDocumentation
+ */
+import { Directive, Expression, FallbackOption } from '../types.js';
+import { ContextKey } from '../context-registry.js';
+/**
+ * A pending stream chunk for async directives in stream mode.
+ * Used by renderStream() to emit replacement scripts after initial HTML.
+ *
+ * @internal
+ */
+export interface StreamPendingChunk {
+    asyncId: string;
+    el: Element;
+    fn: Directive;
+    options: {
+        template?: FallbackOption;
+        [key: string]: unknown;
+    };
+    scopeState: Record<string, unknown>;
+    rootState: Record<string, unknown>;
+    expr: Expression;
+    using?: ContextKey<unknown>[];
+}
+/**
+ * Get the nesting depth of an async directive by walking up the DOM.
+ *
+ * @internal
+ */
+export declare function getAsyncDepth(el: Element, depthMap: WeakMap<Element, number>): number;
+/**
+ * Render fallback content for an async directive.
+ *
+ * @internal
+ */
+export declare function renderFallback(el: Element, fallback: FallbackOption, options: {
+    template?: unknown;
+    [key: string]: unknown;
+}, ssrMode: string, streamCtx?: {
+    fn: Directive;
+    scopeState: Record<string, unknown>;
+    rootState: Record<string, unknown>;
+    expr: Expression;
+    using?: ContextKey<unknown>[];
+    streamPending: StreamPendingChunk[];
+}): Promise<void>;

package/dist/server/async-render.js

@@ -0,0 +1,60 @@
+/**
+ * Async directive rendering utilities for server-side rendering.
+ *
+ * @packageDocumentation
+ */
+import { getTemplateAttrs } from '../template-utils.js';
+import { generateAsyncId } from '../async.js';
+/**
+ * Get the nesting depth of an async directive by walking up the DOM.
+ *
+ * @internal
+ */
+export function getAsyncDepth(el, depthMap) {
+    let current = el.parentElement;
+    while (current) {
+        const depth = depthMap.get(current);
+        if (depth !== undefined) {
+            return depth;
+        }
+        current = current.parentElement;
+    }
+    return 0;
+}
+/**
+ * Render fallback content for an async directive.
+ *
+ * @internal
+ */
+export async function renderFallback(el, fallback, options, ssrMode, streamCtx) {
+    let fallbackHtml;
+    if (typeof fallback === 'string') {
+        fallbackHtml = fallback;
+    }
+    else {
+        const attrs = getTemplateAttrs(el);
+        const result = fallback(attrs, el);
+        fallbackHtml = result instanceof Promise ? await result : result;
+    }
+    el.innerHTML = fallbackHtml;
+    if (ssrMode === 'stream') {
+        const asyncId = generateAsyncId();
+        el.setAttribute('data-g-async', 'streaming');
+        el.setAttribute('data-g-async-id', asyncId);
+        if (streamCtx) {
+            streamCtx.streamPending.push({
+                asyncId,
+                el,
+                fn: streamCtx.fn,
+                options: options,
+                scopeState: streamCtx.scopeState,
+                rootState: streamCtx.rootState,
+                expr: streamCtx.expr,
+                using: streamCtx.using,
+            });
+        }
+    }
+    else {
+        el.setAttribute('data-g-async', 'pending');
+    }
+}

package/dist/server/index-tree.d.ts

@@ -0,0 +1,45 @@
+/**
+ * DOM tree indexing for server-side directive discovery.
+ *
+ * @packageDocumentation
+ */
+import { Expression, Directive } from '../types.js';
+import { ContextKey } from '../context-registry.js';
+import type { DirectiveRegistry } from './render.js';
+/**
+ * An indexed directive instance found in the DOM.
+ *
+ * @internal
+ */
+export interface IndexedDirective {
+    el: Element;
+    name: string;
+    directive: Directive | null;
+    expr: Expression;
+    priority: number;
+    isNativeSlot?: boolean;
+    isCustomElement?: boolean;
+    using?: ContextKey<unknown>[];
+}
+/**
+ * Build a CSS selector for all registered directives.
+ * Uses the global directive registry to support any prefix (g-, l-, v-, etc.).
+ * Also includes local registry entries with g- prefix for backward compatibility.
+ *
+ * @internal
+ */
+export declare function getSelector(localRegistry?: DirectiveRegistry): string;
+/**
+ * Index all directive elements in a subtree.
+ * Discovers elements matching the selector and builds an ordered list
+ * of directives to process.
+ *
+ * @param root - The DOM subtree root to scan
+ * @param selector - CSS selector matching directive elements
+ * @param registry - Local directive registry for backward compatibility
+ * @param index - Accumulator for discovered directives (mutated in place)
+ * @param indexed - Set tracking already-indexed elements (mutated in place)
+ *
+ * @internal
+ */
+export declare function indexTree(root: any, selector: string, registry: DirectiveRegistry, index: IndexedDirective[], indexed: Set<Element>): void;