@wix/patterns 1.364.0 → 1.369.0

package/dist/docs/usePatternsNavigate.md

@@ -0,0 +1,57 @@
+# usePatternsNavigate
+
+**Category:** Base Components/Pages/Router/Hooks/usePatternsNavigate
+
+## Design
+
+### Description
+
+The `usePatternsNavigate` hook provides functions to navigate between pages in a Patterns React application.
+
+
+### Usage
+This hook returns an object with two functions that you can use:
+
+```ts
+const { navigateToCollectionPage, navigateToEntityPage } = usePatternsNavigate();
+```
+
+The `navigateToCollectionPage` function is used to navigate to a collection page. \
+A good usecase for it, is to navigate to a collection page on a breadcrumb click on an entity page. \
+It takes the path of the collection page as an argument:
+
+```ts
+   {
+      if (e.id === 'root') {
+        navigateToCollectionPage({ path: '/entities' });
+      }
+    }}
+  />
+```
+
+The `navigateToEntityPage` function is used to navigate to an entity page. \
+The advantage of using this function is that the header of the entity page, that may contain title, subtitle and breadcrumbs, is being shown right away, without waiting to the fetch of the entity. \
+A good usecase for it, is to navigate to an entity page on an action cell click on a collection page. \
+It takes the path of the entity page, and the entity as arguments:
+
+```ts
+   actionCell={(item) => {
+      return {
+        primaryAction: {
+          text: 'Edit',
+          onClick: () =>
+            navigateToEntityPage({
+              path: `/entities/${item.id}`,
+              entity: item,
+            }),
+          icon: ,
+        }
+      }
+   }}
+```
+
+
+```tsx
+import { usePatternsNavigate } from '@wix/patterns/router';
+```
+

package/dist/docs/usePickerContent.md

