@wix/patterns 1.364.0 → 1.369.0

package/dist/docs/operatorFilter.md

@@ -0,0 +1,183 @@
+# operatorFilter
+
+**Category:** Features/Filter/Factories
+
+## Design
+
+### Usage
+
+The `operatorFilter` factory creates a filter that combines an operator selection with a value input. It is ideal for advanced filtering scenarios where users need to specify how they want to filter data.
+
+This filter is particularly useful when you want to give users fine-grained control over how they search or filter data. Instead of a simple "contains" search, users can choose between exact matches, partial matches, negations, and more.
+
+**Important: Don't use only value-less operators (`IS_EMPTY`, `NOT_EXISTS`). At least one operator requiring a value must be included.**
+
+### Supported Operators
+
+| Operator | WQL | Description |
+|----------|-----|-------------|
+| `EQUALS` | `$eq` | Equal - exact match |
+| `NOT_EQUALS` | `$ne` | Not equal - exclude exact match |
+| `IN` | `$in` | In - value is in the provided array |
+| `NOT_IN` | `$nin` | Not in - value is not in the provided array |
+| `STARTS_WITH` | `$startsWith` | Starts with - string starts with the provided value |
+| `IS_EMPTY` | `$isEmpty` | Is empty - value is null or empty |
+| `CONTAINS` | `$contains` | Contains - string contains the provided value |
+| `NOT_CONTAINS` | `$notContains` | Not contains - string does not contain the provided value |
+| `EXISTS` | `$exists` | Exists - field is not null/undefined |
+| `NOT_EXISTS` | `$notExists` | Not exists - field is null/undefined |
+
+
+```tsx
+import { operatorFilter, FilterOperator, OperatorFilterPicker } from '@wix/patterns';
+```
+
+### string filter
+
+A complete example showing how to use `operatorFilter` with a Table component. Select an operator from the side panel to filter the data.
+
+```tsx
+import { Avatar, Box, Heading } from '@wix/design-system';
+import React from 'react';
+import { CollectionPage } from '@wix/patterns/page';
+import {
+  operatorFilter,
+  FilterOperator,
+  OperatorFilterPicker,
+  transformOperatorFilterToWQL,
+  Table,
+  useTableCollection,
+} from '@wix/patterns';
+import { useHttpClient, searchContacts } from '../../../.storybook/http-client';
+
+interface Contact {
+  id: string;
+  name: string;
+  level: string;
+  createdDate: string | Date;
+}
+
+function operatorFilterWithTableExample() {
+  const httpClient = useHttpClient(100);
+
+  const [nameFilter] = React.useState(() =>
+    operatorFilter({
+      name: 'name',
+      allowedOperators: [
+        FilterOperator.EQUALS,
+        FilterOperator.NOT_EQUALS,
+        FilterOperator.STARTS_WITH,
+        FilterOperator.CONTAINS,
+        FilterOperator.NOT_CONTAINS,
+        FilterOperator.IS_EMPTY,
+        FilterOperator.EXISTS,
+        FilterOperator.NOT_EXISTS,
+        FilterOperator.IN,
+        FilterOperator.NOT_IN,
+      ],
+    }),
+  );
+
+  const state = useTableCollection<Contact>({
+    queryName: 'OperatorFilterExample',
+    paginationMode: 'offset',
+    filters: {
+      name: nameFilter,
+    },
+    fetchData: async ({ limit, offset, search, filters }) => {
+      const nameFilters = filters.name
+        ? transformOperatorFilterToWQL('name', filters.name)
+        : [];
+
+      const searchFilter = search ? [{ name: { $startsWith: search } }] : [];
+
+      const allFilters = [...searchFilter, ...nameFilters];
+      const filter = allFilters.length ? { $and: allFilters } : undefined;
+
+      const response = (await httpClient.request(
+        searchContacts({
+          search: {
+            filter,
+            cursorPaging: { limit, offset },
+          },
+        }),
+      )) as { data: { contacts: Contact[]; pagingMetadata: { total: number } } };
+
+      return {
+        items: response?.data?.contacts || [],
+        total: response?.data?.pagingMetadata?.total,
+      };
+    },
+    itemKey: (item) => item.id,
+    itemName: (item) => item.name,
+    fetchErrorMessage: () => 'Error fetching contacts',
+  });
+
+  return (
+    <Box direction="horizontal" gap="SP4" height="500px">
+      <Box flexGrow={1}>
+        <CollectionPage height="500px">
+          <CollectionPage.Header title={{ text: 'Contacts' }} />
+          <CollectionPage.Content>
+            <Table
+              state={state}
+              columns={[
+                {
+                  id: 'avatar',
+                  title: '',
+                  width: '50px',
+                  render: (contact) => <Avatar name={contact.name} />,
+                },
+                {
+                  id: 'name',
+                  title: 'Name',
+                  width: '200px',
+                  render: (contact) => contact.name || '(empty)',
+                },
+                {
+                  id: 'level',
+                  title: 'Level',
+                  width: '150px',
+                  render: (contact) => contact.level,
+                },
+                {
+                  id: 'createdDate',
+                  title: 'Created',
+                  render: (contact) =>
+                    contact.createdDate
+                      ? new window.Date(contact.createdDate).toLocaleDateString()
+                      : '',
+                },
+              ]}
+            />
+          </CollectionPage.Content>
+        </CollectionPage>
+      </Box>
+      <Box width="350px" direction="vertical" gap="SP2">
+        <Heading size="small">Filter by Name</Heading>
+        <OperatorFilterPicker filter={nameFilter} />
+      </Box>
+    </Box>
+  );
+}
+
+export default operatorFilterWithTableExample;
+```
+
+## API
+
+### Props
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `itemKey` | `((item: OperatorFilterValue<T>) => string)` | No | - | Function to get the key of an item (for value dropdown) |
+| `itemName` | `((item: OperatorFilterValue<T>) => string)` | No | - | Function to get the display name of an item (for value dropdown) |
+| `equals` | `((item1: OperatorFilterValue<T>, item2: OperatorFilterValue<T>) => boolean)` | No | - | Function to check if two items are equal |
+| `encode` | `((value: OperatorFilterValue<T>) => unknown)` | No | - | Function to encode the value for serialization |
+| `decode` | `((value: unknown) => OperatorFilterValue<T>)` | No | - | Function to decode a value from serialization |
+| `matches` | `((item: OperatorFilterValue<T>, value: OperatorFilterValue<T>) => boolean)` | No | - | Function to check if an item matches the filter value |
+| `allowedOperators` | `FilterOperator[]` | Yes | - | List of allowed operators for this filter. The first operator will be used as the default. |
+| `operatorOrderOverride` | `boolean` | No | - | When `true`, keeps `allowedOperators` order as-is instead of reordering by `DEFAULT_OPERATOR_ORDER`. If the first operator doesn't require a value, falls back to default order. |
+| `persistent` | `boolean` | No | - | Marks the filter as a "context" or "scope" filter. This makes the filter not be visible in the sub-toolbar tag list, not saved in views, not counted as "X filters applied". |
+| `isCustomField` | `boolean` | No | - | If the filter is a custom field |
+

