react-fine-grained-signals 0.1.0 → 0.2.0

package/LICENSE-ALIEN-SIGNALS.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-present Johnson Chu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.ja.md

@@ -8,21 +8,88 @@
 
 ## ドキュメント
 
-ライブラリの使い方のガイド、設計検討メモ、ドキュメント索引全体については[`docs/README.ja.md`](docs/README.ja.md)を参照してください。
+ユーザー向けドキュメントの索引は[`docs/README.ja.md`](docs/README.ja.md)を参照してください。
+v0.1.1からの移行については[v0.2移行ガイド](./docs/migration/v0.2.ja.md)を参照してください。
 
 ## インストール
 
 ```sh
-# 公開予定のパッケージ名です。まだnpmには公開していません。
-pnpm add react-fine-grained-signals alien-signals
+pnpm add react-fine-grained-signals
 ```
 
-`alien-signals` はpeer dependencyなので、上のように併せてinstallしてください。
+React(19以降)はpeer dependencyで、Node.js 22以降が必要です。packageはESMのみで、
+entry pointと型を `exports` で公開しているため、`react-fine-grained-signals/utils`
+やJSXランタイムを解決するには、TypeScriptの `moduleResolution` を `bundler`、
+`node16`、`nodenext` のいずれかにしてください。
 
-`useSignals()` を自動挿入するオプションのbuild pluginは別途installします。[描画最適化](docs/rendering-optimization.ja.md)を参照してください。
+## セットアップ
+
+プリミティブとフックは、installした時点で動作します。buildツールやコンパイラの設定は不要です。
+
+```tsx
+import { useSignal, useSignalTracking } from "react-fine-grained-signals";
+
+function Counter() {
+  useSignalTracking();
+  const count = useSignal(0);
+
+  return <button onClick={() => count.value++}>{count.value}</button>;
+}
+```
+
+以下の2つの最適化は任意であり、互いに独立しています。どちらもinstall後に別途設定するもので、上記のフックを使うだけなら不要です。
+
+### JSXランタイム — DOMへの直接バインディング
+
+ネイティブホスト要素の子要素として使われたsignalが、周囲のコンポーネントを再レンダーせずに、そのDOMノードだけを更新できるようになります。
+
+ファイル単位で有効にするには、先頭行にpragmaを書きます。他のファイルはReactのJSXランタイムのままになるため、アプリの一部だけで直接バインディングを使いたい場合はこちらを選んでください。[`examples/react-router`](examples/react-router)がこの構成です。
+
+```tsx
+/** @jsxImportSource react-fine-grained-signals */
+```
+
+プロジェクト全体で有効にする場合は `tsconfig.json` に設定します。
+
+```json
+{
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "jsxImportSource": "react-fine-grained-signals"
+  }
+}
+```
+
+Viteはこの2つを `tsconfig.json` から読むため、`vite.config.ts` 側にJSXの設定は不要です。既定の変換でも `@vitejs/plugin-react` を使う場合でも同じです。
+
+このランタイムが対象とするのはネイティブ要素と、意図的に絞ったpropsだけです。Reactコンポーネントのpropsや子要素に渡したsignalはアンラップされません。許可リスト全体と、JSXをBabelで変換するツールチェーン（`tsconfig.json` を読みません）については[JSXのsignal子要素とhost binding](./docs/guides/jsx-bindings.ja.md)を参照してください。
+
+### ビルドplugin — `useSignalTracking()` の自動挿入
+
+追跡境界をbuild時に挿入するため、コンポーネント側で `useSignalTracking()` を手書きする必要がなくなります。別packageなので個別にinstallします。
+
+```sh
+pnpm add -D unplugin-react-fine-grained-signals
+```
+
+そのうえで、bundlerに応じたentry point（`/vite`、`/rollup`、`/webpack`、`/rspack`、`/esbuild`）をbuild設定に追加します。
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import signals from "unplugin-react-fine-grained-signals/vite";
+
+export default defineConfig({
+  plugins: [signals({ mode: "auto" })],
+});
+```
+
+オプションの詳細と、フックを手書きする場合との使い分けについては[描画最適化](./docs/guides/rendering-optimization.ja.md)を参照してください。
 
 ## 開発
 
+アーキテクチャ、設計、実装履歴は[`development/README.md`](development/README.md)にまとめています。
+
 ```sh
 pnpm install --frozen-lockfile
 pnpm typecheck
