@koppajs/koppajs-core 3.0.0

package/dist/types.d.ts

@@ -0,0 +1,364 @@
+export {};
+import './kpa.d.ts';
+import './globals.d.ts';
+/**
+ * Symbol to identify whether a function is bound to this.
+ */
+export declare const BOUND: unique symbol;
+/**
+ * Symbol to identify whether an object is a Proxy.
+ */
+export declare const IS_PROXY: unique symbol;
+/**
+ * Arguments for the Core.take() method.
+ * Either a ComponentSource with a name, or a Plugin/Module.
+ */
+export type TakeArgs = [ComponentSource, string] | [IPlugin | IModule];
+/**
+ * Generic function type.
+ */
+export type AnyFn = (...args: any[]) => unknown;
+/**
+ * Function that has been bound to a context.
+ */
+export type BoundFn = AnyFn & {
+    [BOUND]?: true;
+};
+/**
+ * Main Core API interface.
+ */
+export interface CoreCallable {
+    (): void;
+    take: {
+        (component: ComponentSource, name: string): void;
+        (pluginOrModule: IPlugin | IModule): void;
+    };
+}
+/**
+ * Registry for lifecycle hooks.
+ */
+export type LifecycleRegistry = Map<LifecycleHook, Set<HookCallback>>;
+/**
+ * Callback function for lifecycle hooks.
+ * @param context - Optional state context passed to the hook
+ */
+export type HookCallback = (context?: State | undefined) => Promise<void>;
+/**
+ * Context provided to plugins and modules during installation.
+ */
+export interface CoreCtx {
+    registerHook: (hookName: LifecycleHook, callback: HookCallback) => void;
+    take: CoreCallable['take'];
+}
+/**
+ * Shared base extension interface.
+ */
+export interface IBaseExtension {
+    /** Unique name of the extension */
+    name: string;
+    /**
+     * Installation method called when extension is registered.
+     * @param context - Core context with registration utilities
+     * @returns Optional cleanup function
+     */
+    install(context: CoreCtx): (() => void) | void;
+}
+/**
+ * Plugin extension interface.
+ * Plugins provide setup methods that run in component context.
+ */
+export interface IPlugin extends IBaseExtension {
+    /**
+     * Setup method called for each component instance.
+     * @this {State} - Component state as this context
+     * @returns Plugin data or cleanup function
+     */
+    setup(this: State): Record<string, unknown> | (() => void);
+    attach: never;
+}
+/**
+ * Internal helper type (no global augmentation of HTMLElement required).
+ */
+export type HTMLElementWithInstance = HTMLElement & {
+    instance?: ComponentInstance;
+};
+/**
+ * Context provided to modules during attachment.
+ */
+export interface ModuleContext {
+    element: HTMLElementWithInstance;
+    parent?: ComponentInstance;
+    core: {
+        take: CoreCallable['take'];
+    };
+}
+/**
+ * Module extension interface.
+ * Modules attach to component elements and provide element-level functionality.
+ */
+export interface IModule extends IBaseExtension {
+    /**
+     * Attach method called when component is created.
+     * @this {ModuleContext} - Module context with element and parent
+     * @returns Optional module data to attach to component
+     */
+    attach(this: ModuleContext): Record<string, unknown> | void;
+    setup?: never;
+}
+/**
+ * # ComponentSource Contract
+ *
+ * This interface defines the contract between the KoppaJS Vite Plugin and
+ * the Core runtime. The plugin produces ComponentSource objects when
+ * transforming `.kpa` files, and the core consumes them at runtime.
+ *
+ * ## Field Categories
+ *
+ * ### REQUIRED Fields (must exist, core will fail without them)
+ * - `template` - HTML template string
+ * - `script`   - JavaScript controller code string
+ * - `style`    - CSS style string (can be empty string)
+ *
+ * ### OPTIONAL Fields (may exist, core handles absence gracefully)
+ * - `scriptMap` - Sourcemap for debugging (null or object)
+ * - `type`      - Component composition mode ("options" | "composite")
+ * - `deps`      - Async import map for [ts] block dependencies
+ * - `structAttr`- Custom attribute name for structural identity
+ *
+ * ### IGNORED Fields (allowed but unused by core runtime)
+ * - Any additional fields not listed above are permitted and will be
+ *   ignored by the core runtime. This allows forward compatibility
+ *   with plugin extensions without breaking existing core versions.
+ *
+ * ## Version Compatibility
+ *
+ * The plugin is expected to emit exactly these fields. Extra fields
+ * (e.g., debug metadata) may be added by the plugin but will not be
+ * processed by the core.
+ *
+ * @see https://github.com/koppajs/koppajs-core for full documentation
+ */
+/**
+ * Async import function for a single dependency.
+ * Returns a promise that resolves to the imported module or value.
+ */
+export interface DepInfo {
+    (): Promise<unknown>;
+}
+/**
+ * Map of dependency identifiers to async import functions.
+ * Each key is the local identifier used in the component script,
+ * and the value is an async function that resolves the import.
+ */
+export type Deps = Record<string, DepInfo> | null;
+/**
+ * Component source payload produced by the Vite plugin for `.kpa` files.
+ *
+ * This is the primary interface for the Core ↔ Plugin contract.
+ * See the ComponentSource Contract documentation above for field categories.
+ */
+export interface ComponentSource {
+    /**
+     * HTML template string for the component.
+     * Contains the component's DOM structure with KoppaJS directives.
+     * @required
+     */
+    template: string;
+    /**
+     * JavaScript controller code string.
+     * Executed at runtime to produce the component controller.
+     * @required
+     */
+    script: string;
+    /**
+     * CSS style string for the component.
+     * Injected into document head with component-scoped ID.
+     * Can be empty string if component has no styles.
+     * @required
+     */
+    style: string;
+    /**
+     * Optional sourcemap payload for dynamic script execution.
+     * The vite-plugin emits this as a parsed sourcemap object (or null).
+     * The core runtime may re-attach this map for DevTools when evaluating scripts.
+     * @optional
+     */
+    scriptMap?: unknown | null;
+    /**
+     * Component composition type.
+     *
+     * - "options" (default): Creates a userContext that combines methods and state,
+     *   and binds it to `this` in lifecycle hooks and methods.
+     * - "composite": No userContext is created, no `this` binding occurs.
+     *   Used for components that compose behavior from multiple sources.
+     *
+     * If not specified, defaults to "options".
+     * @optional
+     */
+    type?: 'options' | 'composite';
+    /**
+     * Imported dependencies from [ts] block.
+     * Each key is the local identifier, value is an async function that resolves the import.
+     * The core runtime resolves these before evaluating the controller script.
+     * @optional
+     */
+    deps?: Deps;
+    /**
+     * Optional HTML attribute name to use for structural identity fallback.
+     * If specified and no structId is set via runtime helper, the reconciliation
+     * will attempt to read structId from this attribute.
+     * Default: 'data-k-struct'
+     * @optional
+     */
+    structAttr?: string;
+    /**
+     * Index signature to allow extra fields from the plugin.
+     * These fields are ignored by the core runtime but permitted
+     * for forward compatibility with plugin extensions.
+     *
+     * Common ignored fields might include:
+     * - Debug metadata
+     * - Plugin-specific configuration
+     * - Future extension points
+     */
+    [key: string]: unknown;
+}
+/**
+ * Public extension union.
+ */
+export type IExtension = ComponentSource | IPlugin | IModule;
+interface PropsDefinition {
+    type?: string;
+    required?: boolean;
+    default?: any;
+    regex?: string;
+}
+/**
+ * Event definition tuple: [eventType, target, handler]
+ * - eventType: DOM event name (e.g., "click", "input")
+ * - target: Selector string, Element, Window, or ref object
+ * - handler: Event handler function
+ */
+export type EventDefinition = [
+    string,
+    string | Element | Window | {
+        ref: string;
+        selector?: string;
+    },
+    AnyFn
+];
+/**
+ * Component reactive state object.
+ */
+export type State = Record<string, any>;
+/**
+ * Component methods object.
+ */
+export type Methods = Record<string, AnyFn>;
+/**
+ * Component props definition.
+ */
+export type Props = Record<string, PropsDefinition>;
+/**
+ * Component events array.
+ */
+export type Events = Array<EventDefinition>;
+/**
+ * List of property paths to watch for changes.
+ */
+export type WatchList = string[];
+/**
+ * Snapshot of watched properties.
+ */
+export type WatchListSnapshot = {
+    parent: object;
+    properties: string[];
+};
+/**
+ * Component element references.
+ */
+export type Refs = Record<string, HTMLElement>;
+/**
+ * Options for composeBySource function.
+ */
+export type ComposeOptions = {
+    /** Index of layer to write to when property doesn't exist in any layer */
+    defaultWriteIndex?: number;
+    /** Whether to include prototype properties in layer search */
+    includePrototype?: boolean;
+};
+export declare const lifecycleHooks: readonly ["created", "beforeMount", "mounted", "beforeUpdate", "updated", "beforeDestroy", "destroyed", "processed"];
+/**
+ * Available lifecycle hook names.
+ */
+export type LifecycleHook = (typeof lifecycleHooks)[number];
+/**
+ * Lifecycle hook handler function.
+ * @this {State} - Component state as this context
+ */
+export type LifecycleHandler = (this: State) => void | Promise<void>;
+interface LifecycleHooks {
+    created?: LifecycleHandler;
+    beforeMount?: LifecycleHandler;
+    mounted?: LifecycleHandler;
+    beforeUpdate?: LifecycleHandler;
+    updated?: LifecycleHandler;
+    beforeDestroy?: LifecycleHandler;
+    destroyed?: LifecycleHandler;
+    processed?: LifecycleHandler;
+}
+export interface Lifecycle {
+    on: (name: LifecycleHook, fn: (this: State) => void | Promise<void>) => void;
+    off: (name: LifecycleHook, fn: (this: State) => void | Promise<void>) => void;
+    clear: () => void;
+    emit(hook: LifecycleHook): Promise<void>;
+}
+/**
+ * Context provided to component script during compilation.
+ */
+export interface ComponentContext {
+    /** Element references */
+    $refs: Refs;
+    /** Parent component instance */
+    $parent?: ComponentInstance;
+    /** Emit event to parent components */
+    $emit: (eventName: string, ...args: unknown[]) => void;
+    /** Get plugin data */
+    $take: (pluginName: string) => Record<string, unknown> | AnyFn | void | undefined;
+    /** Dynamic module properties ($router, $store, ...) */
+    [key: `$${string}`]: unknown;
+}
+/**
+ * Compiled component script function.
+ * @param context - Component context with $refs, $parent, etc.
+ * @returns Component controller with state, methods, etc.
+ */
+export type CompiledScript = (context: ComponentContext) => ComponentController;
+/**
+ * Component controller returned from compiled script.
+ * Contains component definition: state, methods, props, events, etc.
+ */
+export interface ComponentController extends LifecycleHooks {
+    /** Component reactive state */
+    state?: State;
+    /** User context (composed from methods + state for "options" type) */
+    userContext?: State;
+    /** Component methods */
+    methods?: Methods;
+    /** Component props definition */
+    props?: Props;
+    /** Component events */
+    events?: Events;
+    /** Properties to watch for changes */
+    watchList?: WatchList;
+}
+/**
+ * Runtime component instance.
+ * Extends ComponentController with runtime properties like element, template, etc.
+ */
+export interface ComponentInstance extends ComponentContext, Omit<ComponentController, keyof LifecycleHooks> {
+    element: HTMLElementWithInstance;
+    template: HTMLTemplateElement;
+    readyPromise: Promise<void>;
+    lifecycleRegistry: LifecycleRegistry;
+}

