@fictjs/runtime 0.0.13 → 0.0.14

package/src/constants.ts

@@ -5,6 +5,8 @@
  * Borrowed from dom-expressions for comprehensive DOM support.
  */
 
+import { DelegatedEventNames } from './delegated-events'
+
 const isDev =
   typeof __DEV__ !== 'undefined'
     ? __DEV__
@@ -262,32 +264,7 @@ export const $$EVENTS = '_$FICT_DELEGATE'
  * Events that should use event delegation for performance
  * These events bubble and are commonly used across many elements
  */
-const delegatedEvents = isDev
-  ? [
-      'beforeinput',
-      'click',
-      'dblclick',
-      'contextmenu',
-      'focusin',
-      'focusout',
-      'input',
-      'keydown',
-      'keyup',
-      'mousedown',
-      'mousemove',
-      'mouseout',
-      'mouseover',
-      'mouseup',
-      'pointerdown',
-      'pointermove',
-      'pointerout',
-      'pointerover',
-      'pointerup',
-      'touchend',
-      'touchmove',
-      'touchstart',
-    ]
-  : []
+const delegatedEvents = isDev ? DelegatedEventNames : []
 
 export const DelegatedEvents = new Set<string>(delegatedEvents)
 

package/src/context.ts

@@ -0,0 +1,300 @@
+/**
+ * @fileoverview Context API for Fict
+ *
+ * Provides a way to pass data through the component tree without having to pass
+ * props down manually at every level. Context is designed for:
+ *
+ * - SSR isolation (different request = different context values)
+ * - Multi-instance support (multiple app roots with different values)
+ * - Subtree scoping (override values in specific parts of the tree)
+ *
+ * ## Design Principles
+ *
+ * 1. **Reuses existing RootContext hierarchy** - Uses parent chain for value lookup,
+ *    consistent with handleError/handleSuspend mechanisms.
+ *
+ * 2. **Zero extra root creation overhead** - Provider doesn't create new root,
+ *    only mounts value on current root.
+ *
+ * 3. **Auto-aligned with insert/suspense boundaries** - Because they create child
+ *    roots that inherit parent, context values propagate correctly.
+ *
+ * ## Usage
+ *
+ * ```tsx
+ * // Create context with default value
+ * const ThemeContext = createContext<'light' | 'dark'>('light')
+ *
+ * // Provide value to subtree
+ * function App() {
+ *   return (
+ *     <ThemeContext.Provider value="dark">
+ *       <ThemedComponent />
+ *     </ThemeContext.Provider>
+ *   )
+ * }
+ *
+ * // Consume value
+ * function ThemedComponent() {
+ *   const theme = useContext(ThemeContext)
+ *   return <div class={theme}>...</div>
+ * }
+ * ```
+ *
+ * @module
+ */
+
+import { createElement } from './dom'
+import {
+  createRootContext,
+  destroyRoot,
+  flushOnMount,
+  getCurrentRoot,
+  popRoot,
+  pushRoot,
+  type RootContext,
+} from './lifecycle'
+import { insertNodesBefore, removeNodes, toNodeArray } from './node-ops'
+import { createRenderEffect } from './effect'
+import type { BaseProps, FictNode } from './types'
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * Context object created by createContext.
+ * Contains the Provider component and serves as a key for context lookup.
+ */
+export interface Context<T> {
+  /** Unique identifier for this context */
+  readonly id: symbol
+  /** Default value when no provider is found */
+  readonly defaultValue: T
+  /** Provider component for supplying context values */
+  Provider: ContextProvider<T>
+  /** Display name for debugging */
+  displayName?: string
+}
+
+/**
+ * Props for the Context Provider component
+ */
+export interface ProviderProps<T> extends BaseProps {
+  /** The value to provide to the subtree */
+  value: T
+}
+
+/**
+ * Provider component type
+ */
+export type ContextProvider<T> = (props: ProviderProps<T>) => FictNode
+
+// ============================================================================
+// Internal Context Storage
+// ============================================================================
+
+/**
+ * WeakMap to store context values per RootContext.
+ * Using WeakMap ensures proper garbage collection when roots are destroyed.
+ */
+const contextStorage = new WeakMap<RootContext, Map<symbol, unknown>>()
+
+/**
+ * Get the context map for a root, creating it if needed
+ */
+function getContextMap(root: RootContext): Map<symbol, unknown> {
+  let map = contextStorage.get(root)
+  if (!map) {
+    map = new Map()
+    contextStorage.set(root, map)
+  }
+  return map
+}
+
+// ============================================================================
+// Context API
+// ============================================================================
+
+/**
+ * Creates a new context with the given default value.
+ *
+ * Context provides a way to pass values through the component tree without
+ * explicit props drilling. It's especially useful for:
+ *
+ * - Theme data
+ * - Locale/i18n settings
+ * - Authentication state
+ * - Feature flags
+ * - Any data that many components at different nesting levels need
+ *
+ * @param defaultValue - The value to use when no Provider is found above in the tree
+ * @returns A context object with a Provider component
+ *
+ * @example
+ * ```tsx
+ * // Create a theme context
+ * const ThemeContext = createContext<'light' | 'dark'>('light')
+ *
+ * // Use the provider
+ * function App() {
+ *   return (
+ *     <ThemeContext.Provider value="dark">
+ *       <Content />
+ *     </ThemeContext.Provider>
+ *   )
+ * }
+ *
+ * // Consume the context
+ * function Content() {
+ *   const theme = useContext(ThemeContext)
+ *   return <div class={`theme-${theme}`}>Hello</div>
+ * }
+ * ```
+ */
+export function createContext<T>(defaultValue: T): Context<T> {
+  const id = Symbol('fict.context')
+
+  const context: Context<T> = {
+    id,
+    defaultValue,
+    Provider: null as unknown as ContextProvider<T>,
+  }
+
+  // Create the Provider component
+  context.Provider = function Provider(props: ProviderProps<T>): FictNode {
+    const hostRoot = getCurrentRoot()
+
+    // Create a child root for the provider's subtree
+    // This establishes the provider boundary - children will look up from here
+    const providerRoot = createRootContext(hostRoot)
+
+    // Store the context value on this root
+    const contextMap = getContextMap(providerRoot)
+    contextMap.set(id, props.value)
+
+    // Create DOM structure
+    const fragment = document.createDocumentFragment()
+    const marker = document.createComment('fict:ctx')
+    fragment.appendChild(marker)
+
+    let cleanup: (() => void) | undefined
+    let activeNodes: Node[] = []
+
+    const renderChildren = (children: FictNode) => {
+      // Cleanup previous render
+      if (cleanup) {
+        cleanup()
+        cleanup = undefined
+      }
+      if (activeNodes.length) {
+        removeNodes(activeNodes)
+        activeNodes = []
+      }
+
+      if (children == null || children === false) {
+        return
+      }
+
+      const prev = pushRoot(providerRoot)
+      let nodes: Node[] = []
+      try {
+        const output = createElement(children)
+        nodes = toNodeArray(output)
+        const parentNode = marker.parentNode as (ParentNode & Node) | null
+        if (parentNode) {
+          insertNodesBefore(parentNode, nodes, marker)
+        }
+      } finally {
+        popRoot(prev)
+        flushOnMount(providerRoot)
+      }
+
+      cleanup = () => {
+        destroyRoot(providerRoot)
+        removeNodes(nodes)
+      }
+      activeNodes = nodes
+    }
+
+    // Initial render
+    createRenderEffect(() => {
+      // Update context value on re-render (if value prop changes reactively)
+      contextMap.set(id, props.value)
+      renderChildren(props.children)
+    })
+
+    return fragment
+  }
+
+  return context
+}
+
+/**
+ * Reads the current value of a context.
+ *
+ * useContext looks up through the RootContext parent chain to find the
+ * nearest Provider for this context. If no Provider is found, returns
+ * the context's default value.
+ *
+ * @param context - The context object created by createContext
+ * @returns The current context value
+ *
+ * @example
+ * ```tsx
+ * const ThemeContext = createContext('light')
+ *
+ * function ThemedButton() {
+ *   const theme = useContext(ThemeContext)
+ *   return <button class={theme === 'dark' ? 'btn-dark' : 'btn-light'}>Click</button>
+ * }
+ * ```
+ */
+export function useContext<T>(context: Context<T>): T {
+  let root = getCurrentRoot()
+
+  // Walk up the parent chain looking for the context value
+  while (root) {
+    const contextMap = contextStorage.get(root)
+    if (contextMap && contextMap.has(context.id)) {
+      return contextMap.get(context.id) as T
+    }
+    root = root.parent
+  }
+
+  // No provider found, return default value
+  return context.defaultValue
+}
+
+/**
+ * Checks if a context value is currently provided in the tree.
+ *
+ * Useful for conditional behavior when a provider may or may not exist.
+ *
+ * @param context - The context object to check
+ * @returns true if a Provider exists above in the tree
+ *
+ * @example
+ * ```tsx
+ * function OptionalTheme() {
+ *   if (hasContext(ThemeContext)) {
+ *     const theme = useContext(ThemeContext)
+ *     return <div class={theme}>Themed content</div>
+ *   }
+ *   return <div>Default content</div>
+ * }
+ * ```
+ */
+export function hasContext<T>(context: Context<T>): boolean {
+  let root = getCurrentRoot()
+
+  while (root) {
+    const contextMap = contextStorage.get(root)
+    if (contextMap && contextMap.has(context.id)) {
+      return true
+    }
+    root = root.parent
+  }
+
+  return false
+}

