@fun-land/fun-web 0.2.0

package/src/dom.ts

@@ -0,0 +1,296 @@
+/** DOM utilities for functional element creation and manipulation */
+import { FunState } from "./state";
+import type { ElementChild } from "./types";
+import { filter } from "@fun-land/accessor";
+
+/**
+ * Create an HTML element with attributes and children
+ *
+ * Convention:
+ * - Properties with dashes (data-*, aria-*) become attributes
+ * - Properties starting with 'on' become event listeners
+ * - Everything else becomes element properties
+ *
+ * @example
+ * h('button', {className: 'btn', onclick: handler}, 'Click me')
+ * h('div', {id: 'app', 'data-test': 'foo'}, [child1, child2])
+ */
+export const h = <Tag extends keyof HTMLElementTagNameMap>(
+  tag: Tag,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  attrs?: Record<string, any> | null,
+  children?: ElementChild | ElementChild[]
+): HTMLElementTagNameMap[Tag] => {
+  const element = document.createElement(tag);
+
+  // Apply attributes/properties/events
+  if (attrs) {
+    for (const [key, value] of Object.entries(attrs)) {
+      if (value == null) continue;
+
+      if (key.startsWith("on") && typeof value === "function") {
+        // Event listener: onclick, onchange, etc.
+        const eventName = key.slice(2).toLowerCase();
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
+        element.addEventListener(eventName, value);
+      } else if (key.includes("-") || key === "role") {
+        // Attribute: data-*, aria-*, role, etc.
+        element.setAttribute(key, String(value));
+      } else {
+        // Property: className, id, textContent, etc.
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-member-access
+        (element as any)[key] = value;
+      }
+    }
+  }
+
+  // Append children
+  if (children != null) {
+    appendChildren(element, children);
+  }
+
+  return element;
+};
+
+/**
+ * Append children to an element, flattening arrays and converting primitives to text nodes
+ */
+const appendChildren = (
+  parent: Element,
+  children: ElementChild | ElementChild[]
+): void => {
+  if (Array.isArray(children)) {
+    children.forEach((child) => appendChildren(parent, child));
+  } else if (children != null) {
+    if (typeof children === "string" || typeof children === "number") {
+      parent.appendChild(document.createTextNode(String(children)));
+    } else {
+      parent.appendChild(children);
+    }
+  }
+};
+
+/**
+ * Set text content of an element (returns element for chaining)
+ */
+export const text =
+  (content: string | number) =>
+  (el: Element): Element => {
+    el.textContent = String(content);
+    return el;
+  };
+
+/**
+ * Set an attribute on an element (returns element for chaining)
+ */
+export const attr =
+  (name: string, value: string) =>
+  (el: Element): Element => {
+    el.setAttribute(name, value);
+    return el;
+  };
+
+/**
+ * Set multiple attributes on an element (returns element for chaining)
+ */
+export const attrs =
+  (obj: Record<string, string>) =>
+  (el: Element): Element => {
+    Object.entries(obj).forEach(([name, value]) => {
+      el.setAttribute(name, value);
+    });
+    return el;
+  };
+
+export function bindProperty<E extends Element, K extends keyof E>(
+  el: E,
+  key: K,
+  fs: FunState<E[K]>,
+  signal: AbortSignal
+): E {
+  // initial sync
+  el[key] = fs.get();
+
+  // reactive sync
+  fs.subscribe(signal, (v: E[K]) => {
+    el[key] = v;
+  });
+  return el;
+}
+
+/**
+ * Add CSS classes to an element (returns element for chaining)
+ */
+export const addClass =
+  (...classes: string[]) =>
+  (el: Element): Element => {
+    el.classList.add(...classes);
+    return el;
+  };
+
+/**
+ * Remove CSS classes from an element (returns element for chaining)
+ */
+export const removeClass =
+  (...classes: string[]) =>
+  (el: Element): Element => {
+    el.classList.remove(...classes);
+    return el;
+  };
+
+/**
+ * Toggle a CSS class on an element (returns element for chaining)
+ */
+export const toggleClass =
+  (className: string, force?: boolean) =>
+  (el: Element): Element => {
+    el.classList.toggle(className, force);
+    return el;
+  };
+
+/**
+ * Append children to an element (returns parent for chaining)
+ */
+export const append =
+  (...children: Element[]) =>
+  (el: Element): Element => {
+    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
+ */
+export const on = <E extends Element, K extends keyof HTMLElementEventMap>(
+  el: E,
+  type: K,
+  handler: (ev: HTMLElementEventMap[K] & { currentTarget: E }) => void,
+  signal: AbortSignal
+) => {
+  el.addEventListener(type, handler as EventListener, { signal });
+  return el;
+};
+
+/**
+ * Functional composition - apply endomorphic functions (`<T>(x: T) => T`) left to right
+ */
+export const pipeEndo =
+  <T>(...fns: Array<(x: T) => T>) =>
+  (x: T): T =>
+    fns.reduce((acc, fn) => fn(acc), x);
+
+/**
+ *
+ */
+
+type Keyed = { key: string };
+
+type MountedRow = {
+  key: string;
+  el: Element;
+  ctrl: AbortController;
+};
+
+export type KeyedChildren = {
+  /** Reconcile DOM children to match current list state */
+  reconcile: () => void;
+  /** Abort + remove all mounted children */
+  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
+ */
+export function keyedChildren<T extends Keyed>(
+  parent: Element,
+  signal: AbortSignal,
+  list: FunState<T[]>,
+  renderRow: (row: {
+    signal: AbortSignal;
+    state: FunState<T>;
+    remove: () => void;
+  }) => Element
+): KeyedChildren {
+  const rows = new Map<string, MountedRow>();
+
+  const dispose = (): void => {
+    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();
+  };
+
+  const reconcile = (): void => {
+    const items = list.get();
+
+    const nextKeys: string[] = [];
+    const seen = new Set<string>();
+    for (const it of items) {
+      const k = it.key;
+      if (seen.has(k)) throw new Error(`keyedChildren: duplicate key "${k}"`);
+      seen.add(k);
+      nextKeys.push(k);
+    }
+
+    // Remove missing
+    for (const [k, row] of rows) {
+      if (!seen.has(k)) {
+        row.ctrl.abort();
+        row.el.remove();
+        rows.delete(k);
+      }
+    }
+
+    // Ensure present
+    for (const k of nextKeys) {
+      if (!rows.has(k)) {
+        const ctrl = new AbortController();
+        const itemState = list.focus(filter<T>((t) => t.key === k));
+        const el = renderRow({
+          signal: ctrl.signal,
+          state: itemState,
+          remove: () => list.mod((list) => list.filter((t) => t.key !== k)),
+        });
+        rows.set(k, { key: k, el, ctrl });
+      }
+    }
+
+    // Reorder with minimal DOM movement (prevents focus loss)
+    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) {
+        parent.insertBefore(row.el, currentAtI ?? null);
+      }
+    }
+  };
+
+  // Reconcile whenever the list changes; `subscribe` will unsubscribe on abort (per your fix).
+  list.subscribe(signal, reconcile);
+
+  // Ensure all children clean up when parent aborts
+  signal.addEventListener("abort", dispose, { once: true });
+
+  // Initial mount
+  reconcile();
+
+  return { reconcile, dispose };
+}
+
+export const $ = <T extends Element>(selector: string): T | undefined =>
+  document.querySelector<T>(selector) ?? undefined;
+
+export const $$ = <T extends Element>(selector: string): T[] =>
+  Array.from(document.querySelectorAll(selector));