package/dist/utils/dom.d.ts

@@ -0,0 +1,3 @@
+export declare const domExtensions: {
+    [key: string]: PropertyDescriptor;
+};

package/dist/utils/extend.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Extends global prototypes with KoppaJS helper utilities.
+ *
+ * - Object.prototype is always extended (always available in JS)
+ * - HTMLElement.prototype is only extended when DOM APIs exist
+ *
+ * In Node/SSR environments DOM-specific extensions are skipped automatically.
+ */
+export declare const extend: () => void;

package/dist/utils/extension-registry.d.ts

@@ -0,0 +1,10 @@
+import type { IModule, IPlugin } from '../types';
+/**
+ * Global registry for extensions (plugins and modules).
+ * Plugins provide setup methods for components.
+ * Modules provide attach methods for component elements.
+ */
+export declare const ExtensionRegistry: {
+    modules: Record<string, IModule>;
+    plugins: Record<string, IPlugin>;
+};

package/dist/utils/helper.d.ts

@@ -0,0 +1,55 @@
+import { type AnyFn, type State, type Methods } from '../types';
+/**
+ * Binds a function to a context once, preventing multiple bindings.
+ * Uses a symbol to mark bound functions.
+ * @param fn - Function to bind
+ * @param userContext - Context to bind function to
+ * @returns Bound function (or original if already bound or not a function)
+ */
+export declare function bindOnce(fn: AnyFn, userContext: State): AnyFn;
+/**
+ * Binds all methods from the `methods` object to the provided `userContext`.
+ * @param methods - A map of method names and functions
+ * @param userContext - The user context object (this context for user functions)
+ */
+export declare function bindMethods(methods: Methods, userContext: State): void;
+/**
+ * Checks if a string contains basic HTML tags.
+ * @param input - The input string to check
+ * @returns True if the string contains HTML-like syntax, otherwise false
+ */
+export declare function containsHTML(input: string): boolean;
+/**
+ * Safely retrieves a value from a nested object using a string path.
+ * Supports dot/bracket notation: "foo.bar[0].baz"
+ * Does NOT throw (returns undefined on invalid access).
+ * @param obj - Object to read from
+ * @param path - Property path (dot/bracket notation)
+ * @returns Value at path or undefined if not found
+ */
+export declare function getValueByPath(obj: unknown, path: string): unknown;
+/**
+ * Resolves a type constructor or string into a normalized lowercase type name.
+ * Used for comparing prop types during runtime validation.
+ * @param input - A string type name or a constructor function
+ * @returns A lowercase string type (e.g. "string", "array") or "unknown"
+ */
+export declare function getExpectedPropTypeName(input: unknown): string;
+/**
+ * Checks whether a string is a simple property path expression.
+ * Supports: foo.bar.baz, foo[0].bar, foo.bar[0].baz
+ * @param expression - Expression string to check
+ * @returns True if expression is a simple path
+ */
+export declare function isSimplePathExpression(expression: string): boolean;
+/**
+ * Sets a value on a nested object using a dot/bracket-notated path.
+ * Does NOT create missing objects/arrays. Children may not "invent" structure in parent.
+ * Throws descriptive errors when the path is invalid or non-writable.
+ * Supports bracket tokens like [0] or [key] (key treated as string unless numeric).
+ * @param obj - Object to write to
+ * @param path - Property path (dot/bracket notation)
+ * @param value - Value to set
+ * @throws Error if path is invalid or property is read-only
+ */
+export declare function setValueByPath(obj: Record<string, unknown>, path: string, value: unknown): void;

