@wix/patterns 1.255.0 → 1.256.0

package/src/hooks/useBuildOption.ts

@@ -0,0 +1,96 @@
+import {
+  listItemSectionBuilder,
+  listItemSelectBuilder,
+} from '@wix/design-system';
+import { ArrayField, KeyedItem } from '@wix/bex-core';
+import { ListItem } from './listItem';
+import { useCallback, useMemo } from 'react';
+import {
+  DropdownLayoutOption,
+  DropdownLayoutValueOption,
+} from '@wix/design-system/dist/types/DropdownLayout';
+
+export function useBuildOption<V>({
+  filter,
+  checkbox,
+  renderItem,
+}: {
+  filter: ArrayField<V>;
+  renderItem?: (item: V, index: number) => ListItem;
+  checkbox?: boolean;
+}) {
+  return useCallback(
+    (keyedItem: KeyedItem<V>, index: number) => {
+      const { key, item } = keyedItem;
+      const option = renderItem?.(item, index);
+
+      const title = filter.itemName(item);
+
+      return Object.assign(
+        listItemSelectBuilder({
+          id: key,
+          checkbox,
+          ellipsis: true,
+          title: filter.itemName(item),
+          label: title,
+          ...option,
+        }),
+        {
+          sectionId: option?.sectionId,
+          keyedItem,
+        },
+      );
+    },
+    [renderItem, checkbox],
+  );
+}
+
+type DropdownLayoutValueOptionWithSectionId = DropdownLayoutValueOption & {
+  sectionId?: string;
+};
+
+export interface BuildSectionOptionsArgs {
+  readonly items: DropdownLayoutValueOptionWithSectionId[];
+  readonly renderSection?: (
+    sectionId: string,
+  ) => Parameters<typeof listItemSectionBuilder>[0];
+}
+
+export function useBuildGroupedOptions({
+  items,
+  renderSection,
+}: BuildSectionOptionsArgs) {
+  return useMemo(() => {
+    if (!renderSection) {
+      return items;
+    }
+
+    const { groups } = items.reduce(
+      (acc, option) => {
+        const sectionId = option.sectionId || '';
+
+        let group;
+
+        if (acc._cache[sectionId]) {
+          group = acc._cache[sectionId];
+        } else {
+          group = [
+            listItemSectionBuilder(renderSection(sectionId)),
+          ] as DropdownLayoutOption[];
+          acc.groups.push(group);
+          acc._cache[sectionId] = group;
+        }
+
+        group.push(option);
+
+        return acc;
+      },
+      {
+        _cache: {} as Record<string, DropdownLayoutOption[]>,
+        groups: [] as DropdownLayoutOption[][],
+      },
+    );
+
+    return groups.flatMap((e) => e);
+  }, [items, renderSection]);
+}

package/src/hooks/useCollectionComponentBaseParams.ts

@@ -0,0 +1,11 @@
+import { CollectionState, FiltersMap, OptionalFiltersMap } from '@wix/bex-core';
+
+export interface UseCollectionComponentBaseParams<
+  T,
+  F extends FiltersMap = OptionalFiltersMap,
+> {
+  /**
+   * An instance of [CollectionState](./?path=/story/common-state--collectionstate), can be initialized using [useCollection](./?path=/story/common-hooks--usecollection) hook.
+   */
+  collection: CollectionState<T, F>;
+}

package/src/hooks/useCollectionFilterInitialFetchTiming.ts

@@ -0,0 +1,40 @@
+import { useCallback, useMemo, useState } from 'react';
+
+export interface CollectionFilterInitialFetchTimingProps {
+  /**
+   * At which point the initial fetch of the filter collection data takes place. If this prop is omitted, it will take place on component mount.<br> <br>
+   * Supported values: <br>
+   * - `focus`: On the first visitor interaction with the filter component.
+   * @default undefined - on component mount
+   * @external
+   */
+  initialFetchTiming?: 'focus';
+  collection: {
+    initialFetch: () => unknown;
+  };
+}
+export function useCollectionFilterInitialFetchTiming(
+  props: CollectionFilterInitialFetchTimingProps,
+) {
+  const { initialFetchTiming, collection } = props;
+
+  useState(() => {
+    if (!initialFetchTiming) {
+      collection.initialFetch();
+    }
+  });
+
+  const onFocus = useCallback(() => {
+    initialFetchTiming === 'focus' && collection.initialFetch();
+  }, [initialFetchTiming]);
+
+  const skipInitialFetch = useMemo(
+    () => initialFetchTiming === 'focus',
+    [initialFetchTiming],
+  );
+
+  return {
+    onFocus,
+    skipInitialFetch,
+  };
+}

