@wix/patterns 1.364.0 → 1.369.0

package/dist/docs/WidgetsFormProvider.md

@@ -0,0 +1,61 @@
+# WidgetsFormProvider
+
+**Category:** Base Components/Providers
+
+## API
+
+### Overview
+
+`WidgetsFormProvider` wraps form content in Entity/Settings pages to provide widget-level form context. It enables custom form widgets (like `CustomFieldsWidget`) to register with the page form and participate in validation and submission. Place it inside `` or `` content.
+
+```tsx
+import { WidgetsFormProvider } from '@wix/patterns/page';
+```
+
+The `WidgetsFormProvider` is designed to being used as an alternative in cases where [EntityPage](./?path=/story/base-components-pages-entity-page--entitypage) doesn’t cover your needs (for example, you have a side panel and not a full page experience for editing your entity). It enables you to include form-based widgets such as [TagsWidget](./?path=/story/features-enrich-tags--tagswidget) and [CustomFieldsWidget](./?path=/story/features-enrich-data-extension-components--customfieldswidget), and access the page’s state and to validate the widgets data through the [useWidgetsFormContext](./?path=/story/common-hooks--usewidgetsformcontext) hook.
+
+In any case that you have a full page experience, we suggest to use [EntityPage](./?path=/story/base-components-pages-entity-page--entitypage) and not to use `WidgetsFormProvider`, so you can get more out of the box capabilities.
+
+
+### Usage
+
+Wrap your page with `WidgetsFormProvider`
+
+```diff
++ import { WidgetsFormProvider } from '@wix/patterns/page';
+
+export const MyPageProvider = () => {
+
+    return (
++       
+            
++       
+    )
+}
+```
+
+Inside the page, you will be able to access the `state` object returned from the [useWidgetsFormContext](./?path=/story/common-hooks--useformpagecontext) hook.
+
+```diff
++ import { useWidgetsFormContext } from '@wix/patterns';
+
+export const MyEntityPage = () => {
+
++   const state = useFormPageContext();
+
+    return (
+        
+             {
++                           const { isValid, data } = await state.validate();
++                           if (isValid) await handleSubmit();
+                        }}
+                    >
+                        Save
+                    
+                }
+            />
+    )
+}
+```
+
+

package/dist/docs/WixPatternsBMProvider.md

@@ -0,0 +1,31 @@
+# WixPatternsBMProvider
+
+**Category:** Base Components/Providers
+
+## API
+
+### Overview
+
+`WixPatternsBMProvider` is the top-level provider for Wix Patterns applications running inside Wix Business Manager. It wraps your app with the necessary context (BI, fedops, translations, HTTP client, etc.). Use this as the outermost provider in your BM module entry point.
+
+```tsx
+import { WixPatternsBMProvider } from '@wix/patterns/bm';
+```
+
+---
+
+### Example
+
+```tsx
+import React from 'react';
+import { WixPatternsBMProvider } from '@wix/patterns/bm';
+
+export default () => {
+  return (
+    <WixPatternsBMProvider>
+      <div>App Content Goes Here</div>
+    </WixPatternsBMProvider>
+  );
+};
+```
+

package/dist/docs/WixPatternsBaseProvider.md

