@wix/patterns 1.459.0 → 1.460.0

package/dist/docs/ImportButton.md

@@ -86,46 +86,7 @@ import { ImportButton } from '@wix/patterns';
 
 A Wix Data (CMS) collection. `<ImportButton />` needs no config — it reads the import inputs live from the table’s schema source, and the CMS create/edit-field modal is loaded on demand.
 
-```tsx
-import React from 'react';
-import { CollectionPage } from '@wix/patterns/page';
-import { CustomColumns, ImportButton, Table } from '@wix/patterns';
-import { useTableCollection } from '@wix/patterns/schema';
-import { useCmsSchemaSource } from '@wix/patterns-cms';
-
-type CmsItem = {
-  _id: string;
-  name: string;
-  price: string;
-};
-
-function CmsImport() {
-  // The CMS (Wix Data) schema source: `useTableCollection` derives the query and
-  // identity from it and attaches its fields + field management to the table, so
-  // `<ImportButton />` reads everything it needs off the table when it opens — no
-  // config. (In these docs `useCmsSchemaSource` is backed by in-memory data so it
-  // runs with no backend.)
-  const source = useCmsSchemaSource<CmsItem>({ collectionId: 'Products' });
-  const state = useTableCollection<CmsItem>(source);
-
-  return (
-    <CollectionPage>
-      <CollectionPage.Header title={{ text: 'Products' }} />
-      <CollectionPage.Content>
-        <Table
-          state={state}
-          horizontalScroll
-          customColumns={<CustomColumns />}
-          columns={[]}
-          importButton={<ImportButton />}
-        />
-      </CollectionPage.Content>
-    </CollectionPage>
-  );
-}
-
-export default CmsImport;
-```
+Example code: read `dist/docs/ImportButton/cms-import.tsx`
 
 ---
 
@@ -133,73 +94,7 @@ export default CmsImport;
 
 A non–Wix-Data destination (here the stores catalog) with no declared schema: pass a `config` naming the `destination` and listing the `fields` to map onto.
 
-```tsx
-import { Page } from '@wix/design-system';
-import React from 'react';
-import {
-  ImportButton,
-  PageWrapper,
-  Table,
-  ToolbarTitle,
-  useTableCollection,
-  type ImportConfig,
-} from '@wix/patterns';
-import { queryStoreVariants } from '@wix/ambassador-stores-catalog-v1-product/http';
-import { StoreVariant } from '@wix/ambassador-stores-catalog-v1-product/types';
-import { useHttpClient } from '@wix/yoshi-flow-bm';
-
-function PlatformizedImport() {
-  const httpClient = useHttpClient();
-
-  const state = useTableCollection<StoreVariant>({
-    queryName: 'ImportButton-platformized',
-    fetchData: (query) => {
-      const { limit } = query;
-      return httpClient
-        .request(queryStoreVariants({ query: { cursorPaging: { limit } } }))
-        .then(({ data }) => ({
-          items: data.variants ?? [],
-          total: data.metadata?.total,
-        }));
-    },
-    itemKey: (variant) => variant.id ?? '',
-    itemName: (variant) => variant.productName ?? '',
-    fetchErrorMessage: () => 'Error fetching products',
-  });
-
-  // A platformized (non–Wix-Data) destination — here the stores catalog — has no
-  // declared schema, so the `config` names the write target and lists the fields
-  // to map onto (plus any live fields the table's source exposes).
-  const importConfig: ImportConfig = {
-    destination: { storesCatalogProducts: {} },
-    fields: [
-      { id: 'name', header: 'Name' },
-      { id: 'sku', header: 'SKU' },
-    ],
-  };
-
-  return (
-    <PageWrapper>
-      <Page height="400px">
-        <Page.Header title="Products" />
-        <Page.Content>
-          <Table
-            state={state}
-            horizontalScroll
-            title={<ToolbarTitle title="Products" showTotal />}
-            columns={[
-              { title: 'Name', render: (variant) => variant.productName },
-            ]}
-            importButton={<ImportButton config={importConfig} />}
-          />
-        </Page.Content>
-      </Page>
-    </PageWrapper>
-  );
-}
-
-export default PlatformizedImport;
-```
+Example code: read `dist/docs/ImportButton/platformized-import-fields-inline.tsx`
 
 ---
 
