deskforge 1.0.0

package/packages/state/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@deskforge/state",
+  "version": "1.0.0",
+  "description": "DeskForge reactive state system",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "check": "tsc --noEmit",
+    "prepare": "npm run build"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0"
+  },
+  "license": "MIT",
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/deskforge/deskforge.git"
+  },
+  "bugs": {
+    "url": "https://github.com/deskforge/deskforge/issues"
+  },
+  "homepage": "https://github.com/deskforge/deskforge#readme"
+}

package/packages/state/src/computed.ts

@@ -0,0 +1,75 @@
+// computed.ts
+// A Computed value derives from state automatically.
+// It recalculates only when its dependencies change.
+// Reading computed.value always gives the latest result.
+
+import {track} from './state'
+import { schedule, createScheduler } from '@deskforge/core'
+import type { Scheduler } from '@deskforge/core'
+
+// Represents a derived reactive value
+// T is the type of the computed result
+interface DFComputed<T> {
+  readonly value: T  // current result — never set directly
+  invalidate():  void // forces recalculation on next read
+  dispose():     void // stops watching — cleans up memory
+}
+
+// Creates a derived value that updates automatically
+// fn — function that computes the value from state
+// Re-runs only when state it reads actually changes
+function Computed<T>(
+  fn:        () => T,
+  scheduler?: Scheduler
+): DFComputed<T> {
+  const finalScheduler = scheduler || createScheduler()
+  let cachedValue:  T | undefined = undefined
+  let isDirty:      boolean       = true   // true = needs recalc
+  let isDisposed:   boolean       = false  // true = dead, no updates
+
+  // Called when a dependency changes
+  // Marks computed as dirty so next read recalculates
+  const subscriber = (): void => {
+    if (!isDisposed) {
+      isDirty = true
+      schedule(finalScheduler, () => {})
+    }
+  }
+
+  // Gets the current value
+  // Recalculates if dirty — returns cache if clean
+  function getValue(): T {
+    if (isDisposed) {
+      throw new Error('Computed has been disposed')
+    }
+
+    if (isDirty) {
+      // Run fn() while tracking which state it reads
+      track(subscriber, () => {
+        cachedValue = fn()
+      })
+      isDirty = false
+    }
+
+    return cachedValue as T
+  }
+
+  // Forces recalculation on next read
+  function invalidate(): void {
+    isDirty = true
+  }
+
+  // Kills this computed — no more updates after this
+  function dispose(): void {
+    isDisposed = true
+  }
+
+  return {
+    get value()  { return getValue() },
+    invalidate,
+    dispose
+  }
+}
+
+export type { DFComputed }
+export { Computed }

package/packages/state/src/context.ts

@@ -0,0 +1,56 @@
+// context.ts
+// Shares state across the component tree without prop drilling.
+// Create a context at the top level.
+// Any component anywhere in the tree can consume it.
+
+import { State } from './state'
+import { createScheduler } from '@deskforge/core'
+
+// The object returned by Context()
+interface DFContext<T extends Record<string, unknown>> {
+  // The reactive state shared across the tree
+  state: T
+  // Reads the current context value from any component
+  use:   () => T
+  // Updates the context state
+  set:   (updates: Partial<T>) => void
+}
+
+// Creates a shared reactive state container
+// Any component that calls context.use() gets the same state
+// When state changes all consumers re-render automatically
+function Context<T extends Record<string, unknown>>(
+  defaultValue: T
+): DFContext<T> {
+  // Each context gets its own scheduler
+  const scheduler = createScheduler()
+
+  // Create reactive state from default values
+  const reactiveState = State(
+    { ...defaultValue },
+    scheduler
+  )
+
+  // Returns the current context state
+  // Call this inside any component to access shared state
+  function use(): T {
+    return reactiveState
+  }
+
+  // Updates one or more values in the context state
+  function set(updates: Partial<T>): void {
+    Object.keys(updates).forEach(key => {
+      (reactiveState as Record<string, unknown>)[key] =
+        updates[key as keyof T]
+    })
+  }
+
+  return {
+    state: reactiveState,
+    use,
+    set
+  }
+}
+
+export type { DFContext }
+export { Context }

