@lab206/dom 0.1.0

package/src/component.ts

@@ -0,0 +1,127 @@
+import type { Child } from "./h.js";
+import { h } from "./h.js";
+import { show } from "./show.js";
+import { list, type ListOptions } from "./list.js";
+import { createProps, type ReactiveProps } from "./props.js";
+
+export type ComponentProps<P extends object> = ReactiveProps<
+  P & { children?: unknown }
+>;
+
+export type ComponentSetup<P extends object> = (
+  props: ComponentProps<P>,
+) => Node | DocumentFragment | null | undefined;
+
+export type Component<P extends object = Record<string, never>> = (
+  props?: P & { children?: unknown },
+) => Node | DocumentFragment | null | undefined;
+
+/**
+ * Declare a function component with **reactive props**.
+ *
+ * Setup runs **once** per instance. Reading `props.x` inside effects /
+ * JSX reactive scopes tracks the parent's signal or accessor.
+ *
+ * @example
+ * ```tsx
+ * const Hello = component((props: { name: string }) => (
+ *   <p>{() => `Hello, ${props.name}`}</p>
+ * ));
+ *
+ * // Live updates — pass a signal or accessor:
+ * <Hello name={name} />
+ * <Hello name={() => user().name} />
+ * ```
+ */
+export function component<P extends object>(
+  setup: ComponentSetup<P>,
+): Component<P> {
+  const Comp: Component<P> = (raw) => {
+    // If JSX already applied createProps, `raw` is a Proxy — still safe
+    // to wrap again only when we have a plain object. Detect proxy via
+    // missing own keys reliability: always normalize through createProps
+    // on a shallow bag of current keys so double-proxy still reads source.
+    const props = createProps(
+      (raw ?? {}) as P & { children?: unknown },
+    ) as ComponentProps<P>;
+    return setup(props);
+  };
+  Object.defineProperty(Comp, "name", {
+    value: setup.name || "Component",
+    configurable: true,
+  });
+  return Comp;
+}
+
+/**
+ * Conditional render for JSX.
+ * `when` may be a boolean, signal, or zero-arg accessor — unwrapped on read
+ * when used with reactive props / JSX.
+ */
+export function Show(props: {
+  when: boolean | (() => boolean);
+  children: (() => Node) | Node | Child;
+  fallback?: (() => Node) | Node | Child;
+}): HTMLElement {
+  // Normalize so accessors stay lazy for the show() effect.
+  const p = props;
+  const whenFn = (): boolean => {
+    const w = p.when;
+    if (typeof w === "function") return !!(w as () => boolean)();
+    return !!w;
+  };
+
+  const host = document.createElement("div");
+  host.style.display = "contents";
+
+  const resolve = (
+    value: (() => Node) | Node | Child | undefined,
+  ): Node => {
+    if (value == null || value === false || value === true) {
+      return document.createComment("show");
+    }
+    if (typeof value === "function") {
+      const result = (value as () => unknown)();
+      if (result instanceof Node) return result;
+      return h("span", { text: value as () => string | number });
+    }
+    if (typeof value === "string" || typeof value === "number") {
+      return document.createTextNode(String(value));
+    }
+    return value as Node;
+  };
+
+  show(host, whenFn, () => resolve(p.children as (() => Node) | Node));
+
+  if (p.fallback !== undefined) {
+    const fallbackHost = document.createElement("div");
+    fallbackHost.style.display = "contents";
+    show(fallbackHost, () => !whenFn(), () => resolve(p.fallback));
+    const outer = document.createElement("div");
+    outer.style.display = "contents";
+    outer.append(host, fallbackHost);
+    return outer;
+  }
+
+  return host;
+}
+
+/**
+ * Keyed list for JSX.
+ */
+export function For<T>(props: {
+  each: readonly T[] | (() => readonly T[]);
+  children: (item: () => T, index: () => number) => Node;
+  key?: ListOptions<T>["key"];
+}): HTMLElement {
+  const host = document.createElement("div");
+  host.style.display = "contents";
+  const getItems = (): readonly T[] => {
+    const e = props.each;
+    return typeof e === "function" ? (e as () => readonly T[])() : e;
+  };
+  list(host, getItems, props.children, {
+    ...(props.key ? { key: props.key } : {}),
+  });
+  return host;
+}

