@wix/patterns 1.452.0 → 1.454.0

package/dist/docs/useEntity.md

@@ -24,21 +24,43 @@ const entity = useEntity(state);
 ### Example
 
 ```tsx
-function MyEntityPage({ state }) {
-  const entity = useEntity(state);
+import React from 'react';
+import { EntityPage, useEntity, useEntityPage } from '@wix/patterns';
+import { useForm } from '@wix/patterns/form';
+
+interface Shift {
+  id?: string;
+  name?: string;
+}
+
+interface ShiftFormFields {
+  name?: string;
+}
+
+function ShiftPage() {
+  const form = useForm<ShiftFormFields>();
+
+  const state = useEntityPage<Shift, ShiftFormFields>({
+    parentPageId: '',
+    form,
+    fetch: () => Promise.resolve({ entity: { id: '1', name: 'Morning' } }),
+    onSave: () => Promise.resolve({ updatedEntity: { id: '1' } }),
+  });
+
+  // `entity` is `Shift | undefined` — undefined until the fetch resolves.
+  const entity = useEntity<Shift, ShiftFormFields>(state);
 
   return (
     <EntityPage state={state}>
-      <EntityPage.Header
-        title={{ text: entity?.name ?? "Loading..." }}
-        subtitle={entity?.description}
-      />
+      <EntityPage.Header title={{ text: entity?.name ?? 'Loading…' }} />
       <EntityPage.Content>
-        {/* Card.Content receives the entity automatically */}
+        <EntityPage.MainContent>...</EntityPage.MainContent>
       </EntityPage.Content>
     </EntityPage>
   );
 }
+
+export default ShiftPage;
 ```
 
 ### Returns

package/dist/docs/useEntityPage.md

@@ -9,34 +9,59 @@
 A React hook that creates the state for an [`EntityPage`](./?path=/story/base-components-pages-entity-page--entitypage). Configure entity fetching, save flow, form integration, toasts, and navigation. The returned [`EntityPageState`](./?path=/story/base-components-pages-entity-page-state--entitypagestate) is passed to `<EntityPage state={state}>`.
 
 ```tsx
-import { useEntityPage } from '@wix/patterns/page';
+import { useEntityPage } from '@wix/patterns';
 ```
 
 ### Example
 
 ```tsx
-import { useEntityPage, EntityPage } from '@wix/patterns/page';
-import { useForm } from 'react-hook-form';
-
-const form = useForm({ defaultValues: { name: '' } });
-
-const state = useEntityPage({
-  fetch: () => api.getItem(itemId).then((entity) => ({ entity })),
-  onSave: ({ submittedValues }) =>
-    api.updateItem(itemId, submittedValues).then((updatedEntity) => ({ updatedEntity })),
-  form,
-  container,
-  parentPath: '/my-collection',
-});
-
-return (
-  <EntityPage state={state}>
-    <EntityPage.Header title={{ text: 'Edit Item' }} />
-    <EntityPage.Content>
-      <EntityPage.MainContent>...</EntityPage.MainContent>
-    </EntityPage.Content>
-  </EntityPage>
-);
+import React from 'react';
+import { EntityPage, useEntityPage } from '@wix/patterns';
+import { useForm } from '@wix/patterns/form';
+
+interface Shift {
+  id?: string;
+  name?: string;
+}
+
+interface ShiftFormFields {
+  name?: string;
+}
+
+const api = {
+  getShift: (id: string): Promise<Shift> =>
+    Promise.resolve({ id, name: 'Morning' }),
+  updateShift: (id: string, values: Partial<Shift>): Promise<Shift> =>
+    Promise.resolve({ id, ...values }),
+};
+
+function EditShift({ shiftId }: { shiftId: string }) {
+  const form = useForm<ShiftFormFields>({ defaultValues: { name: '' } });
+
+  const state = useEntityPage<Shift, ShiftFormFields>({
+    parentPageId: '',
+    parentPath: '/shifts',
+    form,
+    fetch: () => api.getShift(shiftId).then((entity) => ({ entity })),
+    // `onSave` receives `widgetsFormData` — what the widget fields
+    // contributed. The values the user typed come from the form itself.
+    onSave: ({ widgetsFormData }) =>
+      api
+        .updateShift(shiftId, { ...form.getValues(), ...widgetsFormData })
+        .then((updatedEntity) => ({ updatedEntity })),
+  });
+
+  return (
+    <EntityPage state={state}>
+      <EntityPage.Header title={{ text: 'Edit Shift' }} />
+      <EntityPage.Content>
+        <EntityPage.MainContent>...</EntityPage.MainContent>
+      </EntityPage.Content>
+    </EntityPage>
+  );
+}
+
+export default EditShift;
 ```
 
 ### Returns

