react-component-instance 0.0.0 → 0.0.1

package/README.md

@@ -0,0 +1,27 @@
+# react-component-instance
+
+Get a React class component instance from its `DOM` elements
+
+```javascript
+import getInstance from 'react-component-instance'
+```
+
+## With `@testing-library/react`
+
+**Note** that for use with _Testing Library_ import from `react-component-instance/container`
+
+```javascript
+import getInstance from 'react-component-instance/container'
+
+import {
+  render
+} from '@testing-library/react'
+
+const {
+  container
+} = render(
+  <Component />
+)
+
+const instance = getInstance(container)
+```

package/babel.config.cjs

@@ -0,0 +1,42 @@
+const debug = require('debug')
+
+const log = debug('react-component-instance')
+
+const {
+  env: {
+    NODE_ENV = 'development'
+  }
+} = process
+
+log('`react-component-instance` is awake')
+
+function env () {
+  log({ NODE_ENV })
+
+  return (
+    NODE_ENV === 'production'
+  )
+}
+
+const presets = [
+  [
+    '@babel/env',
+    {
+      targets: {
+        node: 'current'
+      },
+      useBuiltIns: 'usage',
+      corejs: 3
+    }
+  ],
+  '@babel/react'
+]
+
+// @ts-ignore
+module.exports = (api) => {
+  if (api) api.cache.using(env)
+
+  return {
+    presets
+  }
+}

package/eslint.config.mjs

@@ -1,36 +1,168 @@
 import globals from 'globals'
+import standard from '@sequencemedia/eslint-config-standard/configs/recommended/merge'
+import typescript from '@sequencemedia/eslint-config-typescript/configs/recommended/merge'
+import babelParser from '@babel/eslint-parser'
+import typescriptParser from '@typescript-eslint/parser'
+import reactPlugin from 'eslint-plugin-react'
 
-import {
-  configs as standard
-} from '@sequencemedia/eslint-config-standard'
+const reactParserOptions = {
+  ecmaFeatures: {
+    jsx: true
+  }
+}
+
+const reactPlugins = {
+  react: reactPlugin
+}
+
+const reactRules = {
+  'no-unused-vars': [
+    'error',
+    {
+      varsIgnorePattern: 'React'
+    }
+  ],
+  quotes: [
+    'error',
+    'single'
+  ],
+  'jsx-quotes': [
+    'error',
+    'prefer-single'
+  ],
+  'react/jsx-indent': [
+    'error',
+    2,
+    {
+      checkAttributes: true,
+      indentLogicalExpressions: true
+    }
+  ]
+}
 
-import {
-  configs as typescript
-} from '@sequencemedia/eslint-config-typescript'
+const reactSettings = {
+  react: {
+    version: 'detect'
+  }
+}
 
 export default [
+  /**
+   *  React config for all `jsx` files
+   */
   {
-    ...standard.recommended,
+    ...reactPlugin.configs.flat.recommended,
+    settings: {
+      ...reactSettings
+    }
+  },
+  /**
+   *  Standard config
+   */
+  standard({
     files: [
       '**/*.{mjs,cjs,mts,cts}'
     ],
+    ignores: [
+      'src'
+    ],
     languageOptions: {
-      ...standard.recommended.languageOptions,
       globals: {
         ...globals.node
       }
+    },
+    rules: {
+      'no-use-before-define': 'off'
     }
-  },
-  {
-    ...typescript.recommended,
+  }),
+  /**
+   *  Standard config for `mjs` and `mts` files
+   */
+  standard({
+    files: [
+      'src/**/*.{mjs,cjs,mts,cts}'
+    ],
+    languageOptions: {
+      globals: {
+        ...globals.browser
+      }
+    }
+  }),
+  /**
+   *  Standard config for `jsx` files
+   */
+  standard({
+    files: [
+      'src/**/*.jsx'
+    ],
+    ignores: [
+      'src/**/__tests__/**/*.jsx'
+    ],
+    languageOptions: {
+      parser: babelParser,
+      parserOptions: {
+        ...reactParserOptions,
+        project: null
+      },
+      globals: {
+        ...globals.browser
+      }
+    },
+    plugins: {
+      ...reactPlugins
+    }, // @ts-expect-error Storybook
+    rules: {
+      ...reactRules
+    },
+    settings: {
+      ...reactSettings
+    }
+  }),
+  /**
+   *  Standard config for `jsx` files
+   */
+  standard({
+    files: [
+      'src/**/__tests__/**/*.jsx'
+    ],
+    languageOptions: {
+      parser: babelParser,
+      parserOptions: {
+        ...reactParserOptions,
+        project: null
+      },
+      globals: {
+        ...globals.browser,
+        ...globals.jest
+      }
+    },
+    plugins: {
+      ...reactPlugins
+    }, // @ts-expect-error Storybook
+    rules: {
+      ...reactRules
+    },
+    settings: {
+      ...reactSettings
+    }
+  }),
+  /**
+   *  TypeScript config
+   */
+  typescript({
     files: [
       '**/*.{mts,cts}'
     ],
     languageOptions: {
-      ...typescript.recommended.languageOptions,
+      parser: typescriptParser,
+      parserOptions: {
+        projectService: true,
+        project: 'tsconfig.json'
+      },
       globals: {
-        ...globals.node
+        ...globals.browser,
+        ReactComponentInstanceTypes: 'readonly'
       }
     }
-  }
+  })
 ]

