@wix/patterns 1.366.0 → 1.370.0

package/dist/docs/Data Extension Overview.md

@@ -0,0 +1,85 @@
+# Data Extension Overview
+
+**Category:** Features/Enrich/Data Extension
+
+## Overview
+
+### Introduction
+
+Patterns Data Extension feature builds on the [open platform Data Extensions capability](https://dev.wix.com/docs/rnd-general/articles/open-platform/data-extensions/data-extensions-101).
+
+Use this feature to give users more flexibility in managing and displaying data, including:
+
+* **Customization for TPAs**: Enable third-party applications to enrich your tables with their extended fields.
+* **Enhanced UX for site builders**: Enable site builders to customize their tables by adding, reordering, and hiding extended fields.
+* **Direct data entry**: Simplify data input by allowing users to create extended fields directly from the dashboard.
+
+### Features
+
+Enhance your Patterns components so that your users can:
+
+* View extended fields on collection and entity pages.
+* Show, reorder, and hide extended fields with the custom columns feature.
+* Filter and sort extended field data with minimal effort.
+* Enter extended field data directly in entity forms.
+
+![Extended fields demo](./extended-fields.gif)
+
+### Get started
+
+* [Display Your Fields](./?path=/story/features-enrich-data-extension--display-extended-fields)
+* [Enable Filters](./?path=/story/features-enrich-data-extension--enable-filters-for-extended-fields)
+* [Allow Your Users to Add Extended Fields](./?path=/story/features-enrich-data-extension--allow-users-to-add-extended-fields)
+
+### Examples
+
+For detailed code samples, check out the **Examples** tab.
+
+
+## FAQ
+
+### I integrated with CustomFieldsWidget and I need a way to get the data from the form. How can I do that?
+
+If you need a way to retrieve data from the form, you can use the `validate` and `isDirty` methods that are part of the [FormPageState](./?path=/story/common-state--formpagestate). These methods allow you to validate the form data and determine if any changes have been made respectively. To access them, you can retrieve the `state` directly from [useWidgetsFormContext](./?path=/story/common-hooks--usewidgetsformcontext) hook. Take a look at the [CustomFieldsWidget](./?path=/story/features-enrich-data-extension-components--customfieldswidget) for a complete example.
+
+### Is there a restriction on the amount of data that can be stored in the custom fields? If so, what is it?
+
+Yes, there is a limit to the data you can store in the custom fields. You can store up to 50 fields or up to 10kb of fields schema data. To give you an idea of the data size, each short string field takes 120 bytes, while a long text field takes 200 bytes. For instance, if you have 50 fields of short text, you will reach a total of 6KB. On the other hand, if you have 50 fields of long text, you will reach the 10KB limit. It's important to note that in some cases like dropdowns, the field size is determined by the field schema length. This means that theoretically you could reach the limit before reaching the 50 fields limit if the data is large enough. In such a scenario, you will receive an error message indicating the limit has been exceeded.
+
+### Can I open the custom field modal from my code? If so, how?
+
+Absolutely! You have the ability to open the modal directly from your code. To do so, simply call the `openCustomFieldModal` method, which is available through the [ToolbarCollectionState](./?path=/story/common-state--toolbarcollectionstate). To access it, call `state.toolbar.openCustomFieldModal()` where state represents the result of invoking either [useTableCollection](./?path=/story/base-components-collections-table-usetablecollection--usetablecollection) or [useGridCollection](./?path=/story/base-components-collections-grid-usegridcollection--usegridcollection).
+
+### If a TPA creates custom fields, will those fields be visible?
+
+Currently, only user fields created by the user are supported, and they are stored in the `_user_fields` namespace. If a TPA creates custom fields, they will be stored in a separate namespace and will not be visible in the Data Extension integration.
+
+### I have a question that is not answered in this FAQ. What should I do?
+
+If you have a question that is not addressed in this FAQ, don't worry! You can always get in touch with us by joining the [#cairo](https://wix.slack.com/archives/C02K83200PL) Slack channel. We'll be more than happy to assist you there and provide the necessary support.
+
+## BI
+
+### Custom Columns Events
+
+ Event   |   Description   |
+--------- | --------------- |
+[144:155](https://bo.wix.com/data-tools/bi-catalog-app/event/144:155) | Send when a user click on a "Add Custom Field"
+[144:156](https://bo.wix.com/data-tools/bi-catalog-app/event/144:156) | Send when a user click on cancel / add field in the "Add Custom Field" modal
+[144:157](https://bo.wix.com/data-tools/bi-catalog-app/event/144:157) | Send when a user click on "Advanced Settings" in the "Add Custom Field" modal
+[144:160](https://bo.wix.com/data-tools/bi-catalog-app/event/144:160) | Sent when a user changes his choices before he clicks on the apply button 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)
+
+

package/dist/docs/DataResultRaw.md

@@ -0,0 +1,25 @@
+# DataResultRaw
+
+**Category:** Common/Types
+
+## API
+
+### Overview
+
+The return type of the `fetchData` function passed to collection hooks. Contains the `items` array, optional `total` count (after filters), `available` count (before filters), `cursor` for cursor-based pagination, and `hasNext` flag.
+
+### Description
+
+You must return a `DataResultRaw` object from `fetchData()` in collection hooks, such as [`useTableCollection()`](./?path=/story/base-components-collections-table-usetablecollection--usetablecollection) and [`useGridCollection()`](./?path=/story/base-components-collections-grid-usegridcollection--usegridcollection).
+
+
+### Props
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `items` | `T[]` | Yes | - | Array of items returned from the server. |
+| `total` | `number \| null` | No | ``items.length`` | Total items available in the server, *after* applying filters. If not provided, offset pagination will not work correctly. If you are using a cursor and did not include `total` in your query request, you can use the `fetchTotal` function to extract it asynchronously. |
+| `available` | `number` | No | - | Total items available in the server, *before* applying filters. |
+| `cursor` | `string \| null` | No | - | In case of cursor pagination, this will be the value that will be sent in the query on the next page request. |
+| `hasNext` | `boolean \| null` | No | - | Indicates whether there are more items available after the current page. |
+

package/dist/docs/DateRangeFilter.md

@@ -0,0 +1,202 @@
+# DateRangeFilter
+
+**Category:** Features/Filter/Components
+
+## Design
+
+### Overview
+
+Use `DateRangeFilter` for rendering a date range.
+
+> Note: Use this filter only in a "filters panel", and not in the toolbar itself.
+> This filter will always be displayed inside the side panel.
+
+### Timezone shifting
+
+The dates that passed to `fetchData(query.filters)` are in the timezone of the user's browser.
+
+If you want to shift the dates to a different timezone (usually UTC), you can use a utility function, for example:
+
+> Note: use date-fns-tz@^2.0.0
+> Always test your code in a few timezones
+
+```js
+import { zonedTimeToUtc } from 'date-fns-tz';
+
+const fetchData = async (query) => {
+  const {
+    filters: { updatedAt },
+  } = query;
+  const { items, total } = await fetch(
+    queryItems({
+      updatedAt: {
+        start: updatedAt.from && zonedTimeToUtc(updatedAt.from, 'UTC'),
+        end: updatedAt.to && zonedTimeToUtc(updatedAt.to, 'UTC'),
+      },
+    }),
+  );
+
+  return {
+    items,
+    total,
+  };
+};
+```
+
+
+```tsx
+import { DateRangeFilter } from '@wix/patterns';
+```
+
+---
+
+### Examples
+
+### Basic - By default `mode` property equals `COMBINE`
+
+```tsx
+import React from 'react';
+import { dateRangeFilter, DateRangeFilter } from '@wix/patterns';
+
+function BasicDateRangeFilter() {
+  const [filter] = React.useState(() => dateRangeFilter());
+
+  return <DateRangeFilter filter={filter} />;
+}
+```
+
+---
+
+### Only with custom dates
+
+```tsx
+import React from 'react';
+import { dateRangeFilter, DateRangeFilter } from '@wix/patterns';
+
+function OnlyCustomDateRangeFilter() {
+  const [filter] = React.useState(() => dateRangeFilter());
+
+  return <DateRangeFilter filter={filter} mode="ONLY_CUSTOM" />;
+}
+```
+
+---
+
+### Only with predefined dates
+
+```tsx
+import React from 'react';
+import { dateRangeFilter, DateRangeFilter } from '@wix/patterns';
+
+function OnlyPredefinedDateRangeFilter() {
+  const [filter] = React.useState(() => dateRangeFilter());
+
+  return <DateRangeFilter filter={filter} mode="ONLY_PREDEFINED" />;
+}
+```
+
+---
+
+### With override presets in combine mode
+
+```tsx
+import React from 'react';
+import { dateRangeFilter, DateRangeFilter } from '@wix/patterns';
+
+function OverridePresetsCombineDateRangeFilter() {
+  const [filter] = React.useState(() => dateRangeFilter());
+
+  return (
+    <DateRangeFilter
+      filter={filter}
+      mode="COMBINE"
+      dateRangeOptions={['FOURTEEN_DAYS', 'MONTH']}
+    />
+  );
+}
+```
+
+---
+
+### With override presets in predefined mode
+
+```tsx
+import React from 'react';
+import { dateRangeFilter, DateRangeFilter } from '@wix/patterns';
+
+function OverridePresetsPredefinedDateRangeFilter() {
+  const [filter] = React.useState(() => dateRangeFilter());
+
+  return (
+    <DateRangeFilter
+      filter={filter}
+      mode="ONLY_PREDEFINED"
+      dateRangeOptions={['SEVEN_DAYS', 'MONTH']}
+    />
+  );
+}
+```
+
+---
+
+### Future timeframes
+
+```tsx
+import React from 'react';
+import { dateRangeFilter, DateRangeFilter } from '@wix/patterns';
+
+function OverridePresetsFutureDateRangeFilter() {
+  const [filter] = React.useState(() => dateRangeFilter());
+
+  return (
+    <DateRangeFilter
+      filter={filter}
+      mode="COMBINE"
+      dateRangeOptions={[
+        'TODAY',
+        'TOMORROW',
+        'NEXT_THREE_DAYS',
+        'NEXT_SEVEN_DAYS',
+        'NEXT_THIRTY_DAYS',
+      ]}
+    />
+  );
+}
+```
+
+---
+
+### With time resolution
+
+```tsx
+import React from 'react';
+import { dateRangeFilter, DateRangeFilter } from '@wix/patterns';
+
+function WithTimeResolution() {
+  const [filter] = React.useState(() => dateRangeFilter());
+
+  return <DateRangeFilter filterByTime={true} filter={filter} />;
+}
+```
+
+## API
+
+### Props
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `mode` | `"ONLY_PREDEFINED" \| "ONLY_CUSTOM" \| "COMBINE"` | No | - | There are 3 possible modes: - `ONLY_PREDEFINED`: show only predefined dates options - `ONLY_CUSTOM`: show only custom date pickers - `COMBINE`: default, combines both predefined and custom |
+| `dateRangeOptions` | `DateRangeOptions` | No | ``['SEVEN_DAYS', 'FOURTEEN_DAYS', 'MONTH']`` | An optional array of 3 possible options: `'SEVEN_DAYS', 'FOURTEEN_DAYS', 'MONTH'`. |
+| `filterByTime` | `boolean` | No | - | If to include time resolution |
+| `filter` | `Filter<RangeItem<Date>>` | Yes | - | A filter state object such as [ArrayFilter](./?path=/story/features-filter-factories--arrayfilter) |
+| `fieldType` | `"SHORT_TEXT" \| "LONG_TEXT" \| "NUMBER" \| "BOOLEAN" \| "DATE" \| "DATE_TIME" \| "DATETIME" \| "TIME" \| "URL" \| "EMAIL" \| "IMAGE" \| "MEDIA_GALLERY" \| "AUDIO" \| "DOCUMENT" \| "MULTI_DOCUMENT" \| "RICH_TEXT" \| "RICH_CONTENT" \| "REFERENCE" \| "MULTI_REFERENCE" \| "OBJECT" \| "ARRAY" \| "ADDRESS" \| "COLOR" \| "INTEGER" \| "DECIMAL" \| "CHECKBOX" \| "DROPDOWN" \| "FILES" \| "MULTI_SELECT"` | No | - | The field type string used to resolve a prefix icon for the filter. Cairo maps this to the appropriate icon internally. |
+| `layout` | `"button"` | No | - | Padding settings. If this prop it omitted, padding will exist on the sides of the filter.<br> <br> Supported values: <br> - `"button"`: Removes padding from the sides of the filter. |
+| `toolbarItemProps` | `{ label?: ReactNode; }` | No | - | Customizes the filter in the toolbar.<br> <br> Supported properties: <br> - `label`: [string] Prefix for the filter element. |
+| `toolbarTagProps` | `{ label?: string; }` | No | - | Customizes the filter tag in the toolbar.<br> <br> Supported properties: <br> - `label`: [string] Overrides the default filter name when filtered tag is shown. |
+| `initiallyOpen` | `boolean` | No | - | Indicates whether the filter should be visible by default in the filters panel |
+| `accordionItemProps` | `(AccordionItemType & { label?: string; })` | No | - | Customizes the filter [accordion](https://www.docs.wixdesignsystem.com/?path=/story/components-lists--accordion).<br> <br> Supported properties: <br> - `label`: [string] Accordion item title. You can also use `AccordionProps['items'][number].title` for more flexibility. <br> - Extends [AccordionProps['items'[number]](https://www.docs.wixdesignsystem.com/?path=/story/components-lists--accordion). |
+| `popoverProps` | `PopoverCommonProps` | No | - | @deprecated |
+| `onAppliedFilterTagRemove` | `((item: RangeItem<Date>) => unknown)` | No | - | Callback that's run when a filter is removed by a visitor from the sub-toolbar. @param item |
+| `renderToolbarTag` | `((item: RangeItem<Date>) => Partial<Omit<TagProps, "size" \| "onRemove">>)` | No | - | Customizes how the tag list in the sub-toolbar is rendered. <br><br> Extends [`TagListProps['tags'][number]`](https://www.docs.wixdesignsystem.com/?path=/story/components-lists-table--taglist). |
+| `sectionTitle` | `string` | No | - | Title for the section in the accordion. |
+

package/dist/docs/Display Extended Fields.md

@@ -0,0 +1,244 @@
+# Display Extended Fields
+
+**Category:** Features/Enrich/Data Extension
+
+## Guide
+
+This guide explains how to display extended fields in your table.
+
+By the end, you'll see your extended fields when you click **Customize**:
+
+![Customize button](./data-extension-customize-columns.png)
+
+### Before you begin
+
+Make sure that you have:
+
+* A Patterns [`Table`](./?path=%2Fstory%2Fbase-components-collections-table-table--table) component.
+* A server configured to [support data extensions](https://dev.wix.com/docs/rnd-general/articles/open-platform/data-extensions/data-extensions-101#backend).
+
+### Step 1 | Enable the Data Extension feature
+
+The Data Extension feature enables you to add various components throughout your Patterns project to add, edit, and manage custom fields.
+
+To enable the Data Extension feature:
+
+1. Import `DataExtension`.
+
+    ```javascript
+    import { DataExtension } from '@wix/patterns';
+    ```
+
+1. Specify the `FQDN` of your extendable entity in the `useTableCollection` hook.
+
+    ```diff
+    const state = useTableCollection({
+    +   fqdn: '',
+        // ...
+    });
+    ```
+
+1. Pass a `DataExtension` component to the `dataExtension` prop on the table.
+
+    ```diff
+    
+    ```
+
+This step simply enabled the Data Extension features in your table. After the next step, you'll be able to add, show, reorder, and hide extended fields.
+
+### Step 2 | Add, show, reorder, and hide extended fields
+
+To add, show, reorder, and hide extended fields:
+
+1. Add the [Custom Columns feature](./?path=/story/features-display-custom-columns--customcolumns).
+
+    ```diff
+    }
+    +   customColumns={}
+    />
+    ```
+
+1. Click on the **Customize** icon to control the display behavior of the columns.
+
+Now, you have some functionality of extended fields in your table.
+
+### Step 3 (Optional) | View extended fields from the entity page
+
+To add an extra view of extended fields in the entity page:
+
+1. Add `CustomFieldsViewWidget` to your entity page with the `extendedFields` and `fqdn` props. Our guidelines is that `CustomFieldsViewWidget` should take 1/3 of the page width.
+
+    ```diff
+      import { MyEntityCard } from '../components/MyEntityCard';
+      import { MyEntity } from '@wix/ambassador-v1-entity/types';
+    + import { CustomFieldsViewWidget } from '@wix/patterns';
+    
+      function MyPageContent({ entity }: { entity: MyEntity }) {
+        return (
+            
+              
+                
+                  
+                
+    +           
+    +             " />
+    +           
+              
+            
+        );
+      }
+    ```
+
+1. Check out your entity page to see all of your extended fields.
+
+    ![Custom fields view widget](./custom-fields-view-widget.png)
+
+### See also
+
+* [Data Extension Overview](./?path=/story/features-enrich-data-extension--data-extension-overview)
+* [Enable Filters for Extended Fields](./?path=/story/features-enrich-data-extension--enable-filters-for-extended-fields)
+* [Allow Users to Add Extended Fields](./?path=/story/features-enrich-data-extension--allow-users-to-add-extended-fields)
+
+
+## Examples
+
+### Display Extended Fields
+
+This example demonstrates how to display extended fields in your table.
+
+```tsx
+/* eslint-disable import/no-extraneous-dependencies */
+
+import React from 'react';
+
+import { CollectionPage } from '@wix/patterns/page';
+import { Table, useTableCollection, DataExtension } from '@wix/patterns';
+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 Basic() {
+  const httpClient = useHttpClient();
+
+  const state = useTableCollection<Contact>({
+    queryName: 'contacts-CustomFields',
+    paginationMode: 'offset',
+    fqdn: 'wix.patterns.dummyservice.v1.dummy_entity',
+    fetchData: (query) => {
+      const { limit, offset, search, filters } = query;
+      return httpClient
+        .request(
+          queryContacts({
+            query: { paging: { limit, offset }, filter: filters },
+            search,
+          }),
+        )
+        .then(({ data: { contacts, pagingMetadata } }) => ({
+          items: contacts || [],
+          total: pagingMetadata?.total,
+        }));
+    },
+    itemKey: (item: Contact) => item.id!,
+    itemName: (item: Contact) => item.name!,
+    fetchErrorMessage: () => 'Error fetching contacts',
+    filters: {},
+  });
+
+  return (
+    <CollectionPage height="400px">
+      <CollectionPage.Header title={{ text: 'Contacts' }} />
+      <CollectionPage.Content>
+        <Table
+          state={state}
+          dataExtension={<DataExtension />}
+          horizontalScroll
+          columns={[
+            {
+              id: 'name',
+              title: 'Name',
+              width: '250px',
+              render: (contact: any) => contact.name,
+            },
+          ]}
+        />
+      </CollectionPage.Content>
+    </CollectionPage>
+  );
+}
+```
+
+---
+
+### Entity with Personally Identifiable Information (PII)
+
+Some entities contain personal data and are inherently considered PII. For example, 'Contacts'. Marking your entity as containing PII will add a toggle option in the new custom field modal, allowing users to designate fields as PII.
+
+```tsx
+import React from 'react';
+import { CollectionPage } from '@wix/patterns/page';
+import {
+  DataExtension,
+  useTableCollection,
+  Table,
+  CursorQuery,
+} from '@wix/patterns';
+import {
+  Contact,
+  SearchContactsRequest,
+} from '@wix/ambassador-contacts-v5-contact/types';
+import { searchContacts } from '@wix/ambassador-contacts-v5-contact/http';
+import { useHttpClient } from '@wix/yoshi-flow-bm';
+
+function ContainPii() {
+  const httpClient = useHttpClient();
+
+  const state = useTableCollection<Contact>({
+    queryName: 'contacts-ContainPii',
+    paginationMode: 'cursor',
+    fqdn: 'wix.patterns.dummyservice.v1.dummy_entity',
+    toExtendedFields: (item) => item.extendedFields,
+    persistQueryToUrl: true,
+
+    fetchData: async ({ search = '', cursor, limit }: CursorQuery) => {
+      const querySearch: SearchContactsRequest = {
+        search: {
+          search: { expression: search, fields: ['name'] },
+          cursorPaging: { limit, cursor },
+        },
+      };
+      return await httpClient
+        .request(searchContacts(querySearch))
+        .then(({ data: { contacts, pagingMetadata } }) => ({
+          items: contacts || [],
+          total: pagingMetadata?.total,
+          cursor: pagingMetadata?.cursors?.next,
+        }));
+    },
+    fetchErrorMessage: ({ err }) => `Error: ${err}`,
+    itemKey: (item) => item.id!,
+    itemName: (item) => item.name?.first || '',
+  });
+
+  return (
+    <CollectionPage height="400px">
+      <CollectionPage.Header title={{ text: 'Contacts' }} />
+      <CollectionPage.Content>
+        <Table
+          state={state}
+          horizontalScroll
+          dataExtension={<DataExtension containsPii />}
+          columns={[
+            {
+              id: 'name',
+              title: 'Name',
+              width: '250px',
+              render: (item) => item.name,
+            },
+          ]}
+        />
+      </CollectionPage.Content>
+    </CollectionPage>
+  );
+}
+```
+