package/dist/docs/useEntityPageContext.md

@@ -15,11 +15,23 @@ import { useEntityPageContext } from '@wix/patterns/page';
 ### Example
 
 ```tsx
-function MyCardContent() {
-  const state = useEntityPageContext();
-  // Access state.entity, state.form, etc.
+import React from 'react';
+import { useEntityPageContext } from '@wix/patterns';
+
+interface Shift {
+  id?: string;
+  name?: string;
+}
+
+// Rendered inside `<EntityPage>`, which provides the state. Pass the entity
+// type so `state.entity` is typed rather than `unknown`.
+function ShiftCardContent() {
+  const state = useEntityPageContext<Shift>();
+
   return <div>{state.entity?.name}</div>;
 }
+
+export default ShiftCardContent;
 ```
 
 ### Returns

package/dist/docs/useNestedTable.md

@@ -17,36 +17,91 @@ import { useNestedTable } from '@wix/patterns';
 ### Example
 
 ```tsx
-import { useNestedTable, NestedTable, createNestedTableLevel } from '@wix/patterns';
-
-const columns = [
-  { id: 'name', title: 'Name' },
-  { id: 'status', title: 'Status' },
-];
-
-const state = useNestedTable({
-  columns,
-  mainColumn: { title: 'Name' },
-  levels: [
-    createNestedTableLevel({
+import { Page } from '@wix/design-system';
+import React from 'react';
+import { queryContacts } from '@wix/ambassador-contacts-v4-contact/http';
+import { Contact } from '@wix/ambassador-contacts-v4-contact/types';
+import {
+  PageWrapper,
+  NestedTable,
+  useNestedTable,
+  createNestedTableSingleEntityLevels,
+  useCreateCollection,
+  Filter,
+  stringsArrayFilter,
+} from '@wix/patterns';
+import { CollectionPage } from '@wix/patterns/page';
+import { useHttpClient } from '@wix/yoshi-flow-bm';
+
+type ContactFilters = {
+  parentId: Filter<string[]>;
+};
+
+function SingleEntityNestedTable() {
+  const httpClient = useHttpClient();
+
+  const createCollection = useCreateCollection();
+
+  const state = useNestedTable({
+    columns: [
+      {
+        id: 'lastSeen',
+        title: 'Last Seen',
+      },
+    ],
+    levels: createNestedTableSingleEntityLevels(5, {
+      createCollection: () => {
+        const collection = createCollection<Contact, ContactFilters>({
+          queryName: 'SingleEntityNestedTable-contacts',
+          filters: {
+            parentId: stringsArrayFilter(),
+          },
+          fetchData: (query) => {
+            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),
+        });
+
+        return {
+          collection,
+          parentFilter: collection.filters.parentId,
+        };
+      },
       parentKey: (item) => item.parentId,
-      createCollection: () => ({
-        collection: useCollection({
-          queryName: 'my-nested-items',
-          fetchData: (query) => fetchItems(query),
-          itemKey: (item) => item.id,
-        }),
-      }),
-      renderMainColumn: (item) => ({ title: item.name }),
       columns: {
-        name: (item) => item.name,
-        status: (item) => item.status,
+        lastSeen: (item) => String(item.lastSeen),
       },
+      renderMainColumn: (item) => ({
+        subtitle: item.level,
+      }),
     }),
-  ],
-});
-
-return <NestedTable state={state} />;
+  });
+
+  return (
+    <CollectionPage height="400px">
+      <CollectionPage.Header title={{ text: 'Contacts' }} />
+      <CollectionPage.Content>
+        <NestedTable state={state} />
+      </CollectionPage.Content>
+    </CollectionPage>
+  );
+}
 ```
 
 ### Returns

