@wix/patterns 1.475.0 → 1.477.0

package/dist/dts-bundle/components/schema/Grid.d.ts

@@ -0,0 +1,467 @@
+import * as React from 'react';
+import React__default, { ReactNode, Ref, JSXElementConstructor, ReactElement } from 'react';
+import { CardGalleryItemProps, MessageModalLayoutProps, IconElement, AddItemProps } from '@wix/design-system';
+import { ReportProps } from '@wix/fe-essentials/bi';
+import { ClientRect } from '@wix/wix-style-react-incubator/dnd-kit/core';
+
+type ReportBI = (reportProps: ReportProps) => void;
+
+/**
+ * `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;
+}
+
+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;
+};
+
+/**
+ * `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;
+}
+
+interface KeyedItem<T> {
+    item: T;
+    key: string;
+    id: string;
+    pageIndex: number;
+    indexWithinPage: number;
+    index: number;
+}
+
+type SupportedCardGalleryItemProps = Pick<CardGalleryItemProps, 'badge' | 'title' | 'subtitle' | 'suffix' | 'backgroundImageUrl' | 'backgroundImageNode' | 'primaryActionProps' | 'secondaryActionProps' | 'showSuffixOnHover' | 'settingsMenu'>;
+
+type RenderItemRawProps = Omit<Partial<SupportedCardGalleryItemProps>, 'title' | 'subtitle>'>;
+type GridPresetFullProps<T, P> = P & {
+    preset: 'full';
+    renderItem?: (item: T, index: number) => RenderItemRawProps & {
+        title?: React__default.ReactNode;
+        subtitle?: React__default.ReactNode;
+    };
+};
+type GridPresetFooterProps<T, P> = P & {
+    preset: 'footer';
+    renderItem?: (item: T, index: number) => RenderItemRawProps & {
+        title?: React__default.ReactNode;
+        subtitle?: React__default.ReactNode;
+    };
+};
+type GridPresetTitleProps<T, P> = P & {
+    preset?: 'title';
+    renderItem?: (item: T, index: number) => RenderItemRawProps & {
+        title?: React__default.ReactNode;
+        subtitle?: undefined;
+    };
+};
+type GridPresetEmptyProps<T, P> = P & {
+    preset: 'empty';
+    renderItem?: (item: T, index: number) => RenderItemRawProps & {
+        title?: undefined;
+        subtitle?: undefined;
+    };
+};
+type Preset = 'full' | 'footer' | 'title' | 'empty';
+type GridPresetGenericProps<T, P> = P & {
+    preset?: Preset;
+    renderItem?: (item: T, index: number) => RenderItemRawProps & {
+        title?: React__default.ReactNode;
+        subtitle?: React__default.ReactNode;
+    };
+};
+type GridPresetProps<T, P> = GridPresetFullProps<T, P> | GridPresetTitleProps<T, P> | GridPresetEmptyProps<T, P> | GridPresetGenericProps<T, P> | GridPresetFooterProps<T, P>;
+
+interface ActionCellAPI$1<T, F extends FiltersMap> {
+    openConfirmModal: (props?: Partial<MessageModalLayoutProps>) => void;
+    openConfirmDeleteModal: (props?: Partial<MessageModalLayoutProps>) => void;
+    collection: CollectionState<T, F>;
+    keyedItem: KeyedItem<T>;
+}
+
+interface CtaBaseProps {
+    /**
+     * A unique identifier for the CTA.
+     * @external
+     */
+    id: string;
+    /**
+     * A callback that runs each time the button is clicked.
+     * @external
+     */
+    onClick?: () => void;
+    /**
+     * Button label.
+     * @external
+     */
+    label?: string;
+    /**
+     * An optional Icon prefix.
+     * @external
+     */
+    prefixIcon?: IconElement;
+}
+
+interface SectionBadgeConfig {
+    visible: boolean;
+    skin?: 'light' | 'danger' | 'neutralLight';
+}
+/**
+ * A summary item to display in the section header.
+ * @external
+ */
+interface SectionSummaryItem {
+    /**
+     * An icon to display before the text.
+     * @external
+     */
+    icon: ReactNode;
+    /**
+     * A label for the summary item.
+     * @external
+     */
+    text: string;
+    /**
+     * A count value for the summary item.
+     * @external
+     */
+    count: number;
+}
+interface Section {
+    /**
+     * A title for the section.
+     * @external
+     */
+    title: string;
+    /**
+     * A primary call to action for the section.
+     * @overrideType [CtaBaseProps](./?path=/story/common-types--ctabaseprops)
+     * @external
+     */
+    primaryAction?: CtaBaseProps;
+    /**
+     * A badge for the section. Configuration object for showing item count.
+     * @external
+     */
+    badge?: SectionBadgeConfig;
+    /**
+     * Summary items to display in the section header.
+     * Each item can have an icon, text label, and count.
+     * @external
+     */
+    summary?: SectionSummaryItem[];
+    /**
+     * Whether the section is collapsed.
+     * When true, the section items are hidden.
+     * @external
+     */
+    collapsed?: boolean;
+}
+/**
+ * A function that extracts the grouping key from an item.
+ * @external
+ */
+type GroupBy<T> = (item: T) => string;
+/**
+ * A function that renders section configuration given the section ID and all items in the section.
+ * @external
+ */
+type RenderSection<T> = (sectionId: string, items: T[]) => Section;
+
+interface DragAndDropParentState<T, F extends FiltersMap> {
+    readonly reportBi: ReportBI;
+    readonly dragAndDropCategories?: (keyof F)[][] | null | undefined;
+    forceRenderIndexes: undefined | number[];
+    readonly containerRect?: ClientRect;
+    readonly _dnd?: DragAndDropState<T, F> | null;
+}
+/**
+ * `DragAndDropState` — you receive this, you don't construct it.
+ * An internal state object — reached through another state object, never built directly.
+ */
+declare class DragAndDropState<T = any, F = any> {
+    [key: string]: unknown;
+}
+
+type CollectionDragAndDropParentState<T, F extends FiltersMap> = DragAndDropParentState<T, F> & {
+    collection: CollectionState<T, F>;
+    getCollectionSnapshot?: () => {
+        [key: string]: string | number | undefined;
+    };
+};
+
+interface IndexedItem<T> {
+    id: string;
+    item: T;
+    index: number;
+}
+interface CollectionDragEndEvent<T, F extends FiltersMap> {
+    from: IndexedItem<T>;
+    after: IndexedItem<T> | null;
+    over: IndexedItem<T>;
+    filters: ComputedQuery<F>['filters'];
+}
+type DragAndDropSubmit<T, F extends FiltersMap> = (event: CollectionDragEndEvent<T, F>) => Promise<unknown>;
+type DragAndDropCancelResult = Omit<ToastConfig, 'type' | 'biName'> | boolean | null | undefined | void;
+type DragAndDropCancel<T, F extends FiltersMap> = (event: CollectionDragEndEvent<T, F>) => DragAndDropCancelResult | Promise<DragAndDropCancelResult>;
+interface GridCardItemProps {
+    index: number;
+    rowIndex?: number;
+    columnIndex?: number;
+    droppable?: boolean;
+    draggable?: boolean;
+    dragging?: boolean;
+    dragHandleProps?: React__default.HTMLAttributes<HTMLDivElement> & {
+        domRef?: Ref<HTMLDivElement>;
+    };
+    domRef?: (node: HTMLDivElement | null) => void;
+}
+type GridCardItem = React__default.ReactElement<GridCardItemProps, JSXElementConstructor<GridCardItemProps>>;
+interface DraggableCardProps<T, F extends FiltersMap> {
+    state: CollectionDragAndDropParentState<T, F>;
+    index: number;
+    id: string;
+    isOverlay?: boolean;
+    dndDisabled?: boolean;
+    children: GridCardItem;
+}
+interface DraggableCardOverlayProps<T, F extends FiltersMap> {
+    state: CollectionDragAndDropParentState<T, F>;
+    renderItem: (index: number) => ReactElement | null;
+}
+
+type ActionCellAPI<T, F extends FiltersMap> = ActionCellAPI$1<T, F>;
+/**
+ * `ActionCellProps` — cut here because it has its own bundle.
+ * Full shape: `types/ActionCellProps.d.ts`.
+ */
+interface ActionCellProps {
+    [key: string]: unknown;
+}
+/**
+ * `ActionCell` — cut here because it has its own bundle.
+ * Full shape: `types/ActionCell.d.ts`.
+ */
+type ActionCell<T = any, F = any> = ActionCellProps | ((item: T, index: number, api: ActionCellAPI<T, F>) => ActionCellProps);
+
+type BulkActionToolbarRenderProp<T, F extends FiltersMap> = (props: {
+    selectedValues: T[];
+    uncheckedValues: T[];
+    allSelected: boolean;
+    openModal: () => void;
+    clearSelection: () => void;
+    total: number;
+    openConfirmModal: (props?: Partial<MessageModalLayoutProps>) => void;
+    query: ComputedQuery<F>;
+}) => ReactElement;
+
+/**
+ * `ToolbarCollectionBaseProps` — cut here because it has its own bundle.
+ * Full shape: `types/ToolbarCollectionBaseProps.d.ts`.
+ */
+interface ToolbarCollectionBaseProps<T = any, F = any> {
+    [key: string]: unknown;
+}
+
+interface GridSortableContextProps<T, F extends FiltersMap> {
+    state: GridBaseState<T, F>;
+    children?: ReactNode;
+    onSubmit?: DragAndDropSubmit<T, F>;
+}
+
+declare function setStateObject<T, F extends FiltersMap>({ state, modalsContainerRef, }: {
+    state: GridBaseState<T, F>;
+    modalsContainerRef: {
+        current: HTMLElement | null | undefined;
+    };
+}): void;
+declare const GridDragAndDrop: {
+    SortableContext: (<T, F extends FiltersMap>(props: GridSortableContextProps<T, F>) => React.JSX.Element) & {
+        displayName: string;
+    };
+    DraggableCard: (<T, F extends FiltersMap>(props: DraggableCardProps<T, F>) => React.JSX.Element) & {
+        displayName: string;
+    };
+    DraggableCardOverlay: (<T, F extends FiltersMap>(props: DraggableCardOverlayProps<T, F>) => React.ReactPortal) & {
+        displayName: string;
+    };
+    setStateObject: typeof setStateObject;
+};
+
+interface GridContentBaseProps<T, F extends FiltersMap> {
+    preset?: Preset;
+    imagePlacement?: 'side' | 'top';
+    renderItem?: (item: T, index: number) => Partial<SupportedCardGalleryItemProps>;
+    actionCell?: ActionCell<T, F>;
+    renderAddItem?: () => ReactElement<AddItemProps>;
+    dragAndDrop?: typeof GridDragAndDrop;
+    dragAndDropSubmit?: DragAndDropSubmit<T, F>;
+    dragAndDropCancel?: DragAndDropCancel<T, F>;
+    layoutType?: LayoutType;
+}
+
+interface GridSectionsContentProps<T, F extends FiltersMap> extends GridContentBaseProps<T, F> {
+    state: GridState<T, F>;
+    groupBy: GroupBy<T>;
+    renderSection?: RenderSection<T>;
+}
+declare function _GridSectionsContent<T, F extends FiltersMap>(props: GridSectionsContentProps<T, F>): React__default.JSX.Element;
+declare const GridSectionsContent: typeof _GridSectionsContent & {
+    displayName: string;
+};
+
+interface GridItemBaseProps<T, F extends FiltersMap> {
+    /**
+     * A `CardGalleryItem` preset to preserve the same card size regardless of the provided data.
+     * Subtitle will be shown only in 'full' or 'footer' presets.
+     *
+     * @example
+     * full — renders title + subtitle
+     * title — renders only title
+     * empty — renders a card without a footer
+     *
+     * @default title
+     * @external
+     */
+    preset?: Preset;
+    /**
+     * A function that renders a custom item of the grid.
+     * Returns a WSR [`CardGalleryItemProps`](https://www.docs.wixdesignsystem.com/?path=/story/components-lists--cardgalleryitem) object.
+     * @external
+     */
+    renderItem?: (item: T, index: number) => Partial<SupportedCardGalleryItemProps>;
+    /**
+     * Adds an action on the grid item. For example, a delete button to delete an item.
+     * Accepts an [`ActionCellProps`](https://www.docs.wixdesignsystem.com/?path=/story/components-lists-table--tableactioncell) object, or a function that returns an `ActionCellProps` object.
+     * @external
+     */
+    actionCell?: ActionCell<T, F>;
+    /**
+     * A function that renders [`<AddItem>`](https://www.docs.wixdesignsystem.com/?path=/story/components-actions--additem&activeTab=Description&globals=backgrounds.value:!hex(F8F8F8);backgrounds.grid:false) after all cards in a gallery.
+     * <br><br>
+     * The `<AddItem>` card will not show when filters are applied unless the filter is defined with the persistent option.
+     * @external
+     */
+    renderAddItem?: () => ReactElement<AddItemProps>;
+    /**
+     * Sets placement of a background image.
+     * @external
+     */
+    imagePlacement?: CardGalleryItemProps['imagePlacement'];
+}
+
+type LayoutType = 'grid' | 'list';
+/**
+ * `GridBaseState` — you receive this, you don't construct it.
+ * An internal state object — reached through another state object, never built directly.
+ */
+declare class GridBaseState<T = any, F = any> {
+    [key: string]: unknown;
+}
+
+/**
+ * `GridState` — you receive this, you don't construct it.
+ * Produced by `useGridCollection()` (also `useAmbassadorGrid()`, `useVirtualGridStateContext()`). Its own API is in `types/GridState.d.ts`.
+ */
+declare class GridState<T = any, F = any> {
+    [key: string]: unknown;
+}
+
+interface GridBaseProps<T, F extends FiltersMap> extends Omit<ToolbarCollectionBaseProps<T, F>, 'sticky' | 'maxSelection'>, GridItemBaseProps<T, F> {
+    dataHook?: string;
+    /**
+     * Adds functionality to allow visitors to reorder items manually.
+     * For more information, see the [Drag and Drop Overview](./?path=/story/features-sort-drag-and-drop--overview).
+     * @overrideType [GridDragAndDrop](./?path=/story/features-sort-drag-and-drop--griddraganddrop)
+     * @external
+     */
+    dragAndDrop?: typeof GridDragAndDrop;
+    /**
+     * Grid state instance created using [`useGridCollection`](./?path=/story/base-components-collections-grid-usegridcollection--usegridcollection).
+     * @overrideType [GridState](./?path=/story/base-components-collections-grid-gridstate--gridstate)
+     * @external
+     */
+    state: GridState<T, F>;
+    /**
+     * A toolbar for performing bulk actions on multiple items.<br> <br>
+     * Supported parameters: <br>
+     * -`selectedValues`: [array] Items that are checked in the selection column. <br>
+     * -`uncheckedValues`: [array] Items that are unchecked in the selection column. <br>
+     * -`isSelectAll`: [bool] Whether **Select All** is checked. <br>
+     * -`openModal`: [func] Opens a modal that contains the component from `bulkActionModal` render prop. <br>
+     * -`clearSelection`: [func] Clears all selections. Call this after the action on the selected items finishes. <br>
+     * -`total`: [number] Total number of items in the server. <br>
+     * -`openConfirmModal`: [func] Opens a `<MessageModalLayout>` to confirm an action is about to be applied to the selected items. <br>
+     * -`query`: [object] Current paging, sorting, and filtering. Often used together with bulk actions, such as `updateAll`. <br>
+     * @external
+     */
+    bulkActionToolbar?: BulkActionToolbarRenderProp<T, F>;
+    /**
+     * Creates [grid sections](./?path=/story/features-display-grid-sections--grid-sections) that group data based on the values of a specific field.
+     * @external
+     * @overrideType [SectionsProp](./?path=/story/common-types--sectionsprop)
+     */
+    sections?: {
+        GridSections: typeof GridSectionsContent;
+        groupBy: GroupBy<T>;
+        renderSection?: RenderSection<T>;
+    };
+    layoutType?: LayoutType;
+}
+type GridBasePropsWithoutPreset<T, F extends FiltersMap = OptionalFiltersMap> = Omit<GridBaseProps<T, F>, 'preset' | 'renderItem'>;
+type GridProps<T, F extends FiltersMap = OptionalFiltersMap> = GridPresetProps<T, GridBasePropsWithoutPreset<T, F>>;
+
+/** A grid driven by a source: the card title comes from the source's display
+ *  value, so `renderItem` sets only the rest of the card (subtitle, image,
+ *  badge, …). Field-type icons are always on, and not configurable. */
+type SchemaGridProps<T, F extends FiltersMap> = Omit<GridProps<T, F>, 'showFieldTypeIcons' | 'renderItem'> & {
+    renderItem?: (item: T, index: number) => Omit<Partial<SupportedCardGalleryItemProps>, 'title'>;
+};
+declare function _Grid<T, F extends FiltersMap>(props: SchemaGridProps<T, F>): React__default.JSX.Element;
+declare const Grid: typeof _Grid;
+
+export { Grid };
+export type { SchemaGridProps };