package/dist/docs/stringFilter.md

@@ -0,0 +1,204 @@
+# stringFilter
+
+**Category:** Features/Filter/Factories
+
+## Design
+
+### Usage
+
+This filter was primarily designed to be used in conjunction with the search functionality within the WixPatterns collection. It is not typically necessary to use this filter instead of the other available filters.
+
+**Do:**
+
+- Use it to override search property in useCollection API
+
+- Use it when you want to pass a single string value to query object
+
+
+**Don't:**
+
+- Use it in other use-cases unless suggested otherwise
+
+
+```tsx
+import { stringFilter } from '@wix/patterns';
+```
+
+### Set search input initial value
+
+```tsx
+import React from 'react';
+import { CollectionPage } from '@wix/patterns/page';
+import {
+  Table,
+  stringFilter,
+  useTableCollection,
+  OffsetQuery,
+} from '@wix/patterns';
+import { contacts } from '@wix/crm';
+
+function ContactsTable() {
+
+  const someInitialSearchParam = 'jo';
+
+  const state = useTableCollection<contacts.Contact>({
+    search: stringFilter({ initialValue: someInitialSearchParam }),
+    queryName: 'contacts-CairoTable',
+    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,
+      }));
+    },
+    itemName: (item) => `${item.info?.name?.first} ${item.info?.name?.last}`,
+    fetchErrorMessage: () => 'Error Fetching Contacts',
+  });
+
+  return (
+    <CollectionPage height="400px">
+      <CollectionPage.Header title={{ text: 'Contacts' }} />
+      <CollectionPage.Content>
+        <Table
+          state={state}
+          columns={[
+            {
+              title: 'Name',
+              width: '250px',
+              render: (contact) =>
+                `${contact.info?.name?.first} ${contact.info?.name?.last}`,
+            },
+            {
+              title: 'Level',
+              render: (contact) => contact.info?.jobTitle,
+            },
+          ]}
+        />
+      </CollectionPage.Content>
+    </CollectionPage>
+  );
+}
+```
+
+### Set internal filter with single string value
+
+This example shows how to use an internal single value as a filter when you have an external source change, such as when using a `BrowserRouter` or simple `setState`, and you need to refresh the collection. Examine the code to gain a better understanding of this example.
+
+```tsx
+import { Dropdown, FormField, Box } from '@wix/design-system';
+import React from 'react';
+import { CollectionPage } from '@wix/patterns/page';
+import {
+  Filter,
+  OffsetQuery,
+  Table,
+  stringFilter,
+  useTableCollection,
+} from '@wix/patterns';
+import { contacts } from '@wix/crm';
+
+type ContactsFilters = {
+  level: Filter<string>;
+};
+
+function ContactsTable() {
+
+  const state = useTableCollection<contacts.Contact, ContactsFilters>({
+    queryName: 'files-list',
+    fetchData: (query: OffsetQuery<ContactsFilters>) => {
+      const { limit, offset, search, sort, filters } = query;
+
+      let queryBuilder = contacts.queryContacts().limit(limit).skip(offset);
+
+      if (search) {
+        queryBuilder = queryBuilder.startsWith('info.name.first', search);
+      }
+
+      if (filters.level) {
+        queryBuilder = queryBuilder.in('info.jobTitle', [filters.level]);
+      }
+
+      return queryBuilder.find().then(({ items = [], totalCount: total }) => ({
+        items,
+        total,
+      }));
+    },
+    itemName: (item) => `${item.info?.name?.first} ${item.info?.name?.last}`,
+    fetchErrorMessage: () => 'Error Fetching Contacts',
+    filters: {
+      level: stringFilter(),
+    },
+  });
+
+  const collection = state.collection;
+
+  return (
+    <CollectionPage height="400px">
+      <CollectionPage.Header title={{ text: 'Contacts' }} />
+      <CollectionPage.Content>
+        <Box paddingBottom="SP3">
+          <FormField label="Level (As an external Input)">
+            <Dropdown
+              size="medium"
+              placeholder="Select level"
+              popoverProps={{ appendTo: 'window' }}
+              options={[
+                { id: 'Beginner', value: 'Beginner' },
+                { id: 'Amateur', value: 'Amateur' },
+                { id: 'Semi-Pro', value: 'Semi-Pro' },
+                { id: 'Professional', value: 'Professional' },
+                { id: 'World Class', value: 'World Class' },
+                { id: 'Legendary', value: 'Legendary' },
+                { id: 'Ultimate', value: 'Ultimate' },
+              ]}
+              onSelect={(e) => {
+                /*
+                  On level change, refresh the collection with new level value
+                */
+                collection.filters.level.refresh(e.id as string);
+              }}
+            />
+          </FormField>
+        </Box>
+        <Table
+          state={state}
+          columns={[
+            {
+              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(),
+            },
+          ]}
+        />
+      </CollectionPage.Content>
+    </CollectionPage>
+  );
+}
+```
+
+## API
+
+### Props
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `initialValue` | `string` | No | - | The value to initialize the filter with (Optional) |
+| `defaultValue` | `string` | No | - | The value to set the value to, when clearing the filter (Optional) |
+

