ranui 0.2.0-alpha.7 → 0.2.1-alpha.1

package/docs/BUILDER.md

@@ -0,0 +1,230 @@
+# ranui Builder — fluent DOM + fine-grained reactivity
+
+`ranui/builder` is a framework-free way to build DOM declaratively with
+SwiftUI/Solid-style fine-grained reactivity. No virtual DOM, no re-render of a
+whole tree — a signal change updates only the exact node bound to it.
+
+```ts
+import {
+  View,
+  Div,
+  Span,
+  ButtonBuilder, // element factories
+  signal,
+  computed,
+  createEffect,
+  batch,
+  untrack, // reactivity
+  createRoot,
+  onCleanup,
+  getOwner,
+  runWithOwner, // ownership
+  EventManager, // lifecycle-scoped events
+} from 'ranui/builder';
+```
+
+The builder does **not** register custom elements. To use `<r-button>` etc.,
+also import the component subpath once: `import 'ranui/button'`.
+
+---
+
+## 1. Elements
+
+Factories return an `ElementBuilder` (chainable). `build()` returns the DOM node.
+
+```ts
+const box = Div().class('card').text('hi').build();
+
+const submit = View('r-button') // any tag, incl. custom elements
+  .attr('type', 'primary')
+  .text('Save')
+  .on('click', onSave)
+  .build();
+```
+
+Factories: `View(tag)`, `Div`, `Span`, `Slot`, `ButtonBuilder`, `InputBuilder`,
+`Label`, `Ul`, `Li`, `Section`, `Article`, `Nav`, `Header`, `Footer`, `Main`,
+`Style`, `DeclarativeShadow`. For anything else use `View('tag')`.
+
+### Chainable API
+
+| Group          | Methods                                                                                                     |
+| -------------- | ----------------------------------------------------------------------------------------------------------- |
+| Identity/class | `id(v)`, `class(v)`, `addClass(...v)`, `removeClass(...v)`                                                  |
+| Attributes     | `attr(name, v)`, `attrs({...})`, `boolAttr(name, on, enabledValue?)`, `part(v)`, `data(key, v)`             |
+| Style          | `style(prop, v)` / `style({...})`, `cssVar(name, v)`                                                        |
+| A11y           | `aria(key, v)`, `role(v)`, `tabIndex(n)`, `label(v)`, `labelledBy(id)`, `describedBy(id)`, `ariaHidden(b?)` |
+| Content        | `text(v)`, `children(...nodes)`, `replaceChildren(...nodes)`                                                |
+| Refs/shadow    | `ref(holder)`, `shadow(opts?)` → `ShadowBuilder`                                                            |
+| Terminal       | `build()`, `serialize()` (SSR HTML string)                                                                  |
+
+`children()` accepts elements, strings, other `ElementBuilder`s, arrays, and
+`null`/`undefined` (skipped) — nest freely:
+
+```ts
+Ul()
+  .class('list')
+  .children(
+    items.map((it) => Li().text(it.name)),
+    extra && Li().text('extra'),
+  )
+  .build();
+```
+
+### Events
+
+```ts
+.on(type, handler, options?)      // permanent listener (element lifetime)
+.listen(manager, type, handler)   // lifecycle-managed (removed via manager.abort())
+.delegate(manager, selector, type, handler) // event delegation on a container
+```
+
+---
+
+## 2. Reactivity
+
+```ts
+const [count, setCount] = signal(0);
+count(); // read (tracked inside effects/memos)
+setCount(1); // write; setCount(n => n + 1) also works
+setCount(1); // no-op if unchanged (Object.is; override via signal(v, { equals }))
+
+const double = computed(() => count() * 2); // LAZY + memoized: recomputes only
+double(); // when read after a dep changed
+// A memo re-notifies its readers only when its VALUE changes (override the
+// comparison via computed(fn, { equals })), so effects behind a stable memo sleep.
+
+const dispose = createEffect(() => {
+  // runs now + on every dependency change
+  console.log(count());
+  return () => {
+    /* optional cleanup, runs before re-run and on dispose */
+  };
+});
+
+batch(() => {
+  setCount(1);
+  setName('x');
+}); // one flush, effects deduped
+untrack(() => count()); // read without subscribing
+```
+
+- **`computed` is lazy** — an unread memo never recomputes. Diamond dependencies
+  run a dependent effect **once** per change, not once per path.
+- **Effects auto-track**: only signals actually read on the latest run are
+  subscribed (conditionals never leave stale subscriptions).
+- **Cyclic guard**: an effect that writes a signal it reads throws instead of
+  looping forever.
+
+### Reactive bindings
+
+Any of `text`, `attr`, `class`, `boolAttr`, `style`, `part`, `data`, `aria`,
+`role`, `label` accepts a **getter** — pass a signal (or `computed`) and the
+attribute/text updates itself, no manual effect:
+
+```ts
+const [label, setLabel] = signal('Connect');
+const btn = View('r-button').text(label).build(); // updates when setLabel(...) runs
+
+const [active, setActive] = signal(true);
+Div()
+  .class(() => (active() ? 'row active' : 'row')) // recomputes on toggle
+  .boolAttr('disabled', () => !active())
+  .build();
+```
+
+A getter binding creates an effect **owned by the current scope** (see below), so
+it is cleaned up automatically when that scope is disposed. Reactivity applies to
+the single-value forms — `style(prop, getter)`, not the `style({...})` /
+`attrs({...})` map forms, which apply once. A getter dropped into a map is called
+once and never re-runs.
+
+---
+
+## 3. Ownership — the key to leak-free apps (and MPAs)
+
+Every effect/memo (including reactive bindings) is owned by the scope that
+created it. Disposing a scope disposes everything under it — nested effects,
+bindings, and `onCleanup` callbacks.
+
+```ts
+import { createRoot, onCleanup } from 'ranui/builder';
+
+const dispose = createRoot((dispose) => {
+  const el = Div().text(msg).build(); // this binding is owned by the root
+  onCleanup(() => console.log('torn down'));
+  mount(el);
+  return dispose;
+});
+
+// later:
+dispose(); // removes the binding's effect + runs cleanups
+```
+
+Build reactive UI **inside a `createRoot`**. Bindings created with no owner still
+work but won't auto-dispose (dispose them manually).
+
+> **Inside a Web Component?** A component's `constructor`/`connectedCallback` are
+> _not_ reactive scopes, so a getter binding or `createEffect` created there is
+> orphaned (never disposed). Don't use getter bindings in component code — build
+> with plain values and drive updates with explicit `createEffect`s whose dispose
+> functions you collect and call in `disconnectedCallback`, re-arming on reconnect.
+> See the ranui component guide (`CLAUDE.md` → "Using reactivity inside a component").
+
+### Multi-page / SPA pattern
+
+Give each page/route its own root and dispose it on navigation — every effect,
+binding, timer, and listener that page created is torn down in one call:
+
+```ts
+let disposePage: (() => void) | null = null;
+
+function showPage(render: (host: HTMLElement) => void, host: HTMLElement) {
+  disposePage?.(); // tear down the previous page
+  disposePage = createRoot((dispose) => {
+    render(host); // effects/bindings register to this root
+    return dispose;
+  });
+}
+```
+
+ranui's `<r-route>` has this built in. Two modes:
+
+- **Static (default)** — slotted content, shown/hidden by URL; all routes stay in
+  the DOM (great for SSG — every page is pre-rendered): `<r-route path="/a">…</r-route>`.
+- **Lazy (`src`)** — code-split, mount on match / unmount on leave:
+  `<r-route path="/a" src="/pages/a.js">`. On match the module is dynamically
+  imported and its `default: (host) => void | (() => void)` render runs **inside a
+  `createRoot`**; on leave that root is disposed — every effect, binding, and
+  `onCleanup` the page registered is torn down automatically. The per-page-lifecycle
+  mode for larger multi-page apps (client-rendered).
+
+`getOwner()` / `runWithOwner()` let a router capture and restore a scope across
+async boundaries.
+
+---
+
+## 4. Web-component listeners — `EventManager`
+
+For listeners inside a custom element, use `EventManager` (backed by
+`AbortController`) so `disconnectedCallback` removes them all at once:
+
+```ts
+private events = new EventManager();
+connectedCallback() {
+  this.events
+    .on(this.input, 'input', this.onInput)
+    .delegate(this, '[data-action]', 'click', (e, el) => this.run(el.dataset.action));
+}
+disconnectedCallback() { this.events.abort(); } // resets for the next connect
+```
+
+---
+
+## Notes
+
+- **SSR**: builders work under `defineSSR` / `renderToString`; `build()` returns a
+  mock node, `serialize()` returns HTML. Reactive bindings run once during SSR.
+- **Components vs builder**: use registered `<r-*>` elements (see
+  [COMPONENTS.md](./COMPONENTS.md)) for rich widgets; use the builder for
+  layout/glue and reactive views. Theme tokens: [DESIGN.md](./DESIGN.md).

