@zoijs/core 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -4,7 +4,20 @@ All notable changes to Zoijs are documented here. The format is based on
 [Keep a Changelog](https://keepachangelog.com/), and Zoijs follows
 [Semantic Versioning](https://semver.org/) (see `VERSIONING.md`).
 
-## [1.0.0] — Unreleased
+## [1.1.0] — 2026-06-25
+
+### Added
+- **Element refs.** A new `ref` binding gives you the rendered DOM element:
+  `html\`<input ref=${(el) => el.focus()} />\``. The callback runs once, just after
+  the element is inserted (so `focus`/`scroll`/`measure`/`canvas` work), is not
+  reactive, and may return a cleanup function that runs on unmount or list-item
+  removal. Works inside keyed `each` lists. Non-function values are ignored with a
+  dev-mode warning and never become a DOM attribute. No new export — `ref` is a
+  binding semantic, so the seven-function public surface is unchanged (additive
+  MINOR per `VERSIONING.md`). See [Element refs](docs/concepts/refs.md) and
+  [RFC 0001](docs/rfcs/0001-element-refs.md).
+
+## [1.0.0] — 2026-06-24
 
 First stable release. The public API is frozen at seven functions.
 
@@ -33,4 +46,5 @@ First stable release. The public API is frozen at seven functions.
   (Playwright), and TypeScript type tests.
 - No build step required at any point.
 
-[1.0.0]: https://github.com/Zoijs/zoijs/releases/tag/v1.0.0
+[1.1.0]: https://github.com/Zoijs/zoijs/releases/tag/core-v1.1.0
+[1.0.0]: https://github.com/Zoijs/zoijs/releases/tag/core-v1.0.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Easy Framework contributors
+Copyright (c) 2026 Zoijs contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -2,7 +2,7 @@
 
 A lightweight frontend framework you don't have to learn before you use it — **plain HTML, CSS, and JavaScript**, no JSX, no build step, no Virtual DOM.
 
-**[Website](https://zoijs.com)** · **[Documentation](https://zoijs.dev)** · **[GitHub](https://github.com/Zoijs)** · **[npm](https://www.npmjs.com/package/@zoijs/core)**
+**[Documentation](https://zoijs.dev)** · **[GitHub](https://github.com/Zoijs)** · **[npm](https://www.npmjs.com/package/@zoijs/core)**
 
 ```bash
 npm install @zoijs/core

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zoijs/core",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Zoijs — a beginner-friendly, no-build, no-Virtual-DOM frontend framework. Plain HTML, CSS, and JavaScript.",
   "type": "module",
   "main": "src/index.js",
@@ -21,9 +21,9 @@
   "engines": {
     "node": ">=18"
   },
-  "author": "Zoijs contributors (https://zoijs.com)",
+  "author": "Zoijs contributors (https://zoijs.dev)",
   "license": "MIT",
-  "homepage": "https://zoijs.com",
+  "homepage": "https://zoijs.dev",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Zoijs/zoijs.git",
@@ -49,8 +49,8 @@
     "spa"
   ],
   "scripts": {
-    "test": "node --test --import ./tests/setup-dom.js \"tests/**/*.test.js\"",
-    "test:unit": "node --test \"tests/**/*.test.js\"",
+    "test": "node --test --import ./tests/setup-dom.js",
+    "test:unit": "node --test",
     "test:types": "tsc --noEmit -p tsconfig.json",
     "test:browser": "playwright test",
     "dev": "npx serve -l 3000 ."

package/src/core/renderer.js

@@ -82,6 +82,13 @@ function bindChild(anchor, value) {
 }
 
 function bindAttribute(el, attr, values) {
+  if (attr.name === "ref") {
+    // A callback ref. Only a single ${fn} is meaningful; anything else (a string,
+    // a number, a multi-part value) is rejected by bindRef without touching the DOM.
+    bindRef(el, attr.whole ? values[attr.holes[0]] : undefined);
+    return;
+  }
+
   if (attr.event) {
     const handler = values[attr.holes[0]];
     // Only real functions are accepted as handlers — a string/object is ignored,
@@ -119,6 +126,35 @@ function bindAttribute(el, attr, values) {
   else applyAttribute(el, attr.name, compute());
 }
 
+// A callback ref: hand the real element to user code AFTER the current render is
+// inserted, so focus/scroll/measure see a CONNECTED node. We defer one microtask
+// (render binds while the DOM is still a detached fragment; insertion happens
+// right after render returns, synchronously, so a microtask runs once it's live).
+// Not reactive — the function is read once. An optional returned function is an
+// owner-scoped cleanup, disposed on unmount or list-item removal, exactly like a
+// listener. A non-function value is ignored (with a dev warning) and never sets a
+// "ref" attribute — so an inert string can't be wired up.
+function bindRef(el, fn) {
+  if (typeof fn !== "function") {
+    if (isDev()) console.warn(`Zoijs: "ref" expects a function (el) => …; ignoring ${typeof fn} value`);
+    return;
+  }
+  let active = true;
+  let cleanup = null;
+  onCleanup(() => {
+    active = false;
+    if (cleanup) { cleanup(); cleanup = null; }
+  });
+  queueMicrotask(() => {
+    if (!active) return; // removed before the microtask fired
+    const c = fn(el);
+    if (typeof c === "function") {
+      if (active) cleanup = c;
+      else c(); // disposed during fn(): tear down immediately
+    }
+  });
+}
+
 // ---- text / content bindings -------------------------------------------------
 
 function bindReactiveContent(anchor, getValue) {

package/src/index.d.ts

@@ -40,12 +40,29 @@ export interface EachResult {
 /** A component is a function that returns an `html` template. */
 export type Component = () => TemplateResult;
 
+/**
+ * A callback ref. Place it on an element as `ref=${fn}`; it receives the real DOM
+ * element once the surrounding render has been inserted (deferred one microtask,
+ * so `focus()` / `scrollIntoView()` / `getBoundingClientRect()` work). It may
+ * return a cleanup function, which runs on unmount or list-item removal. It runs
+ * once and is not reactive.
+ *
+ * ```ts
+ * html`<input ref=${(el: HTMLInputElement) => el.focus()} />`
+ * html`<div ref=${(el) => { const c = chart(el); return () => c.destroy(); }}></div>`
+ * ```
+ */
+export type Ref<E extends Element = Element> = (element: E) => void | (() => void);
+
 /**
  * Tagged-template function — write your markup as HTML.
  *
  * ```js
  * html`<button onclick=${() => count.set(count.get() + 1)}>${() => count.get()}</button>`
  * ```
+ *
+ * To reach the rendered DOM element, add a callback `ref` (see {@link Ref}):
+ * `html\`<input ref=${(el) => el.focus()} />\``.
  */
 export function html(strings: TemplateStringsArray, ...values: unknown[]): TemplateResult;