@epoch32/visage 0.0.0-stage → 1.0.0

package/src/signals/signal.ts

@@ -0,0 +1,203 @@
+/**
+ * Visage Core Writable Signal & State Primitives
+ */
+import { batch, currentScope, currentSubscriber, warnedCyclicSubscribers } from "./system";
+import {
+  type IDependency,
+  type ISubscriber,
+  type ReadonlySignal,
+  SIGNAL_BRAND,
+  type SignalOptions,
+  SubscriberState,
+  type WritableSignal
+} from "./types";
+
+export type { SignalOptions };
+
+/**
+ * Core Writable Signal implementation
+ */
+export class Signal<T> implements IDependency {
+  [SIGNAL_BRAND] = true as const;
+  private _value: T;
+  private _subscribers: Set<ISubscriber> = new Set();
+  private _equals: (a: T, b: T) => boolean;
+  version = 0;
+
+  constructor(initialValue: T, equals?: (a: T, b: T) => boolean) {
+    this._value = initialValue;
+    this._equals = equals ?? Object.is;
+  }
+
+  get(): T {
+    if (currentSubscriber !== null && currentSubscriber.state !== SubscriberState.DISPOSED) {
+      this._subscribers.add(currentSubscriber);
+      currentSubscriber.sources.add(this);
+      currentSubscriber.sourceVersions.set(this, this.version);
+    }
+    return this._value;
+  }
+
+  set(newValue: T): void {
+    if (this._equals(this._value, newValue)) {
+      return;
+    }
+
+    if (currentSubscriber !== null && this._subscribers.has(currentSubscriber)) {
+      if (!warnedCyclicSubscribers.has(currentSubscriber)) {
+        warnedCyclicSubscribers.add(currentSubscriber);
+        if (typeof console !== "undefined" && typeof console.warn === "function") {
+          console.warn(
+            `[Visage Reactivity] Cyclic update detected: An active subscriber modified a signal that it depends on. ` +
+              `To read a signal inside an effect/computed without creating a circular dependency, wrap the read in untrack():\n` +
+              `  untrack(() => signal())`
+          );
+        }
+      }
+    }
+
+    this._value = newValue;
+    this.version++;
+    batch(() => {
+      this.notify();
+    });
+  }
+
+  update(fn: (prev: T) => T): void {
+    this.set(fn(this._value));
+  }
+
+  get value(): T {
+    return this.get();
+  }
+
+  set value(val: T) {
+    this.set(val);
+  }
+
+  removeSubscriber(sub: ISubscriber): void {
+    this._subscribers.delete(sub);
+  }
+
+  private notify(): void {
+    if (this._subscribers.size === 0) return;
+
+    const subs = Array.from(this._subscribers);
+    for (const sub of subs) {
+      sub.markDirty(SubscriberState.DIRTY);
+    }
+  }
+}
+
+/**
+ * Factory for creating writable, fine-grained reactive signals.
+ *
+ * Signals are the core primitive of Visage's reactivity. Reading a signal inside
+ * a component JSX body, `computed()`, or `effect()` automatically registers that
+ * computation as a dependent subscriber.
+ *
+ * @example
+ * ```tsx
+ * const count = signal(0);
+ *
+ * // Read value
+ * console.log(count()); // 0
+ * console.log(count.value); // 0
+ *
+ * // Write value
+ * count.set(1);
+ * count(2);
+ * count.update(prev => prev + 1);
+ *
+ * // In JSX
+ * <div>Current count: {count}</div>
+ * ```
+ *
+ * @param initialValue - The initial value stored in the signal
+ * @param optionsOrEquals - Custom equality comparison function or SignalOptions
+ * @returns A writable reactive signal function accessor
+ */
+export function signal<T>(
+  initialValue: T,
+  optionsOrEquals?: ((a: T, b: T) => boolean) | SignalOptions<T>
+): WritableSignal<T> {
+  const equals = typeof optionsOrEquals === "function" ? optionsOrEquals : optionsOrEquals?.equals;
+  const isInternal = typeof optionsOrEquals === "object" ? optionsOrEquals?.internal : false;
+  const customName = typeof optionsOrEquals === "object" ? optionsOrEquals?.name : undefined;
+
+  const s = new Signal(initialValue, equals);
+
+  const accessor = ((...args: [value?: T]): T => {
+    if (args.length === 0) {
+      return s.get();
+    }
+    s.set(args[0] as T);
+    return args[0] as T;
+  }) as WritableSignal<T>;
+
+  Object.defineProperties(accessor, {
+    [SIGNAL_BRAND]: { value: true },
+    get: { value: () => s.get() },
+    set: { value: (v: T) => s.set(v) },
+    update: { value: (fn: (prev: T) => T) => s.update(fn) },
+    value: {
+      get: () => s.get(),
+      set: (v: T) => s.set(v)
+    }
+  });
+
+  if (!isInternal && typeof window !== "undefined" && (window as any).__VISAGE_DEVTOOLS__) {
+    const devtools = (window as any).__VISAGE_DEVTOOLS__;
+    const sigId = devtools.registerSignal({
+      name: customName,
+      type: "signal",
+      getValue: () => s.get(),
+      version: () => s.version,
+      subscribersCount: () => (s as any)._subscribers?.size ?? 0,
+      dependents: () =>
+        Array.from((s as any)._subscribers ?? [])
+          .map((sub: any) => sub._devId)
+          .filter(Boolean)
+    });
+    (s as any)._devId = sigId;
+    if (currentScope) {
+      currentScope.addCleanup(() => {
+        devtools.unregisterSignal(sigId);
+      });
+    }
+  }
+
+  return accessor;
+}
+
+/**
+ * Tuple-based signal constructor returning `[getter, setter]` (Solid / Preact Signals convention).
+ *
+ * @example
+ * ```tsx
+ * const [count, setCount] = createSignal(0);
+ *
+ * setCount(5);
+ * setCount(prev => prev + 1);
+ *
+ * <div>Count: {count}</div>
+ * ```
+ *
+ * @param initialValue - The initial value stored in the signal
+ * @param optionsOrEquals - Custom equality comparison function or SignalOptions
+ * @returns A tuple containing `[ReadonlySignal<T>, (value: T | ((prev: T) => T)) => void]`
+ */
+export function createSignal<T>(
+  initialValue: T,
+  optionsOrEquals?: ((a: T, b: T) => boolean) | SignalOptions<T>
+): [ReadonlySignal<T>, (value: T | ((prev: T) => T)) => void] {
+  const s = signal(initialValue, optionsOrEquals);
+  const setter = (value: T | ((prev: T) => T)) => {
+    if (typeof value === "function") {
+      s.update(value as (prev: T) => T);
+    } else {
+      s.set(value);
+    }
+  };
+  return [s, setter];
+}

