@getforma/core 0.2.0 → 0.3.1

package/README.md

@@ -4,7 +4,7 @@
 [![npm](https://img.shields.io/npm/v/@getforma/core)](https://www.npmjs.com/package/@getforma/core)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-Reactive DOM library with fine-grained signals, islands architecture, and SSR hydration. ~15KB gzipped.
+Reactive DOM library with fine-grained signals. No virtual DOM — `h()` creates real elements, signals update only what changed. ~15KB gzipped.
 
 ## Install
 
@@ -12,7 +12,71 @@ Reactive DOM library with fine-grained signals, islands architecture, and SSR hy
 npm install @getforma/core
 ```
 
-## Quick Start
+Or use the CDN (no build step required):
+
+```html
+<script src="https://unpkg.com/@getforma/core/dist/formajs-runtime.global.js"></script>
+```
+
+## Why FormaJS?
+
+Most UI libraries make you choose: simple but limited (Alpine, htmx), or powerful but complex (React, Vue, Svelte). FormaJS gives you a single reactive core that scales from a CDN script tag to a full-stack Rust SSR pipeline.
+
+**Design principles:**
+
+- **Real DOM, not virtual DOM.** `h('div')` returns an actual `HTMLDivElement`. Signals mutate it directly. No diffing pass, no reconciliation overhead for simple updates. Inspired by [Solid](https://www.solidjs.com/).
+- **Fine-grained reactivity.** Powered by [alien-signals](https://github.com/nicolo-ribaudo/alien-signals). When a signal changes, only the specific DOM text node or attribute that depends on it updates — not the whole component tree.
+- **Three entry points, one engine.** HTML Runtime (like Alpine — zero build step), `h()` hyperscript (like Preact), or JSX. All share the same signal graph. Pick the right tool for the job, upgrade without rewriting.
+- **CSP-safe capable.** The HTML Runtime includes a hand-written expression parser. The standard build enables `new Function()` as a fallback for complex expressions; the hardened build (`forma.hardened.js`) locks it off entirely for strict CSP environments.
+- **Islands over SPAs.** `activateIslands()` hydrates independent regions of server-rendered HTML. Each island is self-contained. Ship less JavaScript, keep server-rendered content instant.
+
+**What FormaJS is not:** It's not a framework with opinions about routing, data fetching, or state management patterns. It's a reactive DOM library. You bring the architecture.
+
+## Three Ways to Use FormaJS
+
+### 1. HTML Runtime (no build step)
+
+Drop a script tag, write `data-*` attributes. Zero config, zero tooling.
+
+```html
+<script src="https://unpkg.com/@getforma/core/dist/formajs-runtime.global.js"></script>
+
+<div data-forma-state='{"count": 0}'>
+  <p data-text="{count}"></p>
+  <button data-on:click="{count++}">+1</button>
+  <button data-on:click="{count = 0}">Reset</button>
+</div>
+```
+
+#### Supported Directives
+
+| Directive | Description | Example |
+|-----------|-------------|---------|
+| `data-forma-state` | Declare reactive state (JSON) | `data-forma-state='{"count": 0}'` |
+| `data-text` | Bind text content | `data-text="{count}"` |
+| `data-show` | Toggle visibility (display) | `data-show="{isOpen}"` |
+| `data-if` | Conditional render (add/remove from DOM) | `data-if="{loggedIn}"` |
+| `data-model` | Two-way binding (inputs) | `data-model="{email}"` |
+| `data-on:event` | Event handler | `data-on:click="{count++}"` |
+| `data-class:name` | Conditional CSS class | `data-class:active="{isActive}"` |
+| `data-bind:attr` | Dynamic attribute | `data-bind:href="{url}"` |
+| `data-list` | List rendering with keyed reconciliation | `data-list="{items}"` |
+| `data-computed` | Computed value | `data-computed="doubled = count * 2"` |
+| `data-persist` | Persist state to localStorage | `data-persist="{count}"` |
+| `data-fetch` | Fetch data from URL | `data-fetch="GET /api/items → items"` |
+| `data-transition:*` | Enter/leave CSS transitions | `data-transition:enter="fade-in"` |
+
+CSP-safe expression parser — no `eval()` or `new Function()` by default. For strict CSP environments, use the hardened build:
+
+```html
+<script src="https://unpkg.com/@getforma/core/dist/formajs-runtime-hardened.global.js"></script>
+```
+
+### 2. Hyperscript — `h()`
+
+```bash
+npm install @getforma/core
+```
 
 ```typescript
 import { createSignal, h, mount } from '@getforma/core';
@@ -27,21 +91,209 @@ mount(() =>
 );
 ```
 
-## Features
+### 3. JSX
+
+Same `h()` function, JSX syntax. Configure your bundler:
+
+```json
+// tsconfig.json
+{
+  "compilerOptions": {
+    "jsx": "react",
+    "jsxFactory": "h",
+    "jsxFragmentFactory": "Fragment"
+  }
+}
+```
+
+```tsx
+import { createSignal, h, Fragment, mount } from '@getforma/core';
+
+const [count, setCount] = createSignal(0);
+
+function Counter() {
+  return (
+    <>
+      <p>{() => `Count: ${count()}`}</p>
+      <button onClick={() => setCount(count() + 1)}>+1</button>
+    </>
+  );
+}
+
+mount(() => <Counter />, '#app');
+```
+
+## CDN Usage
+
+### Standard (recommended)
+```html
+<script src="https://unpkg.com/@getforma/core/dist/forma-runtime.js"></script>
+```
+
+### CSP-Safe (strict Content-Security-Policy)
+```html
+<script src="https://unpkg.com/@getforma/core/dist/forma-runtime-csp.js"></script>
+```
+
+> The CSP build uses a hand-written expression parser and never calls `new Function`.
+> It supports most common patterns. See [examples/csp](./examples/csp) for a working demo.
+
+## Core API
+
+### Signals
+
+```typescript
+import { createSignal, createEffect, createComputed, batch } from '@getforma/core';
+
+const [count, setCount] = createSignal(0);
+const doubled = createComputed(() => count() * 2);
+
+createEffect(() => console.log('count:', count()));
+
+batch(() => {
+  setCount(1);
+  setCount(2); // effect fires once with value 2
+});
+```
+
+### Conditional Rendering
+
+```typescript
+import { createSignal, createShow, createSwitch, h } from '@getforma/core';
+
+const [loggedIn, setLoggedIn] = createSignal(false);
+
+// createShow — toggle between two branches
+createShow(loggedIn,
+  () => h('p', null, 'Welcome back'),
+  () => h('p', null, 'Please sign in'),
+);
+
+// createSwitch — multi-branch with caching
+const [view, setView] = createSignal('home');
+createSwitch(view, [
+  { match: 'home', render: () => h('div', null, 'Home') },
+  { match: 'settings', render: () => h('div', null, 'Settings') },
+], () => h('div', null, '404 Not Found'));
+```
+
+### List Rendering
+
+```typescript
+import { createSignal, createList, h } from '@getforma/core';
+
+const [items, setItems] = createSignal([
+  { id: 1, name: 'Alice' },
+  { id: 2, name: 'Bob' },
+]);
+
+createList(
+  items,
+  (item) => item.id,  // key function
+  (item) => h('li', null, item.name),
+);
+```
+
+### Store (deep reactivity)
+
+```typescript
+import { createStore } from '@getforma/core';
+
+const [state, setState] = createStore({
+  user: { name: 'Alice', prefs: { theme: 'dark' } },
+  items: [1, 2, 3],
+});
+
+// Read reactively
+state.user.name;        // 'Alice'
+
+// Mutate — only affected subscribers update
+setState('user', 'name', 'Bob');
+setState('items', items => [...items, 4]);
+```
+
+### Components
+
+```typescript
+import { defineComponent, onMount, onUnmount, h } from '@getforma/core';
+
+const Timer = defineComponent(() => {
+  const [seconds, setSeconds] = createSignal(0);
+
+  onMount(() => {
+    const id = setInterval(() => setSeconds(s => s + 1), 1000);
+    return () => clearInterval(id); // cleanup on unmount
+  });
+
+  return h('span', null, () => `${seconds()}s`);
+});
+
+document.body.appendChild(Timer());
+```
+
+### Context (Dependency Injection)
+
+```typescript
+import { createContext, provide, inject } from '@getforma/core';
+
+const ThemeCtx = createContext('light');
+
+provide(ThemeCtx, 'dark');
+const theme = inject(ThemeCtx); // 'dark'
+```
+
+## Islands Architecture
+
+For server-rendered HTML, activate independent interactive regions:
+
+```typescript
+import { activateIslands, createSignal, h } from '@getforma/core';
+
+activateIslands({
+  Counter: (el, props) => {
+    const [count, setCount] = createSignal(props.initial ?? 0);
+    // Hydrate: attach reactivity to existing server-rendered DOM
+  },
+});
+```
+
+```html
+<!-- Server-rendered HTML -->
+<div data-forma-island="Counter" data-forma-props='{"initial": 5}'>
+  <span>5</span>
+  <button>+1</button>
+</div>
+```
+
+## Subpath Exports
+
+| Import | Description |
+|--------|-------------|
+| `@getforma/core` | Signals, `h()`, `mount()`, lists, stores, components |
+| `@getforma/core/runtime` | HTML Runtime — `initRuntime()`, `mount()`, `unmount()` |
+| `@getforma/core/runtime/global` | HTML Runtime global build (IIFE, for `<script>` tags) |
+| `@getforma/core/runtime-hardened` | Runtime with `new Function()` locked off (strict CSP) |
+| `@getforma/core/runtime-csp` | Alias for `runtime-hardened` (CSP-safe build) |
+| `@getforma/core/runtime-csp/global` | CSP-safe global build (IIFE, for `<script>` tags) |
+| `@getforma/core/ssr` | Server-side rendering — `renderToString()`, `renderToStream()` |
+| `@getforma/core/tc39` | TC39-compatible `Signal.State` and `Signal.Computed` classes |
+
+## Examples
+
+See the [`examples/`](./examples) directory:
 
-- **Real DOM** — `h()` creates actual DOM elements with reactive bindings. No virtual DOM, no diffing overhead.
-- **Fine-grained reactivity** — signals, effects, computed values via alien-signals. Only what changed updates.
-- **Islands architecture** — `activateIslands()` for independent hydration of server-rendered HTML regions.
-- **SSR hydration** — `adoptNode()` walks server-rendered DOM and attaches reactive bindings without re-creating elements.
-- **Conditional rendering** — `createShow()`, `createSwitch()` with branch caching for O(1) toggle.
-- **List rendering** — `createList()` with LIS-based keyed reconciliation, handles 50K+ rows.
-- **State management** — `createStore()` with deep reactivity, history, persistence.
+- **counter** — minimal `h()` counter
+- **counter-jsx** — same counter with JSX syntax
+- **csp** — CSP-safe runtime with strict Content-Security-Policy meta tag
+- **todo** — todo list with `createList` and keyed reconciliation
+- **data-table** — sortable table with `createList`
 
 ## Ecosystem
 
-- [forma](https://github.com/getforma-dev/forma) — Rust server framework (forma-ir + forma-server)
-- [forma-tools](https://github.com/getforma-dev/forma-tools) — Build tooling (@getforma/compiler + @getforma/build)
-- [create-forma-app](https://github.com/getforma-dev/create-forma-app) — CLI scaffolder
+| Package | Description |
+|---------|-------------|
+| [@getforma/core](https://www.npmjs.com/package/@getforma/core) | This library — `npm install @getforma/core` |
+| [forma](https://github.com/getforma-dev/forma) | Rust server framework (forma-ir + forma-server) |
 
 ## License
 

package/dist/{chunk-VKKPX4YU.js → chunk-5H52PKGF.js}

@@ -21,7 +21,7 @@ function createRoot(fn) {
     return fn(dispose);
   } finally {
     currentRoot = rootStack.pop() ?? null;
-    if (rootStack.length === 0 && rootStack.length !== rootStack.__capacity) {
+    if (rootStack.length === 0) {
       rootStack.length = 0;
     }
   }
@@ -562,8 +562,47 @@ function handleEvent(el, key, value2) {
   );
 }
 function handleInnerHTML(el, _key, value2) {
-  const v = value2;
-  el.innerHTML = v.__html;
+  if (typeof value2 === "function") {
+    internalEffect(() => {
+      const resolved = value2();
+      if (resolved == null) {
+        el.innerHTML = "";
+        return;
+      }
+      if (typeof resolved !== "object" || !("__html" in resolved)) {
+        throw new TypeError(
+          "dangerouslySetInnerHTML: expected { __html: string }, got " + typeof resolved
+        );
+      }
+      const html = resolved.__html;
+      if (typeof html !== "string") {
+        throw new TypeError(
+          "dangerouslySetInnerHTML: __html must be a string, got " + typeof html
+        );
+      }
+      const cache = getCache(el);
+      if (cache["innerHTML"] === html) return;
+      cache["innerHTML"] = html;
+      el.innerHTML = html;
+    });
+  } else {
+    if (value2 == null) {
+      el.innerHTML = "";
+      return;
+    }
+    if (typeof value2 !== "object" || !("__html" in value2)) {
+      throw new TypeError(
+        "dangerouslySetInnerHTML: expected { __html: string }, got " + typeof value2
+      );
+    }
+    const html = value2.__html;
+    if (typeof html !== "string") {
+      throw new TypeError(
+        "dangerouslySetInnerHTML: __html must be a string, got " + typeof html
+      );
+    }
+    el.innerHTML = html;
+  }
 }
 function handleXLink(el, key, value2) {
   const localName = key.slice(6);
@@ -685,7 +724,18 @@ function applyStaticProp(el, key, value2) {
     return;
   }
   if (key === "dangerouslySetInnerHTML") {
-    el.innerHTML = value2.__html;
+    if (typeof value2 !== "object" || !("__html" in value2)) {
+      throw new TypeError(
+        "dangerouslySetInnerHTML: expected { __html: string }, got " + typeof value2
+      );
+    }
+    const html = value2.__html;
+    if (typeof html !== "string") {
+      throw new TypeError(
+        "dangerouslySetInnerHTML: __html must be a string, got " + typeof html
+      );
+    }
+    el.innerHTML = html;
     return;
   }
   if (key.charCodeAt(0) === 120 && key.startsWith("xlink:")) {
@@ -843,10 +893,10 @@ function createShow(when, thenFn, elseFn) {
   let currentNode = null;
   let lastTruthy = null;
   let currentDispose = null;
-  const DEBUG_LABEL = thenFn.toString().slice(0, 60);
   const showDispose = internalEffect(() => {
     const truthy = !!when();
     const DEBUG = typeof globalThis.__FORMA_DEBUG__ !== "undefined";
+    const DEBUG_LABEL = DEBUG ? thenFn.toString().slice(0, 60) : "";
     if (truthy === lastTruthy) {
       if (DEBUG) console.log("[forma:show] skip (same)", truthy, DEBUG_LABEL);
       return;
@@ -903,13 +953,13 @@ function setHydrating(value2) {
   hydrating = value2;
 }
 function isDescriptor(v) {
-  return v != null && typeof v === "object" && v.type === "element";
+  return v != null && typeof v === "object" && "type" in v && v.type === "element";
 }
 function isShowDescriptor(v) {
-  return v != null && typeof v === "object" && v.type === "show";
+  return v != null && typeof v === "object" && "type" in v && v.type === "show";
 }
 function isListDescriptor(v) {
-  return v != null && typeof v === "object" && v.type === "list";
+  return v != null && typeof v === "object" && "type" in v && v.type === "list";
 }
 function applyDynamicProps(el, props) {
   if (!props) return;
@@ -1087,7 +1137,7 @@ function adoptBranchContent(desc, regionStart, regionEnd) {
 }
 function adoptNode(desc, ssrEl) {
   if (!ssrEl || ssrEl.tagName !== desc.tag.toUpperCase()) {
-    console.warn(`Hydration mismatch: expected <${desc.tag}>, got <${ssrEl?.tagName?.toLowerCase() ?? "nothing"}>`);
+    if (__DEV__) console.warn(`Hydration mismatch: expected <${desc.tag}>, got <${ssrEl?.tagName?.toLowerCase() ?? "nothing"}>`);
     const fresh = descriptorToElement(desc);
     if (ssrEl) ssrEl.replaceWith(fresh);
     return;
@@ -1754,6 +1804,6 @@ function createList(items, keyFn, renderFn, options) {
   return fragment2;
 }
 
-export { Fragment, batch, cleanup, createEffect, createList, createMemo, createReducer, createRef, createResource, createRoot, createShow, fragment, h, hydrateIsland, internalEffect, longestIncreasingSubsequence, on, onCleanup, onError, popSuspenseContext, pushSuspenseContext, reconcileList, untrack };
-//# sourceMappingURL=chunk-VKKPX4YU.js.map
-//# sourceMappingURL=chunk-VKKPX4YU.js.map
+export { Fragment, __DEV__, batch, cleanup, createEffect, createList, createMemo, createReducer, createRef, createResource, createRoot, createShow, fragment, h, hydrateIsland, internalEffect, longestIncreasingSubsequence, on, onCleanup, onError, popSuspenseContext, pushSuspenseContext, reconcileList, untrack };
+//# sourceMappingURL=chunk-5H52PKGF.js.map
+//# sourceMappingURL=chunk-5H52PKGF.js.map