gonia 0.1.2 → 0.2.0

package/README.md

@@ -58,18 +58,16 @@ hydrate();
 ```typescript
 import { directive, Directive } from 'gonia';
 
-const myApp: Directive = ($element, $state) => {
-  // Initialize state
-  $state.count = 0;
+const myApp: Directive<['$element', '$scope']> = ($element, $scope) => {
+  // Initialize scope
+  $scope.count = 0;
 
   // Define methods
-  $state.increment = () => {
-    $state.count++;
+  $scope.increment = () => {
+    $scope.count++;
   };
 };
 
-myApp.$inject = ['$element', '$state'];
-
 // Register with scope: true to create isolated state
 directive('my-app', myApp, { scope: true });
 ```
@@ -92,6 +90,8 @@ directive('my-app', myApp, { scope: true });
 | `g-class` | Dynamic classes | `<div g-class="{ active: isActive }">` |
 | `g-model` | Two-way binding | `<input g-model="name">` |
 | `g-on` | Event handling | `<button g-on="click: handleClick">` |
+| `g-scope` | Inline scope init | `<div g-scope="{ count: 0 }">` |
+| `g-bind:*` | Dynamic attributes | `<a g-bind:href="link">` |
 
 ## Vite Integration
 
@@ -114,6 +114,23 @@ See the [docs](./docs) folder for detailed documentation:
 - [SSR Guide](./docs/ssr.md)
 - [Reactivity](./docs/reactivity.md)
 
+## Roadmap
+
+### Done
+- [x] Core directives (`g-text`, `g-show`, `g-if`, `g-for`, `g-class`, `g-model`, `g-on`, `g-scope`, `g-bind:*`, `g-html`)
+- [x] Directive options (`scope`, `template`, `assign`, `provide`, `using`)
+- [x] SSR with client hydration
+- [x] Vite plugin with `$inject` transformation
+- [x] Typed context registry
+- [x] Persistent scopes for `g-if` toggles
+
+### Planned
+- [ ] Reducer-based two-way bindings (`scope: { prop: '=' }`)
+- [ ] Scoped CSS with automatic class mangling
+- [ ] Async components with suspense boundaries
+- [ ] Browser devtools extension
+- [ ] Transition system for `g-if`/`g-for`
+
 ## License
 
 MIT

package/dist/client/hydrate.js

@@ -9,7 +9,9 @@ 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';
+import { resolveDependencies as resolveInjectables } from '../inject.js';
+import { resolveContext } from '../context-registry.js';
+import { effect } from '../reactivity.js';
 // Built-in directives
 import { text } from '../directives/text.js';
 import { show } from '../directives/show.js';
@@ -59,6 +61,10 @@ function getSelector(registry) {
         }
         // Also match native <slot> elements
         directiveSelectors.push('slot');
+        // Match template placeholders from SSR (g-if with false condition)
+        directiveSelectors.push('template[data-g-if]');
+        // Match g-scope for inline scope initialization
+        directiveSelectors.push('[g-scope]');
         cachedSelector = directiveSelectors.join(',');
     }
     return cachedSelector;