@@ -0,0 +1,87 @@
+# WixPatternsBaseProvider
+
+**Category:** Base Components/Providers
+
+## API
+
+### Overview
+
+`WixPatternsBaseProvider` is the minimal provider for Wix Patterns. It supplies the core container context without platform-specific integrations. Use this when building standalone applications or testing outside of Business Manager or Essentials.
+
+```tsx
+import { WixPatternsBaseProvider } from '@wix/patterns';
+```
+
+### Example
+
+```tsx
+import React from 'react';
+import { WixPatternsBaseProvider } from '@wix/patterns/essentials';
+import { WixPatternsEssentials } from '@wix/patterns';
+import { initI18n } from '@wix/fe-essentials/i18n';
+import { useTranslation } from '@wix/fe-essentials/react';
+import { createHub } from '@wix/fe-essentials/error-monitor';
+import { HttpClient } from '@wix/fe-essentials/http-client';
+import {
+  DataCapsule,
+  WixStorageStrategy,
+} from '@wix/fe-essentials/data-capsule';
+import * as Sentry from '@wix/fe-essentials/sentry';
+
+function App() {
+  const [value] = React.useState((): WixPatternsEssentials => {
+    const httpClient = new HttpClient();
+
+    return {
+      environment: {
+        language: 'en',
+        artifactId: 'MY_ARTIFACT_ID',
+        componentId: 'MY_COMPONENT_ID',
+      },
+      environmentBI: {
+        artifactId: 'BI_MY_ARTIFACT_ID',
+      },
+      createEssentials: (params) => {
+        return {
+          i18n: initI18n({
+            locale: 'en',
+            ...params.i18n,
+          }),
+          errorMonitor: createHub({
+            Sentry,
+            ...params.errorMonitor,
+            dsn: params.errorMonitor?.dsn as string,
+            appName: params.errorMonitor?.appName as string,
+          }),
+          dataCapsule: new DataCapsule({
+            strategy: new WixStorageStrategy({
+              httpClient,
+            }),
+            ...params.dataCapsule,
+          }),
+        };
+      },
+      errorMonitor: createHub({
+        dsn: 'MY_SENTRY_DSN',
+        appName: 'MY_APP_NAME',
+        Sentry,
+      }),
+      useTranslation,
+      httpClient,
+    };
+  });
+
+  return (
+    <WixPatternsBaseProvider value={value}>
+      <div>App Content Goes Here</div>
+    </WixPatternsBaseProvider>
+  );
+}
+```
+
+### Props
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `value` | `WixPatternsMinimalEssentials` | Yes | - | Minimal essentials that are required for wix-patterns to work (i.e i18n,bi,experiments) |
+

package/dist/docs/WixPatternsEssentialsProvider.md

@@ -0,0 +1,43 @@
+# WixPatternsEssentialsProvider
+
+**Category:** Base Components/Providers
+
+## API
+
+### Overview
+
+`WixPatternsEssentialsProvider` is the provider for Wix Patterns applications running with Wix Essentials (the modern SDK). It wraps your app with container context derived from the Essentials SDK modules.
+
+```tsx
+import { WixPatternsEssentialsProvider } from '@wix/patterns/essentials';
+```
+
+---
+
+A React context provider for `Wix Patterns`'s essentials dependencies.
+
+Every app must be wrapped with this provider in order to be able to render `Wix Patterns` components.
+
+### Views
+
+When using  the data for the [views feature](./?path=/story/features-display-views--views) will be saved via the user-preferences API.
+If your app runs under a specific domain, you'll need too add a mapping to the `/user-preferences` endpoint of [app-settings-service artifact fryingpan dashboard](https://fryingpan.wixpress.com/services/com.wixpress.fed.app-settings-service)
+
+
+---
+
+### Example
+
+```tsx
+import React from 'react';
+import { WixPatternsEssentialsProvider } from '@wix/patterns/essentials';
+
+export default () => {
+  return (
+    <WixPatternsEssentialsProvider>
+      <div>App Content Goes Here</div>
+    </WixPatternsEssentialsProvider>
+  );
+};
+```
+

package/dist/docs/WixPatternsGizaProvider.md

@@ -0,0 +1,37 @@
+# WixPatternsGizaProvider
+
+**Category:** Base Components/Providers
+
+## API
+
+### Overview
+
+`WixPatternsGizaProvider` is the provider for Wix Patterns applications running in the Giza (Editor) environment. It supplies the container context for editor-based applications.
+
+```tsx
+import { WixPatternsGizaProvider } from '@wix/patterns/giza';
+```
+
+---
+
+### Yoshi Flow BM
+
+Requires `@wix/yoshi-flow-bm@^6.49.1` and above
+
+---
+
+### Example
+
+```tsx
+import React from 'react';
+import { WixPatternsGizaProvider } from '@wix/patterns/giza';
+
+export default () => {
+  return (
+    <WixPatternsGizaProvider>
+      <div>App Content Goes Here</div>
+    </WixPatternsGizaProvider>
+  );
+};
+```
+

package/dist/docs/WixPatternsProvider.md