package/docs/COMPONENTS.md

@@ -6,7 +6,7 @@ shape), slots, and `::part()` names — extracted from source. For CSS variables
 (theming tokens) see [style-tokens-public.md](./style-tokens-public.md); for
 design rules see [DESIGN.md](./DESIGN.md).
 
-Generated at: 2026-07-11T05:42:36.629Z
+Generated at: 2026-07-12T08:47:20.080Z
 
 30 custom elements.
 
@@ -110,6 +110,19 @@ Source: `components/icon/index.ts`
 - **Slots**: —
 - **Parts**: `ran-icon`
 
+> **Requires registration.** `<r-icon>` has no built-in icon set — it renders only SVGs
+> registered into its in-memory registry, so `<r-icon name="lock">` is **blank** until `lock`
+> is registered. Register once, in the browser, before the first `<r-icon>` connects:
+>
+> ```ts
+> import { registerBuiltinIcons } from 'ranui'; // or 'ranui/icons'
+> registerBuiltinIcons(); // registers every name in RAN_ICON_NAMES
+> ```
+>
+> For a custom set, call `registerIcon(name, svgString)` / `registerIcons({ … })`, or pass raw
+> SVG markup straight to `name` (rendered as-is when it starts with `<svg`). Valid bundled
+> names are the `RanIconName` union / `RAN_ICON_NAMES` tuple.
+
 ## `<r-img>`
 
 Source: `components/image/index.ts`
