@wix/patterns 1.364.0 → 1.369.0

package/dist/docs/CollectionPage.Content.md

@@ -0,0 +1,154 @@
+# CollectionPage.Content
+
+**Category:** Base Components/Pages/Collection Page
+
+## Design
+
+### Description
+
+This component acts as a container for collection components like [Table](./?path=/story/base-components-collections-table-table--table) and [Grid](./?path=/story/base-components-collections-grid-grid--grid), which should be sent as children.
+
+
+```tsx
+import { CollectionPage } from '@wix/patterns/page'; 
+// And its usage: <CollectionPage.Content>
+```
+
+### Basic
+
+Rendering a a Collection Page with a text content 
+
+```tsx
+import { CollectionPage } from '@wix/patterns/page';
+import React from 'react';
+
+function Basic() {
+  return (
+    <CollectionPage>
+      <CollectionPage.Content>Custom Content</CollectionPage.Content>
+    </CollectionPage>
+  );
+}
+```
+
+### With table
+
+Showing table as the content of the page
+
+```tsx
+import { Avatar } from '@wix/design-system';
+import React from 'react';
+import { Table, useTableCollection } from '@wix/patterns';
+import { CollectionPage } from '@wix/patterns/page';
+import { contacts } from '@wix/crm';
+
+function WithoutTotal() {
+  const state = useTableCollection<contacts.Contact>({
+    queryName: 'contacts-withTable',
+    itemName: (contact) =>
+      `${contact.info?.name?.first} ${contact.info?.name?.last}`,
+    fetchData: (query) => {
+      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,
+      }));
+    },
+    fetchErrorMessage: () => 'Error fetching contacts',
+    filters: {},
+  });
+
+  return (
+    <CollectionPage height="400px">
+      <CollectionPage.Content>
+        <Table
+          state={state}
+          columns={[
+            {
+              id: 'avatar',
+              name: 'Avatar',
+              title: '',
+              width: '50px',
+              hideable: false,
+              render: (contact) => (
+                <Avatar
+                  name={`${contact.info?.name?.first} ${contact.info?.name?.last}`}
+                  imgProps={{ src: contact.info?.picture?.image }}
+                />
+              ),
+            },
+            {
+              id: 'name',
+              title: 'Name',
+              width: '250px',
+              render: (contact) =>
+                `${contact.info?.name?.first} ${contact.info?.name?.last}`,
+            },
+          ]}
+        />
+      </CollectionPage.Content>
+    </CollectionPage>
+  );
+}
+```
+
+### With grid
+
+Showing grid as the content of the page
+
+```tsx
+import React from 'react';
+import { CollectionPage } from '@wix/patterns/page';
+import { Grid, useGridCollection } from '@wix/patterns';
+import { contacts } from '@wix/crm';
+
+function WithGrid() {
+  const grid = useGridCollection<contacts.Contact>({
+    queryName: 'contacts-withGrid',
+    paginationMode: 'offset',
+    itemName: (contact) =>
+      `${contact.info?.name?.first} ${contact.info?.name?.last}`,
+    fetchData: (query) => {
+      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 }) => {
+        const limitedItems = items.slice(0, 4);
+        return {
+          items: limitedItems,
+          total: limitedItems.length,
+        };
+      });
+    },
+    fetchErrorMessage: ({ err }) => String(err),
+  });
+
+  return (
+    <CollectionPage height="400px">
+      <CollectionPage.Content>
+        <Grid
+          state={grid}
+          renderItem={(item) => ({
+            key: item._id,
+            primaryActionProps: { label: item.info?.jobTitle },
+            title: grid.collection.itemName(item),
+          })}
+        />
+      </CollectionPage.Content>
+    </CollectionPage>
+  );
+}
+```
+

package/dist/docs/CollectionPage.Header.md