package/dist/utils/hook-registry.d.ts

@@ -0,0 +1,34 @@
+import type { State, HookCallback, LifecycleHook, LifecycleRegistry } from '../types';
+/**
+ * Creates a new lifecycle hook registry.
+ * @returns New empty lifecycle registry
+ */
+export declare function createHookRegistry(): LifecycleRegistry;
+/**
+ * Registers a hook callback for the given event name.
+ * Creates the internal Set if it doesn't exist yet.
+ * @param registry - Registry to register in, or "global" for global registry
+ * @param name - Lifecycle hook name
+ * @param cb - Callback function to register
+ */
+export declare function hookOn(registry: LifecycleRegistry | 'global', name: LifecycleHook, cb: HookCallback): void;
+/**
+ * Unregisters a specific hook callback for the given event name.
+ * @param registry - Registry to unregister from, or "global" for global registry
+ * @param name - Lifecycle hook name
+ * @param cb - Callback function to unregister
+ */
+export declare function hookOff(registry: LifecycleRegistry | 'global', name: LifecycleHook, cb: HookCallback): void;
+/**
+ * Emits an event to all registered callbacks for the given name.
+ * Each callback is wrapped in try-catch to prevent one failure from stopping others.
+ * @param registry - Registry to emit from, or "global" for global registry
+ * @param name - Lifecycle hook name
+ * @param context - Optional state context to pass to callbacks
+ */
+export declare function hookEmit(registry: LifecycleRegistry | 'global', name: LifecycleHook, context?: State): Promise<void>;
+/**
+ * Clears all registered hooks in the registry.
+ * @param registry - Registry to clear, or "global" for global registry
+ */
+export declare function hookClear(registry: LifecycleRegistry | 'global'): void;

