@deijose/nix-js 1.0.4 → 1.0.6

package/dist/lib/nix/router.d.ts

@@ -0,0 +1,253 @@
+import type { Signal } from "./reactivity";
+import { NixComponent } from "./lifecycle";
+import type { NixTemplate } from "./template";
+/**
+ * Value returned (or resolved) by a navigation guard.
+ * - `false`  — cancel the navigation.
+ * - `string` — redirect to that path.
+ * - `void` / `undefined` — allow the navigation.
+ */
+export type NavigationGuardResult = void | undefined | false | string;
+/**
+ * A navigation guard function.
+ *
+ * @param to   Destination pathname (e.g. `"/admin"`).
+ * @param from Current pathname before the navigation.
+ * @returns `false` to cancel, a path string to redirect, or nothing to allow.
+ *          May return a Promise for async guard logic.
+ *
+ * @example
+ * router.beforeEach((to, from) => {
+ *   if (!auth.isLoggedIn && to !== "/login") return "/login";
+ * });
+ */
+export type NavigationGuard = (to: string, from: string) => NavigationGuardResult | Promise<NavigationGuardResult>;
+export interface RouteRecord {
+    /**
+     * Segmento de ruta. Soporta:
+     *  - Literal:   "/about", "/users"
+     *  - Parámetro: "/users/:id", "/posts/:slug/comments/:cid"
+     *  - Wildcard:  "*"  (fallback global o de prefijo con children)
+     *
+     * Los paths de children se concatenan con el del padre.
+     *
+     * @example
+     * { path: "/users/:id", component: UserDetail }
+     * // Navegar a "/users/42" → params.value = { id: "42" }
+     *
+     * @example
+     * { path: "/dash", component: DashLayout, children: [
+     *   { path: "/users",   component: UsersPage },
+     * ]}
+     * // Genera las rutas planas: /dash, /dash/users
+     */
+    path: string;
+    /** Factory que devuelve la vista a renderizar en este nivel */
+    component: () => NixTemplate | NixComponent;
+    /**
+     * Rutas hijas. Sus paths se unen con el del padre.
+     * El componente padre debe incluir `new RouterView(1)` para renderizarlas.
+     */
+    children?: RouteRecord[];
+    /**
+     * Guard de nivel de ruta. Se ejecuta solo al entrar en esta ruta concreta.
+     * Misma semántica de retorno que `beforeEach`.
+     *
+     * @example
+     * { path: "/admin", component: () => new AdminPage(),
+     *   beforeEnter: (to, from) => {
+     *     if (!isAdmin) return "/";
+     *   }}
+     */
+    beforeEnter?: NavigationGuard;
+}
+/**
+ * Callback for `afterEach` hooks — receives the committed `to` and `from` paths.
+ */
+export type AfterEachHook = (to: string, from: string) => void;
+/**
+ * Result of `router.resolve(path)` — inspect what would match without navigating.
+ */
+export interface ResolvedRoute {
+    /** Whether the path matched any registered route. */
+    matched: boolean;
+    /** Extracted route params (empty object if no match). */
+    params: Record<string, string>;
+    /** The matched route record, or `undefined` if no match. */
+    route: RouteRecord | undefined;
+}
+export interface Router {
+    /** Señal con la ruta activa actual (pathname, p.ej. "/users/42") */
+    readonly current: Signal<string>;
+    /**
+     * Señal con los parámetros dinámicos de la ruta activa (:id, :slug…).
+     * Se actualiza síncronamente con cada `navigate()`.
+     *
+     * @example
+     * // Ruta: "/users/:id"  →  navigate("/users/42")
+     * router.params.value  // { id: "42" }
+     */
+    readonly params: Signal<Record<string, string>>;
+    /**
+     * Señal con los query params de la URL (?clave=valor…).
+     * Se actualiza síncronamente con cada `navigate()`.
+     *
+     * @example
+     * router.navigate("/users?page=2&sort=name")
+     * router.query.value  // { page: "2", sort: "name" }
+     *
+     * @example
+     * router.navigate("/users", { page: 2, sort: "name" })
+     * router.query.value  // { page: "2", sort: "name" }
+     */
+    readonly query: Signal<Record<string, string>>;
+    /**
+     * Navegar a una ruta nueva (pushState + actualiza señales).
+     * Si hay guards registrados, la navegación espera a que todos pasen.
+     *
+     * @param path     Ruta destino. Puede incluir query string: "/users?page=2"
+     * @param query    Query params como objeto. Se mezclan con los del path.
+     *                 Un valor `null`/`undefined` elimina el parámetro.
+     */
+    navigate(path: string, query?: Record<string, string | number | boolean | null | undefined>): void;
+    /**
+     * Navigate without adding an entry to the browser history.
+     * Uses `history.replaceState` instead of `pushState`.
+     * Guards still run normally.
+     *
+     * @param path   Destination path. May include query string.
+     * @param query  Query params as an object.
+     *
+     * @example
+     * // After login — pressing "back" won't return to /login
+     * router.replace("/home");
+     */
+    replace(path: string, query?: Record<string, string | number | boolean | null | undefined>): void;
+    /**
+     * Go back one entry in the browser history.
+     * Equivalent to `history.back()`.
+     *
+     * @example
+     * router.back();
+     */
+    back(): void;
+    /**
+     * Go forward one entry in the browser history.
+     * Equivalent to `history.forward()`.
+     *
+     * @example
+     * router.forward();
+     */
+    forward(): void;
+    /**
+     * Move `delta` entries in the browser history.
+     * Negative values go back, positive go forward.
+     *
+     * @example
+     * router.go(-2); // two pages back
+     * router.go(1);  // same as forward()
+     */
+    go(delta: number): void;
+    /**
+     * Check if a path is currently active.
+     * By default performs an exact match.
+     *
+     * @param path   The path to test.
+     * @param exact  If `false`, matches when `current` starts with `path`.
+     *               Default: `true`.
+     *
+     * @example
+     * router.isActive("/admin");         // exact match
+     * router.isActive("/admin", false);  // prefix: /admin/users → true
+     */
+    isActive(path: string, exact?: boolean): boolean;
+    /**
+     * Inspect what route would match a given path without actually navigating.
+     *
+     * @example
+     * const info = router.resolve("/user/42");
+     * // { matched: true, params: { id: "42" }, route: { path: "/user/:id", ... } }
+     */
+    resolve(path: string): ResolvedRoute;
+    /** Árbol de rutas original (tal como se pasó a createRouter) */
+    readonly routes: RouteRecord[];
+    /**
+     * Registra un guard de navegación global.
+     * Se ejecuta (en orden de registro) antes de cada navegación.
+     *
+     * Retorna una función para eliminar el guard.
+     *
+     * @example
+     * const stop = router.beforeEach((to, from) => {
+     *   if (!auth && to !== "/login") return "/login";
+     * });
+     * stop(); // elimina el guard
+     */
+    beforeEach(guard: NavigationGuard): () => void;
+    /**
+     * Register a hook that runs after every successful navigation.
+     * Useful for analytics, scroll reset, etc.
+     *
+     * Returns a function to remove the hook.
+     *
+     * @example
+     * const stop = router.afterEach((to, from) => {
+     *   window.scrollTo(0, 0);
+     * });
+     * stop();
+     */
+    afterEach(hook: AfterEachHook): () => void;
+}
+/**
+ * Crea el router History API y lo establece como singleton activo del módulo.
+ * Usa `history.pushState` — URLs limpias sin `#`.
+ * `RouterView` y `Link` lo consumen automáticamente — no necesitan que se los pases.
+ *
+ * @note En producción el servidor debe responder con `index.html` para cualquier
+ * ruta no-archivo. Vite dev y `vite preview` lo hacen automáticamente.
+ */
+export declare function createRouter(routes: RouteRecord[]): Router;
+/**
+ * Devuelve el router activo (singleton).
+ * Útil dentro de componentes para acceder a `params` y `current` sin prop-drilling.
+ *
+ * @example
+ * class UserDetail extends NixComponent {
+ *   render() {
+ *     return html`<div>User: ${() => useRouter().params.value.id}</div>`;
+ *   }
+ * }
+ */
+export declare function useRouter(): Router;
+/**
+ * @internal — Resets the router singleton. Used by tests to avoid
+ * "A router already exists" warnings between test cases.
+ */
+export declare function _resetRouter(): void;
+/**
+ * Renderiza el componente de la ruta activa en el nivel `depth`.
+ *
+ * - `new RouterView()`  → nivel raíz (depth 0).
+ * - `new RouterView(1)` → primer nivel de rutas anidadas. Úsalo dentro del
+ *   componente padre para que renderice el hijo correspondiente.
+ *
+ * Consume el router singleton — no requiere que se le pase el router.
+ */
+export declare class RouterView extends NixComponent {
+    private _depth;
+    constructor(depth?: number);
+    render(): NixTemplate;
+}
+/**
+ * Enlace de navegación reactivo que se estiliza como activo/inactivo según la
+ * ruta actual. Consume el router singleton — no requiere que se le pase.
+ *
+ * @example
+ * new Link("/about", "About")
+ */
+export declare class Link extends NixComponent {
+    private _to;
+    private _label;
+    constructor(to: string, label: string);
+    render(): NixTemplate;
+}