package/index.d.mts

@@ -1,5 +1,74 @@
+import type React from 'react'
+
 declare global {
-  namespace ReactComponentInstanceTypes {}
+  namespace ReactComponentInstanceTypes {
+    /**
+     *  https://github.com/bendtherules/react-fiber-traverse
+     */
+
+    export type FiberNode =
+      | FiberNodeForComponentClass
+      | FiberNodeForFunctionComponent
+      | FiberNodeForInstrinsicElement
+      | FiberNodeForTextNode
+
+    export interface FiberRootNode {
+      child: FiberNode
+      sibling: FiberNode | null
+
+      elementType: React.FunctionComponent
+      type: React.FunctionComponent
+
+      stateNode: {
+        current: FiberRootNode
+      }
+      return: FiberRootNode
+    }
+
+    export interface FiberNodeForFunctionComponent {
+      child: FiberNode | null
+      sibling: FiberNode | null
+
+      elementType: React.FunctionComponent
+      type: React.FunctionComponent
+
+      stateNode: null
+      return: FiberNode
+    }
+
+    export interface FiberNodeForComponentClass {
+      child: FiberNode | null
+      sibling: FiberNode | null
+
+      elementType: React.ComponentClass
+      type: React.ComponentClass
+
+      stateNode: React.Component
+      return: FiberNode
+    }
+
+    export interface FiberNodeForInstrinsicElement {
+      child: FiberNode | null
+      sibling: FiberNode | null
+
+      elementType: keyof React.JSX.IntrinsicElements
+      type: keyof React.JSX.IntrinsicElements
+
+      stateNode: HTMLElement
+      return: FiberNode
+    }
+
+    export interface FiberNodeForTextNode {
+      child: null
+      sibling: FiberNode | null
+
+      elementType: null
+      type: null
+
+      stateNode: Text
+      return: FiberNode
+    }
+  }
 }
 
 export {}

package/jest.config.mjs

