@wix/patterns 1.458.0 → 1.460.0

package/dist/docs/useCreateCollection.md

@@ -10,23 +10,10 @@ React hook that that retuns a function that initializes a collection state. Simi
 
 ### Props
 
-| Prop | Type | Required | Default | Description |
-|------|------|----------|---------|-------------|
-| `paginationMode` | `"cursor" \| "offset"` | No | `offset` | Pagination type supported by `fetchData`. <br> <br> Supported values: <br> - `"offset"`: Server accepts `query.offset`. <br> - `"cursor"`: Server returns a cursor when `fetchData` is called. |
-| `fetchData` | `(query: ComputedQuery<F>) => Promise<DataResultRaw<T>>` | Yes | - | Function that fetches the collection data.<br> <br> Supported parameters: <br> - `query`: [object] [ComputedQuery](./com?path=/story/common-models--computedquery) instance. <br> <br> Must return a [DataResultRaw](./?path=/story/common-models--dataresultraw) Promise. |
-| `fetchTotal` | `FetchTotalFn` | No | - | A function that fetches the total number of items in the collection.<br> <br> Supported parameters: <br> - `query`: [object] [ComputedQuery](./com?path=/story/common-models--computedquery) of type `CursorQuery`. <br> <br> Must return a number Promise. |
-| `filters` | `FiltersMap` | Yes | - | Defines the filters that the collection supports. <br> <br> Either an [arrayFilter](./?path=/story/features-filter-factories--arrayfilter) or a [customFilter](./?path=/story/features-filter-factories--customfilter). |
-| `itemName` | `(item: T) => string` | Yes | - | Used to identify the item in many messages from Wix Patterns. <br> <br> For example, '{entity} "{itemName}" was deleted successfully' may become 'Contact "Johnny Doe" was deleted successfully'. <br> <br> If your data has an ID, then `itemKey` will default to this ID. |
-| `itemKey` | `(item: T) => string` | Yes | - | Unique key within the collection. The item's ID is often used for its key. <br> <br> If your data has an ID, then `itemKey` will default to this ID. |
-| `limit` | `number` | No | - | Maximum number of items fetched per page. |
-| `disableAutoSelectAllCount` | `boolean` | No | - | Whether to disable "Select All" server simulation for bulk selection. |
-| `useNewSelectAllLogic` | `boolean` | No | - | Whether to enable new "Select All" logic. <br> <br> If `true`: <br> - Unchecking items after checking "Select All" does not fallback to specific selection logic and values. This means in `<bulkActionToolbar />` and `<MultiBulkActionToolbar />`, "Total Selected" will show `total - unchecked items` and `isSelectAll` will be true. <br> - You will receive a list of unchecked IDs. |
-| `queryName` | `string` | Yes | - | Unique value for each API endpoint consumed in `fetchData`. |
-| `fqdn` | `string` | No | - | Entity fqdn. |
-| `toExtendedFields` | `((item: T) => ExtendedFields \| null)` | No | - | The `ExtendedFields` object used to render custom field values Optional in case your data complies to the type `{ extendedFields: ExtendedFields }` |
-| `fetchErrorMessage` | `((params: { err: unknown; isOnline: boolean; }) => string \| null)` | No | - | Message shown in a toast when fetching from the server fails. <br> <br> If the function returns a nullish value, no toast is shown. @deprecated Instead of using `fetchErrorMessage`, use `errorState` prop in the component, which will show the error message in the card. |
-| `persistQueryToUrl` | `boolean` | No | `false` | Persist the selected filters, search & sort in the query parameters of the URL.<br/> For improved readability, sort & columns are formatted in CSV-like formatting, i.e "?sort=name+desc,price+asc". Do not use commas and/or spaces for your columns IDs.<br> Note: The filters from the selected view will be persist, but the actual view will not be selected |
-| `refreshOnColumnsChange` | `boolean` | No | `false` | Whether the collection refreshes when different columns are selected. <br> <br> Selected columns are passed in `fetchData(query.columns)`. |
-| `selectionConsistencyMode` | `"clear" \| "preserve"` | No | `preserve` | Preserve or clear selection after applying a new search or filter. |
-| `events` | `CollectionEvents<F>` | No | - | Optional callbacks for various events of the collection state lifecycle - `onInitialPageFetched` - when the first page of items is ready - `onSearch` - when fetching new items as a result new search - `onSearchResults` - when the result of a search is ready - `onNewPageStart` - when starting to load the next page of items - `onNewPageAdded` - when the result of the next page is ready - `onError` - When `fetchData` throws an error. Return `true` from this function if the error was reported and shouldn't be reported again internally. |
+Read `dist/dts-bundle/hooks/useCreateCollection.d.ts` for `useCreateCollection`'s full prop list, with types and
+descriptions. They are not repeated here, so the bundle is the single source of truth.
+
+A one-line stub in that file is an answer, not a truncation: an empty body with a
+"Produced by" note means you get the value from that hook or factory rather than
+constructing it. `dist/dts-bundle/index.json` maps every name to its bundle path.
 

