@fun-land/fun-web 0.4.0 → 0.5.0

package/README.md

@@ -36,6 +36,7 @@ import {
   mount,
   bindProperty,
   on,
+  enhance,
   type Component,
   type FunState,
 } from "@fun-land/fun-web";
@@ -45,11 +46,11 @@ const Counter: Component<{state: FunState<number>}> = (signal, {state}) => {
   // Component runs once - no re-rendering on state changes
   const button = h("button", {}, `Count: ${state.get()}`);
 
-  // bindProperty subscribes to the past state and updates named property
-  bindProperty(button, "textContent", state, signal);
+  // bindProperty subscribes to the state and updates named property
+  enhance(button, bindProperty("textContent", state, signal));
 
   // Event handlers never go stale (component doesn't re-run)
-  on(button, "click", () => state.mod((n) => n + 1), signal);
+  enhance(button, on("click", () => state.mod((n) => n + 1), signal));
 
   return button;
 };
@@ -72,8 +73,8 @@ const Counter: Component<{ count: FunState<number> }> = (signal, props) => {
   const button = h("button", {}, "Increment");
 
   // This subscription handles updates, not re-rendering
-  bindProperty(display, "textContent", props.count, signal);
-  on(button, "click", () => props.count.mod(n => n + 1), signal);
+  enhance(display, bindProperty("textContent", props.count, signal));
+  enhance(button, on("click", () => props.count.mod(n => n + 1), signal));
 
   return h("div", {}, [display, button]);
   // Component function exits, but subscriptions keep working
@@ -120,8 +121,8 @@ const FunWebCounter: Component<{ count: FunState<number> }> = (signal, props) =>
   const button = h("button", {}, "+");
 
   // No useCallback needed - this closure never goes stale
-  on(button, "click", () => props.count.mod(n => n + 1), signal);
-  bindProperty(display, "textContent", props.count, signal);
+  enhance(button, on("click", () => props.count.mod(n => n + 1), signal));
+  enhance(display, bindProperty("textContent", props.count, signal));
 
   return h("div", {}, [display, button]);
 };