package/dist/docs/stringsArrayFilter.md

@@ -0,0 +1,118 @@
+# stringsArrayFilter
+
+**Category:** Features/Filter/Factories
+
+## Design
+
+### Usage
+
+The filter is used to manage an array of strings. The string value can be a simple string that is displayed to the user, an enum value that is translated using `itemName` prop, or even an array of IDs that is not used with UI component but rather as an internal filter for querying data.
+
+**Do:**
+
+- Use it for plain strings
+
+- Use it for enum values
+
+- Use it for IDs
+
+
+**Don't:**
+
+- Use it for complex data, prefer using idNameArrayFilter instead
+
+
+```tsx
+import { stringsArrayFilter } from '@wix/patterns';
+```
+
+### Array of strings
+
+A simple array of strings with initial value.
+
+```tsx
+import React from 'react';
+import { stringsArrayFilter, SingleSelectFilter } from '@wix/patterns';
+import { Cell, Layout } from '@wix/design-system';
+
+function basicFilter() {
+  const [filter] = React.useState(() =>
+    stringsArrayFilter({ initialValue: ['Semi-Pro'] }),
+  );
+
+  return (
+    <Layout>
+      <Cell span={4}>
+        <SingleSelectFilter
+          filter={filter}
+          data={[
+            'Beginner',
+            'Amateur',
+            'Semi-Pro',
+            'Professional',
+            'World Class',
+            'Legendary',
+            'Ultimate',
+          ]}
+        />
+      </Cell>
+    </Layout>
+  );
+}
+```
+
+### Array of statuses
+
+The `itemName` prop is used to convert an enum value, which represents the status, into a user-friendly value, usually with a translation.
+
+```tsx
+import React from 'react';
+import { stringsArrayFilter, SingleSelectFilter } from '@wix/patterns';
+import { Cell, Layout } from '@wix/design-system';
+
+function statusFilter() {
+  const statusDisplayName = (status) => {
+    switch (status) {
+      case 'done':
+        return 'Done';
+      case 'in-progress':
+        return 'In Progress';
+      default:
+        return 'Failed';
+    }
+  };
+
+  const [filter] = React.useState(() =>
+    stringsArrayFilter({ itemName: statusDisplayName }),
+  );
+
+  return (
+    <Layout>
+      <Cell span={4}>
+        <SingleSelectFilter
+          filter={filter}
+          data={['done', 'in-progress', 'failed']}
+        />
+      </Cell>
+    </Layout>
+  );
+}
+```
+
+## API
+
+### Props
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `defaultValue` | `T[]` | No | - | The value to set the value to, when clearing the filter (Optional) |
+| `parse` | `(value: string \| Record<string, unknown> \| null \| undefined) => T \| null` | Yes | - | Convert a unknown object to a T.<br> If the function returns null, the item will be skipped when we try to deserializate it from an array. @param value |
+| `simplify` | `((value: T) => Partial<T>)` | No | - | Return a simplified form of an item for serialization. @param value |
+| `matches` | `((item: T, value: T[]) => boolean)` | No | - | Indicates whether an item matches the current value of the filter |
+| `equals` | `((item1: T, item2: T) => boolean)` | No | - | A function which accepts 2 items and returns true if they are equal |
+| `persistent` | `boolean` | No | - | Marks the filter as a "context" or "scope" filter. This makes the filter not be visible in the sub-toolbar tag list, not saved in views, not counted as "X filters applied". |
+| `initialValue` | `T[]` | No | - | The value to initialize the filter with (Optional) |
+| `itemKey` | `(item: T) => string` | Yes | - | A callback function that accepts an item and returns a unique ID of it. typically `item.id`. |
+| `itemName` | `(item: T) => string` | Yes | - | A callback function that accepts an item and returns the item name which is used in many messages through cairo |
+| `isCustomField` | `boolean` | No | - | If the filter is a custom field |
+