package/dist/docs/useEntity.md

@@ -74,4 +74,5 @@ Returns [`EntityPageState`](./?path=/story/base-components-pages-entity-page-sta
 | `panels` | `SidePanelsState \| null` | Yes | - | The page's side-panel host, the way a table's lives on its toolbar. Attached by the first feature that needs one, through `SidePanelsState.setOnPage` — so a page with no panels neither builds nor bundles the side-panel code. Everything on the page shares this host, which is what keeps one panel open at a time. |
 | `customColumnsState` | `CustomColumnsEntityPageState \| null` | Yes | - | The fields card's "Manage fields" state, set by the card that owns it — the panel is rendered by the host with no props and reads it from here, as a table's panel reads `toolbar.customColumnsState`. |
 | `fieldsContainer` | `PatternsFieldsAppContainer \| undefined` | Yes | - | The container the page's field renderers are built with — the one the schema carries, so a table on the same schema shares it. Initialized in `init()` below, next to the schema load the fields also wait on; the schema-entry EntityPage puts it in React context. |
+| `holdSave` | `() => () => void` | Yes | - | Blocks `handleSubmit` until the returned release is called (idempotent). For features whose form fields are not mounted yet — react-hook-form only validates mounted controls, so a save in that window would skip their required-field validation. |
 

package/dist/docs/useEntityPage.md

@@ -70,17 +70,10 @@ export default EditShift;
 
 ### Props
 
-| Prop | Type | Required | Default | Description |
-|------|------|----------|---------|-------------|
-| `fetch` | `() => Promise<{ entity: T \| undefined; }>` | Yes | - | A function that fetches the entity data. @returns a promise that resolves to an object containing the entity. |
-| `onSave` | `(params: OnSaveParams) => Promise<{ updatedEntity: T; }>` | Yes | - | A function to handle the save action. @returns promise that resolves to an object that contains a 'updatedEntity' object. |
-| `saveSuccessToast` | `string \| { message?: string; }` | No | - | An optional object with an optional message, or it can directly get a string message. |
-| `saveErrorToast` | `((err: unknown, params: { retry: () => void; }) => string \| { message?: string; tryAgain?: boolean; action?: { text: string; onClick: () => void; } \| undefined; }) \| undefined` | No | - | An optional function to display an error toast message when a save operation fails. @returns An object with a `message` and an `action` object. Alternatively, it can return an object with an optional `message` and a `tryAgain` flag, or a string message. The previous return types are still supported but are now deprecated. |
-| `deleteAction` | `EntityPageDeleteAction<T>` | No | - | Enables deleting the loaded entity from the entity page. Pass `true` for a schema-backed page to use the source backend, or an object to customize the action and to provide a delete handler for manually wired pages. |
-| `transformEntityToCollectionItem` | `((entity: T) => any)` | No | - | An optional function to transform the updated entity data before it is passed to the collection page. @param entity the updated entity. @returns an object representing the entity in the collection page. |
-| `isNewEntity` | `boolean \| (() => boolean)` | No | - | Whether the page was opened to create a new entity rather than to edit an existing one. Decides how a save is announced to the parent page — created vs updated — so a new item seeded with local defaults is still announced as created. Pass a getter when the route can change while the page stays mounted. When omitted, the announcement follows whether an entity was loaded. |
-| `parentPageId` | `string` | No | - | A string representing the ID of the parent page. Must be passed if not using Patterns Router |
-| `parentPath` | `string` | No | - | A string representing the path of the parent page. Must be passed if using Patterns Router |
-| `parentReferrer` | `string` | No | - | Referrer forwarded to the parent page on back, cancel and save, so callers can carry navigation context across the transition. Only used for parentPageId navigations; Patterns Router keeps its context in router state. Forwarded by the BM and Giza providers. Dropped by the dashboard provider, whose SDK Destination has no referrer field. |
-| `schemaSource` | `SchemaSource<T>` | No | - | An optional schema source describing how to load the schema and access the entity's data. When present, the page can read fields from the source instead of relying only on hand-wired fetch/onSave callbacks. |
+Read `dist/dts-bundle/hooks/useEntityPage.d.ts` for `useEntityPage`'s full prop list, with types and
+descriptions. They are not repeated here, so the bundle is the single source of truth.
+
+A one-line stub in that file is an answer, not a truncation: an empty body with a
+"Produced by" note means you get the value from that hook or factory rather than
+constructing it. `dist/dts-bundle/index.json` maps every name to its bundle path.
 

package/dist/docs/useFilterCollection.md

@@ -147,17 +147,10 @@ function ContactsFilterCollection() {
 
 ### Props
 
-| Prop | Type | Required | Default | Description |
-|------|------|----------|---------|-------------|
-| `fetchTotal` | `FetchTotalFn` | No | - | A function that fetches the total number of items in the collection.<br> <br> Supported parameters: <br> - `query`: [object] [ComputedQuery](./com?path=/story/common-models--computedquery) of type `CursorQuery`. <br> <br> Must return a number Promise. |
-| `limit` | `number` | No | - | Maximum number of items fetched per page. |
-| `disableAutoSelectAllCount` | `boolean` | No | - | Whether to disable "Select All" server simulation for bulk selection. |
-| `useNewSelectAllLogic` | `boolean` | No | - | Whether to enable new "Select All" logic. <br> <br> If `true`: <br> - Unchecking items after checking "Select All" does not fallback to specific selection logic and values. This means in `<bulkActionToolbar />` and `<MultiBulkActionToolbar />`, "Total Selected" will show `total - unchecked items` and `isSelectAll` will be true. <br> - You will receive a list of unchecked IDs. |
-| `queryName` | `string` | Yes | - | Unique value for each API endpoint consumed in `fetchData`. |
-| `fqdn` | `string` | No | - | Entity fqdn. |
-| `toExtendedFields` | `((item: T) => ExtendedFields \| null)` | No | - | The `ExtendedFields` object used to render custom field values Optional in case your data complies to the type `{ extendedFields: ExtendedFields }` |
-| `persistQueryToUrl` | `boolean` | No | `false` | Persist the selected filters, search & sort in the query parameters of the URL.<br/> For improved readability, sort & columns are formatted in CSV-like formatting, i.e "?sort=name+desc,price+asc". Do not use commas and/or spaces for your columns IDs.<br> Note: The filters from the selected view will be persist, but the actual view will not be selected |
-| `refreshOnColumnsChange` | `boolean` | No | `false` | Whether the collection refreshes when different columns are selected. <br> <br> Selected columns are passed in `fetchData(query.columns)`. |
-| `selectionConsistencyMode` | `"clear" \| "preserve"` | No | `preserve` | Preserve or clear selection after applying a new search or filter. |
-| `events` | `CollectionEvents<F>` | No | - | Optional callbacks for various events of the collection state lifecycle - `onInitialPageFetched` - when the first page of items is ready - `onSearch` - when fetching new items as a result new search - `onSearchResults` - when the result of a search is ready - `onNewPageStart` - when starting to load the next page of items - `onNewPageAdded` - when the result of the next page is ready - `onError` - When `fetchData` throws an error. Return `true` from this function if the error was reported and shouldn't be reported again internally. |
+Read `dist/dts-bundle/hooks/useFilterCollection.d.ts` for `useFilterCollection`'s full prop list, with types and
+descriptions. They are not repeated here, so the bundle is the single source of truth.
+
+A one-line stub in that file is an answer, not a truncation: an empty body with a
+"Produced by" note means you get the value from that hook or factory rather than
+constructing it. `dist/dts-bundle/index.json` maps every name to its bundle path.
 

package/dist/docs/useGridCollection.md

@@ -42,23 +42,10 @@ return (
 
 ### Props
 
-| Prop | Type | Required | Default | Description |
-|------|------|----------|---------|-------------|
-| `paginationMode` | `"cursor" \| "offset"` | No | `offset` | Pagination type supported by `fetchData`. <br> <br> Supported values: <br> - `"offset"`: Server accepts `query.offset`. <br> - `"cursor"`: Server returns a cursor when `fetchData` is called. |
-| `fetchData` | `(query: ComputedQuery<F>) => Promise<DataResultRaw<T>>` | Yes | - | Function that fetches the collection data.<br> <br> Supported parameters: <br> - `query`: [object] [ComputedQuery](./com?path=/story/common-models--computedquery) instance. <br> <br> Must return a [DataResultRaw](./?path=/story/common-models--dataresultraw) Promise. |
-| `fetchTotal` | `FetchTotalFn` | No | - | A function that fetches the total number of items in the collection.<br> <br> Supported parameters: <br> - `query`: [object] [ComputedQuery](./com?path=/story/common-models--computedquery) of type `CursorQuery`. <br> <br> Must return a number Promise. |
-| `filters` | `FiltersMap` | Yes | - | Defines the filters that the collection supports. <br> <br> Either an [arrayFilter](./?path=/story/features-filter-factories--arrayfilter) or a [customFilter](./?path=/story/features-filter-factories--customfilter). |
-| `itemName` | `(item: T) => string` | Yes | - | Used to identify the item in many messages from Wix Patterns. <br> <br> For example, '{entity} "{itemName}" was deleted successfully' may become 'Contact "Johnny Doe" was deleted successfully'. <br> <br> If your data has an ID, then `itemKey` will default to this ID. |
-| `itemKey` | `(item: T) => string` | Yes | - | Unique key within the collection. The item's ID is often used for its key. <br> <br> If your data has an ID, then `itemKey` will default to this ID. |
-| `limit` | `number` | No | - | Maximum number of items fetched per page. |
-| `disableAutoSelectAllCount` | `boolean` | No | - | Whether to disable "Select All" server simulation for bulk selection. |
-| `useNewSelectAllLogic` | `boolean` | No | - | Whether to enable new "Select All" logic. <br> <br> If `true`: <br> - Unchecking items after checking "Select All" does not fallback to specific selection logic and values. This means in `<bulkActionToolbar />` and `<MultiBulkActionToolbar />`, "Total Selected" will show `total - unchecked items` and `isSelectAll` will be true. <br> - You will receive a list of unchecked IDs. |
-| `queryName` | `string` | Yes | - | Unique value for each API endpoint consumed in `fetchData`. |
-| `fqdn` | `string` | No | - | Entity fqdn. |
-| `toExtendedFields` | `((item: T) => ExtendedFields \| null)` | No | - | The `ExtendedFields` object used to render custom field values Optional in case your data complies to the type `{ extendedFields: ExtendedFields }` |
-| `fetchErrorMessage` | `((params: { err: unknown; isOnline: boolean; }) => string \| null)` | No | - | Message shown in a toast when fetching from the server fails. <br> <br> If the function returns a nullish value, no toast is shown. @deprecated Instead of using `fetchErrorMessage`, use `errorState` prop in the component, which will show the error message in the card. |
-| `persistQueryToUrl` | `boolean` | No | `false` | Persist the selected filters, search & sort in the query parameters of the URL.<br/> For improved readability, sort & columns are formatted in CSV-like formatting, i.e "?sort=name+desc,price+asc". Do not use commas and/or spaces for your columns IDs.<br> Note: The filters from the selected view will be persist, but the actual view will not be selected |
-| `refreshOnColumnsChange` | `boolean` | No | `false` | Whether the collection refreshes when different columns are selected. <br> <br> Selected columns are passed in `fetchData(query.columns)`. |
-| `selectionConsistencyMode` | `"clear" \| "preserve"` | No | `preserve` | Preserve or clear selection after applying a new search or filter. |
-| `events` | `CollectionEvents<F>` | No | - | Optional callbacks for various events of the collection state lifecycle - `onInitialPageFetched` - when the first page of items is ready - `onSearch` - when fetching new items as a result new search - `onSearchResults` - when the result of a search is ready - `onNewPageStart` - when starting to load the next page of items - `onNewPageAdded` - when the result of the next page is ready - `onError` - When `fetchData` throws an error. Return `true` from this function if the error was reported and shouldn't be reported again internally. |
+Read `dist/dts-bundle/hooks/useGridCollection.d.ts` for `useGridCollection`'s full prop list, with types and
+descriptions. They are not repeated here, so the bundle is the single source of truth.
+
+A one-line stub in that file is an answer, not a truncation: an empty body with a
+"Produced by" note means you get the value from that hook or factory rather than
+constructing it. `dist/dts-bundle/index.json` maps every name to its bundle path.
 

package/dist/docs/useGridFolders.md

@@ -18,8 +18,10 @@ import { useGridFolders } from '@wix/patterns';
 
 ### Props
 
-| Prop | Type | Required | Default | Description |
-|------|------|----------|---------|-------------|
-| `items` | `CollectionState<T1, F1>` | Yes | - | A [collection state](./?path=/story/common-hooks--usecollection) that fetches items |
-| `folders` | `CollectionState<T2, F2>` | Yes | - | A [collection state](./?path=/story/common-hooks--usecollection) that fetches folders |
+Read `dist/dts-bundle/hooks/useGridFolders.d.ts` for `useGridFolders`'s full prop list, with types and
+descriptions. They are not repeated here, so the bundle is the single source of truth.
+
+A one-line stub in that file is an answer, not a truncation: an empty body with a
+"Produced by" note means you get the value from that hook or factory rather than
+constructing it. `dist/dts-bundle/index.json` maps every name to its bundle path.
 

package/dist/docs/useOptimisticActions/custom-error-handling.tsx

@@ -0,0 +1,178 @@
+import { Avatar } from '@wix/design-system';
+import React from 'react';
+import { CollectionPage } from '@wix/patterns/page';
+import {
+  Table,
+  OffsetQuery,
+  PrimaryActionButton,
+  useTableCollection,
+  useOptimisticActions,
+} from '@wix/patterns';
+import { Delete } from '@wix/wix-ui-icons-common';
+import { contacts } from '@wix/crm';
+
+function CustomErrorHandling() {
+
+  const state = useTableCollection<contacts.Contact>({
+    queryName: 'contacts-CustomErrorHandling',
+    itemName: (item) => `${item.info?.name?.first} ${item.info?.name?.last}`,
+    fetchData: (query: OffsetQuery) => {
+      const { limit, offset, search } = query;
+
+      let queryBuilder = contacts.queryContacts().limit(limit).skip(offset);
+
+      if (search) {
+        queryBuilder = queryBuilder.startsWith('info.name.first', search);
+      }
+
+      return queryBuilder.find().then(({ items = [], totalCount: total }) => ({
+        items,
+        total,
+      }));
+    },
+    fetchErrorMessage: () => 'Error fetching contacts',
+  });
+
+  const collection = state.collection;
+
+  const optimisticActions = useOptimisticActions(collection);
+
+  const _createContact = () => {
+    const newContact = {
+      id: new window.Date().toString(),
+      info: {
+        name: {
+          first: 'New',
+          last: 'Contact',
+        },
+      },
+    };
+
+    optimisticActions.createOne(newContact, {
+      errorToast: (err, { retry }) => ({
+        message: 'failed to create a contact',
+        action: {
+          text: 'My custom action',
+          onClick: () => {
+            retry();
+            console.log('retry');
+          },
+        },
+      }),
+      submit: async (contacts) => {
+        return new Promise((resolve, reject) => {
+          window.setTimeout(() => {
+            reject(new Error('error'));
+          }, 1000);
+        });
+      },
+    });
+  };
+
+  const _updateContact = (contact: contacts.Contact) => {
+    const updatedContact = {
+      ...contact,
+      info: {
+        ...contact.info,
+        jobTitle: 'Ultimate',
+      },
+    };
+    optimisticActions.updateOne(updatedContact, {
+      errorToast: (err, { retry }) => ({
+        message: 'failed to update a contact',
+        action: {
+          text: 'My custom action',
+          onClick: () => {
+            retry();
+            console.log('retry');
+          },
+        },
+      }),
+      submit: async (contacts) => {
+        return new Promise((resolve, reject) => {
+          window.setTimeout(() => {
+            reject(new Error('error'));
+          }, 1000);
+        });
+      },
+    });
+  };
+
+  const _deleteContact = (contact: contacts.Contact) => {
+    optimisticActions.deleteOne(contact, {
+      errorToast: (err, { retry }) => ({
+        message: 'failed to delete a contact',
+        action: {
+          text: 'My custom action',
+          onClick: () => {
+            retry();
+            console.log('retry');
+          },
+        },
+      }),
+      submit: async (contacts) => {
+        return new Promise((resolve, reject) => {
+          window.setTimeout(() => {
+            reject(new Error('error'));
+          }, 1000);
+        });
+      },
+    });
+  };
+
+  return (
+    <CollectionPage height="400px">
+      <CollectionPage.Header title={{ text: 'Contacts' }} />
+      <CollectionPage.Content>
+        <Table
+          state={collection}
+          primaryActionButton={<PrimaryActionButton onClick={_createContact} />}
+          columns={[
+            {
+              title: '',
+              width: '50px',
+              render: (contact) => (
+                <Avatar
+                  name={`${contact.info?.name?.first} ${contact.info?.name?.last}`}
+                  imgProps={{ src: contact.info?.picture?.image }}
+                />
+              ),
+            },
+            {
+              title: 'Name',
+              width: '250px',
+              render: (contact) =>
+                `${contact.info?.name?.first} ${contact.info?.name?.last}`,
+            },
+            {
+              title: 'Level',
+              render: (contact) => contact.info?.jobTitle,
+            },
+            {
+              title: 'Last Activity',
+              render: (contact) =>
+                contact.lastActivity?.activityDate?.toLocaleString(),
+            },
+          ]}
+          actionCell={(contact) => ({
+            primaryAction: {
+              text: 'Update',
+              onClick: () => {
+                _updateContact(contact);
+              },
+            },
+            secondaryActions: [
+              {
+                icon: <Delete />,
+                text: 'Delete',
+                onClick: () => {
+                  _deleteContact(contact);
+                },
+              },
+            ],
+          })}
+        />
+      </CollectionPage.Content>
+    </CollectionPage>
+  );
+}

package/dist/docs/useOptimisticActions/default-behaviour.tsx

@@ -0,0 +1,155 @@
+import { Avatar } from '@wix/design-system';
+import React from 'react';
+import { CollectionPage } from '@wix/patterns/page';
+import {
+  Table,
+  OffsetQuery,
+  PrimaryActionButton,
+  useTableCollection,
+  useOptimisticActions,
+} from '@wix/patterns';
+import { Delete } from '@wix/wix-ui-icons-common';
+import { contacts } from '@wix/crm';
+
+function DefaultBehaviour() {
+  const state = useTableCollection<contacts.Contact>({
+    queryName: 'contacts-DefaultBehaviour',
+    itemName: (item) => `${item.info?.name?.first} ${item.info?.name?.last}`,
+    fetchData: (query: OffsetQuery) => {
+      const { limit, offset, search, filters } = query;
+
+      let queryBuilder = contacts.queryContacts().limit(limit).skip(offset);
+
+      if (search) {
+        queryBuilder = queryBuilder.startsWith('info.name.first', search);
+      }
+
+      return queryBuilder.find().then(({ items = [], totalCount: total }) => ({
+        items,
+        total,
+      }));
+    },
+    fetchErrorMessage: () => 'Error fetching contacts',
+  });
+
+  const collection = state.collection;
+
+  const optimisticActions = useOptimisticActions(collection);
+
+  const _createContact = () => {
+    const newContact = {
+      id: new window.Date().toString(),
+      info: {
+        name: {
+          first: 'New',
+          last: 'Contact',
+        },
+      },
+    };
+
+    optimisticActions.createOne(newContact, {
+      submit: async (_contacts) => {
+        const response = (await Promise.all(
+          _contacts.map((contact) =>
+            contacts.createContact(contact.info as contacts.ContactInfo),
+          ),
+        )) as contacts.CreateContactResponse[];
+
+        return response.map(({ contact }) => contact as contacts.Contact);
+      },
+    });
+  };
+
+  const _updateContact = (contact: contacts.Contact) => {
+    const updatedContact = {
+      ...contact,
+      info: {
+        ...contact.info,
+        jobTitle: 'Ultimate',
+      },
+    };
+
+    optimisticActions.updateOne(updatedContact, {
+      submit: async (_contacts) => {
+        const response = (await Promise.all(
+          _contacts.map((contact) =>
+            contacts.updateContact(
+              contact._id as string,
+              contact.info as contacts.ContactInfo,
+              contact.revision as number,
+            ),
+          ),
+        )) as contacts.UpdateContactResponse[];
+
+        return response.map(({ contact }) => contact as contacts.Contact);
+      },
+    });
+  };
+
+  const _deleteContact = (contact: contacts.Contact) => {
+    optimisticActions.deleteOne(contact, {
+      submit: async (_contacts) =>
+        Promise.all(
+          _contacts.map((contact) =>
+            contacts.deleteContact(contact._id as string),
+          ),
+        ),
+    });
+  };
+
+  return (
+    <CollectionPage height="400px">
+      <CollectionPage.Header title={{ text: 'Contacts' }} />
+      <CollectionPage.Content>
+        <Table
+          state={collection}
+          primaryActionButton={<PrimaryActionButton onClick={_createContact} />}
+          columns={[
+            {
+              title: '',
+              width: '50px',
+              render: (contact) => (
+                <Avatar
+                  name={`${contact.info?.name?.first} ${contact.info?.name?.last}`}
+                  imgProps={{ src: contact.info?.picture?.image }}
+                />
+              ),
+            },
+            {
+              title: 'Name',
+              width: '250px',
+              render: (contact) =>
+                `${contact.info?.name?.first} ${contact.info?.name?.last}`,
+            },
+            {
+              title: 'Level',
+              render: (contact) => contact.info?.jobTitle,
+            },
+            {
+              title: 'Last Activity',
+              render: (contact) =>
+                contact.lastActivity?.activityDate?.toLocaleString(),
+            },
+          ]}
+          actionCell={(contact) => ({
+            primaryAction: {
+              text: 'Update',
+              onClick: () => {
+                _updateContact(contact);
+              },
+            },
+            secondaryActions: [
+              {
+                icon: <Delete />,
+                text: 'Delete',
+                onClick: () => {
+                  _deleteContact(contact);
+                },
+              },
+            ],
+          })}
+        />
+      </CollectionPage.Content>
+    </CollectionPage>
+  );
+}

package/dist/docs/useOptimisticActions/error-handling-and-retries.tsx

@@ -0,0 +1,175 @@
+import { Avatar } from '@wix/design-system';
+import React from 'react';
+import { CollectionPage } from '@wix/patterns/page';
+import {
+  Table,
+  OffsetQuery,
+  PrimaryActionButton,
+  useTableCollection,
+  useOptimisticActions,
+} from '@wix/patterns';
+import { Delete } from '@wix/wix-ui-icons-common';
+import { contacts } from '@wix/crm';
+
+function ErrorHandlingAndRetries() {
+
+  const state = useTableCollection<contacts.Contact>({
+    queryName: 'contacts-ErrorHandlingAndRetries',
+    itemName: (item) => `${item.info?.name?.first} ${item.info?.name?.last}`,
+    fetchData: (query: OffsetQuery) => {
+      const { limit, offset, search, filters } = query;
+
+      let queryBuilder = contacts.queryContacts().limit(limit).skip(offset);
+
+      if (search) {
+        queryBuilder = queryBuilder.startsWith('info.name.first', search);
+      }
+
+      return queryBuilder.find().then(({ items = [], totalCount: total }) => ({
+        items,
+        total,
+      }));
+    },
+    fetchErrorMessage: () => 'Error fetching contacts',
+  });
+
+  const collection = state.collection;
+
+  const optimisticActions = useOptimisticActions(collection);
+
+  const _createContact = () => {
+    const newContact = {
+      id: new window.Date().toString(),
+      info: {
+        name: {
+          first: 'New',
+          last: 'Contact',
+        },
+      },
+    };
+
+    optimisticActions.createOne(newContact, {
+      errorToast: (err) => 'failed to create a contact',
+      onError: (err) => {
+        // report error to server
+        console.log('error');
+      },
+      onTryAgain: () => {
+        // report error to server
+        console.log('try again');
+      },
+      submit: async (contacts) => {
+        return new Promise((resolve, reject) => {
+          window.setTimeout(() => {
+            reject(new Error('error'));
+          }, 1000);
+        });
+      },
+    });
+  };
+
+  const _updateContact = (contact: contacts.Contact) => {
+    const updatedContact = {
+      ...contact,
+      info: {
+        ...contact.info,
+        jobTitle: 'Ultimate',
+      },
+    };
+    optimisticActions.updateOne(updatedContact, {
+      errorToast: (err) => 'failed to update a contact',
+      onError: (err) => {
+        // report error to server
+        console.log('error');
+      },
+      onTryAgain: () => {
+        // report error to server
+        console.log('try again');
+      },
+      submit: async (contacts) => {
+        return new Promise((resolve, reject) => {
+          window.setTimeout(() => {
+            reject(new Error('error'));
+          }, 1000);
+        });
+      },
+    });
+  };
+
+  const _deleteContact = (contact: contacts.Contact) => {
+    optimisticActions.deleteOne(contact, {
+      errorToast: (err) => 'failed to delete a contact',
+      onError: (err) => {
+        // report error to server
+        console.log('error');
+      },
+      onTryAgain: () => {
+        // report error to server
+        console.log('try again');
+      },
+      submit: async (contacts) => {
+        return new Promise((resolve, reject) => {
+          window.setTimeout(() => {
+            reject(new Error('error'));
+          }, 1000);
+        });
+      },
+    });
+  };
+
+  return (
+    <CollectionPage height="400px">
+      <CollectionPage.Header title={{ text: 'Contacts' }} />
+      <CollectionPage.Content>
+        <Table
+          state={collection}
+          primaryActionButton={<PrimaryActionButton onClick={_createContact} />}
+          columns={[
+            {
+              title: '',
+              width: '50px',
+              render: (contact) => (
+                <Avatar
+                  name={`${contact.info?.name?.first} ${contact.info?.name?.last}`}
+                  imgProps={{ src: contact.info?.picture?.image }}
+                />
+              ),
+            },
+            {
+              title: 'Name',
+              width: '250px',
+              render: (contact) =>
+                `${contact.info?.name?.first} ${contact.info?.name?.last}`,
+            },
+            {
+              title: 'Level',
+              render: (contact) => contact.info?.jobTitle,
+            },
+            {
+              title: 'Last Activity',
+              render: (contact) =>
+                contact.lastActivity?.activityDate?.toLocaleString(),
+            },
+          ]}
+          actionCell={(contact) => ({
+            primaryAction: {
+              text: 'Update',
+              onClick: () => {
+                _updateContact(contact);
+              },
+            },
+            secondaryActions: [
+              {
+                icon: <Delete />,
+                text: 'Delete',
+                onClick: () => {
+                  _deleteContact(contact);
+                },
+              },
+            ],
+          })}
+        />
+      </CollectionPage.Content>
+    </CollectionPage>
+  );
+}