@blueshed/railroad 0.2.0

package/jsx.ts

@@ -0,0 +1,381 @@
+/**
+ * JSX Runtime — real DOM elements backed by signals
+ *
+ * createElement(tag, props, ...children)
+ *   - tag: string → creates HTML element (or SVG element inside <svg>)
+ *   - tag: function → calls component function(props)
+ *   - props: attributes, event handlers (onclick etc), ref
+ *   - children: string, number, Node, Signal<T>, arrays, null/undefined
+ *
+ * When a Signal is used as a child, an effect auto-updates the text node.
+ * When a Signal is used as a prop value, an effect auto-updates the attribute.
+ *
+ * SVG support:
+ *   <svg> is created with the SVG namespace. Any HTML children appended to
+ *   an SVG-namespaced parent are automatically adopted into the SVG namespace.
+ *   This handles the JSX bottom-up evaluation order transparently — you can
+ *   write <svg><g><circle /></g></svg> and it just works.
+ *
+ * Reactive helpers:
+ *   when(signal, truthy, falsy?)  — conditional rendering, swaps DOM nodes
+ *   list(signal, keyFn, render)   — keyed reactive list, render receives Signal<T>
+ *   list(signal, render)          — index-based reactive list, render receives raw T
+ *   text(fn)                      — reactive text from computed expression
+ */
+
+import { Signal, signal, effect, computed } from "./signals";
+import type { Dispose } from "./signals";
+
+// === SVG namespace ===
+
+const SVG_NS = "http://www.w3.org/2000/svg";
+const storedProps = new WeakMap<Element, Record<string, any>>();
+
+// === Dispose scope management ===
+
+const disposeStack: Dispose[][] = [];
+
+export function pushDisposeScope(): void {
+  disposeStack.push([]);
+}
+
+export function popDisposeScope(): Dispose {
+  const disposers = disposeStack.pop() || [];
+  return () => disposers.forEach((d) => d());
+}
+
+function trackDispose(d: Dispose): void {
+  const scope = disposeStack[disposeStack.length - 1];
+  if (scope) scope.push(d);
+}
+
+// === Fragment ===
+
+export function Fragment(props: any): DocumentFragment {
+  const frag = document.createDocumentFragment();
+  const children = props?.children
+    ? (Array.isArray(props.children) ? props.children : [props.children])
+    : [];
+  appendChildren(frag, children);
+  return frag;
+}
+
+// === Props application ===
+
+function applyProps(el: Element, props: Record<string, any>): void {
+  for (const [key, value] of Object.entries(props)) {
+    if (key === "ref") {
+      if (typeof value === "function") value(el);
+    } else if (key === "innerHTML") {
+      if (value instanceof Signal) {
+        trackDispose(effect(() => { el.innerHTML = value.get(); }));
+      } else {
+        el.innerHTML = value;
+      }
+    } else if (key === "className" || key === "class") {
+      if (value instanceof Signal) {
+        trackDispose(effect(() => { el.setAttribute("class", value.get()); }));
+      } else {
+        el.setAttribute("class", value);
+      }
+    } else if (key === "value" || key === "checked" || key === "disabled" || key === "selected" || key === "srcdoc" || key === "src") {
+      if (value instanceof Signal) {
+        trackDispose(effect(() => { (el as any)[key] = value.get(); }));
+      } else {
+        (el as any)[key] = value;
+      }
+    } else if (key === "style" && typeof value === "object" && !(value instanceof Signal)) {
+      Object.assign((el as any).style, value);
+    } else if (key.startsWith("on")) {
+      el.addEventListener(key.slice(2).toLowerCase(), value);
+    } else {
+      if (value instanceof Signal) {
+        trackDispose(effect(() => {
+          const v = value.get();
+          if (v === false || v == null) el.removeAttribute(key);
+          else el.setAttribute(key, String(v));
+        }));
+      } else if (value !== false && value != null) {
+        el.setAttribute(key, String(value));
+      }
+    }
+  }
+}
+
+// === createElement ===
+
+export function createElement(
+  tag: string | Function,
+  props: Record<string, any> | null,
+  ...children: any[]
+): Node {
+  if (typeof tag === "function") {
+    const componentProps = { ...props, children };
+    return tag(componentProps);
+  }
+
+  // SVG root element is always created with the SVG namespace.
+  // Child SVG elements are adopted in appendChildren when appended
+  // to an SVG-namespaced parent.
+  const el = tag === "svg"
+    ? document.createElementNS(SVG_NS, tag)
+    : document.createElement(tag);
+
+  if (props) {
+    storedProps.set(el, props);
+    applyProps(el, props);
+  }
+
+  appendChildren(el, children);
+  return el;
+}
+
+// === SVG adoption ===
+
+/**
+ * Recursively adopt an HTML element into the SVG namespace.
+ * Creates a new SVG element, re-applies stored props (or copies
+ * attributes), and recursively adopts all children.
+ */
+function adoptSvg(node: Node): Node {
+  if (node instanceof Text || node instanceof Comment) return node;
+  if (!(node instanceof Element) || node.namespaceURI === SVG_NS) return node;
+
+  const svgEl = document.createElementNS(SVG_NS, node.localName);
+  const props = storedProps.get(node);
+
+  if (props) {
+    storedProps.set(svgEl, props);
+    applyProps(svgEl, props);
+  } else {
+    // No stored props — copy attributes directly
+    for (let i = 0; i < node.attributes.length; i++) {
+      const attr = node.attributes[i]!;
+      svgEl.setAttribute(attr.name, attr.value);
+    }
+  }
+
+  // Adopt children recursively
+  while (node.firstChild) {
+    svgEl.appendChild(adoptSvg(node.removeChild(node.firstChild)));
+  }
+
+  return svgEl;
+}
+
+// === Child rendering ===
+
+function appendChildren(parent: Node, children: any[]): void {
+  const isSvgParent = parent instanceof Element &&
+    parent.namespaceURI === SVG_NS;
+
+  for (const child of children.flat(Infinity)) {
+    if (child == null || child === false || child === true) continue;
+
+    if (child instanceof Signal) {
+      const text = document.createTextNode(String(child.peek()));
+      trackDispose(effect(() => {
+        text.textContent = String(child.get());
+      }));
+      parent.appendChild(text);
+    } else if (child instanceof Node) {
+      // Adopt HTML elements into SVG namespace when parent is SVG
+      if (isSvgParent &&
+          child instanceof Element &&
+          child.namespaceURI !== SVG_NS) {
+        parent.appendChild(adoptSvg(child));
+      } else {
+        parent.appendChild(child);
+      }
+    } else {
+      parent.appendChild(document.createTextNode(String(child)));
+    }
+  }
+}
+
+// === text() — reactive computed text node ===
+// Use for expressions: text(() => count.get() > 5 ? "High" : "Low")
+
+export function text(fn: () => string): Node {
+  const value = computed(fn);
+  const node = document.createTextNode(value.peek());
+  trackDispose(effect(() => {
+    node.textContent = value.get();
+  }));
+  return node;
+}
+
+// === when() — conditional rendering ===
+// Swaps DOM nodes only when truthiness transitions (falsy↔truthy).
+// Value changes within the same branch (e.g. "a" → "b") do NOT re-render.
+// Components inside each branch should use signals to react to value changes.
+//   when(isLoggedIn, () => <Dashboard />, () => <Login />)
+
+export function when(
+  condition: Signal<any> | (() => any),
+  truthy: () => Node,
+  falsy?: () => Node,
+): Node {
+  const anchor = document.createComment("when");
+  let current: Node | null = null;
+  let currentDispose: Dispose | null = null;
+  let wasTruthy: boolean | undefined = undefined;
+
+  const sig = typeof condition === "function" ? computed(condition) : condition;
+
+  function swap() {
+    const val = sig.get();
+    const isTruthy = !!val;
+
+    // Only swap when truthiness actually changes
+    if (isTruthy === wasTruthy) return;
+    wasTruthy = isTruthy;
+
+    if (currentDispose) currentDispose();
+    if (current && anchor.parentNode) {
+      anchor.parentNode.removeChild(current);
+    }
+
+    pushDisposeScope();
+    current = isTruthy ? truthy() : (falsy ? falsy() : null);
+    currentDispose = popDisposeScope();
+
+    if (current && anchor.parentNode) {
+      anchor.parentNode.insertBefore(current, anchor.nextSibling);
+    }
+  }
+
+  trackDispose(effect(() => {
+    sig.get(); // track
+    if (!anchor.parentNode) {
+      queueMicrotask(swap);
+    } else {
+      swap();
+    }
+  }));
+
+  // Return a fragment: anchor + initial content
+  const frag = document.createDocumentFragment();
+  frag.appendChild(anchor);
+  if (current) frag.appendChild(current);
+  return frag;
+}
+
+// === list() — keyed reactive list rendering ===
+// Diffs by key to preserve DOM nodes across updates.
+//
+// Keyed form — render receives Signal<T> and Signal<number> so item
+// updates flow into existing DOM without re-creating nodes:
+//   list(items, (t) => t.id, (item, index) => <li>{text(() => item.get().name)}</li>)
+//
+// Non-keyed form (index-based, raw values):
+//   list(items, (item, index) => <li>{item}</li>)
+
+export function list<T>(
+  items: Signal<T[]>,
+  keyFnOrRender: ((item: T) => string | number) | ((item: T, index: number) => Node),
+  maybeRender?: (item: Signal<T>, index: Signal<number>) => Node,
+): Node {
+  const hasKeyFn = maybeRender !== undefined;
+  const keyFn = hasKeyFn ? keyFnOrRender as (item: T) => string | number : null;
+
+  type Entry = { node: Node; dispose: Dispose; item?: Signal<T>; index?: Signal<number> };
+  const anchor = document.createComment("list");
+  let entries: Map<string | number, Entry> = new Map();
+  let order: (string | number)[] = [];
+
+  function removeEntry(key: string | number) {
+    const entry = entries.get(key);
+    if (entry) {
+      entry.dispose();
+      entry.node.parentNode?.removeChild(entry.node);
+      entries.delete(key);
+    }
+  }
+
+  function clearAll() {
+    for (const [, entry] of entries) {
+      entry.dispose();
+      entry.node.parentNode?.removeChild(entry.node);
+    }
+    entries = new Map();
+    order = [];
+  }
+
+  function sync() {
+    const arr = items.get();
+    const parent = anchor.parentNode;
+    if (!parent) return;
+
+    const newKeys = arr.map((item, i) => keyFn ? keyFn(item) : i);
+    const newKeySet = new Set(newKeys);
+
+    // Remove entries no longer in the list
+    for (const key of order) {
+      if (!newKeySet.has(key)) removeEntry(key);
+    }
+
+    // Add or reorder entries
+    let insertBefore: Node = anchor;
+    for (let i = newKeys.length - 1; i >= 0; i--) {
+      const key = newKeys[i]!;
+      let entry = entries.get(key);
+
+      if (!entry) {
+        // New item — create
+        pushDisposeScope();
+        let node: Node;
+        if (hasKeyFn) {
+          const itemSig = signal(arr[i]!);
+          const indexSig = signal(i);
+          node = maybeRender!(itemSig, indexSig);
+          const dispose = popDisposeScope();
+          entry = { node, dispose, item: itemSig, index: indexSig };
+        } else {
+          node = (keyFnOrRender as (item: T, index: number) => Node)(arr[i]!, i);
+          const dispose = popDisposeScope();
+          entry = { node, dispose };
+        }
+        entries.set(key, entry);
+      } else if (hasKeyFn) {
+        // Existing keyed item — push new value into its signal
+        entry.item!.set(arr[i]!);
+        entry.index!.set(i);
+      }
+
+      // Move or insert into correct position
+      if (entry.node.nextSibling !== insertBefore) {
+        parent.insertBefore(entry.node, insertBefore);
+      }
+      insertBefore = entry.node;
+    }
+
+    order = newKeys;
+  }
+
+  trackDispose(effect(() => {
+    items.get(); // track
+    if (!anchor.parentNode) {
+      queueMicrotask(sync);
+    } else {
+      sync();
+    }
+  }));
+
+  trackDispose(() => clearAll());
+
+  const frag = document.createDocumentFragment();
+  frag.appendChild(anchor);
+  return frag;
+}
+
+// === JSX namespace for TypeScript ===
+
+declare global {
+  namespace JSX {
+    type Element = globalThis.Node;
+    interface IntrinsicElements {
+      [tag: string]: any;
+    }
+  }
+}

