@journ/lift 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Journ
+
+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.md

@@ -0,0 +1,41 @@
+# @journ/lift
+
+React hooks for state and timing, built on fitter-happier. No DOM access, so they work in PWAs, React Native and Wails desktop apps alike.
+
+## Install
+
+```sh
+pnpm add @journ/lift react
+```
+
+## Usage
+
+```tsx
+import { useControllableState, useDebouncedValue, useDraft } from '@journ/lift'
+
+function Toggle(props: { pressed?: boolean; defaultPressed?: boolean; onPressedChange?: (pressed: boolean) => void }) {
+	const [pressed, setPressed] = useControllableState(
+		props.pressed,
+		props.defaultPressed ?? false,
+		props.onPressedChange,
+	)
+	return (
+		<button type='button' aria-pressed={pressed ?? false} onClick={() => setPressed(!pressed)}>
+			Toggle
+		</button>
+	)
+}
+
+function Search({ query }: { query: string }) {
+	const debouncedQuery = useDebouncedValue(query, 300)
+	return <p>{debouncedQuery}</p>
+}
+```
+
+| Entry                                | Exports                                                                |
+| ------------------------------------ | ---------------------------------------------------------------------- |
+| `@journ/lift/use-controllable-state` | `useControllableState(value, defaultValue, onChange)`                  |
+| `@journ/lift/use-debounced-value`    | `useDebouncedValue(value, delay)`                                      |
+| `@journ/lift/use-draft`              | `useDraft`: text typed freely that becomes a value on commit           |
+| `@journ/lift/required-context`       | `createRequiredContext(owner)`: a context whose hook throws outside it |
+| `@journ/lift/prefers-reduced-motion` | `prefersReducedMotion()`                                               |

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+import { prefersReducedMotion } from "./prefers-reduced-motion.js";
+import { createRequiredContext } from "./required-context.js";
+import { useControllableState } from "./use-controllable-state.js";
+import { useDebouncedValue } from "./use-debounced-value.js";
+import { Draft, UseDraftOptions, useDraft } from "./use-draft.js";
+export { type Draft, type UseDraftOptions, createRequiredContext, prefersReducedMotion, useControllableState, useDebouncedValue, useDraft };

package/dist/index.js

@@ -0,0 +1,6 @@
+import { prefersReducedMotion } from "./prefers-reduced-motion.js";
+import { createRequiredContext } from "./required-context.js";
+import { useControllableState } from "./use-controllable-state.js";
+import { useDebouncedValue } from "./use-debounced-value.js";
+import { useDraft } from "./use-draft.js";
+export { createRequiredContext, prefersReducedMotion, useControllableState, useDebouncedValue, useDraft };

package/dist/prefers-reduced-motion.d.ts

@@ -0,0 +1,3 @@
+//#region src/prefers-reduced-motion.d.ts
+export declare function prefersReducedMotion(): boolean;
+//#endregion

package/dist/prefers-reduced-motion.js

@@ -0,0 +1,6 @@
+//#region src/prefers-reduced-motion.ts
+function prefersReducedMotion() {
+	return typeof window !== "undefined" && window.matchMedia?.("(prefers-reduced-motion: reduce)").matches === true;
+}
+//#endregion
+export { prefersReducedMotion };

package/dist/required-context.d.ts

@@ -0,0 +1,8 @@
+import { Context } from "react";
+//#region src/required-context.d.ts
+/**
+ * A context that parts must be rendered inside of. The hook throws a clear error
+ * naming the owner, so a part used on its own fails loudly instead of rendering wrong.
+ */
+export declare function createRequiredContext<T>(owner: string): readonly [Context<T | null>, () => T];
+//#endregion

package/dist/required-context.js

@@ -0,0 +1,17 @@
+import { createContext, use } from "react";
+//#region src/required-context.ts
+/**
+* A context that parts must be rendered inside of. The hook throws a clear error
+* naming the owner, so a part used on its own fails loudly instead of rendering wrong.
+*/
+function createRequiredContext(owner) {
+	const RequiredContext = createContext(null);
+	const useRequired = () => {
+		const value = use(RequiredContext);
+		if (value === null) throw new Error(`Must be rendered inside ${owner}`);
+		return value;
+	};
+	return [RequiredContext, useRequired];
+}
+//#endregion
+export { createRequiredContext };

package/dist/use-controllable-state.d.ts

@@ -0,0 +1,7 @@
+//#region src/use-controllable-state.d.ts
+/**
+ * State that the caller may own. `value` undefined means uncontrolled: the hook
+ * keeps the state and still reports every change through `onChange`.
+ */
+export declare function useControllableState<T>(value: T | null | undefined, defaultValue: T | null, onChange?: (value: T) => void): readonly [T | null, (next: T) => void];
+//#endregion

