@wix/patterns 1.476.0 → 1.477.0

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

@@ -0,0 +1,414 @@
+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;
+    };
+}
+
+/**
+ * `CollectionOptimisticActions` — you receive this, you don't construct it.
+ * Produced by `useOptimisticActions()` (also `createNestedOptimisticActions()`, `useCreateNestedOptimisticActions()`, `useCreateOptimisticActions()`). Its own API is in `components/CollectionOptimisticActions.d.ts`.
+ */
+declare class CollectionOptimisticActions<T = any, F = any> {
+    [key: string]: unknown;
+}
+
+/**
+ * `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 per-item delete verdict. */
+interface RemoveItemDisabledResult {
+    disabled: boolean;
+    /** Why the item cannot be deleted — surfaced to the user by consumers. */
+    reason?: string;
+}
+/**
+ * Metadata for an item update. `changedFieldIds` narrows follow-up comparison
+ * work to fields the UI already knows were edited, which avoids diffing every
+ * value when some fields are large or expensive to compare.
+ */
+interface CollectionUpdateContext<T = Record<string, unknown>> {
+    previousItem: T;
+    changedFieldIds: string[];
+}
+
+/** 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>;
+
+interface EditableTableMutationHandlers<T> {
+    /** Factory to create a new empty item with a fresh ID */
+    createItem: () => T;
+    /** Submit updated items to the server */
+    submitUpdate: (items: T[], contexts?: CollectionUpdateContext<T>[]) => Promise<T[] | void>;
+    /** Submit newly created items to the server */
+    submitCreate: (items: T[]) => Promise<T[] | void>;
+    /** Submit item deletions to the server */
+    submitDelete: (items: T[]) => Promise<void>;
+}
+
+interface EditableTablePermissions<T = unknown> {
+    addItemDisabled?: boolean;
+    updateItemDisabled?: boolean;
+    removeItemDisabled?: boolean;
+    /** Deleting several rows in one operation. Absent = follows `removeItemDisabled`. */
+    multiDeleteDisabled?: boolean;
+    /** Per-item refinement of `removeItemDisabled`: disables deleting an item
+     *  even though deleting is generally allowed, optionally with a reason.
+     *  Must be pure and synchronous. Absent = all items deletable. */
+    isRemoveItemDisabled?: (item: T) => RemoveItemDisabledResult;
+}
+
+interface TableLayoutConfig {
+}
+interface GridLayoutConfig {
+}
+interface SpreadsheetLayoutConfig<T, F extends FiltersMap> {
+    mutations: EditableTableMutationHandlers<T>;
+    permissions?: EditableTablePermissions<T>;
+    createOptimisticActions: (collection: CollectionState<T, F>) => CollectionOptimisticActions<T, F>;
+}
+/**
+ * `LayoutSwitchState` — you receive this, you don't construct it.
+ * Produced by `useLayoutSwitchCollection()`.
+ */
+declare class LayoutSwitchState<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 SchemaLayoutSwitchCollectionOptions<T, F extends FiltersMap = OptionalFiltersMap> = SchemaMutableCollectionOptions<T, F> & {
+    table?: TableLayoutConfig;
+    grid?: GridLayoutConfig;
+    spreadsheet?: Omit<SpreadsheetLayoutConfig<T, F>, 'createOptimisticActions' | 'mutations' | 'permissions'>;
+};
+/** One collection and one toolbar driven by a source, shared by every enabled
+ *  layout — the source attaches before any layout mounts, so a page opening
+ *  in grid view has its fields and filters too. */
+declare function useLayoutSwitchCollection<T, F extends FiltersMap = OptionalFiltersMap>(source: SchemaSource<T>, options?: SchemaLayoutSwitchCollectionOptions<T, F>): LayoutSwitchState<T, F>;
+
+export { useLayoutSwitchCollection };
+export type { SchemaLayoutSwitchCollectionOptions };

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

@@ -0,0 +1,59 @@
+import { PatternsFieldsAppContainer } from '@wix/patterns-fields/providers';
+
+/** What a caller passes. Only `collectionId` and `loadSchema` are required. */
+/**
+ * `SchemaSourceInput` — cut here because it has its own bundle.
+ * Full shape: `types/SchemaSourceInput.d.ts`.
+ */
+interface SchemaSourceInput<T = any> {
+    [key: string]: unknown;
+}
+/** 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;
+}
+
+/**
+ * `WixPatternsContainer` — you receive this, you don't construct it.
+ * Produced by `useWixPatternsContainer()` (also `buildWixPatternsContainer()`, `useCustomFieldsViewWidget()`).
+ */
+declare class WixPatternsContainer {
+    [key: string]: unknown;
+}
+
+/**
+ * A source carrying the container its field renderers are built with. Attached
+ * by `useSchemaSource` from `@wix/patterns/schema`, so every state and component
+ * working off one schema shares one container — `SchemaSource` itself lives in
+ * core, which can't name the type.
+ */
+interface SchemaSourceWithFields {
+    readonly fieldsContainer?: PatternsFieldsAppContainer;
+}
+
+/** A resolved source plus the container its field renderers are built with. */
+type FieldsSchemaSource<T> = SchemaSource<T> & Required<SchemaSourceWithFields>;
+/**
+ * Attaches the container the source's field renderers are built with. Used by
+ * `useSchemaSource` below, and by tests building a source through the core
+ * testkit — core can't attach it, so anything constructing a source outside this
+ * package has to.
+ */
+declare function attachFieldsContainer<T>(source: SchemaSource<T>, patternsContainer: WixPatternsContainer): FieldsSchemaSource<T>;
+/**
+ * `defineSchemaSource` with the fields container attached — the source is where
+ * it belongs, so a page and a table on the same schema share one container
+ * instead of each building its own. Core defines the source but can't reference
+ * `@wix/patterns-fields`, hence this layer.
+ *
+ * The states initialize it from their own `init()`; `SchemaFieldsProvider` puts
+ * it in React context for the field renderers.
+ */
+declare function useSchemaSource<T>(input: SchemaSourceInput<T>): FieldsSchemaSource<T>;
+
+export { attachFieldsContainer, useSchemaSource };
+export type { FieldsSchemaSource };