@epoch32/visage 1.0.0 → 1.1.1

package/dist/signals/scope.d.ts

@@ -0,0 +1,61 @@
+import type { CleanupFn, ISubscriber } from "./types";
+/**
+ * Reactive Scope for lifecycle and automatic memory management
+ */
+export declare class Scope {
+    subscribers: Set<ISubscriber>;
+    cleanups: CleanupFn[];
+    parent: Scope | null;
+    isDisposed: boolean;
+    context?: Map<symbol, any>;
+    constructor(parent?: Scope | null);
+    addSubscriber(sub: ISubscriber): void;
+    addCleanup(fn: CleanupFn): void;
+    dispose(): void;
+}
+/**
+ * Register a cleanup callback for the current running effect or active scope.
+ *
+ * Runs automatically when the enclosing component/scope unmounts or before
+ * the effect re-executes.
+ *
+ * @example
+ * ```tsx
+ * function TimerComponent() {
+ *   const id = setInterval(() => console.log("tick"), 1000);
+ *   onCleanup(() => clearInterval(id));
+ *   return <div>Timer running</div>;
+ * }
+ * ```
+ */
+export declare function onCleanup(fn: CleanupFn): void;
+/**
+ * Create an isolated reactive root scope that outlives the current execution context.
+ *
+ * Computations and signals created inside `fn` will not be tied to any parent scope
+ * and will persist until the provided `dispose` callback is invoked.
+ *
+ * @example
+ * ```tsx
+ * const dispose = createRoot((dispose) => {
+ *   const count = signal(0);
+ *   effect(() => console.log(count()));
+ *   return dispose;
+ * });
+ *
+ * // Later, dispose of all memory & subscribers
+ * dispose();
+ * ```
+ *
+ * @param fn - A factory function receiving the `dispose` callback
+ * @returns The return value of `fn`
+ */
+export declare function createRoot<T>(fn: (dispose: () => void) => T): T;
+/**
+ * Run a function with a specified reactive scope active.
+ */
+export declare function runInScope<T>(scope: Scope | null, fn: () => T): T;
+/**
+ * Get the currently active reactive scope.
+ */
+export declare function getActiveScope(): Scope | null;

package/dist/signals/signal.d.ts

