@bromscandium/runtime 1.0.0

package/dist/vnode.js

@@ -0,0 +1,83 @@
+/**
+ * Virtual DOM node types and utilities.
+ * @module
+ */
+/** Symbol used to identify Fragment nodes (multiple children without a wrapper) */
+export const Fragment = Symbol('Fragment');
+/** Symbol used to identify Text nodes */
+export const Text = Symbol('Text');
+/**
+ * Creates a virtual DOM node.
+ *
+ * @param type - The node type (tag name, component, Fragment, or Text)
+ * @param props - Properties/attributes for the node
+ * @param children - Child nodes
+ * @returns A new virtual node
+ *
+ * @example
+ * ```ts
+ * const vnode = createVNode('div', { className: 'container' }, [
+ *   createVNode('span', null, ['Hello']),
+ *   createVNode('span', null, ['World'])
+ * ]);
+ * ```
+ */
+export function createVNode(type, props, children = []) {
+    const normalizedChildren = normalizeChildren(children);
+    return {
+        type,
+        props: props || {},
+        children: normalizedChildren,
+        key: props?.key ?? null,
+        el: null,
+        component: null,
+    };
+}
+/**
+ * Normalizes children into a flat array, filtering out invalid values.
+ * Handles nested arrays and removes nullish/boolean values from conditional rendering.
+ *
+ * @param children - The children to normalize
+ * @returns A flat array of valid children
+ */
+export function normalizeChildren(children) {
+    if (children == null) {
+        return [];
+    }
+    if (!Array.isArray(children)) {
+        children = [children];
+    }
+    return children.flat(Infinity).filter(child => {
+        return child != null && child !== false && child !== true && child !== '';
+    });
+}
+/**
+ * Creates a text virtual node.
+ *
+ * @param text - The text content
+ * @returns A virtual node representing text
+ *
+ * @example
+ * ```ts
+ * const textNode = createTextVNode('Hello, world!');
+ * ```
+ */
+export function createTextVNode(text) {
+    return {
+        type: Text,
+        props: {},
+        children: [String(text)],
+        key: null,
+        el: null,
+    };
+}
+/**
+ * Checks if a value is a virtual node.
+ *
+ * @param value - The value to check
+ * @returns True if the value is a VNode
+ */
+export function isVNode(value) {
+    return value != null && typeof value === 'object' && 'type' in value;
+}
+//# sourceMappingURL=vnode.js.map

package/dist/vnode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vnode.js","sourceRoot":"","sources":["../src/vnode.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,mFAAmF;AACnF,MAAM,CAAC,MAAM,QAAQ,GAAG,MAAM,CAAC,UAAU,CAAC,CAAC;AAE3C,yCAAyC;AACzC,MAAM,CAAC,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC;AAkEnC;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,WAAW,CACzB,IAAe,EACf,KAAiC,EACjC,WAA0B,EAAE;IAE5B,MAAM,kBAAkB,GAAG,iBAAiB,CAAC,QAAQ,CAAC,CAAC;IAEvD,OAAO;QACL,IAAI;QACJ,KAAK,EAAE,KAAK,IAAI,EAAE;QAClB,QAAQ,EAAE,kBAAkB;QAC5B,GAAG,EAAE,KAAK,EAAE,GAAG,IAAI,IAAI;QACvB,EAAE,EAAE,IAAI;QACR,SAAS,EAAE,IAAI;KAChB,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAAC,QAAuB;IACvD,IAAI,QAAQ,IAAI,IAAI,EAAE,CAAC;QACrB,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC7B,QAAQ,GAAG,CAAC,QAAQ,CAAC,CAAC;IACxB,CAAC;IAED,OAAO,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE;QAC5C,OAAO,KAAK,IAAI,IAAI,IAAI,KAAK,KAAK,KAAK,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,EAAE,CAAC;IAC5E,CAAC,CAAiB,CAAC;AACrB,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,eAAe,CAAC,IAAqB;IACnD,OAAO;QACL,IAAI,EAAE,IAAI;QACV,KAAK,EAAE,EAAE;QACT,QAAQ,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACxB,GAAG,EAAE,IAAI;QACT,EAAE,EAAE,IAAI;KACT,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,OAAO,CAAC,KAAU;IAChC,OAAO,KAAK,IAAI,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,IAAI,KAAK,CAAC;AACvE,CAAC"}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@bromscandium/runtime",
+  "version": "1.0.0",
+  "description": "BromiumJS runtime - JSX and rendering",
+  "author": "bromscandium",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bromscandium/bromiumjs.git",
+    "directory": "packages/runtime"
+  },
+  "homepage": "https://github.com/bromscandium/bromiumjs#readme",
+  "bugs": {
+    "url": "https://github.com/bromscandium/bromiumjs/issues"
+  },
+  "keywords": ["bromium", "bromiumjs", "jsx", "runtime", "rendering"],
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./jsx-runtime": {
+      "import": "./dist/jsx-runtime.js",
+      "types": "./dist/jsx-runtime.d.ts"
+    },
+    "./jsx-dev-runtime": {
+      "import": "./dist/jsx-runtime.js",
+      "types": "./dist/jsx-runtime.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch"
+  },
+  "dependencies": {
+    "@bromscandium/core": "^1.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  }
+}

