@manyducks.co/dolla 2.0.0-alpha.4 → 2.0.0-alpha.40

package/notes/readme-scratch.md

@@ -0,0 +1,244 @@
+# README
+
+> This note will eventually become the new README. Here I'm laying out my ideal framework API.
+
+A basic component.
+
+```jsx
+import { mount, state, derive, batch } from "@manyducks.co/dolla";
+
+function ExampleView(props, ctx) {
+  // Signals: state, derive, effect and batch
+
+  const count = state(5);
+
+  const doubled = derive(() => count.value * 2);
+
+  batch(() => {
+    // Perform multiple updates in one go and commit at the end.
+  });
+
+  // If effect is called in the body of a view function it will be cleaned up automatically with the view.
+  ctx.effect(() => {
+    console.log(nested.value);
+  });
+
+  // Emit and listen for context events.
+  ctx.on("event", (e, ...args) => {
+    e.cancel();
+  });
+  ctx.emit("event", ...args);
+
+  // Get and set context values.
+  ctx.set("context value", 5);
+  ctx.get("context value");
+
+  // Provide and use a store.
+  const store = ctx.provide(someStore); // provide creates a new instance attached to this view and returns it.
+  const store = ctx.use(someStore);
+
+  return <p>{count}</p>;
+}
+
+mount(ExampleView, document.body);
+```
+
+<details open>
+<summary>
+  <h2>Signals API</h2>
+</summary>
+
+The signals API. Dolla's signals use explicit tracking, meaning any function where signal values are tracked take an array of the signals you want to track. This way you know exactly what depends on what at a glance without any kind of hidden tracking logic behind the scenes. You are free to `.get()` the value of a signal without worrying about untracking it first.
+
+```jsx
+import { createState } from "@manyducks.co/dolla";
+
+const [$count, setCount] = createState(256);
+
+$count.get(); // 256; returns the current value
+
+const stop = $count.watch((value) => {
+  // Runs once immediately, then again whenever the value changes.
+});
+
+setCount(512); // Update the value of $count. The new value is set and all watchers run synchronously.
+
+stop(); // Stop watching for changes.
+```
+
+That is the basic signal API. Signals are all about composability. Here are some more advanced ways of working with them:
+
+```jsx
+import { createState, toState, valueOf, derive } from "@manyducks.co/dolla";
+
+const [$count, setCount] = createState(72);
+
+// Returns the value of the signal passed in. If the value is not a signal it is returned as is.
+const count = valueOf($count);
+const bool = valueOf(true);
+
+// Creates a signal containing the value passed in. If the value is already a signal it is returned as is.
+const $bool = toState(true);
+const $anotherCount = toState($count);
+
+// Derive a new signal from the value of another. Whenever $count changes, $doubled will follow.
+const $doubled = derive([$count], (count) => count * 2);
+
+// Derive a new signal from the values of several others. When any value in the list changes, $sum will be recomputed.
+const $sum = derive([$count, $doubled], (count, doubled) => count + doubled);
+```
+
+The API if we call it State instead of Signal to distance from the Signal object in standardization process.
+
+```jsx
+import { createState, toState, valueOf, derive } from "@manyducks.co/dolla";
+
+const [$count, setCount] = createState(72);
+
+// Returns the value of the signal passed in. If the value is not a signal it is returned as is.
+const count = valueOf($count);
+const bool = valueOf(true);
+
+// Creates a signal containing the value passed in. If the value is already a signal it is returned as is.
+const $bool = toState(true);
+const $anotherCount = toState($count);
+
+// Derive a new signal from the value of another. Whenever $count changes, $doubled will follow.
+const $doubled = derive([$count], (count) => count * 2);
+
+// Derive a new signal from the values of several others. When any value in the list changes, $sum will be recomputed.
+const $sum = derive([$count, $doubled], (count, doubled) => count + doubled);
+```
+
+States also come in a settable variety, with the setter included 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 have their setter included.
+const $$value = createSettableState("Test");
+$$value.set("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);
+```
+
+Alternative API
+
+```jsx
+import { State } from "@manyducks.co/dolla";
+
+const [$count, setCount] = State(72);
+
+const count = State.unwrap($count);
+const bool = State.unwrap(true);
+
+const $bool = State.wrap(true);
+const $sameCount = State.wrap($count);
+
+const $doubled = State.from([$count], (count) => count * 2);
+
+const $sum = State.from([$count, $doubled], (count, doubled) => count + doubled);
+```
+
+Yet another
+
+```jsx
+import Dolla from "@manyducks.co/dolla";
+
+const [$count, setCount] = Dolla.state(72);
+
+const count = Dolla.get($count);
+const bool = Dolla.get(true);
+
+const $bool = Dolla.toState(true);
+const $sameCount = Dolla.toState($count);
+
+const $doubled = Dolla.computed([$count], (count) => count * 2);
+const $sum = Dolla.computed([$count, $doubled], (count, doubled) => count + doubled);
+
+// or
+
+import { state, computed, get, toState } from "@manyducks.co/dolla";
+
+const [$count, setCount] = state(72);
+
+const count = get($count);
+const bool = get(true);
+
+const $bool = toState(true);
+const $sameCount = toState($count);
+
+const $doubled = computed([$count], (count) => count * 2);
+const $sum = computed([$count, $doubled], (count, doubled) => count + doubled);
+```
+
+Settable signals:
+
+```jsx
+import { createSettableState, createSetter, toSettableSignal, fromSettableSignal } from "@manyducks.co/dolla";
+
+// Create a SettableSignal, which is basically a signal and its setter combined into a single object.
+const $$settable = createSettableState("Example");
+
+// The basic API is identical...
+$$settable.get();
+const stop = $$settable.watch((value) => {
+  // ...
+});
+stop();
+
+// ... except for the addition of a setter.
+$$settable.set("Set me directly");
+
+// When you already have a signal and a setter, they can be combined into one.
+const $$count = toSettableSignal($count, setCount);
+
+// This updates the original $signal value.
+$$count.set(386);
+
+// TODO: You can also split a SettableSignal into a signal and its setter.
+const [$readable, setReadable] = fromSettableSignal($$settable);
+
+// Create a custom setter. Calling this will cap the value to 100.
+const setCountBounded = createSetter($count, (next, current) => {
+  return Math.min(100, next);
+});
+
+setCountBounded((current) => {
+  return current + 1;
+});
+
+// Or make a proxy $$doubled -- but would you actually want to proxy things like this?
+const [$count, setCount] = createState(5);
+const $doubled = derive([$count], (count) => count * 2);
+const $$doubled = toSettableSignal(
+  $doubled,
+  createSetter($doubled, (next, current) => {
+    setCount(next * 2);
+  }),
+);
+```
+
+I'm not really sure we need all of this. On the chopping block:
+
+- The entire concept of settable signals
+  - `createSettableState`
+  - `toSettableSignal`
+  - `fromSettableSignal`
+  - `createSetter`
+
+This makes the entire API just four functions:
+
+- `createState`
+- `derive`
+- `toState`
+- `valueOf`
+
+</details>

package/notes/route-middleware.md

@@ -0,0 +1,42 @@
+# Router Middleware
+
+Allow handling route guards, preloading, etc with per-route middleware. When a route is matched, all middleware from higher layers are run again.
+
+```js
+Dolla.router.setup({
+  middleware: [/* does it make sense to have global middleware? */]
+  routes: [
+    { path: "/login", middleware: [auth] },
+    { path: "/", middleware: [auth], routes: [{ path: "/example", view: ExampleView }] }
+  ]
+});
+
+async function auth(ctx) {
+  // This check can be implemented however it needs to be for the app.
+  const authed = await isAuthorized();
+
+  if (ctx.path === "/login") {
+    if (authed) {
+      ctx.redirect("/");
+    }
+  } else {
+    if (!authed) {
+      ctx.redirect("/login");
+    }
+  }
+  // If no redirect has happened and nothing has been returned then we're clear to proceed.
+}
+
+// A middleware can also return Markup to stay on the URL but show something different.
+async function randomVisitor(ctx) {
+  if (Math.random() > 0.99) {
+    return <LuckyVisitorView />
+  }
+}
+
+// Or preload async data and set a context variable before navigating.
+async function preload(ctx) {
+  const data = await fetchData();
+  ctx.set("data", data);
+}
+```

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/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>
+  `;
+}
+```