@manyducks.co/dolla 2.0.0-alpha.6 → 2.0.0-alpha.60

package/notes/atomic.md

@@ -0,0 +1,452 @@
+# 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/context-routes.md

@@ -0,0 +1,61 @@
+# Context routing
+
+I had an idea to integrate routing back into views instead of having a separate router. I originally had it work this way but I wasn't good enough to pull it off then.
+
+Here's how it might look:
+
+```jsx
+function Example(props, ctx) {
+  return <div>
+    <header>
+      <h1>Some kind of layout.</h1>
+    </header>
+    <main>
+      {this.router(function () {
+        this.route("something/*", SomethingView);
+        this.redirect("*", "./something/*");
+      })}
+
+      {ctx.router([
+        // Route path is relative to parent routes.
+        // Nested route definitions are a thing of the past.
+        // View could define its own routes.
+        { path: "something/*", view: SomethingView }
+      ])}
+    </main>
+  <div>
+}
+
+html`
+  <${Router}>
+    <${Route} path="something/*">
+      This child content isn't materialized until the route matches.
+      <${SomethingView} />
+    <//>
+  <//>
+`
+```
+
+This removes the need to import and define the whole app at the top level. You can also add routes as you need them when prototyping.
+
+Route matching would be done by forwarding the wildcard portion of a match to child routers. Routers would be stored on the element context.
+
+Where would route info be stored then? It would have to be on the context as well.
+
+```js
+// Merged data from all parent segments.
+ctx.route.params;
+ctx.route.query;
+ctx.route.path;
+ctx.route.pattern;
+
+ctx.go("/some/path");
+ctx.back();
+ctx.forward();
+```
+
+## Thoughts
+
+- Would eliminate the need for `ctx.outlet()`. Can pass children directly via `children` prop now.
+- Would eliminate the need for `ViewElement` and `setChildView` method because a top level router no longer needs to call it.
+- Couldn't do the current routing strategy of combining all routes into one flat list at the top level.

package/notes/custom-nodes.md

@@ -0,0 +1,17 @@
+What if people could define custom Markup nodes and use them in JSX. Alternative to writing a view if you need lighter weight or more custom elements.
+
+```js
+class CustomNode implements MarkupNode {
+  domNode = document.createElement('div');
+
+  isMounted = false;
+
+  mount(parent, before) {
+
+  }
+
+  unmount(parentIsUnmounting) {
+
+  }
+}
+```

package/notes/effection-idea.md

@@ -0,0 +1,34 @@
+# Effection Idea
+
+This is probably a different framework, but I've been looking into Effection lately. Effection uses generators to manage async code, guaranteeing that cleanup runs and that you can use synchronous constructs like try/catch as you'd expect. I kind of like it, so I was thinking of adapting dolla views to use generators as well for async mounting and cleanup. It's worth trying just as an experiment and for learning more about generators.
+
+Generators are a poorly understood concept to me and I'm guessing most devs, because I never see them suggested as a solution to any problem in mainstream circles.
+
+```js
+const ExampleStore = store(function* () {
+  // Yield setup (optional)
+  yield* function* () {};
+
+  //
+  yield {};
+
+  // Yield teardown (optional)
+  yield* function* () {};
+});
+
+const ExampleView = view(function* () {
+  yield* provide(ExampleStore);
+
+  const example = yield* use(ExampleStore);
+
+  // Yield setup (optional)
+  yield* function* () {};
+
+  // Yield markup for rendering.
+  // When mounting, the view is considered mounted when the view yields markup.
+  yield <div>TEST</div>;
+
+  // Yield teardown (optional)
+  yield* function* () {};
+});
+```

package/notes/elimination.md

@@ -0,0 +1,33 @@
+# 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/mixins.md

@@ -0,0 +1,22 @@
+# Mixins
+
+Sometimes you want to attach logic to a DOM node without writing a whole view around it.
+
+```js
+function myMixin(options: any): Mixin {
+  return function(element: Element, ctx: MixinContext) {
+    ctx.onMount(() => {
+
+    })
+
+    ctx.onUnmount(() => {
+
+    })
+  }
+
+
+  // Returns nothing. Use context methods to attach event listeners / behavior / whatever.
+}
+
+<h1 mixins={[myMixin({ /* options */ }), /* ... */]}>Whatever</h1>
+```

package/notes/molecule.md

@@ -0,0 +1,35 @@
+Like `compose` but it takes an initial value and a function that can set its value asynchronously. Its callback is a tracking context, so it will be re-run when signals called within are updated.
+
+```ts
+interface MoleculeGetter<T> {
+  (): T;
+  <X>(source: MaybeReactive<X>): X;
+}
+
+interface MoleculeSetter<T> {
+  (next: T): void;
+}
+
+interface MoleculeFunction<T> {
+  (get: MoleculeGetter<T>, set: MoleculeSetter<T>): void | (() => void);
+}
+
+function molecule<T>(initialValue: T, fn: MoleculeFunction<T>) {}
+
+const value = molecule(5, (get, set) => {
+  // get() returns the current value stored in this hadron
+  // get(reactive) returns the value of that reactive and tracks it (== reactive.get())
+  // set(value) updates the value stored in this hadron
+  // This function will not be called unless there is at least one observer.
+
+  let interval = setInterval(() => {
+    set(get() + 1);
+  }, 1000);
+
+  // Can return a cleanup function to run between invocations.
+  // Also called when the last observer stops observing.
+  return () => {
+    clearInterval(interval);
+  };
+});
+```