@manyducks.co/dolla 2.0.0 → 3.0.0

package/README.md

@@ -1,151 +1,179 @@
-# 🖥 @manyducks.co/dolla
+# 💲 @manyducks.co/dolla
 
 ![bundle size](https://img.shields.io/bundlephobia/min/@manyducks.co/dolla)
 ![bundle size](https://img.shields.io/bundlephobia/minzip/@manyducks.co/dolla)
 
-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 research framework for trying out ideas. The goal is to create a full-featured framework that, first and foremost, provides the best developer experience possible out of the box. Low resource usage and small code size are secondary objectives. It's more than a toy and less than a production-ready workhorse. It's a labor of love. Use at your own joy and peril.
 
-- ⚡️ [**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.
+- 🚥 [**Signals**](./docs/reactivity.md) for pinpoint DOM updates.
+- 📦 Reusable components in two types:
+  - 🖥️ **Views** for reusable UI elements.
+  - 💾 **Stores** for sharing state across many views.
+- 🔀 A client-side [**router**](./src/router/README.md) with nested routes, auth guards, async data loading and more.
+- 📍 A simple [**i18n system**](./src/translate/README.md). Put your translated strings in a JSON file and access them with the `t` function in your views.
+- 🍳 The build step is optional. You can use a bundler (like Vite) and [write JSX](./docs/jsx.md), or skip the build step and use `html` tagged templates.
 
-## Check it out: The Counter Example
+## Shut up and show me
 
-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.
+Here's an app that displays "Hello World" or "Goodbye World" and a button to toggle which message is displayed.
 
 ```jsx
-import { useSignal, useEffect, createApp } from "@manyducks.co/dolla";
+import { html, createAtom, createRoot, compose } from "@manyducks.co/dolla";
 
-function Counter() {
-  // 1. Make a reactive thingy, we call it a "signal".
-  const [$count, setCount] = useSignal(0);
-
-  function increment() {
-    setCount((current) => current + 1);
-  }
+function Hello() {
+  const [value, setValue] = createAtom(false);
 
-  // 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());
-  });
+  const word = compose(() => (value() ? "Hello" : "Goodbye"));
 
-  return (
-    <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>
-  );
+  return html`
+    <p>${word} World</p>
+    <button onClick=${() => setValue((current) => !current)}>Toggle</button>
+  `;
 }
-```
 
-### 1\. `useSignal` - State that's actually simple
+createRoot(document.body).mount(Hello);
+```
 
-You make state with `useSignal()`, and it gives you back a `[getter, setter]` pair, just like `useState` in React.
+And here's a counter with a lot more going on, plus some comments to explain what's happening.
 
-- `$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.
+```jsx
+import { html, createAtom, createRoot, onMount, onCleanup, onEffect, showIf } from "@manyducks.co/dolla";
 
-When you need the value in your JS code (like in a `useEffect`), just call it like a function: `$count()`.
+function Counter() {
+  // An atom is the basic building block of dynamic state.
+  // It consists of a getter function and a setter function, returned as a tuple:
+  const [count, setCount] = createAtom(0);
+
+  // Atoms can be composed to derive state from one or more other states.
+  // Composed states update automatically with the values of any atoms they call.
+  const isALot = compose(() => count() > 100);
+
+  // Composed states are lazy-computed if dependencies have changed.
+  isALot(); // computes the value; returns false
+  isALot(); // returns cached value (count has not changed)
+  isALot(); // returns cached value (count has not changed)
+
+  // Hooks can bind logic to the component lifecycle or store and access data on the context.
+  // They always take the Context object as a first argument by convention.
+  onMount(this, () => {
+    console.log("I'll be called when Counter is on the page");
+
+    // You can call hooks wherever and whenever you want as long as you have a Context object to pass.
+    onCleanup(this, () => {
+      console.log("I'll be called when Counter is no longer on the page");
+    });
+  });
 
-### 2\. Effects without the headache
+  // Effects run side-effect code in response to state changes.
+  // Just like `compose`, the effect tracks getters called within and re-runs when values change.
+  onEffect(this, () => {
+    console.log("count has changed:", count());
+  });
 
-`useEffect` and `useMemo` are here, but they're way more chill.
+  // Getters can be dropped into the DOM where dynamic values are needed,
+  // either as children or as HTML attributes. DOM nodes will update in sync with state changes.
+  return html`
+    <div>
+      <p>Count: ${count}</p>
 
-- **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.
+      <button disabled=${isALot} onClick=${() => setCount((current) => current + 1)}>Increment</button>
 
-<!-- end list -->
+      ${showIf(isALot, html`<p>That's a lot!</p>`)}
+    </div>
+  `;
+  // ^ You can use view helpers like `showIf`, `hideIf` and `forEach` for control flow in templates.
+}
 
-```jsx
-const [$count, setCount] = useSignal(0);
-const [$name, setName] = useSignal("Dolla");
-
-// AUTOMATIC: Runs if $count OR $name changes. Simple.
-useEffect(() => {
-  console.log(`Yo ${$name()}, the count is ${$count()}`);
-});
-
-// 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]);
+// A root will create and mount an instance of a view onto a DOM node.
+createRoot(document.body).mount(Counter);
 ```
 
-### 3\. No VDOM, no problem
+A few points to notice:
 
-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.
+- The component function runs only once when the component is initialized (no re-renders).
+- _All_ changes at runtime are a result of atoms being set.
+- All DOM updates are synchronous with state changes. You can use [`batch`](./docs/reactivity.md) to process several changes as one.
+- Getters are tracked in `compose` and `createEffect`/`onEffect` callbacks. You can use [`peek`](./docs/reactivity.md) to opt-out of tracking.
 
-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.
+## Dependent data flow
 
-## The Dolla Building Blocks
+Apps are built by composing atoms into ever more complex data structures, eventually attaching the fingers of the monstrosity to some switches and levers that can manipulate DOM nodes.
 
-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()`.
+Imagine your state as a hamster. Your job is to create a mech suit around the hamster so when he twitches his paw his 10 ton fist takes a chunk out of a mountainside. This is no ordinary hamster; it's your app's state, and the mountainside is the DOM. And the mech suit is your code. Built out of Dolla parts. Yes.
 
-### 1\. Views: Your UI stuff
+Now that everything is clear, here's what that looks like in practice. Only a single number changes, but three values are displayed in sync with the original number. A few small state changes cause large changes visible to the user. It's easy to understand what data is important.
 
-**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.
+```tsx
+import { html, createRoot, createAtom, compose } from "@manyducks.co/dolla";
 
-```jsx
-function ExampleView(props) {
-  const context = useContext();
-  const [$count, setCount] = useSignal(0);
+function Converter() {
+  // Just one source value that changes.
+  const [celsius, setCelsius] = createAtom(0);
 
-  // The logger automatically knows the component's name!
-  context.log("sup from ExampleView");
+  // Depends on `celsius`; updates when `celsius` updates.
+  const fahrenheit = compose(() => {
+    return (celsius() * 9) / 5 + 32;
+  });
 
-  useMount(() => context.log("we're live!"));
-  useUnmount(() => context.log("aight, i'm out"));
+  // Depends on `fahrenheit`; updates when `fahrenheit` updates.
+  const description = compose(() => {
+    const f = fahrenheit();
+    if (f <= 32) return "Freezing ❄️";
+    if (f >= 90) return "Hot! 🔥";
+    return "Moderate 🌤️";
+  });
 
-  return <div>{$count}</div>;
+  return html`
+    <div>
+      <input
+        type="number"
+        value=${celsius}
+        oninput=${(e) => {
+          // Set by user input.
+          setCelsius(e.target.valueAsNumber);
+        }}
+      />
+
+      <p>Celsius: ${celsius}°C</p>
+      <p>Fahrenheit: ${fahrenheit}°F</p>
+      <p>Condition: ${description}</p>
+    </div>
+  `;
 }
-```
 
-[More on views.](./docs/views.md)
+createRoot(document.body).mount(Converter);
+```
 
-### 2\. Stores: For your shared state
+### Stores for shared state
 
-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.
+Dolla comes with a really easy way to share state across views in the same subtree.
 
 ```jsx
+// Define a Store function:
 function CounterStore() {
-  const [$value, setValue] = useSignal(0);
+  const [value, setValue] = createAtom(0);
 
-  // You can return functions to control how the state gets changed.
+  // We can define our own functions to control how the state gets changed.
   const increment = () => setValue((current) => current + 1);
   const decrement = () => setValue((current) => current - 1);
 
-  return { $value, increment, decrement };
+  // This object is accessible to other components that use this store.
+  return { value, increment, decrement };
 }
 ```
 
-You "provide" a store to a part of your app, and any component inside can just grab it.
+You work with stores using the `addStore` and `getStore` hooks. When you add a store to a part of your app, any component inside can now use it.
+
+> Like an umbrella; it provides shade (state) to those under it, but not next to or above it.
 
 ```jsx
 function App() {
-  // Now, App and any components inside it can use CounterStore.
-  const counter = useStoreProvider(CounterStore);
+  // Creates one instance of CounterStore and returns it for immediate use.
+  const counter = addStore(this, CounterStore);
 
   return (
     <div>
+      {/* Child views inherit context and therefore access to stores above them in the view tree. */}
       <CounterView />
       <button onClick={counter.increment}>Increment</button>
     </div>
@@ -153,203 +181,24 @@ function App() {
 }
 
 function CounterView() {
-  // Just ask for the store you need!
-  const counter = useStore(CounterStore);
-  return <p>Current value: {counter.$value}</p>;
-}
-```
-
-[More on stores.](./docs/stores.md)
-
-### 3\. Mixins: Reusable superpowers
-
-**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 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>
-      {/* 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>
-  );
-}
-```
-
-[More on mixins.](./docs/mixins.md)
-
-### 4\. So, what's this "Context" thing anyway?
-
-**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:
-
-- **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.
-
-## Batteries Included: All The Stuff You Get\! 🧰
-
-Dolla isn't just for rendering. We threw in a bunch of tools so you can stop hunting around on npm.
-
-### A Router that Doesn't Suck
-
-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.
-
-#### Route Patterns
-
-- **Static**: `/dashboard/settings`
-- **Number Param** (only matches numbers): `/users/{#id}`
-- **Anything Param**: `/users/{name}`
-- **Wildcard**: `/files/*`
-
-#### Setting it Up
-
-```jsx
-import { createApp } from "@manyducks.co/dolla";
-import { createRouter } from "@manyducks.co/dolla/router";
-import { ThingIndex, ThingDetails, ThingEdit } from "./views.js";
-
-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
-  ],
-});
-
-const app = createApp(router);
-app.mount(document.body);
-```
-
-#### Using It
-
-Just use the `useRouter()` hook.
-
-```jsx
-import { useEffect } from "@manyducks.co/dolla";
-import { useRouter } from "@manyducks.co/dolla/router";
-
-function ThingDetails() {
-  const router = useRouter();
-  const { $params } = router; // get reactive params
-
-  useEffect(() => {
-    console.log("Current thing ID:", $params().id);
-  });
-
-  function goToNext() {
-    const nextId = $params().id + 1;
-    router.go(`/things/${nextId}`);
-  }
-
-  return (
-    <div>
-      <p>Viewing thing #{$params().id}</p>
-      <button onClick={goToNext}>View Next Thing</button>
-    </div>
-  );
-}
-```
-
-### A Built-in HTTP Client
-
-Dolla has a little `http` client for API calls. It automatically parses JSON and has a sick middleware system.
-
-```jsx
-import { http } from "@manyducks.co/dolla/http";
-
-// 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!
-});
-
-const res = await http.get("/api/users");
-console.log(res.body); // already parsed JSON, leggo
-```
-
-### Internationalization (i18n)
-
-Wanna make your app speak different languages? We got you. Dolla's i18n stuff is super simple.
-
-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.
-
-```jsx
-import { createApp, useSignal } from "@manyducks.co/dolla";
-import { i18n, t } from "@manyducks.co/dolla/i18n";
-
-function CounterView() {
-  return <button>{t("buttonLabel")}</button>;
+  // Returns the same instance of CounterStore.
+  const counter = getStore(this, CounterStore);
+  return <p>Current value: {counter.value}</p>;
 }
-
-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));
 ```
 
-## The Tea: How's Dolla Different?
-
-### vs. React
-
-- **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.
-
-### vs. Angular
-
-- **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.
+### What are stores good for?
 
-### vs. Svelte
+- Authentication state
+- Caching data between router pages
+- Avoiding prop drilling for local state
 
-- **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.
+## Extras
 
-### vs. SolidJS
-
-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.
-
-Choose **SolidJS** if you wanna build your car from scratch.
-
-Choose **Dolla** if you wanna just get in and drive.
-
----
+Now that you've seen how to wire up a Dolla app, here are a few things to try:
 
-For more detail [check out the Docs](./docs/index.md).
+- Add a [router](./src/router/README.md) to create an SPA
+- Add [language translations](./src/translate/README.md) to go international.
 
 ---