gonia 0.0.1

package/dist/templates.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Template registry for reusable DOM.
+ *
+ * @remarks
+ * Templates are just reusable HTML. The registry provides async access
+ * to templates from various sources: inline `<template>` tags, fetched
+ * files, or custom sources.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Interface for template retrieval.
+ *
+ * @remarks
+ * Implementations can source templates from anywhere:
+ * inline tags, files, network, bundled, etc.
+ */
+export interface TemplateRegistry {
+    /**
+     * Get a template by name.
+     *
+     * @param name - Template name/path
+     * @returns The template HTML string
+     */
+    get(name: string): Promise<string>;
+}
+/**
+ * Create a template registry with inline -> fetch fallback.
+ *
+ * @remarks
+ * First checks for a `<template id="{name}">` in the document.
+ * If not found, fetches from `/{name}` (or custom base path).
+ * Results are cached.
+ *
+ * @param options - Configuration options
+ * @returns A template registry
+ *
+ * @example
+ * ```ts
+ * // Default: inline -> fetch from /
+ * const templates = createTemplateRegistry();
+ *
+ * // Custom base path
+ * const templates = createTemplateRegistry({ basePath: '/templates/' });
+ *
+ * // Usage
+ * const html = await templates.get('dialog');
+ * ```
+ */
+export declare function createTemplateRegistry(options?: {
+    basePath?: string;
+    fetch?: typeof globalThis.fetch;
+}): TemplateRegistry;
+/**
+ * Create a simple in-memory template registry.
+ *
+ * @remarks
+ * Useful for testing or when templates are bundled.
+ *
+ * @param templates - Map of template names to HTML
+ * @returns A template registry
+ *
+ * @example
+ * ```ts
+ * const templates = createMemoryRegistry({
+ *   dialog: '<div class="dialog"><slot></slot></div>',
+ *   card: '<div class="card"><slot name="title"></slot><slot></slot></div>'
+ * });
+ * ```
+ */
+export declare function createMemoryRegistry(templates: Record<string, string>): TemplateRegistry;
+/**
+ * Create a server-side template registry that reads from filesystem.
+ *
+ * @remarks
+ * For Node.js/server environments. Reads templates from disk.
+ *
+ * @param readFile - Async file reader function
+ * @param basePath - Base directory path
+ * @returns A template registry
+ *
+ * @example
+ * ```ts
+ * import { readFile } from 'fs/promises';
+ *
+ * const templates = createServerRegistry(
+ *   (path) => readFile(path, 'utf-8'),
+ *   './templates/'
+ * );
+ * ```
+ */
+export declare function createServerRegistry(readFile: (path: string) => Promise<string>, basePath?: string): TemplateRegistry;

package/dist/templates.js