package/packages/state/src/effect.ts

@@ -0,0 +1,100 @@
+// effect.ts
+// Effect runs a side effect tied to component lifecycle.
+// Unlike Watch it tracks everything it reads automatically.
+// Re-runs whenever any state it touched changes.
+
+import { track }          from './state'
+import { schedule, createScheduler } from '@deskforge/core'
+import type { Scheduler } from '@deskforge/core'
+
+// The function the developer writes inside Effect()
+// Can optionally return a cleanup function
+type EffectFn = () => void | (() => void)
+
+// Returned by Effect() — lets you stop or run manually
+interface EffectHandle {
+  stop(): void // stops the effect permanently
+  run():  void // manually triggers the effect now
+}
+
+// Creates a side effect tied to reactive state
+// Runs on mount and re-runs when dependencies change
+// Optional dependencies array — if provided only watches those
+function Effect(
+  fn:           EffectFn,
+  scheduler?:    Scheduler,
+  dependencies?: () => unknown[]
+): EffectHandle {
+  const finalScheduler = scheduler || createScheduler()
+  let cleanup:   (() => void) | undefined = undefined
+  let isStopped: boolean                  = false
+
+  // Runs any cleanup from previous execution
+  function runCleanup(): void {
+    if (cleanup) {
+      cleanup()
+      cleanup = undefined
+    }
+  }
+
+  // Executes the effect function
+  // Tracks dependencies automatically if none specified
+  function run(): void {
+    if (isStopped) return
+
+    runCleanup()
+
+    if (dependencies) {
+      // Explicit dependencies — only watch those
+      dependencies()
+      const result = fn()
+      if (typeof result === 'function') {
+        cleanup = result
+      }
+    } else {
+      // Auto-track — watch everything fn reads
+      track(subscriber, () => {
+        const result = fn()
+        if (typeof result === 'function') {
+          cleanup = result
+        }
+      })
+    }
+  }
+
+  // Called when a dependency changes
+  // Schedules a re-run via the scheduler
+  const subscriber = (): void => {
+    if (!isStopped) {
+      schedule(finalScheduler, run)
+    }
+  }
+
+  // Schedule initial run on next tick
+  schedule(finalScheduler, run)
+
+  return {
+    // Stops the effect and runs final cleanup
+    stop(): void {
+      isStopped = true
+      runCleanup()
+    },
+    // Manually schedules a run
+    run(): void {
+      schedule(finalScheduler, run)
+    }
+  }
+}
+
+// Effect with explicit dependency array
+// Only re-runs when specified values change
+Effect.deps = function(
+  fn:           EffectFn,
+  dependencies: () => unknown[],
+  scheduler?:    Scheduler
+): EffectHandle {
+  return Effect(fn, scheduler, dependencies)
+}
+
+export type { EffectFn, EffectHandle }
+export { Effect }

package/packages/state/src/events/dispatch.ts

