@wix/patterns 1.364.0 → 1.369.0

package/dist/docs/InMemoryBackend.md

@@ -0,0 +1,81 @@
+# InMemoryBackend
+
+**Category:** Guides
+
+## Design
+
+### Overview
+
+A mocking utility which acts as a collection server API.
+
+`Wix Patterns` itself uses it for its internal tests.
+
+
+```tsx
+import { InMemoryBackend } from '@wix/patterns/testkit/backend';
+```
+
+---
+
+### Example
+
+```tsx
+import { InMemoryBackend } from '@wix/patterns/testkit/backend';
+import { Chance } from 'chance';
+import { escapeRegExp } from 'lodash';
+
+export function createBackend() {
+  const chance = new Chance();
+
+  return new InMemoryBackend({
+    total: 1000,
+    delay: { min: 100, max: 700 },
+    createOne: (index) => ({
+      id: chance.guid(),
+      name: `${index} ${chance.name()}`,
+      level: chance.pickone([
+        'Beginner',
+        'Amateur',
+        'Semi-Pro',
+        'Professional',
+        'World Class',
+        'Legendary',
+        'Ultimate',
+      ]),
+      image: 'https://picsum.photos/200',
+    }),
+    predicate: ({ search, filters }) => {
+      const rgx = new RegExp(escapeRegExp(search), 'i');
+
+      return (item) => {
+        if (search && !rgx.test(item.name)) {
+          return false;
+        }
+
+        if (filters.level && filters.level.indexOf(item.level) === -1) {
+          return false;
+        }
+
+        return true;
+      };
+    },
+    itemKey: (item) => item.id,
+  });
+}
+```
+
+## API
+
+### Props
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `createOne` | `(index: number) => T` | Yes | - | A callback function for each item creation |
+| `itemKey` | `(item: T) => string` | Yes | - | A callback function that accepts an item and returns a unique ID of it. typically `item.id`. |
+| `predicate` | `((query: BackendQuery<FiltersMap>) => (item: T) => boolean)` | No | - | A function that accepts a subset of [ComputedQuery](./?path=/story/common-types--computedquery) sent by the client and returns another function that accepts an item and should return a boolean that indicates whether the item passes the query filtering or not. |
+| `orderBy` | `((query: BackendQuery<FiltersMap>) => Order<T>[])` | No | - | A function that accepts a subset of [ComputedQuery](./?path=/story/common-types--computedquery) sent by the client and returns another function that accepts an item and should returns a list of rules to order the items by |
+| `projection` | `((query: BackendQuery<FiltersMap>) => (item: T) => T)` | No | - | A function that accepts a subset of [ComputedQuery](./?path=/story/common-types--computedquery) sent by the client and returns a list of fields to project from the item |
+| `delay` | `{ min: number; max: number; }` | No | `{ min: 0, max: 5 }` | Simulates API latency |
+| `total` | `number` | Yes | - | Total number of items to store in the backend |
+| `enableTotal` | `boolean` | No | - | Enable total for the backend. Defaults to "true" |
+

package/dist/docs/Indeterminate.md

