react-fine-grained-signals 0.1.1 → 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,25 +8,29 @@
 
 ## ドキュメント
 
-ライブラリの使い方のガイド、設計検討メモ、ドキュメント索引全体については[`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
-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` のいずれかにしてください。
 
 ## セットアップ
 
 プリミティブとフックは、installした時点で動作します。buildツールやコンパイラの設定は不要です。
 
 ```tsx
-import { useSignal, useSignals } from "react-fine-grained-signals";
+import { useSignal, useSignalTracking } from "react-fine-grained-signals";
 
 function Counter() {
-  useSignals();
+  useSignalTracking();
   const count = useSignal(0);
 
   return <button onClick={() => count.value++}>{count.value}</button>;
@@ -58,11 +62,11 @@ function Counter() {
 
 Viteはこの2つを `tsconfig.json` から読むため、`vite.config.ts` 側にJSXの設定は不要です。既定の変換でも `@vitejs/plugin-react` を使う場合でも同じです。
 
-このランタイムが対象とするのはネイティブ要素と、意図的に絞ったpropsだけです。Reactコンポーネントのpropsや子要素に渡したsignalはアンラップされません。許可リスト全体と、JSXをBabelで変換するツールチェーン（`tsconfig.json` を読みません）については[JSXのsignal子要素とhost binding](docs/jsx-bindings.ja.md)を参照してください。
+このランタイムが対象とするのはネイティブ要素と、意図的に絞ったpropsだけです。Reactコンポーネントのpropsや子要素に渡したsignalはアンラップされません。許可リスト全体と、JSXをBabelで変換するツールチェーン（`tsconfig.json` を読みません）については[JSXのsignal子要素とhost binding](./docs/guides/jsx-bindings.ja.md)を参照してください。
 
-### ビルドplugin — `useSignals()` の自動挿入
+### ビルドplugin — `useSignalTracking()` の自動挿入
 
-追跡境界をbuild時に挿入するため、コンポーネント側で `useSignals()` を手書きする必要がなくなります。別packageなので個別にinstallします。
+追跡境界をbuild時に挿入するため、コンポーネント側で `useSignalTracking()` を手書きする必要がなくなります。別packageなので個別にinstallします。
 
 ```sh
 pnpm add -D unplugin-react-fine-grained-signals
@@ -72,6 +76,7 @@ pnpm add -D unplugin-react-fine-grained-signals
 
 ```ts
 // vite.config.ts
+import { defineConfig } from "vite";
 import signals from "unplugin-react-fine-grained-signals/vite";
 
 export default defineConfig({
@@ -79,10 +84,12 @@ export default defineConfig({
 });
 ```
 
-オプションの詳細と、フックを手書きする場合との使い分けについては[描画最適化](docs/rendering-optimization.ja.md)を参照してください。
+オプションの詳細と、フックを手書きする場合との使い分けについては[描画最適化](./docs/guides/rendering-optimization.ja.md)を参照してください。
 
 ## 開発
 
+アーキテクチャ、設計、実装履歴は[`development/README.md`](development/README.md)にまとめています。
+
 ```sh
 pnpm install --frozen-lockfile
 pnpm typecheck
@@ -110,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,15 +8,19 @@ 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
-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.
 
 ## Setup
 
@@ -24,10 +28,10 @@ The primitives and hooks work as soon as the package is installed — no build
 or compiler configuration is involved:
 
 ```tsx
-import { useSignal, useSignals } from "react-fine-grained-signals";
+import { useSignal, useSignalTracking } from "react-fine-grained-signals";
 
 function Counter() {
-  useSignals();
+  useSignalTracking();
   const count = useSignal(0);
 
   return <button onClick={() => count.value++}>{count.value}</button>;
@@ -68,14 +72,14 @@ 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/jsx-bindings.md)
+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 `useSignals()`
+### Build plugin — automatic `useSignalTracking()`
 
 Inserts the tracking boundary during the build, so components no longer call
-`useSignals()` by hand. It is a separate package:
+`useSignalTracking()` by hand. It is a separate package:
 
 ```sh
 pnpm add -D unplugin-react-fine-grained-signals
@@ -86,6 +90,7 @@ It then needs a bundler entry point — `/vite`, `/rollup`, `/webpack`,
 
 ```ts
 // vite.config.ts
+import { defineConfig } from "vite";
 import signals from "unplugin-react-fine-grained-signals/vite";
 
 export default defineConfig({
@@ -93,11 +98,14 @@ export default defineConfig({
 });
 ```
 
-See [Rendering optimization](docs/rendering-optimization.md) for the options
+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
@@ -126,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"}