@jasonshimmy/custom-elements-runtime 2.5.2 → 2.5.5

package/dist/router.d.ts

@@ -1,208 +1,6 @@
-import { type Store } from './store';
-/**
- * Represents a component that can be rendered by the router.
- * Can be either a class constructor or a function component.
- */
-export type RouteComponent = {
-    new (...args: unknown[]): unknown;
-} | ((...args: unknown[]) => unknown);
-/**
- * Represents the current state of the router.
- */
-export interface RouteState {
-    /** The current path without base, query, or fragment */
-    path: string;
-    /** Route parameters extracted from dynamic path segments */
-    params: Record<string, string>;
-    /** Query parameters from the URL search string */
-    query: Record<string, string>;
-    /** Optional fragment (hash) portion of the URL, without the leading '#' */
-    fragment?: string;
-}
-/**
- * Result type for route guards.
- * - `true`: Allow navigation
- * - `false`: Block navigation
- * - `string`: Redirect to the specified path
- */
-export type GuardResult = boolean | string | Promise<boolean | string>;
-/**
- * Defines a route in the router configuration.
- */
-export interface Route {
-    /** The path pattern for this route (e.g., '/users/:id') */
-    path: string;
-    /** Statically available component (already imported) */
-    component?: string | (() => unknown);
-    /** Lazy loader that resolves to something renderable */
-    load?: () => Promise<{
-        default: string | HTMLElement | ((...args: unknown[]) => unknown);
-    }>;
-    /** Guard that runs before matching — return false to cancel, or a string to redirect */
-    beforeEnter?: (to: RouteState, from: RouteState) => GuardResult;
-    /** Guard that runs right before navigation commits — can cancel or redirect */
-    onEnter?: (to: RouteState, from: RouteState) => GuardResult;
-    /** Hook that runs after navigation completes — cannot cancel */
-    afterEnter?: (to: RouteState, from: RouteState) => void;
-}
-/**
- * Props interface for the router-link component.
- */
-export interface RouterLinkProps {
-    /** Target path or URL to navigate to */
-    to: string;
-    /** HTML tag to render ('a' or 'button') */
-    tag: string;
-    /** Whether to use replace instead of push navigation */
-    replace: boolean;
-    /** Whether to use exact matching for active state */
-    exact: boolean;
-    /** CSS class applied when link is active */
-    activeClass: string;
-    /** CSS class applied when link is exactly active */
-    exactActiveClass: string;
-    /** Value for aria-current attribute when exactly active */
-    ariaCurrentValue: string;
-    /** Whether the link is disabled */
-    disabled: boolean;
-    /** Whether this is an external link */
-    external: boolean;
-    /** Additional CSS classes */
-    class?: string;
-    /** Additional inline styles */
-    style?: string;
-}
-export interface RouterLinkComputed {
-    current: RouteState;
-    isExactActive: boolean;
-    isActive: boolean;
-    className: string;
-    ariaCurrent: string;
-    isButton: boolean;
-    disabledAttr: string;
-    externalAttr: string;
-}
-/**
- * Configuration object for initializing the router.
- */
-export interface RouterConfig {
-    /** Array of route definitions */
-    routes: Route[];
-    /** Base path for all routes */
-    base?: string;
-    /** Initial URL for SSR mode */
-    initialUrl?: string;
-    /** Configure fragment (hash) scrolling behavior */
-    scrollToFragment?: boolean | {
-        /** Whether fragment scrolling is enabled */
-        enabled?: boolean;
-        /** Offset in pixels to account for fixed headers */
-        offset?: number;
-        /** Timeout in ms to wait for element to appear */
-        timeoutMs?: number;
-    };
-}
-/**
- * Parse URL search string into query parameters object.
- * @param search - The search string (with or without leading '?')
- * @returns Object with query parameter key-value pairs
- */
-export declare const parseQuery: (search: string) => Record<string, string>;
-/**
- * Serialize query parameters object into URL search string.
- * @param q - Query parameters object
- * @returns Search string with leading '?' or empty string
- */
-export declare const serializeQuery: (q: Record<string, string> | undefined) => string;
-/**
- * Normalize a path for consistent route matching.
- * Ensures leading slash, removes trailing slash, and collapses duplicate slashes.
- * @param p - Path string to normalize
- * @returns Normalized path string
- */
-export declare function normalizePathForRoute(p: string): string;
-export declare const matchRoute: (routes: Route[], path: string) => {
-    route: Route | null;
-    params: Record<string, string>;
-};
-/**
- * Loads a route's component, supporting both static and async.
- * @param route Route object
- * @returns Promise resolving to the component
- */
-export declare function resolveRouteComponent(route: Route): Promise<string | HTMLElement | ((...args: unknown[]) => unknown)>;
-export declare function useRouter(config: RouterConfig): {
-    _cleanupScrollState: () => void;
-    store: Store<RouteState>;
-    push: (path: string) => Promise<void>;
-    replace: (path: string) => Promise<void>;
-    back: () => void;
-    subscribe: (listener: (state: RouteState) => void) => () => void;
-    matchRoute: (path: string) => {
-        route: Route | null;
-        params: Record<string, string>;
-    };
-    getCurrent: () => RouteState;
-    resolveRouteComponent: typeof resolveRouteComponent;
-    base: string;
-    scrollToFragment: (frag?: string) => Promise<boolean>;
-};
-/**
- * Explicit Router instance type exported for clearer typing across the
- * codebase and tests.
- */
-/**
- * Router instance interface providing navigation and state management.
- */
-export interface Router {
-    /** Reactive store containing current route state */
-    store: Store<RouteState>;
-    /** Navigate to a path (adds to history) */
-    push: (path: string) => Promise<void>;
-    /** Navigate to a path (replaces current history entry) */
-    replace: (path: string) => Promise<void>;
-    /** Go back in browser history */
-    back: () => void;
-    /** Subscribe to route state changes */
-    subscribe: Store<RouteState>['subscribe'];
-    /** Match a path against configured routes */
-    matchRoute: (path: string) => {
-        route: Route | null;
-        params: Record<string, string>;
-    };
-    /** Get current route state */
-    getCurrent: () => RouteState;
-    /** Resolve a route's component */
-    resolveRouteComponent: typeof resolveRouteComponent;
-    /** Base path for the router */
-    base: string;
-    /** Scroll to a fragment/hash element */
-    scrollToFragment: (frag?: string) => Promise<boolean>;
-}
-export declare function matchRouteSSR(routes: Route[], path: string): {
-    route: Route | null;
-    params: Record<string, string>;
-};
-export declare const activeRouterProxy: Router;
-/**
- * Singleton router instance for global access.
- *
- * Define here to prevent circular dependency
- * issue with component.
- */
-export declare function initRouter(config: RouterConfig): {
-    _cleanupScrollState: () => void;
-    store: Store<RouteState>;
-    push: (path: string) => Promise<void>;
-    replace: (path: string) => Promise<void>;
-    back: () => void;
-    subscribe: (listener: (state: RouteState) => void) => () => void;
-    matchRoute: (path: string) => {
-        route: Route | null;
-        params: Record<string, string>;
-    };
-    getCurrent: () => RouteState;
-    resolveRouteComponent: typeof resolveRouteComponent;
-    base: string;
-    scrollToFragment: (frag?: string) => Promise<boolean>;
-};
+export type { RouteComponent, RouteState, GuardResult, Route, RouterLinkProps, RouterLinkComputed, RouterConfig, Router, } from './router/types';
+export { parseQuery, serializeQuery, normalizePathForRoute, DEFAULT_SCROLL_CONFIG, isDangerousScheme, isAbsoluteUrl, safeDecode, canonicalizeBase, } from './router/path-utils';
+export { matchRoute, matchRouteSSR, findMatchedRoute } from './router/matcher';
+export { clearComponentCache, resolveRouteComponent, } from './router/component-loader';
+export { activeRouterProxy } from './router/active-proxy';
+export { useRouter, initRouter } from './router/instance';

