@faber1999/axon.js 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,463 @@
+import { S as Signal, G as Getter, C as ComponentFn, J as JSXChild } from './jsx-KOQXGMp1.js';
+export { F as Fragment, a as Setter, h } from './jsx-KOQXGMp1.js';
+
+/**
+ * axon.js - Reactivity: signal
+ *
+ * A signal is a reactive value container.
+ * Reading it inside an effect creates a subscription.
+ * Writing it notifies all subscribers.
+ */
+
+/**
+ * Creates a reactive signal.
+ *
+ * @param initialValue - The starting value.
+ * @returns A [getter, setter] tuple. Reading the getter inside an effect
+ *          creates a subscription. Writing the setter notifies all subscribers.
+ *
+ * @example
+ * const [count, setCount] = signal(0)
+ * effect(() => console.log(count())) // logs 0
+ * setCount(1)                         // logs 1
+ */
+declare function signal<T>(initialValue: T): Signal<T>;
+/**
+ * Batches multiple signal writes into a single flush of effects.
+ * Prevents effects from running multiple times when several signals change together.
+ *
+ * @example
+ * batch(() => {
+ *   setFirstName('Juan')
+ *   setLastName('García')
+ * }) // effects run once, not twice
+ */
+declare function batch(fn: () => void): void;
+
+/**
+ * axon.js - Reactivity: effect
+ *
+ * A stack-based dependency tracking system.
+ * The currently executing effect is always at the top of the stack.
+ */
+
+/**
+ * Creates a reactive effect that re-runs whenever any signal it reads changes.
+ * Returns a dispose function to stop tracking.
+ *
+ * @param fn - Effect function. May return a cleanup function.
+ * @returns dispose — call to stop the effect and unsubscribe from all signals.
+ */
+declare function effect(fn: () => void | (() => void)): () => void;
+/**
+ * Runs a function without tracking any signals.
+ * Reads inside will not subscribe the current effect.
+ */
+declare function untrack<T>(fn: () => T): T;
+
+/**
+ * axon.js - Reactivity: computed
+ *
+ * A derived, read-only reactive value.
+ * Like a signal, but its value is calculated from other signals.
+ */
+
+/**
+ * Creates a computed (derived) signal.
+ * Re-evaluates automatically when its dependencies change.
+ * Returns a read-only getter — computed values cannot be set directly.
+ *
+ * @param fn - Pure derivation function. Should have no side effects.
+ * @returns A getter function. Reading it inside an effect creates a subscription.
+ *
+ * @example
+ * const [count, setCount] = signal(0)
+ * const double = computed(() => count() * 2)
+ * effect(() => console.log(double())) // logs 0
+ * setCount(5)                          // logs 10
+ */
+declare function computed<T>(fn: () => T): Getter<T>;
+
+/**
+ * axon.js - DOM Renderer: mount() and createApp()
+ */
+
+/**
+ * Mounts a component into a DOM container.
+ * Clears the container first.
+ *
+ * @param component - Component function or a pre-built DOM node.
+ * @param container - Target DOM element.
+ * @param props - Props to pass to the component (if it's a function).
+ */
+declare function mount(component: ComponentFn | Node, container: Element, props?: Record<string, unknown>): void;
+/**
+ * Creates an application entry point.
+ *
+ * @example
+ * createApp(App).mount('#app')
+ * createApp(App).mount(document.getElementById('root')!)
+ */
+declare function createApp(RootComponent: ComponentFn): {
+    mount(selector: string | Element): void;
+};
+
+/**
+ * axon.js - DOM Helpers: Show, For, Dynamic, Portal
+ *
+ * Control-flow components for use in JSX.
+ * These are the idiomatic way to handle conditionals and lists
+ * with fine-grained reactivity (no re-render of the whole tree).
+ */
+
+interface ShowProps<T = unknown> {
+    /** Reactive condition. If a function, it's read as a signal getter. */
+    when: (() => T) | T;
+    /** Rendered when `when` is falsy. */
+    fallback?: JSXChild;
+    /** Rendered when `when` is truthy. */
+    children?: JSXChild | JSXChild[];
+}
+/**
+ * Conditionally renders children or a fallback.
+ *
+ * @example
+ * <Show when={isLoggedIn} fallback={<Login />}>
+ *   <Dashboard />
+ * </Show>
+ */
+declare function Show<T = unknown>({ when, fallback, children }: ShowProps<T>): DocumentFragment;
+interface ForProps<T> {
+    /** Reactive array. If a function, it's read as a signal getter. */
+    each: (() => T[]) | T[];
+    /** Render function called for each item. */
+    children: (item: T, index: () => number) => JSXChild;
+}
+/**
+ * Reactively renders a list.
+ *
+ * @example
+ * <For each={items}>
+ *   {(item, index) => <li>{item.name}</li>}
+ * </For>
+ */
+declare function For<T>({ each, children: renderItem }: ForProps<T>): DocumentFragment;
+interface DynamicProps {
+    /** Reactive component getter. */
+    component: (() => ComponentFn) | ComponentFn;
+    [key: string]: unknown;
+}
+/**
+ * Reactively renders a dynamic component.
+ * Useful when the component itself needs to change based on state.
+ *
+ * @example
+ * const [currentView, setCurrentView] = signal(HomeView)
+ * <Dynamic component={currentView} title="Hello" />
+ */
+declare function Dynamic({ component: getComponent, ...props }: DynamicProps): DocumentFragment;
+interface PortalProps {
+    /** Target DOM element to render into. */
+    mount: Element;
+    children?: JSXChild | JSXChild[];
+}
+/**
+ * Renders children into a different part of the DOM.
+ * Useful for modals, tooltips, and overlays.
+ *
+ * @example
+ * <Portal mount={document.body}>
+ *   <Modal />
+ * </Portal>
+ */
+declare function Portal({ mount: target, children }: PortalProps): Comment;
+
+/**
+ * axon.js — View Transitions
+ *
+ * Wraps DOM updates in the browser's View Transitions API for smooth animations.
+ * Gracefully falls back to a direct call if the browser doesn't support the API.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/View_Transitions_API
+ */
+/**
+ * Wraps a DOM update function in a View Transition.
+ *
+ * If the browser supports `document.startViewTransition`, the update is
+ * animated. Otherwise it runs immediately with no transition.
+ *
+ * @param fn - The function that updates the DOM (e.g. a navigate call).
+ *
+ * @example
+ * // Manually trigger a transition on any state change:
+ * withViewTransition(() => navigate('/about'))
+ * withViewTransition(() => setCurrentTab('settings'))
+ *
+ * @example
+ * // Custom CSS for the transition (add to your stylesheet):
+ * // ::view-transition-old(root) { animation: 150ms ease-out fade-out; }
+ * // ::view-transition-new(root) { animation: 150ms ease-in  fade-in;  }
+ */
+declare function withViewTransition(fn: () => void): void;
+
+/**
+ * axon.js - Component Lifecycle
+ *
+ * Each component gets an "owner" context that tracks:
+ *   - onMount callbacks (run after the component's DOM is inserted)
+ *   - onCleanup callbacks (run when the component is destroyed)
+ *   - child owners (for propagating cleanup down the tree)
+ */
+
+/**
+ * Registers a callback to run after the component mounts (DOM is inserted).
+ * Must be called synchronously during component setup.
+ */
+declare function onMount(fn: () => void): void;
+/**
+ * Registers a cleanup callback to run when the component is destroyed.
+ * Must be called synchronously during component setup.
+ */
+declare function onCleanup(fn: () => void): void;
+
+/**
+ * axon.js - Context API
+ *
+ * Allows passing data down the component tree without prop drilling.
+ * Uses a stack-based approach during the synchronous render phase.
+ */
+
+interface Context<T> {
+    /** Wrap children with this to provide a value down the tree. */
+    Provider: ComponentFn<{
+        value: T;
+        children?: JSXChild | JSXChild[];
+    }>;
+    /** Read the nearest Provider's value. Returns defaultValue if no Provider found. */
+    use(): T;
+}
+/**
+ * Creates a context object.
+ *
+ * @param defaultValue - Returned by `use()` when no Provider is found above.
+ * @returns `{ Provider, use }` — Provider component and reader function.
+ *
+ * @example
+ * const ThemeCtx = createContext('dark')
+ *
+ * function App() {
+ *   return <ThemeCtx.Provider value="light"><Child /></ThemeCtx.Provider>
+ * }
+ * function Child() {
+ *   const theme = ThemeCtx.use() // 'light'
+ *   return <div class={theme}>...</div>
+ * }
+ */
+declare function createContext<T>(defaultValue: T): Context<T>;
+
+/**
+ * axon.js - Router
+ *
+ * Client-side router using the History API.
+ * Built entirely on signals — the current URL is a signal,
+ * so route matching is reactive automatically.
+ */
+
+interface RouteConfig {
+    path: string;
+    component: ComponentFn;
+}
+/**
+ * A group of routes that share a layout and/or an access guard.
+ *
+ * @example
+ * {
+ *   layout: DashboardLayout,
+ *   guard: () => isLoggedIn() || '/login',
+ *   children: [
+ *     { path: '/dashboard', component: Dashboard },
+ *     { path: '/settings',  component: Settings  },
+ *   ],
+ * }
+ */
+interface RouteGroup {
+    layout?: ComponentFn<{
+        children?: JSXChild;
+    }>;
+    /**
+     * Called before rendering any child route.
+     * - Return `true`    → allow access.
+     * - Return `false`   → deny: go back to the previous route, or to `fallbackPath`
+     *                       if there is no previous route (e.g. direct URL access).
+     * - Return a string  → redirect to that path.
+     *
+     * Reactive: if the guard reads a signal (e.g. `isLoggedIn()`),
+     * RouterView re-evaluates it whenever that signal changes.
+     */
+    guard?: () => boolean | string;
+    /**
+     * Path to redirect to when the guard returns `false` and there is no
+     * previous route to go back to (e.g. the user typed the URL directly).
+     * If omitted and there is no previous route, nothing is rendered.
+     */
+    fallbackPath?: string;
+    children: RouteConfig[];
+}
+/** Union of a flat route and a route group. Pass this to `createRouter`. */
+type RouteDefinition = RouteConfig | RouteGroup;
+interface CompiledRoute extends RouteConfig {
+    regex: RegExp;
+    paramNames: string[];
+    layout?: ComponentFn<{
+        children?: JSXChild;
+    }>;
+    guard?: () => boolean | string;
+    fallbackPath?: string;
+}
+interface NavigateOptions {
+    replace?: boolean;
+}
+interface RouterOptions {
+    /** Wrap route transitions in the View Transitions API for animated navigation. */
+    viewTransitions?: boolean;
+}
+interface Router {
+    /** Reactive getter for the current pathname (e.g. '/user/42'). */
+    pathname: Getter<string>;
+    /** Reactive getter for the current query string (e.g. '?tab=posts'). */
+    search: Getter<string>;
+    /** Reactive getter for the current route params (e.g. { id: '42' }). */
+    params: Getter<Record<string, string>>;
+    /** Navigate to a new path programmatically. */
+    navigate(to: string, options?: NavigateOptions): void;
+    /** Compiled route definitions. */
+    routes: CompiledRoute[];
+    /** Returns the route matching the current path, or null. */
+    currentRoute(): CompiledRoute | null;
+}
+/**
+ * Creates and registers the global router instance.
+ * Call this once at app startup, before mounting.
+ *
+ * Accepts flat routes and/or route groups (with shared layout and guard).
+ *
+ * @example
+ * createRouter([
+ *   { path: '/login', component: Login },
+ *   {
+ *     layout: DashboardLayout,
+ *     guard: () => isLoggedIn() || '/login',
+ *     children: [
+ *       { path: '/dashboard', component: Dashboard },
+ *     ],
+ *   },
+ * ], { viewTransitions: true })
+ */
+declare function createRouter(routes: RouteDefinition[], options?: RouterOptions): Router;
+/**
+ * Returns the active router instance.
+ * Must be called after `createRouter()`.
+ */
+declare function useRouter(): Router;
+/**
+ * Returns the current route params as a plain object.
+ * Reactive: re-reads when the route changes.
+ */
+declare function useParams(): Record<string, string>;
+/**
+ * Returns the `navigate` function from the active router.
+ */
+declare function useNavigate(): Router['navigate'];
+
+/**
+ * axon.js - Router Components: RouterView, Link
+ */
+
+/**
+ * Renders the component matching the current route.
+ * Handles route guards and optional group layouts automatically.
+ * Place this where you want the page content to appear.
+ *
+ * @example
+ * function App() {
+ *   return (
+ *     <div>
+ *       <Nav />
+ *       <main><RouterView /></main>
+ *     </div>
+ *   )
+ * }
+ */
+declare function RouterView(): DocumentFragment;
+interface LinkProps {
+    /** Target path for navigation. */
+    href: string;
+    /** Use replaceState instead of pushState. Default: false. */
+    replace?: boolean;
+    /** CSS class always applied to the anchor. */
+    class?: string;
+    /** CSS class applied when `href` matches the current pathname. */
+    activeClass?: string;
+    children?: JSXChild | JSXChild[];
+}
+/**
+ * A client-side navigation link. Prevents full page reload.
+ *
+ * @example
+ * <Link href="/about">About</Link>
+ * <Link href="/profile" activeClass="active">Profile</Link>
+ */
+declare function Link({ href, replace, class: cls, activeClass, children }: LinkProps): HTMLAnchorElement;
+
+/**
+ * axon.js - Store
+ *
+ * Global reactive state built on signals.
+ * Each property is a signal internally; reading via the Proxy creates subscriptions.
+ *
+ * @example
+ * const [store, setStore] = createStore({ count: 0, theme: 'dark' })
+ *
+ * // Read (reactive inside effects/components):
+ * store.count        // 0
+ *
+ * // Write:
+ * setStore('count', 42)
+ * setStore('count', prev => prev + 1)
+ * setStore({ count: 10, theme: 'light' })  // merge update
+ */
+
+/**
+ * Updater function or direct value — mirrors signal's setter API.
+ */
+type ValueOrUpdater<T> = T | ((prev: T) => T);
+/**
+ * The setStore function with 3 call signatures:
+ *   setStore(key, value)           — set one property
+ *   setStore(key, fn)              — update one property with a function
+ *   setStore(partialObject)        — merge-update multiple properties
+ */
+interface SetStore<T extends object> {
+    <K extends keyof T>(key: K, valueOrUpdater: ValueOrUpdater<T[K]>): void;
+    (partial: Partial<T>): void;
+}
+/**
+ * Creates a reactive store from an initial state object.
+ * Each top-level property becomes an independent signal.
+ *
+ * @returns A `[store, setStore]` tuple.
+ *   - `store` — read-only Proxy; reading a property is reactive.
+ *   - `setStore` — write function with 3 overloads.
+ */
+declare function createStore<T extends object>(initialState: T): [T, SetStore<T>];
+/**
+ * Creates a computed value derived from a store.
+ * Syntactic sugar for `computed(() => selector(store))`.
+ *
+ * @example
+ * const fullName = select(store, s => `${s.firstName} ${s.lastName}`)
+ * effect(() => console.log(fullName())) // reactive
+ */
+declare function select<T extends object, R>(store: T, selector: (store: T) => R): Getter<R>;
+
+export { ComponentFn, type Context, Dynamic, type DynamicProps, For, type ForProps, Getter, JSXChild, Link, type LinkProps, type NavigateOptions, Portal, type PortalProps, type RouteConfig, type RouteDefinition, type RouteGroup, type Router, type RouterOptions, RouterView, type SetStore, Show, type ShowProps, Signal, batch, computed, createApp, createContext, createRouter, createStore, effect, mount, onCleanup, onMount, select, signal, untrack, useNavigate, useParams, useRouter, withViewTransition };