package/dist/lib/nix/store.d.ts

@@ -0,0 +1,40 @@
+import { Signal } from "./reactivity";
+/** Transforma cada propiedad del estado inicial en su Signal correspondiente. */
+export type StoreSignals<T extends Record<string, unknown>> = {
+    readonly [K in keyof T]: Signal<T[K]>;
+};
+/** Tipo del store tal como lo ve el usuario. */
+export type Store<T extends Record<string, unknown>, A extends Record<string, unknown> = Record<never, never>> = StoreSignals<T> & A & {
+    /**
+     * Restaura todos los signals a sus valores iniciales.
+     * Equivalente a hacer `signal.value = initialValue` en cada propiedad.
+     */
+    $reset(): void;
+};
+/**
+ * Crea un store reactivo global.
+ *
+ * @param initialState  Objeto plano con los valores iniciales.
+ * @param actionsFactory  Función que recibe los signals y retorna acciones.
+ *
+ * @example
+ *   // Sin acciones
+ *   const theme = createStore({ dark: false, fontSize: 16 });
+ *   theme.dark.value = true;
+ *
+ * @example
+ *   // Con acciones
+ *   const cart = createStore(
+ *     { items: [] as string[], total: 0 },
+ *     (s) => ({
+ *       add:    (item: string) => s.items.update(arr => [...arr, item]),
+ *       clear:  ()             => cart.$reset(),
+ *     })
+ *   );
+ *
+ *   cart.add("Manzana");
+ *   cart.items.value;      // ["Manzana"]
+ *   cart.clear();
+ *   cart.items.value;      // []
+ */
+export declare function createStore<T extends Record<string, unknown>, A extends Record<string, unknown> = Record<never, never>>(initialState: T, actionsFactory?: (signals: StoreSignals<T>) => A): Store<T, A>;

