@wix/patterns 1.468.0 → 1.469.0

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

@@ -0,0 +1,331 @@
+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;
+    };
+}
+
+type PaginationModeRef = {
+    current: 'offset' | 'cursor' | 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>;
+};
+
+/**
+ * `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 CollectionFactory = <T, F extends FiltersMap = OptionalFiltersMap>(config: CollectionConfigWithConditionals<T, F>) => CollectionState<T, F>;
+declare function usePrivateCreateCollection(): <T, F extends FiltersMap = OptionalFiltersMap>(config: CollectionConfigWithConditionals<T, F>, options?: {
+    paginationModeRef?: PaginationModeRef;
+}) => CollectionState<T, F>;
+declare function useCreateCollection(): CollectionFactory;
+declare function useCollection<T, F extends FiltersMap = OptionalFiltersMap>(config: CollectionConfigWithConditionals<T, F>): CollectionState<T, F>;
+
+export { useCollection, useCreateCollection, usePrivateCreateCollection };
+export type { CollectionFactory };

package/dist/dts-bundle/hooks/useCreateCollection.d.ts

@@ -28,7 +28,7 @@ declare class CollectionState<T = any, F = any> {
 
 /**
  * `OffsetQuery` — cut here because it has its own bundle.
- * Look `OffsetQuery` up in the bundle index for its full shape.
+ * Full shape: `types/OffsetQuery.d.ts`.
  */
 type OffsetQuery<F = any> = Omit<ComputedQuery<F>, 'cursor'>;
 type OffsetQueryResult<T> = Omit<DataResultRaw<T>, 'cursor'>;
@@ -38,7 +38,7 @@ type CursorQueryResult<T> = Omit<DataResultRaw<T>, 'cursor'> & {
 };
 /**
  * `CursorQuery` — cut here because it has its own bundle.
- * Look `CursorQuery` up in the bundle index for its full shape.
+ * 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>>;
@@ -54,7 +54,7 @@ type PaginationModeConfig<T, F extends FiltersMap> = {
 
 /**
  * `Filter` — cut here because it has its own bundle.
- * Look `Filter` up in the bundle index for its full shape.
+ * Full shape: `types/Filter.d.ts`.
  */
 interface Filter<T = any> {
     [key: string]: unknown;
@@ -68,7 +68,7 @@ type OptionalFiltersMap = {
 
 /**
  * `ComputedQuery` — cut here because it has its own bundle.
- * Look `ComputedQuery` up in the bundle index for its full shape.
+ * Full shape: `types/ComputedQuery.d.ts`.
  */
 interface ComputedQuery<F = any> {
     [key: string]: unknown;
@@ -76,7 +76,7 @@ interface ComputedQuery<F = any> {
 
 /**
  * `DataResultRaw` — cut here because it has its own bundle.
- * Look `DataResultRaw` up in the bundle index for its full shape.
+ * Full shape: `types/DataResultRaw.d.ts`.
  */
 interface DataResultRaw<T = any> {
     [key: string]: unknown;

package/dist/dts-bundle/hooks/useEntity.d.ts

@@ -2,7 +2,7 @@ import { FieldValues } from 'react-hook-form';
 
 /**
  * `EntityPageState` — you receive this, you don't construct it.
- * Produced by `useEntityPage()` (also `useEntityPageContext()`). Look `EntityPageState` up in the bundle index for its own API.
+ * Produced by `useEntityPage()` (also `useEntityPageContext()`). Its own API is in `types/EntityPageState.d.ts`.
  */
 declare class EntityPageState<T = any, V = any> {
     [key: string]: unknown;