@manyducks.co/dolla 2.0.0-alpha.9 → 2.0.0

package/README.md

@@ -3,644 +3,354 @@
 ![bundle size](https://img.shields.io/bundlephobia/min/@manyducks.co/dolla)
 ![bundle size](https://img.shields.io/bundlephobia/minzip/@manyducks.co/dolla)
 
-> WARNING: This package is in active development. It may contain serious bugs and docs may be outdated or inaccurate. Use at your own risk.
+Alright, so Dolla is this new web framework. Ngl, it's pretty sick. It feels like you're writing React, which is cool, but it's also got this crazy fast reactivity thing going on under the hood. It’s built to feel super familiar, but like, way easier to figure out and it comes with all the stuff you actually need to build something.
 
-Dolla is a batteries-included JavaScript frontend framework covering the needs of moderate-to-complex single page apps:
+- ⚡️ [**Signals**](./docs/signals.md) make your UI updates hit different. Your DOM just refreshes instantly, it's lowkey magic.
+- 📦 You got options for [components](./docs/components.md), three different vibes:
+  - 🖥️ [**Views**](./docs/views.md) are for the UI glow up. You know the drill.
+  - 💾 [**Stores**](./docs/stores.md) are for when your components need to share state without all the drama. We don't do prop drilling in this house.
+  - ✨ [**Mixins**](./docs/mixins.md) give your plain HTML elements some extra rizz. Slay.
+- 🪝 [**Hooks**](./docs/hooks.md) let your components actually cook. They're your familiar, React-style toolkit for state (`useSignal`), lifecycle (`useMount`), and more.
+- 🔀 The client-side [**router**](./docs/router.md) actually understands the assignment. Nested routes, middleware for gatekeeping pages (iykyk), preloading data so it's not laggy... it's all there.
+- 🐕 It comes with its own [**HTTP client**](./docs/http.md) so you can stop installing axios. It's got middleware too, so adding auth headers to every request is easy. We stan.
+- 📍 A lowkey [**i18n system**](./docs/i18n.md). Just yeet your translations into a JSON file and the `t` function pulls them. Simple.
+- 🍳 And the biggest flex? The build system is optional. You can [write your JSX like always](./docs/setup.md), or just [use tagged template literals](./docs/buildless.md) straight in the browser with [HTM](https://github.com/developit/htm). It's a whole vibe.
 
-- ⚡ Reactive DOM updates with [State](). Inspired by Signals, but with more explicit tracking.
-- 📦 Reusable components with [Views](#section-views).
-- 🔀 Built in [routing]() with nested routes and middleware support (check login status, preload data, etc).
-- 🐕 Built in [HTTP]() client with middleware support (set auth headers, etc).
-- 📍 Built in [localization]() system (store translated strings in JSON files and call the `t` function to get them).
-- 🍳 Build system optional. Write views in JSX or use `html` tagged template literals.
+## Check it out: The Counter Example
 
-Let's first get into some examples.
-
-## State
-
-### Basic State API
-
-```jsx
-import { createState, toState, valueOf, derive } from "@manyducks.co/dolla";
-
-const [$count, setCount] = createState(72);
-
-// Get value
-$count.get(): // 72
-
-// Replace the stored value with something else
-setCount(300);
-$count.get(); // 300
-
-// You can also pass a function that takes the current value and returns a new one
-setCount((current) => current + 1);
-$count.get(); // 301
-
-// Watch for changes to the value
-const unwatch = $count.watch((value) => {
-  // This function is called immediately with the current value, then again each time the value changes.
-});
-unwatch(); // Stop watching for changes
-
-// Returns the value of a state. If the value is not a state it is returned as is.
-const count = valueOf($count);
-const bool = valueOf(true);
-
-// Creates a state from a value. If the value is already a state it is returned as is.
-const $bool = toState(true);
-const $anotherCount = toState($count);
-
-// Derive a new state from one or more other states. Whenever $count changes, $doubled will follow.
-const $doubled = derive([$count], (count) => count * 2);
-const $sum = derive([$count, $doubled], (count, doubled) => count + doubled);
-```
-
-States also come in a settable variety that includes the setter on the same object. Sometimes you want to pass around a two-way binding and this is what SettableState is for.
+The best way to get it is to just see it. If you've ever touched React, you'll know what's up, but peep the little things that make your life way easier.
 
 ```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);
+import { useSignal, useEffect, createApp } from "@manyducks.co/dolla";
 
-// 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);
-```
-
-You can also do weird proxy things like this:
-
-```jsx
-// Create an original place for the state to live
-const [$value, setValue] = createState(5);
-
-// Derive a state that doubles the value
-const $doubled = derive([$value], (value) => value * 2);
-
-// Create a setter that takes the doubled value and sets the original $value accordingly.
-const setDoubled = createSetter($doubled, (next, current) => {
-  setValue(next / 2);
-});
-
-// Bundle the derived state and setter into a SettableState to pass around.
-const $$doubled = toSettableState($doubled, setDoubled);
-
-// Setting the doubled state...
-$$doubled.set(100);
-
-// ... will be reflected everywhere.
-$$doubled.get(); // 100
-$doubled.get(); // 100
-$value.get(); // 50
-```
-
-## Views [id="section-views"]
-
-A basic view:
-
-```js
-import Dolla, { createState, html } from "@manyducks.co/dolla";
-
-function Counter(props, ctx) {
-  const [$count, setCount] = createState(0);
+function Counter() {
+  // 1. Make a reactive thingy, we call it a "signal".
+  const [$count, setCount] = useSignal(0);
 
   function increment() {
-    setCount((count) => count + 1);
+    setCount((current) => current + 1);
   }
 
-  return html`
-    <div>
-      <p>Clicks: ${$count}</p>
-      <button onclick=${increment}>+1</button>
-    </div>
-  `;
-}
-
-Dolla.mount(document.body, Counter);
-```
-
-If you've ever used React before (and chances are you have if you're interested in obscure frameworks like this one) this should look very familiar to you.
-
-The biggest difference is that the Counter function runs only once when the component is mounted. All updates after that point are a direct result of `$count` being updated.
-
-## Advanced Componentry
-
-Component functions take two arguments; props and a `Context` object. Props are passed from parent components to child components, and `Context` is provided by the app.
-
-> The following examples are shown in TypeScript for clarity. Feel free to omit the type annotations in your own code if you prefer vanilla JS.
-
-### Props
-
-Props are values passed down from parent components. These can be static values, signals, callbacks and anything else the child component needs to do its job.
-
-```tsx
-import { type State, type Context, html } from "@manyducks.co/dolla";
-
-type HeadingProps = {
-  $text: State<string>;
-};
-
-function Heading(props: HeadingProps, c: Context) {
-  return html`<h1>${props.$text}</h1>`;
-}
-
-function Layout() {
-  const [$text, setText] = signal("HELLO THERE!");
+  // 2. This effect just works. It knows to re-run when $count changes. No drama.
+  useEffect(() => {
+    // to get a signal's value, just call it like a function. easy.
+    console.log("Count is: " + $count());
+  });
 
   return (
-    <section>
-      <Heading $text={$text}>
-    </section>
+    <div>
+      {/* 3. In your HTML, just drop the signal right in. */}
+      <p>Counter: {$count}</p>
+
+      {/* 4. Using signals with helpers like <Show> is a total breeze. */}
+      <Show when={() => $count() > 100}>
+        <p>Whoa, that's a lotta clicks!</p>
+      </Show>
+
+      <div>
+        <button onClick={increment}>+1</button>
+        {/* ... other buttons */}
+      </div>
+    </div>
   );
 }
 ```
 
-### Context
-
-```tsx
-import { type State, type Context, html } from "@manyducks.co/dolla";
+### 1\. `useSignal` - State that's actually simple
 
-type HeadingProps = {
-  $text: State<string>;
-};
+You make state with `useSignal()`, and it gives you back a `[getter, setter]` pair, just like `useState` in React.
 
-function Heading(props: HeadingProps, c: Context) {
-  // A full compliment of logging functions:
-  // Log levels that get printed can be set at the app level.
+- `$count`: This is the **signal**. We just use a `$` at the start by convention. Think of it as a reactive value you can just plop into your JSX.
+- `setCount`: This is how you change the value. Works just like you'd think.
 
-  c.trace("What's going on? Let's find out.");
-  c.info("This is low priority info.");
-  c.log("This is normal priority info.");
-  c.warn("Hey! This could be serious.");
-  c.error("NOT GOOD! DEFINITELY NOT GOOD!!1");
+When you need the value in your JS code (like in a `useEffect`), just call it like a function: `$count()`.
 
-  // And sometimes things are just too borked to press on:
-  c.crash(new Error("STOP THE PRESSES! BURN IT ALL DOWN!!!"));
-
-  // The four lifecycle hooks:
-
-  // c.beforeMount(() => {
-  //   c.info("Heading is going to be mounted. Good time to set things up.");
-  // });
-
-  c.onMount(() => {
-    c.info("Heading has just been mounted. Good time to access the DOM and finalize setup.");
-  });
-
-  // c.beforeUnmount(() => {
-  //   c.info("Heading is going to be unmounted. Good time to begin teardown.");
-  // });
-
-  c.onUnmount(() => {
-    c.info("Heading has just been unmounted. Good time to finalize teardown.");
-  });
-
-  // States can be watched by the component context.
-  // Watchers created this way are cleaned up automatically when the component unmounts.
-
-  c.watch(props.$text, (value) => {
-    c.warn(`text has changed to: ${value}`);
-  });
+### 2\. Effects without the headache
 
-  return html`<h1>${props.$text}</h1>`;
-}
-```
+`useEffect` and `useMemo` are here, but they're way more chill.
 
-## Signals
+- **Automatic Tracking (by default\!)**: You literally don't have to do anything. Dolla just sees what signals you used and re-runs your code when they change.
+- **Manual Tracking (if you're feeling extra)**: If you _really_ want to, you can give it an array of signals to watch. Then it'll _only_ pay attention to those.
 
-Basics
+<!-- end list -->
 
 ```jsx
-const [$count, setCount] = signal(0);
-
-// Set the value directly.
-setCount(1);
-setCount(2);
-
-// Transform the previous value into a new one.
-setCount((current) => current + 1);
-
-// This can be used to create easy helper functions:
-function increment(amount = 1) {
-  setCount((current) => current + amount);
-}
-increment();
-increment(5);
-increment(-362);
+const [$count, setCount] = useSignal(0);
+const [$name, setName] = useSignal("Dolla");
 
-// Get the current value
-$count.get(); // -354
-
-// Watch for new values. Don't forget to call stop() to clean up!
-const stop = $count.watch((current) => {
-  console.log(`count is now ${current}`);
+// AUTOMATIC: Runs if $count OR $name changes. Simple.
+useEffect(() => {
+  console.log(`Yo ${$name()}, the count is ${$count()}`);
 });
 
-increment(); // "count is now -353"
-increment(); // "count is now -352"
-
-stop();
+// MANUAL: This ONLY runs when $count changes.
+// We're using $name() in here, but the effect is like "I don't see it" lol.
+useEffect(() => {
+  console.log(`Yo ${$name()}, the count is ${$count()}`);
+}, [$count]);
 ```
 
-Derive
+### 3\. No VDOM, no problem
 
-```jsx
-import { signal, derive } from "@manyducks.co/dolla";
+Behind the scenes, Dolla isn't re-running your whole component all the time. Nah. It makes a direct connection from your signal to the exact spot in the HTML that uses it.
 
-const [$names, setNames] = signal(["Morg", "Ton", "Bon"]);
-const [$index, setIndex] = signal(0);
+When you `setCount(1)`, Dolla knows only the `<p>` tag and the `<Show>` component care. So it just updates those two things. It's like a ninja. This means no VDOM overhead and it's fast af by default.
 
-// Create a new signal that depends on two existing signals:
-const $selected = derive([$names, $index], (names, index) => names[index]);
+## The Dolla Building Blocks
 
-$selected.get(); // "Morg"
+Dolla gives you a few types of components to keep your code from becoming a mess: **Views**, **Stores**, and **Mixins**. They're all connected by this thing called **context**, which you can grab with `useContext()`.
 
-setIndex(2);
-
-$selected.get(); // "Bon"
-```
+### 1\. Views: Your UI stuff
 
-Proxy
+**Views** are your normal, everyday components for putting stuff on the screen. If you know React components, you're already a pro. They get `props`, use hooks, and return JSX.
 
 ```jsx
-import { createState, createProxyState } from "@manyducks.co/dolla";
-
-const [$names, setNames] = createState(["Morg", "Ton", "Bon"]);
-const [$index, setIndex] = createState(0);
-
-const [$selected, setSelected] = createProxyState([$names, $index], {
-  get(names, index) {
-    return names[index];
-  },
-  set(next, names, _) {
-    const index = names.indexOf(next);
-    if (index === -1) {
-      throw new Error("Name is not in the list!");
-    }
-    setIndex(index);
-  },
-});
+function ExampleView(props) {
+  const context = useContext();
+  const [$count, setCount] = useSignal(0);
 
-$selected.get(); // "Morg"
-$index.get(); // 0
+  // The logger automatically knows the component's name!
+  context.log("sup from ExampleView");
 
-// Set selected directly by name through the proxy.
-setSelected("Ton");
+  useMount(() => context.log("we're live!"));
+  useUnmount(() => context.log("aight, i'm out"));
 
-// Selected and the index have been updated to match.
-$selected.get(); // "Ton"
-$index.get(); // 1
+  return <div>{$count}</div>;
+}
 ```
 
-## Views
+[More on views.](./docs/views.md)
 
-Views are what most frameworks would call Components. Dolla calls them Views because they deal specifically with stuff the user sees, and because Dolla also has another type of component called Stores that share data between views. We will get into those later.
+### 2\. Stores: For your shared state
 
-At its most basic, a view is a function that returns elements.
+Got some state you need to use in a bunch of different places? **Stores** are for that. It's Dolla's built-in way to handle state so you don't have to go install another library.
 
 ```jsx
-function ExampleView() {
-  return <h1>Hello World!</h1>;
-}
-```
-
-#### View Props
+function CounterStore() {
+  const [$value, setValue] = useSignal(0);
 
-A view function takes a `props` object as its first argument. This object contains all properties passed to the view when it's invoked.
+  // You can return functions to control how the state gets changed.
+  const increment = () => setValue((current) => current + 1);
+  const decrement = () => setValue((current) => current - 1);
 
-```js
-import { html } from "@manyducks.co/dolla";
-
-function ListView(props, ctx) {
-  return html`
-    <ul>
-      <${ListItemView} label="Squirrel" />
-      <${ListItemView} label="Chipmunk" />
-      <${ListItemView} label="Groundhog" />
-    </ul>
-  `;
-}
-
-function ListItemView(props, ctx) {
-  return html`<li>${props.label}</li>`;
+  return { $value, increment, decrement };
 }
 ```
 
+You "provide" a store to a part of your app, and any component inside can just grab it.
+
 ```jsx
-function ListView() {
+function App() {
+  // Now, App and any components inside it can use CounterStore.
+  const counter = useStoreProvider(CounterStore);
+
   return (
-    <ul>
-      <ListItemView label="Squirrel" />
-      <ListItemView label="Chipmunk" />
-      <ListItemView label="Groundhog" />
-    </ul>
+    <div>
+      <CounterView />
+      <button onClick={counter.increment}>Increment</button>
+    </div>
   );
 }
 
-function ListItemView(props) {
-  return <li>{props.label}</li>;
+function CounterView() {
+  // Just ask for the store you need!
+  const counter = useStore(CounterStore);
+  return <p>Current value: {counter.$value}</p>;
 }
 ```
 
-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
+[More on stores.](./docs/stores.md)
 
-#### `cond($condition, whenTruthy, whenFalsy)`
+### 3\. Mixins: Reusable superpowers
 
-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.
+**Mixins** are a super cool way to add reusable behaviors to your HTML elements. A mixin is just a function you can slap onto any element, and it can have its own state and lifecycle. It's perfect for stuff like logging, animations, or whatever else you can dream up.
 
 ```jsx
-function ConditionalListView({ $show }) {
+function logLifecycle() {
+  // A mixin is just a function...
+  return (element) => {
+    // ...that takes an element and can use hooks inside.
+    const context = useContext();
+    useMount(() => context.log("element mounted!", element));
+    useUnmount(() => context.log("element unmounted!"));
+  };
+}
+
+// Then you can use it in any View.
+function MyComponent() {
   return (
     <div>
-      {cond(
-        $show,
-
-        // Visible when truthy
-        <ul>
-          <ListItemView label="Squirrel" />
-          <ListItemView label="Chipmunk" />
-          <ListItemView label="Groundhog" />
-        </ul>,
-
-        // Visible when falsy
-        <span>List is hidden</span>,
-      )}
+      {/* Just call it in the `mixin` prop. */}
+      <h1 mixin={logLifecycle()}>I'll log when I show up and leave.</h1>
+
+      {/* You can even use an array of 'em! */}
+      <p mixin={[logLifecycle(), otherMixin()]}>Me too!</p>
     </div>
   );
 }
 ```
 
-#### `repeat($items, keyFn, renderFn)`
+[More on mixins.](./docs/mixins.md)
 
-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.
+### 4\. So, what's this "Context" thing anyway?
 
-```jsx
-function RepeatedListView() {
-  const $items = Dolla.toState(["Squirrel", "Chipmunk", "Groundhog"]);
+**Context** is basically the glue that holds all your components together. Think of it like a family tree. Every component has its own context, but it's linked to its parent. This lets you do some cool stuff:
 
-  return (
-    <ul>
-      {repeat(
-        $items,
-        (item) => item, // Using the string itself as the key
-        ($item, $index, ctx) => {
-          return <ListItemView label={$item} />;
-        },
-      )}
-    </ul>
-  );
-}
-```
+- **Finding Things**: When you do `useStore(CounterStore)`, Dolla just climbs up the family tree from your component until it finds where you provided the store. It's how some component deep in your app can get state from way up top.
+- **Helpful Tools**: The context itself has some neat tricks. The logging methods (`.log()`, `.warn()`, etc.) automatically know your component's name, which is awesome for debugging. There's even a `.crash()` that'll just stop the app and show an error page if things go really wrong. You can get and set the component's name with `context.getName()` and `context.setName()`.
+- **Deep-level State**: Context has its own key-value state system with `setState()` and `getState()`. The framework uses this a bunch. It's there if you wanna get wild, but tbh, for your app's state, **you should probably just use Stores.** They're way easier.
 
-#### `portal(content, parentNode)`
+## Batteries Included: All The Stuff You Get\! 🧰
 
-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.
+Dolla isn't just for rendering. We threw in a bunch of tools so you can stop hunting around on npm.
 
-```jsx
-function PortalView() {
-  const content = (
-    <div class="modal">
-      <p>This is a modal.</p>
-    </div>
-  );
+### A Router that Doesn't Suck
 
-  // Content will be appended to `document.body` while this view is connected.
-  return portal(document.body, content);
-}
-```
+Dolla has a router for making multi-page apps. It just works. Back/forward buttons, bookmarks, all that jazz. It's also smart and always picks the _most specific_ route, so you don't get weird bugs based on the order you write your routes.
 
-### View Context
+#### Route Patterns
 
-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.
+- **Static**: `/dashboard/settings`
+- **Number Param** (only matches numbers): `/users/{#id}`
+- **Anything Param**: `/users/{name}`
+- **Wildcard**: `/files/*`
 
-#### Printing Debug Messages
+#### Setting it Up
 
 ```jsx
-function ExampleView(props, ctx) {
-  // Set the name of this view's context. Console messages are prefixed with name.
-  ctx.name = "CustomName";
+import { createApp } from "@manyducks.co/dolla";
+import { createRouter } from "@manyducks.co/dolla/router";
+import { ThingIndex, ThingDetails, ThingEdit } from "./views.js";
 
-  // 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"));
+const router = createRouter({
+  routes: [
+    {
+      path: "/things",
+      view: null, // a null view just groups routes
+      routes: [
+        { path: "/", view: ThingIndex }, // matches `/things`
+        { path: "/{#id}", view: ThingDetails }, // matches `/things/123`
+        { path: "/{#id}/edit", view: ThingEdit }, // matches `/things/123/edit`
+      ],
+    },
+    { path: "*", redirect: "/things" }, // catch-all
+  ],
+});
 
-  return <h1>Hello World!</h1>;
-}
+const app = createApp(router);
+app.mount(document.body);
 ```
 
-#### Lifecycle Events
+#### Using It
 
-```jsx
-function ExampleView(props, ctx) {
-  ctx.beforeConnect(() => {
-    // Do something before this view's DOM nodes are created.
-  });
+Just use the `useRouter()` hook.
 
-  ctx.onConnected(() => {
-    // Do something immediately after this view is connected to the DOM.
-  });
+```jsx
+import { useEffect } from "@manyducks.co/dolla";
+import { useRouter } from "@manyducks.co/dolla/router";
 
-  ctx.beforeDisconnect(() => {
-    // Do something before removing this view from the DOM.
-  });
+function ThingDetails() {
+  const router = useRouter();
+  const { $params } = router; // get reactive params
 
-  ctx.onDisconnected(() => {
-    // Do some cleanup after this view is disconnected from the DOM.
+  useEffect(() => {
+    console.log("Current thing ID:", $params().id);
   });
 
-  return <h1>Hello World!</h1>;
-}
-```
-
-#### Displaying Children
-
-The context object has an `outlet` function that can be used to display children at a location of your choosing.
+  function goToNext() {
+    const nextId = $params().id + 1;
+    router.go(`/things/${nextId}`);
+  }
 
-```js
-function LayoutView(props, ctx) {
   return (
-    <div className="layout">
-      <OtherView />
-      <div className="content">{ctx.outlet()}</div>
+    <div>
+      <p>Viewing thing #{$params().id}</p>
+      <button onClick={goToNext}>View Next Thing</button>
     </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>
-  );
-}
 ```
 
-#### Observing States
+### A Built-in HTTP Client
 
-The `observe` function starts observing when the view is connected and stops when disconnected. This takes care of cleaning up observers so you don't have to worry about memory leaks.
+Dolla has a little `http` client for API calls. It automatically parses JSON and has a sick middleware system.
 
 ```jsx
-function ExampleView(props, ctx) {
-  const { $someValue } = ctx.getStore(SomeStore);
+import { http } from "@manyducks.co/dolla/http";
 
-  ctx.observe($someValue, (value) => {
-    ctx.log("someValue is now", value);
-  });
-
-  return <h1>Hello World!</h1>;
-}
-```
-
-#### Routing
-
-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 from "@manyducks.co/dolla";
-import { PersonDetails, ThingIndex, ThingDetails, ThingEdit, ThingDelete } from "./views.js";
-
-Dolla.router.setup({
-  routes: [
-    { path: "/people/{name}", view: PersonDetails },
-    {
-      // 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`
-      ],
-    },
-  ],
+// Automatically add an auth header to all API calls
+http.use(async (req, next) => {
+  if (req.url.pathname.startsWith("/api/")) {
+    req.headers.set("authorization", `Bearer ${localStorage.getItem("api-key")}`);
+  }
+  await next(); // don't forget this part!
 });
-```
 
-As you may have inferred from the code above, 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 anywhere through `Dolla.router`.
-
-```js
-function PersonDetails(props, ctx) {
-  // Info about the current route is exported as a set of Readables. Query params are also Writable through $$query:
-  const { $path, $pattern, $params, $query } = Dolla.router;
-
-  Dolla.router.back(); // Step back in the history to the previous route, if any.
-  Dolla.router.back(2); // Hit the back button twice.
+const res = await http.get("/api/users");
+console.log(res.body); // already parsed JSON, leggo
+```
 
-  Dolla.router.forward(); // Step forward in the history to the next route, if any.
-  Dolla.router.forward(4); // Hit the forward button 4 times.
+### Internationalization (i18n)
 
-  Dolla.router.go("/things/152"); // Navigate to another path within the same app.
-  Dolla.router.go("https://www.example.com/another/site"); // Navigate to another domain entirely.
+Wanna make your app speak different languages? We got you. Dolla's i18n stuff is super simple.
 
-  // Three ways to confirm with the user that they wish to navigate before actually doing it.
-  Dolla.router.go("/another/page", { prompt: true });
-  Dolla.router.go("/another/page", { prompt: "Are you sure you want to leave and go to /another/page?" });
-  Dolla.router.go("/another/page", { prompt: PromptView });
+The best part? `t()` gives you back a **signal**. So if the user switches languages, your whole app just updates. Automatically. It's kinda magic.
 
-  // Get the live value of `{name}` from the current path.
-  const $name = Dolla.derive([$params], (p) => p.name);
+```jsx
+import { createApp, useSignal } from "@manyducks.co/dolla";
+import { i18n, t } from "@manyducks.co/dolla/i18n";
 
-  // Render it into a <p> tag. The name portion will update if the URL changes.
-  return <p>The person is: {$name}</p>;
+function CounterView() {
+  return <button>{t("buttonLabel")}</button>;
 }
+
+const app = createApp(CounterView);
+
+// Set up your languages before you start the app
+i18n
+  .setup({
+    locale: "en",
+    translations: [
+      { locale: "en", strings: { buttonLabel: "Click me!" } },
+      { locale: "ja", strings: { buttonLabel: "押してね！" } },
+    ],
+  })
+  .then(() => app.mount(document.body));
 ```
 
-## HTTP Client
+## The Tea: How's Dolla Different?
 
-```js
-// Middleware!
-Dolla.http.use((request, next) => {
-  // Add auth header for all requests going to the API.
-  if (request.url.pathname.startsWith("/api")) {
-    request.headers.set("authorization", `Bearer ${authToken}`);
-  }
+### vs. React
 
-  const response = await next();
+- **No More Re-Renders (Fr!)**: This is the big one. In React, when you call `setCount(1)`, your _entire component function runs all over again_. React then has to figure out what changed with the VDOM. In Dolla, your component function only runs once, ever. When you call `setCount(1)`, Dolla just goes and changes the text in that one `<p>` tag. That's it. This makes it way faster and easier to reason about.
+- **Goodbye, `useCallback`**: Because React re-renders all the time, it creates new functions and objects on every single render. This is why you have to wrap everything in `useCallback` and `useMemo` so you don't cause a chain reaction of re-renders in your child components. Since Dolla components don't re-render, you can just pass a regular function as a prop without a single worry. No more referential equality drama.
+- **Easier Effects**: You know that annoying dependency array? Gone. Unless you, like, _want_ to use it for manual control. This means no more stale closure bugs.
+- **State Management Included**: `Stores` are built in, so you can probably skip installing Redux or Zustand and all the boilerplate that comes with them.
 
-  // Could do something with the response here.
+### vs. Angular
 
-  return response;
-});
+- **Way Less Boilerplate**: Angular is a whole ceremony. Modules, decorators, dependency injection... it's a lot. Dolla is just functions. You write a function, it becomes a component. It's a much more direct vibe.
+- **Stores are like Services, but chill**: Ngl, our `Stores` were lowkey inspired by Angular's services. It's the same idea of providing a thing in one place and using it somewhere else. But instead of all the module and decorator ceremony, you just use a couple of simple hooks.
+- **Signals First, Not an Add-on**: Yeah, Angular has signals now, but the whole framework was built on a different system (Zone.js). Dolla was born with signals as its main character, so the whole DX is built around them. It's not an optional extra, it's the whole point.
 
-const exampleResponse = await Dolla.http.get("/api/example");
+### vs. Svelte
 
-// Body is already parsed from JSON into an object.
-exampleResponse.body.someValue;
-```
+- **It's Just JS**: Dolla is just functions and JSX. Svelte has its own `.svelte` file type and special syntax. Dolla just fits into the normal JS world.
+- **Clearer Updates**: In Dolla, you `setCount(1)`. You know what's happening. In Svelte, `count += 1` is kinda magic.
+- **Consistent Vibe**: Everything in Dolla uses the same hook style. It all feels the same.
 
-## Localization
+### vs. SolidJS
 
-```js
-import Dolla, { html, t } from "@manyducks.co/dolla";
+Okay, Solid is sick, ngl. It uses signals too. The main difference is the vibe. Solid is like getting a super-tuned car engine. **Dolla is the whole car.** With heated seats and a good sound system.
 
-function Counter(props, ctx) {
-  const [$count, setCount] = Dolla.createState(0);
+Choose **SolidJS** if you wanna build your car from scratch.
 
-  function increment() {
-    setCount((count) => count + 1);
-  }
-
-  return html`
-    <div>
-      <p>Clicks: ${$count}</p>
-      <button onclick=${increment}>${t("buttonLabel")}</button>
-    </div>
-  `;
-}
+Choose **Dolla** if you wanna just get in and drive.
 
-Dolla.i18n.setup({
-  locale: "en",
-  translations: [
-    { locale: "en", strings: { buttonLabel: "Click here to increment" } },
-    { locale: "ja", strings: { buttonLabel: "ここに押して増加する" } },
-  ],
-});
+---
 
-Dolla.mount(document.body, Counter);
-```
+For more detail [check out the Docs](./docs/index.md).
 
 ---
 
-[🦆](https://www.manyducks.co)
+[🦆 That's a lot of ducks.](https://www.manyducks.co)