@pyreon/core 0.1.0

package/src/lazy.ts

@@ -0,0 +1,25 @@
+import { signal } from "@pyreon/reactivity"
+import { h } from "./h"
+import type { LazyComponent } from "./suspense"
+import type { ComponentFn, Props } from "./types"
+
+export function lazy<P extends Props>(
+  load: () => Promise<{ default: ComponentFn<P> }>,
+): LazyComponent<P> {
+  const loaded = signal<ComponentFn<P> | null>(null)
+  const error = signal<Error | null>(null)
+
+  load()
+    .then((m) => loaded.set(m.default))
+    .catch((e) => error.set(e instanceof Error ? e : new Error(String(e))))
+
+  const wrapper = ((props: P) => {
+    const err = error()
+    if (err) throw err
+    const comp = loaded()
+    return comp ? h(comp as ComponentFn, props as Props) : null
+  }) as LazyComponent<P>
+
+  wrapper.__loading = () => loaded() === null && error() === null
+  return wrapper
+}

package/src/lifecycle.ts

@@ -0,0 +1,52 @@
+import type { CleanupFn, LifecycleHooks } from "./types"
+
+// The currently-executing component's hook storage, set by the renderer
+// before calling the component function, cleared immediately after.
+let _current: LifecycleHooks | null = null
+
+export function setCurrentHooks(hooks: LifecycleHooks | null) {
+  _current = hooks
+}
+
+export function getCurrentHooks(): LifecycleHooks | null {
+  return _current
+}
+
+/**
+ * Register a callback to run after the component is mounted to the DOM.
+ * Optionally return a cleanup function — it will run on unmount.
+ */
+export function onMount(fn: () => CleanupFn | undefined) {
+  _current?.mount.push(fn)
+}
+
+/**
+ * Register a callback to run when the component is removed from the DOM.
+ */
+export function onUnmount(fn: () => void) {
+  _current?.unmount.push(fn)
+}
+
+/**
+ * Register a callback to run after each reactive update.
+ */
+export function onUpdate(fn: () => void) {
+  _current?.update.push(fn)
+}
+
+/**
+ * Register an error handler for this component subtree.
+ *
+ * When an error is thrown during rendering or in a child component,
+ * the nearest `onErrorCaptured` handler is called with the error.
+ * Return `true` to mark the error as handled and stop propagation.
+ *
+ * @example
+ * onErrorCaptured((err) => {
+ *   setError(String(err))
+ *   return true // handled — don't propagate
+ * })
+ */
+export function onErrorCaptured(fn: (err: unknown) => boolean | undefined) {
+  _current?.error.push(fn)
+}

package/src/map-array.ts

@@ -0,0 +1,42 @@
+/**
+ * mapArray — keyed reactive list mapping.
+ *
+ * Creates each mapped item exactly once per key, then reuses it across
+ * updates. When the source array is reordered or partially changed, only
+ * new keys invoke `map()`; existing entries return the cached result.
+ *
+ * This makes structural list operations (swap, sort, filter) O(k) in
+ * allocations where k is the number of new/removed keys, not O(n).
+ *
+ * The returned accessor reads `source()` reactively, so it can be passed
+ * directly to the keyed-list reconciler.
+ */
+export function mapArray<T, U>(
+  source: () => T[],
+  getKey: (item: T) => string | number,
+  map: (item: T) => U,
+): () => U[] {
+  const cache = new Map<string | number, U>()
+
+  return () => {
+    const items = source()
+    const result: U[] = []
+    const newKeys = new Set<string | number>()
+
+    for (const item of items) {
+      const key = getKey(item)
+      newKeys.add(key)
+      if (!cache.has(key)) {
+        cache.set(key, map(item))
+      }
+      result.push(cache.get(key) as U)
+    }
+
+    // Evict entries whose keys are no longer present
+    for (const key of cache.keys()) {
+      if (!newKeys.has(key)) cache.delete(key)
+    }
+
+    return result
+  }
+}

package/src/portal.ts