@@ -251,8 +264,13 @@ Source: `components/radar/index.ts`
 
 Source: `components/route/index.ts`
 
-- **Attributes**: `exact: boolean`, `path: string`, `sheet: string`
-- **Properties**: `exact: boolean`, `params: Record<string, string>`, `path: string`, `sheet: string`
+- **Attributes**: `exact: boolean`, `path: string`, `sheet: string`, `src: string`
+- **Properties**:
+  - `exact: boolean`
+  - `params: Record<string, string>`
+  - `path: string`
+  - `sheet: string`
+  - `src: string` — A lazy page module's default export: render into `host`, optionally return a cleanup. */
 - **Events**: `routematch` → detail `{ params, path }`
 - **Slots**: `default`
 - **Parts**: —

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ranui",
-  "version": "0.2.0-alpha.7",
+  "version": "0.2.1-alpha.1",
   "description": "A framework-agnostic Web Components UI library built on native custom elements, with TypeScript types, light/dark theming, SSR and PWA support.",
   "main": "dist/index.cjs",
   "module": "dist/index.js",
@@ -50,6 +50,7 @@
     "typings.d.ts",
     "docs/DESIGN.md",
     "docs/COMPONENTS.md",
+    "docs/BUILDER.md",
     "docs/style-tokens-public.md"
   ],
   "keywords": [
@@ -114,6 +115,11 @@
       "import": "./dist/icon.js",
       "require": "./dist/index.cjs"
     },