@@ -0,0 +1,40 @@
+import { type IDependency, type ISubscriber, type ReadonlySignal, SIGNAL_BRAND, type SignalOptions, type WritableSignal } from "./types";
+export type { SignalOptions };
+/**
+ * Core Writable Signal implementation
+ */
+export declare class Signal<T> implements IDependency {
+    [SIGNAL_BRAND]: true;
+    private _value;
+    private _subscribers;
+    private _equals;
+    private _onSet?;
+    version: number;
+    constructor(initialValue: T, equals?: (a: T, b: T) => boolean, onSet?: (val: T) => void);
+    get(): T;
+    set(newValue: T): void;
+    update(fn: (prev: T) => T): void;
+    get value(): T;
+    set value(val: T);
+    removeSubscriber(sub: ISubscriber): void;
+    private notify;
+}
+export declare function signal<T>(initialValue: T, optionsOrEquals?: ((a: T, b: T) => boolean) | SignalOptions<T>): WritableSignal<T>;
+/**
+ * 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 declare function createSignal<T>(initialValue: T, optionsOrEquals?: ((a: T, b: T) => boolean) | SignalOptions<T>): [ReadonlySignal<T>, (value: T | ((prev: T) => T)) => void];

package/dist/signals/store.d.ts

@@ -0,0 +1,45 @@
+export type Store<T> = T;
+/**
+ * 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 declare function createStore<T extends object>(initialState: T): Store<T>;
+/**
+ * Mutate a store inside a synchronous batch operation.
+ *
+ * @example
+ * ```tsx
+ * mutateStore(state, (draft) => {
+ *   draft.user.name = "Charlie";
+ *   draft.user.role = "user";
+ * });
+ * ```
+ */
+export declare function mutateStore<T extends object>(store: Store<T>, mutator: (draft: T) => void): void;
+/**
+ * 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 declare function unwrapStore<T>(store: T): T;

package/dist/signals/system.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Visage Reactivity System Execution Context & Scheduler
+ */
+import { type ISubscriber } from "./types";
+export declare let currentSubscriber: ISubscriber | null;
+export declare let currentScope: any;
+export declare let batchDepth: number;
+export declare const pendingEffects: Set<any>;
+export declare const warnedCyclicSubscribers: WeakSet<ISubscriber>;
+export declare let isFlushing: boolean;
+export declare function setCurrentSubscriber(sub: ISubscriber | null): void;
+export declare function getCurrentSubscriber(): ISubscriber | null;
+export declare function setCurrentScope(scope: any): void;
+export declare function getCurrentScope(): any;
+export declare function addPendingEffect(eff: any): void;
+export declare function removePendingEffect(eff: any): void;
+export declare function flushEffects(): void;
+/**
+ * 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 declare function batch<T>(fn: () => T): T;
+/**
+ * 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 declare function untrack<T>(fn: () => T): T;

package/dist/signals/types.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Visage Fine-Grained Reactive Engine Type Definitions
+ */
+export type CleanupFn = () => void;
+export declare enum SubscriberState {
+    CLEAN = 0,
+    CHECK_DIRTY = 1,
+    DIRTY = 2,
+    DISPOSED = 3
+}
+export declare const SIGNAL_BRAND: unique symbol;
+export declare const COMPUTED_BRAND: unique symbol;
+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 PersistOptions<T> {
+    key: string;
+    storage?: "local" | "session" | Storage;
+    serialize?: (value: T) => string;
+    deserialize?: (raw: string) => T;
+    syncTabs?: boolean;
+}
+export interface SignalOptions<T> {
+    name?: string;
+    equals?: (a: T, b: T) => boolean;
+    internal?: boolean;
+    persist?: string | PersistOptions<T>;
+}
+export interface ComputedOptions {
+    name?: string;
+    internal?: boolean;
+}
+/**
+ * Check if a value is a Visage signal or computed
+ */
+export declare function isSignal<T = unknown>(value: unknown): value is ReadonlySignal<T>;
+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/dist/style/component.d.ts

@@ -0,0 +1,49 @@
+import type { Child } from "../dom/render";
+import { type StyleDefinition } from "./create-style";
+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 declare function Style(props: StyleProps): Child;

package/dist/style/create-style.d.ts

