@wix/patterns 1.475.0 → 1.477.0

package/dist/dts-bundle/components/EditableTable.d.ts

@@ -0,0 +1,551 @@
+import React, { ReactNode, CSSProperties, ComponentType } from 'react';
+import { IconElement, TableColumn as TableColumn$1 } from '@wix/design-system';
+import { AtlasService, RichTextStyleVariables } from '@wix/patterns-fields';
+
+/**
+ * `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 PatternsFieldType = 'SHORT_TEXT' | 'LONG_TEXT' | 'NUMBER' | 'BOOLEAN' | 'DATE' | 'DATETIME' | 'TIME' | 'URL' | 'ARRAY' | 'REFERENCE' | 'MULTI_REFERENCE' | 'OBJECT' | 'IMAGE' | 'VIDEO' | 'MEDIA_GALLERY' | 'ADDRESS' | 'RICH_TEXT' | 'DOCUMENT' | 'RICH_CONTENT' | 'MULTI_DOCUMENT' | 'EMAIL' | 'AUDIO' | 'COLOR' | 'CUSTOM' | 'UNKNOWN';
+type QueryOperator = 'CONTAINS' | 'ENDS_WITH' | 'EQ' | 'EXISTS' | 'GT' | 'GTE' | 'HAS_ALL' | 'HAS_SOME' | 'LT' | 'LTE' | 'NE' | 'STARTS_WITH' | 'URLIZED';
+interface NumberRange {
+    min?: number;
+    max?: number;
+}
+interface StringLengthRange {
+    minLength?: number;
+    maxLength?: number;
+}
+interface SpecificValue {
+    id: string;
+    value: string;
+}
+interface BaseField {
+    id: string;
+    displayName: string;
+    isPii?: boolean;
+    helpText?: string;
+    /** Whether this is a system-managed field (not user-created). */
+    isSystem?: boolean;
+    /** The group this field belongs to, when the source groups its fields.
+     *  Absent ⇒ ungrouped. */
+    group?: string;
+    /** Whether this is the collection's primary display field. */
+    isPrimary?: boolean;
+    validation?: {
+        numberRange?: NumberRange;
+        stringLengthRange?: StringLengthRange;
+        specificValues?: SpecificValue[];
+        /** Regular expression source the value must match. Applies to text-like
+         *  fields only; mutually exclusive with `specificValues`. */
+        pattern?: string;
+        required: boolean;
+    };
+    capabilities?: {
+        supportedQueryOperators: QueryOperator[];
+        sortable: boolean;
+    };
+}
+interface BaseReferenceField extends BaseField {
+    referenceMetadata: {
+        referencedCollectionId: string;
+    };
+}
+interface ReferenceField extends BaseReferenceField {
+    type: 'REFERENCE';
+}
+interface MultiReferenceField extends BaseReferenceField {
+    type: 'MULTI_REFERENCE';
+}
+interface NonReferenceField extends BaseField {
+    type: Exclude<PatternsFieldType, 'REFERENCE' | 'MULTI_REFERENCE'>;
+    /** Present iff `type` is 'CUSTOM'; keys a field type definition registered on the source. */
+    customType?: string;
+}
+type Field = ReferenceField | MultiReferenceField | NonReferenceField;
+
+type ValidationRule = {
+    type: 'required';
+    message: string;
+} | {
+    type: 'min' | 'max';
+    value: number;
+    message: string;
+} | {
+    type: 'minLength' | 'maxLength';
+    value: number;
+    message: string;
+} | {
+    type: 'pattern';
+    value: RegExp;
+    message: string;
+} | {
+    type: 'custom';
+    validate: (value: unknown) => boolean;
+    message: string;
+} | {
+    type: 'specificValues';
+    values: {
+        id: string;
+        value: string;
+    }[];
+    message: string;
+};
+
+/**
+ * `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;
+};
+
+type SortOrder = 'asc' | 'desc';
+type SortOrderWithNone = SortOrder | undefined;
+/**
+ * @deprecated always option is deprecated
+ */
+type SortModeDeprecated = 'always';
+type SortMode = SortModeDeprecated | SortOrderWithNone[];
+
+/**
+ * `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;
+}
+
+/**
+ * Canonical field type keys (UPPER_SNAKE_CASE).
+ * The map is keyed by these values; incoming camelCase strings
+ * are normalised before lookup.
+ */
+type FieldType = 'SHORT_TEXT' | 'LONG_TEXT' | 'NUMBER' | 'BOOLEAN' | 'DATE' | 'DATE_TIME' | 'DATETIME' | 'TIME' | 'URL' | 'EMAIL' | 'IMAGE' | 'MEDIA_GALLERY' | 'AUDIO' | 'DOCUMENT' | 'MULTI_DOCUMENT' | 'RICH_TEXT' | 'RICH_CONTENT' | 'REFERENCE' | 'MULTI_REFERENCE' | 'OBJECT' | 'ARRAY' | 'ADDRESS' | 'COLOR' | 'INTEGER' | 'DECIMAL' | 'CHECKBOX' | 'DROPDOWN' | 'FILES' | 'MULTI_SELECT';
+
+interface ReferenceItem {
+    id: string;
+    name: string;
+    image?: string;
+}
+type RefFieldType = 'IMAGE';
+interface RefSchemaField {
+    type: RefFieldType;
+}
+interface RefSchema {
+    id: string;
+    /** The id of the referenced collection, used to navigate to it from the cell editor. */
+    collectionId?: string;
+    displayField: string;
+    idField: string;
+    fields?: Record<string, RefSchemaField | undefined>;
+}
+interface ReferenceTypeConfig {
+    refSchema: RefSchema;
+    fetchReferenceItems: (query: ComputedQuery) => Promise<{
+        items: ReferenceItem[];
+        total: number;
+    }>;
+    renderFooter?: () => React.ReactNode;
+}
+
+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;
+/**
+ * Event callbacks for section interactions.
+ * @external
+ */
+interface SectionEvents {
+    /**
+     * Called when a section is toggled (collapsed/expanded).
+     * @param sectionId - The ID of the section being toggled
+     * @param isCollapsed - Whether the section is now collapsed
+     * @external
+     */
+    onToggle?: (sectionId: string, isCollapsed: boolean) => void;
+}
+
+interface TableSectionsProps<T, F extends FiltersMap> extends CollectionTableBaseProps<T, F> {
+    groupBy: GroupBy<T>;
+    renderSection: RenderSection<T>;
+    table: TableState<T, F>;
+    collapsible?: boolean;
+    events?: SectionEvents;
+}
+declare const TableSections: (<T, F extends FiltersMap>({ groupBy, renderSection, table, columns, rowDetails, collapsible, events, ...collectionTableProps }: TableSectionsProps<T, F>) => React.JSX.Element) & {
+    displayName: string;
+};
+type TableSectionsProp<T> = {
+    TableSections: typeof TableSections;
+    groupBy: GroupBy<T>;
+    renderSection: RenderSection<T>;
+    collapsible?: boolean;
+    events?: SectionEvents;
+};
+
+interface TableVirtualProps<T, F extends FiltersMap> extends CollectionTableBaseProps<T, F> {
+    rowHeight?: number | ((item: T, index: number) => number);
+    estimatedRowHeight?: number;
+    state: CollectionState<T, F> | TableState<T, F>;
+    sections?: TableSectionsProp<T>;
+}
+
+/**
+ * `ToolbarCollectionState` — you receive this, you don't construct it.
+ * Produced by `useToolbarCollectionContext()` (also `useTableCollectionSyncProps()`, `useKanbanCollectionSyncProps()`, `useToolbarCollectionSyncProps()`).
+ */
+declare class ToolbarCollectionState<T = any, F = any> {
+    [key: string]: unknown;
+}
+
+/**
+ * `TableState` — you receive this, you don't construct it.
+ * Produced by `useTableCollection()` (also `useAmbassadorTable()`, `useTableContext()`). Its own API is in `types/TableState.d.ts`.
+ */
+declare class TableState<T = any, F = any> {
+    [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;
+}
+
+interface AddressCellTypeConfig {
+    /**
+     * Atlas service used to fetch address suggestions. Defaults to the SDK-backed
+     * WixAtlasService, which requires Wix runtime/auth context. Inject a custom
+     * implementation for tests or non-Wix consumers.
+     */
+    atlasService?: AtlasService;
+}
+
+interface RichTextCellTypeConfig {
+    textStyle?: RichTextStyleVariables;
+}
+/**
+ * `CellType` — cut here because it has its own bundle.
+ * Full shape: `types/CellType.d.ts`.
+ */
+interface CellType {
+    [key: string]: unknown;
+}
+interface CellTypeConfigMap {
+    text: never;
+    number: never;
+    boolean: never;
+    url: never;
+    email: never;
+    color: never;
+    date: never;
+    time: never;
+    datetime: never;
+    object: never;
+    array: never;
+    image: never;
+    document: never;
+    multiDocument: never;
+    richContent: never;
+    video: never;
+    audio: never;
+    richText: RichTextCellTypeConfig;
+    mediaGallery: never;
+    reference: ReferenceTypeConfig;
+    multiReference: ReferenceTypeConfig;
+    address: AddressCellTypeConfig;
+    /** An inline custom cell: the full cell contract minus the registry key.
+     *  Authorable directly on a column (`cellType: 'custom'` + `typeConfig`),
+     *  and also produced by the column builder when a schema field's type
+     *  definition (registered via the source's `fieldTypes`) has an
+     *  `editableTable` slot. */
+    custom: Omit<CellType, 'type'>;
+}
+interface EditableColumnBase<T> extends Omit<TableColumn<T>, 'render'> {
+    id: string;
+    /** Column type — maps to a CellType in the registry */
+    cellType: keyof CellTypeConfigMap;
+    /** Extract the cell value from the row data */
+    getValue: (item: T) => any;
+    /** Field metadata associated with the column, when available. */
+    field?: Field;
+    /** Return updated item with new cell value (immutable) */
+    setValue?: (item: T, value: any) => T;
+    /** Column-level validation rules */
+    validation?: ValidationRule[];
+    /** Is this column editable? (default: true if setValue exists) */
+    editable?: boolean | ((item: T) => boolean);
+    /** True if this column represents the schema's primary field. Drives header-action disable rules (e.g. blocks Delete, blocks Make Primary). */
+    isPrimary?: boolean;
+    /** True if this column represents a system field. Drives header-action disable rules (e.g. blocks Edit, Delete, Duplicate). */
+    isSystem?: boolean;
+}
+type EditableColumn<T, C extends keyof CellTypeConfigMap = keyof CellTypeConfigMap> = C extends C ? EditableColumnBase<T> & {
+    cellType: C;
+    typeConfig?: CellTypeConfigMap[C] extends never ? never : CellTypeConfigMap[C];
+} : never;
+
+type TableColumnBase<T = any> = Omit<TableColumn$1<T>, 'sortDescending' | 'sortable' | 'infoTooltipProps' | 'style' | 'titleSuffix'> & {
+    style?: CSSProperties | ((column: TableColumn$1, rowData: KeyedItem<T>, rowNum: number) => CSSProperties);
+    reorderDisabled?: boolean;
+    defaultSortOrder?: SortOrder;
+    sortMode?: SortMode;
+    searchable?: boolean;
+    infoTooltipProps?: TableColumn$1['infoTooltipProps'] & {
+        panelContent?: ReactNode;
+    };
+    mobile?: ColumnMobileConfig;
+    /**
+     * The field type string used to resolve a prefix icon for the column.
+     * Cairo maps this to the appropriate icon internally.
+     * @external
+     */
+    fieldType?: FieldType;
+    /**
+     * Explicit prefix icons for the column (e.g. a custom field type's
+     * `display.icons`). When present, used instead of the `fieldType` mapping.
+     * @external
+     */
+    fieldTypeIcons?: {
+        Small: ComponentType;
+        Medium: ComponentType;
+    };
+    /**
+     * Whether the field contains personally identifiable information.
+     * @external
+     */
+    isPii?: boolean;
+    /**
+     * only for cms. Whether this is a system-managed field.
+     * @external
+     */
+    isSystem?: boolean;
+    /**
+     * Whether this is the primary display field.
+     * @external
+     */
+    isPrimary?: boolean;
+    /**
+     * Column-level validation rules. When a `required` rule is present, a required indicator is shown in the custom columns panel.
+     * @external
+     */
+    validation?: ValidationRule[];
+};
+interface TableColumnOptional<T> extends TableColumnBase<T> {
+    id?: string;
+    name?: string;
+    hiddenFromCustomColumnsSelection?: undefined | true;
+    hideable?: undefined;
+    defaultHidden?: undefined;
+}
+interface TableColumnCustom<T> extends TableColumnBase<T> {
+    id: string;
+    name: string;
+    hiddenFromCustomColumnsSelection?: false;
+    hideable?: true;
+    defaultHidden?: boolean;
+}
+interface TableColumnCustomOptionalName<T> extends TableColumnBase<T> {
+    id: string;
+    name?: string;
+    title: TableColumnBase['title'];
+    hiddenFromCustomColumnsSelection?: false;
+    hideable?: true;
+    defaultHidden?: boolean;
+}
+interface TableColumnCustomDefaultHidden<T> extends TableColumnBase<T> {
+    id: string;
+    name?: string;
+    title: TableColumnBase['title'];
+    hiddenFromCustomColumnsSelection?: false;
+    hideable: false;
+    defaultHidden?: undefined | false;
+}
+type CustomColumnConfig<T> = TableColumnOptional<T> | TableColumnCustom<T> | TableColumnCustomDefaultHidden<T> | TableColumnCustomOptionalName<T>;
+interface SortableColumnConfig<T> extends TableColumnBase<T> {
+    id: string;
+    sortable: true;
+}
+interface NotSortableColumnConfig<T> extends TableColumnBase<T> {
+    id?: string;
+    sortable?: false;
+}
+type SortableConfig<T> = SortableColumnConfig<T> | NotSortableColumnConfig<T>;
+/**
+ * `TableColumn` — cut here because it has its own bundle.
+ * Full shape: `types/TableColumn.d.ts`.
+ */
+type TableColumn<T = any> = CustomColumnConfig<T> & SortableConfig<T>;
+type ColumnMobileConfig = {
+    /**
+     * Which mobile column to display in.
+     * - 'first': Stacks vertically with other 'first' columns
+     * - 'second': Displays as standalone second column
+     * - undefined: Hidden on mobile
+     */
+    column: 'first';
+    /**
+     * Sort order within 'first' column (lower appears higher).
+     * Only relevant when column is 'first'.
+     * @default Infinity
+     */
+    order?: number;
+} | {
+    /**
+     * Which mobile column to display in.
+     * - 'first': Stacks vertically with other 'first' columns
+     * - 'second': Displays as standalone second column
+     * - undefined: Hidden on mobile
+     */
+    column?: 'second';
+};
+
+/**
+ * `CollectionTableBaseProps` — cut here because it has its own bundle.
+ * Full shape: `types/CollectionTableBaseProps.d.ts`.
+ */
+interface CollectionTableBaseProps<T = any, F = any> {
+    [key: string]: unknown;
+}
+
+interface FieldsSourceProvider {
+    setOnTable(toolbar: ToolbarCollectionState<any, any>): void;
+}
+
+interface EditableTableProps<T, F extends FiltersMap = OptionalFiltersMap> extends Omit<TableVirtualProps<T, F>, 'columns' | 'state' | 'onRowClick' | 'forceResize' | 'horizontalScroll' | 'showSelection' | 'showRowNumbers' | 'showAddFieldButton' | 'rowStatus'> {
+    /** EditableTableState instance, created via useEditableTableCollection */
+    state: EditableTableState<T, F>;
+    /** Column definitions with cell types. When a `fieldsSource` is wired, its
+     *  columns are added by the state, so pass `[]` for source-only tables. */
+    columns: EditableColumn<T>[];
+    /** A fields source (e.g. `dataExtensionTableSource(...)`) whose fields become
+     *  columns and whose field management wires into the table. Schema sources
+     *  attach via the `@wix/patterns/schema` collection hooks instead. */
+    fieldsSource?: FieldsSourceProvider;
+    /** When true, hides the built-in header actions popover for all columns. */
+    hideHeaderActions?: boolean;
+    /** data-hook for testkit selectors */
+    dataHook?: string;
+}
+
+/** EditableTable props for a source-driven table: the source supplies the field
+ *  columns and attaches its own fields management. `columns` is optional
+ *  (extras only); field-type icons are always on, and there is no
+ *  `fieldsSource`/`dataExtension`. */
+type SchemaEditableTableProps<T, F extends FiltersMap> = Omit<EditableTableProps<T, F>, 'state' | 'columns' | 'fieldsSource' | 'dataExtension' | 'showFieldTypeIcons'> & {
+    state: EditableTableState<T, F>;
+    /** Columns beyond the source's fields. Default: none. */
+    columns?: EditableColumn<T>[];
+};
+declare function _EditableTable<T, F extends FiltersMap>(props: SchemaEditableTableProps<T, F>): React.JSX.Element;
+declare const EditableTable: typeof _EditableTable;
+
+export { EditableTable };
+export type { SchemaEditableTableProps };

package/dist/dts-bundle/components/EntityPageFieldsCard.d.ts

@@ -0,0 +1,100 @@
+import React from 'react';
+import { CardProps, IconElement } from '@wix/design-system';
+
+interface ErrorCardProps extends CardProps {
+    /**
+     * Title to display in the error state.
+     */
+    title?: string;
+    /**
+     * Subtitle to display in the error state.
+     */
+    subtitle?: string;
+    /**
+     * Action button to display in the error state.
+     */
+    action?: {
+        /**
+         * Action button text.
+         */
+        text: string;
+        /**
+         * Callback function to run when the action button is clicked.
+         */
+        onClick: () => void;
+        /**
+         * [Icon](https://www.docs.wixdesignsystem.com/?path=/story/foundations-icons--icons) to display on the action button before the text.
+         */
+        prefixIcon?: IconElement;
+    };
+}
+
+interface CardContainerProps extends CardProps {
+    /**
+     * Additional loading flag, if you need to show loader after the main entity is fetched.
+     * Also, if an error occurs on a side request (other than passed to `fetch`), you can use `error` to show the card error state.
+     * Alongside with `error` you also need to pass `errorState.onRetry` callback, which should change the `status` accordingly.
+     */
+    status?: 'idle' | 'loading' | 'error' | 'success';
+    /**
+     * Height of content while loading (not including paddings)
+     */
+    minHeight?: string;
+    /**
+     * Card Error State configuration
+     */
+    errorState?: ErrorCardProps;
+    /**
+     * Identifier of the card.
+     * If you want to open a page and auto-scroll and focus ont his card, pass in the the query params `anchor={yourCardId}`.
+     */
+    id?: string;
+}
+
+interface FormPageCardProps extends CardContainerProps {
+}
+
+interface EntityPageCardProps extends FormPageCardProps {
+}
+
+interface EntityPageFieldsCardProps extends Omit<EntityPageCardProps, 'children'> {
+    title: string;
+    subtitle?: string;
+    /**
+     * Field ids to offer, in order. Omitted ⇒ every schema field; system fields
+     * and the id field show their value read-only and can be hidden.
+     * Read once, on the first render — a later change is ignored, since the saved
+     * show/hide and order are keyed to the list the card started with.
+     */
+    fieldIds?: string[];
+    /**
+     * Namespace the per-user show/hide and order are stored under. Default: the
+     * source's collection id — set it only to store the layout under a name of
+     * your own.
+     */
+    persistencyKey?: string;
+    /** Whether to show the "Manage fields" button and panel. Default: `true`. */
+    showManageFields?: boolean;
+    dataHook?: string;
+}
+/** The page's schema fields in a card, with a "Manage fields" panel that shows,
+ *  hides and reorders them, and adds, edits and deletes them. The choice is
+ *  saved per user and survives reloads. Render inside the `EntityPage` from this
+ *  entry.
+ *
+ *  One card per page. Field management is built per card, so on a second card
+ *  the rows of fields added from the first one render without their actions
+ *  menu — the row comes from the page's schema, the menu from the card's own
+ *  copy, which only the mutating card's copy gets merged into. Split the fields
+ *  across cards only when none of them manages fields (`showManageFields:
+ *  false`). */
+declare function _EntityPageFieldsCard({ title, subtitle, fieldIds, persistencyKey, showManageFields, dataHook, ...rest }: EntityPageFieldsCardProps): React.JSX.Element;
+declare namespace _EntityPageFieldsCard {
+    var displayName: string;
+}
+declare const EntityPageFieldsCard: typeof _EntityPageFieldsCard & {
+    displayName: string;
+};
+
+export { EntityPageFieldsCard, _EntityPageFieldsCard };
+export type { EntityPageFieldsCardProps };