+    "./icons": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/icons.js",
+      "require": "./dist/index.cjs"
+    },
     "./image": {
       "types": "./dist/index.d.ts",
       "import": "./dist/image.js",
@@ -209,6 +215,21 @@
       "import": "./dist/card.js",
       "require": "./dist/index.cjs"
     },
+    "./form": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/form.js",
+      "require": "./dist/index.cjs"
+    },
+    "./scratch": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/scratch.js",
+      "require": "./dist/index.cjs"
+    },
+    "./section": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/section.js",
+      "require": "./dist/index.cjs"
+    },
     "./router": {
       "types": "./dist/index.d.ts",
       "import": "./dist/router.js",
@@ -246,7 +267,7 @@
     }
   },
   "devDependencies": {
-    "@argos-ci/playwright": "^7.3.0",
+    "@argos-ci/playwright": "^7.3.5",
     "@playwright/test": "^1.61.1",
     "@types/node": "^26.1.1",
     "@vitest/coverage-v8": "^4.1.10",
@@ -254,8 +275,9 @@
     "less": "^4.6.7",
     "rollup-plugin-visualizer": "^7.0.1",
     "svgo": "^4.0.1",
+    "terser": "^5.49.0",
     "tsx": "^4.23.0",
-    "typescript": "^6.0.3",
+    "typescript": "^7.0.2",
     "vite": "^8.1.4",
     "vitest": "^4.1.10"
   },

package/dist/factory-BdsO0dEW.js