@@ -207,58 +102,7 @@ export default PlatformizedImport;
 
 A non–Wix-Data destination whose fields come from a source (`usePlatformizedSource`) instead of an inline list — like the CMS case, but you still name the `destination` in `config`.
 
-```tsx
-import React from 'react';
-import { CollectionPage } from '@wix/patterns/page';
-import { CustomColumns, ImportButton, Table } from '@wix/patterns';
-import {
-  usePlatformizedSource,
-  useTableCollection,
-} from '@wix/patterns/schema';
-
-type Product = {
-  id: string;
-  name: string;
-  sku: string;
-};
-
-// A platformized entity driven by a source (`usePlatformizedSource`). Like the
-// CMS case, the source supplies the columns and the fields to map onto — you
-// don't hand-list `fields`. Unlike CMS you still name the `destination`: a
-// platformized target has no Wix Data collection to derive it from.
-// (In these docs `usePlatformizedSource` is backed by in-memory data so it runs
-// with no backend.)
-function PlatformizedSourceImport() {
-  const source = usePlatformizedSource<Product>({
-    fqdn: 'stores.catalog.product',
-    backend: { find: async () => ({ items: [], total: 0 }) },
-    itemKey: (product) => product.id,
-    itemName: (product) => product.name,
-  });
-  const state = useTableCollection<Product>(source);
-
-  return (
-    <CollectionPage>
-      <CollectionPage.Header title={{ text: 'Products' }} />
-      <CollectionPage.Content>
-        <Table
-          state={state}
-          horizontalScroll
-          customColumns={<CustomColumns />}
-          columns={[]}
-          importButton={
-            <ImportButton
-              config={{ destination: { storesCatalogProducts: {} } }}
-            />
-          }
-        />
-      </CollectionPage.Content>
-    </CollectionPage>
-  );
-}
-
-export default PlatformizedSourceImport;
-```
+Example code: read `dist/docs/ImportButton/platformized-import-from-a-source.tsx`
 
 ---
 
@@ -266,73 +110,7 @@ export default PlatformizedSourceImport;
 
 Mark fields with `required: true`. The import is blocked while any required field is still unmapped, with a footnote listing the missing ones. (Shown with a platformized `config`.)
 
-```tsx
-import { Page } from '@wix/design-system';
-import React from 'react';
-import {
-  ImportButton,
-  PageWrapper,
-  Table,
-  ToolbarTitle,
-  useTableCollection,
-  type ImportConfig,
-} from '@wix/patterns';
-import { queryStoreVariants } from '@wix/ambassador-stores-catalog-v1-product/http';
-import { StoreVariant } from '@wix/ambassador-stores-catalog-v1-product/types';
-import { useHttpClient } from '@wix/yoshi-flow-bm';
-
-function RequiredFields() {
-  const httpClient = useHttpClient();
-
-  const state = useTableCollection<StoreVariant>({
-    queryName: 'ImportButton-required',
-    fetchData: (query) => {
-      const { limit } = query;
-      return httpClient
-        .request(queryStoreVariants({ query: { cursorPaging: { limit } } }))
-        .then(({ data }) => ({
-          items: data.variants ?? [],
-          total: data.metadata?.total,
-        }));
-    },
-    itemKey: (variant) => variant.id ?? '',
-    itemName: (variant) => variant.productName ?? '',
-    fetchErrorMessage: () => 'Error fetching products',
-  });
-
-  // Mark fields `required: true`. The import is blocked while any required field
-  // is still unmapped, with a footnote listing the missing ones.
-  const importConfig: ImportConfig = {
-    destination: { storesCatalogProducts: {} },
-    fields: [
-      { id: 'name', header: 'Name', required: true },
-      { id: 'price', header: 'Price', required: true },
-      { id: 'sku', header: 'SKU' },
-    ],
-  };
-
-  return (
-    <PageWrapper>
-      <Page height="400px">
-        <Page.Header title="Products" />
-        <Page.Content>
-          <Table
-            state={state}
-            horizontalScroll
-            title={<ToolbarTitle title="Products" showTotal />}
-            columns={[
-              { title: 'Name', render: (variant) => variant.productName },
-            ]}
-            importButton={<ImportButton config={importConfig} />}
-          />
-        </Page.Content>
-      </Page>
-    </PageWrapper>
-  );
-}
-
-export default RequiredFields;
-```
+Example code: read `dist/docs/ImportButton/required-fields.tsx`
 
 ---
 