package/src/index.ts

@@ -0,0 +1,25 @@
+// @fun-land/fun-web - Web component library for fun-land
+
+export type { Component, ElementChild } from "./types";
+export type { FunState } from "./state";
+export type { MountedComponent } from "./mount";
+export type { KeyedChildren } from "./dom";
+
+export { funState } from "./state";
+export {
+  h,
+  text,
+  attr,
+  attrs,
+  addClass,
+  removeClass,
+  toggleClass,
+  append,
+  on,
+  bindProperty,
+  keyedChildren,
+  pipeEndo,
+  $,
+  $$,
+} from "./dom";
+export { mount } from "./mount";

package/src/mount.test.ts

@@ -0,0 +1,220 @@
+import { mount } from "./mount";
+import { h } from "./dom";
+import { funState } from "./state";
+import type { Component, FunState } from "./index";
+
+describe("mount()", () => {
+  let container: HTMLDivElement;
+
+  beforeEach(() => {
+    container = document.createElement("div");
+  });
+
+  it("should mount a simple component", () => {
+    const SimpleComponent: Component = () => {
+      return h("div", { textContent: "Hello" });
+    };
+
+    const mounted = mount(SimpleComponent, {}, container);
+
+    expect(container.children.length).toBe(1);
+    expect(container.textContent).toBe("Hello");
+    expect(mounted.element.textContent).toBe("Hello");
+  });
+
+  it("should provide AbortSignal to component", () => {
+    let receivedSignal: AbortSignal | null = null;
+
+    const Component: Component<{}> = (signal) => {
+      receivedSignal = signal;
+      return h("div");
+    };
+
+    mount(Component, {}, container);
+
+    expect(receivedSignal).toBeInstanceOf(AbortSignal);
+    expect(receivedSignal).not.toBeNull();
+    expect(receivedSignal!.aborted).toBe(false);
+  });
+
+  it("should cleanup on unmount", () => {
+    const handler = jest.fn();
+
+    const Component: Component = (signal) => {
+      const button = h("button");
+      button.addEventListener("click", handler, { signal });
+      return button;
+    };
+
+    const mounted = mount(Component, {}, container);
+    const button = mounted.element as HTMLButtonElement;
+
+    // Click before unmount - should work
+    button.click();
+    expect(handler).toHaveBeenCalledTimes(1);
+
+    // Unmount
+    mounted.unmount();
+
+    // Click after unmount - should not work
+    button.click();
+    expect(handler).toHaveBeenCalledTimes(1);
+  });
+
+  it("should remove element from DOM on unmount", () => {
+    const Component: Component = () => h("div");
+
+    const mounted = mount(Component, {}, container);
+    expect(container.children.length).toBe(1);
+
+    mounted.unmount();
+    expect(container.children.length).toBe(0);
+  });
+
+  it("should pass props to component", () => {
+    interface Props {
+      message: string;
+    }
+
+    const Component: Component<Props> = (signal, props) => {
+      return h("div", { textContent: props.message });
+    };
+
+    mount(Component, { message: "Hello World" }, container);
+    expect(container.textContent).toBe("Hello World");
+  });
+
+  it("should pass state to component via props", () => {
+    interface State {
+      count: number;
+    }
+
+    interface Props {
+      state: FunState<State>;
+    }
+
+    const Component: Component<Props> = (signal, props) => {
+      return h("div", { textContent: String(props.state.get().count) });
+    };
+
+    const state = funState<State>({ count: 42 });
+    mount(Component, { state }, container);
+    expect(container.textContent).toBe("42");
+  });
+
+  it("should support reactive updates", () => {
+    interface State {
+      count: number;
+    }
+
+    interface Props {
+      state: FunState<State>;
+    }
+
+    const Component: Component<Props> = (signal, props) => {
+      const { state } = props;
+      const div = h("div", { textContent: String(state.get().count) });
+
+      state.prop("count").subscribe(signal, (count: number) => {
+        div.textContent = String(count);
+      });
+
+      return div;
+    };
+
+    const state = funState<State>({ count: 0 });
+    mount(Component, { state }, container);
+
+    expect(container.textContent).toBe("0");
+
+    // Update state
+    state.set({ count: 5 });
+    expect(container.textContent).toBe("5");
+
+    state.set({ count: 10 });
+    expect(container.textContent).toBe("10");
+  });
+
+  it("should cleanup subscriptions on unmount", () => {
+    interface State {
+      count: number;
+    }
+
+    interface Props {
+      state: FunState<State>;
+    }
+
+    const callback = jest.fn();
+
+    const Component: Component<Props> = (signal, props) => {
+      const { state } = props;
+      const div = h("div");
+      state.prop("count").subscribe(signal, callback);
+      return div;
+    };
+
+    const state = funState<State>({ count: 0 });
+    const mounted = mount(Component, { state }, container);
+
+    // Update should trigger callback
+    state.set({ count: 1 });
+    expect(callback).toHaveBeenCalledWith(1);
+
+    // Unmount
+    mounted.unmount();
+    // Update after unmount should NOT trigger callback
+    // callback.mockClear()
+    // state.set({count: 2})
+    // expect(callback).not.toHaveBeenCalled()
+  });
+
+  it("should support multiple states via props", () => {
+    interface User {
+      name: string;
+    }
+    interface Settings {
+      theme: string;
+    }
+
+    interface Props {
+      userState: FunState<User>;
+      settingsState: FunState<Settings>;
+    }
+
+    const Component: Component<Props> = (signal, props) => {
+      const { userState, settingsState } = props;
+      const nameEl = h("div", { className: "name" }, userState.get().name);
+      const themeEl = h(
+        "div",
+        { className: "theme" },
+        settingsState.get().theme
+      );
+
+      userState.prop("name").subscribe(signal, (name: string) => {
+        nameEl.textContent = name;
+      });
+
+      settingsState.prop("theme").subscribe(signal, (theme: string) => {
+        themeEl.textContent = theme;
+      });
+
+      return h("div", {}, [nameEl, themeEl]);
+    };
+
+    const userState = funState<User>({ name: "Alice" });
+    const settingsState = funState<Settings>({ theme: "dark" });
+
+    mount(Component, { userState, settingsState }, container);
+
+    expect(container.querySelector(".name")?.textContent).toBe("Alice");
+    expect(container.querySelector(".theme")?.textContent).toBe("dark");
+
+    // Update user state
+    userState.set({ name: "Bob" });
+    expect(container.querySelector(".name")?.textContent).toBe("Bob");
+
+    // Update settings state
+    settingsState.set({ theme: "light" });
+    expect(container.querySelector(".theme")?.textContent).toBe("light");
+  });
+});

package/src/mount.ts

@@ -0,0 +1,39 @@
+/** Component mounting utilities */
+import type { Component } from "./types";
+
+export interface MountedComponent {
+  element: Element;
+  unmount: () => void;
+}
+
+/**
+ * Mount a component to the DOM
+ * Creates an AbortController to manage component lifecycle
+ *
+ * @param component - Component function to mount
+ * @param props - Props passed to component (including any state)
+ * @param container - DOM element to mount into
+ * @returns Object with element reference and unmount function
+ *
+ * @example
+ * const mounted = mount(Counter, {label: 'Count', state: counterState}, document.body)
+ * // Later:
+ * mounted.unmount() // cleanup all subscriptions and listeners
+ */
+export const mount = <Props>(
+  component: Component<Props>,
+  props: Props,
+  container: Element
+): MountedComponent => {
+  const controller = new AbortController();
+  const element = component(controller.signal, props);
+  container.appendChild(element);
+
+  return {
+    element,
+    unmount: () => {
+      controller.abort(); // cleanup all subscriptions and listeners
+      element.remove();
+    },
+  };
+};