@estjs/template 0.0.16-beta.7 → 0.0.16-beta.9

package/dist/template.d.ts

@@ -1,6 +1,6 @@
 import { Signal, Computed } from '@estjs/signals';
-import { S as Scope } from './internal-DR5pJGCO.js';
-export { I as InjectionKey, i as inject, p as provide } from './internal-DR5pJGCO.js';
+import { S as Scope, I as InjectionKey } from './internal-DR5pJGCO.js';
+export { i as inject, p as provide } from './internal-DR5pJGCO.js';
 import { normalizeClassName } from '@estjs/shared';
 
 declare enum COMPONENT_STATE {
@@ -22,13 +22,11 @@ declare enum COMPONENT_TYPE {
     FRAGMENT = "fragment",
     PORTAL = "portal",
     SUSPENSE = "suspense",
-    FOR = "for"
+    FOR = "for",
+    TRANSITION = "transition",
+    TRANSITION_GROUP = "transition-group"
 }
 
-type AnyNode = Node | Component<any> | Element | string | number | boolean | null | undefined | AnyNode[] | (() => AnyNode) | Signal<AnyNode> | Computed<AnyNode>;
-type ComponentProps = Record<string, unknown>;
-type ComponentFn<P = ComponentProps> = (props: P) => AnyNode;
-
 declare class Component<P extends ComponentProps = {}> {
     readonly component: ComponentFn<P>;
     props: P;
@@ -92,56 +90,112 @@ declare function isComponent(node: unknown): node is Component;
  */
 declare function createComponent<P extends ComponentProps>(componentFn: ComponentFn<P>, props?: P): Component<P>;
 
+type AnyNode = Node | Component<any> | Element | string | number | boolean | null | undefined | AnyNode[] | (() => AnyNode) | Signal<AnyNode> | Computed<AnyNode>;
+type ComponentProps = Record<string, unknown>;
+type ComponentFn<P = ComponentProps> = (props: P) => AnyNode;
+/** Phase + plugin name passed to error/warn handlers. */
+interface ErrorInfo {
+    phase: 'install' | 'mount' | 'cleanup' | 'effect';
+    plugin?: string;
+}
 /**
- * Create a template factory function from HTML string.
- *
- * This function creates a reusable template factory that efficiently clones
- * DOM nodes from the provided HTML string. The template is parsed once.
- *
- * Security note: `template(html)` is a raw HTML entrypoint. The caller is
- * responsible for ensuring `html` is trusted and not derived from unsanitized
- * user input.
- *
- * @param html - The HTML string to create template from.
- * @returns Factory function that returns a cloned node of the template.
- * @throws {Error} When template content is empty or invalid.
+ * Application-level configuration. Plugins and user code can set these to
+ * customize framework behaviour without monkey-patching internals.
+ */
+interface AppConfig {
+    /** Invoked when an uncaught error propagates out of a plugin / lifecycle hook / effect. */
+    errorHandler?: (info: ErrorInfo, error: unknown) => void;
+    /** Custom warn handler (dev only). When set, framework `warn()` calls are redirected here. */
+    warnHandler?: (info: {
+        plugin?: string;
+    }, message: string) => void;
+}
+/**
+ * Context passed to every plugin's setup function. Plugins use this to
+ * register providers, hook lifecycle events, and report problems.
+ */
+interface AppContext {
+    /** Provide a value at the application root scope, retrievable via `inject()`. */
+    provide<T>(key: InjectionKey<T> | string | number, value: T): void;
+    /** Inject a value from the application scope. Plugins ordered later can read what earlier plugins provided. */
+    inject<T>(key: InjectionKey<T> | string | number, defaultValue?: T): T;
+    /** Register a callback that runs after the root component mounts. */
+    onMount(fn: () => void): void;
+    /** Register a callback that runs when the application is unmounted. */
+    onCleanup(fn: () => void): void;
+    /** Non-fatal report. Routed to config.warnHandler if set, otherwise a dev console warning. */
+    warn(message: string): void;
+    /** Fatal report. Throws — plugin setup fails, mount() rejects. */
+    error(message: string): never;
+    /** Application config — readable and mutable by plugins. */
+    config: AppConfig;
+    /** Framework version (injected by the build; empty string in unbundled tests). */
+    version: string;
+}
+/**
+ * Plugin definition.
  *
  * @example
- * ```typescript
- * const buttonTemplate = template('<button>Click me</button>');
- * const button1 = buttonTemplate(); // Creates first button instance
- * const button2 = buttonTemplate(); // Creates second button instance
+ * ```ts
+ * const router = definePlugin<{ routes: Route[] }>({
+ *   name: 'essor:router',
+ *   enforce: 'pre',
+ *   setup(ctx, options) {
+ *     ctx.provide(RouterKey, createRouter(options.routes));
+ *   },
+ * });
  * ```
  */
-declare function template(html: string): () => Node;
+interface Plugin<TOptions = void> {
+    /** Required. Used for dedup, error messages, ordering. */
+    name: string;
+    /** Coarse ordering bucket. Default 'default'. Order: pre → default → post; within bucket, array order wins. */
+    enforce?: 'pre' | 'default' | 'post';
+    /** Setup. May be async; mount() awaits it. */
+    setup(ctx: AppContext, options: TOptions): void | Promise<void>;
+}
+/** Plugin entry in `CreateAppOptions.plugins` — bare or paired with options. */
+type PluginEntry = Plugin<void> | readonly [Plugin<any>, unknown];
+/** Options accepted by the config-object form of `createApp(component, options)`. */
+interface CreateAppOptions {
+    plugins?: ReadonlyArray<PluginEntry>;
+    config?: Partial<AppConfig>;
+}
 /**
- * Create and mount an application with the specified component.
- *
- * This function initializes an application by mounting a root component
- * to a target DOM element. It handles target validation and cleanup.
- *
- * @param component - The root component function to mount.
- * @param target - CSS selector string or DOM element to mount to.
- * @returns Object with root component and unmount function.
+ * Application builder returned by `createApp(component)` or `createApp(component, options)`.
  *
  * @example
- * ```typescript
- * const App = () => template('<div>Hello World</div>')
- * const app = createApp(App, '#root');
- *
- * // Or with DOM element
- * const container = document.getElementById('app');
- * const app = createApp(App, container);
+ * ```ts
+ * await createApp(App, {
+ *   plugins: [router, [store, { initial: {} }]],
+ * }).mount('#root');
  * ```
  */
-declare function createApp<P extends ComponentProps = {}>(component: ComponentFn<P>, target: string | Element): {
-    root: Component<{}> | undefined;
-    unmount: () => void;
-} | undefined;
-declare function hydrate<P extends ComponentProps = {}>(component: ComponentFn<P>, target: string | Element): {
-    root: Component<{}> | undefined;
+interface App {
+    /** Application config. Mutate before mounting to install error/warn handlers. */
+    config: AppConfig;
+    /** Mount into the DOM. Returns a Promise when any plugin has async setup; sync otherwise. */
+    mount(target: string | Element): Promise<AppInstance | undefined> | AppInstance | undefined;
+    /** Hydrate over SSR HTML. Returns a Promise when any plugin has async setup; sync otherwise. */
+    hydrate(target: string | Element): Promise<AppInstance | undefined> | AppInstance | undefined;
+}
+/** A mounted application instance. */
+interface AppInstance {
+    /** The root Component wrapper (undefined if mounting produced raw nodes). */
+    root: Component | undefined;
+    /** Tear down the application: dispose scopes, remove DOM nodes. */
     unmount: () => void;
-} | undefined;
+}
+
+/**
+ * Create a reusable template factory from an HTML string. Parsed once, cloned per call.
+ * Caller is responsible for ensuring `html` is trusted.
+ */
+declare function template(html: string): () => Node;
+declare function createApp<P extends ComponentProps = {}>(component: ComponentFn<P>): App;
+declare function createApp<P extends ComponentProps = {}, A extends string | Element | CreateAppOptions = string | Element | CreateAppOptions>(component: ComponentFn<P>, arg: A): A extends string | Element ? AppInstance | undefined : App;
+declare function hydrate<P extends ComponentProps = {}>(component: ComponentFn<P>, target: string | Element): AppInstance | undefined | Promise<AppInstance | undefined>;
+declare function definePlugin<T = void>(plugin: Plugin<T>): Plugin<T>;
 
 type LifecycleHook = () => void | Promise<void>;
 /**
@@ -171,20 +225,21 @@ declare function onDestroy(hook: LifecycleHook): void;
  * Modifiers for `bind:*` two-way bindings.
  *
  * - `trim`   — strip surrounding whitespace
- * - `number` — coerce numeric strings to numbers (no-op on NaN)
+ * - `number` — coerce numeric strings to numbers (no-op on NaN / blank)
  * - `lazy`   — commit on `change` instead of `input`
+ *
+ * Unknown keys are ignored at runtime; the compiler rejects them at build time.
  */
 interface BindModifiers {
     trim?: boolean;
     number?: boolean;
     lazy?: boolean;
-    [key: string]: boolean | undefined;
 }
 /**
  * Creates a two-way binding between a DOM element property and a reactive model.
  *
- * - **Model → DOM** — a reactive `effect()` pushes model changes to the element.
- * - **DOM → Model** — an event listener reads user input and calls `setter`.
+ * - Model → DOM via a reactive `effect()`.
+ * - DOM → Model via an event listener that calls `setter`.
  *
  * @param node      Target element. `null` is tolerated (no-op).
  * @param prop      Bound property (`value` / `checked` / `files` / custom).
@@ -198,13 +253,13 @@ declare function bindElement(node: Element | null, prop: 'value' | 'checked' | '
  * Set up event delegation for specified event types.
  *
  * @param eventNames - Array of event names to delegate.
- * @param document - Document to attach events to (defaults to window.document).
+ * @param document - Document to attach events to (defaults to the global document).
  */
 declare function delegateEvents(eventNames: string[], document?: Document): void;
 /**
  * Clear all delegated events from document.
  *
- * @param document - Document to clear events from (defaults to window.document).
+ * @param document - Document to clear events from (defaults to the global document).
  */
 declare function clearDelegatedEvents(document?: Document): void;
 /**
@@ -265,17 +320,7 @@ declare function next(node: Node | null, step?: number): Node | null;
  */
 declare function nthChild(node: Node | null, index: number): Node | null;
 
-/**
- * Returns a new hydration key.
- *
- * @returns The new hydration key as a string.
- */
 declare function getHydrationKey(): string;
-/**
- * Resets the client-side hydration key counter.
- *
- * @returns {void}
- */
 declare function resetHydrationKey(): void;
 /**
  * Returns whether the runtime is currently in the hydration first-pass.
@@ -303,6 +348,8 @@ declare function beginHydration(root: Element): void;
  * @returns {void}
  */
 declare function endHydration(): void;
+declare function hydrationMarker(parent: Node | null, index: number): Comment | null;
+declare function hydrationAnchor(parent: Node | null, index: number): Node | null;
 /**
  * Returns a factory function that, when called at component render time:
  * - During hydration: increments the key, looks up the pre-built registry,
@@ -666,7 +713,7 @@ declare function defineAsyncComponent<P extends ComponentProps = ComponentProps>
 interface ForProps<T> {
     each: T[] | Signal<T[]> | (() => T[]);
     children: (item: T, index: number) => AnyNode;
-    key?: (item: T) => unknown;
+    key?: (item: T, index: number) => unknown;
     fallback?: () => AnyNode;
 }
 /**
@@ -678,4 +725,96 @@ interface ForProps<T> {
 declare function For<T>(props: ForProps<T>): Node;
 declare namespace For { }
 
-export { type AsyncComponentOptions, Component, type ComponentFn, type ComponentProps, For, Fragment, Portal, Suspense, addEvent, addEventListener, beginHydration, bindElement, child, clearDelegatedEvents, consumeTeleportAnchor, consumeTeleportBlock, createApp, createComponent, createResource, defineAsyncComponent, delegateEvents, endHydration, getHydrationKey, getRenderedElement, hydrate, insert, isComponent, isFragment, isHydrating, isPortal, isSuspense, next, normalizeClass, nthChild, omitProps, onDestroy, onMount, onUpdate, patchAttr, patchAttrHydrate, patchClass, patchClassHydrate, patchStyle, patchStyleHydrate, resetHydrationKey, setStyle, template };
+interface TransitionProps {
+    name?: string;
+    css?: boolean;
+    type?: 'transition' | 'animation';
+    appear?: boolean;
+    duration?: number | {
+        enter: number;
+        leave: number;
+    };
+    enterFromClass?: string;
+    enterActiveClass?: string;
+    enterToClass?: string;
+    appearFromClass?: string;
+    appearActiveClass?: string;
+    appearToClass?: string;
+    leaveFromClass?: string;
+    leaveActiveClass?: string;
+    leaveToClass?: string;
+    onBeforeEnter?: (el: Element) => void;
+    onEnter?: (el: Element, done: () => void) => void;
+    onAfterEnter?: (el: Element) => void;
+    onEnterCancelled?: (el: Element) => void;
+    onBeforeLeave?: (el: Element) => void;
+    onLeave?: (el: Element, done: () => void) => void;
+    onAfterLeave?: (el: Element) => void;
+    onLeaveCancelled?: (el: Element) => void;
+    children?: AnyNode | (() => AnyNode);
+}
+declare function Transition(props: TransitionProps): Node;
+/**
+ * Check if a node is a Transition component.
+ *
+ * @param node - Node to check.
+ * @returns True if node is a Transition.
+ */
+declare function isTransition(node: unknown): boolean;
+
+/**
+ * Props for `<TransitionGroup>`.
+ *
+ * Inherits every enter/leave knob from {@link TransitionProps} (name, css,
+ * type, duration, JS hooks, custom class overrides) and adds:
+ *
+ * - `each` / `key` — same shape as `<For>`; required for stable identity.
+ * - `tag` — wrapper element. Required so we have a layout root to measure
+ *   positions against and to anchor leaving items absolutely. Defaults to
+ *   `'div'`.
+ * - `moveClass` — class applied to elements during the FLIP move animation.
+ *   Defaults to `${name}-move`.
+ * - `children` — render function per item. May return an Element or a
+ *   Component instance (the latter is mounted, its first rendered Element
+ *   participates in the animations).
+ *
+ * `appear` is intentionally NOT supported: items mounted on the initial
+ * render do NOT animate. The appear-related props from {@link TransitionProps}
+ * are therefore omitted from this type. If you need first-frame animation,
+ * mount the group with an empty list and push items after mount.
+ */
+type GroupBaseProps = Omit<TransitionProps, 'children' | 'appear' | 'appearFromClass' | 'appearActiveClass' | 'appearToClass'>;
+interface TransitionGroupProps<T = unknown> extends GroupBaseProps {
+    each: T[] | Signal<T[]> | (() => T[]);
+    key: (item: T, index: number) => unknown;
+    tag?: string;
+    moveClass?: string;
+    children: (item: T, index: number) => unknown;
+}
+/**
+ * Animated keyed list with three coordinated animations:
+ *
+ *   - **enter** — new items fade/slide in using `${name}-enter-*` classes
+ *   - **leave** — removed items animate out (positioned absolutely so the
+ *     remaining items can reflow under FLIP), then are detached
+ *   - **move** — items that stayed but changed position run FLIP: snapshot
+ *     `getBoundingClientRect()` before reconcile, compute delta after,
+ *     invert via `transform`, then transition to identity under `moveClass`
+ *
+ * Each row owns its own scope (mirroring `<For>`), so signals/effects
+ * created inside `children()` are torn down when the row leaves.
+ *
+ * @example
+ * ```tsx
+ * <TransitionGroup name="list" each={items} key={(it) => it.id} tag="ul">
+ *   {(item) => <li>{item.label}</li>}
+ * </TransitionGroup>
+ * ```
+ */
+declare function TransitionGroup<T>(props: TransitionGroupProps<T>): Element;
+/**
+ * Type guard for the TransitionGroup component reference.
+ */
+declare function isTransitionGroup(node: unknown): boolean;
+
+export { type App, type AppConfig, type AppContext, type AppInstance, type AsyncComponentOptions, Component, type ComponentFn, type ComponentProps, type CreateAppOptions, type ErrorInfo, For, Fragment, InjectionKey, type Plugin, type PluginEntry, Portal, Suspense, Transition, TransitionGroup, type TransitionGroupProps, type TransitionProps, addEvent, addEventListener, beginHydration, bindElement, child, clearDelegatedEvents, consumeTeleportAnchor, consumeTeleportBlock, createApp, createComponent, createResource, defineAsyncComponent, definePlugin, delegateEvents, endHydration, getHydrationKey, getRenderedElement, hydrate, hydrationAnchor, hydrationMarker, insert, isComponent, isFragment, isHydrating, isPortal, isSuspense, isTransition, isTransitionGroup, next, normalizeClass, nthChild, omitProps, onDestroy, onMount, onUpdate, patchAttr, patchAttrHydrate, patchClass, patchClassHydrate, patchStyle, patchStyleHydrate, resetHydrationKey, setStyle, template };