package/src/delegated-events.ts

@@ -0,0 +1,24 @@
+export const DelegatedEventNames = [
+  'beforeinput',
+  'click',
+  'dblclick',
+  'contextmenu',
+  'focusin',
+  'focusout',
+  'input',
+  'keydown',
+  'keyup',
+  'mousedown',
+  'mousemove',
+  'mouseout',
+  'mouseover',
+  'mouseup',
+  'pointerdown',
+  'pointermove',
+  'pointerout',
+  'pointerover',
+  'pointerup',
+  'touchend',
+  'touchmove',
+  'touchstart',
+] as const

package/src/index.ts

@@ -1,38 +1,37 @@
+/**
+ * @fileoverview Fict Runtime - Public API
+ *
+ * This module exports the public API for the Fict reactive UI framework.
+ *
+ * ## Recommended Import Pattern (v1.0+)
+ *
+ * ```typescript
+ * // Core public API (most users need only this)
+ * import { createEffect, render } from '@fictjs/runtime'
+ *
+ * // Advanced APIs (power users, escape hatches)
+ * import { createSignal, createContext, createScope } from '@fictjs/runtime/advanced'
+ *
+ * // Internal APIs (compiler/library authors only)
+ * import { bindText, __fictUseSignal } from '@fictjs/runtime/internal'
+ * ```
+ *
+ * @public
+ * @packageDocumentation
+ */
+
 // ============================================================================
 // Core Reactive Primitives
 // ============================================================================
 