package/src/hooks/useCollectionOptions.tsx

@@ -0,0 +1,81 @@
+import { listItemSectionBuilder } from '@wix/design-system';
+import { FiltersMap, CollectionState, ArrayField } from '@wix/bex-core';
+import { ListItem, useBuildOption } from '.';
+import { DropdownCollectionFilterState } from '../state';
+import {
+  KeyedItemOption,
+  MultiSelectCheckboxFilterBaseOption,
+} from '../components/MultiSelectCheckboxFilterBase';
+
+interface UseCollectionOptionsProps<V, F extends FiltersMap> {
+  collection: CollectionState<V, F>;
+  dropdownCollectionFilterState: DropdownCollectionFilterState<V, F>;
+  renderItem?: (item: V, index: number) => ListItem;
+  filter: ArrayField<V>;
+}
+
+export function useCollectionOptions<V, F extends FiltersMap>({
+  collection,
+  dropdownCollectionFilterState,
+  renderItem,
+  filter,
+}: UseCollectionOptionsProps<V, F>) {
+  const buildOption = useBuildOption<V>({
+    filter,
+    renderItem,
+    checkbox: true,
+  });
+
+  const {
+    result: { keyedItems },
+    query: {
+      search: { isEmpty: isEmptySearch },
+    },
+  } = collection;
+
+  // Original behavior: promote when not searching
+  const shouldPromote = isEmptySearch;
+  
+  // Always use the snapshot from onOptionsShow to maintain consistent session behavior
+  // This prevents items from jumping during the session, even if snapshot is empty
+  const itemsToPromote = dropdownCollectionFilterState.promotedItems;
+
+  const promotedItems = shouldPromote 
+    ? keyedItems.filter(item => itemsToPromote.includes(item.key))
+    : [];
+
+  const finalOptions = promotedItems.length
+    ? promotedItems.map(buildOption)
+    : [];
+
+  const divider =
+    shouldPromote && 
+    promotedItems.length &&
+    promotedItems.length !== keyedItems.length
+      ? [
+          listItemSectionBuilder({
+            id: 'promoted-section-divider',
+            type: 'divider',
+          }),
+        ]
+      : [];
+
+  const promotedOptions: MultiSelectCheckboxFilterBaseOption<V>[] = [
+    ...finalOptions,
+    ...divider,
+  ];
+
+  const promotedItemKeys = new Set(itemsToPromote);
+
+  const otherOptions: KeyedItemOption<V>[] = (
+    shouldPromote
+      ? keyedItems.filter(({ key }) => !promotedItemKeys.has(key))
+      : keyedItems
+  ).map(buildOption);
+
+  const options = [...(shouldPromote ? promotedOptions : []), ...otherOptions];
+
+  return {
+    options,
+  };
+}

package/src/hooks/useCollectionPageChild/index.ts

@@ -0,0 +1 @@
+export * from './useCollectionPageChild';

package/src/hooks/useCollectionPageChild/useCollectionPageChild.tsx

@@ -0,0 +1,38 @@
+import React, { isValidElement, Children, ReactNode } from 'react';
+import {
+  CollectionPageHeader,
+  CollectionPageHeaderElement,
+} from '../../components/CollectionPageHeaderNew';
+import {
+  CollectionPageContent,
+  CollectionPageContentElement,
+} from '../../components/CollectionPageContent';
+
+export function useCollectionPageChild(children: ReactNode) {
+  // Mapping to raw WDS components since original Page filtering none expected components: https://github.com/wix-private/wix-design-systems/blob/master/packages/wix-style-react/src/Page/Page.js#L626
+  return Children.toArray(children)
+    .map((child, index) => {
+      let newChild = null;
+      if (isValidElement(child)) {
+        switch (child.type) {
+          case CollectionPageHeader:
+            const header = child as CollectionPageHeaderElement;
+            newChild = header.type.useCollectionPageHeader(header);
+            break;
+          case CollectionPageContent:
+            const content = child as CollectionPageContentElement;
+            newChild = content.type.useCollectionPageContent(content);
+            break;
+          default:
+            // WIP: Eventually once we will support all child types this will return null
+            newChild = child;
+        }
+      }
+
+      if (newChild === null) {
+        return null;
+      }
+      return React.cloneElement(newChild, { key: index });
+    })
+    .filter((c) => c);
+}

