RFC: `useItem` hook

[Kelin2025]

Case

Currrently there's useItemState and useItemApi hooks

But I came up with an idea of a more unified and convenient hook

Solution

1. Unify shapes returned from APIs so we can use all the available APIs in a single hook RFC: Unify all "APIs" and namings #18
2. Add useItem(api, key) hook that accepts all the entities - ListApi, ItemApi, MappingApi, SelectionApi
3. Add <ItemProvider api={api} /> and support useItem(api) to solve prop-drilling and get rid of IDs

import { createListApi, createItemApi } from '@keyval/core'
import { useItem, ItemProvider } from '@keyval/react'

const $swaps = createListApi({ ... })
const swapsApi = createItemApi({ ... })

const SwapWidget = ({ id }) => {
  return (
    <ItemProvider api={swapsItemApi} id={id}>
      <SwapInfo />
      <ConfirmSwapButton />
    </ItemProvider>
  )
}

const SwapInfo = () => {
  const [swapState] = useItem(swapsItemApi)
  
  return <div>{swapState.from} -> {swapState.to}</div>
}

const ConfirmSwapButton = () => {
  const [swapState, api] = useItem(swapsItemApi)
  
  return <button onClick={api.confirm}>Confirm</button>
}

[Minhir]

It definitely solves the prop-drilling problem, but there is a new one.
If I'm passing the item from one component to its children, I can guarantee that the item is not null.

const SwapWidget = ({ id }) => {
  const [swapState] = useItem(swapsItemApi, id);

  if (!swapState) {
    return <Placeholder />;
  }

  return (
    <>
      <SwapInfo swapState={swapState} />
    <>
  )
}

const SwapInfo = ({swapState}: {swapState: SwapState}) => {
  return <div>{swapState.from} -> {swapState.to}</div>
}

With provider solution, you need always to check if there is an item in every child.

Or maybe I understand your idea a little bit wrong, and you want to render children conditionally if the item with id exist in kv.

[Kelin2025]

I can guarantee that the item is not null
you need always to check if there is an item in every child

It's up to the user
If they want to pass it through props - they can useItem at top-level and pass it down through props
If they are using useItem (or useItemState or any other solution that takes item from KV) - yes, there's a chance that the item is null. Either handle it or add item! if you're 100% sure it's there
I believe this question is not related to the hook itself. The only difference between useItemState and useItem there is that you get an option to get the key from Context

[Minhir]

Sure, we can implement it and see how it helps users in their scenarios.