@manyducks.co/dolla 2.0.0 → 3.0.0

package/dist/core/context.d.ts

@@ -1,147 +1,23 @@
-import type { Store } from "../types";
-import { type Logger, type LoggerOptions } from "./logger";
-import { type EffectFn, type MaybeSignal, type UnsubscribeFn } from "./signals";
-export declare enum LifecycleEvent {
-    WILL_MOUNT = "willMount",
-    DID_MOUNT = "didMount",
-    WILL_UNMOUNT = "willUnmount",
-    DID_UNMOUNT = "didUnmount",
-    DISPOSE = "dispose"
-}
-export type LifecycleEventName = "willMount" | "didMount" | "willUnmount" | "didUnmount" | "dispose";
-type LifecycleListener = () => void;
-declare enum LifecycleState {
-    Unmounted = 0,
-    WillMount = 1,
-    DidMount = 2,
-    WillUnmount = 3,
-    DidUnmount = 4,
-    Disposed = 5
-}
-declare const NAME: unique symbol;
-declare const LIFECYCLE: unique symbol;
-declare const PARENT: unique symbol;
-declare const STORES: unique symbol;
-declare const STATE: unique symbol;
-/**
- * Manages lifecycle events for a Context.
- */
-declare class ContextLifecycle {
-    private context;
-    state: LifecycleState;
-    listeners: Map<LifecycleEvent, Set<LifecycleListener>>;
-    bound?: Set<Context>;
-    constructor(context: Context);
-    /**
-     * Listen for a certain event to be emitted. Listeners are called when the event results in a state change.
-     */
-    on<E extends LifecycleEvent>(event: E, listener: LifecycleListener): void;
-    /**
-     * Stop a particular listener from being called when an event is emitted.
-     */
-    off<E extends LifecycleEvent>(event: E, listener: LifecycleListener): void;
-    /**
-     * Advance the lifecycle state machine.
-     */
-    emit<E extends LifecycleEvent>(event: E): void;
-    /**
-     * Bind `context` to this lifecycle; when any event is emitted here it will be emitted for `context` as well.
-     */
-    bind(context: Context): void;
-    /**
-     * Call all the event's listeners and re-emit to bound contexts.
-     */
-    private notify;
-}
-export interface ContextGetStateOptions<T> {
-    fallback?: T;
-    /**
-     * Only check this context; skip parent contexts.
-     */
-    immediate?: boolean;
-}
-export interface ContextGetStateOptionsWithFallbackValue<T> extends ContextGetStateOptions<T> {
-    fallback: T;
-}
-export interface ContextGetStateMapOptions {
-    /**
-     * Only include state from this context; skip parent contexts.
-     */
-    immediate?: boolean;
-}
-export interface ContextOptions {
-    logger?: LoggerOptions;
-}
-export interface LinkedContextOptions extends ContextOptions {
-    bindLifecycleToParent?: boolean;
-}
-export interface Context extends Logger {
-}
-export declare class Context implements Logger {
-    #private;
-    [NAME]: string;
-    [LIFECYCLE]: ContextLifecycle;
-    [PARENT]?: Context;
-    [STORES]?: Map<Store<any, any>, any>;
-    [STATE]?: Map<any, any>;
-    get isMounted(): boolean;
-    /**
-     * Returns a new Context with this one as its parent.
-     */
-    static createChildOf(parent: Context, name: MaybeSignal<string>, options?: LinkedContextOptions): Context;
-    /**
-     * Emit a lifecycle event to `context`.
-     */
-    static emit(context: Context, event: LifecycleEvent): void;
-    constructor(name: MaybeSignal<string>, options?: ContextOptions);
-    /**
-     * Returns the current name of this context.
-     */
-    getName(): string;
-    /**
-     * Sets a new name for this context.
-     */
-    setName(name: MaybeSignal<string>): void;
-    /**
-     * Creates an instance of a store and attaches it to this context.
-     */
-    provideStore<T>(store: Store<any, T>, options?: any): this;
-    /**
-     * Retrieves the nearest instance of `store`. If this context doesn't have it, the parent context is checked. This process continues until either:
-     * 1. An instance of the store is found and returned.
-     * 2. No instance is found and an error is thrown.
-     */
-    useStore<T>(store: Store<any, T>): T;
-    /**
-     * Registers a `listener` to be called at a specific transition point during this context's lifecycle.
-     *
-     * Prefer `useMount` and `useUnmount` hooks for general usage.
-     */
-    onLifecycleTransition(event: LifecycleEventName, listener: LifecycleListener): () => void;
-    effect(callback: EffectFn): UnsubscribeFn;
-    /**
-     * Gets the value stored at `key`, or returns `options.fallback` if none is set.
-     */
-    getState<T>(key: any, options: ContextGetStateOptionsWithFallbackValue<T>): T;
-    /**
-     * Gets the value stored at `key`, or throws an error if none is set.
-     */
-    getState<T>(key: any, options?: ContextGetStateOptions<T>): T;
-    /**
-     * Returns a Map containing all state values available to this context.
-     *
-     * Pass `options.immediate` to only include state stored on this context.
-     * By default all state stored on parent contexts is also included.
-     */
-    getStateMap(options?: ContextGetStateMapOptions): Map<any, any>;
-    /**
-     * Stores `value` at `key` in this context's state.
-     */
-    setState<T>(key: any, value: T): void;
-    /**
-     * For each tuple in `entries`, stores `value` at `key` in this context's state.
-     */
-    setState(entries: [key: any, value: any][]): void;
-}
-export declare function createContext(name: MaybeSignal<string>, options?: ContextOptions): Context;
+import type { Store } from "../types.js";
+export type LifecycleListener = () => any;
+type ContextState = {
+    isMounted: boolean;
+};
+export type ComponentState = ContextState & {
+    name: string;
+};
+export type Context<T = Record<string | symbol, any>> = ContextState & T;
+export declare function createContext(parent?: Context): Context;
+export declare function mountContext(context: Context): void;
+export declare function unmountContext(context: Context): void;
+export declare function onMount(context: Context, fn: LifecycleListener): void;
+export declare function onCleanup(context: Context, fn: LifecycleListener): void;
+export declare function onEffect(context: Context, fn: () => void): void;
+export declare const STORE_ID: unique symbol;
+export declare function addStore<Props, Returns>(context: Context, store: Store<Props, Returns> & {
+    [STORE_ID]?: symbol;
+}, ...args: undefined extends Props ? [props?: Props] : [props: Props]): Returns;
+export declare function getStore<Returns>(context: Context, store: Store<any, Returns> & {
+    [STORE_ID]?: symbol;
+}): Returns;
 export {};

package/dist/core/debug.d.ts

@@ -0,0 +1,19 @@
+import { Context } from "./context.js";
+export declare const noOp: () => void;
+export type LogLevel = "info" | "log" | "warn" | "error" | "silent";
+export declare const setLogLevel: (level: LogLevel) => void;
+export declare const setLogFilter: (filter: (name: string) => boolean) => void;
+export declare function getDebug(context: Context, ...tags: [string, any][]): {
+    readonly info: (...args: any[]) => void;
+    readonly trace: (...args: any[]) => void;
+    readonly log: (...args: any[]) => void;
+    readonly warn: (...args: any[]) => void;
+    readonly error: (...args: any[]) => void;
+};
+export declare function createDebug(name: string, ...tags: [string, any][]): {
+    readonly info: (...args: any[]) => void;
+    readonly trace: (...args: any[]) => void;
+    readonly log: (...args: any[]) => void;
+    readonly warn: (...args: any[]) => void;
+    readonly error: (...args: any[]) => void;
+};

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, 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 { forEach, showIf, hideIf, createPortal } 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;