package/logger.ts

@@ -0,0 +1,91 @@
+/**
+ * Logger — colored, timestamped, level-gated console output.
+ *
+ * Usage:
+ *   import { createLogger, setLogLevel, loggedRequest } from "@blueshed/railroad";
+ *
+ *   const log = createLogger("[server]");
+ *   log.info("listening on :3000");   // 12:34:56.789 INFO  [server] listening on :3000
+ *   log.debug("tick");                // only shown when level is "debug"
+ *   log.warn("slow query");           // yellow
+ *   log.error("connection failed");   // red, always shown
+ *
+ *   setLogLevel("debug");             // show everything
+ *
+ *   const handler = loggedRequest("[api]", myHandler);  // wrap a route with access logging
+ */
+
+export type LogLevel = "error" | "warn" | "info" | "debug";
+
+const LEVELS: Record<LogLevel, number> = { error: 0, warn: 1, info: 2, debug: 3 };
+
+let current: LogLevel =
+  (typeof process !== "undefined" && process.env?.LOG_LEVEL as LogLevel) || "info";
+
+export function setLogLevel(level: LogLevel) {
+  current = level;
+}
+
+export function getLogLevel(): LogLevel {
+  return current;
+}
+
+function shouldLog(level: LogLevel): boolean {
+  return LEVELS[current] >= LEVELS[level];
+}
+
+// === Colors ===
+
+const gray = (s: string) => `\x1b[90m${s}\x1b[0m`;
+const yellow = (s: string) => `\x1b[33m${s}\x1b[0m`;
+const red = (s: string) => `\x1b[31m${s}\x1b[0m`;
+const dim = (s: string) => `\x1b[2m${s}\x1b[0m`;
+
+const color: Record<LogLevel, (s: string) => string> = {
+  error: red,
+  warn: yellow,
+  info: gray,
+  debug: dim,
+};
+
+function timestamp() {
+  return new Date().toISOString().slice(11, 23);
+}
+
+function fmt(level: LogLevel, tag: string, msg: string) {
+  return `${gray(timestamp())} ${color[level](level.toUpperCase().padEnd(5))} ${tag} ${msg}`;
+}
+
+/** Create a tagged logger instance. */
+export function createLogger(tag: string) {
+  return {
+    info: (msg: string) => { if (shouldLog("info")) console.log(fmt("info", tag, msg)); },
+    warn: (msg: string) => { if (shouldLog("warn")) console.warn(fmt("warn", tag, msg)); },
+    error: (msg: string) => { console.error(fmt("error", tag, msg)); },
+    debug: (msg: string) => { if (shouldLog("debug")) console.log(fmt("debug", tag, msg)); },
+  };
+}
+
+type Handler = (req: Request) => Response | Promise<Response>;
+
+/** Wrap a route handler with access logging. */
+export function loggedRequest(tag: string, handler: Handler): Handler {
+  const log = createLogger(tag);
+  return async (req: Request) => {
+    const start = performance.now();
+    try {
+      const res = await handler(req);
+      const ms = (performance.now() - start).toFixed(1);
+      log.info(
+        `${req.method} ${new URL(req.url).pathname} → ${res.status} (${ms}ms)`,
+      );
+      return res;
+    } catch (err: any) {
+      const ms = (performance.now() - start).toFixed(1);
+      log.error(
+        `${req.method} ${new URL(req.url).pathname} threw (${ms}ms): ${err.message}`,
+      );
+      throw err;
+    }
+  };
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@blueshed/railroad",
+  "version": "0.2.0",
+  "description": "Signals, JSX, and routes — a micro UI framework for Bun",
+  "type": "module",
+  "main": "index.ts",
+  "types": "index.ts",
+  "exports": {
+    ".": "./index.ts",
+    "./signals": "./signals.ts",
+    "./jsx": "./jsx.ts",
+    "./routes": "./routes.ts",
+    "./shared": "./shared.ts",
+    "./jsx-runtime": "./jsx-runtime.ts",
+    "./jsx-dev-runtime": "./jsx-dev-runtime.ts"
+  },
+  "files": [
+    "*.ts",
+    "!*.test.ts",
+    "README.md",
+    "LICENSE",
+    ".claude/skills"
+  ],
+  "scripts": {
+    "check": "bunx tsc --noEmit",
+    "test": "bun test"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.11",
+    "typescript": "^5.9.3"
+  },
+  "author": "Peter Bunyan <peter@blueshed.co.uk> (https://blueshed.co.uk)",
+  "license": "MIT",
+  "homepage": "https://github.com/blueshed/railroad",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/blueshed/railroad"
+  },
+  "keywords": ["signals", "jsx", "router", "bun", "ui", "framework"]
+}

