@manyducks.co/dolla 2.0.0-alpha.3 → 2.0.0-alpha.31

package/docs/stores.md

@@ -0,0 +1,62 @@
+# Stores
+
+> TODO: Write about stores
+
+```tsx
+import Dolla, { createStore, createState, createView } from "@manyducks.co/dolla";
+
+const CounterStore = createStore(function (initialValue: number) {
+  const [$count, setCount] = createState(initialValue);
+
+  // Respond to context events which bubble up from views.
+  this.on("counter:increment", () => {
+    setCount((count) => count + 1);
+  });
+
+  this.on("counter:decrement", () => {
+    setCount((count) => count - 1);
+  });
+
+  this.on("counter:reset", () => {
+    setCount(0);
+  });
+
+  return $count;
+});
+
+// Stores can be attached to the app itself.
+// createStore returns a factory function that is called with the store's options to create a new instance.
+Dolla.attachStore(CounterStore(0));
+
+const CounterView = createView(function () {
+  // Store instances can also be attached 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.
+  this.attachStore(CounterStore(0));
+
+  // Store return values can be accessed with `useStore`.
+  // This method will traverse up the view tree to find the nearest attached instance.
+  // An error will be thrown if no instances are attached at or above this level in the tree.
+  const $count = this.useStore(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={() => this.emit("counter:decrement")}>-1</button>
+        <button onClick={() => this.emit("counter:reset")}>Reset</button>
+        <button onClick={() => this.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,308 @@
+# 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 elements.
+
+```jsx
+const ExampleView = createView(function () {
+  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
+const ListItemView = createView(function (props) {
+  return <li>{props.label}</li>;
+});
+
+const ListView = createView(function () {
+  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
+const ConditionalListView = createView(function (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
+const RepeatedListView = createView(function () {
+  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
+const PortalView = createView(function () {
+  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.
+
+The context can be accessed in one of two ways; as `this` when you pass a non-arrow function, or as the second parameter passed after the props object.
+
+```jsx
+// Option 1: Access through `this`
+const ExampleView = createView(function (props) {
+  this.onMount(() => {
+    this.log("HELLO!");
+  });
+
+  return <h1>Hello World!</h1>;
+});
+
+// Option 2: Access as second argument (for arrow functions)
+const ExampleView = createView((props, ctx) => {
+  ctx.onMount(() => {
+    ctx.log("HELLO!");
+  });
+
+  return <h1>Hello World!</h1>;
+});
+```
+
+Which one you use is just an aesthetic preference, but I kind of like the classic `function` syntax with `this`.
+
+### Printing Debug Messages
+
+```jsx
+const ExampleView = createView(function (props) {
+  // Set the name of this view's context. Console messages are prefixed with name.
+  this.setName("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.
+  this.info("Verbose debugging info that might be useful to know");
+  this.log("Standard messages");
+  this.warn("Something bad might be happening");
+  this.error("Uh oh!");
+
+  // If you encounter a bad enough situation, you can halt and disconnect the entire app.
+  this.crash(new Error("BOOM"));
+
+  return <h1>Hello World!</h1>;
+});
+```
+
+### Lifecycle Events
+
+```jsx
+const ExampleView = createView(function (props) {
+  this.beforeMount(() => {
+    // Do something before this view's DOM nodes are created.
+  });
+
+  this.onMount(() => {
+    // Do something immediately after this view is connected to the DOM.
+  });
+
+  this.beforeUnmount(() => {
+    // Do something before removing this view from the DOM.
+  });
+
+  this.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
+const LayoutView = createView(function (props) {
+  return (
+    <div className="layout">
+      <div className="content">{this.outlet()}</div>
+    </div>
+  );
+});
+
+const ExampleView = createView(function () {
+  // <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
+const ExampleView = createView(function (props) {
+  const [$count, setCount] = createState(0);
+
+  // This callback will run when any states in the dependency array receive new values.
+  this.watch([$count], (count) => {
+    this.log("count is now", count);
+  });
+
+  // ...
+});
+```
+
+### Context Variables
+
+> TODO: Write about context state (`.get` and `.set`)
+
+### Context Events
+
+Events can be emitted from views and [stores](./stores.md) using `this.emit(eventName, data)`. Context events will bubble up the view tree just like native browser events bubble up the DOM tree.
+
+```js
+this.on("eventName", (event) => {
+  event.type; // "eventName"
+  event.detail; // the value that was passed when the event was emitted (or undefined if none)
+});
+
+this.once("eventName", (event) => {
+  // Receive only once and then stop listening.
+});
+
+// Remove a listener by reference.
+// Listener must be the same exact function that was passed to `on` or `once`.
+this.off("eventName", listener);
+
+// Emit an event.
+this.emit("eventName", { value: "This object will be exposed as event.detail" });
+```
+
+### Bubbling
+
+Events bubble up through the view tree unless `stopPropagation` is called by a listener. In the following example we have a view listening for events that are emitted from a child of a child.
+
+```js
+const ParentView = createView(function () {
+  // Listen for greetings that bubble up.
+  this.on("greeting", (event) => {
+    const { name, message } = event.detail;
+
+    this.log(`${name} says "${message}"!`);
+  });
+
+  return (
+    <div>
+      <ChildView />
+    </div>
+  );
+});
+
+const ChildView = createView(function () {
+  this.on("greeting", (event) => {
+    // Let's perform some censorship.
+    // If propagation is stopped this event will not bubble any further and ParentView won't see it.
+    if (containsForbiddenKnowledge(event.message)) {
+      event.stopPropagation();
+    }
+  });
+
+  return (
+    <div>
+      <ChildOfChildView />
+    </div>
+  );
+});
+
+const ChildOfChildView = createView(function () {
+  return (
+    <form
+      onSubmit={(e) => {
+        // This is a browser event handler.
+        // Browser events can't be listened for with `this.on`, but we can emit context events from here that can be.
+        e.preventDefault();
+
+        // Pluck the values from the form.
+        const name = e.currentTarget.name.value;
+        const message = e.currentTarget.message.value;
+
+        // Emit!
+        this.emit("greeting", { name, message });
+      }}
+    >
+      <input type="text" name="name" placeholder="Your Name" />
+      <input type="text" name="message" placeholder="Your Message" />
+      <button type="submit">Submit</button>
+    </form>
+  );
+});
+```
+
+---
+
+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/context-vars.md

@@ -0,0 +1,21 @@
+# Idea: Context Variables
+
+In designing how Dolla's version of 'context' works, I've been going through a few different ideas. The simplest seems to be the ability to store _context variables_ that, once set, are accessible on the same context or any child context.
+
+```js
+function SomeView(props, ctx) {
+  ctx.set("key", 5);
+
+  // ... and in a child view do
+  ctx.get("key");
+  // which returns null if the value isn't present.
+  // It's like localStorage for the view tree.
+}
+```
+
+They can be typed, but always with a possibility to return null.
+
+```js
+const value = ctx.get<number>("key");
+// value is number | null to force the programmer to check it.
+```

package/notes/readme-scratch.md

@@ -0,0 +1,222 @@
+# README
+
+> This note will eventually become the new README. Here I'm laying out my ideal framework API.
+
+A basic component.
+
+```jsx
+import Dolla, { createState, derive } from "@manyducks.co/dolla";
+
+function ExampleView(props, ctx) {
+  const [$count, setCount] = createState(5);
+  const $doubled = derive([$count], (n) => n * 2);
+
+  ctx.watch([$count], (count) => {
+    ctx.log("value of count is now %n", count);
+  });
+
+  return <p>{$count}</p>;
+}
+
+Dolla.mount(document.body, ExampleView);
+```
+
+<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);
+}
+```