@@ -0,0 +1,68 @@
+# WixPatternsProvider
+
+**Category:** Base Components/Providers
+
+## API
+
+### Overview
+
+`WixPatternsProvider` is the recommended top-level provider for most Wix Patterns applications. It auto-detects the environment (BM, Essentials, Giza) and supplies the appropriate context. Wrap your entire app with this provider.
+
+> **Note: If you're using [Yoshi BM Flow](https://bo.wix.com/pages/yoshi/docs/business-manager-flow/overview) over Business-Manager, you can use [WixPatternsBMProvider](./?path=/story/base-components-providers--wixpatternsbmprovider) if you prefer.**
+
+> **Note: If you're using [Yoshi BM Flow](https://bo.wix.com/pages/yoshi/docs/business-manager-flow/overview) over Giza, you may choose to use [WixPatternsGizaProvider](./?path=/story/base-components-providers--wixpatternsgizaprovider) as an option.**
+
+> **Note: If you're using [Yoshi Fullstack](https://bo.wix.com/pages/yoshi/docs/fullstack-flow/overview), use [WixPatternsEssentialsProvider](./?path=/story/base-components-providers--wixpatternsessentialsprovider) instead.**
+
+
+
+
+A React context provider for `Wix Patterns`'s essentials dependencies.
+
+
+Use `WixPatternsBaseProvider` in case your app does not run under a Giza/WixEssentials configured environment, so you fully control the injection of services (such as i18n,sentry).
+
+
+```tsx
+import { WixPatternsProvider } from '@wix/patterns/provider';
+```
+
+### Requirements
+
+Verify `@wix/dashboard` is installed in your project.
+
+```bash
+yarn add @wix/dashboard
+```
+
+Or, if you're using npm:
+
+```bash
+npm install @wix/dashboard
+```
+
+
+### Usage
+
+On the page where you want to use Wix Patterns, you need to add a `WixDesignSystemProvider` followed by a `WixPatternsProvider`.
+
+```jsx
+import React from 'react';
+import { withDashboard } from '@wix/patterns';
+import { WixDesignSystemProvider } from '@wix/design-system';
+import { WixPatternsProvider } from '@wix/patterns/provider';
+
+export default withDashboard(() => {
+  return (
+    
+      
+        {
+          // Wix Patterns components
+        }
+      
+    
+  );
+});
+```
+
+

package/dist/docs/Working with Cache.md

@@ -0,0 +1,114 @@
+# Working with Cache
+
+**Category:** Guides
+
+##  
+
+Wix Patterns uses cache to optimize the request time, more specifically it uses the "in-memory" cache strategy which means that the cache persists only during the browser session. Once the browser tab is closed all cache is cleared.
+
+For Business Manager environment, Wix Patterns provides an additional optimization — a single cache instance for all modules. While the user stays in Business Manager and navigate using the Business Manager API (without page reload), the same cache instance will be used for all Wix Patterns applications.
+
+> This behavior in Business Manager is **disabled** by default, to enable it see below.
+
+The data in the cache is stored in the key-value storage where key is generated using two components: `queryName` and `computedQuery` (request parameters). `queryName` is defined by the user when creating the collection (e.g. `useCollection` hook) and the `computedQuery` is auto generated based on the current query (sort, filters, search, etc). So if two applications in Business Manager use the same `queryName`, the global cache is enabled and the user navigates from one to another, the cache data will used.
+
+> It's recommended to use the [fqdn](https://bo.wix.com/wix-docs/rnd/p13n-guidelines---aips/guidance-aips/wix-api-basics/[1009]-fqdn) of the service used in fetchData as queryName.
+
+Most of the time this behavior is undesirable in Business Manager because some applications want to always have up-to-date data. That's why this optimization is disabled by default.
+
+## Enable global cache
+
+To enable the global cache in Business Manager, one should explicitly set it in the `` component.
+
+```js
+import { WixPatternsBMProvider } from '@wix/patterns/bm';
+
+export const App = () => {
+  return (
+    
+      {...}
+    
+  )
+}
+```
+
+## Cache invalidation
+
+In cases when the global cache is enabled it might be inconsistent with recent changes the user performed in other pages which use the same `queryName`. For such use cases Wix Patterns provides an API to invalidate all cache occurences of the provided `queryName`.
+
+Consider having a BM page with a Wix Patterns table:
+
+###### _.application.json_
+
+```js
+{
+  "moduleId": "contacts-list"
+}
+```
+
+###### _src/pages/contacts-list-page/index.tsx_
+
+```jsx
+import React from 'react';
+import { queryContacts } from '@wix/ambassador-contacts-v4-contact/http';
+import { useCollection } from '@wix/patterns';
+import { useHttpClient } from '@wix/yoshi-flow-bm';
+
+export default () => {
+  const httpClient = useHttpClient();
+  const collection = useCollection({
+    queryName: 'wix.contacts.v4.contact',
+    fetchData: (query) => {
+      const { limit, offset, search, filters } = query;
+      return httpClient.request(queryContacts(/* ... */)).then((res) => {
+        /* ... */
+      });
+    },
+  });
+
+  return <>{/* ... */};
+};
+```
+
+And another BM page that changes data related to this collection:
+
+###### _.application.json_
+
+```js
+{
+  "moduleId": "create-new-contact"
+}
+```
+
+###### _src/pages/create-new-contact-page/index.tsx_
+
+Here, right after the action, we should notify Wix Patterns cache about the change:
+
+> Install `@wix/patterns-integration-utils` package first.
+
+```diff
+import React from 'react';
+import { createContact } from '@wix/ambassador-contacts-v4-contact/http';
+import { useHttpClient } from '@wix/yoshi-flow-bm';
++ import { invalidateCacheForCollection } from '@wix/patterns-integration-utils/bm';
+
+export default () => {
+  const httpClient = useHttpClient();
+
+  const onSubmit = async () => {
+    await httpClient.request(
+      createContact({
+        /* ... */
+      }),
+    );
++   invalidateCacheForCollection({
+      moduleId: 'contacts-list', // BM module ID of the page that renders the collection
+      queryName: 'wix.contacts.v4.contact', // the queryName passed to Wix Patterns useCollection in the page that renders the collection
+    });
+  };
+
+  return <>{/* ... */};
+};
+```
+
+

