pudui 0.0.0

package/README.md

@@ -0,0 +1,161 @@
+# pudui
+
+A tiny JSX UI runtime built from the ground up. The model is intentionally
+small: functional component factories return `Component` instances, and
+component state lives in ordinary closures.
+
+## Constraints
+
+- No runtime dependencies.
+- No hooks.
+- No class components as a user-facing component model.
+- Functional components only.
+- Stateful behavior is explicit: mutate closure data and call
+  `component.update()`.
+
+## MVP API
+
+- `Component<Props>` stores a render function and exposes `update(callback?)`
+  and `mount(callback)`.
+- `component.update(callback?)` requests an update. When a callback is passed,
+  it runs after the update has committed to the DOM.
+- `Component<Props>` accepts an optional `error(props, reason)` function that
+  renders fallback output when that component or one of its children throws.
+- `render(child, container)` mounts JSX or a component into a DOM container and
+  returns a root with `rerender(child)` and `unmount()`.
+- `hydrate(root, options)` hydrates server-rendered boundaries and returns the
+  same root API synchronously.
+- `renderToString(child, props?)` from `pudui/server` renders JSX or a component
+  to escaped HTML.
+- `createElement`, `jsx`, `jsxs`, and `jsxDEV` provide classic and automatic JSX
+  runtimes.
+- `ref` accepts one callback or nested arrays of callbacks. Each callback
+  receives the element after insertion and may return a cleanup function that
+  runs before removal. Known JSX tag names infer the matching DOM element type.
+- `component.mount(callback)` registers callbacks that run once, after the
+  component first enters the DOM and after ref callbacks for that commit.
+- `event(type, handler)` returns a ref callback that adds an event listener and
+  removes it during cleanup. Known DOM event names infer the matching event
+  object type.
+- `Fragment` renders children without adding an extra element.
+
+## Child Diffing and Keys
+
+Pudui flattens nested child arrays and fragments before rendering. Empty
+children (`null`, `undefined`, and booleans) are ignored.
+
+Child arrays are reconciled by position. During DOM updates, the child at index
+0 is patched with the next child at index 0, index 1 with index 1, and so on;
+new trailing children are appended together and removed trailing children are
+cleaned up together. Pudui does not compute keyed list moves across an array.
+
+`key` still affects identity at the current position. Host elements are reused
+only when their tag name and key match, and child components rendered by a
+parent are cached by explicit key or, when no key is provided, by render order.
+Use keys to preserve component state across conditional output, but do not rely
+on keys to reorder existing DOM nodes in a list.
+
+## JSX Setup
+
+Use the automatic runtime in applications:
+
+```json
+{
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "jsxImportSource": "pudui"
+  }
+}
+```
+
+## Stateless Component
+
+```tsx
+import { Component } from "pudui";
+import { renderToString } from "pudui/server";
+
+type Props = {
+  name: string;
+};
+
+function HelloWorld(_initialProps: Props) {
+  return new Component<Props>({
+    render({ name }) {
+      return <div>Hello, {name}!</div>;
+    },
+  });
+}
+
+renderToString(<HelloWorld name="Ada" />);
+```
+
+## Error Handling
+
+```tsx
+import { type Child, Component } from "pudui";
+
+type Props = {
+  children?: Child;
+};
+
+function Boundary(_initialProps: Props) {
+  return new Component<Props>({
+    error(_props, reason) {
+      return <p>Something went wrong: {String(reason)}</p>;
+    },
+    render({ children }) {
+      return <section>{children}</section>;
+    },
+  });
+}
+```
+
+## Stateful Component
+
+```tsx
+import { Component, event } from "pudui";
+
+type Props = {
+  initialCount?: number;
+};
+
+function Counter(initialProps: Props) {
+  let count = initialProps.initialCount ?? 0;
+
+  const component = new Component<Props>({
+    render(renderProps) {
+      if (initialProps.initialCount !== renderProps.initialCount) {
+        count = renderProps.initialCount ?? 0;
+      }
+
+      return (
+        <div>
+          <p>Count: {count}</p>
+          <button
+            type="button"
+            ref={[
+              event("click", () => {
+                count++;
+                component.update();
+              }),
+            ]}
+          >
+            Increment
+          </button>
+        </div>
+      );
+    },
+  });
+
+  return component;
+}
+```
+
+## Development
+
+```bash
+vp check
+vp test
+vp run bundle-size
+vp pack
+```

