chore: Add collection example

[ciampo]

Part of #939

Adds the default example for the Collection component and a simple test

[vercel]

This pull request is being automatically deployed with Vercel (learn more).
To see the status of your deployments, click below or on the icon next to each commit.

ariakit – ./

🔍 Inspect: https://vercel.com/ariakit/ariakit/8eHUtutcqAhH3XZMQttdLi7yXNRD
✅ Preview: https://ariakit-git-add-example-collection-default-ariakit.vercel.app

reakit – ./

🔍 Inspect: https://vercel.com/ariakit/reakit/J8Jz17jyM2K16s5CjtxKR2wGgVw3
✅ Preview: Canceled

[Deployment for a379ef1 canceled]

[codesandbox-ci]

This pull request is automatically built and testable in CodeSandbox.

To see build info of the built libraries, click here or the icon next to each commit SHA.

[codecov]

Codecov Report

Merging #977 (a379ef1) into v2 (8ec7290) will increase coverage by 0.33%.
The diff coverage is 100.00%.

@@            Coverage Diff             @@
##               v2     #977      +/-   ##
==========================================
+ Coverage   64.25%   64.58%   +0.33%     
==========================================
  Files         170      171       +1     
  Lines        4233     4236       +3     
  Branches     1167     1167              
==========================================
+ Hits         2720     2736      +16     
+ Misses       1512     1499      -13     
  Partials        1        1              

Impacted Files	Coverage Δ
...t/src/collection/__examples__/collection/index.tsx	100.00% <100.00%> (ø)
packages/ariakit/src/collection/collection-item.ts	100.00% <0.00%> (+29.41%)	⬆️
packages/ariakit/src/collection/collection.tsx	100.00% <0.00%> (+100.00%)	⬆️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 8ec7290...a379ef1. Read the comment docs.

[ciampo]

@diegohaz let me know if the example is in line with the visual styles and the contents that have been used throughout the project.

For the test, I couldn't really think of anything in particular to test for, since the Collection component by default renders a few divs

[diegohaz]

Thank you @ciampo!

The main use for the Collection components is to keep the state in sync with a collection of DOM elements. For example, given the following elements:

const collection = useCollectionState();
<Collection state={collection}>
  <CollectionItem>Apple</CollectionItem>
  <CollectionItem>Grape</CollectionItem>
  <CollectionItem>Orange</CollectionItem>
</Collection>

I should be able to access the elements refs through the collection state:

collection.items.forEach((item) => {
  console.log(item.ref.current);
});

But it's really useful in combination with the getItem prop, which allows us to register any prop to the state besides the element ref:

function ToolsPanelItem({ value, isDisabled, ...props }) {
  const getItem = React.useCallback(
    (defaultItem) => ({ ...defaultItem, value, isDisabled }),
    [value, isDisabled]
  );
  return <CollectionItem getItem={getItem} hidden={isDisabled} {...props} />
}

function Panel() {
  const collection = useCollectionState();
  <Collection state={collection}>
    <ToolsPanelItem value="Apple">Apple</ToolsPanelItem>
    <ToolsPanelItem value="Grape" isDisabled>Grape</ToolsPanelItem>
    <ToolsPanelItem value="Orange">Orange</ToolsPanelItem>
  </Collection>
}

We can now access value and isDisabled through the state:

collection.items.map((item) => (
  <MenuItemCheckbox
    key={item.value}
    checked={!isDisabled}
    value={item.value}
  >
    {item.value}
  </MenuItemCheckbox>
));

It also keeps the order of the elements in sync with the DOM, so rendering elements dynamically will not push them to the end of the items list in the state:

<CollectionItem>Apple</CollectionItem>
{isAdmin && <CollectionItem>Grape</CollectionItem>}
<CollectionItem>Orange</CollectionItem>

In the example above, Grape will be the second element even if it's lazily rendered.

As a more concrete use case, this could be used here to keep the menu items in sync with the actual panel tools:

---

That being said, that panel is a really complex example, and I don't think we should have something like that as the default example. Even the getItem prop should probably be another example. But maybe a simple way to exemplify the collection features is to render a count.

[ciampo]

Thank you @diegohaz for the review — I addressed all the feedback so far.

That being said, that panel is a really complex example, and I don't think we should have something like that as the default example. Even the getItem prop should probably be another example. But maybe a simple way to exemplify the collection features is to render a count.

Yeah, that example is quite complex and I'm not sure I get exactly how, in your example, MenuItemCheckbox is able to write the collection state — but I'm sure it's going to be more clear when that example gets added to the codebase.

The main use for the Collection components is to keep the state in sync with a collection of DOM elements. For example, given the following elements:
...
But it's really useful in combination with the getItem prop, which allows us to register any prop to the state besides the element ref:

All of this insight is great, and I think it would benefit the consumers of the component is it was added to its README. Right now the documentation for the component is not very clear about what this component is useful for and its main features.

[diegohaz]

Awesome! Thank you!

[diegohaz]

Yeah, that example is quite complex and I'm not sure I get exactly how, in your example, MenuItemCheckbox is able to write the collection state — but I'm sure it's going to be more clear when that example gets added to the codebase.

Yeah! That was just something I made off the top of my head. But here's a quick prototype of how that could work (https://codesandbox.io/s/ariakit-toolspanel-nf8xf?file=/App.tsx). Basically, CollectionItem would control the availability of each tool, whereas the menu state would control the visibility.

All of this insight is great, and I think it would benefit the consumers of the component is it was added to its README. Right now the documentation for the component is not very clear about what this component is useful for and its main features.

Agree! We should definitely include an explanation in the docs.