react-fine-grained-signals 0.1.0

package/dist/utils.d.ts

@@ -0,0 +1,78 @@
+import { t as ReadonlySignal } from "./base-Bx5ahfW2.js";
+import { Key, ReactNode } from "react";
+//#region src/utils.d.ts
+/** A plain value or a value created by `signal`, `computed`, or `deepSignal`. */
+type SignalInput<T> = T | ReadonlySignal<T>;
+/** Renders its children only while `when` is truthy. */
+interface ShowProps<T> {
+  when: SignalInput<T>;
+  fallback?: ReactNode;
+  children: ReactNode | ((value: NonNullable<T>) => ReactNode);
+}
+/**
+ * A small reactive conditional-rendering boundary.
+ *
+ * Unlike Solid's compiler-aware control flow, this is a normal React component:
+ * only this component rerenders when a signal read from `when` changes.
+ */
+declare function Show<T>({ when, fallback, children }: ShowProps<T>): ReactNode;
+/** A branch declaration consumed by the nearest `Switch`. */
+interface MatchProps<T> {
+  when: SignalInput<T>;
+  children: ReactNode | ((value: NonNullable<T>) => ReactNode);
+}
+/**
+ * Declares a `Switch` branch. `Match` only has meaning as a child of `Switch`.
+ */
+declare function Match<T>(_props: MatchProps<T>): null;
+/** Chooses and renders the first truthy child `Match`. */
+interface SwitchProps {
+  fallback?: ReactNode;
+  children?: ReactNode;
+}
+/**
+ * A small reactive multi-branch boundary inspired by Solid's `Switch`/`Match`.
+ */
+declare function Switch({ fallback, children }: SwitchProps): ReactNode;
+/** A collection supported by `For` when each item has its own identity. */
+type ForCollection<T> = readonly T[] | ReadonlySet<T>;
+/** Renders an array or set whose items have stable identities. */
+interface ForProps<T> {
+  each: SignalInput<ForCollection<T> | null | undefined>;
+  fallback?: ReactNode;
+  /** Returns the stable React key for an item. It must be pure and data-derived. */
+  by: (item: T, index: number) => Key;
+  children: (item: T, index: number) => ReactNode;
+}
+/** Renders a map whose entries have stable identities. */
+interface ForMapProps<K, V> {
+  each: SignalInput<ReadonlyMap<K, V> | null | undefined>;
+  fallback?: ReactNode;
+  /** Returns the stable React key for an entry. It must be pure and data-derived. */
+  by: (entry: readonly [K, V], index: number) => Key;
+  children: (entry: readonly [K, V], index: number) => ReactNode;
+}
+/**
+ * A React list boundary inspired by Solid's `For`.
+ *
+ * React still owns reconciliation. `by` supplies stable keys, so use `Index`
+ * instead when a list's identity is intentionally positional.
+ */
+declare function For<T>(props: ForProps<T>): ReactNode;
+declare function For<K, V>(props: ForMapProps<K, V>): ReactNode;
+/** Renders an array whose row identity is intentionally its position. */
+interface IndexProps<T> {
+  each: SignalInput<readonly T[] | null | undefined>;
+  fallback?: ReactNode;
+  /** Receives a render-time accessor for the current value at this position. */
+  children: (item: () => T, index: number) => ReactNode;
+}
+/**
+ * A position-keyed React list boundary inspired by Solid's `Index`.
+ *
+ * The accessor should be read during render. For identity-keyed lists, use
+ * `For` instead and provide `by`.
+ */
+declare function Index<T>({ each, fallback, children }: IndexProps<T>): ReactNode;
+//#endregion
+export { For, ForCollection, ForMapProps, ForProps, Index, IndexProps, Match, MatchProps, Show, ShowProps, SignalInput, Switch, SwitchProps };

package/dist/utils.js

