@manyducks.co/dolla 2.0.0 → 3.1.0

package/notes/atomic.md

@@ -1,452 +0,0 @@
-# ATOMIC overhaul
-
-Overhaul of Dolla as Atomic.
-
-Diff:
-
-- Change signals to plain functions.
-- Access component context things with $functions in the component body.
-- Split `router` and `localize` into companion packages.
-- No top-level app; just `mount` a view.
-
-Goals:
-
-- Easy drop-in script tag to get started. Feasible to start with a CDN for prototyping and introduce build step later.
-- Server side rendering support. `html` templates should create intermediate data structure that can be turned into DOM nodes or a string.
-
-## Signals
-
-```js
-import { atom, memo } from "@manyducks.co/atomic";
-
-// Atoms are hybrid getter/setter functions. Call without a value to get, call with a value to set.
-const count = atom(0);
-
-// Basic computed properties are just functions. Taking advantage of the fact that functions called in functions will still be tracked.
-const doubled = () => count() * 2;
-
-// Use memo to make a memoized value for more expensive calculations.
-const quadrupled = memo(() => doubled() * 2);
-```
-
-## Scopes
-
-Provided are certain functions that start with a `$` character. These are scope functions. They only work inside a component scope, which is to say, inside the body of a View or Store function.
-
-ViewContext and StoreContext cease to be something the user worries about. Just import and call scope functions. This also provides TypeScript autocomplete for stores and things in plain JS.
-
-```js
-function Example() {
-  // Lifecycle
-  $mount(() => {
-    // ...
-  });
-  $unmount(() => {
-    // ...
-  });
-
-  // Logger
-  const debug = $debug();
-  const debug = $debug("my-custom-prefix"); // Optionally pass a prefix (replaces ctx.name = "...")
-
-  // Signal effects
-  const count = atom(0);
-  $effect(() => {
-    debug.log("count has changed: %d", count());
-
-    return () => {
-      // Cleanup function. Runs between effect invocations or on unmount.
-    };
-  });
-
-  // Context/Stores
-  $provide(SomeStore);
-  const some = $use(SomeStore);
-
-  // Router lib:
-  const router = $router();
-  router.pattern; // full pattern up to this point in the tree (merged from nested parent routers)
-  router.path; // full path up to this point
-  router.params; // merged params
-  router.query; // parsed query params
-  // Router navigation:
-  router.go("/somewhere/else");
-  router.back();
-  router.forward();
-
-  // .on() returns an outlet on which you can chain more .on() to define subroutes.
-  // This goes directly into your template to render those routes.
-  const outlet = router
-    .on("/example/route/one/*", SomeView)
-    .on("/example/route/two/*", OtherView)
-    .on("/example/route/three/*", AnotherView);
-
-  // Localize lib:
-  const { t } = $localize();
-
-  // Special internal function. Returns the actual internal context object.
-  // This could be exported for extension purposes.
-  const ctx = $$context();
-
-  // TODO: Need another way to render children. Children should be passed to the view (as Markup).
-  // So maybe just passing them into your template would work.
-}
-```
-
-### Scopes
-
-> NOTE: Views and directives are called within a scope.
-
-```js
-// Functions starting with $ can be called within a scope.
-// Scopes will clean up all effects created within them when they are disconnected.
-const scope = createScope(() => {
-  $effect(() => {
-    // Atoms and memos called within an $effect are automatically tracked.
-    console.log(`count is ${count()} (doubled: ${doubled()})`);
-  });
-
-  // Changing tracked values will trigger effects to run again.
-  count(1);
-
-  // $effects are called immediately once, then again each time one or more dependencies change.
-  // Effects are settled in queueMicrotask(), effectively batching them.
-
-  count(2);
-  count(3);
-  count(4);
-  // Multiple synchronous calls in a row like this will only trigger the effect once.
-});
-
-// ----- Scope Functions ----- //
-
-$effect(() => {
-  // Tracks dependencies. This function will run again when any of them change.
-});
-
-$connected(() => {
-  // Runs when scope is connected.
-  // In views and directives this happens in the next microtask after DOM nodes are attached.
-});
-
-$disconnected(() => {
-  // Runs when scope is disconnected.
-  // In views and directives this happens in the next microtask after DOM nodes are disconnected.
-});
-
-// ----- Scope API ----- //
-
-const scope = createScope(() => {
-  /* ... */
-});
-
-// Connect starts all $effects and runs $connected callbacks.
-scope.connect();
-
-// Disconnect disposes all $effects and runs $disconnected callbacks.
-scope.disconnect();
-```
-
-## Templates
-
-```js
-// Provide directives and views in a config object.
-const template = html({
-  directives: { custom: customDirective },
-  views: { SomeView },
-})`
-  <div>
-    <SomeView *custom=${x} prop=${value} />
-  </div>
-`;
-
-// Or put the views and directives at the end?
-const template = html`
-  <div>
-    <p>Counter: ${count}</p>
-
-    <!-- bind events with @name -->
-    <div>
-      <button @click=${increment}>+1</button>
-      <button @click=${decrement}>-1</button>
-    </div>
-
-    <!-- apply directives with *name -->
-    <div *ref=${refAtom} *if=${x} *unless=${x} *show=${x} *hide=${x} *classes=${x} *styles=${x} *custom=${whatever} />
-
-    <!-- bind properties with .name -->
-    <span .textContent=${x} />
-
-    <!-- two-way bind atoms with :value -->
-    <input :value=${valueAtom} />
-
-    <ul *if=${hasValues}>
-      <!-- render iterables from signals with list() -->
-      ${list(values, (value, index) => {
-        // Render views into HTML templates with view()
-        return html`<li><SomeView item=${value} /></li>`.withViews({ SomeView });
-      })}
-    </ul>
-  </div>
-`
-  .withDirectives({ custom: customDirective })
-  .withViews({ SomeView });
-
-// Key
-// @ for event listeners
-// * for directives
-// . for properties
-// :value for two-way value binding
-// no prefix for attributes
-```
-
-### Event modifiers
-
-```js
-html`<button
-  @click.stop.prevent.throttle[250]=${() => {
-    // stopPropagation & preventDefault already called
-    // Listener will be triggered a maximum of once every 250 milliseconds.
-  }}
->
-  Click Me
-</button>`;
-```
-
-You can chain modifiers on event handlers. Inspired by [`Mizu.js`](https://mizu.sh/#event).
-
-#### `.prevent`
-
-Calls event.preventDefault() when triggered.
-
-#### `.stop`
-
-Calls event.stopPropagation() when triggered.
-
-#### `.once`
-
-Register listener with { once: true }. If present the listener is removed after being triggered once.
-
-#### `.passive`
-
-Register listener with { passive: true }.
-
-#### `.capture`
-
-Register listener with { capture: true }.
-
-#### `.self`
-
-Trigger listener only if event.target is the element itself.
-
-#### `.attach[element | window | document]`
-
-> `@click.attach[document]=${...}`
-
-Attach listener to a different target.
-
-#### `.throttle[duration≈250ms]`
-
-Prevent listener from being called more than once during the specified time frame. Duration value is in milliseconds.
-
-#### `.debounce[duration≈250ms]`
-
-Delay listener execution until the specified time frame has passed without any activity. Duration value is in milliseconds.
-
-### Lists
-
-```js
-list(values, (value, index) => {
-  return html`<li>${view(SomeComponent, value)}</li>`;
-});
-```
-
-### Custom Directives
-
-```js
-function myDirective(element, value, modifiers) {
-  // Directives are called inside a scope.
-  $disconnected(() => {
-    // Cleanup
-  });
-}
-```
-
-## Full Example
-
-```js
-import { atom, memo, html, connect, $effect } from "@manyducks.co/atomic";
-
-// Functions starting with $ can only be called in the body of a component function.
-
-// IDEA: CSS components. Ref counted and added to head while used at least once on the page.
-const button = css`
-  color: "red";
-
-  &:hover {
-    color: "blue";
-  }
-`;
-
-function Counter() {
-  const debug = logger("Component");
-
-  const count = atom(0);
-
-  // Simple computed value; computation runs each time function is called
-  const doubled = () => count() * 2;
-
-  // Memoized; computation only runs when one of its dependencies changes
-  const quadrupled = memo((previousValue) => doubled() * 2, { equals: deepEqual });
-  // memos pass their previous to their callback
-  // memos can have an equality function specified (as can atoms)
-
-  $effect(() => {
-    // Dependencies are tracked when getters are called in a tracked scope.
-    // Tracked scopes are the body of a `memo` or `effect` callback.
-    debug.log(`Count is: ${count()}`);
-
-    // untrack
-    const value = peek(count);
-    const doubled = peek(() => {
-      return count() * 2;
-    });
-  });
-
-  $connected(() => {
-    // Runs when component is connected.
-  });
-
-  $disconnected(() => {
-    // Runs when component is disconnected.
-  });
-
-  function increment() {
-    // Set new value
-    count(count() + 1);
-  }
-
-  function decrement() {
-    count(count() - 1);
-  }
-
-  const hasValues = () => values().length > 0;
-
-  return html`
-    <div>
-      <p>Counter: ${count}</p>
-      <div>
-        <button @click=${increment}>+1</button>
-        <button @click=${decrement}>-1</button>
-      </div>
-
-      <div *ref=${refAtom} *if=${x} *unless=${x} *show=${x} *hide=${x} *classes=${x} *styles=${x} *custom=${whatever} />
-
-      <!-- Property binding -->
-      <span .textContent=${x} />
-
-      <!-- Two way binding of atoms -->
-      <input :value=${valueAtom} />
-
-      <ul *if=${hasValues}>
-        ${list(values, (value, index) => {
-          return html`<li>${view(SomeComponent, value)}</li>`;
-        })}
-      </ul>
-    </div>
-  `.withDirectives({ custom: customDirective });
-}
-
-// In another file...
-
-function refDirective(element, fn) {
-  fn(element);
-  $disconnected(() => {
-    fn(undefined);
-  });
-}
-
-function ifDirective(element, condition) {
-  // directives run in microtask immediately after element is attached to parent, before next paint
-
-  const placeholder = document.createComment("");
-
-  // $functions work in directives; they hook into the lifecycle of the element
-  $effect(() => {
-    if (condition()) {
-      // show element
-      if (!element.parentNode && placeholder.parentNode) {
-        element.insertBefore(placeholder.parentNode);
-        placeholder.parentNode.removeChild(placeholder);
-      }
-    } else {
-      // hide element
-      if (element.parentNode && !placeholder.parentNode) {
-        placeholder.insertBefore(element.parentNode);
-        element.parentNode.removeChild(element);
-      }
-    }
-  });
-}
-
-function unlessDirective(element, condition) {
-  return ifDirective(element, () => !condition());
-}
-
-function showDirective(element, condition) {
-  // Store the element's current value.
-  let value = element.style.display;
-
-  $effect(() => {
-    if (condition()) {
-      // Apply the stored value when truthy.
-      element.style.display = value;
-    } else {
-      // Store value and hide when falsy.
-      value = element.style.display;
-      element.style.display = "none !important";
-    }
-  });
-}
-
-function hideDirective(element, condition) {
-  return showDirective(element, () => !condition());
-}
-
-function classesDirective(element, classes) {
-  // TODO: Applies an object of class names and values, where the values may be signals or plain values.
-  // Truthy means "apply this class" while falsy means don't.
-}
-
-function stylesDirective(element, styles) {
-  // TODO: Same idea as *classes but for styles.
-}
-
-connect(Component, document.body);
-
-// Easy custom elements? Could be another library.
-element("my-counter", function () {
-  // Runs just after connectedCallback. `this` is bound to the custom HTMLElement class.
-  const shadow = this.attachShadow({ mode: "closed" });
-
-  return html`<div></div>`;
-});
-
-// function css(strings, values) {
-//   return {
-//     type: "css",
-
-//   }
-// }
-```
-
-```ts
-interface TemplateNode {
-  mount(parent: Node, after?: Node): void;
-  unmount(skipDOM?: boolean): void;
-}
-
-interface TemplateDirective {
-  (element: Element, value: unknown): Node | TemplateNode;
-}
-```

package/notes/elimination.md

@@ -1,33 +0,0 @@
-# What can we remove?
-
-I still want to get this library with all its features down below 15kb. It's currently at 17.8kb. That said, I don't want to strip out things that are actually useful. The mission of this library is to be batteries-included, which implies some extra weight.
-
-What can be removed without compromising the basics?
-
-## Events?
-
-> 1st ELIMINATED. We're at 16.77kb now.
-
-If we have the ability to get contexts and call methods on them, isn't that just a better version of events?
-
-## Logger / Built-in Crash View
-
-> REDUCED! Removed simple-color-hash in favor of custom OKLCH hash and we're down to 15.9kb.
-
-Logger could be a different package. Crashes could be handled by a crash handler you attach.
-
-```js
-Dolla.onCrash((error) => {
-  // Do what you will with this error.
-});
-```
-
-## HTTP Client?
-
-Do we really need this? It's kind of a nice wrapper but the only thing I use the middleware for is to add auth headers for API calls, and it's trivial to write a function around `fetch` that does that. No need for the complexity of middleware.
-
-Not really. Fetch is hella basic. I just tried to write my own trivial wrapper around fetch and it took a little too much thought. I don't want to do that for every project. Adding middleware to authenticate feels trivial with `http`.
-
-## Markup?
-
-Can JSX and `html` return DOM nodes directly? Not really, because views need to be mounted and unmounted like DOM nodes but they don't have the same API. Although I could define a minimal DOM-compatible API so that DOM nodes could directly work.

package/notes/observable.md

@@ -1,180 +0,0 @@
-# Observable
-
-Signals have some downsides, like if you call them inside a function, and you then call that function inside a tracking context, it can cause the tracking context to re-run unexpectedly. You then have to defensively call things inside `untracked` to avoid tracking deeply nested signal getters. It's not unmanageable but it's extremely surprising and unintuitive when you first run into it. It's a new and unnecessary consideration that makes code feel less safe and predictable.
-
-I'm considering using Observable (or my own extended version of it) as a basis for a state management system. Still built on top of `alien-signals` but with explicit tracking of signal values. It could look something like the following.
-
-This would probably be best as a separate library, maybe called `@manyducks.co/atomic`.
-
-Going back to the atom/compose terminology.
-
-```js
-// Define an atom, the basic value holder object.
-const count = atom(5);
-
-// Atoms have a `value` field that is writable. This is not tracked by default.
-count.value; // 5
-count.value = 12;
-count.value; // 12
-
-// Implements the Observable interface.
-const subscription = count.subscribe({
-  next: (value) => {
-    console.log("count is now", value);
-  },
-  error: (error) => {},
-  completed: () => {},
-});
-subscription.closed; // boolean
-subscription.unsubscribe();
-
-// Like `value` getter but tracks count in a signal tracking scope.
-count.track(); // 12
-
-// Can be closed which completes all subscribers and will throw an error if a new value is set.
-count.close();
-```
-
-Atoms can be composed.
-
-```js
-// You explicitly pass a dependencies array at the end, similar to React.
-// Dependencies will be tracked and the compose function re-run any time they receive a new value.
-const doubled = composed((prev) => count.value * 2, [count]);
-
-// Read-only value.
-doubled.value;
-
-// Observable
-const subscription = doubled.subscribe((value) => {
-  // ...
-});
-
-// Trackable
-doubled.track();
-
-// Completes subscriptions, untracks deps and prevents receiving any new values.
-doubled.close();
-```
-
-Effects work basically the same as `composed` but they return a cancel function instead of a value.
-
-```js
-const cancel = effect(() => {
-  console.log(`count is now ${count.value}`);
-}, [count]);
-
-cancel();
-```
-
-Other thoughts:
-
-```js
-// You can name observables for debugging purposes. If one of them throws an error it can include the name.
-const count = atom(5).named("count");
-
-// Maybe even named effects.
-const cancel = effect(() => {
-  console.log(`count is now ${count.value}`);
-}, [count]).named("countReader");
-
-// Promise-based await next? This will resolve when count.value is set.
-// If the subscription errors it rejects with that error. If the subscription completes it rejects with an error to indicate that.
-const nextCount = await count.nextValue();
-
-// Filter and signal. Wait up to 5 seconds for next even value.
-const controller = new AbortController();
-setTimeout(controller.abort, 5000);
-const nextEven = await count.nextValue({
-  filter: (value) => value % 2 === 0,
-  signal: controller.signal,
-  // or timeout: 5000
-});
-// Resolves to null if aborted or timed out.
-
-// Batching
-
-const count1 = atom(5);
-const count2 = atom(12);
-
-effect(() => {
-  console.log(`total: ${count1.value + count2.value}`);
-}, [count1, count2]);
-
-// This causes the effect to run twice
-count1.value = 50;
-count2.value = 8;
-
-// A batch suspends effects until it concludes; this runs the effect once
-batch(() => {
-  count1.value = 50;
-  count2.value = 8;
-});
-
-// Deep reactivity
-const data = atom(
-  {
-    users: [
-      { id: 1, name: "Tony" },
-      { id: 2, name: "Morgan" },
-    ],
-  },
-  { deep: true },
-);
-
-// These updates trigger effects and subscriptions.
-// By default only setting `.value` directly will trigger notifications.
-data.value.users[0].name = "Bon";
-data.value.users.find((user) => user.id === 1).name = "Tony";
-
-// Then in theory, if you referenced one of the values
-const morgan = data.value.users.find((user) => user.id === 2);
-
-// And passed that around and modified it that would also still be reactive to the original atom.
-// I don't know if this is a good idea.
-morgan.name = "AKLSJDAKSD";
-```
-
-## What would Dolla look like with this?
-
-```jsx
-function CounterView() {
-  const count = atom(0);
-
-  const increment = () => count.value++;
-  const decrement = () => count.value--;
-
-  return (
-    <div>
-      Counter: {count}
-      <button onClick={increment}>+1</button>
-      <button onClick={decrement}>-1</button>
-    </div>
-  );
-}
-
-function ExampleView(props, ctx) {
-  const name = atom("");
-
-  // Update local name whenever props.name changes
-  ctx.effect(() => {
-    name.value = props.name.value;
-  }, [props.name]);
-
-  // Update greeting whenever local name changes
-  const greeting = composed(() => `Hello, ${name.value}`, [name]);
-
-  return (
-    <div>
-      <span>{greeting}</span>
-      <input value={name} onInput={(e) => (name.value = e.target.value)} />
-    </div>
-  );
-}
-```
-
-## TypeScript
-
-- `Atom<T>` for the basic building block with a writable value.
-- `Composed<T>` for a derived state based on other `Atom<T>` and `Composed<T>` values.
-- `Atomic<T>` to encompass the basic API of both `Atom<T>` and `Composed<T>`.