@@ -191,7 +192,7 @@ const Dashboard: Component<{
 const nameEl = h("div");
 const nameState: FunState<string> = state.prop("user").prop("name");
 
-bindProperty(nameEl, "textContent", nameState, signal);
+enhance(nameEl, bindProperty("textContent", nameState, signal));
 // nameEl.textContent stays in sync with nameState
 ```
 
@@ -199,24 +200,18 @@ bindProperty(nameEl, "textContent", nameState, signal);
 
 ```typescript
 const button = h("button", {}, "Click me");
-on(button, "click", (e: MouseEvent & { currentTarget: HTMLButtonElement }) => {
+enhance(button, on("click", (e: MouseEvent & { currentTarget: HTMLButtonElement }) => {
   console.log(e.currentTarget.textContent);
-}, signal);
+}, signal));
 ```
 
 **Chain for two-way bindings:**
 
 ```typescript
-const input = on(
-  bindProperty(
-    h("input", { type: "text" }),
-    "value",
-    state.prop("name"),
-    signal
-  ),
-  "input",
-  (e) => state.prop("name").set(e.currentTarget.value),
-  signal
+const input = enhance(
+  h("input", { type: "text" }),
+  bindProperty("value", state.prop("name"), signal),
+  on("input", (e) => state.prop("name").set(e.currentTarget.value), signal)
 );
 ```
 
@@ -240,8 +235,8 @@ const MyComponent: Component<{ state: FunState<State> }> = (signal, {state}) =>
   const button = h("button");
 
   // All three clean up when signal aborts
-  bindProperty(display, "textContent", state.prop("count"), signal);
-  on(button, "click", () => state.mod(increment), signal);
+  enhance(display, bindProperty("textContent", state.prop("count"), signal));
+  enhance(button, on("click", () => state.mod(increment), signal));
   state.watch(signal, (s) => console.log("Changed:", s));
 
   return h("div", {}, [display, button]);
@@ -275,7 +270,7 @@ const baz = state.focus(bazFromState).get()
 
 ```typescript
 // ✅ Good
-bindProperty(element, "textContent", state.prop("count"), signal);
+enhance(element, bindProperty("textContent", state.prop("count"), signal));
 
 // ❌ Avoid (when bindProperty works)
 state.prop("count").watch(signal, (count) => {
@@ -287,9 +282,9 @@ state.prop("count").watch(signal, (count) => {
 
 ```typescript
 // ✅ Good - types inferred
-on(button, "click", (e) => {
+enhance(button, on("click", (e) => {
   e.currentTarget.disabled = true; // TypeScript knows it's HTMLButtonElement
-}, signal);
+}, signal));
 
 // ❌ Avoid - loses type information
 button.addEventListener("click", (e) => {
@@ -341,102 +336,93 @@ const div = h("div", { id: "app" }, [
 - Everything else → property assignment
 
 #### bindProperty
-```ts
-<E extends Element, K extends keyof E>(
-  el: E,
-  key: K,
-  fs: FunState<E[K]>,
-  signal: AbortSignal
-): E
-```
 
-Bind element property to state. Returns element for chaining.
+Bind element property to state. Returns `Enhancer`.
 
 ```typescript
-const input: HTMLInputElement = h("input");
-bindProperty(input, "value", state.prop("name"), signal);
+const input = enhance(
+  h("input"),
+  bindProperty("value", state.prop("name"), signal)
+);
 // input.value syncs with state.name
 ```
 
 #### on
-```ts
-<E extends Element, K extends keyof HTMLElementEventMap>(
-  el: E,
-  type: K,
-  handler: (ev: HTMLElementEventMap[K] & { currentTarget: E }) => void,
-  signal: AbortSignal
-): E
-```
 
-Add type-safe event listener. Returns element for chaining.
+Add type-safe event listener. Returns `Enhancer`.
 
 ```typescript
-on(h("button"), "click", (e) => {
-  // e.currentTarget is typed as HTMLButtonElement
-  e.currentTarget.disabled = true;
-}, signal);
+const button = enhance(
+  h("button"),
+  on("click", (e) => {
+    e.currentTarget.disabled = true;
+  }, signal)
+);
 ```
 
-#### keyedChildren
-```ts
-<T extends { key: string }>(
-  parent: Element,
-  signal: AbortSignal,
-  list: FunState<T[]>,
-  renderRow: (row: {
-    signal: AbortSignal;
-    state: FunState<T>;
-    remove: () => void;
-  }) => Element
-): KeyedChildren<T>
-```
+#### bindListChildren
 
-Render and reconcile keyed lists efficiently. Each row gets its own AbortSignal for cleanup and a focused state.
+Render and reconcile keyed lists efficiently. Each row gets its own AbortSignal for cleanup and a focused state. Returns `Enhancer`.
 
 ```typescript
+import { Acc } from "@fun-land/accessor";
+
 interface Todo {
-  key: string;
+  id: string;
   label: string;
   done: boolean;
 }
 
 const todos: FunState<Todo[]> = funState([
-  { key: "a", label: "First", done: false }
+  { id: "a", label: "First", done: false }
 ]);
 
-keyedChildren(h("ul"), signal, todos, (row) => {
-  const li = h("li");
-
-  // row.state is a focused FunState<Todo> for this item
-  bindProperty(li, "textContent", row.state.prop("label"), row.signal);
-
-  // row.remove() removes this item from the list
-  const deleteBtn = h("button", { textContent: "Delete" });
-  on(deleteBtn, "click", row.remove, row.signal);
-
-  li.appendChild(deleteBtn);
-  return li;
-});
+const list = enhance(
+  h("ul"),
+  bindListChildren({
+    signal,
+    state: todos,
+    key: Acc<Todo>().prop("id"),
+    row: ({ signal, state, remove }) => {
+      const li = h("li");
+
+      // state is a focused FunState<Todo> for this item
+      enhance(li, bindProperty("textContent", state.prop("label"), signal));
+
+      // remove() removes this item from the list
+      const deleteBtn = h("button", { textContent: "Delete" });
+      enhance(deleteBtn, on("click", remove, signal));
+
+      li.appendChild(deleteBtn);
+      return li;
+    }
+  })
+);
 ```
 
 #### renderWhen
 ```ts
-<Props>(
-  state: FunState<boolean>,
-  comp: (signal: AbortSignal, props: Props) => Element,
-  props: Props,
-  signal: AbortSignal
-): Element
+function renderWhen<State, Props>(options: {
+  state: FunState<State>;
+  predicate?: (value: State) => boolean;
+  component: Component<Props>;
+  props: Props;
+  signal: AbortSignal;
+}): Element
 ```
 
-Conditionally render a component based on a boolean state. Returns a container element that mounts/unmounts the component as the state changes.
+Conditionally render a component based on state and an optional predicate. Returns a container element that mounts/unmounts the component as the condition changes.
 
 **Key features:**
-- Component is mounted when state becomes `true`, unmounted when `false`
+- Component is mounted when condition is `true`, unmounted when `false`
+- With boolean state, component mounts when state is `true`
+- With predicate, component mounts when `predicate(state)` returns `true`
 - Each mount gets its own AbortController for proper cleanup
 - Container uses `display: contents` to not affect layout
 - Multiple toggles create fresh component instances each time
 
+**Example with boolean state:**
+
 ```typescript
 const ShowDetails: Component<{ user: User }> = (signal, { user }) => {
   return h("div", { className: "details" }, [
@@ -450,22 +436,47 @@ const App: Component = (signal) => {
   const userState = funState({ email: "alice@example.com", joinDate: "2024" });
 
   const toggleBtn = h("button", { textContent: "Toggle Details" });
-  on(toggleBtn, "click", () => {
+  enhance(toggleBtn, on("click", () => {
     showDetailsState.mod(show => !show);
-  }, signal);
+  }, signal));
 
   // Details component mounts/unmounts based on showDetailsState
-  const detailsEl = renderWhen(
-    showDetailsState,
-    ShowDetails,
-    { user: userState.get() },
+  const detailsEl = renderWhen({
+    state: showDetailsState,
+    component: ShowDetails,
+    props: { user: userState.get() },
     signal
-  );
+  });
 
   return h("div", {}, [toggleBtn, detailsEl]);
 };
 ```
 
+**Example with predicate:**
+
+```typescript
+enum Status { Loading, Success, Error }
+
+const SuccessMessage: Component<{ message: string }> = (signal, { message }) => {
+  return h("div", { className: "success" }, message);
+};
+
+const App: Component = (signal) => {
+  const statusState = funState(Status.Loading);
+
+  // Only render SuccessMessage when status is Success
+  const successEl = renderWhen({
+    state: statusState,
+    predicate: (status) => status === Status.Success,
+    component: SuccessMessage,
+    props: { message: "Operation completed!" },
+    signal
+  });
+
+  return h("div", {}, [successEl]);
+};
+```
+
 **When to use:**
 - Conditionally showing/hiding expensive components (better than CSS `display: none`)
 - Mounting components that need full cleanup when hidden

package/dist/esm/src/dom.d.ts

@@ -1,6 +1,7 @@
 /** DOM utilities for functional element creation and manipulation */
 import { type FunState } from "@fun-land/fun-state";
-import type { ElementChild } from "./types";
+import type { Component, ElementChild } from "./types";
+import { Accessor } from "@fun-land/accessor";
 export type Enhancer<El extends Element> = (element: El) => El;
 /**
  * Create an HTML element with attributes and children
@@ -17,28 +18,36 @@ export type Enhancer<El extends Element> = (element: El) => El;
 export declare const h: <Tag extends keyof HTMLElementTagNameMap>(tag: Tag, attrs?: Record<string, any> | null, children?: ElementChild | ElementChild[]) => HTMLElementTagNameMap[Tag];
 /**
  * Set text content of an element (returns element for chaining)
+ * @returns {Enhancer}
  */
 export declare const text: (content: string | number) => <El extends Element>(el: El) => El;
 /**
  * Set an attribute on an element (returns element for chaining)
+ * @returns {Enhancer}
  */
 export declare const attr: (name: string, value: string) => <El extends Element>(el: El) => El;
 /**
  * Set multiple attributes on an element (returns element for chaining)
  */
 export declare const attrs: (obj: Record<string, string>) => <El extends Element>(el: El) => El;
-export declare function bindProperty<E extends Element, K extends keyof E>(el: E, key: K, fs: FunState<E[K]>, signal: AbortSignal): E;
-export declare const bindPropertyTo: <E extends Element, K extends keyof E & string>(key: K, state: FunState<E[K]>, signal: AbortSignal) => (el: E) => E;
+/**
+ * update property `key` of element when state updates
+ * @returns {Enhancer}
+ */
+export declare const bindProperty: <E extends Element, K extends keyof E & string>(key: K, state: FunState<E[K]>, signal: AbortSignal) => (el: E) => E;
 /**
  * Add CSS classes to an element (returns element for chaining)
+ * @returns {Enhancer}
  */
 export declare const addClass: (...classes: string[]) => <El extends Element>(el: El) => El;
 /**
  * Remove CSS classes from an element (returns element for chaining)
+ * @returns {Enhancer}
  */
 export declare const removeClass: (...classes: string[]) => <El extends Element>(el: El) => El;
 /**
  * Toggle a CSS class on an element (returns element for chaining)
+ * @returns {Enhancer}
  */
 export declare const toggleClass: (className: string, force?: boolean) => (el: Element) => Element;
 /**
@@ -49,24 +58,15 @@ export declare const append: (...children: Element[]) => <El extends Element>(el
 /**
  * Add event listener with required AbortSignal (returns element for chaining)
  * Signal is required to prevent forgetting cleanup
+ * @returns {Enhancer}
  */
-export declare const on: <E extends Element, K extends keyof HTMLElementEventMap>(el: E, type: K, handler: (ev: HTMLElementEventMap[K] & {
-    currentTarget: E;
-}) => void, signal: AbortSignal) => E;
-/** Enhancer version of `on()` */
-export declare const onTo: <E extends Element, K extends keyof HTMLElementEventMap>(type: K, handler: (ev: HTMLElementEventMap[K] & {
+export declare const on: <E extends Element, K extends keyof GlobalEventHandlersEventMap>(type: K, handler: (ev: GlobalEventHandlersEventMap[K] & {
     currentTarget: E;
 }) => void, signal: AbortSignal) => (el: E) => E;
 /**
  * Apply enhancers to an HTMLElement.
  */
 export declare const enhance: <El extends Element>(x: El, ...fns: Array<Enhancer<El>>) => El;
-/**
- *
- */
-type Keyed = {
-    key: string;
-};
 export type KeyedChildren = {
     /** Reconcile DOM children to match current list state */
     reconcile: () => void;
@@ -74,19 +74,19 @@ export type KeyedChildren = {
     dispose: () => void;
 };
 /**
- * Keep a DOM container's children in sync with a FunState<Array<T>> using stable `t.key`.
- *
- * - No VDOM
- * - Preserves existing row elements across updates
- * - Creates one AbortController per row (cleaned up on removal or parent abort)
- * - Reorders by DOM moves (appendChild)
- * - Only remounts if order changes
+ * Keep an element's children in sync with a FunState<T[]> by stable identity.
+ * Cleanup is driven by `signal` abort (no handle returned).
  */
-export declare function keyedChildren<T extends Keyed>(parent: Element, signal: AbortSignal, list: FunState<T[]>, renderRow: (row: {
+export declare const bindListChildren: <T>(options: {
     signal: AbortSignal;
-    state: FunState<T>;
-    remove: () => void;
-}) => Element): KeyedChildren;
+    state: FunState<T[]>;
+    key: Accessor<T, string>;
+    row: (args: {
+        signal: AbortSignal;
+        state: FunState<T>;
+        remove: () => void;
+    }) => Element;
+}) => <El extends Element>(parent: El) => El;
 /**
  * Conditionally render a component based on state and an optional predicate.
  * Returns a container element that mounts/unmounts the component as the condition changes.
@@ -116,10 +116,9 @@ export declare function keyedChildren<T extends Keyed>(parent: Element, signal:
 export declare function renderWhen<State, Props>(options: {
     state: FunState<State>;
     predicate?: (value: State) => boolean;
-    component: (signal: AbortSignal, props: Props) => Element;
+    component: Component<Props>;
     props: Props;
     signal: AbortSignal;
 }): Element;
 export declare const $: <T extends Element>(selector: string) => T | undefined;
 export declare const $$: <T extends Element>(selector: string) => T[];
-export {};

package/dist/esm/src/dom.js

@@ -1,4 +1,3 @@
-import { filter } from "@fun-land/accessor";
 /**
  * Create an HTML element with attributes and children
  *
@@ -39,16 +38,17 @@ attrs, children) => {
     }
     // Append children
     if (children != null) {
-        appendChildren(element, children);
+        appendChildren(children)(element);
     }
     return element;
 };
 /**
  * Append children to an element, flattening arrays and converting primitives to text nodes
+ * @returns {Enhancer}
  */
-const appendChildren = (parent, children) => {
+const appendChildren = (children) => (parent) => {
     if (Array.isArray(children)) {
-        children.forEach((child) => appendChildren(parent, child));
+        children.forEach((child) => appendChildren(child)(parent));
     }
     else if (children != null) {
         if (typeof children === "string" || typeof children === "number") {
@@ -58,23 +58,24 @@ const appendChildren = (parent, children) => {
             parent.appendChild(children);
         }
     }
+    return parent;
 };
 /**
  * Set text content of an element (returns element for chaining)
+ * @returns {Enhancer}
  */
 export const text = (content) => (el) => {
     el.textContent = String(content);
     return el;
 };
-;
 /**
  * Set an attribute on an element (returns element for chaining)
+ * @returns {Enhancer}
  */
 export const attr = (name, value) => (el) => {
     el.setAttribute(name, value);
     return el;
 };
-;
 /**
  * Set multiple attributes on an element (returns element for chaining)
  */
@@ -84,35 +85,38 @@ export const attrs = (obj) => (el) => {
     });
     return el;
 };
-;
-export function bindProperty(el, key, fs, signal) {
+/**
+ * update property `key` of element when state updates
+ * @returns {Enhancer}
+ */
+export const bindProperty = (key, state, signal) => (el) => {
     // initial sync
-    el[key] = fs.get();
+    el[key] = state.get();
     // reactive sync
-    fs.watch(signal, (v) => {
+    state.watch(signal, (v) => {
         el[key] = v;
     });
     return el;
-}
-export const bindPropertyTo = (key, state, signal) => (el) => bindProperty(el, key, state, signal);
+};
 /**
  * Add CSS classes to an element (returns element for chaining)
+ * @returns {Enhancer}
  */
 export const addClass = (...classes) => (el) => {
     el.classList.add(...classes);
     return el;
 };
-;
 /**
  * Remove CSS classes from an element (returns element for chaining)
+ * @returns {Enhancer}
  */
 export const removeClass = (...classes) => (el) => {
     el.classList.remove(...classes);
     return el;
 };
-;
 /**
  * Toggle a CSS class on an element (returns element for chaining)
+ * @returns {Enhancer}
  */
 export const toggleClass = (className, force) => (el) => {
     el.classList.toggle(className, force);
@@ -126,37 +130,52 @@ export const append = (...children) => (el) => {
     children.forEach((child) => el.appendChild(child));
     return el;
 };
-;
 /**
  * Add event listener with required AbortSignal (returns element for chaining)
  * Signal is required to prevent forgetting cleanup
+ * @returns {Enhancer}
  */
-export const on = (el, type, handler, signal) => {
+export const on = (type, handler, signal) => (el) => {
     el.addEventListener(type, handler, { signal });
     return el;
 };
-/** Enhancer version of `on()` */
-export const onTo = (type, handler, signal) => (el) => on(el, type, handler, signal);
 /**
  * Apply enhancers to an HTMLElement.
  */
 export const enhance = (x, ...fns) => fns.reduce((acc, fn) => fn(acc), x);
+const keyOf = (keyAcc, item) => {
+    const k = keyAcc.query(item)[0];
+    if (k == null)
+        throw new Error("bindListChildren: key accessor returned no value");
+    return k;
+};
+const byKey = (keyAcc, key) => ({
+    query: (xs) => {
+        const hit = xs.find((t) => keyOf(keyAcc, t) === key);
+        return hit ? [hit] : [];
+    },
+    mod: (f) => (xs) => {
+        let found = false;
+        return xs.map((t) => {
+            if (keyOf(keyAcc, t) !== key)
+                return t;
+            if (found)
+                throw new Error(`bindListChildren: duplicate key "${key}"`);
+            found = true;
+            return f(t);
+        });
+    },
+});
 /**
- * Keep a DOM container's children in sync with a FunState<Array<T>> using stable `t.key`.
- *
- * - No VDOM
- * - Preserves existing row elements across updates
- * - Creates one AbortController per row (cleaned up on removal or parent abort)
- * - Reorders by DOM moves (appendChild)
- * - Only remounts if order changes
+ * Keep an element's children in sync with a FunState<T[]> by stable identity.
+ * Cleanup is driven by `signal` abort (no handle returned).
  */
-export function keyedChildren(parent, signal, list, renderRow) {
+export const bindListChildren = (options) => (parent) => {
+    const { signal, state: list, key: keyAcc, row: renderRow } = options;
     const rows = new Map();
     const dispose = () => {
         for (const row of rows.values()) {
-            // Abort first so listeners/subscriptions clean up
             row.ctrl.abort();
-            // Remove from DOM (safe even if already removed)
             row.el.remove();
         }
         rows.clear();
@@ -166,13 +185,13 @@ export function keyedChildren(parent, signal, list, renderRow) {
         const nextKeys = [];
         const seen = new Set();
         for (const it of items) {
-            const k = it.key;
+            const k = keyOf(keyAcc, it);
             if (seen.has(k))
-                throw new Error(`keyedChildren: duplicate key "${k}"`);
+                throw new Error(`bindListChildren: duplicate key "${k}"`);
             seen.add(k);
             nextKeys.push(k);
         }
-        // Remove missing
+        // remove missing
         for (const [k, row] of rows) {
             if (!seen.has(k)) {
                 row.ctrl.abort();
@@ -180,38 +199,34 @@ export function keyedChildren(parent, signal, list, renderRow) {
                 rows.delete(k);
             }
         }
-        // Ensure present
+        // ensure present
         for (const k of nextKeys) {
             if (!rows.has(k)) {
                 const ctrl = new AbortController();
-                const itemState = list.focus(filter((t) => t.key === k));
+                const itemState = list.focus(byKey(keyAcc, k));
                 const el = renderRow({
                     signal: ctrl.signal,
                     state: itemState,
-                    remove: () => list.mod((list) => list.filter((t) => t.key !== k)),
+                    remove: () => list.mod((xs) => xs.filter((t) => keyOf(keyAcc, t) !== k)),
                 });
-                rows.set(k, { key: k, el, ctrl });
+                rows.set(k, { el, ctrl });
             }
         }
-        // Reorder with minimal DOM movement (prevents focus loss)
+        // reorder with minimal DOM moves
         const children = parent.children; // live
         for (let i = 0; i < nextKeys.length; i++) {
             const k = nextKeys[i];
             const row = rows.get(k);
             const currentAtI = children[i];
-            if (currentAtI !== row.el) {
+            if (currentAtI !== row.el)
                 parent.insertBefore(row.el, currentAtI !== null && currentAtI !== void 0 ? currentAtI : null);
-            }
         }
     };
-    // Reconcile whenever the list changes; `subscribe` will unsubscribe on abort (per your fix).
     list.watch(signal, reconcile);
-    // Ensure all children clean up when parent aborts
     signal.addEventListener("abort", dispose, { once: true });
-    // Initial mount
     reconcile();
-    return { reconcile, dispose };
-}
+    return parent;
+};
 /**
  * Conditionally render a component based on state and an optional predicate.
  * Returns a container element that mounts/unmounts the component as the condition changes.
@@ -239,7 +254,7 @@ export function keyedChildren(parent, signal, list, renderRow) {
  * });
  */
 export function renderWhen(options) {
-    const { state, predicate = (x) => x, component, props, signal } = options;
+    const { state, predicate = (x) => x, component, props, signal, } = options;
     const container = document.createElement("span");
     container.style.display = "contents";
     let childCtrl = null;