@manyducks.co/dolla 2.0.0-alpha.66 → 2.0.0-alpha.68

package/README.md

@@ -15,52 +15,53 @@ Dolla is a batteries-included JavaScript frontend framework covering the needs o
 - 📍 Lightweight [localization](./docs/i18n.md) system (store translated strings in JSON files and call the `t` function to get them).
 - 🍳 Build system optional. [Write views in JSX](./docs/setup.md) or bring in [HTM](https://github.com/developit/htm) and use tagged template literals directly in the browser.
 
-Dolla's goals include:
+Dolla's goals:
 
 - Be fun to create with.
 - Be snappy and responsive for real life apps.
-- Be compact as possible but not at the expense of necessary features.
+- Be as compact as possible but not at the expense of necessary features.
 
-## Why Dolla?
+## DEV TO-DO
 
-> TODO: Write about why Dolla was started and what it's all about.
-
-- Borne of frustration using React and similar libs (useEffect, referential equality, a pain to integrate other libs into its lifecycle, need to hunt for libraries to move much beyond Hello World).
-- Merges ideas from my favorite libraries and frameworks (Solid/Knockout, Choo, Svelte, i18next, etc) into one curated set designed to work well together.
-- Opinionated (with the _correct_ opinions).
-- Many mainstream libraries seem too big for what they do. The entirety of Dolla is less than half the size of [`react-router`](https://bundlephobia.com/package/react-router@7.1.5).
+- Make sure docs are correct and accurate.
+- Release v2.0.0
 
 ## An Example
 
 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.
 
 ```jsx
-import { $, effect, when, mount } from "@manyducks.co/dolla";
-
-function Counter(props, ctx) {
-  const $count = $(0);
+import { useSignal, useEffect, createApp } from "@manyducks.co/dolla";
 
-  effect(() => {
-    console.log("Count is: " + $count());
-    // An effect will re-run whenever any signal accessed inside it receives a new value.
-  });
+function Counter() {
+  const [$count, setCount] = useSignal();
 
   function reset() {
-    $count.set(0);
+    setCount(0);
   }
 
   function increment() {
-    $count.set((current) => current + 1);
+    setCount((current) => current + 1);
   }
 
   function decrement() {
-    $count.set((current) => current - 1);
+    setCount((current) => current - 1);
   }
 
+  // Runs once when the view is mounted, then again every time $count receives a new value.
+  useEffect(() => {
+    console.log("Count is: " + $count());
+  });
+
   return (
     <div>
-      <p>Counter: {$count}</p>
       {/* Signals can be slotted into the DOM to render them */}
+      <p>Counter: {$count}</p>
+
+      {/* Signals are just functions that return a value, so you can compose them on the fly */}
+      <Show when={() => $count() > 100}>
+        <p>That's a lot of clicks.</p>
+      </Show>
 
       <div>
         <button onClick={increment}>+1</button>
@@ -71,60 +72,8 @@ function Counter(props, ctx) {
   );
 }
 
-mount(Counter, document.body);
-```
-
-> TODO: Show small examples for routing and stores.
-
-```js
-function MessageStore(options, ctx) {
-  const message = $("Hello world!");
-
-  ctx.effect(() => {
-    ctx.log(`Message is now: ${message()}`);
-    // Calling `get()` inside an effect (or compose) function will track that reactive value as a dependency.
-    // Effects will re-run when a dependency updates.
-  });
-  // `ctx` refers to the context object; StoreContext in a store and ViewContext in a view.
-  // Context objects contain methods for controlling the component, logging and attaching lifecycle hooks.
-
-  return {
-    $message: $(() => message()),
-    setMessage: (value: string) => message.set(value.toUpperCase()),
-  };
-}
-
-function App(props, ctx) {
-  // Provide a store for this and all child views.
-  ctx.addStore(MessageStore);
-
-  const { $message, setMessage } = ctx.getStore(MessageStore);
-  // Provides a MessageStore on this context and any child contexts.
-  // When a store is provided its value is returned right away.
-
-  return (
-    <div>
-      <MessageView />
-      <MessageView />
-      <MessageView />
-
-      <input
-        type="text"
-        value={$message}
-        onInput={(e) => {
-          setMessage(e.currentTarget.value);
-        }}
-      />
-    </div>
-  );
-}
-
-function MessageView(props, ctx) {
-  const { message } = ctx.getStore(MessageStore);
-  // Gets the nearest instance of MessageStore. In this case the one provided at the parent.
-
-  return <span>{message}</span>;
-}
+const app = createApp(Counter);
+app.mount(document.body);
 ```
 
 For more detail [check out the Docs](./docs/index.md).

package/dist/core/context.d.ts

@@ -2,12 +2,13 @@ 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 = 0,
-    DID_MOUNT = 1,
-    WILL_UNMOUNT = 2,
-    DID_UNMOUNT = 3,
-    DISPOSE = 4
+    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,
@@ -87,16 +88,11 @@ export declare class Context implements Logger {
     /**
      * Returns a new Context with this one as its parent.
      */
-    static linked(parent: Context, name: MaybeSignal<string>, options?: LinkedContextOptions): Context;
+    static createChildOf(parent: Context, name: MaybeSignal<string>, options?: LinkedContextOptions): Context;
     /**
      * Emit a lifecycle event to `context`.
      */
     static emit(context: Context, event: LifecycleEvent): void;
-    /**
-     * Traverses _parent contexts until arriving at one that doesn't have a parent itself.
-     * Returns null if this context is the parent.
-     */
-    static getRoot(context: Context): Context | null;
     constructor(name: MaybeSignal<string>, options?: ContextOptions);
     /**
      * Returns the current name of this context.
@@ -117,21 +113,11 @@ export declare class Context implements Logger {
      */
     getStore<T>(store: Store<any, T>): T;
     /**
-     * Schedule a callback function to run just before this context is mounted.
-     */
-    beforeMount(listener: LifecycleListener): () => void;
-    /**
-     * Schedule a callback function to run after this context is mounted.
-     */
-    onMount(listener: LifecycleListener): () => void;
-    /**
-     * Schedule a callback function to run just before this context is unmounted.
-     */
-    beforeUnmount(listener: LifecycleListener): () => void;
-    /**
-     * Schedule a callback function to run after this context is unmounted.
+     * Registers a `listener` to be called at a specific transition point during this context's lifecycle.
+     *
+     * Prefer `useMount` and `useUnmount` hooks for general usage.
      */
-    onUnmount(listener: LifecycleListener): () => void;
+    onLifecycleTransition(event: LifecycleEventName, listener: LifecycleListener): () => void;
     effect(callback: EffectFn): UnsubscribeFn;
     /**
      * Gets the value stored at `key`, or returns `options.fallback` if none is set.

package/dist/{hooks/index.d.ts → core/hooks.d.ts}

@@ -1,29 +1,28 @@
-import { type Context, type Logger, type Ref, type Store } from "../core";
+import { type Context, type Ref, type Store } from "../core";
 import { type EffectFn, type MaybeSignal, type Setter, type Signal, type SignalOptions } from "../core/signals";
 /**
- * Returns the Context object of the View, Store or Mixin this hook is called in.
+ * Returns the Context object of the `View`, `Store` or `Mixin` this hook is called in.
+ *
+ * @param name - If passed, the context will be renamed. Context takes the name of the component function by default.
  */
-export declare function useContext(): Context;
+export declare function useContext(name?: MaybeSignal<string>): Context;
 /**
- * Returns a logger. If a name is passed it will be used as a prefix for all console messages.
- * Otherwise the default name of the context will be used.
+ * Returns the nearest instance of a Store provided to this context.
  */
-export declare function useLogger(name?: MaybeSignal<string>): Logger;
+export declare function useStore<T>(store: Store<any, T>): T;
 /**
- * Creates a new read-only Getter and a bound Setter function.
- * @deprecated prefer useSignal
+ * Adds a store to this context and returns the store instance.
  */
-export declare function useState<T>(value: T, options?: SignalOptions<T>): [Signal<T>, Setter<T>];
+export declare function useStoreProvider<T, O>(store: Store<O, T>, options?: O): T;
 /**
- * Creates a new read-only Signal and a bound Setter function.
- * @deprecated prefer useSignal
+ * Schedules `callback` to run just after the component is mounted.
+ * If `callback` returns a function, that function will run when the context is unmounted.
  */
-export declare function useState<T>(value: undefined, options: SignalOptions<T>): [Signal<T | undefined>, Setter<T | undefined>];
+export declare function useMount(callback: () => void | (() => void)): void;
 /**
- * Creates a new read-only Signal and a bound Setter function.
- * @deprecated prefer useSignal
+ * Schedules `callback` to run when the context is unmounted.
  */
-export declare function useState<T>(): [Signal<T | undefined>, Setter<T | undefined>];
+export declare function useUnmount(callback: () => void): void;
 /**
  * Creates a new read-only Signal. Returns bound Getter and Setter functions.
  *
@@ -38,7 +37,6 @@ export declare function useSignal<T>(value: T, options?: SignalOptions<T>): [Sig
 export declare function useSignal<T>(value: undefined, options: SignalOptions<T>): [Signal<T | undefined>, Setter<T | undefined>];
 export declare function useSignal<T>(): [Signal<T | undefined>, Setter<T | undefined>];
 export declare function useMemo<T>(compute: (current?: T) => MaybeSignal<T>, deps?: Signal<any>[], options?: SignalOptions<T>): Signal<T>;
-export declare function useEffect(fn: EffectFn, deps?: Signal<any>[]): void;
 /**
  * Takes the current state and a dispatched action. Returns a new state based on the action.
  * Typically the body of this function will be a large switch statement.
@@ -53,9 +51,10 @@ export type Dispatcher<Action> = (action: Action) => void;
  */
 export declare function useReducer<State, Action>(reducer: Reducer<State, Action>, initialState: State): [Signal<State>, Dispatcher<Action>];
 /**
- * Uses a previously added Store. Takes the Store function itself and returns the nearest instance.
+ * Creates an effect bound to the current context.
+ * The `fn` is called when the component is mounted, then again each time the dependencies are updated until the component is unmounted.
  */
-export declare function useStore<T>(store: Store<any, T>): T;
+export declare function useEffect(fn: EffectFn, deps?: Signal<any>[]): void;
 /**
  * A hybrid Ref which is both a function ref and a React-style object ref with a `current` property.
  * Both the `current` property and the function syntax access the same value.
@@ -65,13 +64,7 @@ export interface HybridRef<T> extends Ref<T> {
 }
 /**
  * Creates a Ref. Useful for getting references to DOM nodes.
+ *
+ * @deprecated use ref()
  */
 export declare function useRef<T>(initialValue?: T): HybridRef<T>;
-/**
- * Calls `callback` when the context is mounted. If `callback` returns a function, that function is called when the context is unmounted.
- */
-export declare function useMount(callback: () => void | (() => void)): void;
-/**
- * Calls `callback` when the context is unmounted.
- */
-export declare function useUnmount(callback: () => void): void;

package/dist/core/index.d.ts

@@ -1,13 +1,14 @@
 export { createApp } from "./app.js";
-export { $, batch, effect, get, memo as memo, writable, untracked } from "./signals.js";
-export type { MaybeSignal, Writable, Signal } from "./signals.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 type { Context } from "./context.js";
-export { m, Markup, MarkupNode, portal, render, repeat, unless, when } from "./markup.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 { Show, type ShowProps } from "./views/show.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";

package/dist/core/markup.d.ts

@@ -2,7 +2,7 @@ import type { IntrinsicElements, Renderable, View } from "../types.js";
 import { Context } from "./context.js";
 import { MarkupNode } from "./nodes/_markup.js";
 import { KeyFn, RenderFn } from "./nodes/repeat.js";
-import { type MaybeSignal, type Signal } from "./signals.js";
+import { type Signal } from "./signals.js";
 export { MarkupNode };
 type PropsOf<V extends string | View<any>> = V extends View<infer U> ? U : any;
 /**
@@ -53,50 +53,25 @@ export interface MarkupCustomElementProps {
 /**
  * Creates a `Markup` element that defines an HTML element.
  */
-export declare function m<T extends keyof IntrinsicElements>(tag: T, attrs: IntrinsicElements[T] & {
+export declare function createMarkup<T extends keyof IntrinsicElements>(tag: T, attrs: IntrinsicElements[T] & {
     children?: Renderable;
 }): Markup;
 /**
  * Creates a `Markup` element that defines an HTML custom element.
  */
-export declare function m<T extends keyof MarkupCustomElementProps>(type: T, props: MarkupCustomElementProps[T]): Markup;
+export declare function createMarkup<T extends keyof MarkupCustomElementProps>(type: T, props: MarkupCustomElementProps[T]): Markup;
 /**
  * Creates a `Markup` element that defines a `MarkupNode`.
  */
-export declare function m<T extends keyof MarkupNodeProps>(type: T, props: MarkupNodeProps[T]): Markup;
+export declare function createMarkup<T extends keyof MarkupNodeProps>(type: T, props: MarkupNodeProps[T]): Markup;
 /**
  * Creates a `Markup` element that defines a view.
  */
-export declare function m<P extends {}>(type: View<P>, props?: P): Markup;
+export declare function createMarkup<P extends {}>(type: View<P>, props?: P): Markup;
 /**
  * Creates a `Markup` element that defines a view.
  */
-export declare function m<P>(type: View<P>, props: P): Markup;
-/**
- * If `condition` is truthy, displays `thenContent`, otherwise `elseContent`.
- *
- * @deprecated use `Show` view with `when` prop.
- */
-export declare function when(condition: MaybeSignal<any>, thenContent?: Renderable, elseContent?: Renderable): Markup;
-/**
- * Inverted `when`. If `condition` is falsy, displays `thenContent`, otherwise `elseContent`.
- *
- * @deprecated use `Show` view with `unless` prop.
- */
-export declare function unless(condition: MaybeSignal<any>, thenContent?: Renderable, elseContent?: Renderable): Markup;
-/**
- * Calls `render` for each item in `items`. Dynamically adds and removes views as items change.
- * The result of `key` is used to compare items and decide if item was added, removed or updated.
- *
- * @deprecated use `For` view
- */
-export declare function repeat<T>(items: MaybeSignal<T[]>, key: KeyFn<T>, render: RenderFn<T>): Markup;
-/**
- * Renders `content` into a `parent` node anywhere in the page, rather than its usual position in the view.
- *
- * @deprecated use `Portal` view
- */
-export declare function portal(parent: Element, content: Renderable): Markup;
+export declare function createMarkup<P>(type: View<P>, props: P): Markup;
 /**
  * Takes any `Renderable` value and returns a `MarkupNode` that will display it.
  */

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

@@ -1,5 +1,5 @@
 import type { Context } from "../context.js";
-import { Signal } from "../signals.js";
+import { type Signal } from "../signals.js";
 import { MarkupNode } from "./_markup.js";
 /**
  * Renders any kind of content; markup, signals, DOM nodes, etc.

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

@@ -19,7 +19,6 @@ export declare class ElementNode extends MarkupNode {
     mount(parent: Node, after?: Node): void;
     unmount(skipDOM?: boolean): void;
     move(parent: Element, after?: Node): void;
-    private update;
     private attachProp;
     private getKey;
     private applyProps;

package/dist/core/ref.d.ts

@@ -1,3 +1,4 @@
+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.

package/dist/core/signals.d.ts

@@ -32,14 +32,33 @@ export interface SignalOptions<T> {
      */
     equals?: EqualityFn<T>;
 }
-export declare function $<T>(compute: (previousValue?: T) => MaybeSignal<T>, options?: MemoOptions<T>): Signal<T>;
-export declare function $<T>(): Writable<T | undefined>;
-export declare function $<T>(initialValue: undefined, options: SignalOptions<T | undefined>): Writable<T | undefined>;
-export declare function $<T>(initialValue: T, options?: SignalOptions<T>): Writable<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>;
+/**
+ * Ensures that a value is a read-only signal.
+ *
+ * @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)
+ */
 export declare function readable<T>(signal: MaybeSignal<T>): Signal<T>;
+/**
+ * Creates a new signal, returning a getter and setter pair.
+ *
+ * @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.
@@ -71,23 +90,11 @@ export declare function get<T>(value: MaybeSignal<T>): T;
  */
 export type EffectFn = () => void | (() => void);
 export type UnsubscribeFn = () => void;
-export declare const INTERNAL_EFFECT: unique symbol;
-export interface EffectOptions {
-    /**
-     * An array of signals this effect 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>[];
-    /**
-     * For internal use.
-     */
-    _type?: symbol;
-}
 /**
  * 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 stop watching for changes.
- * If you are using an effect inside a View or Store, use `ctx.effect` instead, which cleans up automatically when the component unmounts.
+ * 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.
  */
-export declare function effect(fn: EffectFn, options?: EffectOptions): UnsubscribeFn;
+export declare function effect(fn: EffectFn): UnsubscribeFn;

package/dist/core/views/for.d.ts

@@ -1,12 +1,12 @@
 import type { Renderable } from "../../types";
 import type { Context } from "../context";
 import { type Key, RepeatNode } from "../nodes/repeat";
-import { type Signal } from "../signals";
+import { type MaybeSignal, type Signal } from "../signals";
 export interface ForProps<T> {
     /**
      * An array of items to render.
      */
-    each: Signal<T[]>;
+    each: MaybeSignal<T[]>;
     /**
      * A function to extract a unique key that identifies each item.
      * If no `key` function is passed, object identity (===) will be used.

package/dist/core/views/show.d.ts

@@ -1,16 +1,16 @@
 import type { Renderable } from "../../types";
 import type { Context } from "../context";
 import { DynamicNode } from "../nodes/dynamic";
-import { type Signal } from "../signals";
+import { type MaybeSignal } from "../signals";
 export interface ShowProps {
     /**
      * If present, children will be rendered only when this signal holds a truthy value.
      */
-    when?: Signal<any>;
+    when?: MaybeSignal<any>;
     /**
      * If present, children will be rendered only when this signal holds a falsy value.
      */
-    unless?: Signal<any>;
+    unless?: MaybeSignal<any>;
     /**
      * Content to render if conditions permit.
      */

package/dist/http.js

@@ -6,7 +6,7 @@ var g = (r, e, t) => e in r ? b(r, e, { enumerable: !0, configurable: !0, writab
 var a = (r, e, t) => g(r, typeof e != "symbol" ? e + "" : e, t), m = (r, e, t) => e.has(r) || f("Cannot " + t);
 var d = (r, e, t) => (m(r, e, "read from private field"), t ? t.call(r) : e.get(r)), c = (r, e, t) => e.has(r) ? f("Cannot add the same private member more than once") : e instanceof WeakSet ? e.add(r) : e.set(r, t);
 var o = (r, e, t) => (m(r, e, "access private method"), t);
-import { a as w } from "./typeChecking-_dGK_0uR.js";
+import { a as w } from "./typeChecking-Cw-4pIto.js";
 var l, p, i, h;
 class O {
   constructor() {