@wix/patterns 1.458.0 → 1.460.0

package/dist/docs/PickerModal.md

@@ -19,105 +19,7 @@ import { PickerModal } from '@wix/patterns';
 
 ### Multi Select
 
-```tsx
-import { Avatar, EmptyState, Page } from '@wix/design-system';
-import React from 'react';
-import { queryContacts } from '@wix/ambassador-contacts-v4-contact/http';
-import {
-  OffsetQuery,
-  PickerContent,
-  PickerContentComponentProps,
-  PickerModal,
-  PickerModalOpenButton,
-  stringsArrayFilter,
-  usePickerContent,
-  Filter,
-} from '@wix/patterns';
-import { usePickerModal } from '@wix/patterns/essentials';
-import { useHttpClient } from '@wix/fe-essentials/react';
-import { Contact } from '@wix/ambassador-contacts-v4-contact/types';
-
-type ContactsFilters = {
-  level: Filter<string[]>;
-};
-
-function PickerModalMultiSelect() {
-  const httpClient = useHttpClient();
-
-  // Usually we will extract this component to a separate file and use dynamic import when passing it as `pickerContentComponent`
-  const pickerContentComponent = async () => ({
-    default: function ContactsPicker(
-      props: PickerContentComponentProps<Contact, ContactsFilters>,
-    ) {
-      const state = usePickerContent({
-        fetchErrorMessage: ({ err }) => String(err),
-        modalState: props.modalState,
-        filters: {
-          level: stringsArrayFilter(props.modalState.filters.level),
-        },
-        itemName: (contact) => contact.id as string,
-      });
-
-      return (
-        <PickerContent
-          state={state}
-          showSelectAllCheckbox
-          renderItem={(contact) => ({
-            subtitle: contact.level,
-            image: <Avatar size="size60" shape="square" name={contact.name} />,
-          })}
-          {...props}
-        />
-      );
-    },
-  });
-
-  const state = usePickerModal<Contact, ContactsFilters>({
-    queryName: 'PickerModalSelectAll',
-    fetchData: (query: OffsetQuery<ContactsFilters>) => {
-      const { limit, offset, search, filters } = query;
-      return httpClient
-        .request(
-          queryContacts({
-            query: { paging: { limit, offset }, filter: filters },
-            search,
-          }),
-        )
-        .then(({ data: { contacts, pagingMetadata } }) => ({
-          items: contacts as Contact[],
-          total: pagingMetadata?.total,
-        }));
-    },
-    limit: 100,
-    pickerContentComponent,
-    onSelect: (_contacts) => {
-      // Do something with contacts
-    },
-  });
-
-  return (
-    <Page>
-      <Page.Header
-        title="Picker Modal Example"
-        actionsBar={
-          <>
-            <PickerModalOpenButton state={state}>
-              Select Contacts
-            </PickerModalOpenButton>
-
-            <PickerModal
-              title="Select Contacts"
-              state={state}
-              multiple
-              renderError={(err) => <EmptyState title={String(err)} />}
-            />
-          </>
-        }
-      />
-    </Page>
-  );
-}
-```
+Example code: read `dist/docs/PickerModal/multi-select.tsx`
 
 ---
 
