@wix/patterns 1.475.0 → 1.477.0

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

@@ -0,0 +1,422 @@
+import { IterateeShorthand } from 'lodash';
+
+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;
+    };
+}
+
+/**
+ * `QueryState` — you receive this, you don't construct it.
+ * An internal state object — reached through another state object, never built directly.
+ */
+declare class QueryState<F = any> {
+    [key: string]: unknown;
+}
+
+type Iterator<T> = (value: T, index: number) => unknown;
+interface Order<T> {
+    fieldName: Iterator<T> | IterateeShorthand<T>;
+    order: 'asc' | 'desc';
+}
+
+/**
+ * `CollectionOptimisticSequenceExecutor` — you receive this, you don't construct it.
+ * An internal state object — reached through another state object, never built directly.
+ */
+declare class CollectionOptimisticSequenceExecutor {
+    [key: string]: unknown;
+}
+
+interface CollectionOptimisticActionsBaseParams<T, F extends FiltersMap> {
+    /**
+     * A function that simulates the filtering in the server.
+     * The function should return another function that accepts an item, and return a boolean that indicates whether the item passes the query filters or not.
+     * @param computedQuery - The computed query object.
+     * @external
+     */
+    readonly predicate?: (computedQuery: ComputedQuery<F>) => (item: T) => boolean;
+    /**
+     * A function that simulates the ordering of the items in the server.<br>
+     * The function should return a list of rules in the form of `{fieldName: string; order: 'asc' | 'desc';}` to order the items by
+     * @param computedQuery - The computed query object.
+     * @external
+     */
+    readonly orderBy?: (computedQuery: ComputedQuery<F>) => Order<T>[];
+    /**
+     * A function to retrieve the creation date of an item.
+     * @param item - The item.
+     * @external
+     */
+    readonly createdAt?: (item: T) => Date;
+    /**
+     * Time to wait before batching multiple `updateMany` calls into a single server call.
+     * @default 0
+     * @external
+     */
+    readonly batchWait?: number;
+    /**
+     * Indicates whether to refresh the current page without invalidating the cache.
+     * @external
+     */
+    readonly noInvalidate?: boolean;
+    /**
+     * Adds a namespace to the cache key.
+     * @external
+     */
+    readonly cacheNamespace?: string;
+    readonly sequences?: Map<string, CollectionOptimisticSequenceExecutor>;
+    readonly query?: QueryState<F>;
+}
+
+/**
+ * `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>;
+
+/**
+ * `CellType` — cut here because it has its own bundle.
+ * Full shape: `types/CellType.d.ts`.
+ */
+interface CellType {
+    [key: string]: unknown;
+}
+
+/**
+ * `EditableTableState` — you receive this, you don't construct it.
+ * Produced by `useEditableTableCollection()`.
+ */
+declare class EditableTableState<T = any, F = any> {
+    [key: string]: unknown;
+}
+
+type FetchData<T> = (query: OffsetQuery) => Promise<OffsetQueryResult<T>>;
+type SchemaItemCreationOptions<T> = {
+    /** Creates the initial values for a newly added item. */
+    createLocalItem?: () => Partial<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>;
+};
+type SchemaMutableCollectionOptions<T, F extends FiltersMap> = SchemaCollectionOptions<T, F> & SchemaItemCreationOptions<T>;
+
+type SchemaEditableTableCollectionOptions<T, F extends FiltersMap = OptionalFiltersMap> = SchemaMutableCollectionOptions<T, F> & {
+    optimisticActionParams?: Partial<CollectionOptimisticActionsBaseParams<T, F>>;
+    /** Additional cell types to register alongside the built-in ones. */
+    extraCellTypes?: CellType[];
+};
+/** An editable-table collection driven by a source: query config, columns,
+ *  field management, and row writes all come from the source. */
+declare function useEditableTableCollection<T, F extends FiltersMap = OptionalFiltersMap>(source: SchemaSource<T>, options?: SchemaEditableTableCollectionOptions<T, F>): EditableTableState<T, F>;
+
+export { useEditableTableCollection };
+export type { SchemaEditableTableCollectionOptions };