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

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, createView } from "@manyducks.co/dolla";
+
+const UserNameView = createView(function (props) {
+  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, { 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

@@ -1,5 +1,308 @@
 # Views
 
-> TODO: Write me.
+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.
 
-This page goes into detail on Views; props, context, applying styles and classes, etc.
+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/notes/stores.md

@@ -0,0 +1,73 @@
+# Stores
+
+Ideas for updating the API.
+
+```js
+import { createStore, attachStore, useStore, createView } from "@manyducks.co/dolla";
+
+const Counter = createStore(function (initialCount: number) {
+  const [$value, setValue] = createState(initialCount);
+
+  this.on("counter:increment", (e) => {
+    e.stopPropagation(); // Stop this event from bubbling up to counters at higher levels (if any).
+    setValue((current) => current + 1);
+  });
+
+  this.on("counter:decrement", (e) => {
+    e.stopPropagation();
+    setValue((current) => current - 1);
+  });
+
+  // Events can be emitted from this context in a store.
+  this.emit("otherEvent");
+
+  this.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.
+  });
+  this.onUnmount(() => {
+    // Cleanup
+  });
+
+  // Context variables will be accessible on the same context (e.g. the view this is attached to and below)
+  this.get("context variable");
+  this.set("context variable", "context variable value");
+
+  // Stores don't have to return anything, but if they do it becomes accessible by using `useStore(ctx, Store)`.
+  return $value;
+});
+
+// Attach it to the app.
+Dolla.attachStore(Counter(0));
+
+const ExampleView = createView(function () {
+  // useStore lets you access the return value
+  // but the events will still be received and handled regardless
+  const $count = this.useStore(Counter);
+
+  // Convenience helper to attach and use in one step?
+  const $count = this.attachAndUseStore(Counter(0));
+
+  return html`
+    <button onclick=${() => this.emit("counter:decrement")}>-1</button>
+    <span>${$count}</span>
+    <button onclick=${() => this.emit("counter:increment")}>+1</button>
+  `;
+});
+
+// ViewContext is also still passed as a second argument if you'd rather use arrow functions to define views.
+const ExampleView = createView((props, self) => {
+  // useStore lets you access the return value
+  // but the events will still be received and handled regardless
+  const $count = self.useStore(Counter);
+
+  return html`
+    <button onclick=${() => self.emit("counter:decrement")}>-1</button>
+    <span>${$count}</span>
+    <button onclick=${() => self.emit("counter:increment")}>+1</button>
+  `;
+});
+```
+
+This means `createStore` returns a function that is called to create a Store instance. The instance is

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@manyducks.co/dolla",
-  "version": "2.0.0-alpha.27",
+  "version": "2.0.0-alpha.29",
   "description": "Front-end components, routing and state management.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",