package/dist/utils/identity.d.ts

@@ -0,0 +1,6 @@
+export declare const STRUCT_ID: unique symbol;
+export declare const SLOT_ID: unique symbol;
+export declare function setStructId(node: object, id: unknown): void;
+export declare function getStructId(node: object): unknown;
+export declare function setSlotId(node: object, id: unknown): void;
+export declare function getSlotId(node: object): unknown;

package/dist/utils/index.d.ts

@@ -0,0 +1,15 @@
+export * from './helper';
+export * from './dom';
+export { domExtensions } from './dom';
+export * from './object';
+export { objectExtensions } from './object';
+export * from './string';
+export * from './script';
+export * from './template-watch';
+export * from './hook-registry';
+export * from './logger';
+export { ExtensionRegistry } from './extension-registry';
+export * from './type-guards';
+export { extend } from './extend';
+export { reconcileDOM } from './reconcile';
+export * from './identity';

package/dist/utils/logger.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Logging system with configurable log levels and emoji indicators.
+ * Supports different configurations for development and production.
+ */
+/**
+ * Log levels in order of severity.
+ */
+export declare enum LogLevel {
+    DEBUG = 0,
+    INFO = 1,
+    WARN = 2,
+    ERROR = 3,
+    NONE = 4
+}
+type LogContext = {
+    component?: string;
+    method?: string;
+    [key: string]: unknown;
+};
+/**
+ * Logger class for consistent logging across the framework.
+ */
+declare class Logger {
+    private level;
+    private isDevelopment;
+    /**
+     * Initialize logger with environment detection.
+     * @param options - Logger configuration options
+     * @param options.level - Minimum log level (defaults based on environment)
+     * @param options.isDevelopment - Whether in development mode
+     */
+    init(options?: {
+        level?: LogLevel;
+        isDevelopment?: boolean;
+    }): void;
+    /**
+     * Set the minimum log level.
+     * @param level - Minimum log level to display
+     */
+    setLevel(level: LogLevel): void;
+    /**
+     * Get current log level.
+     * @returns Current minimum log level
+     */
+    getLevel(): LogLevel;
+    private shouldLog;
+    private formatMessage;
+    /**
+     * Log an error message.
+     * @param message - Error message
+     * @param args - Additional arguments to log
+     */
+    error(message: string, ...args: any[]): void;
+    /**
+     * Log a warning message.
+     * @param message - Warning message
+     * @param args - Additional arguments to log
+     */
+    warn(message: string, ...args: any[]): void;
+    /**
+     * Log an info message.
+     * @param message - Info message
+     * @param args - Additional arguments to log
+     */
+    info(message: string, ...args: any[]): void;
+    /**
+     * Log a debug message.
+     * @param message - Debug message
+     * @param args - Additional arguments to log
+     */
+    debug(message: string, ...args: any[]): void;
+    /**
+     * Log an error with context information.
+     * @param message - Error message
+     * @param context - Context object with additional information
+     * @param error - Optional error object
+     */
+    errorWithContext(message: string, context: LogContext, error?: Error | unknown): void;
+    /**
+     * Log a warning with context information.
+     * @param message - Warning message
+     * @param context - Context object with additional information
+     */
+    warnWithContext(message: string, context: LogContext): void;
+}
+export declare const logger: Logger;
+export {};

