@wix/patterns 1.475.0 → 1.477.0

package/dist/dts-bundle/hooks/schema/useCollection.d.ts

@@ -0,0 +1,341 @@
+interface ExtendedFieldsDataMap {
+    [key: string]: any;
+}
+interface ExtendedFields {
+    _type?: 'ExtendedFields';
+    /**
+     * Data Extensions extended fields
+     * Key: Namespace
+     * Value: extended fields data in Struct format
+     */
+    namespaces?: {
+        _user_fields?: ExtendedFieldsDataMap | undefined;
+        [key: string]: ExtendedFieldsDataMap | undefined;
+    };
+}
+
+/**
+ * `CollectionState` — you receive this, you don't construct it.
+ * Produced by `useFilterCollection()` (also `useStaticListFilterCollection()`, `useCollection()`, `createCollection()`).
+ */
+declare class CollectionState<T = any, F = any> {
+    [key: string]: unknown;
+}
+
+/**
+ * `OffsetQuery` — cut here because it has its own bundle.
+ * Full shape: `types/OffsetQuery.d.ts`.
+ */
+type OffsetQuery<F = any> = Omit<ComputedQuery<F>, 'cursor'>;
+type OffsetQueryResult<T> = Omit<DataResultRaw<T>, 'cursor'>;
+type OffsetFetchDataFn<T, F extends FiltersMap> = (query: OffsetQuery<F>) => Promise<OffsetQueryResult<T>>;
+type CursorQueryResult<T> = Omit<DataResultRaw<T>, 'cursor'> & {
+    cursor: string | undefined | null;
+};
+/**
+ * `CursorQuery` — cut here because it has its own bundle.
+ * Full shape: `types/CursorQuery.d.ts`.
+ */
+type CursorQuery<F = any> = Omit<ComputedQuery<F>, 'offset'>;
+type CursorFetchDataFn<T, F extends FiltersMap> = (query: CursorQuery<F>) => Promise<CursorQueryResult<T>>;
+type FetchTotalFn = (query: CursorQuery) => Promise<number>;
+type PaginationModeConfig<T, F extends FiltersMap> = {
+    paginationMode?: 'offset';
+    fetchData: OffsetFetchDataFn<T, F>;
+} | {
+    paginationMode: 'cursor';
+    fetchTotal?: FetchTotalFn;
+    fetchData: CursorFetchDataFn<T, F>;
+};
+
+/** The resolved source: defaults filled, `loadSchema` memoized. */
+/**
+ * `SchemaSource` — cut here because it has its own bundle.
+ * Full shape: `types/SchemaSource.d.ts`.
+ */
+interface SchemaSource<T = any> {
+    [key: string]: unknown;
+}
+
+/**
+ * `Filter` — cut here because it has its own bundle.
+ * Full shape: `types/Filter.d.ts`.
+ */
+interface Filter<T = any> {
+    [key: string]: unknown;
+}
+type FiltersMap = {
+    [key: string]: Filter<any> | undefined;
+};
+type OptionalFiltersMap = {
+    [key: string]: undefined;
+};
+
+/**
+ * `ComputedQuery` — cut here because it has its own bundle.
+ * Full shape: `types/ComputedQuery.d.ts`.
+ */
+interface ComputedQuery<F = any> {
+    [key: string]: unknown;
+}
+
+/**
+ * `DataResultRaw` — cut here because it has its own bundle.
+ * Full shape: `types/DataResultRaw.d.ts`.
+ */
+interface DataResultRaw<T = any> {
+    [key: string]: unknown;
+}
+
+interface ComputedResult {
+    total: number;
+    available: number;
+}
+
+type OnResultUpdated<F extends FiltersMap> = (params: {
+    query: ComputedQuery<F>;
+    result: ComputedResult;
+}) => unknown;
+type OnNewPageAdded<F extends FiltersMap> = (params: {
+    totalNewItems: number;
+    result: {
+        total: number;
+        available: number;
+    };
+    query: ComputedQuery<F>;
+}) => unknown;
+interface CollectionEvents<F extends FiltersMap> {
+    /** When the first page of items is ready */
+    readonly onInitialPageFetched?: OnResultUpdated<F>;
+    /** When fetching new items as a result new search */
+    readonly onSearch?: (params: {
+        query: ComputedQuery<F>;
+    }) => unknown;
+    /** When the result of a search is ready */
+    readonly onSearchResults?: OnResultUpdated<F>;
+    /** When starting to load the next page of items */
+    readonly onNewPageStart?: (params: {
+        query: ComputedQuery<F>;
+    }) => void | undefined | null | OnNewPageAdded<F>;
+    /** When the result of the next page is ready */
+    readonly onNewPageAdded?: OnNewPageAdded<F>;
+    /** When `fetchData` throws an error. Return `true` from this function if the error was reported and shouldn't be reported again internally. */
+    readonly onError?: (params: {
+        err: unknown;
+        isOnline: boolean;
+    }) => boolean | undefined | null | void;
+}
+
+/**
+ * Retry configuration for failed queries.
+ * - `false`: Disable retries entirely
+ * - `number`: Retry up to this many times
+ * - `function`: Custom retry logic that receives (failureCount, error) and returns boolean
+ */
+type RetryValue = boolean | number | ((failureCount: number, error: unknown) => boolean);
+interface QueryOptions {
+    staleTime?: number;
+    retryDelay?: number;
+    /**
+     * Configure retry behavior for failed queries.
+     *
+     * By default, Cairo retries all failed queries up to 3 times.
+     *
+     * @example
+     * // Disable retries entirely
+     * queryOptions: { retry: false }
+     *
+     * @example
+     * // Custom retry logic
+     * queryOptions: {
+     *   retry: (failureCount, error) => {
+     *     // Only retry on 5xx server errors
+     *     if (isHttpError(error) && error.response?.status >= 500) {
+     *       return failureCount < 3;
+     *     }
+     *     return false;
+     *   }
+     * }
+     */
+    retry?: RetryValue;
+}
+
+interface CollectionConfigBase<T, F extends FiltersMap> {
+    /**
+     * Whether to disable "Select All" server simulation for bulk selection.
+     * @external
+     */
+    disableAutoSelectAllCount?: boolean;
+    /**
+     * Whether to enable new "Select All" logic.
+     * <br> <br>
+     * If `true`: <br>
+     * - Unchecking items after checking "Select All" does not fallback to specific selection logic and values. This means in `<bulkActionToolbar />` and `<MultiBulkActionToolbar />`, "Total Selected" will show `total - unchecked items` and `isSelectAll` will be true. <br>
+     * - You will receive a list of unchecked IDs.
+     * @external
+     */
+    useNewSelectAllLogic?: boolean;
+    /**
+     * Unique value for each API endpoint consumed in `fetchData`.
+     * @external
+     */
+    queryName: string;
+    /**
+     * Entity fqdn.
+     * @external
+     */
+    fqdn?: string;
+    /**
+     * The `ExtendedFields` object used to render custom field values
+     * Optional in case your data complies to the type `{ extendedFields: ExtendedFields }`
+     */
+    toExtendedFields?: (item: T) => ExtendedFields | undefined | null;
+    /**
+     * Message shown in a toast when fetching from the server fails.
+     * <br> <br>
+     * If the function returns a nullish value, no toast is shown.
+     * @external
+     * @deprecated Instead of using `fetchErrorMessage`, use `errorState` prop in the component, which will show the error message in the card.
+     */
+    fetchErrorMessage?: (params: {
+        err: unknown;
+        isOnline: boolean;
+    }) => string | null | undefined;
+    search?: Filter<string>;
+    queryOptions?: QueryOptions;
+    /**
+     * Persist the selected filters, search & sort in the query parameters of the URL.<br/>
+     * For improved readability, sort & columns are formatted in CSV-like formatting, i.e "?sort=name+desc,price+asc". Do not use commas and/or spaces for your columns IDs.<br>
+     * Note: The filters from the selected view will be persist, but the actual view will not be selected
+     * @default false
+     */
+    persistQueryToUrl?: boolean;
+    /**
+     * Whether the collection refreshes when different columns are selected.
+     * <br> <br>
+     * Selected columns are passed in `fetchData(query.columns)`.
+     * @default false
+     * @external
+     */
+    refreshOnColumnsChange?: boolean;
+    initialPage?: DataResultRaw<T>;
+    deferInitialLoading?: boolean;
+    /**
+     * Preserve or clear selection after applying a new search or filter.
+     * @default preserve
+     * @external
+     */
+    selectionConsistencyMode?: 'preserve' | 'clear';
+    /**
+     * Optional callbacks for various events of the collection state lifecycle
+     * - `onInitialPageFetched` - when the first page of items is ready
+     * - `onSearch` - when fetching new items as a result new search
+     * - `onSearchResults` - when the result of a search is ready
+     * - `onNewPageStart` - when starting to load the next page of items
+     * - `onNewPageAdded` - when the result of the next page is ready
+     * - `onError` - When `fetchData` throws an error. Return `true` from this function if the error was reported and shouldn't be reported again internally.
+     */
+    events?: CollectionEvents<F>;
+}
+interface CollectionConfigAnyPaginationMode<T, F extends FiltersMap> extends CollectionConfigBase<T, F> {
+    /**
+     * Function that fetches the collection data.<br> <br>
+     * Supported parameters: <br>
+     * - `query`: [object] [ComputedQuery](./com?path=/story/common-models--computedquery) instance.
+     * <br> <br>
+     *
+     * Must return a [DataResultRaw](./?path=/story/common-models--dataresultraw) Promise.
+     * @external
+     */
+    fetchData: (query: ComputedQuery<F>) => Promise<DataResultRaw<T>>;
+    /**
+     * A function that fetches the total number of items in the collection.<br> <br>
+     * Supported parameters: <br>
+     * - `query`: [object] [ComputedQuery](./com?path=/story/common-models--computedquery) of type `CursorQuery`.
+     * <br> <br>
+     * Must return a number Promise.
+     * @external
+     */
+    fetchTotal?: FetchTotalFn;
+    /**
+     * Defines the filters that the collection supports.
+     * <br> <br>
+     * Either an [arrayFilter](./?path=/story/features-filter-factories--arrayfilter) or a [customFilter](./?path=/story/features-filter-factories--customfilter).
+     * @external
+     */
+    filters: F;
+    /**
+     * Used to identify the item in many messages from Wix Patterns.
+     * <br> <br>
+     * For example, '{entity} "{itemName}" was deleted successfully' may become 'Contact "Johnny Doe" was deleted successfully'.
+     * <br> <br>
+     * If your data has an ID, then `itemKey` will default to this ID.
+     * @external
+     */
+    itemName: (item: T) => string;
+    /**
+     * Unique key within the collection. The item's ID is often used for its key.
+     * <br> <br>
+     * If your data has an ID, then `itemKey` will default to this ID.
+     * @external
+     */
+    itemKey: (item: T) => string;
+    /**
+     * Maximum number of items fetched per page.
+     * @external
+     */
+    limit?: number;
+}
+interface CollectionConfig<T, F extends FiltersMap> extends CollectionConfigAnyPaginationMode<T, F> {
+    /**
+     * Pagination type supported by `fetchData`.
+     * <br> <br>
+     * Supported values: <br>
+     * - `"offset"`: Server accepts `query.offset`. <br>
+     * - `"cursor"`: Server returns a cursor when `fetchData` is called.
+     * @default offset
+     * @external
+     */
+    paginationMode?: 'cursor' | 'offset';
+}
+
+type ItemKeyConfig<T> = T extends {
+    id?: string | null;
+} ? {
+    itemKey?: (item: T) => string;
+} : T extends {
+    _id?: string | null;
+} ? {
+    itemKey?: (item: T) => string;
+} : {
+    itemKey: (item: T) => string;
+};
+type ItemNameConfig<T> = T extends {
+    name?: string | null;
+} ? {
+    itemName?: (item: T) => string;
+} : {
+    itemName: (item: T) => string;
+};
+type FiltersConfig<F extends FiltersMap> = F extends OptionalFiltersMap ? {
+    filters?: {};
+} : {
+    filters: F;
+};
+type CollectionConfigConditionals<T, F extends FiltersMap> = FiltersConfig<F> & ItemKeyConfig<T> & ItemNameConfig<T> & PaginationModeConfig<T, F>;
+type CollectionConfigWithConditionals<T, F extends FiltersMap> = Omit<CollectionConfig<T, F>, 'itemKey' | 'itemName' | 'filters' | 'paginationMode' | 'fetchData'> & CollectionConfigConditionals<T, F>;
+
+type FetchData<T> = (query: OffsetQuery) => Promise<OffsetQueryResult<T>>;
+type SchemaCollectionOptions<T, F extends FiltersMap> = Omit<CollectionConfigWithConditionals<T, F>, 'queryName' | 'paginationMode' | 'fetchData' | 'fetchTotal' | 'itemKey' | 'itemName' | 'fqdn'> & {
+    /** Wraps the source's fetch (filter/enrich results) without replacing it. */
+    wrapFetchData?: (next: FetchData<T>) => FetchData<T>;
+};
+
+/**
+ * A bare collection driven by a schema source — data half only. For the fields
+ * UI (columns, filters, field management) use a component hook from this entry
+ * (`useTableCollection`, `useLayoutSwitchCollection`, …).
+ */
+declare const useCollection: <T, F extends FiltersMap = OptionalFiltersMap>(source: SchemaSource<T>, options?: SchemaCollectionOptions<T, F>) => CollectionState<T, F>;
+
+export { useCollection };