package/dist/use-controllable-state.js

@@ -0,0 +1,17 @@
+import { useCallback, useState } from "react";
+//#region src/use-controllable-state.ts
+/**
+* State that the caller may own. `value` undefined means uncontrolled: the hook
+* keeps the state and still reports every change through `onChange`.
+*/
+function useControllableState(value, defaultValue, onChange) {
+	const [uncontrolled, setUncontrolled] = useState(defaultValue);
+	const controlled = value !== void 0;
+	const setValue = useCallback((next) => {
+		if (!controlled) setUncontrolled(next);
+		onChange?.(next);
+	}, [controlled, onChange]);
+	return [controlled ? value : uncontrolled, setValue];
+}
+//#endregion
+export { useControllableState };

package/dist/use-debounced-value.d.ts

@@ -0,0 +1,3 @@
+//#region src/use-debounced-value.d.ts
+export declare function useDebouncedValue<T>(value: T, delay: number): T;
+//#endregion

package/dist/use-debounced-value.js

@@ -0,0 +1,14 @@
+import { useEffect, useState } from "react";
+import { debounce } from "@journ/fitter-happier";
+//#region src/use-debounced-value.ts
+function useDebouncedValue(value, delay) {
+	const [debounced, setDebounced] = useState(value);
+	useEffect(() => {
+		const update = debounce(setDebounced, delay);
+		update(value);
+		return update.cancel;
+	}, [value, delay]);
+	return debounced;
+}
+//#endregion
+export { useDebouncedValue };

package/dist/use-draft.d.ts

@@ -0,0 +1,20 @@
+//#region src/use-draft.d.ts
+export interface UseDraftOptions<T> {
+  value: T;
+  format: (value: T) => string;
+  /** Return undefined to reject the text, which keeps the old value. */
+  parse: (text: string) => T | undefined;
+  onCommit: (value: T) => void;
+}
+export interface Draft {
+  text: string;
+  edit: (text: string) => void;
+  discard: () => void;
+  commit: () => void;
+}
+/**
+ * Text that is typed freely and only turns into a value on commit. While not
+ * editing it shows `format(value)`.
+ */
+export declare function useDraft<T>({ value, format, parse, onCommit }: UseDraftOptions<T>): Draft;
+//#endregion

package/dist/use-draft.js

@@ -0,0 +1,21 @@
+import { useState } from "react";
+//#region src/use-draft.ts
+/**
+* Text that is typed freely and only turns into a value on commit. While not
+* editing it shows `format(value)`.
+*/
+function useDraft({ value, format, parse, onCommit }) {
+	const [draft, setDraft] = useState(null);
+	return {
+		text: draft ?? format(value),
+		edit: setDraft,
+		discard: () => setDraft(null),
+		commit: () => {
+			const parsed = parse(draft ?? "");
+			if (parsed !== void 0) onCommit(parsed);
+			setDraft(null);
+		}
+	};
+}
+//#endregion
+export { useDraft };

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@journ/lift",
+  "version": "0.1.0",
+  "description": "React hooks for state and timing, built on fitter-happier. No DOM access, so they work in PWAs, React Native and Wails desktop apps alike.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/thommorais/kid-a.git",
+    "directory": "packages/lift"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "@journ/source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./prefers-reduced-motion": {
+      "@journ/source": "./src/prefers-reduced-motion.ts",
+      "types": "./dist/prefers-reduced-motion.d.ts",
+      "default": "./dist/prefers-reduced-motion.js"
+    },
+    "./required-context": {
+      "@journ/source": "./src/required-context.ts",
+      "types": "./dist/required-context.d.ts",
+      "default": "./dist/required-context.js"
+    },
+    "./use-controllable-state": {
+      "@journ/source": "./src/use-controllable-state.ts",
+      "types": "./dist/use-controllable-state.d.ts",
+      "default": "./dist/use-controllable-state.js"
+    },
+    "./use-debounced-value": {
+      "@journ/source": "./src/use-debounced-value.ts",
+      "types": "./dist/use-debounced-value.d.ts",
+      "default": "./dist/use-debounced-value.js"
+    },
+    "./use-draft": {
+      "@journ/source": "./src/use-draft.ts",
+      "types": "./dist/use-draft.d.ts",
+      "default": "./dist/use-draft.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@journ/fitter-happier": "0.1.0"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0"
+  },
+  "nx": {
+    "tags": [
+      "scope:hooks"
+    ]
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run",
+    "typecheck": "tsc -b",
+    "lint": "oxlint",
+    "format:check": "oxfmt --check"
+  }
+}