package/dist/runtime/builtin-components.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Built-in utility components provided by the custom-elements runtime.
+ *
+ * These components are registered automatically when this module is imported.
+ * They are designed to be minimal, tree-shakeable, and zero-dependency.
+ *
+ * Included components:
+ * - `<cer-suspense>` — Shows a fallback while async work is pending
+ * - `<cer-error-boundary>` — Catches render errors and shows a fallback UI
+ * - `<cer-keep-alive>` — Preserves component state across DOM removal/re-insertion
+ */
+/**
+ * A built-in component that conditionally renders either the default slot
+ * content or the `fallback` slot content, controlled by the `pending` prop.
+ *
+ * Use the `pending` attribute/property to signal that async work is in
+ * progress; the component will swap to the `fallback` slot until `pending`
+ * becomes falsy.
+ *
+ * @example
+ * ```html
+ * <cer-suspense pending>
+ *   <!-- shown when pending=false -->
+ *   <my-async-content></my-async-content>
+ *
+ *   <!-- shown while pending=true -->
+ *   <div slot="fallback">Loading…</div>
+ * </cer-suspense>
+ * ```
+ *
+ * @example Programmatic usage
+ * ```ts
+ * component('my-data-loader', () => {
+ *   const pending = ref(true);
+ *   useOnConnected(async () => {
+ *     await fetchData();
+ *     pending.value = false;
+ *   });
+ *   return html`
+ *     <cer-suspense pending="${pending.value}">
+ *       <my-data-view></my-data-view>
+ *       <div slot="fallback">Loading data…</div>
+ *     </cer-suspense>
+ *   `;
+ * });
+ * ```
+ */
+export declare function registerSuspense(): void;
+/**
+ * A built-in component that catches errors thrown during child component
+ * rendering and displays a fallback UI instead of crashing the page.
+ *
+ * Errors are caught via the `useOnError` lifecycle hook. Once an error is
+ * caught the component switches to showing the `fallback` named slot (or a
+ * default "Something went wrong" message if no fallback slot is provided).
+ *
+ * Call the custom `reset()` method on the element to clear the error and
+ * attempt re-rendering the default slot.
+ *
+ * @example
+ * ```html
+ * <cer-error-boundary>
+ *   <my-risky-component></my-risky-component>
+ *
+ *   <div slot="fallback">
+ *     <p>Something went wrong. <button onclick="this.closest('cer-error-boundary').reset()">Retry</button></p>
+ *   </div>
+ * </cer-error-boundary>
+ * ```
+ */
+export declare function registerErrorBoundary(): void;
+/**
+ * Register all built-in components (`cer-suspense`, `cer-error-boundary`,
+ * `cer-keep-alive`).
+ * Safe to call multiple times — each registration is guarded by a
+ * `customElements.get()` check.
+ */
+export declare function registerBuiltinComponents(): void;

