@wix/patterns 1.364.0 → 1.369.0

package/dist/docs/Table Sections.md

@@ -0,0 +1,473 @@
+# Table Sections
+
+**Category:** Features/Display/Table Sections
+
+## Design
+
+### Description
+
+Group [`Table`](./?path=/story/base-components-collections-table-table--table) data into sections.
+
+#### Usage
+
+1. Create a [`Table`](./?path=/story/base-components-collections-table-table--table) collection component.
+1. In the `fetchData` function of the [`useTableCollection()`](./?path=/story/base-components-collections-table-usetablecollection--usetablecollection) hook, return data grouped by the desired field for creating sections. You can use `sort` for this, or simply return the data grouped by the field in a flat array. Patterns detects this field and sections the table data by its values.
+1. Define the `sections` prop on the `Table`. The prop must be a [`TableSectionsProp`](./?path=/story/common-types--tablesectionsprop) object, where the `renderSection` callback returns a [`Section`](./?path=/story/common-types--collectionsection) object with `id`, `title`, and optional `primaryAction` properties.
+
+```tsx
+import { TableSections } from '@wix/patterns';
+```
+
+### Demo
+
+This example sorts and groups the data by `jobTitle`.
+
+```tsx
+import React from 'react';
+import { CollectionPage } from '@wix/patterns/page';
+import { Table, TableSections, useTableCollection } from '@wix/patterns';
+import { contacts } from '@wix/crm';
+import { Avatar } from '@wix/design-system';
+import { AddSmall } from '@wix/wix-ui-icons-common';
+
+function TableSectionsExample() {
+  const groupBy = React.useCallback(
+    (item: contacts.Contact) => item.info?.jobTitle as string,
+    [],
+  );
+
+  const renderSection = React.useCallback(
+    (sectionId: string) => ({
+      title: sectionId,
+      primaryAction: {
+        id: 'primary-action',
+        label: 'Primary Action',
+        prefixIcon: <AddSmall />,
+        onClick: () => {},
+      },
+    }),
+    [],
+  );
+
+  const table = useTableCollection<contacts.Contact>({
+    queryName: 'TableSections',
+    paginationMode: 'offset',
+    itemName: (item) => `${item.info?.name?.first} ${item.info?.name?.last}`,
+    fetchData: (query) => {
+      const { limit, offset, search } = query;
+
+      let queryBuilder = contacts.queryContacts().limit(limit).skip(offset);
+
+      if (search) {
+        queryBuilder = queryBuilder.startsWith('info.name.first', search);
+      }
+
+      queryBuilder.ascending('info.jobTitle');
+
+      return queryBuilder.find().then(({ items = [], totalCount: total }) => ({
+        items,
+        total,
+      }));
+    },
+    fetchErrorMessage: ({ err }) => String(err),
+  });
+
+  return (
+    <CollectionPage height="400px">
+      <CollectionPage.Header title={{ text: 'Contacts' }} />
+      <CollectionPage.Content>
+        <Table
+          sections={{
+            TableSections,
+            groupBy,
+            renderSection,
+          }}
+          state={table}
+          columns={[
+            {
+              id: 'avatar',
+              title: '',
+              width: '50px',
+              render: (contact) => (
+                <Avatar
+                  name={`${contact.info?.name?.first} ${contact.info?.name?.last}`}
+                />
+              ),
+            },
+            {
+              id: 'name',
+              title: 'Name',
+              width: '250px',
+              render: (contact) =>
+                `${contact.info?.name?.first} ${contact.info?.name?.last}`,
+            },
+            {
+              id: 'jobTitle',
+              title: 'Job Title',
+              render: (contact) => contact.info?.jobTitle,
+            },
+            {
+              id: 'email',
+              title: 'Email',
+              render: (contact) => contact.primaryEmail,
+            },
+          ]}
+        />
+      </CollectionPage.Content>
+    </CollectionPage>
+  );
+}
+
+export default TableSectionsExample;
+```
+
+### With Badge
+
+This example shows how to use a badge in the section header.
+
+```tsx
+import React from 'react';
+import { CollectionPage } from '@wix/patterns/page';
+import {
+  Section,
+  Table,
+  TableSections,
+  useTableCollection,
+} from '@wix/patterns';
+import { contacts } from '@wix/crm';
+import { Avatar } from '@wix/design-system';
+import { AddSmall } from '@wix/wix-ui-icons-common';
+
+function TableSectionsExample() {
+  const groupBy = React.useCallback((item: contacts.Contact) => {
+    const name = item.info?.name?.first;
+    const jobTitle = item.info?.jobTitle;
+    return `${jobTitle} - ${name?.slice(0, 1).toUpperCase() || 'other'}`;
+  }, []);
+
+  const renderSection = React.useCallback((sectionId: string) => {
+    const firstLetter = sectionId.split(' - ')[1]?.toLowerCase();
+
+    return {
+      title: sectionId,
+      primaryAction: {
+        id: 'primary-action',
+        label: 'Primary Action',
+        prefixIcon: <AddSmall />,
+        onClick: () => {},
+      },
+      badge: {
+        visible: true,
+        skin: firstLetter === 'a' ? 'danger' : 'light',
+      } as Section['badge'],
+    };
+  }, []);
+
+  const table = useTableCollection<contacts.Contact>({
+    queryName: 'TableSections',
+    paginationMode: 'offset',
+    itemName: (item) => `${item.info?.name?.first} ${item.info?.name?.last}`,
+    fetchData: (query) => {
+      const { limit, offset, search } = query;
+
+      let queryBuilder = contacts.queryContacts().limit(limit).skip(offset);
+
+      if (search) {
+        queryBuilder = queryBuilder.startsWith('info.name.first', search);
+      }
+
+      queryBuilder.ascending('info.jobTitle');
+      queryBuilder.ascending('info.name.first');
+      return queryBuilder.find().then(({ items = [], totalCount: total }) => ({
+        items,
+        total,
+      }));
+    },
+    fetchErrorMessage: ({ err }) => String(err),
+  });
+
+  return (
+    <CollectionPage height="400px">
+      <CollectionPage.Header title={{ text: 'Contacts' }} />
+      <CollectionPage.Content>
+        <Table
+          sections={{
+            TableSections,
+            groupBy,
+            renderSection,
+          }}
+          state={table}
+          columns={[
+            {
+              id: 'avatar',
+              title: '',
+              width: '50px',
+              render: (contact) => (
+                <Avatar
+                  name={`${contact.info?.name?.first} ${contact.info?.name?.last}`}
+                />
+              ),
+            },
+            {
+              id: 'name',
+              title: 'Name',
+              width: '250px',
+              render: (contact) =>
+                `${contact.info?.name?.first} ${contact.info?.name?.last}`,
+            },
+            {
+              id: 'jobTitle',
+              title: 'Job Title',
+              render: (contact) => contact.info?.jobTitle,
+            },
+            {
+              id: 'locale',
+              title: 'Locale',
+              render: (contact) => contact.info?.locale,
+            },
+          ]}
+        />
+      </CollectionPage.Content>
+    </CollectionPage>
+  );
+}
+
+export default TableSectionsExample;
+```
+
+### With Summary
+
+This example shows how to use a summary in the section header.
+
+```tsx
+import React from 'react';
+import { CollectionPage } from '@wix/patterns/page';
+import {
+  Section,
+  Table,
+  TableSections,
+  useTableCollection,
+} from '@wix/patterns';
+import { contacts } from '@wix/crm';
+import { Avatar } from '@wix/design-system';
+import { BarSmall, DrinkSmall, AddSmall } from '@wix/wix-ui-icons-common';
+
+function TableSectionsExample() {
+  const groupBy = React.useCallback((item: contacts.Contact) => {
+    return item.info?.jobTitle as string;
+  }, []);
+
+  const renderSection = React.useCallback(
+    (sectionId: string, items: contacts.Contact[]) => {
+      return {
+        title: sectionId,
+        primaryAction: {
+          id: 'primary-action',
+          label: 'Primary Action',
+          prefixIcon: <AddSmall />,
+          onClick: () => {},
+        },
+        badge: {
+          visible: true,
+          skin: 'light',
+        } as Section['badge'],
+        summary: [
+          {
+            icon: <BarSmall />,
+            text: 'English',
+            count: items.filter((item) => item.info?.locale === 'en-US').length,
+          },
+          {
+            icon: <DrinkSmall />,
+            text: 'French',
+            count: items.filter((item) => item.info?.locale === 'fr-FR').length,
+          },
+        ],
+      };
+    },
+    [],
+  );
+
+  const table = useTableCollection<contacts.Contact>({
+    queryName: 'TableSections',
+    paginationMode: 'offset',
+    itemName: (item) => `${item.info?.name?.first} ${item.info?.name?.last}`,
+    fetchData: (query) => {
+      const { limit, offset, search } = query;
+
+      let queryBuilder = contacts.queryContacts().limit(limit).skip(offset);
+
+      if (search) {
+        queryBuilder = queryBuilder.startsWith('info.name.first', search);
+      }
+
+      queryBuilder.ascending('info.jobTitle');
+      queryBuilder.ascending('info.name.first');
+      return queryBuilder.find().then(({ items = [], totalCount: total }) => ({
+        items,
+        total,
+      }));
+    },
+    fetchErrorMessage: ({ err }) => String(err),
+  });
+
+  return (
+    <CollectionPage height="400px">
+      <CollectionPage.Header title={{ text: 'Contacts' }} />
+      <CollectionPage.Content>
+        <Table
+          sections={{
+            TableSections,
+            groupBy,
+            renderSection,
+          }}
+          state={table}
+          columns={[
+            {
+              id: 'avatar',
+              title: '',
+              width: '50px',
+              render: (contact) => (
+                <Avatar
+                  name={`${contact.info?.name?.first} ${contact.info?.name?.last}`}
+                />
+              ),
+            },
+            {
+              id: 'name',
+              title: 'Name',
+              width: '250px',
+              render: (contact) =>
+                `${contact.info?.name?.first} ${contact.info?.name?.last}`,
+            },
+            {
+              id: 'jobTitle',
+              title: 'Job Title',
+              render: (contact) => contact.info?.jobTitle,
+            },
+            {
+              id: 'locale',
+              title: 'Locale',
+              render: (contact) => contact.info?.locale,
+            },
+          ]}
+        />
+      </CollectionPage.Content>
+    </CollectionPage>
+  );
+}
+
+export default TableSectionsExample;
+```
+
+### With Collapse
+
+This example shows how to use a collapse action in the section header.
+
+```tsx
+import React from 'react';
+import { CollectionPage } from '@wix/patterns/page';
+import { Table, TableSections, useTableCollection } from '@wix/patterns';
+import { contacts } from '@wix/crm';
+import { Avatar } from '@wix/design-system';
+
+function TableSectionsExample() {
+  const [collapsedSections, setCollapsedSections] = React.useState<Set<string>>(new Set());
+
+  const groupBy = React.useCallback(
+    (contact: contacts.Contact) => contact.info?.jobTitle ?? 'Unknown',
+    [],
+  );
+  const renderSection = React.useCallback(
+    (sectionId: string) => {
+      return {
+        title: sectionId,
+        collapsed: collapsedSections.has(sectionId),
+      };
+    },
+    [collapsedSections],
+  );
+
+  const table = useTableCollection<contacts.Contact>({
+    queryName: 'TableSections',
+    paginationMode: 'offset',
+    itemName: (item) => `${item.info?.name?.first} ${item.info?.name?.last}`,
+    fetchData: (query) => {
+      const { limit, offset, search } = query;
+
+      let queryBuilder = contacts.queryContacts().limit(limit).skip(offset);
+
+      if (search) {
+        queryBuilder = queryBuilder.startsWith('info.name.first', search);
+      }
+
+      queryBuilder.ascending('info.jobTitle');
+
+      return queryBuilder.find().then(({ items = [], totalCount: total }) => ({
+        items,
+        total,
+      }));
+    },
+    fetchErrorMessage: ({ err }) => String(err),
+  });
+
+  return (
+    <CollectionPage height="400px">
+      <CollectionPage.Header title={{ text: 'Contacts' }} />
+      <CollectionPage.Content>
+        <Table
+          sections={{
+            TableSections,
+            groupBy,
+            renderSection,
+            collapsible: true,
+            events: {
+              onToggle: (sectionId, isCollapsed) => {
+                if (isCollapsed) {
+                  setCollapsedSections(new Set(collapsedSections.add(sectionId)));
+                } else {
+                  collapsedSections.delete(sectionId);
+                  setCollapsedSections(new Set(collapsedSections));
+                }
+              },
+            },
+          }}
+          state={table}
+          columns={[
+            {
+              id: 'avatar',
+              title: '',
+              width: '50px',
+              render: (contact) => (
+                <Avatar
+                  name={`${contact.info?.name?.first} ${contact.info?.name?.last}`}
+                />
+              ),
+            },
+            {
+              id: 'name',
+              title: 'Name',
+              width: '250px',
+              render: (contact) =>
+                `${contact.info?.name?.first} ${contact.info?.name?.last}`,
+            },
+            {
+              id: 'jobTitle',
+              title: 'Job Title',
+              render: (contact) => contact.info?.jobTitle,
+            },
+            {
+              id: 'email',
+              title: 'Email',
+              render: (contact) => contact.primaryEmail,
+            },
+          ]}
+        />
+      </CollectionPage.Content>
+    </CollectionPage>
+  );
+}
+
+export default TableSectionsExample;
+```
+