gonia 0.1.2 → 0.2.0

package/dist/inject.d.ts

@@ -11,11 +11,21 @@
  *
  * @packageDocumentation
  */
+import type { ContextKey } from './context-registry.js';
+import type { Expression, EvalFn } from './types.js';
+/**
+ * An injectable dependency - either a string name or a typed context key.
+ */
+export type Injectable = string | ContextKey<unknown>;
+/**
+ * Check if a value is a ContextKey.
+ */
+export declare function isContextKey(value: unknown): value is ContextKey<unknown>;
 /**
  * A function with optional `$inject` annotation.
  */
 interface InjectableFunction extends Function {
-    $inject?: readonly string[];
+    $inject?: readonly Injectable[];
 }
 /**
  * Get the list of injectable dependencies for a function.
@@ -25,7 +35,7 @@ interface InjectableFunction extends Function {
  * In production, always use `$inject` to survive minification.
  *
  * @param fn - The function to inspect
- * @returns Array of dependency names
+ * @returns Array of dependency names or context keys
  *
  * @example
  * ```ts
@@ -33,10 +43,41 @@ interface InjectableFunction extends Function {
  * const myDirective = (expr, ctx, el, http, userService) => {};
  * getInjectables(myDirective); // ['expr', 'ctx', 'el', 'http', 'userService']
  *
- * // Production - explicit annotation
- * myDirective.$inject = ['http', 'userService'];
- * getInjectables(myDirective); // ['http', 'userService']
+ * // Production - explicit annotation with context keys
+ * myDirective.$inject = ['$element', SlotContentContext];
+ * getInjectables(myDirective); // ['$element', SlotContentContext]
  * ```
  */
-export declare function getInjectables(fn: InjectableFunction): string[];
+export declare function getInjectables(fn: InjectableFunction): Injectable[];
+/**
+ * Configuration for dependency resolution.
+ */
+export interface DependencyResolverConfig {
+    /** Resolve a ContextKey to its value */
+    resolveContext: (key: ContextKey<unknown>) => unknown;
+    /** Resolve $scope injectable */
+    resolveState: () => Record<string, unknown>;
+    /** Resolve $rootState injectable (may be same as state) */
+    resolveRootState?: () => Record<string, unknown>;
+    /** Resolve custom injectable by name (services, providers) */
+    resolveCustom?: (name: string) => unknown | undefined;
+    /** Current mode */
+    mode: 'server' | 'client';
+}
+/**
+ * Resolve dependencies for a directive function.
+ *
+ * @remarks
+ * Unified dependency resolution used by both client and server.
+ * Handles $inject arrays, ContextKey injection, and the `using` option.
+ *
+ * @param fn - The directive function (with optional $inject)
+ * @param expr - The expression string from the directive attribute
+ * @param element - The target DOM element
+ * @param evalFn - Function to evaluate expressions
+ * @param config - Resolution configuration
+ * @param using - Optional array of context keys to append
+ * @returns Array of resolved dependency values
+ */
+export declare function resolveDependencies(fn: InjectableFunction, expr: Expression | string, element: Element, evalFn: EvalFn, config: DependencyResolverConfig, using?: ContextKey<unknown>[]): unknown[];
 export {};

package/dist/inject.js

@@ -11,6 +11,12 @@
  *
  * @packageDocumentation
  */