package/src/signals/store.ts

@@ -0,0 +1,163 @@
+import { Signal } from "./signal";
+import { batch } from "./system";
+import { isSignal } from "./types";
+
+const STORE_RAW = Symbol("visage.store.raw");
+const STORE_SIGNALS = Symbol("visage.store.signals");
+const STORE_PROXY = Symbol("visage.store.proxy");
+
+export type Store<T> = T;
+
+function isObject(val: unknown): val is Record<string | symbol, any> {
+  return (
+    typeof val === "object" &&
+    val !== null &&
+    (typeof Node === "undefined" || !(val instanceof Node)) &&
+    !isSignal(val)
+  );
+}
+
+function getOrCreatePropertySignal(target: any, prop: string | symbol): Signal<any> {
+  let signalsMap: Map<string | symbol, Signal<any>> = target[STORE_SIGNALS];
+  if (!signalsMap) {
+    signalsMap = new Map();
+    Object.defineProperty(target, STORE_SIGNALS, {
+      value: signalsMap,
+      enumerable: false,
+      writable: true
+    });
+  }
+
+  let sig = signalsMap.get(prop);
+  if (!sig) {
+    sig = new Signal(target[prop]);
+    signalsMap.set(prop, sig);
+  }
+  return sig;
+}
+
+function createStoreProxy<T extends object>(target: T): T {
+  if (!isObject(target)) return target;
+  if ((target as any)[STORE_PROXY]) return (target as any)[STORE_PROXY];
+
+  const proxy = new Proxy(target, {
+    get(target, prop, receiver) {
+      if (prop === STORE_RAW) return target;
+      if (prop === STORE_PROXY) return proxy;
+
+      // Track property access
+      if (typeof prop === "string" || typeof prop === "symbol") {
+        const sig = getOrCreatePropertySignal(target, prop);
+        sig.get(); // Register dependency
+      }
+
+      const value = Reflect.get(target, prop, receiver);
+
+      // Lazily wrap nested objects in proxy
+      if (isObject(value)) {
+        return createStoreProxy(value);
+      }
+
+      return value;
+    },
+
+    set(target, prop, value, receiver) {
+      const prevValue = Reflect.get(target, prop, receiver);
+      if (Object.is(prevValue, value)) {
+        return true;
+      }
+
+      const success = Reflect.set(target, prop, value, receiver);
+      if (success) {
+        const sig = getOrCreatePropertySignal(target, prop);
+        sig.set(value);
+
+        // If array length or property keys changed, notify length/keys
+        if (Array.isArray(target) && prop !== "length") {
+          const lenSig = getOrCreatePropertySignal(target, "length");
+          lenSig.set(target.length);
+        }
+      }
+      return success;
+    },
+
+    deleteProperty(target, prop) {
+      const hadProp = Reflect.has(target, prop);
+      const success = Reflect.deleteProperty(target, prop);
+      if (hadProp && success) {
+        const sig = getOrCreatePropertySignal(target, prop);
+        sig.set(undefined);
+      }
+      return success;
+    }
+  });
+
+  Object.defineProperty(target, STORE_PROXY, {
+    value: proxy,
+    enumerable: false,
+    writable: true
+  });
+
+  return proxy;
+}
+
+/**
+ * Create a deep reactive proxy store with per-property fine-grained signal tracking.
+ *
+ * Nested objects and arrays are lazily wrapped in reactive proxies. Reading a property
+ * tracks that exact key, and updating a property only notifies computations observing that key.
+ *
+ * @example
+ * ```tsx
+ * const state = createStore({
+ *   user: { name: "Alice", role: "admin" },
+ *   items: ["Apple", "Banana"]
+ * });
+ *
+ * // Fine-grained read
+ * <div>User: {() => state.user.name}</div>
+ *
+ * // Fine-grained write (mutates only user.name subscribers)
+ * state.user.name = "Bob";
+ * state.items.push("Cherry");
+ * ```
+ *
+ * @param initialState - An object or array representing the initial state tree
+ * @returns A deeply reactive proxy store
+ */
+export function createStore<T extends object>(initialState: T): Store<T> {
+  if (!isObject(initialState)) {
+    throw new Error("createStore requires an object or array as initial state");
+  }
+  return createStoreProxy(initialState);
+}
+
+/**
+ * Mutate a store inside a synchronous batch operation.
+ *
+ * @example
+ * ```tsx
+ * mutateStore(state, (draft) => {
+ *   draft.user.name = "Charlie";
+ *   draft.user.role = "user";
+ * });
+ * ```
+ */
+export function mutateStore<T extends object>(store: Store<T>, mutator: (draft: T) => void): void {
+  batch(() => {
+    mutator(store);
+  });
+}
+
+/**
+ * Unwrap a reactive proxy store to get the underlying raw, un-proxied JavaScript object.
+ *
+ * @param store - The reactive store proxy
+ * @returns The raw underlying object
+ */
+export function unwrapStore<T>(store: T): T {
+  if (isObject(store) && (store as any)[STORE_RAW]) {
+    return (store as any)[STORE_RAW];
+  }
+  return store;
+}

