feat(bindings): add useStateManager() (#1905)

* feat(bindings): add `useStateManager`

* fixes to README

* fixes to README

* remove React from peerDeps from state

* merge master

Author: layershifter

packages/react-bindings/README.md

@@ -0,0 +1,88 @@
+`@stardust-ui/react-bindings`
+===
+
+A set of reusable components and hooks to build component libraries and UI kits.
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+
+
+- [Installation](#installation)
+- [Hooks](#hooks)
+  - [`useStateManager()`](#usestatemanager)
+    - [Usage](#usage)
+    - [Reference](#reference)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+# Installation
+
+**NPM**
+```bash
+npm install --save @stardust-ui/react-bindings
+```
+
+**Yarn**
+```bash
+yarn add @stardust-ui/react-bindings
+```
+
+# Hooks
+
+## `useStateManager()`
+
+A React hook that provides bindings for state managers. 
+
+### Usage 
+
+The examples below assume a component called `<Input>` will be used this way:
+
+```tsx
+type InputProps = {
+  defaultValue?: string;
+  value?: string;
+  onChange?: (value: string) => void;
+};
+type InputState = { value: string };
+type InputActions = { change: (value: string) => void };
+
+const createInputManager: ManagerFactory<InputState, InputActions> = config =>
+  createManager<InputState, InputActions>({
+    ...config,
+    actions: {
+      change: (value: string) => () => ({ value })
+    },
+    state: { value: "", ...config.state }
+  });
+
+const Input: React.FC<InputProps> = props => {
+  const [state, actions] = useStateManager(createInputManager, {
+    mapPropsToInitialState: () => ({ value: props.defaultValue }),
+    mapPropsToState: () => ({ value: props.value })
+  });
+
+  return (
+    <input
+      onChange={e => {
+        actions.change(e.target.value);
+        if (props.onChange) props.onChange(e.target.value);
+      }}
+      value={state.value}
+    />
+  );
+};
+```
+
+### Reference
+
+```tsx
+const [state, actions] = useStateManager(createInputManager)
+const [state, actions] = useStateManager(
+  managerFactory: ManagerFactory<State, Actions>, 
+  options: UseStateManagerOptions<Props>,
+)
+```
+
+- `managerFactory` - a factory that implements state manager API
+- `options.mapPropsToInitialState` - optional, maps component's props to the initial state
+- `options.mapPropsToState` - optional, maps component's props to the state, should be used if your component implements [controlled mode](https://reactjs.org/docs/uncontrolled-components.html).

packages/react-bindings/package.json

@@ -23,6 +23,9 @@
     "react": "^16.8.0",
     "react-dom": "^16.8.0"
   },
+  "optionalDependencies": {
+    "@stardust-ui/state": "^0.39.0"
+  },
   "publishConfig": {
     "access": "public"
   },

packages/react-bindings/src/hooks/useDispatchEffect.ts

@@ -0,0 +1,35 @@
+import { AnyAction, SideEffect } from '@stardust-ui/state'
+import * as React from 'react'
+
+type Dispatch<Action extends AnyAction> = (
+  e: DispatchEvent,
+  action: Action,
+  ...args: Parameters<Action>
+) => void
+
+type DispatchEffect<State> = (e: DispatchEvent, prevState: State, nextState: State) => void
+
+type DispatchEvent = React.SyntheticEvent | Event
+
+const useDispatchEffect = <State>(
+  dispatchEffect: DispatchEffect<State>,
+): [Dispatch<AnyAction>, SideEffect<State>] => {
+  const latestEffect = React.useRef<DispatchEffect<State>>(dispatchEffect)
+  const latestEvent = React.useRef<DispatchEvent | null>(null)
+
+  latestEffect.current = dispatchEffect
+
+  const dispatch = React.useCallback<Dispatch<AnyAction>>((e, action, ...args) => {
+    latestEvent.current = e
+
+    action(...args)
+    latestEvent.current = null
+  }, [])
+  const sideEffect = React.useCallback<SideEffect<State>>((prevState, nextState) => {
+    return latestEffect.current(latestEvent.current as DispatchEvent, prevState, nextState)
+  }, [])
+
+  return [dispatch, sideEffect]
+}
+
+export default useDispatchEffect

packages/react-bindings/src/hooks/useStateManager.ts

@@ -0,0 +1,73 @@
+import {
+  AnyActions,
+  EnhancedActions,
+  Manager,
+  ManagerFactory,
+  SideEffect,
+} from '@stardust-ui/state'
+import * as React from 'react'
+
+type UseStateManagerOptions<State> = {
+  mapPropsToInitialState?: () => Partial<State>
+  mapPropsToState?: () => Partial<State>
+  sideEffects?: SideEffect<State>[]
+}
+
+export const getDefinedProps = <Props extends Record<string, any>>(
+  props: Props,
+): Partial<Props> => {
+  const definedProps: Partial<Props> = {}
+
+  Object.keys(props).forEach(propName => {
+    if (props[propName] !== undefined) {
+      definedProps[propName] = props[propName]
+    }
+  })
+
+  return definedProps
+}
+
+const useStateManager = <State extends Record<string, any>, Actions extends AnyActions>(
+  managerFactory: ManagerFactory<State, Actions>,
+  options: UseStateManagerOptions<State> = {},
+): [Readonly<State>, Readonly<Actions>] => {
+  const {
+    mapPropsToInitialState = () => ({} as Partial<State>),
+    mapPropsToState = () => ({} as Partial<State>),
+    sideEffects = [],
+  } = options
+  const latestManager = React.useRef<Manager<State, Actions> | null>(null)
+
+  // Heads up! forceUpdate() is used only for triggering rerenders stateManager is SSOT()
+  const [, forceUpdate] = React.useState()
+  const syncState = React.useCallback(
+    (_prevState: State, nextState: State) => forceUpdate(nextState),
+    [],
+  )
+
+  // If manager exists, the current state will be used
+  const initialState = latestManager.current
+    ? latestManager.current.state
+    : getDefinedProps(mapPropsToInitialState())
+
+  latestManager.current = managerFactory({
+    // Factory has already configured actions
+    actions: {} as EnhancedActions<State, Actions>,
+    state: { ...initialState, ...getDefinedProps(mapPropsToState()) },
+    sideEffects: [...sideEffects, syncState],
+  })
+
+  // We need to pass exactly `manager.state` to provide the same state object during the same render
+  // frame.
+  // It keeps behavior consistency between React state tools and our managers
+  // https://github.com/facebook/react/issues/11527#issuecomment-360199710
+
+  if (process.env.NODE_ENV === 'production') {
+    return [latestManager.current.state, latestManager.current.actions]
+  }
+
+  // Object.freeze() is used only in dev-mode to avoid usage mistakes
+  return [Object.freeze(latestManager.current.state), Object.freeze(latestManager.current.actions)]
+}
+
+export default useStateManager

packages/react-bindings/src/index.ts

@@ -1,2 +1,5 @@
 export { default as getElementType } from './utils/getElementType'
 export { default as getUnhandledProps } from './utils/getUnhandledProps'
+
+export { default as unstable_useDispatchEffect } from './hooks/useDispatchEffect'
+export { default as useStateManager } from './hooks/useStateManager'

packages/react-bindings/test/hooks/useDispatchEffect-test.tsx

@@ -0,0 +1,76 @@
+import { unstable_useDispatchEffect, useStateManager } from '@stardust-ui/react-bindings'
+import { createManager, ManagerFactory } from '@stardust-ui/state'
+import { shallow } from 'enzyme'
+import * as React from 'react'
+import * as ReactTestUtils from 'react-dom/test-utils'
+
+type TestState = { value: string }
+type TestActions = { change: (value: string) => void; clear: () => void }
+
+const createTestManager: ManagerFactory<TestState, TestActions> = config =>
+  createManager<TestState, TestActions>({
+    ...config,
+    actions: {
+      change: (value: string) => () => ({ value }),
+      clear: () => () => ({ value: '' }),
+    },
+    state: {
+      value: '',
+      ...config.state,
+    },
+  })
+
+type TestComponentProps = Partial<TestState> & {
+  onChange: (e: React.ChangeEvent | React.MouseEvent, value: TestComponentProps) => void
+  defaultValue?: string
+  value?: string
+}
+
+const TestComponent: React.FunctionComponent<TestComponentProps> = props => {
+  const [dispatch, dispatchEffect] = unstable_useDispatchEffect<TestState>(
+    (e, prevState, nextState) => {
+      if (prevState.value !== nextState.value) {
+        props.onChange(e as React.ChangeEvent | React.MouseEvent, {
+          ...props,
+          value: nextState.value,
+        })
+      }
+    },
+  )
+  const [state, actions] = useStateManager(createTestManager, {
+    mapPropsToInitialState: () => ({ value: props.defaultValue }),
+    mapPropsToState: () => ({ value: props.value }),
+    sideEffects: [dispatchEffect],
+  })
+
+  return (
+    <>
+      <input onChange={e => dispatch(e, actions.change, e.target.value)} value={state.value} />
+      <button onClick={e => dispatch(e, actions.clear)} />
+    </>
+  )
+}
+
+describe('useDispatchEffect', () => {
+  it('calls an action with params', () => {
+    const onChange = jest.fn()
+    const wrapper = shallow(<TestComponent onChange={onChange} />)
+
+    ReactTestUtils.act(() => {
+      wrapper.find('input').simulate('change', { target: { value: 'baz' } })
+    })
+
+    expect(wrapper.find('input').prop('value')).toBe('baz')
+  })
+
+  it('calls an action without params', () => {
+    const onChange = jest.fn()
+    const wrapper = shallow(<TestComponent defaultValue="foo" onChange={onChange} />)
+
+    ReactTestUtils.act(() => {
+      wrapper.find('button').simulate('click')
+    })
+
+    expect(wrapper.find('input').prop('value')).toBe('')
+  })
+})