-export { createSignal, createSelector, type Signal, $state } from './signal'
-export { effectScope } from './signal'
-export { createStore, type Store } from './store'
-export { createMemo, type Memo, $memo } from './memo'
-export { createEffect, createRenderEffect, type Effect, $effect } from './effect'
-export { createScope, runInScope, type ReactiveScope } from './scope'
-export {
-  __fictUseContext,
-  __fictPushContext,
-  __fictPopContext,
-  __fictUseSignal,
-  __fictUseMemo,
-  __fictUseEffect,
-  __fictRender,
-  __fictResetContext,
-} from './hooks'
-export {
-  createVersionedSignal,
-  type VersionedSignal,
-  type VersionedSignalOptions,
-} from './versioned-signal'
-
-// Props helpers
-export {
-  __fictProp,
-  __fictProp as prop,
-  __fictPropsRest,
-  mergeProps,
-  useProp,
-  createPropsProxy,
-} from './props'
+/**
+ * Note: createSignal is exported from ./advanced as an escape hatch.
+ * For most use cases, prefer:
+ * - $state: For component-local state (compiler-transformed, safe scoping)
+ * - $store: For cross-component shared state with deep reactivity
+ */
+export { createMemo, type Memo } from './memo'
+export { createEffect, type Effect } from './effect'
 
 // ============================================================================
 // Lifecycle
