docs(react) React widgets and useWidget hook documentation

[chrisgervang]

For #9278 #9056 #9298

Background

A features not "done" until its documented.. react widget docs.

Change List

• useWidget api reference
• JSX widgets usage

[chrisgervang]

Could be good to do an audit for this and use maplibre since it doesn't need a token.

[ibgreen]

Good idea - Add a bullet to our v9.1 tracker task?

[coveralls]

coverage: 91.701% (-0.006%) from 91.707%
when pulling 027397d on chr/use-widget-docs
into 05bca74 on master.

[ibgreen]

Good idea - Add a bullet to our v9.1 tracker task?

[ibgreen]

Vanilla sounds so weird... And the fact that I can't easily think of a better name makes me feel this is an indication of the dual usage of the word "widget" here being more problematic than initially expected.

How about we reserve the word "widget" for actual widgets, and talk about wrapping widgets into react "components"? I realize it will required rewriting the docs a bit, but I think a ton of confusion can be avoided.

Suggested change

	import {CompassWidget as VanillaCompassWidget, CompassWidgetProps} from '@deck.gl/widgets';
	export const CompassWidget = (props: CompassWidgetProps = {}) => {
	const widget = useWidget(VanillaCompassWidget, props);
	return null;
	};
	<DeckGL>
	<CompassWidget/>
	</DeckGL>
	```
	See a full example [here](../../developer-guide/custom-widgets/react-widgets.md).
	import {CompassWidget, CompassWidgetProps} from '@deck.gl/widgets';
	export type CompassProps = CompassWidgetProps;
	export const Compass = (props: CompassProps = {}) => {
	const widget = useWidget(CompassWidget, props);
	return null;
	};
	<DeckGL>
	<CompassWidget/>
	</DeckGL>

See a full example here.

[chrisgervang]

Yeah, that's a fair point. A Widget is just a hook. You could compose multiple widgets in one component.. widgets may or may not mount a DOM element. So yeah these components could really be anything.. we're just suggesting a usage.

I'll try reworking the PRs with this idea.

The open question I have is how to implement a widget nested in a JSX view..

<MapView id="minimap">
  <Compass />
</MapView>

I was originally going to inject a viewId prop, assuming all props were passed into the hook, or introduce something new like a ViewContext. I've been putting this off thinking the community react library might be a better solution.