Merge e51907d into fa224d0

karma.conf.js

@@ -114,13 +114,16 @@ module.exports = function(config) {
 			{
 				pattern:
 					config.grep ||
-					'{debug,hooks,compat,test-utils,}/test/{browser,shared}/**/*.test.js',
+					'{debug,hooks,compat,test-utils,shared-internals,}/test/{browser,shared}/**/*.test.js',
 				watched: false
 			}
 		],
 
 		preprocessors: {
-			'{debug,hooks,compat,test-utils,}/test/**/*': ['webpack', 'sourcemap']
+			'{debug,hooks,compat,test-utils,shared-internals,}/test/**/*': [
+				'webpack',
+				'sourcemap'
+			]
 		},
 
 		webpack: {
@@ -156,6 +159,10 @@ module.exports = function(config) {
 					'preact/compat': path.join(__dirname, './compat/src'),
 					'preact/hooks': path.join(__dirname, './hooks/src'),
 					'preact/test-utils': path.join(__dirname, './test-utils/src'),
+					'preact/shared-internals': path.join(
+						__dirname,
+						'./shared-internals/src'
+					),
 					preact: path.join(__dirname, './src')
 				}
 			},

package.json

@@ -22,6 +22,7 @@
     "build:hooks": "microbundle build --raw --cwd hooks",
     "build:test-utils": "microbundle build --raw --cwd test-utils",
     "build:compat": "microbundle build --raw --cwd compat --globals 'preact/hooks=preactHooks'",
+    "build:shared-internals": "microbundle build --raw --cwd shared-internals",
     "dev": "microbundle watch --raw --format cjs",
     "dev:hooks": "microbundle watch --raw --format cjs --cwd hooks",
     "dev:compat": "microbundle watch --raw --format cjs --cwd compat --globals 'preact/hooks=preactHooks'",
@@ -118,7 +119,10 @@
     "hooks/package.json",
     "test-utils/src",
     "test-utils/package.json",
