docs: more guides

Author: lukasbach

packages/docs/docs/recipes/0-handling-expensive-components.mdx

@@ -7,6 +7,25 @@ category: recipe
 
 import { DemoBox } from "../../src/components/demo/demo-box";
 
+Sometimes, rendering tree items can be expensive. This can cause slow usage of the Tree react component,
+since all items are rendered as part of a single flat list, and mutations to the displayed tree structure,
+such as expanding or collapsing items or changing the tree will trigger a re-render of all items.
+
 <DemoBox stories={["react-guides-render-performance-slow-item-renderers--slow-item-renderers"]} />
 
+Memoizing the individual tree item render methods can help reduce the performance impact of rendering
+expensive tree items. This can be done using the `React.memo` function, which will only re-render the
+component if the props have changed.
+
+`React.memo` will only rerender its contents if any of its props have changed. Headless Tree doesn't
+memoize props generated with `tree.getContainerProps()` and `item.getProps()` by default, and will
+create new props during each render. By including the [Prop Memoization Feature](/features/propmemoization)
+however, these props will be memoized automatically, making memoization of render items feasible.
+
+Note that, in the sample below, expanding or collapsing individual items is much more efficient than
+in the sample above, since now only those items that actually change will be rerendered.
+
 <DemoBox stories={["react-guides-render-performance-memoized-slow-item-renderers--memoized-slow-item-renderers"]} />
+
+You can further improve performance on large trees by making use of Virtualization, which is explained in
+the [Virtualization Guide](/recipe/virtualization).

packages/docs/docs/recipes/1-virtualization.mdx

@@ -7,4 +7,25 @@ category: recipe
 
 import { DemoBox } from "../../src/components/demo/demo-box";
 
+Large trees can have a significant impact on render and usage performance, and cause slow
+interactions. Virtualization is a concept, where the performance hit of a very large list of items
+is mitigated by only rendering the items that are currently visible in the viewport.
+
+While this is not trivial to do with nested structures like trees, Headless Tree makes this
+easy by flattening the tree structure and providing the tree items as flat list. Virtualization
+is not a included feature of Headless Tree, but you can easily pass this flat list to any virtualization
+library of your choice, and use that to create a tree that only renders the visible items.
+
+In the sample below, `react-virtual` is used to virtualize the tree and render 100k items while
+still being performant in rendering and interaction.
+
 <DemoBox stories={["react-scalability-basic-virtualization--basic-virtualization"]} />
+
+:::warning
+
+You likely will want to use proxified item instances instead of static item instances when
+using trees with many items. Read this guide to learn more about [Proxy Item Instances](/recipe/proxy-instances).
+You can use them by setting the `instanceBuilder` tree config option to [`buildProxiedInstance`](/api/core/function/buildProxiedInstance),
+a symbol that you can import from `@headless-tree/core`.
+
+:::

…ges/docs/docs/recipes/2-outside-drag.mdx packages/docs/docs/recipes/3-plugins.mdxpackages/docs/docs/recipes/2-outside-drag.mdx renamed to packages/docs/docs/recipes/3-plugins.mdx packages/docs/docs/recipes/2-outside-drag.mdx renamed to packages/docs/docs/recipes/3-plugins.mdx

@@ -32,7 +32,7 @@ const meta = {
   },
   args: {
     itemsPerLevel: 10,
-    openLevels: 2,
+    openLevels: 4,
     useProxyInstances: true,
   },
 } satisfies Meta;