deskforge 1.0.0

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

@@ -0,0 +1,83 @@
+// propagation.ts
+// Stage 3 of the event pipeline.
+// After hit testing finds the target node —
+// the event bubbles UP through the tree.
+// Parent components can intercept or react to child events.
+// A handler can call stopPropagation() to prevent bubbling.
+
+import type { DFNode, DFTree } from '@deskforge/core'
+import type { DFEvent } from './event'
+
+// A handler function attached to a node
+// Returns true if it handled the event
+type EventHandler = (event: DFEvent) => boolean | void
+
+// Map of node IDs to their event handlers
+// Populated when components declare onClick, onTap etc.
+type HandlerMap = Map<string, EventHandler>
+
+// Builds the path from target node up to root
+// Used to know which nodes to visit during bubbling
+function buildBubblePath(
+  tree:     DFTree,
+  targetId: string
+): DFNode[] {
+  const path: DFNode[] = []
+
+  // Recursive search that builds path from root to target
+  function search(node: DFNode): boolean {
+    // Found the target node
+    if (node.id === targetId) {
+      path.push(node)
+      return true
+    }
+
+    // Search children
+    for (const child of node.children) {
+      if (search(child)) {
+        // Child found target — add this node to path too
+        path.push(node)
+        return true
+      }
+    }
+
+    return false
+  }
+
+  search(tree.root)
+
+  // Path is currently root-to-target — reverse for bubbling
+  // Bubbling goes target → parent → grandparent → root
+  return path.reverse()
+}
+
+// Propagates event from target up through ancestors
+// Calls handler on each node in the bubble path
+// Stops if event.stopped becomes true
+function propagate(
+  tree:       DFTree,
+  event:      DFEvent,
+  handlerMap: HandlerMap
+): void {
+  // Cannot propagate without a target
+  if (!event.targetId) return
+
+  // Build the path from target to root
+  const bubblePath = buildBubblePath(tree, event.targetId)
+
+  // Walk up the path calling handlers
+  for (const node of bubblePath) {
+    // Stop if a previous handler stopped propagation
+    if (event.stopped) break
+
+    // Get the handler for this node if any
+    const handler = handlerMap.get(node.id)
+
+    if (handler) {
+      handler(event)
+    }
+  }
+}
+
+export type { EventHandler, HandlerMap }
+export { propagate, buildBubblePath }

package/packages/state/src/index.ts

@@ -0,0 +1,32 @@
+
+
+// index.ts
+// Public door into the state package.
+// All other packages import from here.
+
+// Core reactive state
+export * from './state'
+
+// Derived values
+export * from './computed'
+
+// Reactive side effects
+export * from './watch'
+
+// Lifecycle side effects
+export * from './effect'
+
+// Stable non-reactive references
+export * from './ref'
+
+// Global app-wide state
+export * from './store'
+
+// Shared state across component tree
+export * from './context'
+
+// Shared event primitives used by UI components
+export * from './events'
+
+// Complex state with named actions
+export * from './reducer'

package/packages/state/src/reducer.ts

@@ -0,0 +1,87 @@
+// reducer.ts
+// Complex state management with named actions.
+// Similar to Redux but simpler — no boilerplate.
+// Mutate state directly inside actions.
+
+import { State } from './state'
+import { createScheduler } from '@deskforge/core'
+
+// Shape of one action handler
+// Receives current state and optional payload
+type ReducerAction<T> = (
+  state:    T,
+  payload?: unknown
+) => void
+
+// Map of action names to handler functions
+type ReducerActions<T> = {
+  [key: string]: ReducerAction<T>
+}
+
+// Configuration passed to Reducer()
+interface ReducerConfig<T extends Record<string, unknown>> {
+  state:   T                  // initial state
+  actions: ReducerActions<T>  // named action handlers
+}
+
+// The object returned by Reducer()
+interface DFReducer<T extends Record<string, unknown>> {
+  state:    T       // reactive state — read directly
+  dispatch: (       // call a named action
+    action:   string,
+    payload?: unknown
+  ) => void
+  reset:    () => void // resets to initial state
+}
+
+// Creates a reducer with named actions
+// State is reactive — UI updates when actions run
+// Actions receive state directly — mutate it freely
+function Reducer<T extends Record<string, unknown>>(
+  config: ReducerConfig<T>
+): DFReducer<T> {
+  // Each reducer gets its own scheduler
+  const scheduler = createScheduler()
+
+  // Create reactive state
+  const reactiveState = State(
+    { ...config.state },
+    scheduler
+  )
+
+  // Snapshot of initial state for reset
+  const initialState = { ...config.state }
+
+  // Calls a named action with optional payload
+  function dispatch(action: string, payload?: unknown): void {
+    const actionFn = config.actions[action]
+
+    if (!actionFn) {
+      console.error(
+        `DeskForge Reducer: unknown action "${action}"`
+      )
+      return
+    }
+
+    // Pass reactive state directly to action
+    // Action mutates it — Proxy handles re-renders
+    actionFn(reactiveState, payload)
+  }
+
+  // Resets all values back to initial state
+  function reset(): void {
+    Object.keys(initialState).forEach(key => {
+      (reactiveState as Record<string, unknown>)[key] =
+        initialState[key]
+    })
+  }
+
+  return {
+    state:    reactiveState,
+    dispatch,
+    reset
+  }
+}
+
+export type { DFReducer, ReducerConfig, ReducerActions }
+export { Reducer }

