@wix/patterns 1.364.0 → 1.369.0

package/dist/docs/NestedTableLevel.md

@@ -0,0 +1,24 @@
+# NestedTableLevel
+
+**Category:** Base Components/Collections/NestedTable
+
+## API
+
+### Overview
+
+Describes a single level in a [`NestedTable`](./?path=/story/base-components-collections-nestedtable--nestedtable) hierarchy. Each level defines how its items are fetched (`createCollection`), how they relate to parents (`parentKey`), and how they render (`columns`, `renderMainColumn`, `actionCell`). Supports expandability, breadcrumbs, drag-and-drop, and row highlighting.
+
+### Props
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `columns` | `Partial<Record<C, (row: T, rowNum: number) => ReactNode>>` | No | - | Render logic of the cells for this level. By default, all cells will be empty |
+| `renderMainColumn` | `RenderMainColumn<T>` | No | - | Render logic of the main column for this level. T) => { title?: string; subtitle?: string; image?: ReactNode; } |
+| `actionCell` | `ActionCell<T, F>` | No | - | A table's last column. Use this column to add an action at the end of each row. For example, a delete button to delete an item. Pass an [`ActionCellProps`](https://www.docs.wixdesignsystem.com/?path=/story/components-lists-table--tableactioncell) object, or a function that returns an `ActionCellProps` object. |
+| `breadcrumbs` | `((item: T) => { id: string; name: string; }[] \| null)` | No | - | A function that accepts the item of the current level and returns an array of breadcrumbs to be displayed in the toolbar. Each breadcrumb is an object with `id` and `name` properties. `fetchData` will be called with `query.fields` that contains the value `breadcrumbs` to signal that the breadcrumbs should be fetched. |
+| `expandable` | `((item: T) => boolean)` | No | - | A function that accepts the item of the current level and returns a boolean value that indicates whether the item can be expanded. By default, all items are expandable. |
+| `isRowHighlight` | `((item: T) => boolean)` | No | - | A function that accepts the item of the current level and returns a boolean value indicating whether the item should be highlighted. |
+| `parentKey` | `(item: T) => string \| null \| undefined` | Yes | - | A function that accepts the item of the current level and returns the key of the parent item, for example: `(item) => item.parentId`. |
+| `createCollection` | `(params?: NestedOptimisticActionsState<T, F> \| undefined) => { collection: CollectionState<T, F>; parentFilter?: Filter<...> \| undefined; }` | Yes | - | A function that creates a collection for the current level (using [useCreateCollection](./?path=/story/common-hooks--usecreatecollection) hook), and returns the collection state and a reference to a filter object within this collection that filters the collection by the parent key. => { collection: [CollectionState](./?path=/story/common-state--collectionstate); parentFilter?: [Filter<string[]>](./?path=/story/features-filter-factories--stringsarrayfilter); } |
+| `optimisticActionsPredicate` | `((query: ComputedQuery<F>) => (item: T) => boolean)` | No | - | A [predicate](./?path=/story/features-actions-updates--useoptimisticactions) function to pass to the internal [OptimisticActions](/?path=/story/features-actions-updates--collectionoptimisticactions) created by NestedTable |
+

package/dist/docs/NestedTableNodeState.md

@@ -0,0 +1,23 @@
+# NestedTableNodeState
+
+**Category:** Base Components/Collections/NestedTable
+
+## API
+
+### Overview
+
+`NestedTableNodeState` represents a single node in a [`NestedTable`](./?path=/story/base-components-collections-nestedtable--nestedtable) tree. Each node has a `depth`, `expanded` state, `children` collection, `optimisticActions`, and access to its parent via `getParent()`. Use `getData()` to access the item and `toggleExpand()` to expand/collapse.
+
+### Props
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `getParent` | `<TD, FD extends FiltersMap>() => NestedTableNodeStatePublicAPI<C, TD, FD> \| null` | Yes | - | Get the node this node is a child of => [NestedTableNodeState](./?path=/story/base-components-collections-nestedtable--nestedtablenodestate) \| `undefined` |
+| `children` | `CollectionState<T, F>` | No | - | The collection of the node |
+| `optimisticActions` | `NestedTableNodeStateOptimisticActionsPublicAPI<T>` | No | - | The optimistic actions of the node, affects items both in nested & flat mode |
+| `getData` | `<TD>() => TD \| null` | Yes | - | The "parent" item of this node => T \| null |
+| `toggleExpand` | `() => void` | Yes | - | Toggle the expand/collapse state of the node |
+| `expanded` | `boolean` | Yes | - | Whether the node is expanded |
+| `depth` | `number` | Yes | - | The depth of the node in the tree |
+| `getDescendants` | `<TD, FD extends FiltersMap>() => NestedTableNodeStatePublicAPI<C, TD, FD>[]` | Yes | - | Get all the nodes that are descendants of this node from all levels => [NestedTableNodeState](./?path=/story/base-components-collections-nestedtable--nestedtablenodestate)[] |
+