package/dist/runtime/component/element-class.d.ts

@@ -0,0 +1,4 @@
+import type { ComponentConfig } from '../types';
+export declare function createElementClass<S extends object, C extends object, P extends object, T extends object = object>(tag: string, config: ComponentConfig<S, C, P, T>): CustomElementConstructor | {
+    new (): object;
+};

package/dist/runtime/component/factory.d.ts

@@ -0,0 +1,39 @@
+import type { VNode } from '../types';
+/**
+ * Streamlined functional component API with automatic reactive props and lifecycle hooks.
+ *
+ * @example
+ * ```ts
+ * // Simple component with no parameters
+ * component('simple-header', () => {
+ *   return html`<h1>Hello World</h1>`;
+ * });
+ *
+ * // With props using useProps() hook
+ * component('with-props', () => {
+ *   const { message } = useProps({ message: 'Hello' });
+ *   return html`<div>${message}</div>`;
+ * });
+ *
+ * // With props and lifecycle hooks
+ * component('my-switch', () => {
+ *   const { modelValue, label } = useProps({ modelValue: false, label: '' });
+ *   const emit = useEmit();
+ *
+ *   useOnConnected(() => console.log('Switch connected!'));
+ *   useOnDisconnected(() => console.log('Switch disconnected!'));
+ *
+ *   return html`
+ *     <label>
+ *       ${label}
+ *       <input
+ *         type="checkbox"
+ *         :checked="${modelValue}"
+ *         @change="${(e) => emit('update:modelValue', e.target.checked)}"
+ *       />
+ *     </label>
+ *   `;
+ * });
+ * ```
+ */
+export declare function component(tag: string, renderFn: () => VNode | VNode[] | Promise<VNode | VNode[]>): void;

package/dist/runtime/component/registry.d.ts

@@ -0,0 +1,16 @@
+import type { ComponentConfig } from '../types';
+/**
+ * @internal
+ * Runtime registry of component configs.
+ * NOTE: This is an internal implementation detail. Do not import from the
+ * published package in consumer code — it is intended for runtime/HMR and
+ * internal tests only. Consumers should use the public `component` API.
+ */
+export declare const registry: Map<string, ComponentConfig<object, object, object>>;
+/**
+ * Lazily initialize the global registry slot with SSR safety.
+ * This avoids performing a write to globalThis at module-import time
+ * (which is a side-effect that prevents bundlers from tree-shaking).
+ * Enhanced with SSR detection and multi-tenant safety.
+ */
+export declare function initGlobalRegistryIfNeeded(): void;

package/dist/runtime/component.d.ts

