@fun-land/fun-web 0.5.0 → 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# @fun-land/fun-web
+
+## 1.0.0
+
+### Minor Changes
+
+- 8f57a13: Add derive and mapRead to fun-state, add bindClass and hx to fun-web
+
+### Patch Changes
+
+- Updated dependencies [8f57a13]
+  - @fun-land/fun-state@9.2.0

package/README.md

@@ -31,28 +31,24 @@ pnpm add @fun-land/fun-web @fun-land/accessor
 
 ```typescript
 import {
-  h,
+  hx,
   funState,
   mount,
-  bindProperty,
-  on,
-  enhance,
   type Component,
   type FunState,
+  type FunRead,
 } from "@fun-land/fun-web";
 
 
 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 state and updates named property
-  enhance(button, bindProperty("textContent", state, signal));
-
-  // Event handlers never go stale (component doesn't re-run)
-  enhance(button, on("click", () => state.mod((n) => n + 1), signal));
-
-  return button;
+  return hx("button", {
+    signal,
+    // bind syncs the button text with state
+    bind: { textContent: state },
+    // Event handlers never go stale (component doesn't re-run)
+    on: { click: () => state.mod((n) => n + 1) },
+  });
 };
 
 // Create reactive state and mount 
@@ -69,12 +65,16 @@ const mounted = mount(Counter, { state: funState(0) }, document.body);
 const Counter: Component<{ count: FunState<number> }> = (signal, props) => {
   console.log("Component runs once");
 
-  const display = h("div");
-  const button = h("button", {}, "Increment");
+  const display = hx("div", {
+    signal,
+    bind: { textContent: props.count },
+  });
 
-  // This subscription handles updates, not re-rendering
-  enhance(display, bindProperty("textContent", props.count, signal));
-  enhance(button, on("click", () => props.count.mod(n => n + 1), signal));
+  const button = hx("button", {
+    signal,
+    props: { textContent: "Increment" },
+    on: { click: () => props.count.mod(n => n + 1) },
+  });
 
   return h("div", {}, [display, button]);
   // Component function exits, but subscriptions keep working
@@ -117,12 +117,17 @@ function ReactCounter() {
 const FunWebCounter: Component<{ count: FunState<number> }> = (signal, props) => {
   console.log("Mounting!"); // Logs once, never again
 
-  const display = h("div");
-  const button = h("button", {}, "+");
+  const display = hx("div", {
+    signal,
+    bind: { textContent: props.count },
+  });
 
-  // No useCallback needed - this closure never goes stale
-  enhance(button, on("click", () => props.count.mod(n => n + 1), signal));
-  enhance(display, bindProperty("textContent", props.count, signal));
+  const button = hx("button", {
+    signal,
+    props: { textContent: "+" },
+    // No useCallback needed - this closure never goes stale
+    on: { click: () => props.count.mod(n => n + 1) },
+  });
 
   return h("div", {}, [display, button]);
 };
@@ -149,6 +154,27 @@ userState.prop("name").watch(signal, (name) => {
 });
 ```
 
+**FunRead** - Read-only reactive values returned by `mapRead` and `derive`:
+
+```typescript
+import { mapRead, derive } from "@fun-land/fun-state";
+
+// Transform single value
+const count = funState(5);
+const doubled = mapRead(count, n => n * 2);
+
+// Combine multiple values
+const firstName = funState("Alice");
+const lastName = funState("Smith");
+const fullName = derive(firstName, lastName, (f, l) => `${f} ${l}`);
+
+// Use with bindings (accepts FunRead)
+const display = hx("div", {
+  signal,
+  bind: { textContent: fullName },
+});
+```
+
 ### Component Signature
 
 Components are functions that receive an AbortSignal and props:
@@ -186,33 +212,42 @@ const Dashboard: Component<{
 
 ### Reactivity Patterns
 
-**Use `bindProperty` for simple one-way bindings:**
+**One-way binding with `hx`:**
 
 ```typescript
-const nameEl = h("div");
 const nameState: FunState<string> = state.prop("user").prop("name");
 
-enhance(nameEl, bindProperty("textContent", nameState, signal));
+const nameEl = hx("div", {
+  signal,
+  bind: { textContent: nameState },
+});
 // nameEl.textContent stays in sync with nameState
 ```
 
-**Use `on` for events:**
+**Two-way binding with `hx`:**
 
 ```typescript
-const button = h("button", {}, "Click me");
-enhance(button, on("click", (e: MouseEvent & { currentTarget: HTMLButtonElement }) => {
-  console.log(e.currentTarget.textContent);
-}, signal));
+const input = hx("input", {
+  signal,
+  props: { type: "text" },
+  bind: { value: state.prop("name") },
+  on: { input: (e) => state.prop("name").set(e.currentTarget.value) },
+});
 ```
 
-**Chain for two-way bindings:**
+**Event handlers with `hx`:**
 
 ```typescript
-const input = enhance(
-  h("input", { type: "text" }),
-  bindProperty("value", state.prop("name"), signal),
-  on("input", (e) => state.prop("name").set(e.currentTarget.value), signal)
-);
+const button = hx("button", {
+  signal,
+  props: { textContent: "Click me" },
+  on: {
+    click: (e) => {
+      console.log(e.currentTarget.textContent);
+      e.currentTarget.disabled = true; // type-safe!
+    }
+  },
+});
 ```
 
 **Use `.watch()` for complex logic:**
@@ -225,6 +260,17 @@ state.watch(signal, (s) => {
 });
 ```
 
+**Using enhancers (alternative to `hx`):**
+
+```typescript
+// If you prefer functional composition
+const input = enhance(
+  h("input", { type: "text" }),
+  bindProperty("value", state.prop("name"), signal),
+  on("input", (e) => state.prop("name").set(e.currentTarget.value), signal)
+);
+```
+
 ### Cleanup with AbortSignal
 
 All subscriptions and event listeners require an AbortSignal. When the signal aborts, everything cleans up automatically:
@@ -253,7 +299,7 @@ For the most part you won't have to worry about the abort signal if you use the
 **Don't have one big app state**
 This isn't redux. There's little reason to create giant state objects. Create state near the leaves and hoist it when you need to. That said
 
-**You can have more that one state**
+**You can have more than one state**
 It's just a value. If having one state manage multiple properties works then great but if you want to have several that's fine too.
 
 **Deep chains of .prop() are a smell**
@@ -266,37 +312,49 @@ const bazFromState = Acc<MyState>().prop('foo').prop('bar').prop('baz')
 const baz = state.focus(bazFromState).get()
 ```
 
-**Prefer helpers over manual subscriptions:**
+**Using .get() in component scope is a smell**
+State is for when you want components to respond to state changes as such you should be using it with bindProperty or state.watch or inside event handlers. There are many cases for .get() but if it's the first thing you reach for you're probably gonna be confused that the UI isn't updating. 
+
+**Prefer `hx` for reactive elements:**
 
 ```typescript
-// ✅ Good
-enhance(element, bindProperty("textContent", state.prop("count"), signal));
+// ✅ Good - declarative and type-safe
+const input = hx("input", {
+  signal,
+  props: { type: "text" },
+  bind: { value: state.prop("name") },
+  on: { input: (e) => state.prop("name").set(e.currentTarget.value) },
+});
+
+// ✅ Also good - functional composition with enhancers
+const input = enhance(
+  h("input", { type: "text" }),
+  bindProperty("value", state.prop("name"), signal),
+  on("input", (e) => state.prop("name").set(e.currentTarget.value), signal)
+);
 
-// ❌ Avoid (when bindProperty works)
-state.prop("count").watch(signal, (count) => {
-  element.textContent = String(count);
+// ❌ Avoid manual subscriptions when `bind` works
+const input = h("input", { type: "text" });
+state.prop("name").watch(signal, (name) => {
+  input.value = name; // Just use bind!
 });
 ```
 
-**Use `on()` for type safety:**
+**Don't bind events in `h()` props:**
 
 ```typescript
-// ✅ Good - types inferred
-enhance(button, on("click", (e) => {
-  e.currentTarget.disabled = true; // TypeScript knows it's HTMLButtonElement
-}, signal));
-
-// ❌ Avoid - loses type information
-button.addEventListener("click", (e) => {
-  (e.currentTarget as HTMLButtonElement).disabled = true;
-}); // ❌ Forgot {signal} !
+// ✅ Good - uses hx with type-safe events
+const button = hx("button", {
+  signal,
+  on: { click: (e) => e.currentTarget.disabled = true },
+});
 
-// ❌ Avoid binding events in props
-h('button', {onclick: (e) => {
-  // ❌ type info lost!
-  (e.currentTarget as HTMLButtonElement).disabled = true;
-  // ❌ event handler not cleaned up!
-}})
+// ❌ Avoid - h() event props aren't cleaned up and lose types
+const button = h("button", {
+  onclick: (e) => {
+    (e.currentTarget as HTMLButtonElement).disabled = true; // needs cast
+  }, // ❌ event handler not cleaned up!
+});
 ```
 
 **Manual subscriptions for complex updates:**
@@ -319,9 +377,30 @@ state.watch(signal, (s) => {
 
 ### DOM Utilities
 
+#### `hx` (recommended)
+
+Create elements with structured props, attrs, event handlers, and reactive bindings. More complex but provides better type safety and ergonomics than `h` + enhancers.
+
+```typescript
+const input = hx("input", {
+  signal,
+  props: { type: "text", placeholder: "Enter name" },
+  attrs: { "data-test": "name-input" },
+  bind: { value: nameState },
+  on: { input: (e) => nameState.set(e.currentTarget.value) },
+});
+```
+
+**Parameters:**
+- `props` - Element properties (typed per element, writable properties only)
+- `attrs` - HTML attributes (data-*, aria-*, etc.)
+- `on` - Event handlers (type-safe, with inferred `currentTarget`)
+- `bind` - Reactive bindings (properties sync with FunState)
+- `signal` - **Required** AbortSignal for cleanup
+
 #### `h`
 
-Declaratively create an HTML Element with properties and children.
+Create HTML elements declaratively. Consider using `hx` if you want to add event handlers or respond to state changes.
 
 ```typescript
 const div = h("div", { id: "app" }, [
@@ -332,12 +411,12 @@ const div = h("div", { id: "app" }, [
 
 **Attribute conventions:**
 - Dashed properties (`data-*`, `aria-*`) → `setAttribute()`
-- Don't event bind with properties, use `on()`
+- Properties starting with `on` → event listeners (⚠️ not cleaned up, use `hx` or `on()` enhancer)
 - Everything else → property assignment
 
 #### bindProperty
 
-Bind element property to state. Returns `Enhancer`.
+Bind element property to state. Accepts `FunRead` (including `FunState`, `map`, `derive` results). Returns `Enhancer`. Consider using `hx` with `bind` for better ergonomics.
 
 ```typescript
 const input = enhance(
@@ -345,11 +424,24 @@ const input = enhance(
   bindProperty("value", state.prop("name"), signal)
 );
 // input.value syncs with state.name
+
+// Works with derived values
+const formatted = mapRead(state.prop("price"), p => `$${p.toFixed(2)}`);
+const display = enhance(
+  h("div"),
+  bindProperty("textContent", formatted, signal)
+);
+
+// Equivalent with hx:
+const input = hx("input", {
+  signal,
+  bind: { value: state.prop("name") },
+});
 ```
 
 #### on
 
-Add type-safe event listener. Returns `Enhancer`.
+Add type-safe event listener. Returns `Enhancer`. Consider using `hx` with `on` for better ergonomics.
 
 ```typescript
 const button = enhance(
@@ -358,11 +450,21 @@ const button = enhance(
     e.currentTarget.disabled = true;
   }, signal)
 );
+
+// Equivalent with hx:
+const button = hx("button", {
+  signal,
+  on: {
+    click: (e) => {
+      e.currentTarget.disabled = true;
+    }
+  },
+});
 ```
 
 #### bindListChildren
 
-Render and reconcile keyed lists efficiently. Each row gets its own AbortSignal for cleanup and a focused state. Returns `Enhancer`.
+Render a list of items from a state array. Each row gets its own AbortSignal for cleanup and a focused state. Returns `Enhancer`.
 
 ```typescript
 import { Acc } from "@fun-land/accessor";
@@ -382,7 +484,7 @@ const list = enhance(
   bindListChildren({
     signal,
     state: todos,
-    key: Acc<Todo>().prop("id"),
+    key: prop<Todo>()("id"), // key is an accessor that targets the unique string value in your array items
     row: ({ signal, state, remove }) => {
       const li = h("li");
 
@@ -403,7 +505,7 @@ const list = enhance(
 #### renderWhen
 ```ts
 function renderWhen<State, Props>(options: {
-  state: FunState<State>;
+  state: FunRead<State>;
   predicate?: (value: State) => boolean;
   component: Component<Props>;
   props: Props;
@@ -411,7 +513,7 @@ function renderWhen<State, Props>(options: {
 }): Element
 ```
 
-Conditionally render a component based on state and an optional predicate. Returns a container element that mounts/unmounts the component as the condition changes.
+Conditionally render a component based on state and an optional predicate. Accepts `FunRead` (including `FunState`, `map`, `derive` results). Returns a container element that mounts/unmounts the component as the condition changes.
 
 **Key features:**
 - Component is mounted when condition is `true`, unmounted when `false`
@@ -435,10 +537,11 @@ const App: Component = (signal) => {
   const showDetailsState = funState(false);
   const userState = funState({ email: "alice@example.com", joinDate: "2024" });
 
-  const toggleBtn = h("button", { textContent: "Toggle Details" });
-  enhance(toggleBtn, on("click", () => {
-    showDetailsState.mod(show => !show);
-  }, signal));
+  const toggleBtn = hx("button", {
+    signal,
+    props: { textContent: "Toggle Details" },
+    on: { click: () => showDetailsState.mod(show => !show) },
+  });
 
   // Details component mounts/unmounts based on showDetailsState
   const detailsEl = renderWhen({
@@ -495,38 +598,30 @@ showState.watch(signal, (show) => {
 });
 ```
 
-#### $ and $$ - DOM Query Utilities
-
-Convenient shortcuts for `querySelector` and `querySelectorAll` with better TypeScript support.
+#### querySelectorAll
 
-**`$<T extends Element>(selector: string): T | undefined`**
-
-Query a single element. Returns `undefined` instead of `null` if not found.
+Query multiple elements. Returns a real Array (not NodeList) for better ergonomics.
 
 ```typescript
-const button = $<HTMLButtonElement>("#submit-btn");
-if (button) {
-  button.disabled = true;
-}
-
-const input = $<HTMLInputElement>(".name-input");
+const items = querySelectorAll<HTMLDivElement>(".item").map(addClass("active"));
 ```
 
-**`$$<T extends Element>(selector: string): T[]`**
+#### enhance
 
-Query multiple elements. Returns a real Array (not NodeList) for better ergonomics.
+Apply multiple enhancers to an element. Useful with `h()` and the enhancer utilities below.
 
 ```typescript
-const items = $$<HTMLDivElement>(".item");
-items.forEach(item => item.classList.add("active"));
-
-// Array methods work directly
-const texts = $$(".label").map(el => el.textContent);
+const input = enhance(
+  h("input", { type: "text" }),
+  addClass("form-control"),
+  bindProperty("value", nameState, signal),
+  on("input", (e) => nameState.set(e.currentTarget.value), signal)
+);
 ```
 
 #### Other utilities
 
-All return the element for chaining:
+All return the element for chaining (used with `enhance`):
 
 ```typescript
 text: (content: string | number) => (el: Element) => Element
@@ -536,8 +631,6 @@ addClass: (...classes: string[]) => (el: Element) => Element
 removeClass: (...classes: string[]) => (el: Element) => Element
 toggleClass: (className: string, force?: boolean) => (el: Element) => Element
 append: (...children: Element[]) => (el: Element) => Element
-// pipe a value through a series of endomorphisms
-pipeAll: <T>(x: T, ...fns: Array<(x: T) => T>) => T
 ```
 
 ### Mounting
@@ -573,6 +666,7 @@ interface MountedComponent {
 Components compose by calling other components and passing focused state via props:
 
 ```typescript
+import { h } from "@fun-land/fun-web";
 import { prop } from "@fun-land/accessor";
 import { UserProfile, UserData } from "./UserProfile";
 import { SettingsPanel, Settings } from "./Settings";

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

@@ -1,5 +1,5 @@
 /** DOM utilities for functional element creation and manipulation */
-import { type FunState } from "@fun-land/fun-state";
+import { type FunState, type FunRead } from "@fun-land/fun-state";
 import type { Component, ElementChild } from "./types";
 import { Accessor } from "@fun-land/accessor";
 export type Enhancer<El extends Element> = (element: El) => El;
@@ -16,6 +16,46 @@ export type Enhancer<El extends Element> = (element: El) => El;
  * h('div', {id: 'app', 'data-test': 'foo'}, [child1, child2])
  */
 export declare const h: <Tag extends keyof HTMLElementTagNameMap>(tag: Tag, attrs?: Record<string, any> | null, children?: ElementChild | ElementChild[]) => HTMLElementTagNameMap[Tag];
+type WritableKeys<T> = {
+    [K in keyof T]-?: (<F>() => F extends {
+        [Q in K]: T[K];
+    } ? 1 : 2) extends <F>() => F extends {
+        -readonly [Q in K]: T[K];
+    } ? 1 : 2 ? K : never;
+}[keyof T];
+type HxProps<El extends Element> = Partial<{
+    [K in WritableKeys<El> & string]: El[K] | null | undefined;
+}>;
+type HxHandlers<El extends Element> = Partial<{
+    [K in keyof GlobalEventHandlersEventMap]: (ev: GlobalEventHandlersEventMap[K] & {
+        currentTarget: El;
+    }) => void;
+}>;
+type HxBindings<El extends Element> = Partial<{
+    [K in WritableKeys<El> & string]: FunRead<El[K]>;
+}>;
+type HxOptionsBase<El extends Element> = {
+    props?: HxProps<El>;
+    attrs?: Record<string, string | number | boolean | null | undefined>;
+};
+type HxOptions<El extends Element> = HxOptionsBase<El> & {
+    signal: AbortSignal;
+    on?: HxHandlers<El>;
+    bind?: HxBindings<El>;
+};
+/**
+ * Create an element with structured props, attrs, event handlers, and bindings.
+ *
+ * @example
+ * hx("input", {
+ *   signal,
+ *   props: { type: "text" },
+ *   attrs: { "data-test": "name" },
+ *   bind: { value: nameState },
+ *   on: { input: (e) => nameState.set(e.currentTarget.value) },
+ * });
+ */
+export declare function hx<Tag extends keyof HTMLElementTagNameMap>(tag: Tag, options: HxOptions<HTMLElementTagNameMap[Tag]>, children?: ElementChild | ElementChild[]): HTMLElementTagNameMap[Tag];
 /**
  * Set text content of an element (returns element for chaining)
  * @returns {Enhancer}
@@ -34,7 +74,7 @@ export declare const attrs: (obj: Record<string, string>) => <El extends Element
  * 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;
+export declare const bindProperty: <E extends Element, K extends keyof E & string>(key: K, state: FunRead<E[K]>, signal: AbortSignal) => (el: E) => E;
 /**
  * Add CSS classes to an element (returns element for chaining)
  * @returns {Enhancer}
@@ -114,11 +154,13 @@ export declare const bindListChildren: <T>(options: {
  * });
  */
 export declare function renderWhen<State, Props>(options: {
-    state: FunState<State>;
+    state: FunRead<State>;
     predicate?: (value: State) => boolean;
     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[];
+/** add passed class (idempotent) to element when state returns true */
+export declare const bindClass: (className: string, state: FunRead<boolean>, signal: AbortSignal) => <E extends Element>(el: E) => E;
+export declare const querySelectorAll: <T extends Element>(selector: string) => T[];
+export {};

package/dist/esm/src/dom.js

@@ -1,3 +1,8 @@
+/**
+ * Type-preserving Object.entries helper for objects with known keys
+ * @internal
+ */
+const entries = (obj) => Object.entries(obj);
 /**
  * Create an HTML element with attributes and children
  *
@@ -12,7 +17,9 @@
  */
 export const h = (tag, 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-attrs, children) => {
+attrs, children
+// eslint-disable-next-line complexity
+) => {
     const element = document.createElement(tag);
     // Apply attributes/properties/events
     if (attrs) {
@@ -42,6 +49,52 @@ attrs, children) => {
     }
     return element;
 };
+// eslint-disable-next-line complexity
+export function hx(tag, options, children) {
+    if (!(options === null || options === void 0 ? void 0 : options.signal)) {
+        throw new Error("hx: signal is required");
+    }
+    const { signal, props, attrs: attrMap, on: onMap, bind } = options;
+    const element = document.createElement(tag);
+    if (props) {
+        for (const [key, value] of entries(props)) {
+            if (value == null)
+                continue;
+            element[key] = value;
+        }
+    }
+    if (attrMap) {
+        for (const [key, value] of Object.entries(attrMap)) {
+            if (value == null)
+                continue;
+            element.setAttribute(key, String(value));
+        }
+    }
+    if (children != null) {
+        appendChildren(children)(element);
+    }
+    if (bind) {
+        const bindElementProperty = (key, state) => {
+            bindProperty(key, state, signal)(element);
+        };
+        for (const key of Object.keys(bind)) {
+            const state = bind[key];
+            if (!state)
+                continue;
+            bindElementProperty(key, state);
+        }
+    }
+    if (onMap) {
+        for (const [event, handler] of Object.entries(onMap)) {
+            if (!handler)
+                continue;
+            element.addEventListener(event, handler, {
+                signal,
+            });
+        }
+    }
+    return element;
+}
 /**
  * Append children to an element, flattening arrays and converting primitives to text nodes
  * @returns {Enhancer}
@@ -180,6 +233,7 @@ export const bindListChildren = (options) => (parent) => {
         }
         rows.clear();
     };
+    // eslint-disable-next-line complexity
     const reconcile = () => {
         const items = list.get();
         const nextKeys = [];
@@ -259,6 +313,7 @@ export function renderWhen(options) {
     container.style.display = "contents";
     let childCtrl = null;
     let childEl = null;
+    // eslint-disable-next-line complexity
     const reconcile = () => {
         const shouldRender = predicate(state.get());
         if (shouldRender && !childEl) {
@@ -285,6 +340,10 @@ export function renderWhen(options) {
     reconcile();
     return container;
 }
-export const $ = (selector) => { var _a; return (_a = document.querySelector(selector)) !== null && _a !== void 0 ? _a : undefined; };
-export const $$ = (selector) => Array.from(document.querySelectorAll(selector));
+/** add passed class (idempotent) to element when state returns true */
+export const bindClass = (className, state, signal) => (el) => {
+    state.watch(signal, (active) => el.classList.toggle(className, active));
+    return el;
+};
+export const querySelectorAll = (selector) => Array.from(document.querySelectorAll(selector));
 //# sourceMappingURL=dom.js.map