@@ -0,0 +1,63 @@
+import type * as CSS from "csstype";
+import { type ClassValue } from "./cx";
+/**
+ * Standard CSS Properties interface with full TypeScript & VS Code IntelliSense,
+ * supporting nested pseudo-classes, descendant selectors, and custom CSS variables.
+ */
+export type CSSProperties = CSS.Properties<string | number> & {
+    [key: `&${string}`]: CSSProperties | undefined;
+    [key: `.${string}`]: CSSProperties | undefined;
+    [key: `:${string}`]: CSSProperties | undefined;
+    [key: `@media${string}`]: CSSProperties | undefined;
+    [key: `@keyframes${string}`]: Record<string, CSSProperties> | undefined;
+    [key: `${number}%`]: CSSProperties | undefined;
+    from?: CSSProperties;
+    to?: CSSProperties;
+    [customProp: `--${string}`]: string | number | undefined;
+};
+export type StyleDefinition = Record<string, CSSProperties>;
+export type StyleClasses<T extends string = string> = {
+    [K in T]: string;
+} & Record<string, any> & {
+    scope: string;
+    scopeAttr: string;
+    css: string;
+    cx: (...args: ClassValue[]) => string;
+};
+/**
+ * Convert a JavaScript object style dictionary into standard CSS
+ */
+export declare function objectToCSS(classes: Record<string, any>): string;
+/**
+ * Define scoped CSS styles with type-safe class name mappings
+ *
+ * Supports tagged template literals, string CSS, or JavaScript style objects:
+ *
+ * 1. Object syntax with full VS Code CSS IntelliSense:
+ * ```tsx
+ * const styles = createStyle({
+ *   card: { background: "var(--card-bg)", padding: "16px", display: "flex" },
+ *   button: { background: "var(--primary)", "&:hover": { background: "var(--primary-hover)" } }
+ * });
+ * ```
+ *
+ * 2. Tagged template literal syntax:
+ * ```tsx
+ * const styles = createStyle`
+ *   .card { padding: 16px; border-radius: 8px; }
+ *   .active { color: var(--primary); }
+ * `;
+ * ```
+ */
+export declare function createStyle<T extends string = string>(templateOrObject: string | TemplateStringsArray | StyleDefinition, ...valuesOrOptions: any[]): StyleClasses<T>;
+/**
+ * Tagged template for defining a single scoped CSS class
+ */
+export declare function css(strings: TemplateStringsArray, ...values: any[]): string;
+/**
+ * Hook to inject dynamic or component-level CSS with automatic cleanup
+ */
+export declare function useStyle(cssInput: string | StyleDefinition | (() => string | StyleDefinition), options?: {
+    passToChildren?: boolean;
+    id?: string;
+}): string;

package/dist/style/cx.d.ts

@@ -0,0 +1,18 @@
+export type ClassValue = string | number | boolean | null | undefined | (() => any) | ClassValue[] | Record<string, any>;
+/**
+ * Check if a class value tree contains any reactive signal or function getters
+ */
+export declare function hasReactiveClass(val: any): boolean;
+/**
+ * Normalize dynamic classes from strings, numbers, arrays, and objects
+ */
+export declare function normalizeClass(val: any): string;
+/**
+ * Flexible classnames utility for combining conditional classes
+ *
+ * Example:
+ * ```ts
+ * cx("btn", { active: isActive(), disabled: !isEnabled() }, ["extra-1", extraClass])
+ * ```
+ */
+export declare function cx(...args: ClassValue[]): string;

package/dist/style/hash.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Fast 32-bit FNV-1a deterministic string hashing algorithm
+ */
+export declare function hashString(str: string): string;
+/**
+ * Generate a deterministic scope identifier for CSS blocks
+ */
+export declare function getScopeId(css: string, prefix?: string): string;

package/dist/style/index.d.ts

@@ -0,0 +1,8 @@
+export * from "./component";
+export * from "./create-style";
+export * from "./cx";
+export * from "./hash";
+export * from "./layout";
+export * from "./manager";
+export * from "./parser";
+export * from "./scale";

package/dist/{src/style → style}/index.js

