summitjs 0.1.0

package/dist/summit.d.cts

@@ -0,0 +1,269 @@
+/**
+ * Per-element bookkeeping.
+ *
+ * Summit attaches a small metadata record to every element it touches: the
+ * scope stack in effect there, teardown callbacks, a move-detection marker, and
+ * whether the element is a component root. Kept in a WeakMap so nothing leaks
+ * onto the DOM and everything is collected when a node is dropped.
+ */
+type Scope = Record<PropertyKey, unknown>;
+
+/**
+ * Shared type contracts used across Summit's modules.
+ */
+
+/** A parsed Summit attribute, e.g. `s-on:click.prevent="go()"`. */
+interface DirectiveMeta {
+    /** The directive name without the `s-` prefix, e.g. "on", "bind", "text". */
+    name: string;
+    /** The part after the colon, e.g. "click" in s-on:click. Null if absent. */
+    value: string | null;
+    /** Dot-separated modifiers, e.g. ["prevent", "stop"]. */
+    modifiers: string[];
+    /** The attribute's expression string (its value). */
+    expression: string;
+    /** The original attribute name as written in the DOM. */
+    raw: string;
+}
+/**
+ * Utilities handed to every directive. This is the directive author's API and
+ * intentionally mirrors what the built-ins use, so third-party directives are
+ * first-class.
+ */
+interface DirectiveUtils {
+    /** Evaluate a value expression in this element's scope. */
+    evaluate(expression: string): unknown;
+    /** Evaluate an action (statements) in this element's scope, with extra locals. */
+    evaluateAction(expression: string, locals?: Scope): unknown;
+    /** Create a batched reactive effect that is torn down with the element. */
+    effect(fn: () => void): void;
+    /** Register a teardown callback. */
+    cleanup(fn: () => void): void;
+    /** Initialize a subtree (used by structural directives). */
+    initTree(el: Element, scopes?: Scope[]): void;
+    /** Tear down a subtree. */
+    destroyTree(el: Element): void;
+    /** The scope stack visible at this element. */
+    scopes: Scope[];
+    /** Build a fresh RootEnv for an element, optionally with extra locals. */
+    makeEnv(el: Element, locals?: Scope): RootEnvLike;
+    /** The Summit global. */
+    Summit: SummitGlobalLike;
+}
+interface RootEnvLike {
+    has(name: string): boolean;
+    get(name: string): unknown;
+    set(name: string, value: unknown): void;
+}
+/** The context object passed to a magic factory. */
+interface MagicContext {
+    el: Element;
+    scopes: Scope[];
+    evaluate(expression: string): unknown;
+    effect(fn: () => void): void;
+    cleanup(fn: () => void): void;
+}
+type DirectiveHandler = (el: Element, meta: DirectiveMeta, utils: DirectiveUtils) => void;
+type MagicFactory = (ctx: MagicContext) => unknown;
+type DataProvider = (...args: unknown[]) => Record<PropertyKey, unknown>;
+type BindProvider = () => Record<string, unknown>;
+/** A minimal shape of the Summit global for internal cross-references. */
+interface SummitGlobalLike {
+    version: string;
+    store(name: string, value?: unknown): unknown;
+    [key: string]: unknown;
+}
+
+/**
+ * The registries.
+ *
+ * Everything pluggable in Summit lives here: directives, magics, reusable data
+ * providers, global stores, and reusable bind objects. Keeping these in a leaf
+ * module (no imports from the rest of Summit) means registration can happen at
+ * any time without import cycles, which is what makes Summit's registration
+ * timing-safe instead of Alpine's load-order-sensitive model.
+ */
+
+declare function getBind(name: string): BindProvider | undefined;
+
+/**
+ * initTree / destroyTree: the DOM engine.
+ *
+ * initTree walks an element and its descendants, establishing s-data scopes and
+ * running directives in priority order. Structural directives (s-if, s-for,
+ * s-teleport) take over their own subtree. destroyTree runs every teardown
+ * callback so effects stop, listeners detach, and component `destroy()` fires.
+ */
+
+declare function initTree(el: Element, scopesArg?: Scope[]): void;
+declare function destroyTree(el: Element): void;
+
+/**
+ * A signal: a single reactive value with an explicit getter/setter.
+ *
+ * Reading the signal (calling it) subscribes the active effect. Writing it
+ * (`.set`) wakes every subscribed effect, but only if the value actually
+ * changed (`Object.is`). `.peek()` reads without subscribing.
+ */
+interface Signal<T> {
+    (): T;
+    set(next: T | ((prev: T) => T)): void;
+    peek(): T;
+}
+declare function signal<T>(initial: T): Signal<T>;
+/** True if `x` is a signal produced by `signal()`. */
+declare function isSignal<T = unknown>(x: unknown): x is Signal<T>;
+
+/**
+ * A computed value: a memoized, lazily-evaluated derivation.
+ *
+ * Unlike a plain getter (which Alpine re-runs on every read), a computed caches
+ * its result and only recomputes when one of its own dependencies changes. It
+ * stays lazy: the getter does not run until something reads the computed.
+ */
+interface Computed<T> {
+    (): T;
+    peek(): T;
+}
+declare function computed<T>(getter: () => T): Computed<T>;
+
+/**
+ * Deep reactive objects.
+ *
+ * `reactive(obj)` returns a Proxy that tracks property reads and triggers on
+ * writes, so `this.open = true` inside a component method just works. Nested
+ * objects and arrays are wrapped lazily on access. This is what backs a
+ * component's `s-data` scope, giving Alpine-style ergonomics on top of
+ * Summit's fine-grained effect system.
+ */
+/** Wrap an object in a deep reactive proxy. Idempotent and cached per object. */
+declare function reactive<T extends object>(target: T): T;
+/** Unwrap a reactive proxy back to its plain object. Safe on non-proxies. */
+declare function toRaw<T>(observed: T): T;
+/** True if `x` is a reactive proxy. */
+declare function isReactive(x: unknown): boolean;
+
+/**
+ * The reactive effect system.
+ *
+ * This is the heart of Summit. An `effect` is a function that automatically
+ * re-runs whenever any reactive value it read during its last run changes.
+ * Dependency tracking is fine-grained: a `dep` is a set of effects that
+ * depend on one specific value, so a change only wakes the effects that
+ * actually read that value. Nothing else re-runs.
+ */
+type Dep = Set<ReactiveEffect>;
+interface EffectOptions {
+    /** Skip the initial run. The effect only runs when its scheduler fires. */
+    lazy?: boolean;
+    /** Called instead of re-running the effect directly when a dep changes. */
+    scheduler?: () => void;
+    /** Called when the effect is stopped. */
+    onStop?: () => void;
+}
+interface ReactiveEffect {
+    (): void;
+    /** The deps this effect is currently subscribed to. */
+    deps: Dep[];
+    /** Whether the effect is still live. Stopped effects never re-run. */
+    active: boolean;
+    scheduler?: () => void;
+    onStop?: () => void;
+    /** The user function this effect wraps. */
+    raw: () => unknown;
+}
+/**
+ * Create a reactive effect. Runs immediately unless `lazy` is set. Returns a
+ * runner you can call manually or hand to `stop()`.
+ */
+declare function effect(fn: () => unknown, options?: EffectOptions): ReactiveEffect;
+/** Permanently stop an effect and unsubscribe it from every dep. */
+declare function stop(runner: ReactiveEffect): void;
+/** Run `fn` without subscribing the active effect to anything read inside it. */
+declare function untrack<T>(fn: () => T): T;
+/**
+ * Group multiple writes so dependent effects run once at the end instead of
+ * after each write. Batches nest; only the outermost flush runs effects.
+ */
+declare function batch<T>(fn: () => T): T;
+
+/**
+ * Resolve after the current flush completes. With a callback, runs it after the
+ * flush; without one, returns a promise you can await.
+ */
+declare function nextTick(callback?: () => void): Promise<void>;
+
+/**
+ * The Summit global.
+ *
+ * This is the object users interact with: register data, directives, magics,
+ * stores, and plugins, then start. Registration is timing-safe. Built-ins are
+ * registered at import, custom registrations override them, and start() can be
+ * called whenever the DOM is ready. There is no load-order event to miss.
+ */
+
+declare const version = "0.1.0";
+interface SummitGlobal {
+    version: string;
+    started: () => boolean;
+    start(root?: Element): void;
+    data(name: string, provider: DataProvider): SummitGlobal;
+    directive(name: string, handler: DirectiveHandler, priority?: number): SummitGlobal;
+    magic(name: string, factory: MagicFactory): SummitGlobal;
+    bind(name: string, provider: BindProvider): SummitGlobal;
+    store(name: string, value?: unknown): unknown;
+    plugin(fn: (summit: SummitGlobal) => void): SummitGlobal;
+    addGlobals(names: string[]): SummitGlobal;
+    getBind: typeof getBind;
+    signal: typeof signal;
+    computed: typeof computed;
+    effect: typeof effect;
+    reactive: typeof reactive;
+    batch: typeof batch;
+    nextTick: typeof nextTick;
+    initTree: typeof initTree;
+    destroyTree: typeof destroyTree;
+}
+declare const Summit: SummitGlobal;
+
+/**
+ * The interpreter walks an AST and produces a value. It never calls `eval` or
+ * `new Function`, so a strict `script-src` CSP with no `unsafe-eval` is fully
+ * satisfied. Identifiers resolve first against interpreter-local bindings
+ * (arrow params, let/const), then the component data scope (the RootEnv), then
+ * a small allowlist of safe globals.
+ */
+
+/** The component-level environment: the merged s-data stack plus magics. */
+interface RootEnv {
+    has(name: string): boolean;
+    get(name: string): unknown;
+    set(name: string, value: unknown): void;
+}
+/** Add names to the global allowlist that expressions may access. */
+declare function addGlobals(names: string[]): void;
+
+/**
+ * Public evaluator API.
+ *
+ * `evaluateExpression` runs a value expression (s-data, s-text, :bind, s-show).
+ * `evaluateAction` runs a statement list (s-on handlers, s-init). Both parse to
+ * a cached AST and interpret it with no `eval` / `new Function`, so Summit runs
+ * under a strict Content-Security-Policy out of the box.
+ */
+
+/** Evaluate a value expression against a component environment. */
+declare function evaluateExpression(source: string, root: RootEnv, thisVal?: unknown): unknown;
+/** Evaluate an action (one or more statements) against a component environment. */
+declare function evaluateAction(source: string, root: RootEnv, thisVal?: unknown): unknown;
+
+/**
+ * Summit: a rugged, signal-powered framework for composing behavior directly
+ * in your HTML. This is the package entry for bundler/npm users. Import the
+ * default `Summit` global, register anything you like, then call `Summit.start()`.
+ *
+ * For a zero-build drop-in, use the CDN build (dist/summit.min.js), which
+ * attaches `window.Summit` and starts automatically.
+ */
+
+export { type BindProvider, type Computed, type DataProvider, type DirectiveHandler, type DirectiveMeta, type DirectiveUtils, type MagicContext, type MagicFactory, type Signal, Summit, type SummitGlobal, addGlobals, batch, computed, Summit as default, effect, evaluateAction, evaluateExpression, isReactive, isSignal, nextTick, reactive, signal, stop, toRaw, untrack, version };