@@ -0,0 +1,273 @@
+# Indeterminate
+
+**Category:** Base Components/Collections/Picker
+
+## Design
+
+### Examples
+
+### Items indeterminate status
+
+```tsx
+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>
+  );
+}
+```
+
+---
+
+### All indeterminate
+
+```tsx
+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/Internal Scroll.md

@@ -0,0 +1,236 @@
+# Internal Scroll
+
+**Category:** Features/Display/Internal Scroll
+
+## Design
+
+### Internal scroll
+
+The "internalScroll" prop enables internal scrolling within the component itself, by wrapping it inside a limited height container.
+
+**Do:**
+
+- Wrap the component inside a container element with a limited height. This container will provide a visual boundary for the component's content and enable scrolling within that confined space.
+
+- Set a minimum height of at least 482px for the container. This height ensures that the component has enough space to display its content, including any placeholder states that might be utilized during loading or when there is no data to display.
+
+
+**Don't:**
+
+- Ensure that there is no scrollable parent container surrounding the table/grid component. Having a scrollable parent can lead to double scrolling behavior, which can be confusing and inconvenient for users
+
+
+### Developer examples
+
+### Full Width Section
+
+```tsx
+import { Avatar, Box, Card } from '@wix/design-system';
+import React from 'react';
+import { CollectionPage } from '@wix/patterns/page';
+import {
+  OffsetQuery,
+  TableGridSwitch,
+  useTableGridSwitchCollection,
+  useOptimisticActions,
+} from '@wix/patterns';
+import { contacts } from '@wix/crm';
+
+function FullWidthInternalScroll() {
+
+  const state = useTableGridSwitchCollection<contacts.Contact>({
+    queryName: 'TableGridSwitchNarrowInternalScroll',
+    paginationMode: 'offset',
+    fetchData: (query: OffsetQuery) => {
+      const { limit, offset, search, filters } = query;
+
+      let queryBuilder = contacts.queryContacts().limit(limit).skip(offset);
+
+      if (search) {
+        queryBuilder = queryBuilder.startsWith('info.name.first', search);
+      }
+
+      return queryBuilder.find().then(({ items = [], totalCount: total }) => ({
+        items,
+        total,
+      }));
+    },
+    itemName: (item) => `${item.info?.name?.first} ${item.info?.name?.last}`,
+    fetchErrorMessage: () => 'Error fetching contacts',
+    limit: 50,
+    filters: {},
+  });
+
+  useOptimisticActions(state.collection);
+
+  return (
+    <CollectionPage height="622px">
+      <CollectionPage.Header title={{ text: 'Contacts' }} />
+      <CollectionPage.Content>
+        <Box direction="vertical" gap="SP3">
+          <Card>
+            <Card.Header title="Content Above" />
+            <Card.Content>
+              <Box width="100%" height="130px" />
+            </Card.Content>
+          </Card>
+          <Box
+            direction="vertical"
+            width="100%"
+            maxHeight="482px"
+            overflow="hidden"
+          >
+            <TableGridSwitch
+              state={state}
+              internalScroll
+              columns={[
+                {
+                  id: 'avatar',
+                  title: '',
+                  hideable: true,
+                  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: 'Last Activity',
+                  render: (contact) =>
+                    contact.lastActivity?.activityDate?.toLocaleString(),
+                },
+              ]}
+            />
+          </Box>
+          <Card>
+            <Card.Header title="Content Below" />
+            <Card.Content>
+              <Box width="100%" height="130px" />
+            </Card.Content>
+          </Card>
+        </Box>
+      </CollectionPage.Content>
+    </CollectionPage>
+  );
+}
+```
+
+---
+
+### Narrow Side Section
+
+```tsx
+import { Avatar, Box, Card } from '@wix/design-system';
+import React from 'react';
+import { CollectionPage } from '@wix/patterns/page';
+import {
+  OffsetQuery,
+  TableGridSwitch,
+  useTableGridSwitchCollection,
+  useOptimisticActions,
+} from '@wix/patterns';
+import { contacts } from '@wix/crm';
+
+function NarrowInternalScroll() {
+
+  const state = useTableGridSwitchCollection<contacts.Contact>({
+    queryName: 'TableGridSwitchNarrowInternalScroll',
+    paginationMode: 'offset',
+    fetchData: (query: OffsetQuery) => {
+      const { limit, offset, search, filters } = query;
+
+      let queryBuilder = contacts.queryContacts().limit(limit).skip(offset);
+
+      if (search) {
+        queryBuilder = queryBuilder.startsWith('info.name.first', search);
+      }
+
+      return queryBuilder.find().then(({ items = [], totalCount: total }) => ({
+        items,
+        total,
+      }));
+    },
+    itemName: (item) => `${item.info?.name?.first} ${item.info?.name?.last}`,
+    fetchErrorMessage: () => 'Error fetching contacts',
+    limit: 50,
+    filters: {},
+  });
+
+  useOptimisticActions(state.collection);
+
+  return (
+    <CollectionPage height="622px">
+      <CollectionPage.Header title={{ text: 'Contacts' }} />
+      <CollectionPage.Content>
+        <Box direction="horizontal" gap="SP3" width="100%" height="482px">
+          <Box direction="vertical" width="390px" height="100%">
+            <TableGridSwitch
+              state={state}
+              internalScroll
+              columns={[
+                {
+                  id: 'avatar',
+                  title: '',
+                  hideable: true,
+                  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}`,
+                },
+              ]}
+            />
+          </Box>
+          <Box direction="vertical" overflow="auto" flex={1} height="100%">
+            <Card>
+              <Card.Header title="Content" />
+              <Card.Content>
+                <Box width="100%" height="4000px" />
+              </Card.Content>
+            </Card>
+          </Box>
+        </Box>
+      </CollectionPage.Content>
+    </CollectionPage>
+  );
+}
+```
+
+## BI
+
+### Custom Columns Events
+
+ Event   |   Description   |
+--------- | --------------- |
+[144:112](https://bo.wix.com/data-tools/bi-catalog-app/event/144:112) | Sent when a Wix Patterns component is done loading more items (after scrolling)
+
+
+
+### 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)
+
+