package/dist/docs/usePickerContent.md

@@ -19,26 +19,40 @@ import { usePickerContent } from '@wix/patterns';
 ### Example
 
 ```tsx
-import { usePickerContent, PickerContent } from '@wix/patterns';
-
-const MyPickerContent = ({ modalState }) => {
-  const contentState = usePickerContent({
-    modalState,
-    filters: { status: stringFilter() },
-    fetchData: (query) => fetchItems(query),
+import React from 'react';
+import {
+  PickerContent,
+  PickerContentComponentProps,
+  usePickerContent,
+} from '@wix/patterns';
+
+interface Item {
+  id: string;
+  name: string;
+  status: string;
+}
+
+// A PickerModal renders this component as its `pickerContentComponent` and
+// supplies `modalState` through props — the content hook never builds it, and
+// it does not take `fetchData`: the modal owns fetching.
+function ItemsPickerContent(props: PickerContentComponentProps<Item>) {
+  const state = usePickerContent({
+    modalState: props.modalState,
+    fetchErrorMessage: ({ err }) => String(err),
     itemKey: (item) => item.id,
     itemName: (item) => item.name,
   });
 
   return (
     <PickerContent
-      state={contentState}
-      columns={[
-        { title: 'Name', render: (item) => item.name },
-      ]}
+      state={state}
+      renderItem={(item) => ({ subtitle: item.status })}
+      {...props}
     />
   );
-};
+}
+
+export default ItemsPickerContent;
 ```
 
 ### Returns

package/dist/docs/usePickerModal.md

@@ -25,22 +25,104 @@ import { usePickerModal } from '@wix/patterns/essentials';
 ### Example
 
 ```tsx
-import { usePickerModal, PickerModal } from '@wix/patterns/bm';
-
-const pickerState = usePickerModal({
-  queryName: 'my-picker',
-  fetchData: (query) => fetchItems(query),
-  limit: 50,
-  onSelect: (items) => handleSelect(items),
-  pickerContentComponent: () => import('./MyPickerContent'),
-});
-
-return (
-  <>
-    <button onClick={pickerState.open}>Open Picker</button>
-    <PickerModal state={pickerState} />
-  </>
-);
+import { Avatar, EmptyState, Page } from '@wix/design-system';
+import React from 'react';
+import { queryContacts } from '@wix/ambassador-contacts-v4-contact/http';
+import {
+  OffsetQuery,
+  PickerContent,
+  PickerContentComponentProps,
+  PickerModal,
+  PickerModalOpenButton,
+  usePickerContent,
+} from '@wix/patterns';
+import {
+  WixPatternsEssentialsProvider,
+  usePickerModal,
+} from '@wix/patterns/essentials';
+import { useHttpClient } from '@wix/fe-essentials/react';
+import { Contact } from '@wix/ambassador-contacts-v4-contact/types';
+
+function PickerModalSingleSelectExample() {
+  const httpClient = useHttpClient();
+
+  // Usually we will extract this component to a separate file and use dynamic import when passing it as `pickerContentComponent`
+  const pickerContentComponent = async () => ({
+    default: function ContactsPicker(
+      props: PickerContentComponentProps<Contact>,
+    ) {
+      const state = usePickerContent({
+        modalState: props.modalState,
+        fetchErrorMessage: ({ err }) => String(err),
+        itemName: (contact) => contact.id as string,
+      });
+
+      return (
+        // wrap with a provider that suits your environment
+        <WixPatternsEssentialsProvider>
+          <PickerContent
+            state={state}
+            renderItem={(contact) => ({
+              subtitle: contact.level,
+              image: (
+                <Avatar size="size60" shape="square" name={contact.name} />
+              ),
+            })}
+            renderEmptyState={() => (
+              <EmptyState title="You don’t have any contacts that support this action." />
+            )}
+            {...props}
+          />
+        </WixPatternsEssentialsProvider>
+      );
+    },
+  });
+
+  const state = usePickerModal<Contact>({
+    queryName: 'PickerModalSingleSelectExample',
+    fetchData: (query: OffsetQuery) => {
+      const { limit, offset, search, filters } = query;
+      return httpClient
+        .request(
+          queryContacts({
+            query: { paging: { limit, offset }, filter: filters },
+            search,
+          }),
+        )
+        .then(({ data: { contacts, pagingMetadata } }) => ({
+          items: contacts as Contact[],
+          total: pagingMetadata?.total,
+        }));
+    },
+    limit: 25,
+    // Usually we will use dynamic import, i.e pickerContentComponent: () => import('./ContactsPicker')
+    pickerContentComponent,
+    onSelect: (_contacts) => {
+      // Do something with contacts
+    },
+  });
+
+  return (
+    <Page>
+      <Page.Header
+        title="Picker Modal Example"
+        actionsBar={
+          <>
+            <PickerModalOpenButton state={state}>
+              Select a Contact
+            </PickerModalOpenButton>
+
+            <PickerModal
+              title="Select a Contact"
+              state={state}
+              renderError={(err) => <EmptyState title={String(err)} />}
+            />
+          </>
+        }
+      />
+    </Page>
+  );
+}
 ```
 
 ### Returns