package/dist/utils/object.d.ts

@@ -0,0 +1,3 @@
+export declare const objectExtensions: {
+    [key: string]: PropertyDescriptor;
+};

package/dist/utils/reconcile.d.ts

@@ -0,0 +1,23 @@
+/**
+ * DOM Reconciliation Utility
+ *
+ * Provides efficient DOM diffing to update the DOM without destroying
+ * and recreating custom element instances. This prevents infinite mount
+ * loops when parent components re-render.
+ */
+/**
+ * Reconciles the DOM content of a host element with new content.
+ * This is the main entry point for DOM reconciliation.
+ *
+ * The algorithm:
+ * 1. For the first render (host has no children), simply append the new content
+ * 2. For subsequent renders, diff the existing children against new content
+ * 3. Preserve custom element instances where possible
+ * 4. Only update what has changed
+ *
+ * @param host - The host element to update
+ * @param newContent - The new DocumentFragment with desired content
+ * @param isFirstRender - Whether this is the initial render
+ * @param structAttr - Optional attribute name for structural identity fallback
+ */
+export declare function reconcileDOM(host: HTMLElement, newContent: DocumentFragment, isFirstRender: boolean, structAttr?: string): void;

package/dist/utils/script.d.ts

@@ -0,0 +1,18 @@
+import type { CompiledScript } from '../types';
+/**
+ * Resolved dependencies object passed to the compiled script.
+ * Keys are the local identifiers, values are the resolved import values.
+ */
+export type ResolvedDeps = Record<string, unknown>;
+/**
+ * Compiles component script string into an executable function.
+ * Exposes context variables ($refs, $parent, etc.) and dynamic module properties.
+ * Optionally injects resolved dependencies as local variables.
+ *
+ * @param strg - Component script string
+ * @param resolvedDeps - Optional resolved dependencies to inject as local variables
+ * @returns Compiled script function
+ * @throws Error if compilation fails
+ * @throws SyntaxError if user script redeclares an injected dependency name
+ */
+export declare function compileCode(strg: string, resolvedDeps?: ResolvedDeps): CompiledScript;

package/dist/utils/string.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Converts a kebab-case string to camelCase.
+ * @param s - The kebab-case string to convert
+ * @returns The converted camelCase string
+ */
+export declare function kebabToCamel(s: string): string;
+/**
+ * Evaluates a JavaScript expression in a controlled, restricted scope.
+ * Blocks access to dangerous globals (window, document, eval, etc.).
+ * Treats simple property paths as "safe" and resolves them via getValueByPath.
+ * Evaluates complex expressions using Function, but only with variables from state.
+ * Functions are called with state as this context.
+ * Note: This is not a full sandbox. It's "restricted and pragmatic".
+ * @param expression - Expression string to evaluate
+ * @param state - State object to use as context
+ * @returns Evaluated result or undefined on error/forbidden keywords
+ */
+export declare function evaluateExpression(expression: string, state?: Record<string, unknown>): unknown;

package/dist/utils/template-watch.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Extracts property paths from template expressions for automatic watching.
+ * Parses {{ expression }} syntax and extracts simple property paths.
+ * @param templateHtml - Template HTML string
+ * @returns Array of unique property paths to watch
+ */
+export declare function extractWatchListFromTemplate(templateHtml: string): string[];