package/src/signals/system.ts

@@ -0,0 +1,124 @@
+/**
+ * Visage Reactivity System Execution Context & Scheduler
+ */
+import { type ISubscriber, SubscriberState } from "./types";
+
+export let currentSubscriber: ISubscriber | null = null;
+export let currentScope: any = null;
+export let batchDepth = 0;
+export const pendingEffects: Set<any> = new Set();
+export const warnedCyclicSubscribers: WeakSet<ISubscriber> = new WeakSet();
+export let isFlushing = false;
+
+export function setCurrentSubscriber(sub: ISubscriber | null): void {
+  currentSubscriber = sub;
+}
+
+export function getCurrentSubscriber(): ISubscriber | null {
+  return currentSubscriber;
+}
+
+export function setCurrentScope(scope: any): void {
+  currentScope = scope;
+}
+
+export function getCurrentScope(): any {
+  return currentScope;
+}
+
+export function addPendingEffect(eff: any): void {
+  pendingEffects.add(eff);
+}
+
+export function removePendingEffect(eff: any): void {
+  pendingEffects.delete(eff);
+}
+
+const MAX_FLUSH_COUNT = 100;
+
+export function flushEffects(): void {
+  if (isFlushing || batchDepth > 0) return;
+  isFlushing = true;
+  let iterations = 0;
+  try {
+    while (pendingEffects.size > 0) {
+      if (++iterations > MAX_FLUSH_COUNT) {
+        pendingEffects.clear();
+        throw new Error(
+          `[Visage Reactivity] Maximum update depth exceeded (${MAX_FLUSH_COUNT} cycles). ` +
+            `An effect continuously triggered state mutations (infinite loop detected). ` +
+            `Ensure effects that modify signals do not unconditionally depend on them, or use untrack() to read state.`
+        );
+      }
+      const effectsToRun = Array.from(pendingEffects);
+      pendingEffects.clear();
+
+      for (const eff of effectsToRun) {
+        if (eff.state === SubscriberState.DIRTY || eff.state === SubscriberState.CHECK_DIRTY) {
+          eff.run();
+        }
+      }
+    }
+  } finally {
+    isFlushing = false;
+  }
+}
+
+/**
+ * Batch multiple signal mutations so downstreams and effects update synchronously once at completion.
+ *
+ * Prevents intermediate flicker, wasted recomputations, and glitch states.
+ *
+ * @example
+ * ```tsx
+ * const firstName = signal("Jane");
+ * const lastName = signal("Doe");
+ *
+ * batch(() => {
+ *   firstName.set("John");
+ *   lastName.set("Smith");
+ *   // Downstream computed and effects run only ONCE here
+ * });
+ * ```
+ *
+ * @param fn - A function performing multiple signal updates
+ * @returns The return value of `fn`
+ */
+export function batch<T>(fn: () => T): T {
+  batchDepth++;
+  try {
+    return fn();
+  } finally {
+    batchDepth--;
+    if (batchDepth === 0) {
+      flushEffects();
+    }
+  }
+}
+
+/**
+ * Read reactive state without subscribing the current active effect or computed computation.
+ *
+ * @example
+ * ```tsx
+ * effect(() => {
+ *   const id = currentId(); // Subscribed: effect re-runs when currentId changes
+ *
+ *   // Not subscribed: effect does NOT re-run when analyticsCounter changes
+ *   const count = untrack(() => analyticsCounter());
+ *   sendMetric(id, count);
+ * });
+ * ```
+ *
+ * @param fn - A function reading reactive signals without tracking
+ * @returns The return value of `fn`
+ */
+export function untrack<T>(fn: () => T): T {
+  const prev = currentSubscriber;
+  currentSubscriber = null;
+  try {
+    return fn();
+  } finally {
+    currentSubscriber = prev;
+  }
+}

