@wix/patterns 1.364.0 → 1.369.0

package/dist/docs/useEntity.md

@@ -0,0 +1,44 @@
+# useEntity
+
+**Category:** Base Components/Pages/Entity Page/Hooks/useEntity
+
+## API
+
+### Overview
+
+A React hook that subscribes to the entity from [`EntityPageState`](./?path=/story/base-components-pages-entity-page-state--entitypagestate) and returns it reactively. Use this when you need to access the entity outside of `Card.Content`, such as in the page header (title, subtitle, breadcrumbs, etc.).
+
+**Important:** During the first render the entity will be `undefined` while data is being fetched. Do not rely on the initial value — always handle the `undefined` case.
+
+```tsx
+import { useEntity } from '@wix/patterns';
+```
+
+### Signature
+
+```tsx
+const entity = useEntity(state);
+// entity: T | undefined
+```
+
+### Example
+
+```tsx
+function MyEntityPage({ state }) {
+  const entity = useEntity(state);
+
+  return (
+    
+      
+      
+        {/* Card.Content receives the entity automatically */}
+      
+    
+  );
+}
+```
+
+### Returns
+
+Returns [`EntityPageState`](./?path=/story/base-components-pages-entity-page-state--entitypagestate)`.entity` — the current entity value (`T | undefined`).
+

package/dist/docs/useEntityPage.md

@@ -0,0 +1,57 @@
+# useEntityPage
+
+**Category:** Base Components/Pages/Entity Page/Hooks/useEntityPage
+
+## API
+
+### Overview
+
+A React hook that creates the state for an [`EntityPage`](./?path=/story/base-components-pages-entity-page--entitypage). Configure entity fetching, save flow, form integration, toasts, and navigation. The returned [`EntityPageState`](./?path=/story/base-components-pages-entity-page-state--entitypagestate) is passed to ``.
+
+```tsx
+import { useEntityPage } from '@wix/patterns/page';
+```
+
+### Example
+
+```tsx
+import { useEntityPage, EntityPage } from '@wix/patterns/page';
+import { useForm } from 'react-hook-form';
+
+const form = useForm({ defaultValues: { name: '' } });
+
+const state = useEntityPage({
+  fetch: () => api.getItem(itemId).then((entity) => ({ entity })),
+  onSave: ({ submittedValues }) =>
+    api.updateItem(itemId, submittedValues).then((updatedEntity) => ({ updatedEntity })),
+  form,
+  container,
+  parentPath: '/my-collection',
+});
+
+return (
+  
+    
+    
+      ...
+    
+  
+);
+```
+
+### Returns
+
+[EntityPageState](./?path=/story/base-components-pages-entity-page-state--entitypagestate)
+
+### Props
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `fqdn` | `string` | No | - | Entity fqdn. |
+| `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. |
+| `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 |
+

package/dist/docs/useEntityPageContext.md

@@ -0,0 +1,28 @@
+# useEntityPageContext
+
+**Category:** Base Components/Pages/Entity Page/Hooks/useEntityPageContext
+
+## API
+
+### Overview
+
+A React hook that retrieves [`EntityPageState`](./?path=/story/base-components-pages-entity-page-state--entitypagestate) from React context. Use it in any child component rendered within [`EntityPage`](./?path=/story/base-components-pages-entity-page--entitypage) to access the page state without prop-drilling.
+
+```tsx
+import { useEntityPageContext } from '@wix/patterns/page';
+```
+
+### Example
+
+```tsx
+function MyCardContent() {
+  const state = useEntityPageContext();
+  // Access state.entity, state.form, etc.
+  return {state.entity?.name};
+}
+```
+
+### Returns
+
+[EntityPageState](./?path=/story/base-components-pages-entity-page-state--entitypagestate)
+

package/dist/docs/useFilterCollection.md