@@ -0,0 +1,216 @@
+# CollectionPage.Header
+
+**Category:** Base Components/Pages/Collection Page
+
+## Design
+
+### Description
+
+This component renders a [Page.Header](https://www.docs.wixdesignsystem.com/?path=/story/components-layout-page--page-header) component inside a [CollectionPage](./?path=/story/base-components-pages-collection-page--collectionpage).
+
+
+```tsx
+import { CollectionPage } from '@wix/patterns/page'; 
+// And its usage: <CollectionPage.Header>
+```
+
+### Full
+
+Rendering a header with title, subtitle, total, primary action, and more actions. To learn how to create a more actions menu, see [`MoreActions`](./?path=/story/features-actions-more-actions--more-actions).
+
+```tsx
+import { Avatar, Breadcrumbs } from '@wix/design-system';
+import React from 'react';
+import {
+  Table,
+  useTableCollection,
+  MoreActions,
+  PrimaryActions,
+} from '@wix/patterns';
+import { CollectionPage } from '@wix/patterns/page';
+import { InvoiceSmall, VisibleSmall } from '@wix/wix-ui-icons-common';
+import { contacts } from '@wix/crm';
+
+function Full() {
+  const state = useTableCollection<contacts.Contact>({
+    queryName: 'contacts-full',
+    itemName: (contact) =>
+      `${contact.info?.name?.first} ${contact.info?.name?.last}`,
+    fetchData: (query) => {
+      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,
+      }));
+    },
+    fetchErrorMessage: () => 'Error fetching contacts',
+    filters: {},
+  });
+
+  return (
+    <CollectionPage height="400px">
+      <CollectionPage.Header
+        title={{ text: 'Contacts' }}
+        subtitle={{ text: 'My Contacts' }}
+        breadcrumbs={
+          <Breadcrumbs
+            activeId="2"
+            items={[
+              { id: '1', value: 'First crumb' },
+              { id: '2', value: 'Second crumb' },
+            ]}
+          />
+        }
+        primaryAction={
+          <PrimaryActions
+            label="Do something"
+            onClick={() => console.log('I do something')}
+          />
+        }
+        moreActions={
+          <MoreActions
+            items={[
+              [
+                {
+                  biName: 'action-1',
+                  text: 'Do Action #1',
+                  prefixIcon: <InvoiceSmall />,
+                  onClick: () => {
+                    console.log('Action #1');
+                  },
+                },
+                {
+                  biName: 'action-2',
+                  text: 'Another Action #2',
+                  prefixIcon: <VisibleSmall />,
+                  onClick: () => {
+                    console.log('Action #2');
+                  },
+                },
+              ],
+            ]}
+            containerId="6dcbba57-c740-477c-a747-30094cf54ca1"
+          />
+        }
+      />
+      <CollectionPage.Content>
+        <Table
+          state={state}
+          columns={[
+            {
+              id: 'avatar',
+              name: 'Avatar',
+              title: '',
+              width: '50px',
+              hideable: false,
+              render: (contact) => (
+                <Avatar
+                  name={`${contact.info?.name?.first} ${contact.info?.name?.last}`}
+                  imgProps={{ src: contact.info?.picture?.image }}
+                />
+              ),
+            },
+            {
+              id: 'name',
+              title: 'Name',
+              width: '250px',
+              render: (contact) =>
+                `${contact.info?.name?.first} ${contact.info?.name?.last}`,
+            },
+          ]}
+        />
+      </CollectionPage.Content>
+    </CollectionPage>
+  );
+}
+```
+
+### Without Total
+
+Hiding the total number of entities in the header of a collection page, with `hideTotal` config.
+
+```tsx
+import { Avatar } from '@wix/design-system';
+import React from 'react';
+import { Table, useTableCollection } from '@wix/patterns';
+import { CollectionPage } from '@wix/patterns/page';
+import { contacts } from '@wix/crm';
+
+function WithoutTotal() {
+  const state = useTableCollection<contacts.Contact>({
+    queryName: 'contacts-DisabledCustomColumns',
+    itemName: (contact) =>
+      `${contact.info?.name?.first} ${contact.info?.name?.last}`,
+    fetchData: (query) => {
+      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,
+      }));
+    },
+    fetchErrorMessage: () => 'Error fetching contacts',
+    filters: {},
+  });
+
+  return (
+    <CollectionPage height="400px">
+      <CollectionPage.Header title={{ text: 'Contacts', hideTotal: true }} />
+      <CollectionPage.Content>
+        <Table
+          state={state}
+          columns={[
+            {
+              id: 'avatar',
+              name: 'Avatar',
+              title: '',
+              width: '50px',
+              hideable: false,
+              render: (contact) => (
+                <Avatar
+                  name={`${contact.info?.name?.first} ${contact.info?.name?.last}`}
+                  imgProps={{ src: contact.info?.picture?.image }}
+                />
+              ),
+            },
+            {
+              id: 'name',
+              title: 'Name',
+              width: '250px',
+              render: (contact) =>
+                `${contact.info?.name?.first} ${contact.info?.name?.last}`,
+            },
+          ]}
+        />
+      </CollectionPage.Content>
+    </CollectionPage>
+  );
+}
+```
+
+## API
+
+### Props
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `breadcrumbs` | `BreadcrumbsElement` | No | - | A [`Breadcrumbs`](https://www.docs.wixdesignsystem.com/?path=/story/components-navigation--breadcrumbs) element to be rendered on the header. |
+| `title` | `{ text: string; hideTotal?: boolean \| undefined; }` | Yes | - | `text`: The title text. \ `hideTotal`: Determines whether to hide the number of total entities on the title of the page. |
+| `subtitle` | `PageSubTitleProps` | No | - | The page subtitle text. |
+| `primaryAction` | `PrimaryActionsElement` | No | - | A [`PrimaryActions`](./?path=/story/features-actions-primary-actions--primary-actions) component to be rendered on the header. A primary button w/o PopoverMenu component to be rendered in the header. |
+| `secondaryActions` | `SecondaryActionsElement` | No | - | A [`SecondaryActions`](./?path=/story/features-actions-secondary-actions--secondary-actions) component to be rendered on the header. A Secondary button w/o PopoverMenu component to be rendered on the header |
+| `moreActions` | `MoreActionsElement` | No | - | A [`MoreActions`](./?path=/story/features-actions-more-actions--more-actions) component to be rendered on the header. |
+

package/dist/docs/CollectionPage.md

@@ -0,0 +1,183 @@
+# CollectionPage
+
+**Category:** Base Components/Pages/Collection Page
+
+## Design
+
+### Description
+
+CollectionPage wraps [](https://www.docs.wixdesignsystem.com/?path=/story/components-layout-page--page) from `@wix/design-system`. \
+It provides scrolling context for collection components, such as [](./?path=/story/components-collection--table).
+Also, it displays total items count in the page header.
+
+It accepts two types of children: [CollectionPage.Header](./?path=/story/base-components-pages-collection-page--collectionpage-header) and [CollectionPage.Content](./?path=/story/base-components-pages-collection-page--collectionpage-content).
+
+
+
+```tsx
+import { CollectionPage } from '@wix/patterns/page';
+```
+
+### Full
+
+```tsx
+import { Avatar, Breadcrumbs } from '@wix/design-system';
+import React from 'react';
+import {
+  Table,
+  useTableCollection,
+  MoreActions,
+  PrimaryActions,
+} from '@wix/patterns';
+import { CollectionPage } from '@wix/patterns/page';
+import { InvoiceSmall, VisibleSmall } from '@wix/wix-ui-icons-common';
+import { contacts } from '@wix/crm';
+
+function Full() {
+  const state = useTableCollection<contacts.Contact>({
+    queryName: 'contacts-full',
+    itemName: (contact) =>
+      `${contact.info?.name?.first} ${contact.info?.name?.last}`,
+    fetchData: (query) => {
+      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,
+      }));
+    },
+    fetchErrorMessage: () => 'Error fetching contacts',
+    filters: {},
+  });
+
+  return (
+    <CollectionPage height="400px">
+      <CollectionPage.Header
+        title={{ text: 'Contacts' }}
+        subtitle={{
+          text: 'My Contacts',
+          learnMore: {
+            url: 'https://www.wix.com/',
+            label: 'my custom learn more label', // Defaults to "Learn more"
+          },
+        }}
+        breadcrumbs={
+          <Breadcrumbs
+            activeId="2"
+            items={[
+              { id: '1', value: 'First crumb' },
+              { id: '2', value: 'Second crumb' },
+            ]}
+          />
+        }
+        primaryAction={
+          <PrimaryActions
+            label="Do something"
+            onClick={() => console.log('I do something')}
+          />
+        }
+        moreActions={
+          <MoreActions
+            items={[
+              [
+                {
+                  text: 'Do Action #1',
+                  prefixIcon: <InvoiceSmall />,
+                  onClick: () => {
+                    console.log('Action #1');
+                  },
+                },
+                {
+                  text: 'Another Action #2',
+                  prefixIcon: <VisibleSmall />,
+                  onClick: () => {
+                    console.log('Action #2');
+                  },
+                },
+              ],
+            ]}
+            containerId="6dcbba57-c740-477c-a747-30094cf54ca1"
+          />
+        }
+      />
+      <CollectionPage.Content>
+        <Table
+          state={state}
+          columns={[
+            {
+              id: 'avatar',
+              name: 'Avatar',
+              title: '',
+              width: '50px',
+              hideable: false,
+              render: (contact) => (
+                <Avatar
+                  name={`${contact.info?.name?.first} ${contact.info?.name?.last}`}
+                  imgProps={{ src: contact.info?.picture?.image }}
+                />
+              ),
+            },
+            {
+              id: 'name',
+              title: 'Name',
+              width: '250px',
+              render: (contact) =>
+                `${contact.info?.name?.first} ${contact.info?.name?.last}`,
+            },
+          ]}
+        />
+      </CollectionPage.Content>
+    </CollectionPage>
+  );
+}
+```
+
+### Basic
+
+Simple page for demonstration of page parts
+
+```tsx
+import { CollectionPage } from '@wix/patterns/page';
+
+import React from 'react';
+
+function Basic() {
+  return (
+    <CollectionPage>
+      <CollectionPage.Header title={{ text: 'Custom Header' }} />
+      <CollectionPage.Content>Custom Content</CollectionPage.Content>
+    </CollectionPage>
+  );
+}
+```
+
+## API
+
+### Extends
+
+[Page](https://www.docs.wixdesignsystem.com/?path=/story/components-layout-page--page)
+
+### Props
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `children` | `ReactNode` | No | - | Accepts [CollectionPage.Header](./?path=/story/base-components-pages-collection-page--collectionpage-header) and [CollectionPage.Content](./?path=/story/base-components-pages-collection-page--collectionpage-content) elements |
+| `dataHook` | `string` | No | - | Applies a data-hook HTML attribute that can be used in the tests |
+| `backgroundImageUrl` | `string` | No | - | Provides a link to the background image source (URL). Image will be displayed at the top of a page, underneath the \<Page.Header/>. |
+| `maxWidth` | `number` | No | - | Sets the maximum width of the page (paddings excluded) |
+| `minWidth` | `number` | No | - | Sets the minimum width of the page (paddings excluded) |
+| `height` | `string` | No | - | Sets the height of the page in pixels (px), viewport height (vh), etc. |
+| `sidePadding` | `number` | No | - | Sets the side paddings of a page |
+| `className` | `string` | No | - | Specifies a CSS class name to be appended to the component’s root element. |
+| `gradientClassName` | `string` | No | - | Specifies a CSS class name that defines a gradient background for \<Page.Header/> |
+| `scrollableContentRef` | `((ref: HTMLElement \| null) => void)` | No | - | Defines a reference called together with page scrollable content ref after page mount. <br/> **Note** - if you need this ref only for listening to scroll events on the scrollable content then use this prop instead: `scrollProps = {onScrollChanged/onScrollAreaChanged}` |
+| `zIndex` | `number` | No | - | Specifies the stack order (z-index) of a page |
+| `horizontalScroll` | `boolean` | No | - | Enables page content to scroll horizontally when its width exceed maximum allowed width |
+| `scrollProps` | `ScrollableContainerCommonProps` | No | - | Pass properties related to the scrollable content of the page. <br/> **onScrollAreaChanged** - defines a handler function for scroll area changes. Function is triggered when the user scrolls to a different area of the scrollable content. See signature for possible areas: `function({area: {y: AreaY, x: AreaX}, target: HTMLElement}) => void` `AreaY`: top \| middle \| bottom \| none `AreaX`: start \| middle \| end \| none (not implemented yet) <br/> **onScrollAreaChanged** - defines a general handler for scroll changes with throttling (100ms): `function({target: HTMLElement}) => void` |
+

package/dist/docs/CollectionPremiumEmptyState.md

@@ -0,0 +1,115 @@
+# CollectionPremiumEmptyState
+
+**Category:** Features/Display/Empty States
+
+## Design
+
+### Description
+
+Displays an empty state encouraging users to upgrade to a premiuim plan. Pass through the `emptyState` prop of a [`Grid`](./?path=/story/base-components-collections-grid-grid--grid), [`Table`](./?path=/story/base-components-collections-table-table--table), or other collection component.
+
+
+```tsx
+import { CollectionPremiumEmptyState } from '@wix/patterns';
+```
+
+### Demo
+
+```tsx
+import { Avatar, Text } from '@wix/design-system';
+import React from 'react';
+import { CollectionPage } from '@wix/patterns/page';
+import {
+  TableGridSwitch,
+  useTableGridSwitchCollection,
+  Filter,
+  idNameArrayFilter,
+  stringsArrayFilter,
+  CollectionPremiumEmptyState
+} from '@wix/patterns';
+import { Contact } from '@wix/ambassador-contacts-v4-contact/types';
+import { useHttpClient } from '@wix/yoshi-flow-bm';
+
+interface Duration {
+  id: string;
+  name: string;
+  days: number | null;
+}
+
+type ContactsFilters = {
+  level: Filter<string[]>;
+  lastSeen: Filter<Duration[]>;
+};
+
+function CollectionPremiumEmptyStateExample() {
+  const httpClient = useHttpClient();
+  const state = useTableGridSwitchCollection<Contact, ContactsFilters>({
+    queryName: 'contacts-EmptyStateNewItemCTA',
+    paginationMode: 'offset',
+    fetchData: () =>
+      Promise.resolve({
+        items: [],
+        total: 0,
+      }),
+    itemKey: (item) => item.id as string,
+    itemName: (item) => item.name as string,
+    fetchErrorMessage: () => 'Error fetching contacts',
+    filters: {
+      level: stringsArrayFilter(),
+      lastSeen: idNameArrayFilter(),
+    },
+  });
+
+  return (
+    <CollectionPage height="500px">
+      <CollectionPage.Header title={{ text: 'Contacts' }} />
+      <CollectionPage.Content>
+        <TableGridSwitch
+          state={state}
+          columns={[
+            {
+              title: '',
+              width: '50px',
+              render: (contact) => (
+                <Avatar name={contact.name} imgProps={{ src: contact.image }} />
+              ),
+            },
+            {
+              title: 'Name',
+              width: '250px',
+              render: (contact) => contact.name,
+            },
+            {
+              title: 'Last Seen',
+              render: (contact) => contact.lastSeen?.toLocaleString(),
+            },
+          ]}
+          emptyState={
+            <CollectionPremiumEmptyState upgradeCta={{ onClick: () => {} }} />
+          }
+        />
+      </CollectionPage.Content>
+    </CollectionPage>
+  );
+}
+```
+
+## API
+
+### Props
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `upgradeCta` | `PremiumButtonProps` | Yes | - | Configures the default call to action button.\ `onClick`: Adds a callback for when the button is clicked. <br> `text`: Text of the button. To render the default upgrade button, you must provide the `onClick` callback. |
+| `dataHook` | `string` | No | - | Applies a data-hook HTML attribute to be used in the tests |
+| `className` | `string` | No | - | Specifies a CSS class name to be appended to the component’s root element. |
+| `children` | `ReactNode` | No | - | Contains components rendered below the subtitle, e.g., `<Button/>` or `<TextButton/>` |
+| `title` | `string` | No | - | Overrides the default title. |
+| `skin` | `"page" \| "page-no-border" \| "section"` | No | - | Sets the style skin for the empty state |
+| `theme` | `"page" \| "page-no-border" \| "section"` | No | - | @deprecated use skin prop instead |
+| `subtitle` | `string` | No | - | Overrides the default subtitle. |
+| `image` | `ReactNode` | No | - | Overrides the default image. Accepts a custom `ReactElement` or boolean value. Pass `false` to hide the default image. |
+| `classNames` | `{ imageContainer?: string; }` | No | - | Sets the empty state image bottom margin. If not specified, use the default padding defined in the CSS. |
+| `align` | `"start" \| "center" \| "end"` | No | - | Sets the alignment of all empty state contents within the component container |
+| `customCta` | `ReactNode` | No | - | Adds another custom call to action button. Pass a [TextButton](https://www.docs.wixdesignsystem.com/?path=/story/components-actions--textbutton) component. |
+