@@ -1,50 +1,3 @@
-import type { ComponentConfig, VNode } from './types';
-/**
- * @internal
- * Runtime registry of component configs.
- * NOTE: This is an internal implementation detail. Do not import from the
- * published package in consumer code — it is intended for runtime/HMR and
- * internal tests only. Consumers should use the public `component` API.
- */
-export declare const registry: Map<string, ComponentConfig<object, object, object>>;
-export declare function createElementClass<S extends object, C extends object, P extends object, T extends object = object>(tag: string, config: ComponentConfig<S, C, P, T>): CustomElementConstructor | {
-    new (): object;
-};
-/**
- * Streamlined functional component API with automatic reactive props and lifecycle hooks.
- *
- * @example
- * ```ts
- * // Simple component with no parameters
- * component('simple-header', () => {
- *   return html`<h1>Hello World</h1>`;
- * });
- *
- * // With props using useProps() hook
- * component('with-props', () => {
- *   const { message } = useProps({ message: 'Hello' });
- *   return html`<div>${message}</div>`;
- * });
- *
- * // With props and lifecycle hooks
- * component('my-switch', () => {
- *   const { modelValue, label } = useProps({ modelValue: false, label: '' });
- *   const emit = useEmit();
- *
- *   useOnConnected(() => console.log('Switch connected!'));
- *   useOnDisconnected(() => console.log('Switch disconnected!'));
- *
- *   return html`
- *     <label>
- *       ${label}
- *       <input
- *         type="checkbox"
- *         :checked="${modelValue}"
- *         @change="${(e) => emit('update:modelValue', e.target.checked)}"
- *       />
- *     </label>
- *   `;
- * });
- * ```
- */
-export declare function component(tag: string, renderFn: () => VNode | VNode[] | Promise<VNode | VNode[]>): void;
+export { registry } from './component/registry';
+export { createElementClass } from './component/element-class';
+export { component } from './component/factory';

package/dist/runtime/discovery-state.d.ts

@@ -0,0 +1,30 @@
+/**
+ * discovery-state.ts
+ *
+ * Isolated discovery-render flag. Extracted from hooks.ts to break the
+ * circular dependency between hooks.ts and reactive.ts — both modules need
+ * to check `isDiscoveryRender()`, but hooks.ts also imports from reactive.ts.
+ *
+ * All side-effectful hooks (watchEffect, watch, useOnConnected, useStyle,
+ * provide, inject, useEmit, …) must guard their setup with
+ * `isDiscoveryRender()` and return early / return no-ops when it is true.
+ */
+/**
+ * Returns `true` while a discovery render is in progress.
+ * Used by `html` tagged templates and hooks to short-circuit side effects.
+ * @internal
+ */
+export declare function isDiscoveryRender(): boolean;
+/**
+ * Mark the start of a discovery render pass.
+ * Call this immediately before invoking the render function for the first time
+ * (before `useProps` prop-name collection).
+ * @internal
+ */
+export declare function beginDiscoveryRender(): void;
+/**
+ * Mark the end of a discovery render pass.
+ * Call this in a `finally` block after the discovery render function returns.
+ * @internal
+ */
+export declare function endDiscoveryRender(): void;

package/dist/runtime/hooks.d.ts

@@ -2,6 +2,13 @@
  * Context-based hooks for functional components
  * Provides React-like hooks with perfect TypeScript inference
  */
+export { beginDiscoveryRender, endDiscoveryRender } from './discovery-state';
+/**
+ * Returns true while a discovery render is in progress.
+ * Used by `html` and other primitives to short-circuit side effects.
+ * @internal
+ */
+export declare function isDiscoveryRender(): boolean;
 /**
  * Set the current component context (called internally during render)
  * @internal
@@ -12,6 +19,12 @@ export declare function setCurrentComponentContext(context: Record<string, unkno
  * @internal
  */
 export declare function clearCurrentComponentContext(): void;
+/**
+ * Get the current component context. Useful for advanced composable patterns
+ * that need to access or pass the context explicitly.
+ * @internal
+ */
+export declare function getCurrentComponentContext(): Record<string, unknown> | null;
 /**
  * Get the emit function for the current component
  * Must be called during component render
@@ -137,3 +150,105 @@ export declare function useProps<T extends Record<string, unknown>>(defaults: T)
  * ```
  */
 export declare function useStyle(callback: () => string): void;
