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

package/docs/mixins.md

@@ -0,0 +1,176 @@
+# A Deep Dive into Dolla Mixins
+
+Aight, let's talk about one of Dolla's most lowkey powerful features: **Mixins**. They're a sick way to add reusable superpowers directly to your HTML elements. Once you get the hang of them, you'll find all sorts of cool uses for 'em.
+
+## So, what even IS a Mixin?
+
+A Mixin is a function that you can slap onto any DOM element to give it extra behavior. It doesn't render any new HTML itself; instead, it attaches to an existing element (that a View spit out) and enhances it.
+
+Think of it like this:
+
+- A **View** is like the car itself. It has a structure, seats, a steering wheel. It's the thing you see.
+- A **Mixin** is like adding a turbocharger, a custom sound system, or underglow lighting to that car. It doesn't change the car's structure, but it gives it new abilities and makes it do cool stuff.
+
+## Why use a Mixin instead of just wrapping everything in a View?
+
+That's the million-dollar question, fr. You _could_ make a `<HoverHighlightable>` View that wraps a `<div>`, but that gets messy fast.
+
+Here's when you should reach for a Mixin:
+
+1.  **The logic is all about ONE element.** If your code is just focused on making a single `<div>` or `<button>` do something cool, a Mixin is perfect. No need to create a whole new component just for that.
+2.  **You're not adding new HTML.** Mixins are for adding behavior, not for rendering more stuff. If you need to spit out more `divs` and `spans`, that's a job for a View.
+3.  **You wanna share the same behavior everywhere.** Got a cool "fade in on scroll" effect? Make it a mixin, and you can slap it on images, paragraphs, whole sections—anything\! It's way cleaner than copy-pasting logic or making a dozen different wrapper components.
+
+Basically, Mixins are for **behavior**, and Views are for **structure**.
+
+## How to Make a Mixin
+
+Making a mixin is a two-step function dance. It sounds weird, but it's super useful.
+
+1.  The **outer function** is for configuration. It's where you can pass in options to customize the mixin's behavior. This function's job is to return...
+2.  The **inner function**. This is the real meat of the mixin. It gets the actual DOM element as an argument, and inside this function, you can use all the Dolla hooks you know and love (`useMount`, `useEffect`, `useSignal`, etc.).
+
+<!-- end list -->
+
+```jsx
+// The outer "configuration" function
+function myMixin(options) {
+  // The inner "attachment" function
+  return (element) => {
+    // `element` is the real HTML element!
+    // You can use hooks in here.
+    useMount(() => {
+      console.log(`${options.greeting} from my mixin! I'm attached to:`, element);
+    });
+  };
+}
+```
+
+### Applying a Mixin
+
+You apply a mixin to an element in your View using the `mixin` prop. Just call the outer function to get the inner function, and Dolla handles the rest.
+
+```jsx
+function MyView() {
+  return <div mixin={myMixin({ greeting: "What up" })}>I have a mixin!</div>;
+}
+```
+
+## Examples to Make it Click
+
+### Basic Example: `autofocus`
+
+Let's start with a super simple one. Sometimes you just want an input to be focused the second it appears on the page.
+
+```jsx
+import { useMount } from "@manyducks.co/dolla";
+
+function autofocus() {
+  return (element) => {
+    useMount(() => {
+      // Just tell the element to focus itself when it mounts. Done.
+      element.focus();
+    });
+  };
+}
+
+// How to use it:
+function LoginForm() {
+  return <input type="text" placeholder="Username" mixin={autofocus()} />;
+}
+```
+
+### Real-World Example: `clickOutside`
+
+This is a classic\! You need to close a dropdown or a modal when the user clicks anywhere else on the page. This is a total pain to do with Views, but it's a breeze with a mixin.
+
+```jsx
+import { useMount, useSignal, Show } from "@manyducks.co/dolla";
+
+function clickOutside(onOutsideClick) {
+  return (element) => {
+    useMount(() => {
+      const handleClick = (event) => {
+        // If the click is outside the element...
+        if (!element.contains(event.target)) {
+          // ...call the function we were given!
+          onOutsideClick();
+        }
+      };
+
+      document.addEventListener("mousedown", handleClick);
+      return () => document.removeEventListener("mousedown", handleClick);
+    });
+  };
+}
+
+// How to use it for a dropdown:
+function DropdownMenu() {
+  const [$isOpen, setOpen] = useSignal(false);
+
+  return (
+    <div class="dropdown-container">
+      <button onClick={() => setOpen(true)}>Open Menu</button>
+      <Show when={$isOpen}>
+        <div class="menu" mixin={clickOutside(() => setOpen(false))}>
+          <p>Item 1</p>
+          <p>Item 2</p>
+        </div>
+      </Show>
+    </div>
+  );
+}
+```
+
+See how clean that is? The dropdown's logic for opening is in the View, but the reusable "closing" logic is tucked away in a mixin.
+
+### Advanced Example: `lazyLoadImage`
+
+Let's make a mixin that uses the browser's `IntersectionObserver` API to only load an image when it scrolls into view. This is a huge performance win and a perfect job for a mixin.
+
+```jsx
+import { useMount } from "@manyducks.co/dolla";
+
+function lazyLoadImage() {
+  return (imgElement) => {
+    useMount(() => {
+      const observer = new IntersectionObserver((entries) => {
+        entries.forEach((entry) => {
+          // When the image is visible on screen...
+          if (entry.isIntersecting) {
+            // ...swap the real image src into place!
+            imgElement.src = imgElement.dataset.src;
+            // And we're done, so stop watching.
+            observer.unobserve(imgElement);
+          }
+        });
+      });
+
+      observer.observe(imgElement);
+
+      return () => observer.disconnect();
+    });
+  };
+}
+
+// How to use it:
+function ImageGallery() {
+  return (
+    <div class="gallery">
+      {/* The initial src can be a tiny placeholder */}
+      <img mixin={lazyLoadImage()} src="/placeholder.gif" data-src="/real-image-1.jpg" alt="A cool pic" />
+      <img mixin={lazyLoadImage()} src="/placeholder.gif" data-src="/real-image-2.jpg" alt="Another cool pic" />
+    </div>
+  );
+}
+```
+
+This is peak mixin usage. The logic is 100% about that `<img>` element and its behavior. Making a `<LazyImage>` View for this would be total overkill.
+
+---
+
+End.
+
+- [🗂️ Docs](./index.md)
+- [🏠 README](../README.md)
+- [🦆 That's a lot of ducks.](https://www.manyducks.co)

package/docs/ref.md

@@ -0,0 +1,77 @@
+# Refs: For When You Gotta Get Your Hands Dirty
+
+Aight, so what's a **ref**? It's basically a little box for holding onto a value. It's a function, so `myRef()` gets you the value, and `myRef(newValue)` sets a new one. If you try to get a value from an empty ref, it'll throw a fit, so heads up.
+
+Think of it like a signal's uncool cousin—it holds stuff, but it's **not reactive**. It won't trigger updates. It's for when you need to break the rules a little.
+
+## Use Case \#1: Grabbing DOM elements
+
+The main character energy of refs is grabbing actual HTML elements. Just yeet a `ref={myRef}` prop onto any element, and bam, the real DOM node lands in `myRef.current`. Now you can mess with it directly using regular JS, no cap. It's your secret backdoor to the DOM.
+
+```tsx
+import { useRef } from "@manyducks.co/dolla";
+
+function ExampleView() {
+  const element = useRef<HTMLElement>();
+
+  useMount(() => {
+    // We're just changing the text directly on the element. Wild.
+    element.current.innerText = "GOODBYE WORLD";
+  });
+
+  return <div ref={element}>HELLO WORLD</div>;
+}
+```
+
+## Use Case \#2: Parent Controlling a Child
+
+This is some next-level strats, fr. You can use a ref to let a parent component control a child. The child makes a little API object—like a remote control—and sends it up to the parent via a ref. Then the parent can just be like `controls.current.increment()` and make the child do stuff. It's a total power move for when you need to break the rules.
+
+```tsx
+import { useRef, useSignal } from "@manyducks.co/dolla";
+
+// The child component that's gonna get controlled
+interface CounterViewControls {
+  increment(): void;
+  decrement(): void;
+  reset(): void;
+}
+
+function CounterView({ controls }: { controls: Ref<CounterViewControls> }) {
+  const [$count, setCount] = useSignal(0);
+
+  // We're making our "remote control" and giving it to the parent's ref
+  controls.current = {
+    increment: () => setCount((c) => c + 1),
+    decrement: () => setCount((c) => c - 1),
+    reset: () => setCount(0),
+  };
+
+  return <span>Count: {$count}</span>;
+}
+
+// The parent component doing the controlling
+function ParentView() {
+  const controls = useRef<CounterViewControls>();
+
+  return (
+    <section>
+      <h1>Counter</h1>
+      <CounterView controls={controls} />
+
+      {/* Now we can use the remote control from the parent! */}
+      <button onClick={() => controls.current.increment()}>+1</button>
+      <button onClick={() => controls.current.decrement()}>-1</button>
+      <button onClick={() => controls.current.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,281 @@
+# The 411 on Dolla Routing
+
+Aight, let's talk routing. If you're building a single-page app (aka an SPA), you're gonna need a router. It's the thing that lets you have different "pages" like `/home`, `/about`, and `/users/123` without the browser doing a full page refresh every time. It makes your app feel fast and snappy, and it gives you shareable links and a working back button, which is a must. Lowkey, an app without a router is a major L.
+
+Dolla's router is built right in, and it's designed to be super intuitive but also powerful enough to handle whatever you throw at it.
+
+## Setting Up Your Router
+
+First things first, you gotta create your router. You do this with the `createRouter` function. You give it a list of all the routes in your app. Then, instead of giving `createApp` your main component, you just give it the router you just made. Dolla handles the rest.
+
+```jsx
+import { createApp } from "@manyducks.co/dolla";
+import { createRouter } from "@manyducks.co/dolla/router";
+import { HomePage, AboutPage, NotFoundPage } from "./views.js";
+
+const router = createRouter({
+  // Use hash routing if you don't have a fancy server setup
+  // hash: true,
+  routes: [
+    { path: "/", view: HomePage },
+    { path: "/about", view: AboutPage },
+    { path: "*", view: NotFoundPage },
+  ],
+});
+
+const app = createApp(router);
+app.mount(document.body);
+```
+
+That's the basic setup. Now, when you go to `/about`, Dolla will automatically show the `AboutPage` component. Easy peasy.
+
+## Defining Routes
+
+The `routes` array is the heart of your router. Each object in the array defines one route.
+
+### Route Patterns
+
+The `path` property tells the router what the URL should look like. It can be simple or have dynamic parts.
+
+- **Static**: `/dashboard/settings` - a plain old path.
+- **Numeric Param**: `/users/{#id}` - The `{#id}` part will only match numbers, and the `id` param will be a number.
+- **Generic Param**: `/users/{name}` - The `{name}` part will match any string.
+- **Wildcard**: `/files/*` - This is a catch-all. It'll match `/files/` and anything that comes after it. It can only be at the end of a path.
+
+Dolla uses **specificity-based matching**. That means the most specific route always wins, no matter what order you define them in. So `/users/new` will always match before `/users/{name}`. No more weird ordering bugs\! No cap.
+
+### Redirects
+
+Instead of a `view`, you can give a route a `redirect` property. This is perfect for old URLs or for sending users from `/` to `/dashboard`.
+
+```jsx
+const router = createRouter({
+  routes: [
+    { path: "/", redirect: "/dashboard" },
+    { path: "/dashboard", view: DashboardPage },
+  ],
+});
+```
+
+### `beforeMatch`: The Gatekeeper
+
+This is a super powerful one. `beforeMatch` is a function that runs _after_ a route matches but _before_ the view shows up. It's the perfect spot to do stuff like:
+
+- Checking if a user is logged in.
+- Fetching data for the page before it renders.
+- Redirecting somewhere else based on some logic.
+
+The `beforeMatch` function gets a context object (`ctx`) where you can call `ctx.redirect()` to send the user away, or `ctx.setState()` to pass data down to the view.
+
+```jsx
+import { sessionStore } from "./stores"; // Pretend we have a global store
+
+const router = createRouter({
+  routes: [
+    { path: "/login", view: LoginPage },
+    {
+      path: "/dashboard",
+      view: DashboardPage,
+      beforeMatch: (ctx) => {
+        // Gatekeep this route!
+        if (!sessionStore.isLoggedIn()) {
+          // If they're not logged in, yeet 'em to the login page.
+          ctx.redirect("/login");
+        }
+      },
+    },
+  ],
+});
+```
+
+### `data`: Stashing Info on a Route
+
+You can also just stick a `data` object on any route. It's a chill way to attach extra info, like a page title or breadcrumbs. This data will show up in the `$match` signal from the router.
+
+```jsx
+const router = createRouter({
+  routes: [
+    {
+      path: "/",
+      view: HomePage,
+      data: { title: "Welcome Home" },
+    },
+    {
+      path: "/about",
+      view: AboutPage,
+      data: { title: "About Us" },
+    },
+  ],
+});
+
+// In some other component...
+function DocumentTitle() {
+  const router = useRouter();
+  useEffect(() => {
+    // Grab the title from the matched route's data!
+    document.title = router.$match().data.title || "My App";
+  });
+  return null; // This component doesn't render anything
+}
+```
+
+## Layout Routes: This is where it gets spicy
+
+Okay, this is where it gets really cool. Most apps have a main layout—a navbar, a sidebar, a footer—and the actual page content changes inside that layout. Dolla makes this super easy.
+
+To create a layout, you just make a route that has a `view` _and_ a nested `routes` array. That view becomes the layout for all the nested routes.
+
+The best part? The child component that matches the nested route gets passed down to your layout component as the `children` prop. You can place it wherever you want\!
+
+### Example
+
+Let's make a main app layout with a navbar and a footer.
+
+**1. Create the Layout View:**
+
+Notice how it just renders `props.children` wherever the page content should go.
+
+```jsx
+// views/MainLayout.jsx
+function MainLayout(props) {
+  return (
+    <div class="app-container">
+      <nav>
+        <a href="/">Home</a> | <a href="/about">About</a>
+      </nav>
+
+      <main>
+        {/* The child route will be rendered right here! */}
+        {props.children}
+      </main>
+
+      <footer>
+        <p>&copy; 2024 My Awesome App</p>
+      </footer>
+    </div>
+  );
+}
+```
+
+**2. Set up the Router to use the Layout:**
+
+```jsx
+// router.js
+import { createRouter } from "@manyducks.co/dolla/router";
+import { MainLayout } from "./views/MainLayout.jsx";
+import { HomePage, AboutPage } from "./views.js";
+
+const router = createRouter({
+  routes: [
+    {
+      // This is our layout route
+      path: "/",
+      view: MainLayout,
+      // These routes will be rendered inside MainLayout
+      routes: [
+        { path: "/", view: HomePage },
+        { path: "/about", view: AboutPage },
+      ],
+    },
+  ],
+});
+```
+
+Now, when you go to `/` or `/about`, you'll see the `MainLayout` with either `HomePage` or `AboutPage` rendered inside that `<main>` tag. It's clean, it's simple, and it just works. It's giving... effortless.
+
+## Hopping Around Your App
+
+Sometimes you need to change the page from your code, like after a form submission. For that, you use the `useRouter` hook.
+
+### `useRouter()`
+
+This hook gives you the router instance, which has a bunch of useful methods and signals.
+
+- `router.go(path, options?)`: The main way to navigate. You can also pass an `options` object.
+  - `replace: true`: Replaces the current page in history instead of adding a new one. The back button will skip it.
+  - `preserveQuery: true`: Keeps the current query params and merges them with any new ones.
+- `router.back()`: Goes back one step in the browser history.
+- `router.forward()`: Goes forward one step.
+- `router.updateQuery(params)`: Just changes the query params in the URL without a full navigation. Super useful for filters and sorting.
+
+<!-- end list -->
+
+```jsx
+import { useRouter } from "@manyducks.co/dolla/router";
+
+function SomeComponent() {
+  const router = useRouter();
+
+  const goToUser = () => {
+    // This will go to /users/42 but won't add a new history entry
+    router.go("/users/42", { replace: true });
+  };
+
+  const setSort = () => {
+    // This will just change the URL to ?sort=name without reloading
+    router.updateQuery({ sort: "name" });
+  };
+
+  return (
+    <>
+      <button onClick={goToUser}>Go to User 42</button>
+      <button onClick={setSort}>Sort by Name</button>
+    </>
+  );
+}
+```
+
+## Spying on the Route
+
+Your components often need to know what the current URL is, especially to get params like a user's ID. The `useRouter` hook gives you reactive signals for this too\!
+
+- `$match`: A signal with the whole match object, including path, params, query, and any `data` you added to the route.
+- `$path`: A signal with the current path (e.g., `/users/123`).
+- `$params`: A signal with an object of the dynamic parts of the URL (e.g., `{ id: 123 }`).
+- `$query`: A signal with an object of the query params (e.g., `?sort=asc` becomes `{ sort: 'asc' }`).
+- `$pattern`: A signal with the full route pattern that was matched (e.g., `/users/{#id}`). If you're in a nested route, this will be the full joined path, like `/users/{#id}/posts`.
+
+<!-- end list -->
+
+```jsx
+import { useRouter } from "@manyducks.co/dolla/router";
+import { useEffect, useSignal } from "@manyducks.co/dolla";
+
+function UserProfilePage() {
+  const router = useRouter();
+  const { $params } = router;
+  const [$user, setUser] = useSignal(null);
+
+  // This effect will automatically re-run if the user ID in the URL changes!
+  useEffect(() => {
+    const userId = $params().id;
+    // You can't pass an async function directly to useEffect,
+    // so we define one inside and call it.
+    const fetchUser = async () => {
+      const data = await fetch(`/api/users/${userId}`).then((res) => res.json());
+      setUser(data);
+    };
+
+    if (userId) {
+      fetchUser();
+    }
+  });
+
+  return (
+    <div>
+      <h1>User Profile</h1>
+      <Show when={$user}>
+        <p>Name: {() => $user().name}</p>
+      </Show>
+    </div>
+  );
+}
+```
+
+---
+
+End.
+
+- [🗂️ Docs](./index.md)
+- [🏠 README](../README.md)
+- [🦆 That's a lot of ducks.](https://www.manyducks.co)

package/docs/setup.md

@@ -0,0 +1,137 @@
+# Dolla Setup Guide: Let's Get Cookin'
+
+Aight, so you're ready to build something sick with Dolla. Bet. This guide will get you from zero to a running "Hello World" app in just a few minutes.
+
+We're gonna use [Vite](https://vitejs.dev/) as our build tool. It's fast af, super easy to set up, and it works perfectly with Dolla's JSX.
+
+## Step 1: Make a New Vite Project
+
+First things first, you need a place for your project to live. Pop open your terminal and run this command:
+
+```bash
+npm create vite@latest
+```
+
+Vite will ask you a few questions. Here's what you should pick:
+
+1.  **Project name:** Go wild. Let's use `my-dolla-app` for this guide.
+2.  **Select a framework:** Choose **Vanilla**. (Yeah, I know, but trust the process. We're adding Dolla ourselves).
+3.  **Select a variant:** Choose **TypeScript** (or JavaScript if that's more your vibe).
+
+Once it's done, hop into your new project directory:
+
+```bash
+cd my-dolla-app
+```
+
+## Step 2: Install Dolla
+
+Now that you're in your project, you just need to install Dolla from npm.
+
+```bash
+npm install @manyducks.co/dolla
+```
+
+This will add Dolla to your `package.json` and `node_modules`.
+
+## Step 3: Set Up JSX
+
+You're gonna want to write JSX, right? It's way better than trying to write UI with just functions. To make it work, you just need to tell TypeScript (or JavaScript) how to handle it.
+
+Open up your `tsconfig.json` file (or `jsconfig.json` if you're using plain JS) and add these two lines to the `compilerOptions`:
+
+```json
+{
+  "compilerOptions": {
+    // ... a bunch of other options will be here ...
+
+    "jsx": "react-jsx",
+    "jsxImportSource": "@manyducks.co/dolla"
+  }
+}
+```
+
+- `"jsx": "react-jsx"` tells the compiler to use the modern JSX transform.
+- `"jsxImportSource": "@manyducks.co/dolla"` tells it to use Dolla's functions when it sees JSX, not React's.
+
+Vite will see this and automatically know what to do. No extra plugins needed. It's a whole vibe.
+
+## Step 4: Write Your First Component
+
+Okay, time for the fun part. Let's clear out the default Vite stuff and write a real Dolla component.
+
+Open up the main file at `src/main.ts` (or `main.js`) and replace everything in it with this:
+
+```jsx
+import { createApp, useSignal } from "@manyducks.co/dolla";
+
+// This is our main View component!
+function App() {
+  const [$message, setMessage] = useSignal("Hello, Dolla!");
+
+  return (
+    <div>
+      <h1>{$message}</h1>
+      <p>Welcome to your new app.</p>
+    </div>
+  );
+}
+
+// This is how we tell Dolla to start up.
+// It builds your App component and sticks it into the #app element.
+createApp(App).mount("#app");
+```
+
+## Step 5: Peep Your HTML
+
+Vite gives you a basic `index.html` in the root of your project. It'll look something like this:
+
+```html
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Vite + TS</title>
+  </head>
+  <body>
+    <div id="app">
+      <!-- Your app mounts in here! -->
+    </div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>
+```
+
+The important line is `<script type="module" src="/src/main.ts"></script>`. That's what loads your app.
+
+You can see we mounted our main view in `#app`, so your message will show up there.
+
+## Step 6: Run It\!
+
+That's it, you're ready to go. Back in your terminal, run the dev server:
+
+```bash
+npm run dev
+```
+
+Vite will spit out a local URL (usually `http://localhost:5173`). Open that up in your browser, and you should see your "Hello, Dolla\!" message.
+
+You're officially a Dolla developer. Slay.
+
+## What's Next?
+
+Now that you're set up, you can start building for real. Here's where you should probably go next:
+
+- [**Views**](./views.md): A deep dive into the main character of your app.
+- [**Signals**](./signals.md) Learn all about the magic that makes your app reactive.
+- [**Stores**](./stores.md): Figure out how to manage state without losing your mind.
+
+---
+
+End.
+
+- [🗂️ Docs](./index.md)
+- [🏠 README](../README.md)
+- [🦆 That's a lot of ducks.](https://www.manyducks.co)