@manyducks.co/dolla 2.0.0-alpha.5 → 2.0.0-alpha.51

package/notes/scratch.md

@@ -1,5 +1,328 @@
 # Scratch Note
 
+Idea: Monomorphic app context. Replaces StoreContext, ViewContext, etc.
+
+Routes are baked into the app once again, but
+
+```jsx
+import { createRoot } from "@manyducks.co/dolla";
+import { example } from "./stores/example.js";
+
+const root = createRoot();
+
+root.use(example());
+
+async function auth(_, state, redirect) {
+  // route context
+  // Routes run through each callback until one resolves to a renderable value.
+  // If redirect is called, the route is re-matched and no further callbacks are run for this route.
+
+  if (state.auth == null) {
+    redirect("/login");
+  }
+}
+
+root.route("/users/*", auth, (C) => {
+  C.route("/{#id}/*", (C) => {
+    C.route("/", (C) => <UserDetailRoute userId={C.params.id} />);
+    C.route("*", "./");
+  });
+});
+
+root.route("/users/*", auth, (route) => {
+  route("/{#id}/*", (route) => {
+    // TODO: It's possible to reference the wrong 'route'
+    // Track active context and throw error if the one you call belongs to the wrong context?
+    route("/", (_, state) => <UserDetailView userId={state.params.id} />);
+    route("*", "./");
+  });
+});
+
+function ExampleView(props, ctx) {
+  // ctx.routes returns a special type of outlet that renders children based on
+  // the route segments that come after the ones at this ctx.
+
+  // The weakness of this idea is that routes can't be validated without initializing views.
+  return (
+    <div>
+      <Suspense fallback={<span>Loading...</span>}>
+        {ctx.routes((route) => {
+          route("/subroute", () => <OtherView />);
+
+          // Routes can be async.
+          route("/other", () => import("some-module"));
+        })}
+      </Suspense>
+    </div>
+  );
+
+  // Also Suspense. This can be simply implemented with events.
+  ctx.emit("suspense:begin", uniqueId);
+  // Then when done:
+  ctx.emit("suspense:end", uniqueId);
+
+  // The nearest Suspense view will track ids which are in suspense and show fallback content in the meantime.
+}
+
+function Suspense(props, ctx) {
+  const [$tracked, setTracked] = createState({});
+
+  ctx.on("suspense:begin", (e) => {
+    setTracked((tracked) => {
+      return {
+        ...tracked,
+        [e.detail]: new Date(),
+      };
+    });
+  });
+
+  ctx.on("suspense:end", (e) => {
+    setTracked((tracked) => {
+      const updated = Object.assign({}, tracked);
+      delete updated[e.detail];
+      return updated;
+    });
+  });
+
+  // TODO: Hide suspended view without unmounting it. This might take special logic.
+}
+
+// Can also pass markup directly if you don't need the context.
+root.route("/", auth, <HomeRoute />);
+
+// Static redirect.
+root.route("*", "/");
+
+// Programmatic redirect.
+root.route("*", (C) => {
+  C.log("hit wildcard");
+  C.redirect("/");
+});
+
+root.mount(document.body);
+
+// generate an HTML string for server side rendering.
+root.toString("/some/path");
+```
+
+---
+
+```js
+class ClockStore extends Store {
+
+
+  constructor() {
+
+  }
+}
+
+class CounterStore extends Store {
+  // Could have better name. This will catch any
+  // this.emit('counter:increment') or this.emit('counter:decrement') calls
+  // and update the state according to these functions.
+  value = new Emittable('counter', 0, {
+    increment: state => state + 1,
+    decrement: state => state - 1
+  });
+}
+
+type CounterEvents = {
+  increment: [amount: number];
+  decrement: [amount: number];
+}
+
+
+
+```
+
+---
+
+Bring the $ back and the name full circle.
+
+```js
+import { $, $$ } from "@manyducks.co/dolla";
+
+// Shorthand dolla sign
+
+// An initial value (with optional options object) creates a state.
+const [$count, setCount] = $(0);
+// = createState(0)
+
+// An array and a function derives a state.
+const $doubled = $.map([$count], (count) => count * 2);
+// = derive([$count], (count) => count * 2);
+
+// A state returns the same state.
+const $sameCount = $.from($count);
+const $wrapped = $.from({ message: "This is a state with no setter." });
+// = toState($count)
+
+// Get value from a state. Values that are not states are returned directly.
+const count = $.get($count);
+```
+
+What about other operators like RxJS?
+
+```js
+// These would be functionally equivalent.
+const $doubled = $count.pipe($.map((count) => count * 2));
+const $doubled = $.map([$count], (count) => count * 2);
+
+// Chainable. Get doubled value, but only update if it's between 10 and 100.
+const $boundedDouble = $count.pipe(
+  // Transforms the value
+  $.map((count) => count * 2),
+
+  // Receives the value when it changes without affecting the output.
+  // Only receives values while this state is actively being watched.
+  $.tap((count) => console.log(`doubled value is ${count}`))
+
+  // Value only changes if it's within the range.
+  $.filter((count) => count >= 10 && count <= 100),
+);
+
+// Could have a top level pipe operator
+const $boundedDouble = $.pipe(
+  [$count],
+  $.map((count) => count * 2),
+  $.tap((count) => console.log(`doubled value is ${count}`))
+  $.filter((count) => count >= 10 && count <= 100),
+);
+
+// Could also be chainable
+const $boundedDouble = $count
+  .map((count) => count * 2)
+  .tap((count) => console.log(`doubled value is ${count}`))
+  .filter((count) => count >= 10 && count <= 100);
+
+// I kind of like this more than the current derive. It's cleaner.
+$count.map(c => c * 2);
+$count.merge([$other], (c, o) => c * o);
+
+// Another way to merge multiple.
+$.merge([$count, $other], (c, o) => c * o);
+
+// What if you want to add something in the middle?
+
+const $example = $count
+  .map((count) => count * 2)
+  .tap((count) => console.log(`doubled value is ${count}`))
+  .merge([$other1, $other2], (count, other1, other2) => /* ... */)
+  .filter((value) => value >= 10 && value <= 100);
+
+// Is this a good pattern?
+$count
+  .merge([$other], (count, other) => count * other)
+  .merge([$another], (merged, another) => merged * another);
+// I think it gets a little weird to follow.
+
+// equivalent to
+derive(
+  [
+    derive([$count, $other], (count, other) => count * other),
+    $another
+  ],
+  (merged, another) => merged * another)
+// Is this a pattern? Yeah, I guess I do that. Just never in line like that.
+
+// Do we want to handle errors?
+// I feel like errors usually happen in watchers though.
+$boundedDouble.watch((value) => {
+  // Received a value.
+}, (error) => {
+  // Something threw an error.
+});
+// Or like this.
+$boundedDouble.watch({
+  change: (value) => {
+    // Received a value.
+    // This code is most likely to throw an error.
+    // Should errors here be passed to the error callback?
+    // What is the point if you can just try/catch?
+
+    // Although if you don't then Dolla could use this to catch
+    // and trace errors better than it does now.
+  },
+  error: (error) => {
+    // Something threw an error.
+  }
+});
+
+// Filter derives a new state where the value only updates if the function returns truthy.
+const $evens = $count.pipe($.filter((count) => count % 1 === 0));
+// This is equivalent to
+const $events = $.map([$count], (count) => count, { equals: (a, b) => a % 1 === 0 });
+
+function filter(...args) {
+  if (isArray(args[0]) && isFunction(args[1])) {
+    // Standalone signature. Returns a new derived state.
+  } else if (args.length === 1 && isFunction(args[1])) {
+    // Curried signature. Returns a function that takes an array of states
+    // and returns one with args[1] as the equality check.
+  }
+}
+```
+
+And you can write your own operators that implement these two signatures.
+
+```js
+// Here's one I might want to include.
+// Use this to prevent ever getting a null value.
+compare((next, previous) => next ?? previous ?? "default");
+
+function compare(...args) {}
+```
+
+---
+
+I've been looking into other libraries that don't make you track your dependencies specifically. I think this is weird and unhinged to be honest. Calling functions with side effects that magically re-run things when the value changes is a truly weird and unexpected lifecycle. At least if you're explicitly tracking dependencies you know exactly what depends on what at a glance. Getting the computer to figure it out for you doesn't seem smart.
+
+```js
+import { $ } from "@manyducks.co/dolla";
+
+const [count, setCount] = $(0);
+
+const doubled = $.computed(() => count() * 2);
+
+$.effect(() => {
+  console.log(doubled());
+});
+
+$.batch(() => {
+  // Set multiple things but defer updates to after this function returns.
+});
+
+// Helpers on $; can plug into template as is.
+$.if(
+  $.computed(() => count() > 5),
+  <span>Greater than 5!</span>,
+  <span>Not greater than 5...</span>,
+);
+
+const switched = $.switch(count, [[1, "one"], [2, "two"], [3, "three"]], "more...");
+
+$.repeat()
+
+// TODO: How feasible is this?
+<Repeat each={}>
+  {(item, index) => {
+
+  }}
+</Repeat>
+
+<Show when={condition}>
+  Condition is true.
+</Show>
+
+// Get
+count();
+
+// Set
+count(52);
+```
+
+---
+
 What if Dolla was just a global object that you don't instantiate. I have never personally run into a use case for having more than one app on a page at once. In all my projects, the page and the app are synonymous.
 
 Doing this would make it possible to access things inside the Dolla app from _outside_ code such as Quill blots. Effectively all code that has access to your Dolla import is _inside_ the app.
