@manyducks.co/dolla 2.0.0-alpha.23 → 2.0.0-alpha.25

package/README.md

@@ -20,8 +20,8 @@ Let's first get into some examples.
 
 ### Basic State API
 
-```jsx
-import { createState, toState, valueOf, derive, createWatcher } from "@manyducks.co/dolla";
+```js
+import { createState, derive } from "@manyducks.co/dolla";
 
 const [$count, setCount] = createState(72);
 
@@ -35,26 +35,24 @@ $count.get(); // 300
 // You can also pass a function that takes the current value and returns a new one
 setCount((current) => current + 1);
 $count.get(); // 301
+```
 
-// Derive a new state from one or more other states. Whenever $count changes, $doubled will follow.
+Now that you have a state you can derive more states from that one. Derived states automatically stay in sync with the values of their dependencies.
+
+```js
+// Pass and array of one or more states followed by a function that computes a new value.
 const $doubled = derive([$count], (count) => count * 2);
-const $sum = derive([$count, $doubled], (count, doubled) => count + doubled);
 
-// Returns the value of a state. If the value is not a state it is returned as is.
-const count = valueOf($count);
-const bool = valueOf(true);
+$doubled.get(); // 602
 
-// Creates a state from a value. If the value is already a state it is returned as is.
-const $bool = toState(true);
-const $anotherCount = toState($count);
+setCount(500);
 
-const watcher = createWatcher();
+$doubled.get(); // 1000
+```
+
+### In Views
 
-// Watch for changes to the value
-const stop = watcher.watch([$count], (value) => [
-// This function is called immediately with the current value, then again each time the value changes.
-]);
-stop(); // Stop watching for changes
+```jsx
 
 ```
 
@@ -105,12 +103,12 @@ $doubled(); // 100
 $value(); // 50
 ```
 
