@manyducks.co/dolla 2.0.0-alpha.33 → 2.0.0-alpha.35

package/README.md

@@ -7,7 +7,7 @@
 
 Dolla is a batteries-included JavaScript frontend framework covering the needs of moderate-to-complex single page apps:
 
-- ⚡ Reactive DOM updates with [State](./docs/state.md). Inspired by Signals, but with explicit tracking.
+- ⚡ Reactive DOM updates with [Signals](./docs/state.md).
 - 📦 Reusable components with [Views](./docs/views.md).
 - 💾 Reusable state management with [Stores](./docs/stores.md).
 - 🔀 Built-in [routing](./docs/router.md) with nested routes and middleware support (check login status, preload data, etc).
@@ -35,22 +35,20 @@ Dolla's goals include:
 A basic view. Note that the view function is called exactly once when the view is first mounted. All changes to DOM nodes thereafter happen as a result of `$state` values changing.
 
 ```js
-import Dolla, { createState } from "@manyducks.co/dolla";
+import Dolla, { atom, html } from "@manyducks.co/dolla";
 
 function Counter() {
-  const [$count, setCount] = createState(0);
+  const count = atom(0);
 
-  function increment() {
-    setCount((count) => count + 1);
-  }
-
-  function decrement() {
-    setCount((count) => count - 1);
-  }
-
-  function reset() {
-    setCount(0);
-  }
+  return html`
+    <div>
+      <p>Counter: ${count}</p>
+      <div>
+        <button onclick=${() => count.value--}>-1</button>
+        <button onclick=${() => count.value++}>+1</button>
+      </div>
+    </div>
+  `;
 
   return (
     <div>

package/dist/core/{batch.d.ts → _batch.d.ts}

@@ -7,11 +7,15 @@ export declare class Batch {
     constructor(dolla: Dolla);
     /**
      * Queues a callback that runs before the next batch of writes.
+     *
+     * @deprecated
      */
     read(callback: () => void): void;
     /**
      * Queues a callback to run in the next render batch.
      * Always put DOM mutations in a write callback when possible to help Dolla batch them efficiently.
+     *
+     * @deprecated
      */
     write(callback: () => void, key?: string): void;
 }

package/dist/core/context.d.ts

@@ -1,8 +1,14 @@
 import type { Emitter } from "@manyducks.co/emitter";
 import type { Dolla } from "./dolla";
 import type { Store, StoreFunction } from "./store";
-interface ContextEmitterEvents {
-    [eventName: string | symbol]: [ContextEvent, ...args: any[]];
+export interface GenericEvents {
+    [type: string]: [...args: any[]];
+}
+export interface GenericContextData {
+    [key: string | symbol]: any;
+}
+export interface ContextEmitterEvents {
+    [type: string | symbol]: [ContextEvent, ...args: any[]];
 }
 export interface ElementContext {
     /**
@@ -40,36 +46,32 @@ export interface ElementContext {
  * ContextEvent objects already have the event name stored as `event.type`.
  */
 export type WildcardListenerMap = Map<(event: ContextEvent, ...args: any[]) => void, (eventName: string | symbol, event: ContextEvent, ...args: any[]) => void>;
-export interface ComponentContext {
+export interface ComponentContext<Events extends GenericEvents = GenericEvents> {
     /**
-     * Sets a context variable and returns its value.
+     * A name for debugging purposes. Prepended to log messages.
      */
-    set<T>(key: string | symbol, value: T): T;
-    /**
-     * Gets the value of a context variable. Returns null if the variable is not set.
-     */
-    get<T>(key: string | symbol): T | null;
+    name: string;
     /**
      * Adds a listener to be called when an event with a matching `type` is emitted.
      */
-    on<T = unknown>(type: string, listener: (event: ContextEvent, ...args: any[]) => void): void;
+    on<T extends keyof Events>(type: T, listener: (event: ContextEvent, ...args: Events[T]) => void): void;
     /**
      * Removes a listener from the list to be called when an event with a matching `type` is emitted.
      */
-    off<T = unknown>(type: string, listener: (event: ContextEvent, ...args: any[]) => void): void;
+    off(type: string, listener: (event: ContextEvent, ...args: any[]) => void): void;
     /**
      * Adds a listener to be called when an event with a matching `type` is emitted. The listener is immediately removed after being called once.
      */
-    once<T = unknown>(type: string, listener: (event: ContextEvent, ...args: any[]) => void): void;
+    once<T extends keyof Events>(type: T, listener: (event: ContextEvent, ...args: Events[T]) => void): void;
     /**
      * Emits a new event to all listeners.
      */
-    emit<T = unknown>(type: string, ...args: any[]): boolean;
+    emit<T extends keyof Events>(type: T, ...args: Events[T]): boolean;
 }
 /**
- * A context capable of hosting stores.
+ * A context capable of providing stores.
  */
-export interface StorableContext extends ComponentContext {
+export interface StoreProviderContext {
     /**
      * Attaches a new store to this context and returns it.
      */
@@ -82,10 +84,12 @@ export interface StorableContext extends ComponentContext {
      * Attaches a new store to this context and returns it.
      */
     provide<Options, Value>(store: StoreFunction<Options, Value>, options: Options): Value;
+}
+export interface StoreConsumerContext {
     /**
      * Gets the closest instance of a store. Throws an error if the store isn't provided higher in the tree.
      */
-    use<Value>(store: StoreFunction<any, Value>): Value;
+    get<Value>(store: StoreFunction<any, Value>): Value;
 }
 /**
  * An event emitted from and received by a Dolla context. These are separate from DOM events.
@@ -98,4 +102,3 @@ export declare class ContextEvent {
     stop(): void;
     get [Symbol.toStringTag](): string;
 }
-export {};

package/dist/core/dolla.d.ts

@@ -1,13 +1,10 @@
-import { HTTP } from "../modules/http.js";
-import { I18n } from "../modules/i18n.js";
-import { type Router } from "../modules/router.js";
-import { type CrashViewProps } from "../views/default-crash-view.js";
-import { Batch } from "./batch.js";
-import { ContextEvent, type StorableContext } from "./context.js";
+import { HTTP } from "../http/index.js";
+import { I18n } from "../translate/index.js";
+import { type Router } from "../router/index.js";
+import { type CrashViewProps } from "./views/default-crash-view.js";
+import { type StoreProviderContext, type StoreConsumerContext } from "./context.js";
 import { type Markup, type MarkupElement } from "./markup.js";
 import { type ViewElement, type ViewFunction } from "./nodes/view.js";
-import { createRef, isRef } from "./ref.js";
-import { createState, createWatcher, derive, isState, toState, toValue } from "./state.js";
 import { StoreFunction } from "./store.js";
 export type Environment = "development" | "production";
 /**
@@ -42,22 +39,11 @@ export type LoggerOptions = {
      */
     uid?: string;
 };
-export declare class Dolla implements StorableContext {
+export declare class Dolla implements StoreProviderContext, StoreConsumerContext {
     #private;
-    readonly batch: Batch;
-    private readonly stats;
     readonly http: HTTP;
     readonly i18n: I18n;
     constructor();
-    watch: <I extends import("./state.js").MaybeState<any>[]>(states: [...I], fn: (...currentValues: import("./state.js").StateValues<I>) => void) => import("./state.js").StopFunction;
-    createState: typeof createState;
-    toState: typeof toState;
-    toValue: typeof toValue;
-    isState: typeof isState;
-    derive: typeof derive;
-    createWatcher: typeof createWatcher;
-    createRef: typeof createRef;
-    isRef: typeof isRef;
     /**
      * True when the app is connected to a DOM node and displayed to the user.
      */
@@ -85,33 +71,6 @@ export declare class Dolla implements StorableContext {
      * Returns the top level view Dolla is rendering inside the root element. This will return undefined until Dolla.mount() is called.
      */
     getRootView(): ViewElement | undefined;
-    /**
-     * Sets a context variable and returns its value. Context variables are accessible on the app and in child views.
-     */
-    set<T>(key: string | symbol, value: T): T;
-    /**
-     * Gets the value of a context variable. Returns null if the variable is not set.
-     */
-    get<T>(key: string | symbol): T | null;
-    /**
-     * Returns an object of all context variables stored at the app level.
-     */
-    /**
-     * Adds a listener to be called when an event with a matching `type` is emitted.
-     */
-    on<T = unknown>(type: string, listener: (event: ContextEvent, ...args: any[]) => void): void;
-    /**
-     * Removes a listener from the list to be called when an event with a matching `type` is emitted.
-     */
-    off<T = unknown>(type: string, listener: (event: ContextEvent, ...args: any[]) => void): void;
-    /**
-     * Adds a listener to be called when an event with a matching `type` is emitted. The listener is immediately removed after being called once.
-     */
-    once<T = unknown>(type: string, listener: (event: ContextEvent, ...args: any[]) => void): void;
-    /**
-     * Emits a new event to all listeners.
-     */
-    emit<T = unknown>(type: string, ...args: any[]): boolean;
     /**
      * Attaches a new store to this context.
      */
@@ -127,7 +86,7 @@ export declare class Dolla implements StorableContext {
     /**
      * Gets the nearest instance of a store. Throws an error if the store isn't provided higher in the tree.
      */
-    use<Value>(store: StoreFunction<any, Value>): Value;
+    get<Value>(store: StoreFunction<any, Value>): Value;
     mount(selector: string, router: Router): Promise<void>;
     mount(selector: string, view: ViewFunction<any>): Promise<void>;
     mount(element: Element, router: Router): Promise<void>;

package/dist/core/markup.d.ts

@@ -1,28 +1,7 @@
 import type { Renderable } from "../types.js";
 import type { ElementContext } from "./context.js";
 import { type ViewContext, type ViewFunction, type ViewResult } from "./nodes/view.js";
-import { type MaybeState, type State } from "./state.js";
-import { IS_MARKUP } from "./symbols.js";
-export declare class _Markup implements Markup {
-    [IS_MARKUP]: boolean;
-    static text(value: MaybeState<string>): _Markup;
-    static from(renderable: Renderable): Markup;
-    /**
-     * In the case of a view, type will be the View function itself. It can also hold an identifier for special nodes like "$cond", "$repeat", etc.
-     * DOM nodes can be created by name, such as HTML elements like "div", "ul" or "span", SVG elements like ""
-     */
-    type: string | ViewFunction<any>;
-    /**
-     * Data that will be passed to a new MarkupElement instance when it is constructed.
-     */
-    props: Record<string, any> | undefined;
-    /**
-     *
-     */
-    children: Markup[];
-    constructor(type: string | ViewFunction<any>, props?: Record<string, any>, children?: Renderable[]);
-    toElement(context: ElementContext): MarkupElement;
-}
+import { MaybeReactive, type Reactive } from "./signals.js";
 /**
  * Markup is a set of element metadata that hasn't been constructed into a MarkupElement yet.
  */
@@ -61,17 +40,16 @@ export interface MarkupAttributes {
     $text: {
         value: any;
     };
-    $repeat: {
-        $items: State<any[]>;
+    $list: {
+        items: Reactive<any[]>;
         keyFn: (value: any, index: number) => string | number | symbol;
-        renderFn: ($item: State<any>, $index: State<number>, c: ViewContext) => ViewResult;
+        renderFn: (item: Reactive<any>, index: Reactive<number>, ctx: ViewContext) => ViewResult;
     };
-    $observer: {
-        sources: MaybeState<any>[];
-        renderFn: (...items: any) => Renderable;
+    $dynamic: {
+        source: Reactive<Renderable>;
     };
     $outlet: {
-        $children: State<MarkupElement[]>;
+        children: MaybeReactive<MarkupElement[]>;
     };
     $node: {
         value: Node;
@@ -91,12 +69,12 @@ export declare const html: (strings: TemplateStringsArray, ...values: any[]) =>
 /**
  * Displays content conditionally. When `condition` holds a truthy value, `thenContent` is displayed; when `condition` holds a falsy value, `elseContent` is displayed.
  */
-export declare function cond(condition: MaybeState<any>, thenContent?: Renderable, elseContent?: Renderable): Markup;
+export declare function cond(condition: MaybeReactive<any>, thenContent?: Renderable, elseContent?: Renderable): Markup;
 /**
  * Calls `renderFn` for each item in `items`. Dynamically adds and removes views as items change.
  * The result of `keyFn` is used to compare items and decide if item was added, removed or updated.
  */
-export declare function repeat<T>(items: MaybeState<T[]>, keyFn: (value: T, index: number) => string | number | symbol, renderFn: ($value: State<T>, $index: State<number>, ctx: ViewContext) => ViewResult): Markup;
+export declare function list<T>(items: MaybeReactive<T[]>, keyFn: (value: T, index: number) => string | number | symbol, renderFn: (item: Reactive<T>, index: Reactive<number>, ctx: ViewContext) => ViewResult): Markup;
 /**
  * Renders `content` into a `parent` node anywhere in the page, rather than its usual position in the view.
  */

package/dist/core/nodes/{observer.d.ts → dynamic.d.ts}

@@ -1,27 +1,25 @@
 import type { Renderable } from "../../types.js";
 import type { ElementContext } from "../context.js";
 import { type MarkupElement } from "../markup.js";
-import { type MaybeState } from "../state.js";
+import { type Reactive, type UnsubscribeFunction } from "../signals.js";
 import { IS_MARKUP_ELEMENT } from "../symbols.js";
-interface ObserverOptions {
+interface DynamicOptions {
+    source: Reactive<Renderable>;
     elementContext: ElementContext;
-    sources: MaybeState<any>[];
-    renderFn: (...values: any) => Renderable;
 }
 /**
  * Displays dynamic children without a parent element.
- * Used when a State is passed as a child in a view template.
+ * Renders a Reactive value via a render function.
  */
-export declare class Observer implements MarkupElement {
+export declare class Dynamic implements MarkupElement {
     [IS_MARKUP_ELEMENT]: boolean;
     node: Text;
     children: MarkupElement[];
-    renderFn: (...values: any) => Renderable;
     elementContext: ElementContext;
-    watcher: import("../state.js").StateWatcher;
-    sources: MaybeState<any>[];
+    source: Reactive<Renderable>;
+    unsubscribe?: UnsubscribeFunction;
     get isMounted(): boolean;
-    constructor({ sources, renderFn, elementContext }: ObserverOptions);
+    constructor(options: DynamicOptions);
     mount(parent: Node, after?: Node): void;
     unmount(parentIsUnmounting?: boolean): void;
     cleanup(parentIsUnmounting: boolean): void;

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

@@ -1,7 +1,7 @@
 import { type ElementContext } from "../context.js";
 import { type Markup, type MarkupElement } from "../markup.js";
 import { type Ref } from "../ref.js";
-import { type State, type StopFunction } from "../state.js";
+import { type MaybeReactive, type UnsubscribeFunction } from "../signals.js";
 import { IS_MARKUP_ELEMENT } from "../symbols.js";
 type HTMLOptions = {
     elementContext: ElementContext;
@@ -15,10 +15,9 @@ export declare class HTML implements MarkupElement {
     props: Record<string, any>;
     childMarkup: Markup[];
     children: MarkupElement[];
-    stopCallbacks: StopFunction[];
+    unsubscribers: UnsubscribeFunction[];
     elementContext: ElementContext;
     uniqueId: string;
-    _batchWrite: (callback: () => void, key?: string) => void;
     ref?: Ref<any>;
     canClickAway: boolean;
     get isMounted(): boolean;
@@ -26,11 +25,10 @@ export declare class HTML implements MarkupElement {
     mount(parent: Node, after?: Node): void;
     unmount(parentIsUnmounting?: boolean): void;
     getUpdateKey(type: string, value: string | number): string;
-    _mutate(callback: () => any, updateKey?: string): void;
-    attachProp<T>(value: State<T> | T, callback: (value: T) => void, updateKey: string): void;
+    attachProp<T>(value: MaybeReactive<T>, callback: (value: T) => void): void;
     applyProps(element: HTMLElement | SVGElement, props: Record<string, unknown>): void;
-    applyStyles(element: HTMLElement | SVGElement, styles: unknown, stopCallbacks: StopFunction[]): () => void;
-    applyClasses(element: HTMLElement | SVGElement, classes: unknown, stopCallbacks: StopFunction[]): () => void;
+    applyStyles(element: HTMLElement | SVGElement, styles: unknown, unsubscribers: UnsubscribeFunction[]): () => void;
+    applyClasses(element: HTMLElement | SVGElement, classes: unknown, unsubscribers: UnsubscribeFunction[]): () => void;
 }
 /**
  * Converts a camelCase string to kebab-case.

package/dist/core/nodes/{repeat.d.ts → list.d.ts}

@@ -1,33 +1,31 @@
 import { type ElementContext } from "../context.js";
 import { type MarkupElement } from "../markup.js";
-import { type Setter, type State, type StopFunction } from "../state.js";
+import { type Atom, type Reactive, type UnsubscribeFunction } from "../signals.js";
 import { IS_MARKUP_ELEMENT } from "../symbols.js";
 import { type ViewContext, type ViewResult } from "./view.js";
-interface RepeatOptions<T> {
+interface ListOptions<T> {
     elementContext: ElementContext;
-    $items: State<T[]>;
-    keyFn: (value: T, index: number) => string | number | symbol;
-    renderFn: ($value: State<T>, $index: State<number>, ctx: ViewContext) => ViewResult;
+    items: Reactive<T[]>;
+    keyFn: (item: T, index: number) => string | number | symbol;
+    renderFn: (item: Reactive<T>, index: Reactive<number>, ctx: ViewContext) => ViewResult;
 }
 type ConnectedItem<T> = {
     key: any;
-    $value: State<T>;
-    setValue: Setter<T>;
-    $index: State<number>;
-    setIndex: Setter<number>;
+    item: Atom<T>;
+    index: Atom<number>;
     element: MarkupElement;
 };
-export declare class Repeat<T> implements MarkupElement {
+export declare class List<T> implements MarkupElement {
     [IS_MARKUP_ELEMENT]: boolean;
     node: Text;
-    $items: State<T[]>;
-    stopCallback?: StopFunction;
+    items: Reactive<T[]>;
+    unsubscribe: UnsubscribeFunction | null;
     connectedItems: ConnectedItem<T>[];
     elementContext: ElementContext;
-    renderFn: (this: ViewContext, $value: State<T>, $index: State<number>, context: ViewContext) => ViewResult;
+    renderFn: (this: ViewContext, value: Reactive<T>, index: Reactive<number>, context: ViewContext) => ViewResult;
     keyFn: (value: T, index: number) => string | number | symbol;
     get isMounted(): boolean;
-    constructor({ elementContext, $items, renderFn, keyFn }: RepeatOptions<T>);
+    constructor({ elementContext, items, renderFn, keyFn }: ListOptions<T>);
     mount(parent: Node, after?: Node): void;
     unmount(parentIsUnmounting?: boolean): void;
     _cleanup(parentIsUnmounting: boolean): void;

package/dist/core/nodes/outlet.d.ts

@@ -1,5 +1,5 @@
 import { type MarkupElement } from "../markup.js";
-import { type MaybeState, type StopFunction } from "../state.js";
+import { type MaybeReactive, type UnsubscribeFunction } from "../signals.js";
 import { IS_MARKUP_ELEMENT } from "../symbols.js";
 /**
  * Manages several MarkupElements as one.
@@ -8,10 +8,10 @@ export declare class Outlet implements MarkupElement {
     [IS_MARKUP_ELEMENT]: boolean;
     node: Text;
     isMounted: boolean;
-    source: MaybeState<MarkupElement[]>;
+    source: MaybeReactive<MarkupElement[]>;
     elements: MarkupElement[];
-    stopCallback?: StopFunction;
-    constructor(source: MaybeState<MarkupElement[]>);
+    unsubscribe?: UnsubscribeFunction;
+    constructor(source: MaybeReactive<MarkupElement[]>);
     mount(parent: Node, after?: Node | undefined): void;
     unmount(parentIsUnmounting?: boolean): void;
     cleanup(parentIsUnmounting: boolean): void;

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

@@ -1,13 +1,13 @@
 import { Emitter } from "@manyducks.co/emitter";
-import { type ElementContext, type StorableContext, type WildcardListenerMap } from "../context.js";
+import { type ComponentContext, type ElementContext, type GenericEvents, type StoreConsumerContext, type StoreProviderContext, type WildcardListenerMap } from "../context.js";
 import type { Logger } from "../dolla.js";
-import { type Markup, type MarkupElement } from "../markup.js";
-import { type MaybeState, type State, type StateValues, type StopFunction } from "../state.js";
+import { cond, list, portal, type Markup, type MarkupElement } from "../markup.js";
+import { type EffectCallback, type Reactive, type UnsubscribeFunction } from "../signals.js";
 import { IS_MARKUP_ELEMENT } from "../symbols.js";
 /**
  * Any valid value that a View can return.
  */
-export type ViewResult = Node | State<any> | Markup | Markup[] | null;
+export type ViewResult = Node | Reactive<any> | Markup | Markup[] | null;
 export type ViewFunction<P> = (this: ViewContext, props: P, context: ViewContext) => ViewResult;
 /**
  * A view that has been constructed into DOM nodes.
@@ -18,18 +18,11 @@ export interface ViewElement extends MarkupElement {
      */
     setChildView(view: ViewFunction<{}>): ViewElement;
 }
-export interface ViewContext extends Logger, StorableContext {
+export interface ViewContext<Events extends GenericEvents = GenericEvents> extends Omit<Logger, "setName">, ComponentContext<Events>, StoreProviderContext, StoreConsumerContext {
     /**
      * An ID unique to this view.
      */
     readonly uid: string;
-    /**
-     * Returns an object of all variables stored on this context.
-     */
-    /**
-     * Sets the name of the view's built in logger.
-     */
-    setName(name: string): ViewContext;
     /**
      * True while this view is connected to the DOM.
      */
@@ -51,14 +44,26 @@ export interface ViewContext extends Logger, StorableContext {
      */
     onUnmount(callback: () => void): void;
     /**
-     * Watch a set of states. The callback is called when any of the states receive a new value.
-     * Watchers will be automatically stopped when this view is unmounted.
+     * Passes a getter function to `callback` that will track reactive states and return their current values.
+     * Callback will be run each time a tracked state gets a new value.
+     */
+    effect(callback: EffectCallback): UnsubscribeFunction;
+    /**
+     * Renders a list of reactive items.
+     */
+    list: typeof list;
+    /**
+     * Creates a reactive conditional; the second argument is displayed when the condition is true and the third is displayed when the condition is false.
      */
-    watch<T extends MaybeState<any>[]>(states: [...T], callback: (...values: StateValues<T>) => void): StopFunction;
+    if: typeof cond;
     /**
      * Returns a Markup element that displays this view's children.
      */
     outlet(): Markup;
+    /**
+     * Displays an element as a child of another DOM node, rather than the position it would normally be mounted at.
+     */
+    portal: typeof portal;
 }
 type ViewEvents = {
     beforeMount: [];
@@ -75,9 +80,8 @@ export declare class View<P> implements ViewElement {
     _props: P;
     _element?: MarkupElement;
     _childMarkup: Markup[];
-    _$children: State<MarkupElement[]>;
-    _setChildren: import("../state.js").Setter<MarkupElement[], MarkupElement[]>;
-    _watcher: import("../state.js").StateWatcher;
+    _children: import("../signals.js").Atom<MarkupElement[]>;
+    _unsubscribes: UnsubscribeFunction[];
     _emitter: Emitter<ViewEvents>;
     _wildcardListeners: WildcardListenerMap;
     constructor(elementContext: ElementContext, view: ViewFunction<P>, props: P, children?: Markup[]);

package/dist/core/ref.d.ts

@@ -19,6 +19,8 @@ export interface Ref<T> {
  *
  * @param value - An (optional) initial value to store.
  *
+ * @deprecated
+ *
  * @example
  * const ref = createRef(5);
  * ref(); // 5
@@ -26,4 +28,18 @@ export interface Ref<T> {
  * ref(); // 500
  */
 export declare function createRef<T>(value?: T): Ref<T>;
+/**
+ * A Ref is a function that returns the last argument it was called with.
+ * Calling it with no arguments will simply return the latest value.
+ * Calling it with an argument will store that value and immediately return it.
+ *
+ * @param value - An (optional) initial value to store.
+ *
+ * @example
+ * const number = ref(5);
+ * number(); // 5
+ * number(500);
+ * number(); // 500
+ */
+export declare function ref<T>(value?: T): Ref<T>;
 export declare function isRef<T extends Node>(value: any): value is Ref<T>;