@@ -0,0 +1,79 @@
+// dispatch.ts
+// Stage 4 of the event pipeline — the final stage.
+// Takes the propagated event and delivers it to
+// the developer's callback in a clean simple form.
+// Developer sees onClick(state) — nothing else.
+// All the complexity of the previous three stages is hidden.
+
+import type { DFEvent }    from './event'
+import type { HandlerMap } from './propagation'
+
+// The clean callback shape the developer writes
+// They only see the event — never the pipeline
+type DFCallback = (event: DFEvent) => void
+
+// Maps component prop names to event types
+// e.g. "onClick" maps to "TAP"
+const PROP_TO_EVENT: Record<string, string> = {
+  onClick:      'TAP',
+  onDoubleTap:  'DOUBLE_TAP',
+  onLongPress:  'LONG_PRESS',
+  onDragStart:  'DRAG_START',
+  onDragMove:   'DRAG_MOVE',
+  onDragEnd:    'DRAG_END',
+  onSwipeLeft:  'SWIPE_LEFT',
+  onSwipeRight: 'SWIPE_RIGHT',
+  onSwipeUp:    'SWIPE_UP',
+  onSwipeDown:  'SWIPE_DOWN',
+  onKeyDown:    'KEY_DOWN',
+  onKeyUp:      'KEY_UP',
+  onFocus:      'FOCUS',
+  onBlur:       'BLUR',
+  onScroll:     'SCROLL',
+  onHoverEnter: 'HOVER_ENTER',
+  onHoverLeave: 'HOVER_LEAVE',
+}
+
+// Extracts all event handlers from a node's props
+// Returns a map of event type to callback
+function extractHandlers(
+  nodeId: string,
+  props:  Record<string, unknown>,
+  map:    HandlerMap
+): void {
+  Object.keys(PROP_TO_EVENT).forEach(propName => {
+    const callback = props[propName]
+
+    if (typeof callback === 'function') {
+      // Register this node's handler in the map
+      map.set(nodeId, (event: DFEvent) => {
+        // Only fire if event type matches
+        if (event.type === PROP_TO_EVENT[propName]) {
+          (callback as DFCallback)(event)
+        }
+      })
+    }
+  })
+}
+
+// Dispatches a fully processed event to the developer
+// Called after ingestion, hit testing, and propagation
+// This is what the developer actually experiences
+function dispatch(
+  event:      DFEvent,
+  handlerMap: HandlerMap
+): void {
+  // Nothing to dispatch if no target was hit
+  if (!event.targetId) return
+
+  // Get the handler for the target node
+  const handler = handlerMap.get(event.targetId)
+
+  if (handler) {
+    // Deliver the clean event to the developer callback
+    handler(event)
+  }
+}
+
+export type { DFCallback }
+export { dispatch, extractHandlers, PROP_TO_EVENT }

package/packages/state/src/events/event.ts

@@ -0,0 +1,97 @@
+// event.ts
+// Defines the clean platform-agnostic event object.
+// Every OS sends different raw events.
+// DeskForge converts them all into this one clean shape.
+// Developer only ever sees DFEvent — never raw OS messages.
+
+// All possible event types in DeskForge
+type DFEventType =
+  | 'TAP'           // finger or mouse click
+  | 'DOUBLE_TAP'    // double click or double tap
+  | 'LONG_PRESS'    // held down for 500ms+
+  | 'DRAG_START'    // drag began
+  | 'DRAG_MOVE'     // drag in progress
+  | 'DRAG_END'      // drag finished
+  | 'SWIPE_LEFT'    // swipe gesture left
+  | 'SWIPE_RIGHT'   // swipe gesture right
+  | 'SWIPE_UP'      // swipe gesture up
+  | 'SWIPE_DOWN'    // swipe gesture down
+  | 'KEY_DOWN'      // keyboard key pressed
+  | 'KEY_UP'        // keyboard key released
+  | 'FOCUS'         // component received focus
+  | 'BLUR'          // component lost focus
+  | 'SCROLL'        // scroll event
+  | 'RESIZE'        // window or component resized
+  | 'HOVER_ENTER'   // mouse entered component bounds
+  | 'HOVER_LEAVE'   // mouse left component bounds
+
+// The source platform that generated the event
+type DFEventSource =
+  | 'windows'
+  | 'macos'
+  | 'linux'
+  | 'ios'
+  | 'android'
+
+// Clean platform-agnostic event object
+// Every OS event gets converted to this shape
+interface DFEvent {
+  // What kind of event this is
+  type:      DFEventType
+
+  // Which platform generated it
+  source:    DFEventSource
+
+  // X coordinate where event occurred
+  x:         number
+
+  // Y coordinate where event occurred
+  y:         number
+
+  // When event occurred in milliseconds
+  timestamp: number
+
+  // ID of the node that was targeted
+  // Set by hit testing after ingestion
+  targetId:  string | null
+
+  // For keyboard events — which key was pressed
+  key:       string | null
+
+  // Whether propagation has been stopped
+  // Set to true by a handler to prevent bubbling
+  stopped:   boolean
+
+  // Raw OS event data — for advanced use only
+  raw:       unknown
+}
+
+// Creates a clean DFEvent from raw data
+function createEvent(
+  type:   DFEventType,
+  source: DFEventSource,
+  x:      number,
+  y:      number,
+  raw:    unknown,
+  key?:   string
+): DFEvent {
+  return {
+    type,
+    source,
+    x,
+    y,
+    timestamp: Date.now(),
+    targetId:  null,
+    key:       key ?? null,
+    stopped:   false,
+    raw
+  }
+}
+
+// Stops event from bubbling further up the tree
+function stopPropagation(event: DFEvent): void {
+  event.stopped = true
+}
+
+export type { DFEvent, DFEventType, DFEventSource }
+export { createEvent, stopPropagation }