@@ -340,48 +118,7 @@ export default RequiredFields;
 
 A CMS capability: when the collection’s schema permits adding fields, unmapped CSV columns default to creating a new field (with an "Edit field" affordance) instead of being skipped. `<ImportButton />` wires it from the schema automatically.
 
-```tsx
-import React from 'react';
-import { CollectionPage } from '@wix/patterns/page';
-import { CustomColumns, ImportButton, Table } from '@wix/patterns';
-import { useTableCollection } from '@wix/patterns/schema';
-import { useCmsSchemaSource } from '@wix/patterns-cms';
-
-type CmsItem = {
-  _id: string;
-  name: string;
-  price: string;
-};
-
-// "Create new field" is a CMS (Wix Data) capability, wired automatically: when
-// the collection's schema permits adding fields (`schemaPermissions.createField`),
-// CSV columns that don't match an existing field default to creating a new field
-// (with an "Edit field" affordance) instead of being skipped. It's read off the
-// table's schema source, so `<ImportButton />` takes no config.
-function CreateNewField() {
-  // (In these docs `useCmsSchemaSource` is backed by in-memory data — with
-  // add-field allowed — so it runs with no backend.)
-  const source = useCmsSchemaSource<CmsItem>({ collectionId: 'Products' });
-  const state = useTableCollection<CmsItem>(source);
-
-  return (
-    <CollectionPage>
-      <CollectionPage.Header title={{ text: 'Products' }} />
-      <CollectionPage.Content>
-        <Table
-          state={state}
-          horizontalScroll
-          customColumns={<CustomColumns />}
-          columns={[]}
-          importButton={<ImportButton />}
-        />
-      </CollectionPage.Content>
-    </CollectionPage>
-  );
-}
-
-export default CreateNewField;
-```
+Example code: read `dist/docs/ImportButton/create-new-field.tsx`
 
 ---
 
@@ -389,48 +126,7 @@ export default CreateNewField;
 
 A CMS behavior: when a CSV column maps to the collection’s id field (`_id`), that row floats to the top and the modal offers an "update or skip" write policy for rows that collide on ID.
 
-```tsx
-import React from 'react';
-import { CollectionPage } from '@wix/patterns/page';
-import { CustomColumns, ImportButton, Table } from '@wix/patterns';
-import { useTableCollection } from '@wix/patterns/schema';
-import { useCmsSchemaSource } from '@wix/patterns-cms';
-
-type CmsItem = {
-  _id: string;
-  name: string;
-  price: string;
-};
-
-// Update-or-skip-by-ID is a CMS (Wix Data) behavior. When a CSV column maps to
-// the collection's id field (`_id`), that row floats to the top and the modal
-// offers an "update or skip" write policy for rows that collide on ID. The id
-// field comes from the schema source, so it's mappable and the import derives it
-// — `<ImportButton />` takes no config.
-function IdCollisionWritePolicy() {
-  // (In these docs `useCmsSchemaSource` is backed by in-memory data — including
-  // the `_id` field — so it runs with no backend.)
-  const source = useCmsSchemaSource<CmsItem>({ collectionId: 'Products' });
-  const state = useTableCollection<CmsItem>(source);
-
-  return (
-    <CollectionPage>
-      <CollectionPage.Header title={{ text: 'Products' }} />
-      <CollectionPage.Content>
-        <Table
-          state={state}
-          horizontalScroll
-          customColumns={<CustomColumns />}
-          columns={[]}
-          importButton={<ImportButton />}
-        />
-      </CollectionPage.Content>
-    </CollectionPage>
-  );
-}
-
-export default IdCollisionWritePolicy;
-```
+Example code: read `dist/docs/ImportButton/update-or-skip-by-id.tsx`
 
 ---
 