package/src/hooks/useColumnsSyncProps.ts

@@ -0,0 +1,93 @@
+import { useEffect, useMemo, useState } from 'react';
+import { runInAction } from 'mobx';
+import { TableColumn } from '../model';
+import { ToolbarCollectionState } from '../state';
+import { FiltersMap } from '@wix/bex-core';
+import { CustomColumnsElement } from '../components/assertComponentType';
+import { usePageContext } from '@wix/bex-core/react';
+import { useWixPatternsRouter } from '../providers/WixPatternsRouterProvider';
+
+export interface UseColumnsSyncPropsParams<T, F extends FiltersMap> {
+  customColumns?: CustomColumnsElement | null;
+  columns: TableColumn<T>[];
+  toolbar: ToolbarCollectionState<T, F>;
+}
+
+export function useColumnsSyncProps<T, F extends FiltersMap>(
+  props: UseColumnsSyncPropsParams<T, F>,
+) {
+  const { toolbar, customColumns, columns: tableColumns } = props;
+  const { modalsContainerRef } = usePageContext();
+  const router = useWixPatternsRouter();
+
+  const customColumnsProps = useMemo(() => {
+    if (customColumns == null) {
+      return null;
+    }
+
+    const { onColumnClick } = customColumns.props;
+
+    return {
+      onColumnClick,
+      dragAndDrop: customColumns.type.dragAndDrop,
+    };
+  }, [customColumns]);
+
+  useState(() =>
+    customColumns?.type.setCustomColumnsState({
+      toolbar,
+      customColumnsProps: {
+        dragAndDrop: customColumnsProps?.dragAndDrop,
+      },
+      modalsContainerRef,
+    }),
+  );
+
+  useEffect(() => {
+    runInAction(() => {
+      toolbar.customColumnsProps = customColumnsProps;
+    });
+  }, [customColumnsProps]);
+
+  useEffect(() => {
+    if (router?.isUsingCache) {
+      return;
+    }
+
+    toolbar._adjustSortWithNewColumns(tableColumns);
+  }, [tableColumns.map((e, i) => e.id ?? i).join('')]);
+
+  useEffect(() => {
+    toolbar.setNewColumns(tableColumns);
+  }, [
+    tableColumns,
+    customColumnsProps != null,
+    toolbar.customColumnsStateInitialized,
+  ]);
+
+  const customColumnsDependency = useMemo(
+    () =>
+      JSON.stringify(
+        tableColumns.map(
+          (
+            { id, reorderDisabled, hiddenFromCustomColumnsSelection, hideable },
+            i,
+          ) => ({
+            id: id ?? i,
+            reorderDisabled,
+            hiddenFromCustomColumnsSelection,
+            hideable,
+          }),
+        ),
+      ),
+    [tableColumns],
+  );
+
+  useEffect(() => {
+    toolbar._adjustSelectedColumns();
+  }, [
+    customColumnsDependency,
+    customColumnsProps != null,
+    toolbar.customColumnsStateInitialized,
+  ]);
+}

package/src/hooks/useCreateNestedOptimisticActions.ts

@@ -0,0 +1,31 @@
+import { useCallback } from 'react';
+import {
+  CollectionOptimisticActionsBaseParams,
+  CollectionState,
+  FiltersMap,
+} from '@wix/bex-core';
+import { useWixPatternsContainer } from '@wix/bex-core/react';
+import {
+  createNestedOptimisticActions,
+  NestedOptimisticActionsState,
+} from '../state/NestedTableState/createNestedOptimisticActions';
+
+export function useCreateNestedOptimisticActions() {
+  const container = useWixPatternsContainer();
+
+  return useCallback(
+    <T, F extends FiltersMap>(
+      collection: CollectionState<T, F>,
+      state?: NestedOptimisticActionsState<T, F>,
+      params?: Partial<CollectionOptimisticActionsBaseParams<T, F>>,
+    ) => {
+      return createNestedOptimisticActions(
+        container,
+        collection,
+        state,
+        params,
+      );
+    },
+    [],
+  );
+}

package/src/hooks/useCreateWSRColumnBase.ts

