Merge pull request #2952 from preactjs/use-debug-name

Add addHookName to preact/devtools to relabel native hooks in devtools

devtools/package.json

@@ -9,6 +9,7 @@
 	"umd:main": "dist/devtools.umd.js",
 	"source": "src/index.js",
 	"license": "MIT",
+	"types": "src/index.d.ts",
 	"peerDependencies": {
 		"preact": "^10.0.0"
 	}

devtools/src/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Customize the displayed name of a useState, useReducer or useRef hook
+ * in the devtools panel.
+ *
+ * @param value Wrapped native hook.
+ * @param name Custom name
+ */
+export function addHookName<T>(value: T, name: string): T;

devtools/src/index.js

@@ -1,3 +1,15 @@
+import { options } from 'preact';
 import { initDevTools } from './devtools';
 
 initDevTools();
+
+/**
+ * Display a custom label for a custom hook for the devtools panel
+ * @type {<T>(value: T, name: string) => T}
+ */
+export function addHookName(value, name) {
+	if (options._addHookName) {
+		options._addHookName(name);
+	}
+	return value;
+}

devtools/test/browser/addHookName.test.js

@@ -0,0 +1,51 @@
+import { createElement, render, options } from 'preact';
+import { setupScratch, teardown } from '../../../test/_util/helpers';
+import { useState } from 'preact/hooks';
+import { addHookName } from 'preact/devtools';
+
+/** @jsx createElement */
+
+describe('addHookName', () => {
+	/** @type {HTMLDivElement} */
+	let scratch;
+
+	beforeEach(() => {
+		scratch = setupScratch();
+	});
+
+	afterEach(() => {
+		teardown(scratch);
+		delete options._addHookName;
+	});
+
+	it('should do nothing when no options hook is present', () => {
+		function useFoo() {
+			return addHookName(useState(0), 'foo');
+		}
+
+		function App() {
+			let [v] = useFoo();
+			return <div>{v}</div>;
+		}
+
+		expect(() => render(<App />, scratch)).to.not.throw();
+	});
+
+	it('should call options hook with value', () => {
+		let spy = (options._addHookName = sinon.spy());
+
+		function useFoo() {
+			return addHookName(useState(0), 'foo');
+		}
+
+		function App() {
+			let [v] = useFoo();
+			return <div>{v}</div>;
+		}
+
+		render(<App />, scratch);
+
+		expect(spy).to.be.calledOnce;
+		expect(spy).to.be.calledWith('foo');
+	});
+});

karma.conf.js

@@ -274,7 +274,7 @@ module.exports = function(config) {
 			{
 				pattern:
 					config.grep ||
-					'{debug,hooks,compat,test-utils,jsx-runtime,}/test/{browser,shared}/**/*.test.js',
+					'{debug,devtools,hooks,compat,test-utils,jsx-runtime,}/test/{browser,shared}/**/*.test.js',
 				watched: false,
 				type: 'js'
 			}
@@ -285,7 +285,7 @@ module.exports = function(config) {
 		},
 
 		preprocessors: {
-			'{debug,hooks,compat,test-utils,jsx-runtime,}/test/**/*': [
+			'{debug,devtools,hooks,compat,test-utils,jsx-runtime,}/test/**/*': [
 				'esbuild',
 				'sourcemap'
 			]

mangle.json

@@ -66,6 +66,7 @@
       "$_root": "__",
       "$_diff": "__b",
       "$_commit": "__c",
+      "$_addHookName": "__a",
       "$_render": "__r",
       "$_hook": "__h",
       "$_catchError": "__e",

src/index.d.ts

@@ -266,6 +266,7 @@ declare namespace preact {
 		requestAnimationFrame?: typeof requestAnimationFrame;
 		debounceRendering?(cb: () => void): void;
 		useDebugValue?(value: string | number): void;
+		_addHookName?(name: string | number): void;
 		__suspenseDidResolve?(vnode: VNode, cb: () => void): void;
 		// __canSuspenseResolve?(vnode: VNode, cb: () => void): void;
 	}