@manyducks.co/dolla 2.0.0 → 3.1.0

package/docs/components.md

@@ -1,238 +0,0 @@
-# The Lowdown on Dolla Components
-
-Aight, so in Dolla, your whole app is just a bunch of **components**. They're the lego bricks for your UI, your state, all that good stuff. Getting how they work is basically the key to winning at this whole framework thing.
-
-Dolla's got three main types of components, and each one has its own lane:
-
-1.  **Views**: For making your UI look pretty.
-2.  **Stores**: For handling and sharing state so you don't lose your mind.
-3.  **Mixins**: For giving your plain old HTML elements some extra rizz.
-
-They're all connected by this thing called **context**, which is how they talk to each other and share stuff like stores. Let's get into it.
-
----
-
-## Views: The Stuff You See
-
-**Views** are the components you're gonna be making all the time. They're literally just JavaScript functions that spit out some JSX. If you've ever touched React, you'll feel right at home, fr.
-
-### Making a View
-
-It's just a function that gets a `props` object. That's it.
-
-```jsx
-import { useSignal } from "@manyducks.co/dolla";
-
-// A super simple View
-function Greeting(props) {
-  return <h1>Yo, {props.name}!</h1>;
-}
-
-// A View with its own state and stuff
-function Counter() {
-  const [$count, setCount] = useSignal(0);
-  const increment = () => setCount((c) => c + 1);
-
-  return (
-    <div>
-      <p>Count: {$count}</p>
-      <button onClick={increment}>+1</button>
-    </div>
-  );
-}
-```
-
-### Passing Props
-
-You send data into your Views with `props`. They look just like HTML attributes. This is how you make your components useful instead of just being static, boring things.
-
-```jsx
-function App() {
-  return (
-    <div>
-      {/* Pass a normal string */}
-      <Greeting name="Alice" />
-
-      {/* To derive a signal and keep it reactive, wrap it in a function! */}
-      <Greeting name={() => $currentUser().firstName} />
-    </div>
-  );
-}
-```
-
----
-
-## Stores: Stop Prop Drilling Hell
-
-**Stores** are Dolla's answer to state management. Got some state that like, ten different components need? Instead of passing props down a million levels (aka "prop drilling," the worst), you just use a Store.
-
-### Making a Store
-
-A Store is a function that makes and returns an object full of signals and functions. It's like a clean little API for a piece of your app's state.
-
-```jsx
-import { useSignal, useMemo } from "@manyducks.co/dolla";
-
-function UserStore(options) {
-  // `options` come from where you provide the store
-  const [$user, setUser] = useSignal({ id: options.initialUserId, name: "Guest" });
-  const $isGuest = useMemo(() => $user().id === null);
-
-  const login = (userData) => {
-    // A real login would probably fetch this data
-    setUser(userData);
-  };
-
-  const logout = () => {
-    setUser({ id: null, name: "Guest" });
-  };
-
-  // Send out the signals and functions for other components to use
-  return { $user, $isGuest, login, logout };
-}
-```
-
-### Using a Store
-
-First, you "provide" the store in a parent component with `useStoreProvider`. Then, any kid component can grab it with `useStore`. Easy.
-
-```jsx
-import { useStoreProvider, useStore } from "@manyducks.co/dolla";
-
-// 1. Provide the store up high
-function App() {
-  // Now the UserStore is available to App and everything inside it
-  useStoreProvider(UserStore, { initialUserId: null });
-
-  return <Navbar />;
-}
-
-// 2. Use it down low
-function Navbar() {
-  // Just ask for the UserStore instance
-  const userStore = useStore(UserStore);
-
-  return (
-    <nav>
-      <Show when={() => !userStore.$isGuest()}>
-        <p>Welcome, {() => userStore.$user().name}!</p>
-        <button onClick={userStore.logout}>Log Out</button>
-      </Show>
-      <Show when={() => userStore.$isGuest()}>
-        <button onClick={() => userStore.login({ id: 1, name: "Alice" })}>Log In</button>
-      </Show>
-    </nav>
-  );
-}
-```
-
----
-
-## Mixins: Giving Your HTML Superpowers
-
-**Mixins** are a sick feature for attaching reusable logic straight to your HTML elements. A mixin is a function that returns _another_ function, and that inner function gets the element it's attached to. Inside, you can use hooks to do whatever you want.
-
-### Making a Mixin
-
-Here's a mixin that makes an element's background change color when you hover over it.
-
-```jsx
-import { useMount } from "@manyducks.co/dolla";
-
-function hoverHighlight(color = "yellow") {
-  // The outer function lets you set it up
-  return (element) => {
-    // The inner function gets the element and can use hooks
-    const originalColor = element.style.backgroundColor;
-
-    const handleMouseEnter = () => {
-      element.style.backgroundColor = color;
-    };
-
-    const handleMouseLeave = () => {
-      element.style.backgroundColor = originalColor;
-    };
-
-    useMount(() => {
-      element.addEventListener("mouseenter", handleMouseEnter);
-      element.addEventListener("mouseleave", handleMouseLeave);
-
-      // useMount lets you return a cleanup function. Dope.
-      return () => {
-        element.removeEventListener("mouseenter", handleMouseEnter);
-        element.removeEventListener("mouseleave", handleMouseLeave);
-      };
-    });
-  };
-}
-```
-
-### Using a Mixin
-
-You slap mixins onto elements with the `mixin` prop. You can use one, or go wild and use a whole array of 'em.
-
-```jsx
-function InteractiveList() {
-  return (
-    <ul>
-      {/* Just call the outer function to apply it */}
-      <li mixin={hoverHighlight()}>Hover me!</li>
-      <li mixin={hoverHighlight("lightblue")}>Or me!</li>
-      <li mixin={[hoverHighlight(), otherMixin()]}>I got two, lol</li>
-    </ul>
-  );
-}
-```
-
----
-
-## The Component Lifecycle (aka Birth and Death)
-
-Dolla components have a simple life: they get **mounted** (put on the page) and **unmounted** (yeeted off the page). You can run code at these times with lifecycle hooks.
-
-### `useMount(callback)`
-
-This hook runs your code right after your component shows up. It's the spot for setting up timers, listeners, whatever.
-
-If you return a function from `useMount`, Dolla will automatically run it for you right after the component is unmounted. It's like a built-in maid service for your code.
-
-### `useUnmount(callback)`
-
-This hook runs your code right before the component is unmounted. Good for quick, one-off cleanup tasks.
-
-```jsx
-import { useMount, useUnmount, useSignal } from "@manyducks.co/dolla";
-
-function RealtimeClock() {
-  const [$time, setTime] = useSignal(new Date().toLocaleTimeString());
-
-  // useMount is perfect for setup AND cleanup
-  useMount(() => {
-    console.log("Clock's here, starting the timer.");
-    const timerId = setInterval(() => {
-      setTime(new Date().toLocaleTimeString());
-    }, 1000);
-
-    // This cleanup function runs when the component is gone
-    return () => {
-      console.log("Clock's leaving, killing the timer.");
-      clearInterval(timerId);
-    };
-  });
-
-  // useUnmount for other random cleanup
-  useUnmount(() => {
-    console.log("The clock is officially off the page.");
-  });
-
-  return <p>The time is: {$time}</p>;
-}
-```
-
----
-
-End.
-
-- [🗂️ Docs](./index.md)
-- [🏠 README](../README.md)
-- [🦆 That's a lot of ducks.](https://www.manyducks.co)

package/docs/hooks.md

@@ -1,356 +0,0 @@
-# Dolla Hooks: The Cheat Sheet
-
-Aight, so here's the deal with all the hooks in Dolla. Hooks are basically functions that let you tap into Dolla's brain—its reactive system and all that lifecycle stuff—from any of your components.
-
-## Lifecycle Hooks
-
-These hooks let you run code when your component is born, when it dies, and all the moments in between.
-
-### `useMount(callback)`
-
-Runs your code right after the component shows up on the page. If your function returns _another_ function, Dolla will automatically run that right after the component gets yeeted off the page. Perfect for cleanup\!
-
-**Signature:**
-
-```ts
-function useMount(callback: () => void | (() => void)): void;
-```
-
-**Example:**
-
-```tsx
-import { useMount, useSignal } from "@manyducks.co/dolla";
-
-function IntervalTimer() {
-  const [$seconds, setSeconds] = useSignal(0);
-
-  useMount(() => {
-    // Start a timer when the component shows up
-    const intervalId = setInterval(() => {
-      setSeconds((s) => s + 1);
-    }, 1000);
-
-    // Return a function to clean up the mess. This runs on unmount.
-    return () => {
-      console.log("k, bye interval");
-      clearInterval(intervalId);
-    };
-  });
-
-  return <p>Seconds on page: {$seconds}</p>;
-}
-```
-
-### `useUnmount(callback)`
-
-Runs your code right after the component is removed. Great for any last-minute cleanup.
-
-**Signature:**
-
-```ts
-function useUnmount(callback: () => void): void;
-```
-
-**Example:**
-
-```tsx
-import { useUnmount } from "@manyducks.co/dolla";
-
-function AnalyticsTracker({ eventName }) {
-  useUnmount(() => {
-    // Tell your analytics that the user bounced
-    fireAnalyticsEvent(`user_left_${eventName}_view`);
-  });
-
-  return <div>...</div>;
-}
-```
-
-## State Hooks
-
-These are the main tools for making your components interactive and smart.
-
-### `useSignal(initialValue?)`
-
-The main way to make reactive state in Dolla. It gives you back a `[getter, setter]` pair.
-
-**Signature:**
-
-```ts
-function useSignal<T>(value?: T, options?: SignalOptions<T>): [Signal<T>, Setter<T>];
-```
-
-**Example:**
-
-```tsx
-import { useSignal } from "@manyducks.co/dolla";
-
-function TextInput() {
-  const [$text, setText] = useSignal("");
-  const handleInput = (e) => setText(e.target.value);
-
-  return (
-    <div>
-      <input type="text" value={$text} onInput={handleInput} />
-      <p>You typed: {$text}</p>
-    </div>
-  );
-}
-```
-
-### `useMemo(compute, deps?)`
-
-Makes a new signal that's calculated from other signals. It's smart and only re-calculates when one of the signals it depends on changes.
-
-**Signature:**
-
-```ts
-function useMemo<T>(compute: () => T, deps?: Signal<any>[]): Signal<T>;
-```
-
-**Example:**
-
-```tsx
-import { useSignal, useMemo } from "@manyducks.co/dolla";
-
-function ShoppingCart() {
-  const [$price, setPrice] = useSignal(100);
-  const [$quantity, setQuantity] = useSignal(2);
-
-  // This signal will always be the right total. No math for you.
-  const $total = useMemo(() => $price() * $quantity());
-
-  return (
-    <div>
-      <p>Price: {$price}</p>
-      <p>Quantity: {$quantity}</p>
-      <hr />
-      <p>Total: {$total}</p>
-    </div>
-  );
-}
-```
-
-### `useReducer(reducer, initialState)`
-
-For when your state gets complicated and you wanna feel like a pro. It's just like the one in React.
-
-**Signature:**
-
-```ts
-type Reducer<State, Action> = (state: State, action: Action) => State;
-type Dispatcher<Action> = (action: Action) => void;
-
-function useReducer<State, Action>(
-  reducer: Reducer<State, Action>,
-  initialState: State,
-): [Signal<State>, Dispatcher<Action>];
-```
-
-**Example:**
-
-```tsx
-import { useReducer } from "@manyducks.co/dolla";
-
-const counterReducer = (state, action) => {
-  switch (action.type) {
-    case "INCREMENT":
-      return { ...state, count: state.count + 1 };
-    case "DECREMENT":
-      return { ...state, count: state.count - 1 };
-    default:
-      return state;
-  }
-};
-
-function ReducerCounter() {
-  const [$state, dispatch] = useReducer(counterReducer, { count: 0 });
-
-  return (
-    <>
-      <p>Count: {() => $state().count}</p>
-      <button onClick={() => dispatch({ type: "INCREMENT" })}>+</button>
-      <button onClick={() => dispatch({ type: "DECREMENT" })}>-</button>
-    </>
-  );
-}
-```
-
-### `useRef(initialValue?)`
-
-Gives you a little box to hold onto something. Super useful for grabbing HTML elements. You can use `.current` or just call it like a function to get the value.
-
-**Signature:**
-
-```ts
-function useRef<T>(initialValue?: T): HybridRef<T>;
-```
-
-**Example:**
-
-```tsx
-import { useRef, useMount } from "@manyducks.co/dolla";
-
-function FocusOnMount() {
-  const inputEl = useRef();
-
-  useMount(() => {
-    // get the element from .current
-    if (inputEl.current) {
-      inputEl.current.focus();
-    }
-    // you can also just call it like a function, lol
-    console.log(inputEl());
-  });
-
-  return <input ref={inputEl} placeholder="i'm gonna be focused" />;
-}
-```
-
-## Effect Hooks
-
-These are for doing "side effects" - stuff that isn't just rendering, like fetching data or messing with the DOM directly.
-
-### `useEffect(callback, deps?)`
-
-The go-to hook for side effects. Your code runs after the component shows up, and then again whenever the signals it uses change. It's automatic, but you can give it a `deps` array if you wanna be extra and control it yourself.
-
-**Signature:**
-
-```ts
-function useEffect(fn: () => void, deps?: Signal<any>[]): void;
-```
-
-**Example:**
-
-```tsx
-import { useEffect, useSignal } from "@manyducks.co/dolla";
-import { http } from "@manyducks.co/dolla/http";
-
-function UserData({ $userId }) {
-  const [$user, setUser] = useSignal(null);
-
-  // This effect will re-run whenever the $userId prop changes.
-  useEffect(() => {
-    const userId = $userId();
-    http.get(`/api/users/${userId}`).then((res) => {
-      setUser(res.body);
-    });
-  });
-
-  return (
-    <Show when={$user}>
-      <p>User: {() => $user().name}</p>
-    </Show>
-  );
-}
-```
-
-## Context Hooks
-
-These are the hooks you use to mess with the context system. Think of it like a way to pass stuff down to your components without having to prop drill, which is a total vibe killer.
-
-### `useContext(name?)`
-
-This just grabs the `Context` object for whatever component you're in. The context has useful stuff like loggers and is how stores get passed around.
-
-**Signature:**
-
-```ts
-function useContext(name?: MaybeSignal<string>): Context;
-```
-
-**Parameters:**
-
-- `name` (optional): A string or signal you can pass in to give your component a custom name for logging. Makes debugging less of a headache.
-
-**Example:**
-
-```tsx
-import { useContext } from "@manyducks.co/dolla";
-
-function UserProfile() {
-  // Grab the context and give it a cooler name
-  const context = useContext("UserProfilePage");
-
-  useMount(() => {
-    // The log will now say "[UserProfilePage]". Noice.
-    context.log("Component just dropped.");
-  });
-
-  return <div>...</div>;
-}
-```
-
-### `useStore(Store)`
-
-This hook looks up the component tree and finds the closest `Store` that a parent component hooked you up with.
-
-**Signature:**
-
-```ts
-function useStore<T>(store: Store<any, T>): T;
-```
-
-**Parameters:**
-
-- `store`: Just tell it which Store you're looking for.
-
-**Example:**
-
-```tsx
-// Pretend some parent component already provided the SessionStore
-import { useStore } from "@manyducks.co/dolla";
-import { SessionStore } from "./stores/SessionStore.js";
-
-function Navbar() {
-  const session = useStore(SessionStore);
-
-  return (
-    <nav>
-      <Show when={session.$isLoggedIn}>
-        <p>Yo, {() => session.$user().name}!</p>
-      </Show>
-    </nav>
-  );
-}
-```
-
-### `useStoreProvider(Store, options?)`
-
-This is how you make a `Store` available to a component and all its kids. You create it here, and then any component inside can just use `useStore` to grab it.
-
-**Signature:**
-
-```ts
-function useStoreProvider<T, O>(store: Store<O, T>, options?: O): T;
-```
-
-**Parameters:**
-
-- `store`: The Store you wanna provide.
-- `options` (optional): Any options you need to pass to the Store when it's made.
-
-**Example:**
-
-```tsx
-import { useStoreProvider } from "@manyducks.co/dolla";
-import { ThemeStore } from "./stores/ThemeStore.js";
-import { AppContent } from "./AppContent.js";
-
-function App() {
-  // Provide the ThemeStore to the whole app.
-  // Any child can now get it with useStore(ThemeStore).
-  useStoreProvider(ThemeStore, { defaultTheme: "dark" });
-
-  return <AppContent />;
-}
-```
-
----
-
-End.
-
-- [🗂️ Docs](./index.md)
-- [🏠 README](../README.md)
-- [🦆 That's a lot of ducks.](https://www.manyducks.co)