package/src/signals/types.ts

@@ -0,0 +1,64 @@
+/**
+ * Visage Fine-Grained Reactive Engine Type Definitions
+ */
+
+export type CleanupFn = () => void;
+
+// State flags for subscriber status
+export enum SubscriberState {
+  CLEAN = 0,
+  CHECK_DIRTY = 1,
+  DIRTY = 2,
+  DISPOSED = 3
+}
+
+export const SIGNAL_BRAND = Symbol("visage.signal");
+export const COMPUTED_BRAND = Symbol("visage.computed");
+
+export interface ReadonlySignal<T> {
+  get(): T;
+  readonly value: T;
+  (): T;
+  readonly [SIGNAL_BRAND]: true;
+}
+
+export interface WritableSignal<T> extends ReadonlySignal<T> {
+  set(value: T): void;
+  update(fn: (prev: T) => T): void;
+  (value?: T): T;
+  value: T;
+}
+
+export interface SignalOptions<T> {
+  name?: string;
+  equals?: (a: T, b: T) => boolean;
+  internal?: boolean;
+}
+
+export interface ComputedOptions {
+  name?: string;
+  internal?: boolean;
+}
+
+/**
+ * Check if a value is a Visage signal or computed
+ */
+export function isSignal<T = unknown>(value: unknown): value is ReadonlySignal<T> {
+  return typeof value === "function" && (SIGNAL_BRAND in value || COMPUTED_BRAND in value);
+}
+
+export interface ISubscriber {
+  state: SubscriberState;
+  sources: Set<IDependency>;
+  sourceVersions: Map<IDependency, number>;
+  markDirty(targetState?: SubscriberState): void;
+  dispose(): void;
+}
+
+export interface IDependency {
+  version: number;
+  removeSubscriber(sub: ISubscriber): void;
+}
+
+export type Subscriber = ISubscriber;
+export type Dependency = IDependency;