package/src/dynamic.ts

@@ -0,0 +1,93 @@
+import { effect, type Dispose } from "@lab206/core";
+
+/**
+ * Values a reactive JSX child function may return.
+ * Nodes mount as DOM; strings/numbers become text; nullish clears the slot.
+ */
+export type DynamicChild =
+  | Node
+  | DocumentFragment
+  | string
+  | number
+  | boolean
+  | null
+  | undefined
+  | DynamicChild[];
+
+/**
+ * Mount a reactive child that may return **text or DOM nodes**.
+ *
+ * Previously function children were always treated as text via `String(value)`,
+ * which produced `[object HTMLParagraphElement]` when a node was returned
+ * (common for Tabs / Accordion / List content).
+ *
+ * Uses a `display: contents` host so layout is unaffected.
+ */
+export function bindDynamic(
+  parent: ParentNode,
+  get: () => DynamicChild,
+): Dispose {
+  const host = document.createElement("span");
+  host.setAttribute("data-pu-dyn", "");
+  // contents: children participate in parent layout as if unwrapped
+  (host.style as CSSStyleDeclaration).display = "contents";
+  parent.appendChild(host);
+
+  let textNode: Text | null = null;
+  let mode: "empty" | "text" | "nodes" = "empty";
+
+  return effect(() => {
+    const value = get();
+
+    if (value == null || value === false || value === true) {
+      host.replaceChildren();
+      textNode = null;
+      mode = "empty";
+      return;
+    }
+
+    if (typeof value === "string" || typeof value === "number") {
+      const s = String(value);
+      if (mode === "text" && textNode) {
+        textNode.data = s;
+      } else {
+        host.replaceChildren();
+        textNode = document.createTextNode(s);
+        host.appendChild(textNode);
+        mode = "text";
+      }
+      return;
+    }
+
+    // Nodes / arrays — never String(object)
+    textNode = null;
+    mode = "nodes";
+    host.replaceChildren();
+    appendValue(host, value);
+  });
+}
+
+function appendValue(parent: ParentNode, value: DynamicChild): void {
+  if (value == null || value === false || value === true) return;
+
+  if (typeof value === "string" || typeof value === "number") {
+    parent.appendChild(document.createTextNode(String(value)));
+    return;
+  }
+
+  // Prefer nodeType over instanceof — DocumentFragment may be missing in some test envs
+  if (
+    typeof value === "object" &&
+    value !== null &&
+    "nodeType" in (value as object) &&
+    typeof (value as Node).nodeType === "number"
+  ) {
+    parent.appendChild(value as Node);
+    return;
+  }
+
+  if (Array.isArray(value)) {
+    for (const item of value) appendValue(parent, item);
+  }
+  // Non-node objects are ignored (avoids "[object HTML…]")
+}

package/src/fragment.ts

@@ -0,0 +1,43 @@
+import type { Child } from "./h.js";
+import { bindDynamic, type DynamicChild } from "./dynamic.js";
+
+/** Normalize JSX children into a flat list. */
+export function normalizeChildren(children: unknown): Child[] {
+  if (children == null || children === false || children === true) {
+    return [];
+  }
+  if (Array.isArray(children)) {
+    const out: Child[] = [];
+    for (const child of children) {
+      out.push(...normalizeChildren(child));
+    }
+    return out;
+  }
+  return [children as Child];
+}
+
+/** Append a Child to a parent (static node, reactive text, or reactive nodes). */
+export function appendChild(parent: ParentNode, child: Child): void {
+  if (child == null || child === false || child === true) return;
+  if (typeof child === "function") {
+    bindDynamic(parent, child as () => DynamicChild);
+    return;
+  }
+  if (typeof child === "string" || typeof child === "number") {
+    parent.appendChild(document.createTextNode(String(child)));
+    return;
+  }
+  parent.appendChild(child);
+}
+
+/**
+ * JSX Fragment — groups children without a wrapper element.
+ * Returns a DocumentFragment (children move into the parent on insert).
+ */
+export function Fragment(props: { children?: unknown }): DocumentFragment {
+  const frag = document.createDocumentFragment();
+  for (const child of normalizeChildren(props.children)) {
+    appendChild(frag, child);
+  }
+  return frag;
+}

