gonia 0.1.2 → 0.1.3

package/dist/index.d.ts

@@ -7,7 +7,7 @@
  *
  * @packageDocumentation
  */
-export { Mode, Expression, Context, Directive, directive, getDirective, getDirectiveNames, clearDirectives } from './types.js';
+export { Mode, Expression, Context, Directive, directive, getDirective, getDirectiveNames, clearDirectives, configureDirective } from './types.js';
 export type { DirectiveMeta } from './types.js';
 export { createContext, createChildContext } from './context.js';
 export { reactive, effect, createScope, createEffectScope } from './reactivity.js';
@@ -15,6 +15,10 @@ export type { EffectScope } from './reactivity.js';
 export { createTemplateRegistry, createMemoryRegistry, createServerRegistry } from './templates.js';
 export type { TemplateRegistry } from './templates.js';
 export { findRoots, parseInterpolation } from './expression.js';
-export { getInjectables } from './inject.js';
+export { getInjectables, isContextKey } from './inject.js';
+export type { Injectable } from './inject.js';
 export { getRootScope, clearRootScope } from './scope.js';
+export { findAncestor } from './dom.js';
+export { createContextKey, registerContext, resolveContext, hasContext, removeContext, clearContexts } from './context-registry.js';
+export type { ContextKey } from './context-registry.js';
 export * as directives from './directives/index.js';

package/dist/index.js

@@ -7,11 +7,13 @@
  *
  * @packageDocumentation
  */
-export { Mode, directive, getDirective, getDirectiveNames, clearDirectives } from './types.js';
+export { Mode, directive, getDirective, getDirectiveNames, clearDirectives, configureDirective } from './types.js';
 export { createContext, createChildContext } from './context.js';
 export { reactive, effect, createScope, createEffectScope } from './reactivity.js';
 export { createTemplateRegistry, createMemoryRegistry, createServerRegistry } from './templates.js';
 export { findRoots, parseInterpolation } from './expression.js';
-export { getInjectables } from './inject.js';
+export { getInjectables, isContextKey } from './inject.js';
 export { getRootScope, clearRootScope } from './scope.js';
+export { findAncestor } from './dom.js';
+export { createContextKey, registerContext, resolveContext, hasContext, removeContext, clearContexts } from './context-registry.js';
 export * as directives from './directives/index.js';

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 $state 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 '$state':
+                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/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;
@@ -114,20 +112,13 @@ fn, options) {
             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;
-                }
-            });
+            // 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) {

package/dist/server/render.js

@@ -4,12 +4,14 @@
  * @packageDocumentation
  */
 import { parseHTML } from 'linkedom';
-import { Mode, DirectivePriority } from '../types.js';
+import { Mode, DirectivePriority, getDirective } 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';
+import { resolveDependencies as resolveInjectables } from '../inject.js';
+import { resolveContext } from '../context-registry.js';
 /** Registered services */
 let services = new Map();
 const selectorCache = new WeakMap();
@@ -53,46 +55,29 @@ export function registerService(name, service) {
     services.set(name, service);
 }
 /**
- * Resolve dependencies for a directive based on its $inject array.
+ * Create resolver config for server-side dependency resolution.
  *
  * @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}`);
-            }
-        }
-    });
+function createServerResolverConfig(el, rootState) {
+    return {
+        resolveContext: (key) => resolveContext(el, key),
+        resolveState: () => getLocalState(el) ?? rootState,
+        resolveRootState: () => rootState,
+        resolveCustom: (name) => {
+            // 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)
+            return resolveFromProviders(el, name);
+        },
+        mode: 'server'
+    };
 }
 /**
  * Render HTML with directives on the server.
@@ -150,12 +135,15 @@ export async function render(html, state, registry) {
                     for (const [name, directive] of registry) {
                         const attr = match.getAttribute(`g-${name}`);
                         if (attr !== null) {
+                            // Look up options from the global directive registry
+                            const registration = getDirective(`g-${name}`);
                             index.push({
                                 el: match,
                                 name,
                                 directive,
                                 expr: attr,
-                                priority: directive.priority ?? DirectivePriority.NORMAL
+                                priority: directive.priority ?? DirectivePriority.NORMAL,
+                                using: registration?.options.using
                             });
                         }
                     }
@@ -225,7 +213,8 @@ export async function render(html, state, registry) {
                     processNativeSlot(item.el);
                 }
                 else {
-                    const args = resolveDependencies(item.directive, item.expr, item.el, ctx, state);
+                    const config = createServerResolverConfig(item.el, state);
+                    const args = resolveInjectables(item.directive, item.expr, item.el, ctx.eval.bind(ctx), config, item.using);
                     await item.directive(...args);
                     // Register as context provider if directive declares $context
                     if (item.directive.$context?.length) {

package/dist/types.d.ts

@@ -3,6 +3,8 @@
  *
  * @packageDocumentation
  */