package/src/env.d.ts

@@ -0,0 +1,11 @@
+/// <reference types="vite/client" />
+
+interface ImportMetaEnv {
+  readonly DEV: boolean;
+  readonly PROD: boolean;
+  readonly MODE: string;
+}
+
+interface ImportMeta {
+  readonly env: ImportMetaEnv;
+}

package/src/hooks.ts

@@ -0,0 +1,166 @@
+/**
+ * React-style hooks for state persistence across re-renders.
+ * @module
+ */
+
+import { ref, Ref } from '@bromscandium/core';
+import { getCurrentInstance } from './lifecycle.js';
+
+/**
+ * Creates a reactive state variable that persists across component re-renders.
+ * Similar to React's useState but returns a Ref for reactivity integration.
+ *
+ * @param initialValue - The initial value, or a function that returns the initial value
+ * @returns A reactive ref containing the state value
+ *
+ * @example
+ * ```ts
+ * function Counter() {
+ *   const count = useState(0);
+ *
+ *   return (
+ *     <button onClick={() => count.value++}>
+ *       Count: {count.value}
+ *     </button>
+ *   );
+ * }
+ *
+ * // With lazy initialization
+ * const expensive = useState(() => computeExpensiveValue());
+ * ```
+ */
+export function useState<T>(initialValue: T | (() => T)): Ref<T> {
+  const instance = getCurrentInstance();
+
+  if (!instance) {
+    const value = typeof initialValue === 'function'
+      ? (initialValue as () => T)()
+      : initialValue;
+    return ref(value);
+  }
+
+  const hookIndex = instance.hookIndex++;
+
+  if (hookIndex >= instance.hooks.length) {
+    const value = typeof initialValue === 'function'
+      ? (initialValue as () => T)()
+      : initialValue;
+    const stateRef = ref(value);
+    instance.hooks.push(stateRef);
+    return stateRef;
+  }
+
+  return instance.hooks[hookIndex];
+}
+
+/**
+ * Creates a mutable ref object that persists across re-renders without triggering updates.
+ * Useful for storing DOM references or mutable values that don't affect rendering.
+ *
+ * @param initialValue - The initial value for the ref
+ * @returns An object with a `current` property containing the value
+ *
+ * @example
+ * ```ts
+ * function TextInput() {
+ *   const inputRef = useRef<HTMLInputElement>(null);
+ *
+ *   onMounted(() => {
+ *     inputRef.current?.focus();
+ *   });
+ *
+ *   return <input ref={inputRef} />;
+ * }
+ *
+ * // Storing mutable values
+ * const renderCount = useRef(0);
+ * renderCount.current++; // Doesn't trigger re-render
+ * ```
+ */
+export function useRef<T>(initialValue: T): { current: T } {
+  const instance = getCurrentInstance();
+
+  if (!instance) {
+    return { current: initialValue };
+  }
+
+  const hookIndex = instance.hookIndex++;
+
+  if (hookIndex >= instance.hooks.length) {
+    instance.hooks.push({ current: initialValue });
+  }
+
+  return instance.hooks[hookIndex];
+}
+
+/**
+ * Memoizes an expensive computation, recalculating only when dependencies change.
+ *
+ * @param factory - A function that computes and returns the memoized value
+ * @param deps - An array of dependencies that trigger recalculation when changed
+ * @returns The memoized value
+ *
+ * @example
+ * ```ts
+ * function FilteredList({ items, filter }) {
+ *   const filtered = useMemo(
+ *     () => items.filter(item => item.includes(filter)),
+ *     [items, filter]
+ *   );
+ *
+ *   return <ul>{filtered.map(item => <li>{item}</li>)}</ul>;
+ * }
+ * ```
+ */
+export function useMemo<T>(factory: () => T, deps: any[]): T {
+  const instance = getCurrentInstance();
+
+  if (!instance) {
+    return factory();
+  }
+
+  const hookIndex = instance.hookIndex++;
+
+  if (hookIndex >= instance.hooks.length) {
+    instance.hooks.push({ value: factory(), deps });
+    return instance.hooks[hookIndex].value;
+  }
+
+  const hook = instance.hooks[hookIndex];
+  const depsChanged = !hook.deps || deps.some((dep, i) => dep !== hook.deps[i]);
+
+  if (depsChanged) {
+    hook.value = factory();
+    hook.deps = deps;
+  }
+
+  return hook.value;
+}
+
+/**
+ * Memoizes a callback function, returning the same reference until dependencies change.
+ * Useful for passing stable callbacks to child components to prevent unnecessary re-renders.
+ *
+ * @param callback - The callback function to memoize
+ * @param deps - An array of dependencies that trigger creating a new callback when changed
+ * @returns The memoized callback function
+ *
+ * @example
+ * ```ts
+ * function Parent() {
+ *   const [count, setCount] = useState(0);
+ *
+ *   const handleClick = useCallback(() => {
+ *     console.log('Clicked with count:', count);
+ *   }, [count]);
+ *
+ *   return <Child onClick={handleClick} />;
+ * }
+ * ```
+ */
+export function useCallback<T extends (...args: any[]) => any>(
+  callback: T,
+  deps: any[]
+): T {
+  return useMemo(() => callback, deps);
+}