package/dist/docs/useAmbassadorCollection.md

@@ -0,0 +1,45 @@
+# useAmbassadorCollection
+
+**Category:** Common/Hooks
+
+## API
+
+### Overview
+
+A React hook that initializes a collection state using an Ambassador SDK package.
+The ambassador package should implement the [`crud.ts` module](https://bo.wix.com/wix-docs/rnd/platformization-guidelines/api-design-patterns#platformization-guidelines_api-design-patterns_auto-crud-sdk-generation-experimental). This is a higher-level alternative to [`useCollection`](./?path=/story/common-hooks--usecollection) that auto-generates `fetchData`, `queryName`, and `itemKey` from the Ambassador SDK.
+
+```tsx
+import { useAmbassadorCollection } from '@wix/patterns';
+```
+
+### Example
+
+```tsx
+import { useAmbassadorCollection, Table } from '@wix/patterns';
+import { contacts } from '@wix/crm';
+
+const state = useAmbassadorCollection({
+  ambassador: contacts,
+  transformPlatformizedQuery: (query) => query,
+});
+
+return (
+   c.name },
+    ]}
+  />
+);
+```
+
+### Returns
+
+[CollectionState](./?path=/story/common-state--collectionstate)
+
+### Props
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `ambassador` | `Required<Pick<AutoCrudHttp<T>, "fqdn" \| "queryEntities">>` | Yes | - | CRUD subpackage of a metro Ambassador package. |
+| `transformPlatformizedQuery` | `TransformPlatformizedQuery` | No | - | A function to transform the cairo query to a PlatformizedQuery object (which will be used to fetch data from the server): - `platformizedQuery`: PlatformizedQuery - `wixPatternsQuery`: CursorQuery The function should return a PlatformizedQuery instance or a promise of PlatformizedQuery |
+| `queryName` | `string` | No | `ambassador.fqdn` | The query name used for cache purposes. This should be a unique value per API endpoint. |
+

package/dist/docs/useCollection.md

@@ -0,0 +1,61 @@
+# useCollection
+
+**Category:** Common/Hooks
+
+## API
+
+### Overview
+
+The base React hook for creating a [`CollectionState`](./?path=/story/common-state--collectionstate). All other collection hooks (`useTableCollection`, `useGridCollection`, etc.) build on top of `useCollection`.
+
+Use this hook directly when you need a collection state that is not tied to a specific component, or when building custom collection components.
+
+```tsx
+import { useCollection } from '@wix/patterns';
+```
+
+### Example
+
+```tsx
+import { useCollection } from '@wix/patterns';
+
+const collection = useCollection({
+  queryName: 'my-items',
+  fetchData: async (query) => {
+    const { items, total } = await api.list(query);
+    return { items, total };
+  },
+  itemKey: (item) => item.id,
+  limit: 50,
+  filters: { status: stringFilter() },
+});
+
+// collection.keyedItems, collection.total, collection.invalidate(), etc.
+```
+
+### Returns
+
+[CollectionState](./?path=/story/common-state--collectionstate)
+
+### 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. |
+

package/dist/docs/useCreateCollection.md

@@ -0,0 +1,32 @@
+# useCreateCollection
+
+**Category:** Common/Hooks
+
+## API
+
+### Overview
+
+React hook that that retuns a function that initializes a collection state. Similiar to [useCollection](./?path=/story/common-hooks--usecollection), but it returns a function that initializes a collection state instead of the collection state itself.
+
+### 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. |
+

package/dist/docs/useCreateNestedOptimisticActions.md

@@ -0,0 +1,21 @@
+# useCreateNestedOptimisticActions
+
+**Category:** Base Components/Collections/NestedTable
+
+## API
+
+### Overview
+
+A React hook that returns a function to create [OptimisticActions](./?path=/story/features-actions-updates--collectionoptimisticactions) instance for a nested table collection created in the `levels.createCollection` prop of [useNestedTable](./?path=/story/base-components-collections-nestedtable--usenestedtable).
+
+For additional information and how to use it, see [Node API usage example](./?path=/story/base-components-collections-nestedtable--nestedtable#Node_API_usage)
+
+
+### Props
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `collection` | `CollectionState<T, F>` | Yes | - | @required The collection that is created by [NestedTableLevel.createCollection](./?path=/story/base-components-collections-nestedtable--nestedtablelevel). |
+| `state` | `unknown` | Yes | - | The state object that passed to the [NestedTableLevel.createCollection](./?path=/story/base-components-collections-nestedtable--nestedtablelevel) - this must be passed here. |
+| `params` | `CollectionOptimisticActionsBaseParams<T, F>` | No | - | Additional [OptimisticActions](./?path=/story/features-actions-updates--useoptimisticactions) configuration. |
+