@fun-land/fun-web 0.2.0

package/wip/hx-magic-properties-plan.md

@@ -0,0 +1,575 @@
+# Magic Properties for fun-web Element Constructor
+
+## Overview
+Add new `hx()` helper function with magic properties `$bind`, `$on`, and `$model` to enable inline reactive bindings, reducing boilerplate while maintaining type safety and explicit signal management. The `$model` property provides automatic two-way binding sugar.
+
+## User Decisions (Confirmed)
+- ✅ **Approach**: Non-curried `hx(signal, tag, attrs)` - signal as first parameter
+- ✅ **Naming**: Use `$` prefix (`$bind`, `$on`, `$model`)
+- ✅ **Initial scope**: Include `$bind`, `$on`, and `$model` (not `$class`/`$style` yet)
+- ✅ **Two-way binding**: Include `$model` sugar for automatic two-way binding
+- ✅ **File structure**: Keep hx() in separate files (`hx.ts`, `hx.test.ts`) since it's experimental
+
+## Current State
+Users must chain `bindProperty()` and `on()` calls after creating elements:
+
+```typescript
+const input = h("input", { type: "text" });
+bindProperty(input, "value", state.prop("name"), signal);
+on(input, "input", (e) => state.prop("name").set(e.currentTarget.value), signal);
+```
+
+## Proposed API
+
+### New hx() Function
+```typescript
+// Signal is explicit as first parameter
+const input = hx(signal, "input", {
+  type: "text",
+  $model: { value: state.prop("name") }
+});
+
+// Can mix with regular h() for static elements
+const heading = h("h1", {}, "Login Form");
+```
+
+### Real-world Example
+```typescript
+const LoginForm: Component<{}, [FunWebState<LoginState>]> = (signal, props, state) => {
+  return h("form", { className: "login" }, [
+    h("h2", {}, "Login"),
+
+    // Email input with automatic two-way binding using $model
+    hx(signal, "input", {
+      type: "email",
+      placeholder: "Email",
+      $model: { value: state.prop("email") }
+    }),
+
+    // Password input with automatic two-way binding
+    hx(signal, "input", {
+      type: "password",
+      placeholder: "Password",
+      $model: { value: state.prop("password") }
+    }),
+
+    // Submit button with custom handler
+    hx(signal, "button", {
+      type: "submit",
+      $on: { click: handleSubmit }
+    })
+  ]);
+};
+```
+
+## Implementation Plan
+
+### Phase 1: Core Implementation
+
+**File: `/packages/fun-web/src/hx.ts`** (new file - keeping experimental features separate)
+
+1. **Create new hx.ts file** with hx() function (non-curried, signal as first param):
+```typescript
+// src/hx.ts - Experimental magic properties for fun-web
+import { bindProperty, on, appendChildren } from "./dom";
+import type { ElementChild } from "./types";
+import type { FunWebState } from "./state";
+
+export interface MagicAttrs<E extends Element> {
+  $bind?: Partial<{
+    [K in keyof E]: FunWebState<E[K]>
+  }>;
+  $on?: Partial<{
+    [K in keyof HTMLElementEventMap]: (
+      ev: HTMLElementEventMap[K] & { currentTarget: E }
+    ) => void
+  }>;
+  $model?: Partial<{
+    [K in keyof E]: FunWebState<E[K]>
+  }>;
+}
+
+export const hx = <Tag extends keyof HTMLElementTagNameMap>(
+  signal: AbortSignal,
+  tag: Tag,
+  attrs?: (Record<string, any> & MagicAttrs<HTMLElementTagNameMap[Tag]>) | null,
+  children?: ElementChild | ElementChild[]
+): HTMLElementTagNameMap[Tag] => {
+  const element = document.createElement(tag);
+
+  if (attrs) {
+    const { $bind, $on, $model, ...regularAttrs } = attrs;
+
+    // Process regular attributes (reuse h() logic)
+    for (const [key, value] of Object.entries(regularAttrs)) {
+      if (value == null) continue;
+
+      if (key.startsWith("on") && typeof value === "function") {
+        const eventName = key.slice(2).toLowerCase();
+        element.addEventListener(eventName, value);
+      } else if (key.includes("-") || key === "role") {
+        element.setAttribute(key, String(value));
+      } else {
+        (element as any)[key] = value;
+      }
+    }
+
+    // Process $model magic property (two-way binding sugar)
+    if ($model) {
+      for (const [key, state] of Object.entries($model)) {
+        // Bind property (state → element)
+        bindProperty(element, key as any, state as any, signal);
+
+        // Auto-detect event and setup listener (element → state)
+        const eventType = getEventForProperty(key, element.tagName);
+        on(element, eventType as any, (e: any) => {
+          (state as any).set(e.currentTarget[key]);
+        }, signal);
+      }
+    }
+
+    // Process $bind magic property
+    if ($bind) {
+      for (const [key, state] of Object.entries($bind)) {
+        bindProperty(element, key as any, state as any, signal);
+      }
+    }
+
+    // Process $on magic property
+    if ($on) {
+      for (const [type, handler] of Object.entries($on)) {
+        on(element, type as any, handler as any, signal);
+      }
+    }
+  }
+
+  // Append children (reuse appendChildren from h())
+  if (children != null) {
+    appendChildren(element, children);
+  }
+
+  return element;
+};
+
+// Helper to auto-detect the correct event type for a property
+function getEventForProperty(prop: string, tagName: string): string {
+  if (prop === "checked") return "change";
+  if (prop === "value" && tagName === "SELECT") return "change";
+  if (prop === "value") return "input";
+  return "change"; // default
+}
+```
+
+**Note**: hx() will duplicate some attribute processing logic from h(), but keeps experimental features isolated.
+
+**File: `/packages/fun-web/src/index.ts`**
+
+2. **Export hx() and types from the new file**:
+```typescript
+export { hx, type MagicAttrs } from "./hx";
+```
+
+### Phase 2: Testing
+
+**File: `/packages/fun-web/src/hx.test.ts`** (new file - separate tests for experimental feature)
+
+Create comprehensive test suite:
+
+```typescript
+import { hx } from "./hx";
+import { useFunWebState } from "./state";
+
+describe("hx() magic properties", () => {
+  let signal: AbortSignal;
+
+  beforeEach(() => {
+    const controller = new AbortController();
+    signal = controller.signal;
+  });
+
+  describe("$bind", () => {
+    it("should set initial property value from state", () => {
+      const state = useFunWebState("hello");
+      const input = hx(signal, "input", {
+        $bind: { value: state }
+      }) as HTMLInputElement;
+      expect(input.value).toBe("hello");
+    });
+
+    it("should update property when state changes", () => {
+      const state = useFunWebState("hello");
+      const input = hx(signal, "input", {
+        $bind: { value: state }
+      }) as HTMLInputElement;
+
+      state.set("world");
+      expect(input.value).toBe("world");
+    });
+
+    it("should stop updating after signal aborts", () => {
+      const controller = new AbortController();
+      const state = useFunWebState("hello");
+      const input = hx(controller.signal, "input", {
+        $bind: { value: state }
+      }) as HTMLInputElement;
+
+      controller.abort();
+      state.set("world");
+      expect(input.value).toBe("hello");
+    });
+
+    it("should support binding multiple properties", () => {
+      const valueState = useFunWebState("test");
+      const disabledState = useFunWebState(true);
+      const input = hx(signal, "input", {
+        $bind: {
+          value: valueState,
+          disabled: disabledState
+        }
+      }) as HTMLInputElement;
+
+      expect(input.value).toBe("test");
+      expect(input.disabled).toBe(true);
+    });
+  });
+
+  describe("$on", () => {
+    it("should attach event listeners", () => {
+      const handler = jest.fn();
+      const button = hx(signal, "button", {
+        $on: { click: handler }
+      });
+
+      button.click();
+      expect(handler).toHaveBeenCalled();
+    });
+
+    it("should support multiple event listeners", () => {
+      const clickHandler = jest.fn();
+      const mouseoverHandler = jest.fn();
+      const button = hx(signal, "button", {
+        $on: {
+          click: clickHandler,
+          mouseover: mouseoverHandler
+        }
+      });
+
+      button.click();
+      expect(clickHandler).toHaveBeenCalled();
+
+      button.dispatchEvent(new MouseEvent("mouseover"));
+      expect(mouseoverHandler).toHaveBeenCalled();
+    });
+
+    it("should cleanup listeners on signal abort", () => {
+      const controller = new AbortController();
+      const handler = jest.fn();
+      const button = hx(controller.signal, "button", {
+        $on: { click: handler }
+      });
+
+      controller.abort();
+      button.click();
+      expect(handler).not.toHaveBeenCalled();
+    });
+  });
+
+  describe("$bind and $on together", () => {
+    it("should support both in same element (two-way binding)", () => {
+      const state = useFunWebState("hello");
+      const input = hx(signal, "input", {
+        $bind: { value: state },
+        $on: {
+          input: (e) => state.set(e.currentTarget.value)
+        }
+      }) as HTMLInputElement;
+
+      expect(input.value).toBe("hello");
+
+      // Simulate user typing
+      input.value = "world";
+      input.dispatchEvent(new Event("input"));
+
+      expect(state.get()).toBe("world");
+    });
+  });
+
+  describe("$model", () => {
+    it("should create automatic two-way binding for input value", () => {
+      const state = useFunWebState("hello");
+      const input = hx(signal, "input", {
+        type: "text",
+        $model: { value: state }
+      }) as HTMLInputElement;
+
+      // Initial binding (state → element)
+      expect(input.value).toBe("hello");
+
+      // Simulate user typing (element → state)
+      input.value = "world";
+      input.dispatchEvent(new Event("input"));
+      expect(state.get()).toBe("world");
+
+      // State changes should update element
+      state.set("foo");
+      expect(input.value).toBe("foo");
+    });
+
+    it("should create automatic two-way binding for checkbox checked", () => {
+      const state = useFunWebState(false);
+      const checkbox = hx(signal, "input", {
+        type: "checkbox",
+        $model: { checked: state }
+      }) as HTMLInputElement;
+
+      expect(checkbox.checked).toBe(false);
+
+      checkbox.checked = true;
+      checkbox.dispatchEvent(new Event("change"));
+      expect(state.get()).toBe(true);
+
+      state.set(false);
+      expect(checkbox.checked).toBe(false);
+    });
+
+    it("should use 'change' event for select elements", () => {
+      const state = useFunWebState("option1");
+      const select = hx(signal, "select", {
+        $model: { value: state }
+      }) as HTMLSelectElement;
+
+      expect(select.value).toBe("option1");
+
+      select.value = "option2";
+      select.dispatchEvent(new Event("change"));
+      expect(state.get()).toBe("option2");
+    });
+
+    it("should cleanup on signal abort", () => {
+      const controller = new AbortController();
+      const state = useFunWebState("hello");
+      const input = hx(controller.signal, "input", {
+        $model: { value: state }
+      }) as HTMLInputElement;
+
+      controller.abort();
+
+      // After abort, element changes shouldn't update state
+      input.value = "world";
+      input.dispatchEvent(new Event("input"));
+      expect(state.get()).toBe("hello");
+
+      // And state changes shouldn't update element
+      state.set("foo");
+      expect(input.value).toBe("world");
+    });
+
+    it("should be simpler than explicit $bind + $on", () => {
+      // This is a documentation test showing the benefit
+      const state = useFunWebState("test");
+
+      // Explicit way (verbose)
+      const input1 = hx(signal, "input", {
+        $bind: { value: state },
+        $on: { input: (e) => state.set(e.currentTarget.value) }
+      });
+
+      // Sugar way (concise)
+      const input2 = hx(signal, "input", {
+        $model: { value: state }
+      });
+
+      // Both should behave identically
+      expect(input1.value).toBe("test");
+      expect(input2.value).toBe("test");
+    });
+  });
+
+  describe("regular attributes", () => {
+    it("should process regular attributes alongside magic properties", () => {
+      const state = useFunWebState("test");
+      const input = hx(signal, "input", {
+        type: "text",
+        className: "form-input",
+        placeholder: "Enter name",
+        $bind: { value: state }
+      }) as HTMLInputElement;
+
+      expect(input.type).toBe("text");
+      expect(input.className).toBe("form-input");
+      expect(input.placeholder).toBe("Enter name");
+      expect(input.value).toBe("test");
+    });
+  });
+
+  describe("type inference", () => {
+    it("should infer correct element type from tag", () => {
+      // This is a compile-time test - if it compiles, it passes
+      const input = hx(signal, "input", {});
+      const _value: string = input.value; // HTMLInputElement has value
+
+      const div = hx(signal, "div", {});
+      // @ts-expect-error - HTMLDivElement doesn't have value property
+      const _noValue: string = div.value;
+    });
+  });
+});
+```
+
+### Phase 3: Documentation
+
+**File: `/packages/fun-web/README.md`**
+
+Add new section after "Best Practices":
+
+```markdown
+## Magic Properties with hx()
+
+For more concise inline bindings, use the `hx()` helper:
+
+### Basic Usage
+
+```typescript
+import { hx } from "@fun-land/fun-web";
+
+const MyComponent: Component<{}, [FunWebState<State>]> = (signal, props, state) => {
+  // Use hx() with $model for simple two-way binding
+  const input = hx(signal, "input", {
+    type: "text",
+    placeholder: "Enter your name",
+    $model: { value: state.prop("name") }
+  });
+
+  // Mix with regular h() for static elements
+  const label = h("label", {}, "Name:");
+
+  return h("div", {}, [label, input]);
+};
+```
+
+### Magic Properties
+
+**`$bind`**: Bind element properties to reactive state
+
+```typescript
+$bind: { value: state.prop("name") }  // Syncs input.value with state.name
+$bind: { checked: state.prop("agreed") }  // Syncs checkbox.checked with state.agreed
+$bind: { disabled: state.prop("isDisabled") }  // Syncs button.disabled with state
+```
+
+Equivalent to `bindProperty(el, "value", state.prop("name"), signal)` but inline.
+
+**`$on`**: Attach event listeners
+
+```typescript
+$on: { click: () => console.log("clicked") }
+$on: { input: (e) => state.set(e.currentTarget.value) }
+$on: { submit: (e) => { e.preventDefault(); handleSubmit(); } }
+```
+
+Equivalent to `on(el, "click", handler, signal)` but inline.
+
+**`$model`**: Automatic two-way binding (combines $bind + $on)
+
+```typescript
+$model: { value: state.prop("name") }  // Auto two-way binding for input.value
+$model: { checked: state.prop("agreed") }  // Auto two-way binding for checkbox.checked
+```
+
+Automatically:
+- Binds property from state to element (like $bind)
+- Sets up event listener to sync changes back to state (like $on)
+- Detects the correct event type based on property and element:
+  - `checked` → `change` event
+  - `value` on `<select>` → `change` event
+  - `value` on other elements → `input` event
+
+### Two-Way Binding Patterns
+
+**Explicit two-way binding** with $bind + $on:
+
+```typescript
+const input = hx(signal, "input", {
+  type: "email",
+  $bind: { value: state.prop("email") },
+  $on: { input: (e) => state.prop("email").set(e.currentTarget.value) }
+});
+```
+
+**Automatic two-way binding** with $model (recommended for simple cases):
+
+```typescript
+const input = hx(signal, "input", {
+  type: "email",
+  $model: { value: state.prop("email") }
+});
+```
+
+Use `$model` when the default event detection works for you. Use explicit `$bind` + `$on` when you need custom event handling or transformation logic.
+
+### When to use hx() vs h()
+
+**Use `hx()` when:**
+- Element needs reactive bindings (`$bind`)
+- Element needs event listeners that update state (`$on`)
+- You want inline syntax for cleaner code
+
+**Use regular `h()` when:**
+- Element is static (no bindings or event listeners)
+- You prefer explicit `bindProperty()` and `on()` calls
+- Building non-reactive components
+
+Both approaches work together - use what fits the situation.
+```
+
+**File: `/packages/fun-web/examples/todo-app/todo-app.ts`**
+
+Refactor one component to demonstrate hx():
+
+```typescript
+// Before: verbose with separate calls
+const Todo: Component<TodoProps, [FunWebState<TodoState>]> = (signal, props, state) => {
+  const checkbox = h("input", { type: "checkbox" });
+  bindProperty(checkbox, "checked", state.prop("checked"), signal);
+  on(checkbox, "change", (e) => {
+    state.prop("checked").set(e.currentTarget.checked);
+  }, signal);
+
+  // ... more elements ...
+};
+
+// After: concise with hx() and $model
+const Todo: Component<TodoProps, [FunWebState<TodoState>]> = (signal, props, state) => {
+  const checkbox = hx(signal, "input", {
+    type: "checkbox",
+    $model: { checked: state.prop("checked") }
+  });
+
+  const labelInput = hx(signal, "input", {
+    type: "text",
+    $model: { value: state.prop("label") }
+  });
+
+  // ... more elements ...
+};
+```
+
+## Verification Plan
+
+1. **Tests pass**: All 71 existing tests + new hx() tests
+2. **Type safety**: IDE autocomplete works, no type errors
+3. **Examples build**: `yarn build:examples` succeeds
+4. **Bundle size**: Check impact (expect <500 bytes increase)
+5. **Manual testing**: Try hx() in examples, verify cleanup works
+
+## Critical Files
+
+- `/packages/fun-web/src/hx.ts` - **NEW FILE** - hx() function with magic properties (experimental)
+- `/packages/fun-web/src/hx.test.ts` - **NEW FILE** - Comprehensive test suite for hx()
+- `/packages/fun-web/src/index.ts` - Add exports for hx and MagicAttrs
+- `/packages/fun-web/examples/todo-app/todo-app.ts` - Refactor to demonstrate hx()
+- `/packages/fun-web/README.md` - Document magic properties API
+
+## Next Steps
+
+Ready to implement hx() with all three magic properties: `$bind`, `$on`, and `$model`.

package/wip/next.md

@@ -0,0 +1,22 @@
+Ready to ship:
+
+2. Update root CLAUDE.md - Document fun-web in the monorepo guide.
+3. Publish to npm - Run lerna publish to release it.
+
+Polish before shipping:
+
+5. Performance testing - Benchmark keyedChildren with large lists
+6. Add more examples - Maybe a form validation example or simple SPA
+
+New features:
+
+7. Conditional rendering helper - Similar to keyedChildren but for if/else
+8. Animation helpers - Utilities for transitions when elements mount/unmount
+9. Portal support - Render components outside their parent container
+10. Server integration - Document patterns for hydrating server-rendered HTML
+
+Documentation:
+
+11. Migration guide - For users coming from React or other frameworks
+12. API comparison table - Show fun-web equivalents to React patterns
+13. Video walkthrough - Record building something with fun-web