@wix/patterns 1.366.0 → 1.369.0

package/dist/docs/GridDragAndDrop.md

@@ -0,0 +1,131 @@
+# GridDragAndDrop
+
+**Category:** Features/Sort/Drag and Drop
+
+## Design
+
+### Description
+
+Enables [drag and drop](./?path=/story/features-sort-drag-and-drop--overview) functionality on a [`Grid`](./?path=/story/base-components-collections-grid-grid--grid) component.
+
+#### Usage
+
+1. Define a [`Grid`](./?path=/story/base-components-collections-grid-grid--grid) component.
+1. Import and pass the `GridDragAndDrop` component to the `dragAndDrop` prop on the `Grid`.
+1. Define the relevant drag and drop props on the [`Grid`](./?path=/story/base-components-collections-grid-grid--grid&tab=API):
+
+      * `dragAndDropSubmit`
+      * `dragAndDropCancel` (optional)
+      * `dragAndDropBulkSubmit` (optional)
+      * `dragAndDropCategories` (optional)
+      * `dragAndDropReorderModeToolbar` (optional)
+
+
+```tsx
+import { GridDragAndDrop } from '@wix/patterns';
+```
+
+### Grid
+
+Drag and drop items in a grid.
+
+```tsx
+import React from 'react';
+import { CollectionPage } from '@wix/patterns/page';
+import {
+  GridDragAndDrop,
+  useOptimisticActions,
+  useGridCollection,
+  Grid,
+  ToolbarTitle,
+  CursorQuery,
+} from '@wix/patterns';
+import { tasks } from '@wix/crm';
+
+function GridExample() {
+  const { queryTasks, moveTaskAfter, countTasks } = tasks;
+
+  const grid = useGridCollection<tasks.Task>({
+    queryName: 'tasks-Grid',
+    paginationMode: 'cursor',
+    itemKey: (item) => item._id as string,
+    itemName: (item) => item.title as string,
+    fetchData: async (query: CursorQuery) => {
+      const { limit, cursor } = query;
+
+      let queryBuilder = queryTasks().limit(limit);
+
+      if (cursor) {
+        queryBuilder = queryBuilder.skipTo(cursor);
+      }
+
+      return queryBuilder.find().then((res) => {
+        const { items = [], cursors } = res;
+        return {
+          items,
+          cursor: cursors.next,
+        };
+      });
+    },
+    fetchTotal: async (_query: CursorQuery) => {
+      const filter = {};
+      return countTasks({ filter }).then((res) => res.count as number);
+    },
+    fetchErrorMessage: ({ err }) => String(err),
+  });
+
+  useOptimisticActions(grid.collection);
+
+  return (
+    <CollectionPage height="400px">
+      <CollectionPage.Header title={{ text: 'Tasks' }} />
+      <CollectionPage.Content>
+        <Grid
+          title={<ToolbarTitle title="Tasks list" />}
+          state={grid}
+          renderItem={(task: tasks.Task) => ({
+            key: task._id,
+            primaryActionProps: { label: task.source?.sourceType },
+            title: grid.collection.itemName(task),
+          })}
+          search={false}
+          dragAndDrop={GridDragAndDrop}
+          dragAndDropSubmit={(event) =>
+            moveTaskAfter(event.from.item._id as string, {
+              beforeTaskId: event.after
+                ? (event.after.item._id as string)
+                : null,
+            })
+          }
+        />
+      </CollectionPage.Content>
+    </CollectionPage>
+  );
+}
+```
+
+## BI
+
+### Events
+
+  Event   |   Description   |
+--------- | --------------- |
+[144:138](https://bo.wix.com/data-tools/bi-catalog-app/event/144:138) | Sent when a user clicks on an item and tries to drag it, in order to sort the items manually
+[144:139](https://bo.wix.com/data-tools/bi-catalog-app/event/144:139) | Sent when a user finish to drag an item
+[144:140](https://bo.wix.com/data-tools/bi-catalog-app/event/144:140) | Sent when a user finish to drag items but those changes weren't update in the server from different reasons
+[144:141](https://bo.wix.com/data-tools/bi-catalog-app/event/144:141) | Sent when a user clicks on a "try again" CTA he gets in an error notification
+
+
+
+### Component load events
+Event   |   Description   |
+--------- | --------------- |
+[144:110](https://bo.wix.com/data-tools/bi-catalog-app/event/144:110) | Sent when a Wix Patterns component starts loading
+[144:111](https://bo.wix.com/data-tools/bi-catalog-app/event/144:111) | Sent when a Wix Patterns component is done loading
+
+
+#### 🐪 Couldn't find what you need?
+* Check our [BI Catalog](https://bo.wix.com/data-tools/bi-catalog-app?viewId=all-items-view&selectedColumns=src%2Cevid%2Cname%2Cowner%2Cproduct%2CuserType+false%2CdateUpdated%2CdateCreated+false%2CcreatedBy+false%2Cstatus&source=%5B%7B%22id%22%3A%22144%22%2C%22name%22%3A%22144+-+Cairo%22%7D%5D)
+* Contact us on [#cairo-bi](https://wix.slack.com/archives/C03N53KURH9)
+
+

package/dist/docs/GridFolders.md

@@ -0,0 +1,259 @@
+# GridFolders
+
+**Category:** Base Components/Collections/GridFolders/GridFolders
+
+## Design
+
+### Description
+
+The `GridFolders` component presents folders and their respective content in a visually organized grid view, where each part is neatly divided into its own dedicated section. The [`useGridFolders()`](./?path=/story/base-components-collections-gridfolders-usegridfolders--usegridfolders) hook manages the state and behavior of the grid component based on the provided collections.
+
+
+```tsx
+import { GridFolders, useGridFolders } from '@wix/patterns';
+```
+
+### Demo
+
+```tsx
+import React from 'react';
+import { queryContacts } from '@wix/ambassador-contacts-v4-contact/http';
+import { Contact } from '@wix/ambassador-contacts-v4-contact/types';
+import {
+  OffsetQuery,
+  useCollection,
+  GridFolders,
+  PageWrapper,
+  useGridFolders,
+} from '@wix/patterns';
+import { useHttpClient } from '@wix/yoshi-flow-bm';
+import { Page } from '@wix/design-system';
+
+function Basic() {
+  const httpClient = useHttpClient();
+
+  const collection = useCollection<Contact>({
+    queryName: 'griditems',
+    itemKey: (item) => item.id as string,
+    itemName: (item) => item.name as string,
+    fetchData: (query: OffsetQuery) => {
+      const { limit, offset, search, filters } = query;
+      return httpClient
+        .request(
+          queryContacts({
+            query: { paging: { limit, offset }, filter: filters },
+            search,
+          }),
+        )
+        .then((res) => {
+          const {
+            data: { contacts = [], pagingMetadata },
+          } = res;
+          return {
+            items: contacts,
+            total: pagingMetadata?.total,
+          };
+        });
+    },
+    fetchErrorMessage: ({ err }) => String(err),
+  });
+
+  const foldersCollection = useCollection<Contact>({
+    queryName: 'gridfolders',
+    paginationMode: 'offset',
+    itemName: (item) => item.name as string,
+    fetchData: (query: OffsetQuery) => {
+      const { limit, offset, search, filters } = query;
+      return httpClient
+        .request(
+          queryContacts({
+            query: { paging: { limit: 20, offset }, filter: filters },
+            search,
+          }),
+        )
+        .then((res) => {
+          const {
+            data: { contacts = [], pagingMetadata },
+          } = res;
+          return {
+            items: contacts,
+            total: 20,
+          };
+        });
+    },
+    fetchErrorMessage: ({ err }) => String(err),
+  });
+
+  const componentState = useGridFolders({
+    items: collection,
+    folders: foldersCollection,
+  });
+
+  return (
+    <PageWrapper>
+      <Page height="400px">
+        <Page.Header title="Folders and items" />
+
+        <Page.Content>
+          <GridFolders
+            state={componentState}
+            preset="title"
+            folderPreset="title"
+          />
+        </Page.Content>
+      </Page>
+    </PageWrapper>
+  );
+}
+```
+
+---
+
+### Variations
+
+### Grid Folders
+
+Displaying folders and their contents in a grid view.
+
+```tsx
+import React from 'react';
+import { queryContacts } from '@wix/ambassador-contacts-v4-contact/http';
+import { Contact } from '@wix/ambassador-contacts-v4-contact/types';
+import {
+  OffsetQuery,
+  useCollection,
+  GridFolders,
+  PageWrapper,
+  useGridFolders,
+} from '@wix/patterns';
+import { useHttpClient } from '@wix/yoshi-flow-bm';
+import { Page } from '@wix/design-system';
+
+function Basic() {
+  const httpClient = useHttpClient();
+
+  const collection = useCollection<Contact>({
+    queryName: 'griditems_example',
+    itemKey: (item) => item.id as string,
+    itemName: (item) => item.name as string,
+    fetchData: (query: OffsetQuery) => {
+      const { limit, offset, search, filters } = query;
+      return httpClient
+        .request(
+          queryContacts({
+            query: { paging: { limit, offset }, filter: filters },
+            search,
+          }),
+        )
+        .then((res) => {
+          const {
+            data: { contacts = [], pagingMetadata },
+          } = res;
+          return {
+            items: contacts,
+            total: pagingMetadata?.total,
+          };
+        });
+    },
+    fetchErrorMessage: ({ err }) => String(err),
+  });
+
+  const foldersCollection = useCollection<Contact>({
+    queryName: 'gridfolders_example',
+    paginationMode: 'offset',
+    itemName: (item) => item.name as string,
+    fetchData: (query: OffsetQuery) => {
+      const { limit, offset, search, filters } = query;
+      return httpClient
+        .request(
+          queryContacts({
+            query: { paging: { limit, offset }, filter: filters },
+            search,
+          }),
+        )
+        .then((res) => {
+          const {
+            data: { contacts = [], pagingMetadata },
+          } = res;
+          return {
+            items: contacts,
+            total: pagingMetadata?.total,
+          };
+        });
+    },
+    fetchErrorMessage: ({ err }) => String(err),
+  });
+
+  const componentState = useGridFolders({
+    items: collection,
+    folders: foldersCollection,
+  });
+
+  return (
+    <PageWrapper>
+      <Page height="400px">
+        <Page.Header title="Folders and items" />
+
+        <Page.Content>
+          <GridFolders
+            state={componentState}
+            preset="title"
+            folderPreset="title"
+          />
+        </Page.Content>
+      </Page>
+    </PageWrapper>
+  );
+}
+```
+
+## API
+
+### Props
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `state` | `GridFoldersState<T1, F1, T2, F2>` | Yes | - | A GridFoldersState instance created using [useGridFolders](./?path=/story/base-components-collections-gridfolders-usegridfolders--usegridfolders). |
+| `itemsSectionTitle` | `string` | No | - | Optional custom title for the items section |
+| `renderFolderItem` | `((item: T2, index: number) => Partial<SupportedCardGalleryItemProps>)` | No | - | Same as `renderItem`, but for a folder item. |
+| `folderPreset` | `"title" \| "full"` | No | - | Same as `preset` but for a folder item |
+| `folderActionCell` | `ActionCell<T2, F2>` | No | - | Same as `actionCell`, but for a folder item. |
+| `renderFolderAddItem` | `(() => ReactElement<AddItemProps, string \| JSXElementConstructor<any>>)` | No | - | Same as `renderAddItem`, but for a folder item. |
+| `search` | `boolean \| FilterElement<any> \| CollectionSearchElement` | No | `true` | Displays a search input on the right side of the table toolbar.<br> <br> Accepts a boolean or a custom React element as a parameter. When passing `false`, no search input is displayed. |
+| `title` | `ToolbarTitleElement` | No | - | Displays a title at the left of a toolbar. Accepts a [ToolbarTitle](./?path=/story/features-display-toolbar--toolbartitle) component. |
+| `tags` | `TagsElement<T1, Partial<F1 & F2>>` | No | - | Enables tags feature. In this element you can pass the configuration |
+| `errorState` | `((err: unknown, params: { isOnline: boolean; retry: () => void; }) => ReactElement<any, string \| JSXElementConstructor<any>>)` | No | - | A render function to be rendered when there's an error fetching data from the server.<br> The function accepts the following parameters <br> * `err`: The error thrown by the [fetchData](./?path=/story/common-hooks--usecollection) function <br> * `isOnline`: Indicates whether internet connection is available <br> * `retry`: Retry collection fetch on failed response, similar to `collection.retryFetch` <br> Returns [`EmptyState`](https://www.docs.wixdesignsystem.com/?path=/story/components-layout--emptystate) component. |
+| `maxSelection` | `number` | No | - | Limits the amount of rows a visitor can select. |
+| `views` | `CollectionViewsDropdownElement<Partial<F1 & F2>>` | No | - | Adds view options to the table headers. Accepts a [Views](./?path=/story/features-display-views--views) component. |
+| `filters` | `CollectionToolbarFiltersElement` | No | - | Adds filters to the toolbar and/or a sliding panel. Accepts a `ToolbarFilters` component, which must have the `panelTitle` prop defined. |
+| `tabs` | `TabsFilterElement<TabsFilterProps<T1>>` | No | - | Displays tabs at the left of a toolbar. Accepts a [TabsFilter](./?path=/story/features-filter-components--tabsfilter) component. |
+| `minCardHeight` | `MinHeight<string \| number>` | No | `300px` | Minimum height for a card's container when showing:<br> - A loader<br> - Empty state<br> - Error state <br><br> If no unit is specified, `px` is used. |
+| `renderError` | `((params: { err: unknown; isOnline: boolean; retry: () => void; }) => ReactElement<any, string \| JSXElementConstructor<any>>)` | No | - | A render function to be rendered when there's an error fetching data from the server.<br> The function accepts the following parameters <br> * `err`: The error thrown by the [fetchData](./?path=/story/common-hooks--usecollection) function <br> * `isOnline`: Indicates whether internet connection is available <br> * `retry`: Retry collection fetch on failed response, similar to `collection.retryFetch` <br> Returns [`EmptyState`](https://www.docs.wixdesignsystem.com/?path=/story/components-layout--emptystate) component. @deprecated Use `errorState` instead. |
+| `emptyState` | `ReactNode` | No | - | Renders when there are no items to display. Accepts a [`CollectionEmptyState`](./?path=/story/features-display-empty-states--collectionemptystate) component. |
+| `noResultsState` | `ReactNode \| ((params: { hasAvailableItems: boolean; query: ComputedQuery<Partial<F1 & F2>>; }) => ReactNode)` | No | - | Shown when a search or filter has no results. Accepts a [`CollectionNoResultsState`](./?path=/story/features-display-empty-states--collectionnoresultsstate) component, or a function that accepts the following parameters: - `hasAvailableItems`: Indicates whether other items may be shown using other filter or search parameters. - `query`: An instance of [`ComputedQuery`](./?path=/story/common-models--computedquery) representing the query that resulted in the empty state. The function should return [`CollectionNoResultsState`](./?path=/story/features-display-empty-states--collectionnoresultsstate). |
+| `summaryBar` | `ReactNode` | No | - | Display a summary bar below the toolbar. Accepts a [`SummaryBar`](./?path=/story/features-display-toolbar--summarybar) component. |
+| `dragAndDropSubmit` | `DragAndDropSubmit<T1, Partial<F1 & F2>>` | No | - | Function that submits a drop event to the server. <br> <br> The parameter is an event object containing the following details: <br> -`from: {item: T; index: number}`: The dragged item. <br> -`after: null \| [item: T; iindex: number}`: The previous dropped item. If this is the first item to be dropped, this argument is `null`. <br> -`filters`: Applied [Drag and Drop](./?path=/story/features-sort-drag-and-drop--overview) filters. @returns Promise |
+| `dragAndDropBulkSubmit` | `DragAndDropBulkSubmit<T1, Partial<F1 & F2>>` | No | - | Function that submits an array of drop events to the server. <br> <br> The parameter is an array of event objects containing the following details: <br> -`from: {item: T; index: number}`: The dragged item. <br> -`after: null \| [item: T; index: number}`: The previous dropped item. If this is the first item to be dropped, this argument is `null`. <br> -`filters`: Applied [Drag and Drop](./?path=/story/features-sort-drag-and-drop--overview) filters. <br> @returns Promise |
+| `dragAndDropCancel` | `DragAndDropCancel<T1, Partial<F1 & F2>>` | No | - | A function that cancels a drop event. <br> Supported arguments: <br> - `from: {item: T; index: number}`: The dragged item. - `after: null \| {item: T; index: number}`: The item that the dragged item was dropped after. If dropped at the head of the collection, this argument will be `null`. - `filters`: Currently applied filters. Used in cases where your server holds a unique ordering per filtering. See the `dragAndDropCategories` prop. If the move is cancelled, the function returns a toast config object with a message. Otherwise, the function will return a null value. |
+| `extensionMenuItems` | `ExtensionMenuItemsType` | No | - | @deprecated It doesn't need to be passed implicitly anymore. |
+| `dragAndDropReorderModeToolbar` | `ReorderModeToolbarElement \| null` | No | - | Drag and drop reorder mode toolbar. This prop accepts a `ReorderModeToolbar` component.<br> The `ReorderModeToolbar` component accepts the following props:<br> + `learnMoreUrl`: [string] A URL in the toolbar.<br> + `reorderModeTitle`: [string] A title in the toolbar. |
+| `customColumns` | `CustomColumnsElement \| null` | No | - | Adds functionality to allow visitors to create choose which columns to display and in what order. Accepts a [CustomColumns](./?path=/story/features-display--customcolumns) component. |
+| `multiLevelSorting` | `MultiLevelSortingElement` | No | - | Adds functionality to allow visitors to sort multiple columns simultaneously. Accepts a [MultiLevelSorting](./?path=/story/features-sort-sortable-columns-multilevelsorting--multilevelsorting) component. |
+| `primaryActionButton` | `PrimaryActionButtonElement` | No | - | Adds functionality for a primary action button in the toolbar. Accepts a [PrimaryActionButton](./?path=/story/features-actions-primary-actions--primary-action-button) component. |
+| `secondaryActions` | `ToolbarSecondaryActionsElement` | No | - | Secondary buttons w/o PopoverMenu component to be rendered on the toolbar. |
+| `moreActions` | `MoreActionsElement` | No | - | A [`MoreActions`](./?path=/story/features-actions-more-actions--more-actions) component to be rendered on the header. |
+| `AddApplyFiltersButton` | `AddApplyFiltersButtonType` | No | - | Apply filter button implementation: `import { AddApplyFiltersButton } from '@wix/patterns';` <br> Add `Apply` button to the filters panel footer. Panel filters will be applied only after the button is clicked. |
+| `internalScroll` | `boolean` | No | - | Indicates whether the table should have an [internal scroll](./?path=/story/features-display-internal-scroll--internal-scroll) instead of the default page scroll. |
+| `showFieldTypeIcons` | `boolean` | No | `false` | When true, renders prefix icons for field types in column headers, filters, and the customize-columns panel. Each column and filter should have a `fieldType` property set so Cairo can render the matching icon. |
+| `showTitleBar` | `boolean` | No | `true` | Indicates whether to show Table Title Bar or not. Note: if you pass `showTitleBar = false` title bar is not removed from the DOM. For better accessibility column titles should be defined as well. |
+| `exportButton` | `ReactElement<any, string \| JSXElementConstructor<any>>` | No | - | A [`<ExportButton />`](./?path=/story/features-export--exportto) react element to be added to the toolbar |
+| `importButton` | `ReactElement<any, string \| JSXElementConstructor<any>>` | No | - | A [`<ImportButton />`] react element to be added to the toolbar. |
+| `exportModal` | `ReactElement<any, string \| JSXElementConstructor<any>>` | No | - | A [`<ExportModal />`](./?path=/story/features-export--exportto#CTA_is_out_of_the_table) react element to be rendered in table's context. |
+| `importModal` | `ReactElement<any, string \| JSXElementConstructor<any>>` | No | - | A [`<ImportModal />`] react element to be rendered in table's context. |
+| `dragAndDropCategories` | `(keyof F1 \| keyof F2)[][] \| null` | No | - | By default, drag and drop works only without filters. To enable drag and drop with filters, pass an array of filters to this prop. The functionality will then work only for the specified filters, and to enable without filters, you must pass an empty array. For more information, see the [Drag and Drop Overview](//?path=/story/features-sort-drag-and-drop--overview). |
+| `preset` | `"title" \| "full" \| "footer" \| "empty"` | No | `title` | A `CardGalleryItem` preset to preserve the same card size regardless of the provided data. Subtitle will be shown only in 'full' or 'footer' presets. @example full — renders title + subtitle title — renders only title empty — renders a card without a footer |
+| `renderItem` | `((item: T1, index: number) => Partial<SupportedCardGalleryItemProps>)` | No | - | A function that renders a custom item of the grid. Returns a WSR [`CardGalleryItemProps`](https://www.docs.wixdesignsystem.com/?path=/story/components-lists--cardgalleryitem) object. |
+| `actionCell` | `ActionCell<T1, F1>` | No | - | Adds an action on the grid item. For example, a delete button to delete an item. Accepts an [`ActionCellProps`](https://www.docs.wixdesignsystem.com/?path=/story/components-lists-table--tableactioncell) object, or a function that returns an `ActionCellProps` object. |
+| `renderAddItem` | `(() => ReactElement<AddItemProps, string \| JSXElementConstructor<any>>)` | No | - | A function that renders [`<AddItem>`](https://www.docs.wixdesignsystem.com/?path=/story/components-actions--additem&activeTab=Description&globals=backgrounds.value:!hex(F8F8F8);backgrounds.grid:false) after all cards in a gallery. <br><br> The `<AddItem>` card will not show when filters are applied unless the filter is defined with the persistent option. |
+| `imagePlacement` | `"top" \| "side"` | No | - | Sets placement of a background image. |
+

package/dist/docs/GridFoldersSection.md

@@ -0,0 +1,16 @@
+# GridFoldersSection
+
+**Category:** Base Components/Collections/GridFolders/GridFoldersSection
+
+## Design
+
+### Description
+
+`GridFoldersSection` renders a section within a `GridFolders` layout — either the folders section or the items section. Each section can include an optional `header` (e.g. a section title) and accepts `children` for the grid content.
+
+This component is typically used in conjunction with [`GridFolders`](./?path=/story/base-components-collections-gridfolders--gridfolders) and [`useGridCollection`](./?path=/story/common-hooks--usegridcollection).
+
+```tsx
+import { GridFoldersSection } from '@wix/patterns';
+```
+

package/dist/docs/GridFoldersState.md

@@ -0,0 +1,20 @@
+# GridFoldersState
+
+**Category:** Base Components/Collections/GridFolders/GridFoldersState
+
+## API
+
+### Overview
+
+`GridFoldersState` manages the state for a [`GridFolders`](./?path=/story/base-components-collections-gridfolders--gridfolders) component, which displays both folders and items in a grid layout. It holds separate `CollectionState` instances for folders and items, plus a shared toolbar. Created by [`useGridCollection`](./?path=/story/common-hooks--usegridcollection) with a folders configuration.
+
+### Description
+
+`GridFoldersState` is the return value of the [`useGridFoldersCollection()`](./?path=/story/base-components-collections-gridfolders-usegridfolders--usegridfolders) hook.
+
+### Props
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `toolbar` | `ToolbarCollectionState<T1, {}>` | Yes | - | Underlying [ToolbarCollectionState](./?path=/story/common-state--toolbarcollectionstate) instance |
+

package/dist/docs/GridSectionsProp.md

@@ -0,0 +1,22 @@
+# GridSectionsProp
+
+**Category:** Common/Types
+
+## API
+
+### Overview
+
+Configuration object for the `sections` prop on [`Grid`](./?path=/story/base-components-collections-grid--grid). Enables grouping grid items into sections with headers. Provide a `GridSections` component, a `groupBy` function that extracts the grouping key from each item, and an optional `renderSection` callback for custom section headers.
+
+### Description
+
+Pass to the `sections` prop of a `Grid` component to create [Grid Sections](./?path=/story/features-display-grid-sections--grid-sections).
+
+### Props
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `GridSections` | `(<T, F extends FiltersMap>(props: GridSectionsContentProps<T, F>) => Element) & { displayName: string; }` | Yes | - | A `GridSections` component. Import and pass the component without parameters. |
+| `groupBy` | `GroupBy<T>` | Yes | - | A function that extracts the grouping key from an item. Items with the same key will be grouped into the same section. |
+| `renderSection` | `RenderSection<T>` | No | - | A callback function to render the grid sections. The function receives the section ID and items in the section, and should return the `title`, and optional `primaryAction`, `badge`, or `summary` for each section. For more information, see the [section](./?path=/story/common-types--collectionsection) type. |
+

package/dist/docs/GridState.md

@@ -0,0 +1,22 @@
+# GridState
+
+**Category:** Base Components/Collections/Grid/GridState
+
+## API
+
+### Overview
+
+`GridState` manages the state for a [`Grid`](./?path=/story/base-components-collections-grid--grid) component. It wraps a `CollectionState` for data, a `ToolbarCollectionState` for the toolbar, and tracks grid-specific UI state like size presets and sections. Created by [`useGridCollection`](./?path=/story/common-hooks--usegridcollection).
+
+### Description
+
+`GridState` is the return value of the [`useGridCollection()`](./?path=/story/base-components-collections-grid-usegridcollection--usegridcollection) hook.
+
+### Props
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `collection` | `CollectionState<T, F>` | Yes | - | Underlying [CollectionState](./?path=/story/common-state--collectionstate) instance |
+| `toolbar` | `ToolbarCollectionState<T, F>` | Yes | - | Underlying [ToolbarCollectionState](./?path=/story/common-state--toolbarcollectionstate) instance |
+| `onAddItemActionComplete` | `(items: T[]) => void` | Yes | - | Reset active filters & sorting and adds new items to the collection. @param items - new items to add to the collection |
+

package/dist/docs/Highlighted Search.md

@@ -0,0 +1,114 @@
+# Highlighted Search
+
+**Category:** Features/Display/Highlighted Search
+
+## Design
+
+### Description
+
+The searchable prop on table columns allows you to specify whether a column's content is included in search operations.
+When a search is performed, matching text within searchable columns is automatically highlighted in the UI.
+
+Simply add `searchable: true` to any column definition to enable search highlighting for that column.
+
+### Example
+
+Search by first name, last name, or level and see the results highlighted in the 2 first columns.
+
+```tsx
+import { Avatar } from '@wix/design-system';
+import React from 'react';
+import { CollectionPage } from '@wix/patterns/page';
+import {
+  OffsetQuery,
+  Table,
+  useTableCollection,
+} from '@wix/patterns';
+import { contacts } from '@wix/crm';
+
+function Default() {
+
+  const state = useTableCollection<contacts.Contact>({
+    queryName: 'contacts-VisibleColumns',
+    itemName: (item) => `${item.info?.name?.first} ${item.info?.name?.last}`,
+    fetchData: (query: OffsetQuery) => {
+      const { limit, offset, search, filters } = query;
+
+      let queryBuilder = contacts.queryContacts().limit(limit).skip(offset);
+
+      // Filter by search term in name and job title fields
+      if (search && search.trim()) {
+        // Filter locally after fetching since Wix contacts API has specific query limitations
+        return queryBuilder.find().then(({ items = [], totalCount }) => {
+          const searchTerm = search.toLowerCase();
+          const filteredItems = items.filter(contact => {
+            const firstName = contact.info?.name?.first?.toLowerCase() || '';
+            const lastName = contact.info?.name?.last?.toLowerCase() || '';
+            const fullName = `${firstName} ${lastName}`.trim();
+            const jobTitle = contact.info?.jobTitle?.toLowerCase() || '';
+
+            return fullName.includes(searchTerm) || jobTitle.includes(searchTerm);
+          });
+
+          return {
+            items: filteredItems,
+            total: filteredItems.length,
+          };
+        });
+      }
+
+      return queryBuilder.find().then(({ items = [], totalCount: total }) => ({
+        items,
+        total,
+      }));
+    },
+    fetchErrorMessage: () => 'Error fetching contacts',
+    filters: {},
+  });
+
+  return (
+    <CollectionPage height="400px">
+      <CollectionPage.Header title={{ text: 'Contacts' }} />
+      <CollectionPage.Content>
+        <Table
+          state={state}
+          columns={[
+            {
+              id: 'avatar',
+              name: 'Avatar',
+              title: '',
+              width: '50px',
+              render: (contact) => (
+                <Avatar
+                  name={`${contact.info?.name?.first} ${contact.info?.name?.last}`}
+                  imgProps={{ src: contact.info?.picture?.image }}
+                />
+              ),
+            },
+            {
+              id: 'name',
+              title: 'Name',
+              width: '250px',
+              searchable: true, // Mark this column as searchable
+              render: (contact) => `${contact.info?.name?.first} ${contact.info?.name?.last}`,
+            },
+            {
+              id: 'level',
+              title: 'Level',
+              searchable: true, // Mark this column as searchable
+              render: (contact) => contact.info?.jobTitle,
+            },
+            {
+              id: 'lastActivity',
+              title: 'Last Activity',
+              render: (contact) =>
+                contact.lastActivity?.activityDate?.toLocaleString(),
+            },
+          ]}
+        />
+      </CollectionPage.Content>
+    </CollectionPage>
+  );
+}
+```
+