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.705% (-0.002%) from 91.707%
when pulling baaee31 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.

[chrisgervang]

How about we reserve the word "widget" for actual widgets, and talk about wrapping widgets into react "components"?

I rewrote the developer guide with this framing and I think it is a lot clearer now. I don't think the react examples in the dev guide benefit from using the word "Widget" in their component names, however, I think the deck.gl core widgets wrapped in react should have the same name to their non-react counterpart to avoid confusion.

This naming is inconsistent and will cause confusion:

import {Compass} from '@deck.gl/react';

<DeckGL>
  <ScatterplotLayer/>
  <MapView/>
  <Compass/>
</DeckGL>

I'd prefer the react export be called import {CompassWidget} from '@deck.gl/react'; so that it's clear that it is a widget.

[ibgreen]

'd prefer the react export be called import {CompassWidget} from '@deck.gl/react'; so that it's clear that it is a widget.

Well, I guess it depends on what one thinks off when using the word "widget". What aspect of the word "Widget" is important to you? If it is basically a React component? Mainly that it needs to be a child of deck? That it supports the positioning prop?

Having different exports with the same name can be confusing down the road, especially when asking people to wrap widgets into react component using useWidget which was my original call-out (the "VanillaCompass" issue).

How about a prefix? ReactCompassWidget? DeckCompassWidget?

Just brainstorming, no strong opinion, your call.

[chrisgervang]

Another option would be to extract a widget class from JSX, like we do with layers and views. It could be done in a way where passing custom react components that use useWidget still works.

Edit: This won't work for TypeScript.

[ibgreen]

It would be nice if we had a direction in mind that covered all cases (i.e. all the types of objects in the "deck.gl zoo": layers, views, controllers, widgets, ...).

Could the replacement of the current half-broken "layers as JSX" approach also be something like useLayer() and useView()?

Or could there be simple wrapper components instead of hooks?

<Widget widget={CompassWidget} ... />
<Layer layer={ScatterplotLayer} ... />

But I guess for perfect typing custom wrappers need to be spelt out for each wrapper?

const ReactCompassWidget(props: CompassWidgetProps) => 

Or the prop types can be inferred from the component type using some generic?

[chrisgervang]

There's no question to me anymore about dropping the word "Widget" from the dev guide and examples for the custom react-wrapped widgets. The new framing makes more sense to me.

So now it's just a question of what to call (and how to export) the official react-wrapped widgets.

Our JSX implementation, in general, is due for a re-think since it doesn't work with typescript - and we've got a promising alternative in deck.gl-community.

Options at this point:

• prefix the names to differentiate (+deconflicted name, -a bit clumsy looking)
• match the name, export from different modules (+consistent naming, -export confusion)

I'll think about this some more.

[chrisgervang]

Ha, we were writing at the same time. Interesting idea! That could be a good solution for folks who aren't ready to adopt the custom renderer, but want to use typescript.

We could either wait for deck v10 to deprecate the old version and ship this, or could try adding support for something new before then while maintaining legacy support.

What do you think, @Pessimistress?

[ibgreen]

We could either wait for deck v10 to deprecate the old version and ship this, or could try adding support for something new before then while maintaining legacy support.

• I think we need to form an idea about what "something new" means first before we can say when it should ship.
• I personally wouldn't delay 9.1 for this
• but if we can get some clarity on longer term strategy now, then we can make sure 9.1 is a step in the right direction.