package/src/h.ts

@@ -0,0 +1,236 @@
+import { bindAttr, bindClass, bindProp, bindStyle, bindText } from "./bind.js";
+import { bindDynamic, type DynamicChild } from "./dynamic.js";
+import { on } from "./on.js";
+import { createProps } from "./props.js";
+
+export type Child =
+  | Node
+  | DocumentFragment
+  | string
+  | number
+  | boolean
+  | null
+  | undefined
+  | (() => DynamicChild);
+
+export type FunctionComponent<P = Record<string, unknown>> = (
+  props: P,
+) => Node | DocumentFragment | null | undefined;
+
+export type Props = {
+  /** Static or reactive text content (sets textContent). */
+  text?: string | number | (() => string | number | boolean | null | undefined);
+  class?: string | (() => string | Record<string, boolean | undefined | null> | null | undefined);
+  className?: string | (() => string | Record<string, boolean | undefined | null> | null | undefined);
+  style?:
+    | Record<string, string | number | null | undefined>
+    | (() => Record<string, string | number | null | undefined> | null | undefined);
+  /** ref callback with the created element */
+  ref?: (el: HTMLElement) => void;
+  children?: unknown;
+  [key: string]: unknown;
+};
+
+const RESERVED = new Set([
+  "text",
+  "class",
+  "className",
+  "style",
+  "ref",
+  "children",
+]);
+
+/**
+ * Create an element — or invoke a function component.
+ *
+ * Classic JSX (`jsxFactory: "h"`) compiles `<App />` to `h(App, props)`.
+ * Automatic runtime uses `jsx()` which also supports function types.
+ */
+export function h<K extends keyof HTMLElementTagNameMap>(
+  tag: K,
+  props?: Props | null,
+  ...children: Child[]
+): HTMLElementTagNameMap[K];
+
+export function h(
+  tag: string,
+  props?: Props | null,
+  ...children: Child[]
+): HTMLElement;
+
+export function h<P extends Record<string, unknown>>(
+  tag: FunctionComponent<P>,
+  props?: (P & Props) | null,
+  ...children: Child[]
+): Node | DocumentFragment;
+
+export function h(
+  tag: string | FunctionComponent,
+  props?: Props | null,
+  ...children: Child[]
+): Node | DocumentFragment {
+  // Function component (classic JSX: h(App, props, ...children))
+  if (typeof tag === "function") {
+    const raw: Record<string, unknown> = { ...(props ?? {}) };
+    if (children.length === 1) {
+      raw.children = children[0];
+    } else if (children.length > 1) {
+      raw.children = children;
+    }
+    const result = tag(createProps(raw) as never);
+    if (result == null) {
+      return document.createComment("powers");
+    }
+    return result;
+  }
+
+  if (typeof tag !== "string" || tag === "") {
+    throw new Error(
+      `[powers/dom] h() expected a tag name string or component function, got: ${typeof tag}`,
+    );
+  }
+
+  const el = document.createElement(tag);
+
+  if (props) {
+    applyProps(el, props);
+  }
+
+  for (const child of children) {
+    appendChild(el, child);
+  }
+
+  // Also support props.children (automatic runtime path sometimes)
+  if (props?.children != null && children.length === 0) {
+    const c = props.children;
+    if (Array.isArray(c)) {
+      for (const item of c) appendChild(el, item as Child);
+    } else {
+      appendChild(el, c as Child);
+    }
+  }
+
+  return el;
+}
+
+/** Create a reactive or static text node. */
+export function text(
+  value: string | number | (() => string | number | boolean | null | undefined),
+): Text {
+  const node = document.createTextNode("");
+  if (typeof value === "function") {
+    bindText(node, value);
+  } else {
+    node.data = String(value);
+  }
+  return node;
+}
+
+function applyProps(el: HTMLElement, props: Props): void {
+  for (const key of Object.keys(props)) {
+    if (RESERVED.has(key)) continue;
+    const value = props[key];
+
+    if (key.startsWith("on") && key.length > 2 && typeof value === "function") {
+      // onClick → click, onMouseDown → mousedown
+      const event = key.slice(2).toLowerCase();
+      on(el, event, value as EventListener);
+      continue;
+    }
+
+    if (typeof value === "function") {
+      if (isDomProp(key)) {
+        bindProp(el, key, value as () => unknown);
+      } else {
+        bindAttr(
+          el,
+          toAttrName(key),
+          value as () => string | number | boolean | null | undefined,
+        );
+      }
+      continue;
+    }
+
+    if (isDomProp(key)) {
+      (el as unknown as Record<string, unknown>)[key] = value;
+    } else if (value === true) {
+      el.setAttribute(toAttrName(key), "");
+    } else if (value !== false && value != null) {
+      el.setAttribute(toAttrName(key), String(value));
+    }
+  }
+
+  const classValue = props.class ?? props.className;
+  if (classValue !== undefined) {
+    if (typeof classValue === "function") {
+      bindClass(el, classValue);
+    } else if (classValue != null) {
+      el.className = classValue;
+    }
+  }
+
+  if (props.style !== undefined) {
+    if (typeof props.style === "function") {
+      bindStyle(el, props.style);
+    } else if (props.style) {
+      bindStyle(el, () => props.style as Record<string, string | number>);
+    }
+  }
+
+  if (props.text !== undefined) {
+    if (typeof props.text === "function") {
+      bindText(el, props.text);
+    } else {
+      el.textContent = String(props.text);
+    }
+  }
+
+  if (typeof props.ref === "function") {
+    props.ref(el);
+  }
+}
+
+function appendChild(parent: ParentNode, child: Child): void {
+  if (child == null || child === false || child === true) return;
+  if (typeof child === "function") {
+    // May return text *or* DOM nodes (Tabs/Accordion content, etc.)
+    bindDynamic(parent, child as () => DynamicChild);
+    return;
+  }
+  if (typeof child === "string" || typeof child === "number") {
+    parent.appendChild(document.createTextNode(String(child)));
+    return;
+  }
+  parent.appendChild(child);
+}
+
+const DOM_PROPS = new Set([
+  "value",
+  "checked",
+  "selected",
+  "disabled",
+  "hidden",
+  "readOnly",
+  "multiple",
+  "muted",
+  "controls",
+  "defaultValue",
+  "defaultChecked",
+  "innerHTML",
+  "tabIndex",
+  "spellcheck",
+]);
+
+function isDomProp(name: string): boolean {
+  return DOM_PROPS.has(name);
+}
+
+function toAttrName(key: string): string {
+  if (key.startsWith("aria")) {
+    return key.replace(/([A-Z])/g, "-$1").toLowerCase();
+  }
+  if (key.startsWith("data") && key.length > 4 && key[4] !== "-") {
+    return key.replace(/([A-Z])/g, "-$1").toLowerCase();
+  }
+  return key;
+}

