@wix/patterns 1.468.0 → 1.470.0

package/dist/docs/Collection Toolkit.md

@@ -0,0 +1,116 @@
+# Collection Toolkit
+
+**Category:** Guides
+
+Paths written as `dist/…` below are relative to the `@wix/patterns` package root — the directory holding its `package.json`.
+
+## Related components
+
+`SummaryBar`, `CollectionSearch`, `CollectionToolbarFilters`, `MultiSelectCheckboxFilter`, `MultiInlineCheckboxFilter`, `MultiAutoInlineCheckboxFilter`, `SingleSelectFilter`, `RadioGroupFilter`, `TabsFilter`, `MultiSelectCollectionFilter`, `useFilterCollection`, `AutoCompleteFilter`, `DateRangeFilter`, `NumberRangeFilter`, `OperatorFilterPicker`, `operatorFilter`, `idNameArrayFilter`, `stringFilter`, `stringsArrayFilter`, `arrayFilter`, `dateRangeFilter`, `customFilter`, `useStaticListFilterCollection`, `Sortable Columns`, `MultiLevelSorting`, `EntityPage`, `useEntityPage`, `usePatternsNavigate`, `PickerModal`, `usePickerModal`, `bulkActionModal`, `PrimaryActions`, `SecondaryActions`, `More Actions`, `deleteSecondaryAction`, `PrimaryActionButton`, `MultiBulkActionToolbar`, `useOptimisticActions`, `CollectionOptimisticActions`, `TableTopNotification`, `CollectionEmptyState`, `CollectionNoResultsState`, `CollectionPremiumEmptyState`, `ExportButton`
+
+Each name resolves in `dist/docs/index.json` — as a key, or as one of an entry's `symbols` aliases.
+
+## Overview
+
+Which component to reach for, arranged by what the person using the dashboard is trying to
+do: understand the situation, narrow it, open one record, act, and be told what happened.
+
+Two of those stages get skipped most often, and both leave a page that technically works:
+
+1. **A dashboard that reports on records should show aggregate numbers, not only rows.** A
+   filtered table answers "what are all the records" and none of "how many", "which one
+   needs me", or "why did this happen".
+2. **If a row represents a real business record, the user should be able to open it** —
+   unless the page is explicitly a report or an export.
+
+## Understand — the aggregate
+
+| Need | Component |
+| --- | --- |
+| Totals, counts, a status breakdown above the table | `SummaryBar` |
+| Making the numbers describe the visible subset | wire each metric to the collection's filter state, so the count follows the filters |
+
+`SummaryBar` goes inside the page shell, above the collection. Compute its values from the
+same query the table runs, or from a count query alongside it — a metric that disagrees with
+the rows on screen is worse than no metric.
+
+## Focus — narrowing
+
+| Need | Component |
+| --- | --- |
+| Free-text search | `CollectionSearch` |
+| The filter bar itself | `CollectionToolbarFilters` |
+| Several values from a known list | `MultiSelectCheckboxFilter`, `MultiInlineCheckboxFilter`, `MultiAutoInlineCheckboxFilter` |
+| One value | `SingleSelectFilter`, `RadioGroupFilter`, `TabsFilter` |
+| Values fetched from an API rather than a fixed list | `MultiSelectCollectionFilter` + `useFilterCollection` |
+| Type-ahead over many values | `AutoCompleteFilter` |
+| Date or number ranges | `DateRangeFilter`, `NumberRangeFilter` |
+| Comparison operators — greater than, contains | `OperatorFilterPicker` + `operatorFilter` |
+| The filter's state object | `idNameArrayFilter`, `stringFilter`, `stringsArrayFilter`, `arrayFilter`, `dateRangeFilter`, `customFilter` |
+| A fixed in-memory option list | `useStaticListFilterCollection` |
+| Sorting | `Sortable Columns`, `MultiLevelSorting` |
+
+**A filter has to reach the query.** Declare it in the filters map you pass the collection
+hook, and read its value inside the hook's fetch callback. Filter UI that renders but never
+changes the rows is a defect that looks like a feature — and it is the failure these
+components exist to prevent.
+
+**For the factories and hooks above, the signature is in the bundle, not the doc.** Props
+tables are generated from components, so a factory's doc has an API heading with no table
+under it while its bundle carries the real signature — the generic it constrains, the
+optional params object it accepts, and the filter-state type it returns. That is the
+difference between knowing a name and being able to call it, and it holds for every hook and
+every filter factory listed here.
+
+## Investigate — opening one record
+
+| Surface | When | Built from |
+| --- | --- | --- |
+| **Side panel** | Inspect or lightly edit one record while keeping the filtered list on screen. | The design system's `SidePanel` — patterns has no side panel of its own. |
+| **Entity page** | Multi-section detail, editing, history, or a URL someone can share. | `EntityPage` and `useEntityPage`, navigated to through `usePatternsNavigate`. |
+| **Expanded row** | A couple of extra fields, no separate workspace needed. | The collection's own row expansion. |
+| **Picker / bulk confirm** | Choosing records, or confirming an action across many. | `PickerModal` + `usePickerModal`, `bulkActionModal` |
+
+A dialog that creates, updates or displays one record listed by the collection is an
+`EntityPage`, not a modal — a create or "add new" form included, since it writes the record.
+`useEntityPage`'s **Create route** section covers registering that route and the params that
+differ from the edit call.
+
+Form state on an entity page comes from `@wix/patterns/form`: `useForm` for the form,
+`useController` for a single field. That entry point re-exports `@wix/bex-core/form`, which
+wraps [react-hook-form](https://react-hook-form.com/) — so reading values, resetting, and the
+rest of the form object's surface are react-hook-form's API and are documented there, not
+here.
+
+## Act and confirm
+
+| Need | Component |
+| --- | --- |
+| Page header actions | `PrimaryActions`, `SecondaryActions`, `More Actions` — into the page header's `primaryAction`, `secondaryActions` and `moreActions` slots |
+| Table toolbar button | `PrimaryActionButton` — the table's own `primaryActionButton` prop |
+| Row actions | `deleteSecondaryAction`, in the row's `actionCell` |
+| Acting on a multi-row selection | `MultiBulkActionToolbar`, `bulkActionModal` |
+| Immediate feedback, reconciled after the call | `useOptimisticActions`, which returns `CollectionOptimisticActions` |
+| A banner above the table | `TableTopNotification` |
+
+`useOptimisticActions` takes the collection state — the collection property of the state
+object your collection hook returns — and not that state object itself. The two are different
+types and the wrong one does not compile.
+
+## The states that are not the happy path
+
+| State | Component |
+| --- | --- |
+| The collection is genuinely empty | `CollectionEmptyState` |
+| Filters or search matched nothing | `CollectionNoResultsState` |
+| The feature needs a paid plan | `CollectionPremiumEmptyState` |
+| The load failed | the collection state's error handling — give the user a retry |
+
+Empty and no-results are different messages: one says "add your first record", the other
+says "loosen the filters". Shipping only the first makes a working filter look broken.
+
+## Export
+
+`ExportButton` for CSV and similar. Its doc is titled `ExportTo`.
+
+

package/dist/docs/Collection to Entity Flow.md

@@ -0,0 +1,145 @@
+# Collection to Entity Flow
+
+**Category:** Guides
+
+Paths written as `dist/…` below are relative to the `@wix/patterns` package root — the directory holding its `package.json`.
+
+Examples below are illustrative: each one demonstrates this page's API, and everything around it — data source, layout, http client — is only scaffolding to make that runnable.
+
+## Related components
+
+`CollectionPage`, `EntityPage`, `EntityPageState`, `useEntityPage`, `useEntity`, `useCreateCollection`, `usePatternsNavigate`, `PatternsReactRouter`, `PatternsReactRoute`
+
+Each name resolves in `dist/docs/index.json` — as a key, or as one of an entry's `symbols` aliases.
+
+## Overview
+
+A collection page and the form for one of its items are **two patterns pages**, not a page
+plus a modal. That holds for creating a record as much as editing one: an "add new" form
+writes the record, so it is an `EntityPage` however small it is.
+
+Modals are for dialogs that neither write nor display a listed record — a delete or discard
+confirmation, an unsaved-changes prompt. A page that lists nothing is outside the rule
+entirely.
+
+## What owns each step
+
+| Step | Owner |
+| --- | --- |
+| Getting from a row or a header action to the item | the navigate-to-entity-page function on `usePatternsNavigate` |
+| Registering the route | `PatternsReactRoute`, as a **direct child** of `PatternsReactRouter` |
+| Fetch, save, validation, dirty state, skeletons, errors | `useEntityPage` |
+| Form state and field binding | `useForm` / `useController` from `@wix/patterns/form` |
+| Body layout | `EntityPage.Header`, `.MainContent`, `.AdditionalContent`, `.Card` |
+| The individual fields inside those cards | the design system — `FormField`, `Input`, `Text` |
+
+Prefer navigating through `usePatternsNavigate` to making a plain route change: it renders
+the entity header — title, subtitle, breadcrumbs — immediately, without waiting for the fetch
+to resolve.
+
+Reading the fetched entity inside the page is `useEntity`, and the state object the hook
+returns is `EntityPageState`.
+
+## The routes have to be the router's own children
+
+`PatternsReactRouter` converts the children whose type is exactly `PatternsReactRoute`, one
+level deep. Anything else in that child list reaches React Router unconverted and is rejected
+while rendering.
+
+The shape this rules out is the natural one: letting the collection page declare the routes it
+navigates to, because the collection page is the thing that knows it has an entity page. The
+router only ever receives the page component, not the routes nested inside it. Keep every route
+in the router's own child list, and let the elements they render live wherever you like.
+`PatternsReactRouter`'s doc has the wrong and right shapes side by side.
+
+## Every path here is page-relative
+
+The router roots at `path="/"` even when the dashboard page itself is served from a named
+route. So a page scaffolded at `shifts` registers `path="/"` and `path="/:id"` — **not**
+`/shifts` and `/shifts/:id`.
+
+Repeating the page's own name in a route path, in the parent path an entity page is given, or
+in a navigation call produces no error and no warning; the route simply never matches, or the
+back navigation lands nowhere. It is the most common reason an entity page "does not open".
+
+## Binding a field: `useController`, not `register`
+
+`@wix/patterns/form` re-exports `@wix/bex-core/form`, which wraps
+[react-hook-form](https://react-hook-form.com/) — so `form.getValues()`, `form.reset()` and
+the rest are react-hook-form's API. The re-export is `export *`, so it carries the **types**
+too: a component taking the form as a prop can import `UseFormReturn` from
+`@wix/patterns/form` and write `form: UseFormReturn<ShiftForm>`. The
+`ReturnType<typeof useForm<ShiftForm>>` in the example below is the same type by another
+route, not a workaround for a missing export. One part of it does not carry over: `register` returns
+props for a plain `<input>`, and a design-system component is not one. It fails two ways.
+
+**Spreading the result onto the component does not compile.** `register` types its min and
+max as a string or a number whatever options you passed, while the design system types them as
+an optional number. The resulting error names the input's own props interface, which reads
+like a design-system bug and is not one.
+
+**Handing its ref to the component compiles and is wrong.** The design system's input takes an
+imperative handle on `ref`, while the ref `register` supplies accepts any instance — so it
+binds the handle rather than the underlying element. The field never registers, validation
+never sees it, and nothing reports it.
+
+Bind through value and change handler instead:
+
+```tsx
+import { useController, useForm } from '@wix/patterns/form';
+import { FormField, Input } from '@wix/design-system';
+
+type ShiftForm = { name: string; hours: number };
+
+function NameField({ form }: { form: ReturnType<typeof useForm<ShiftForm>> }) {
+  const { field, fieldState } = useController({
+    name: 'name',
+    control: form.control,
+    rules: { required: 'Name is required' },
+  });
+
+  return (
+    <FormField
+      label="Name"
+      required
+      status={fieldState.error ? 'error' : undefined}
+      statusMessage={fieldState.error?.message}
+    >
+      <Input value={field.value} onChange={field.onChange} onBlur={field.onBlur} />
+    </FormField>
+  );
+}
+```
+
+Validation rules belong in the controller's own rules option, not on the design-system
+component. If you need `register` for a genuine DOM concern such as input masking, the input
+accepts a separate optional ref for the underlying element — give it to that one, never to
+`ref`.
+
+### Where an edit route's initial values come from
+
+That field starts empty, which is right for a create route and not enough for an edit one.
+**The fetched entity reaches a field through `defaultValue` on its controller** — read the
+entity with `useEntity(state)` in the page, or `useEntityPageContext()` inside the card, and
+pass `defaultValue: entity?.name` beside the `name` and `control` already there. The two
+worked versions are `EntityPage`'s `input-initialization-with-usecontroller` and
+`input-initialization-with-controller` examples, one per binding style; both do it this way
+rather than reset the form from inside `fetch`.
+
+Mind the order this happens in: `entity` is `undefined` on the first render, while the fetch
+is still in flight, so anything reading it has to tolerate that — `useEntity`'s own doc makes
+the same point. A `defaultValue` is consumed when the field registers, so a field that
+registers before the entity lands keeps the empty value it was given.
+
+## Two names that read like something they are not
+
+- **`useCreateCollection` does not create items.** It returns a function that initialises
+  collection state.
+- **`onSave`'s argument does not carry your form values.** It has one key,
+  `widgetsFormData`, holding what the widget fields contributed. The values the user typed
+  come from the form object you already hold.
+
+`useEntityPage`'s own doc covers the call itself — both generics, the parameter set, and the
+create route.
+
+

package/dist/docs/CollectionEmptyState.md

@@ -4,6 +4,8 @@
 
 Paths written as `dist/…` below are relative to the `@wix/patterns` package root — the directory holding its `package.json`.
 
+Examples below are illustrative: each one demonstrates this page's API, and everything around it — data source, layout, http client — is only scaffolding to make that runnable.
+
 ## Design
 
 ### Description
@@ -17,19 +19,19 @@ import { CollectionEmptyState } from '@wix/patterns';
 
 ### Demo
 
-Example code: read `dist/docs/CollectionEmptyState/demo.tsx`
+Example code: read `dist/examples/CollectionEmptyState/demo.tsx`
 
 ### 2 CTAs
 
 Use the `customCta` prop to add an extra call to action beside the default **+ Add Item** button.
 
-Example code: read `dist/docs/CollectionEmptyState/2-ctas.tsx`
+Example code: read `dist/examples/CollectionEmptyState/2-ctas.tsx`
 
 ### Passive Empty State
 
 Exclude the `addNewCta` prop to display an empty state without options for user interaction.
 
-Example code: read `dist/docs/CollectionEmptyState/passive-empty-state.tsx`
+Example code: read `dist/examples/CollectionEmptyState/passive-empty-state.tsx`
 
 ## API
 

package/dist/docs/CollectionErrorState.md

@@ -2,6 +2,8 @@
 
 **Category:** Common/State
 
+Examples below are illustrative: each one demonstrates this page's API, and everything around it — data source, layout, http client — is only scaffolding to make that runnable.
+
 ## Design
 
 ### Description

package/dist/docs/CollectionNoResultsState.md

@@ -4,6 +4,10 @@
 
 Paths written as `dist/…` below are relative to the `@wix/patterns` package root — the directory holding its `package.json`.
 
+Examples below are illustrative: each one demonstrates this page's API, and everything around it — data source, layout, http client — is only scaffolding to make that runnable.
+
+Some of that scaffolding is environment-scoped and is **not** needed to use this component: `@wix/ambassador-contacts-v4-contact/types`, `@wix/yoshi-flow-bm`. Those resolve only against a Wix build environment (a Yoshi flow's runtime, a generated service client, an internal sibling package) — substitute your own data source and http client rather than installing them.
+
 ## Design
 
 ### Description

package/dist/docs/CollectionOptimisticActions.md

@@ -4,6 +4,10 @@
 
 Paths written as `dist/…` below are relative to the `@wix/patterns` package root — the directory holding its `package.json`.
 
+Examples below are illustrative: each one demonstrates this page's API, and everything around it — data source, layout, http client — is only scaffolding to make that runnable.
+
+Some of that scaffolding is environment-scoped and is **not** needed to use this component: `@wix/ambassador-contacts-v4-contact/http`, `@wix/ambassador-contacts-v4-contact/types`, `@wix/yoshi-flow-bm`. Those resolve only against a Wix build environment (a Yoshi flow's runtime, a generated service client, an internal sibling package) — substitute your own data source and http client rather than installing them.
+
 ## Design
 
 ### Description
@@ -58,14 +62,14 @@ Create one item optimistically.
  In this example, click on "Create contact" to see a new contact. 
  The item received in the submit function is temporary (can be without id which created in the server). Ensure you return the created item with all the properties from the server response. This will be the item in the collection at the end of this operation.
 
-Example code: read `dist/docs/CollectionOptimisticActions/create-one.tsx`
+Example code: read `dist/examples/CollectionOptimisticActions/create-one.tsx`
 
 ### Create many
 
 Create many items optimatically.
  In this example, click on "Create contacts" to see several new contacts. Scroll down to see the new contacts
 
-Example code: read `dist/docs/CollectionOptimisticActions/create-many.tsx`
+Example code: read `dist/examples/CollectionOptimisticActions/create-many.tsx`
 
 ---
 
@@ -78,14 +82,14 @@ Allows updating items in the collection while submitting the update action to th
 Update one item in the table. 
  In this example, click on update button to see the new level of contact
 
-Example code: read `dist/docs/CollectionOptimisticActions/update-one.tsx`
+Example code: read `dist/examples/CollectionOptimisticActions/update-one.tsx`
 
 ### Update many
 
 Update many items optimatically by using bulk selection.
  In this example, click on all items and see only 2 items are selected because we use `maxSelection`, and only these 2 are been updated
 
-Example code: read `dist/docs/CollectionOptimisticActions/update-many.tsx`
+Example code: read `dist/examples/CollectionOptimisticActions/update-many.tsx`
 
 ### Update all
 
@@ -93,7 +97,7 @@ Update all items optimatically by using bulk selection.
  `updateAll` is for the use case when all items that match the current filtering should be updated, but naturally not all of them are currently visible in the table (because of pagination)
  In this example, click one time on several items and one time on all items and see the updated items
 
-Example code: read `dist/docs/CollectionOptimisticActions/update-all.tsx`
+Example code: read `dist/examples/CollectionOptimisticActions/update-all.tsx`
 
 ---
 
@@ -105,19 +109,19 @@ Allows removing items from the collection while submitting the delete action to
 
 Delete one item optimatically.
 
-Example code: read `dist/docs/CollectionOptimisticActions/delete-one.tsx`
+Example code: read `dist/examples/CollectionOptimisticActions/delete-one.tsx`
 
 ### Delete many
 
 Delete many items optimatically by using bulk selection.
 
-Example code: read `dist/docs/CollectionOptimisticActions/delete-many.tsx`
+Example code: read `dist/examples/CollectionOptimisticActions/delete-many.tsx`
 
 ### Delete all
 
 Delete all items optimatically by using bulk selection. 
 
-Example code: read `dist/docs/CollectionOptimisticActions/delete-all.tsx`
+Example code: read `dist/examples/CollectionOptimisticActions/delete-all.tsx`
 
 ## API
 

package/dist/docs/CollectionPage.Content.md

@@ -2,6 +2,8 @@
 
 **Category:** Base Components/Pages/Collection Page
 
+Examples below are illustrative: each one demonstrates this page's API, and everything around it — data source, layout, http client — is only scaffolding to make that runnable.
+
 ## Design
 
 ### Description

package/dist/docs/CollectionPage.Header.md

@@ -4,6 +4,8 @@
 
 Paths written as `dist/…` below are relative to the `@wix/patterns` package root — the directory holding its `package.json`.
 
+Examples below are illustrative: each one demonstrates this page's API, and everything around it — data source, layout, http client — is only scaffolding to make that runnable.
+
 ## Design
 
 ### Description
@@ -20,19 +22,19 @@ import { CollectionPage } from '@wix/patterns/page';
 
 Rendering a header with title, subtitle, total, primary action, and more actions. To learn how to create a more actions menu, see [`MoreActions`](./?path=/story/features-actions-more-actions--more-actions).
 
-Example code: read `dist/docs/CollectionPage.Header/full.tsx`
+Example code: read `dist/examples/CollectionPage.Header/full.tsx`
 
 ### Without Total
 
 Hiding the total number of entities in the header of a collection page, with `hideTotal` config.
 
-Example code: read `dist/docs/CollectionPage.Header/without-total.tsx`
+Example code: read `dist/examples/CollectionPage.Header/without-total.tsx`
 
 ### With Badges
 
 Rendering one or more [`Badge`](https://www.docs.wixdesignsystem.com/?path=/story/components-indicators--badge) badges at the end of the title row, after the total, with `badges`. Set the skin and text of each; their size is always `small`. Badges are not rendered while the header is collapsed into its minimized state.
 
-Example code: read `dist/docs/CollectionPage.Header/with-badges.tsx`
+Example code: read `dist/examples/CollectionPage.Header/with-badges.tsx`
 
 ## API
 

package/dist/docs/CollectionPage.md

@@ -4,6 +4,8 @@
 
 Paths written as `dist/…` below are relative to the `@wix/patterns` package root — the directory holding its `package.json`.
 
+Examples below are illustrative: each one demonstrates this page's API, and everything around it — data source, layout, http client — is only scaffolding to make that runnable.
+
 ## Design
 
 ### Description

package/dist/docs/CollectionPremiumEmptyState.md

@@ -4,6 +4,10 @@
 
 Paths written as `dist/…` below are relative to the `@wix/patterns` package root — the directory holding its `package.json`.
 
+Examples below are illustrative: each one demonstrates this page's API, and everything around it — data source, layout, http client — is only scaffolding to make that runnable.
+
+Some of that scaffolding is environment-scoped and is **not** needed to use this component: `@wix/ambassador-contacts-v4-contact/types`, `@wix/yoshi-flow-bm`. Those resolve only against a Wix build environment (a Yoshi flow's runtime, a generated service client, an internal sibling package) — substitute your own data source and http client rather than installing them.
+
 ## Design
 
 ### Description

package/dist/docs/CollectionSearch.md

@@ -4,6 +4,8 @@
 
 Paths written as `dist/…` below are relative to the `@wix/patterns` package root — the directory holding its `package.json`.
 
+Examples below are illustrative: each one demonstrates this page's API, and everything around it — data source, layout, http client — is only scaffolding to make that runnable.
+
 ## Design
 
 ### Description
@@ -59,25 +61,25 @@ import { CollectionSearch } from '@wix/patterns';
 
 The search input will bw shown be default
 
-Example code: read `dist/docs/CollectionSearch/default.tsx`
+Example code: read `dist/examples/CollectionSearch/default.tsx`
 
 ### Max length
 
 An option to limit the amout of characaters
 
-Example code: read `dist/docs/CollectionSearch/max-length.tsx`
+Example code: read `dist/examples/CollectionSearch/max-length.tsx`
 
 ### Placeholder
 
 An option to define the placeholder text.
 
-Example code: read `dist/docs/CollectionSearch/placeholder.tsx`
+Example code: read `dist/examples/CollectionSearch/placeholder.tsx`
 
 ### Search highlighting
 
 Gets highlighted search results in the table. Learn how to [enable it](./?path=/story/features-display--highlighted-search-results).
 
-Example code: read `dist/docs/CollectionSearch/search-highlighting.tsx`
+Example code: read `dist/examples/CollectionSearch/search-highlighting.tsx`
 
 ## API
 

package/dist/docs/Component Tests.md

@@ -2,6 +2,10 @@
 
 **Category:** Guides/Component Tests
 
+Examples below are illustrative: each one demonstrates this page's API, and everything around it — data source, layout, http client — is only scaffolding to make that runnable.
+
+Some of that scaffolding is environment-scoped and is **not** needed to use this component: `@wix/yoshi-flow-bm/testkit`, `@wix/yoshi-flow-bm/testkit/http-client`. Those resolve only against a Wix build environment (a Yoshi flow's runtime, a generated service client, an internal sibling package) — substitute your own data source and http client rather than installing them.
+
 ## Design
 
 ### Overview

package/dist/docs/Composition and Providers.md

@@ -0,0 +1,135 @@
+# Composition and Providers
+
+**Category:** Guides
+
+Paths written as `dist/…` below are relative to the `@wix/patterns` package root — the directory holding its `package.json`.
+
+Examples below are illustrative: each one demonstrates this page's API, and everything around it — data source, layout, http client — is only scaffolding to make that runnable.
+
+## Related components
+
+`WixPatternsProvider`, `WixPatternsBMProvider`, `WixPatternsGizaProvider`, `WixPatternsEssentialsProvider`, `WixPatternsBaseProvider`, `CollectionPage`, `EntityPage`, `SettingsPage`, `Table`, `Grid`, `TableGridSwitch`, `TableFolders`, `GridFolders`, `TableState`, `GridState`, `TableGridSwitchState`, `TableFoldersState`, `GridFoldersState`, `useTableCollection`, `useGridCollection`, `useTableGridSwitchCollection`, `useTableFolders`, `useGridFolders`, `PatternsReactRouter`, `PatternsReactRoute`, `usePatternsNavigate`, `withDashboard`
+
+Each name resolves in `dist/docs/index.json` — as a key, or as one of an entry's `symbols` aliases.
+
+## Overview
+
+Every patterns page is four nested layers. Getting the nesting wrong is the most common
+way a page that looks right throws at runtime.
+
+```
+Provider                  <- WixPatternsProvider, or one of the flow-specific providers
+  +-- Page                <- CollectionPage, EntityPage, or SettingsPage
+       +-- Collection     <- Table, Grid, TableGridSwitch, TableFolders, GridFolders
+            +-- Features  <- filters, actions, sorting, drag-and-drop
+```
+
+## The collection triad
+
+Every collection type is the same three pieces — a component, a state type, and the hook
+that builds the state:
+
+| Component | State type | Hook |
+| --- | --- | --- |
+| `Table` | `TableState` | `useTableCollection` |
+| `Grid` | `GridState` | `useGridCollection` |
+| `TableGridSwitch` | `TableGridSwitchState` | `useTableGridSwitchCollection` |
+| `TableFolders` | `TableFoldersState` | `useTableFolders` |
+| `GridFolders` | `GridFoldersState` | `useGridFolders` |
+
+Call the hook, pass the result to the component's `state` prop, and put the component
+inside a page. `useCreateCollection` is not part of this table and does not create items —
+it returns a function that initialises collection state.
+
+## Choosing a provider
+
+There is one provider per host environment, and each has its own entry point. Pick by where
+the app runs, not by preference.
+
+| Provider | Entry point | The host it serves |
+| --- | --- | --- |
+| `WixPatternsProvider` | `@wix/patterns/provider` | The Wix dashboard. Requires the `@wix/dashboard` peer dependency. |
+| `WixPatternsBMProvider` | `@wix/patterns/bm` | Yoshi BM Flow over Business Manager. |
+| `WixPatternsGizaProvider` | `@wix/patterns/giza` | Yoshi BM Flow over Giza. |
+| `WixPatternsEssentialsProvider` | `@wix/patterns/essentials` | Yoshi Fullstack. |
+| `WixPatternsBaseProvider` | `@wix/patterns/essentials` | Neither Giza nor Essentials — you inject i18n, sentry and the rest yourself. |
+
+**No provider detects its environment for you**, and none of them is a drop-in for another:
+each entry point exports exactly the one provider named above — except `essentials`, which
+carries two — so reaching for the wrong subpath is an import error rather than a silent
+fallback. The project's own flow decides which row applies; each provider's doc carries its
+import line verbatim.
+
+## The provider must be a parent, not a sibling
+
+Collection hooks read the provider's context, so the provider has to be **above** them in
+the tree — in a different component, not the same one.
+
+This throws at runtime, and the JSX looks correct, which is what makes it hard to see:
+
+
+```tsx
+function ShiftsApp() {
+  // `useTableCollection` runs before `WixPatternsProvider` exists above it
+  const state = useTableCollection({ /* … */ });
+  return (
+    <WixPatternsProvider>
+      <Table state={state} columns={columns} />
+    </WixPatternsProvider>
+  );
+}
+```
+
+Split the provider and the page into separate components:
+
+```tsx
+// ShiftsApp.tsx
+import { WixPatternsProvider } from '@wix/patterns/provider';
+
+interface Shift {
+  id: string;
+  name: string;
+}
+
+function ShiftsRoot() {
+  return (
+    <WixPatternsProvider>
+      <ShiftsCollectionPage />
+    </WixPatternsProvider>
+  );
+}
+
+// ShiftsCollectionPage.tsx
+import { Table, useTableCollection, OffsetQuery } from '@wix/patterns';
+import { CollectionPage } from '@wix/patterns/page';
+
+function ShiftsCollectionPage() {
+  // the provider's context exists above this component
+  const state = useTableCollection<Shift>({
+    queryName: 'shifts',
+    itemKey: (item) => item.id,
+    itemName: (item) => item.name,
+    fetchData: async (query: OffsetQuery) => ({ items: [] as Shift[], total: 0 }),
+    filters: {},
+  });
+
+  return (
+    <CollectionPage>
+      <Table state={state} columns={[{ title: 'Name', render: (item) => item.name }]} />
+    </CollectionPage>
+  );
+}
+```
+
+Keep the provider — and the router, if there is one — in the app's root component, and give
+each page its own file.
+
+## More than one page
+
+Use the library's own router rather than adding a second one: `PatternsReactRouter`,
+`PatternsReactRoute` and `usePatternsNavigate`. The router reads the page location out of
+the dashboard context that `withDashboard` renders, so it needs that wrapper above it with a
+`location` prop and throws at render time without one. `PatternsReactRouter`'s
+**Requirements** section has the setup.
+
+

package/dist/docs/ComputedQuery.md

@@ -4,6 +4,8 @@
 
 Paths written as `dist/…` below are relative to the `@wix/patterns` package root — the directory holding its `package.json`.
 
+Examples below are illustrative: each one demonstrates this page's API, and everything around it — data source, layout, http client — is only scaffolding to make that runnable.
+
 ## API
 
 ### Overview