✨ add @coven/pair

Author: loucyx

@coven/pair/README.md

@@ -0,0 +1,79 @@
+<img alt="Coven Engineering Pair logo" src="https://raw.githubusercontent.com/covenengineering/libraries/main/@coven/pair/logo.svg" height="108" />
+
+[![JSR](https://jsr.io/badges/@coven/pair)](https://jsr.io/@coven/pair)
+[![JSR Score](https://jsr.io/badges/@coven/pair/score)](https://jsr.io/@coven/pair/score)
+
+🧩 [Paired hook pattern](https://lou.cx/articles/the-paired-hook-pattern)
+helper.
+
+## Examples
+
+### Preact
+
+```tsx
+import { useState } from "preact";
+import { pair } from "@coven/pair/preact";
+
+const useCount = (initialCount) => {
+	const [count, setCount] = useState(initialCount);
+
+	return { onClick: () => setCount(count + 1), children: count };
+};
+
+const PairedCount = pair(useCount);
+
+const Component = ({ array = [] }) => (
+	<ul>
+		{array.map((key) => (
+			<PairedCount key={key}>
+				{(usePairedCount) => {
+					const props = usePairedCount(key);
+
+					return (
+						<li>
+							<button type="button" {...props} />
+						</li>
+					);
+				}}
+			</PairedCount>
+		))}
+	</ul>
+);
+```
+
+### React
+
+```tsx
+import { useState } from "react";
+import { pair } from "@coven/pair/react";
+
+const useCount = (initialCount) => {
+	const [count, setCount] = useState(initialCount);
+
+	return { onClick: () => setCount(count + 1), children: count };
+};
+
+const PairedCount = pair(useCount);
+
+const Component = ({ array = [] }) => (
+	<ul>
+		{array.map((key) => (
+			<PairedCount key={key}>
+				{(usePairedCount) => {
+					const props = usePairedCount(key);
+
+					return (
+						<li>
+							<button type="button" {...props} />
+						</li>
+					);
+				}}
+			</PairedCount>
+		))}
+	</ul>
+);
+```
+
+## Other links
+
+- [Coverage](https://coveralls.io/github/covenengineering/libraries).

@coven/pair/deno.json

@@ -0,0 +1,9 @@
+{
+	"name": "@coven/pair",
+	"version": "0.0.5",
+	"exports": {
+		".": "./mod.ts",
+		"./preact": "./preact/mod.ts",
+		"./react": "./react/mod.ts"
+	}
+}

@coven/pair/logo.svg

@@ -0,0 +1,2 @@
+export * as preact from "./preact/mod.ts";
+export * as react from "./react/mod.ts";

@coven/pair/mod.ts

@@ -0,0 +1,15 @@
+import type { PairedRenderFunction } from "./PairedRenderFunction.ts";
+
+/**
+ * Paired component properties (just children with the paired hook render function).
+ *
+ * @category Internal
+ */
+export type PairedComponentProperties<
+	Hook extends (...attributes: never) => unknown,
+> = {
+	/**
+	 * Children has to be a function, and the argument is the paired hook.
+	 */
+	readonly children: PairedRenderFunction<Hook>;
+};

@coven/pair/preact/PairedComponentProperties.ts

@@ -0,0 +1,14 @@
+import type { Unary } from "@coven/types";
+import type { h } from "preact";
+
+/**
+ * Function that receives the paired hook and must return a `VNode`.
+ *
+ * @category Internal
+ */
+export type PairedRenderFunction<
+	Hook extends (...attributes: never) => unknown,
+> = Unary<
+	[hook: Hook],
+	ReturnType<typeof h>
+>;

@coven/pair/preact/PairedRenderFunction.ts

@@ -0,0 +1,3 @@
+export { pair } from "./pair.ts";
+export type { PairedComponentProperties } from "./PairedComponentProperties.ts";
+export type { PairedRenderFunction } from "./PairedRenderFunction.ts";

@coven/pair/preact/mod.ts

@@ -0,0 +1,53 @@
+import type { FunctionComponent } from "preact";
+import type { PairedComponentProperties } from "./PairedComponentProperties.ts";
+
+/**
+ * Creates a component with a function children that has the given hook in context.
+ *
+ * @example
+ * ```tsx
+ * const useCount = initialCount => {
+ * 	const [count, setCount] = useState(initialCount);
+ *
+ * 	return { onClick: () => setCount(count + 1), children: count };
+ * };
+ *
+ * const PairedCount = pair(useCount);
+ *
+ * const Component = ({ array = [] }) => (
+ * 	<ul>
+ * 		{array.map(key => (
+ * 			<PairedCount key={key}>
+ * 				{usePairedCount => {
+ * 					const props = usePairedCount(key);
+ *
+ * 					return (
+ * 						<li>
+ * 							<button
+ * 								type="button"
+ * 								{...props}
+ * 							/>
+ * 						</li>
+ * 					);
+ * 				}}
+ * 			</PairedCount>
+ * 		))}
+ * 	</ul>
+ * );
+ * ```
+ * @param hook Hook to be paired.
+ * @returns Component that expects a function as children with the paired hook.
+ */
+export const pair = <Hook extends (...attributes: never) => unknown>(
+	hook: Hook,
+): FunctionComponent<PairedComponentProperties<Hook>> => {
+	const PairedComponent = ((properties) => properties.children(hook)) as
+		& FunctionComponent<
+			PairedComponentProperties<Hook>
+		>
+		& { displayName: string };
+
+	return (
+		(PairedComponent.displayName = `paired(${hook.name})`), PairedComponent
+	);
+};

@coven/pair/preact/pair.ts

@@ -0,0 +1,15 @@
+import type { PairedRenderFunction } from "./PairedRenderFunction.ts";
+
+/**
+ * Paired component properties (just children with the paired hook render function).
+ *
+ * @category Internal
+ */
+export type PairedComponentProperties<
+	Hook extends (...attributes: never) => unknown,
+> = {
+	/**
+	 * Children has to be a function, and the argument is the paired hook.
+	 */
+	readonly children: PairedRenderFunction<Hook>;
+};

@coven/pair/react/PairedComponentProperties.ts

@@ -0,0 +1,14 @@
+import type { Unary } from "@coven/types";
+import type { createElement } from "react";
+
+/**
+ * Function that receives the paired hook and must return a `ReactElement`.
+ *
+ * @category Internal
+ */
+export type PairedRenderFunction<
+	Hook extends (...attributes: never) => unknown,
+> = Unary<
+	[hook: Hook],
+	ReturnType<typeof createElement>
+>;

@coven/pair/react/PairedRenderFunction.ts

@@ -0,0 +1,3 @@
+export { pair } from "./pair.ts";
+export type { PairedComponentProperties } from "./PairedComponentProperties.ts";
+export type { PairedRenderFunction } from "./PairedRenderFunction.ts";

@coven/pair/react/mod.ts

@@ -0,0 +1,46 @@
+import type { FunctionComponent } from "react";
+import { pair as preactPair } from "../preact/pair.ts";
+import type { PairedComponentProperties } from "./PairedComponentProperties.ts";
+
+/**
+ * Creates a component with a function children that has the given hook in context.
+ *
+ * @example
+ * ```tsx
+ * const useCount = initialCount => {
+ * 	const [count, setCount] = useState(initialCount);
+ *
+ * 	return { onClick: () => setCount(count + 1), children: count };
+ * };
+ *
+ * const PairedCount = pair(useCount);
+ *
+ * const Component = ({ array = [] }) => (
+ * 	<ul>
+ * 		{array.map(key => (
+ * 			<PairedCount key={key}>
+ * 				{usePairedCount => {
+ * 					const props = usePairedCount(key);
+ *
+ * 					return (
+ * 						<li>
+ * 							<button
+ * 								type="button"
+ * 								{...props}
+ * 							/>
+ * 						</li>
+ * 					);
+ * 				}}
+ * 			</PairedCount>
+ * 		))}
+ * 	</ul>
+ * );
+ * ```
+ * @param hook Hook to be paired.
+ * @returns Component that expects a function as children with the paired hook.
+ */
+export const pair = preactPair as <
+	Hook extends (...attributes: never) => unknown,
+>(
+	hook: Hook,
+) => FunctionComponent<PairedComponentProperties<Hook>>;

@coven/pair/react/pair.ts

@@ -15,6 +15,7 @@ libraries:
   build regular expressions.
 - 🌪️ [`@coven/iterables`](https://jsr.io/@coven/iterables) — Iteration rituals.
 - 💀 [`@coven/math`](https://jsr.io/@coven/math) — Math witchcraft.
+- 🧩 [`@coven/pair`](https://jsr.io/@coven/pair) — Paired hook pattern helper.
 - 💫 [`@coven/parsers`](https://jsr.io/@coven/parsers) — Parsing charms.
 - 🛡️ [`@coven/predicates`](https://jsr.io/@coven/predicates) — Predicate wards.
 - 🖌️ [`@coven/terminal`](https://jsr.io/@coven/terminal) — Delightfully simple

README.md

@@ -11,9 +11,8 @@ to `1.0.0` for everything. Now about the actual "to do":
 - [x] Move `functional-expression` as `@coven/expression`.
 - [x] Move `@lou.codes/cron` as `@coven/cron`.
 - [x] Move `@lou.codes/notify` as `@simulcast/core`.
-- [ ] Move `react-pair` as `@coven/react-pair`.
-- [ ] Move `preact-pair` as `@coven/preact-pair`.
-- [ ] Check if is worth it to create `@coven/solid-pair`.
+- [x] Move `*-pair` as `@coven/pair`.
+- [x] Check if is worth it to create `@coven/solid-pair` (they don't need this).
 - [ ] Cleanup tests.
 - [ ] Cleanup docs.
 - [ ] Start working on new `@simulcast/{name}` libs:

TODO.md

@@ -20,7 +20,15 @@
 		"singleQuote": false,
 		"useTabs": true
 	},
-	"imports": { "@std/assert": "jsr:@std/assert@^1.0.6" },
+	"imports": {
+		"@std/assert": "jsr:@std/assert@^1.0.6",
+		"@types/react": "npm:@types/react@^18.3.11",
+		"@types/react-dom": "npm:@types/react-dom@^18.3.1",
+		"preact": "npm:preact@^10.24.2",
+		"preact-render-to-string": "npm:preact-render-to-string@^6.5.11",
+		"react": "npm:react@^18.3.1",
+		"react-dom": "npm:react-dom@^18.3.1"
+	},
 	"lint": {
 		"rules": {
 			"include": [
@@ -135,6 +143,7 @@
 		"./@coven/expression",
 		"./@coven/iterables",
 		"./@coven/math",
+		"./@coven/pair",
 		"./@coven/parsers",
 		"./@coven/predicates",
 		"./@coven/terminal",

deno.json

@@ -0,0 +1,37 @@
+/** @jsxImportSource preact */
+import { pair, type PairedComponentProperties } from "@coven/pair/preact";
+import { assertStrictEquals } from "@std/assert";
+import { renderToString } from "preact-render-to-string";
+import { useState } from "preact/hooks";
+
+const Render = (usePairedState: typeof useState) => {
+	const [count, setCount] = usePairedState(0);
+
+	return (
+		<button onClick={() => setCount(count + 1)} type="button">
+			{count}
+		</button>
+	);
+};
+
+const Wanted = ({ children }: PairedComponentProperties<typeof useState>) =>
+	children(useState);
+
+const key = "TEST";
+
+const PairedState = pair(useState);
+
+Deno.test("Paired hook with key returns component wrapping hook and with key", () =>
+	assertStrictEquals(
+		renderToString(<PairedState key={key}>{Render}</PairedState>),
+		renderToString(<Wanted key={key}>{Render}</Wanted>),
+	));
+
+Deno.test("Paired hook without key returns component wrapping hook and without key", () =>
+	assertStrictEquals(
+		renderToString(<PairedState>{Render}</PairedState>),
+		renderToString(<Wanted>{Render}</Wanted>),
+	));
+
+Deno.test("Paired hook has a displayName that reflects it's a paired hook", () =>
+	assertStrictEquals(PairedState.displayName, `paired(${useState.name})`));

tests/@coven/pair/preact.test.tsx

@@ -0,0 +1,41 @@
+/** @jsxImportSource react */
+/** @jsxImportSourceTypes @types/react */
+import { pair, type PairedComponentProperties } from "@coven/pair/react";
+import { assertStrictEquals } from "@std/assert";
+import { useState } from "react";
+import { renderToString } from "react-dom/server";
+
+const Render = (usePairedState: typeof useState) => {
+	const [count, setCount] = usePairedState(0);
+
+	return (
+		<button onClick={() => setCount(count + 1)} type="button">
+			{count}
+		</button>
+	);
+};
+
+const Wanted = ({ children }: PairedComponentProperties<typeof useState>) =>
+	children(useState);
+
+const key = "TEST";
+
+const PairedState = pair(useState);
+
+Deno.test("Paired hook with key returns component wrapping hook and with key", () =>
+	assertStrictEquals(
+		renderToString(<PairedState key={key}>{Render}</PairedState>),
+		renderToString(<Wanted key={key}>{Render}</Wanted>),
+	));
+
+Deno.test("Paired hook without key returns component wrapping hook and without key", () =>
+	assertStrictEquals(
+		renderToString(<PairedState>{Render}</PairedState>),
+		renderToString(<Wanted>{Render}</Wanted>),
+	));
+
+Deno.test("Paired hook has a displayName that reflects it's a paired hook", () =>
+	assertStrictEquals(
+		PairedState.displayName,
+		`paired(${useState.name})`,
+	));

tests/@coven/pair/react.test.tsx

@@ -8,7 +8,6 @@ type TestRegistry = { [TEST_EVENT]: never };
 Deno.test("emit with listeners calls the listeners", () => {
 	let called = false;
 	emit<TestRegistry>({
-		// eslint-disable-next-line no-param-reassign
 		[TEST_EVENT]: [() => (called = true)],
 	})(TEST_EVENT)();