@manyducks.co/dolla 2.0.0 → 3.1.0

package/dist/core/index.d.ts

@@ -1,24 +1,23 @@
-export { createApp } from "./app.js";
-export { batch, effect, get, memo, readable, signal, untracked, writable } from "./signals.js";
-export type { MaybeSignal, Signal, Writable, Setter } from "./signals.js";
-export * from "./hooks.js";
-export { createContext } from "./context.js";
+export { createRoot } from "./root.js";
+export type { DollaPlugin } from "./root.js";
+export { batch, compose, createAtom, createEffect, peek, subscribe, unwrap } from "./signals.js";
+export type { Getter, Setter } from "./signals.js";
+export { addStore, getNearestViewNode, getRootElement, getStore, onCleanup, onEffect, onMount } from "./context.js";
 export type { Context } from "./context.js";
-export { createMarkup, Markup, MarkupNode, render } from "./markup.js";
-export { ref, type Ref } from "./ref.js";
-export { For, type ForProps } from "./views/for.js";
-export { Portal, type PortalProps } from "./views/portal.js";
-export { Show, type ShowProps } from "./views/show.js";
-export { deepEqual, shallowEqual, strictEqual } from "../utils.js";
-export { getEnv, setEnv } from "./env.js";
-export { createLogger, onLoggerCrash, setLogFilter, setLogLevels } from "./logger.js";
-export type { Logger, LoggerCrashProps, LoggerOptions, LogLevels } from "./logger.js";
-export type { CSSProperties, Env, InputType, Mixin, Renderable, Store, View } from "../types.js";
-export type { CrashViewProps } from "./views/default-crash-view.js";
+export { createDebug, getDebug, setLogFilter, setLogLevel } from "./debug.js";
+export { createPortal, forEach, hideIf, showIf } from "./markup/helpers.js";
+export { html } from "./markup/html.js";
+export { ViewNode } from "./markup/nodes/view.js";
+export type { Markup, MarkupNode } from "./markup/types.js";
+export { createMarkup, render } from "./markup/utils.js";
+export { createRef } from "./ref.js";
+export type { Ref } from "./ref.js";
+export type { CSSProperties, Env, InputType, MaybeGetter, Renderable, Store, View } from "../types.js";
 import type { IntrinsicElements as Elements } from "../types.js";
 declare global {
     namespace JSX {
         interface IntrinsicElements extends Elements {
+            [tag: `${string}-${string}`]: any;
             [tag: string]: any;
         }
     }

package/dist/core/markup/helpers.d.ts

@@ -0,0 +1,34 @@
+import { Renderable } from "..";
+import { type Getter } from "../signals";
+import { PortalNode } from "./nodes/portal";
+import { KeyFn, RenderFn } from "./nodes/repeat";
+/**
+ * Displays a dynamic list. Items will be added and removed as the list is updated.
+ *
+ * @param items - List items. Can be reactive.
+ * @param keyFn - Takes (item, index) as plain values and returns a unique key to identify that item (usually the item's ID).
+ * @param renderFn - Takes (item, index) as Reactive values and returns content to display for that item.
+ */
+export declare function forEach<T>(items: Getter<Iterable<T>> | Iterable<T>, keyFn: KeyFn<T>, renderFn: RenderFn<T>): Renderable;
+/**
+ * Shows content only when `condition` is truthy.
+ * It can be a plain value or a Getter to track dynamically.
+ *
+ * @param condition - Condition to hide or show content on.
+ * @param content - Content to display when condition is truthy.
+ * @param fallback - Content to display when condition is falsy.
+ */
+export declare function showIf(condition: any, content: Renderable, fallback?: Renderable): Renderable;
+/**
+ * Shows content only when `condition` is falsy.
+ * It can be a plain value or a Getter to track dynamically.
+ *
+ * @param condition - Condition to hide or show content on.
+ * @param content - Content to display when condition is falsy.
+ * @param fallback - Content to display when condition is truthy.
+ */
+export declare function hideIf(condition: any, content: Renderable, fallback?: Renderable): Renderable;
+/**
+ * Creates a portal that renders `content` into another element on the page.
+ **/
+export declare function createPortal(parent: Element, content: Renderable): import("./types").Markup<typeof PortalNode>;

package/dist/core/markup/html.d.ts

@@ -0,0 +1,3 @@
+import type { Markup } from "./types.js";
+export type Template = Markup | Markup[];
+export declare function html(statics: TemplateStringsArray, ...args: any[]): Template;

package/dist/core/{nodes → markup/nodes}/dom.d.ts

@@ -1,13 +1,14 @@
-import { MarkupNode } from "./_markup";
+import { Context } from "../../context.js";
+import { MarkupNode, type MountTarget } from "../types.js";
 /**
  * A lightweight MarkupNode wrapper for a plain DOM node.
  */
 export declare class DOMNode extends MarkupNode {
-    private root;
-    constructor(node: Node);
+    #private;
+    constructor(_context: Context, node: Node);
     getRoot(): Node;
     isMounted(): boolean;
-    mount(parent: Element, after?: Node): void;
+    mount(parent: MountTarget, after?: Node): void;
     unmount(skipDOM?: boolean): void;
     move(parent: Element, after?: Node): void;
 }

package/dist/core/markup/nodes/dynamic.d.ts

@@ -0,0 +1,16 @@
+import type { Context } from "../../context.js";
+import { type Getter } from "../../signals.js";
+import { MarkupNode, MountTarget } from "../types.js";
+/**
+ * Renders any kind of content; markup, signals, DOM nodes, etc.
+ * If it can be rendered by Dolla then Dynamic will do it.
+ */
+export declare class DynamicNode extends MarkupNode {
+    #private;
+    constructor(context: Context, slot: Getter<any>);
+    getRoot(): Text;
+    isMounted(): boolean;
+    mount(parent: MountTarget, after?: Node): void;
+    unmount(skipDOM?: boolean): void;
+    move(parent: MountTarget, after?: Node): void;
+}

package/dist/core/markup/nodes/element.d.ts

@@ -0,0 +1,14 @@
+import { Context } from "../../context.js";
+import { MarkupNode, MountTarget } from "../types.js";
+/**
+ * Renders an HTML or SVG element.
+ */
+export declare class ElementNode extends MarkupNode {
+    #private;
+    constructor(context: Context, tag: string, props: Record<string, any>);
+    getRoot(): HTMLElement | SVGElement;
+    isMounted(): boolean;
+    mount(parent: MountTarget, after?: Node): void;
+    unmount(skipDOM?: boolean): void;
+    move(parent: MountTarget, after?: Node): void;
+}

package/dist/core/markup/nodes/portal.d.ts

@@ -0,0 +1,15 @@
+import type { Renderable } from "../../../types.js";
+import { Context } from "../../context.js";
+import { MarkupNode, MountTarget } from "../types.js";
+/**
+ * Renders content into a specified parent node.
+ */
+export declare class PortalNode extends MarkupNode {
+    #private;
+    constructor(context: Context, value: Renderable, parent: MountTarget);
+    getRoot(): Text;
+    isMounted(): boolean;
+    mount(logicalParent: MountTarget, after?: Node): void;
+    unmount(skipDOM?: boolean): void;
+    move(logicalParent: MountTarget, after?: Node): void;
+}

package/dist/core/markup/nodes/repeat.d.ts

@@ -0,0 +1,21 @@
+import type { Renderable } from "../../../types.js";
+import type { Context } from "../../context.js";
+import { type Getter } from "../../signals.js";
+import { MarkupNode } from "../types.js";
+export type Key = any;
+export type KeyFn<T> = (item: T, index: number) => Key;
+export type RenderFn<T> = (item: Getter<T>, index: Getter<number>) => Renderable;
+/**
+ * Renders a list of items.
+ */
+export declare class RepeatNode<T> extends MarkupNode {
+    #private;
+    constructor(context: Context, items: Getter<Iterable<T>>, key: KeyFn<T>, render: RenderFn<T>);
+    getRoot(): Text;
+    isMounted(): boolean;
+    mount(parent: Element, after?: Node): void;
+    unmount(skipDOM?: boolean): void;
+    move(parent: Element, after?: Node): void;
+    private _cleanup;
+    private _update;
+}

package/dist/core/markup/nodes/view.d.ts

@@ -0,0 +1,17 @@
+import type { View } from "../../../types.js";
+import { ComponentState, Context } from "../../context.js";
+import { MarkupNode } from "../types.js";
+export declare const VIEW: unique symbol;
+/**
+ * Renders a View.
+ */
+export declare class ViewNode<P> extends MarkupNode {
+    #private;
+    readonly context: Context<ComponentState & Record<string | symbol, any>>;
+    constructor(context: Context, view: View<P>, props: P);
+    getRoot(): Node | undefined;
+    isMounted(): boolean;
+    mount(parent: Element, after?: Node): void;
+    unmount(skipDOM?: boolean): void;
+    move(parent: Element, after?: Node): void;
+}

package/dist/core/markup/scheduler.d.ts

@@ -0,0 +1 @@
+export declare function scheduleUpdate(updateFn: () => void): void;

package/dist/core/markup/types.d.ts

@@ -0,0 +1,62 @@
+import type { IntrinsicElements, View } from "../../types.js";
+import { Context } from "../index.js";
+/**
+ * Determines the type of the `props` object for any kind of Markup type.
+ */
+export type PropsOf<T extends string | View<any> | (new (...args: any[]) => MarkupNode)> = T extends View<infer P> ? P : T extends new (...args: infer Args) => MarkupNode ? {
+    args: Args extends [Context, ...infer Rest] ? Rest : [];
+} : T extends keyof IntrinsicElements ? IntrinsicElements[T] : any;
+export declare const IS_MARKUP: unique symbol;
+export declare const IS_MARKUP_NODE: unique symbol;
+export declare const IS_MARKUP_NODE_CLASS: unique symbol;
+/**
+ * A set of basic metadata that can be constructed into a `MarkupNode`.
+ */
+export interface Markup<Type extends string | View<any> | (new (...args: any[]) => MarkupNode) = string | View<any> | (new (...args: any[]) => MarkupNode)> {
+    [IS_MARKUP]: true;
+    type: Type;
+    props: PropsOf<Type>;
+}
+export interface MountTarget {
+    insertBefore(node: Node, child: Node | null): any;
+    moveBefore?: (node: Node, child: Node | null) => any;
+    appendChild(node: Node): any;
+}
+/**
+ * A node that can be mounted by the Markup layout engine. Can be extended to create new custom node types.
+ *
+ * A `MarkupNode` instance can be passed anywhere a `Renderable` is required.
+ */
+export declare abstract class MarkupNode {
+    static [IS_MARKUP_NODE_CLASS]: boolean;
+    get [IS_MARKUP_NODE](): boolean;
+    /**
+     * Returns a single DOM node to represent this MarkupNode's position in the DOM.
+     * Usually the parent element, but it can be an empty Text node used as a marker.
+     *
+     * It only needs to be defined while the node is mounted, so it can be created in the `mount` function.
+     */
+    abstract getRoot(): Node | undefined;
+    /**
+     * Returns true while this node is mounted.
+     */
+    abstract isMounted(): boolean;
+    /**
+     * Mount this node to a `parent` element.
+     * If passed, this node will be mounted as the next sibling of `after`.
+     */
+    abstract mount(parent: MountTarget, after?: Node): void;
+    /**
+     * Unmount this MarkupNode from its parent element.
+     *
+     * The `skipDOM` option can be passed as an optimization when unmounting a parent node.
+     * A value of `true` indicates that no DOM operations need to happen because the parent is already being unmounted.
+     *
+     * @param skipDOM - No DOM updates will be performed when true. Lifecycle methods will be called regardless.
+     */
+    abstract unmount(skipDOM?: boolean): void;
+    /**
+     * Moves a node without unmounting and remounting (if the browser supports Element.moveBefore).
+     */
+    abstract move(parent: MountTarget, after?: Node): void;
+}

package/dist/core/markup/utils.d.ts

@@ -0,0 +1,22 @@
+import type { Renderable, View } from "../../types.js";
+import { Context } from "../context.js";
+import { Markup, MarkupNode, MountTarget, PropsOf } from "./types.js";
+export declare function createMarkup<Type extends string | View<any> | (new (...args: any[]) => MarkupNode)>(type: Type, props: PropsOf<Type>): Markup<Type>;
+export declare function isMarkup<T extends string | View<any> | (new (...args: any[]) => MarkupNode)>(value: any): value is Markup<T>;
+export declare function isMarkupNode(value: any): value is MarkupNode;
+export declare function isMarkupNodeClass(value: any): value is new (...args: any[]) => MarkupNode;
+/**
+ * Takes any `Renderable` value and returns a `MarkupNode` that will display it.
+ */
+export declare function render(content: Renderable, context?: Context<Record<string | symbol, any>>): MarkupNode;
+/**
+ * Convert basically anything into an array of `MarkupNode`
+ */
+export declare function toMarkupNodes(context: Context, ...content: any[]): MarkupNode[];
+export declare function addChild(parent: MountTarget, node: Node, after?: Node | null): void;
+export declare function createTextNode(text: string): Text;
+/**
+ * Moves an element using `moveBefore` if the browser supports it, otherwise falls back to `insertBefore`.
+ */
+export declare function moveAfter(parent: MountTarget, node: Node, after?: Node | null): void;
+export declare function addListener<T extends Event>(target: EventTarget, event: string, listener: (event: T) => any): () => void;

package/dist/core/ref.d.ts

@@ -1,19 +1,13 @@
-export declare const EMPTY_REF: unique symbol;
-/**
- * A hybrid getter/setter function that stores the last value it was called with.
- * Guarantees a value is held at runtime by throwing an error if no value is set.
- */
 export interface Ref<T> {
     /**
-     * Returns the currently stored value of the ref, or throws an error if no value has been set.
+     * Call with no arguments to get the stored value.
+     * Throws an error if the ref is empty (this means you forgot to pass it or it was called after teardown).
      */
     (): T;
     /**
-     * Stores a new value to the ref and returns that value.
+     * Call with an argument to initialize the value. Returns a cleanup function.
+     * The cleanup function should clear any references to the DOM node.
      */
-    (value: T): T;
+    (value: T): () => void;
 }
-/**
- * Creates a Ref.
- */
-export declare function ref<T>(value?: T): Ref<T>;
+export declare function createRef<T = HTMLElement>(): Ref<T>;

package/dist/core/root.d.ts

@@ -0,0 +1,36 @@
+import type { Renderable, View } from "../types.js";
+import { type Context } from "./context.js";
+export type CleanupCallback = () => void | Promise<void>;
+/**
+ * Plugins run before the app is mounted. If they return a promise, mounting will be delayed until the promise resolves.
+ * If a cleanup function is returned, it will be called before the app is unmounted. The cleanup function's promise will delay unmounting.
+ *
+ * Hooks can be used inside plugins.
+ */
+export type DollaPlugin = (context: Context) => Promise<CleanupCallback | void> | CleanupCallback | void;
+export interface DollaRootOptions {
+    /**
+     * Adds additional view info to the DOM to help with debugging.
+     */
+    debug?: boolean;
+}
+export interface DollaRoot {
+    /**
+     * Registers a plugin to be added before `mount`.
+     */
+    plugin(plugin: DollaPlugin): DollaRoot;
+    /**
+     * Mounts a `view` to this root.
+     */
+    mount(view: View<{}>): Promise<void>;
+    /**
+     * Mounts any renderable content to this root.
+     */
+    mount(content: Renderable): Promise<void>;
+    /**
+     * Unmounts the currently mounted content.
+     */
+    unmount(): void;
+}
+export declare function createRoot(selector: string, options?: DollaRootOptions): DollaRoot;
+export declare function createRoot(element: Element, options?: DollaRootOptions): DollaRoot;

package/dist/core/signals.d.ts

@@ -1,100 +1,70 @@
-import { Context } from "./context";
-export declare function getCurrentContext(): Context | undefined;
-export declare function setCurrentContext(context: Context | undefined): Context | undefined;
 /**
- * A function that returns the current value of a signal.
- * Automatically tracked as a dependency when called within a tracking scope (such as `memo` or `effect` functions).
+ * Returns the currently held value. Registers the state as a dependency when called within a tracking context.
  */
-export interface Signal<T> {
-    (): T;
-}
+export type Getter<T> = () => T;
 /**
- * A function that sets the value of the signal.
+ * A value that may be a static value or a getter function.
+ * Can be converted to a plain value with `unwrap`.
  */
-export interface Setter<T> {
-    (value: T | ((previousValue: T) => T)): void;
-}
+export type MaybeGetter<T> = T | Getter<T>;
 /**
- * A getter and setter in a single object. Callable like a getter, but includes a `set` method for updating the signal's value.
+ * Updates the value of an atom. Takes a new plain value, or an update function to compute one.
  */
-export interface Writable<T> extends Signal<T> {
-    set: Setter<T>;
-}
+export type Setter<T> = (next: SetterAction<T>) => T;
+export type SetterAction<T> = T | ((prev: T) => T);
 /**
- * Utility type for a value that may be a getter or a plain value.
- * This value can be unwrapped to a plain value with `get` or `untracked` (depending on whether you're in a tracking context and need to track it).
+ * A getter and setter pair, as returned from `createAtom`.
  */
-export type MaybeSignal<T> = Signal<T> | T;
-export type EqualityFn<T> = (previousValue: T, nextValue: T) => boolean;
-export interface SignalOptions<T> {
-    /**
-     * A function to compare the current and next values. Returning `true` means the value has changed.
-     */
-    equals?: EqualityFn<T>;
-}
-export declare function writable<T>(): Writable<T | undefined>;
-export declare function writable<T>(initialValue: undefined, options: SignalOptions<T | undefined>): Writable<T | undefined>;
-export declare function writable<T>(initialValue: T, options?: SignalOptions<T>): Writable<T>;
+export type AtomAccessors<T> = [Getter<T>, Setter<T>];
 /**
- * Ensures that a value is a read-only signal.
+ * Creates a new atom with a default `undefined` value.
+ * Returns a `[getter, setter]` function tuple.
  *
  * @example
- * const $number = readable(5); // converts plain values to signals
- *
- * const $number = writable(5);
- * const $value = readable($number);
- * $number(); // 5
- * $value(); // 5
- * $number.set(6);
- * $number(); // 6
- * $value(); // 6 (tracks value but can't be written)
+ * const [getValue, setValue] = createAtom();
  */
-export declare function readable<T>(signal: MaybeSignal<T>): Signal<T>;
+export declare function createAtom<T>(): AtomAccessors<T | undefined>;
 /**
- * Creates a new signal, returning a getter and setter pair.
+ * Creates a new atom with a value computed from an existing getter.
+ * This is usually used to create a 'settable' getter, in which you can store
+ * a temporary value until it gets overwritten by a _real_ update.
  *
  * @example
- * const [$count, setCount] = signal(0);
- */
-export declare function signal<T>(initialValue: T, options?: SignalOptions<T>): [Signal<T>, Setter<T>];
-export declare function signal<T>(initialValue: undefined, options: SignalOptions<T>): [Signal<T | undefined>, Setter<T | undefined>];
-export declare function signal<T>(): [Signal<T | undefined>, Setter<T | undefined>];
-export interface MemoOptions<T> extends SignalOptions<T> {
-    /**
-     * An array of signals this `memo` depends on. If this is passed, calls to signals within `fn` will NOT be tracked.
-     * Instead the `deps` array will be tracked and `fn` will re-run when any value in `deps` changes.
-     */
-    deps?: Signal<any>[];
-}
-/**
- * Creates a derived signal that recomputes its value only when its dependencies change.
- * Subsequent calls will return a cached value.
- * Dependencies are tracked when called inside `fn` by default,
- * but can be overridden by passing a `deps` array in the options object.
- */
-export declare function memo<T>(compute: (previousValue?: T) => MaybeSignal<T>, options?: MemoOptions<T>): Signal<T>;
-/**
- * Suspends effects during `fn`. Effects for all updated Signal values are called at the end of the batch.
+ * const [getValue, setValue] = createAtom("");
+ * const [getInputValue, setInputValue] = createAtom(getValue);
+ *
+ * setInputValue("temporary");
+ * getValue("");
+ * getInputValue(); // "temporary"
+ *
+ * setValue("overwritten");
+ * getValue("overwritten");
+ * getInputValue(); // "overwritten"
  */
-export declare function batch(fn: () => void): void;
+export declare function createAtom<T>(compute: Getter<T>): AtomAccessors<T>;
 /**
- * Call a Signal function without tracking its value.
+ * Creates a new atom with an initial value.
+ * Returns a `[getter, setter]` function tuple.
+ *
+ * @example
+ * const [getCount, setCount] = createAtom(5);
  */
-export declare function untracked<T>(value: MaybeSignal<T>): T;
+export declare function createAtom<T>(initialValue: T): AtomAccessors<T>;
+export declare function compose<T>(getter: (previousValue?: T) => Getter<T> | T): Getter<T>;
+export declare function createEffect(fn: () => void): () => void;
 /**
- * Unwraps the plain value from a Signal. If the value is not a Signal it is returned as-is.
+ * Unwraps a `MaybeGetter<T>` into a plain `T`.
+ * Tracks the value if it is a getter.
+ * Use the non-tracking `peek` if you're being stealthy.
  */
-export declare function get<T>(value: MaybeSignal<T>): T;
+export declare function unwrap<T>(value: T | Getter<T>): T;
 /**
- * Function to be invoked for the effect. Can return an optional cleanup function to be called between invocations.
+ * Unwraps a `MaybeGetter<T>` into a plain `T`. Will _not_ track if the value is a getter.
  */
-export type EffectFn = () => void | (() => void);
-export type UnsubscribeFn = () => void;
+export declare function peek<T>(value: T | Getter<T>): T;
 /**
- * Creates a tracked scope that re-runs whenever the values of any tracked reactives changes.
- * Reactives are tracked by accessing their `value` within the body of the function.
- *
- * NOTE: You must call the unsubscribe function to clean up the effect.
- * If you are using an effect inside a View or Store, try the `useEffect` hook instead, which cleans up automatically when the component unmounts.
+ * Groups several signal changes into a single transaction.
+ * Suspends effects until `callback` finishes, then runs all updates at once.
  */
-export declare function effect(fn: EffectFn): UnsubscribeFn;
+export declare function batch(callback: () => void): void;
+export declare function subscribe<T>(target: Getter<T>, fn: (value: T) => any): () => void;

package/dist/core/symbols.d.ts

@@ -0,0 +1,2 @@
+export declare const PARENT_ELEMENT: unique symbol;
+export declare const DEBUG: unique symbol;