-## Views [id="section-views"]
+<h2 id="section-views">Views</h2>
 
 A basic view:
 
 ```js
-import Dolla, { createState, html } from "@manyducks.co/dolla";
+import Dolla, { createState } from "@manyducks.co/dolla";
 
 function Counter(props, ctx) {
   const [$count, setCount] = createState(0);
@@ -119,12 +117,24 @@ function Counter(props, ctx) {
     setCount((count) => count + 1);
   }
 
-  return html`
+  function decrement() {
+    setCount((count) => count - 1);
+  }
+
+  function reset() {
+    setCount(0);
+  }
+
+  return (
     <div>
-      <p>Clicks: ${$count}</p>
-      <button onclick=${increment}>+1</button>
+      <p>Clicks: {$count}</p>
+      <div>
+        <button onClick={decrement}>-1</button>
+        <button onClick={reset}>0</button>
+        <button onClick={increment}>-1</button>
+      </div>
     </div>
-  `;
+  );
 }
 
 Dolla.mount(document.body, Counter);

package/dist/core/dolla.d.ts

@@ -2,7 +2,7 @@ import { type CrashViewProps } from "../views/default-crash-view.js";
 import { Batch } from "./batch.js";
 import { type Markup, type MarkupElement } from "./markup.js";
 import { type ViewElement, type ViewFunction } from "./nodes/view.js";
-import { createRef, createSettableState, createState, createWatcher, derive, isRef, toSettableState, toState, valueOf } from "./state.js";
+import { createRef, createState, createWatcher, derive, isRef, isState, toState, toValue } from "./state.js";
 import { HTTP } from "../modules/http.js";
 import { I18n } from "../modules/i18n.js";
 import { Router } from "../modules/router.js";
@@ -52,10 +52,9 @@ export declare class Dolla {
     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;
-    createSettableState: typeof createSettableState;
-    toSettableState: typeof toSettableState;
     toState: typeof toState;
-    valueOf: typeof valueOf;
+    toValue: typeof toValue;
+    isState: typeof isState;
     derive: typeof derive;
     createWatcher: typeof createWatcher;
     createRef: typeof createRef;

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

@@ -15,6 +15,7 @@ export declare class HTML implements MarkupElement {
     stopCallbacks: StopFunction[];
     elementContext: ElementContext;
     uniqueId: string;
+    _batchWrite: (callback: () => void, key?: string) => void;
     ref?: Ref<any>;
     canClickAway: boolean;
     get isMounted(): boolean;
@@ -22,6 +23,7 @@ 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;
     applyProps(element: HTMLElement | SVGElement, props: Record<string, unknown>): void;
     applyStyles(element: HTMLElement | SVGElement, styles: unknown, stopCallbacks: StopFunction[]): () => void;

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

@@ -15,19 +15,16 @@ export declare class Observer implements MarkupElement {
     [TYPE_MARKUP_ELEMENT]: boolean;
     node: Node;
     endNode: Node;
-    connectedViews: MarkupElement[];
+    children: MarkupElement[];
     renderFn: (...values: any) => Renderable;
     elementContext: ElementContext;
-    observerControls: {
-        start: () => void;
-        stop: () => void;
-    };
     watcher: import("../state.js").StateWatcher;
+    sources: State<any>[];
     get isMounted(): boolean;
     constructor({ states, renderFn, elementContext }: ObserverOptions);
     mount(parent: Node, after?: Node): void;
     unmount(parentIsUnmounting?: boolean): void;
     cleanup(parentIsUnmounting: boolean): void;
-    update(...children: Renderable[]): void;
+    update(children: Renderable[]): void;
 }
 export {};

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

@@ -8,11 +8,12 @@ export declare class Outlet implements MarkupElement {
     [TYPE_MARKUP_ELEMENT]: boolean;
     node: Text;
     isMounted: boolean;
-    elements: MaybeState<MarkupElement[]>;
-    children: MarkupElement[];
+    source: MaybeState<MarkupElement[]>;
+    elements: MarkupElement[];
     stopCallback?: StopFunction;
-    constructor(elements: MaybeState<MarkupElement[]>);
+    constructor(source: MaybeState<MarkupElement[]>);
     mount(parent: Node, after?: Node | undefined): void;
     unmount(parentIsUnmounting?: boolean): void;
-    update(newChildren: MarkupElement[]): void;
+    cleanup(parentIsUnmounting: boolean): void;
+    update(newElements: MarkupElement[]): void;
 }

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

@@ -71,6 +71,7 @@ export declare class View<P> implements ViewElement {
     _view: ViewFunction<P>;
     _props: P;
     _element?: MarkupElement;
+    _childMarkup: Markup[];
     _$children: State<MarkupElement[]>;
     _setChildren: import("../state.js").Setter<MarkupElement[], MarkupElement[]>;
     _watcher: import("../state.js").StateWatcher;

package/dist/core/state.d.ts

@@ -1,5 +1,5 @@
 import { strictEqual } from "../utils";
-import { TYPE_SETTABLE_STATE, TYPE_STATE } from "./symbols";
+import { TYPE_STATE } from "./symbols";
 /**
  * Stops the observer that created it when called.
  */
@@ -62,16 +62,25 @@ export interface SettableState<I, O = I> extends State<I> {
      */
     set(callback: (current: I) => O): void;
 }
-export interface Ref<T extends Node> extends State<T | undefined> {
-    node: T | undefined;
+/**
+ *
+ */
+export interface Ref<T> {
+    /**
+     * Get: returns the current value stored in the ref (or undefined).
+     */
+    (): T | undefined;
+    /**
+     * Set: stores a new `value` in the ref.
+     */
+    <T>(value: T | undefined): void;
 }
 export declare function isState<T>(value: any): value is State<T>;
-export declare function isSettableState<T>(value: any): value is SettableState<T>;
 export declare function isRef<T extends Node>(value: any): value is Ref<T>;
 /**
  * Retrieves a plain value from a variable that may be a state.
  */
-export declare function valueOf<T>(value: MaybeState<T>): T;
+export declare function toValue<T>(source: MaybeState<T>): T;
 /**
  * Ensures a variable that may be a state or plain value is a state.
  */
@@ -95,44 +104,44 @@ export declare class Signal<T> implements State<T> {
 /**
  * Creates a state and setter.
  */
-export declare function createState<T>(initialValue: T, options?: CreateStateOptions<T>): [State<T>, Setter<T>];
+export declare function createState<T>(value: T, options?: CreateStateOptions<T>): [State<T>, Setter<T>];
 /**
  * Creates a state and setter.
  */
-export declare function createState<T>(initialValue?: T, options?: CreateStateOptions<T | undefined>): [State<T | undefined>, Setter<T | undefined>];
-export declare class SettableSignal<T> implements State<T>, SettableState<T> {
-    [TYPE_STATE]: boolean;
-    [TYPE_SETTABLE_STATE]: boolean;
-    __value: ValueHolder<T>;
-    constructor(value: ValueHolder<T>);
-    get(): T;
-    set(action: T | ((value: T) => T)): void;
-    watch(callback: (value: T) => void, options?: WatchOptions<T>): () => void;
-}
-/**
- * Creates a SettableState.
- */
-export declare function createSettableState<T>(initialValue: T, options?: CreateStateOptions<T>): SettableState<T>;
-/**
- * Creates a SettableState.
- */
-export declare function createSettableState<T>(initialValue?: T, options?: CreateStateOptions<T | undefined>): SettableState<T | undefined>;
-/**
- * Join a state and its setter into a single SettableState object.
- */
-export declare function toSettableState<I, O = I>($state: State<I>, setter: Setter<I, O>): SettableState<I, O>;
-/**
- * Creates a Setter with custom logic provided by `callback`.
- */
-export declare function createSetter<I, O = I>($state: State<I>, callback: (next: O, current: I) => void): Setter<I, O>;
+export declare function createState<T>(value?: T, options?: CreateStateOptions<T | undefined>): [State<T | undefined>, Setter<T | undefined>];
 export interface DeriveOptions {
     equals?: (next: unknown, current: unknown) => boolean;
 }
-export declare function derive<Inputs extends MaybeState<any>[], T>(states: [...Inputs], fn: (...currentValues: StateValues<Inputs>) => T | State<T>, options?: DeriveOptions): State<T>;
 /**
- * A special kind of State exclusively for storing references to DOM nodes.
+ * Derives a new `State` from one or more existing states.
+ *
+ * @param sources - Array of source states to track.
+ * @param fn - A function called to recompute the value when any tracked source states receive a new value.
+ *
+ * @example
+ * // With one source...
+ * const [$count, setCount] = createState(5);
+ * const $doubled = derive([$count], count => count * 2);
+ * // ... or many:
+ * const [$greeting, setGreeting] = createState("Hello");
+ * const [$name, setName] = createState("World");
+ * const $hello = derive([$greeting, name], (greeting, name) => `${greeting}, ${name}!`);
+ */
+export declare function derive<Sources extends MaybeState<any>[], T>(sources: [...Sources], fn: (...values: StateValues<Sources>) => T | State<T>, options?: DeriveOptions): State<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 ref = createRef(5);
+ * ref(); // 5
+ * ref(500);
+ * ref(); // 500
  */
-export declare function createRef<T extends Node>(): Ref<T>;
+export declare function createRef<T>(value?: T): Ref<T>;
 export interface StateWatcher {
     /**
      * Watch one or more states, calling the provided `fn` each time one of their values changes.

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-export { createRef, createSettableState, createSetter, createState, derive, isRef, toSettableState, toState, valueOf, } from "./core/state.js";
-export type { MaybeState, Ref, SettableState, State, StopFunction } from "./core/state.js";
-export { strictEqual, shallowEqual, deepEqual } from "./utils.js";
+export { createRef, createState, derive, isRef, isState, toState, toValue } from "./core/state.js";
+export type { MaybeState, Ref, Setter, State, StopFunction } from "./core/state.js";
+export { deepEqual, shallowEqual, strictEqual } from "./utils.js";
 export { cond, createMarkup, html, portal, repeat } from "./core/markup.js";
 export type { Markup, MarkupElement } from "./core/markup.js";
 import { Dolla } from "./core/dolla.js";
@@ -10,9 +10,9 @@ export declare const t: (selector: string, options?: import("./modules/i18n.js")
 export declare function setDevDebug(value: boolean): void;
 export declare function getDevDebug(): boolean;
 export type { Dolla, Environment, Logger, LoggerErrorContext, LoggerOptions, Loggles } from "./core/dolla.js";
+export type { ViewContext, ViewElement, ViewFunction } from "./core/nodes/view.js";
 export type { HTTPRequest, HTTPResponse } from "./modules/http.js";
 export type { InputType, Renderable } from "./types.js";
-export type { ViewContext, ViewFunction, ViewElement as ViewNode } from "./core/nodes/view.js";
 export type { CrashViewProps } from "./views/default-crash-view.js";
 import type { IntrinsicElements as Elements } from "./types";
 declare global {