package/dist/summit.d.ts

@@ -0,0 +1,269 @@
+/**
+ * Per-element bookkeeping.
+ *
+ * Summit attaches a small metadata record to every element it touches: the
+ * scope stack in effect there, teardown callbacks, a move-detection marker, and
+ * whether the element is a component root. Kept in a WeakMap so nothing leaks
+ * onto the DOM and everything is collected when a node is dropped.
+ */
+type Scope = Record<PropertyKey, unknown>;
+
+/**
+ * Shared type contracts used across Summit's modules.
+ */
+
+/** A parsed Summit attribute, e.g. `s-on:click.prevent="go()"`. */
+interface DirectiveMeta {
+    /** The directive name without the `s-` prefix, e.g. "on", "bind", "text". */
+    name: string;
+    /** The part after the colon, e.g. "click" in s-on:click. Null if absent. */
+    value: string | null;
+    /** Dot-separated modifiers, e.g. ["prevent", "stop"]. */
+    modifiers: string[];
+    /** The attribute's expression string (its value). */
+    expression: string;
+    /** The original attribute name as written in the DOM. */
+    raw: string;
+}
+/**
+ * Utilities handed to every directive. This is the directive author's API and
+ * intentionally mirrors what the built-ins use, so third-party directives are
+ * first-class.
+ */
+interface DirectiveUtils {
+    /** Evaluate a value expression in this element's scope. */
+    evaluate(expression: string): unknown;
+    /** Evaluate an action (statements) in this element's scope, with extra locals. */
+    evaluateAction(expression: string, locals?: Scope): unknown;
+    /** Create a batched reactive effect that is torn down with the element. */
+    effect(fn: () => void): void;
+    /** Register a teardown callback. */
+    cleanup(fn: () => void): void;
+    /** Initialize a subtree (used by structural directives). */
+    initTree(el: Element, scopes?: Scope[]): void;
+    /** Tear down a subtree. */
+    destroyTree(el: Element): void;
+    /** The scope stack visible at this element. */
+    scopes: Scope[];
+    /** Build a fresh RootEnv for an element, optionally with extra locals. */
+    makeEnv(el: Element, locals?: Scope): RootEnvLike;
+    /** The Summit global. */
+    Summit: SummitGlobalLike;
+}
+interface RootEnvLike {
+    has(name: string): boolean;
+    get(name: string): unknown;
+    set(name: string, value: unknown): void;
+}
+/** The context object passed to a magic factory. */
+interface MagicContext {
+    el: Element;
+    scopes: Scope[];
+    evaluate(expression: string): unknown;
+    effect(fn: () => void): void;
+    cleanup(fn: () => void): void;
+}
+type DirectiveHandler = (el: Element, meta: DirectiveMeta, utils: DirectiveUtils) => void;
+type MagicFactory = (ctx: MagicContext) => unknown;
+type DataProvider = (...args: unknown[]) => Record<PropertyKey, unknown>;
+type BindProvider = () => Record<string, unknown>;
+/** A minimal shape of the Summit global for internal cross-references. */
+interface SummitGlobalLike {
+    version: string;
+    store(name: string, value?: unknown): unknown;
+    [key: string]: unknown;
+}
+
+/**
+ * The registries.
+ *
+ * Everything pluggable in Summit lives here: directives, magics, reusable data
+ * providers, global stores, and reusable bind objects. Keeping these in a leaf
+ * module (no imports from the rest of Summit) means registration can happen at
+ * any time without import cycles, which is what makes Summit's registration
+ * timing-safe instead of Alpine's load-order-sensitive model.
+ */
+
+declare function getBind(name: string): BindProvider | undefined;
+
+/**
+ * initTree / destroyTree: the DOM engine.
+ *
+ * initTree walks an element and its descendants, establishing s-data scopes and
+ * running directives in priority order. Structural directives (s-if, s-for,
+ * s-teleport) take over their own subtree. destroyTree runs every teardown
+ * callback so effects stop, listeners detach, and component `destroy()` fires.
+ */
+
+declare function initTree(el: Element, scopesArg?: Scope[]): void;
+declare function destroyTree(el: Element): void;
+
+/**
+ * A signal: a single reactive value with an explicit getter/setter.
+ *
+ * Reading the signal (calling it) subscribes the active effect. Writing it
+ * (`.set`) wakes every subscribed effect, but only if the value actually
+ * changed (`Object.is`). `.peek()` reads without subscribing.
+ */
+interface Signal<T> {
+    (): T;
+    set(next: T | ((prev: T) => T)): void;
+    peek(): T;
+}
+declare function signal<T>(initial: T): Signal<T>;
+/** True if `x` is a signal produced by `signal()`. */
+declare function isSignal<T = unknown>(x: unknown): x is Signal<T>;
+
+/**
+ * A computed value: a memoized, lazily-evaluated derivation.
+ *
+ * Unlike a plain getter (which Alpine re-runs on every read), a computed caches
+ * its result and only recomputes when one of its own dependencies changes. It
+ * stays lazy: the getter does not run until something reads the computed.
+ */
+interface Computed<T> {
+    (): T;
+    peek(): T;
+}
+declare function computed<T>(getter: () => T): Computed<T>;
+
+/**
+ * Deep reactive objects.
+ *
+ * `reactive(obj)` returns a Proxy that tracks property reads and triggers on
+ * writes, so `this.open = true` inside a component method just works. Nested
+ * objects and arrays are wrapped lazily on access. This is what backs a
+ * component's `s-data` scope, giving Alpine-style ergonomics on top of
+ * Summit's fine-grained effect system.
+ */
+/** Wrap an object in a deep reactive proxy. Idempotent and cached per object. */
+declare function reactive<T extends object>(target: T): T;
+/** Unwrap a reactive proxy back to its plain object. Safe on non-proxies. */
+declare function toRaw<T>(observed: T): T;
+/** True if `x` is a reactive proxy. */
+declare function isReactive(x: unknown): boolean;
+
+/**
+ * The reactive effect system.
+ *
+ * This is the heart of Summit. An `effect` is a function that automatically
+ * re-runs whenever any reactive value it read during its last run changes.
+ * Dependency tracking is fine-grained: a `dep` is a set of effects that
+ * depend on one specific value, so a change only wakes the effects that
+ * actually read that value. Nothing else re-runs.
+ */
+type Dep = Set<ReactiveEffect>;
+interface EffectOptions {
+    /** Skip the initial run. The effect only runs when its scheduler fires. */
+    lazy?: boolean;
+    /** Called instead of re-running the effect directly when a dep changes. */
+    scheduler?: () => void;
+    /** Called when the effect is stopped. */
+    onStop?: () => void;
+}
+interface ReactiveEffect {
+    (): void;
+    /** The deps this effect is currently subscribed to. */
+    deps: Dep[];
+    /** Whether the effect is still live. Stopped effects never re-run. */
+    active: boolean;
+    scheduler?: () => void;
+    onStop?: () => void;
+    /** The user function this effect wraps. */
+    raw: () => unknown;
+}
+/**
+ * Create a reactive effect. Runs immediately unless `lazy` is set. Returns a
+ * runner you can call manually or hand to `stop()`.
+ */
+declare function effect(fn: () => unknown, options?: EffectOptions): ReactiveEffect;
+/** Permanently stop an effect and unsubscribe it from every dep. */
+declare function stop(runner: ReactiveEffect): void;
+/** Run `fn` without subscribing the active effect to anything read inside it. */
+declare function untrack<T>(fn: () => T): T;
+/**
+ * Group multiple writes so dependent effects run once at the end instead of
+ * after each write. Batches nest; only the outermost flush runs effects.
+ */
+declare function batch<T>(fn: () => T): T;
+
+/**
+ * Resolve after the current flush completes. With a callback, runs it after the
+ * flush; without one, returns a promise you can await.
+ */
+declare function nextTick(callback?: () => void): Promise<void>;
+
+/**
+ * The Summit global.
+ *
+ * This is the object users interact with: register data, directives, magics,
+ * stores, and plugins, then start. Registration is timing-safe. Built-ins are
+ * registered at import, custom registrations override them, and start() can be
+ * called whenever the DOM is ready. There is no load-order event to miss.
+ */
+
+declare const version = "0.1.0";
+interface SummitGlobal {
+    version: string;
+    started: () => boolean;
+    start(root?: Element): void;
+    data(name: string, provider: DataProvider): SummitGlobal;
+    directive(name: string, handler: DirectiveHandler, priority?: number): SummitGlobal;
+    magic(name: string, factory: MagicFactory): SummitGlobal;
+    bind(name: string, provider: BindProvider): SummitGlobal;
+    store(name: string, value?: unknown): unknown;
+    plugin(fn: (summit: SummitGlobal) => void): SummitGlobal;
+    addGlobals(names: string[]): SummitGlobal;
+    getBind: typeof getBind;
+    signal: typeof signal;
+    computed: typeof computed;
+    effect: typeof effect;
+    reactive: typeof reactive;
+    batch: typeof batch;
+    nextTick: typeof nextTick;
+    initTree: typeof initTree;
+    destroyTree: typeof destroyTree;
+}
+declare const Summit: SummitGlobal;
+
+/**
+ * The interpreter walks an AST and produces a value. It never calls `eval` or
+ * `new Function`, so a strict `script-src` CSP with no `unsafe-eval` is fully
+ * satisfied. Identifiers resolve first against interpreter-local bindings
+ * (arrow params, let/const), then the component data scope (the RootEnv), then
+ * a small allowlist of safe globals.
+ */
+
+/** The component-level environment: the merged s-data stack plus magics. */
+interface RootEnv {
+    has(name: string): boolean;
+    get(name: string): unknown;
+    set(name: string, value: unknown): void;
+}
+/** Add names to the global allowlist that expressions may access. */
+declare function addGlobals(names: string[]): void;
+
+/**
+ * Public evaluator API.
+ *
+ * `evaluateExpression` runs a value expression (s-data, s-text, :bind, s-show).
+ * `evaluateAction` runs a statement list (s-on handlers, s-init). Both parse to
+ * a cached AST and interpret it with no `eval` / `new Function`, so Summit runs
+ * under a strict Content-Security-Policy out of the box.
+ */
+
+/** Evaluate a value expression against a component environment. */
+declare function evaluateExpression(source: string, root: RootEnv, thisVal?: unknown): unknown;
+/** Evaluate an action (one or more statements) against a component environment. */
+declare function evaluateAction(source: string, root: RootEnv, thisVal?: unknown): unknown;
+
+/**
+ * Summit: a rugged, signal-powered framework for composing behavior directly
+ * in your HTML. This is the package entry for bundler/npm users. Import the
+ * default `Summit` global, register anything you like, then call `Summit.start()`.
+ *
+ * For a zero-build drop-in, use the CDN build (dist/summit.min.js), which
+ * attaches `window.Summit` and starts automatically.
+ */
+
+export { type BindProvider, type Computed, type DataProvider, type DirectiveHandler, type DirectiveMeta, type DirectiveUtils, type MagicContext, type MagicFactory, type Signal, Summit, type SummitGlobal, addGlobals, batch, computed, Summit as default, effect, evaluateAction, evaluateExpression, isReactive, isSignal, nextTick, reactive, signal, stop, toRaw, untrack, version };