@@ -0,0 +1,15 @@
+export default {
+  bail: 1,
+  verbose: true,
+  rootDir: '.',
+  roots: [
+    './src'
+  ],
+  testRegex: '(/__tests__/.*|(\\.|/)(test|spec))\\.(mjs?|jsx?)$',
+  testEnvironment: 'jsdom',
+  transform: {
+    '^.+\\.jsx$': 'babel-jest',
+    '^.+\\.mjs$': 'babel-jest'
+  },
+  moduleFileExtensions: ['js', 'mjs', 'cjs', 'jsx']
+}

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "react-component-instance",
-  "version": "0.0.0",
-  "main": "./index.mjs",
+  "version": "0.0.1",
+  "main": "./src/index.mjs",
   "type": "module",
   "types": "./index.d.mts",
   "author": {
-    "name": "Jonathan Perry for Sequence Media Limited",
-    "email": "jonathanperry@sequencemedia.net",
-    "url": "https://sequencemedia.net"
+    "name": "Jonathan Perry for Modern Poacher Limited",
+    "email": "jonathanperry@modernpoacher.com",
+    "url": "https://modernpoacher.com"
   },
   "license": "ISC",
   "engines": {
@@ -15,19 +15,41 @@
   },
   "repository": {
     "type": "git",
-    "url": "git://github.com/sequencemedia/react-component-instance.git"
+    "url": "git://github.com/modernpoacher/react-component-instance.git"
   },
   "scripts": {
     "lint": "eslint",
-    "lint:fix": "npm run lint -- --fix"
+    "lint:fix": "npm run lint -- --fix",
+    "test": "NODE_ENV=test jest",
+    "prepare": "husky"
   },
   "devDependencies": {
+    "@babel/core": "^7.26.10",
+    "@babel/eslint-parser": "^7.26.10",
+    "@babel/preset-env": "^7.26.9",
+    "@babel/preset-react": "^7.26.3",
     "@sequencemedia/eslint-config-standard": "^0.2.42",
     "@sequencemedia/eslint-config-typescript": "^0.1.60",
+    "@testing-library/jest-dom": "^6.6.3",
+    "@testing-library/react": "^16.2.0",
+    "@types/debug": "^4.1.12",
+    "@types/jest": "^29.5.14",
+    "@types/react": "^19.0.10",
+    "core-js": "^3.41.0",
     "eslint": "^9.22.0",
-    "globals": "^16.0.0"
+    "eslint-plugin-react": "^7.37.4",
+    "globals": "^16.0.0",
+    "husky": "^9.1.7",
+    "jest": "^29.7.0",
+    "jest-environment-jsdom": "^29.7.0",
+    "react": "^19.0.0"
+  },
+  "imports": {
+    "#react-component-instance": "./src/index.mjs",
+    "#react-component-instance/container": "./src/container/index.mjs"
   },
   "exports": {
-    ".": "./src/index.mjs"
+    ".": "./src/index.mjs",
+    "./container": "./src/container/index.mjs"
   }
 }

package/src/__tests__/index.spec.jsx

@@ -0,0 +1,58 @@
+/**
+ *  @typedef {ReactComponentInstanceTypes.FiberNode} FiberNode
+ */
+
+import React from 'react'
+
+import '@testing-library/jest-dom'
+import {
+  render
+} from '@testing-library/react'
+
+import getReactComponentInstanceFrom, {
+  findReactComponentInstanceFor
+} from '#react-component-instance'
+
+describe('#react-component-instance', () => {
+  class Component extends React.Component {
+    render () {
+      return (
+        <div>
+          <div>
+            <div className='target' />
+          </div>
+        </div>
+      )
+    }
+  }
+
+  describe('`getReactComponentInstanceFrom`', () => {
+    it('gets the instance', () => {
+      const {
+        container: {
+          firstElementChild: element
+        }
+      } = render(
+        <Component />
+      )
+
+      expect(getReactComponentInstanceFrom(element))
+        .toBeInstanceOf(Component)
+    })
+  })
+
+  describe('`findReactComponentInstanceFor`', () => {
+    it('gets the instance', () => {
+      const {
+        container: {
+          firstElementChild: element
+        }
+      } = render(
+        <Component />
+      )
+
+      expect(findReactComponentInstanceFor(element?.querySelector('.target'), Component))
+        .toBeInstanceOf(Component)
+    })
+  })
+})

package/src/container/__tests__/index.spec.jsx

@@ -0,0 +1,29 @@
+import React from 'react'
+
+import '@testing-library/jest-dom'
+import {
+  render
+} from '@testing-library/react'
+
+import getReactComponentInstanceFrom from '#react-component-instance/container'
+
+describe('#react-component-instance/container', () => {
+  describe('`getReactComponentInstanceFrom`', () => {
+    class Component extends React.Component {
+      render () {
+        return <div />
+      }
+    }
+
+    it('gets the instance', () => {
+      const {
+        container
+      } = render(
+        <Component />
+      )
+
+      expect(getReactComponentInstanceFrom(container))
+        .toBeInstanceOf(Component)
+    })
+  })
+})

