@manyducks.co/dolla 2.0.0-alpha.27 → 2.0.0-alpha.28

package/README.md

@@ -7,102 +7,15 @@
 
 Dolla is a batteries-included JavaScript frontend framework covering the needs of moderate-to-complex single page apps:
 
-- ⚡ Reactive DOM updates with [State](). Inspired by Signals, but with more explicit tracking.
-- 📦 Reusable components with [Views](#section-views).
-- 🔀 Built in [routing]() with nested routes and middleware support (check login status, preload data, etc).
-- 🐕 Built in [HTTP]() client with middleware support (set auth headers, etc).
-- 📍 Built in [localization]() system (store translated strings in JSON files and call the `t` function to get them).
-- 🍳 Build system optional. Write views in JSX or use `html` tagged template literals.
+- ⚡ Reactive DOM updates with [State](./docs/state.md). Inspired by Signals, but with more explicit tracking.
+- 📦 Reusable components with [Views](./docs/views.md).
+- 🔀 Built in [routing](./docs/router.md) with nested routes and middleware support (check login status, preload data, etc).
+- 🐕 Built in [HTTP](./docs/http.md) client with middleware support (set auth headers, etc).
+- 📍 Built in [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 use `html` tagged template literals.
 
 Let's first get into some examples.
 
-## State
-
-### Basic State API
-
-```js
-import { createState, derive } from "@manyducks.co/dolla";
-
-const [$count, setCount] = createState(72);
-
-// Get value
-$count.get(): // 72
-
-// Replace the stored value with something else
-setCount(300);
-$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
-```
-
-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);
-
-$doubled.get(); // 602
-
-setCount(500);
-
-$doubled.get(); // 1000
-```
-
-### In Views
-
-```jsx
-
-```
-
-States also come in a settable variety that includes the setter on the same object. Sometimes you want to pass around a two-way binding and this is what SettableState is for.
-
-```jsx
-import { createSettableState, fromSettable, toSettable } from "@manyducks.co/dolla";
-
-// Settable states can be set by passing a value when they are called.
-const $$value = createSettableState("Test");
-$$value(); // "Test"
-$$value("New Value");
-$$value(); // "New Value"
-
-// They can also be split into a State and Setter
-const [$value, setValue] = fromSettableState($$value);
-
-// And a State and Setter can be combined into a SettableState.
-const $$otherValue = toSettableState($value, setValue);
-
-// Or discard the setter and make it read-only using the good old toState function:
-const $value = toState($$value);
-```
-
-You can also do weird proxy things like this:
-
-```jsx
-// Create an original place for the state to live
-const [$value, setValue] = createState(5);
-
-// Derive a state that doubles the value
-const $doubled = derive([$value], (value) => value * 2);
-
-// Create a setter that takes the doubled value and sets the original $value accordingly.
-const setDoubled = createSetter($doubled, (next, current) => {
-  setValue(next / 2);
-});
-
-// Bundle the derived state and setter into a SettableState to pass around.
-const $$doubled = toSettableState($doubled, setDoubled);
-
-// Setting the doubled state...
-$$doubled(100);
-
-// ... will be reflected everywhere.
-$$doubled(); // 100
-$doubled(); // 100
-$value(); // 50
-```
-
 <h2 id="section-views">Views</h2>
 
 A basic view:

package/dist/core/context.d.ts

@@ -0,0 +1,88 @@
+import type { Emitter } from "@manyducks.co/emitter";
+import type { Store, StoreFactory } from "./store";
+import type { Dolla } from "./dolla";
+interface ContextEmitterEvents {
+    [eventName: string | symbol]: [ContextEvent<any>];
+}
+export interface ElementContext {
+    /**
+     * The root Dolla instance this element belongs to.
+     */
+    root: Dolla;
+    /**
+     * Storage for context variables.
+     */
+    data: Record<string | symbol, unknown>;
+    /**
+     * Event emitter for this context.
+     */
+    emitter: Emitter<ContextEmitterEvents>;
+    /**
+     * Stores attached to this context.
+     */
+    stores: Map<string, Store<any, any>>;
+    /**
+     * A reference to the parent context.
+     */
+    parent?: ElementContext;
+    /**
+     * Whether to create DOM nodes in the SVG namespace. An `<svg>` element will set this to true and pass it down to children.
+     */
+    isSVG?: boolean;
+    /**
+     * The name of the nearest parent view.
+     */
+    viewName?: string;
+}
+export interface ComponentContext {
+    /**
+     * Sets a context variable and returns its value.
+     */
+    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;
+    /**
+     * Adds a listener to be called when `eventName` is emitted.
+     */
+    on<T = unknown>(eventName: string, listener: (event: ContextEvent<T>) => void): void;
+    /**
+     * Removes a listener from the list to be called when `eventName` is emitted.
+     */
+    off<T = unknown>(eventName: string, listener: (event: ContextEvent<T>) => void): void;
+    /**
+     * Adds a listener to be called when `eventName` is emitted. The listener is immediately removed after being called once.
+     */
+    once<T = unknown>(eventName: string, listener: (event: ContextEvent<T>) => void): void;
+    /**
+     * Emits a new event to all listeners.
+     */
+    emit<T = unknown>(eventName: string, detail: T): boolean;
+}
+/**
+ * A context capable of hosting stores.
+ */
+export interface StorableContext extends ComponentContext {
+    /**
+     * Attaches a new store to this context.
+     */
+    attachStore(store: Store<any, any>): void;
+    /**
+     * Gets the closest instance of a store. Throws an error if the store isn't provided higher in the tree.
+     */
+    useStore<Value>(factory: StoreFactory<any, Value>): Value;
+}
+/**
+ * An event emitted from and received by a Dolla context. These are separate from DOM events.
+ */
+export declare class ContextEvent<T> {
+    #private;
+    type: string;
+    detail: T;
+    get propagationStopped(): boolean;
+    constructor(type: string, detail: T);
+    stopPropagation(): void;
+    get [Symbol.toStringTag](): string;
+}
+export {};

package/dist/core/dolla.d.ts

@@ -1,12 +1,14 @@
+import { HTTP } from "../modules/http.js";
+import { I18n } from "../modules/i18n.js";
+import { 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 { 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 { HTTP } from "../modules/http.js";
-import { I18n } from "../modules/i18n.js";
-import { Router } from "../modules/router.js";
+import { type Store, type StoreFactory } from "./store.js";
 export type Environment = "development" | "production";
 /**
  * Log type toggles. Each message category can be turned on or off or enabled only in a specific environment.
@@ -40,11 +42,7 @@ export type LoggerOptions = {
      */
     uid?: string;
 };
-export interface DollaModuleConfig<Options = never> {
-    root: Dolla;
-    options: Options;
-}
-export declare class Dolla {
+export declare class Dolla implements StorableContext {
     #private;
     readonly batch: Batch;
     private readonly stats;
@@ -88,9 +86,6 @@ export declare class Dolla {
      * Returns the top level view Dolla is rendering inside the root element. This will return undefined until Dolla.mount() is called.
      */
     getRootView(): ViewElement | undefined;
-    /**
-     * Registers a Dolla module.
-     */
     /**
      * Sets a context variable and returns its value. Context variables are accessible on the app and in child views.
      */
@@ -102,7 +97,30 @@ export declare class Dolla {
     /**
      * Returns an object of all context variables stored at the app level.
      */
-    getAll(): Record<string | symbol, unknown>;
+    /**
+     * Adds a listener to be called when `eventName` is emitted.
+     */
+    on<T = unknown>(eventName: string, listener: (event: ContextEvent<T>) => void): void;
+    /**
+     * Removes a listener from the list to be called when `eventName` is emitted.
+     */
+    off<T = unknown>(eventName: string, listener: (event: ContextEvent<T>) => void): void;
+    /**
+     * Adds a listener to be called when `eventName` is emitted. The listener is immediately removed after being called once.
+     */
+    once<T = unknown>(eventName: string, listener: (event: ContextEvent<T>) => void): void;
+    /**
+     * Emits a new event to all listeners.
+     */
+    emit<T = unknown>(eventName: string, detail: T): boolean;
+    /**
+     * Attaches a new store to this context.
+     */
+    attachStore(store: Store<any, any>): void;
+    /**
+     * Gets the nearest instance of a store. Throws an error if the store isn't provided higher in the tree.
+     */
+    useStore<Value>(factory: StoreFactory<any, Value>): Value;
     mount(selector: string, view?: ViewFunction<any>): Promise<void>;
     mount(element: HTMLElement, view?: ViewFunction<any>): Promise<void>;
     unmount(): Promise<void>;

package/dist/core/markup.d.ts

@@ -1,29 +1,7 @@
 import type { Renderable } from "../types.js";
-import type { Dolla } from "./dolla.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";
-export interface ElementContext {
-    /**
-     * The root Dolla instance this element belongs to.
-     */
-    root: Dolla;
-    /**
-     * Storage for context variables.
-     */
-    data: Record<string | symbol, unknown>;
-    /**
-     * A reference to the parent context.
-     */
-    parent?: ElementContext;
-    /**
-     * Whether to create DOM nodes in the SVG namespace. An `<svg>` element will set this to true and pass it down to children.
-     */
-    isSVG?: boolean;
-    /**
-     * The name of the nearest parent view.
-     */
-    viewName?: string;
-}
 /**
  * Markup is a set of element metadata that hasn't been constructed into a MarkupElement yet.
  */

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

@@ -1,4 +1,5 @@
-import { type ElementContext, type Markup, type MarkupElement } from "../markup.js";
+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 { IS_MARKUP_ELEMENT } from "../symbols.js";

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

@@ -1,5 +1,6 @@
 import type { Renderable } from "../../types.js";
-import { type ElementContext, type MarkupElement } from "../markup.js";
+import type { ElementContext } from "../context.js";
+import { type MarkupElement } from "../markup.js";
 import { type MaybeState } from "../state.js";
 import { IS_MARKUP_ELEMENT } from "../symbols.js";
 interface ObserverOptions {

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

@@ -1,5 +1,6 @@
-import { type Renderable } from "../../types.js";
-import { type ElementContext, type MarkupElement } from "../markup.js";
+import type { Renderable } from "../../types.js";
+import type { ElementContext } from "../context.js";
+import { type MarkupElement } from "../markup.js";
 import { IS_MARKUP_ELEMENT } from "../symbols.js";
 interface PortalConfig {
     content: Renderable;

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

@@ -1,4 +1,5 @@
-import { type ElementContext, type MarkupElement } from "../markup.js";
+import { type ElementContext } from "../context.js";
+import { type MarkupElement } from "../markup.js";
 import { type Setter, type State, type StopFunction } from "../state.js";
 import { IS_MARKUP_ELEMENT } from "../symbols.js";
 import { type ViewContext, type ViewResult } from "./view.js";

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

@@ -1,13 +1,14 @@
+import { Emitter } from "@manyducks.co/emitter";
+import { type ElementContext, type StorableContext } from "../context.js";
 import type { Logger } from "../dolla.js";
-import { type ElementContext, type Markup, type MarkupElement } from "../markup.js";
+import { type Markup, type MarkupElement } from "../markup.js";
 import { type MaybeState, type State, type StateValues, type StopFunction } from "../state.js";
 import { IS_MARKUP_ELEMENT } from "../symbols.js";
-import { Emitter } from "@manyducks.co/emitter";
 /**
  * Any valid value that a View can return.
  */
 export type ViewResult = Node | State<any> | Markup | Markup[] | null;
-export type ViewFunction<P> = (props: P, context: ViewContext) => ViewResult;
+export type ViewFunction<P> = (this: ViewContext, props: P, context: ViewContext) => ViewResult;
 /**
  * A view that has been constructed into DOM nodes.
  */
@@ -17,23 +18,14 @@ export interface ViewElement extends MarkupElement {
      */
     setChildView(view: ViewFunction<{}>): ViewElement;
 }
-export interface ViewContext extends Logger {
+export interface ViewContext extends Logger, StorableContext {
     /**
      * An ID unique to this view.
      */
     readonly uid: string;
-    /**
-     * Sets a context variable and returns its value. Context variables are accessible on the same context and from those of 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 variables stored on this context.
      */
-    getAll(): Record<string | symbol, unknown>;
     /**
      * Sets the name of the view's built in logger.
      */
@@ -64,6 +56,7 @@ export interface ViewContext extends Logger {
      */
     outlet(): Markup;
 }
+export declare function createView<Props extends Record<string, any> = Record<string, unknown>>(fn: ViewFunction<Props>): ViewFunction<Props>;
 type ViewEvents = {
     beforeMount: [];
     mounted: [];

package/dist/core/store.d.ts

@@ -0,0 +1,44 @@
+import { Emitter } from "@manyducks.co/emitter";
+import { type ComponentContext, type ElementContext } from "./context.js";
+import type { Logger } from "./dolla.js";
+export type StoreFunction<Options, Value> = (this: StoreContext, options: Options, context: StoreContext) => Value;
+export type StoreFactory<Options, Value> = Options extends undefined ? () => Store<Options, Value> : (options: Options) => Store<Options, Value>;
+export interface StoreContext extends Logger, ComponentContext {
+    /**
+     * Registers a callback to run just after this store is mounted.
+     */
+    onMount(callback: () => void): void;
+    /**
+     * Registers a callback to run just after this store is unmounted.
+     */
+    onUnmount(callback: () => void): void;
+}
+type StoreEvents = {
+    mounted: [];
+    unmounted: [];
+};
+export declare class Store<Options, Value> {
+    readonly key: string;
+    private _fn;
+    private _options;
+    /**
+     * Value is guaranteed to be set after `attach` is called.
+     */
+    value: Value;
+    _elementContext: ElementContext;
+    _emitter: Emitter<StoreEvents>;
+    _logger: Logger;
+    constructor(key: string, fn: StoreFunction<Options, Value>, options: Options);
+    attach(elementContext: ElementContext): void;
+    handleMount(): void;
+    handleUnmount(): void;
+}
+export declare function isStoreFactory<Options, Value>(value: any): value is StoreFactory<Options, Value>;
+export declare function isStore<Options, Value>(value: any): value is Store<Options, Value>;
+/**
+ * Defines a new store.
+ */
+export declare function createStore<Options = undefined, Value = unknown>(fn: StoreFunction<Options, Value>): StoreFactory<Options, Value>;
+export declare class StoreError extends Error {
+}
+export {};

package/dist/core/symbols.d.ts

@@ -2,3 +2,5 @@ export declare const IS_STATE: unique symbol;
 export declare const IS_REF: unique symbol;
 export declare const IS_MARKUP: unique symbol;
 export declare const IS_MARKUP_ELEMENT: unique symbol;
+export declare const IS_STORE: unique symbol;
+export declare const IS_STORE_FACTORY: unique symbol;

package/dist/index.d.ts

@@ -1,9 +1,11 @@
 export { createState, derive, isState, toState, toValue } from "./core/state.js";
 export type { MaybeState, Setter, State, StopFunction } from "./core/state.js";
 export { createRef, isRef, type Ref } from "./core/ref.js";
+export { createStore, type Store, type StoreFunction, type StoreFactory } from "./core/store.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";
+export { createView } from "./core/nodes/view.js";
 import { Dolla } from "./core/dolla.js";
 declare const dolla: Dolla;
 export default dolla;