package/src/style/component.tsx

@@ -0,0 +1,122 @@
+import type { Child } from "../dom/render";
+import { effect, onCleanup } from "../signals";
+import { objectToCSS, type StyleDefinition } from "./create-style";
+import { getScopeId } from "./hash";
+import { styleManager } from "./manager";
+import { scopeCSS } from "./parser";
+
+export interface StyleProps {
+  children?: string | StyleDefinition | (() => string | StyleDefinition);
+  classes?: StyleDefinition | (() => StyleDefinition);
+  passToChildren?: boolean;
+  id?: string;
+}
+
+/**
+ * Scoped Component Style Block
+ *
+ * Automatically hashes and scopes CSS rules to the parent component/container,
+ * preventing style leaks and collisions. Supports CSS strings or JavaScript style objects.
+ *
+ * Examples:
+ *
+ * 1. Object syntax:
+ * ```tsx
+ * export function Card(props) {
+ *   return (
+ *     <div class="card">
+ *       <h2>{props.title}</h2>
+ *       <Style classes={{
+ *         card: { background: "var(--card-bg)", padding: "20px", borderRadius: "8px" },
+ *         "& h2": { fontSize: "1.2rem", color: "var(--text)" }
+ *       }} />
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * 2. Component Scoped CSS string:
+ * ```tsx
+ * export function StepItem(props) {
+ *   return (
+ *     <div class="step-node">
+ *       <span class="step-num">{props.step}</span>
+ *       <span>{props.title}</span>
+ *
+ *       <Style>{`
+ *         .step-node { display: flex; align-items: center; gap: 8px; }
+ *         .step-num { font-weight: 600; color: var(--primary); }
+ *       `}</Style>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export function Style(props: StyleProps): Child {
+  const getRawCSS = (): string => {
+    if (props.classes) {
+      const cls = typeof props.classes === "function" ? props.classes() : props.classes;
+      return objectToCSS(cls);
+    }
+    if (props.children) {
+      const ch = typeof props.children === "function" ? props.children() : props.children;
+      return typeof ch === "object" ? objectToCSS(ch) : ch;
+    }
+    return "";
+  };
+
+  const rawCSS = getRawCSS();
+  const scopeId = props.id ?? getScopeId(rawCSS);
+  const scopeAttr = `data-${scopeId}`;
+
+  // In browser, create a marker node to locate parent element and tag it
+  if (typeof document !== "undefined") {
+    const marker = document.createTextNode("");
+    let unsubscribe: (() => void) | null = null;
+
+    effect(() => {
+      const currentCSS = getRawCSS();
+      const currentScopeId = props.id ?? getScopeId(currentCSS);
+      const scoped = scopeCSS(currentCSS, {
+        scopeId: currentScopeId,
+        passToChildren: props.passToChildren ?? true
+      });
+
+      if (unsubscribe) {
+        unsubscribe();
+      }
+      unsubscribe = styleManager.inject(currentScopeId, scoped);
+
+      // Attach data-v-xyz attribute to parent container
+      const attachScope = () => {
+        const parent = (marker.parentElement || marker.parentNode) as HTMLElement | null;
+        if (parent && typeof parent.setAttribute === "function") {
+          parent.setAttribute(`data-${currentScopeId}`, "");
+        }
+      };
+      attachScope();
+      queueMicrotask(attachScope);
+    });
+
+    onCleanup(() => {
+      if (unsubscribe) {
+        unsubscribe();
+      }
+      const parent = (marker.parentElement || marker.parentNode) as HTMLElement | null;
+      if (parent && typeof parent.removeAttribute === "function") {
+        parent.removeAttribute(scopeAttr);
+      }
+    });
+
+    return marker;
+  }
+
+  // SSR environment: inject CSS into SSR registry
+  const scoped = scopeCSS(rawCSS, {
+    scopeId,
+    passToChildren: props.passToChildren ?? true
+  });
+  styleManager.inject(scopeId, scoped);
+
+  return null;
+}