@@ -0,0 +1,56 @@
+import { TableColumn } from '../model';
+import { useCallback } from 'react';
+
+export interface UseCreateWSRColumnBaseParams {
+  horizontalScroll?: boolean;
+}
+
+export function useCreateWSRColumnBase({
+  horizontalScroll,
+}: UseCreateWSRColumnBaseParams) {
+  return useCallback(
+    (
+      column: Omit<TableColumn<unknown>, 'render' | 'style'>,
+      index: number,
+      length: number,
+    ) => {
+      const { id, title, width, sortable, infoTooltipProps } = column;
+      const lastColumn = index === length - 1;
+
+      const lastColumnStyleNoHorizontalScroll =
+        width != null
+          ? {
+              flexBasis: width,
+              flexGrow: 1,
+            }
+          : {
+              flex: 1,
+            };
+
+      const lastColumnStyle = horizontalScroll
+        ? {
+            flexBasis: width ?? 0,
+            flexShrink: 0,
+            flexGrow: 1,
+          }
+        : lastColumnStyleNoHorizontalScroll;
+
+      const columnStyle = width == null ? { flex: 1 } : undefined;
+
+      const style = lastColumn ? lastColumnStyle : columnStyle;
+
+      return {
+        id,
+        key: id ?? index,
+        title,
+        style,
+        width: lastColumn && !horizontalScroll ? undefined : width,
+        sortable: id && sortable ? true : undefined,
+        infoTooltipProps: infoTooltipProps?.content
+          ? infoTooltipProps
+          : undefined,
+      };
+    },
+    [horizontalScroll],
+  );
+}

package/src/hooks/useCustomFieldsWidget.ts

@@ -0,0 +1,53 @@
+import { useEffect, useState } from 'react';
+import { CustomFieldsWidgetState } from '../state';
+import { useWixPatternsContainer } from '@wix/bex-core/react';
+import {
+  ExtendedFields,
+  parseFqdn,
+  DefaultPermissionsConfig,
+} from '@wix/bex-core';
+import { useWidgetForm } from './useWidgetForm';
+
+export interface UseCustomFieldsWidgetParams {
+  fqdn: string;
+  fieldName?: string;
+  filterable?: boolean;
+  containsPii?: boolean;
+  defaultPermissions?: DefaultPermissionsConfig;
+  extendedFields?: ExtendedFields;
+}
+
+export function useCustomFieldsWidget({
+  fqdn: fqdnString,
+  fieldName = 'extendedFields',
+  filterable,
+  containsPii,
+  defaultPermissions,
+  extendedFields,
+}: UseCustomFieldsWidgetParams) {
+  const fqdn = parseFqdn(fqdnString);
+  const container = useWixPatternsContainer();
+  const widgetForm = useWidgetForm();
+
+  const [{ state, appLoaded }] = useState(() => {
+    const widgetState = new CustomFieldsWidgetState({
+      fqdn,
+      container,
+      filterable,
+      containsPii,
+      defaultPermissions,
+      extendedFields,
+    });
+
+    widgetForm?.registerWidget(fieldName, widgetState);
+
+    return {
+      state: widgetState,
+      appLoaded: widgetState._appLoadingStart(),
+    };
+  });
+
+  useEffect(() => state.init({ appLoaded }), []);
+
+  return state;
+}

package/src/hooks/useDateRangeFilterState.ts

@@ -0,0 +1,31 @@
+import { useState } from 'react';
+import { DateRangeFilterState } from '../state';
+import { useWixPatternsContainer } from '@wix/bex-core/react';
+import { DateRangeFilterMode, Filter, RangeItem } from '@wix/bex-core';
+import { useFilterToolbarState } from '../providers';
+
+export interface UseDateRangeFilterStateParams {
+  filter: Filter<RangeItem<Date>>;
+  filterByTime?: boolean;
+  mode?: DateRangeFilterMode;
+}
+
+export function useDateRangeFilterState(params: UseDateRangeFilterStateParams) {
+  const { filter, filterByTime, mode } = params;
+
+  const { translate } = useWixPatternsContainer();
+  const toolbar = useFilterToolbarState();
+
+  const [state] = useState(
+    () =>
+      new DateRangeFilterState({
+        translate,
+        filter,
+        toolbar,
+        filterByTime,
+        mode,
+      }),
+  );
+
+  return state;
+}

package/src/hooks/useDropdownPlaceholder.ts

