@number10/jsx-core 5.0.0

package/dist/hooks.d.ts

@@ -0,0 +1,322 @@
+import { Signal } from '@preact/signals-core';
+import { DesignTokens } from './design-tokens/design-token-types';
+import { AtlasFrameInfo, FrameRect, Size, SurfaceContext } from './host-adapter';
+import { PartialTheme } from './theme';
+type Cleanup = void | (() => void);
+/**
+ * Portable hook context — the data structure passed through the hook runtime.
+ * Each renderer extends this with renderer-specific fields (e.g., Phaser adds `parent: ParentType`).
+ */
+export interface HookContext {
+    /** Current hook slot index (incremented by each hook call) */
+    index: number;
+    /** Hook state slots (one per hook call) */
+    slots: unknown[];
+    /** Pending effects to run after render */
+    effects: (() => Cleanup)[];
+    /** Cleanup functions to run on unmount */
+    cleanups: Cleanup[];
+    /** The rendered VNode output of the component */
+    vnode: unknown | null;
+    /** The component VNode itself (type = function) */
+    componentVNode: {
+        type: unknown;
+        props?: Record<string, unknown> | undefined;
+        children?: unknown[];
+        __memo?: boolean;
+    };
+    /** The component function */
+    function: (props: unknown) => unknown;
+    /** Optional updater callback (set by renderer's withHooks/scheduleUpdate) */
+    updater?: (() => void) | undefined;
+    /** Optional per-runtime update handler for concurrent renderer runtimes */
+    updateHandler?: ((ctx: HookContext) => void) | undefined;
+    /** Whether this is a VNode factory (no hooks used) */
+    isFactory: boolean;
+    /** Last rendered props (for memoization) */
+    lastProps?: unknown;
+    /** Whether component uses memoization (default: true) */
+    memoized?: boolean;
+    /** Theme context for this component */
+    theme?: PartialTheme | undefined;
+    /** Design tokens injected by the renderer (colors, text styles, spacing, etc.) */
+    themeTokens?: Record<string, unknown> | undefined;
+    /** Flag to prevent updates after disposal */
+    disposed?: boolean;
+    /**
+     * Surface context for accessing viewport, scheduler, and capabilities.
+     * Set by the renderer's withHooks() wrapper during component render.
+     *
+     * @migration(audit:scene-portal-mount) Phase 6G — enables portable hooks
+     *   (useViewportSize, useLayoutEffect via HostScheduler, ...).
+     */
+    surface?: SurfaceContext | undefined;
+}
+/**
+ * Get the current hook context. Must be called during component render.
+ * Uses a global registry to ensure correctness even when bundlers duplicate modules.
+ * @returns Current context or null if not in render
+ */
+export declare function getCurrentCtx(): HookContext | null;
+/**
+ * Set the current hook context. Called by withHooks() in the renderer.
+ * @internal
+ */
+export declare function setCurrentCtx(ctx: HookContext | null): void;
+/**
+ * Portable render cycle — sets up hook context, runs render, runs effects.
+ * Each renderer wraps this with its own lifecycle guards.
+ *
+ * @param ctx - The hook context for this component
+ * @param render - The render function to execute
+ * @param opts - Optional renderer-specific hooks
+ * @returns The result of the render function, or null if the guard fails
+ *
+ * @migration(audit:scene-portal-mount) Phase 6I — extracted from Phaser withHooks().
+ *   The guard callback replaces Phaser-specific scene/shutdown checks.
+ */
+export declare function withHooks<T>(ctx: HookContext, render: () => T, opts?: {
+    /** Renderer-specific lifecycle guard. Return false to abort render. */
+    isAlive?: () => boolean;
+    /** Called after render, before restoring context. For renderer-specific side effects. */
+    onAfterRender?: () => void;
+}): T | null;
+/**
+ * Get current hook context, throwing if not in a render context.
+ * Used by hooks that MUST be called during render.
+ * @returns Non-null hook context
+ * @throws Error if called outside of a component render
+ */
+export declare function getCurrentOrThrow(): HookContext;
+/** Callback type for renderer-specific update logic */
+export type UpdateHandler = (ctx: HookContext) => void;
+/**
+ * Register a renderer-specific update handler.
+ * Called once by the renderer package to override core's no-op scheduleUpdate.
+ * Uses a global registry to ensure correctness even when bundlers duplicate modules.
+ * @param handler - Function that performs the actual VDOM patching for a component
+ */
+export declare function setUpdateHandler(handler: UpdateHandler): void;
+/**
+ * State hook for managing component state.
+ * @param initial - Initial state value or initializer function
+ * @returns Tuple of current state and setter function
+ */
+export declare function useState<T>(initial: T): [T, (v: T | ((p: T) => T)) => void];
+/**
+ * Ref hook for storing mutable values.
+ * @param val - Initial ref value
+ * @returns Ref object with current property
+ */
+export declare function useRef<T>(val: T): {
+    current: T;
+};
+/**
+ * Memoization hook for expensive computations.
+ * @param fn - Function to memoize
+ * @param deps - Dependency array
+ * @returns Memoized value
+ */
+export declare function useMemo<T>(fn: () => T, deps: readonly unknown[]): T;
+export declare function useCallback<T extends (...args: any[]) => any>(fn: T, deps: readonly unknown[]): T;
+/**
+ * Effect hook for side effects with cleanup.
+ * @param fn - Effect function that optionally returns cleanup
+ * @param deps - Optional dependency array
+ */
+export declare function useEffect(fn: () => Cleanup, deps?: readonly unknown[] | undefined): void;
+/**
+ * Hook to access current theme context.
+ * Returns the theme that was passed down through the VDOM tree.
+ * @returns Current theme context or undefined if no theme is set
+ */
+export declare function useTheme(): PartialTheme | undefined;
+/**
+ * Hook to access design tokens injected by the renderer.
+ * Each renderer sets `themeTokens` on the hook context during component render
+ * (e.g., Phaser's plugin injects color presets, text styles, spacing).
+ * Returns undefined if no tokens are configured by the active renderer.
+ * @returns Design tokens or undefined
+ */
+export declare function useThemeTokens<T = DesignTokens>(): T | undefined;
+/**
+ * Hook to force component re-render when signals change.
+ */
+export declare function useForceRedraw(throttleMs: number, ...signals: Signal<unknown>[]): void;
+export declare function useForceRedraw(...signals: Signal<unknown>[]): void;
+/**
+ * Hook to manually trigger a component redraw.
+ * @returns Function to trigger redraw
+ */
+export declare function useRedraw(): () => void;
+/**
+ * Checks if dependency arrays have changed.
+ */
+export declare function depsChanged(a?: readonly unknown[], b?: readonly unknown[]): boolean;
+/**
+ * Shallow comparison for props objects.
+ * Used for component memoization (React.memo equivalent).
+ */
+export declare function shallowEqual(a: unknown, b: unknown): boolean;
+/**
+ * Check if component should update based on props comparison.
+ */
+export declare function shouldComponentUpdate(ctx: HookContext, newProps: unknown): boolean;
+/**
+ * Disposes component context and runs cleanups.
+ */
+export declare function disposeCtx(c: HookContext): void;
+/**
+ * Hook to access the full SurfaceContext (viewport, scheduler, capabilities).
+ * Must be called during component render. Returns null if no surface is available.
+ *
+ * Portable — works with any renderer that provides SurfaceContext.
+ * @returns SurfaceContext or null
+ *
+ * @migration(audit:surface-access) Phase 7 — new hook, replaces manual ctx.surface access.
+ */
+export declare function useSurface(): SurfaceContext | null;
+/**
+ * Hook to get the current viewport size from the surface context.
+ * Portable — works with any renderer that provides SurfaceContext.
+ * @returns Viewport dimensions { width, height }
+ *
+ * @migration(audit:scene-portal-mount) Phase 6G — extracted from Phaser hooks.ts.
+ *   Uses ctx.surface.viewport instead of Phaser-specific RenderContext.
+ */
+export declare function useViewportSize(): {
+    width: number;
+    height: number;
+};
+/**
+ * Hook that collects debug metrics from the active renderer on an interval.
+ *
+ * Delegates to the `debugSnapshotCollector` function registered by the
+ * renderer on the {@link SurfaceContext}. When no collector is registered,
+ * returns an empty snapshot.
+ *
+ * Portable — works with any renderer (Phaser, Pixi, …). Each renderer
+ * wires its own collector into the SurfaceContext during surface creation.
+ *
+ * @param intervalMs - Refresh interval in milliseconds (default: 250)
+ * @returns Debug snapshot (key → string|number), refreshed on interval
+ *
+ * @example
+ * ```tsx
+ * import { useDebugSnapshot } from '@number10/jsx-core'
+ * import { DebugPanel } from '@number10/jsx-components'
+ *
+ * function App() {
+ *   const snapshot = useDebugSnapshot(500)
+ *   return <DebugPanel snapshot={snapshot} metrics={['fps', 'renderer']} />
+ * }
+ * ```
+ */
+export declare function useDebugSnapshot(intervalMs?: number): Record<string, string | number>;
+type CleanupFn = void | (() => void);
+/**
+ * Layout-aware effect hook — defers execution to the next animation frame.
+ * Uses HostScheduler.requestAnimationFrame() when available, falls back to
+ * global requestAnimationFrame.
+ *
+ * Portable across renderers. Each renderer's HostScheduler provides the tick source.
+ * Phaser uses scene.events.once('update'), PixiJS would use app.ticker.addOnce().
+ *
+ * @param fn - Effect function that optionally returns a cleanup
+ * @param deps - Optional dependency array
+ *
+ * @migration(audit:scene-portal-mount) Phase 6H — portable version uses HostScheduler.
+ */
+export declare function useLayoutEffect(fn: () => CleanupFn, deps?: readonly unknown[] | undefined): void;
+/**
+ * Load a texture from a URL and register it under the given key.
+ * Returns `{ ready, key }` — use `key` as the `texture` prop on `<Image>`.
+ *
+ * Portable — works with any renderer that provides `textureLoader` on
+ * its SurfaceContext. Replaces Phaser-specific preload functions.
+ *
+ * @param key — Unique texture key (e.g. 'icon', 'background')
+ * @param url — URL to load the texture from
+ * @returns `{ ready: boolean, key: string }`
+ *
+ * @example
+ * ```tsx
+ * function MyIcon() {
+ *   const { ready, key } = useTexture('star', '/assets/star.png')
+ *   if (!ready) return <Text text="Loading..." />
+ *   return <Image texture={key} width={48} height={48} />
+ * }
+ * ```
+ */
+export declare function useTexture(key: string, url: string): {
+    ready: boolean;
+    key: string;
+};
+/**
+ * Configuration for loading a single SVG as a texture.
+ * Used by {@link useSVGTexture} for batch loading.
+ */
+export interface SVGTextureConfig {
+    /** Unique texture key */
+    key: string;
+    /** SVG markup string */
+    svg: string;
+    /** Texture width in pixels (default: 32) */
+    width?: number;
+    /** Texture height in pixels (default: 32) */
+    height?: number;
+}
+/**
+ * Render an SVG string to a texture and register it under the given key.
+ * Returns `ready: boolean` — when true, use the key as `<Image texture={key} />`.
+ *
+ * Portable — works with any renderer that provides `textureLoader.loadSVG`
+ * on its SurfaceContext.
+ */
+export declare function useSVGTexture(key: string, svg: string, width?: number, height?: number): boolean;
+/**
+ * Load multiple SVGs as textures in batch.
+ * Returns `ready: boolean` — when true, all textures are registered.
+ */
+export declare function useSVGTexture(configs: SVGTextureConfig[]): boolean;
+/**
+ * Result object returned by {@link useAtlas}.
+ *
+ * Combines atlas loading state with portable metadata access so callers can
+ * render frames and inspect atlas contents without renderer-specific APIs.
+ */
+export interface UseAtlasResult {
+    /** Whether the atlas image and JSON data are fully loaded and queryable. */
+    ready: boolean;
+    /** Texture key to pass into portable image-like components. */
+    key: string;
+    /** Dimensions of the full atlas texture, if available from the active renderer. */
+    textureSize: Size | undefined;
+    /** All known frame names within the loaded atlas. */
+    frameNames: string[];
+    /** Full portable metadata for every known frame in the atlas. */
+    frames: AtlasFrameInfo[];
+    /** Look up full metadata for a specific frame name. */
+    getFrameInfo: (frame: string) => AtlasFrameInfo | undefined;
+    /** Look up only the atlas rectangle for a specific frame name. */
+    getFrameRect: (frame: string) => FrameRect | undefined;
+}
+/**
+ * Load a texture atlas from image + data URLs.
+ * Returns `{ ready, key }` plus portable atlas metadata helpers.
+ * Use `key` as `texture` and frame names as `frame`.
+ *
+ * @param key — Unique atlas key (e.g. 'buttons')
+ * @param imageUrl — URL to the atlas image (PNG)
+ * @param dataUrl — URL to the atlas data (JSON)
+ *
+ * @example
+ * ```tsx
+ * const { ready, key } = useAtlas('buttons', '/ui/buttons.png', '/ui/buttons.json')
+ * if (!ready) return <Text text="Loading..." />
+ * return <Image texture={key} frame="ButtonGreen" />
+ * ```
+ */
+export declare function useAtlas(key: string, imageUrl: string, dataUrl: string): UseAtlasResult;
+export {};
+//# sourceMappingURL=hooks.d.ts.map

package/dist/hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../src/hooks.ts"],"names":[],"mappings":"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"}