@fun-land/fun-web 0.2.0

package/LICENSE.md

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,515 @@
+# @fun-land/fun-web
+
+A lightweight web component library for building reactive UIs with native DOM and compositional state management.
+
+## Why fun-web?
+
+Build web UIs without a framework using:
+- **Run-once components** that never re-render (sidesteps stale closures, memoization, render cycles)
+- **Reactive state** following the FunState compositional pattern
+- **Native DOM** elements (no virtual DOM)
+- **TypeScript-first** APIs with full type inference
+- **AbortSignal** for automatic cleanup
+
+Perfect for embedding interactive components in static sites, building lightweight tools, or avoiding framework lock-in.
+
+## Features
+
+- **Subscription-based reactivity** - State changes automatically update DOM
+- **Keyed list rendering** - Efficient reconciliation without virtual DOM
+- **Type-safe utilities** - Element types and events inferred automatically
+- **Memory-safe by default** - AbortSignal prevents leaks
+- **Framework-agnostic** - Just functions and elements
+
+## Installation
+
+```bash
+yarn add @fun-land/fun-web @fun-land/accessor
+```
+
+## Quick Start
+
+```typescript
+import {
+  h,
+  funState,
+  mount,
+  bindProperty,
+  on,
+  type Component,
+  type FunState,
+} 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 past state and updates named property
+  bindProperty(button, "textContent", state, signal);
+
+  // Event handlers never go stale (component doesn't re-run)
+  on(button, "click", () => state.mod((n) => n + 1), signal);
+
+  return button;
+};
+
+// Create reactive state and mount 
+const mounted = mount(Counter, { state: funState(0) }, document.body);
+```
+
+## Core Concepts
+
+### Components Run Once
+
+**The most important difference from React/Vue/Svelte:** fun-web components execute once when mounted, set up subscriptions, and never re-run.
+
+```typescript
+const Counter: Component<{ count: FunState<number> }> = (signal, props) => {
+  console.log("Component runs once");
+
+  const display = h("div");
+  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);
+
+  return h("div", {}, [display, button]);
+  // Component function exits, but subscriptions keep working
+};
+```
+
+When `count` changes, the component **doesn't re-run**. Instead, the `bindProperty` subscription updates `display.textContent` directly.
+
+**Problems this sidesteps:**
+
+| Framework components | fun-web components |
+|---------------------|-------------------|
+| Re-execute on every state change | Execute once, subscriptions handle updates |
+| Need memoization (`useMemo`, `useCallback`) | No re-execution = no stale closures to worry about |
+| Virtual DOM diffing overhead | Direct DOM updates via subscriptions |
+| Rules about when you can update state | Update state whenever you want |
+| "Render cycles" and batching complexity | No render cycles, updates are just function calls |
+
+**What this means:**
+- Component functions are just **constructors** - they build UI once and set up reactive bindings
+- State changes trigger **targeted DOM updates**, not full re-renders
+- No "rendering" concept - just imperative DOM manipulation driven by reactive state
+- Simpler mental model: "When X changes, update this specific DOM property"
+
+**Concrete example:**
+
+```typescript
+// In React - component re-executes on every count change
+function ReactCounter() {
+  const [count, setCount] = useState(0);
+  console.log("Re-rendering!"); // Logs on every state change
+
+  // Need useCallback to prevent infinite re-renders
+  const increment = useCallback(() => setCount(c => c + 1), []);
+
+  return <div>{count} <button onClick={increment}>+</button></div>;
+}
+
+// In fun-web - component executes once
+const FunWebCounter: Component<{ count: FunState<number> }> = (signal, props) => {
+  console.log("Mounting!"); // Logs once, never again
+
+  const display = h("div");
+  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);
+
+  return h("div", {}, [display, button]);
+};
+```
+
+In React, clicking the button causes the entire component to re-execute. In fun-web, clicking the button just calls `count.mod()`, which triggers the `bindProperty` subscription to update `display.textContent`. The component function never runs again.
+
+### FunState - Reactive State with Subscriptions
+
+`FunState<T>` provides reactive compositional state [@fun-land/fun-state](../fun-state):
+
+```typescript
+const userState = funState({ name: "Alice", age: 30 });
+
+// Get current value
+userState.prop("name").get(); // "Alice"
+
+// Update state
+userState.prop("age").set(31);
+
+// Subscribe to changes (cleaned up when signal aborts)
+userState.prop("name").subscribe(signal, (name) => {
+  element.textContent = name; // runs when name changes
+});
+```
+
+### Component Signature
+
+Components are functions that receive an AbortSignal and props:
+
+```typescript
+type Component<Props = {}> = (
+  signal: AbortSignal,    // For cleanup
+  props: Props            // Data (static or reactive)
+) => Element              // Returns plain DOM element
+```
+
+**Props can contain anything:** Static values, callbacks, reactive state, or any combination. There's no distinction between "props" and "state" - state is just data that happens to have `.get()` and `.set()` methods.
+
+**Examples:**
+```typescript
+// Static props only
+const Static: Component<{ title: string }> = (signal, props) =>
+  h("h1", {}, props.title);
+
+// Reactive state in props
+const Counter: Component<{ count: FunState<number> }> = (signal, props) =>
+  h("div", {}, String(props.count.get()));
+
+// Mix of static and reactive
+const Dashboard: Component<{
+  onLogout: () => void;
+  user: FunState<User>;
+  settings: FunState<Settings>;
+}> = (signal, props) => {
+  // props.onLogout is a static callback
+  // props.user is reactive state
+  // props.settings is reactive state
+};
+```
+
+### Reactivity Patterns
+
+**Use `bindProperty` for simple one-way bindings:**
+
+```typescript
+const nameEl = h("div");
+const nameState: FunState<string> = state.prop("user").prop("name");
+
+bindProperty(nameEl, "textContent", nameState, signal);
+// nameEl.textContent stays in sync with nameState
+```
+
+**Use `on` for events:**
+
+```typescript
+const button = h("button", {}, "Click me");
+on(button, "click", (e: MouseEvent & { currentTarget: HTMLButtonElement }) => {
+  console.log(e.currentTarget.textContent);
+}, 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
+);
+```
+
+**Use `.subscribe()` for complex logic:**
+
+```typescript
+state.subscribe(signal, (s) => {
+  element.textContent = s.count > 100 ? "Max!" : String(s.count);
+  element.className = s.count > 100 ? "maxed" : "normal";
+  element.setAttribute("aria-label", `Count: ${s.count}`);
+});
+```
+
+### Cleanup with AbortSignal
+
+All subscriptions and event listeners require an AbortSignal. When the signal aborts, everything cleans up automatically:
+
+```typescript
+const MyComponent: Component<{ state: FunState<State> }> = (signal, props) => {
+  const display = h("div");
+  const button = h("button");
+
+  // All three clean up when signal aborts
+  bindProperty(display, "textContent", props.state.prop("count"), signal);
+  on(button, "click", () => props.state.mod(increment), signal);
+  props.state.subscribe(signal, (s) => console.log("Changed:", s));
+
+  return h("div", {}, [display, button]);
+};
+
+const mounted = mount(MyComponent, { state }, container);
+mounted.unmount(); // Aborts signal → everything cleans up
+```
+
+For the most part you won't have to worry about the abort signal if you use the helpers provided.
+
+## Best Practices
+
+**Prefer helpers over manual subscriptions:**
+
+```typescript
+// ✅ Good
+bindProperty(element, "textContent", state.prop("count"), signal);
+
+// ❌ Avoid (when bindProperty works)
+state.prop("count").subscribe(signal, (count) => {
+  element.textContent = String(count);
+});
+```
+
+**Use `on()` for type safety:**
+
+```typescript
+// ✅ Good - types inferred
+on(button, "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;
+}, { signal });
+```
+
+**Manual subscriptions for complex updates:**
+
+```typescript
+// ✅ complex updates may need subscribe
+state.subscribe(signal, (s) => {
+  // Multiple DOM updates based on complex conditions
+  if (s.status === "loading") {
+    spinner.style.display = "block";
+    button.disabled = true;
+  } else {
+    spinner.style.display = "none";
+    button.disabled = false;
+  }
+});
+```
+
+## API Reference
+
+### DOM Utilities
+
+#### `h`
+
+Declaratively create an HTML Element with properties and children.
+
+```typescript
+const div = h("div", { id: "app" }, [
+  h("h1", null, "Hello"),
+  h("input", { type: "text", value: "foo" })
+]);
+```
+
+**Attribute conventions:**
+- Dashed properties (`data-*`, `aria-*`) → `setAttribute()`
+- Don't event bind with properties, use `on()`
+- 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.
+
+```typescript
+const input: HTMLInputElement = h("input");
+bindProperty(input, "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.
+
+```typescript
+on(h("button"), "click", (e) => {
+  // e.currentTarget is typed as HTMLButtonElement
+  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>
+```
+
+Render and reconcile keyed lists efficiently. Each row gets its own AbortSignal for cleanup and a focused state.
+
+```typescript
+interface Todo {
+  key: string;
+  label: string;
+  done: boolean;
+}
+
+const todos: FunState<Todo[]> = funState([
+  { key: "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;
+});
+```
+
+#### $ and $$ - DOM Query Utilities
+
+Convenient shortcuts for `querySelector` and `querySelectorAll` with better TypeScript support.
+
+**`$<T extends Element>(selector: string): T | undefined`**
+
+Query a single element. Returns `undefined` instead of `null` if not found.
+
+```typescript
+const button = $<HTMLButtonElement>("#submit-btn");
+if (button) {
+  button.disabled = true;
+}
+
+const input = $<HTMLInputElement>(".name-input");
+```
+
+**`$$<T extends Element>(selector: string): T[]`**
+
+Query multiple elements. Returns a real Array (not NodeList) for better ergonomics.
+
+```typescript
+const items = $$<HTMLDivElement>(".item");
+items.forEach(item => item.classList.add("active"));
+
+// Array methods work directly
+const texts = $$(".label").map(el => el.textContent);
+```
+
+#### Other utilities
+
+All return the element for chaining:
+
+```typescript
+text: (content: string | number) => (el: Element) => Element
+attr: (name: string, value: string) => (el: Element) => Element
+attrs: (obj: Record<string, string>) => (el: Element) => Element
+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
+pipeEndo: <T>(...fns: Array<(x: T) => T>) => (x: T) => T
+```
+
+### Mounting
+
+#### mount
+```ts
+<Props>(component: Component<Props>, props: Props, container: Element): MountedComponent
+```
+
+Mount component to DOM and manage lifecycle. You probably only need to call this once in your app.
+
+```typescript
+const state = funState({ count: 0 });
+const mounted = mount(
+  Counter,
+  { label: "Clicks", state },
+  document.body
+);
+
+mounted.unmount(); // Cleanup
+```
+
+**Returns:**
+```typescript
+interface MountedComponent {
+  element: Element
+  unmount(): void
+}
+```
+
+## Composition
+
+Components compose by calling other components and passing focused state via props:
+
+```typescript
+import { prop } from "@fun-land/accessor";
+
+interface AppState {
+  user: UserData;
+  settings: Settings;
+}
+
+const App: Component<{ state: FunState<AppState> }> = (signal, props) => 
+  h("div", {}, [
+    UserProfile(signal, {
+      editable: true,
+      state: props.state.focus(prop<AppState>()("user")),
+    }),
+    SettingsPanel(signal, {
+      state: props.state.focus(prop<AppState>()("settings")),
+    })
+  ]);
+```
+
+Focused states only trigger updates when their slice changes. Components can also create **local state** using `funState()` instead of receiving it via props - there's no distinction, state is just data.
+
+## Examples
+
+See working examples:
+- `examples/counter/counter.ts` - Basic reactivity and composition
+- `examples/todo-app/todo-app.ts` - Keyed lists and form binding
+
+```bash
+yarn build:examples
+open examples/counter/index.html
+open examples/todo-app/todo.html
+```
+
+## Status
+
+**Experimental** - APIs may change.
+
+## License
+
+MIT

package/coverage/clover.xml

@@ -0,0 +1,136 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<coverage generated="1768272411491" clover="3.2.0">
+  <project timestamp="1768272411491" name="All files">
+    <metrics statements="121" coveredstatements="118" conditionals="38" coveredconditionals="34" methods="37" coveredmethods="32" elements="196" coveredelements="184" complexity="0" loc="121" ncloc="121" packages="1" files="3" classes="3"/>
+    <file name="dom.ts" path="/Users/jethrolarson/develop/fun-land/packages/fun-web/src/dom.ts">
+      <metrics statements="113" coveredstatements="110" conditionals="38" coveredconditionals="34" methods="34" coveredmethods="29"/>
+      <line num="4" count="2" type="stmt"/>
+      <line num="18" count="2" type="stmt"/>
+      <line num="23" count="32" type="stmt"/>
+      <line num="26" count="32" type="cond" truecount="2" falsecount="0"/>
+      <line num="27" count="13" type="stmt"/>
+      <line num="28" count="18" type="cond" truecount="2" falsecount="0"/>
+      <line num="30" count="16" type="cond" truecount="4" falsecount="0"/>
+      <line num="32" count="3" type="stmt"/>
+      <line num="33" count="3" type="stmt"/>
+      <line num="34" count="13" type="cond" truecount="4" falsecount="0"/>
+      <line num="36" count="2" type="stmt"/>
+      <line num="39" count="11" type="stmt"/>
+      <line num="45" count="32" type="cond" truecount="2" falsecount="0"/>
+      <line num="46" count="17" type="stmt"/>
+      <line num="49" count="32" type="stmt"/>
+      <line num="55" count="2" type="stmt"/>
+      <line num="59" count="29" type="cond" truecount="2" falsecount="0"/>
+      <line num="60" count="12" type="stmt"/>
+      <line num="61" count="24" type="cond" truecount="2" falsecount="0"/>
+      <line num="62" count="22" type="cond" truecount="4" falsecount="0"/>
+      <line num="63" count="12" type="stmt"/>
+      <line num="65" count="10" type="stmt"/>
+      <line num="73" count="2" type="stmt"/>
+      <line num="74" count="2" type="stmt"/>
+      <line num="75" count="4" type="stmt"/>
+      <line num="76" count="4" type="stmt"/>
+      <line num="77" count="4" type="stmt"/>
+      <line num="83" count="2" type="stmt"/>
+      <line num="84" count="2" type="stmt"/>
+      <line num="85" count="3" type="stmt"/>
+      <line num="86" count="3" type="stmt"/>
+      <line num="87" count="3" type="stmt"/>
+      <line num="93" count="2" type="stmt"/>
+      <line num="94" count="2" type="stmt"/>
+      <line num="95" count="2" type="stmt"/>
+      <line num="96" count="2" type="stmt"/>
+      <line num="97" count="3" type="stmt"/>
+      <line num="99" count="2" type="stmt"/>
+      <line num="102" count="2" type="stmt"/>
+      <line num="109" count="4" type="stmt"/>
+      <line num="112" count="4" type="stmt"/>
+      <line num="113" count="1" type="stmt"/>
+      <line num="115" count="4" type="stmt"/>
+      <line num="121" count="2" type="stmt"/>
+      <line num="122" count="2" type="stmt"/>
+      <line num="123" count="4" type="stmt"/>
+      <line num="124" count="4" type="stmt"/>
+      <line num="125" count="4" type="stmt"/>
+      <line num="131" count="2" type="stmt"/>
+      <line num="132" count="2" type="stmt"/>
+      <line num="133" count="2" type="stmt"/>
+      <line num="134" count="2" type="stmt"/>
+      <line num="135" count="2" type="stmt"/>
+      <line num="141" count="2" type="stmt"/>
+      <line num="142" count="2" type="stmt"/>
+      <line num="143" count="6" type="stmt"/>
+      <line num="144" count="6" type="stmt"/>
+      <line num="145" count="6" type="stmt"/>
+      <line num="151" count="2" type="stmt"/>
+      <line num="152" count="2" type="stmt"/>
+      <line num="153" count="3" type="stmt"/>
+      <line num="154" count="4" type="stmt"/>
+      <line num="155" count="3" type="stmt"/>
+      <line num="162" count="2" type="stmt"/>
+      <line num="168" count="3" type="stmt"/>
+      <line num="169" count="3" type="stmt"/>
+      <line num="175" count="2" type="stmt"/>
+      <line num="176" count="2" type="stmt"/>
+      <line num="177" count="1" type="stmt"/>
+      <line num="178" count="3" type="stmt"/>
+      <line num="208" count="2" type="stmt"/>
+      <line num="218" count="5" type="stmt"/>
+      <line num="220" count="5" type="stmt"/>
+      <line num="221" count="5" type="stmt"/>
+      <line num="223" count="8" type="stmt"/>
+      <line num="225" count="8" type="stmt"/>
+      <line num="227" count="5" type="stmt"/>
+      <line num="230" count="5" type="stmt"/>
+      <line num="231" count="8" type="stmt"/>
+      <line num="233" count="8" type="stmt"/>
+      <line num="234" count="8" type="stmt"/>
+      <line num="235" count="8" type="stmt"/>
+      <line num="236" count="17" type="stmt"/>
+      <line num="237" count="17" type="cond" truecount="2" falsecount="0"/>
+      <line num="238" count="16" type="stmt"/>
+      <line num="239" count="16" type="stmt"/>
+      <line num="243" count="7" type="stmt"/>
+      <line num="244" count="7" type="cond" truecount="2" falsecount="0"/>
+      <line num="245" count="1" type="stmt"/>
+      <line num="246" count="1" type="stmt"/>
+      <line num="247" count="1" type="stmt"/>
+      <line num="252" count="7" type="stmt"/>
+      <line num="253" count="15" type="cond" truecount="2" falsecount="0"/>
+      <line num="254" count="9" type="stmt"/>
+      <line num="255" count="21" type="stmt"/>
+      <line num="256" count="9" type="stmt"/>
+      <line num="259" count="0" type="stmt"/>
+      <line num="261" count="9" type="stmt"/>
+      <line num="266" count="7" type="stmt"/>
+      <line num="267" count="7" type="stmt"/>
+      <line num="268" count="15" type="stmt"/>
+      <line num="269" count="15" type="stmt"/>
+      <line num="270" count="15" type="stmt"/>
+      <line num="271" count="15" type="cond" truecount="2" falsecount="0"/>
+      <line num="272" count="10" type="cond" truecount="4" falsecount="0"/>
+      <line num="278" count="5" type="stmt"/>
+      <line num="281" count="5" type="stmt"/>
+      <line num="284" count="5" type="stmt"/>
+      <line num="286" count="4" type="stmt"/>
+      <line num="289" count="2" type="stmt"/>
+      <line num="290" count="0" type="cond" truecount="0" falsecount="4"/>
+      <line num="292" count="2" type="stmt"/>
+      <line num="293" count="0" type="stmt"/>
+    </file>
+    <file name="mount.ts" path="/Users/jethrolarson/develop/fun-land/packages/fun-web/src/mount.ts">
+      <metrics statements="7" coveredstatements="7" conditionals="0" coveredconditionals="0" methods="2" coveredmethods="2"/>
+      <line num="23" count="1" type="stmt"/>
+      <line num="28" count="9" type="stmt"/>
+      <line num="29" count="9" type="stmt"/>
+      <line num="30" count="9" type="stmt"/>
+      <line num="32" count="9" type="stmt"/>
+      <line num="35" count="3" type="stmt"/>
+      <line num="36" count="3" type="stmt"/>
+    </file>
+    <file name="state.ts" path="/Users/jethrolarson/develop/fun-land/packages/fun-web/src/state.ts">
+      <metrics statements="1" coveredstatements="1" conditionals="0" coveredconditionals="0" methods="1" coveredmethods="1"/>
+      <line num="2" count="31" type="stmt"/>
+    </file>
+  </project>
+</coverage>