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

package/docs/signals.md

@@ -0,0 +1,166 @@
+## ⚡ Reactive Updates with `Signals`
+
+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 your UI must update itself to stay in sync with that state as it changes. JavaScript frameworks all have their own ways of doing this, but there are two main ones; virtual DOM and signals. Dolla follows the Signals philosophy.
+
+[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.
+
+The Signals API in Dolla has just four functions:
+
+- `$` to create a new Source or derived Signal.
+- `get` to unwrap a possible Signal value.
+- `peek` to unwrap a possible Signal value without tracking it.
+- `effect` to run side effects when tracked signals change.
+
+### Basic State API
+
+```js
+import { $ } from "@manyducks.co/dolla";
+
+const count = $(72);
+
+// Get the current value.
+count(): // 72
+
+// Set a new value.
+count(300);
+
+// The State now reflects the latest value.
+count(); // 300
+
+// Data can also be updated by passing an update function.
+// This function takes the current state and returns the next.
+count((value) => value + 1);
+count(); // 301
+```
+
+### Deriving States from other States
+
+#### Example 1: Doubled
+
+```js
+import { $ } from "@manyducks.co/dolla";
+
+// Passing a value to $() results in a Source...
+const count = $(1);
+
+// ...while passing a function results in a Signal with a derived value.
+const doubled = $(() => count() * 2);
+
+count(10);
+doubled(); // 20
+```
+
+##### A note on derived signals.
+
+Because signals are simply functions that return a value, you can also derive state by simply defining a function that returns a value. Any `Source` called in this function will therefore be tracked when this function is called in a tracked scope.
+
+The difference is that the value of the plain function is computed again each and every time that function is called. Wrapping it with `$()` will result in the computed value being cached until one of its dependencies changes. If you are coming from React then you may want to think of this like `useMemo`.
+
+```js
+// Plain getter: OK
+const plainCount = () => count() * 2;
+
+// Signal: OK
+const cachedCount = $(() => count() * 2);
+```
+
+Using plain getters to derive values is perfectly fine. It may be a waste to cache a very simple getter, but if the value is accessed frequently or involves expensive computations then you can get better performance by wrapping it in a Signal.
+
+#### Example 2: Selecting a User
+
+```js
+import { $ } from "@manyducks.co/dolla";
+
+const users = $([
+  { id: 1, name: "Audie" },
+  { id: 2, name: "Bob" },
+  { id: 3, name: "Cabel" },
+]);
+const userId = $(1);
+
+const selectedUser = $(() => users().find((user) => user.id === userId()));
+
+selectedUser(); // { id: 1, name: "Audie" }
+
+userId(3);
+
+selectedUser(); // { 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 { $ } from "@manyducks.co/dolla";
+
+const user = $({ id: 1, name: "Audie" });
+const name = $(() => user().name);
+
+name(); // "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 Signals
+
+```js
+import { $, get } from "@manyducks.co/dolla";
+
+const count = state(512);
+
+// Unwrap the value of count. Returns 512.
+const value = get(count);
+// Passing a non-state value will simply return it.
+const name = get("World");
+
+// If you need to convert a static piece of data into a Signal you can simply wrap it in a getter function.
+const value = () => "Hello";
+```
+
+### In Views
+
+```jsx
+import { $ } from "@manyducks.co/dolla";
+
+function UserNameView(props, ctx) {
+  const name = $(() => props.user().name);
+
+  // Passing an object to `class` results in keys with a truthy value being applied as classes.
+  // Those with falsy values will be ignored.
+  // Signals can be given as values and they will be tracked.
+  return (
+    <span
+      class={{
+        "user-name": true,
+        "is-selected": props.selected
+      }}>
+      {name}
+    </span>
+  );
+})
+
+// In parent view:
+
+const selected = $(false);
+const user = $({ id: 1, name: "Audie" });
+
+<UserNameView selected={selected} user={user} />
+
+// Changing signal values out here will now update the UserNameView internals.
+```
+
+---
+
+End.
+
+- [🗂️ Docs](./index.md)
+- [🏠 README](../README.md)
+- [🦆 That's a lot of ducks.](https://www.manyducks.co)

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/examples/webcomponent/index.html

@@ -0,0 +1,14 @@
+<!DOCTYPE html>
+<html>
+
+<head>
+  <title>Web Component Example</title>
+</head>
+
+<body>
+  <my-counter></my-counter>
+
+  <script type="module" src="./main.js"></script>
+</body>
+
+</html>