@@ -1,165 +0,0 @@
-import { c as l, n as d } from "./mocks-CMGoftIc.js";
-var p = () => ({ current: null }), o = class h {
-  el;
-  constructor(t) {
-    this.el = l ? new d(t) : document.createElement(t);
-  }
-  id(t) {
-    return this.el.setAttribute("id", t), this;
-  }
-  class(t) {
-    return l ? this.el.attributes.set("class", t) : this.el.className = t, this;
-  }
-  addClass(...t) {
-    return t.forEach((e) => this.el.classList.add(e)), this;
-  }
-  removeClass(...t) {
-    return t.forEach((e) => this.el.classList.remove(e)), this;
-  }
-  attr(t, e) {
-    return this.el.setAttribute(t, e), this;
-  }
-  attrs(t) {
-    return Object.entries(t).forEach(([e, r]) => {
-      r != null && this.el.setAttribute(e, String(r));
-    }), this;
-  }
-  boolAttr(t, e, r = "") {
-    return e ? this.el.setAttribute(t, r) : this.el.removeAttribute(t), this;
-  }
-  part(t) {
-    return this.el.setAttribute("part", t), this;
-  }
-  data(t, e) {
-    return this.attr(`data-${t}`, e);
-  }
-  style(t, e) {
-    return typeof t == "string" ? this.el.style.setProperty(t, e ?? "") : Object.entries(t).forEach(([r, a]) => this.el.style.setProperty(r, a)), this;
-  }
-  cssVar(t, e) {
-    const r = t.startsWith("--") ? t : `--${t}`;
-    return this.style(r, e);
-  }
-  aria(t, e) {
-    return this.attr(`aria-${t}`, e);
-  }
-  role(t) {
-    return this.attr("role", t);
-  }
-  tabIndex(t) {
-    return this.attr("tabindex", String(t));
-  }
-  label(t) {
-    return this.aria("label", t);
-  }
-  labelledBy(t) {
-    return this.aria("labelledby", t);
-  }
-  describedBy(t) {
-    return this.aria("describedby", t);
-  }
-  ariaHidden(t = !0) {
-    return this.aria("hidden", String(t));
-  }
-  on(t, e, r) {
-    return this.el.addEventListener(t, e, r), this;
-  }
-  listen(t, e, r, a) {
-    return t.on(this.el, e, r, a), this;
-  }
-  delegate(t, e, r, a, n) {
-    return t.delegate(this.el, e, r, a, n), this;
-  }
-  children(...t) {
-    const e = (r) => r.reduce((a, n) => Array.isArray(n) ? a.concat(e(n)) : a.concat(n), []);
-    return e(t).forEach((r) => {
-      r != null && (r instanceof h ? this.el.appendChild(r.build()) : typeof r == "string" ? l ? this.el.appendChild(r) : this.el.appendChild(document.createTextNode(r)) : this.el.appendChild(r));
-    }), this;
-  }
-  replaceChildren(...t) {
-    if (l) {
-      const e = this.el;
-      e.childrenList = [];
-    } else this.el.replaceChildren();
-    return this.children(...t);
-  }
-  text(t) {
-    return this.el.textContent = t, this;
-  }
-  ref(t) {
-    return t.current = this.el, this;
-  }
-  shadow(t = { mode: "closed" }) {
-    const e = this.el.attachShadow(t);
-    return new u(this.el, e, t);
-  }
-  build() {
-    return this.el;
-  }
-  serialize() {
-    if (l) return this.el.serialize();
-    const t = document.createElement("div");
-    return t.appendChild(this.el.cloneNode(!0)), t.innerHTML;
-  }
-}, u = class {
-  root;
-  hostEl;
-  options;
-  constructor(i, t, e) {
-    this.hostEl = i, this.root = t, this.options = e;
-  }
-  children(...i) {
-    const t = (e) => e.reduce((r, a) => Array.isArray(a) ? r.concat(t(a)) : r.concat(a), []);
-    return t(i).forEach((e) => {
-      e != null && (e instanceof o ? this.root.appendChild(e.build()) : typeof e == "string" ? l ? this.root.appendChild(e) : this.root.appendChild(document.createTextNode(e)) : this.root.appendChild(e));
-    }), this;
-  }
-  adoptSheet(...i) {
-    return this.root.adoptedStyleSheets = [...this.root.adoptedStyleSheets, ...i], this;
-  }
-  css(i) {
-    if (l)
-      return this.root.adoptedStyleSheets.push(i), this;
-    if (typeof CSSStyleSheet < "u") try {
-      const e = new CSSStyleSheet();
-      return e.replaceSync(i), this.root.adoptedStyleSheets = [...this.root.adoptedStyleSheets, e], this;
-    } catch {
-    }
-    const t = document.createElement("style");
-    return t.textContent = i, this.root.appendChild(t), this;
-  }
-  done() {
-    return {
-      host: this.hostEl,
-      shadow: this.root
-    };
-  }
-  serialize() {
-    return l ? this.root.serialize() : this.root.innerHTML;
-  }
-}, s = (i) => new o(i), f = () => s("div"), S = () => s("span"), y = () => s("slot"), b = () => s("button"), v = () => s("input"), C = () => s("style"), E = () => s("label"), w = () => s("ul"), A = () => s("li"), g = () => s("section"), L = () => s("article"), B = () => s("nav"), m = () => s("header"), x = () => s("footer"), H = () => s("main"), N = (i = "open", t = !1) => {
-  const e = s("template");
-  return e.attr("shadowrootmode", i), t && e.attr("shadowrootdelegatesfocus", ""), e;
-};
-export {
-  s as _,
-  x as a,
-  p as b,
-  E as c,
-  B as d,
-  g as f,
-  w as g,
-  C as h,
-  f as i,
-  A as l,
-  S as m,
-  b as n,
-  m as o,
-  y as p,
-  N as r,
-  v as s,
-  L as t,
-  H as u,
-  o as v,
-  u as y
-};

package/dist/route-MQZpn2BP.js

