@wix/patterns 1.366.0 → 1.370.0

package/dist/docs/AutoCompleteFilter.md

@@ -0,0 +1,276 @@
+# AutoCompleteFilter
+
+**Category:** Features/Filter/Components
+
+## Design
+
+```tsx
+import { AutoCompleteFilter } from '@wix/patterns';
+```
+
+---
+
+### Examples
+
+### Basic
+
+```tsx
+import React from 'react';
+import {
+  AutoCompleteFilter,
+  idNameArrayFilter,
+  useFilterCollection,
+} from '@wix/patterns';
+import { Observer } from 'mobx-react-lite';
+
+function BasicAutoCompleteFilter() {
+  const fakeEntityHttpClient = useFakeEntityHttpClient();
+
+  const [filter] = React.useState(() => idNameArrayFilter());
+
+  const collection = useFilterCollection(filter, {
+    queryName: 'BasicAutoCompleteFilter',
+    fetchData: (query) => {
+      const { limit, offset, search, filters } = query;
+      return fakeEntityHttpClient
+        .request({
+          url: '/api/fake-entity',
+          params: { limit, offset, search, filters },
+        })
+        .then(({ data: { items, total } }) => ({ items, total }));
+    },
+    limit: 50,
+    filters: {},
+  });
+
+  return (
+    <Layout>
+      <Cell span={4}>
+        <AutoCompleteFilter
+          filter={filter}
+          collection={collection}
+          popoverProps={{ appendTo: 'window' }}
+        />
+      </Cell>
+
+      <Cell span={4}>
+        <Observer>
+          {() => <pre>{JSON.stringify(filter.value, null, 2)}</pre>}
+        </Observer>
+      </Cell>
+    </Layout>
+  );
+}
+```
+
+---
+
+### With sections
+
+```tsx
+import React from 'react';
+import {
+  AutoCompleteFilter,
+  idNameArrayFilter,
+  useFilterCollection,
+} from '@wix/patterns';
+
+function BasicAutoCompleteFilter() {
+  const fakeEntityHttpClient = useFakeEntityHttpClient();
+
+  const [filter] = React.useState(() => idNameArrayFilter());
+
+  const collection = useFilterCollection(filter, {
+    queryName: 'BasicAutoCompleteFilter',
+    fetchData: (query) => {
+      const { limit, offset, search, filters } = query;
+      return fakeEntityHttpClient
+        .request({
+          url: '/api/fake-entity',
+          params: { limit, offset, search, filters },
+        })
+        .then(({ data: { items, total } }) => ({ items, total }));
+    },
+    limit: 50,
+    filters: {},
+  });
+
+  return (
+    <Layout>
+      <Cell span={4}>
+        <AutoCompleteFilter
+          filter={filter}
+          collection={collection}
+          popoverProps={{ appendTo: 'window' }}
+          renderSection={(sectionId) => {
+            return {
+              id: sectionId,
+              title: sectionId,
+            };
+          }}
+          renderItem={(item) => {
+            const numberInName = parseInt(item.name.trim().split(' ')[0], 10);
+            return {
+              id: item.id,
+              title: item.name,
+              sectionId: `User's generation #${Math.floor(numberInName / 10)}`,
+            };
+          }}
+        />
+      </Cell>
+    </Layout>
+  );
+}
+```
+
+---
+
+### Items selection Filter
+
+```tsx
+import React from 'react';
+import {
+  AutoCompleteFilter,
+  idNameArrayFilter,
+  ItemsSelectionValue,
+  useItemsSelectionFilter,
+} from '@wix/patterns';
+import { Cell, Layout } from '@wix/design-system';
+
+function ItemsSelectionFilterExample() {
+  const [filter] = React.useState(() =>
+    idNameArrayFilter<ItemsSelectionValue>(),
+  );
+
+  const { collection, renderItem } = useItemsSelectionFilter({
+    providerKey: 'your-provider-key',
+    filter,
+  });
+
+  return (
+    <Layout>
+      <Cell span={4}>
+        <AutoCompleteFilter
+          filter={filter}
+          collection={collection}
+          renderItem={renderItem}
+        />
+      </Cell>
+    </Layout>
+  );
+}
+```
+
+## API
+
+### Extends
+
+[AutoCompleteProps](https://www.docs.wixdesignsystem.com/?path=/story/components-form--autocomplete)
+
+### Props
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `size` | `"small" \| "tiny" \| "medium" \| "large"` | No | - | Controls the size of the input. Default value: `medium` |
+| `dataHook` | `string` | No | - | Applies a data-hook HTML attribute that can be used in the tests |
+| `className` | `string` | No | - | Specifies a CSS class name to be appended to the component's root element. |
+| `dropDirectionUp` | `boolean` | No | - | @deprecated |
+| `focusOnSelectedOption` | `boolean` | No | - | Scroll view to the selected option on opening the dropdown |
+| `onClose` | `(() => void)` | No | - | Callback function called whenever the user press the `Escape` keyboard. |
+| `onOptionMarked` | `((option: DropdownLayoutValueOption \| null, optionElementId?: string) => void)` | No | - | Callback function called whenever an option becomes focused (hovered/active). Receives the relevant option object from the original props.options array. |
+| `onOptionsNavigate` | `((option: DropdownLayoutValueOption \| null) => void)` | No | - | Callback function called whenever the user navigates to an option (via keyboard or mouse). Receives the relevant option object from the original props.options array, or null when navigation is cleared. |
+| `visible` | `boolean` | No | - | Should show or hide the component |
+| `selectedId` | `string \| number` | No | - | The id of the selected option in the list |
+| `tabIndex` | `number` | No | - | Indicates that element can be focused and where it participates in sequential keyboard navigation |
+| `onClickOutside` | `((e: TouchEvent \| MouseEvent) => void)` | No | - | @deprecated Do not use this prop. |
+| `fixedHeader` | `ReactNode` | No | - | A fixed header to the list |
+| `fixedFooter` | `ReactNode` | No | - | A fixed footer to the list |
+| `maxHeightPixels` | `string \| number` | No | - | Set the max height of the dropdownLayout in pixels |
+| `minWidthPixels` | `string \| number` | No | - | Set the min width of the dropdownLayout in pixels |
+| `withArrow` | `boolean` | No | - | @deprecated Do not use this prop. |
+| `closeOnSelect` | `boolean` | No | - | Closes DropdownLayout on option selection |
+| `onMouseEnter` | `MouseEventHandler<HTMLElement>` | No | - | Callback function called whenever the user entered with the mouse to the dropdown layout. |
+| `onMouseLeave` | `MouseEventHandler<HTMLElement>` | No | - | Callback function called whenever the user exited with the mouse from the dropdown layout. |
+| `onMouseDown` | `MouseEventHandler<HTMLElement>` | No | - | Callback function called whenever the user clicks the dropdown layout. |
+| `itemHeight` | `"big" \| "small"` | No | - | @deprecated Do not use this prop. |
+| `selectedHighlight` | `boolean` | No | - | Whether the selected option will be highlighted when dropdown reopened. |
+| `inContainer` | `boolean` | No | - | Whether the `<DropdownLayout/>` is in a container component. If `true`, some styles such as shadows, positioning and padding will be added the the component contentContainer. |
+| `infiniteScroll` | `boolean` | No | - | Set this prop for lazy loading of the dropdown layout items. |
+| `loadMore` | `((page: number) => void)` | No | - | A callback called when more items are requested to be rendered. |
+| `hasMore` | `boolean` | No | - | Whether there are more items to be loaded. |
+| `markedOption` | `string \| number \| boolean` | No | - | Sets the default hover behavior when: 1. `false` means no default 2. `true` means to hover the first selectable option 3. Any number/string represents the id of option to hover |
+| `overflow` | `"visible" \| "hidden" \| "scroll" \| "auto"` | No | - | Set overflow of container |
+| `focusOnOption` | `string \| number` | No | - | Marks (not selects) and scrolls view to the option on opening the dropdown by option id |
+| `scrollToOption` | `string \| number` | No | - | Scrolls to the specified option when dropdown is opened without marking it |
+| `listType` | `"action" \| "select"` | No | - | Defines type of behavior applied in list |
+| `autoFocus` | `boolean` | No | - | Focus the element on mount (standard React input autoFocus) |
+| `scrollbar` | `"fixed" \| "overlay"` | No | - | Controls which type of scrollbar to render |
+| `listboxId` | `string` | No | - | Defines the id for the listbox |
+| `autocomplete` | `string` | No | - | Sets the value of native autocomplete attribute (check the [HTML spec](https://html.spec.whatwg.org/multipage/form-control-infrastructure.html#attr-fe-autocomplete) for possible values |
+| `id` | `string` | No | - | Assigns a unique identifier for the root element |
+| `role` | `string` | No | - | Specifies the role of the input element for accessibility |
+| `ariaControls` | `string` | No | - | Associate a control with the regions that it controls |
+| `ariaDescribedby` | `string` | No | - | Associate a region with its descriptions. Similar to aria-controls but instead associating descriptions to the region and description identifiers are separated with a space. |
+| `ariaLabel` | `string` | No | - | Define a string that labels the current element in case where a text label is not visible on the screen |
+| `autoSelect` | `boolean` | No | - | Automatically selects the entire input text |
+| `defaultValue` | `InputValue` | No | - | Defines the initial value of an input |
+| `disabled` | `boolean` | No | - | Specifies whether input should be disabled or not |
+| `status` | `"error" \| "warning" \| "loading"` | No | - | Specify the status of a field |
+| `statusMessage` | `ReactNode` | No | - | Defines the message to display on status icon hover. If not given or empty there will be no tooltip. |
+| `statusMessageTooltipProps` | `TooltipCommonProps` | No | - | Status message tooltip props |
+| `hideStatusSuffix` | `boolean` | No | - | Specifies whether status suffix should be hidden |
+| `forceFocus` | `boolean` | No | - | USED FOR TESTING - forces focus state on the input |
+| `forceHover` | `boolean` | No | - | USED FOR TESTING - forces hover state on the input |
+| `maxLength` | `number` | No | - | Sets the maximum number of characters that can be inserted to a field |
+| `menuArrow` | `boolean` | No | - | Specifies whether input should have a dropdown menu arrow on the right side |
+| `clearButton` | `boolean` | No | - | Displays clear button (X) on a non-empty input |
+| `focusOnClearClick` | `boolean` | No | - | Specifies whether to focus the field when clear button is clicked |
+| `name` | `string` | No | - | Reference element data when a form is submitted |
+| `border` | `"standard" \| "round" \| "bottomLine" \| "none"` | No | - | Control the border style of input |
+| `noLeftBorderRadius` | `boolean` | No | - | Specifies whether input shouldn't have rounded corners on its left |
+| `noRightBorderRadius` | `boolean` | No | - | Specifies whether input shouldn't have rounded corners on its right |
+| `onBlur` | `FocusEventHandler<HTMLInputElement>` | No | - | Defines a standard input onBlur callback |
+| `onChange` | `ChangeEventHandler<HTMLInputElement>` | No | - | Defines a standard input onChange callback |
+| `onClear` | `((event: MouseEvent<HTMLButtonElement, MouseEvent> \| KeyboardEvent<HTMLButtonElement>) => void)` | No | - | Displays clear button (X) on a non-empty input and calls a callback function |
+| `onCompositionChange` | `((isComposing: boolean) => void)` | No | - | Defines a callback function called on compositionstart/compositionend events |
+| `onEnterPressed` | `KeyboardEventHandler<HTMLInputElement>` | No | - | Defines a callback handler that is called when the user presses -enter- |
+| `onEscapePressed` | `KeyboardEventHandler<HTMLInputElement>` | No | - | Defines a callback handler that is called when the user presses -escape- |
+| `onFocus` | `FocusEventHandler<HTMLInputElement>` | No | - | Defines a standard input onFocus callback |
+| `onInputClicked` | `MouseEventHandler<HTMLInputElement \| HTMLDivElement>` | No | - | Defines a standard input onClick callback |
+| `onKeyDown` | `KeyboardEventHandler<HTMLInputElement>` | No | - | Defines a standard input onKeyDown callback |
+| `onKeyUp` | `KeyboardEventHandler<HTMLInputElement>` | No | - | Defines a standard input onKeyUp callback |
+| `onPaste` | `ClipboardEventHandler<HTMLInputElement>` | No | - | Defines a callback handler that is called when user pastes text from a clipboard (using a mouse or keyboard shortcut) |
+| `onCopy` | `ClipboardEventHandler<HTMLInputElement>` | No | - | Defines a callback handler that is called when user copies text to a clipboard (using a mouse or keyboard shortcut) |
+| `placeholder` | `string` | No | - | Sets a placeholder message to display |
+| `prefix` | `ReactNode` | No | - | Pass a component you want to show as the prefix of the input, e.g., text, icon |
+| `readOnly` | `boolean` | No | - | Specifies whether input is read only |
+| `disableEditing` | `boolean` | No | - | Restricts input editing |
+| `suffix` | `ReactNode` | No | - | Pass a component you want to show as the suffix of the input, e.g., text, icon |
+| `textOverflow` | `"clip" \| "ellipsis"` | No | - | Handles text overflow behavior. It can either `clip` (default) or display `ellipsis`. |
+| `tooltipPlacement` | `"auto" \| "auto-start" \| "auto-end" \| "top-start" \| "top" \| "top-end" \| "right-start" \| "right" \| "right-end" \| "bottom-end" \| "bottom" \| "bottom-start" \| "left-end" \| "left" \| "left-start"` | No | - | Controls placement of a status tooltip @deprecated use tooltipProps instead |
+| `type` | `string` | No | - | Specifies the type of `<input/>` element to display. Default is text. |
+| `value` | `string \| number` | No | - | Specifies the current value of the element |
+| `required` | `boolean` | No | - | Specifies whether input is mandatory |
+| `min` | `MinValue` | No | - | Sets a minimum value of an input. Similar to HTML5 min attribute. |
+| `max` | `MaxValue` | No | - | Sets a maximum value of an input. Similar to html5 max attribute. |
+| `step` | `number` | No | - | Specifies the interval between number values |
+| `customInput` | `Function \| ReactNode` | No | - | Render a custom input instead of the default html input tag |
+| `pattern` | `string` | No | - | Sets a pattern that typed value must match to be valid (regex) |
+| `clearButtonTooltipContent` | `ReactNode` | No | - | When provided hover will display a tooltip with content |
+| `clearButtonTooltipProps` | `TooltipCommonProps` | No | - | Clear button tooltip props |
+| `clearButtonAriaLabel` | `string` | No | - | Aria label for the clear button |
+| `inputElementRef` | `any` | No | - | Specifies reference of the input element |
+| `filter` | `Filter<V[]>` | Yes | - | [ArrayFilter](./?path=/story/features-filter-factories--arrayfilter) state object |
+| `renderItem` | `((item: V, index: number) => ListItem)` | No | - | Function that returns a [ListItemSelectProps](https://www.docs.wixdesignsystem.com/?path=/story/components-form-dropdownlistitems--listitemselect) extended by `{section?: string}`. |
+| `renderSection` | `((sectionId: string) => ListItemSelectionBuilderParams)` | No | - | A function that returns [ListItemSectionProps](https://www.docs.wixdesignsystem.com/?path=/story/components-form-dropdownlistitems--listitemsection) <br/> According to make it works you need return `sectionId` in `renderItem` method. <br/> ⚠️ Server should return section items sorted by sections in strict order. Otherwise, when using infinite scrolling the behavior of the sections will be unexpected. <br/> (Optional) |
+| `collection` | `CollectionState<V, F>` | Yes | - | A collection state object to fetch the dropdown items.<br> Typically, a collection created using [useFilterCollection](./?path=/story/features-filter-hooks--usefiltercollection) hook. |
+| `fieldType` | `"SHORT_TEXT" \| "LONG_TEXT" \| "NUMBER" \| "BOOLEAN" \| "DATE" \| "DATE_TIME" \| "DATETIME" \| "TIME" \| "URL" \| "EMAIL" \| "IMAGE" \| "MEDIA_GALLERY" \| "AUDIO" \| "DOCUMENT" \| "MULTI_DOCUMENT" \| "RICH_TEXT" \| "RICH_CONTENT" \| "REFERENCE" \| "MULTI_REFERENCE" \| "OBJECT" \| "ARRAY" \| "ADDRESS" \| "COLOR" \| "INTEGER" \| "DECIMAL" \| "CHECKBOX" \| "DROPDOWN" \| "FILES" \| "MULTI_SELECT"` | No | - | The field type string used to resolve a prefix icon for the filter. Cairo maps this to the appropriate icon internally. |
+| `layout` | `"button"` | No | - | Padding settings. If this prop it omitted, padding will exist on the sides of the filter.<br> <br> Supported values: <br> - `"button"`: Removes padding from the sides of the filter. |
+| `toolbarItemProps` | `{ label?: ReactNode; }` | No | - | Customizes the filter in the toolbar.<br> <br> Supported properties: <br> - `label`: [string] Prefix for the filter element. |
+| `toolbarTagProps` | `{ label?: string; }` | No | - | Customizes the filter tag in the toolbar.<br> <br> Supported properties: <br> - `label`: [string] Overrides the default filter name when filtered tag is shown. |
+| `initiallyOpen` | `boolean` | No | - | Indicates whether the filter should be visible by default in the filters panel |
+| `accordionItemProps` | `(AccordionItemType & { label?: string; })` | No | - | Customizes the filter [accordion](https://www.docs.wixdesignsystem.com/?path=/story/components-lists--accordion).<br> <br> Supported properties: <br> - `label`: [string] Accordion item title. You can also use `AccordionProps['items'][number].title` for more flexibility. <br> - Extends [AccordionProps['items'[number]](https://www.docs.wixdesignsystem.com/?path=/story/components-lists--accordion). |
+| `onAppliedFilterTagRemove` | `((item: V) => unknown)` | No | - | Callback that's run when a filter is removed by a visitor from the sub-toolbar. @param item |
+| `renderToolbarTag` | `((item: V) => Partial<Omit<TagProps, "size" \| "onRemove">>)` | No | - | Customizes how the tag list in the sub-toolbar is rendered. <br><br> Extends [`TagListProps['tags'][number]`](https://www.docs.wixdesignsystem.com/?path=/story/components-lists-table--taglist). |
+| `sectionTitle` | `string` | No | - | Title for the section in the accordion. |
+

package/dist/docs/BulkActionModalRenderProp.md

@@ -0,0 +1,22 @@
+# BulkActionModalRenderProp
+
+**Category:** Common/Types
+
+## API
+
+### Overview
+
+A render-prop type for the `bulkActionModal` prop on collection components (`Table`, `Grid`, etc.). The render function receives selection state (`selectedValues`, `uncheckedValues`, `allSelected`), a `query` object, and modal controls (`openModal`, `closeModal`). Return a React element for the modal content.
+
+### Props
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `openModal` | `() => void` | Yes | - | Opens the modal . |
+| `closeModal` | `() => void` | Yes | - | Closes the modal. |
+| `isModalOpen` | `boolean` | Yes | - | return true if the modal is open |
+| `allSelected` | `boolean` | Yes | - | return boolean value Whether the Select All option is selected. |
+| `selectedValues` | `T[]` | Yes | - | Selected item values. |
+| `uncheckedValues` | `T[]` | Yes | - | Unselected item values. |
+| `query` | `ComputedQueryFull<F>` | Yes | - | Instance of [ComputedQuery](./?path=/story/common-types--computedquery) that represents the query that resulted in an empty state. Representation of the current paging, sorting and filtering applied. Usually for using together with bulk action such as `updateAll` and `deleteAll`. |
+

package/dist/docs/BulkSelectState.md

@@ -0,0 +1,18 @@
+# BulkSelectState
+
+**Category:** Common/State
+
+## API
+
+### Overview
+
+`BulkSelectState` manages the selection state for bulk actions in collection components. It tracks which items are selected, supports "Select All", and provides `allSelected`, `selectedValues`, and `uncheckedValues` properties. Created internally by [`CollectionState`](./?path=/story/common-state--collectionstate) — you typically access it via `state.collection.bulkSelect`.
+
+### Props
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `selectedValues` | `T[]` | Yes | - | The items that were checked via the selection column |
+| `uncheckedValues` | `T[]` | Yes | - | The items that were unchecked via the selection column |
+| `allSelected` | `boolean` | Yes | - | Indicates whether the "Select All" checkbox is checked |
+

package/dist/docs/Category.md

@@ -0,0 +1,19 @@
+# Category
+
+**Category:** Common/Types
+
+## API
+
+### Overview
+
+Defines a category in the [`Views`](./?path=/story/features-display-views--views) dropdown. A category groups related views and appears as a section header. Each category has a unique `id`, a display `name`, and an array of [`View`](./?path=/story/common-types--view) objects.
+
+### Props
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `id` | `string` | Yes | - | Unique identifier. |
+| `views` | `View<F>[]` | Yes | - | Array of [view objects](./?path=%2Fstory%2Fcommon-types--view) that appear under the category in the dropdown. |
+| `name` | `string` | Yes | - | What the category is called in the dropdown. |
+| `info` | `InfoIconProps` | No | - | @deprecated Info icon is now automatically rendered by Cairo for all categories. [InfoIconProps](https://www.docs.wixdesignsystem.com/?path=/story/components-form--infoicon) |
+

package/dist/docs/CollectionEmptyState.md

@@ -0,0 +1,240 @@
+# CollectionEmptyState
+
+**Category:** Features/Display/Empty States
+
+## Design
+
+### Description
+
+Displays an empty state for a table when no items exist in the collection. Pass through the `emptyState` prop of a [`Grid`](./?path=/story/base-components-collections-grid-grid--grid), [`Table`](./?path=/story/base-components-collections-table-table--table), or other collection component.
+
+
+```tsx
+import { CollectionEmptyState } from '@wix/patterns';
+```
+
+### Demo
+
+```tsx
+import { Avatar } from '@wix/design-system';
+import React from 'react';
+import { CollectionPage } from '@wix/patterns/page';
+import {
+  CollectionEmptyState,
+  TableGridSwitch,
+  useTableGridSwitchCollection,
+} from '@wix/patterns';
+import { contacts } from '@wix/crm';
+
+function EmptyStateDemo() {
+  const state = useTableGridSwitchCollection<contacts.Contact>({
+    queryName: 'contacts-EmptyStateDemo',
+    paginationMode: 'offset',
+    fetchData: () =>
+      Promise.resolve({
+        items: [],
+        total: 0,
+      }),
+    itemName: (item) => `${item.info?.name?.first} ${item.info?.name?.last}`,
+    fetchErrorMessage: () => 'Error fetching contacts',
+    filters: {},
+  });
+
+  return (
+    <CollectionPage height="500px">
+      <CollectionPage.Header title={{ text: 'Contacts' }} />
+      <CollectionPage.Content>
+        <TableGridSwitch
+          state={state}
+          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: 'Last Activity',
+              render: (contact) =>
+                contact.lastActivity?.activityDate?.toLocaleString(),
+            },
+          ]}
+          emptyState={
+            <CollectionEmptyState addNewCta={{ onClick: () => {} }} />
+          }
+        />
+      </CollectionPage.Content>
+    </CollectionPage>
+  );
+}
+```
+
+### 2 CTAs
+
+Use the `customCta` prop to add an extra call to action beside the default **+ Add Item** button.
+
+```tsx
+import { Avatar, TextButton } from '@wix/design-system';
+import React from 'react';
+import { CollectionPage } from '@wix/patterns/page';
+import {
+  CollectionEmptyState,
+  TableGridSwitch,
+  useTableGridSwitchCollection,
+} from '@wix/patterns';
+import { More } from '@wix/wix-ui-icons-common';
+import { contacts } from '@wix/crm';
+
+function EmptyState2CTAs() {
+  const state = useTableGridSwitchCollection<contacts.Contact>({
+    queryName: 'contacts-EmptyState2CTAs',
+    paginationMode: 'offset',
+    fetchData: () =>
+      Promise.resolve({
+        items: [],
+        total: 0,
+      }),
+    itemName: (item) => `${item.info?.name?.first} ${item.info?.name?.last}`,
+    fetchErrorMessage: () => 'Error fetching contacts',
+    filters: {},
+  });
+
+  return (
+    <CollectionPage height="500px">
+      <CollectionPage.Header title={{ text: 'Contacts' }} />
+      <CollectionPage.Content>
+        <TableGridSwitch
+          state={state}
+          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: 'Last Activity',
+              render: (contact) =>
+                contact.lastActivity?.activityDate?.toLocaleString(),
+            },
+          ]}
+          emptyState={
+            <CollectionEmptyState
+              addNewCta={{ onClick: () => {} }}
+              customCta={
+                <TextButton prefixIcon={<More />}>More Actions</TextButton>
+              }
+            />
+          }
+        />
+      </CollectionPage.Content>
+    </CollectionPage>
+  );
+}
+```
+
+### Passive Empty State
+
+Exclude the `addNewCta` prop to display an empty state without options for user interaction.
+
+```tsx
+import { Avatar, Text, TextButton } from '@wix/design-system';
+import React from 'react';
+import { CollectionPage } from '@wix/patterns/page';
+import {
+  CollectionEmptyState,
+  TableGridSwitch,
+  useTableGridSwitchCollection,
+} from '@wix/patterns';
+import { contacts } from '@wix/crm';
+
+function PassiveEmptyState() {
+  const state = useTableGridSwitchCollection<contacts.Contact>({
+    queryName: 'contacts-passive',
+    paginationMode: 'offset',
+    fetchData: () =>
+      Promise.resolve({
+        items: [],
+        total: 0,
+      }),
+    itemName: (item) => `${item.info?.name?.first} ${item.info?.name?.last}`,
+    fetchErrorMessage: () => 'Error fetching contacts',
+    filters: {},
+  });
+
+  return (
+    <CollectionPage height="500px">
+      <CollectionPage.Header title={{ text: 'Contacts' }} />
+      <CollectionPage.Content>
+        <TableGridSwitch
+          state={state}
+          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: 'Last Activity',
+              render: (contact) =>
+                contact.lastActivity?.activityDate?.toLocaleString(),
+            },
+          ]}
+          emptyState={<CollectionEmptyState />}
+        />
+      </CollectionPage.Content>
+    </CollectionPage>
+  );
+}
+```
+
+## API
+
+### Props
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `addNewCta` | `NewItemButtonProps` | No | - | Configuration for the default call to action button.\ `onClick`: Adds a callback for when the button is clicked. <br> `text`: Text of the button. To render the default add new item button, you must provide the `onClick` callback. |
+| `dataHook` | `string` | No | - | Applies a data-hook HTML attribute to be used in the tests |
+| `className` | `string` | No | - | Specifies a CSS class name to be appended to the component’s root element. |
+| `children` | `ReactNode` | No | - | Contains components rendered below the subtitle, e.g., `<Button/>` or `<TextButton/>` |
+| `title` | `string` | No | - | Overrides the default title. |
+| `skin` | `"page" \| "page-no-border" \| "section"` | No | - | Sets the style skin for the empty state |
+| `theme` | `"page" \| "page-no-border" \| "section"` | No | - | @deprecated use skin prop instead |
+| `subtitle` | `string` | No | - | Overrides the default subtitle. |
+| `image` | `ReactNode` | No | - | Overrides the default image. Accepts a custom `ReactElement` or boolean value. Pass `false` to hide the default image. |
+| `classNames` | `{ imageContainer?: string; }` | No | - | Sets the empty state image bottom margin. If not specified, use the default padding defined in the CSS. |
+| `align` | `"start" \| "center" \| "end"` | No | - | Sets the alignment of all empty state contents within the component container |
+| `customCta` | `ReactNode` | No | - | Adds another custom call to action button. Pass a [TextButton](https://www.docs.wixdesignsystem.com/?path=/story/components-actions--textbutton) component. |
+