package/src/container/index.mjs

@@ -0,0 +1,44 @@
+/**
+ *  @typedef {ReactComponentInstanceTypes.FiberRootNode} FiberRootNode
+ */
+
+/**
+ *  @param {string} key
+ *  @returns {boolean}
+ */
+function isReactContainerKey (key) {
+  return key.startsWith('__reactContainer$')
+}
+
+/**
+ *  @param {HTMLElement} container
+ *  @returns {React.Component<any, any, any> | HTMLElement | Text | null}
+ */
+export default function getReactComponentInstanceFrom (container) {
+  const key = (
+    Object.keys(container)
+      .find(isReactContainerKey)
+  )
+
+  if (key) {
+    const { // @ts-expect-error
+      [key]: fiberNode
+    } = container
+
+    if (fiberNode) {
+      const {
+        stateNode: {
+          current: {
+            child: {
+              stateNode
+            }
+          }
+        }
+      } = fiberNode
+
+      return stateNode
+    }
+  }
+
+  throw new Error('Component instance is not found')
+}

package/src/index.mjs

@@ -0,0 +1,101 @@
+/**
+ *  @typedef {ReactComponentInstanceTypes.FiberNode} FiberNode
+ */
+
+/**
+ *  @param {PropertyKey} key
+ *  @returns {boolean}
+ */
+function isReactFiberKey (key) {
+  return String(key).startsWith('__reactFiber$')
+}
+
+/**
+ *  @param {FiberNode} fiberNode
+ *  @returns {Generator<FiberNode, void, unknown>}
+ */
+function * traverseFiberNodeTree (fiberNode) {
+  let currentNode = fiberNode
+
+  while (true) {
+    yield currentNode
+
+    currentNode = currentNode.return
+  }
+}
+
+/**
+ *  @param {Element | null | undefined} element
+ *  @param {(() => React.JSX.Element) | typeof React.Component} Component
+ *  @returns {React.Component<any, any, any> | HTMLElement | Text | null}
+ */
+export function findReactComponentInstanceFor (element, Component) {
+  if (element instanceof HTMLElement) {
+    const key = (
+      Object.keys(element)
+        .find(isReactFiberKey)
+    )
+
+    if (key) {
+      const { // @ts-expect-error
+        [key]: fiberNode
+      } = element
+
+      if (fiberNode) {
+        for (const fiber of traverseFiberNodeTree(fiberNode)) {
+          const {
+            type
+          } = fiber
+
+          if (type === Component) {
+            const {
+              stateNode
+            } = fiber
+
+            return stateNode
+          }
+        }
+      }
+    }
+
+    throw new Error('Component instance is not found')
+  }
+
+  throw new Error('Element is not an Element')
+}
+
+/**
+ *  @param {Element | null} element
+ *  @returns {React.Component<any, any, any> | HTMLElement | Text | null}
+ */
+export default function getReactComponentInstanceFrom (element) {
+  if (element instanceof HTMLElement) {
+    const key = (
+      Object.keys(element)
+        .find(isReactFiberKey)
+    )
+
+    if (key) {
+      const { // @ts-expect-error
+        [key]: fiberNode
+      } = element
+
+      if (fiberNode) {
+        /**
+         *  `return` is the component which owns `element`
+         */
+        const {
+          return: {
+            stateNode
+          }
+        } = fiberNode
+
+        return stateNode
+      }
+    }
+
+    throw new Error('Component instance is not found')
+  }
+
+  throw new Error('Element is not an Element')
+}

package/tsconfig.json

@@ -5,7 +5,8 @@
     "allowJs": true,
     "checkJs": true,
     "noEmit": true,
-    "strict": true
+    "strict": true,
+    "jsx": "react"
   },
   "include": [
     "."