package/routes.ts

@@ -0,0 +1,110 @@
+/**
+ * Routes — Hash-based client router built on signals
+ *
+ * API:
+ *   routes(target, table)   — declarative hash router, swaps target content
+ *   route<T>(pattern)       — reactive route: Signal<T | null>, null when unmatched
+ *   navigate(path)          — set location.hash programmatically
+ *   matchRoute(pattern, path) — pure pattern matcher, returns params or null
+ *
+ * Handlers return a Node to render. The router manages cleanup automatically.
+ *   routes(app, {
+ *     "/":          () => <Home />,
+ *     "/site/:id":  ({ id }) => <SiteDetail id={id} />,
+ *   });
+ */
+
+import { Signal, computed, effect } from "./signals";
+import type { Dispose } from "./signals";
+import { pushDisposeScope, popDisposeScope } from "./jsx";
+
+let hashSignal: Signal<string> | null = null;
+
+function getHash(): Signal<string> {
+  if (!hashSignal) {
+    hashSignal = new Signal(location.hash.slice(1) || "/");
+    window.addEventListener("hashchange", () => {
+      hashSignal!.set(location.hash.slice(1) || "/");
+    });
+  }
+  return hashSignal;
+}
+
+export function matchRoute(
+  pattern: string,
+  path: string,
+): Record<string, string> | null {
+  const pp = pattern.split("/");
+  const hp = path.split("/");
+  if (pp.length !== hp.length) return null;
+  const params: Record<string, string> = {};
+  for (let i = 0; i < pp.length; i++) {
+    if (pp[i]!.startsWith(":")) {
+      try {
+        params[pp[i]!.slice(1)] = decodeURIComponent(hp[i]!);
+      } catch {
+        return null;
+      }
+    } else if (pp[i] !== hp[i]) return null;
+  }
+  return params;
+}
+
+export function route<
+  T extends Record<string, string> = Record<string, string>,
+>(pattern: string): Signal<T | null> {
+  const hash = getHash();
+  return computed(() => matchRoute(pattern, hash.get()) as T | null);
+}
+
+export function navigate(path: string): void {
+  location.hash = path;
+}
+
+type RouteHandler = (params: Record<string, string>) => Node;
+
+export function routes(
+  target: HTMLElement,
+  table: Record<string, RouteHandler>,
+): Dispose {
+  const hash = getHash();
+  let activePattern: string | null = null;
+  let activeDispose: Dispose | null = null;
+
+  function teardown() {
+    if (activeDispose) activeDispose();
+    activeDispose = null;
+    activePattern = null;
+    target.replaceChildren();
+  }
+
+  function run(handler: RouteHandler, params: Record<string, string>) {
+    pushDisposeScope();
+    const node = handler(params);
+    activeDispose = popDisposeScope();
+    target.appendChild(node);
+  }
+
+  return effect(() => {
+    const path = hash.get();
+    for (const [pattern, handler] of Object.entries(table)) {
+      const params = matchRoute(pattern, path);
+      if (params) {
+        if (pattern === activePattern) return;
+        teardown();
+        activePattern = pattern;
+        run(handler, params);
+        return;
+      }
+    }
+    if (table["*"]) {
+      if (activePattern !== "*") {
+        teardown();
+        activePattern = "*";
+        run(table["*"], {});
+      }
+      return;
+    }
+    teardown();
+  });
+}

package/shared.ts

@@ -0,0 +1,32 @@
+/**
+ * Shared — typed provide / inject for dependency sharing.
+ *
+ * Any module can provide a value under a typed key.
+ * Any other module can inject it without prop-threading.
+ *
+ *   const STORE = key<Store>("store");
+ *   provide(STORE, createStore());   // in home.ts
+ *   const store = inject(STORE);     // anywhere
+ */
+
+const registry = new Map<symbol, unknown>();
+
+export type Key<T> = symbol & { __brand: T };
+
+export function key<T>(name: string): Key<T> {
+  return Symbol(name) as Key<T>;
+}
+
+export function provide<T>(k: Key<T>, value: T): void {
+  registry.set(k, value);
+}
+
+export function inject<T>(k: Key<T>): T {
+  const v = registry.get(k);
+  if (v === undefined) throw new Error(`No provider for ${k.description}`);
+  return v as T;
+}
+
+export function tryInject<T>(k: Key<T>): T | undefined {
+  return registry.get(k) as T | undefined;
+}