@manyducks.co/dolla 2.0.0 → 3.0.0

package/docs/http.md

@@ -1,178 +0,0 @@
-# The HTTP Client
-
-Every app needs to talk to a server at some point, and while you _could_ just use the browser's built-in `fetch`, it's kinda basic. You end up writing the same boilerplate code over and over again for things like setting headers and parsing JSON. It's a vibe killer.
-
-That's why Dolla comes with its own `http` client right out of the box. It's a smart wrapper around `fetch` that makes your life way easier.
-
-**Why you'll actually wanna use it:**
-
-- **Automatic JSON:** It automatically stringifies your request bodies to JSON and parses JSON responses. No more `.then(res => res.json())` chains\!
-- **Middleware:** This is the main event. You can set up "middleware" functions that run on _every single request_. This is clutch for adding auth tokens, logging, or handling errors in one central place.
-- **Clean API:** It's just simple. `http.get('/users')` is way cleaner than a big `fetch` call.
-- **Smart Error Handling:** It automatically throws an error for bad responses (like 404s or 500s), so you don't have to check `res.ok` yourself.
-
-## Basic Requests
-
-The `http` object is a global singleton, so you just import it and go. It has methods for all the common HTTP verbs.
-
-```jsx
-import { http } from "@manyducks.co/dolla/http";
-import { useSignal, useMount } from "@manyducks.co/dolla";
-
-function UserList() {
-  const [$users, setUsers] = useSignal([]);
-
-  useMount(async () => {
-    // Just call the method you need!
-    const res = await http.get("/api/users");
-    // The body is already parsed JSON!
-    setUsers(res.body);
-  });
-
-  return (
-    <ul>
-      <For each={$users}>{(user) => <li>{() => user().name}</li>}</For>
-    </ul>
-  );
-}
-```
-
-Here are the main methods you'll use:
-
-- `http.get(uri, options?)`
-- `http.post(uri, options?)`
-- `http.put(uri, options?)`
-- `http.patch(uri, options?)`
-- `http.delete(uri, options?)`
-
-## Passing Options to a Request
-
-For anything more than a simple GET request, you'll need to pass an `options` object. This is where you put your request body, headers, and query params.
-
-### Sending a `body`
-
-When you use `post`, `put`, or `patch`, you'll probably wanna send some data. Just put your JavaScript object in the `body` property. Dolla will automatically set the `Content-Type` to `application/json` and `JSON.stringify` it for you.
-
-```jsx
-const handleCreateUser = async () => {
-  const newUser = { name: "Alice", email: "alice@example.com" };
-
-  try {
-    const res = await http.post("/api/users", {
-      body: newUser,
-    });
-    console.log("User created!", res.body);
-  } catch (error) {
-    console.error("Failed to create user:", error);
-  }
-};
-```
-
-### Adding `headers`
-
-You can pass a plain object for your headers.
-
-```jsx
-const res = await http.get("/api/some-protected-route", {
-  headers: {
-    "X-Custom-Header": "MyValue",
-  },
-});
-```
-
-### Adding `query` Params
-
-Don't mess with building query strings by hand. Just pass an object to the `query` property and Dolla will build the URL for you.
-
-```jsx
-// This will make a request to /api/users?sort=name&limit=10
-const res = await http.get("/api/users", {
-  query: {
-    sort: "name",
-    limit: 10,
-  },
-});
-```
-
-## Middleware: The Secret Sauce
-
-This is the best part. Middleware is a function that can intercept _every single request_ before it goes out. You can inspect it, change it, or even stop it. It's perfect for stuff you need to do all the time.
-
-You add middleware with `http.use(myMiddleware)`.
-
-### Example: The Auth Header
-
-This is the classic use case. You need to add a `Bearer` token to every request that goes to your API. Instead of adding it to every single call, you just set up a middleware once.
-
-```jsx
-import { http } from "@manyducks.co/dolla/http";
-
-// This middleware will run for EVERY http call
-http.use(async (req, next) => {
-  // Check if the request is going to our API
-  if (req.url.pathname.startsWith("/api/")) {
-    const token = localStorage.getItem("auth_token");
-    if (token) {
-      // Add the auth header!
-      req.headers.set("Authorization", `Bearer ${token}`);
-    }
-  }
-
-  // This part is super important! You HAVE to call next()
-  // to let the request continue on its way.
-  await next();
-});
-
-// Now, this request will automatically have the auth header.
-const profile = await http.get("/api/me");
-```
-
-The `http.use()` function also returns a function that you can call to **remove** that specific middleware later if you need to.
-
-## Handling Responses
-
-When a request is successful, you get a response object back with all the info you need:
-
-- `res.body`: The response body, already parsed for you (usually as JSON).
-- `res.status`: The HTTP status code (e.g., `200`).
-- `res.statusText`: The status text (e.g., `"OK"`).
-- `res.headers`: A `Headers` object with all the response headers.
-- `res.url`: The final `URL` object of the request.
-- `res.method`: The HTTP method that was used.
-
-## Error Handling
-
-Dolla's HTTP client makes error handling way easier. If a request gets a response with a status code in the 400s or 500s (like a `404 Not Found` or `500 Server Error`), it will automatically **throw an error**.
-
-This means you can use a standard `try...catch` block to handle both network failures and bad HTTP responses in the same place.
-
-The error it throws is a special `HTTPResponseError`. The cool part is that the error object itself has a `.response` property, so you can still inspect the full response body, headers, and status, even on a failed request.
-
-```jsx
-const fetchUserData = async (userId) => {
-  try {
-    const res = await http.get(`/api/users/${userId}`);
-    console.log("Got user:", res.body);
-  } catch (error) {
-    // Check if it's an error from the server
-    if (error instanceof HTTPResponseError) {
-      console.error(`Server responded with ${error.response.status}`);
-      console.error("Response body:", error.response.body); // You can still read the error body!
-    } else {
-      // It was probably a network error or something else
-      console.error("An unexpected error occurred:", error.message);
-    }
-  }
-};
-
-fetchUserData(999); // Let's pretend this user doesn't exist
-// Console will log: "Server responded with 404"
-```
-
----
-
-End.
-
-- [🗂️ Docs](./index.md)
-- [🏠 README](../README.md)
-- [🦆 That's a lot of ducks.](https://www.manyducks.co)

package/docs/i18n.md

@@ -1,220 +0,0 @@
-# Dolla's i18n (aka making your app speak other languages)
-
-Aight, so your app is probably in English by default. But what if you wanna go global? That's where internationalization (or "i18n" if you're lazy) comes in. It's the whole process of making your app work in different languages.
-
-You _could_ just use a giant object and some `if` statements, but that's a one-way ticket to spaghetti code city. It's a whole vibe killer.
-
-That's why Dolla comes with its own i18n system right out of the box.
-
-**Why it's lowkey the GOAT:**
-
-- **It's Reactive AF:** The main `t()` function you use to get text returns a **signal**. That means if the user switches languages, your entire UI just updates. Automatically. No cap, it's kinda magic.
-- **Smart String Templates:** You can put variables, format numbers, handle plurals, and all that jazz right in your translation strings. It's super powerful.
-- **Load Translations How You Want:** You can hardcode them, load them from a JSON file, or even fetch them from an API. You do you.
-- **Batteries Included:** It comes with formatters for numbers, dates, and lists, all using the browser's smart `Intl` stuff so it's always correct for whatever language you're in.
-
-## Setting It Up
-
-First things first, you gotta tell Dolla about the languages you support. You do this once when your app starts up, using `i18n.setup()`. It's super important to do this _before_ you mount your app so all the text is ready to go.
-
-```jsx
-import { createApp } from "@manyducks.co/dolla";
-import { i18n } from "@manyducks.co/dolla/i18n";
-import { App } from "./App.jsx";
-
-const app = createApp(App);
-
-// Set up all your languages
-i18n
-  .setup({
-    // Tell it what language to start with. 'auto' is smart and will try to match the user's browser language.
-    locale: "auto",
-    translations: [
-      // You can define strings right here...
-      {
-        locale: "en",
-        strings: {
-          greeting: "Hello, world!",
-          nav: {
-            home: "Home",
-            about: "About Us",
-          },
-        },
-      },
-      // ...or tell it to fetch a JSON file for another language.
-      {
-        locale: "es",
-        path: "/translations/es.json",
-      },
-      // ...or even give it a function that fetches them from an API!
-      {
-        locale: "ja",
-        fetch: () => fetch("/api/translations/ja").then((res) => res.json()),
-      },
-    ],
-  })
-  .then(() => {
-    // Only mount the app AFTER the translations are loaded!
-    app.mount(document.body);
-  });
-```
-
-## The `t()` function: Your New Bestie
-
-This is the main function you'll be using. You import `t` and call it with a key to get the translated string.
-
-```jsx
-import { t } from "@manyducks.co/dolla/i18n";
-
-function Greeting() {
-  // This returns a signal, so it will automatically update if the language changes!
-  return <h1>{t("greeting")}</h1>;
-}
-
-function Navbar() {
-  return (
-    <nav>
-      <a href="/">{t("nav.home")}</a>
-      <a href="/about">{t("nav.about")}</a>
-    </nav>
-  );
-}
-```
-
-If a translation is missing, it won't crash your app. It'll just show something like `[MISSING: your.key]`, so you know you forgot something.
-
-## Smart Strings: Variables and Formatting
-
-This is where the magic happens. You can put placeholders in your strings and pass values to the `t()` function.
-
-### Basic Variables
-
-Just wrap your variable name in double curly braces: `{{variableName}}`. The best part? You can pass signals as values, and the text will update automatically when the signal changes\!
-
-```jsx
-// In your translation file:
-{
-  "welcome_message": "Welcome back, {{username}}!"
-}
-
-// In your component:
-const [$username, setUsername] = useSignal("Alice");
-
-// Because you're passing a signal, this will be reactive!
-const $welcomeText = t("welcome_message", { username: $username });
-
-// $welcomeText() is "Welcome back, Alice!"
-// If you call setUsername("Bob"), $welcomeText() automatically becomes "Welcome back, Bob!"
-```
-
-### Formatting Numbers, Dates, and More\!
-
-You can add formatters to your variables using a pipe `|`. Dolla comes with a few built-in ones.
-
-- **`number`**: For formatting numbers (prices, percentages, etc.).
-- **`datetime`**: For formatting dates and times.
-- **`list`**: For formatting a list of things with commas and "and".
-
-These formatters take options that are the same as the browser's `Intl` APIs, so they're super powerful. And yes, they're fully reactive with signals too.
-
-```jsx
-// In your translation file:
-{
-  "product_price": "Price: {{price | number(style: currency, currency: USD)}}"
-}
-
-// In your component:
-const [$price, setPrice] = useSignal(49.99);
-
-// This text will update automatically if you call setPrice() later!
-const $priceText = t("product_price", { price: $price });
-```
-
-### Custom Formatters
-
-You can even make your own formatters with `i18n.addFormat()`.
-
-```js
-// Set this up once when your app starts
-i18n.addFormat("uppercase", (locale, value) => {
-  return String(value).toUpperCase();
-});
-
-// In your translation file:
-{ "shout": "HEY, {{name | uppercase}}!" }
-
-// In your component:
-t("shout", { name: "Bob" }); // Renders: "HEY, BOB!"
-```
-
-## Plurals and Context: Next-Level i18n
-
-Languages are weird, especially with plurals. Dolla's i18n system has your back.
-
-### Pluralization (`count`)
-
-You can create different versions of a string based on a `count` you pass in. Dolla uses the standard pluralization rules for whatever language you're in (`one`, `other`, `few`, `many`, etc.). And you guessed it—if you pass a signal for the count, the string will automatically switch between singular and plural\!
-
-Just add `_one`, `_other`, etc., to your keys.
-
-```jsx
-// In your translation file:
-{
-  "message_count_one": "You have 1 new message.",
-  "message_count_other": "You have {{count}} new messages."
-}
-
-// In your component:
-const [$messageCount, setMessageCount] = useSignal(1);
-
-// This will automatically switch between the singular and plural versions!
-const $messageText = t("message_count", { count: $messageCount });
-
-// $messageText() is "You have 1 new message."
-// after setMessageCount(5), $messageText() becomes "You have 5 new messages."
-```
-
-### Context (`context`)
-
-Sometimes you need a different translation for the same word based on the situation. For example, a "profile" button might be different for a user vs. a company.
-
-```js
-// In your translation file:
-{
-  "edit_profile": "Edit Profile",
-  "edit_profile_company": "Edit Company Profile"
-}
-
-// In your component:
-const userType = "company";
-t("edit_profile", { context: userType }); // Renders: "Edit Company Profile"
-t("edit_profile");                        // Renders: "Edit Profile"
-```
-
-## Using Formatters Directly
-
-Sometimes you just wanna format a number or a date without a full translation string. The `i18n` object has helper functions for that too, and they're also reactive\!
-
-```jsx
-import { i18n } from "@manyducks.co/dolla/i18n";
-
-function ProductDetails({ product }) {
-  const $price = i18n.number(() => product().price, { style: "currency", currency: "USD" });
-  const $lastUpdated = i18n.dateTime(() => product().updatedAt, { dateStyle: "long" });
-
-  return (
-    <div>
-      <p>Price: {$price}</p>
-      <p>Last Updated: {$lastUpdated}</p>
-    </div>
-  );
-}
-```
-
----
-
-End.
-
-- [🗂️ Docs](./index.md)
-- [🏠 README](../README.md)
-- [🦆 That's a lot of ducks.](https://www.manyducks.co)

package/docs/index.md

@@ -1,10 +0,0 @@
-# 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

@@ -1,136 +0,0 @@
-# Dolla Internals: What the Heck is Markup?
-
-Aight, so you've been writing Views and they spit out JSX and everything just magically shows up on the page. But what's _actually_ happening under the hood? If you're the kind of dev who likes to pop the hood and see how the engine works, this doc is for you.
-
-We're gonna talk about **Markup**. This is some deep-level Dolla lore, so buckle up.
-
-## So, what even IS Markup?
-
-When you write this in your View:
-
-```jsx
-<div>Hello, {$name}!</div>
-```
-
-That JSX doesn't just become HTML. Before it ever touches the DOM, it gets turned into a tree of JavaScript objects. We call these objects **Markup Nodes**. Think of it like Dolla's own private version of the DOM, but way smarter and built with reactivity in mind from the ground up.
-
-This tree of Markup Nodes is what Dolla actually uses to create, update, and destroy the real HTML elements on your page.
-
-### The `MarkupNode` Abstract Class
-
-At the very bottom of it all is the `MarkupNode` abstract class. Every single thing in the Markup tree, from a simple piece of text to a whole component, is a class that extends `MarkupNode`. It's the blueprint that guarantees every node knows how to do a few basic things:
-
-- `mount(parent, after?)`: Put me on the page.
-- `unmount(skipDOM?)`: Take me off the page.
-- `move(parent, after?)`: Move me without a full unmount/remount.
-- `getRoot()`: Give me my main HTML element.
-- `isMounted()`: Am I currently on the page?
-
-Understanding this is key: your entire app is just a tree of these objects calling these methods on each other.
-
-## Why should I care?
-
-Honestly? 99% of the time, you don't need to. This is all internal stuff. But understanding it can help you debug weird issues and really get why Dolla is so fast. It's also just kinda cool to know how your tools work, fr.
-
-## The Different Flavors of Markup Nodes
-
-There are a few different types of nodes in the Markup tree, each with a specific job.
-
-### `ElementNode`
-
-This is the main character. Every time you write a `<div>`, `<p>`, or `<button>`, Dolla creates an `ElementNode`. This is the object that holds onto the real HTML element and is responsible for all the cool stuff you can do with props.
-
-### `DOMNode`
-
-This is the simplest one. It's a lightweight wrapper for any plain ol' DOM node. This includes simple text\! When you write `<div>Hello</div>`, the word "Hello" becomes a native browser `Text` node, which then gets wrapped in a Dolla `DOMNode`. It's the leaf at the very bottom of the tree.
-
-### `DynamicNode`
-
-This is the secret sauce for reactivity. When you put a signal directly in your JSX, like `<p>{$count}</p>`, Dolla wraps it in a `DynamicNode`. Its job is to listen to the signal and swap out its content whenever the signal's value changes.
-
-### `RepeatNode`
-
-This is the powerhouse behind the `<For>` component. It's way smarter than a simple loop and uses a key-based diffing algorithm to make the absolute minimum number of changes to the DOM when the list updates.
-
-### `ViewNode`
-
-When you use one of your own components, like `<MyComponent />`, Dolla creates a `ViewNode`. Its job is to call your component's function, set up a new `Context` for it, and then manage the tree of Markup Nodes that your component returns.
-
-### `PortalNode`
-
-This is the node for the `<Portal>` component. It's special because it mounts its children to a completely different part of the DOM, and it has to handle its own cleanup.
-
-Here's the tea: normally, when a parent element gets yeeted off the page, all its kids go with it automatically. Dolla uses this for a speed boost—it tells the child nodes "don't worry about removing yourselves, I got this." But a Portal's content is living its best life somewhere else in the DOM, like at the end of `<body>`. So when the Portal's _logical_ parent gets removed, its content is left stranded. That's why the `PortalNode` has to do its own cleanup and manually remove its content from wherever it was teleported to. It can't rely on the parent's cleanup crew.
-
-## The Context Tree: The Brains of the Operation
-
-So how does all this stuff actually connect? The secret is the **Context Tree**.
-
-Think of it like this: when Dolla builds your Markup tree, it builds a second, invisible tree right alongside it. Not every node gets its own context, though. Only **`ViewNode`s** and **`ElementNode`s** create a new child context. The other node types, like `DynamicNode` or `RepeatNode`, just hitch a ride on their parent's context.
-
-This parallel tree is the entire brain of a Dolla component.
-
-### How `useStore` and `useContext` Work
-
-Each context object has a link to its parent. This is the whole magic trick.
-
-When you call `useStore(MyStore)`, Dolla is like, "Aight, lemme check the _current_ context for this store... nope. Lemme ask my parent... nope. Lemme ask _their_ parent..." It just keeps climbing up this context tree until it finds the store or hits the top.
-
-And how do hooks like `useContext` know which context they're in? When a `ViewNode` is about to run your component function, it basically shouts "YO, I'M THE ACTIVE CONTEXT NOW\!" into a global, private variable. Then your function runs, all your hooks grab that global context, and when your function is done, the `ViewNode` sets it back to what it was before. It's a clever little trick that makes hooks feel like magic.
-
-### The Lifecycle Connection
-
-The `Context` object is also a tiny state machine that moves through lifecycle states:
-
-`Unmounted` -\> `WillMount` -\> `DidMount` -\> `WillUnmount` -\> `DidUnmount` -\> `Disposed`
-
-When a `MarkupNode`'s `mount()` method is called, it's actually just telling its own `Context` object to emit the `WillMount` event, then it does its DOM stuff, then it tells the context to emit `DidMount`. The `useMount` hook you use in your component is really just a simple wrapper for `context.onLifecycleTransition("didMount", callback)`.
-
-**What's cool for a power user:**
-
-- **Bound Lifecycles:** When you create a Store or a Mixin, its context is "bound" to the parent View's context. This means when the View's context gets the `DidMount` event, the Store's context automatically gets it too. That's how hooks inside Stores and Mixins just work without any extra setup.
-- **Smart Effects:** The `useEffect` hook has to be called in the main body of your component function. It tells the context to queue up the effect to run at `WillMount`. For advanced use cases, you can use the lower-level `context.effect()` method from inside a lifecycle hook (like `useMount`), and the context is smart enough to run it immediately since the component is already mounted.
-
-## Putting It All Together
-
-So, when you write a View like this:
-
-```jsx
-function MyView() {
-  const [$users, setUsers] = useSignal([{ id: 1, name: "Alice" }]);
-
-  return (
-    <div class="container">
-      <h1>Users</h1>
-      <For each={$users} key={(u) => u.id}>
-        {($user) => <p>{() => $user().name}</p>}
-      </For>
-    </div>
-  );
-}
-```
-
-Here's a simplified version of the Markup tree Dolla builds internally. Remember, each of these nodes has its own `Context` object, linked to its parent's.
-
-```
-ElementNode(div)
-  - ElementNode(h1)
-    - DOMNode(Text("Users"))
-  - RepeatNode(for the $users signal)
-    - ViewNode(for the <p> component instance)
-      - ElementNode(p)
-        - DynamicNode(for the user's name)
-          - DOMNode(Text("Alice"))
-```
-
-When you add a new user to the `$users` signal, only the `RepeatNode` gets notified. It then creates a new `ViewNode` for the new user, which in turn creates its own little tree (and its own child context), and mounts it to the DOM. Nothing else on the page has to re-render.
-
-That's the power of the Markup tree. It's a fully reactive, fine-grained representation of your UI that allows for incredibly efficient updates. And now you know what's really going on under the hood.
-
----
-
-End.
-
-- [🗂️ Docs](./index.md)
-- [🏠 README](../README.md)
-- [🦆 That's a lot of ducks.](https://www.manyducks.co)