@@ -40,7 +39,10 @@ export {
 
 export { onMount, onDestroy, onCleanup, createRoot } from './lifecycle'
 
-// Ref utilities
+// ============================================================================
+// Ref
+// ============================================================================
+
 export { createRef } from './ref'
 
 // ============================================================================
@@ -48,9 +50,6 @@ export { createRef } from './ref'
 // ============================================================================
 
 export { batch, untrack } from './scheduler'
-export { setCycleProtectionOptions } from './cycle-guard'
-
-// Transition API for priority scheduling
 export { startTransition, useTransition, useDeferredValue } from './scheduler'
 
 // ============================================================================
@@ -64,71 +63,22 @@ export { Fragment } from './jsx'
 // DOM Rendering
 // ============================================================================
 
-export { createElement, render, template } from './dom'
+export { createElement, render } from './dom'
+export { createPortal } from './binding'
 export { ErrorBoundary } from './error-boundary'
 export { Suspense, createSuspenseToken } from './suspense'
+export { createContext, useContext, hasContext, type Context, type ProviderProps } from './context'
 
 // ============================================================================
-// Reactive DOM Bindings
-// ============================================================================
-
-export {
-  // Core binding utilities
-  createTextBinding,
-  createChildBinding,
-  createAttributeBinding,
-  createStyleBinding,
-  createClassBinding,
-  // Low-level binding helpers (for direct DOM manipulation)
-  bindText,
-  bindAttribute,
-  bindStyle,
-  bindClass,
-  bindEvent,
-  callEventHandler,
-  bindProperty,
-  bindRef,
-  insert,
-  // Event delegation
-  delegateEvents,
-  clearDelegatedEvents,
-  addEventListener,
-  // Spread props
-  spread,
-  assign,
-  classList,
-  // Reactive detection
-  isReactive,
-  // Advanced bindings
-  createConditional,
-  createPortal,
-  createShow,
-  // Utility functions
-  unwrap,
-} from './binding'
-
-// Constants for DOM handling
-export {
-  Properties,
-  ChildProperties,
-  Aliases,
-  getPropAlias,
-  BooleanAttributes,
-  SVGElements,
-  SVGNamespace,
-  DelegatedEvents,
-  UnitlessStyles,
-} from './constants'
-
-// Reconcile algorithm
-export { default as reconcileArrays } from './reconcile'
+// Props Utilities (Public)
+// ============================================================================
+
+export { prop, mergeProps } from './props'
 
 // ============================================================================
 // Types
 // ============================================================================
 
-export type { MaybeReactive, BindingHandle, CreateElementFn, AttributeSetter } from './binding'
-
 export type {
   FictNode,
   FictVNode,
@@ -146,24 +96,3 @@ export type {
   ErrorInfo,
   SuspenseToken,
 } from './types'
-
-// Devtools hook (optional)
-export { getDevtoolsHook, type FictDevtoolsHook } from './devtools'
-
-// ============================================================================
-// List Helpers (for compiler-generated code)
-// ============================================================================
-
-export {
-  // DOM manipulation primitives
-  moveNodesBefore,
-  removeNodes,
-  insertNodesBefore,
-  // High-level list binding (for compiler-generated code)
-  createKeyedList,
-  // Utilities
-  toNodeArray,
-  isNodeBetweenMarkers,
-  // Types
-  type KeyedListBinding,
-} from './list-helpers'

package/src/internal.ts

@@ -0,0 +1,130 @@
+/**
+ * @fileoverview Internal APIs for Fict Compiler
+ *
+ * This module exports internal APIs used by compiler-generated code.
+ * These APIs are NOT part of the public API and should NOT be used directly.
+ *
+ * @internal
+ * @packageDocumentation
+ */
+
+// ============================================================================
+// Core Primitives (also exported from main, but needed by compiler)
+// ============================================================================
+
+export { createSignal, createSelector } from './signal'
+export { createStore, type Store } from './store'
+export { createMemo } from './memo'
+export { createEffect } from './effect'
+export { Fragment } from './jsx'
+
+// ============================================================================
+// Hook Context Management (Compiler-generated code)
+// ============================================================================
+
+export {
+  __fictUseContext,
+  __fictPushContext,
+  __fictPopContext,
+  __fictUseSignal,
+  __fictUseMemo,
+  __fictUseEffect,
+  __fictRender,
+  __fictResetContext,
+} from './hooks'
+
+// ============================================================================
+// Props Helpers (Compiler-generated code)
+// ============================================================================
+
+export { __fictProp, __fictPropsRest, createPropsProxy, mergeProps, prop } from './props'
+
+// ============================================================================
+// DOM Bindings (Compiler-generated code)
+// ============================================================================
+
+export {
+  bindText,
+  bindAttribute,
+  bindStyle,
+  bindClass,
+  bindEvent,
+  callEventHandler,
+  bindProperty,
+  bindRef,
+  insert,
+  createConditional,
+  createPortal,
+  spread,
+  assign,
+  classList,
+  isReactive,
+  unwrap,
+} from './binding'
+
+// ============================================================================
+// Event Delegation (Compiler-generated code)
+// ============================================================================
+
+export { delegateEvents, clearDelegatedEvents, addEventListener } from './binding'
+
+// ============================================================================
+// List Helpers (Compiler-generated code)
+// ============================================================================
+
+export {
+  moveNodesBefore,
+  removeNodes,
+  insertNodesBefore,
+  createKeyedList,
+  toNodeArray,
+  isNodeBetweenMarkers,
+  type KeyedListBinding,
+} from './list-helpers'
+
+// ============================================================================
+// DOM Creation (Compiler-generated code)
+// ============================================================================
+
+export { createElement, template } from './dom'
+export { createRenderEffect } from './effect'
+
+// ============================================================================
+// Lifecycle (Compiler-generated code)
+// ============================================================================
+
+export { onDestroy } from './lifecycle'
+
+// ============================================================================
+// Scope (Compiler-generated code)
+// ============================================================================
+
+export { runInScope } from './scope'
+
+// ============================================================================
+// Constants (Compiler/Runtime shared)
+// ============================================================================
+
+export {
+  Properties,
+  ChildProperties,
+  Aliases,
+  getPropAlias,
+  BooleanAttributes,
+  SVGElements,
+  SVGNamespace,
+  DelegatedEvents,
+  UnitlessStyles,
+} from './constants'
+
+// ============================================================================
+// Reconciliation (Internal)
+// ============================================================================
+
+export { default as reconcileArrays } from './reconcile'
+
+// ============================================================================
+// Types (Internal)
+// ============================================================================
+
+export type { MaybeReactive, BindingHandle, CreateElementFn, AttributeSetter } from './binding'