package/dist/docs/usePickerStandalone.md

@@ -21,25 +21,55 @@ import { usePickerStandalone } from '@wix/patterns';
 ### Example
 
 ```tsx
-import { usePickerStandalone, PickerStandalone } from '@wix/patterns';
-
-const state = usePickerStandalone({
-  queryName: 'site-picker',
-  fetchData: (query) => fetchSites(query),
-  itemKey: (site) => site.id,
-  itemName: (site) => site.name,
-  limit: 20,
-  defaultDestinationUrl: (site) => `/site/${site.id}/dashboard`,
-});
-
-return (
-  <PickerStandalone
-    state={state}
-    columns={[
-      { title: 'Site Name', render: (site) => site.name },
-    ]}
-  />
-);
+import React from 'react';
+import { EmptyState } from '@wix/design-system';
+import { queryContacts } from '@wix/ambassador-contacts-v4-contact/http';
+import {
+  OffsetQuery,
+  PickerStandalone,
+  usePickerStandalone,
+} from '@wix/patterns';
+import { useHttpClient } from '@wix/fe-essentials/react';
+
+function Basic() {
+  const httpClient = useHttpClient();
+
+  const fetchData = (query: OffsetQuery) => {
+    const { limit, offset, search } = query;
+    return httpClient
+      .request(
+        queryContacts({
+          query: { paging: { limit, offset } },
+          search,
+        }),
+      )
+      .then(({ data: { contacts, pagingMetadata } }) => ({
+        items: contacts || [],
+        total: pagingMetadata?.total,
+      }));
+  };
+
+  const state = usePickerStandalone({
+    queryName: 'picker-standalone-basic',
+    fetchData,
+    limit: 25,
+    defaultDestinationUrl: 'https://www.wix.com',
+    fetchErrorMessage: () => 'Error fetching contacts',
+    itemName: (contact) => contact.name as string,
+  });
+
+  return (
+    <PickerStandalone
+      height="666px"
+      defaultTitle="Select a Contact"
+      state={state}
+      renderError={() => <EmptyState title="Error has occured" />}
+      renderEmptyState={() => (
+        <EmptyState title="You don't have any contacts that support this action." />
+      )}
+    />
+  );
+}
 ```
 
 ### Returns

package/dist/docs/useSettingsPage.md