package/packages/state/src/ref.ts

@@ -0,0 +1,41 @@
+// ref.ts
+// A Ref holds a stable value that persists across renders.
+// Changing ref.value NEVER triggers a re-render.
+// Use for timers, element references, previous values.
+
+// Represents a stable reference container
+// T is the type of value being held
+interface DFRef<T> {
+  value:          T  // readable and writable — never re-renders
+  readonly initial: T  // original value — never changes
+}
+
+// Creates a stable non-reactive reference
+// NO Proxy. NO tracking. NO subscriber notification.
+function Ref<T>(initialValue: T): DFRef<T> {
+  // Plain variable — changing this notifies nobody
+  let current: T = initialValue
+
+  return {
+    // Returns current value
+    get value(): T {
+      return current
+    },
+    // Updates current value — no re-render triggered
+    set value(newValue: T) {
+      current = newValue
+    },
+    // Always returns the original starting value
+    get initial(): T {
+      return initialValue
+    }
+  }
+}
+
+// Resets ref back to its original initial value
+function resetRef<T>(ref: DFRef<T>): void {
+  ref.value = ref.initial
+}
+
+export type { DFRef }
+export { Ref, resetRef }

package/packages/state/src/state.ts

@@ -0,0 +1,97 @@
+// state.ts
+// The reactive state system for DeskForge.
+// Uses JavaScript Proxy to intercept reads and writes.
+// When you read state — your component is registered as a watcher.
+// When you write state — all watchers are notified and re-render.
+
+import { schedule, createScheduler } from '@deskforge/core'
+import type { Scheduler } from '@deskforge/core'
+
+// A string key on the state object e.g. "count" or "notes"
+type StateKey = string
+
+// A function that re-renders a component when called
+type Subscriber = () => void
+
+// Maps each state key to all components watching it
+// e.g. "count" → [ComponentA, ComponentB]
+type SubscriberMap = Map<StateKey, Set<Subscriber>>
+
+// The currently rendering component
+// Any state reads while this is set register as subscribers
+let activeSubscriber: Subscriber | null = null
+
+// Sets the active subscriber during component rendering
+function setActiveSubscriber(sub: Subscriber | null): void {
+  activeSubscriber = sub
+}
+
+// Creates a reactive state object from an initial value
+// Mutate properties directly — UI updates automatically
+// Uses JavaScript Proxy to intercept reads and writes
+
+function State<T extends Record<string, unknown>>(
+  initialValue: T,
+  scheduler?:   Scheduler
+): T {
+  // Create a default scheduler if not provided
+  const finalScheduler = scheduler || createScheduler()
+  // Maps each key to the set of components watching it
+  const subscribers: SubscriberMap = new Map()
+
+  // Gets or creates the subscriber set for a key
+  function getSubscribers(key: StateKey): Set<Subscriber> {
+    if (!subscribers.has(key)) {
+      subscribers.set(key, new Set())
+    }
+    return subscribers.get(key)!
+  }
+
+  // Wrap the state object in a Proxy
+  const proxy = new Proxy(initialValue, {
+
+    // Intercepts every READ of state
+    // If a component is rendering — register it as subscriber
+    get(target, key: string) {
+      if (activeSubscriber !== null) {
+        getSubscribers(key).add(activeSubscriber)
+      }
+      return target[key]
+    },
+
+    // Intercepts every WRITE to state
+    // Notifies all subscribers via scheduler
+    set(target, key: string, value: unknown) {
+      const oldValue = target[key]
+
+      // Skip if value did not actually change
+      if (oldValue === value) return true
+
+      // Update the value
+      target[key as keyof T] = value as T[keyof T]
+
+      // Notify all watchers — batched via scheduler
+      getSubscribers(key).forEach(subscriber => {
+        schedule(finalScheduler, subscriber)
+      })
+
+      return true
+    }
+  })
+
+  return proxy as T
+}
+
+// Tracks which state keys a component reads during render
+// Registers component as subscriber for those keys
+function track(
+  subscriber: Subscriber,
+  fn:         () => void
+): void {
+  setActiveSubscriber(subscriber)
+  fn()
+  setActiveSubscriber(null)
+}
+
+export type { Subscriber, SubscriberMap }
+export { State, track, setActiveSubscriber }

