@uppy/react: add useUppyState

[Murderlon]

Closes #4698
Closes #4680
Closes #4725

Problems

1. If someone wants to use Uppy without one of our UI's, they have to recreate Uppy's entire state themselves. Meaning, listening to almost all events and then calling to useState hooks. Quite painful.
2. If you are using dashboard, people still want to put Uppy inside useState because of the React mindset. Ending up with a fragile series of useState and useEffect.
3. We say in the docs to always put Uppy outside of the component. This works okay for simple cases. But If you want to render multiple Uppy UIs, you do have to put Uppy in useState, even though we said before you shouldn't.

This PR focusses on one but outlines all problems to see how they relate to each other. Normally it's better to only talk about one thing in a PR, but I thought I proof of concept would help the discussion and it's good to talk about how the problems and solutions relate to each other. So feel free to provide feedback on all three.

Solution to 1 (this PR)

A new hook useUppyState which allows you to select a part of Uppy's state and the component will only re-render based on that state. This is mostly useful if you want to create a custom UI or if you use something like Dashboard but you just want to do something extra on the page somewhere based on Uppy state.

import Uppy from '@uppy/core'
import { Dashboard, useUppyState } from '@uppy/react'

export default function App () {
  // see next section why this is in useState
  const [uppy] = useState(() => new Uppy())
  const files = useUppyState(uppy, (state) => state.files)
  // We can also get specific plugin state
  const metaFields = useUppyState(uppy, (state) => state.plugins?.dashboard?.metaFields)

  return (
    <Dashboard id="dashboard" uppy={uppy} />
  )
}

Solution to 2 and 3 (future docs PR)

If you pass a function to useState, React will only call it during initialization. When re-rendering, the @uppy/default-store state remains in the background so uploads will continue. When the component is unmounted, its state (and uploads) will be reset.

Component based thinking means that you isolate state with your component. People writing React want to do this with Uppy. In fact, if you want to render an unknown amount of Uppy components, this is the only way.

Example: I want Uppy state to remain during re-renders but not during page change (unmount)

import React, { useState } from 'react'
import Uppy from '@uppy/core'
import { Dashboard } from '@uppy/react'

export default function App () {
  // important: passing an initialiser function to prevent the state from recreating!
  const [uppy] = useState(() => new Uppy())
  const [show, setShow] = useState(false)

  return (
    <>
      {/* toggle button */}
      {show && <Dashboard id="dashboard" uppy={uppy} />}
    </>
  )
}

Example: I want Uppy state to also remain during page changes

It's a common use case from customers, they want they're users to able to use their app (switch pages) while the upload continues. This is not something we can easily provide in a hook or store, unless we want to store everything in localStorage (not a good idea). However using React patterns this is possible: lifting state up.

import React, { useState, useEffect } from 'react'
import Uppy from '@uppy/core'
import { Dashboard, useUppyState } from '@uppy/react'

function Page1 () {
 // ...
}

function Page2 ({ uppy }) {
  const totalProgress = useUppyState(uppy, (state) => state.totalProgress)  
  return (
    <>
       <p>{totalProgress}</p>
      <Dashboard id="dashboard" uppy={uppy} />
    </>
  )
}

export default function App () {
  // keeping the uppy instance alive above the pages the user can switch during uploading
  const [uppy] = useState(() => new Uppy())

  return (
    <>
      <Page1 />
      <Page2 uppy={uppy} />
    </>
  )
}

[socket-security]

Updated dependencies detected. Learn more about Socket for GitHub ↗︎

Packages	Version	New capabilities	Transitives	Size	Publisher
@types/react	18.2.28...18.2.23	None	+0/-0	365 kB	types

[nickrttn]

As for the future work planned: what do you think about offering an UppyProvider that instantiates Uppy for users and manages stuff. That might make it easier for React users to reason about where Uppy is created, at the app, page or component level? That would also allow you to get rid of the first uppy argument to useUppyStateSelector as you could get it from context. I like the pattern used here: https://github.com/pmndrs/zustand/blob/main/docs/guides/initialize-state-with-props.md

[Murderlon]

As for the future work planned: what do you think about offering an UppyProvider that instantiates Uppy for users and manages stuff

I thought about it but refrained from doing so:

Context is very tempting to use! However, this also means it’s too easy to overuse it. Just because you need to pass some props several levels deep doesn’t mean you should put that information into context — React docs

Their use cases for adding context also don't align with what Uppy is used for. Realistically, there is only one page where people upload in most apps and it would be overkill to provide a context for this in my opinion. I'd rather keep it simple and explicit for now. Perhaps reconsidering when we see people needing this more.

[mifi]

simple and elegant!

lgtm except for comments by others

[aduh95]

Maybe a noob question: why does useUppyState return a simple value when React's useState returns an iterator? I guess that's because Uppy state is immutable, but shouldn't we try to be consistent nonetheless? Or maybe that's a usual pattern in React ecosystem

[Murderlon]

useState is for state you control, hence it's [value, setValue]. useSyncExternalStore is for state you do not control outside of React. You don't (and can't) do the setting of state and so we only return the value, based on your selector (chosen subset of state).

[Murderlon]

@aduh95 still getting the same error as before when running yarn e2e:client and navigating to the React page 🤔

[Murderlon]

@aduh95 still getting the same error as before when running yarn e2e:client and navigating to the React page 🤔

This is now resolved 👍

[Jokcy]

@Murderlon I just notice that useSyncExternalStore should not be used like this, the getSnapshot should return be uppy.getState, it is how React know if the selector need to be be run again. If we make getSnapshot based on selector then if the selector alway return a new object, it will lead to infinite loop of component render.

For example useUppyState(uppy, (s) => Object.values(s.files)), even though s.files not changed, the Object.values(s.files) is always a new object.

There is another api from react use-sync-external-store package, which is useSyncExternalStoreWithSelector, we should use it instead to perform update on the selector function. I will make a PR for this.

BTW, it this api released? I tried to import from @uppy/react 3.1.4 but no this api found.

[Murderlon]

Thanks for the update. I can't find anything about useSyncExternalStoreWithSelector? It's not the in types I have locally nor is it on the react.dev website. The problem you describe is a common React problem though, whenever you put arrays in a dependency array. Regardless it should at least be documented.

[Jokcy]

@Murderlon react-redux use this hook, you can see the code here https://github.com/reduxjs/react-redux/blob/854f3e1687382925952712399f93c0e7d271cdbb/src/utils/useSyncExternalStore.ts#L2C94-L2C94 . And this hook is published by react offical repo, https://github.com/facebook/react/blob/main/packages/use-sync-external-store/src/useSyncExternalStoreWithSelector.js.

The problem you describe is a common React problem though

Yes if we implement this way, but the recommend usage of useSyncExternalStore is to provide a stable getSnapshot function, normally it is the getState method of store. Use this to detect if store.state changed and then call selector.