@preact/signals 2.0.5 → 2.1.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @preact/signals
 
+## 2.1.0
+
+### Minor Changes
+
+- [#683](https://github.com/preactjs/signals/pull/683) [`4b585a5`](https://github.com/preactjs/signals/commit/4b585a5f15300b73dc66f45effd21342e3f6e5d5) Thanks [@JoviDeCroock](https://github.com/JoviDeCroock)! - Provide `@preact/signals/utils` package with some helpers to make working with signals easier in Preact
+
 ## 2.0.5
 
 ### Patch Changes

package/README.md

@@ -111,6 +111,84 @@ function Person() {
 
 This way we'll bypass checking the virtual-dom and update the DOM property directly.
 
+## Utility Components and Hooks
+
+The `@preact/signals/utils` package provides additional utility components and hooks to make working with signals even easier.
+
+### Show Component
+
+The `Show` component provides a declarative way to conditionally render content based on a signal's value.
+
+```js
+import { Show } from "@preact/signals/utils";
+import { signal } from "@preact/signals";
+
+const isVisible = signal(false);
+
+function App() {
+	return (
+		<Show when={isVisible} fallback={<p>Nothing to see here</p>}>
+			<p>Now you see me!</p>
+		</Show>
+	);
+}
+
+// You can also use a function to access the value
+function App() {
+	return <Show when={isVisible}>{value => <p>The value is {value}</p>}</Show>;
+}
+```
+
+### For Component
+
+The `For` component helps you render lists from signal arrays with automatic caching of rendered items.
+
+```js
+import { For } from "@preact/signals/utils";
+import { signal } from "@preact/signals";
+
+const items = signal(["A", "B", "C"]);
+
+function App() {
+	return (
+		<For each={items} fallback={<p>No items</p>}>
+			{(item, index) => <div key={index}>Item: {item}</div>}
+		</For>
+	);
+}
+```
+
+### Additional Hooks
+
+#### useLiveSignal
+
+The `useLiveSignal` hook allows you to create a local signal that stays synchronized with an external signal.
+
+```js
+import { useLiveSignal } from "@preact/signals/utils";
+import { signal } from "@preact/signals";
+
+const external = signal(0);
+
+function Component() {
+	const local = useLiveSignal(external);
+	// local will automatically update when external changes
+}
+```
+
+#### useSignalRef
+
+The `useSignalRef` hook creates a signal that behaves like a React ref with a `.current` property.
+
+```js
+import { useSignalRef } from "@preact/signals/utils";
+
+function Component() {
+	const ref = useSignalRef(null);
+	return <div ref={ref}>The ref's value is {ref.current}</div>;
+}
+```
+
 ## License
 
 `MIT`, see the [LICENSE](../../LICENSE) file.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@preact/signals",
-  "version": "2.0.5",
+  "version": "2.1.0",
   "license": "MIT",
   "description": "Manage state with style in Preact",
   "keywords": [],
@@ -30,6 +30,12 @@
       "browser": "./dist/signals.module.js",
       "import": "./dist/signals.mjs",
       "require": "./dist/signals.js"
+    },
+    "./utils": {
+      "types": "./utils/dist/index.d.ts",
+      "browser": "./utils/dist/utils.module.js",
+      "import": "./utils/dist/utils.mjs",
+      "require": "./utils/dist/utils.js"
     }
   },
   "mangle": "../../mangle.json",
@@ -38,7 +44,10 @@
     "dist",
     "CHANGELOG.md",
     "LICENSE",
-    "README.md"
+    "README.md",
+    "utils/dist",
+    "utils/package.json",
+    "utils/src"
   ],
   "dependencies": {
     "@preact/signals-core": "^1.7.0"

package/utils/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@preact/signals-utils",
+  "description": "Sub package for @preact/signals that contains some useful utilities",
+  "private": true,
+  "amdName": "preactSignalsutils",
+  "main": "dist/utils.js",
+  "module": "dist/utils.module.js",
+  "unpkg": "dist/utils.min.js",
+  "types": "dist/index.d.ts",
+  "source": "src/index.ts",
+  "mangle": "../../../mangle.json",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "browser": "./dist/utils.module.js",
+      "import": "./dist/utils.mjs",
+      "require": "./dist/utils.js"
+    }
+  },
+  "dependencies": {
+    "@preact/signals-core": "workspace:^1.3.0"
+  },
+  "peerDependencies": {
+    "@preact/signals": "workspace:*",
+    "preact": ">= 10.25.0"
+  }
+}

package/utils/src/index.ts

@@ -0,0 +1,71 @@
+import { ReadonlySignal, Signal } from "@preact/signals-core";
+import { useSignal } from "@preact/signals";
+import { Fragment, createElement, JSX } from "preact";
+import { useMemo } from "preact/hooks";
+
+interface ShowProps<T = boolean> {
+	when: Signal<T> | ReadonlySignal<T>;
+	fallback?: JSX.Element;
+	children: JSX.Element | ((value: T) => JSX.Element);
+}
+
+export function Show<T = boolean>(props: ShowProps<T>): JSX.Element | null {
+	const value = props.when.value;
+	if (!value) return props.fallback || null;
+	return typeof props.children === "function"
+		? props.children(value)
+		: props.children;
+}
+
+interface ForProps<T> {
+	each:
+		| Signal<Array<T>>
+		| ReadonlySignal<Array<T>>
+		| (() => Signal<Array<T>> | ReadonlySignal<Array<T>>);
+	fallback?: JSX.Element;
+	children: (value: T, index: number) => JSX.Element;
+}
+
+export function For<T>(props: ForProps<T>): JSX.Element | null {
+	const cache = useMemo(() => new Map(), []);
+	let list = (
+		(typeof props.each === "function" ? props.each() : props.each) as Signal<
+			Array<T>
+		>
+	).value;
+
+	if (!list.length) return props.fallback || null;
+
+	const items = list.map((value, key) => {
+		if (!cache.has(value)) {
+			cache.set(value, props.children(value, key));
+		}
+		return cache.get(value);
+	});
+
+	return createElement(Fragment, null, items);
+}
+
+export function useLiveSignal<T>(
+	value: Signal<T> | ReadonlySignal<T>
+): Signal<Signal<T> | ReadonlySignal<T>> {
+	const s = useSignal(value);
+	if (s.peek() !== value) s.value = value;
+	return s;
+}
+
+export function useSignalRef<T>(value: T): Signal<T> & { current: T } {
+	const ref = useSignal(value) as Signal<T> & { current: T };
+	if (!("current" in ref))
+		Object.defineProperty(ref, "current", refSignalProto);
+	return ref;
+}
+const refSignalProto = {
+	configurable: true,
+	get(this: Signal) {
+		return this.value;
+	},
+	set(this: Signal, v: any) {
+		this.value = v;
+	},
+};