@@ -0,0 +1,62 @@
+import { useMemo } from 'react';
+import { DropdownSelectState } from '../state';
+import { Filter } from '@wix/bex-core';
+import { useDropdownTranslationContext } from '../providers';
+
+export interface UseDropdownPlaceholderParams<V> {
+  dropdownSelect: DropdownSelectState<V>;
+  filter: Filter<V[]>;
+  shouldShowPlaceholder: boolean;
+  isOverflow: boolean;
+  placeholderProp?: string;
+}
+
+export function useDropdownPlaceholder<V>({
+  dropdownSelect,
+  filter,
+  shouldShowPlaceholder,
+  isOverflow,
+  placeholderProp,
+}: UseDropdownPlaceholderParams<V>) {
+  const {
+    select: { selectedValues },
+    container,
+  } = dropdownSelect;
+  const { translate } = useDropdownTranslationContext();
+
+  const selectedValuesText = useMemo(() => {
+    return selectedValues.map(({ item }) => filter.itemName(item)).join(', ');
+  }, [selectedValues]);
+
+  return useMemo(() => {
+    let placeholder = '';
+
+    if (!shouldShowPlaceholder) {
+      return { selectedValuesText, placeholder };
+    }
+
+    if (selectedValues.length !== 0) {
+      if (
+        (process.env.NODE_ENV === 'test' && selectedValuesText.length > 40) ||
+        isOverflow
+      ) {
+        placeholder = translate('selectedItems', {
+          total: selectedValues.length,
+        });
+      } else {
+        placeholder = selectedValuesText;
+      }
+    } else if (placeholderProp) {
+      placeholder = placeholderProp;
+    } else {
+      placeholder = translate('placeholder');
+    }
+
+    return { selectedValuesText, placeholder };
+  }, [
+    selectedValues,
+    shouldShowPlaceholder,
+    isOverflow,
+    container.initTask.status.status,
+  ]);
+}

package/src/hooks/useDropdownSelectFilterState.ts

@@ -0,0 +1,29 @@
+import { useState } from 'react';
+import { DropdownSelectFilterState } from '../state';
+import { useWixPatternsContainer } from '@wix/bex-core/react';
+import { ArrayField } from '@wix/bex-core';
+import { useFilterToolbarState } from '../providers';
+
+export interface UseDropdownSelectFilterStateParams<V> {
+  filter: ArrayField<V>;
+}
+
+export function useDropdownSelectFilterState<V>(
+  params: UseDropdownSelectFilterStateParams<V>,
+) {
+  const { filter } = params;
+
+  const container = useWixPatternsContainer();
+  const toolbar = useFilterToolbarState();
+
+  const [state] = useState(
+    () =>
+      new DropdownSelectFilterState<V>({
+        container,
+        toolbar,
+        filter,
+      }),
+  );
+
+  return state;
+}

package/src/hooks/useEmptyStateTexts.ts

@@ -0,0 +1,40 @@
+import { CollectionState, FiltersMap } from '@wix/bex-core';
+import { ReactNode } from 'react';
+
+export function useEmptyStateTexts<T, F extends FiltersMap>(props: {
+  state: CollectionState<T, F>;
+  subtitle?: ReactNode;
+}) {
+  const { state } = props;
+  const {
+    translate: t,
+    result: { originQuery, hasAvailableItems },
+  } = state;
+
+  const { search, rawSearch } = originQuery;
+
+  const subtitle = (() => {
+    if (props.subtitle) {
+      return props.subtitle;
+    }
+
+    if (hasAvailableItems && search != null) {
+      return t('cairo.emptyState.subtitle.nothingMatches', {
+        term: rawSearch,
+      });
+    }
+
+    if (hasAvailableItems) {
+      return t('cairo.emptyState.subtitle.nothingMatchesCriteria');
+    }
+
+    return t('cairo.emptyState.subtitle.nothingAvailable');
+  })();
+
+  const title = t('cairo.emptyState.title');
+
+  return {
+    title,
+    subtitle,
+  };
+}

package/src/hooks/useEntity.ts

@@ -0,0 +1,9 @@
+import { EntityPageState } from '../state';
+import { useSelector } from '../useSelector';
+import { FieldValues } from 'react-hook-form';
+
+export function useEntity<T, V extends FieldValues = FieldValues>(
+  state: EntityPageState<T, V>,
+) {
+  return useSelector(() => state.entity);
+}