+import type { ContextKey } from './context-registry.js';
+import type { Injectable } from './inject.js';
 /**
  * Execution mode for the framework.
  */
@@ -59,9 +61,13 @@ export interface InjectableRegistry {
     $mode: Mode;
 }
 /**
- * Maps a tuple of injectable names to their corresponding types.
+ * Extract the value type from a ContextKey.
+ */
+type ContextKeyValue<K> = K extends ContextKey<infer V> ? V : never;
+/**
+ * Maps a tuple of injectable names or context keys to their corresponding types.
  *
- * @typeParam K - Tuple of injectable name strings
+ * @typeParam K - Tuple of injectable names (strings) or ContextKey objects
  * @typeParam T - Type map (defaults to InjectableRegistry)
  *
  * @example
@@ -69,13 +75,14 @@ export interface InjectableRegistry {
  * type Args = MapInjectables<['$element', '$state']>;
  * // => [Element, Record<string, unknown>]
  *
- * // With custom type map
- * type Args2 = MapInjectables<['$element', 'custom'], { $element: Element; custom: MyType }>;
- * // => [Element, MyType]
+ * // With context keys
+ * const MyContext = createContextKey<{ value: number }>('MyContext');
+ * type Args2 = MapInjectables<['$element', typeof MyContext]>;
+ * // => [Element, { value: number }]
  * ```
  */