package/dist/component-D3kwgmef.mjs

@@ -0,0 +1,275 @@
+//#region src/invariant.ts
+/**
+* Throws a `TypeError` when a condition is not truthy.
+*
+* @param condition Condition to assert.
+* @param message Error message for failed assertions.
+*/
+function invariant(condition, message) {
+	if (!condition) fail(message);
+}
+/**
+* Throws a `TypeError` with the provided message.
+*
+* @param message Error message to throw.
+* @returns This function never returns.
+*/
+function fail(message) {
+	throw new TypeError(message);
+}
+//#endregion
+//#region src/core/component.ts
+const componentInternals = /* @__PURE__ */ new WeakMap();
+let updateFrameScheduled = false;
+let scheduledUpdates = /* @__PURE__ */ new Map();
+/**
+* Stateful unit of rendering in Pudui.
+*
+* Components own their render function, mount callbacks, child component
+* instances, and update scheduling. Create components from JSX factories and
+* call {@link update} when internal state changes.
+*
+* @example
+* ```tsx
+* import { Component, event } from "pudui";
+*
+* export function Counter() {
+*   let count = 0;
+*   const counter = new Component({
+*     render() {
+*       return <button ref={event("click", () => { count++; counter.update(); })}>{count}</button>;
+*     },
+*   });
+*
+*   return counter;
+* }
+* ```
+*/
+var Component = class {
+	/**
+	* Creates a component from render options.
+	*
+	* @param options Render, error, and hydration options for this component.
+	*/
+	constructor(options) {
+		componentInternals.set(this, {
+			i: 0,
+			c: /* @__PURE__ */ new Map(),
+			e: options.error,
+			h: options.hydrate,
+			f: /* @__PURE__ */ new Map(),
+			m: false,
+			o: [],
+			p: void 0,
+			r: options.render,
+			u: []
+		});
+	}
+	/**
+	* Queues a callback to run after the component's first browser mount.
+	*
+	* If the component is already mounted, the callback is ignored.
+	*
+	* @param callback Function to run after the initial mount commits.
+	*/
+	mount(callback) {
+		const internals = getComponentInternals(this);
+		if (!internals.m) internals.o.push(callback);
+	}
+	/**
+	* Schedules this component to rerender.
+	*
+	* Multiple updates in the same turn are batched. The optional callback runs
+	* after the update commits, unless the root has been unmounted.
+	*
+	* @param callback Function to run after the update commits.
+	*/
+	update(callback) {
+		for (const listener of getComponentInternals(this).f.keys()) scheduleUpdate(listener, callback);
+	}
+};
+/**
+* Checks whether a value is a Pudui component instance.
+*
+* @param value Value to inspect.
+* @returns `true` when the value is a {@link Component}.
+*/
+function isComponent(value) {
+	return value instanceof Component;
+}
+function getComponentInternals(component) {
+	const internals = componentInternals.get(component);
+	invariant(internals, "component");
+	return internals;
+}
+/**
+* Replaces the props stored on a component instance.
+*
+* @param component Component to update.
+* @param props Next props.
+*/
+function setComponentProps(component, props) {
+	getComponentInternals(component).p = props;
+}
+/**
+* Reads the current props stored on a component instance.
+*
+* @param component Component to inspect.
+* @returns Current props, or an empty object before props are assigned.
+*/
+function readComponentProps(component) {
+	return getComponentInternals(component).p ?? {};
+}
+/**
+* Reads hydration metadata associated with a component.
+*
+* @param component Component to inspect.
+* @returns Hydration metadata supplied in component options.
+*/
+function readComponentHydrateMeta(component) {
+	return getComponentInternals(component).h;
+}
+/**
+* Runs a component's render callback.
+*
+* @param component Component to render.
+* @returns Rendered child output.
+*/
+function renderComponentOutput(component) {
+	return getComponentInternals(component).r(readComponentProps(component));
+}
+/**
+* Runs a component's error callback for a failed render.
+*
+* @param component Component whose render failed.
+* @param reason Error or rejection reason from rendering.
+* @returns Fallback child output.
+*/
+function renderComponentErrorOutput(component, reason) {
+	const internals = getComponentInternals(component);
+	if (!internals.e) throw reason;
+	return internals.e(readComponentProps(component), reason);
+}
+/**
+* Marks the beginning of a component render pass.
+*
+* @param component Component being rendered.
+*/
+function beginComponentRender(component) {
+	const internals = getComponentInternals(component);
+	internals.i = 0;
+	internals.u = [];
+}
+/**
+* Marks the end of a component render pass and prunes unused child instances.
+*
+* @param component Component that finished rendering.
+*/
+function finishComponentRender(component) {
+	const internals = getComponentInternals(component);
+	for (const childSlot of internals.c.keys()) if (!internals.u.includes(childSlot)) internals.c.delete(childSlot);
+}
+/**
+* Resolves a component virtual node to a component instance.
+*
+* @param vnode Component virtual node.
+* @param owner Parent component that owns child instance slots.
+* @returns Existing or newly created component instance.
+*/
+function resolveComponent(vnode, owner) {
+	if (!owner) return createComponent(vnode.type, vnode.props);
+	const internals = getComponentInternals(owner);
+	const slot = vnode.key === void 0 ? "." + internals.i++ : "#" + String(vnode.key);
+	const existing = internals.c.get(slot);
+	internals.u.push(slot);
+	if (existing?.t === vnode.type) {
+		setComponentProps(existing.v, vnode.props);
+		return existing.v;
+	}
+	const component = createComponent(vnode.type, vnode.props);
+	internals.c.set(slot, {
+		t: vnode.type,
+		v: component
+	});
+	return component;
+}
+/**
+* Creates a component instance from a component factory.
+*
+* @param factory Component factory to invoke.
+* @param props Initial props.
+* @returns Created component instance.
+*/
+function createComponent(factory, props) {
+	const component = factory(props);
+	if (!isComponent(component)) throw new TypeError("Component");
+	setComponentProps(component, props);
+	return component;
+}
+/**
+* Subscribes a renderer to component updates.
+*
+* @param component Component to observe.
+* @param listener Update listener to schedule.
+* @returns Cleanup function that removes the subscription.
+*/
+function subscribeComponent(component, listener) {
+	const listeners = getComponentInternals(component).f;
+	listeners.set(listener, (listeners.get(listener) ?? 0) + 1);
+	return () => {
+		const count = listeners.get(listener);
+		if (count !== void 0) if (count <= 1) listeners.delete(listener);
+		else listeners.set(listener, count - 1);
+	};
+}
+/**
+* Queues a component's mount callbacks into a commit effect list.
+*
+* @param component Component that may need mounting.
+* @param mountEffects Effect list for the current commit.
+*/
+function queueComponentMount(component, mountEffects) {
+	if (getComponentInternals(component).m) return;
+	mountEffects.push(() => {
+		mountComponent(component);
+	});
+}
+function mountComponent(component) {
+	const internals = getComponentInternals(component);
+	if (internals.m) return;
+	internals.m = true;
+	const callbacks = internals.o;
+	internals.o = [];
+	for (const callback of callbacks) callback();
+}
+function scheduleUpdate(listener, callback) {
+	let callbacks = scheduledUpdates.get(listener);
+	if (!callbacks) scheduledUpdates.set(listener, callbacks = []);
+	callback && callbacks.push(callback);
+	if (updateFrameScheduled) return;
+	updateFrameScheduled = true;
+	Promise.resolve().then(() => {
+		queueMicrotask(() => {
+			updateFrameScheduled = false;
+			const updates = scheduledUpdates;
+			scheduledUpdates = /* @__PURE__ */ new Map();
+			for (const [update, callbacks] of updates) {
+				const committed = update();
+				if (isPromiseLike(committed)) {
+					committed.then((asyncCommitted) => {
+						if (asyncCommitted === false) return;
+						for (const callback of callbacks) callback();
+					});
+					continue;
+				}
+				if (committed === false) continue;
+				for (const callback of callbacks) callback();
+			}
+		});
+	});
+}
+function isPromiseLike(value) {
+	return typeof value?.then === "function";
+}
+//#endregion
+export { isComponent as a, readComponentProps as c, resolveComponent as d, setComponentProps as f, invariant as h, finishComponentRender as i, renderComponentErrorOutput as l, fail as m, beginComponentRender as n, queueComponentMount as o, subscribeComponent as p, createComponent as r, readComponentHydrateMeta as s, Component as t, renderComponentOutput as u };