@wix/patterns 1.366.0 → 1.369.0

package/dist/docs/TabsFilter.md

@@ -0,0 +1,484 @@
+# TabsFilter
+
+**Category:** Features/Filter/Components
+
+## Design
+
+### Description
+
+Filter component that always renders in the toolbar.
+
+Make sure to check your tab names in other languages. Default tab names may be short in English but not in other languages.
+
+Stay away from using:
+- Tabs and table filters together.
+- More than four tabs.
+
+```tsx
+import { TabsFilter } from '@wix/patterns';
+```
+
+---
+
+### Variations
+
+### Basic Tabs
+
+This example uses the `` `data` prop to include filter tabs in the table.
+
+```tsx
+import { Avatar } from '@wix/design-system';
+import React from 'react';
+import { CollectionPage } from '@wix/patterns/page';
+import {
+  Filter,
+  Table,
+  TabsFilter,
+  useTableCollection,
+  idNameArrayFilter,
+  OffsetQuery,
+} from '@wix/patterns';
+import { contacts } from '@wix/crm';
+
+type ContactsFilters = {
+  level: Filter<{ id: string; name: string }[]>;
+};
+
+function TabsFilterExample() {
+
+  const state = useTableCollection<contacts.Contact, ContactsFilters>({
+    queryName: 'TabsFilterExample',
+    fetchData: (query: OffsetQuery<ContactsFilters>) => {
+      const { limit, offset, search, filters } = query;
+
+      let queryBuilder = contacts.queryContacts().limit(limit).skip(offset);
+
+      if (search) {
+        queryBuilder = queryBuilder.startsWith('info.name.first', search);
+      }
+
+      if (filters.level) {
+        queryBuilder = queryBuilder.in(
+          'info.jobTitle',
+          filters.level.map(({ id }) => id),
+        );
+      }
+
+      return queryBuilder.find().then(({ items = [], totalCount: total }) => ({
+        items,
+        total,
+      }));
+    },
+    itemName: (item) => `${item.info?.name?.first} ${item.info?.name?.last}`,
+    fetchErrorMessage: ({ err }) => String(err),
+    filters: {
+      level: idNameArrayFilter({
+        initialValue: [{ id: 'Beginner', name: 'Beginner' }],
+      }),
+    },
+  });
+  const collection = state.collection;
+  return (
+    <CollectionPage height="400px">
+      <CollectionPage.Header title={{ text: 'Contacts' }} />
+      <CollectionPage.Content>
+        <Table
+          state={state}
+          tabs={
+            <TabsFilter
+              filter={collection.filters.level}
+              data={[
+                { id: 'Beginner', name: 'Beginner' },
+                { id: 'Professional', name: 'Professional' },
+                { id: 'World Class', name: 'World Class' },
+              ]}
+              all="All Levels"
+            />
+          }
+          columns={[
+            {
+              title: '',
+              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(),
+            },
+          ]}
+        />
+      </CollectionPage.Content>
+    </CollectionPage>
+  );
+}
+```
+
+### Tabs with a basic counter
+
+This example uses the `` `counterBadge` prop to include a counter badge in the table's filter tabs.
+
+```tsx
+import { Avatar } from '@wix/design-system';
+import React from 'react';
+import { CollectionPage } from '@wix/patterns/page';
+import {
+  Filter,
+  Table,
+  TabsFilter,
+  TabTotalParens,
+  useTableCollection,
+  useOptimisticActions,
+  idNameArrayFilter,
+  OffsetQuery,
+} from '@wix/patterns';
+import { contacts } from '@wix/crm';
+
+type ContactsFilters = {
+  level: Filter<{ id: string; name: string }[]>;
+};
+
+function TabsFilterTotalParensExample() {
+  const state = useTableCollection<contacts.Contact, ContactsFilters>({
+    queryName: 'TabsFilterTotalParensExample',
+    fetchData: (query: OffsetQuery<ContactsFilters>) => {
+      const { limit, offset, search, filters } = query;
+
+      let queryBuilder = contacts.queryContacts().limit(limit).skip(offset);
+
+      if (search) {
+        queryBuilder = queryBuilder.startsWith('info.name.first', search);
+      }
+
+      if (filters.level) {
+        queryBuilder = queryBuilder.in(
+          'info.jobTitle',
+          filters.level.map(({ id }) => id),
+        );
+      }
+
+      return queryBuilder.find().then(({ items = [], totalCount: total }) => ({
+        items,
+        total,
+      }));
+    },
+    itemName: (item) => `${item.info?.name?.first} ${item.info?.name?.last}`,
+    fetchErrorMessage: ({ err }) => String(err),
+    filters: {
+      level: idNameArrayFilter({
+        initialValue: [{ id: 'Beginner', name: 'Beginner' }],
+      }),
+    },
+  });
+  const collection = state.collection;
+  const optimisticActions = useOptimisticActions(collection, {
+    predicate: ({ filters }) => {
+      return (contact) => {
+        if (
+          Array.isArray(filters.level) &&
+          filters.level.length &&
+          filters.level.every((e) => e.id !== contact.info?.jobTitle)
+        ) {
+          return false;
+        }
+
+        return true;
+      };
+    },
+  });
+  return (
+    <CollectionPage height="400px">
+      <CollectionPage.Header title={{ text: 'Contacts' }} />
+      <CollectionPage.Content>
+        <Table
+          state={state}
+          actionCell={(item) => ({
+            primaryAction:
+              item.info?.jobTitle !== 'World Class'
+                ? {
+                    text: 'World Class',
+                    onClick: () => {
+                      const updatedContacts = [
+                        {
+                          ...item,
+                          info: {
+                            ...item.info,
+                            jobTitle: 'World Class',
+                          },
+                        },
+                      ];
+                      optimisticActions.updateMany(updatedContacts, {
+                        submit: (_contacts) =>
+                          Promise.all(
+                            _contacts.map((contact) =>
+                              contacts.updateContact(
+                                contact._id as string,
+                                contact.info as contacts.ContactInfo,
+                                contact.revision as number,
+                              ),
+                            ),
+                          ),
+                      });
+                    },
+                  }
+                : undefined,
+          })}
+          tabs={
+            <TabsFilter
+              filter={collection.filters.level}
+              data={[
+                { id: 'Beginner', name: 'Beginner' },
+                { id: 'Professional', name: 'Professional' },
+                { id: 'World Class', name: 'World Class' },
+              ]}
+              all="All Levels"
+              counterBadge={(item) => (
+                <TabTotalParens
+                  optimisticActions={optimisticActions}
+                  value={item}
+                />
+              )}
+            />
+          }
+          columns={[
+            {
+              title: '',
+              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(),
+            },
+          ]}
+        />
+      </CollectionPage.Content>
+    </CollectionPage>
+  );
+}
+```
+
+### Tabs with a counter badge
+
+This example uses the `` `counterBadge` prop to include a counter badge in the table's filter tabs.
+
+```tsx
+import { Avatar } from '@wix/design-system';
+import React from 'react';
+import { CollectionPage } from '@wix/patterns/page';
+import {
+  Filter,
+  Table,
+  TabsFilter,
+  TabTotalCounterBadge,
+  useTableCollection,
+  useOptimisticActions,
+  idNameArrayFilter,
+  OffsetQuery,
+} from '@wix/patterns';
+import { contacts } from '@wix/crm';
+
+type ContactsFilters = {
+  level: Filter<{ id: string; name: string }[]>;
+};
+
+function TabsFilterTotalBadgeExample() {
+  const state = useTableCollection<contacts.Contact, ContactsFilters>({
+    queryName: 'TabsFilterTotalBadgeExample',
+    fetchData: (query: OffsetQuery<ContactsFilters>) => {
+      const { limit, offset, search, filters } = query;
+
+      let queryBuilder = contacts.queryContacts().limit(limit).skip(offset);
+
+      if (search) {
+        queryBuilder = queryBuilder.startsWith('info.name.first', search);
+      }
+
+      if (filters.level) {
+        queryBuilder = queryBuilder.in(
+          'info.jobTitle',
+          filters.level.map(({ id }) => id),
+        );
+      }
+
+      return queryBuilder.find().then(({ items = [], totalCount: total }) => ({
+        items,
+        total,
+      }));
+    },
+    itemName: (item) => `${item.info?.name?.first} ${item.info?.name?.last}`,
+    fetchErrorMessage: ({ err }) => String(err),
+    filters: {
+      level: idNameArrayFilter({
+        initialValue: [{ id: 'Beginner', name: 'Beginner' }],
+      }),
+    },
+  });
+  const collection = state.collection;
+  const optimisticActions = useOptimisticActions(collection, {
+    predicate: ({ filters }) => {
+      return (contact) => {
+        if (
+          Array.isArray(filters.level) &&
+          filters.level.length &&
+          filters.level.every((e) => e.id !== contact.info?.jobTitle)
+        ) {
+          return false;
+        }
+
+        return true;
+      };
+    },
+  });
+
+  return (
+    <CollectionPage height="400px">
+      <CollectionPage.Header title={{ text: 'Contacts' }} />
+      <CollectionPage.Content>
+        <Table
+          state={state}
+          actionCell={(item) => ({
+            primaryAction:
+              item.info?.jobTitle !== 'World Class'
+                ? {
+                    text: 'World Class',
+                    onClick: () => {
+                      const updatedContacts = [
+                        {
+                          ...item,
+                          info: {
+                            ...item.info,
+                            jobTitle: 'World Class',
+                          },
+                        },
+                      ];
+
+                      optimisticActions.updateMany(updatedContacts, {
+                        submit: (_contacts) =>
+                          Promise.all(
+                            _contacts.map((contact) =>
+                              contacts.updateContact(
+                                contact._id as string,
+                                contact.info as contacts.ContactInfo,
+                                contact.revision as number,
+                              ),
+                            ),
+                          ),
+                      });
+                    },
+                  }
+                : undefined,
+          })}
+          tabs={
+            <TabsFilter
+              filter={collection.filters.level}
+              data={[
+                { id: 'Beginner', name: 'Beginner' },
+                { id: 'Professional', name: 'Professional' },
+                { id: 'World Class', name: 'World Class' },
+              ]}
+              all="All Levels"
+              counterBadge={(item) => (
+                <TabTotalCounterBadge
+                  optimisticActions={optimisticActions}
+                  value={item}
+                />
+              )}
+            />
+          }
+          columns={[
+            {
+              title: '',
+              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(),
+            },
+          ]}
+        />
+      </CollectionPage.Content>
+    </CollectionPage>
+  );
+}
+```
+
+## API
+
+### Props
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `data` | `V[]` | Yes | - | List of tabs. |
+| `filter` | `Filter<V[]>` | Yes | - | Defines the selected filter. <br><br> Must be an [arrayFilter](./?path=/story/features-filter-factories--arrayfilter) object. |
+| `all` | `string \| false \| null` | No | - | Display name of the tab that indicates that all items are included. <br> Changes the value of `filter` to an empty array. |
+| `counterBadge` | `((value: V \| null) => TabTotalCounterBadge<V> \| TabTotalParens<V> \| null) \| undefined` | No | - | Renders a counter badge next to the tabs' texts. <br><br> See different examples of this implementation in the [Overview](./?path=/story/features-filter-components--tabsfilter) tab. |
+| `type` | `"uniformFull"` | No | - | Tabs layout type. <br><br> If this prop is omitted, the width depends on the label width. The total width of all the tabs cannot exceed 80% of the toolbar. <br><br> Supported values:<br> - `uniformFull`: Tabs are spread out uniformly. |
+| `mobilePopoverProps` | `PopoverCommonProps` | No | - | Custom popover props for the mobile dropdown menu. On mobile devices, tabs are displayed as a dropdown menu. |
+
+## BI
+
+### Tabs Filter Events
+
+  Event   |   Description   |
+--------- | --------------- |
+[144:121](https://bo.wix.com/data-tools/bi-catalog-app/event/144:121) | Sent when a user selects a tab in a Wix Patterns component
+
+
+
+
+### 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
+
+`getToolbarTabs` API is exposed from the `` [testkit](./?path=/story/base-components-collections-table-table--table&activeTab=Testkit)
+
+

package/dist/docs/Tags Overview.md

@@ -0,0 +1,118 @@
+# Tags Overview
+
+**Category:** Features/Enrich/Tags
+
+## Overview
+
+### Introduction
+
+This document provides an overview and usage guidelines for the Tags feature in Wix Patterns. Tags are labels that can be attached to entities, offering a flexible way to categorize and manage data.
+
+### Feature Overview
+
+Tags in Wix Patterns are supported in multiple areas. They are primarily used in two contexts:
+
+- **Collection Page**: Where tags can be used to organize and filter entities in a table view.
+- **Entity Page**: Where tags can be managed for individual entities through the TagsWidget.
+
+Tags Limit: Users can create up to 100 tags per entity and accordingly assign up to 100 tags to a single item.
+
+#### Using Tags in the Collection Page
+
+You can opt-in to the Tags feature on collection page by using the `tags` prop in the `Table` component. The `tags` prop accepts a `Tags` component that you should import from `@wix/patterns`. The following features are supported:
+
+- Displaying tags as a column in the entities table
+- Filtering the table by tags
+- Bulk assigning tags to multiple entities
+- Adding, updating, and deleting tags via modal
+
+##### Supported Components
+
+The Tags feature is supported in the following components:
+
+- Table
+- TableGridSwitch (only the table view)
+- TableFolders
+- TableGridSwitchFolders (only the table view)
+
+#### Using Tags in the Entity Page
+
+Using tags in entity page can be used to manage tags for a specific entity. The following features are supported:
+
+- Viewing all tags associated with the entity
+- Assigning new tags to the entity
+- Removing existing tags from the entity
+
+Read more about [Tags](./?path=/story/features-enrich-tags--tagswidget).
+
+
+## Server Prerequisites
+
+
+### Overview
+
+The backend implementation of tags can be divided into two parts:
+1. **Management of which tags exist for each FQDN** - This is handled by the [Tags Service](https://github.com/wix-private/wixos/tree/master/tags-service), which is managed by Wix Patterns. This service is responsible for creating, updating, and deleting tags for each FQDN.
+
+2. **Management of which tags are assigned to each entity** - For implementation details, please refer to the official guidelines provided by P13n [here](https://github.com/wix-private/server-infra/tree/master/framework/loom-prime/examples/prime-tags). Currently, the endpoint with filter functionality is not supported on the client side. If you require this functionality, please contact us directly.
+
+### Adding support for tags for specific entity
+
+#### Tags Field
+The entity should have a `tags` field in the entity's schema. It should be of type as described in this [protobuf](https://github.com/wix-private/p13n/blob/186e5c8cc7245686cc8f5558672d34f9075ef7a2/protos/common/src/main/proto/wix/common/tags.proto#L33). On Scala, you can import it from `wix.common.tags`. For example, a product entity can be defined in the following structure:
+
+```js
+{
+  id: "123",
+  name: "Super shoes",
+  tags: {
+    privateTags: {
+      tagIds: ["222","333"]
+    },
+    tags: {
+      tagIds: ["444","555"]
+    }
+  }
+}
+```
+
+An example for defining the `tags` field in a proto file:
+
+```js
+message Product {
+  option (.wix.api.entity) = {
+    fqdn: "wix.ecom.catalog.v1.product"
+    taggable: {}
+    extensible: {}
+  }
+  string id = 1;
+  string name = 2;
+  wix.common.tags tags = 3;
+}
+```
+
+**More details and limitations on tags:**
+- Each entity can be labeled with multiple tags.
+- Maximum of 100 tags per entity.
+- Each tag is a short string (max 250 characters) and is case-insensitive.
+- No enforcement on the character set.
+- Tags must be unique on a given entity. Assigning a tag to an entity that already has it assigned is a no-op, with no error returned. The same applies when attempting to unassign a tag that the entity does not have.
+- Currently, Wix Patterns supports only private tags. Public tags are not supported.
+- Private tags are not presented to UoU and should be filtered out from any UoU responses.
+
+#### Permissions and Security
+
+- The permission on the `BulkUpdateTags` endpoint should be separate from the `update` endpoint to allow assignment to specific users/apps without granting full edit capabilities.
+- The permission to assign/unassign private tags must be separate from the permission to write the entity itself. This is to prevent a user-of-user (UoU) with entity write permissions from labeling it (e.g., a UoU can create an order but must not be able to label it).
+- This can be achieved by using [conditional fields](https://dev.wix.com/docs/rnd-general/articles/p13n-guidelines-aips/guidance-aips/design-patterns/7001-partial-responses-projections).
+
+#### API Parameters
+As demonstrated in the example above, the API should receive:
+- List of entity IDs to update
+- List of tag IDs to assign to all specified entities
+- List of tag IDs to remove from all specified entities
+
+#### Query Entity
+When using private tags, ensure private tags are filtered out from the response to prevent visibility to UoU.
+
+