@wix/patterns 1.364.0 → 1.369.0

package/dist/docs/Tags.md

@@ -0,0 +1,718 @@
+# Tags
+
+**Category:** Features/Enrich/Tags
+
+## Overview
+
+### Introduction
+
+Tags allow users a flexible way to categorize and manage their data.
+
+Wix Patterns table supports displaying the tags as a column, bulk assign for tags and filtering by tags.
+
+You can opt-in to the Tags feature on your collection by using the tags prop in the Table.
+See [Tags overview](./?path=/story/features-enrich-tags--tags-overview) for an overview of the feature and the required server implementation.
+
+## Tags API
+
+You can use the [Tags API](https://dev.wix.com/docs/rest/internal-only/tag-v1/introduction) to create, manage, and list your tags.
+
+Note the following limitations:
+
+- **Tags Limit:** Each FQDN plus exposure combination can have a maximum of 100 tags.
+- **Immutable Tag Exposure:** Once a tag's exposure is set during creation, it can't be changed.
+- **Tenant Support:** The service supports only the `metaSiteId` tenant.
+
+
+### Getting Started
+
+1. Pass `Tags` to [Table](./?path=/story/base-components-collections-table-table--table)
+
+```diff
+import React from 'react';
+import { CollectionPage } from '@wix/patterns/page';
+- import { MyEntity } from '@wix/ambassador-v1-entity/types';
++ import { MyEntity, Tags as TagsType, UpdateEntityRequest } from '@wix/ambassador-v1-entity/types';
++ import { queryMyEntities, bulkUpdateMyEntityNameTags } from '@wix/ambassador-v1-entity/http';
+- import { Table, useTableCollection } from '@wix/patterns';
++ import { Table, useTableCollection, Tags } from '@wix/patterns';
+
+  function TableWithTags() {
+  const httpClient = useHttpClient();
+
+  const state = useTableCollection({
+    queryName: 'my-entity-table-name',
+    paginationMode: 'offset',
+    fqdn: 'wix.domain.MyEntityService.v1.myEntity',
+    fetchData: async () => {
+      const res = await httpClient.request(queryMyEntities());
+
+      return {
+        total: res.data.MyEntities?.length || 0,
+        items: res.data.MyEntities || [],
+      };
+    },
+    fetchErrorMessage: ({ err }) => `Error: ${err}`,
+    itemKey: (item) => item.id!,
+    itemName: (item) => item.name!,
+  });
+
+
+
++  const handleBulkUpdateTags = ({
++      entityIds,
++      assignTags,
++      unassignTags,
++    }: {
++      entityIds: string[];
++      assignTags: TagsType;
++      unassignTags: TagsType;
++    }) => {
++      return httpClient.request(
++        bulkUpdateMyEntityTags({
++          entityIds,
++          assignTags,
++          unassignTags,
++        }),
++      );
++    };
+
+
+  return (
+    
+      
+        
++          }
+          bulkActionToolbar={() => (
+            
+          )}
+          columns={[
+            {
+              id: 'name',
+              hideable: false,
+              title: 'Name',
+              render: (item) => item.name,
+              width: '250px',
+            },
+          ]}
+        />
+      
+    
+    );
+  }
+```
+
+2. For enabling bulk assignment action add [MultiBulkActionToolbar](./?path=/story/features-actions-bulk-actions--multibulkactiontoolbar).
+
+
+## Examples
+
+### Basic
+
+WixPatterns tags provide a default column, filtering, and bulk action for assigning tags.
+
+```tsx
+/* eslint-disable */
+import React from 'react';
+import { CollectionPage } from '@wix/patterns/page';
+import {
+  Table,
+  Tags,
+  useTableCollection,
+  MultiBulkActionToolbar,
+} from '@wix/patterns';
+import {
+  DummyEntity,
+  Tags as TagsType,
+} from '@wix/ambassador-cairo-dummyservice-v1-dummy-entity/types';
+
+function Basic() {
+  const contacts: DummyEntity[] = [
+    {
+      id: '1',
+      name: 'Sadie Ramirez',
+      tags: { privateTags: { tagIds: ['1', '2', '4'] } },
+    },
+    {
+      id: '2',
+      name: 'Jose Pittman	',
+      tags: { privateTags: { tagIds: [] } },
+    },
+    {
+      id: '3',
+      name: 'Garrett Graves	',
+      tags: { privateTags: { tagIds: ['4'] } },
+    },
+  ];
+
+  const state = useTableCollection<DummyEntity>({
+    queryName: 'contacts-table',
+    paginationMode: 'offset',
+    fqdn: 'wix.patterns.dummyservice.v1.dummy_entity',
+    fetchData: async ({ search = '' }) => {
+      // your code to fetch the entity's tags
+      return {
+        total: contacts.length,
+        items: contacts,
+      };
+    },
+    fetchErrorMessage: ({ err }) => `Error: ${err}`,
+    itemKey: (item) => item.id!,
+    itemName: (item) => item.name!,
+  });
+
+  const handleBulkUpdateTags = ({
+    entityIds,
+    assignTags,
+    unassignTags,
+  }: {
+    entityIds: string[];
+    assignTags: TagsType;
+    unassignTags: TagsType;
+  }) => {
+    // your code to update the server
+
+    return Promise.resolve();
+  };
+
+  return (
+    <CollectionPage>
+      <CollectionPage.Header title={{ text: "Contacts" }} />
+      <CollectionPage.Content>
+        <Table
+          state={state}
+          tags={
+            <Tags
+              entityTypeName="Contact"
+              bulkUpdateTags={handleBulkUpdateTags}
+            />
+          }
+          columns={[
+            {
+              id: 'name',
+              hideable: false,
+              title: 'Name',
+              render: (item) => item.name,
+              width: '250px',
+            },
+          ]}
+          bulkActionToolbar={() => <MultiBulkActionToolbar />}
+        />
+      </CollectionPage.Content>
+    </CollectionPage>
+  );
+}
+```
+
+---
+
+### Customized Tags Column position
+
+Position the "Tags" column differently in your table.
+
+```tsx
+/* eslint-disable */
+import React from 'react';
+import { CollectionPage } from '@wix/patterns/page';
+import {
+  Table,
+  Tags,
+  useTagsColumn,
+  useTableCollection,
+  CustomColumns,
+} from '@wix/patterns';
+import {
+  DummyEntity,
+  Tags as TagsType,
+} from '@wix/ambassador-cairo-dummyservice-v1-dummy-entity/types';
+
+function CustomizedTagsColumnPosition() {
+  const contacts: DummyEntity[] = [
+    {
+      id: '1',
+      name: 'Sadie Ramirez',
+      tags: { privateTags: { tagIds: ['1', '2', '4'] } },
+    },
+    {
+      id: '2',
+      name: 'Jose Pittman	',
+      tags: { privateTags: { tagIds: [] } },
+    },
+    {
+      id: '3',
+      name: 'Garrett Graves	',
+      tags: { privateTags: { tagIds: ['4'] } },
+    },
+  ];
+
+  const state = useTableCollection<DummyEntity>({
+    queryName: 'contacts-table',
+    paginationMode: 'offset',
+    fqdn: 'wix.patterns.dummyservice.v1.dummy_entity',
+    fetchData: async ({ search = '' }) => {
+      // your code to fetch the entity's tags
+      return {
+        total: contacts.length,
+        items: contacts,
+      };
+    },
+    fetchErrorMessage: ({ err }) => `Error: ${err}`,
+    itemKey: (item) => item.id!,
+    itemName: (item) => item.name!,
+  });
+
+  const { buildTagsColumn } = useTagsColumn<DummyEntity>();
+
+  const handleBulkUpdateTags = ({
+    entityIds,
+    assignTags,
+    unassignTags,
+  }: {
+    entityIds: string[];
+    assignTags: TagsType;
+    unassignTags: TagsType;
+  }) => {
+    // your code to update the server
+
+    return Promise.resolve();
+  };
+
+  return (
+    <CollectionPage>
+      <CollectionPage.Header title={{text: "Contacts" }} />
+      <CollectionPage.Content>
+        <Table
+          state={state}
+          customColumns={<CustomColumns />}
+          tags={
+            <Tags
+              entityTypeName="Contact"
+              bulkUpdateTags={handleBulkUpdateTags}
+            />
+          }
+          columns={[
+            buildTagsColumn(),
+            {
+              id: 'name',
+              hideable: false,
+              title: 'Name',
+              render: (item) => item.name,
+              width: '250px',
+            },
+          ]}
+        />
+      </CollectionPage.Content>
+    </CollectionPage>
+  );
+}
+```
+
+---
+
+### Custom config for Tags Column
+
+Config the Tags column props. In this example the column the defaultHidden is false
+
+```tsx
+/* eslint-disable */
+import React from 'react';
+import { CollectionPage } from '@wix/patterns/page';
+import {
+  Table,
+  Tags,
+  useTagsColumn,
+  useTableCollection,
+  CustomColumns,
+} from '@wix/patterns';
+import {
+  DummyEntity,
+  Tags as TagsType,
+} from '@wix/ambassador-cairo-dummyservice-v1-dummy-entity/types';
+
+function CustomizedTagsColumnPosition() {
+  const contacts: DummyEntity[] = [
+    {
+      id: '1',
+      name: 'Sadie Ramirez',
+      tags: { privateTags: { tagIds: ['1', '2', '4'] } },
+    },
+    {
+      id: '2',
+      name: 'Jose Pittman	',
+      tags: { privateTags: { tagIds: [] } },
+    },
+    {
+      id: '3',
+      name: 'Garrett Graves	',
+      tags: { privateTags: { tagIds: ['4'] } },
+    },
+  ];
+
+  const state = useTableCollection<DummyEntity>({
+    queryName: 'contacts-table',
+    paginationMode: 'offset',
+    fqdn: 'wix.patterns.dummyservice.v1.dummy_entity',
+    fetchData: async ({ search = '' }) => {
+      // your code to fetch the entity's tags
+      return {
+        total: contacts.length,
+        items: contacts,
+      };
+    },
+    fetchErrorMessage: ({ err }) => `Error: ${err}`,
+    itemKey: (item) => item.id!,
+    itemName: (item) => item.name!,
+  });
+
+  const { buildTagsColumn } = useTagsColumn<DummyEntity>();
+
+  const handleBulkUpdateTags = ({
+    entityIds,
+    assignTags,
+    unassignTags,
+  }: {
+    entityIds: string[];
+    assignTags: TagsType;
+    unassignTags: TagsType;
+  }) => {
+    // your code to update the server
+
+    return Promise.resolve();
+  };
+
+  return (
+    <CollectionPage>
+      <CollectionPage.Header title={{ text: "Contacts" }} />
+      <CollectionPage.Content>
+        <Table
+          state={state}
+          customColumns={<CustomColumns />}
+          tags={
+            <Tags
+              entityTypeName="Contact"
+              bulkUpdateTags={handleBulkUpdateTags}
+              columnConfig={{ defaultHidden: false }} // Config here if you use the default position of tags columns
+            />
+          }
+          columns={[
+            buildTagsColumn({ defaultHidden: false }), // Config here if you use the custom position of tags columns
+            {
+              id: 'name',
+              hideable: false,
+              title: 'Name',
+              render: (item) => item.name,
+              width: '250px',
+            },
+          ]}
+        />
+      </CollectionPage.Content>
+    </CollectionPage>
+  );
+}
+```
+
+---
+
+### Customized Filter position
+
+Locate the Tags filter in a different position on your filters side panel or toolbar.
+
+```tsx
+/* eslint-disable */
+import React from 'react';
+import { CollectionPage } from '@wix/patterns/page';
+import {
+  CollectionToolbarFilters,
+  Table,
+  MultiSelectCheckboxFilter,
+  Tags,
+  idNameArrayFilter,
+  useTagsFilter,
+  useTableCollection,
+  useStaticListFilterCollection,
+} from '@wix/patterns';
+import {
+  DummyEntity,
+  Tags as TagsType,
+} from '@wix/ambassador-cairo-dummyservice-v1-dummy-entity/types';
+
+function CustomizedFilterPosition() {
+  const [filter] = React.useState(() => idNameArrayFilter());
+
+  const filterCollection = useStaticListFilterCollection(
+    filter,
+    [
+      'Beginner',
+      'Amateur',
+      'Semi-Pro',
+      'Professional',
+      'World Class',
+      'Legendary',
+      'Ultimate',
+    ].map((name) => ({ id: name, name })),
+  );
+
+  const contacts: DummyEntity[] = [
+    {
+      id: '1',
+      name: 'Sadie Ramirez',
+      tags: { privateTags: { tagIds: ['1', '2', '4'] } },
+    },
+    {
+      id: '2',
+      name: 'Jose Pittman	',
+      tags: { privateTags: { tagIds: [] } },
+    },
+    {
+      id: '3',
+      name: 'Garrett Graves	',
+      tags: { privateTags: { tagIds: ['4'] } },
+    },
+  ];
+
+  const state = useTableCollection<DummyEntity>({
+    queryName: 'contacts-table',
+    paginationMode: 'offset',
+    fqdn: 'wix.patterns.dummyservice.v1.dummy_entity',
+    fetchData: async ({ search = '' }) => {
+      // your code to fetch the entity's tags
+      return {
+        total: contacts.length,
+        items: contacts,
+      };
+    },
+    fetchErrorMessage: ({ err }) => `Error: ${err}`,
+    itemKey: (item) => item.id!,
+    itemName: (item) => item.name!,
+  });
+
+  const { buildTagsFilter } = useTagsFilter(state);
+  const tagsFilter = buildTagsFilter();
+
+  const handleBulkUpdateTags = ({
+    entityIds,
+    assignTags,
+    unassignTags,
+  }: {
+    entityIds: string[];
+    assignTags: TagsType;
+    unassignTags: TagsType;
+  }) => {
+    // your code to update the server
+
+    return Promise.resolve();
+  };
+
+  return (
+    <CollectionPage>
+      <CollectionPage.Header title={{ text: "Contacts" }} />
+      <CollectionPage.Content>
+        <Table
+          state={state}
+          tags={
+            <Tags
+              entityTypeName="Contact"
+              bulkUpdateTags={handleBulkUpdateTags}
+            />
+          }
+          columns={[
+            {
+              id: 'name',
+              hideable: false,
+              title: 'Name',
+              render: (item) => item.name,
+              width: '250px',
+            },
+          ]}
+          filters={
+            <CollectionToolbarFilters>
+              {tagsFilter}
+              <MultiSelectCheckboxFilter
+                popoverProps={{ appendTo: 'window' }}
+                filter={filter}
+                collection={filterCollection}
+              />
+            </CollectionToolbarFilters>
+          }
+        />
+      </CollectionPage.Content>
+    </CollectionPage>
+  );
+}
+```
+
+---
+
+### On Table with Folders
+
+This example shows a `TableFolders` component with tags. Note that you can only assign tags to table items and not to folders.
+
+```tsx
+import React from 'react';
+import { CollectionPage } from '@wix/patterns/page';
+import {
+  TagsFolders,
+  MultiBulkActionToolbar,
+  useCollection,
+  TableFolders,
+  useTableFolders,
+  CustomColumns,
+  OffsetQuery,
+} from '@wix/patterns';
+import { Tags as TagsType } from '@wix/ambassador-cairo-dummyservice-v1-dummy-entity/types';
+import { queryContacts } from '@wix/ambassador-contacts-v4-contact/http';
+import { Contact } from '@wix/ambassador-contacts-v4-contact/types';
+import { useHttpClient } from '@wix/yoshi-flow-bm';
+
+function TagsOnTableFolders() {
+  const httpClient = useHttpClient();
+
+  const collection = useCollection<Contact>({
+    queryName: 'tableitems',
+    fqdn: 'wix.patterns.dummyservice.v1.dummy_entity',
+    itemKey: (item) => item.id as string,
+    itemName: (item) => item.name as string,
+    fetchData: (query: OffsetQuery) => {
+      const { limit, offset, search, filters } = query;
+      return httpClient
+        .request(
+          queryContacts({
+            query: { paging: { limit, offset }, filter: filters },
+            search,
+          }),
+        )
+        .then((res) => {
+          const {
+            data: { contacts = [], pagingMetadata },
+          } = res;
+          return {
+            items: contacts,
+            total: pagingMetadata?.total,
+          };
+        });
+    },
+    fetchErrorMessage: ({ err }) => String(err),
+  });
+
+  // Note: This is only for demo/mock purposes.
+  // In real usage, you should use your actual API method to fetch folders
+  const foldersCollection = useCollection<Contact>({
+    queryName: 'tablefolders',
+    paginationMode: 'offset',
+    itemName: (item) => item.name as string,
+    fetchData: (query: OffsetQuery) => {
+      const { limit, offset, search, filters } = query;
+      return httpClient
+        .request(
+          queryContacts({
+            query: { paging: { limit: 2, offset }, filter: filters },
+            search,
+          }),
+        )
+        .then((res) => {
+          const {
+            data: { contacts = [], pagingMetadata },
+          } = res;
+          return {
+            items: contacts.map((contact) => ({
+              ...contact,
+              id: `folder-${contact.id}`,
+            })),
+            total: 2,
+          };
+        });
+    },
+    fetchErrorMessage: ({ err }) => String(err),
+  });
+
+  const componentState = useTableFolders({
+    items: collection,
+    folders: foldersCollection,
+  });
+
+  const handleBulkUpdateTags = ({
+    entityIds,
+    assignTags,
+    unassignTags,
+  }: {
+    entityIds: string[];
+    assignTags: TagsType;
+    unassignTags: TagsType;
+  }) => {
+    // your code to update the server
+    return Promise.resolve();
+  };
+
+  return (
+    <CollectionPage height="400px">
+      <CollectionPage.Header title={{ text: 'Contacts' }} />
+      <CollectionPage.Content>
+        <TableFolders
+          state={componentState}
+          tags={
+            <TagsFolders
+              entityTypeName="Contact"
+              bulkUpdateTags={handleBulkUpdateTags}
+            />
+          }
+          customColumns={<CustomColumns />}
+          columns={[
+            {
+              id: 'name',
+              hideable: false,
+              title: 'Name',
+              render: (contact) => contact.name,
+              renderFolder: (folder) => folder.name,
+              width: '250px',
+            },
+          ]}
+          bulkActionToolbar={() => <MultiBulkActionToolbar />}
+        />
+      </CollectionPage.Content>
+    </CollectionPage>
+  );
+}
+```
+
+## API
+
+### Props
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `entityTypeName` | `string` | Yes | - | A string that represents the name of the entity type(for example "Orders"), will be shown on the title of the manage tags modal |
+| `columnConfig` | `TagsColumnConfig<T>` | No | - | Optional config for the column @param hideable When set to false, will make the column always being checked and shown @param defaultHidden Unchecks the column by default for the first visit (not relevant when hideable=false) |
+| `bulkUpdateTags` | `(params: BulkUpdateTagsParams) => Promise<unknown>` | Yes | - | A callback function that gets a list of assigned and a list of unassigned tags for the selected entities in the bulk and updates the entities according to it @param assignTags The assign tags objects that need to be update in the entities @param unassignTags The unassign tags objects that need to be update in the entities @param entityIds The entities IDs that need to be updated |
+| `asyncBulkUpdateTags` | `((params: AsyncBulkUpdateTagsParams<T, F>) => Promise<{ jobId: string; }>)` | No | - | A callback function that takes the user's current entity selection as a parameter and starts an asynchronous bulk update of the tags using asyncJobInfra |
+| `disableDefaultPageAction` | `boolean` | No | - | When set to true, will disable "Manage tags" action in the page actions menu. |
+
+## BI
+
+### Tags Events
+
+| Event                                                                                                     | Description                                                        |
+| --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
+| [144:166](https://bo.wix.com/data-tools/bi-catalog-app/event/144:166) |  Send when a user click on a "Tags Modal" |
+| [144:167](https://bo.wix.com/data-tools/bi-catalog-app/event/144:167) |Send when a user click on button that will close "Tags Modal" |
+| [144:168](https://bo.wix.com/data-tools/bi-catalog-app/event/144:168) | Send when a user add or delete a tag from his component |
+| [144:169](https://bo.wix.com/data-tools/bi-catalog-app/event/144:169) | Send when a user tried to add/delete/rename/assign/remove assigned tag, but his changes weren't update in the server from different reasons |
+| [144:170](https://bo.wix.com/data-tools/bi-catalog-app/event/144:170) | Sent when the search results are displayed, after a user searches for a tag. Relevant for tables that enabled using tags |
+| [144:171](https://bo.wix.com/data-tools/bi-catalog-app/event/144:171) | Send when a Tags' widget is loaded |
+| [144:172](https://bo.wix.com/data-tools/bi-catalog-app/event/144:172) | Send when a user click on the widget's ctas |
+| [144:173](https://bo.wix.com/data-tools/bi-catalog-app/event/144:173) | Send when a user assign or remove a tag from an item |
+| [144:175](https://bo.wix.com/data-tools/bi-catalog-app/event/144:175) | Assign Tags to entities |
+
+
+
+### 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)
+
+