package/packages/state/src/events/hittest.ts

@@ -0,0 +1,95 @@
+// hittest.ts
+// Stage 2 of the event pipeline.
+// Finds exactly which node the user targeted.
+// Uses the pixel coordinates from the event
+// and the layout coordinates calculated by C++ Muscle.
+// Walks the tree and returns the deepest matching node.
+
+import type { DFTree, DFNode } from '@deskforge/core'
+import type { DFEvent } from './event'
+// The layout rectangle of a node
+// Calculated by the C++ layout engine
+interface DFLayoutRect {
+  x:      number  // left edge
+  y:      number  // top edge
+  width:  number  // total width
+  height: number  // total height
+}
+
+// Maps node IDs to their layout rectangles
+// Populated by the C++ Muscle after every layout pass
+type LayoutMap = Map<string, DFLayoutRect>
+
+// Returns true if point is inside the rectangle
+function containsPoint(
+  rect: DFLayoutRect,
+  x:    number,
+  y:    number
+): boolean {
+  return (
+    x >= rect.x &&
+    x <= rect.x + rect.width &&
+    y >= rect.y &&
+    y <= rect.y + rect.height
+  )
+}
+
+// Walks the tree depth first looking for the deepest node
+// that contains the event coordinates
+// Returns the most specific node that was hit
+function hitTestNode(
+  node:      DFNode,
+  layoutMap: LayoutMap,
+  x:         number,
+  y:         number
+): DFNode | null {
+  // Get the layout rectangle for this node
+  const rect = layoutMap.get(node.id)
+
+  // If no layout rect — node has not been laid out yet
+  if (!rect) return null
+
+  // If point is not inside this node — skip entirely
+  if (!containsPoint(rect, x, y)) return null
+
+  // Check children first — deepest match wins
+  // Children are rendered on top of parents
+  for (let i = node.children.length - 1; i >= 0; i--) {
+    const child = node.children[i]
+    if (!child) continue
+
+    const childHit = hitTestNode(child, layoutMap, x, y)
+
+    // Found a matching child — return it
+    if (childHit) return childHit
+  }
+
+  // No child matched — this node itself is the target
+  return node
+}
+
+// Entry point for hit testing
+// Takes the full tree, layout map, and event
+// Sets event.targetId to the hit node's id
+function hitTest(
+  tree:      DFTree,
+  layoutMap: LayoutMap,
+  event:     DFEvent
+): DFNode | null {
+  const hit = hitTestNode(
+    tree.root,
+    layoutMap,
+    event.x,
+    event.y
+  )
+
+  // Update the event with the target node id
+  if (hit) {
+    event.targetId = hit.id
+  }
+
+  return hit
+}
+
+export type { DFLayoutRect, LayoutMap }
+export { hitTest, hitTestNode, containsPoint }