package/dist/dts-bundle/hooks/schema/useEntityPage.d.ts

@@ -0,0 +1,244 @@
+import { FieldValues, UseFormReturn } from 'react-hook-form';
+import { cairoPageCtaClickedParams } from '@wix/bex-utils/@wix/bi-logger-os-data/v2/types';
+import { ReactNode } from 'react';
+
+/** The resolved source: defaults filled, `loadSchema` memoized. */
+/**
+ * `SchemaSource` — cut here because it has its own bundle.
+ * Full shape: `types/SchemaSource.d.ts`.
+ */
+interface SchemaSource<T = any> {
+    [key: string]: unknown;
+}
+
+type ToastType = 'STANDARD' | 'PREMIUM' | 'SUCCESS' | 'WARNING' | 'ERROR';
+type ToastTimeout = 'NONE' | 'NORMAL';
+type ToastPriority = 'LOW' | 'NORMAL' | 'HIGH';
+type ToastActionUiType = 'BUTTON' | 'LINK';
+type ToastAction = {
+    text: string;
+    onClick?: Function;
+    removeToastOnClick?: boolean;
+    uiType?: ToastActionUiType;
+    navigationTarget?: {
+        url: string;
+        openInNewTab?: boolean;
+    };
+};
+type ErrorToastDetails = {
+    requestId: string;
+};
+type ToastConfig = {
+    message: string;
+    biName?: string;
+    timeout?: ToastTimeout;
+    priority?: ToastPriority;
+    type?: ToastType;
+    onCloseClick?: () => unknown;
+    onToastSeen?: () => unknown;
+    action?: ToastAction;
+    details?: ErrorToastDetails;
+};
+
+/**
+ * `WixPatternsContainer` — you receive this, you don't construct it.
+ * Produced by `useWixPatternsContainer()` (also `buildWixPatternsContainer()`, `useCustomFieldsViewWidget()`).
+ */
+declare class WixPatternsContainer {
+    [key: string]: unknown;
+}
+
+type SaveCtaText = 'PUBLISH' | 'APPLY' | 'CONNECT' | 'ACTIVATE' | 'SAVE' | 'SUBMIT';
+interface SaveCtaSecondaryAction {
+    consumerText: string;
+    onClick: () => void;
+    icon?: ReactNode;
+    disabled?: boolean;
+    dataHook?: string;
+}
+interface ActionsBarConfig {
+    saveCta?: {
+        text?: SaveCtaText;
+        consumerText?: string;
+        biAdditionalInfo?: cairoPageCtaClickedParams['additionalInfo'];
+        /** Puts these behind a chevron on the save CTA. Not rendered on mobile, where a split action cannot be full-width. */
+        secondaryActions?: SaveCtaSecondaryAction[];
+    };
+    cancelCta?: {
+        biAdditionalInfo?: cairoPageCtaClickedParams['additionalInfo'];
+    };
+}
+
+/**
+ * `WixPatternsRouterState` — you receive this, you don't construct it.
+ * Produced by `useWixPatternsRouter()`.
+ */
+declare class WixPatternsRouterState {
+    [key: string]: unknown;
+}
+
+type DeleteErrorToast = (err: unknown, params: {
+    retry: () => void;
+}) => {
+    message?: string;
+    tryAgain?: boolean;
+    action?: {
+        text: string;
+        onClick: () => void;
+    };
+} | string;
+interface EntityPageDeleteActionConfig<T> {
+    enabled?: boolean;
+    onDelete?: (entity: T) => Promise<void>;
+    successToast?: Pick<ToastConfig, 'message'> | string;
+    errorToast?: DeleteErrorToast;
+    itemName?: (entity: T) => string;
+}
+type EntityPageDeleteAction<T> = boolean | EntityPageDeleteActionConfig<T>;
+
+/**
+ * `OnSaveParams` — cut here because it has its own bundle.
+ * Full shape: `types/OnSaveParams.d.ts`.
+ */
+type OnSaveParams = Record<string, unknown>;
+interface EntityPageStateParamsBase<T, V extends FieldValues = FieldValues> {
+    /**
+     * A function that fetches the entity data.
+     * @returns a promise that resolves to an object containing the entity.
+     */
+    fetch: () => Promise<{
+        entity: T | undefined;
+    }>;
+    /**
+     * A function to handle the save action.
+     * @returns promise that resolves to an object that contains a 'updatedEntity' object.
+     */
+    onSave: (params: OnSaveParams) => Promise<{
+        updatedEntity: T;
+    }>;
+    /**
+     * An optional object with an optional message, or it can directly get a string message.
+     */
+    saveSuccessToast?: {
+        message?: string;
+    } | string;
+    /**
+     * An optional function to display an error toast message when a save operation fails.
+     * @returns An object with a `message` and an `action` object. Alternatively, it can return an object with an optional `message` and a `tryAgain` flag, or a string message.
+     * The previous return types are still supported but are now deprecated.
+     */
+    saveErrorToast?: (err: unknown, params: {
+        retry: () => void;
+    }) => {
+        message?: string;
+        /**
+         * @deprecated use `action` instead
+         */
+        tryAgain?: boolean;
+        action?: {
+            text: string;
+            onClick: () => void;
+        };
+    } | string;
+    /**
+     * Enables deleting the loaded entity from the entity page. Pass `true` for a
+     * schema-backed page to use the source backend, or an object to customize the
+     * action and to provide a delete handler for manually wired pages.
+     */
+    deleteAction?: EntityPageDeleteAction<T>;
+    /**
+     * An optional function to transform the updated entity data before it is passed to the collection page.
+     * @param entity the updated entity.
+     * @returns an object representing the entity in the collection page.
+     */
+    transformEntityToCollectionItem?: (entity: T) => any;
+    form: UseFormReturn<V>;
+    /**
+     * An object representing the container, possibly for dependency injection or component management.
+     */
+    container: WixPatternsContainer;
+    /**
+     * A string representing the ID of the parent page.
+     * Must be passed if not using Patterns Router
+     */
+    parentPageId?: string;
+    /**
+     * A string representing the path of the parent page.
+     * Must be passed if using Patterns Router
+     */
+    parentPath?: string;
+    /**
+     * Referrer forwarded to the parent page on back, cancel and save, so callers
+     * can carry navigation context across the transition.
+     *
+     * Only used for parentPageId navigations; Patterns Router keeps its context
+     * in router state.
+     *
+     * Forwarded by the BM and Giza providers. Dropped by the dashboard provider,
+     * whose SDK Destination has no referrer field.
+     */
+    parentReferrer?: string;
+    /**
+     * An object representing the router state
+     */
+    routerState?: WixPatternsRouterState | null;
+    /**
+     * An optional object to override the actions bar.
+     */
+    actionsBarConfig?: ActionsBarConfig;
+    /**
+     * Whether the page was opened to create a new entity rather than to edit an
+     * existing one. Decides how a save is announced to the parent page — created
+     * vs updated — so a new item seeded with local defaults is still announced
+     * as created. Pass a getter when the route can change while the page stays
+     * mounted. When omitted, the announcement follows whether an entity was
+     * loaded.
+     */
+    isNewEntity?: boolean | (() => boolean);
+    /**
+     * An optional schema source describing how to load the schema and access
+     * the entity's data. When present, the page can read fields from the source
+     * instead of relying only on hand-wired fetch/onSave callbacks.
+     */
+    schemaSource?: SchemaSource<T>;
+}
+/**
+ * `EntityPageStateParams` — cut here because it has its own bundle.
+ * Full shape: `types/EntityPageStateParams.d.ts`.
+ */
+type EntityPageStateParams<T = any, V = any> = EntityPageStateParamsBase<T, V>;
+/**
+ * `EntityPageState` — you receive this, you don't construct it.
+ * Produced by `useEntityPage()` (also `useEntityPageContext()`). Its own API is in `types/EntityPageState.d.ts`.
+ */
+declare class EntityPageState<T = any, V = any> {
+    [key: string]: unknown;
+}
+
+/**
+ * `UseEntityPageParams` — cut here because it has its own bundle.
+ * Full shape: `types/UseEntityPageParams.d.ts`.
+ */
+type UseEntityPageParams<T = any, V = any> = Pick<EntityPageStateParams<T, V>, 'fetch' | 'onSave' | 'saveSuccessToast' | 'saveErrorToast' | 'deleteAction' | 'transformEntityToCollectionItem' | 'isNewEntity' | 'form' | 'parentPageId' | 'parentPath' | 'parentReferrer' | 'schemaSource'>;
+
+/** Entity page options for a source-driven page: the source loads the schema and
+ *  its backend reads and writes the entity, so `fetch` and `onSave` derive from
+ *  it — pass one only to replace the derived default. */
+type SchemaEntityPageOptions<T, V extends FieldValues = FieldValues> = Omit<UseEntityPageParams<T, V>, 'fetch' | 'onSave' | 'schemaSource' | 'isNewEntity'> & {
+    /** Creates the initial values for a new entity. */
+    createLocalItem?: () => Partial<T>;
+    /** The entity to load. Omitted ⇒ the create route: the page starts empty and
+     *  saving creates an entity. */
+    entityId?: string;
+    /** Replaces the read through the source's backend. */
+    fetch?: UseEntityPageParams<T, V>['fetch'];
+    /** Replaces the write through the source's backend. */
+    onSave?: UseEntityPageParams<T, V>['onSave'];
+};
+/** An entity page driven by a source: the source supplies the schema its fields
+ *  render from, and its backend reads and writes the entity. Render the state
+ *  with the `EntityPage` from this entry — it wires the fields provider. */
+declare function useEntityPage<T, V extends FieldValues = FieldValues>(source: SchemaSource<T>, options: SchemaEntityPageOptions<T, V>): EntityPageState<T, V>;
+
+export { useEntityPage };
+export type { SchemaEntityPageOptions };