+/**
+ * Store a value under a key so that descendant components can retrieve it
+ * with `inject()`. Must be called during component render.
+ *
+ * @example
+ * ```ts
+ * component('theme-provider', () => {
+ *   provide('theme', 'dark');
+ *   return html`<slot></slot>`;
+ * });
+ * ```
+ */
+export declare function provide<T>(key: string | symbol, value: T): void;
+/**
+ * Retrieve a value provided by an ancestor component. Traverses the shadow
+ * DOM tree upward through ShadowRoot host elements looking for the nearest
+ * `provide()` call with the matching key. Returns `defaultValue` (or
+ * `undefined`) when no provider is found. Must be called during render.
+ *
+ * @example
+ * ```ts
+ * component('themed-button', () => {
+ *   const theme = inject<string>('theme', 'light');
+ *   return html`<button class="btn-${theme}">Click</button>`;
+ * });
+ * ```
+ */
+export declare function inject<T>(key: string | symbol, defaultValue?: T): T | undefined;
+/**
+ * Execute a function that calls hooks (useOnConnected, useOnDisconnected, etc.)
+ * using an explicit component context rather than requiring the call to happen
+ * directly inside a render function. This enables composable utility functions
+ * that register lifecycle callbacks from outside the render body.
+ *
+ * @example
+ * ```ts
+ * function useLogger(label: string) {
+ *   return createComposable(() => {
+ *     useOnConnected(() => console.log(`${label} connected`));
+ *     useOnDisconnected(() => console.log(`${label} disconnected`));
+ *   });
+ * }
+ *
+ * component('my-comp', () => {
+ *   const stopLogger = useLogger('my-comp');
+ *   stopLogger(context); // pass the component context explicitly
+ *   return html`<div>Hello</div>`;
+ * });
+ * ```
+ *
+ * More commonly, use it as a direct wrapper inside render:
+ * ```ts
+ * component('my-comp', () => {
+ *   // Accepts context automatically from getCurrentComponentContext()
+ *   createComposable(() => {
+ *     useOnConnected(() => console.log('connected from composable'));
+ *   })();
+ *   return html`<div>Hello</div>`;
+ * });
+ * ```
+ */
+export declare function createComposable<T>(fn: () => T): (ctx?: Record<string, unknown>) => T;
+/**
+ * Expose a public interface from the current component so that parent
+ * components holding a template ref to this element can call its methods
+ * or read its properties. Must be called during component render.
+ *
+ * @example
+ * ```ts
+ * component('my-counter', () => {
+ *   const count = ref(0);
+ *   useExpose({ increment: () => count.value++, get count() { return count.value; } });
+ *   return html`<div>${count.value}</div>`;
+ * });
+ *
+ * // Parent: counterRef.value.increment()
+ * ```
+ */
+export declare function useExpose<T extends Record<string, unknown>>(exposed: T): void;
+/**
+ * Access named slots provided to the current component. Returns helpers to
+ * check slot presence and retrieve slotted elements. Must be called during
+ * component render.
+ *
+ * @example
+ * ```ts
+ * component('my-card', () => {
+ *   const slots = useSlots();
+ *   return html`
+ *     <div class="card">
+ *       <slot></slot>
+ *       ${slots.has('footer') ? html`<footer><slot name="footer"></slot></footer>` : ''}
+ *     </div>
+ *   `;
+ * });
+ * ```
+ */
+export declare function useSlots(): {
+    has(name?: string): boolean;
+    getNodes(name?: string): Element[];
+    names(): string[];
+};

package/dist/runtime/logger.d.ts

@@ -6,6 +6,14 @@
  * Programmatically toggle dev-mode logging at runtime.
  * Prefer setting `globalThis.__CE_RUNTIME_DEV__ = true` before importing
  * the runtime so logs are enabled as early as possible.
+ *
+ * @param v - `true` to enable dev logging, `false` to disable it.
+ *
+ * @example
+ * ```ts
+ * import { setDevMode } from '@jasonshimmy/custom-elements-runtime';
+ * setDevMode(true); // enable verbose dev logs
+ * ```
  */
 export declare function setDevMode(v: boolean): void;
 /**
@@ -17,6 +25,16 @@ export declare function devError(message: string, ...args: unknown[]): void;
  */
 export declare function devWarn(message: string, ...args: unknown[]): void;
 /**
- * Log info only in development mode
+ * Log an informational message only in development mode.
+ * No-ops in production builds or when dev mode is disabled.
+ *
+ * @param message - Message to log.
+ * @param args - Additional values to pass to `console.log`.
+ *
+ * @example
+ * ```ts
+ * import { devLog } from '@jasonshimmy/custom-elements-runtime';
+ * devLog('[my-component] mounted', { props });
+ * ```
  */
 export declare function devLog(message: string, ...args: unknown[]): void;