Fix mergeProp, createElemPropsHook, and composeHooks types

[NicholasBoll]

mergeProps

mergeProps is a utility function used by all of our components to properly merge React props from
React hooks and the props you pass to components. The functionality merges props like the cs prop,
css prop, style prop, callbacks, and other props in a way that tries to be intuitive. If you add
a cs prop and a hook also has a cs prop, both are merged in such a way that the cs prop from
both is represented. Same with the style prop - the style objects will be merged together.
Callbacks are merged in a way that both callbacks are called. The strange and undocumented merging
was when one of the props is null. Basically, in the case of mergeProps(props1, props2),
props2 will override props1 (callbacks are merged so that props2 callbacks are called after
props1), except if props1 sets a null value.

mergeProps({foo: null, bar: 'bar1'}, {foo: 'foo', bar: 'bar2'}); // { foo: null, bar: 'bar2' }

The null processing allows behavior hooks to "remove" props from passed props. Usually this is for
prop redirection or allow passing non-element props to a hook and the hook can remove it. The
runtime works fine, but TypeScript didn't like how we merged the types:

function mergeProps<P1, P2>(props1: P1, props2: P2): P1 & P2 {}

mergeProps({foo: 'foo'}, {bar: 'bar'}); // { foo: string, bar: string }

The problem is if a prop has a null and a non-null value:

type Test = {foo: null} & {foo: string}); // never

TypeScript Playground

There is also a problem if a prop type was changed:

type Test = {foo: string} & {foo: number}; // {foo: never}

TypeScript Playground

Since we used &, an intersection type, there is no intersection between string and number and
therefore foo becomes never. The runtime actually makes foo be a number.

Fixing this revealed a common problem - a prop type may require a narrowed type, but a hook provides a widened type. This required us to add as const to our props:

const useMyHook = createElemPropsHook(useMyModel)(model => {
  return {
    'aria-haspopup': 'listbox'
  } as const // without `as const`, the type is `{'aria-haspopup': string}`
});

<div {...useMyHook(model, {}} /> // would error without `as const` because `aria-haspopup` has a narrowed type of `'true' | 'listbox' | 'menu'` and `string` is too wide.

We use the TypeScript 5.0 const Type Parameters to narrow the type. The object passed is a constant, so we upgraded mergeProps and createElemPropsHook to use const Type Parameters to automatically narrow the type to avoid this issue.

We upgraded the type of mergeProps to be more complicated, but more accurate so that prop types override prop types and also the null handle works:

// before
mergeProps({foo: null}, {foo: 'bar'}); // never
mergeProps({foo: 'bar'}, {foo: 'baz' }); // {foo: string}
mergeProps({foo: 'bar'}, {foo: 1}); // {foo: never}

// after
mergeProps({foo: null}, {foo: 'bar'}); // {foo: null}
mergeProps({foo: 'bar'}, {foo: 'baz' }); // {foo: 'baz'}
mergeProps({foo: 'bar'}, {foo: 1}); // {foo: 1}

createElemPropsHook

The createElemPropsHook now uses const Type Parameters to narrow types. Similar to mergeProps:

const useMyHook = createElemPropsHook(useMyModel)(model => {
  return {
    'aria-haspopup': 'listbox'
  } as const // without `as const`, the type is `{'aria-haspopup': string}`
});

<div {...useMyHook(model, {}} /> // would error without `as const` because `aria-haspopup` has a narrowed type of `'true' | 'listbox' | 'menu'` and `string` is too wide.

We use const Type Parameters to narrow the type since the elemProps hook returns a read-only object. This prevents you from needing to provide as const.

const useMyHook = createElemPropsHook(useMyModel)(config => {
  return {
    'aria-haspopup': 'listbox'
  }
})

// before
useMyHook(model, {}) // { 'aria-haspopup': string }

// after
useMyHook(model, {}) // { 'aria-haspopup': 'listbox' }

composeHooks

composeHooks composes multiple hooks together, calling mergeProps along the way. If we used a null in any hook the result was returning never. We updated to accurately return the correct type. This could be alerting you to errors you didn't see before since the spread elemProps didn't have props before and thus wouldn't have any conflicts.

const useHook1 = createElemPropsHook(useMyModel)(model => {
  return {
    foo: 'foo',
    name: null // remove 'name' prop so it doesn't get sent to the element
  }
})

const useHook1 = createElemPropsHook(useMyModel)(model => {
  return {
    bar: 'bar',
    name: 'foo' // maybe set a variable to be used by `useHook2`
  }
})

const useHook3 = composeHooks(useHook1, useHook2)

// before
useHook3(model, {}) // never

// after
useHook3(model, {}) // { foo: 'foo', bar: 'bar', name: null}