package/dist/docs/NestedTableOptimisticActions.md

@@ -0,0 +1,21 @@
+# NestedTableOptimisticActions
+
+**Category:** Base Components/Collections/NestedTable
+
+## API
+
+### Overview
+
+Extends the standard optimistic actions API with nested-table-specific operations. Provides `updateMany`, `updateOne`, `deleteMany`, and `deleteOne` methods that accept a `propagate` parameter to cascade changes to child nodes. Access via `nodeState.optimisticActions`.
+
+### Props
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `updateMany` | `<R>(items: T[], params: NestedUpdateManyParams<T, R>) => void` | Yes | - | Updates multiple items @param items - The items to update. @param params - Additional parameters for the update operation. @param params.propagate - Indicates whether to propagate the update children nodes @param params.patch - Partial data to patch the items with. |
+| `updateOne` | `<R>(item: T, params: NestedUpdateManyParams<T, R>) => void` | Yes | - | Updates one item @param item - The items to update. @param params - Additional parameters for the update operation. @param params.propagate - Indicates whether to propagate the update children nodes @param params.patch - Partial data to patch the items with. |
+| `deleteMany` | `<R>(items: T[], params: NestedDeleteManyParams<T, R>) => void` | Yes | - | Deletes multiple items and their descendants @param items - An array of items to delete. @param params - Additional parameters for the delete operation. |
+| `deleteOne` | `<R>(item: T, params: NestedDeleteManyParams<T, R>) => void` | Yes | - | Deletes one item and its descendants @param item - An array of items to delete. @param params - Additional parameters for the delete operation. |
+| `createOne` | `(item: T, params: CreateManyParams<T>) => void` | Yes | - | Creates a single item in the collection. @param item - The item to create. @param params - Additional parameters for the operation. |
+| `createMany` | `(items: T[], params: CreateManyParams<T>) => void` | Yes | - | Creates multiple items in the collection. @param items - The items to create. @param params - Additional parameters for the operation. |
+

package/dist/docs/NestedTableState.md

@@ -0,0 +1,21 @@
+# NestedTableState
+
+**Category:** Base Components/Collections/NestedTable
+
+## API
+
+### Overview
+
+`NestedTableState` manages the state for a [`NestedTable`](./?path=/story/base-components-collections-nestedtable--nestedtable) component. It handles multi-level hierarchical data with expand/collapse, flat and nested view modes, toolbar, and optimistic actions. Created by [`useNestedTable`](./?path=/story/base-components-collections-nestedtable-usenestedtable--usenestedtable).
+
+### Props
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `toolbar` | `ToolbarCollectionState<unknown, {}>` | Yes | - | Underlying [ToolbarCollectionState](./?path=/story/common-state--toolbarcollectionstate) instance |
+| `tableState` | `TableState<unknown, {}>` | Yes | - | Underlying [TableState](./?path=/story/base-components-collections-table-tablestate--tablestate) instance |
+| `getNode` | `<TD, FD extends FiltersMap>(key: string) => NestedTableNodeStatePublicAPI<C, TD, FD> \| undefined` | Yes | - | Get the node this item is the parent of. i.e. this node's collection items' parent id is the `key` @param key string) => [NestedTableNodeState](./?path=/story/base-components-collections-nestedtable--nestedtablenodestate) \| undefined |
+| `getRootNode` | `<TD, FD extends FiltersMap>() => NestedTableNodeStatePublicAPI<C, TD, FD>` | Yes | - | Get the root node of the nested table, this node's collection items' parent id is `null`, the items are the top level items |
+| `getAllNodes` | `<TD, FD extends FiltersMap>() => NestedTableNodeStatePublicAPI<C, TD, FD>[]` | Yes | - | Get all the nodes in the table |
+| `refreshAll` | `() => void` | Yes | - | An API to refresh all items in the nested table. |
+