@@ -50,4 +117,4 @@ pnpm test:browser
 
 - [alien-signals](https://www.npmjs.com/package/alien-signals) — 本パッケージが基盤とするシグナルエンジン。
 - [@preact/signals-core](https://www.npmjs.com/package/@preact/signals-core) — ベンチマークの比較対象。
-- [@preact/signals-react](https://www.npmjs.com/package/@preact/signals-react) — `useSignals()` boundaryのstore protocol設計における先行事例。詳細は[Prior art](docs/design/use-signals-boundary-design.ja.md#先行事例)を参照。
+- [@preact/signals-react](https://www.npmjs.com/package/@preact/signals-react) — 外部API `useSignals()` boundaryのstore protocol設計における先行事例。詳細は[Prior art](./development/design/use-signals-boundary-design.ja.md#先行事例)を参照。

package/README.md

@@ -8,21 +8,104 @@ An experimental fine-grained rendering layer for React 19, built on [alien-signa
 
 ## Documentation
 
-See [`docs/README.md`](docs/README.md) for guides on using the library, design investigation memos, and the full documentation index.
+See [`docs/README.md`](docs/README.md) for the user documentation index.
+For upgrades from v0.1.1, see the [v0.2 migration guide](./docs/migration/v0.2.md).
 
 ## Installation
 
 ```sh
-# Planned package name — it is not published to npm yet.
-pnpm add react-fine-grained-signals alien-signals
+pnpm add react-fine-grained-signals
 ```
 
-`alien-signals` is a peer dependency, so install it alongside this package.
+React (19 or newer) is a peer dependency, and Node.js 22 or newer is required.
+The package is ESM-only and publishes its entry points and types through
+`exports`, so TypeScript needs `moduleResolution` set to `bundler`, `node16`, or
+`nodenext` to resolve `react-fine-grained-signals/utils` and the JSX runtime.
 
-The optional build plugin for automatic `useSignals()` insertion is installed separately — see [Rendering optimization](docs/rendering-optimization.md).
+## Setup
+
+The primitives and hooks work as soon as the package is installed — no build
+or compiler configuration is involved:
+
+```tsx
+import { useSignal, useSignalTracking } from "react-fine-grained-signals";
+
+function Counter() {
+  useSignalTracking();
+  const count = useSignal(0);
+
+  return <button onClick={() => count.value++}>{count.value}</button>;
+}
+```
+
+The two optimizations below are opt-in and independent of each other. Both are
+configured after installing, and neither is needed to use the hooks above.
+
+### JSX runtime — direct DOM bindings
+
+Lets a signal used as the child of a native host element update that DOM node
+on its own, without re-rendering the component around it.
+
+Opt in one file at a time with a pragma on the first line. Every other file
+keeps React's JSX runtime, so this is the form to reach for when only part of
+an app needs the direct bindings — it is how
+[`examples/react-router`](examples/react-router) is set up:
+
+```tsx
+/** @jsxImportSource react-fine-grained-signals */
+```
+
+Or opt the whole project in through `tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "jsxImportSource": "react-fine-grained-signals"
+  }
+}
+```
+
+Vite reads both of those from `tsconfig.json` — with its default transform and
+with `@vitejs/plugin-react` alike — so `vite.config.ts` needs no JSX
+configuration of its own.
+
+The runtime covers native elements only, and a deliberately narrow set of
+props. Signals passed to a React component's props or children are not
+unwrapped. See [JSX signal children and host bindings](./docs/guides/jsx-bindings.md)
+for the full allow-list, and for toolchains that transform JSX through Babel,
+which do not read `tsconfig.json`.
+
+### Build plugin — automatic `useSignalTracking()`
+
+Inserts the tracking boundary during the build, so components no longer call
+`useSignalTracking()` by hand. It is a separate package:
+
+```sh
+pnpm add -D unplugin-react-fine-grained-signals
+```
+
+It then needs a bundler entry point — `/vite`, `/rollup`, `/webpack`,
+`/rspack`, or `/esbuild` — added to the build configuration:
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import signals from "unplugin-react-fine-grained-signals/vite";
+
+export default defineConfig({
+  plugins: [signals({ mode: "auto" })],
+});
+```
+
+See [Rendering optimization](./docs/guides/rendering-optimization.md) for the options
+and for the trade-offs against calling the hook by hand.
 
 ## Development
 
+Architecture, design, and implementation history are indexed in
+[`development/README.md`](development/README.md).
+
 ```sh
 pnpm install --frozen-lockfile
 pnpm typecheck
@@ -51,4 +134,4 @@ Run `pnpm dev:browser` to build the transform package and inspect the same examp
 
 - [alien-signals](https://www.npmjs.com/package/alien-signals) — the signal engine this package builds on.
 - [@preact/signals-core](https://www.npmjs.com/package/@preact/signals-core) — benchmark comparison target.
-- [@preact/signals-react](https://www.npmjs.com/package/@preact/signals-react) — prior art for the `useSignals()` boundary's store protocol; see [Prior art](docs/design/use-signals-boundary-design.md#prior-art).
+- [@preact/signals-react](https://www.npmjs.com/package/@preact/signals-react) — prior art for the external `useSignals()` boundary's store protocol; see [Prior art](./development/design/use-signals-boundary-design.md#prior-art).

package/dist/base-WD_74mfC.js

@@ -0,0 +1,55 @@
+import { n as SIGNAL_BRAND, t as coreRuntime } from "./core-runtime-2jSE9Tz5.js";
+//#region src/core/base.ts
+const signalInstances = /* @__PURE__ */ new WeakSet();
+/** Marks an internal signal implementation for the public identity guard. */
+function registerSignal(value) {
+	signalInstances.add(value);
+	Object.defineProperty(value, SIGNAL_BRAND, {
+		value: 1,
+		enumerable: false,
+		writable: false,
+		configurable: false
+	});
+	return value;
+}
+/** Returns whether a value came from this package's signal APIs, any copy. */
+function isSignal(value) {
+	if (typeof value !== "object" || value === null) return false;
+	if (signalInstances.has(value)) return true;
+	const brand = value[SIGNAL_BRAND];
+	if (typeof brand !== "number" || brand < 1) return false;
+	return typeof value.peek === "function";
+}
+/** Creates a writable reactive value. */
+function signal(initialValue) {
+	return coreRuntime.signal(initialValue);
+}
+/** Creates a lazily evaluated reactive value. */
+function computed(getter) {
+	return coreRuntime.computed(getter);
+}
+/** Runs a reactive side effect and returns a disposer. */
+function effect(fn) {
+	return coreRuntime.effect(fn);
+}
+/**
+* Package-internal: an effect that is never owned by the effect or computed
+* running when it is created. Hooks and JSX bindings create theirs from React
+* commits, which can run synchronously inside a user effect (`flushSync`), and
+* must not be disposed when that unrelated effect next re-runs.
+*/
+function detachedEffect(fn) {
+	return coreRuntime.detachedEffect(fn);
+}
+/** Groups writes, deferring effect notifications until the callback completes. */
+function batch(fn) {
+	return coreRuntime.batch(fn);
+}
+/** Runs a callback without collecting reactive dependencies. */
+function untracked(fn) {
+	return coreRuntime.untracked(fn);
+}
+//#endregion
+export { isSignal as a, untracked as c, effect as i, computed as n, registerSignal as o, detachedEffect as r, signal as s, batch as t };
+
+//# sourceMappingURL=base-WD_74mfC.js.map

package/dist/base-WD_74mfC.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-WD_74mfC.js","names":[],"sources":["../src/core/base.ts"],"sourcesContent":["import { coreRuntime } from \"./core-runtime.js\";\nimport { SIGNAL_BRAND, SIGNAL_BRAND_MIN_VERSION, SIGNAL_BRAND_VERSION } from \"./signal-brand.js\";\n\n/** A readable reactive value. */\nexport interface ReadonlySignal<T> {\n  readonly value: T;\n  peek(): T;\n}\n\n/** A readable and writable reactive value. */\nexport interface Signal<T> extends ReadonlySignal<T> {\n  value: T;\n}\n\nconst signalInstances = new WeakSet<object>();\n\n// The brand carries a protocol version instead of `true` so a future instance\n// can tell which contract a foreign signal claims. See signal-brand.ts for why\n// v0.2 uses a different key from v0.1.x rather than a larger version number.\n\n/** Marks an internal signal implementation for the public identity guard. */\nexport function registerSignal<T extends object>(value: T): T {\n  signalInstances.add(value);\n  // Non-enumerable keeps the brand out of JSON, `Object.keys`, spread, and\n  // React's prop diffing; non-writable and non-configurable keep it from being\n  // retargeted or stripped once the value is public. The hardening is free:\n  // measured against a writable/configurable descriptor the cost is identical,\n  // because it is the `defineProperty` call itself, and V8 keeps the instance\n  // in fast properties either way (checked with `%HasFastProperties`). Stamping\n  // the prototype instead would be worse — that pushes the prototype into\n  // dictionary mode, which every lookup through it then pays for.\n  Object.defineProperty(value, SIGNAL_BRAND, {\n    value: SIGNAL_BRAND_VERSION,\n    enumerable: false,\n    writable: false,\n    configurable: false,\n  });\n  return value;\n}\n\n/** Returns whether a value came from this package's signal APIs, any copy. */\nexport function isSignal(value: unknown): value is ReadonlySignal<unknown> {\n  if (typeof value !== \"object\" || value === null) return false;\n  // The WeakSet is both the cheaper lookup and the authority for values created\n  // by this instance; the brand is the fallback for every other instance.\n  if (signalInstances.has(value)) return true;\n  const brand = (value as { [SIGNAL_BRAND]?: unknown })[SIGNAL_BRAND];\n  if (typeof brand !== \"number\" || brand < SIGNAL_BRAND_MIN_VERSION) return false;\n  // A foreign brand is a claim, not a proof. Checking the cheap half of the\n  // contract turns a malformed brand into `false` instead of a crash inside a\n  // render, and costs nothing on the local-instance path above.\n  return typeof (value as ReadonlySignal<unknown>).peek === \"function\";\n}\n\n/** Creates a writable reactive value. */\nexport function signal<T>(initialValue: T): Signal<T> {\n  return coreRuntime.signal(initialValue);\n}\n\n/** Creates a lazily evaluated reactive value. */\nexport function computed<T>(getter: () => T): ReadonlySignal<T> {\n  return coreRuntime.computed(getter);\n}\n\n/** Runs a reactive side effect and returns a disposer. */\nexport function effect(fn: () => void | (() => void)): () => void {\n  return coreRuntime.effect(fn);\n}\n\n/**\n * Package-internal: an effect that is never owned by the effect or computed\n * running when it is created. Hooks and JSX bindings create theirs from React\n * commits, which can run synchronously inside a user effect (`flushSync`), and\n * must not be disposed when that unrelated effect next re-runs.\n */\nexport function detachedEffect(fn: () => void | (() => void)): () => void {\n  return coreRuntime.detachedEffect(fn);\n}\n\n/** Groups writes, deferring effect notifications until the callback completes. */\nexport function batch<T>(fn: () => T): T {\n  return coreRuntime.batch(fn);\n}\n\n/** Runs a callback without collecting reactive dependencies. */\nexport function untracked<T>(fn: () => T): T {\n  return coreRuntime.untracked(fn);\n}\n"],"mappings":";;AAcA,MAAM,kCAAkB,IAAI,QAAgB;;AAO5C,SAAgB,eAAiC,OAAa;CAC5D,gBAAgB,IAAI,KAAK;CASzB,OAAO,eAAe,OAAO,cAAc;EACzC,OAAA;EACA,YAAY;EACZ,UAAU;EACV,cAAc;CAChB,CAAC;CACD,OAAO;AACT;;AAGA,SAAgB,SAAS,OAAkD;CACzE,IAAI,OAAO,UAAU,YAAY,UAAU,MAAM,OAAO;CAGxD,IAAI,gBAAgB,IAAI,KAAK,GAAG,OAAO;CACvC,MAAM,QAAS,MAAuC;CACtD,IAAI,OAAO,UAAU,YAAY,QAAA,GAAkC,OAAO;CAI1E,OAAO,OAAQ,MAAkC,SAAS;AAC5D;;AAGA,SAAgB,OAAU,cAA4B;CACpD,OAAO,YAAY,OAAO,YAAY;AACxC;;AAGA,SAAgB,SAAY,QAAoC;CAC9D,OAAO,YAAY,SAAS,MAAM;AACpC;;AAGA,SAAgB,OAAO,IAA2C;CAChE,OAAO,YAAY,OAAO,EAAE;AAC9B;;;;;;;AAQA,SAAgB,eAAe,IAA2C;CACxE,OAAO,YAAY,eAAe,EAAE;AACtC;;AAGA,SAAgB,MAAS,IAAgB;CACvC,OAAO,YAAY,MAAM,EAAE;AAC7B;;AAGA,SAAgB,UAAa,IAAgB;CAC3C,OAAO,YAAY,UAAU,EAAE;AACjC"}