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

package/docs/views.md

@@ -0,0 +1,208 @@
+# Views
+
+Views are one of two component types in Dolla. We call them views because they deal specifically with presenting visible things to the user. The other type of component, [Stores](./stores.md), deal with data and events.
+
+At its most basic, a view is a function that returns markup.
+
+```jsx
+function ExampleView() {
+  return <h1>Hello World!</h1>;
+}
+```
+
+## View Props
+
+A view function takes a `props` object as its first argument. This object contains all properties passed to the view when it's invoked.
+
+```jsx
+function ListItemView(props) {
+  return <li>{props.label}</li>;
+}
+
+function ListView() {
+  return (
+    <ul>
+      <ListItemView label="Squirrel" />
+      <ListItemView label="Chipmunk" />
+      <ListItemView label="Groundhog" />
+    </ul>
+  );
+}
+```
+
+As you may have guessed, you can pass States as props and slot them in in exactly the same way. This is important because Views do not re-render the way you might expect from other frameworks. Whatever you pass as props is what the View gets for its entire lifecycle.
+
+## View Helpers
+
+### `cond($condition, whenTruthy, whenFalsy)`
+
+The `cond` helper does conditional rendering. When `$condition` is truthy, the second argument is rendered. When `$condition` is falsy the third argument is rendered. Either case can be left null or undefined if you don't want to render something for that condition.
+
+```jsx
+function ConditionalListView(props) {
+  return (
+    <div>
+      {cond(
+        props.$show,
+
+        // Visible when truthy
+        <ul>
+          <ListItemView label="Squirrel" />
+          <ListItemView label="Chipmunk" />
+          <ListItemView label="Groundhog" />
+        </ul>,
+
+        // Visible when falsy
+        <span>List is hidden</span>,
+      )}
+    </div>
+  );
+}
+```
+
+### `repeat($items, keyFn, renderFn)`
+
+The `repeat` helper repeats a render function for each item in a list. The `keyFn` takes an item's value and returns a number, string or Symbol that uniquely identifies that list item. If `$items` changes or gets reordered, all rendered items with matching keys will be reused, those no longer in the list will be removed and those that didn't previously have a matching key are created.
+
+```jsx
+function RepeatedListView() {
+  const [$items, setItems] = createState(["Squirrel", "Chipmunk", "Groundhog"]);
+
+  return (
+    <ul>
+      {repeat(
+        $items,
+        (item, index) => item, // Using the string itself as the key
+        ($item, $index, context) => {
+          return <ListItemView label={$item} />;
+        },
+      )}
+    </ul>
+  );
+}
+```
+
+### `portal(content, parentNode)`
+
+The `portal` helper displays DOM elements from a view as children of a parent element elsewhere in the document. Portals are typically used to display modals and other content that needs to appear at the top level of a document.
+
+```jsx
+function PortalView() {
+  const content = (
+    <div class="modal">
+      <p>This is a modal.</p>
+    </div>
+  );
+
+  // Content will be appended to `document.body` while this view is connected.
+  return portal(document.body, content);
+}
+```
+
+## View Context
+
+A view function takes a context object as its second argument. The context provides a set of functions you can use to respond to lifecycle events, observe dynamic data, print debug messages and display child elements among other things.
+
+```jsx
+function ExampleView(props, ctx) {
+  ctx.onMount(() => {
+    ctx.log("HELLO!");
+  });
+
+  return <h1>Hello World!</h1>;
+}
+```
+
+### Printing Debug Messages
+
+```jsx
+function ExampleView(props, ctx) {
+  // Set the name of this view's context. Console messages are prefixed with name.
+  ctx.name = "CustomName";
+
+  // Print messages to the console. These are suppressed by default in the app's "production" mode.
+  // You can also change which of these are printed and filter messages from certain contexts in the `createApp` options object.
+  ctx.info("Verbose debugging info that might be useful to know");
+  ctx.log("Standard messages");
+  ctx.warn("Something bad might be happening");
+  ctx.error("Uh oh!");
+
+  // If you encounter a bad enough situation, you can halt and disconnect the entire app.
+  ctx.crash(new Error("BOOM"));
+
+  return <h1>Hello World!</h1>;
+}
+```
+
+### Lifecycle Events
+
+```jsx
+function ExampleView(props, ctx) {
+  ctx.beforeMount(() => {
+    // Do something before this view's DOM nodes are created.
+  });
+
+  ctx.onMount(() => {
+    // Do something immediately after this view is connected to the DOM.
+  });
+
+  ctx.beforeUnmount(() => {
+    // Do something before removing this view from the DOM.
+  });
+
+  ctx.onUnmount(() => {
+    // Do some cleanup after this view is disconnected from the DOM.
+  });
+
+  return <h1>Hello World!</h1>;
+}
+```
+
+### Displaying Children
+
+The context has an `outlet` function that can be used to display children at a location of your choosing.
+
+```js
+function LayoutView(props, ctx) {
+  return (
+    <div className="layout">
+      <div className="content">{ctx.outlet()}</div>
+    </div>
+  );
+}
+
+function ExampleView() {
+  // <h1> and <p> are displayed inside LayoutView's outlet.
+  return (
+    <LayoutView>
+      <h1>Hello</h1>
+      <p>This is inside the box.</p>
+    </LayoutView>
+  );
+}
+```
+
+### Watching States
+
+The `watch` function starts observing when the view is connected and stops when disconnected. This takes care of cleaning up watchers so you don't have to worry about memory leaks.
+
+```jsx
+function ExampleView(props, ctx) {
+  const [$count, setCount] = createState(0);
+
+  // This callback will run when any states in the dependency array receive new values.
+  ctx.watch([$count], (count) => {
+    ctx.log("count is now", count);
+  });
+
+  // ...
+}
+```
+
+---
+
+End.
+
+- [🗂️ Docs](./index.md)
+- [🏠 README](../README.md)
+- [🦆 That's a lot of ducks.](https://www.manyducks.co)

package/examples/webcomponent/index.html

@@ -0,0 +1,14 @@
+<!DOCTYPE html>
+<html>
+
+<head>
+  <title>Web Component Example</title>
+</head>
+
+<body>
+  <my-counter></my-counter>
+
+  <script type="module" src="./main.js"></script>
+</body>
+
+</html>

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/core/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.