@@ -0,0 +1,163 @@
+# useFilterCollection
+
+**Category:** Features/Filter/Hooks
+
+## Design
+
+### Overview
+
+React hook that connects a filter to a collection state.
+
+This allows a visitor to select items from a server and filter the filter collection by those items.
+
+### Examples
+
+### Basic
+
+```tsx
+import { Avatar } from '@wix/design-system';
+import React from 'react';
+import { CollectionPage } from '@wix/patterns/page';
+import {
+  CollectionToolbarFilters,
+  Filter,
+  idNameArrayFilter,
+  Table,
+  MultiSelectCheckboxFilter,
+  useTableCollection,
+  useFilterCollection,
+  OffsetQuery,
+} from '@wix/patterns';
+import { contacts } from '@wix/crm';
+
+interface Contact {
+  id: string;
+  name: string;
+}
+
+type ContactsFilters = {
+  contacts: Filter<Contact[]>;
+};
+
+function ContactsFilterCollection() {
+
+  const state = useTableCollection<contacts.Contact, ContactsFilters>({
+    queryName: 'contacts-ContactsFilterCollection',
+    itemName: (item) => `${item.info?.name?.first} ${item.info?.name?.last}`,
+    fetchData: (query: OffsetQuery<ContactsFilters>) => {
+      const { limit, offset, search, filters } = query;
+
+      let queryBuilder = contacts.queryContacts().limit(limit).skip(offset);
+
+      if (search) {
+        queryBuilder = queryBuilder.startsWith('info.name.first', search);
+      }
+
+      if (filters.contacts) {
+        queryBuilder = queryBuilder.in(
+          '_id',
+          filters.contacts.map(({ id }) => id),
+        );
+      }
+
+      return queryBuilder.find().then(({ items = [], totalCount: total }) => ({
+        items,
+        total,
+      }));
+    },
+    fetchErrorMessage: () => 'Error fetching contacts',
+    filters: {
+      contacts: idNameArrayFilter(),
+    },
+  });
+
+  const collection = state.collection;
+
+  const contactsCollection = useFilterCollection<Contact>(
+    collection.filters.contacts,
+    {
+      queryName: 'contacts',
+      paginationMode: 'offset',
+      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: items.map((item) => ({
+              id: item._id!,
+              name: `${item.info?.name?.first} ${item.info?.name?.last}`,
+            })),
+            total,
+          }));
+      },
+      limit: 50,
+      filters: {},
+    },
+  );
+
+  return (
+    <CollectionPage height="400px">
+      <CollectionPage.Header title={{ text: 'Contacts' }} />
+      <CollectionPage.Content>
+        <Table
+          state={state}
+          columns={[
+            {
+              title: '',
+              width: '48px',
+              render: (contact) => (
+                <Avatar
+                  name={`${contact.info?.name?.first} ${contact.info?.name?.last}`}
+                  imgProps={{ src: contact.info?.picture?.image }}
+                />
+              ),
+            },
+            {
+              title: 'Name',
+              render: (contact) =>
+                `${contact.info?.name?.first} ${contact.info?.name?.last}`,
+            },
+          ]}
+          filters={
+            <CollectionToolbarFilters inline={1}>
+              <MultiSelectCheckboxFilter
+                toolbarItemProps={{
+                  label: 'Filter by',
+                }}
+                filter={collection.filters.contacts}
+                collection={contactsCollection}
+              />
+            </CollectionToolbarFilters>
+          }
+        />
+      </CollectionPage.Content>
+    </CollectionPage>
+  );
+}
+```
+
+## API
+
+### 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. |
+

package/dist/docs/useGridCollection.md

@@ -0,0 +1,58 @@
+# useGridCollection
+
+**Category:** Base Components/Collections/Grid/useGridCollection
+
+## API
+
+### Description
+
+`useGridCollection` is a React hook designed to facilitate the management of the [`Grid`](./?path=/story/base-components-collections-grid-grid--grid) component.It returns a [`GridState`](./?path=/story/base-components-collections-grid-gridstate--gridstate) to pass to the `state` prop of the `Grid` component.
+
+```tsx
+import { useGridCollection } from '@wix/patterns';
+```
+
+### Example
+
+```jsx
+import { useGridCollection, Grid } from '@wix/patterns';
+import { contacts } from '@wix/crm';
+
+const state = useGridCollection(/* Your collection parameters */);
+
+return (
+   contact.name,
+      }
+    ]}
+    /* Additional Grid props */
+  />
+);
+```
+
+
+### Returns
+
+[GridState](./?path=/story/base-components-collections-grid-gridstate--gridstate)
+
+### 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/useGridFolders.md

@@ -0,0 +1,25 @@
+# useGridFolders
+
+**Category:** Base Components/Collections/GridFolders/useGridFolders
+
+## API
+
+### Description
+
+`useGridFolders` is a React hook designed to facilitate the management of the [`GridFolders`](./?path=/story/base-components-collections-gridfolders-gridfolders--gridfolders) component.It returns a [`GridFoldersState`](./?path=/story/base-components-collections-gridfolders-gridfoldersstate--gridfoldersstate) to pass to the `state` prop of the `GridFolders` component.
+
+```tsx
+import { useGridFolders } from '@wix/patterns';
+```
+
+### Returns
+
+[GridFoldersState](./?path=/story/base-components-collections-gridfolders-gridfoldersstate--gridfoldersstate)
+
+### 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 |
+

package/dist/docs/useItemsSelectionFilter.md