@@ -0,0 +1,91 @@
+import { o as isSignal } from "./base-BZTnpU8U.js";
+import { t as useManagedSignals } from "./use-signals-8i2B-94o.js";
+import { Children, Fragment, isValidElement } from "react";
+import { jsx } from "react/jsx-runtime";
+//#region src/utils.tsx
+/**
+* A small reactive conditional-rendering boundary.
+*
+* Unlike Solid's compiler-aware control flow, this is a normal React component:
+* only this component rerenders when a signal read from `when` changes.
+*/
+function Show({ when, fallback = null, children }) {
+	const store = useManagedSignals();
+	try {
+		const value = readSignalInput(when);
+		if (!value) return fallback;
+		return typeof children === "function" ? children(value) : children;
+	} finally {
+		store.f();
+	}
+}
+/**
+* Declares a `Switch` branch. `Match` only has meaning as a child of `Switch`.
+*/
+function Match(_props) {
+	return null;
+}
+/**
+* A small reactive multi-branch boundary inspired by Solid's `Switch`/`Match`.
+*/
+function Switch({ fallback = null, children }) {
+	const store = useManagedSignals();
+	try {
+		for (const match of collectMatches(children)) {
+			const value = readSignalInput(match.props.when);
+			if (!value) continue;
+			const branch = match.props.children;
+			return typeof branch === "function" ? branch(value) : branch;
+		}
+		return fallback;
+	} finally {
+		store.f();
+	}
+}
+function For({ each, fallback = null, by, children }) {
+	const store = useManagedSignals();
+	try {
+		const collection = readSignalInput(each);
+		if (collection === null || collection === void 0) return fallback;
+		const items = Array.isArray(collection) ? collection : Array.from(collection);
+		if (items.length === 0) return fallback;
+		return items.map((item, index) => /* @__PURE__ */ jsx(Fragment, { children: children(item, index) }, by(item, index)));
+	} finally {
+		store.f();
+	}
+}
+/**
+* A position-keyed React list boundary inspired by Solid's `Index`.
+*
+* The accessor should be read during render. For identity-keyed lists, use
+* `For` instead and provide `by`.
+*/
+function Index({ each, fallback = null, children }) {
+	const store = useManagedSignals();
+	try {
+		const items = readSignalInput(each);
+		if (items === null || items === void 0 || items.length === 0) return fallback;
+		const readAt = (index) => (readSignalInput(each) ?? items)[index];
+		return items.map((_item, index) => /* @__PURE__ */ jsx(Fragment, { children: children(() => readAt(index), index) }, index));
+	} finally {
+		store.f();
+	}
+}
+function readSignalInput(value) {
+	return isSignal(value) ? value.value : value;
+}
+function collectMatches(children) {
+	const matches = [];
+	Children.forEach(children, (child) => {
+		if (!isValidElement(child)) return;
+		if (child.type === Fragment) {
+			const fragment = child;
+			matches.push(...collectMatches(fragment.props.children));
+		} else if (child.type === Match) matches.push(child);
+	});
+	return matches;
+}
+//#endregion
+export { For, Index, Match, Show, Switch };
+
+//# sourceMappingURL=utils.js.map

