Can "controlling a non react widget" be made clearer?

As a reader, I find the example very concise and basic. It is not clear what to do with the same pattern as soon as it grows out of scope:

• an instance of a class such as MapWidget having more than one method
• an instance of a class such as MapWidget subscribes to events

MapWidget has a constructor and setZoom, it may not be clear why the "zoom" state is of interest when constructing the widget.

A hypothetical example that would have more methods could make it more obvious that all those methods should be called in a single effect and that this effect should manage two refs - one for a dom element, and one for an instance of a class that depends on said dom element.

I'm not sure if the issue of documenting how to actually perform cleanup in a pattern such as this would invalidate this example though:

  const containerRef = useRef(null);
  const mapRef = useRef(null);
  
  // an effect that is just concerned about creating an instance of a class with a dom element dependency
  // cleanup(), destroy(), dispose() or noop() make sense to be called
  useEffect(() => {
    if (mapRef.current === null) {
      mapRef.current = new MapWidget(containerRef.current);
    } 
    return ()=>{
      if(mapRef.current) mapRef.current.dispose()
    }
  },[])
  
  // an effect that just works on a map ref, doesn't care about any dom elements and such
  useEffect(() => {
    const map = mapRef.current;
    if(!map) return
    map.setFoo(foo);
    map.setBar(bar);
    map.setBaz(baz);
    map.setQux(qux);
  }, [foo,bar,baz,qux]);

I myself find it hard to reconcile certain concepts that i've picked up over the years and bits and pieces of best practices i pick up, mostly on twitter i guess. One such is that useMount is not advised, and imagine that reasoning is why this example doesn't have the empty dep effect (but other sections do?).

I'm afraid to make any suggestions, but i think that an example running an animation with the canvas could be a valuable example:

• a canvas 2d widget would require the ref from the <canvas/> element
• a circle going up and down in a square area would require an raf loop - creating a need for something to be cleaned up.
• a toggle could change the color of the circle
• another toggle could change the shape of the circle to a star

The way effects would be grouped in such an example could give more data points what the best practices are with this pattern.

Probably out of scope - but it's also interesting to know what should be done in case the dom element ref is for whatever reason null if that is still possible with modern react.

Comece pelo exemplo de documentação “controlling a non react widget” e revise as orientações sobre useEffect/useRef em relação aos casos levantados aqui. Decida se o escopo do exemplo, várias refs e o comportamento de cleanup podem ser explicitados; considera-se concluído quando a página documentar claramente o padrão compatível ou registrar um escopo mais restrito.