package/packages/state/src/events/index.ts

@@ -0,0 +1,18 @@
+// index.ts
+// Public door into the events module.
+// Exports everything needed to handle user interactions.
+
+// The clean event object and types
+export * from './event'
+
+// Stage 1 — OS message conversion
+export * from './ingestion'
+
+// Stage 2 — find which node was targeted
+export * from './hittest'
+
+// Stage 3 — bubble event up the tree
+export * from './propagation'
+
+// Stage 4 — deliver to developer callback
+export * from './dispatch'

package/packages/state/src/events/ingestion.ts

@@ -0,0 +1,102 @@
+// ingestion.ts
+// Stage 1 of the event pipeline.
+// Converts raw OS window messages into clean DFEvent objects.
+// Every platform speaks a different language.
+// Ingestion translates them all into one common language.
+
+import {
+  createEvent
+}               from './event'
+import type {
+  DFEvent,
+  DFEventSource
+} from './event'
+
+// Raw event shape from Windows (Win32)
+interface Win32Event {
+  message: number  // e.g. WM_LBUTTONDOWN = 0x0201
+  wParam:  number
+  lParam:  number  // encodes x and y coordinates
+}
+
+// Raw event shape from macOS (Cocoa)
+interface CocoaEvent {
+  type:    number  // NSEventType
+  locationInWindow: { x: number, y: number }
+  keyCode: number
+}
+
+// Raw event shape from mobile (iOS/Android)
+interface TouchEvent {
+  action: string   // 'down', 'up', 'move'
+  x:      number
+  y:      number
+}
+
+// Converts a Windows Win32 message into a DFEvent
+function ingestWin32(raw: Win32Event): DFEvent | null {
+  // Extract x and y from lParam
+  // Low word is x, high word is y
+  const x = raw.lParam & 0xFFFF
+  const y = (raw.lParam >> 16) & 0xFFFF
+
+  // WM_LBUTTONDOWN
+  if (raw.message === 0x0201) {
+    return createEvent('TAP', 'windows', x, y, raw)
+  }
+
+  // WM_LBUTTONDBLCLK
+  if (raw.message === 0x0203) {
+    return createEvent('DOUBLE_TAP', 'windows', x, y, raw)
+  }
+
+  // WM_KEYDOWN
+  if (raw.message === 0x0100) {
+    return createEvent('KEY_DOWN', 'windows', 0, 0, raw)
+  }
+
+  // Unknown message — ignore
+  return null
+}
+
+// Converts a macOS Cocoa event into a DFEvent
+function ingestCocoa(raw: CocoaEvent): DFEvent | null {
+  const x = raw.locationInWindow.x
+  const y = raw.locationInWindow.y
+
+  // NSLeftMouseDown = 1
+  if (raw.type === 1) {
+    return createEvent('TAP', 'macos', x, y, raw)
+  }
+
+  // NSLeftMouseDragged = 6
+  if (raw.type === 6) {
+    return createEvent('DRAG_MOVE', 'macos', x, y, raw)
+  }
+
+  // NSKeyDown = 10
+  if (raw.type === 10) {
+    return createEvent('KEY_DOWN', 'macos', 0, 0, raw)
+  }
+
+  return null
+}
+
+// Converts a mobile touch event into a DFEvent
+function ingestTouch(
+  raw:    TouchEvent,
+  source: DFEventSource
+): DFEvent | null {
+  if (raw.action === 'down') {
+    return createEvent('TAP', source, raw.x, raw.y, raw)
+  }
+
+  if (raw.action === 'move') {
+    return createEvent('DRAG_MOVE', source, raw.x, raw.y, raw)
+  }
+
+  return null
+}
+
+export { ingestWin32, ingestCocoa, ingestTouch }
+export type { Win32Event, CocoaEvent, TouchEvent }