@@ -125,106 +27,7 @@ function PickerModalMultiSelect() {
 
  Radio button selection, the user can select one item only
 
-```tsx
-import { Avatar, EmptyState, Page } from '@wix/design-system';
-import React from 'react';
-import { queryContacts } from '@wix/ambassador-contacts-v4-contact/http';
-import {
-  OffsetQuery,
-  PickerContent,
-  PickerContentComponentProps,
-  PickerModal,
-  PickerModalOpenButton,
-  usePickerContent,
-} from '@wix/patterns';
-import {
-  WixPatternsEssentialsProvider,
-  usePickerModal,
-} from '@wix/patterns/essentials';
-import { useHttpClient } from '@wix/fe-essentials/react';
-import { Contact } from '@wix/ambassador-contacts-v4-contact/types';
-
-function PickerModalSingleSelectExample() {
-  const httpClient = useHttpClient();
-
-  // Usually we will extract this component to a separate file and use dynamic import when passing it as `pickerContentComponent`
-  const pickerContentComponent = async () => ({
-    default: function ContactsPicker(
-      props: PickerContentComponentProps<Contact>,
-    ) {
-      const state = usePickerContent({
-        modalState: props.modalState,
-        fetchErrorMessage: ({ err }) => String(err),
-        itemName: (contact) => contact.id as string,
-      });
-
-      return (
-        // wrap with a provider that suits your environment
-        <WixPatternsEssentialsProvider>
-          <PickerContent
-            state={state}
-            renderItem={(contact) => ({
-              subtitle: contact.level,
-              image: (
-                <Avatar size="size60" shape="square" name={contact.name} />
-              ),
-            })}
-            renderEmptyState={() => (
-              <EmptyState title="You don’t have any contacts that support this action." />
-            )}
-            {...props}
-          />
-        </WixPatternsEssentialsProvider>
-      );
-    },
-  });
-
-  const state = usePickerModal<Contact>({
-    queryName: 'PickerModalSingleSelectExample',
-    fetchData: (query: OffsetQuery) => {
-      const { limit, offset, search, filters } = query;
-      return httpClient
-        .request(
-          queryContacts({
-            query: { paging: { limit, offset }, filter: filters },
-            search,
-          }),
-        )
-        .then(({ data: { contacts, pagingMetadata } }) => ({
-          items: contacts as Contact[],
-          total: pagingMetadata?.total,
-        }));
-    },
-    limit: 25,
-    // Usually we will use dynamic import, i.e pickerContentComponent: () => import('./ContactsPicker')
-    pickerContentComponent,
-    onSelect: (_contacts) => {
-      // Do something with contacts
-    },
-  });
-
-  return (
-    <Page>
-      <Page.Header
-        title="Picker Modal Example"
-        actionsBar={
-          <>
-            <PickerModalOpenButton state={state}>
-              Select a Contact
-            </PickerModalOpenButton>
-
-            <PickerModal
-              title="Select a Contact"
-              state={state}
-              renderError={(err) => <EmptyState title={String(err)} />}
-            />
-          </>
-        }
-      />
-    </Page>
-  );
-}
-```
+Example code: read `dist/docs/PickerModal/single-selection.tsx`
 
 ---
 
@@ -232,128 +35,7 @@ function PickerModalSingleSelectExample() {
 
  When the user opens the modal some of the items are already selected
 
-```tsx
-import { Avatar, EmptyState, Page } from '@wix/design-system';
-import React from 'react';
-import { queryContacts } from '@wix/ambassador-contacts-v4-contact/http';
-import {
-  OffsetQuery,
-  PickerContent,
-  PickerContentComponentProps,
-  PickerModal,
-  PickerModalOpenButton,
-  usePickerContent,
-} from '@wix/patterns';
-import {
-  WixPatternsEssentialsProvider,
-  usePickerModal,
-} from '@wix/patterns/essentials';
-import { useHttpClient } from '@wix/fe-essentials/react';
-import { Contact } from '@wix/ambassador-contacts-v4-contact/types';
-
-function PickerModalInitialSelect() {
-  const httpClient = useHttpClient();
-
-  const selection = React.useRef<Contact[]>([]);
-
-  // Usually we will extract this component to a separate file and use dynamic import when passing it as `pickerContentComponent`
-  const pickerContentComponent = async () => ({
-    default: function ContactsPicker(
-      props: PickerContentComponentProps<Contact>,
-    ) {
-      const state = usePickerContent({
-        modalState: props.modalState,
-        fetchErrorMessage: ({ err }) => String(err),
-        initialSelect: {
-          defaultStatus: 'unchecked',
-          values: selection.current.map((value) => ({
-            value,
-            status: 'checked',
-          })),
-        },
-        itemName: (contact) => contact.id as string,
-      });
-
-      return (
-        // wrap with a provider that suits your environment
-        <WixPatternsEssentialsProvider>
-          <PickerContent
-            state={state}
-            renderItem={(contact) => ({
-              subtitle: contact.level,
-              image: (
-                <Avatar size="size60" shape="square" name={contact.name} />
-              ),
-            })}
-            renderEmptyState={() => (
-              <EmptyState title="You don’t have any contacts that support this action." />
-            )}
-            {...props}
-          />
-        </WixPatternsEssentialsProvider>
-      );
-    },
-  });
-
-  const state = usePickerModal<Contact>({
-    queryName: 'PickerModalExample',
-    fetchData: (query: OffsetQuery) => {
-      const { limit, offset, search, filters } = query;
-      return httpClient
-        .request(
-          queryContacts({
-            query: { paging: { limit, offset }, filter: filters },
-            search,
-          }),
-        )
-        .then(({ data: { contacts, pagingMetadata } }) => ({
-          items: contacts as Contact[],
-          total: pagingMetadata?.total,
-        }));
-    },
-    fetchInitialProps: () => {
-      return httpClient
-        .request(
-          queryContacts({
-            query: { paging: { limit: 25, offset: 0 }, filter: {} },
-          }),
-        )
-        .then(({ data: { contacts = [] } }) => {
-          selection.current = contacts.slice(3, 6);
-        });
-    },
-
-    limit: 25,
-    // Usually we will use dynamic import, i.e pickerContentComponent: () => import('./ContactsPicker')
-    pickerContentComponent,
-    onSelect: (_contacts) => {
-      // Do something with contacts
-    },
-  });
-
-  return (
-    <Page>
-      <Page.Header
-        title="Picker Modal Example"
-        actionsBar={
-          <>
-            <PickerModalOpenButton state={state}>
-              Select a Contact
-            </PickerModalOpenButton>
-
-            <PickerModal
-              title="Select a Contact"
-              state={state}
-              multiple
-              renderError={(err) => <EmptyState title={String(err)} />}
-            />
-          </>
-        }
-      />
-    </Page>
-  );
-}
-```
+Example code: read `dist/docs/PickerModal/pre-selected-item.tsx`
 
 ---
 
@@ -361,147 +43,7 @@ function PickerModalInitialSelect() {
 
 You can add a `SingleSelectFilter` to your Picker Modal to filter its contents. To have it you need to pass `SingleSelectFilter` to the `filterComponent` prop in `PickerContent` and define the filter behavior when creating a state (check out `usePickerContent` and `usePickerModal`) in the example.
 
-```tsx
-import { Avatar, EmptyState, Page } from '@wix/design-system';
-import React from 'react';
-import { queryContacts } from '@wix/ambassador-contacts-v4-contact/http';
-import {
-  OffsetQuery,
-  PickerContent,
-  PickerContentComponentProps,
-  PickerModal,
-  PickerModalOpenButton,
-  usePickerContent,
-  idNameArrayFilter,
-  SingleSelectFilter,
-  Filter,
-  useStaticListFilterCollection,
-} from '@wix/patterns';
-import {
-  WixPatternsEssentialsProvider,
-  usePickerModal,
-} from '@wix/patterns/essentials';
-import { useHttpClient } from '@wix/fe-essentials/react';
-import { Contact } from '@wix/ambassador-contacts-v4-contact/types';
-
-type ContactFilters = {
-  level: Filter<{ id: string; name: string }[]>;
-};
-
-function PickerModalFilterDropdownExample() {
-  const httpClient = useHttpClient();
-
-  // Usually we will extract this component to a separate file and use dynamic import when passing it as `pickerContentComponent`
-  const pickerContentComponent = async () => ({
-    default: function ContactsPicker(
-      props: PickerContentComponentProps<Contact, ContactFilters>,
-    ) {
-      const state = usePickerContent({
-        modalState: props.modalState,
-        fetchErrorMessage: ({ err }) => String(err),
-        filters: {
-          level: idNameArrayFilter(props.modalState.filters.level),
-        },
-        itemName: (contact) => contact.id as string,
-      });
-
-      const filterTypesCollection = useStaticListFilterCollection(
-        state.filters.level,
-        [
-          { id: '1', name: 'Beginner' },
-          { id: '2', name: 'Amateur' },
-          { id: '3', name: 'Semi-Pro' },
-          { id: '4', name: 'Professional' },
-          { id: '5', name: 'World Class' },
-          { id: '6', name: 'Legendary' },
-          { id: '7', name: 'Ultimate' },
-          { id: '8', name: 'Ye' },
-        ],
-      );
-
-      return (
-        // wrap with a provider that suits your environment
-        <WixPatternsEssentialsProvider>
-          <PickerContent
-            filterComponent={
-              <SingleSelectFilter
-                filter={state?.filters?.level}
-                collection={filterTypesCollection}
-                renderItem={(item, index) => ({
-                  title: item.name,
-                })}
-              />
-            }
-            state={state}
-            renderItem={(contact) => ({
-              subtitle: contact.level,
-              image: (
-                <Avatar size="size60" shape="square" name={contact.name} />
-              ),
-            })}
-            {...props}
-          />
-        </WixPatternsEssentialsProvider>
-      );
-    },
-  });
-
-  const state = usePickerModal<Contact, ContactFilters>({
-    queryName: 'PickerModalSingleSelectExample',
-    filters: {
-      level: {
-        initialValue: [{ id: '1', name: 'Beginner' }],
-      },
-    },
-    fetchData: (query: OffsetQuery<ContactFilters>) => {
-      const { limit, offset, search, filters } = query;
-      return httpClient
-        .request(
-          queryContacts({
-            query: {
-              paging: { limit, offset },
-              filter: { level: filters.level?.[0].id },
-            },
-            search,
-          }),
-        )
-        .then(({ data: { contacts, pagingMetadata } }) => {
-          return {
-            items: contacts as Contact[],
-            total: pagingMetadata?.total,
-          };
-        });
-    },
-    limit: 25,
-    // Usually we will use dynamic import, i.e pickerContentComponent: () => import('./ContactsPicker')
-    pickerContentComponent,
-    onSelect: (_contacts) => {
-      // Do something with contacts
-    },
-  });
-
-  return (
-    <Page>
-      <Page.Header
-        title="Picker Modal Example"
-        actionsBar={
-          <>
-            <PickerModalOpenButton state={state}>
-              Select a Contact
-            </PickerModalOpenButton>
-
-            <PickerModal
-              title="Select a Contact"
-              state={state}
-              renderError={(err) => <EmptyState title={String(err)} />}
-            />
-          </>
-        }
-      />
-    </Page>
-  );
-}
-```
+Example code: read `dist/docs/PickerModal/with-filter-dropdown.tsx`
 
 ---
 
@@ -509,107 +51,7 @@ function PickerModalFilterDropdownExample() {
 
 You can override the search behavior using the `search` prop. Pass `false` to hide search, or a custom `<CollectionSearch />`
 
-```tsx
-import { Avatar, EmptyState, Page } from '@wix/design-system';
-import React from 'react';
-import { queryContacts } from '@wix/ambassador-contacts-v4-contact/http';
-import {
-  OffsetQuery,
-  PickerContent,
-  PickerContentComponentProps,
-  PickerModal,
-  PickerModalOpenButton,
-  stringsArrayFilter,
-  usePickerContent,
-  Filter,
-  CollectionSearch,
-} from '@wix/patterns';
-import { usePickerModal } from '@wix/patterns/essentials';
-import { useHttpClient } from '@wix/fe-essentials/react';
-import { Contact } from '@wix/ambassador-contacts-v4-contact/types';
-
-type ContactsFilters = {
-  level: Filter<string[]>;
-};
-
-function SearchOverride() {
-  const httpClient = useHttpClient();
-
-  // Usually we will extract this component to a separate file and use dynamic import when passing it as `pickerContentComponent`
-  const pickerContentComponent = async () => ({
-    default: function ContactsPicker(
-      props: PickerContentComponentProps<Contact, ContactsFilters>,
-    ) {
-      const state = usePickerContent({
-        fetchErrorMessage: ({ err }) => String(err),
-        modalState: props.modalState,
-        filters: {
-          level: stringsArrayFilter(props.modalState.filters.level),
-        },
-        itemName: (contact) => contact.id as string,
-      });
-
-      return (
-        <PickerContent
-          state={state}
-          search={<CollectionSearch placeholder="Custom placeholder..." />}
-          showSelectAllCheckbox
-          renderItem={(contact) => ({
-            subtitle: contact.level,
-            image: <Avatar size="size60" shape="square" name={contact.name} />,
-          })}
-          {...props}
-        />
-      );
-    },
-  });
-
-  const state = usePickerModal<Contact, ContactsFilters>({
-    queryName: 'PickerModalSelectAll',
-    fetchData: (query: OffsetQuery<ContactsFilters>) => {
-      const { limit, offset, search, filters } = query;
-      return httpClient
-        .request(
-          queryContacts({
-            query: { paging: { limit, offset }, filter: filters },
-            search,
-          }),
-        )
-        .then(({ data: { contacts, pagingMetadata } }) => ({
-          items: contacts as Contact[],
-          total: pagingMetadata?.total,
-        }));
-    },
-    limit: 100,
-    pickerContentComponent,
-    onSelect: (_contacts) => {
-      // Do something with contacts
-    },
-  });
-
-  return (
-    <Page>
-      <Page.Header
-        title="Picker Modal Example"
-        actionsBar={
-          <>
-            <PickerModalOpenButton state={state}>
-              Select Contacts
-            </PickerModalOpenButton>
-
-            <PickerModal
-              title="Select Contacts"
-              state={state}
-              multiple
-              renderError={(err) => <EmptyState title={String(err)} />}
-            />
-          </>
-        }
-      />
-    </Page>
-  );
-}
-```
+Example code: read `dist/docs/PickerModal/search-override.tsx`
 
 ## API
 
@@ -632,50 +74,14 @@ Integrating with `PickerModal` is usually done by the following steps
 
 
 
-### Extends
-
-[CustomModalLayoutProps](https://www.docs.wixdesignsystem.com/?path=/story/components-overlays-modal--custommodallayout)
-
 ### Props
 
-| Prop | Type | Required | Default | Description |
-|------|------|----------|---------|-------------|
-| `modalProps` | `Partial<ModalProps>` | No | - | Optional props to forward to `Modal` component |
-| `state` | `PickerModalState<T, F>` | Yes | - | State object created with [`usePickerModal`](./?path=/story/base-components-collections-picker-hooks--usepickermodal) |
-| `renderError` | `(params: { err: unknown; isOnline: boolean; }) => ReactElement<any, string \| JSXElementConstructor<any>>` | Yes | - | A component to be rendered in the modal content when there's a failure fetching the data @param params @param params.err - The original failure error object @param params.isOnline - Indicates whether internet connection is available or not |
-| `multiple` | `MultipleSelection` | No | - | Limits the number of items that can be selected.<br> Either a boolean or a number. A number indicates the maximum number of selections, `true` indicates no limit, `false` indicates only 1 item (radio button will be shown instead of checkboxes) |
-| `title` | `ReactNode` | No | - | Sets text title for the modal; can be used in conjunction with other components |
-| `subtitle` | `ReactNode` | No | - | Sets text subtitle for the modal; can be used in conjunction with other components |
-| `content` | `ReactNode` | No | - | Sets the modal's main content, rendered in the middle scrollable area. When omitted, `children` are rendered in this area instead. |
-| `children` | `ReactNode` | No | - | Sets the modal's content. Rendered in the middle scrollable area when `content` is omitted; when `content` is provided, rendered directly inside the modal root after the layout blocks, so fully custom nodes can be mounted and animated. |
-| `primaryButtonText` | `ReactNode` | No | - | Sets text label or other content (e.g., <Loader/>) for the primary button |
-| `primaryButtonProps` | `Omit<ButtonProps, "internalDataHook">` | No | - | Passes on any `<Button/>` properties on the primary button |
-| `primaryButtonOnClick` | `(() => void)` | No | - | Defines a call-back function after user clicks on the primary button |
-| `primaryButtonTooltipProps` | `(TooltipCommonProps & { content: ReactNode; })` | No | - | Passes on any `<Tooltip/>` properties on the primary button tooltip |
-| `secondaryButtonText` | `ReactNode` | No | - | Sets text label for the secondary button |
-| `secondaryButtonProps` | `Omit<ButtonProps, "internalDataHook">` | No | - | Passes on any `<Button/>` properties on the secondary button |
-| `secondaryButtonOnClick` | `(() => void)` | No | - | Defines a call-back function after user clicks on the secondary button |
-| `actionsSize` | `"small" \| "tiny" \| "medium" \| "large"` | No | - | Sets the size of action buttons |
-| `sideActions` | `ReactNode` | No | - | Contains a checkbox or other components at the start of the footer |
-| `footnote` | `ReactNode` | No | - | Renders supplementary text or other components at the bottom of the modal |
-| `footnoteSkin` | `"light" \| "neutral"` | No | - | Sets the look and feel of the footnote |
-| `width` | `Width<string \| number>` | No | - | Fixes the width of component; if content area is wider than `width`, it scrolls horizontally |
-| `maxWidth` | `MaxWidth<string \| number>` | No | - | Sets the maximum width of component; if content area is longer than maxWidth, it scrolls horizontally |
-| `height` | `Height<string \| number>` | No | - | Fixes the height of component |
-| `maxHeight` | `MaxHeight<string \| number>` | No | - | Sets the maximum height of component; if content area is longer than maxHeight, it scrolls vertically |
-| `removeContentPadding` | `boolean` | No | - | Removes 30 px left and right padding from the content area |
-| `showHeaderDivider` | `boolean \| "auto"` | No | - | Controls visibility of a header divider. When set to `auto`, it is shown only when scroll position is greater than 0. When set to `true`, it is always visible, and when set to `false`, it is always hidden. |
-| `showFooterDivider` | `boolean \| "auto"` | No | - | Controls visibility of a footer divider. When set to `auto`, it is shown up until content is scrolled to the very bottom. When set to `true`, it is always visible, and when set to `false`, it is always hidden. |
-| `overflowY` | `"visible" \| "hidden" \| "scroll" \| "auto" \| "overlay" \| "none" \| "clip" \| "-moz-initial" \| "inherit" \| "initial" \| "revert" \| "revert-layer" \| "unset" \| "-moz-hidden-unscrollable"` | No | - | Determines what happens when content overflows component vertically. Value 'none' will be removed in next major, use "visible" value instead. |
-| `style` | `CSSProperties` | No | - | Sets object of CSS styles |
-| `theme` | `"standard" \| "premium" \| "destructive"` | No | - | @deprecated use skin prop instead |
-| `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 affect footer buttons skin. |
+Read `dist/dts-bundle/components/PickerModal.d.ts` for `PickerModal`'s full prop list, with types and
+descriptions. They are not repeated here, so the bundle is the single source of truth.
+
+A one-line stub in that file is an answer, not a truncation: an empty body with a
+"Produced by" note means you get the value from that hook or factory rather than
+constructing it. `dist/dts-bundle/index.json` maps every name to its bundle path.
 
 ## BI