package/src/index.ts

@@ -0,0 +1,54 @@
+/**
+ * @lab206/dom
+ *
+ * Thin, explicit DOM bindings over @lab206/core.
+ *
+ * Learn order:
+ *   mount → h / JSX → component → reactive props → Show / For
+ *
+ * Form controls in @lab206/ui use `bind={signal}` for two-way state —
+ * `bind` is intentionally not unwrapped by createProps (see props.ts).
+ */
+
+export { mount } from "./mount.js";
+export type { MountResult } from "./mount.js";
+
+export { h, text } from "./h.js";
+export type { Child, Props, FunctionComponent } from "./h.js";
+
+export { Fragment, normalizeChildren, appendChild } from "./fragment.js";
+
+export {
+  bindText,
+  bindAttr,
+  bindProp,
+  bindClass,
+  bindStyle,
+} from "./bind.js";
+
+export { bindDynamic } from "./dynamic.js";
+export type { DynamicChild } from "./dynamic.js";
+
+export { on } from "./on.js";
+export { show } from "./show.js";
+export { list } from "./list.js";
+export type { ListOptions } from "./list.js";
+export { insert, remove } from "./insert.js";
+
+export { component, Show, For } from "./component.js";
+export type {
+  Component,
+  ComponentProps,
+  ComponentSetup,
+} from "./component.js";
+
+export {
+  createProps,
+  mergeProps,
+  splitProps,
+  unwrapProp,
+  getRawProp,
+  isSignal,
+  isReactiveProps,
+} from "./props.js";
+export type { ReactiveProps } from "./props.js";