@@ -0,0 +1,124 @@
+/**
+ * Template registry for reusable DOM.
+ *
+ * @remarks
+ * Templates are just reusable HTML. The registry provides async access
+ * to templates from various sources: inline `<template>` tags, fetched
+ * files, or custom sources.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Create a template registry with inline -> fetch fallback.
+ *
+ * @remarks
+ * First checks for a `<template id="{name}">` in the document.
+ * If not found, fetches from `/{name}` (or custom base path).
+ * Results are cached.
+ *
+ * @param options - Configuration options
+ * @returns A template registry
+ *
+ * @example
+ * ```ts
+ * // Default: inline -> fetch from /
+ * const templates = createTemplateRegistry();
+ *
+ * // Custom base path
+ * const templates = createTemplateRegistry({ basePath: '/templates/' });
+ *
+ * // Usage
+ * const html = await templates.get('dialog');
+ * ```
+ */
+export function createTemplateRegistry(options = {}) {
+    const { basePath = '/', fetch: fetchFn = globalThis.fetch } = options;
+    const cache = new Map();
+    return {
+        async get(name) {
+            if (cache.has(name)) {
+                return cache.get(name);
+            }
+            // Try inline <template> first
+            if (typeof document !== 'undefined') {
+                const el = document.getElementById(name);
+                if (el instanceof HTMLTemplateElement) {
+                    const html = el.innerHTML;
+                    cache.set(name, html);
+                    return html;
+                }
+            }
+            // Fall back to fetch
+            const url = basePath + name;
+            const response = await fetchFn(url);
+            if (!response.ok) {
+                throw new Error(`Template not found: ${name} (${response.status})`);
+            }
+            const html = await response.text();
+            cache.set(name, html);
+            return html;
+        }
+    };
+}
+/**
+ * Create a simple in-memory template registry.
+ *
+ * @remarks
+ * Useful for testing or when templates are bundled.
+ *
+ * @param templates - Map of template names to HTML
+ * @returns A template registry
+ *
+ * @example
+ * ```ts
+ * const templates = createMemoryRegistry({
+ *   dialog: '<div class="dialog"><slot></slot></div>',
+ *   card: '<div class="card"><slot name="title"></slot><slot></slot></div>'
+ * });
+ * ```
+ */
+export function createMemoryRegistry(templates) {
+    return {
+        async get(name) {
+            const html = templates[name];
+            if (html === undefined) {
+                throw new Error(`Template not found: ${name}`);
+            }
+            return html;
+        }
+    };
+}
+/**
+ * Create a server-side template registry that reads from filesystem.
+ *
+ * @remarks
+ * For Node.js/server environments. Reads templates from disk.
+ *
+ * @param readFile - Async file reader function
+ * @param basePath - Base directory path
+ * @returns A template registry
+ *
+ * @example
+ * ```ts
+ * import { readFile } from 'fs/promises';
+ *
+ * const templates = createServerRegistry(
+ *   (path) => readFile(path, 'utf-8'),
+ *   './templates/'
+ * );
+ * ```
+ */
+export function createServerRegistry(readFile, basePath = './templates/') {
+    const cache = new Map();
+    return {
+        async get(name) {
+            if (cache.has(name)) {
+                return cache.get(name);
+            }
+            const path = basePath + name + '.html';
+            const html = await readFile(path);
+            cache.set(name, html);
+            return html;
+        }
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,362 @@
+/**
+ * Core types for gonia.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Execution mode for the framework.
+ */
+export declare enum Mode {
+    /** Server-side rendering */
+    SERVER = "server",
+    /** Client-side hydration/runtime */
+    CLIENT = "client"
+}
+declare const __brand: unique symbol;
+/**
+ * A branded string type for expressions.
+ *
+ * @remarks
+ * This prevents arbitrary strings from being passed as expressions,
+ * reducing the risk of eval injection. Only the framework's parser
+ * should create Expression values.
+ */
+export type Expression = string & {
+    [__brand]: 'expression';
+};
+/**
+ * Function to evaluate an expression against state.
+ */
+export type EvalFn = <T = unknown>(expr: Expression) => T;
+/**
+ * Registry of framework-provided injectables.
+ *
+ * @remarks
+ * For provider contexts, use the second type parameter of `Directive` instead:
+ *
+ * ```ts
+ * const themed: Directive<['$element', 'theme'], {theme: ThemeContext}> = ($el, theme) => {
+ *   // theme is typed as ThemeContext
+ * };
+ * ```
+ */
+export interface InjectableRegistry {
+    /** The expression string from the directive attribute */
+    $expr: Expression;
+    /** The target DOM element */
+    $element: Element;
+    /** Function to evaluate expressions against state */
+    $eval: EvalFn;
+    /** Local reactive state object (isolated per element) */
+    $state: Record<string, unknown>;
+    /** Root reactive state object (shared across all elements) */
+    $rootState: Record<string, unknown>;
+    /** Template registry for c-template directive */
+    $templates: {
+        get(name: string): Promise<string>;
+    };
+    /** Current execution mode (server or client) */
+    $mode: Mode;
+}
+/**
+ * Maps a tuple of injectable names to their corresponding types.
+ *
+ * @typeParam K - Tuple of injectable name strings
+ * @typeParam T - Type map (defaults to InjectableRegistry)
+ *
+ * @example
+ * ```ts
+ * type Args = MapInjectables<['$element', '$state']>;
+ * // => [Element, Record<string, unknown>]
+ *
+ * // With custom type map
+ * type Args2 = MapInjectables<['$element', 'custom'], { $element: Element; custom: MyType }>;
+ * // => [Element, MyType]
+ * ```
+ */
+export type MapInjectables<K extends readonly string[], T = InjectableRegistry> = {
+    [I in keyof K]: K[I] extends keyof T ? T[K[I]] : unknown;
+};
+/**
+ * Evaluation context passed to directives.
+ */
+export interface Context {
+    /** Current execution mode */
+    readonly mode: Mode;
+    /**
+     * Evaluate an expression against the current state.
+     *
+     * @typeParam T - Expected return type
+     * @param expr - The expression to evaluate
+     * @returns The evaluated result
+     */
+    eval<T = unknown>(expr: Expression): T;
+    /**
+     * Get a value from the context by key.
+     *
+     * @param key - The key to look up
+     * @returns The value, or undefined
+     */
+    get<T = unknown>(key: string): T | undefined;
+    /**
+     * Create a child context with additional values.
+     *
+     * @param additions - Values to add to the child context
+     * @returns A new child context
+     */
+    child(additions: Record<string, unknown>): Context;
+}
+/**
+ * Directive priority levels.
+ *
+ * @remarks
+ * Higher priority directives run first. Structural directives
+ * (like c-if, c-for) need to run before behavioral ones.
+ */
+export declare enum DirectivePriority {
+    /** Structural directives that control DOM presence (c-if, c-for) */
+    STRUCTURAL = 1000,
+    /** Template/transclusion directives */
+    TEMPLATE = 500,
+    /** Normal behavioral directives */
+    NORMAL = 0
+}
+/**
+ * Static metadata for a directive.
+ *
+ * @remarks
+ * Declared on the directive function before registration.
+ * Used to determine processing order and behavior.
+ *
+ * @typeParam T - Type map for injectable dependencies
+ */
+export interface DirectiveMeta<T = InjectableRegistry> {
+    /**
+     * Whether this directive transcludes content.
+     *
+     * @remarks
+     * If true, children are saved before the directive runs.
+     */
+    transclude?: boolean;
+    /**
+     * Dependencies to inject into the directive.
+     *
+     * @remarks
+     * Available injectables:
+     * - `$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)
+     * - Any registered service names
+     * - Any names provided by ancestor directives via `$context`
+     */
+    $inject?: readonly string[];
+    /**
+     * Names this directive exposes as context to descendants.
+     *
+     * @remarks
+     * When a directive declares `$context`, its `$state` 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';
+     * };
+     * themeProvider.$inject = ['$state'];
+     * themeProvider.$context = ['theme'];
+     *
+     * // Descendants can inject 'theme'
+     * const button: Directive = ($element, theme) => {
+     *   console.log(theme.mode);
+     * };
+     * button.$inject = ['$element', 'theme'];
+     * ```
+     */
+    $context?: string[];
+    /**
+     * Processing priority. Higher runs first.
+     *
+     * @defaultValue DirectivePriority.NORMAL
+     */
+    priority?: number;
+}
+/**
+ * A directive function with typed parameters based on injectable keys.
+ *
+ * @remarks
+ * Use this type annotation to get contextual typing for directive parameters.
+ * The tuple of keys maps to parameter types from InjectableRegistry.
+ *
+ * @typeParam K - Tuple of injectable key names
+ * @typeParam T - Optional custom type map to extend InjectableRegistry
+ *
+ * @example
+ * ```ts
+ * // Basic usage - $element is typed as Element
+ * const myDirective: Directive<['$element']> = ($element) => {
+ *   $element.textContent = 'hello';
+ * };
+ *
+ * // Multiple injectables
+ * const text: Directive<['$expr', '$element', '$eval']> = ($expr, $element, $eval) => {
+ *   $element.textContent = String($eval($expr) ?? '');
+ * };
+ *
+ * // With custom types (extend InjectableRegistry first)
+ * declare module 'gonia' {
+ *   interface InjectableRegistry {
+ *     myService: { doThing(): void };
+ *   }
+ * }
+ * const custom: Directive<['$element', 'myService']> = ($el, svc) => {
+ *   svc.doThing();
+ * };
+ * ```
+ */
+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>;
+/**
+ * Attributes passed to template functions.
+ */
+export interface TemplateAttrs {
+    /** The element's innerHTML before transformation */
+    children: string;
+    /** All attributes from the element */
+    [attr: string]: string;
+}
+/**
+ * Template can be a string or a function that receives element attributes and the element.
+ */
+export type TemplateOption = string | ((attrs: TemplateAttrs, el: Element) => string | Promise<string>);
+/**
+ * Options for directive registration.
+ */
+export interface DirectiveOptions {
+    /**
+     * Whether to create a new scope for this directive.
+     *
+     * @remarks
+     * When true, the directive creates a new scope that inherits
+     * from the parent scope via prototype chain.
+     *
+     * @defaultValue false
+     */
+    scope?: boolean;
+    /**
+     * Template for the directive's content.
+     *
+     * @remarks
+     * Can be a string or a function that receives the element's
+     * attributes and children, returning HTML.
+     *
+     * @example
+     * ```ts
+     * // Static template
+     * directive('my-modal', handler, {
+     *   template: '<div class="modal"><slot></slot></div>'
+     * });
+     *
+     * // Dynamic template with props
+     * directive('fancy-heading', null, {
+     *   template: ({ level, children }) => `<h${level}>${children}</h${level}>`
+     * });
+     *
+     * // Async template (e.g., dynamic import)
+     * directive('lazy-component', handler, {
+     *   template: () => import('./template.html?raw').then(m => m.default)
+     * });
+     * ```
+     */
+    template?: TemplateOption;
+    /**
+     * DI provider overrides for descendants.
+     *
+     * @remarks
+     * Maps injectable names to values. Descendants requesting these
+     * names via `$inject` will receive the provided values instead
+     * of global services.
+     *
+     * Useful for testing (mock services) or scoping services to a subtree.
+     *
+     * @example
+     * ```ts
+     * // Test harness with mock services
+     * directive('test-harness', null, {
+     *   scope: true,
+     *   provide: {
+     *     '$http': mockHttpClient,
+     *     'apiUrl': 'http://localhost:3000/test'
+     *   }
+     * });
+     *
+     * // Descendants get mock values
+     * directive('api-consumer', ($http, apiUrl) => {
+     *   $http.get(apiUrl + '/users');
+     * });
+     * ```
+     */
+    provide?: Record<string, unknown>;
+}
+/** Registered directive with options */
+export interface DirectiveRegistration {
+    fn: Directive<any> | null;
+    options: DirectiveOptions;
+}
+/**
+ * Register a directive by name.
+ *
+ * @remarks
+ * Directives are functions with `$inject` set to declare dependencies.
+ * If the name contains a hyphen and scope is true, it's also registered
+ * as a custom element.
+ *
+ * The function can be `null` for pure template directives that have no
+ * runtime behavior.
+ *
+ * @param name - The directive name (e.g., 'c-text' or 'todo-app')
+ * @param fn - The directive function, or null for template-only directives
+ * @param options - Registration options
+ *
+ * @example
+ * ```ts
+ * // Directive with behavior
+ * directive('todo-app', ($element, $state) => {
+ *   $state.todos = [];
+ * }, { scope: true });
+ *
+ * // Template-only directive
+ * directive('fancy-heading', null, {
+ *   template: ({ level, children }) => `<h${level}>${children}</h${level}>`
+ * });
+ * ```
+ */
+export declare function directive(name: string, fn: Directive<any> | null, options?: DirectiveOptions): void;
+/**
+ * Get a directive registration by name.
+ *
+ * @param name - The directive name
+ * @returns The directive registration (fn and options), or undefined if not found
+ */
+export declare function getDirective(name: string): DirectiveRegistration | undefined;
+/**
+ * Get a directive function by name.
+ *
+ * @param name - The directive name
+ * @returns The directive function, null for template-only directives, or undefined if not found
+ */
+export declare function getDirectiveFn(name: string): Directive<any> | null | undefined;
+/**
+ * Get all registered directive names.
+ *
+ * @returns Array of directive names
+ */
+export declare function getDirectiveNames(): string[];
+/**
+ * Clear all registered directives.
+ *
+ * @remarks
+ * Primarily useful for testing.
+ */
+export declare function clearDirectives(): void;
+export {};

package/dist/types.js

@@ -0,0 +1,110 @@
+/**
+ * Core types for gonia.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Execution mode for the framework.
+ */
+export var Mode;
+(function (Mode) {
+    /** Server-side rendering */
+    Mode["SERVER"] = "server";
+    /** Client-side hydration/runtime */
+    Mode["CLIENT"] = "client";
+})(Mode || (Mode = {}));
+/**
+ * Directive priority levels.
+ *
+ * @remarks
+ * Higher priority directives run first. Structural directives
+ * (like c-if, c-for) need to run before behavioral ones.
+ */
+export var DirectivePriority;
+(function (DirectivePriority) {
+    /** Structural directives that control DOM presence (c-if, c-for) */
+    DirectivePriority[DirectivePriority["STRUCTURAL"] = 1000] = "STRUCTURAL";
+    /** Template/transclusion directives */
+    DirectivePriority[DirectivePriority["TEMPLATE"] = 500] = "TEMPLATE";
+    /** Normal behavioral directives */
+    DirectivePriority[DirectivePriority["NORMAL"] = 0] = "NORMAL";
+})(DirectivePriority || (DirectivePriority = {}));
+/** Global directive registry */
+const directiveRegistry = new Map();
+/**
+ * Register a directive by name.
+ *
+ * @remarks
+ * Directives are functions with `$inject` set to declare dependencies.
+ * If the name contains a hyphen and scope is true, it's also registered
+ * as a custom element.
+ *
+ * The function can be `null` for pure template directives that have no
+ * runtime behavior.
+ *
+ * @param name - The directive name (e.g., 'c-text' or 'todo-app')
+ * @param fn - The directive function, or null for template-only directives
+ * @param options - Registration options
+ *
+ * @example
+ * ```ts
+ * // Directive with behavior
+ * directive('todo-app', ($element, $state) => {
+ *   $state.todos = [];
+ * }, { scope: true });
+ *
+ * // Template-only directive
+ * directive('fancy-heading', null, {
+ *   template: ({ level, children }) => `<h${level}>${children}</h${level}>`
+ * });
+ * ```
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function directive(name, fn, options = {}) {
+    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') {
+        // Defer to avoid circular deps - custom element class is created in scope.ts
+        queueMicrotask(() => {
+            import('./scope.js').then(({ registerDirectiveElement }) => {
+                registerDirectiveElement(name, fn, options);
+            });
+        });
+    }
+}
+/**
+ * Get a directive registration by name.
+ *
+ * @param name - The directive name
+ * @returns The directive registration (fn and options), or undefined if not found
+ */
+export function getDirective(name) {
+    return directiveRegistry.get(name);
+}
+/**
+ * Get a directive function by name.
+ *
+ * @param name - The directive name
+ * @returns The directive function, null for template-only directives, or undefined if not found
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function getDirectiveFn(name) {
+    return directiveRegistry.get(name)?.fn;
+}
+/**
+ * Get all registered directive names.
+ *
+ * @returns Array of directive names
+ */
+export function getDirectiveNames() {
+    return Array.from(directiveRegistry.keys());
+}
+/**
+ * Clear all registered directives.
+ *
+ * @remarks
+ * Primarily useful for testing.
+ */
+export function clearDirectives() {
+    directiveRegistry.clear();
+}

package/dist/vite/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Vite plugin exports.
+ *
+ * @packageDocumentation
+ */
+export { gonia, gonia as default } from './plugin.js';

package/dist/vite/index.js

@@ -0,0 +1,6 @@
+/**
+ * Vite plugin exports.
+ *
+ * @packageDocumentation
+ */
+export { gonia, gonia as default } from './plugin.js';