-export type MapInjectables<K extends readonly string[], T = InjectableRegistry> = {
-    [I in keyof K]: K[I] extends keyof T ? T[K[I]] : unknown;
+export type MapInjectables<K extends readonly (string | ContextKey<unknown>)[], T = InjectableRegistry> = {
+    [I in keyof K]: K[I] extends ContextKey<unknown> ? ContextKeyValue<K[I]> : K[I] extends keyof T ? T[K[I]] : unknown;
 };
 /**
  * Evaluation context passed to directives.
@@ -148,9 +155,19 @@ export interface DirectiveMeta<T = InjectableRegistry> {
      * - `$eval`: Function to evaluate expressions: `(expr) => value`
      * - `$state`: Local reactive state object (isolated per element)
      * - Any registered service names
+     * - Any `ContextKey` for typed context resolution
      * - Any names provided by ancestor directives via `$context`
+     *
+     * @example
+     * ```ts
+     * // String-based injection
+     * myDirective.$inject = ['$element', '$state'];
+     *
+     * // With typed context keys
+     * myDirective.$inject = ['$element', SlotContentContext];
+     * ```
      */
-    $inject?: readonly string[];
+    $inject?: readonly Injectable[];
     /**
      * Names this directive exposes as context to descendants.
      *
@@ -187,9 +204,9 @@ export interface DirectiveMeta<T = InjectableRegistry> {
  *
  * @remarks
  * Use this type annotation to get contextual typing for directive parameters.
- * The tuple of keys maps to parameter types from InjectableRegistry.
+ * The tuple of keys maps to parameter types from InjectableRegistry or ContextKey types.
  *
- * @typeParam K - Tuple of injectable key names
+ * @typeParam K - Tuple of injectable key names or ContextKey objects
  * @typeParam T - Optional custom type map to extend InjectableRegistry
  *
  * @example
@@ -204,6 +221,12 @@ export interface DirectiveMeta<T = InjectableRegistry> {
  *   $element.textContent = String($eval($expr) ?? '');
  * };
  *
+ * // With typed context keys
+ * const slot: Directive<['$element', typeof SlotContentContext]> = ($element, content) => {
+ *   // content is typed as SlotContent
+ *   console.log(content.slots);
+ * };
+ *
  * // With custom types (extend InjectableRegistry first)
  * declare module 'gonia' {
  *   interface InjectableRegistry {
@@ -215,7 +238,7 @@ export interface DirectiveMeta<T = InjectableRegistry> {
  * };
  * ```
  */
-export type Directive<K extends readonly (string & keyof (InjectableRegistry & T))[] = readonly (string & keyof InjectableRegistry)[], T extends Record<string, unknown> = {}> = ((...args: MapInjectables<K, InjectableRegistry & T>) => void | Promise<void>) & DirectiveMeta<InjectableRegistry & T>;
+export type Directive<K extends readonly (string | ContextKey<unknown>)[] = readonly (string & keyof InjectableRegistry)[], T extends Record<string, unknown> = {}> = ((...args: MapInjectables<K, InjectableRegistry & T>) => void | Promise<void>) & DirectiveMeta<InjectableRegistry & T>;
 /**
  * Attributes passed to template functions.
  */
@@ -297,6 +320,34 @@ export interface DirectiveOptions {
      * ```
      */
     provide?: Record<string, unknown>;
+    /**
+     * Context keys this directive uses.
+     *
+     * @remarks
+     * Declares which contexts the directive depends on. The resolved
+     * context values are appended to the directive function parameters
+     * in the order they appear in this array.
+     *
+     * This enables:
+     * - Static analysis of context dependencies
+     * - Automatic `$inject` generation by the Vite plugin
+     * - Type-safe context access without manual `resolveContext` calls
+     *
+     * @example
+     * ```ts
+     * const ThemeContext = createContextKey<{ mode: 'light' | 'dark' }>('Theme');
+     * const UserContext = createContextKey<{ name: string }>('User');
+     *
+     * directive('themed-greeting', ($element, $state, theme, user) => {
+     *   // theme and user are resolved from the using array
+     *   $element.textContent = `Hello ${user.name}!`;
+     *   $element.className = theme.mode;
+     * }, {
+     *   using: [ThemeContext, UserContext]
+     * });
+     * ```
+     */
+    using?: ContextKey<unknown>[];
 }
 /** Registered directive with options */
 export interface DirectiveRegistration {
@@ -359,4 +410,30 @@ export declare function getDirectiveNames(): string[];
  * Primarily useful for testing.
  */
 export declare function clearDirectives(): void;
+/**
+ * Configure options for an existing directive.
+ *
+ * @remarks
+ * Merges the provided options with any existing options for the directive.
+ * If the directive hasn't been registered yet, stores the options to be
+ * applied when it is registered.
+ *
+ * This is useful for configuring built-in or third-party directives
+ * without needing access to the directive function.
+ *
+ * @param name - The directive name
+ * @param options - Options to merge
+ *
+ * @example
+ * ```ts
+ * // Add scope to a built-in directive
+ * configureDirective('g-text', { scope: true });
+ *
+ * // Add template to a custom element
+ * configureDirective('app-header', {
+ *   template: '<header><slot></slot></header>'
+ * });
+ * ```
+ */
+export declare function configureDirective(name: string, options: Partial<DirectiveOptions>): void;
 export {};

package/dist/types.js

@@ -108,3 +108,44 @@ export function getDirectiveNames() {
 export function clearDirectives() {
     directiveRegistry.clear();
 }
+/**
+ * Configure options for an existing directive.
+ *
+ * @remarks
+ * Merges the provided options with any existing options for the directive.
+ * If the directive hasn't been registered yet, stores the options to be
+ * applied when it is registered.
+ *
+ * This is useful for configuring built-in or third-party directives
+ * without needing access to the directive function.
+ *
+ * @param name - The directive name
+ * @param options - Options to merge
+ *
+ * @example
+ * ```ts
+ * // Add scope to a built-in directive
+ * configureDirective('g-text', { scope: true });
+ *
+ * // Add template to a custom element
+ * configureDirective('app-header', {
+ *   template: '<header><slot></slot></header>'
+ * });
+ * ```
+ */
+export function configureDirective(name, options) {
+    const existing = directiveRegistry.get(name);
+    if (existing) {
+        directiveRegistry.set(name, {
+            fn: existing.fn,
+            options: { ...existing.options, ...options }
+        });
+    }
+    else {
+        // Store options for later - directive will be registered soon
+        directiveRegistry.set(name, {
+            fn: null,
+            options: options
+        });
+    }
+}

package/dist/vite/plugin.d.ts

@@ -10,6 +10,14 @@
  * @packageDocumentation
  */
 import type { Plugin } from 'vite';
+/**
+ * Options for directive registration.
+ */
+export interface DirectiveOptionsConfig {
+    scope?: boolean;
+    template?: string | ((attrs: Record<string, string>) => string | Promise<string>);
+    provide?: Record<string, unknown>;
+}
 /**
  * Plugin options.
  */
@@ -48,6 +56,25 @@ export interface GoniaPluginOptions {
      * @example ['app-', 'my-', 'ui-']
      */
     directiveElementPrefixes?: string[];
+    /**
+     * Options to apply to directives.
+     *
+     * Can be an object mapping directive names to options, or a function
+     * that receives the directive name and returns options.
+     *
+     * @example
+     * ```ts
+     * // Object form - explicit per-directive
+     * directiveOptions: {
+     *   'g-text': { scope: true },
+     *   'app-card': { template: '<div class="card"><slot></slot></div>' }
+     * }
+     *
+     * // Function form - dynamic/pattern-based
+     * directiveOptions: (name) => name.startsWith('app-') ? { scope: true } : undefined
+     * ```
+     */
+    directiveOptions?: Record<string, DirectiveOptionsConfig> | ((name: string) => DirectiveOptionsConfig | undefined);
 }
 /**
  * Gonia Vite plugin.