feat(hooks): add use hook

compat/src/index.d.ts

@@ -130,6 +130,8 @@ declare namespace React {
 		subscribe: (flush: () => void) => () => void,
 		getSnapshot: () => T
 	): T;
+	// React 19 hooks
+	export import use = _hooks.use;
 	export function useEffectEvent<T extends Function>(cb: T): T;
 
 	// Preact Defaults

compat/src/index.js

@@ -19,7 +19,8 @@ import {
 	useMemo,
 	useReducer,
 	useRef,
-	useState
+	useState,
+	use
 } from 'preact/hooks';
 import { Children } from './Children';
 import { PureComponent } from './PureComponent';
@@ -208,6 +209,7 @@ export default {
 	useMemo,
 	useCallback,
 	useContext,
+	use,
 	useDebugValue,
 	version,
 	Children,

compat/test/browser/exports.test.js

@@ -41,6 +41,7 @@ describe('compat exports', () => {
 		expect(Compat.useInsertionEffect).to.be.a('function');
 		expect(Compat.useTransition).to.be.a('function');
 		expect(Compat.useDeferredValue).to.be.a('function');
+		expect(Compat.use).to.be.a('function');
 
 		// Suspense
 		expect(Compat.Suspense).to.be.a('function');
@@ -82,6 +83,7 @@ describe('compat exports', () => {
 		expect(Named.useMemo).to.be.a('function');
 		expect(Named.useCallback).to.be.a('function');
 		expect(Named.useContext).to.be.a('function');
+		expect(Named.use).to.be.a('function');
 
 		// Suspense
 		expect(Named.Suspense).to.be.a('function');

compat/test/ts/index.tsx

@@ -17,6 +17,12 @@ React.createPortal(<div />, document.createDocumentFragment());
 React.createPortal(<div />, document.body.shadowRoot!);
 
 const Ctx = React.createContext({ contextValue: '' });
+const contextValue: { contextValue: string } = React.use(Ctx);
+const promiseValue: string = React.use(Promise.resolve('value'));
+
+contextValue.contextValue.toLowerCase();
+promiseValue.toLowerCase();
+
 class SimpleComponentWithContextAsProvider extends React.Component {
 	componentProp = 'componentProp';
 	render() {

hooks/src/index.d.ts

@@ -123,6 +123,17 @@ export function useMemo<T>(factory: () => T, inputs: Inputs | undefined): T;
  */
 export function useContext<T>(context: PreactContext<T>): T;
 
+/**
+ * Read the value of a resource like a Promise or a Context. Unlike other
+ * hooks, `use` may be called conditionally.
+ *
+ * When passed a pending Promise the component suspends until it settles,
+ * rethrowing the rejection reason if it rejects.
+ *
+ * @param resource The Promise or Context to read
+ */
+export function use<T>(resource: Promise<T> | PreactContext<T>): T;
+
 /**
  * Customize the displayed value in the devtools panel.
  *

hooks/src/index.js

@@ -164,6 +164,48 @@ function getHookState(index, type) {
 	return hooks._list[index];
 }
 
+/**
+ * Read the value of a Promise (suspending while pending) or a Context.
+ * Unlike other hooks, `use` may be called conditionally.
+ * @template T
+ * @param {Promise<T> | import('preact').PreactContext<T>} resource
+ * @returns {T}
+ */
+export function use(resource) {
+	if (options._hook) {
+		options._hook(currentComponent, currentIndex, 12);
+	}
+
+	if (typeof resource.then == 'function') {
+		const thenable =
+			/** @type {Promise<T> & { status?: string, value?: T, reason?: any }} */ (
+				resource
+			);
+		if (thenable.status == 'fulfilled') return thenable.value;
+		if (thenable.status == 'rejected') throw thenable.reason;
+		if (thenable.status != 'pending') {
+			thenable.status = 'pending';
+			thenable.then(
+				value => {
+					thenable.status = 'fulfilled';
+					thenable.value = value;
+				},
+				reason => {
+					thenable.status = 'rejected';
+					thenable.reason = reason;
+				}
+			);
+		}
+		throw thenable;
+	}
+
+	const context = /** @type {import('./internal').PreactContext} */ (resource);
+	const provider = currentComponent.context[context._id];
+	if (!provider) return context._defaultValue;
+	provider.sub(currentComponent);
+	return provider.props.value;
+}
+
 /**
  * @template {unknown} S
  * @param {import('./index').Dispatch<import('./index').StateUpdater<S>>} [initialState]