@wix/patterns 1.366.0 → 1.369.0

package/dist/docs/Enable Filters for Extended Fields.md

@@ -0,0 +1,243 @@
+# Enable Filters for Extended Fields
+
+**Category:** Features/Enrich/Data Extension
+
+## Guide
+
+This article explains how to enable filters on your extended fields.
+
+Once enabled, you'll see your extended fields when you click **Filter**:
+
+![Filter button](./data-extension-filter.png)
+
+Filters will be automatically displayed for your extended fields based on the following mapping:
+
+* **Boolean**: Radio button
+* **Number**: Number range
+* **Dates**: Date picker
+* **Strings** (including URL and files): Not supported
+
+### 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).
+* Followed the [steps to display extended fields](./?path=/story/features-enrich-data-extension--display-extended-fields).
+
+### Step 1 | Expose a Nile/Search endpoint
+
+1. In your `BUILD.bazel` file, add a [`search` macro definition](https://github.com/wix-private/search/blob/master/nile/README.md#macro-definition-prime_app) to your `prime_app()`. For example:
+
+    ```javascript
+    prime_app(
+        // ..
+        search = {
+            "pii": False,
+            "tenancy": "Instance",
+            "schemas": {
+                "poc": {
+                    "cluster": "es-poc",
+                },
+            },
+        }
+        // ..
+    )
+    ```
+
+1. In your proto, add a search API including search, filter, sort and aggregation capabilities. For example:
+
+    ```javascript
+    rpc SearchDummyEntities (SearchDummyEntitiesRequest) returns (SearchDummyEntitiesResponse) {
+        option (google.api.http).post = "/v1/dummy-entities/search";
+        option (wix.api.crud) = {
+            method: SEARCH
+            search_options: {
+            items_field: 'dummy_entities'
+            paging: {
+                type: CURSOR
+            },
+            wql: {
+                pattern: {
+                operator: ALL_APPLICABLE_OPERATORS
+                sort: BOTH
+                field: "created_date"
+                field: "updated_date"
+                }
+            }
+            }
+        };
+    }
+    ```
+
+> **Note:** The source of truth for this information is in the [Nile/Search README](https://github.com/wix-private/search/blob/master/nile/README.md#data-extensions--extended-fields).
+
+### Step 2 | Support filter aggregations over your entity
+
+1. Mark your extensible entity as filterable.
+
+    ```javascript
+    option (wix.api.entity) = {
+      fqdn: "wix.search.test.v1.product",
+      app_def_id: "00000000-0000-0000-0000-000000000000"
+      extensible: {
+        filterable: true
+      }
+    }
+    ```
+
+1. Apply Schema changes to production via [Dev Portal](https://wix-bo.com/dev/projects) in the **Nile Search** tab.
+
+    ![Nile search tab](./nile-search-tab.png)
+
+### Step 3 | Edit your Table component
+
+In your table component:
+
+1. Import the `transformCustomFiltersToWQL` and `transformSortToWQL` helper functions.
+
+    ```javascript
+    import { transformCustomFiltersToWQL, transformSortToWQL } from '@wix/patterns';
+    ```
+
+1. Use the helper functions in your `fetchData` function. For example:
+
+    ```diff
+    const state = useTableCollection({
+        fqdn: 'wix.cairo.dummyservice.v1.dummy_entity',
+        toExtendedFields: (item) => item.extendedFields,
+        fetchData: async ({ search = '', filters, sort }) => {
+            const querySearch: SearchDummyEntitiesRequest = {
+            search: {
+    +         sort: transformSortToWQL(sort),
+                filter: {
+    +           ...transformCustomFiltersToWQL(state, filters),
+                name: { $startsWith: search },
+                },
+            },
+            };
+            // ...
+        },
+        // ...
+    });
+    ```
+
+1. Mark the data extension component `filterable`.
+
+    ```diff
+    }
+        // ..
+    />
+    ```
+
+### See also
+
+* [Data Extension Overview](./?path=/story/features-enrich-data-extension--data-extension-overview)
+* [Allow Users to Add Extended Fields](./?path=/story/features-enrich-data-extension--allow-users-to-add-extended-fields)
+
+
+## Examples
+
+### Filter by a custom field
+
+This example demonstrates how to enable filtering capabilities for custom fields by configuring your FQDN to support filters.
+
+```tsx
+import React from 'react';
+import { CollectionPage } from '@wix/patterns/page';
+import {
+  DataExtension,
+  useTableCollection,
+  Table,
+  transformCustomFiltersToWQL,
+  transformSortToWQL,
+  CursorQuery,
+  useSelector,
+} 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 WithFiltersSupport() {
+  const httpClient = useHttpClient();
+
+  const state = useTableCollection<Contact>({
+    queryName: 'cool-table-name',
+    paginationMode: 'cursor',
+    fqdn: 'wix.patterns.dummyservice.v1.dummy_entity',
+    toExtendedFields: (item) => item.extendedFields,
+    persistQueryToUrl: true,
+
+    fetchData: async ({
+      search = '',
+      filters,
+      sort,
+      cursor,
+      limit,
+    }: CursorQuery) => {
+      const querySearch: SearchContactsRequest = {
+        search: {
+          search: { expression: search, fields: ['name'] },
+          cursorPaging: { limit, cursor },
+          sort: transformSortToWQL(sort),
+          filter: {
+            ...transformCustomFiltersToWQL(state, filters),
+            name: { $startsWith: search },
+          },
+        },
+      };
+      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 || '',
+  });
+
+  // !!! DO NOT USE THIS CODE - IT IS FOR DEMONSTRATION PURPOSES ONLY !!!
+  const items = useSelector(
+    () => state.toolbar.customColumnsState?.columnsCollection.result.items,
+  );
+  React.useEffect(() => {
+    const columns = items?.filter((item) =>
+      ['checkbox', 'datetime', 'decimal']
+        .map((field) => `extendedFields.namespaces._user_fields.${field}`)
+        .includes(item.id),
+    );
+    columns?.forEach((column) => {
+      state.toolbar.customColumnsState?.onColumnCheckboxToggle(column);
+    });
+  }, [items?.length]);
+  // **************************************************************** //
+
+  return (
+    <CollectionPage height="400px">
+      <CollectionPage.Header title={{ text: 'Contacts' }} />
+      <CollectionPage.Content>
+        <Table
+          state={state}
+          horizontalScroll
+          dataExtension={<DataExtension filterable disableUserDefinedWriting />}
+          columns={[
+            {
+              id: 'name',
+              title: 'Name',
+              width: '250px',
+              render: (item) => item.name,
+            },
+          ]}
+        />
+      </CollectionPage.Content>
+    </CollectionPage>
+  );
+}
+```
+

package/dist/docs/EntityPage.AdditionalContent.md

@@ -0,0 +1,25 @@
+# EntityPage.AdditionalContent
+
+**Category:** Base Components/Pages/Entity Page
+
+## API
+
+### Overview
+
+A slot component for the side panel of an [`EntityPage`](./?path=/story/base-components-pages-entity-page--entitypage). Place it inside `` alongside ``. Supports an optional `sticky` prop to keep the content fixed while scrolling.
+
+```tsx
+import { EntityPage } from '@wix/patterns/page';
+```
+
+### Usage
+
+This component acts as a container for [EntityPage.Card](./?path=/story/base-components-pages-entity-page--entitypage-card) child components and is displayed on the right side of the Page layout. For examples of how this component is used, please refer to the [EntityPage](./?path=/story/base-components-pages-entity-page--entitypage) examples.
+
+### Props
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `dataHook` | `string` | No | - | Applies a data-hook HTML attribute that can be used in tests |
+| `sticky` | `boolean` | No | - | Makes the additional content sticky when scrolling |
+

package/dist/docs/EntityPage.Card.md

@@ -0,0 +1,250 @@
+# EntityPage.Card
+
+**Category:** Base Components/Pages/Entity Page
+
+## Examples
+
+### Basic
+
+This example demonstrates a basic usage of the `Card` in both the main and supplementary content.
+
+```tsx
+import React from 'react';
+import {
+  EntityPage,
+  EntityPageState,
+  useEntity,
+  useEntityPage,
+} from '@wix/patterns';
+import { useForm } from '@wix/patterns/form';
+import { Box, Card, Text } from '@wix/design-system';
+
+interface MyEntity {
+  id: string;
+  name?: string;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+function Basic() {
+  const form = useForm();
+  const state: EntityPageState<MyEntity> = useEntityPage<MyEntity>({
+    parentPageId: '',
+    form,
+    onSave: () =>
+      Promise.resolve({
+        updatedEntity: {
+          ...state.entity,
+        } as MyEntity,
+      }),
+    saveErrorToast: (e) => 'Failed to save',
+    fetch: () =>
+      Promise.resolve({
+        entity: {
+          id: 'id',
+          name: 'Entity Name',
+          createdAt: new window.Date(),
+          updatedAt: new window.Date(),
+        },
+      }),
+  });
+
+  const entity = useEntity<MyEntity>(state);
+
+  return (
+    <EntityPage state={state}>
+      <EntityPage.Header title={{ text: entity?.name ?? '' }} />
+      <EntityPage.Content>
+        <EntityPage.MainContent>
+          <EntityPage.Card minHeight="24px">
+            <Card.Header title="Main Content Card" />
+            <Card.Divider />
+            <Card.Content>
+              <Box gap="SP2" direction="vertical">
+                <Text>Hi from the main content!</Text>
+              </Box>
+            </Card.Content>
+          </EntityPage.Card>
+        </EntityPage.MainContent>
+        <EntityPage.AdditionalContent>
+          <EntityPage.Card minHeight="24px">
+            <Card.Header title="Side Content Card" />
+            <Card.Divider />
+            <Card.Content>
+              <Box gap="SP2" direction="vertical">
+                <Text>Hi from the side panel!</Text>
+              </Box>
+            </Card.Content>
+          </EntityPage.Card>
+        </EntityPage.AdditionalContent>
+      </EntityPage.Content>
+    </EntityPage>
+  );
+}
+```
+
+---
+
+### Card States
+
+This example showcases various card statuses: `loading`, `error`, and `success`. Each status displays a corresponding state: Skeleton for `loading`, an Error state for `error`, or the actual children component for `success`.
+
+```tsx
+import React from 'react';
+import {
+  EntityPage,
+  EntityPageState,
+  useEntity,
+  useEntityPage,
+} from '@wix/patterns';
+import { useForm } from '@wix/patterns/form';
+import { Box, Card, Text } from '@wix/design-system';
+import { CardContainerProps } from '../../../dist/types/components/CardContainer';
+
+interface MyEntity {
+  id: string;
+  name?: string;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+function States() {
+  const form = useForm();
+  const state: EntityPageState<MyEntity> = useEntityPage<MyEntity>({
+    parentPageId: '',
+    form,
+    onSave: () =>
+      Promise.resolve({
+        updatedEntity: {
+          ...state.entity,
+        } as MyEntity,
+      }),
+    saveErrorToast: (e) => 'Failed to save',
+    fetch: () =>
+      Promise.resolve({
+        entity: {
+          id: 'id',
+          name: 'Entity Name',
+          createdAt: new window.Date(),
+          updatedAt: new window.Date(),
+        },
+      }),
+  });
+
+  const entity = useEntity<MyEntity>(state);
+
+  const [status1, setStatus1] =
+    React.useState<CardContainerProps['status']>('loading');
+
+  const [status2, setStatus2] =
+    React.useState<CardContainerProps['status']>('error');
+
+  React.useEffect(() => {
+    window.setTimeout(() => {
+      setStatus1('success');
+    }, 5000);
+  }, []);
+
+  return (
+    <EntityPage state={state}>
+      <EntityPage.Header title={{ text: entity?.name ?? '' }} />
+      <EntityPage.Content>
+        <EntityPage.MainContent>
+          <EntityPage.Card minHeight="24px" status={status1}>
+            <Card.Header title="Loading -> Success" />
+            <Card.Divider />
+            <Card.Content>
+              <Box gap="SP2" direction="vertical">
+                <Text>It took a while but I'm here now!</Text>
+              </Box>
+            </Card.Content>
+          </EntityPage.Card>
+        </EntityPage.MainContent>
+        <EntityPage.AdditionalContent>
+          <EntityPage.Card minHeight="24px" status="loading">
+            <Card.Header title="Loading..." />
+            <Card.Divider />
+            <Card.Content>
+              <Box gap="SP2" direction="vertical">
+                <Text>Just a sec...</Text>
+              </Box>
+            </Card.Content>
+          </EntityPage.Card>
+          <EntityPage.Card
+            minHeight="24px"
+            status={status2}
+            errorState={{
+              action: {
+                text: 'Retry',
+                onClick: () => {
+                  setStatus2('loading');
+                  window.setTimeout(() => {
+                    setStatus2('success');
+                  }, 2000);
+                },
+              },
+            }}
+          >
+            <Card.Header title="Error Card" />
+            <Card.Divider />
+            <Card.Content>
+              <Box gap="SP2" direction="vertical">
+                <Text>Just a sec...</Text>
+              </Box>
+            </Card.Content>
+          </EntityPage.Card>
+        </EntityPage.AdditionalContent>
+      </EntityPage.Content>
+    </EntityPage>
+  );
+}
+```
+
+## API
+
+### Overview
+
+A card container used inside [`EntityPage.MainContent`](./?path=/story/base-components-pages-entity-page--entitypage-maincontent) or [`EntityPage.AdditionalContent`](./?path=/story/base-components-pages-entity-page--entitypage-additionalcontent). It wraps form fields and content sections with a card layout, and supports loading/error/success states for async content.
+
+```tsx
+import { EntityPage } from '@wix/patterns/page';
+```
+
+### Extends
+
+[Card](https://www.docs.wixdesignsystem.com/?path=/story/components-layout-card--card)
+
+### Composition
+
+```tsx
+
+  
+  
+    
+        {/* ← this component */}
+        
+          {/* form fields */}
+        
+      
+    
+  
+
+```
+
+### Props
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `status` | `"error" \| "loading" \| "idle" \| "success"` | No | - | Additional loading flag, if you need to show loader after the main entity is fetched. Also, if an error occurs on a side request (other than passed to `fetch`), you can use `error` to show the card error state. Alongside with `error` you also need to pass `errorState.onRetry` callback, which should change the `status` accordingly. |
+| `minHeight` | `string` | No | - | Height of content while loading (not including paddings) |
+| `errorState` | `ErrorCardProps` | No | - | Card Error State configuration |
+| `id` | `string` | No | - | Identifier of the card. If you want to open a page and auto-scroll and focus ont his card, pass in the the query params `anchor={yourCardId}`. |
+| `children` | `ReactNode` | No | - | Contains elements inside the card such as `<Card.Header/>`, `<Card.Subeader/>`, `<Card.Content/>` or `<Card.Divider/>`. |
+| `controls` | `ReactNode` | No | - | Contains elements that control the component, usually a `<CloseButton/>`. |
+| `stretchVertically` | `boolean` | No | - | Makes a card stretch vertically to max height in a layout or container. |
+| `hideOverflow` | `boolean` | No | - | Defines whether to hide portions of card content that overflows its dimensions. |
+| `showShadow` | `boolean` | No | - | Defines whether to apply a drop shadow effect. |
+| `dataHook` | `string` | No | - | Applies a data-hook HTML attribute that can be used in tests. |
+| `className` | `string` | No | - | Specifies a CSS class name to be appended to the component's root element. |
+| `highlight` | `"focus"` | No | - | Applies a highlighting effect on the borders of the component. |
+

package/dist/docs/EntityPage.Content.md

@@ -0,0 +1,24 @@
+# EntityPage.Content
+
+**Category:** Base Components/Pages/Entity Page
+
+## API
+
+### Overview
+
+A layout slot for the body of an [`EntityPage`](./?path=/story/base-components-pages-entity-page--entitypage). Wraps `` and optionally `` to create the two-column layout.
+
+```tsx
+import { EntityPage } from '@wix/patterns/page';
+```
+
+### Usage
+
+This component acts as a container for [EntityPage.MainContent](./?path=/story/base-components-pages-entity-page--entitypage-maincontent) and [EntityPage.AdditionalContent](./?path=/story/base-components-pages-entity-page--entitypage-additionalcontent) components. For examples of how this component is used, please refer to the [EntityPage](./?path=/story/base-components-pages-entity-page--entitypage&tab=Examples) examples.
+
+### Props
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `children` | `ReactNode` | Yes | - | <EntityPage.MainContent> and, if needed, <EntityPage.AdditionalContent> elements |
+