package/packages/state/src/store.ts

@@ -0,0 +1,79 @@
+// store.ts
+// Global app-wide reactive state.
+// Accessible from any component without prop drilling.
+// Supports named actions and optional persistence to disk.
+
+import { State, track } from './state'
+import { createScheduler } from '@deskforge/core'
+
+// The shape of actions object passed to Store()
+// Each action receives state and an optional payload
+type Actions<T> = {
+  [key: string]: (state: T, payload?: unknown) => void
+}
+
+// Configuration passed to Store()
+interface StoreConfig<T extends Record<string, unknown>> {
+  state:      T            // initial state values
+  actions:    Actions<T>   // named functions that modify state
+  persist?:   boolean      // save to disk and restore on startup
+  persistKey?: string      // key used for persistence storage
+}
+
+// The object returned by Store()
+interface DFStore<T extends Record<string, unknown>> {
+  state:    T              // reactive state — read directly
+  dispatch: (             // call a named action
+    action:  string,
+    payload?: unknown
+  ) => void
+  reset:    () => void     // resets state to initial values
+}
+
+// Creates a global reactive store
+// State is reactive — components re-render on change
+// Actions are the only way to modify state
+function Store<T extends Record<string, unknown>>(
+  config: StoreConfig<T>
+): DFStore<T> {
+  // Each store gets its own scheduler
+  const scheduler = createScheduler()
+
+  // Create reactive state from initial values
+  const reactiveState = State(
+    { ...config.state },
+    scheduler
+  )
+
+  // Keep a copy of initial state for reset
+  const initialState = { ...config.state }
+
+  // Calls a named action with optional payload
+  function dispatch(action: string, payload?: unknown): void {
+    const actionFn = config.actions[action]
+
+    if (!actionFn) {
+      console.error(`DeskForge Store: unknown action "${action}"`)
+      return
+    }
+
+    actionFn(reactiveState, payload)
+  }
+
+  // Resets all state values back to their initial values
+  function reset(): void {
+    Object.keys(initialState).forEach(key => {
+      (reactiveState as Record<string, unknown>)[key] =
+        initialState[key]
+    })
+  }
+
+  return {
+    state:    reactiveState,
+    dispatch,
+    reset
+  }
+}
+
+export type { DFStore, StoreConfig, Actions }
+export { Store }

package/packages/state/src/watch.ts

