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

package/docs/state.md

@@ -0,0 +1,141 @@
+## ⚡ Reactive Updates with `State`
+
+Dolla sets out to solve the challenge of keeping your UI in sync with your data. All apps have state that changes at runtime, and as those values change your UI must update itself to stay in sync with that state. JavaScript frameworks all have their own ways of meeting this challenge, but there are two main ones; virtual DOM and signals.
+
+[React](https://react.dev) and similar frameworks make use of a [virtual DOM](https://svelte.dev/blog/virtual-dom-is-pure-overhead), in which every state change causes a "diff" of the real DOM nodes on the page against a lightweight representation of what those nodes _should_ look like, followed by a "patch" where the minimal updates are performed to bring the DOM in line with the ideal virtual DOM.
+
+[Solid](https://www.solidjs.com) and similar frameworks make use of [signals](https://dev.to/this-is-learning/the-evolution-of-signals-in-javascript-8ob), which are containers for data that will change over time. Signal values are accessed through special getter functions that can be called inside of a "scope" to track their values. When the value of a tracked signal changes, any computations that happened in scopes that depend on those signals are re-run. In an app like this, all of your DOM updates are performed with pinpoint accuracy without diffing as signal values change.
+
+Dolla uses a concept of a `State`, which is a signal-like container for values that change over time. Where `State` differs from signals, however, is that there is no magical scope tracking going on behind the scenes. All States that depend on others do so explicity, so your code is easier to read and understand.
+
+The `State` API has just four functions:
+
+- `createState` to create a new state and a linked setter function.
+- `derive` to create a new state whose value depends on one or more other states.
+- `toState` to ensure that a value is a state object.
+- `toValue` to ensure that a value is a plain value.
+
+### Basic State API
+
+```js
+import { createState } from "@manyducks.co/dolla";
+
+// Equivalent to React's `useState` or Solid's `createSignal`.
+// A new read-only State and linked Setter are created.
+const [$count, setCount] = createState(72);
+
+// Get the current value.
+$count.get(): // 72
+
+// Set a new value.
+setCount(300);
+
+// The State now reflects the latest value.
+$count.get(); // 300
+
+// Data can also be updated by passing a function.
+// This function takes the current state and returns a new one.
+setCount((current) => current + 1);
+$count.get(); // 301
+```
+
+### Deriving States from other States
+
+#### Example 1: Doubled
+
+```js
+import { createState, derive } from "@manyducks.co/dolla";
+
+const [$count, setCount] = createState(1);
+
+const $doubled = derive([$count], (count) => count * 2);
+
+setCount(10);
+$doubled.get(); // 20
+```
+
+That was a typical toy example where we create a `$doubled` state that always contains the value of `$count`... doubled! This is the essential basic example of computed properties, as written in Dolla.
+
+#### Example 2: Selecting a User
+
+```js
+import { createState, derive } from "@manyducks.co/dolla";
+
+const [$users, setUsers] = createState([
+  { id: 1, name: "Audie" },
+  { id: 2, name: "Bob" },
+  { id: 3, name: "Cabel" },
+]);
+const [$selectedUserId, setSelectedUserId] = createState(1);
+
+const $selectedUser = derive([$users, $selectedUserId], (users, id) => {
+  return users.find((user) => user.id === id);
+});
+
+$selectedUser.get(); // { id: 1, name: "Audie" }
+
+setSelectedId(3);
+
+$selectedUser.get(); // { id: 3, name: "Cabel" }
+```
+
+That was a more realistic example you might actually use in real life. Here we are selecting a user from a list based on its `id` field. This is kind of similar to a `JOIN` operation in a SQL database. I use this kind of pattern constantly in my apps.
+
+The strength of setting up a join like this is that the `$users` array can be updated (by API call, websockets, etc.) and your `$selectedUser` will always be pointing to the latest version of the user data.
+
+#### Example 3: Narrowing Complex Data
+
+```jsx
+import { createState, derive } from "@manyducks.co/dolla";
+
+const [$user, setUser] = createState({ id: 1, name: "Audie" });
+
+const $name = derive([$user], (user) => user.name);
+
+$name.get(); // "Audie"
+
+// In a view:
+<span class="user-name">{$name}</span>;
+```
+
+Another common pattern. In a real app, most data is stored as arrays of objects. But what you need in order to slot it into a view is just a string. In the example above we've selected the user's name and slotted it into a `span`. If the `$user` value ever changes, the name will stay in sync.
+
+### Converting to and from States
+
+```js
+import { createState, toState, toValue } from "@manyducks.co/dolla";
+
+const [$count, setCount] = createState(512);
+
+// Unwrap the value of $count. Returns 512.
+const count = toValue($count);
+// Passing a non-state value will simply return it.
+const name = toValue("World");
+
+// Wrap "Hello" into a State containing "Hello"
+const $value = toState("Hello");
+// Passing a state will simply return that same state.
+const $number = toState($count);
+```
+
+### In Views
+
+```jsx
+import { derive } from "@manyducks.co/dolla";
+
+function UserNameView(props, ctx) {
+  const $name = derive([props.$user], (user) => user.name);
+
+  return <span class={{ "user-name": true, "is-selected": props.$selected }}>{$name}</span>;
+});
+```
+
+In the example above we've displayed the `name` field from a `$user` object inside of a span. We are also assigning an `is-selected` class dynamically based on whether the `$selected` prop contains a truthy or falsy value.
+
+---
+
+End.
+
+- [🗂️ Docs](./index.md)
+- [🏠 README](../README.md)
+- [🦆 That's a lot of ducks.](https://www.manyducks.co)

package/docs/stores.md

@@ -0,0 +1,62 @@
+# Stores
+
+> TODO: Write about stores
+
+```tsx
+import Dolla, { createState } from "@manyducks.co/dolla";
+
+function CounterStore (initialValue, ctx) {
+  const [$count, setCount] = createState(initialValue);
+
+  // Respond to context events which bubble up from views.
+  ctx.on("counter:increment", (e) => {
+    e.stop(); // call to stop events bubbling to parent contexts.
+    setCount((count) => count + 1);
+  });
+
+  ctx.on("counter:decrement", () => {
+    setCount((count) => count - 1);
+  });
+
+  ctx.on("counter:reset", () => {
+    setCount(0);
+  });
+
+  return $count;
+});
+
+// Stores can be provided by the app itself.
+Dolla.provide(CounterStore, 0);
+
+function CounterView(props, ctx) {
+  // Store instances can also be provided at the view level to provide them to the current scope and those of child views.
+  // Views that are not children of this CounterView will not be able to access this particular instance of CounterStore.
+  ctx.provide(CounterStore, 0);
+
+  // Store return values can be accessed with `use`.
+  // This method will check the current context for an instance, then recursively check up the view tree until it finds one.
+  // An error will be thrown if no instances of the store are provided.
+  const $count = ctx.use(CounterStore);
+
+  // The buttons increment the value inside the store by emitting events.
+  // Child views at any depth could also emit these events to update the store.
+  return (
+    <div>
+      <p>Clicks: {$count}</p>
+      <div>
+        <button onClick={() => ctx.emit("counter:decrement")}>-1</button>
+        <button onClick={() => ctx.emit("counter:reset")}>Reset</button>
+        <button onClick={() => ctx.emit("counter:increment")}>+1</button>
+      </div>
+    </div>
+  );
+});
+```
+
+---
+
+End.
+
+- [🗂️ Docs](./index.md)
+- [🏠 README](../README.md)
+- [🦆 That's a lot of ducks.](https://www.manyducks.co)

package/docs/views.md

@@ -0,0 +1,208 @@
+# Views
+
+Views are one of two component types in Dolla. We call them views because they deal specifically with presenting visible things to the user. The other type of component, [Stores](./stores.md), deal with data and events.
+
+At its most basic, a view is a function that returns markup.
+
+```jsx
+function ExampleView() {
+  return <h1>Hello World!</h1>;
+}
+```
+
+## View Props
+
+A view function takes a `props` object as its first argument. This object contains all properties passed to the view when it's invoked.
+
+```jsx
+function ListItemView(props) {
+  return <li>{props.label}</li>;
+}
+
+function ListView() {
+  return (
+    <ul>
+      <ListItemView label="Squirrel" />
+      <ListItemView label="Chipmunk" />
+      <ListItemView label="Groundhog" />
+    </ul>
+  );
+}
+```
+
+As you may have guessed, you can pass States as props and slot them in in exactly the same way. This is important because Views do not re-render the way you might expect from other frameworks. Whatever you pass as props is what the View gets for its entire lifecycle.
+
+## View Helpers
+
+### `cond($condition, whenTruthy, whenFalsy)`
+
+The `cond` helper does conditional rendering. When `$condition` is truthy, the second argument is rendered. When `$condition` is falsy the third argument is rendered. Either case can be left null or undefined if you don't want to render something for that condition.
+
+```jsx
+function ConditionalListView(props) {
+  return (
+    <div>
+      {cond(
+        props.$show,
+
+        // Visible when truthy
+        <ul>
+          <ListItemView label="Squirrel" />
+          <ListItemView label="Chipmunk" />
+          <ListItemView label="Groundhog" />
+        </ul>,
+
+        // Visible when falsy
+        <span>List is hidden</span>,
+      )}
+    </div>
+  );
+}
+```
+
+### `repeat($items, keyFn, renderFn)`
+
+The `repeat` helper repeats a render function for each item in a list. The `keyFn` takes an item's value and returns a number, string or Symbol that uniquely identifies that list item. If `$items` changes or gets reordered, all rendered items with matching keys will be reused, those no longer in the list will be removed and those that didn't previously have a matching key are created.
+
+```jsx
+function RepeatedListView() {
+  const [$items, setItems] = createState(["Squirrel", "Chipmunk", "Groundhog"]);
+
+  return (
+    <ul>
+      {repeat(
+        $items,
+        (item, index) => item, // Using the string itself as the key
+        ($item, $index, context) => {
+          return <ListItemView label={$item} />;
+        },
+      )}
+    </ul>
+  );
+}
+```
+
+### `portal(content, parentNode)`
+
+The `portal` helper displays DOM elements from a view as children of a parent element elsewhere in the document. Portals are typically used to display modals and other content that needs to appear at the top level of a document.
+
+```jsx
+function PortalView() {
+  const content = (
+    <div class="modal">
+      <p>This is a modal.</p>
+    </div>
+  );
+
+  // Content will be appended to `document.body` while this view is connected.
+  return portal(document.body, content);
+}
+```
+
+## View Context
+
+A view function takes a context object as its second argument. The context provides a set of functions you can use to respond to lifecycle events, observe dynamic data, print debug messages and display child elements among other things.
+
+```jsx
+function ExampleView(props, ctx) {
+  ctx.onMount(() => {
+    ctx.log("HELLO!");
+  });
+
+  return <h1>Hello World!</h1>;
+}
+```
+
+### Printing Debug Messages
+
+```jsx
+function ExampleView(props, ctx) {
+  // Set the name of this view's context. Console messages are prefixed with name.
+  ctx.name = "CustomName";
+
+  // Print messages to the console. These are suppressed by default in the app's "production" mode.
+  // You can also change which of these are printed and filter messages from certain contexts in the `createApp` options object.
+  ctx.info("Verbose debugging info that might be useful to know");
+  ctx.log("Standard messages");
+  ctx.warn("Something bad might be happening");
+  ctx.error("Uh oh!");
+
+  // If you encounter a bad enough situation, you can halt and disconnect the entire app.
+  ctx.crash(new Error("BOOM"));
+
+  return <h1>Hello World!</h1>;
+}
+```
+
+### Lifecycle Events
+
+```jsx
+function ExampleView(props, ctx) {
+  ctx.beforeMount(() => {
+    // Do something before this view's DOM nodes are created.
+  });
+
+  ctx.onMount(() => {
+    // Do something immediately after this view is connected to the DOM.
+  });
+
+  ctx.beforeUnmount(() => {
+    // Do something before removing this view from the DOM.
+  });
+
+  ctx.onUnmount(() => {
+    // Do some cleanup after this view is disconnected from the DOM.
+  });
+
+  return <h1>Hello World!</h1>;
+}
+```
+
+### Displaying Children
+
+The context has an `outlet` function that can be used to display children at a location of your choosing.
+
+```js
+function LayoutView(props, ctx) {
+  return (
+    <div className="layout">
+      <div className="content">{ctx.outlet()}</div>
+    </div>
+  );
+}
+
+function ExampleView() {
+  // <h1> and <p> are displayed inside LayoutView's outlet.
+  return (
+    <LayoutView>
+      <h1>Hello</h1>
+      <p>This is inside the box.</p>
+    </LayoutView>
+  );
+}
+```
+
+### Watching States
+
+The `watch` function starts observing when the view is connected and stops when disconnected. This takes care of cleaning up watchers so you don't have to worry about memory leaks.
+
+```jsx
+function ExampleView(props, ctx) {
+  const [$count, setCount] = createState(0);
+
+  // This callback will run when any states in the dependency array receive new values.
+  ctx.watch([$count], (count) => {
+    ctx.log("count is now", count);
+  });
+
+  // ...
+}
+```
+
+---
+
+End.
+
+- [🗂️ Docs](./index.md)
+- [🏠 README](../README.md)
+- [🦆 That's a lot of ducks.](https://www.manyducks.co)

package/index.d.ts

@@ -1,6 +1,6 @@
-export * from "./lib/index";
+export * from "./src/index";
 
-import type { IntrinsicElements as Elements } from "./lib/core/types";
+import type { IntrinsicElements as Elements } from "./src/types";
 
 declare global {
   namespace JSX {

package/notes/TODO.md

@@ -0,0 +1,6 @@
+# TO DO LIST
+
+- Combine/refactor very similar Group, Outlet and Observer nodes.
+  - Group is simplest and exists to mount an array of MarkupElements as one.
+  - Outlet is basically the same as Group but it expects a $children state with an array of MarkupElements.
+  - Observer is a generic catch-all that works with a set of states and a render function. The render function can return any kind of Renderable which is then converted into a MarkupElement, but very similar update logic outside of that. Observer uses Group internally.

package/notes/atomic.md

@@ -0,0 +1,209 @@
+# Atomic API
+
+```js
+function SomeView(props, ctx) {
+  // Atoms are the basic building block of state.
+  const count = new Atom(5);
+
+  count.value; // returns the value
+  count.value = 12; // replaces the value
+  count.update((value) => value + 1); // updates the value. You can use Immer here for complex objects.
+
+  // or you could just implement an update function yourself with Immer. Probably gonna cut it.
+  function update(atom, callback) {
+    atom.value = produce(atom.value, callback);
+  }
+  update(count, (value) => value + 1);
+
+  // Listen for changes. Callback will be run the next time the value changes and each time again afterwards.
+  const unsubscribe = count.subscribe((value) => {
+    console.log(value);
+  });
+
+  // Composed is a state that depends on one or more other states.
+  // The callback takes a getter function that will track that state as a dependency and return its current value.
+  // We recompute if any tracked dependency receives a new value.
+  const doubled = new Composed((get) => get(count) * 2);
+
+  // Effects follow the same pattern as a Composed callback.
+  ctx.effect(() => {
+    console.log(doubled.value);
+  });
+
+  const print = new Atom(false);
+
+  // Dependency lists are rebuilt every time the callback is run.
+  // Below, `value` will not be tracked as a dependency until `print` has changed to true.
+  ctx.effect(() => {
+    if (get(print)) {
+      console.log(get(value));
+    }
+  });
+
+  // get() is also the ONLY way to track dependencies.
+  // You're free to use the state's own getter if you want the value without actually tracking it.
+  ctx.effect((get) => {
+    if (get(value) > 5) {
+      console.log(doubled.get()); // will not be tracked
+    }
+  });
+
+  // ALSO: Need to track sets and updates so we can throw an error if a set was committed in the same scope that value is tracked. Otherwise this will cause an infinite loop.
+}
+```
+
+Refined API:
+
+```js
+const $count = atom(5);
+$count.value++;
+$count.value; // 6
+
+const $doubled = compose(() => get($count) * 2);
+const $quadrupled = compose(() => get($doubled) * 2);
+
+ctx.effect(() => {
+  if (get($count) > 25) {
+    console.log($doubled.value);
+    get($quadrupled);
+  }
+});
+```
+
+vs old API:
+
+```js
+// ----- Basic State ----- //
+
+// Old
+const [$count, setCount] = createState(5);
+setCount((count) => count + 1);
+$count.get(); // 6
+
+// New
+const count = atom(5);
+count.value++;
+count.value; // 6
+
+// ----- Derived State ----- //
+
+// Old
+const $doubled = derive([$count], (count) => count * 2);
+const $quadrupled = derive([$doubled], (doubled) => doubled * 2);
+
+// New
+const doubled = compose((get) => get(count) * 2);
+const quadrupled = compose((get) => get(doubled) * 2);
+
+// ----- Side Effects ----- //
+
+// Old
+ctx.watch([$count, $quadrupled], (count, quadrupled) => {
+  if (count > 25) {
+    console.log($doubled.get()); // not tracked
+
+    console.log(quadrupled);
+    // changes to $quadrupled will trigger this callback to re-run, even if count is still <= 25
+  }
+});
+
+// New
+ctx.effect((get) => {
+  // count is tracked by reading it with 'get'
+  if (get(count) > 25) {
+    console.log(doubled.value); // not tracked
+
+    get(quadrupled); // only tracked while count > 25 (this 'get' doesn't run otherwise)
+    // changes to 'quadrupled' will NOT trigger this callback to re-run unless 'count' is already >= 25
+  }
+});
+```
+
+Atoms and composed values implement the `Reactive<T>` interface for TypeScript purposes. There is also `Atom<T>` and `Composed<T>` if you want to be specific.
+
+The API above is a remix of Preact signals, Jotai and the TC39 Signals proposal. I strongly dislike automatic dependency tracking. I think the developer should explicitly describe what they want instead of having the language assume what they want and making them opt out with `untrack` and such. Madness.
+
+It's also unintuitive what's a tracked scope and what isn't. There's nothing to tell you that at a glance. It's left up to the framework conventions. With this API you know; if you're in a function scope and you have a getter, you're in a tracking-capable scope. Doing that tracking is then left up to you. You can explicitly see that things are being tracked by reading the code. There is no background knowledge needed and no side effects required.
+
+Further API:
+
+```js
+// If count is reactive we get its current value. Otherwise we get it as is.
+const value = unwrap(count);
+
+// If count is reactive we get it as is (typed as Reactive<T>). Otherwise we get it wrapped as a Reactive<T>.
+const value = reactive(count);
+```
+
+```js
+const me = compose((get) => {
+  const id = get(userId);
+  return get(users)_?.find((u) => u.id === id);
+});
+
+const $me = derive([$userId, $users], (id, users) => users?.find((u) => u.id === id));
+```
+
+```js
+const Counter = view("Counter", function () {
+  const count = atom(0);
+
+  return html`
+    <div>
+      <span>${count}</span>
+
+      <button onclick=${() => count.value++}>Increment</button>
+      <button onclick=${() => count.value--}>Decrement</button>
+    </div>
+  `;
+});
+
+const Routes = view("Routes", function () {
+  this.onMount(function () {
+    // this still refers to view context
+    this.log("hello!");
+  });
+
+  return html`
+    <div>
+      ${this.router(function () {
+        this.route("/path", View);
+
+        this.route("/nested", Layout, function () {
+          this.route("/test", Nested); // RouterOutlet passed as children
+        });
+      })}
+    </div>
+  `;
+});
+
+const CounterStore = store("Counter", function () {
+  const count = atom(0);
+
+  return {
+    count: compose(() => get(count)),
+
+    increment() {
+      count.value++;
+    },
+    decrement() {
+      count.value--;
+    },
+  };
+});
+
+const Counter = view("Counter", function () {
+  const counter = this.attach(CounterStore);
+
+  // const { count, increment, decrement } = this.get(CounterStore);
+
+  return html`
+    <div>
+      <span>${counter.count}</span>
+
+      <button onclick=${counter.increment}>Increment</button>
+      <button onclick=${counter.decrement}>Decrement</button>
+    </div>
+  `;
+});
+```

package/notes/context-routes.md

@@ -0,0 +1,56 @@
+# Context routing
+
+I had an idea to integrate routing back into views instead of having a separate router. I originally had it work this way but I wasn't good enough to pull it off then.
+
+Here's how it might look:
+
+```jsx
+function Example(props, ctx) {
+  return <div>
+    <header>
+      <h1>Some kind of layout.</h1>
+    </header>
+    <main>
+      {ctx.router([
+        // Route path is relative to parent routes.
+        // Nested route definitions are a thing of the past.
+        // View could define its own routes.
+        { path: "something/*", view: SomethingView }
+      ])}
+    </main>
+  <div>
+}
+
+html`
+  <${Router}>
+    <${Route} path="something/*">
+      This child content isn't materialized until the route matches.
+      <${SomethingView} />
+    <//>
+  <//>
+`
+```
+
+This removes the need to import and define the whole app at the top level. You can also add routes as you need them when prototyping.
+
+Route matching would be done by forwarding the wildcard portion of a match to child routers. Routers would be stored on the element context.
+
+Where would route info be stored then? It would have to be on the context as well.
+
+```js
+// Merged data from all parent segments.
+ctx.route.params;
+ctx.route.query;
+ctx.route.path;
+ctx.route.pattern;
+
+ctx.go("/some/path");
+ctx.back();
+ctx.forward();
+```
+
+## Thoughts
+
+- Would eliminate the need for `ctx.outlet()`. Can pass children directly via `children` prop now.
+- Would eliminate the need for `ViewElement` and `setChildView` method because a top level router no longer needs to call it.
+- Couldn't do the current routing strategy to combining all routes into one flat list at the top level.