@@ -438,88 +134,7 @@ export default IdCollisionWritePolicy;
 
 Pass a `backup` to snapshot the collection before importing (undone on cancel) and a `jobApplicationErrorMap` to map a failed job’s application-error codes to messages. (Shown with a platformized `config`.)
 
-```tsx
-import { Page } from '@wix/design-system';
-import React from 'react';
-import {
-  ImportButton,
-  PageWrapper,
-  Table,
-  ToolbarTitle,
-  useTableCollection,
-  type ImportConfig,
-} from '@wix/patterns';
-import { queryStoreVariants } from '@wix/ambassador-stores-catalog-v1-product/http';
-import { StoreVariant } from '@wix/ambassador-stores-catalog-v1-product/types';
-import { useHttpClient } from '@wix/yoshi-flow-bm';
-
-function BackupAndErrorHandling() {
-  const httpClient = useHttpClient();
-
-  const state = useTableCollection<StoreVariant>({
-    queryName: 'ImportButton-backup',
-    fetchData: (query) => {
-      const { limit } = query;
-      return httpClient
-        .request(queryStoreVariants({ query: { cursorPaging: { limit } } }))
-        .then(({ data }) => ({
-          items: data.variants ?? [],
-          total: data.metadata?.total,
-        }));
-    },
-    itemKey: (variant) => variant.id ?? '',
-    itemName: (variant) => variant.productName ?? '',
-    fetchErrorMessage: () => 'Error fetching products',
-  });
-
-  const importConfig: ImportConfig = {
-    destination: { storesCatalogProducts: {} },
-    fields: [{ id: 'name', header: 'Name', required: true }],
-
-    // Optional: snapshot the collection before importing. The returned `restore`
-    // runs only if the user cancels mid-import (a job failure leaves partial
-    // rows and offers "Try again" instead).
-    backup: async () => {
-      // ...take a snapshot...
-      return {
-        restore: async () => {
-          // ...restore the snapshot...
-        },
-      };
-    },
-
-    // Optional: map the failed job's application-error codes to messages. You
-    // supply only the code → message map; the import resolves it through the
-    // error handler internally.
-    jobApplicationErrorMap: {
-      MISSING_REQUIRED_FIELDS: ({ data }) => ({
-        message: `Missing required fields: ${data?.missingFields?.join(', ')}`,
-      }),
-    },
-  };
-
-  return (
-    <PageWrapper>
-      <Page height="400px">
-        <Page.Header title="Products" />
-        <Page.Content>
-          <Table
-            state={state}
-            horizontalScroll
-            title={<ToolbarTitle title="Products" showTotal />}
-            columns={[
-              { title: 'Name', render: (variant) => variant.productName },
-            ]}
-            importButton={<ImportButton config={importConfig} />}
-          />
-        </Page.Content>
-      </Page>
-    </PageWrapper>
-  );
-}
-
-export default BackupAndErrorHandling;
-```
+Example code: read `dist/docs/ImportButton/backup-error-handling.tsx`
 
 ## API
 

package/dist/docs/Indeterminate/all-indeterminate.tsx