+/**
+ * Check if a value is a ContextKey.
+ */
+export function isContextKey(value) {
+    return typeof value === 'object' && value !== null && 'id' in value && typeof value.id === 'symbol';
+}
 /**
  * Get the list of injectable dependencies for a function.
  *
@@ -19,7 +25,7 @@
  * In production, always use `$inject` to survive minification.
  *
  * @param fn - The function to inspect
- * @returns Array of dependency names
+ * @returns Array of dependency names or context keys
  *
  * @example
  * ```ts
@@ -27,9 +33,9 @@
  * const myDirective = (expr, ctx, el, http, userService) => {};
  * getInjectables(myDirective); // ['expr', 'ctx', 'el', 'http', 'userService']
  *
- * // Production - explicit annotation
- * myDirective.$inject = ['http', 'userService'];
- * getInjectables(myDirective); // ['http', 'userService']
+ * // Production - explicit annotation with context keys
+ * myDirective.$inject = ['$element', SlotContentContext];
+ * getInjectables(myDirective); // ['$element', SlotContentContext]
  * ```
  */
 export function getInjectables(fn) {
@@ -61,3 +67,59 @@ function parseFunctionParams(fn) {
         .map(p => p.replace(/\s*=.*$/, ''))
         .filter(Boolean);
 }
+/**
+ * Resolve dependencies for a directive function.
+ *
+ * @remarks
+ * Unified dependency resolution used by both client and server.
+ * Handles $inject arrays, ContextKey injection, and the `using` option.
+ *
+ * @param fn - The directive function (with optional $inject)
+ * @param expr - The expression string from the directive attribute
+ * @param element - The target DOM element
+ * @param evalFn - Function to evaluate expressions
+ * @param config - Resolution configuration
+ * @param using - Optional array of context keys to append
+ * @returns Array of resolved dependency values
+ */
+export function resolveDependencies(fn, expr, element, evalFn, config, using) {
+    const inject = getInjectables(fn);
+    const args = inject.map(dep => {
+        // Handle ContextKey injection
+        if (isContextKey(dep)) {
+            return config.resolveContext(dep);
+        }
+        // Handle string-based injection
+        switch (dep) {
+            case '$expr':
+                return expr;
+            case '$element':
+                return element;
+            case '$eval':
+                return evalFn;
+            case '$scope':
+                return config.resolveState();
+            case '$rootState':
+                return config.resolveRootState?.() ?? config.resolveState();
+            case '$mode':
+                return config.mode;
+            default: {
+                // Look up in custom resolver (services, providers, etc.)
+                if (config.resolveCustom) {
+                    const resolved = config.resolveCustom(dep);
+                    if (resolved !== undefined) {
+                        return resolved;
+                    }
+                }
+                throw new Error(`Unknown injectable: ${dep}`);
+            }
+        }
+    });
+    // Append contexts from `using` option
+    if (using?.length) {
+        for (const key of using) {
+            args.push(config.resolveContext(key));
+        }
+    }
+    return args;
+}

package/dist/process.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Shared element processing for structural directives.
+ *
+ * @remarks
+ * Provides a unified way to process directives on elements created by
+ * structural directives like g-if and g-for. Supports scope reuse for
+ * state preservation across re-renders.
+ *
+ * @packageDocumentation
+ */
+import { Mode } from './types.js';
+/** Attribute used to mark elements processed by structural directives */
+export declare const PROCESSED_ATTR = "data-g-processed";
+/**
+ * Options for processing element directives.
+ */
+export interface ProcessOptions {
+    /**
+     * Existing scope to use instead of creating a new one.
+     * Use this to preserve state across re-renders (e.g., g-if toggle).
+     */
+    existingScope?: Record<string, unknown>;
+    /**
+     * Additional properties to add to the scope.
+     * Used by g-for to add item/index variables.
+     */
+    scopeAdditions?: Record<string, unknown>;
+    /**
+     * Skip processing structural directives (g-for, g-if).
+     * Set to true when processing content inside a structural directive
+     * to avoid infinite recursion.
+     */
+    skipStructural?: boolean;
+}
+/**
+ * Process directives on an element using registered directives.
+ *
+ * @remarks
+ * This processes all non-structural directives (g-text, g-class, g-show, g-on, etc.)
+ * on an element. For structural directives, use the directives directly.
+ *
+ * @param el - The element to process
+ * @param parentScope - The parent scope for variable resolution
+ * @param mode - Server or client mode
+ * @param options - Processing options
+ * @returns The scope used for this element (for chaining/children)
+ */
+export declare function processElementDirectives(el: Element, parentScope: Record<string, unknown>, mode: Mode, options?: ProcessOptions): Record<string, unknown>;
+/**
+ * Process an element tree (element and all descendants).
+ *
+ * @remarks
+ * Recursively processes directives on an element and all its children.
+ * Each child gets its own scope that inherits from the parent.
+ *
+ * @param el - The root element to process
+ * @param parentScope - The parent scope
+ * @param mode - Server or client mode
+ * @param options - Processing options (existingScope only applies to root element)
+ */
+export declare function processElementTree(el: Element, parentScope: Record<string, unknown>, mode: Mode, options?: ProcessOptions): void;

package/dist/process.js

@@ -0,0 +1,215 @@
+/**
+ * Shared element processing for structural directives.
+ *
+ * @remarks
+ * Provides a unified way to process directives on elements created by
+ * structural directives like g-if and g-for. Supports scope reuse for
+ * state preservation across re-renders.
+ *
+ * @packageDocumentation
+ */
+import { Mode, getDirective } from './types.js';
+import { createContext } from './context.js';
+import { createScope, effect } from './reactivity.js';
+import { resolveDependencies } from './inject.js';
+import { resolveContext } from './context-registry.js';
+import { resolveFromProviders, resolveFromDIProviders } from './providers.js';
+/** Attribute used to mark elements processed by structural directives */
+export const PROCESSED_ATTR = 'data-g-processed';
+/**
+ * Create resolver config for dependency resolution.
+ *
+ * @internal
+ */
+function createResolverConfig(el, scope, mode) {
+    return {
+        resolveContext: (key) => resolveContext(el, key),
+        resolveState: () => scope,
+        resolveRootState: () => scope,
+        resolveCustom: (name) => {
+            const diProvided = resolveFromDIProviders(el, name);
+            if (diProvided !== undefined)
+                return diProvided;
+            return resolveFromProviders(el, name);
+        },
+        mode: mode === Mode.SERVER ? 'server' : 'client'
+    };
+}
+/**
+ * Set up an event handler on an element.
+ *
+ * @internal
+ */
+function setupEventHandler(el, expr, ctx, scope) {
+    const colonIdx = expr.indexOf(':');
+    if (colonIdx === -1) {
+        return;
+    }
+    const eventName = expr.slice(0, colonIdx).trim();
+    const handlerExpr = expr.slice(colonIdx + 1).trim();
+    el.addEventListener(eventName, (event) => {
+        const result = ctx.eval(handlerExpr);
+        if (typeof result === 'function') {
+            result.call(scope, event);
+        }
+    });
+}
+/**
+ * Process directives on an element using registered directives.
+ *
+ * @remarks
+ * This processes all non-structural directives (g-text, g-class, g-show, g-on, etc.)
+ * on an element. For structural directives, use the directives directly.
+ *
+ * @param el - The element to process
+ * @param parentScope - The parent scope for variable resolution
+ * @param mode - Server or client mode
+ * @param options - Processing options
+ * @returns The scope used for this element (for chaining/children)
+ */
+export function processElementDirectives(el, parentScope, mode, options = {}) {
+    const { existingScope, scopeAdditions = {}, skipStructural = true } = options;
+    // Mark element as processed
+    el.setAttribute(PROCESSED_ATTR, '');
+    // Use existing scope or create a new child scope
+    const scope = existingScope
+        ? (Object.keys(scopeAdditions).length > 0
+            ? createScope(existingScope, scopeAdditions)
+            : existingScope)
+        : createScope(parentScope, scopeAdditions);
+    const ctx = createContext(mode, scope);
+    // Process g-scope (inline scope initialization)
+    const scopeAttr = el.getAttribute('g-scope');
+    if (scopeAttr) {
+        const scopeValues = ctx.eval(scopeAttr);
+        if (scopeValues && typeof scopeValues === 'object') {
+            Object.assign(scope, scopeValues);
+        }
+    }
+    // Process g-text
+    const textAttr = el.getAttribute('g-text');
+    if (textAttr) {
+        if (mode === Mode.CLIENT) {
+            effect(() => {
+                const value = ctx.eval(textAttr);
+                el.textContent = String(value ?? '');
+            });
+        }
+        else {
+            const value = ctx.eval(textAttr);
+            el.textContent = String(value ?? '');
+        }
+    }
+    // Process g-class
+    const classAttr = el.getAttribute('g-class');
+    if (classAttr) {
+        const applyClasses = () => {
+            const classObj = ctx.eval(classAttr);
+            if (classObj && typeof classObj === 'object') {
+                for (const [className, shouldAdd] of Object.entries(classObj)) {
+                    if (shouldAdd) {
+                        el.classList.add(className);
+                    }
+                    else {
+                        el.classList.remove(className);
+                    }
+                }
+            }
+        };
+        if (mode === Mode.CLIENT) {
+            effect(applyClasses);
+        }
+        else {
+            applyClasses();
+        }
+    }
+    // Process g-show
+    const showAttr = el.getAttribute('g-show');
+    if (showAttr) {
+        const applyShow = () => {
+            const value = ctx.eval(showAttr);
+            el.style.display = value ? '' : 'none';
+        };
+        if (mode === Mode.CLIENT) {
+            effect(applyShow);
+        }
+        else {
+            applyShow();
+        }
+    }
+    // Process g-on (client only)
+    if (mode === Mode.CLIENT) {
+        const onAttr = el.getAttribute('g-on');
+        if (onAttr) {
+            setupEventHandler(el, onAttr, ctx, scope);
+        }
+    }
+    // Process g-model (client only)
+    if (mode === Mode.CLIENT) {
+        const modelAttr = el.getAttribute('g-model');
+        if (modelAttr) {
+            const registration = getDirective('g-model');
+            if (registration?.fn) {
+                const config = createResolverConfig(el, scope, mode);
+                const args = resolveDependencies(registration.fn, modelAttr, el, ctx.eval.bind(ctx), config, registration.options.using);
+                registration.fn(...args);
+            }
+        }
+    }
+    // Process g-html
+    const htmlAttr = el.getAttribute('g-html');
+    if (htmlAttr) {
+        const applyHtml = () => {
+            const value = ctx.eval(htmlAttr);
+            el.innerHTML = String(value ?? '');
+        };
+        if (mode === Mode.CLIENT) {
+            effect(applyHtml);
+        }
+        else {
+            applyHtml();
+        }
+    }
+    // Process g-bind:* attributes
+    const bindAttrs = [...el.attributes].filter(a => a.name.startsWith('g-bind:'));
+    for (const attr of bindAttrs) {
+        const targetAttr = attr.name.slice('g-bind:'.length);
+        const valueExpr = attr.value;
+        const applyBinding = () => {
+            const value = ctx.eval(valueExpr);
+            if (value === null || value === undefined) {
+                el.removeAttribute(targetAttr);
+            }
+            else {
+                el.setAttribute(targetAttr, String(value));
+            }
+        };
+        if (mode === Mode.CLIENT) {
+            effect(applyBinding);
+        }
+        else {
+            applyBinding();
+        }
+    }
+    return scope;
+}
+/**
+ * Process an element tree (element and all descendants).
+ *
+ * @remarks
+ * Recursively processes directives on an element and all its children.
+ * Each child gets its own scope that inherits from the parent.
+ *
+ * @param el - The root element to process
+ * @param parentScope - The parent scope
+ * @param mode - Server or client mode
+ * @param options - Processing options (existingScope only applies to root element)
+ */
+export function processElementTree(el, parentScope, mode, options = {}) {
+    // Process the root element
+    const scope = processElementDirectives(el, parentScope, mode, options);
+    // Process children recursively (they get fresh child scopes)
+    for (const child of el.children) {
+        processElementTree(child, scope, mode, { skipStructural: true });
+    }
+}

package/dist/providers.js

@@ -4,6 +4,7 @@
  * @packageDocumentation
  */
 import { reactive } from './reactivity.js';
+import { findAncestor } from './dom.js';
 /**
  * Local state stored per element.
  *
@@ -83,15 +84,13 @@ export function registerDIProviders(el, provideMap) {
  * @internal
  */
 export function resolveFromDIProviders(el, name) {
-    let current = el.parentElement;
-    while (current) {
-        const provideMap = diProviders.get(current);
+    return findAncestor(el, (e) => {
+        const provideMap = diProviders.get(e);
         if (provideMap && name in provideMap) {
             return provideMap[name];
         }
-        current = current.parentElement;
-    }
-    return undefined;
+        return undefined;
+    });
 }
 /**
  * Resolve a context value from ancestor elements.
@@ -107,15 +106,13 @@ export function resolveFromDIProviders(el, name) {
  * @internal
  */
 export function resolveFromProviders(el, name) {
-    let current = el.parentElement;
-    while (current) {
-        const info = contextProviders.get(current);
+    return findAncestor(el, (e) => {
+        const info = contextProviders.get(e);
         if (info?.directive.$context?.includes(name)) {
             return info.state;
         }
-        current = current.parentElement;
-    }
-    return undefined;
+        return undefined;
+    });
 }
 /**
  * Clear local state for an element.

package/dist/scope.js

@@ -6,7 +6,9 @@
 import { reactive } from './reactivity.js';
 import { createContext } from './context.js';
 import { Mode } from './types.js';
-import { getInjectables } from './inject.js';
+import { resolveDependencies } from './inject.js';
+import { findAncestor } from './dom.js';
+import { resolveContext } from './context-registry.js';
 /** WeakMap to store element scopes */
 const elementScopes = new WeakMap();
 /** Root scope for top-level directives without explicit parent scope */
@@ -73,13 +75,9 @@ export function getElementScope(el) {
  * @returns The nearest scope, or root scope if none found and fallback enabled
  */
 export function findParentScope(el, includeSelf = false, useRootFallback = true) {
-    let current = includeSelf ? el : el.parentElement;
-    while (current) {
-        const scope = elementScopes.get(current);
-        if (scope) {
-            return scope;
-        }
-        current = current.parentElement;
+    const scope = findAncestor(el, (e) => elementScopes.get(e), includeSelf);
+    if (scope) {
+        return scope;
     }
     // Fall back to root scope for top-level directives
     return useRootFallback ? getRootScope() : undefined;
@@ -112,22 +110,19 @@ fn, options) {
             const parentScope = findParentScope(this);
             // Create this element's scope
             const scope = createElementScope(this, parentScope);
+            // Apply assigned values to scope
+            if (options.assign) {
+                Object.assign(scope, options.assign);
+            }
             // 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;
-                }
-            });
+            // Resolve dependencies using shared resolver
+            const config = {
+                resolveContext: (key) => resolveContext(this, key),
+                resolveState: () => scope,
+                mode: 'client'
+            };
+            const args = resolveDependencies(fn, '', this, ctx.eval.bind(ctx), config, options.using);
             const result = fn(...args);
             // Handle async directives
             if (result instanceof Promise) {