package/src/index.ts

@@ -0,0 +1,56 @@
+// Runtime package exports
+
+// Type exports from vnode
+export type {
+  VNode,
+  VNodeChild,
+  VNodeChildren,
+  VNodeType,
+  ComponentFunction,
+  ComponentInstance,
+} from './vnode.js';
+
+// Value exports from vnode
+export {
+  Fragment,
+  Text,
+  createVNode,
+  normalizeChildren,
+  createTextVNode,
+  isVNode,
+} from './vnode.js';
+
+// Value exports from jsx-runtime
+export {
+  jsx,
+  jsxs,
+  jsxDEV,
+  createElement,
+  h,
+} from './jsx-runtime.js';
+
+// Type exports from jsx-runtime
+export type { JSXElement } from './jsx-runtime.js';
+
+export {
+  render,
+  createApp,
+} from './renderer.js';
+
+export type { AppConfig } from './renderer.js';
+
+export {
+  onMounted,
+  onUnmounted,
+  onUpdated,
+  getCurrentInstance,
+  setCurrentInstance,
+} from './lifecycle.js';
+
+// Hooks for state persistence
+export {
+  useState,
+  useRef,
+  useMemo,
+  useCallback,
+} from './hooks.js';

package/src/jsx-runtime.ts

@@ -0,0 +1,132 @@
+/**
+ * JSX Runtime for TypeScript/Vite.
+ * Configure in tsconfig.json: "jsx": "react-jsx", "jsxImportSource": "@bromscandium/runtime"
+ * @module
+ */
+
+import {createVNode, Fragment, VNode, VNodeType} from './vnode.js';
+
+export { Fragment };
+
+/**
+ * JSX element type alias for VNode.
+ */
+export interface JSXElement extends VNode {}
+
+/**
+ * Creates a virtual node from JSX syntax (React 17+ automatic runtime).
+ * This is called automatically by the TypeScript/Babel JSX transform.
+ *
+ * @param type - Element type (tag name or component function)
+ * @param props - Props object including children
+ * @param key - Optional key for list reconciliation
+ * @returns A virtual node
+ */
+export function jsx(
+  type: VNodeType,
+  props: Record<string, any> | null,
+  key?: string | number | null
+): VNode {
+  const { children, ...restProps } = props || {};
+
+  return createVNode(
+    type,
+    {...restProps, key: key ?? restProps?.key},
+    children
+  );
+}
+
+/**
+ * Creates a virtual node with static children (optimization hint).
+ * Functionally identical to jsx() but indicates children won't change.
+ *
+ * @param type - Element type (tag name or component function)
+ * @param props - Props object including children
+ * @param key - Optional key for list reconciliation
+ * @returns A virtual node
+ */
+export function jsxs(
+  type: VNodeType,
+  props: Record<string, any> | null,
+  key?: string | number | null
+): VNode {
+  return jsx(type, props, key);
+}
+
+/**
+ * Development version of jsx() with extra validation and warnings.
+ * Only performs validation when import.meta.env.DEV is true.
+ *
+ * @param type - Element type (tag name or component function)
+ * @param props - Props object including children
+ * @param key - Optional key for list reconciliation
+ * @param _isStatic - Unused static children hint
+ * @param _source - Source location for error messages
+ * @param _self - Component reference for error messages
+ * @returns A virtual node
+ */
+export function jsxDEV(
+  type: VNodeType,
+  props: Record<string, any> | null,
+  key?: string | number | null,
+  _isStatic?: boolean,
+  _source?: { fileName: string; lineNumber: number; columnNumber: number },
+  _self?: any
+): VNode {
+  if (import.meta.env?.DEV) {
+    if (typeof type === 'string' && type !== type.toLowerCase() && !type.includes('-')) {
+      console.warn(
+        `Invalid element type: "${type}". HTML elements must be lowercase. ` +
+        `Did you mean to use a component? Components should start with uppercase.`
+      );
+    }
+
+    if (props) {
+      if ('class' in props && !('className' in props)) {
+        console.warn(
+          `Invalid prop "class" detected. Use "className" instead.`
+        );
+      }
+    }
+  }
+
+  return jsx(type, props, key);
+}
+
+/**
+ * Creates a virtual node using classic createElement syntax.
+ * Use this for manual VNode creation without JSX.
+ *
+ * @param type - Element type (tag name or component function)
+ * @param props - Props object (without children)
+ * @param children - Child elements as rest parameters
+ * @returns A virtual node
+ *
+ * @example
+ * ```ts
+ * const vnode = createElement('div', { className: 'app' },
+ *   createElement('h1', null, 'Hello'),
+ *   createElement('p', null, 'World')
+ * );
+ * ```
+ */
+export function createElement(
+  type: VNodeType,
+  props: Record<string, any> | null,
+  ...children: any[]
+): VNode {
+  const normalizedProps = props || {};
+  const flatChildren = children.length === 1 ? children[0] : children;
+
+  return createVNode(type, normalizedProps, flatChildren);
+}
+
+/**
+ * Alias for createElement, providing a shorter hyperscript-style API.
+ *
+ * @example
+ * ```ts
+ * const vnode = h('div', { className: 'app' }, h('span', null, 'Hello'));
+ * ```
+ */
+export const h = createElement;