@@ -0,0 +1,131 @@
+// watch.ts
+// Watch reacts to specific state value changes.
+// Runs a callback when the watched value changes.
+// Three variants: standard, immediate, once.
+
+import { track } from './state'
+import { schedule } from '@deskforge/core'
+import type { Scheduler } from '@deskforge/core'
+
+// Function that returns the value being watched
+type WatchSource<T> = () => T
+
+// Called when value changes — receives new and old value
+// Can return a cleanup function
+type WatchCallback<T> = (
+  newValue: T,
+  oldValue: T | undefined
+) => void | (() => void)
+
+// Returned by Watch() — lets you stop or trigger manually
+interface WatchHandle {
+  stop():    void // stops watching permanently
+  trigger(): void // manually triggers the callback now
+}
+
+// Internal factory for all three Watch variants
+function createWatch<T>(
+  source:    WatchSource<T>,
+  callback:  WatchCallback<T>,
+  scheduler: Scheduler,
+  options: {
+    immediate: boolean // run callback on load too
+    once:      boolean // run callback exactly one time
+  }
+): WatchHandle {
+  let oldValue:  T | undefined       = undefined
+  let cleanup:   (() => void) | undefined = undefined
+  let isStopped: boolean             = false
+
+  // Runs any cleanup from previous callback
+  function runCleanup(): void {
+    if (cleanup) {
+      cleanup()
+      cleanup = undefined
+    }
+  }
+
+  // Runs when a dependency changes
+  // Compares new value to old — fires callback if different
+  const subscriber = (): void => {
+    if (isStopped) return
+
+    let newValue: T | undefined = undefined
+
+    track(subscriber, () => {
+      newValue = source()
+    })
+
+    if (newValue !== oldValue) {
+      runCleanup()
+
+      const result = callback(newValue as T, oldValue)
+
+      // If callback returned a function — that is cleanup
+      if (typeof result === 'function') {
+        cleanup = result
+      }
+
+      oldValue = newValue
+
+      // Stop after first run if once mode
+      if (options.once) {
+        isStopped = true
+      }
+    }
+  }
+
+  // Initial read to register dependencies
+  track(subscriber, () => {
+    oldValue = source()
+  })
+
+  // If immediate — run callback right away on first load
+  if (options.immediate) {
+    schedule(scheduler, subscriber)
+  }
+
+  return {
+    stop():    void { isStopped = true; runCleanup() },
+    trigger(): void { schedule(scheduler, subscriber) }
+  }
+}
+
+// Standard Watch — runs when value changes
+function Watch<T>(
+  source:    WatchSource<T>,
+  callback:  WatchCallback<T>,
+  scheduler: Scheduler
+): WatchHandle {
+  return createWatch(source, callback, scheduler, {
+    immediate: false,
+    once:      false
+  })
+}
+
+// Runs on load AND on every change after that
+Watch.immediate = function<T>(
+  source:    WatchSource<T>,
+  callback:  WatchCallback<T>,
+  scheduler: Scheduler
+): WatchHandle {
+  return createWatch(source, callback, scheduler, {
+    immediate: true,
+    once:      false
+  })
+}
+
+// Runs exactly one time then stops automatically
+Watch.once = function<T>(
+  source:    WatchSource<T>,
+  callback:  WatchCallback<T>,
+  scheduler: Scheduler
+): WatchHandle {
+  return createWatch(source, callback, scheduler, {
+    immediate: false,
+    once:      true
+  })
+}
+
+export type { WatchHandle, WatchCallback, WatchSource }
+export { Watch }

package/packages/state/test/api.test.js

@@ -0,0 +1,16 @@
+const test = require('node:test')
+const assert = require('node:assert/strict')
+
+const { createEvent, stopPropagation } = require('../dist/index.js')
+
+test('state package exposes DFEvent helpers from the public entrypoint', () => {
+  const event = createEvent('TAP', 'linux', 12, 24, { source: 'test' })
+  assert.strictEqual(event.type, 'TAP')
+  assert.strictEqual(event.source, 'linux')
+  assert.strictEqual(event.x, 12)
+  assert.strictEqual(event.y, 24)
+  assert.strictEqual(event.stopped, false)
+
+  stopPropagation(event)
+  assert.strictEqual(event.stopped, true)
+})

package/packages/state/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "CommonJS",
+    "rootDir": "./src",
+    "outDir": "./dist",
+    "strict": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "skipLibCheck": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/packages/theme/dist/animate.d.ts

@@ -0,0 +1,72 @@
+import type { DFStyle } from './style';
+interface AnimationConfig {
+    duration: number;
+    delay?: number;
+    easing?: string;
+    from: Partial<DFStyle>;
+    to: Partial<DFStyle>;
+    repeat?: number | 'infinite';
+}
+declare function fadeIn(options?: {
+    duration?: number;
+    delay?: number;
+}): AnimationConfig;
+declare function fadeOut(options?: {
+    duration?: number;
+    delay?: number;
+}): AnimationConfig;
+declare function slideUp(options?: {
+    duration?: number;
+    delay?: number;
+    distance?: number;
+}): AnimationConfig;
+declare function slideDown(options?: {
+    duration?: number;
+    delay?: number;
+    distance?: number;
+}): AnimationConfig;
+declare function slideLeft(options?: {
+    duration?: number;
+    delay?: number;
+    distance?: number;
+}): AnimationConfig;
+declare function slideRight(options?: {
+    duration?: number;
+    delay?: number;
+    distance?: number;
+}): AnimationConfig;
+declare function scaleIn(options?: {
+    duration?: number;
+    delay?: number;
+}): AnimationConfig;
+declare function scaleOut(options?: {
+    duration?: number;
+    delay?: number;
+}): AnimationConfig;
+declare function pulse(options?: {
+    duration?: number;
+}): AnimationConfig;
+declare function shake(options?: {
+    duration?: number;
+}): AnimationConfig;
+declare function spin(options?: {
+    duration?: number;
+}): AnimationConfig;
+declare function custom(config: AnimationConfig): AnimationConfig;
+declare const Animate: {
+    fadeIn: typeof fadeIn;
+    fadeOut: typeof fadeOut;
+    slideUp: typeof slideUp;
+    slideDown: typeof slideDown;
+    slideLeft: typeof slideLeft;
+    slideRight: typeof slideRight;
+    scaleIn: typeof scaleIn;
+    scaleOut: typeof scaleOut;
+    pulse: typeof pulse;
+    shake: typeof shake;
+    spin: typeof spin;
+    custom: typeof custom;
+};
+export type { AnimationConfig };
+export { Animate, fadeIn, fadeOut, slideUp, slideDown, slideLeft, slideRight, scaleIn, scaleOut, pulse, shake, spin, custom, };
+//# sourceMappingURL=animate.d.ts.map

