util: polymorphic primatives

[danethurber]

new util methods to support typed(typescript) forwardRef components that support static properties, polymorphism and memoization.

for an example of how the methods would be used please see #1675 which shows refactoring the Button component and related components. Button is by far the most complicated and widely used component that supports the old polymorphic style.

[danethurber]

oops. forgot to document using a render prop function. i'll add an example - the approach is pretty straightforward

interface Props {
  children?: React.ReactNode | (() => JSX.Element);
}
const TestInput = forwardRefWithAs<Props, "input">((props, ref) => {
  const { as: Comp = "input", children, ...rest } = props;

  return (
    <Comp ref={ref} {...rest}>
      {isFunction(children) ? children() : children}
    </Comp>
  );
});

[jhewlett]

@danethurber So the idea here is that by asking the consumer to specify the underlying DOM element to be used, you're able to provide better autocomplete and static guarantees? (e.g. if they specify as="button", then href wouldn't be accepted as a valid prop?)

[KaidenR]

This looks like a really great pattern that should help a LOT with customization.

Is the idea that a component could have multiple <subcomponent>As props so that I can override different parts of the component? Like when rendering a Dropdown component I could have buttonAs and a menuAs props to customize the rendering of either of them.

(Also submitting fixes for a few typos)

[danethurber]

@justin yes the types should be able to tell which attrs/props are valid for the given tag name. the component's tag name also needs to have a default value. so for example the following component defaults to a button but can be changed as needed.

const Button = forwardRefWithAs<Props, 'button'>(() => ...)

will be typed to only allow valid button props, including using HTMLButtonElement for the ref and event types. but if you used as like so

<Button as="a" />

the typings would now related to a HTMLAnchorElement so attributes like href would be valid

---

@KaidenR i don't have a standard answer for how we get to the internal elements yet - but your approach could definitely be something we finalize on. we might end up with a collection of compound components meant to be hyper flexible and each should allow using the as prop when needed; and we will most likely have a set of components that are convenience wrappers to provide a simpler interface that encapsulate common patterns. Some current examples being our Field components vs a convenience wrapper like the MultiSelect component.

With the addition of these typings, our compounds component would allow changing the underlying dom elements at whatever level you need. an example being.

const Button = forwardRefWithAs<Props, 'button'>(() => ...)
interface Statics {
  Button: typeof Button
}
const Compound = forwardRefWithAsAndStatics<unknown, 'div', Statics>(() ...)
Compound.Button = Button

render(
  <Compound as="section">
    <Button  />
    <Button as="a" />
  </Compound>
)