@@ -0,0 +1,61 @@
+# usePickerContent
+
+**Category:** Base Components/Collections/Picker/Hooks
+
+## API
+
+### Description
+
+`usePickerContent` is a React hook that creates the collection state for the content displayed inside a [`PickerModal`](./?path=/story/base-components-picker--pickermodal). It extends the collection config (like `filters`, `itemName`) and adds picker-specific options such as `modalState`, `events`, and `initialSelect`.
+
+Define a `PickerContentComponent` that calls `usePickerContent` with the `modalState` received via props, then pass it to `usePickerModal` as `pickerContentComponent`.
+
+```tsx
+import { usePickerContent } from '@wix/patterns';
+```
+
+---
+
+### Example
+
+```tsx
+import { usePickerContent, PickerContent } from '@wix/patterns';
+
+const MyPickerContent = ({ modalState }) => {
+  const contentState = usePickerContent({
+    modalState,
+    filters: { status: stringFilter() },
+    fetchData: (query) => fetchItems(query),
+    itemKey: (item) => item.id,
+    itemName: (item) => item.name,
+  });
+
+  return (
+     item.name },
+      ]}
+    />
+  );
+};
+```
+
+### Returns
+
+The same config object, enriched with internal collection state. Pass it to ``.
+
+### Props
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `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> & PickerEvents<T, 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. Optional callbacks for various events of the picker content lifecycle Extends [CollectionEvents](./?path=/story/common-hooks--usecollection) `onReady` - when picker content is ready `onInitialFetchError` - when there's an error loading the picker. When the callback returns a promise, the initial loader will keep showing until the promise is resolved (useful for cases of redirect to login for example). `onItemSelectClick` - when clicking on an item checkbox / radio button |
+| `modalState` | `PickerModalState<T, F>` | Yes | - | The modal state object passed from `<PickerModal />` |
+| `initialSelect` | `true \| ((item: T, index: number) => boolean) \| PickerSelection<T>` | No | - | Sets initial selection to the picker. Either:<br> - `boolean` - Sets the first item as selected. - `function` - A predicate for items to be selected in the picker. - `object` (Older API, new API below) - `selectedValues` - Specific selection - `isSelectAll` - All selected - `uncheckedValues` - Optional unchecked items - `partiallySelectedIds` - Items that should have 3rd indeterminate status - `object` (New API) - `values` - Initial selected values. Using this prop it's possible to specify the initial status of each pre-selected value. - `defaultStatus` - Forces this status on all items and all future items that will be loaded to the picker when scrolling. |
+

package/dist/docs/usePickerModal.md

@@ -0,0 +1,68 @@
+# usePickerModal
+
+**Category:** Base Components/Collections/Picker/Hooks
+
+## API
+
+### Description
+
+`usePickerModal` is a React hook that creates the state for a [`PickerModal`](./?path=/story/base-components-picker--pickermodal). It accepts picker configuration (query name, fetch data, filters, pagination, selection callback) and a lazy-loaded `pickerContentComponent`. Import from the entry point that matches your environment.
+
+```tsx
+import { usePickerModal } from '@wix/patterns/bm';
+```
+
+```tsx
+import { usePickerModal } from '@wix/patterns/giza';
+```
+
+```tsx
+import { usePickerModal } from '@wix/patterns/essentials';
+```
+
+---
+
+### Example
+
+```tsx
+import { usePickerModal, PickerModal } from '@wix/patterns/bm';
+
+const pickerState = usePickerModal({
+  queryName: 'my-picker',
+  fetchData: (query) => fetchItems(query),
+  limit: 50,
+  onSelect: (items) => handleSelect(items),
+  pickerContentComponent: () => import('./MyPickerContent'),
+});
+
+return (
+  <>
+    Open Picker
+    
+  
+);
+```
+
+### Returns
+
+`PickerModalState` — pass it to ``.
+
+### Props
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `environment` | `Environment` | Yes | - | The user's environment - `language` - preferable language for the user |
+| `errorMonitor` | `ErrorMonitor` | Yes | - | A `ErrorMonitor` instance `@wix/fe-essentials/error-monitor` |
+| `biLoggerFactory` | `(options?: (FactoryOptions & { trackSession?: boolean \| "force" \| undefined; }) \| undefined) => Factory` | Yes | - | A `BILoggerFactory` instance `@wix/fe-essentials/bi` |
+| `limit` | `number` | No | - | Number of items to fetch on each page |
+| `filters` | `Partial<RawFiltersParams<F>>` | No | - | Defines the initial values and config for filters that the collection supports. For example: { premium: {initialValue: 'true'} } |
+| `fetchInitialProps` | `(() => Promise<unknown>)` | No | - | Optional function that loads more dependencies required for the content of the modal to show. The modal will keep showing a loader when this promise is still pending. For example custom i18n translations. |
+| `onSelect` | `(items: T[], options: OnSelectOptions<T>) => unknown` | Yes | - | A function being called after clicking the primary button of the modal. It accepts the following parameters: - `items` - The items that were selected in the modal's internal selector list - `options.isSelectAll` - Indicates the user toggled on the "Select All" checkbox (relevant only when `showSelectAllCheckbox` is passed to `<PickerContent />`) - `options.selectedCount` - The number of items the user selected. Subtracts from total count the items that were unchecked after toggling on the "Select All" checkbox - `options.uncheckedValues` - The items the user unchecked after toggling on the "Select All" checkbox (relevant only when `showSelectAllCheckbox` is passed to `<PickerContent />`) - `options.partiallySelectedIds` - Selected items in indeterminate status |
+| `pickerContentComponent` | `() => Promise<{ default: PickerContentComponent<T, F>; }>` | Yes | - | A function that returns a promise of dynamically imported component that renders [`<PickerContent `/>](./?path=/story/base-components-collections-picker--pickercontent) internally |
+| `events` | `PickerModalEvents` | No | - | Optional callbacks for various events of the picker modal lifecycle `onError` - when there's an error fetching initial data, picker content chunk or initial props. |
+| `paginationMode` | `"cursor" \| "offset"` | No | `offset` | Indicates what type of pagination the `fetchData` function supports.<br> In case the server accepts the `query.offset` parameter - pass `'offset'` In case the server returns a `cursor` from `fetchData` - pass `'cursor'` |
+| `queryName` | `string` | Yes | - | The query name used for cache purposes. This should be a unique value per API endpoint consumed inside the `fetchData` function.<br> It's recommended to use the [Fqdn](https://bo.wix.com/wix-docs/rnd/p13n-guidelines---aips/guidance-aips/wix-api-basics/[1009]-fqdn) of the service used in `fetchData` as `queryName` |
+| `fetchData` | `((query: ComputedQuery<F>) => Promise<DataResultRaw<T>>)` | No | - | A function that integrates with the API to fetch the collection data from.<br> Accepts the following parameters: - `query`: A [ComputedQuery](./?path=/story/common-types--computedquery) instance. Holds all the relevant variables to query the server API with. The function must return a promise of [DataResultRaw](./?path=/story/common-models--dataresultraw) |
+| `skipFirstPagePrefetch` | `boolean` | No | - | In the picker modal, the data is prefetched before the user opens the modal. This flag disables this behavior. |
+| `disableAutoSelectOnSingleItem` | `boolean` | No | - | A flag to disable default behavior when fetch data returns a single item. Instead of calling onSelect a dialog will be opened. |
+

package/dist/docs/usePickerStandalone.md

@@ -0,0 +1,56 @@
+# usePickerStandalone
+
+**Category:** Base Components/Collections/Picker/Hooks
+
+## API
+
+### Description
+
+`usePickerStandalone` is a React hook that creates the state for a [`PickerStandalone`](./?path=/story/base-components-picker--pickerstandalone) component — a full-page picker for selecting an item and navigating to a destination URL. It extends [`useCollection`](./?path=/story/common-hooks--usecollection) with picker-specific options like `defaultDestinationUrl` and `initialSelect`.
+
+```tsx
+import { usePickerStandalone } from '@wix/patterns';
+```
+
+### Extends
+
+[`useCollection`](./?path=/story/common-hooks--usecollection)
+
+---
+
+### Example
+
+```tsx
+import { usePickerStandalone, PickerStandalone } from '@wix/patterns';
+
+const state = usePickerStandalone({
+  queryName: 'site-picker',
+  fetchData: (query) => fetchSites(query),
+  itemKey: (site) => site.id,
+  itemName: (site) => site.name,
+  limit: 20,
+  defaultDestinationUrl: (site) => `/site/${site.id}/dashboard`,
+});
+
+return (
+   site.name },
+    ]}
+  />
+);
+```
+
+### Returns
+
+`PickerStandaloneState` — pass it to ``.
+
+### Props
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `noItemsAvailableDestinationUrl` | `string` | No | - | URL to navigate to when there are no items available in the collection. |
+| `initialSelect` | `true \| ((item: T, index: number) => boolean)` | No | - | A predicate for an item to be selected in the picker. Pass `true` to select the first item. |
+| `defaultDestinationUrl` | `string \| ((item: T) => string)` | Yes | - | A destination URL or callback to redirect to when the user selects an item. Will be used when no query param override was provided. |
+| `urlSegmentPropertyMap` | `Record<string, (keyof T)[]>` | No | - | Map of query params to object properties to allow for URL filtering. For example - `urlSegmentPropertyMap: { msid: ['metaSiteId'] }` will add support for `?msid=123` query params to filter `metaSiteId`. |
+| `events` | `PickerStandaloneEvents<T, F>` | No | - | Optional callbacks for various events of the picker & collection state lifecycle:<br> - `onSingleItemAutoNavigation` - when the picker is opened and auto-selects the only item in the collection<br> - `onContinueToDestinationUrl` - when the user selects an item and submits<br> - `onReady` - fires when the picker is ready to be interacted with<br> - `onInitialPageFetched` - when the first page of items is ready<br> - `onSearch` - when fetching new items as a result new search<br> - `onSearchResults` - when the result of a search is ready<br> - `onNewPageStart` - when starting to load the next page of items<br> - `onNewPageAdded` - when the result of the next page is ready |
+| `logoType` | `"wix" \| "editorx"` | No | - | The type of logo to display in the picker. |
+

package/dist/docs/useSelector.md

@@ -0,0 +1,181 @@
+# useSelector
+
+**Category:** Common/Hooks
+
+## Design
+
+### Description
+
+`useSelector` is a custom hook designed for React applications that doesn't use MobX for state management. Its primary purpose is to simplify the process of getting updated values from the MobX state within functional components. By creating a reactive binding between a MobX selector function and a React component, useSelector allows components to subscribe to changes in specific parts of the MobX state and automatically update when those parts change.
+
+You should use useSelector when you want to access and use specific data from the MobX store in a React functional component.
+
+WixPatterns uses internally Mobx state management library.
+It also exposes Mobx state with custom hooks like `useTableCollection` and `useWidgetsFormContext`.
+For applications that doesn't use MobX and want the values from MobX to be updated, and not staled, the `useSelector` custom hook is for the rescue.
+
+
+```tsx
+import { useSelector } from '@wix/patterns';
+```
+
+### Basic
+
+Add a filter and see the value of title changes
+
+```tsx
+import { Avatar, Page } from '@wix/design-system';
+import React from 'react';
+import { CollectionPage } from '@wix/patterns/page';
+import {
+  Table,
+  useSelector,
+  stringsArrayFilter,
+  idNameArrayFilter,
+  CollectionToolbarFilters,
+  MultiSelectCheckboxFilter,
+  useTableCollection,
+  useStaticListFilterCollection,
+  Filter,
+  SingleSelectFilter,
+  OffsetQuery,
+} from '@wix/patterns';
+import { contacts } from '@wix/crm';
+import { subDays } from 'date-fns';
+
+interface Duration {
+  id: string;
+  name: string;
+  days: number | null;
+}
+
+type ContactsFilters = {
+  lastActivity: Filter<Duration[]>;
+  level: Filter<string[]>;
+};
+
+function UseSelectorExample() {
+
+  const state = useTableCollection<contacts.Contact, ContactsFilters>({
+    queryName: 'contacts-useSelector',
+    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.level) {
+        queryBuilder = queryBuilder.in('info.jobTitle', filters.level);
+      }
+
+      const lastActivityDays = filters.lastActivity?.[0]?.days;
+      if (lastActivityDays) {
+        queryBuilder = queryBuilder.gt(
+          'lastActivity.activityDate',
+          subDays(new window.Date(), lastActivityDays),
+        );
+      }
+
+      return queryBuilder.find().then(({ items = [], totalCount: total }) => ({
+        items,
+        total,
+      }));
+    },
+    itemName: (item) => `${item.info?.name?.first} ${item.info?.name?.last}`,
+    fetchErrorMessage: () => 'Error fetching contacts',
+    filters: {
+      level: stringsArrayFilter(),
+      lastActivity: idNameArrayFilter(),
+    },
+  });
+
+  const collection = state.collection;
+
+  const lastActivityCollection = useStaticListFilterCollection(
+    collection.filters.lastActivity,
+    [
+      { id: 'w', name: 'Week', days: 7 },
+      { id: 'm', name: 'Month', days: 30 },
+      { id: 'y', name: 'Year', days: 365 },
+      { id: 'o', name: 'Other', days: null },
+    ],
+  );
+
+  const levelsCollection = useStaticListFilterCollection(
+    collection.filters.level,
+    [
+      'Beginner',
+      'Amateur',
+      'Semi-Pro',
+      'Professional',
+      'World Class',
+      'Legendary',
+      'Ultimate',
+    ],
+  );
+
+  // hasActiveFilters will have the updated value from MobX store
+  const hasActiveFilters = useSelector(() => collection.query.hasActiveFilters);
+
+  return (
+    <CollectionPage height="400px">
+      <CollectionPage.Header
+        title={{ text: `hasActiveFilters value:${hasActiveFilters}` }}
+      />
+      <Page.Content>
+        <Table
+          state={state}
+          filters={
+            <CollectionToolbarFilters>
+              <MultiSelectCheckboxFilter
+                accordionItemProps={{ label: 'Level' }}
+                popoverProps={{ appendTo: 'window' }}
+                filter={collection.filters.level!}
+                collection={levelsCollection}
+                renderItem={(level) => ({ title: level })}
+              />
+              <SingleSelectFilter
+                filter={collection.filters.lastActivity!}
+                placeholder="Select Last Activity"
+                accordionItemProps={{ label: 'Last Activity' }}
+                collection={lastActivityCollection}
+              />
+            </CollectionToolbarFilters>
+          }
+          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: 'Level',
+              render: (contact) => contact.info?.jobTitle,
+            },
+            {
+              title: 'Last Activity',
+              render: (contact) =>
+                contact.lastActivity?.activityDate?.toLocaleString(),
+            },
+          ]}
+        />
+      </Page.Content>
+    </CollectionPage>
+  );
+}
+```
+

package/dist/docs/useSettingsPage.md

@@ -0,0 +1,54 @@
+# useSettingsPage
+
+**Category:** Base Components/Pages/Settings Page/Hooks/useSettingsPage
+
+## API
+
+### Overview
+
+A React hook that creates the state for a [`SettingsPage`](./?path=/story/base-components-pages-settings-page--settingspage). Configure settings fetching, save/cancel flow, form integration, and toasts. The returned [`SettingsPageState`](./?path=/story/base-components-pages-settings-page-state--settingspagestate) is passed to ``.
+
+```tsx
+import { useSettingsPage } from '@wix/patterns/page';
+```
+
+### Example
+
+```tsx
+import { useSettingsPage, SettingsPage } from '@wix/patterns/page';
+import { useForm } from 'react-hook-form';
+
+const form = useForm({ defaultValues: { notifications: true } });
+
+const state = useSettingsPage({
+  fetch: () => api.getSettings().then((settings) => ({ settings })),
+  onSave: () => api.saveSettings(form.getValues()),
+  onCancel: () => form.reset(),
+  form,
+  container,
+});
+
+return (
+  
+    
+    
+      ...
+    
+  
+);
+```
+
+### Returns
+
+[SettingsPageState](./?path=/story/base-components-pages-settings-page-state--settingspagestate)
+
+### Props
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `fetch` | `() => Promise<{ settings: T \| undefined; }>` | Yes | - | A function that fetches the settings data. @returns a promise that resolves to an object containing the settings. |
+| `onSave` | `() => Promise<void>` | Yes | - | A function to handle the save action. |
+| `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. |
+| `onCancel` | `() => Promise<void>` | Yes | - | A function to handle the cancel action. |
+

package/dist/docs/useSettingsPageContext.md

@@ -0,0 +1,28 @@
+# useSettingsPageContext
+
+**Category:** Base Components/Pages/Settings Page/Hooks/useSettingsPageContext
+
+## API
+
+### Overview
+
+A React hook that retrieves [`SettingsPageState`](./?path=/story/base-components-pages-settings-page-state--settingspagestate) from React context. Use it in any child component rendered within [`SettingsPage`](./?path=/story/base-components-pages-settings-page--settingspage) to access the page state without prop-drilling.
+
+```tsx
+import { useSettingsPageContext } from '@wix/patterns/page';
+```
+
+### Example
+
+```tsx
+function MySettingsCard() {
+  const state = useSettingsPageContext();
+  // Access state.form, state.settings, etc.
+  return Current value: {state.settings?.theme};
+}
+```
+
+### Returns
+
+[SettingsPageState](./?path=/story/base-components-pages-settings-page-state--settingspagestate)
+