@@ -848,10 +848,12 @@ class Signal {
   _value;
   _subscribers = new Set;
   _equals;
+  _onSet;
   version = 0;
-  constructor(initialValue, equals) {
+  constructor(initialValue, equals, onSet) {
     this._value = initialValue;
     this._equals = equals ?? Object.is;
+    this._onSet = onSet;
   }
   get() {
     if (currentSubscriber !== null && currentSubscriber.state !== 3 /* DISPOSED */) {
@@ -876,6 +878,9 @@ class Signal {
     }
     this._value = newValue;
     this.version++;
+    if (this._onSet) {
+      this._onSet(newValue);
+    }
     batch(() => {
       this.notify();
     });
@@ -901,11 +906,91 @@ class Signal {
     }
   }
 }
+function resolveStorage(storageOption) {
+  if (storageOption && typeof storageOption === "object") {
+    return storageOption;
+  }
+  if (storageOption === "session") {
+    try {
+      if (typeof sessionStorage !== "undefined")
+        return sessionStorage;
+    } catch {}
+    try {
+      if (typeof window !== "undefined" && window.sessionStorage) {
+        return window.sessionStorage;
+      }
+    } catch {}
+    try {
+      if (typeof globalThis !== "undefined" && globalThis.sessionStorage) {
+        return globalThis.sessionStorage;
+      }
+    } catch {}
+    return null;
+  }
+  try {
+    if (typeof localStorage !== "undefined")
+      return localStorage;
+  } catch {}
+  try {
+    if (typeof window !== "undefined" && window.localStorage) {
+      return window.localStorage;
+    }
+  } catch {}
+  try {
+    if (typeof globalThis !== "undefined" && globalThis.localStorage) {
+      return globalThis.localStorage;
+    }
+  } catch {}
+  return null;
+}
 function signal(initialValue, optionsOrEquals) {
   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 persistOption = typeof optionsOrEquals === "object" ? optionsOrEquals?.persist : undefined;
+  const persistConfig = persistOption ? typeof persistOption === "string" ? { key: persistOption } : persistOption : undefined;
+  let effectiveInitial = initialValue;
+  const storage = persistConfig ? resolveStorage(persistConfig.storage) : null;
+  const serialize = persistConfig?.serialize ?? JSON.stringify;
+  const deserialize = persistConfig?.deserialize ?? JSON.parse;
+  if (persistConfig && storage) {
+    try {
+      const stored = storage.getItem(persistConfig.key);
+      if (stored !== null) {
+        effectiveInitial = deserialize(stored);
+      }
+    } catch {}
+  }
+  let isSyncing = false;
+  const onSet = persistConfig && storage ? (val) => {
+    if (isSyncing)
+      return;
+    try {
+      storage.setItem(persistConfig.key, serialize(val));
+    } catch {}
+  } : undefined;
+  const s = new Signal(effectiveInitial, equals, onSet);
+  if (persistConfig && storage && (persistConfig.syncTabs ?? true) && typeof window !== "undefined" && typeof window.addEventListener === "function") {
+    const onStorage = (e) => {
+      if (e.key === persistConfig.key) {
+        try {
+          const nextVal = e.newValue !== null ? deserialize(e.newValue) : initialValue;
+          isSyncing = true;
+          try {
+            s.set(nextVal);
+          } finally {
+            isSyncing = false;
+          }
+        } catch {}
+      }
+    };
+    window.addEventListener("storage", onStorage);
+    if (currentScope) {
+      currentScope.addCleanup(() => {
+        window.removeEventListener("storage", onStorage);
+      });
+    }
+  }
   const accessor = (...args) => {
     if (args.length === 0) {
       return s.get();

package/dist/style/layout.d.ts

@@ -0,0 +1,129 @@
+import type { Child } from "../dom";
+import type { ClassProp, HTMLAttributes } from "../jsx-runtime/jsx";
+export interface BaseLayoutProps extends HTMLAttributes<HTMLDivElement> {
+    as?: string;
+    gap?: number | string;
+    p?: number | string;
+    px?: number | string;
+    py?: number | string;
+    pt?: number | string;
+    pb?: number | string;
+    pl?: number | string;
+    pr?: number | string;
+    m?: number | string;
+    mx?: number | string;
+    my?: number | string;
+    mt?: number | string;
+    mb?: number | string;
+    ml?: number | string;
+    mr?: number | string;
+    w?: number | string;
+    h?: number | string;
+    minW?: number | string;
+    maxW?: number | string;
+    minH?: number | string;
+    maxH?: number | string;
+    class?: ClassProp;
+    className?: ClassProp;
+    style?: any;
+    children?: Child;
+    [key: string]: any;
+}
+export interface StackProps extends BaseLayoutProps {
+    align?: "start" | "center" | "end" | "stretch" | "baseline";
+    justify?: "start" | "center" | "end" | "between" | "around" | "evenly";
+    direction?: "vertical" | "horizontal";
+    reversed?: boolean;
+    wrap?: boolean | "wrap" | "nowrap" | "wrap-reverse";
+    inline?: boolean;
+}
+/**
+ * <Stack> Layout Primitive
+ *
+ * Vertical (column) layout by default. Provides zero margin collapse,
+ * built-in spatial scale gap, and automatic flex overflow containment.
+ *
+ * @example
+ * <Stack gap={4} align="center">
+ *   <Header />
+ *   <Content />
+ * </Stack>
+ */
+export declare function Stack(props: StackProps): Child;
+export interface RowProps extends BaseLayoutProps {
+    align?: "start" | "center" | "end" | "stretch" | "baseline";
+    justify?: "start" | "center" | "end" | "between" | "around" | "evenly";
+    reversed?: boolean;
+    wrap?: boolean | "wrap" | "nowrap" | "wrap-reverse";
+    inline?: boolean;
+}
+/**
+ * <Row> Layout Primitive
+ *
+ * Horizontal row layout with sensible vertical centering (align="center") by default.
+ *
+ * @example
+ * <Row gap={3} justify="between">
+ *   <Avatar />
+ *   <Typography>Online</Typography>
+ * </Row>
+ */
+export declare function Row(props: RowProps): Child;
+export interface CenterProps extends BaseLayoutProps {
+    inline?: boolean;
+}
+/**
+ * <Center> Layout Primitive
+ *
+ * Centers child content horizontally and vertically without CSS boilerplate.
+ *
+ * @example
+ * <Center h="screen">
+ *   <Spinner />
+ * </Center>
+ */
+export declare function Center(props: CenterProps): Child;
+export interface GridProps extends BaseLayoutProps {
+    columns?: number | string;
+    minChildWidth?: number | string;
+    rows?: number | string;
+    rowGap?: number | string;
+    colGap?: number | string;
+    align?: "start" | "center" | "end" | "stretch";
+    justify?: "start" | "center" | "end" | "stretch";
+    inline?: boolean;
+}
+/**
+ * <Grid> Layout Primitive
+ *
+ * Effortless CSS Grid. Specify fixed columns or a responsive minChildWidth
+ * to achieve fluid wrapping grids without writing complex media queries.
+ *
+ * @example
+ * // Responsive auto-wrapping grid
+ * <Grid minChildWidth={260} gap={4}>
+ *   <Card />
+ *   <Card />
+ * </Grid>
+ */
+export declare function Grid(props: GridProps): Child;
+export interface SpacerProps extends BaseLayoutProps {
+    size?: number | string;
+    x?: number | string;
+    y?: number | string;
+    flex?: boolean | number;
+}
+/**
+ * <Spacer> Layout Primitive
+ *
+ * Creates flexible pushing space in Rows/Stacks (defaults to flex: 1)
+ * or creates a dedicated spatial gap block when given size.
+ *
+ * @example
+ * <Row>
+ *   <Logo />
+ *   <Spacer />
+ *   <UserProfile />
+ * </Row>
+ */
+export declare function Spacer(props: SpacerProps): Child;

package/dist/style/manager.d.ts

@@ -0,0 +1,31 @@
+export interface InjectedStyle {
+    id: string;
+    css: string;
+    count: number;
+    element?: HTMLStyleElement;
+}
+export declare class StyleManager {
+    private _styles;
+    private _ssrStyles;
+    /**
+     * Inject CSS into the document head or SSR registry
+     */
+    inject(id: string, css: string): () => void;
+    /**
+     * Check if a style scope is currently registered
+     */
+    has(id: string): boolean;
+    /**
+     * Extract all styles collected during Server-Side Rendering (SSR)
+     */
+    extractSSRStyles(): string;
+    /**
+     * Clear all registered and SSR styles
+     */
+    clear(): void;
+}
+export declare const styleManager: StyleManager;
+/**
+ * Helper to get SSR style tag HTML
+ */
+export declare function extractStyleTags(): string;