package/src/insert.ts

@@ -0,0 +1,14 @@
+/** Append or insert a node. Returns the node for chaining. */
+export function insert<T extends Node>(
+  parent: ParentNode,
+  child: T,
+  anchor: Node | null = null,
+): T {
+  parent.insertBefore(child, anchor);
+  return child;
+}
+
+/** Remove a node from its parent if attached. */
+export function remove(node: Node): void {
+  node.parentNode?.removeChild(node);
+}

package/src/jsx-runtime.ts

@@ -0,0 +1,100 @@
+/**
+ * Automatic JSX runtime for Powers.
+ *
+ * Vite / TypeScript:
+ *   jsx: "react-jsx"
+ *   jsxImportSource: "@lab206/dom"
+ *
+ * Function components receive **reactive props** via `createProps`
+ * (unless they already wrapped themselves with `component()`).
+ */
+import { h, type Props } from "./h.js";
+import { Fragment, normalizeChildren } from "./fragment.js";
+import { createProps } from "./props.js";
+
+export { Fragment };
+
+export type FunctionComponent<P = Record<string, unknown>> = (
+  props: P,
+) => Node | DocumentFragment | null | undefined;
+
+/** Marker set on components that already apply createProps. */
+export const REACTIVE_PROPS = Symbol.for("powers.reactiveProps");
+
+export function jsx(
+  type: string | FunctionComponent<Record<string, unknown>>,
+  props: (Props & { children?: unknown }) | null,
+  _key?: string | number,
+): Node | DocumentFragment {
+  return create(type, props);
+}
+
+export function jsxs(
+  type: string | FunctionComponent<Record<string, unknown>>,
+  props: (Props & { children?: unknown }) | null,
+  _key?: string | number,
+): Node | DocumentFragment {
+  return create(type, props);
+}
+
+export function jsxDEV(
+  type: string | FunctionComponent<Record<string, unknown>>,
+  props: (Props & { children?: unknown }) | null,
+  _key?: string | number,
+): Node | DocumentFragment {
+  return create(type, props);
+}
+
+function create(
+  type: string | FunctionComponent<Record<string, unknown>>,
+  props: (Props & { children?: unknown }) | null,
+): Node | DocumentFragment {
+  const p = props ?? {};
+  const { children, ...rest } = p;
+
+  if (typeof type === "function") {
+    // Always pass through createProps so bare function components get
+    // reactive field access. component() also wraps — double-wrap is OK
+    // (outer raw object, inner Proxy of raw; component's createProps runs first).
+    const reactive = createProps(p as Record<string, unknown>);
+    const result = type(reactive as Record<string, unknown>);
+    if (result == null) {
+      return document.createComment("powers");
+    }
+    return result;
+  }
+
+  const childList = normalizeChildren(children);
+  return h(type, rest as Props, ...childList);
+}
+
+export namespace JSX {
+  export type Element = Node | DocumentFragment;
+  export type ElementType = string | FunctionComponent<any>;
+
+  export interface ElementAttributesProperty {
+    props: unknown;
+  }
+  export interface ElementChildrenAttribute {
+    children: unknown;
+  }
+
+  export type LibraryManagedAttributes<C, P> = P;
+
+  export interface IntrinsicAttributes {
+    key?: string | number;
+  }
+
+  export type IntrinsicElements = {
+    [K in keyof HTMLElementTagNameMap]: Props & {
+      children?: unknown;
+    } & {
+      [attr: string]: unknown;
+    };
+  } & {
+    [elemName: string]: Props & {
+      children?: unknown;
+      [attr: string]: unknown;
+    };
+  };
+}