@@ -0,0 +1,60 @@
+# useItemsSelectionFilter
+
+**Category:** Common/hooks
+
+## Design
+
+### Description
+
+The `useItemsSelectionFilter` hook creates a filter that fetches and displays items from a specific provider.
+
+For more information, see [Items Selection](https://bo.wix.com/pages/items-selection/).
+
+
+```tsx
+import { useItemsSelectionFilter } from '@wix/patterns';
+```
+
+### Basic filter with Items Selection
+
+Call `useItemsSelectionFilter` with a `providerKey` and a filter object. The hook returns a `collection` and `renderItem` that you pass to a filter component, such as `MultiSelectCheckboxFilter`.
+
+```tsx
+import React from 'react';
+import {
+  idNameArrayFilter,
+  ItemsSelectionValue,
+  MultiSelectCheckboxFilter,
+  useItemsSelectionFilter,
+} from '@wix/patterns';
+
+function ItemsSelectionFilterExample() {
+  const [filter] = React.useState(() =>
+    idNameArrayFilter<ItemsSelectionValue>(),
+  );
+
+  const { collection, renderItem } = useItemsSelectionFilter({
+    providerKey: 'your-provider-key',
+    filter,
+  });
+
+  return (
+    <MultiSelectCheckboxFilter
+      filter={filter}
+      collection={collection}
+      renderItem={renderItem}
+    />
+  );
+}
+```
+
+## API
+
+### Props
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `providerKey` | `string` | Yes | - | The provider key to use for fetching items. |
+| `filter` | `Filter<ItemsSelectionValue[]>` | Yes | - | This is a reference to the filter that was defined in the main collection. For example: `collection.filters.<filterName>`. |
+| `queryFilters` | `Record<string, any> \| null` | No | - | Additional filters to apply to the query. |
+

package/dist/docs/useNestedTable.md

@@ -0,0 +1,66 @@
+# useNestedTable
+
+**Category:** Base Components/Collections/NestedTable
+
+## API
+
+### Description
+
+`useNestedTable` is a React hook that creates the state for a [`NestedTable`](./?path=/story/base-components-collections-nestedtable--nestedtable) component — a table that displays hierarchical data with expand/collapse, flat and nested view modes, and multi-level optimistic actions.
+
+You define the hierarchy through `levels`, where each level describes how to fetch its items, how they relate to their parent, and how to render columns. The hook returns a [`NestedTableState`](./?path=/story/base-components-collections-nestedtable--nestedtablestate) to pass to ``.
+
+```tsx
+import { useNestedTable } from '@wix/patterns';
+```
+
+### Example
+
+```tsx
+import { useNestedTable, NestedTable, createNestedTableLevel } from '@wix/patterns';
+
+const columns = [
+  { id: 'name', title: 'Name' },
+  { id: 'status', title: 'Status' },
+];
+
+const state = useNestedTable({
+  columns,
+  mainColumn: { title: 'Name' },
+  levels: [
+    createNestedTableLevel({
+      parentKey: (item) => item.parentId,
+      createCollection: () => ({
+        collection: useCollection({
+          queryName: 'my-nested-items',
+          fetchData: (query) => fetchItems(query),
+          itemKey: (item) => item.id,
+        }),
+      }),
+      renderMainColumn: (item) => ({ title: item.name }),
+      columns: {
+        name: (item) => item.name,
+        status: (item) => item.status,
+      },
+    }),
+  ],
+});
+
+return ;
+```
+
+### Returns
+
+[NestedTableState](./?path=/story/base-components-collections-nestedtable--nestedtablestate)
+
+### Props
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `fetchAllLimit` | `number` | No | `1000` | If the total items in the server are less or equal to this threshold, all items will be fetched and rendered at once, in expanded state (referred to as "Eager" mode). |
+| `fetchAllThreshold` | `number` | No | - | @deprecated Use `fetchAllLimit` instead. |
+| `expandAllThreshold` | `number` | No | ``fetchAllThreshold`` | In "Eager" mode, items will be in expanded state. This threshold allows to use collapsed state if the total items in the server are greater than this threshold. |
+| `columns` | `NestedTableColumn<C>[]` | Yes | - | Columns to be rendered in the nested table. Same as [TableColumn](./?path=/story/common-types--tablecolumn) - just without rendering logic of cells (`render` prop will be defined for each level individually in the `levels` prop). |
+| `mainColumn` | `{ title?: string; width?: string \| number; } \| undefined` | No | - | Main column of the nested table. An object with the following properties: - `title`: The title of the column. @default '' - `width`: The width of the column. Can be a number (in pixels) or a string (percentage). @default '326px' |
+| `levels` | `Omit<NestedTableLevelDescriptor<C, any, any>, "depth">[]` | Yes | - | Configuration of the nested table levels. Use one of the helper function to create the levels configuration: - [createNestedTableLevel](./?path=/story/base-components-collections-nestedtable--createnestedtablelevel) - for cases where each level if of a different entity type. - [createNestedTableSingleEntityLevels](./?path=/story/base-components-collections-nestedtable--createnestedtablesingleentitylevels) - for cases where all levels are of the same entity type. |
+