@@ -11,8 +334,8 @@ Doing this would make it possible to access things inside the Dolla app from _ou
 import Dolla from "@manyducks.co/dolla";
 
 // Languages: add translation, set language and get localized string as a signal
-Dolla.language.setup({
-  initialLanguage: Dolla.language.detect({ fallback: "ja" }), // Detect user's language and fall back to passed value
+Dolla.i18n.setup({
+  initialLanguage: Dolla.i18n.detect({ fallback: "ja" }), // Detect user's language and fall back to passed value
   languages: [
     { name: "ja", path: "/static/locales/ja.json" },
     {
@@ -26,8 +349,8 @@ Dolla.language.setup({
   ]
 });
 
-Dolla.language.$current
-Dolla.language.t$()
+Dolla.i18n.$locale
+Dolla.i18n.t$()
 
 // A single setup call to keep things contained (must happen before mount)
 Dolla.router.setup({
@@ -75,10 +398,10 @@ debug.log("HELLO");
 debug.warn("THIS IS A SCOPED LOGGER");
 
 // Efficiently and safely read and mutate the DOM using Dolla's render batching
-Dolla.render.read(() => {
+Dolla.batch.read(() => {
   // Reference DOM nodes
 });
-Dolla.render.update(() => {
+Dolla.batch.write(() => {
   // Mutate the DOM as part of Dolla's next batch
 }, "some-key");
 
@@ -93,7 +416,7 @@ function SomeView (props: SomeViewProps, ctx: Dolla.ViewContext) {
   const debug = Dolla.createLogger("SomeView");
 
   // returns a signal and a setter function
-  const [$someValue, setSomeValue] = Dolla.createSignal(4);
+  const [$someValue, setSomeValue] = Dolla.createState(4);
 
   // Router is now a part of the Dolla object
   Dolla.router.$path;

package/notes/splitting.md

@@ -0,0 +1,5 @@
+# Splitting
+
+Thinking again of splitting this out into multiple libraries. Or at least having the base signals+markup be its own standalone thing that the rest of the framework is built on.
+
+This implementation of signals + templates would be useful for web components.

package/notes/stores.md

@@ -0,0 +1,53 @@
+# Stores
+
+Ideas for updating the API.
+
+```js
+function CounterStore(initialCount = 0, ctx) {
+  const [$value, setValue] = createState(initialCount);
+
+  ctx.on("counter:increment", (e) => {
+    e.stop(); // Stop this event from bubbling up to counters at higher levels (if any).
+    setValue((current) => current + 1);
+  });
+
+  ctx.on("counter:decrement", (e) => {
+    e.stop();
+    setValue((current) => current - 1);
+  });
+
+  // Events can be emitted from this context in a store.
+  ctx.emit("otherEvent");
+
+  ctx.onMount(() => {
+    // Setup
+    // This is called based on the context the store is attached to.
+    // If Dolla, it's called when the app is mounted. If ViewContext, it's called when the view is mounted.
+  });
+  ctx.onUnmount(() => {
+    // Cleanup
+  });
+
+  // Context variables will be accessible on the same context (e.g. the view this is attached to and below)
+  ctx.get("context variable");
+  ctx.set("context variable", "context variable value");
+
+  // Stores don't have to return anything, but if they do it becomes accessible with `ctx.use(Store)`.
+  return $value;
+}
+
+// Attach it to the app.
+Dolla.provide(CounterStore, 0);
+
+function ExampleView(props, ctx) {
+  // ctx.use lets you access the return value
+  // but the events will still be received and handled regardless
+  const $count = ctx.use(Counter);
+
+  return html`
+    <button onclick=${() => this.emit("counter:decrement")}>-1</button>
+    <span>${$count}</span>
+    <button onclick=${() => this.emit("counter:increment")}>+1</button>
+  `;
+}
+```

package/package.json

@@ -1,14 +1,17 @@
 {
   "name": "@manyducks.co/dolla",
-  "version": "2.0.0-alpha.5",
+  "version": "2.0.0-alpha.51",
   "description": "Front-end components, routing and state management.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "module",
   "sideEffects": false,
-  "repository": "https://github.com/manyducksco/dolla",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/manyducksco/dolla.git"
+  },
   "scripts": {
-    "test": "npm run build && node --test",
+    "test": "vitest",
     "build:esbuild": "tsc && node build.js",
     "build": "vite build && tsc",
     "start": "tsc --watch",
@@ -36,16 +39,16 @@
       "types": "./jsx-dev-runtime.d.ts"
     }
   },
+  "dependencies": {
+    "alien-signals": "^1.0.3"
+  },
   "devDependencies": {
-    "@types/node": "^22.10.6",
+    "@types/node": "^22.12.0",
     "csstype": "^3.1.3",
-    "esbuild": "^0.24.2",
-    "history": "^5.3.0",
-    "htm": "^3.1.1",
-    "nanoid": "^5.0.9",
     "prettier": "^3.4.2",
-    "simple-color-hash": "^1.0.2",
     "typescript": "^5.7.3",
-    "vite": "^6.0.7"
+    "vite": "^6.0.11",
+    "vite-plugin-externalize-deps": "^0.9.0",
+    "vitest": "^3.0.5"
   }
 }

package/vite.config.js

@@ -1,11 +1,12 @@
 import { resolve } from "node:path";
 import { defineConfig } from "vite";
+// import { externalizeDeps } from "vite-plugin-externalize-deps";
 
 export default defineConfig({
   build: {
-    // minify: "terser",
-    // minify: false,
     sourcemap: true,
+    minify: true,
+    // target: "esnext",
 
     lib: {
       entry: {
@@ -16,13 +17,7 @@ export default defineConfig({
       name: "Dolla",
       formats: ["es"],
     },
-    // rollupOptions: {
-    //   external: ["vue"],
-    //   output: {
-    //     globals: {
-    //       vue: "Vue",
-    //     },
-    //   },
-    // },
   },
+
+  // plugins: [externalizeDeps()],
 });

package/build.js

@@ -1,34 +0,0 @@
-import fs from "node:fs";
-import esbuild from "esbuild";
-
-esbuild
-  .build({
-    entryPoints: ["src/index.ts"],
-    bundle: true,
-    metafile: true,
-    sourcemap: true,
-    // minify: process.env.NODE_ENV === "production",
-    outdir: "dist",
-    format: "esm",
-  })
-  .then((result) => {
-    fs.writeFileSync("esbuild-meta.json", JSON.stringify(result.metafile));
-  });
-
-esbuild.build({
-  entryPoints: ["src/jsx-runtime.js"],
-  bundle: false,
-  minify: false,
-  sourcemap: true,
-  outdir: "dist",
-  format: "esm",
-});
-
-esbuild.build({
-  entryPoints: ["src/jsx-dev-runtime.js"],
-  bundle: false,
-  minify: false,
-  sourcemap: true,
-  outdir: "dist",
-  format: "esm",
-});

package/dist/markup.d.ts

@@ -1,100 +0,0 @@
-import type { Dolla } from "./modules/dolla.js";
-import { MaybeSignal, type Signal } from "./signals.js";
-import type { Renderable, Stringable } from "./types.js";
-import { type ViewFunction, type ViewContext, type ViewResult } from "./view.js";
-export interface ElementContext {
-    /**
-     * The root Dolla instance this element belongs to.
-     */
-    root: Dolla;
-    /**
-     * 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;
-}
-/**
- * Markup is a set of element metadata that hasn't been constructed into a MarkupNode yet.
- */
-export interface Markup {
-    type: string | ViewFunction<any>;
-    props?: Record<string, any>;
-    children?: Markup[];
-}
-/**
- * A DOM node that has been constructed from a Markup object.
- */
-export interface MarkupNode {
-    readonly node?: Node;
-    readonly isMounted: boolean;
-    mount(parent: Node, after?: Node): void;
-    unmount(): void;
-}
-export declare function isMarkup(value: unknown): value is Markup;
-export declare function isNode(value: unknown): value is MarkupNode;
-export declare function toMarkup(renderables: Renderable | Renderable[]): Markup[];
-export interface MarkupAttributes {
-    $text: {
-        value: MaybeSignal<Stringable>;
-    };
-    $cond: {
-        $predicate: Signal<any>;
-        thenContent?: Renderable;
-        elseContent?: Renderable;
-    };
-    $repeat: {
-        $items: Signal<any[]>;
-        keyFn: (value: any, index: number) => string | number | symbol;
-        renderFn: ($item: Signal<any>, $index: Signal<number>, c: ViewContext) => ViewResult;
-    };
-    $observer: {
-        signals: Signal<any>[];
-        renderFn: (...items: any) => Renderable;
-    };
-    $outlet: {
-        $children: Signal<MarkupNode[]>;
-    };
-    $node: {
-        value: Node;
-    };
-    $portal: {
-        content: Renderable;
-        parent: Node;
-    };
-    [tag: string]: Record<string, any>;
-}
-export declare function createMarkup<T extends keyof MarkupAttributes>(type: T, attributes: MarkupAttributes[T], ...children: Renderable[]): Markup;
-export declare function createMarkup<I>(type: ViewFunction<I>, attributes?: I, ...children: Renderable[]): Markup;
-/**
- * Generate markup with HTML in a tagged template literal.
- */
-export declare const html: (strings: TemplateStringsArray, ...values: any[]) => Markup | Markup[];
-/**
- * Displays content conditionally. When `predicate` holds a truthy value, `thenContent` is displayed; when `predicate` holds a falsy value, `elseContent` is displayed.
- */
-export declare function cond(predicate: MaybeSignal<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: MaybeSignal<T[]>, keyFn: (value: T, index: number) => string | number | symbol, renderFn: ($value: Signal<T>, $index: Signal<number>, ctx: ViewContext) => ViewResult): Markup;
-/**
- * Render `content` into a `parent` node anywhere in the page, rather than at its position in the view.
- */
-export declare function portal(parent: Node, content: Renderable): Markup;
-/**
- * A special kind of signal exclusively for storing references to DOM nodes.
- */
-export declare function createRef<T extends Node>(): Ref<T>;
-export declare function isRef<T extends Node>(value: any): value is Ref<T>;
-export interface Ref<T extends Node> extends Signal<T | undefined> {
-    node: T | undefined;
-}
-/**
- * Construct Markup metadata into a set of MarkupNodes.
- */
-export declare function constructMarkup(elementContext: ElementContext, markup: Markup | Markup[]): MarkupNode[];
-/**
- * Combines one or more MarkupNodes into a single MarkupNode.
- */
-export declare function mergeNodes(nodes: MarkupNode[]): MarkupNode;
-export declare function isRenderable(value: unknown): value is Renderable;

package/dist/modules/language.d.ts

@@ -1,41 +0,0 @@
-import { type Signal } from "../signals.js";
-import type { Stringable } from "../types.js";
-import type { Dolla } from "./dolla.js";
-/**
- * An object where values are either a translated string or another nested Translation object.
- */
-type LocalizedStrings = Record<string, string | Record<string, string | Record<string, string | Record<string, string>>>>;
-export interface LanguageConfig {
-    name: string;
-    /**
-     * Path to a JSON file with translated strings for this language.
-     */
-    path?: string;
-    /**
-     * A callback function that returns a Promise that resolves to the translation object for this language.
-     */
-    fetch?: () => Promise<LocalizedStrings>;
-}
-export type LanguageSetupOptions = {
-    /**
-     * Default language to load on startup
-     */
-    initialLanguage?: string | null;
-    languages: LanguageConfig[];
-};
-export declare class Language {
-    #private;
-    $current: Signal<string | undefined>;
-    constructor(dolla: Dolla);
-    get supportedLanguages(): string[];
-    setup(options: LanguageSetupOptions): void;
-    setLanguage(name: string): Promise<void>;
-    /**
-     * Returns a Signal containing the value at `key`.
-    
-     * @param key - Key to the translated value.
-     * @param values - A map of {{placeholder}} names and the values to replace them with.
-     */
-    t(key: string, values?: Record<string, Stringable | Signal<Stringable>>): Signal<string>;
-}
-export {};