gonia 0.1.2 → 0.2.0

package/dist/server/render.js

@@ -3,13 +3,15 @@
  *
  * @packageDocumentation
  */
-import { parseHTML } from 'linkedom';
-import { Mode, DirectivePriority } from '../types.js';
+import { parseHTML } from 'linkedom/worker';
+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();
@@ -24,11 +26,26 @@ function getSelector(registry) {
         const directiveSelectors = [...registry.keys()].map(n => `[g-${n}]`);
         // Also match native <slot> elements
         directiveSelectors.push('slot');
+        // Match g-scope for inline scope initialization
+        directiveSelectors.push('[g-scope]');
         selector = directiveSelectors.join(',');
         selectorCache.set(registry, selector);
     }
     return selector;
 }
+/**
+ * Check if element has any g-bind:* attributes.
+ *
+ * @internal
+ */
+function hasBindAttributes(el) {
+    for (const attr of el.attributes) {
+        if (attr.name.startsWith('g-bind:')) {
+            return true;
+        }
+    }
+    return false;
+}
 /**
  * Register a directive in the registry.
  *
@@ -53,46 +70,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.
@@ -135,6 +135,10 @@ export async function render(html, state, registry) {
                 const matches = el.matches(selector) ? [el] : [];
                 const descendants = [...el.querySelectorAll(selector)];
                 for (const match of [...matches, ...descendants]) {
+                    // Skip elements inside template content (used as placeholders)
+                    if (match.closest('template')) {
+                        continue;
+                    }
                     // Handle native <slot> elements
                     if (match.tagName === 'SLOT') {
                         index.push({
@@ -150,12 +154,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
                             });
                         }
                     }
@@ -216,6 +223,27 @@ export async function render(html, state, registry) {
             const directives = byElement.get(el);
             // Sort directives on this element by priority (higher first)
             directives.sort((a, b) => b.priority - a.priority);
+            // Process g-scope first (inline scope initialization)
+            const scopeAttr = el.getAttribute('g-scope');
+            if (scopeAttr) {
+                const scopeValues = ctx.eval(scopeAttr);
+                if (scopeValues && typeof scopeValues === 'object') {
+                    Object.assign(state, scopeValues);
+                }
+            }
+            // Process g-bind:* attributes (dynamic attribute binding)
+            for (const attr of [...el.attributes]) {
+                if (attr.name.startsWith('g-bind:')) {
+                    const targetAttr = attr.name.slice('g-bind:'.length);
+                    const value = ctx.eval(attr.value);
+                    if (value === null || value === undefined) {
+                        el.removeAttribute(targetAttr);
+                    }
+                    else {
+                        el.setAttribute(targetAttr, String(value));
+                    }
+                }
+            }
             for (const item of directives) {
                 // Check if element was disconnected by a previous directive (e.g., g-for replacing it)
                 if (!item.el.isConnected) {
@@ -225,7 +253,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.
  */
