packages/labs/react/use-controller.*

/create-component.*

/use-controller.*

- Added `useControler()` hook for creating React hooks from Reactive Controllers ([#1532](https://github.com/Polymer/lit-html/pulls/1532)).

- Adds React component wrapper for custom elements. Use by calling `createComponent` ([#1420](https://github.com/Polymer/lit-html/pulls/1420)).

React integration for Web Components and Reactive Controllers.

Reactive Controllers allow developers to hook a component's lifecycle to bundle

together state and behavior related to a feature. They are similar to React

hooks in the user cases and capabilities, but are plain JavaScript objects

instead of functions with hidden state.

`useController` is a React hook that create and stores a Reactive Controller

and drives its lifecycle using React hooks like `useState` and

`useLayoutEffect`.

`useController` uses `useState` to create and store an instance of a controller and a `ReactControllerHost`. It then calls the controller's lifecycle from the hook body and `useLayoutEffect` callbacks, emulating the `ReactiveElement` lifecycle as closely as possible. `ReactControllerHost` implements `addController` so that controller composition works and nested controller lifecycles are called correctly. `ReactControllerHost` also implements `requestUpdate` by calling a `useState` setter, so that a controller with new renderable state can cause its host component to re-render.

Controller timings are implemented as follows:

| Controller API | React hook equivalent |

| ---------------- | ----------------------------------- |

| constructor | useState initial value |

| hostConnected | useState initial value |

| hostDisconnected | useLayoutEffect cleanup, empty deps |

| hostUpdate | hook body |

| hostUpdated | useLayoutEffect |

| requestUpdate | useState setter |

| updateComplete | useLayoutEffect |

import * as React from 'react';

import {useController} from '@lit-labs/react/use-controller.js';

import {MouseController} from '@example/mouse-controller';

const useMouse = () => {

// Use useController to create and store a controller instance:

const controller = useController(React, (host) => new MouseController(host));

// return the controller: return controller;

// or return a custom object for a more React-idiomatic API:

return controller.position;

};

const Component = (props) => {

const mousePosition = useMouse();

return (

<pre>

x: {mousePosition.x}

y: {mousePosition.y}

</pre>

);

};

From inside your project folder, run:

$ npm install @lit-labs/react

"/create-component.{d.ts,d.ts.map,js,js.map}",

"/use-controller.{d.ts,d.ts.map,js,js.map}"

"clean": "rm -rf {index,create-component,use-controller}.{js,js.map,d.ts} development/ test/ *.tsbuildinfo",

entryPoints: ['index', 'create-component', 'use-controller'],

import 'react/umd/react.development.js';

import 'react-dom/umd/react-dom.development.js';

import {useController} from '../use-controller.js';

import {assert} from '@esm-bundle/chai';

import {

ReactiveController,

ReactiveControllerHost,

} from '@lit/reactive-element';

const {React, ReactDOM} = window;

suite('useController', () => {

let container: HTMLElement;

let ctorCallCount = 0;

setup(() => {

container = document.createElement('div');

document.body.appendChild(container);

ctorCallCount = 0;

});

teardown(() => {

if (container && container.parentNode) {

container.parentNode.removeChild(container);

}

});

class TestController implements ReactiveController {

host: ReactiveControllerHost;

a: string;

log: Array<string> = [];

constructor(host: ReactiveControllerHost, a: string) {

this.host = host;

this.a = a;

host.addController(this);

ctorCallCount++;

}

hostConnected() {

this.log.push('connected');

}

hostDisconnected() {

this.log.push('disconnected');

}

hostUpdate() {

this.log.push('update');

}

hostUpdated() {

this.log.push('updated');

}

}

const useTest = (a: string) => {

return useController(

React,

(host: ReactiveControllerHost) => new TestController(host, a)

);

};

test('basic lifecycle', () => {

let testController!: TestController;

const TestComponent = ({x}: {x: number}) => {

testController = useTest('a');

return React.createElement('div', {className: 'foo'}, [

`x:${x}, a:${testController.a}`,

]);

};

const render = (props: any) => {

ReactDOM.render(React.createElement(TestComponent, props), container);

};

render({x: 1});

assert.equal(ctorCallCount, 1);

assert.equal(container.innerHTML, `<div class="foo">x:1, a:a</div>`);

assert.deepEqual(testController.log, ['connected', 'update', 'updated']);

const firstTestController = testController;

testController.log.length = 0;

render({x: 2});

assert.equal(ctorCallCount, 1);

assert.equal(container.innerHTML, `<div class="foo">x:2, a:a</div>`);

assert.deepEqual(testController.log, ['update', 'updated']);

assert.strictEqual(testController, firstTestController);

});

test('requestUpdate', async () => {

let testController!: TestController;

const TestComponent = ({x}: {x: number}) => {

testController = useTest('a');

return React.createElement('div', {className: 'foo'}, [

`x:${x}, a:${testController.a}`,

]);

};

const render = (props: any) => {

ReactDOM.render(React.createElement(TestComponent, props), container);

};

render({x: 1});

assert.deepEqual(testController.log, ['connected', 'update', 'updated']);

testController.log.length = 0;

testController.a = 'b';

testController.host.requestUpdate();

await new Promise((r) => setTimeout(r, 0));

assert.equal(container.innerHTML, `<div class="foo">x:1, a:b</div>`);

assert.deepEqual(testController.log, ['update', 'updated']);

});

test('disconnect', () => {

let testController!: TestController;

const TestComponent = ({x}: {x: number}) => {

testController = useTest('a');

return React.createElement('div', {className: 'foo'}, [

`x:${x}, a:${testController.a}`,

]);

};

ReactDOM.render(React.createElement(TestComponent, {x: 1}), container);

assert.deepEqual(testController.log, ['connected', 'update', 'updated']);

testController.log.length = 0;

ReactDOM.render(React.createElement('div'), container);

assert.equal(container.innerHTML, `<div></div>`);

assert.deepEqual(testController.log, ['disconnected']);

});

test('updateComplete', async () => {

let testController!: TestController;

let updateCompleteCount = 0;

let lastNestedUpdate: boolean | undefined;

let rerender = false;

const TestComponent = ({x}: {x: number}) => {

testController = useTest('a');

testController.host.updateComplete.then((nestedUpdate) => {

updateCompleteCount++;

lastNestedUpdate = nestedUpdate;

});

if (rerender) {

// prevent an infinite loop

rerender = false;

testController.host.requestUpdate();

}

return React.createElement('div', {className: 'foo'}, [

`x:${x}, a:${testController.a}`,

]);

};

const render = (props: any) => {

ReactDOM.render(React.createElement(TestComponent, props), container);

};

render({x: 1});

assert.deepEqual(testController.log, ['connected', 'update', 'updated']);

testController.log.length = 0;

await 0;

assert.equal(updateCompleteCount, 1);

assert.strictEqual(lastNestedUpdate, false);

// cause a requestUpdate() during render

rerender = true;

render({x: 2});

await 0;

// Expect only one more renders since requestUpdate() is called

// during render

assert.equal(updateCompleteCount, 2);

assert.strictEqual(lastNestedUpdate, false);

await 0;

assert.equal(updateCompleteCount, 2);

});