package/packages/theme/dist/animate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"animate.d.ts","sourceRoot":"","sources":["../src/animate.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAA;AAGtC,UAAU,eAAe;IACvB,QAAQ,EAAG,MAAM,CAAA;IACjB,KAAK,CAAC,EAAK,MAAM,CAAA;IACjB,MAAM,CAAC,EAAI,MAAM,CAAA;IACjB,IAAI,EAAO,OAAO,CAAC,OAAO,CAAC,CAAA;IAC3B,EAAE,EAAS,OAAO,CAAC,OAAO,CAAC,CAAA;IAC3B,MAAM,CAAC,EAAI,MAAM,GAAG,UAAU,CAAA;CAC/B;AAGD,iBAAS,MAAM,CAAC,OAAO,CAAC,EAAE;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,KAAK,CAAC,EAAK,MAAM,CAAA;CAClB,GAAG,eAAe,CAQlB;AAGD,iBAAS,OAAO,CAAC,OAAO,CAAC,EAAE;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,KAAK,CAAC,EAAK,MAAM,CAAA;CAClB,GAAG,eAAe,CAQlB;AAGD,iBAAS,OAAO,CAAC,OAAO,CAAC,EAAE;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,KAAK,CAAC,EAAK,MAAM,CAAA;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB,GAAG,eAAe,CASlB;AAGD,iBAAS,SAAS,CAAC,OAAO,CAAC,EAAE;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,KAAK,CAAC,EAAK,MAAM,CAAA;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB,GAAG,eAAe,CASlB;AAGD,iBAAS,SAAS,CAAC,OAAO,CAAC,EAAE;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,KAAK,CAAC,EAAK,MAAM,CAAA;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB,GAAG,eAAe,CASlB;AAGD,iBAAS,UAAU,CAAC,OAAO,CAAC,EAAE;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,KAAK,CAAC,EAAK,MAAM,CAAA;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB,GAAG,eAAe,CASlB;AAGD,iBAAS,OAAO,CAAC,OAAO,CAAC,EAAE;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,KAAK,CAAC,EAAK,MAAM,CAAA;CAClB,GAAG,eAAe,CAQlB;AAGD,iBAAS,QAAQ,CAAC,OAAO,CAAC,EAAE;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,KAAK,CAAC,EAAK,MAAM,CAAA;CAClB,GAAG,eAAe,CAQlB;AAGD,iBAAS,KAAK,CAAC,OAAO,CAAC,EAAE;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB,GAAG,eAAe,CAQlB;AAGD,iBAAS,KAAK,CAAC,OAAO,CAAC,EAAE;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB,GAAG,eAAe,CAQlB;AAGD,iBAAS,IAAI,CAAC,OAAO,CAAC,EAAE;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB,GAAG,eAAe,CAQlB;AAGD,iBAAS,MAAM,CAAC,MAAM,EAAE,eAAe,GAAG,eAAe,CAExD;AAGD,QAAA,MAAM,OAAO;;;;;;;;;;;;;CAaZ,CAAA;AAED,YAAY,EAAE,eAAe,EAAE,CAAA;AAC/B,OAAO,EACL,OAAO,EACP,MAAM,EAAE,OAAO,EACf,OAAO,EAAE,SAAS,EAClB,SAAS,EAAE,UAAU,EACrB,OAAO,EAAE,QAAQ,EACjB,KAAK,EAAE,KAAK,EAAE,IAAI,EAClB,MAAM,GACP,CAAA"}