@@ -48,7 +50,7 @@ export interface InjectableRegistry {
     /** Function to evaluate expressions against state */
     $eval: EvalFn;
     /** Local reactive state object (isolated per element) */
-    $state: Record<string, unknown>;
+    $scope: Record<string, unknown>;
     /** Root reactive state object (shared across all elements) */
     $rootState: Record<string, unknown>;
     /** Template registry for g-template directive */
@@ -59,23 +61,28 @@ 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
  * ```ts
- * type Args = MapInjectables<['$element', '$state']>;
+ * type Args = MapInjectables<['$element', '$scope']>;
  * // => [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.
@@ -146,25 +153,35 @@ export interface DirectiveMeta<T = InjectableRegistry> {
      * - `$expr`: The expression string from the attribute
      * - `$element`: The target DOM element
      * - `$eval`: Function to evaluate expressions: `(expr) => value`
-     * - `$state`: Local reactive state object (isolated per element)
+     * - `$scope`: 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', '$scope'];
+     *
+     * // With typed context keys
+     * myDirective.$inject = ['$element', SlotContentContext];
+     * ```
      */
-    $inject?: readonly string[];
+    $inject?: readonly Injectable[];
     /**
      * Names this directive exposes as context to descendants.
      *
      * @remarks
-     * When a directive declares `$context`, its `$state` becomes
+     * When a directive declares `$context`, its `$scope` becomes
      * available to descendant directives under those names.
      * Useful for passing state through isolate scope boundaries.
      *
      * @example
      * ```ts
-     * const themeProvider: Directive = ($state) => {
-     *   $state.mode = 'dark';
+     * const themeProvider: Directive = ($scope) => {
+     *   $scope.mode = 'dark';
      * };
-     * themeProvider.$inject = ['$state'];
+     * themeProvider.$inject = ['$scope'];
      * themeProvider.$context = ['theme'];
      *
      * // Descendants can inject 'theme'
@@ -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,67 @@ 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, $scope, 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>[];
+    /**
+     * Values to assign to the directive's scope.
+     *
+     * @remarks
+     * Requires `scope: true`. Assigns the provided values to the
+     * directive's scope, making them available in expressions.
+     *
+     * Useful for injecting external values (like styles) that should
+     * be accessible in templates without manual `$scope` assignment.
+     *
+     * @example
+     * ```ts
+     * import styles from './button.css';
+     *
+     * directive('my-button', handler, {
+     *   scope: true,
+     *   assign: { $styles: styles }
+     * });
+     *
+     * // In template:
+     * // <div g-class="$styles.container">...</div>
+     * ```
+     */
+    assign?: Record<string, unknown>;
+    /**
+     * Index signature for custom options.
+     *
+     * @remarks
+     * Allows libraries to pass additional options that gonia
+     * doesn't process directly. Libraries can create typed
+     * wrapper functions around `directive()` for type safety.
+     */
+    [key: string]: unknown;
 }
 /** Registered directive with options */
 export interface DirectiveRegistration {
@@ -321,8 +405,8 @@ export interface DirectiveRegistration {
  * @example
  * ```ts
  * // Directive with behavior
- * directive('todo-app', ($element, $state) => {
- *   $state.todos = [];
+ * directive('todo-app', ($element, $scope) => {
+ *   $scope.todos = [];
  * }, { scope: true });
  *
  * // Template-only directive
@@ -359,4 +443,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

@@ -49,8 +49,8 @@ const directiveRegistry = new Map();
  * @example
  * ```ts
  * // Directive with behavior
- * directive('todo-app', ($element, $state) => {
- *   $state.todos = [];
+ * directive('todo-app', ($element, $scope) => {
+ *   $scope.todos = [];
  * }, { scope: true });
  *
  * // Template-only directive
@@ -61,6 +61,11 @@ const directiveRegistry = new Map();
  */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export function directive(name, fn, options = {}) {
+    // Validate: assign requires scope: true
+    if (options.assign && !options.scope) {
+        throw new Error(`Directive '${name}': 'assign' requires 'scope: true'. ` +
+            `To modify parent scope, use $scope in your directive function.`);
+    }
     directiveRegistry.set(name, { fn, options });
     // Register as custom element if name contains hyphen and scope is true
     if (fn && name.includes('-') && options.scope && typeof customElements !== 'undefined') {
@@ -108,3 +113,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.

package/dist/vite/plugin.js

@@ -113,15 +113,56 @@ function detectDirectives(code, id, isDev, attributePrefixes, elementPrefixes, c
     }
     return found;
 }
+/**
+ * Get options for a directive from the directiveOptions config.
+ */
+function getDirectiveOptions(name, directiveOptions) {
+    if (!directiveOptions)
+        return undefined;
+    if (typeof directiveOptions === 'function') {
+        return directiveOptions(name);
+    }
+    return directiveOptions[name];
+}
+/**
+ * Serialize directive options to a string for code generation.
+ */
+function serializeOptions(options) {
+    const parts = [];
+    if (options.scope !== undefined) {
+        parts.push(`scope: ${options.scope}`);
+    }
+    if (options.template !== undefined) {
+        if (typeof options.template === 'string') {
+            parts.push(`template: ${JSON.stringify(options.template)}`);
+        }
+        else {
+            // Function templates can't be serialized - warn and skip
+            console.warn('[gonia] Function templates in directiveOptions are not supported. Use a string template.');
+        }
+    }
+    if (options.provide !== undefined) {
+        // provide can contain functions which can't be serialized
+        console.warn('[gonia] "provide" in directiveOptions is not supported via plugin config.');
+    }
+    return `{ ${parts.join(', ')} }`;
+}
 /**
  * Generate import statements for detected directives.
  */
-function generateImports(directives, customDirectives, currentFile, rootDir) {
+function generateImports(directives, customDirectives, currentFile, rootDir, directiveOptions) {
     if (directives.size === 0)
         return '';
     // Group by module
     const moduleImports = new Map();
+    // Track which directives need configuration
+    const directivesToConfigure = [];
     for (const name of directives) {
+        // Check if this directive has options
+        const options = getDirectiveOptions(name, directiveOptions);
+        if (options) {
+            directivesToConfigure.push({ name, options });
+        }
         // Check built-in first
         const builtin = BUILTIN_DIRECTIVES[name];
         if (builtin) {
@@ -152,6 +193,14 @@ function generateImports(directives, customDirectives, currentFile, rootDir) {
     }
     // Generate import statements
     const statements = [];
+    // Add configureDirective import if we have options to apply
+    if (directivesToConfigure.length > 0) {
+        const goniaImports = moduleImports.get('gonia') ?? [];
+        if (!goniaImports.includes('configureDirective')) {
+            goniaImports.push('configureDirective');
+        }
+        moduleImports.set('gonia', goniaImports);
+    }
     for (const [module, imports] of moduleImports) {
         if (imports.length > 0) {
             statements.push(`import { ${imports.join(', ')} } from '${module}';`);
@@ -161,6 +210,10 @@ function generateImports(directives, customDirectives, currentFile, rootDir) {
             statements.push(`import '${module}';`);
         }
     }
+    // Add configureDirective calls
+    for (const { name, options } of directivesToConfigure) {
+        statements.push(`configureDirective('${name}', ${serializeOptions(options)});`);
+    }
     return statements.length > 0 ? statements.join('\n') + '\n' : '';
 }
 /**
@@ -239,7 +292,7 @@ function transformInject(code) {
  * ```
  */
 export function gonia(options = {}) {
-    const { autoDirectives = true, includeDirectives = [], excludeDirectives = [], directiveSources = [], directiveAttributePrefixes = ['g-'], directiveElementPrefixes = options.directiveElementPrefixes ?? options.directiveAttributePrefixes ?? ['g-'], } = options;
+    const { autoDirectives = true, includeDirectives = [], excludeDirectives = [], directiveSources = [], directiveAttributePrefixes = ['g-'], directiveElementPrefixes = options.directiveElementPrefixes ?? options.directiveAttributePrefixes ?? ['g-'], directiveOptions, } = options;
     let isDev = false;
     let rootDir = process.cwd();
     // Map of custom directive name -> DirectiveInfo
@@ -303,7 +356,7 @@ export function gonia(options = {}) {
                     const hasGoniaImport = code.includes("from 'gonia/directives'") ||
                         code.includes('from "gonia/directives"');
                     // For custom directives, check if already imported
-                    const importStatement = generateImports(detected, customDirectives, id, rootDir);
+                    const importStatement = generateImports(detected, customDirectives, id, rootDir, directiveOptions);
                     if (importStatement && !hasGoniaImport) {
                         result = importStatement + result;
                         modified = true;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gonia",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "A lightweight, SSR-first reactive UI library with declarative directives",
   "type": "module",
   "license": "MIT",
@@ -36,6 +36,10 @@
       "types": "./dist/server/index.d.ts",
       "import": "./dist/server/index.js"
     },
+    "./directives": {
+      "types": "./dist/directives/index.d.ts",
+      "import": "./dist/directives/index.js"
+    },
     "./vite": {
       "types": "./dist/vite/index.d.ts",
       "import": "./dist/vite/index.js"
@@ -56,6 +60,7 @@
   "devDependencies": {
     "@types/node": "^25.0.10",
     "@vitest/coverage-v8": "^4.0.17",
+    "conventional-changelog-cli": "^5.0.0",
     "jsdom": "^27.4.0",
     "typescript": "^5.7.0",
     "vite": "^6.4.0",
@@ -64,6 +69,8 @@
   "scripts": {
     "build": "tsc",
     "test": "vitest run",
-    "test:watch": "vitest"
+    "test:watch": "vitest",
+    "changelog": "conventional-changelog -p angular -i CHANGELOG.md -s",
+    "changelog:all": "conventional-changelog -p angular -i CHANGELOG.md -s -r 0"
   }
 }