package/dist/lib/nix/template.d.ts

@@ -0,0 +1,380 @@
+import type { NixComponent } from "./lifecycle";
+export interface NixTemplate {
+    readonly __isNixTemplate: true;
+    /** Monta el template en un contenedor (uso externo / raíz). */
+    mount(container: Element | string): NixMountHandle;
+    /**
+     * @internal — Renderiza el template antes del nodo `before` (o al final
+     * de `parent` si `before` es null).  Retorna una función de limpieza.
+     */
+    _render(parent: Node, before: Node | null): () => void;
+}
+export interface NixMountHandle {
+    unmount(): void;
+}
+/**
+ * Contenedor para una referencia directa a un elemento DOM.
+ * Se asigna automáticamente cuando el template se monta y se limpia al
+ * desmontarse.
+ *
+ * @example
+ * const inputRef = ref<HTMLInputElement>();
+ * html`<input ref=${inputRef} />`
+ * // después del mount:
+ * inputRef.el?.focus();
+ */
+export interface NixRef<T extends Element = Element> {
+    el: T | null;
+}
+/**
+ * Crea un objeto `NixRef` vacío.
+ * Pásalo como valor del atributo especial `ref` en un template para que
+ * Nix.js rellene automáticamente `ref.el` con el elemento real del DOM.
+ */
+export declare function ref<T extends Element = Element>(): NixRef<T>;
+/**
+ * Toggles the visibility of an element **without unmounting it** from the DOM
+ * (sets `style.display = "none"` when hidden, restores it when visible).
+ *
+ * Use the `show` or `hide` attribute bindings inside templates — or call
+ * this helper directly for imperative use outside of templates.
+ *
+ * ### Template usage
+ * ```html
+ * <!-- show: element is visible when condition is truthy -->
+ * <div show=${() => isVisible.value}>...</div>
+ *
+ * <!-- hide: element is hidden when condition is truthy (inverse of show) -->
+ * <div hide=${() => isLoading.value}>Submit</div>
+ * ```
+ *
+ * ### Difference from conditional rendering
+ * | | `show` / `hide` | conditional (`() => condition ? html\`…\` : null`) |
+ * |---|---|---|
+ * | DOM node kept | ✅ always | ❌ destroyed when hidden |
+ * | Lifecycle hooks | not called on toggle | called on every toggle |
+ * | Use when | hiding/showing frequently | rarely shown alternatives |
+ *
+ * ### Imperative usage (outside a template)
+ * ```typescript
+ * import { showWhen } from "@deijose/nix-js";
+ * import { effect } from "@deijose/nix-js";
+ *
+ * const el = document.getElementById("my-panel")!;
+ * // Reactively controlled:
+ * effect(() => showWhen(el, isVisible.value));
+ * ```
+ */
+export declare function showWhen(el: HTMLElement, condition: boolean): void;
+/**
+ * Resultado de `repeat()` — lista con keys para diffing eficiente.
+ * El template engine lo reconoce y solo añade/mueve/elimina los nodos
+ * que realmente cambiaron, preservando el DOM de los items estables.
+ */
+export interface KeyedList<T = unknown> {
+    readonly __isKeyedList: true;
+    readonly items: T[];
+    readonly keyFn: (item: T, index: number) => string | number;
+    readonly renderFn: (item: T, index: number) => NixTemplate | NixComponent;
+}
+/**
+ * Crea una lista con keys para diffing eficiente.
+ * Úsalo en lugar de `.map()` cuando la lista cambia frecuentemente.
+ *
+ * @param items    Array reactivo de datos
+ * @param keyFn    Devuelve una clave única por item (p.ej. `item => item.id`)
+ * @param renderFn Devuelve el template/componente para cada item
+ *
+ * @example
+ * ${() => repeat(
+ *   users.value,
+ *   u => u.id,
+ *   u => html`<li>${u.name}</li>`
+ * )}
+ */
+export declare function repeat<T>(items: T[], keyFn: (item: T, index: number) => string | number, renderFn: (item: T, index: number) => NixTemplate | NixComponent): KeyedList<T>;
+/**
+ * Renders `content` into `target` instead of the current position in the tree.
+ * The portal is cleaned up automatically when the parent template is unmounted.
+ *
+ * Use this to render modals, tooltips, notifications, or dropdowns outside of
+ * your component tree — typically into `document.body` — so they are not clipped
+ * by `overflow: hidden` or buried under other stacking contexts.
+ *
+ * The portal returns a `NixTemplate`, so it works as a node value anywhere in
+ * a template, including inside reactive conditionals: the portal is
+ * mounted/unmounted together with whatever controls its condition.
+ *
+ * @param content  Template or component to render inside the portal.
+ * @param target   CSS selector or `Element` to render into. Defaults to `document.body`.
+ *
+ * @example Reactive modal
+ * ```typescript
+ * import { signal, portal, html } from "@deijose/nix-js";
+ *
+ * const isOpen = signal(false);
+ *
+ * html`
+ *   <button @click=${() => { isOpen.value = true; }}>Open</button>
+ *
+ *   ${() => isOpen.value
+ *     ? portal(html`
+ *         <div class="overlay" @click=${() => { isOpen.value = false; }}>
+ *           <div class="modal" @click.stop=${() => {}}>
+ *             <h2>Hello from a portal!</h2>
+ *             <button @click=${() => { isOpen.value = false; }}>Close</button>
+ *           </div>
+ *         </div>
+ *       `)
+ *     : null
+ *   }
+ * `
+ * ```
+ *
+ * @example Custom target
+ * ```typescript
+ * portal(html`<div class="toast">Saved!</div>`, "#toast-root")
+ * portal(html`<Tooltip />`, document.getElementById("tooltip-layer")!)
+ * ```
+ */
+/**
+ * Opaque token created by `createPortalOutlet()`.
+ *
+ * Pass it to `portalOutlet()` to declare the DOM anchor where portals targeting
+ * this outlet will render, and to `portal(content, outlet)` as the target.
+ *
+ * @see createPortalOutlet
+ * @see portalOutlet
+ */
+export interface PortalOutlet {
+    readonly __isPortalOutlet: true;
+    /** @internal — resolved DOM container; set when `portalOutlet()` is mounted */
+    _container: Element | null;
+}
+/**
+ * Creates a `PortalOutlet` token — a lightweight, typed anchor point that
+ * decouples *where* a portal renders from direct DOM access.
+ * No CSS selectors, no `document.querySelector`, no manual element references.
+ *
+ * ### Workflow
+ * 1. Create the token at module or component scope.
+ * 2. Place `${portalOutlet(outlet)}` in your layout template to declare the anchor.
+ * 3. From any child: `portal(content, outlet)` renders into that anchor.
+ *
+ * @example
+ * ```typescript
+ * const modalOutlet = createPortalOutlet();
+ *
+ * // Layout:
+ * html`
+ *   <main>${mainContent}</main>
+ *   ${portalOutlet(modalOutlet)}
+ * `
+ *
+ * // Child (any depth):
+ * html`${() => show.value ? portal(html\`<Modal />\`, modalOutlet) : null}`
+ * ```
+ */
+export declare function createPortalOutlet(): PortalOutlet;
+/**
+ * Declares the DOM anchor for a `PortalOutlet` inside a template.
+ * Creates a `<div data-nix-outlet>` at this position; portals targeting
+ * `outlet` will render their content as children of that div.
+ *
+ * The anchor's lifecycle follows its parent template — when the parent
+ * unmounts, the outlet div and any portals inside it are cleaned up.
+ *
+ * @example
+ * ```typescript
+ * mount(html`
+ *   <div class="app">
+ *     <main>${mainContent}</main>
+ *     ${portalOutlet(modalOutlet)}
+ *   </div>
+ * `, document.body);
+ * ```
+ */
+export declare function portalOutlet(outlet: PortalOutlet): NixTemplate;
+export declare function portal(content: NixTemplate | NixComponent, target?: Element | string | PortalOutlet | NixRef<Element>): NixTemplate;
+/**
+ * Provides a `PortalOutlet` to descendant components via the inject system.
+ * Must be called inside `onInit()` of a `NixComponent`.
+ *
+ * Eliminates prop drilling: any descendant can call `injectOutlet()` to
+ * obtain the outlet without it being passed through every layer.
+ *
+ * @example
+ * ```typescript
+ * class AppLayout extends NixComponent {
+ *   private outlet = createPortalOutlet();
+ *   onInit() { provideOutlet(this.outlet); }
+ *   render() {
+ *     return html`
+ *       <main>...</main>
+ *       ${portalOutlet(this.outlet)}
+ *     `;
+ *   }
+ * }
+ * ```
+ */
+export declare function provideOutlet(outlet: PortalOutlet): void;
+/**
+ * Injects the nearest `PortalOutlet` provided by an ancestor component.
+ * Returns `undefined` if no ancestor has called `provideOutlet()`.
+ *
+ * Use `portal(content, injectOutlet())` to render into the ancestor's outlet
+ * with no CSS selectors, no `document.querySelector`, and no prop drilling.
+ *
+ * @example
+ * ```typescript
+ * class ToastButton extends NixComponent {
+ *   private outlet: PortalOutlet | undefined;
+ *   private active  = signal(false);
+ *   onInit() { this.outlet = injectOutlet(); }
+ *   render() {
+ *     return html`
+ *       <button @click=${() => { this.active.value = true; }}>Notify</button>
+ *       ${() => this.active.value
+ *         ? portal(html\`<div class="toast">Done!</div>\`, this.outlet)
+ *         : null
+ *       }
+ *     `;
+ *   }
+ * }
+ * ```
+ */
+export declare function injectOutlet(): PortalOutlet | undefined;
+/**
+ * Fallback value for `createErrorBoundary()`:
+ * - A static `NixTemplate` or `NixComponent` — always render this on error.
+ * - A function `(err) => NixTemplate | NixComponent` — render based on the error.
+ */
+export type ErrorFallback = NixTemplate | NixComponent | ((err: unknown) => NixTemplate | NixComponent);
+/**
+ * Wraps `content` in an error boundary. If any error is thrown during the
+ * **initial render** or during a **reactive update** inside `content`, the
+ * boundary automatically:
+ * 1. Tears down the broken subtree (effects, event listeners, DOM).
+ * 2. Renders `fallback` in its place — without crashing the rest of the app.
+ *
+ * Errors caught:
+ * - `onInit()` / `render()` throws in any `NixComponent` inside `content`
+ * - Throws inside `html\`\`` binding expressions during initial render
+ * - Reactive re-renders: effects created inside `content` that throw when
+ *   a signal changes
+ *
+ * Not caught (same as React):
+ * - Event handler throws (wrap those with your own try/catch)
+ * - Async code (Promises, `setTimeout`, etc.)
+ * - Errors thrown inside `fallback` itself (propagate to the parent boundary)
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { createErrorBoundary, html, signal } from "@deijose/nix-js";
+ *
+ * mount(
+ *   createErrorBoundary(
+ *     new MyWidget(),
+ *     (err) => html`<div class="error">Widget failed: ${String(err)}</div>`
+ *   ),
+ *   "#app"
+ * );
+ * ```
+ *
+ * @example Static fallback
+ * ```typescript
+ * createErrorBoundary(
+ *   html`${() => riskyValue.value}`,
+ *   html`<p>Something went wrong.</p>`
+ * )
+ * ```
+ *
+ * @example Nested boundaries (inner catches first)
+ * ```typescript
+ * createErrorBoundary(
+ *   html`
+ *     <header>...</header>
+ *     ${createErrorBoundary(new RiskyWidget(), html`<p>Widget error</p>`)}
+ *   `,
+ *   html`<p>App-level error</p>`
+ * )
+ * ```
+ */
+export declare function createErrorBoundary(content: NixTemplate | NixComponent, fallback: ErrorFallback): NixTemplate;
+/**
+ * Options for `transition()`.  All class-name overrides are optional — by
+ * default they are derived from `name` (default `"nix"`).
+ *
+ * | phase        | from class        | active class        | to class        |
+ * |--------------|-------------------|---------------------|-----------------|
+ * | enter        | `{n}-enter-from`  | `{n}-enter-active`  | `{n}-enter-to`  |
+ * | leave        | `{n}-leave-from`  | `{n}-leave-active`  | `{n}-leave-to`  |
+ */
+export interface TransitionOptions {
+    /**
+     * Prefix for all generated CSS classes.  Default `"nix"`.
+     * e.g. `name: "fade"` generates `.fade-enter-from`, `.fade-leave-to`, …
+     */
+    name?: string;
+    /** Override the enter-from class individually. */
+    enterFrom?: string;
+    /** Override the enter-active class individually. */
+    enterActive?: string;
+    /** Override the enter-to class individually. */
+    enterTo?: string;
+    /** Override the leave-from class individually. */
+    leaveFrom?: string;
+    /** Override the leave-active class individually. */
+    leaveActive?: string;
+    /** Override the leave-to class individually. */
+    leaveTo?: string;
+    /**
+     * When `true` the enter transition also plays on the very first render
+     * (similar to Vue's `appear`).  Default `false`.
+     */
+    appear?: boolean;
+    /**
+     * Fallback duration in **milliseconds** used when no `transition-duration`
+     * or `animation-duration` is found on the element via `getComputedStyle`.
+     */
+    duration?: number;
+    /** Called synchronously right before the enter classes are added. */
+    onBeforeEnter?: (el: Element) => void;
+    /** Called after the enter transition has fully completed. */
+    onAfterEnter?: (el: Element) => void;
+    /** Called synchronously right before the leave classes are added. */
+    onBeforeLeave?: (el: Element) => void;
+    /** Called after the leave transition has fully completed and the DOM is removed. */
+    onAfterLeave?: (el: Element) => void;
+}
+/** Content that can be wrapped with `transition()`. */
+export type TransitionContent = NixTemplate | NixComponent | (() => NixTemplate | NixComponent | null);
+/**
+ * Wraps `content` with CSS class-based enter / leave transitions.
+ *
+ * **Static content** (NixTemplate / NixComponent): plays the enter transition
+ * on mount (only if `appear: true`; otherwise instant), and cleans up
+ * immediately on unmount without a leave transition.
+ *
+ * **Reactive conditional** `() => Template | null`: plays the enter
+ * transition when the expression goes from `null` → value, and the leave
+ * transition when it goes from value → `null`.  An in-progress leave is
+ * cancelled and the DOM is removed synchronously when new content enters.
+ *
+ * @example
+ * ```css
+ * .fade-enter-active, .fade-leave-active { transition: opacity 0.3s ease; }
+ * .fade-enter-from,   .fade-leave-to     { opacity: 0; }
+ * ```
+ * ```typescript
+ * const show = signal(true);
+ *
+ * // Reactive — full enter + leave
+ * transition(() => show.value ? html`<p>Hello</p>` : null, { name: "fade" })
+ *
+ * // Static — only enter (if appear: true)
+ * transition(html`<span>Always here</span>`, { name: "slide", appear: true })
+ * ```
+ */
+export declare function transition(content: TransitionContent, options?: TransitionOptions): NixTemplate;
+export declare function html(strings: TemplateStringsArray, ...values: unknown[]): NixTemplate;