@@ -1,88 +0,0 @@
-import { a as p, i as o, n as l, r as n, t as d } from "./utils-DBfrRFoE.js";
-import { t as m } from "./events-C59wGdni.js";
-import { p as f } from "./factory-BdsO0dEW.js";
-import { a as _, n as b } from "./ssr-DSGwPtEd.js";
-import { getSSGPath as g } from "./utils/router.js";
-var v = ".remove-wap-active-focus{outline:0;-webkit-tap-highlight-color:transparent}.remove-wap-active-focus:active,.remove-wap-active-focus:focus{outline:0;-webkit-tap-highlight-color:transparent}:host{display:block}:host([hidden]){display:none!important}", w = class extends b {
-  static get observedAttributes() {
-    return [
-      "path",
-      "exact",
-      "sheet"
-    ];
-  }
-  _events = new m();
-  _shadowDom;
-  _params = {};
-  constructor() {
-    super(), this._shadowDom = l(this, v), d(this._shadowDom, "slot", () => f().build());
-  }
-  get path() {
-    return n(this, "path", "/");
-  }
-  set path(t) {
-    o(this, "path", t);
-  }
-  get exact() {
-    return this.hasAttribute("exact");
-  }
-  get params() {
-    return { ...this._params };
-  }
-  get sheet() {
-    return n(this, "sheet");
-  }
-  set sheet(t) {
-    o(this, "sheet", t);
-  }
-  handlerExternalCss = () => {
-    p(this, this._shadowDom, "sheet", null, this.sheet);
-  };
-  _matchPath(t) {
-    const a = this.path, e = {}, r = [], h = a.split("/").map((s) => s.startsWith(":") ? (r.push(s.slice(1)), "([^/]+)") : s === "*" ? "(.*)" : s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("/"), c = this.exact ? new RegExp(`^${h}$`) : new RegExp(`^${h}(?:/.*)?$`), i = t.match(c);
-    return i ? (r.forEach((s, u) => {
-      e[s] = decodeURIComponent(i[u + 1] ?? "");
-    }), {
-      matched: !0,
-      params: e
-    }) : {
-      matched: !1,
-      params: e
-    };
-  }
-  _update(t) {
-    const { matched: a, params: e } = this._matchPath(t);
-    this._params = e, this.hidden = !a, a && this.dispatchEvent(new CustomEvent("routematch", {
-      detail: {
-        path: t,
-        params: e
-      },
-      bubbles: !0
-    }));
-  }
-  _preSerialize() {
-    const t = g();
-    t !== null && this._update(t);
-  }
-  connectedCallback() {
-    this.handlerExternalCss();
-    const t = this.closest("r-router");
-    t && t._currentPath && this._update(t._currentPath);
-  }
-  disconnectedCallback() {
-    this._events.abort();
-  }
-  attributeChangedCallback(t, a, e) {
-    if (a !== e) {
-      if (t === "path" || t === "exact") {
-        const r = this.closest("r-router");
-        r && this._update(r._currentPath);
-      }
-      t === "sheet" && this.handlerExternalCss();
-    }
-  }
-};
-_("r-route", w);
-export {
-  w as t
-};

package/dist/signal-CSSZxlK5.js

@@ -1,57 +0,0 @@
-var c = null, u = null, f = null;
-function b(r, e) {
-  const s = e?.equals ?? Object.is;
-  let t = r;
-  const n = /* @__PURE__ */ new Set();
-  return [() => (c && u && (n.add(c), u.add(n)), t), (o) => {
-    const d = typeof o == "function" ? o(t) : o;
-    if (!s(t, d))
-      if (t = d, f) for (const a of n) f.add(a);
-      else for (const a of [...n]) a();
-  }];
-}
-function p(r) {
-  let e, s = !1;
-  const t = /* @__PURE__ */ new Set(), n = () => {
-    if (s) return;
-    e?.();
-    for (const o of t) o.delete(n);
-    t.clear();
-    const l = c, i = u;
-    c = n, u = t;
-    try {
-      e = r() ?? void 0;
-    } finally {
-      c = l, u = i;
-    }
-  };
-  return n(), () => {
-    s = !0, e?.();
-    for (const l of t) l.delete(n);
-    t.clear();
-  };
-}
-function v(r) {
-  const [e, s] = b(void 0);
-  return p(() => s(r())), e;
-}
-function S(r) {
-  if (f) {
-    r();
-    return;
-  }
-  const e = /* @__PURE__ */ new Set();
-  f = e;
-  try {
-    r();
-  } finally {
-    f = null;
-    for (const s of e) s();
-  }
-}
-export {
-  b as i,
-  v as n,
-  p as r,
-  S as t
-};