-    "test-utils/dist"
+    "test-utils/dist",
+    "shared-internals/src",
+    "shared-internals/package.json",
+    "shared-internals/dist"
   ],
   "keywords": [
     "preact",

shared-internals/README.md

@@ -0,0 +1,5 @@
+# Shared internals
+
+This package is only intended to be used for testing frameworks or debuggers which need to access private internals of Preact. Examples for that are the devtools and adapter for the enzyme testing library. Don't use this for "normal" apps. Please use the public API for those.
+
+Note that due to it being treated as internal, it doesn't follow the same stability guarantees as our public API. We may introduce breaking changes here at any point.

shared-internals/mangle.json

@@ -0,0 +1,48 @@
+{
+  "help": {
+    "what is this file?": "It controls protected/private property mangling so that minified builds have consistent property names.",
+    "why are there duplicate minified properties?": "Most properties are only used on one type of objects, so they can have the same name since they will never collide. Doing this reduces size."
+  },
+  "minify": {
+    "mangle": {
+      "properties": {
+        "regex": "^_"
+      }
+    },
+    "compress": {
+      "hoist_vars": true,
+      "reduce_funcs": false
+    }
+  },
+  "props": {
+    "cname": 6,
+    "props": {
+      "$_depth": "__b",
+      "$_lastDomChild": "__d",
+      "$_dirty": "__d",
+      "$_force": "__e",
+      "$_nextState": "__s",
+      "$_renderCallbacks": "__h",
+      "$_vnode": "__v",
+      "$_children": "__k",
+      "$_suspensions": "__u",
+      "$_dom": "__e",
+      "$_component": "__c",
+      "$__html": "__html",
+      "$_parent": "__",
+      "$_pendingError": "__E",
+      "$_processingException": "__",
+      "$_context": "__n",
+      "$_defaultValue": "__",
+      "$_id": "__c",
+      "$_parentDom": "__P",
+      "$_root": "__",
+      "$_diff": "__b",
+      "$_commit": "__c",
+      "$_render": "__r",
+      "$_hook": "__h",
+      "$_catchError": "__e",
+      "$_unmount": "_e"
+    }
+  }
+}

shared-internals/package.json

@@ -0,0 +1,19 @@
+{
+	"name": "shared-internals",
+	"amdName": "sharedInternals",
+	"version": "0.1.0",
+	"private": true,
+	"description": "Shared internals for testing or debugging adapters",
+	"main": "dist/shared-internals.js",
+	"module": "dist/shared-internals.module.js",
+	"umd:main": "dist/shared-internals.umd.js",
+	"source": "src/index.js",
+	"license": "MIT",
+	"types": "src/index.d.ts",
+	"peerDependencies": {
+		"preact": "^10.0.0"
+	},
+	"mangle": {
+		"regex": "^_"
+	}
+}

shared-internals/src/index.d.ts

@@ -0,0 +1,40 @@
+import * as preact from '../../src';
+
+export function getParent(vnode: preact.VNode): preact.VNode | null;
+export function getComponent(vnode: preact.VNode): preact.Component | null;
+export function getDom(vnode: preact.VNode): HTMLElement | Text | null;
+export function getChildren(
+	vnode: preact.VNode
+): Array<preact.VNode | null | undefined>;
+export function getComponentVNode(component: preact.Component): preact.VNode;
+export function getContainerVNode(
+	container: Element | Document | ShadowRoot | DocumentFragment
+): preact.VNode | null;
+
+//
+// Option hooks
+//
+// These are using the public types to avoid conflicts. Downside of that
+// is that the return types need to be declared manually here.
+type OptionsDiff = (vnode: preact.VNode) => void;
+type OptionsCommit = (
+	vnode: preact.VNode,
+	commitQueue: preact.Component[]
+) => void;
+type OptionsRoot = (
+	vnode: preact.ComponentChild,
+	parent: Element | Document | ShadowRoot | DocumentFragment
+) => void;
+
+// Getters
+export function getOptionsDiff(options: preact.Options): OptionsDiff;
+export function getOptionsCommit(options: preact.Options): OptionsCommit;
+export function getOptionsRoot(options: preact.Options): OptionsRoot;
+
+// Setters
+export function setOptionsDiff(options: preact.Options, fn: OptionsDiff): void;
+export function setOptionsCommit(
+	options: preact.Options,
+	fn: OptionsCommit
+): void;
+export function setOptionsRoot(options: preact.Options, fn: OptionsRoot): void;

shared-internals/src/index.js

@@ -0,0 +1,120 @@
+/**
+ * Get the direct parent of a `VNode`.
+ * @param {import('../../src/internal').VNode} vnode
+ * @returns {import('../../src/internal').VNode | null}
+ */
+export function getParent(vnode) {
+	return vnode._parent;
+}
+
+/**
+ * Return the `Component` instance associated with a rendered `VNode`.
+ * @param {import('../../src/internal').VNode} vnode
+ * @returns {import('../../src/internal').Component | null}
+ */
+export function getComponent(vnode) {
+	return vnode._component;
+}
+
+/**
+ * Return the rendered DOM node associated with a rendered `VNode`.
+ *
+ * "Associated" here means either the DOM node directly output as a result of
+ * rendering the vnode (for DOM vnodes) or the first DOM node output by a
+ * child vnode for component vnodes.
+ *
+ * @param {import('../../src/internal').VNode} vnode
+ * @returns {import('../../src/internal').PreactElement | Text | null}
+ */
+export function getDom(vnode) {
+	return vnode._dom;
+}
+
+/**
+ * Return the child `VNodes` associated with a rendered `VNode`.
+ * @param {import('../../src/internal').VNode} vnode
+ * @returns {Array<import('../../src/internal').VNode | null | undefined>}
+ */
+export function getChildren(vnode) {
+	return vnode._children;
+}
+
+/**
+ * Return the `VNode` of a `component` when it was last rendered.
+ * @param {import('../../src/internal').Component} component
+ * @returns {import('../../src/internal').VNode}
+ */
+export function getComponentVNode(component) {
+	return component._vnode;
+}
+
+/**
+ * Return the `VNode` that is associated with a DOM node that was rendered into.
+ * This property only exists on root nodes, commonly called containers. They
+ * are created via top-level `render(vnode, container)` calls.
+ * @param {Element | Document | ShadowRoot | DocumentFragment} container
+ * @returns {import('../../src/internal').VNode | null}
+ */
+export function getContainerVNode(container) {
+	return container._children;
+}
+
+// Options getters/setters
+
+/**
+ * Return private `options._diff` hook that's called before `diff()`.
+ * @param {import('../../src/internal').Options} options
+ * @returns {import('../../src/internal').Options["_diff"]}
+ */
+export function getOptionsDiff(options) {
+	return options._diff;
+}
+
+/**
+ * Return private `options._commit` hook that's called at the end of
+ * each commit.
+ * @param {import('../../src/internal').Options} options
+ * @returns {import('../../src/internal').Options["_commit"]}
+ */
+export function getOptionsCommit(options) {
+	return options._commit;
+}
+
+/**
+ * Return private `options._root` hook that's called when a tree
+ * is rendered from the top via `render(vnode, dom)`.
+ * @param {import('../../src/internal').Options} options
+ * @returns {import('../../src/internal').Options["_root"]}
+ */
+export function getOptionsRoot(options) {
+	return options._root;
+}
+
+/**
+ * Set private `options._diff` hook that's called before `diff()`.
+ * @param {import('../../src/internal').Options} options
+ * @param {import('../../src/internal').Options["_diff"]} fn
+ */
+export function setOptionsDiff(options, fn) {
+	options._diff = fn;
+}
+
+/**
+ * Set private `options._commit` hook that's called at the end of
+ * each commit.
+ * @param {import('../../src/internal').Options} options
+ * @param {import('../../src/internal').Options["_commit"]} fn
+ */
+export function setOptionsCommit(options, fn) {
+	options._commit = fn;
+}
+
+/**
+ * Set private `options._root` hook that's called at the end of
+ * each commit.
+ * @param {import('../../src/internal').Options} options
+ * @param {import('../../src/internal').Options["_root"]} fn
+ */
+export function setOptionsRoot(options, fn) {
+	options._root = fn;
+}