@@ -73,7 +79,14 @@ function getDirectivesForElement(el, registry) {
     for (const [name, directive] of registry) {
         const attr = el.getAttribute(`g-${name}`);
         if (attr !== null) {
-            directives.push({ name, directive, expr: attr });
+            // Look up options from the global directive registry
+            const registration = getDirective(`g-${name}`);
+            directives.push({
+                name,
+                directive,
+                expr: attr,
+                using: registration?.options.using
+            });
         }
     }
     // Sort by priority (higher first)
@@ -124,48 +137,28 @@ export function setElementContext(el, ctx) {
     contextCache.set(el, ctx);
 }
 /**
- * Resolve dependencies for a directive based on its $inject array.
+ * Create resolver config for client-side dependency resolution.
  *
  * @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}`);
-            }
-        }
-    });
+function createClientResolverConfig(el, ctx) {
+    return {
+        resolveContext: (key) => resolveContext(el, key),
+        resolveState: () => findParentScope(el, true) ?? getLocalState(el),
+        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: 'client'
+    };
 }
 /**
  * Process directives on a single element.
@@ -184,15 +177,60 @@ function processElement(el, registry) {
         processNativeSlot(el);
         return;
     }
+    // Handle template placeholders from SSR (g-if with false condition)
+    if (el.tagName === 'TEMPLATE' && el.hasAttribute('data-g-if')) {
+        const ifDirective = registry.get('if');
+        if (ifDirective) {
+            const expr = el.getAttribute('data-g-if') || '';
+            const ctx = getContextForElement(el);
+            const config = createClientResolverConfig(el, ctx);
+            const registration = getDirective('g-if');
+            const args = resolveInjectables(ifDirective, expr, el, ctx.eval.bind(ctx), config, registration?.options.using);
+            const result = ifDirective(...args);
+            if (result instanceof Promise) {
+                return result;
+            }
+        }
+        return;
+    }
     const directives = getDirectivesForElement(el, registry);
-    if (directives.length === 0)
+    const hasScopeAttr = el.hasAttribute('g-scope');
+    const hasBindAttrs = [...el.attributes].some(a => a.name.startsWith('g-bind:'));
+    // Skip if nothing to process
+    if (directives.length === 0 && !hasScopeAttr && !hasBindAttrs)
         return;
     const ctx = getContextForElement(el);
+    const scope = findParentScope(el, true) ?? {};
+    // Process g-scope first (inline scope initialization)
+    if (hasScopeAttr) {
+        const scopeAttr = el.getAttribute('g-scope');
+        const scopeValues = ctx.eval(scopeAttr);
+        if (scopeValues && typeof scopeValues === 'object') {
+            Object.assign(scope, scopeValues);
+        }
+    }
+    // Process g-bind:* attributes (dynamic attribute binding with reactivity)
+    for (const attr of [...el.attributes]) {
+        if (attr.name.startsWith('g-bind:')) {
+            const targetAttr = attr.name.slice('g-bind:'.length);
+            const valueExpr = attr.value;
+            effect(() => {
+                const value = ctx.eval(valueExpr);
+                if (value === null || value === undefined) {
+                    el.removeAttribute(targetAttr);
+                }
+                else {
+                    el.setAttribute(targetAttr, String(value));
+                }
+            });
+        }
+    }
     // Process directives sequentially, handling async ones properly
     let chain;
-    for (const { directive, expr } of directives) {
+    for (const { directive, expr, using } of directives) {
         const processDirective = () => {
-            const args = resolveDependencies(directive, expr, el, ctx);
+            const config = createClientResolverConfig(el, ctx);
+            const args = resolveInjectables(directive, expr, el, ctx.eval.bind(ctx), config, using);
             const result = directive(...args);
             // Register as provider if directive declares $context
             if (directive.$context?.length) {
@@ -330,8 +368,8 @@ async function processDirectiveElements() {
         }
         const { fn, options } = registration;
         // Only process directives with templates (web components),
-        // scope: true, or provide (DI overrides)
-        if (!options.template && !options.scope && !options.provide) {
+        // scope: true, provide (DI overrides), or using (context dependencies)
+        if (!options.template && !options.scope && !options.provide && !options.using) {
             continue;
         }
         // Find all elements matching this directive's tag name
@@ -346,6 +384,10 @@ async function processDirectiveElements() {
             if (options.scope) {
                 const parentScope = findParentScope(el);
                 scope = createElementScope(el, parentScope);
+                // Apply assigned values to scope
+                if (options.assign) {
+                    Object.assign(scope, options.assign);
+                }
             }
             else {
                 scope = findParentScope(el, true) ?? {};
@@ -357,19 +399,12 @@ async function processDirectiveElements() {
             // 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 config = {
+                    resolveContext: (key) => resolveContext(el, key),
+                    resolveState: () => scope,
+                    mode: 'client'
+                };
+                const args = resolveInjectables(fn, '', el, ctx.eval.bind(ctx), config, options.using);
                 const result = fn(...args);
                 if (result instanceof Promise) {
                     await result;

package/dist/context-registry.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Type-safe context registry for sharing data across DOM ancestors/descendants.
+ *
+ * @remarks
+ * Provides a unified system for registering and resolving typed context values
+ * on DOM elements. Similar to React's Context or Vue's provide/inject but with
+ * full type safety through branded context keys.
+ *
+ * @packageDocumentation
+ */
+/**
+ * A branded context key that provides type safety for context values.
+ *
+ * @typeParam T - The type of value this context holds
+ *
+ * @remarks
+ * The `__type` property is a phantom type - it doesn't exist at runtime
+ * but provides compile-time type checking when registering and resolving.
+ */
+export interface ContextKey<T> {
+    /** Unique identifier for this context */
+    readonly id: symbol;
+    /** Debug name for error messages */
+    readonly name: string;
+    /** Phantom type for TypeScript inference */
+    readonly __type?: T;
+}
+/**
+ * Create a typed context key.
+ *
+ * @typeParam T - The type of value this context will hold
+ * @param name - Debug name for the context (used in error messages)
+ * @returns A unique context key
+ *
+ * @example
+ * ```ts
+ * interface UserData {
+ *   name: string;
+ *   email: string;
+ * }
+ *
+ * const UserContext = createContextKey<UserData>('User');
+ *
+ * // Register on an element
+ * registerContext(el, UserContext, { name: 'Alice', email: 'alice@example.com' });
+ *
+ * // Resolve from a descendant - fully typed!
+ * const user = resolveContext(childEl, UserContext);
+ * // user is UserData | undefined
+ * ```
+ */
+export declare function createContextKey<T>(name: string): ContextKey<T>;
+/**
+ * Register a context value on an element.
+ *
+ * @typeParam T - The context value type (inferred from key)
+ * @param el - The element to register the context on
+ * @param key - The context key
+ * @param value - The value to store
+ *
+ * @remarks
+ * Descendants can resolve this context using `resolveContext`.
+ * If a context with the same key is already registered on this element,
+ * it will be overwritten.
+ *
+ * @example
+ * ```ts
+ * const ThemeContext = createContextKey<{ mode: 'light' | 'dark' }>('Theme');
+ *
+ * registerContext(rootEl, ThemeContext, { mode: 'dark' });
+ * ```
+ */
+export declare function registerContext<T>(el: Element, key: ContextKey<T>, value: T): void;
+/**
+ * Resolve a context value from an ancestor element.
+ *
+ * @typeParam T - The context value type (inferred from key)
+ * @param el - The element to start searching from
+ * @param key - The context key to look for
+ * @param includeSelf - Whether to check the element itself (default: false)
+ * @returns The context value, or undefined if not found
+ *
+ * @remarks
+ * Walks up the DOM tree from the element's parent (or the element itself
+ * if `includeSelf` is true), looking for an ancestor with the specified
+ * context registered.
+ *
+ * @example
+ * ```ts
+ * const ThemeContext = createContextKey<{ mode: 'light' | 'dark' }>('Theme');
+ *
+ * // Somewhere up the tree, ThemeContext was registered
+ * const theme = resolveContext(el, ThemeContext);
+ * if (theme) {
+ *   console.log(theme.mode); // 'light' or 'dark'
+ * }
+ * ```
+ */
+export declare function resolveContext<T>(el: Element, key: ContextKey<T>, includeSelf?: boolean): T | undefined;
+/**
+ * Check if a context is registered on an element.
+ *
+ * @param el - The element to check
+ * @param key - The context key
+ * @returns True if the context is registered on this specific element
+ *
+ * @remarks
+ * This only checks the element itself, not ancestors.
+ * Use `resolveContext` to search up the tree.
+ */
+export declare function hasContext<T>(el: Element, key: ContextKey<T>): boolean;
+/**
+ * Remove a context from an element.
+ *
+ * @param el - The element to remove the context from
+ * @param key - The context key to remove
+ *
+ * @remarks
+ * Does nothing if the context wasn't registered.
+ */
+export declare function removeContext<T>(el: Element, key: ContextKey<T>): void;
+/**
+ * Clear all contexts from an element.
+ *
+ * @param el - The element to clear
+ *
+ * @remarks
+ * Called during element cleanup/removal.
+ */
+export declare function clearContexts(el: Element): void;

package/dist/context-registry.js

@@ -0,0 +1,153 @@
+/**
+ * Type-safe context registry for sharing data across DOM ancestors/descendants.
+ *
+ * @remarks
+ * Provides a unified system for registering and resolving typed context values
+ * on DOM elements. Similar to React's Context or Vue's provide/inject but with
+ * full type safety through branded context keys.
+ *
+ * @packageDocumentation
+ */
+import { findAncestor } from './dom.js';
+/**
+ * Storage for all contexts per element.
+ *
+ * @internal
+ */
+const contexts = new WeakMap();
+/**
+ * Create a typed context key.
+ *
+ * @typeParam T - The type of value this context will hold
+ * @param name - Debug name for the context (used in error messages)
+ * @returns A unique context key
+ *
+ * @example
+ * ```ts
+ * interface UserData {
+ *   name: string;
+ *   email: string;
+ * }
+ *
+ * const UserContext = createContextKey<UserData>('User');
+ *
+ * // Register on an element
+ * registerContext(el, UserContext, { name: 'Alice', email: 'alice@example.com' });
+ *
+ * // Resolve from a descendant - fully typed!
+ * const user = resolveContext(childEl, UserContext);
+ * // user is UserData | undefined
+ * ```
+ */
+export function createContextKey(name) {
+    return {
+        id: Symbol(name),
+        name,
+    };
+}
+/**
+ * Register a context value on an element.
+ *
+ * @typeParam T - The context value type (inferred from key)
+ * @param el - The element to register the context on
+ * @param key - The context key
+ * @param value - The value to store
+ *
+ * @remarks
+ * Descendants can resolve this context using `resolveContext`.
+ * If a context with the same key is already registered on this element,
+ * it will be overwritten.
+ *
+ * @example
+ * ```ts
+ * const ThemeContext = createContextKey<{ mode: 'light' | 'dark' }>('Theme');
+ *
+ * registerContext(rootEl, ThemeContext, { mode: 'dark' });
+ * ```
+ */
+export function registerContext(el, key, value) {
+    let map = contexts.get(el);
+    if (!map) {
+        map = new Map();
+        contexts.set(el, map);
+    }
+    map.set(key.id, value);
+}
+/**
+ * Resolve a context value from an ancestor element.
+ *
+ * @typeParam T - The context value type (inferred from key)
+ * @param el - The element to start searching from
+ * @param key - The context key to look for
+ * @param includeSelf - Whether to check the element itself (default: false)
+ * @returns The context value, or undefined if not found
+ *
+ * @remarks
+ * Walks up the DOM tree from the element's parent (or the element itself
+ * if `includeSelf` is true), looking for an ancestor with the specified
+ * context registered.
+ *
+ * @example
+ * ```ts
+ * const ThemeContext = createContextKey<{ mode: 'light' | 'dark' }>('Theme');
+ *
+ * // Somewhere up the tree, ThemeContext was registered
+ * const theme = resolveContext(el, ThemeContext);
+ * if (theme) {
+ *   console.log(theme.mode); // 'light' or 'dark'
+ * }
+ * ```
+ */
+export function resolveContext(el, key, includeSelf = false) {
+    return findAncestor(el, (e) => {
+        const map = contexts.get(e);
+        if (map?.has(key.id)) {
+            return map.get(key.id);
+        }
+        return undefined;
+    }, includeSelf);
+}
+/**
+ * Check if a context is registered on an element.
+ *
+ * @param el - The element to check
+ * @param key - The context key
+ * @returns True if the context is registered on this specific element
+ *
+ * @remarks
+ * This only checks the element itself, not ancestors.
+ * Use `resolveContext` to search up the tree.
+ */
+export function hasContext(el, key) {
+    const map = contexts.get(el);
+    return map?.has(key.id) ?? false;
+}
+/**
+ * Remove a context from an element.
+ *
+ * @param el - The element to remove the context from
+ * @param key - The context key to remove
+ *
+ * @remarks
+ * Does nothing if the context wasn't registered.
+ */
+export function removeContext(el, key) {
+    const map = contexts.get(el);
+    if (map) {
+        map.delete(key.id);
+        if (map.size === 0) {
+            contexts.delete(el);
+        }
+    }
+}
+/**
+ * Clear all contexts from an element.
+ *
+ * @param el - The element to clear
+ *
+ * @remarks
+ * Called during element cleanup/removal.
+ */
+export function clearContexts(el) {
+    contexts.delete(el);
+}

package/dist/directives/for.d.ts

@@ -26,4 +26,4 @@ export declare const FOR_TEMPLATE_ATTR = "data-g-for-template";
  * <div g-for="(value, key) in object" g-text="key + ': ' + value"></div>
  * ```
  */
-export declare const cfor: Directive<['$expr', '$element', '$eval', '$state', '$mode']>;
+export declare const cfor: Directive<['$expr', '$element', '$eval', '$scope', '$mode']>;