@manyducks.co/dolla 2.0.0-alpha.30 → 2.0.0-alpha.32

package/docs/views.md

@@ -2,12 +2,12 @@
 
 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 elements.
+At its most basic, a view is a function that returns markup.
 
 ```jsx
-const ExampleView = createView(function () {
+function ExampleView() {
   return <h1>Hello World!</h1>;
-});
+}
 ```
 
 ## View Props
@@ -15,11 +15,11 @@ const ExampleView = createView(function () {
 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
-const ListItemView = createView(function (props) {
+function ListItemView(props) {
   return <li>{props.label}</li>;
-});
+}
 
-const ListView = createView(function () {
+function ListView() {
   return (
     <ul>
       <ListItemView label="Squirrel" />
@@ -27,7 +27,7 @@ const ListView = createView(function () {
       <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.
@@ -39,7 +39,7 @@ As you may have guessed, you can pass States as props and slot them in in exactl
 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
-const ConditionalListView = createView(function (props) {
+function ConditionalListView(props) {
   return (
     <div>
       {cond(
@@ -57,7 +57,7 @@ const ConditionalListView = createView(function (props) {
       )}
     </div>
   );
-});
+}
 ```
 
 ### `repeat($items, keyFn, renderFn)`
@@ -65,7 +65,7 @@ const ConditionalListView = createView(function (props) {
 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
-const RepeatedListView = createView(function () {
+function RepeatedListView() {
   const [$items, setItems] = createState(["Squirrel", "Chipmunk", "Groundhog"]);
 
   return (
@@ -79,7 +79,7 @@ const RepeatedListView = createView(function () {
       )}
     </ul>
   );
-});
+}
 ```
 
 ### `portal(content, parentNode)`
@@ -87,7 +87,7 @@ const RepeatedListView = createView(function () {
 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
-const PortalView = createView(function () {
+function PortalView() {
   const content = (
     <div class="modal">
       <p>This is a modal.</p>
@@ -96,80 +96,66 @@ const PortalView = createView(function () {
 
   // 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.
 
-The context can be accessed in one of two ways; as `this` when you pass a non-arrow function, or as the second parameter passed after the props object.
-
 ```jsx
-// Option 1: Access through `this`
-const ExampleView = createView(function (props) {
-  this.onMount(() => {
-    this.log("HELLO!");
-  });
-
-  return <h1>Hello World!</h1>;
-});
-
-// Option 2: Access as second argument (for arrow functions)
-const ExampleView = createView((props, ctx) => {
+function ExampleView(props, ctx) {
   ctx.onMount(() => {
     ctx.log("HELLO!");
   });
 
   return <h1>Hello World!</h1>;
-});
+}
 ```
 
-Which one you use is just an aesthetic preference, but I kind of like the classic `function` syntax with `this`.
-
 ### Printing Debug Messages
 
 ```jsx
-const ExampleView = createView(function (props) {
+function ExampleView(props, ctx) {
   // Set the name of this view's context. Console messages are prefixed with name.
-  this.setName("CustomName");
+  ctx.setName("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.
-  this.info("Verbose debugging info that might be useful to know");
-  this.log("Standard messages");
-  this.warn("Something bad might be happening");
-  this.error("Uh oh!");
+  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.
-  this.crash(new Error("BOOM"));
+  ctx.crash(new Error("BOOM"));
 
   return <h1>Hello World!</h1>;
-});
+}
 ```
 
 ### Lifecycle Events
 
 ```jsx
-const ExampleView = createView(function (props) {
-  this.beforeMount(() => {
+function ExampleView(props, ctx) {
+  ctx.beforeMount(() => {
     // Do something before this view's DOM nodes are created.
   });
 
-  this.onMount(() => {
+  ctx.onMount(() => {
     // Do something immediately after this view is connected to the DOM.
   });
 
-  this.beforeUnmount(() => {
+  ctx.beforeUnmount(() => {
     // Do something before removing this view from the DOM.
   });
 
-  this.onUnmount(() => {
+  ctx.onUnmount(() => {
     // Do some cleanup after this view is disconnected from the DOM.
   });
 
   return <h1>Hello World!</h1>;
-});
+}
 ```
 
 ### Displaying Children
@@ -177,15 +163,15 @@ const ExampleView = createView(function (props) {
 The context has an `outlet` function that can be used to display children at a location of your choosing.
 
 ```js
-const LayoutView = createView(function (props) {
+function LayoutView(props, ctx) {
   return (
     <div className="layout">
-      <div className="content">{this.outlet()}</div>
+      <div className="content">{ctx.outlet()}</div>
     </div>
   );
-});
+}
 
-const ExampleView = createView(function () {
+function ExampleView() {
   // <h1> and <p> are displayed inside LayoutView's outlet.
   return (
     <LayoutView>
@@ -193,7 +179,7 @@ const ExampleView = createView(function () {
       <p>This is inside the box.</p>
     </LayoutView>
   );
-});
+}
 ```
 
 ### Watching States
@@ -201,16 +187,16 @@ const ExampleView = createView(function () {
 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
-const ExampleView = createView(function (props) {
+function ExampleView(props, ctx) {
   const [$count, setCount] = createState(0);
 
   // This callback will run when any states in the dependency array receive new values.
-  this.watch([$count], (count) => {
-    this.log("count is now", count);
+  ctx.watch([$count], (count) => {
+    ctx.log("count is now", count);
   });
 
   // ...
-});
+}
 ```
 
 ### Context Variables
@@ -219,24 +205,24 @@ const ExampleView = createView(function (props) {
 
 ### Context Events
 
-Events can be emitted from views and [stores](./stores.md) using `this.emit(eventName, data)`. Context events will bubble up the view tree just like native browser events bubble up the DOM tree.
+Events can be emitted from views and [stores](./stores.md) using `ctx.emit(eventName, data)`. Context events will bubble up the view tree just like native browser events bubble up the DOM tree.
 
 ```js
-this.on("eventName", (event) => {
+ctx.on("eventName", (event) => {
   event.type; // "eventName"
   event.detail; // the value that was passed when the event was emitted (or undefined if none)
 });
 
-this.once("eventName", (event) => {
+ctx.once("eventName", (event) => {
   // Receive only once and then stop listening.
 });
 
 // Remove a listener by reference.
 // Listener must be the same exact function that was passed to `on` or `once`.
-this.off("eventName", listener);
+ctx.off("eventName", listener);
 
 // Emit an event.
-this.emit("eventName", { value: "This object will be exposed as event.detail" });
+ctx.emit("eventName", { value: "This object will be exposed as event.detail" });
 ```
 
 ### Bubbling
@@ -244,12 +230,12 @@ this.emit("eventName", { value: "This object will be exposed as event.detail" })
 Events bubble up through the view tree unless `stopPropagation` is called by a listener. In the following example we have a view listening for events that are emitted from a child of a child.
 
 ```js
-const ParentView = createView(function () {
+function ParentView(props, ctx) {
   // Listen for greetings that bubble up.
-  this.on("greeting", (event) => {
+  ctx.on("greeting", (event) => {
     const { name, message } = event.detail;
 
-    this.log(`${name} says "${message}"!`);
+    ctx.log(`${name} says "${message}"!`);
   });
 
   return (
@@ -257,10 +243,10 @@ const ParentView = createView(function () {
       <ChildView />
     </div>
   );
-});
+}
 
-const ChildView = createView(function () {
-  this.on("greeting", (event) => {
+function ChildView(props, ctx) {
+  ctx.on("greeting", (event) => {
     // Let's perform some censorship.
     // If propagation is stopped this event will not bubble any further and ParentView won't see it.
     if (containsForbiddenKnowledge(event.message)) {
@@ -273,9 +259,9 @@ const ChildView = createView(function () {
       <ChildOfChildView />
     </div>
   );
-});
+}
 
-const ChildOfChildView = createView(function () {
+function ChildOfChildView(props, ctx) {
   return (
     <form
       onSubmit={(e) => {
@@ -288,7 +274,7 @@ const ChildOfChildView = createView(function () {
         const message = e.currentTarget.message.value;
 
         // Emit!
-        this.emit("greeting", { name, message });
+        ctx.emit("greeting", { name, message });
       }}
     >
       <input type="text" name="name" placeholder="Your Name" />
@@ -296,7 +282,7 @@ const ChildOfChildView = createView(function () {
       <button type="submit">Submit</button>
     </form>
   );
-});
+}
 ```
 
 ---

package/notes/scratch.md

@@ -1,5 +1,140 @@
 # Scratch Note
 
+Idea: Monomorphic app context. Replaces StoreContext, ViewContext, etc.
+
+Routes are baked into the app once again, but
+
+```jsx
+import { createRoot } from "@manyducks.co/dolla";
+import { example } from "./stores/example.js";
+
+const root = createRoot();
+
+root.use(example());
+
+async function auth(_, state, redirect) {
+  // route context
+  // Routes run through each callback until one resolves to a renderable value.
+  // If redirect is called, the route is re-matched and no further callbacks are run for this route.
+
+  if (state.auth == null) {
+    redirect("/login");
+  }
+}
+
+root.route("/users/*", auth, (C) => {
+  C.route("/{#id}/*", (C) => {
+    C.route("/", (C) => <UserDetailRoute userId={C.params.id} />);
+    C.route("*", "./");
+  });
+});
+
+root.route("/users/*", auth, (route) => {
+  route("/{#id}/*", (route) => {
+    // TODO: It's possible to reference the wrong 'route'
+    // Track active context and throw error if the one you call belongs to the wrong context?
+    route("/", (_, state) => <UserDetailView userId={state.params.id} />);
+    route("*", "./");
+  });
+});
+
+function ExampleView(props, ctx) {
+  // ctx.routes returns a special type of outlet that renders children based on
+  // the route segments that come after the ones at this ctx.
+
+  // The weakness of this idea is that routes can't be validated without initializing views.
+  return (
+    <div>
+      <Suspense fallback={<span>Loading...</span>}>
+        {ctx.routes((route) => {
+          route("/subroute", () => <OtherView />);
+
+          // Routes can be async.
+          route("/other", () => import("some-module"));
+        })}
+      </Suspense>
+    </div>
+  );
+
+  // Also Suspense. This can be simply implemented with events.
+  ctx.emit("suspense:begin", uniqueId);
+  // Then when done:
+  ctx.emit("suspense:end", uniqueId);
+
+  // The nearest Suspense view will track ids which are in suspense and show fallback content in the meantime.
+}
+
+function Suspense(props, ctx) {
+  const [$tracked, setTracked] = createState({});
+
+  ctx.on("suspense:begin", (e) => {
+    setTracked((tracked) => {
+      return {
+        ...tracked,
+        [e.detail]: new Date(),
+      };
+    });
+  });
+
+  ctx.on("suspense:end", (e) => {
+    setTracked((tracked) => {
+      const updated = Object.assign({}, tracked);
+      delete updated[e.detail];
+      return updated;
+    });
+  });
+
+  // TODO: Hide suspended view without unmounting it. This might take special logic.
+}
+
+// Can also pass markup directly if you don't need the context.
+root.route("/", auth, <HomeRoute />);
+
+// Static redirect.
+root.route("*", "/");
+
+// Programmatic redirect.
+root.route("*", (C) => {
+  C.log("hit wildcard");
+  C.redirect("/");
+});
+
+root.mount(document.body);
+
+// generate an HTML string for server side rendering.
+root.toString("/some/path");
+```
+
+---
+
+```js
+class ClockStore extends Store {
+
+
+  constructor() {
+
+  }
+}
+
+class CounterStore extends Store {
+  // Could have better name. This will catch any
+  // this.emit('counter:increment') or this.emit('counter:decrement') calls
+  // and update the state according to these functions.
+  value = new Emittable('counter', 0, {
+    increment: state => state + 1,
+    decrement: state => state - 1
+  });
+}
+
+type CounterEvents = {
+  increment: [amount: number];
+  decrement: [amount: number];
+}
+
+
+
+```
+
 ---
 
 Bring the $ back and the name full circle.

package/notes/stores.md

@@ -3,71 +3,53 @@
 Ideas for updating the API.
 
 ```js
-import { createStore, attachStore, useStore, createView } from "@manyducks.co/dolla";
+import { attachStore, useStore } from "@manyducks.co/dolla";
 
-const Counter = createStore(function (initialCount: number) {
+function CounterStore(initialCount = 0, ctx) {
   const [$value, setValue] = createState(initialCount);
 
-  this.on("counter:increment", (e) => {
+  ctx.on("counter:increment", (e) => {
     e.stopPropagation(); // Stop this event from bubbling up to counters at higher levels (if any).
     setValue((current) => current + 1);
   });
 
-  this.on("counter:decrement", (e) => {
+  ctx.on("counter:decrement", (e) => {
     e.stopPropagation();
     setValue((current) => current - 1);
   });
 
   // Events can be emitted from this context in a store.
-  this.emit("otherEvent");
+  ctx.emit("otherEvent");
 
-  this.onMount(() => {
+  ctx.onMount(() => {
     // Setup
     // This is called based on the context the store is attached to.
     // If Dolla, it's called when the app is mounted. If ViewContext, it's called when the view is mounted.
   });
-  this.onUnmount(() => {
+  ctx.onUnmount(() => {
     // Cleanup
   });
 
   // Context variables will be accessible on the same context (e.g. the view this is attached to and below)
-  this.get("context variable");
-  this.set("context variable", "context variable value");
+  ctx.get("context variable");
+  ctx.set("context variable", "context variable value");
 
   // Stores don't have to return anything, but if they do it becomes accessible by using `useStore(ctx, Store)`.
   return $value;
-});
+}
 
 // Attach it to the app.
-Dolla.attachStore(Counter(0));
+Dolla.attachStore(CounterStore, 0);
 
-const ExampleView = createView(function () {
+function ExampleView(props, ctx) {
   // useStore lets you access the return value
   // but the events will still be received and handled regardless
-  const $count = this.useStore(Counter);
-
-  // Convenience helper to attach and use in one step?
-  const $count = this.attachAndUseStore(Counter(0));
+  const $count = ctx.useStore(Counter);
 
   return html`
     <button onclick=${() => this.emit("counter:decrement")}>-1</button>
     <span>${$count}</span>
     <button onclick=${() => this.emit("counter:increment")}>+1</button>
   `;
-});
-
-// ViewContext is also still passed as a second argument if you'd rather use arrow functions to define views.
-const ExampleView = createView((props, self) => {
-  // useStore lets you access the return value
-  // but the events will still be received and handled regardless
-  const $count = self.useStore(Counter);
-
-  return html`
-    <button onclick=${() => self.emit("counter:decrement")}>-1</button>
-    <span>${$count}</span>
-    <button onclick=${() => self.emit("counter:increment")}>+1</button>
-  `;
-});
+}
 ```
-
-This means `createStore` returns a function that is called to create a Store instance. The instance is

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@manyducks.co/dolla",
-  "version": "2.0.0-alpha.30",
+  "version": "2.0.0-alpha.32",
   "description": "Front-end components, routing and state management.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/build.js

@@ -1,34 +0,0 @@
-import fs from "node:fs";
-import esbuild from "esbuild";
-
-esbuild
-  .build({
-    entryPoints: ["src/index.ts"],
-    bundle: true,
-    metafile: true,
-    sourcemap: true,
-    // minify: process.env.NODE_ENV === "production",
-    outdir: "dist",
-    format: "esm",
-  })
-  .then((result) => {
-    fs.writeFileSync("esbuild-meta.json", JSON.stringify(result.metafile));
-  });
-
-esbuild.build({
-  entryPoints: ["src/jsx-runtime.js"],
-  bundle: false,
-  minify: false,
-  sourcemap: true,
-  outdir: "dist",
-  format: "esm",
-});
-
-esbuild.build({
-  entryPoints: ["src/jsx-dev-runtime.js"],
-  bundle: false,
-  minify: false,
-  sourcemap: true,
-  outdir: "dist",
-  format: "esm",
-});