package/dist/docs/arrayFilter.md

@@ -0,0 +1,226 @@
+# arrayFilter
+
+**Category:** Features/Filter/Factories
+
+## Design
+
+### Description
+
+A generic filter factory that can be used with the `filters` property of the `useCollection` hook, for selecting one or multiple values from a fixed or dynamic list of items.
+
+This is the base factory for the existing factories that we have:
+
+- [idNameArrayFilter](./?path=/story/features-filter-factories--idnamearrayfilter)
+- [stringsArrayFilter](./?path=/story/features-filter-factories--stringsarrayfilter)
+
+
+```tsx
+import { arrayFilter } from '@wix/patterns';
+```
+
+**Do:**
+
+- Use it when existing factories don't answer your use-case
+
+
+**Don't:**
+
+- Use it to re-implement already existing factories
+
+
+### stringArrayFilter
+
+A reproduce of `stringsArrayFilter`.
+
+```tsx
+import React from 'react';
+import {
+  stringsArrayFilter,
+  SingleSelectFilter,
+  useStaticListFilterCollection,
+} from '@wix/patterns';
+import { Cell, Layout } from '@wix/design-system';
+
+function stringArrayFilterExample() {
+  const [filter] = React.useState(() =>
+    stringsArrayFilter({
+      itemKey: (item) => `item-${item}`,
+      itemName: (item) => item,
+    }),
+  );
+
+  const levelsCollection = useStaticListFilterCollection(filter, [
+    'Beginner',
+    'Amateur',
+    'Semi-Pro',
+    'Professional',
+    'World Class',
+    'Legendary',
+    'Ultimate',
+  ]);
+
+  return (
+    <Layout>
+      <Cell span={4}>
+        <SingleSelectFilter filter={filter} collection={levelsCollection} />
+      </Cell>
+    </Layout>
+  );
+}
+```
+
+### idNameArrayFilter
+
+A reproduce of `idNameArrayFilter`.
+
+```tsx
+import React from 'react';
+import {
+  idNameArrayFilter,
+  SingleSelectFilter,
+  useStaticListFilterCollection,
+} from '@wix/patterns';
+import { Cell, Layout } from '@wix/design-system';
+
+interface Level {
+  id: string;
+  name: string;
+}
+
+function idNameArrayFilterExample() {
+  const [filter] = React.useState(() => idNameArrayFilter());
+
+  const levelsCollection = useStaticListFilterCollection(filter, [
+    { id: 'b', name: 'Beginner' },
+    { id: 'a', name: 'Amateur' },
+    { id: 's', name: 'Semi-Pro' },
+    { id: 'p', name: 'Professional' },
+    { id: 'w', name: 'World Class' },
+    { id: 'l', name: 'Legendary' },
+    { id: 'u', name: 'Ultimate' },
+  ]);
+
+  return (
+    <Layout>
+      <Cell span={4}>
+        <SingleSelectFilter filter={filter} collection={levelsCollection} />
+      </Cell>
+    </Layout>
+  );
+}
+```
+
+### Custom array of objects
+
+A reproduce of `stringsArrayFilter`.
+
+```tsx
+import React from 'react';
+import {
+  arrayFilter,
+  MultiSelectCheckboxFilter,
+  useStaticListFilterCollection,
+} from '@wix/patterns';
+import { Avatar, Cell, Layout } from '@wix/design-system';
+
+interface City {
+  id: string;
+  title: string;
+  subtitle: string;
+  description: string;
+  imageUrl: string;
+}
+
+function customArrayFilter() {
+  const [filter] = React.useState(() =>
+    arrayFilter<City>({
+      itemKey: (item) => item.id,
+      itemName: (item) => item.title,
+      parse: (value) =>
+        typeof value === 'object' && value
+          ? {
+              id: value.id as string,
+              title: value.title as string,
+              subtitle: value.subtitle as string,
+              description: value.description as string,
+              imageUrl: value.imageUrl as string,
+            }
+          : null,
+    }),
+  );
+
+  const citiesCollection = useStaticListFilterCollection(filter, [
+    {
+      id: '1',
+      title: 'Jerusalem',
+      subtitle: 'Israel',
+      description: 'Fascinating place to visit and photograph',
+      imageUrl: `https://www.planetware.com/wpimages/2019/12/israel-in-pictures-beautiful-places-to-photograph-jerusalem.jpg`,
+    },
+    {
+      id: '2',
+      title: 'The Dead Sea',
+      subtitle: 'Israel',
+      description: 'The lowest land point on Earth',
+      imageUrl: `https://www.planetware.com/wpimages/2019/12/israel-in-pictures-beautiful-places-to-photograph-the-dead-sea.jpg`,
+    },
+    {
+      id: '3',
+      title: 'Masada',
+      subtitle: 'Israel',
+      description: 'Mountaintop fortress',
+      imageUrl: `https://www.planetware.com/wpimages/2019/12/israel-in-pictures-beautiful-places-to-photograph-masada.jpg`,
+    },
+    {
+      id: '4',
+      title: 'Eilat',
+      subtitle: 'Israel',
+      description: 'Southern Israeli city',
+      imageUrl: `https://www.planetware.com/wpimages/2019/12/israel-in-pictures-beautiful-places-to-photograph-eilat.jpg`,
+    },
+    {
+      id: '5',
+      title: 'Haifa',
+      subtitle: 'Israel',
+      description: "Israel's third largest city",
+      imageUrl: `https://www.planetware.com/wpimages/2019/12/israel-in-pictures-beautiful-places-to-photograph-haifa.jpg`,
+    },
+  ]);
+
+  return (
+    <Layout>
+      <Cell span={4}>
+        <MultiSelectCheckboxFilter
+          popoverProps={{ appendTo: 'window' }}
+          filter={filter}
+          collection={citiesCollection}
+          renderItem={(item) => ({
+            id: item.id,
+            prefix: <Avatar size="size30" imgProps={{ src: item.imageUrl }} />,
+            title: item.title,
+            subtitle: item.description,
+          })}
+        />
+      </Cell>
+    </Layout>
+  );
+}
+```
+
+## API
+
+### Props
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `defaultValue` | `T[]` | No | - | The value to set the value to, when clearing the filter (Optional) |
+| `parse` | `(value: string \| Record<string, unknown> \| null \| undefined) => T \| null` | Yes | - | Convert a unknown object to a T.<br> If the function returns null, the item will be skipped when we try to deserializate it from an array. @param value |
+| `simplify` | `((value: T) => Partial<T>)` | No | - | Return a simplified form of an item for serialization. @param value |
+| `matches` | `((item: T, value: T[]) => boolean)` | No | - | Indicates whether an item matches the current value of the filter |
+| `equals` | `((item1: T, item2: T) => boolean)` | No | - | A function which accepts 2 items and returns true if they are equal |
+| `persistent` | `boolean` | No | - | Marks the filter as a "context" or "scope" filter. This makes the filter not be visible in the sub-toolbar tag list, not saved in views, not counted as "X filters applied". |
+| `initialValue` | `T[]` | No | - | The value to initialize the filter with (Optional) |
+| `itemKey` | `(item: T) => string` | Yes | - | A callback function that accepts an item and returns a unique ID of it. typically `item.id`. |
+| `itemName` | `(item: T) => string` | Yes | - | A callback function that accepts an item and returns the item name which is used in many messages through cairo |
+| `isCustomField` | `boolean` | No | - | If the filter is a custom field |
+