package/dist/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","names":[],"sources":["../src/utils.tsx"],"sourcesContent":["import {\n  Children,\n  Fragment,\n  isValidElement,\n  type Key,\n  type ReactElement,\n  type ReactNode,\n} from \"react\";\nimport { isSignal, type ReadonlySignal } from \"./core/index.js\";\nimport { useManagedSignals } from \"./react/use-signals.js\";\n\n/*\n * These four components use the *managed* render scope rather than the\n * best-effort `useSignals()`. The library owns their entire function body, so\n * an exact boundary — open at the top, closed in a `finally` before the\n * component returns — costs nothing here, while `useSignals()`' scope can stay\n * open past the return (until the next `useSignals()` call, a layout effect, or\n * a microtask) and misattribute a *sibling's* render-time signal read to this\n * component's store, which then silently stops updating the sibling. Every\n * branch and early return must stay inside the `try`. See\n * docs/design/use-signals-boundary-design.md.\n */\n\n/** A plain value or a value created by `signal`, `computed`, or `deepSignal`. */\nexport type SignalInput<T> = T | ReadonlySignal<T>;\n\n/** Renders its children only while `when` is truthy. */\nexport interface ShowProps<T> {\n  when: SignalInput<T>;\n  fallback?: ReactNode;\n  children: ReactNode | ((value: NonNullable<T>) => ReactNode);\n}\n\n/**\n * A small reactive conditional-rendering boundary.\n *\n * Unlike Solid's compiler-aware control flow, this is a normal React component:\n * only this component rerenders when a signal read from `when` changes.\n */\nexport function Show<T>({ when, fallback = null, children }: ShowProps<T>): ReactNode {\n  const store = useManagedSignals();\n  try {\n    const value = readSignalInput(when);\n\n    if (!value) return fallback;\n    return typeof children === \"function\"\n      ? children(value as NonNullable<T>)\n      : children;\n  } finally {\n    store.f();\n  }\n}\n\n/** A branch declaration consumed by the nearest `Switch`. */\nexport interface MatchProps<T> {\n  when: SignalInput<T>;\n  children: ReactNode | ((value: NonNullable<T>) => ReactNode);\n}\n\n/**\n * Declares a `Switch` branch. `Match` only has meaning as a child of `Switch`.\n */\nexport function Match<T>(_props: MatchProps<T>): null {\n  return null;\n}\n\n/** Chooses and renders the first truthy child `Match`. */\nexport interface SwitchProps {\n  fallback?: ReactNode;\n  children?: ReactNode;\n}\n\n/**\n * A small reactive multi-branch boundary inspired by Solid's `Switch`/`Match`.\n */\nexport function Switch({ fallback = null, children }: SwitchProps): ReactNode {\n  const store = useManagedSignals();\n  try {\n    for (const match of collectMatches(children)) {\n      const value = readSignalInput(match.props.when);\n      if (!value) continue;\n\n      const branch = match.props.children;\n      return typeof branch === \"function\"\n        ? branch(value as NonNullable<unknown>)\n        : branch;\n    }\n\n    return fallback;\n  } finally {\n    store.f();\n  }\n}\n\n/** A collection supported by `For` when each item has its own identity. */\nexport type ForCollection<T> = readonly T[] | ReadonlySet<T>;\n\n/** Renders an array or set whose items have stable identities. */\nexport interface ForProps<T> {\n  each: SignalInput<ForCollection<T> | null | undefined>;\n  fallback?: ReactNode;\n  /** Returns the stable React key for an item. It must be pure and data-derived. */\n  by: (item: T, index: number) => Key;\n  children: (item: T, index: number) => ReactNode;\n}\n\n/** Renders a map whose entries have stable identities. */\nexport interface ForMapProps<K, V> {\n  each: SignalInput<ReadonlyMap<K, V> | null | undefined>;\n  fallback?: ReactNode;\n  /** Returns the stable React key for an entry. It must be pure and data-derived. */\n  by: (entry: readonly [K, V], index: number) => Key;\n  children: (entry: readonly [K, V], index: number) => ReactNode;\n}\n\n/**\n * A React list boundary inspired by Solid's `For`.\n *\n * React still owns reconciliation. `by` supplies stable keys, so use `Index`\n * instead when a list's identity is intentionally positional.\n */\nexport function For<T>(props: ForProps<T>): ReactNode;\nexport function For<K, V>(props: ForMapProps<K, V>): ReactNode;\nexport function For(\n  { each, fallback = null, by, children }: ForProps<unknown> | ForMapProps<unknown, unknown>,\n): ReactNode {\n  const store = useManagedSignals();\n  try {\n    const collection = readSignalInput(each);\n\n    if (collection === null || collection === undefined) {\n      return fallback;\n    }\n\n    const items = Array.isArray(collection) ? collection : Array.from(collection);\n    if (items.length === 0) return fallback;\n\n    return items.map((item, index) => (\n      <Fragment key={by(item, index)}>{children(item, index)}</Fragment>\n    ));\n  } finally {\n    store.f();\n  }\n}\n\n/** Renders an array whose row identity is intentionally its position. */\nexport interface IndexProps<T> {\n  each: SignalInput<readonly T[] | null | undefined>;\n  fallback?: ReactNode;\n  /** Receives a render-time accessor for the current value at this position. */\n  children: (item: () => T, index: number) => ReactNode;\n}\n\n/**\n * A position-keyed React list boundary inspired by Solid's `Index`.\n *\n * The accessor should be read during render. For identity-keyed lists, use\n * `For` instead and provide `by`.\n */\nexport function Index<T>({ each, fallback = null, children }: IndexProps<T>): ReactNode {\n  const store = useManagedSignals();\n  try {\n    const items = readSignalInput(each);\n\n    if (items === null || items === undefined || items.length === 0) {\n      return fallback;\n    }\n\n    // Reads back through `each` on every call rather than closing over the\n    // render-time `items` snapshot, so an accessor a child stores and calls\n    // later (from an event handler, say) still sees the current value instead\n    // of a stale row. The snapshot is only the fallback for a collection that\n    // has since become null/undefined. `as T` stands in for the old `!`: an\n    // out-of-range position reads as `undefined`, exactly as before, and a\n    // sparse hole is no longer disguised as a present value.\n    const readAt = (index: number): T =>\n      (readSignalInput(each) ?? items)[index] as T;\n\n    return items.map((_item, index) => (\n      <Fragment key={index}>{children(() => readAt(index), index)}</Fragment>\n    ));\n  } finally {\n    store.f();\n  }\n}\n\nfunction readSignalInput<T>(value: SignalInput<T>): T {\n  return isSignal(value) ? (value.value as T) : value;\n}\n\nfunction collectMatches(children: ReactNode): Array<ReactElement<MatchProps<unknown>>> {\n  const matches: Array<ReactElement<MatchProps<unknown>>> = [];\n\n  Children.forEach(children, (child) => {\n    if (!isValidElement(child)) return;\n    if (child.type === Fragment) {\n      const fragment = child as ReactElement<{ children?: ReactNode }>;\n      matches.push(...collectMatches(fragment.props.children));\n    } else if (child.type === Match) {\n      matches.push(child as ReactElement<MatchProps<unknown>>);\n    }\n  });\n\n  return matches;\n}\n"],"mappings":";;;;;;;;;;;AAuCA,SAAgB,KAAQ,EAAE,MAAM,WAAW,MAAM,YAAqC;CACpF,MAAM,QAAQ,kBAAkB;CAChC,IAAI;EACF,MAAM,QAAQ,gBAAgB,IAAI;EAElC,IAAI,CAAC,OAAO,OAAO;EACnB,OAAO,OAAO,aAAa,aACvB,SAAS,KAAuB,IAChC;CACN,UAAU;EACR,MAAM,EAAE;CACV;AACF;;;;AAWA,SAAgB,MAAS,QAA6B;CACpD,OAAO;AACT;;;;AAWA,SAAgB,OAAO,EAAE,WAAW,MAAM,YAAoC;CAC5E,MAAM,QAAQ,kBAAkB;CAChC,IAAI;EACF,KAAK,MAAM,SAAS,eAAe,QAAQ,GAAG;GAC5C,MAAM,QAAQ,gBAAgB,MAAM,MAAM,IAAI;GAC9C,IAAI,CAAC,OAAO;GAEZ,MAAM,SAAS,MAAM,MAAM;GAC3B,OAAO,OAAO,WAAW,aACrB,OAAO,KAA6B,IACpC;EACN;EAEA,OAAO;CACT,UAAU;EACR,MAAM,EAAE;CACV;AACF;AA+BA,SAAgB,IACd,EAAE,MAAM,WAAW,MAAM,IAAI,YAClB;CACX,MAAM,QAAQ,kBAAkB;CAChC,IAAI;EACF,MAAM,aAAa,gBAAgB,IAAI;EAEvC,IAAI,eAAe,QAAQ,eAAe,KAAA,GACxC,OAAO;EAGT,MAAM,QAAQ,MAAM,QAAQ,UAAU,IAAI,aAAa,MAAM,KAAK,UAAU;EAC5E,IAAI,MAAM,WAAW,GAAG,OAAO;EAE/B,OAAO,MAAM,KAAK,MAAM,UACtB,oBAAC,UAAD,EAAA,UAAiC,SAAS,MAAM,KAAK,EAAY,GAAlD,GAAG,MAAM,KAAK,CAAoC,CAClE;CACH,UAAU;EACR,MAAM,EAAE;CACV;AACF;;;;;;;AAgBA,SAAgB,MAAS,EAAE,MAAM,WAAW,MAAM,YAAsC;CACtF,MAAM,QAAQ,kBAAkB;CAChC,IAAI;EACF,MAAM,QAAQ,gBAAgB,IAAI;EAElC,IAAI,UAAU,QAAQ,UAAU,KAAA,KAAa,MAAM,WAAW,GAC5D,OAAO;EAUT,MAAM,UAAU,WACb,gBAAgB,IAAI,KAAK,MAAA,CAAO;EAEnC,OAAO,MAAM,KAAK,OAAO,UACvB,oBAAC,UAAD,EAAA,UAAuB,eAAe,OAAO,KAAK,GAAG,KAAK,EAAY,GAAvD,KAAuD,CACvE;CACH,UAAU;EACR,MAAM,EAAE;CACV;AACF;AAEA,SAAS,gBAAmB,OAA0B;CACpD,OAAO,SAAS,KAAK,IAAK,MAAM,QAAc;AAChD;AAEA,SAAS,eAAe,UAA+D;CACrF,MAAM,UAAoD,CAAC;CAE3D,SAAS,QAAQ,WAAW,UAAU;EACpC,IAAI,CAAC,eAAe,KAAK,GAAG;EAC5B,IAAI,MAAM,SAAS,UAAU;GAC3B,MAAM,WAAW;GACjB,QAAQ,KAAK,GAAG,eAAe,SAAS,MAAM,QAAQ,CAAC;EACzD,OAAO,IAAI,MAAM,SAAS,OACxB,QAAQ,KAAK,KAA0C;CAE3D,CAAC;CAED,OAAO;AACT"}