@@ -0,0 +1,39 @@
+import type { Props, VNode, VNodeChild } from "./types"
+
+/**
+ * Symbol used as the VNode type for a Portal — runtime-dom mounts the
+ * children into `target` instead of the normal parent.
+ */
+export const PortalSymbol: unique symbol = Symbol("pyreon.Portal")
+
+export interface PortalProps {
+  /** DOM element to render children into (e.g. document.body). */
+  target: Element
+  children: VNodeChild
+}
+
+/**
+ * Portal — renders `children` into a different DOM node than the
+ * current parent tree.
+ *
+ * Useful for modals, tooltips, dropdowns, and any overlay that needs to
+ * escape CSS overflow/stacking context restrictions.
+ *
+ * @example
+ * // Render a modal at document.body level regardless of where in the
+ * // component tree <Modal> is used:
+ * Portal({ target: document.body, children: h(Modal, { onClose }) })
+ *
+ * // JSX:
+ * <Portal target={document.body}>
+ *   <Modal onClose={close} />
+ * </Portal>
+ */
+export function Portal(props: PortalProps): VNode {
+  return {
+    type: PortalSymbol as unknown as string,
+    props: props as unknown as Props,
+    children: [],
+    key: null,
+  }
+}

package/src/ref.ts

@@ -0,0 +1,19 @@
+/**
+ * createRef — mutable container for a DOM element or component value.
+ *
+ * Usage:
+ *   const inputRef = createRef<HTMLInputElement>()
+ *   onMount(() => { inputRef.current?.focus() })
+ *   return <input ref={inputRef} />
+ *
+ * The runtime sets `ref.current` after the element is inserted into the DOM
+ * and clears it to `null` when the element is removed.
+ */
+
+export interface Ref<T = unknown> {
+  current: T | null
+}
+
+export function createRef<T = unknown>(): Ref<T> {
+  return { current: null }
+}

package/src/show.ts

@@ -0,0 +1,108 @@
+import type { Props, VNode, VNodeChild, VNodeChildAtom } from "./types"
+
+// ─── Show ─────────────────────────────────────────────────────────────────────
+
+export interface ShowProps extends Props {
+  /** Accessor — children render when truthy, fallback when falsy. */
+  when: () => unknown
+  fallback?: VNodeChild
+  children?: VNodeChild
+}
+
+/**
+ * Conditionally render children based on a reactive condition.
+ *
+ * @example
+ * h(Show, { when: () => isLoggedIn() },
+ *   h(Dashboard, null)
+ * )
+ *
+ * // With fallback:
+ * h(Show, { when: () => user(), fallback: h(Login, null) },
+ *   h(Dashboard, null)
+ * )
+ */
+export function Show(props: ShowProps): VNode | null {
+  // Returns a reactive accessor; the renderer unwraps it at mount time.
+  return ((): VNodeChildAtom =>
+    (props.when()
+      ? (props.children ?? null)
+      : (props.fallback ?? null)) as VNodeChildAtom) as unknown as VNode
+}
+
+// ─── Switch / Match ───────────────────────────────────────────────────────────
+
+export interface MatchProps extends Props {
+  /** Accessor — this branch renders when truthy. */
+  when: () => unknown
+  children?: VNodeChild
+}
+
+/**
+ * A branch inside `<Switch>`. Renders when `when()` is truthy.
+ * Must be used as a direct child of `Switch`.
+ *
+ * `Match` acts as a pure type/identity marker — Switch identifies it by checking
+ * `vnode.type === Match` rather than by the runtime return value.
+ */
+export function Match(_props: MatchProps): VNode | null {
+  // Match is never mounted directly — Switch inspects Match VNodes by type identity.
+  return null
+}
+
+export interface SwitchProps extends Props {
+  /** Rendered when no Match branch is truthy. */
+  fallback?: VNodeChild
+  children?: VNodeChild | VNodeChild[]
+}
+
+/**
+ * Multi-branch conditional rendering. Evaluates each `Match` child in order,
+ * renders the first whose `when()` is truthy, or `fallback` if none match.
+ *
+ * @example
+ * h(Switch, { fallback: h("p", null, "404") },
+ *   h(Match, { when: () => route() === "/" }, h(Home, null)),
+ *   h(Match, { when: () => route() === "/about" }, h(About, null)),
+ * )
+ */
+function isMatchVNode(branch: VNodeChild): branch is VNode {
+  return (
+    branch !== null &&
+    typeof branch === "object" &&
+    !Array.isArray(branch) &&
+    (branch as VNode).type === Match
+  )
+}
+
+function resolveMatchChildren(matchVNode: VNode): VNodeChildAtom {
+  if (matchVNode.children.length === 0) {
+    return ((matchVNode.props as unknown as MatchProps).children ?? null) as VNodeChildAtom
+  }
+  if (matchVNode.children.length === 1) return matchVNode.children[0] as VNodeChildAtom
+  return matchVNode.children as unknown as VNodeChildAtom
+}
+
+function normalizeBranches(children: SwitchProps["children"]): VNodeChild[] {
+  if (Array.isArray(children)) return children
+  if (children != null) return [children]
+  return []
+}
+
+export function Switch(props: SwitchProps): VNode | null {
+  // Returns a reactive accessor; the renderer unwraps it at mount time.
+  return ((): VNodeChildAtom => {
+    const branches = normalizeBranches(props.children)
+
+    for (const branch of branches) {
+      if (!isMatchVNode(branch)) continue
+      const matchProps = branch.props as unknown as MatchProps
+      if (matchProps.when()) return resolveMatchChildren(branch)
+    }
+
+    return (props.fallback ?? null) as VNodeChildAtom
+  }) as unknown as VNode
+}
+
+// Keep MatchSymbol export for any code that was using it
+export const MatchSymbol: unique symbol = Symbol("pyreon.Match")