@@ -0,0 +1,127 @@
+import { Avatar, EmptyState, Page } from '@wix/design-system';
+import React from 'react';
+import { queryContacts } from '@wix/ambassador-contacts-v4-contact/http';
+import {
+  Filter,
+  OffsetQuery,
+  PickerContent,
+  PickerContentComponentProps,
+  PickerModal,
+  PickerModalOpenButton,
+  PickerSelection,
+  stringsArrayFilter,
+  usePickerContent,
+} from '@wix/patterns';
+import { usePickerModal } from '@wix/patterns/essentials';
+import {
+  useEnvironment,
+  useErrorMonitor,
+  useHttpClient,
+} from '@wix/fe-essentials/react';
+import { Contact } from '@wix/ambassador-contacts-v4-contact/types';
+
+type ContactsFilters = {
+  level: Filter<string[]>;
+};
+
+function PickerModalAllIndeterminate() {
+  const environment = useEnvironment();
+  const httpClient = useHttpClient();
+  const errorMonitor = useErrorMonitor();
+
+  const selection = React.useRef<PickerSelection<Contact>>({
+    defaultStatus: 'indeterminate',
+  });
+
+  // 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),
+        },
+        initialSelect: selection.current,
+      });
+
+      return (
+        <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}
+        />
+      );
+    },
+  });
+
+  const state = usePickerModal<Contact, ContactsFilters>({
+    queryName: 'PickerModalAllIndeterminate',
+    fetchInitialProps: () => {
+      return httpClient.request(
+        queryContacts({
+          query: { paging: { limit: 25, offset: 0 }, filter: {} },
+        }),
+      );
+    },
+    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, { values, defaultStatus }) => {
+      selection.current = {
+        values: values.map(({ value, status }) => ({
+          value,
+          status: status.isIndeterminate
+            ? 'indeterminate'
+            : status.isChecked
+            ? 'checked'
+            : 'unchecked', // reset non-indeterminate to regular checked->unchecked mode
+        })),
+        defaultStatus,
+      };
+    },
+  });
+
+  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>
+  );
+}

package/dist/docs/Indeterminate/items-indeterminate-status.tsx

@@ -0,0 +1,126 @@
+import { Avatar, EmptyState, Page } from '@wix/design-system';
+import React from 'react';
+import { queryContacts } from '@wix/ambassador-contacts-v4-contact/http';
+import {
+  Filter,
+  OffsetQuery,
+  PickerContent,
+  PickerContentComponentProps,
+  PickerModal,
+  PickerModalOpenButton,
+  PickerSelection,
+  stringsArrayFilter,
+  usePickerContent,
+} from '@wix/patterns';
+import { usePickerModal } from '@wix/patterns/essentials';
+import {
+  useEnvironment,
+  useErrorMonitor,
+  useHttpClient,
+} from '@wix/fe-essentials/react';
+import { Contact } from '@wix/ambassador-contacts-v4-contact/types';
+
+type ContactsFilters = {
+  level: Filter<string[]>;
+};
+
+function PickerModalIndeterminate() {
+  const environment = useEnvironment();
+  const httpClient = useHttpClient();
+  const errorMonitor = useErrorMonitor();
+
+  const selection = React.useRef<PickerSelection<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, ContactsFilters>,
+    ) {
+      const state = usePickerContent({
+        fetchErrorMessage: ({ err }) => String(err),
+        modalState: props.modalState,
+        filters: {
+          level: stringsArrayFilter(props.modalState.filters.level),
+        },
+        initialSelect: selection.current,
+      });
+
+      return (
+        <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}
+        />
+      );
+    },
+  });
+
+  const state = usePickerModal<Contact, ContactsFilters>({
+    queryName: 'PickerModalIndeterminate',
+    fetchInitialProps: () => {
+      return httpClient
+        .request(
+          queryContacts({
+            query: { paging: { limit: 25, offset: 0 }, filter: {} },
+          }),
+        )
+        .then(({ data: { contacts = [] } }) => {
+          selection.current = {
+            partiallySelectedIds: contacts
+              .slice(3, 6)
+              .map((c) => c.id as string),
+          };
+        });
+    },
+    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, { values, defaultStatus }) => {
+      selection.current = {
+        values,
+        defaultStatus,
+      };
+    },
+  });
+
+  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>
+  );
+}