@@ -9,33 +9,54 @@
 A React hook that creates the state for a [`SettingsPage`](./?path=/story/base-components-pages-settings-page--settingspage). Configure settings fetching, save/cancel flow, form integration, and toasts. The returned [`SettingsPageState`](./?path=/story/base-components-pages-settings-page-state--settingspagestate) is passed to `<SettingsPage state={state}>`.
 
 ```tsx
-import { useSettingsPage } from '@wix/patterns/page';
+import { useSettingsPage } from '@wix/patterns';
 ```
 
 ### Example
 
 ```tsx
-import { useSettingsPage, SettingsPage } from '@wix/patterns/page';
-import { useForm } from 'react-hook-form';
-
-const form = useForm({ defaultValues: { notifications: true } });
-
-const state = useSettingsPage({
-  fetch: () => api.getSettings().then((settings) => ({ settings })),
-  onSave: () => api.saveSettings(form.getValues()),
-  onCancel: () => form.reset(),
-  form,
-  container,
-});
-
-return (
-  <SettingsPage state={state}>
-    <SettingsPage.Header title={{ text: 'Settings' }} />
-    <SettingsPage.Content>
-      <SettingsPage.MainContent>...</SettingsPage.MainContent>
-    </SettingsPage.Content>
-  </SettingsPage>
-);
+import React from 'react';
+import { SettingsPage, useSettingsPage } from '@wix/patterns';
+import { useForm } from '@wix/patterns/form';
+
+interface Settings {
+  notifications?: boolean;
+}
+
+interface SettingsFormFields {
+  notifications?: boolean;
+}
+
+const api = {
+  getSettings: (): Promise<Settings> =>
+    Promise.resolve({ notifications: true }),
+  saveSettings: (values: SettingsFormFields): Promise<void> =>
+    Promise.resolve(),
+};
+
+function AppSettings() {
+  const form = useForm<SettingsFormFields>({
+    defaultValues: { notifications: true },
+  });
+
+  const state = useSettingsPage<Settings, SettingsFormFields>({
+    form,
+    fetch: () => api.getSettings().then((settings) => ({ settings })),
+    onSave: () => api.saveSettings(form.getValues()),
+    onCancel: async () => form.reset(),
+  });
+
+  return (
+    <SettingsPage state={state}>
+      <SettingsPage.Header title={{ text: 'Settings' }} />
+      <SettingsPage.Content>
+        <SettingsPage.MainContent>...</SettingsPage.MainContent>
+      </SettingsPage.Content>
+    </SettingsPage>
+  );
+}
+
+export default AppSettings;
 ```
 
 ### Returns

package/dist/docs/useSettingsPageContext.md

@@ -15,11 +15,22 @@ import { useSettingsPageContext } from '@wix/patterns/page';
 ### Example
 
 ```tsx
-function MySettingsCard() {
-  const state = useSettingsPageContext();
-  // Access state.form, state.settings, etc.
+import React from 'react';
+import { useSettingsPageContext } from '@wix/patterns';
+
+interface AppSettings {
+  theme?: string;
+}
+
+// Rendered inside `<SettingsPage>`, which provides the state. Pass the
+// settings type so `state.settings` is typed rather than `unknown`.
+function ThemeSummary() {
+  const state = useSettingsPageContext<AppSettings>();
+
   return <div>Current value: {state.settings?.theme}</div>;
 }
+
+export default ThemeSummary;
 ```
 
 ### Returns

package/dist/esm/components/CardContainer/CardContainer.st.css.js

@@ -1,12 +1,12 @@
 // @ts-nocheck
 import { classesRuntime, statesRuntime } from "../../stylable-esm-runtime.js";
-var _namespace_ = "CardContainer3189623173";
+var _namespace_ = "CardContainer3564880150";
 var _style_ = classesRuntime.bind(null, _namespace_);
 export var cssStates = statesRuntime.bind(null, _namespace_);
 export var style = _style_;
 export var st = _style_;
 export var namespace = _namespace_;
-export var classes = { "root": "CardContainer3189623173__root" };
+export var classes = { "root": "CardContainer3564880150__root" };
 export var keyframes = {};
 export var layers = {};
 export var containers = {};

package/dist/esm/components/CmsFieldManagement/CmsFieldForm.st.css.js

@@ -1,12 +1,12 @@
 // @ts-nocheck
 import { classesRuntime, statesRuntime } from "../../stylable-esm-runtime.js";
-var _namespace_ = "CmsFieldForm4067018512";
+var _namespace_ = "CmsFieldForm1400944717";
 var _style_ = classesRuntime.bind(null, _namespace_);
 export var cssStates = statesRuntime.bind(null, _namespace_);
 export var style = _style_;
 export var st = _style_;
 export var namespace = _namespace_;
-export var classes = { "root": "CmsFieldForm4067018512__root", "fullBleedDivider": "CmsFieldForm4067018512__fullBleedDivider" };
+export var classes = { "root": "CmsFieldForm1400944717__root", "fullBleedDivider": "CmsFieldForm1400944717__fullBleedDivider" };
 export var keyframes = {};
 export var layers = {};
 export var containers = {};