package/src/suspense.ts

@@ -0,0 +1,41 @@
+import { Fragment, h } from "./h"
+import type { Props, VNode, VNodeChild } from "./types"
+
+/** Internal marker attached to lazy()-wrapped components */
+export type LazyComponent<P extends Props = Props> = ((props: P) => VNode | null) & {
+  __loading: () => boolean
+}
+
+/**
+ * Suspense — shows `fallback` while a lazy child component is still loading.
+ *
+ * Works in tandem with `lazy()` from `@pyreon/react-compat` (or `@pyreon/core/lazy`).
+ * The child VNode's `.type.__loading()` signal drives the switch.
+ *
+ * Usage:
+ *   const Page = lazy(() => import("./Page"))
+ *
+ *   h(Suspense, { fallback: h(Spinner, null) }, h(Page, null))
+ *   // or with JSX:
+ *   <Suspense fallback={<Spinner />}><Page /></Suspense>
+ */
+export function Suspense(props: { fallback: VNodeChild; children?: VNodeChild }): VNode {
+  return h(Fragment, null, () => {
+    const ch = props.children
+    const childNode = typeof ch === "function" ? ch() : ch
+
+    // Check if the child is a VNode whose type is a lazy component still loading
+    const isLoading =
+      childNode != null &&
+      typeof childNode === "object" &&
+      !Array.isArray(childNode) &&
+      typeof (childNode as VNode).type === "function" &&
+      ((childNode as VNode).type as unknown as LazyComponent).__loading?.()
+
+    if (isLoading) {
+      const fb = props.fallback
+      return typeof fb === "function" ? fb() : fb
+    }
+    return childNode
+  })
+}

package/src/telemetry.ts

@@ -0,0 +1,55 @@
+/**
+ * Error telemetry — hook into Pyreon's error reporting for Sentry, Datadog, etc.
+ *
+ * @example
+ * import { registerErrorHandler } from "@pyreon/core"
+ * import * as Sentry from "@sentry/browser"
+ *
+ * registerErrorHandler(ctx => {
+ *   Sentry.captureException(ctx.error, {
+ *     extra: { component: ctx.component, phase: ctx.phase },
+ *   })
+ * })
+ */
+
+export interface ErrorContext {
+  /** Component function name, or "Anonymous" */
+  component: string
+  /** Lifecycle phase where the error occurred */
+  phase: "setup" | "render" | "mount" | "unmount" | "effect"
+  /** The thrown value */
+  error: unknown
+  /** Unix timestamp (ms) */
+  timestamp: number
+  /** Component props at the time of the error */
+  props?: Record<string, unknown>
+}
+
+export type ErrorHandler = (ctx: ErrorContext) => void
+
+let _handlers: ErrorHandler[] = []
+
+/**
+ * Register a global error handler. Called whenever a component throws in any
+ * lifecycle phase. Returns an unregister function.
+ */
+export function registerErrorHandler(handler: ErrorHandler): () => void {
+  _handlers.push(handler)
+  return () => {
+    _handlers = _handlers.filter((h) => h !== handler)
+  }
+}
+
+/**
+ * Internal — called by the runtime whenever a component error is caught.
+ * Existing console.error calls are preserved; this is additive.
+ */
+export function reportError(ctx: ErrorContext): void {
+  for (const h of _handlers) {
+    try {
+      h(ctx)
+    } catch {
+      // handler errors must never propagate back into the framework
+    }
+  }
+}