@manyducks.co/dolla 2.0.0-alpha.6 → 2.0.0-alpha.61

package/docs/i18n.md

@@ -0,0 +1,43 @@
+# Internationalization (i18n) Support
+
+```jsx
+import { $, mount } from "@manyducks.co/dolla";
+import { i18n, t } from "@manyducks.co/dolla/i18n";
+
+
+function CounterView(props) {
+  const $count = $(0);
+
+  const increment = () => {
+    $count(count => count + 1);
+  };
+
+  return (
+    <div>
+      <p>Clicks: {$count}</p>
+      <button onClick={increment}>{t("buttonLabel")}</button>
+    </div>
+  );
+});
+
+// Await i18n setup before mounting the app to make sure translations are loaded.
+i18n
+  .setup({
+    locale: "en",
+    translations: [
+      { locale: "en", strings: { buttonLabel: "Click here to increment" } },
+      { locale: "ja", strings: { buttonLabel: "ここに押して増加する" } },
+    ],
+  })
+  .then(() => {
+    return mount(CounterView, document.body);
+  });
+```
+
+---
+
+End.
+
+- [🗂️ Docs](./index.md)
+- [🏠 README](../README.md)
+- [🦆 That's a lot of ducks.](https://www.manyducks.co)

package/docs/index.md

@@ -0,0 +1,10 @@
+# Dolla Docs
+
+> Write table of contents (see files in this folder in the meantime)
+
+---
+
+End.
+
+- [🏠 README](../README.md)
+- [🦆 That's a lot of ducks.](https://www.manyducks.co)

package/docs/markup.md

@@ -0,0 +1,16 @@
+# Markup
+
+Dolla creates a tree of views that manage the DOM, updating attributes and recreating parts of the DOM as signal values change.
+
+```js
+import { $, m, render } from "@manyducks.co/dolla";
+
+const $count = $(0);
+const labelMarkup = m("span", { children: $count });
+// or in JSX:
+const labelMarkup = <span>{$count}</span>;
+
+const rendered = render(labelMarkup);
+
+rendered.mount(document.body);
+```

package/docs/mixins.md

@@ -0,0 +1,32 @@
+# Mixins
+
+Mixins are a way to add custom lifecycle handlers to plain DOM nodes without creating an entire view. You can encapsulate reusable logic in mixin functions and apply them like CSS classes.
+
+Mixin functions take a reference to the element and a `MixinContext` object which adds lifecycle hooks similar to those of `ViewContext`.
+
+```tsx
+import { type Mixin } from "@manyducks.co/dolla";
+
+const logMe: Mixin = (element, ctx) => {
+  ctx.onMount(() => {
+    ctx.log("element mounted");
+  });
+  ctx.onUnmount(() => {
+    ctx.log("element unmounted");
+  });
+};
+
+// Pass one mixin
+<h1 mixin={logMe}>Title</h1>;
+
+// Or an array of mixins
+<p mixin={[logMe, anotherMixin, yetAnotherMixin]}>Text goes here...</p>;
+```
+
+---
+
+End.
+
+- [🗂️ Docs](./index.md)
+- [🏠 README](../README.md)
+- [🦆 That's a lot of ducks.](https://www.manyducks.co)

package/docs/ref.md

@@ -0,0 +1,93 @@
+# Ref
+
+Refs are functions that serve as a getter and setter for a stored value. Calling a ref with no arguments will return its stored value, or throw an error if no value has yet been stored. Calling a ref with a single argument will store a new value.
+
+This signature is very similar to that of a `Source` signal, with the differences being their error throwing behavior while empty and that refs are _not_ trackable in a signal context.
+
+## Pattern #1: Referencing DOM nodes
+
+The main pattern for refs is as a DOM node reference. Markup elements take a `ref` attribute to which they will pass their DOM node when they are mounted.
+
+Once you have this reference you can manipulate the node outside the usual declarative template workflow.
+
+```tsx
+import { ref } from "@manyducks.co/dolla";
+
+function ExampleView() {
+  const element = ref<HTMLElement>();
+
+  ctx.onMount(() => {
+    element().innerText = "GOODBYE THERE";
+  });
+
+  return <div ref={element}>HELLO THERE</div>;
+}
+```
+
+## Pattern #2: Controlling a child view from a parent view
+
+Another useful pattern is to pass an API object from a child view to the parent, allowing the parent to call methods to control the child view in an imperative way.
+
+```tsx
+import { ref } from "@manyducks.co/dolla";
+
+// First we'll define the view to be controlled.
+
+interface CounterViewControls {
+  increment(): void;
+  decrement(): void;
+  reset(): void;
+}
+
+interface CounterViewProps {
+  controls: Ref<CounterViewControls>;
+}
+
+function CounterView({ controls }: CounterViewProps) {
+  const $count = $(count);
+
+  // Passing a `controls` object to the ref whose methods reference internal state.
+  controls({
+    increment() {
+      $count((current) => current + 1);
+    },
+    decrement() {
+      $count((current) => current - 1);
+    },
+    reset() {
+      $count(0);
+    },
+  });
+
+  return <span>Count: {$count}</span>;
+}
+
+// Then we'll use it in the parent:
+
+function ParentView() {
+  // Create a Ref to store the controls object.
+  const controls = ref<CounterViewControls>();
+
+  return (
+    <section>
+      <h1>Counter</h1>
+
+      {/* CounterView will set the controls object */}
+      <CounterView controls={controls} />
+
+      {/* Our buttons will call the methods on the controls object causing state changes within CounterView */}
+      <button onClick={() => controls.increment()}>+1</button>
+      <button onClick={() => controls.decrement()}>-1</button>
+      <button onClick={() => controls.reset()}>=0</button>
+    </section>
+  );
+}
+```
+
+---
+
+End.
+
+- [🗂️ Docs](./index.md)
+- [🏠 README](../README.md)
+- [🦆 That's a lot of ducks.](https://www.manyducks.co)

package/docs/router.md

@@ -0,0 +1,80 @@
+# Router
+
+Dolla makes heavy use of client-side routing. You can define as many routes as you have views, and the URL
+will determine which one the app shows at any given time. By building an app around routes, lots of things one expects
+from a web app will just work; back and forward buttons, sharable URLs, bookmarks, etc.
+
+Routes are matched by highest specificity regardless of the order they were registered.
+This avoids some confusing situations that come up with order-based routers like that of `express`.
+On the other hand, order-based routers can support regular expressions as patterns which Dolla's router cannot.
+
+## Route Patterns
+
+Routes are defined with strings called patterns. A pattern defines the shape the URL path must match, with special
+placeholders for variables that appear within the route. Values matched by those placeholders are parsed out and exposed
+to your code (`router` store, `$params` readable). Below are some examples of patterns and how they work.
+
+- Static: `/this/is/static` has no params and will match only when the route is exactly `/this/is/static`.
+- Numeric params: `/users/{#id}/edit` has the named param `{#id}` which matches numbers only, such as `123` or `52`. The
+  resulting value will be parsed as a number.
+- Generic params: `/users/{name}` has the named param `{name}` which matches anything in that position in the path. The
+  resulting value will be a string.
+- Wildcard: `/users/*` will match anything beginning with `/users` and store everything after that in params
+  as `wildcard`. `*` is valid only at the end of a route.
+
+Now, here are some route examples in the context of an app:
+
+```js
+import Dolla, { createRouter } from "@manyducks.co/dolla";
+import { ThingIndex, ThingDetails, ThingEdit, ThingDelete } from "./views.js";
+
+const router = createRouter({
+  routes: [
+    {
+      // A `null` component with subroutes acts as a namespace for those subroutes.
+      // Passing a view instead of `null` results in subroutes being rendered inside that view wherever `ctx.outlet()` is called.
+      path: "/things",
+      view: null,
+      routes: [
+        { path: "/", view: ThingIndex }, // matches `/things`
+        { path: "/{#id}", view: ThingDetails }, // matches `/things/{#id}`
+        { path: "/{#id}/edit", view: ThingEdit }, // matches `/things/{#id}/edit`
+        { path: "/{#id}/delete", view: ThingDelete }, // matches `/things/{#id}/delete`
+      ],
+    },
+    // All routes that don't match anything else will redirect to `/things`
+    { path: "*", redirect: "/things" },
+  ],
+});
+
+// Mount the router in place of a view.
+Dolla.mount(document.body, router);
+```
+
+When the URL matches a pattern the corresponding view is displayed. If we visit `/people/john`,
+we will see the `PersonDetails` view and the params will be `{ name: "john" }`. Params can be
+accessed from anywhere in the app through `Dolla.router`.
+
+```js
+import Dolla from "@manyducks.co/dolla";
+
+// Info about the current route is exported as a set of Readables. Query params are also Writable through $$query:
+const { $path, $pattern, $params, $query } = router;
+
+router.back(); // Step back in the history to the previous route, if any.
+router.back(2); // Hit the back button twice.
+
+router.forward(); // Step forward in the history to the next route, if any.
+router.forward(4); // Hit the forward button 4 times.
+
+router.go("/things/152"); // Navigate to another path within the same app.
+router.go("https://www.example.com/another/site"); // Navigate to another domain entirely.
+```
+
+---
+
+End.
+
+- [🗂️ Docs](./index.md)
+- [🏠 README](../README.md)
+- [🦆 That's a lot of ducks.](https://www.manyducks.co)

package/docs/setup.md

@@ -0,0 +1,31 @@
+# Setting up Dolla
+
+## Installation
+
+Dolla is published on npm as `@manyducks.co/dolla`. You can install it in your project with the following command:
+
+```
+npm i @manyducks.co/dolla
+```
+
+## JSX
+
+If you want to use JSX in your app you can add the following options to your `tsconfig.json` or `jsconfig.json`. Modern build systems like [Vite](https://vite.dev) will pick these up automatically.
+
+```json
+{
+  "compilerOptions": {
+    // ... other options ...
+    "jsx": "react-jsx",
+    "jsxImportSource": "@manyducks.co/dolla"
+  }
+}
+```
+
+---
+
+End.
+
+- [🗂️ Docs](./index.md)
+- [🏠 README](../README.md)
+- [🦆 That's a lot of ducks.](https://www.manyducks.co)

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)