@manyducks.co/dolla 2.0.0-alpha.5 → 2.0.0-alpha.50

package/examples/webcomponent/main.js

@@ -0,0 +1,165 @@
+import { $, effect, when } from "../../dist/index.js";
+
+class EffectScope {
+  #observing = false;
+  #observers = [];
+  #cleanups = [];
+
+  get observing() {
+    return this.#observing;
+  }
+
+  observe(callback) {
+    this.#observers.push(callback);
+    if (this.#observing) {
+      this.#cleanups.push(effect(callback));
+    }
+  }
+
+  start() {
+    this.#observing = true;
+    for (const callback of this.#observers) {
+      this.#cleanups.push(effect(callback));
+    }
+  }
+
+  stop() {
+    this.#observing = false;
+    for (const cleanup of this.#cleanups) {
+      cleanup();
+    }
+    this.#cleanups.length = 0;
+  }
+}
+
+function setAttribute(el, attr, value) {
+  // handle special case attributes
+  el.setAttribute(attr, value);
+}
+
+function createElement(tag, attrs, children) {
+  // attrs can contain signals as values
+  // children can contain signals as values
+
+  // signals will be observed while the element is connected.
+
+  const el = document.createElement(tag);
+  const scope = new EffectScope();
+
+  for (const key in attrs) {
+    if (typeof attrs[key] === "function") {
+      // determine if it's an event handler or a signal
+      // this is determined by the name beginning with "on"
+      if (key.startsWith("on")) {
+        el.addEventListener(key.slice(2), attrs[key]);
+      } else {
+        // if signal then add an observer on the scope.
+        scope.observe(() => {
+          setAttribute(el, key, attrs[key]());
+        });
+      }
+    } else {
+      // attr is static
+      setAttribute(el, key, attrs[key]);
+    }
+  }
+
+  for (const child of children) {
+    if (typeof child === "function") {
+      // transform into a dynamic element
+      // for now just printing it as a string
+      const node = document.createTextNode(String(child()));
+      console.log("HELLO", node, child);
+      scope.observe(() => {
+        node.textContent = String(child());
+      });
+      el.appendChild(node);
+    } else if (child instanceof Node) {
+      el.appendChild(child);
+    } else {
+      el.appendChild(document.createTextNode(String(child)));
+    }
+  }
+
+  // run custom setup logic on connect and disconnect
+  el.$dolla = {
+    connected: false,
+    connect() {
+      if (this.connected) return;
+      console.log(el, "$dolla connected");
+      scope.start();
+
+      for (const child of el.childNodes) {
+        if ("$dolla" in child) {
+          child.$dolla.connect();
+        }
+      }
+    },
+    disconnect() {
+      if (!this.connected) return;
+      console.log(el, "$dolla disconnected");
+      scope.stop();
+
+      for (const child of el.childNodes) {
+        if ("$dolla" in child) {
+          child.$dolla.disconnect();
+        }
+      }
+    },
+  };
+
+  return el;
+}
+
+function mount(element, parent) {
+  // Observe childList changes on subtree and run lifecycle callbacks.
+  const observer = new MutationObserver((mutations) => {
+    for (const mutation of mutations) {
+      for (const node of mutation.addedNodes) {
+        if ("$dolla" in node) {
+          node.$dolla.connect();
+        }
+      }
+
+      for (const node of mutation.removedNodes) {
+        if ("$dolla" in node) {
+          node.$dolla.disconnect();
+        }
+      }
+    }
+  });
+  observer.observe(parent, { childList: true, subtree: true });
+
+  parent.appendChild(element);
+}
+
+// const html = htm.bind(createElement);
+
+// need array of all event handler names
+
+class DollaElement extends HTMLElement {
+  connectedCallback() {
+    if (this.template) {
+      mount(this.template, this);
+    }
+  }
+}
+
+class MyCounter extends DollaElement {
+  count = $(0);
+  increment = () => this.count((x) => x + 1);
+
+  template = createElement("div", {}, [
+    createElement("span", {}, ["Clicks: ", this.count]),
+    createElement("button", { onclick: this.increment }, ["Click Me!"]),
+    () => this.count() > 10 && createElement("span", {}, ["That's a lot of clicks."]),
+  ]);
+
+  // template = html`
+  //   <span>Clicks: ${this.count}</span>
+  //   <button onclick=${this.increment}>Click Me!</button>
+  //   ${() => this.count() > 10 && html`<span>That's a lot!</span>`}
+  // `;
+}
+
+customElements.define("my-counter", MyCounter);

package/index.d.ts

@@ -1,6 +1,6 @@
-export * from "./lib/index";
+export * from "./src/index";
 
-import type { IntrinsicElements as Elements } from "./lib/core/types";
+import type { IntrinsicElements as Elements } from "./src/types";
 
 declare global {
   namespace JSX {

package/notes/TODO.md

@@ -0,0 +1,6 @@
+# TO DO LIST
+
+- Combine/refactor very similar Group, Outlet and Observer nodes.
+  - Group is simplest and exists to mount an array of MarkupElements as one.
+  - Outlet is basically the same as Group but it expects a $children state with an array of MarkupElements.
+  - Observer is a generic catch-all that works with a set of states and a render function. The render function can return any kind of Renderable which is then converted into a MarkupElement, but very similar update logic outside of that. Observer uses Group internally.

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) {
+
+  }
+}
+```