package/dist/docs/Next.js.md

@@ -0,0 +1,143 @@
+# Next.js
+
+**Category:** Guides
+
+##  
+
+**Next.js** is replacing the Yoshi fullstack flow.\
+It's not yet officially supported by the infra team, however early adopters can try it out using the WIX [Next.js template](https://github.com/wix-private/nextjs-playground/tree/master/packages/nextjs-template).
+
+### Integration with Patterns
+
+Patterns support Next.js with some limitations:
+
+- Patterns don’t support SSR which means that NextJS will not be able to compile it as a server component, Patterns can be used only in the CSR mode.
+
+### Getting started
+
+- Install the following dependencies
+
+```diff
+"dependencies": {
++  "@wix/patterns": "^2.657.0",
+   "@wix/design-system": "^1.70.0",
+   "next": "^12.3.4",
++  "next-global-css": "^1.3.1",
++  "webpack-node-externals": "^3.0.0"
+}
+```
+
+- Modify the `next.config.js`
+
+```diff
++  const { patchWebpackConfig } = require('next-global-css');
++  const webpackNodeExternals = require('webpack-node-externals');
+
+const nextConfig = {
+   webpack: (config, options) => {
++    patchWebpackConfig(config, options);
++    if (options.isServer) {
++      config.externals = webpackNodeExternals({
++        allowlist: [/design-system/],
++      });
++    }
+
+    return config;
+   }
+};
+
+module.exports = nextConfig;
+```
+
+- Create Patterns application and wrap it up with the `Next.js` dynamic import.\
+  Patterns don't support SSR, attempting to compile it in the SSR mode will cause the Next.js exception.
+
+```diff
++++ /pages/index.tsx
+const Index: NextPage = () => {
+  return (
+    <>
+      
+        Create Next App
+        
+      
++     
+    
+  );
+};
+
+export default Index;
+
++++ /components/PatternsDynamicComponent.tsx
++ import dynamic from 'next/dynamic';
++ import { Box, Loader } from '@wix/design-system';
+
++ export const PatternsDynamicComponent = dynamic(
++   () => import('./PatternsComponent').then(({ PatternsComponent }) => PatternsComponent),
++   {
++     ssr: false, // Here we instruct Next.js to compile it only as a client side component.
++     loading: () => (
++       
++         
++       
++     )
++   }
++ );
+
++++ /components/PatternsComponent.tsx
++ import { WixPatternsEssentialsProvider } from '@wix/patterns/essentials';
++ import { Box } from '@wix/design-system';
++ import { App } from './App';
+
++ export const PatternsComponent = () => {
++   return (
++     
++       
++         
++       
++     
++   );
+};
+
+```
+
+### NextJS and Views feature
+
+The `Views` feature uses an history object in order to put the viewId parameter in the URL.
+
+The default history object that Patterns use is `import { createBrowserHistory } from 'history';`, but it conflicts with the NextJS router, which doesn't provide an history object itself.
+
+If you want to use the views feature and NextJS, you should provide your own history object to Patterns, with `push` and `replace` properties from NextJS router, for example:
+
+```js
+import { WixPatternsEssentialsProvider } from '@wix/patterns/essentials';
+import { Collection } from './Collection';
+import { useRouter } from 'next/router'
+import { WixPatternsContainerOverridesProvider } from '@wix/patterns';
+import { useState } from 'react';
+import { WixPatternsContainerParams } from '@wix/patterns/core';
+import { createBrowserHistory } from '@wix/patterns/history';
+
+export const Patterns = () => {
+  const router = useRouter();
+  const [wixPatternsContainerOverrides] = useState>(
+    () => ({
+      history: { ...createBrowserHistory(), push: router.push, replace: router.replace }
+    }),
+  );
+
+  return (
+    
+      
+        The children
+      
+    
+  );
+};
+```
+
+If you ignore this step, you may have issues with navigation from the collection page to other pages in your app.
+
+For further technical details, please refer to the [Patterns NextJS example](https://github.com/wix-private/cairo/tree/master/examples/nextjs).
+
+

package/dist/docs/NumberRangeFilter.md

@@ -0,0 +1,230 @@
+# NumberRangeFilter
+
+**Category:** Features/Filter/Components
+
+## Design
+
+### Overview
+
+# NumberRangeFilter Component
+
+A flexible numeric range filter component that enables users to filter data within specified minimum and maximum bounds. Perfect for filtering prices, quantities, or any numeric values.
+
+## Quick Start
+
+```typescript
+import { NumberRangeFilter, numberRangeFilter } from '@wix/patterns';
+
+function PriceRangeExample() {
+  const [filter] = React.useState(() =>
+    numberRangeFilter({
+      name: 'price',
+      initialValue: { from: 0, to: 100 },
+    }),
+  );
+
+  return ;
+}
+```
+
+## Props
+
+| Prop      | Type                             | Default     | Description                                                     |
+| --------- | -------------------------------- | ----------- | --------------------------------------------------------------- |
+| `filter`  | `FilterProps>` | Required    | Filter object containing current range values and update method |
+| `decimal` | `boolean`                        | `false`     | Enable decimal number support                                   |
+| `min`     | `number`                         | `undefined` | Minimum allowed value                                           |
+| `max`     | `number`                         | `undefined` | Maximum allowed value                                           |
+
+## Features
+
+### 1. Input Validation
+
+- Automatically validates numeric inputs
+- Enforces min/max constraints
+- Prevents invalid number formats
+
+### 2. Smart Error Handling
+
+The component displays error messages in the following scenarios:
+
+```typescript
+// Below minimum value error
+ // "Value must be greater than or equal to 10"
+
+// Above maximum value error
+ // "Value must be less than or equal to 100"
+
+// Invalid range error
+// When 'from' value is greater than 'to' value
+// Shows on the relevant input field that caused the invalid range
+"Minimum value cannot be greater than maximum value"
+"Maximum value cannot be less than minimum value"
+```
+
+### 3. Performance Optimization
+
+- Implements 500ms debounced updates to prevent excessive filtering
+- Updates only occur after user stops typing
+
+## Complete Example
+
+```typescript
+import { NumberRangeFilter, numberRangeFilter } from '@wix/patterns';
+import { useCollection } from '@wix/patterns';
+
+function ProductFilters() {
+  // Initialize filter
+  const [priceFilter] = React.useState(() =>
+    numberRangeFilter({
+      name: 'price',
+      initialValue: { from: 10, to: 50 },
+      onChange: (value) => {
+        // Optional: Handle changes directly
+        console.log('Price range:', value);
+      },
+    }),
+  );
+
+  // Use with collection (recommended approach)
+  const collection = useCollection({
+    queryName: 'products-query',
+    filters: {
+      price: priceFilter,
+    },
+    fetchData: async (query) => {
+      const { filters } = query;
+      // Access price range via filters.price
+      return fetchProducts(filters);
+    },
+  });
+
+  return (
+    
+  );
+}
+```
+
+## Best Practices
+
+1. **Initialize with Factory Function**
+
+```typescript
+// Recommended
+const [filter] = React.useState(() =>
+  numberRangeFilter({
+    name: 'priceRange',
+    initialValue: { from: 0, to: 100 },
+  }),
+);
+
+// Avoid direct initialization
+const [filter] = React.useState({ from: 0, to: 100 });
+```
+
+2. **Use with Collections**
+
+```typescript
+// Recommended - Integration with collection
+const collection = useCollection({
+  filters: {
+    price: numberRangeFilter(),
+  },
+  // ... other collection config
+});
+
+// Avoid standalone usage without collection integration
+const [range, setRange] = useState({ from: 0, to: 100 });
+```
+
+## Error States
+
+The component handles various error states automatically:
+
+1. **Input Validation Errors**
+
+   - Non-numeric input
+   - Values outside min/max bounds
+   - Invalid decimal formats when `decimal={false}`
+
+2. **Range Logic Errors**
+
+   - From value greater than To value
+   - To value less than From value
+
+3. **Boundary Errors**
+   - Values below specified minimum
+   - Values above specified maximum
+
+Each error state displays appropriate error messages below the relevant input field and highlights the field in error state.
+
+
+```tsx
+import { NumberRangeFilter } from '@wix/patterns';
+```
+
+---
+
+### Examples
+
+### Without passing config props, integer only values, without min or max limitations
+
+```tsx
+import React from 'react';
+import { NumberRangeFilter, numberRangeFilter } from '@wix/patterns';
+
+function DefaultNumberRangeFilter() {
+  const [filter] = React.useState(() => numberRangeFilter());
+
+  return <NumberRangeFilter filter={filter} />;
+}
+```
+
+---
+
+### With decimal values
+
+```tsx
+import React from 'react';
+import { NumberRangeFilter, numberRangeFilter } from '@wix/patterns';
+
+function DecimalNumberRangeFilter() {
+  const [filter] = React.useState(() => numberRangeFilter());
+
+  return <NumberRangeFilter filter={filter} decimal />;
+}
+```
+
+---
+
+### With min and max limitations.
+
+```tsx
+import React from 'react';
+import { NumberRangeFilter, numberRangeFilter } from '@wix/patterns';
+
+function DecimalNumberRangeFilter() {
+  const [filter] = React.useState(() => numberRangeFilter());
+
+  return <NumberRangeFilter filter={filter} decimal min={0} max={5} />;
+}
+```
+
+## API
+
+### Props
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `filter` | `Filter<RangeItem<number>>` | Yes | - | A filter state object such as [ArrayFilter](./?path=/story/features-filter-factories--arrayfilter) |
+| `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). |
+| `popoverProps` | `PopoverCommonProps` | No | - | @deprecated |
+| `onAppliedFilterTagRemove` | `((item: RangeItem<number>) => unknown)` | No | - | Callback that's run when a filter is removed by a visitor from the sub-toolbar. @param item |
+| `renderToolbarTag` | `((item: RangeItem<number>) => 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/OperatorFilterPicker.md

@@ -0,0 +1,195 @@
+# OperatorFilterPicker
+
+**Category:** Features/Filter/Components
+
+## Design
+
+### Overview
+
+The `OperatorFilterPicker` component provides a UI for users to select a filter operator and input a value. It renders a dropdown for operator selection and an input field for the filter value.
+
+This component is designed to work with the `operatorFilter` factory.
+
+**Important:** The `allowedOperators` array must include at least one operator that requires a value input (e.g., `EQUALS`, `STARTS_WITH`). If only value-less operators like `IS_EMPTY` or `NOT_EXISTS` are provided, the component will throw an error.
+
+### Key Features
+
+- **Operator selection**: Users can choose from a list of allowed operators via a dropdown.
+- **Value input**: Text input for entering the filter value.
+- **Automatic apply**: Filter is applied when user presses Enter or blurs the input.
+- **Operators without values**: Supports operators like `IS_EMPTY` and `NOT_EXISTS` that don't require a value input.
+
+### 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 { OperatorFilterPicker, operatorFilter, FilterOperator } from '@wix/patterns';
+```
+
+---
+
+### Examples
+
+### 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 |
+|------|------|----------|---------|-------------|
+| `filter` | `Filter<OperatorFilterValue<T>>` | Yes | - | A filter state object such as [ArrayFilter](./?path=/story/features-filter-factories--arrayfilter) |
+| `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). |
+| `popoverProps` | `PopoverCommonProps` | No | - | @deprecated |
+| `onAppliedFilterTagRemove` | `((item: OperatorFilterValue<T>) => unknown)` | No | - | Callback that's run when a filter is removed by a visitor from the sub-toolbar. @param item |
+| `renderToolbarTag` | `((item: OperatorFilterValue<T>) => 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. |
+