@wix/patterns 1.366.0 → 1.370.0

package/dist/docs/PageWrapper.md

@@ -0,0 +1,50 @@
+# PageWrapper
+
+**Category:** Base Components/Pages/Custom/PageWrapper
+
+## Design
+
+### Description
+
+`PageWrapper` is designed to wrap `` from `@wix/design-system`.
+
+It provides the following capabilities children components:
+
+- Scrollable container reference
+- A slot to render side panels
+- A slot to render overlay components
+
+
+```tsx
+import { PageWrapper } from '@wix/patterns';
+```
+
+---
+
+### Developer examples
+
+### Basic usage
+
+```tsx
+import { PageWrapper } from '@wix/patterns';
+import { Page } from '@wix/design-system';
+import React from 'react';
+
+function BasicPage() {
+  return (
+    <PageWrapper>
+      <Page>
+        <Page.Header title="Page Title" />
+        <Page.Content>Page Content</Page.Content>
+      </Page>
+    </PageWrapper>
+  );
+}
+```
+
+## API
+
+### Required Providers
+
+[WixPatternsProvider](./?path=/story/base-components-providers--wixpatternsprovider)
+

package/dist/docs/PatternsReactRoute.md

@@ -0,0 +1,31 @@
+# PatternsReactRoute
+
+**Category:** Base Components/Pages/Router
+
+## Design
+
+### Description
+
+The `PatternsReactRoute` component defines a route for a Patterns element.
+
+This component extends [`Route`](https://reactrouter.com/en/main/route/route)  from `react-router-dom`.
+
+### Usage
+Wrap `PatternsReactRoute` components with [`PatternsReactRouter`](/?path=/story/base-components-pages-routing--patternsreactrouter).
+
+```tsx
+import { PatternsReactRoute } from '@wix/patterns/router';
+```
+
+## API
+
+### Extends
+
+[React Router Route](https://reactrouter.com/en/main/route/route)
+
+### Props
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `type` | `"collection" \| "other" \| "createEntity" \| "editEntity"` | Yes | - | Page type. Supported values: <br /> - `"collection"` <br /> - `"createEntity"` <br /> - `"editEntity"` <br /> - `"other"` <br /> |
+

package/dist/docs/PatternsReactRouter.md

@@ -0,0 +1,24 @@
+# PatternsReactRouter
+
+**Category:** Base Components/Pages/Router
+
+## Design
+
+### Description
+
+The `PatternsReactRouter` component wraps `PatternsReactRoute` components and defines the base path for those routes.
+
+This component extends [`BrowserRouter`](https://reactrouter.com/en/main/router-components/browser-router) from `react-router-dom`.
+
+### Usage
+
+1. Import `PatternsReactRouter` and `PatternsReactRoute`.
+1. For each page you want to route to, add a [`PatternsReactRoute`](./?path=%2Fstory%2Fbase-components-pages-routing--patternsreactroute) component inside the the `PatternsReactRouter` component.
+
+
+```tsx
+import { PatternsReactRouter } from '@wix/patterns/router';
+```
+
+## API
+

package/dist/docs/PickerContent.md

@@ -0,0 +1,129 @@
+# PickerContent
+
+**Category:** Base Components/Collections/Picker
+
+## API
+
+### Overview
+
+`PickerContent` displays the content of a picker (list of selectable items). It is used inside [`PickerModal`](./?path=/story/base-components-picker--pickermodal) and [`PickerStandalone`](./?path=/story/base-components-picker--pickerstandalone). Configure it via the [`usePickerContent`](./?path=/story/base-components-picker-hooks--usepickercontent) hook.
+
+```tsx
+import { PickerContent } from '@wix/patterns';
+```
+
+---
+
+### Description
+
+#### Overview
+
+Use `` to render a picker inside a ``.
+
+Use a dynamic import to pass your custom picker content component to `usePickerModal.pickerContentComponent`.
+
+#### API
+
+A picker content component accepts props that are being passed by the parent ``.
+
+We should do the following with those props:
+
+- Forward them to `` and to [`usePickerContent`](./?path=/story/base-components-collections-picker-hooks--usepickercontent)
+- If we have filters, we should build the filters schema using `props.modalState.filters` raw parameters (see ["With Filters" example](./?path=/story/base-components-collections-picker--pickermodal))
+- We also must wrap with [``](./?path=/story/base-components-providers--wixpatternsprovider) because the parent doesn't do that as it's just a modal and not a collection component.
+
+##### `usePickerContent`
+
+This hook is a helper hook that helps us to create a picker state object, using the config we already provided to the parent modal `usePickerModal` hook.
+It accepts everything [`useCollection`](./?path=/story/common-hooks--usecollection) accepts minus `fetchData`, `paginationMode` & `limit` which were already provided to the parent modal `usePickerModal` hook.
+
+#### Example
+
+```jsx
+import {
+  PickerContentComponentProps,
+  PickerContent,
+  usePickerContent,
+} from '@wix/patterns';
+import { WixPatternsBMProvider } from '@wix/patterns/bm';
+import { EmptyState } from '@wix/design-system';
+
+/**
+ * @param {PickerContentComponentProps} props
+ */
+export default function ContactsPicker(props) {
+  const state = usePickerContent({
+    queryName: 'ContactsPicker',
+    modalState: props.modalState,
+    fetchErrorMessage: ({ err }) => err.message,
+  });
+
+  return (
+    
+       ({
+          title: contact.name,
+          subtitle: contact.email,
+        })}
+        renderEmptyState={() => (
+          
+        )}
+        // we must forward the props
+        {...props}
+      />
+    
+  );
+}
+```
+
+Then use a dynamic import to pass it to `usePickerModal.pickerContentComponent` (see full example [here](./?activeTab=API&path=%2Fstory%2Fbase-components-collections-picker--pickermodal)):
+
+```typescript jsx
+import { usePickerModal } from '@wix/patterns/bm';
+import { PickerModal } from '@wix/patterns';
+
+export function PickerModalExample() {
+  const state = usePickerModal({
+    pickerContentComponent: () => import('./ContactsPicker'),
+    // ...
+  });
+  return (
+    
+  );
+}
+```
+
+
+### Props
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `state` | `UsePickerContentParams<T, F> \| PickerContentState<T, F>` | Yes | - | A state object created with [`usePickerContent`](./?path=/story/base-components-collections-picker-hooks--usepickercontent) |
+| `selectorListProps` | `Partial<SelectorListContentProps>` | No | - | Additional props to pass to [SelectorList](https://www.docs.wixdesignsystem.com/?path=/story/components-lists--selectorlist), i.e `imageSize`, `imageShape` etc. |
+| `customContentButtonOnClick` | `((param: { onClose: (newItems?: T[]) => void; }) => void)` | No | - | A callback to be called when the custom content button is clicked |
+| `showSelectAllCheckbox` | `boolean` | No | - | Shows "Select All" checkbox as a side action (overrides "customContent" prop). If `multiple={number}` or `multiple={false}` are used, this prop does nothing. |
+| `filterComponent` | `ReactElement<any, string \| JSXElementConstructor<any>>` | No | - | Shows a SingleSelectFilter component in a picker modal to filter items; |
+| `renderItem` | `(item: T, index: number) => Partial<PickerListItemProps>` | Yes | - | A function that render a item row in the selector list |
+| `renderEmptyState` | `((params: { hasAvailableItems: boolean; query: ComputedQuery<F>; }) => ReactElement<any, any> \| null)` | No | - | A render function to be rendered when there're no items to show in the table.<br> You can use the built in [`<CollectionEmptyState />`](./?path=/story/features-display-empty-states--collectionemptystate).<br> The function accepts the following parameters * `hasAvailableItems`: Indicates whether other items might have been shown using other filtering / search * `query`: An instance of [ComputedQuery](./?path=/story/common-types--computedquery) that represents the query that resulted with an empty state |
+| `enablePrimaryButton` | `boolean` | No | - | When set to `true`, the modal primary button will be always enabled. |
+| `search` | `boolean \| CollectionSearchElement` | No | `true` | Displays a search input in the picker modal. Accepts a boolean or a custom CollectionSearch element as a parameter. When passing `false`, no search input is displayed. |
+| `hideSearch` | `boolean` | No | - | @deprecated Use search={false} instead Hides the search input of the picker |
+| `customMaxSelectionLabel` | `((_: { num: number; max: number; }) => string)` | No | - | Function that returns label for multi selection like: '2 items selected (24 max)` This function accepts argument {num: number, max: number} |
+| `renderCustomNotification` | `((data: { selected?: number; total?: number; }) => ReactElement<FloatingNotificationProps, typeof FloatingNotification>) \| undefined` | No | - | Function that returns custom notification that will be displayed in the picker modal. Useful to describe additional information about the selection (for instance how to increase limit of selected items). @param data.selected - number of selected items @param data.total - total number of items |
+| `showSelectedCount` | `boolean` | No | - | Displays count of selected items in <CustomModalLayout /> `sideActions` |
+| `className` | `string` | No | - | Specifies a CSS class name to be appended to the component’s root element. |
+| `dataHook` | `string` | No | - | Applies a data-hook HTML attribute to be used in the tests. |
+| `closeButtonProps` | `ModalCloseButtonProps` | No | - | Close button props. |
+| `helpButtonProps` | `ModalControlButtonProps` | No | - | Help button props. |
+| `onCloseButtonClick` | `MouseEventHandler<HTMLButtonElement>` | No | - | @deprecated use `closeButtonProps` instead. |
+| `onHelpButtonClick` | `MouseEventHandler<HTMLButtonElement>` | No | - | @deprecated use `helpButtonProps` instead. |
+| `skin` | `"standard" \| "premium" \| "destructive"` | No | - | a global skin for the modal, will be applied as stylable state and will affect footer buttons skin. |
+| `autoAdditionalStepOnInitialSelect` | `boolean` | No | - | When true, the picker will start directly on the additional step, skipping the first selection step. The back button will also be hidden. |
+| `additionalStepTitle` | `string` | No | - | The additional step title |
+| `additionalStepSubtitle` | `string` | No | - | The additional step subtitle |
+| `renderAdditionalStepContent` | `((props: { item: T; }) => Element)` | No | - | Defines a function that returns a component to render in the additional step content area, if `hasAdditionalStep` returns `false` this prop is ignored. |
+| `hasAdditionalStep` | `((props: { item: T; }) => boolean)` | No | - | Indicates if selected item has additional step or not |
+| `onBeforeSelectAdditionalStep` | `(() => Promise<unknown>)` | No | - | Defines a callback function just before primaryButtonOnClick callback, returned value will be added as `additionalStepData` in onSelect payload |
+| `continueButtonOnClick` | `((props: { item: T; }) => void)` | No | - | Defines a callback function after user clicks on the continue button to additional step content |
+| `backButtonOnClick` | `((props: { item: T; }) => void)` | No | - | Defines a callback function after user clicks on the back button in the additional step content |
+| `additionalStepOverrides` | `{ extraNode?: ReactNode; extraText?: string; subtitle?: string; image?: ReactNode; enablePrimaryButton?: boolean \| undefined; } \| undefined` | No | - | Additional steps modal content overrides |
+