Typed children for function-based widgets

[agubler]

Type: feature

The following has been addressed in the PR:

• There is a related issue
• All code has been formatted with prettier as per the readme code style guidelines
• Unit or Functional tests are included in the PR

Description:

Provides extended typing of children for function-based widgets, supported by all widget authoring patterns. When children types are defined it makes them mandatory for widget usage.

import { create, tsx } from '@dojo/framework/core/vdom';

const factory = create().children<(value: string) => RenderResult>();

const Foo = factory(function Foo({ children }) {
    const [childRender] = children();
    return childRender('text');
});

// usages

// using TSX
<Foo>{(value) => <div>value</div>}</Foo>

// Using the widget function
Foo({}, [(value) => <div>value</div>]); 

// Using the `w()` pragma
w(Foo, {}, [(value) => <div>value</div>]);

Typed children provide a first class replacement for widgets that use render props, for example Outlet.

<Outlet id="outlet" renderer={(matchDetails) => {
    if (matchDetails.isExact()) {
        return <Home />;
    }
    return null;
}}/>

<Outlet id="outlet">{(matchDetails) => {
    if (matchDetails.isExact()) {
        return <Home />;
    }
    return null;
}}</Outlet>

Resolves #528
Resolves #43

[matt-gadd]

will this conflict with the global Omit type added in 3.5? I presume not but worth a check

[agubler]

It shouldn't do, I did a quick check and there no complaints about Omit

[matt-gadd]

is this correct now? would it not be __children__?

[agubler]

Nice catch

[agubler]

Fixed and a couple of other misses too.

[matt-gadd]

do we need an example test with w() also?

[agubler]

I can add that

[agubler]

Added.

[matt-gadd]

how come this had to change?

[agubler]

Because by default children are not set to an empty array when using w any more.

[matt-gadd]

but this is the assertion for getChildren no? which is both typed as an array and returns an empty array if not set?

[agubler]

If it is a WNode or VNode then it just returns the children from the element.

[matt-gadd]

Ah okay, sorry I missed that this was in the selector, and not the assertion template. This makes me concerned about these types/values a little bit though.

I think any kind of children interface should be consistently returning either an empty array [] for no children, an array of one ['a'] for one item, or an array of many ['a','b','c'] for many items. This means the end user can consistently work on an array without guards for api's such as this, and would match other child like api's such as NodeList.

I'm not sure what the ramifications are on types or whether it's possible with TSX, but it'd seem more consistent to make the user define create().children<[ whatever ]>() over create().children<whatever>() if they need to define a single item.

[agubler]

I think that's fair point about always having children and it being an array (that can be defaulted). I've made some changes (WIP atm as need to put back the defaulting of children) that added support for children to be mandatory and able to be typed singularly but are consumed by the widget author as the first item in an array.

[matt-gadd]

can we add a convenience type for this? it's used quite a lot in the mocks, and presumably would be also for a user writing a mock?

[agubler]

I added a DefaultMiddlewareResult interface that represents MiddlewareResult<any, any, any, any>

[matt-gadd]

this is awesome 👍 took some wrangling in the end but worth it.