@wix/patterns 1.366.0 → 1.369.0

package/dist/docs/SummaryBar.md

@@ -0,0 +1,515 @@
+# SummaryBar
+
+**Category:** Features/Display/Toolbar
+
+## Design
+
+### Description
+
+Displays summary information.
+
+This data is not updated dynamically as part of a collection's fetch, meaning you need to update it youself.
+
+### Success
+
+This example shows the summary bar in the `"success"` state using the `` `status` prop.
+
+```tsx
+/* eslint-disable import/no-extraneous-dependencies */
+import React from 'react';
+import { Page } from '@wix/design-system';
+import {
+  Table,
+  PageWrapper,
+  SummaryBar,
+  SummaryData,
+  useTableCollection,
+  OffsetQuery,
+} from '@wix/patterns';
+import { contacts } from '@wix/crm';
+
+function SuccessState() {
+
+  const state = useTableCollection<contacts.Contact>({
+    queryName: 'contacts-summaryBar',
+    paginationMode: 'offset',
+    fqdn: 'wix.patterns.dummyservice.v1.dummy_entity',
+    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',
+    filters: {},
+  });
+
+  return (
+    <PageWrapper>
+      <Page height="400px">
+        <Page.Header />
+        <Page.Content>
+          <Table
+            state={state}
+            summaryBar={
+              <SummaryBar
+                data={
+                  [
+                    { title: 'Orders', value: '12' },
+                    { title: 'Restaurants', value: '420' },
+                    { title: 'Deliveries', value: '42' },
+                  ] as SummaryData
+                }
+                status="success"
+                onRetry={async () => {}}
+              />
+            }
+            columns={[
+              {
+                id: 'name',
+                title: 'Name',
+                width: '250px',
+                render: (contact) =>
+                  `${contact.info?.name?.first} ${contact.info?.name?.last}`,
+              },
+            ]}
+          />
+        </Page.Content>
+      </Page>
+    </PageWrapper>
+  );
+}
+```
+
+---
+
+### Loading
+
+This example shows the summary bar in the `"loading"` state using the `` `status` prop.
+
+```tsx
+/* eslint-disable import/no-extraneous-dependencies */
+import React from 'react';
+import { Page } from '@wix/design-system';
+import {
+  Table,
+  PageWrapper,
+  SummaryBar,
+  SummaryData,
+  useTableCollection,
+  OffsetQuery,
+} from '@wix/patterns';
+import { contacts } from '@wix/crm';
+
+function LoadingState() {
+
+  const state = useTableCollection<contacts.Contact>({
+    queryName: 'contacts-summaryBar',
+    paginationMode: 'offset',
+    fqdn: 'wix.patterns.dummyservice.v1.dummy_entity',
+    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',
+    filters: {},
+  });
+
+  return (
+    <PageWrapper>
+      <Page height="400px">
+        <Page.Header />
+        <Page.Content>
+          <Table
+            state={state}
+            summaryBar={
+              <SummaryBar
+                data={
+                  [
+                    { title: 'Orders', value: '12' },
+                    { title: 'Restaurants', value: '420' },
+                    { title: 'Deliveries', value: '42' },
+                  ] as SummaryData
+                }
+                status="loading"
+                onRetry={async () => {}}
+              />
+            }
+            columns={[
+              {
+                id: 'name',
+                title: 'Name',
+                width: '250px',
+                render: (contact) =>
+                  `${contact.info?.name?.first} ${contact.info?.name?.last}`,
+              },
+            ]}
+          />
+        </Page.Content>
+      </Page>
+    </PageWrapper>
+  );
+}
+```
+
+---
+
+### Error
+
+This example shows the summary bar in the `"error"` state using the `` `status` prop.
+
+```tsx
+/* eslint-disable import/no-extraneous-dependencies */
+import React from 'react';
+import { Page } from '@wix/design-system';
+import {
+  Table,
+  PageWrapper,
+  SummaryBar,
+  SummaryData,
+  useTableCollection,
+  OffsetQuery,
+} from '@wix/patterns';
+import { contacts } from '@wix/crm';
+
+function ErrorState() {
+
+  const state = useTableCollection<contacts.Contact>({
+    queryName: 'contacts-summaryBar',
+    paginationMode: 'offset',
+    fqdn: 'wix.patterns.dummyservice.v1.dummy_entity',
+    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',
+    filters: {},
+  });
+
+  return (
+    <PageWrapper>
+      <Page height="400px">
+        <Page.Header />
+        <Page.Content>
+          <Table
+            state={state}
+            summaryBar={
+              <SummaryBar
+                data={
+                  [
+                    { title: 'Orders', value: '12' },
+                    { title: 'Restaurants', value: '420' },
+                    { title: 'Deliveries', value: '42' },
+                  ] as SummaryData
+                }
+                status="error"
+                onRetry={async () => {
+                  /* refetch summary*/
+                }}
+              />
+            }
+            columns={[
+              {
+                id: 'name',
+                title: 'Name',
+                width: '250px',
+                render: (contact) =>
+                  `${contact.info?.name?.first} ${contact.info?.name?.last}`,
+              },
+            ]}
+          />
+        </Page.Content>
+      </Page>
+    </PageWrapper>
+  );
+}
+```
+
+---
+
+### Loading with success
+
+This example shows the summary bar in the `"loading"` state, that changes to the `"success"` state when the data is fetched, using the `` `status` prop.
+
+```tsx
+/* eslint-disable import/no-extraneous-dependencies */
+import React from 'react';
+import { Page } from '@wix/design-system';
+import {
+  Table,
+  PageWrapper,
+  PrimaryActionButton,
+  SummaryBar,
+  SummaryBarStatus,
+  useTableCollection,
+  useSelector,
+  OffsetQuery,
+} from '@wix/patterns';
+import { contacts } from '@wix/crm';
+
+function LoadWithSuccess() {
+
+  const state = useTableCollection<contacts.Contact>({
+    queryName: 'contacts-summaryBar',
+    paginationMode: 'offset',
+    fqdn: 'wix.patterns.dummyservice.v1.dummy_entity',
+    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',
+    filters: {},
+  });
+
+  const [summaryStatus, setSummaryStatus] =
+    React.useState<SummaryBarStatus>('loading');
+  const [ordersCount, setOrderCount] = React.useState<number>(
+    state.collection.result.items.length,
+  );
+
+  const loadOrderCount: () => Promise<number> = async () => {
+    return new Promise((resolve) => {
+      window.setTimeout(() => {
+        resolve(state.collection.result.items.length);
+      }, 5000);
+    });
+  };
+
+  React.useEffect(() => {
+    const fetchData = async () => {
+      const ordersCount = await loadOrderCount();
+      setOrderCount(ordersCount);
+      setSummaryStatus('success');
+    };
+
+    fetchData();
+  }, []);
+
+  const collectionItems = useSelector(
+    () => state.collection.result.items.length,
+  );
+
+  React.useEffect(() => {
+    console.log(collectionItems);
+    setOrderCount(state.collection.result.items.length);
+  }, [collectionItems]);
+
+  return (
+    <PageWrapper>
+      <Page height="400px">
+        <Page.Header />
+        <Page.Content>
+          <Table
+            state={state}
+            summaryBar={
+              <SummaryBar
+                data={[
+                  { title: 'Orders Contacts', value: String(ordersCount) },
+                ]}
+                status={summaryStatus}
+                onRetry={async () => {}}
+              />
+            }
+            columns={[
+              {
+                id: 'name',
+                title: 'Name',
+                width: '250px',
+                render: (contact) =>
+                  `${contact.info?.name?.first} ${contact.info?.name?.last}`,
+              },
+            ]}
+            primaryActionButton={<PrimaryActionButton />}
+          />
+        </Page.Content>
+      </Page>
+    </PageWrapper>
+  );
+}
+```
+
+---
+
+### Loading with error
+
+This example shows the summary bar in the `"loading"` state, that changes to the `"error"` state when the data fetch fails, using the `` `status` prop.
+The `onRetry` prop is used to retry the fetch the data when **Reload** is clicked.
+
+```tsx
+/* eslint-disable import/no-extraneous-dependencies */
+import React from 'react';
+import { Page } from '@wix/design-system';
+import {
+  Table,
+  PageWrapper,
+  SummaryBar,
+  SummaryBarStatus,
+  SummaryData,
+  useTableCollection,
+  OffsetQuery,
+} from '@wix/patterns';
+import { contacts } from '@wix/crm';
+
+function LoadWithError() {
+
+  const state = useTableCollection<contacts.Contact>({
+    queryName: 'contacts-summaryBar',
+    paginationMode: 'offset',
+    fqdn: 'wix.patterns.dummyservice.v1.dummy_entity',
+    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',
+    filters: {},
+  });
+
+  const [summaryStatus, setSummaryStatus] =
+    React.useState<SummaryBarStatus>('loading');
+  const [summaryData, setSummaryData] = React.useState<SummaryData>([]);
+  const loadSummaryData: () => Promise<SummaryData> = async () => {
+    return new Promise((resolve, reject) => {
+      window.setTimeout(() => {
+        reject('error');
+      }, 2000);
+    });
+  };
+
+  const fetchData = async () => {
+    setSummaryStatus('loading');
+    try {
+      const summaryBarData = await loadSummaryData();
+      setSummaryData(summaryBarData);
+      setSummaryStatus('success');
+    } catch (error) {
+      setSummaryStatus('error');
+    }
+  };
+
+  React.useEffect(() => {
+    fetchData();
+  }, []);
+
+  return (
+    <PageWrapper>
+      <Page height="400px">
+        <Page.Header />
+        <Page.Content>
+          <Table
+            state={state}
+            summaryBar={
+              <SummaryBar
+                data={summaryData}
+                status={summaryStatus}
+                onRetry={async () => {
+                  await fetchData();
+                }}
+              />
+            }
+            columns={[
+              {
+                id: 'name',
+                title: 'Name',
+                width: '250px',
+                render: (contact) =>
+                  `${contact.info?.name?.first} ${contact.info?.name?.last}`,
+              },
+            ]}
+          />
+        </Page.Content>
+      </Page>
+    </PageWrapper>
+  );
+}
+```
+
+## API
+
+### Props
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `data` | `SummaryData` | Yes | - | Data to display in the summary bar. |
+| `status` | `"error" \| "loading" \| "success"` | Yes | `success` | Summary bar status. <br><br> Supported values:<br> - `"success"`<br> - `"loading"`<br> - `"error"` |
+| `onRetry` | `() => void \| Promise<void>` | Yes | - | Function that is called every time **Reload** is clicked. |
+
+## BI
+
+### Events
+
+We haven't defined any events for this feature yet.
+
+
+
+### 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)
+
+
+## Testkit
+
+### Usage
+
+`getSummaryBar` API is exposed from the `` [testkit](./?path=/story/components-collection--table&tab=Testkit)
+
+