package/package.json

@@ -0,0 +1,114 @@
+{
+  "name": "react-fine-grained-signals",
+  "version": "0.1.0",
+  "description": "Fine-grained signal rendering for React 19, built on alien-signals.",
+  "license": "MIT",
+  "author": "akazawa",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sakzw/react-fine-grained-signals.git"
+  },
+  "homepage": "https://github.com/sakzw/react-fine-grained-signals#readme",
+  "bugs": {
+    "url": "https://github.com/sakzw/react-fine-grained-signals/issues"
+  },
+  "keywords": [
+    "react",
+    "signals",
+    "signal",
+    "fine-grained",
+    "reactivity",
+    "jsx",
+    "jsx-runtime",
+    "alien-signals"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "devEngines": {
+    "runtime": {
+      "name": "node",
+      "version": "24.20.0",
+      "onFail": "download"
+    }
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./jsx-runtime": {
+      "types": "./dist/jsx-runtime.d.ts",
+      "import": "./dist/jsx-runtime.js"
+    },
+    "./jsx-dev-runtime": {
+      "types": "./dist/jsx-dev-runtime.d.ts",
+      "import": "./dist/jsx-dev-runtime.js"
+    },
+    "./runtime": {
+      "types": "./dist/runtime.d.ts",
+      "import": "./dist/runtime.js"
+    },
+    "./utils": {
+      "types": "./dist/utils.d.ts",
+      "import": "./dist/utils.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "alien-signals": "^3.2.1",
+    "react": ">=19.0.0"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.62.1",
+    "@preact/signals-core": "1.14.4",
+    "@testing-library/react": "^16.3.3",
+    "@types/node": "^24.13.3",
+    "@types/react": "^19.2.18",
+    "@types/react-dom": "^19.2.5",
+    "@vitest/coverage-v8": "4.1.11",
+    "alien-signals": "^3.2.1",
+    "babel-plugin-react-compiler": "^1.0.0",
+    "jsdom": "^30.0.1",
+    "oxlint": "^1.80.0",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
+    "tsdown": "0.22.14",
+    "typescript": "^7.0.2",
+    "vite": "^8.2.2",
+    "vitest": "^4.1.11",
+    "node": "runtime:24.20.0"
+  },
+  "scripts": {
+    "bench": "pnpm build:runtime && node --expose-gc benchmarks/core.mjs",
+    "bench:deep": "pnpm build:runtime && node --expose-gc benchmarks/deep-signal.mjs",
+    "bench:react": "pnpm build:runtime && node --expose-gc benchmarks/react-render.mjs",
+    "bench:transform": "pnpm build:transform && pnpm --filter unplugin-react-fine-grained-signals bench",
+    "build": "pnpm build:runtime && pnpm build:transform",
+    "build:runtime": "tsdown && node scripts/strip-dts-sourcemap-comments.mjs",
+    "build:transform": "pnpm --filter unplugin-react-fine-grained-signals build",
+    "dev:browser": "pnpm build:transform && node examples/browser/server.mjs",
+    "build:browser": "pnpm build:transform && vite build --config examples/browser/vite.config.ts",
+    "preview:browser": "vite preview --config examples/browser/vite.config.ts --host 127.0.0.1 --port 4174 --strictPort",
+    "typecheck": "pnpm typecheck:runtime && pnpm typecheck:transform",
+    "typecheck:runtime": "tsc --noEmit",
+    "typecheck:transform": "pnpm --filter unplugin-react-fine-grained-signals typecheck",
+    "lint": "oxlint",
+    "lint:fix": "oxlint --fix",
+    "test": "pnpm test:runtime && pnpm test:transform",
+    "test:runtime": "vitest run",
+    "test:transform": "pnpm --filter unplugin-react-fine-grained-signals test",
+    "test:coverage": "pnpm test:coverage:runtime && pnpm test:coverage:transform",
+    "test:coverage:runtime": "vitest run --coverage",
+    "test:coverage:transform": "pnpm --filter unplugin-react-fine-grained-signals test:coverage",
+    "test:consumer": "pnpm build && node tests/consumer-smoke.mjs",
+    "prepare:e2e": "pnpm --dir examples/react-router install --frozen-lockfile",
+    "test:browser": "playwright test",
+    "size": "pnpm build:runtime && node scripts/check-size.mjs",
+    "size:update": "pnpm build:runtime && node scripts/check-size.mjs --update"
+  }
+}