@wix/patterns 1.475.0 → 1.477.0

package/dist/dts-bundle/types/SchemaSourceInput.d.ts

@@ -0,0 +1,814 @@
+import { ComponentType, ReactNode, ReactElement, MutableRefObject } from 'react';
+
+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;
+
+/**
+ * `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;
+}
+
+/**
+ * `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 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 FetchTotalFn = (query: CursorQuery) => Promise<number>;
+
+/** Field-management permissions. Absent when the schema's fields cannot be edited. */
+interface SchemaPermissions {
+    createField: boolean;
+    updateField: boolean;
+    deleteField: boolean;
+}
+/** The per-item delete verdict. */
+interface RemoveItemDisabledResult {
+    disabled: boolean;
+    /** Why the item cannot be deleted — surfaced to the user by consumers. */
+    reason?: string;
+}
+/** Item-level CRUD permissions. */
+interface ItemPermissions<T = Record<string, unknown>> {
+    createItem: boolean;
+    updateItem: boolean;
+    deleteItem: boolean;
+    /** Deleting several items in one operation. Absent = follows `deleteItem`. */
+    bulkDeleteItems?: boolean;
+    /** Per-item refinement of `deleteItem`: disables deleting an item even
+     *  though `deleteItem` is true, optionally with a reason. Must be pure and
+     *  synchronous. Absent = all items deletable. */
+    isRemoveItemDisabled?: (item: T) => RemoveItemDisabledResult;
+}
+/**
+ * A source-neutral description of a collection — data only, no behavior.
+ * Item access is in `CollectionBackend`, field mutations in `FieldActions`.
+ */
+interface Schema {
+    id: string;
+    fields: Record<string, Field | undefined>;
+    /** Human-readable label, when the source has one. Reported to BI. */
+    name?: string;
+    /** The kind of data set, when the source distinguishes kinds. Reported to BI. */
+    type?: string;
+    /** The field that best represents the entity (titles/selections). */
+    displayField: string;
+    /** The identifier field. */
+    idField: string;
+    /** Group display order, present when fields carry a `group`. */
+    groups?: string[];
+    /** Absent when the schema's fields cannot be edited. */
+    schemaPermissions?: SchemaPermissions;
+    itemPermissions?: ItemPermissions;
+}
+interface BackupConfig {
+    create: () => Promise<{
+        backupId: string;
+    }>;
+    waitForCompletion: (backupId: string, options?: {
+        signal?: AbortSignal;
+    }) => Promise<void>;
+    cancel?: (backupId: string) => Promise<void>;
+    restore?: (backupId: string) => Promise<{
+        restorationId: string;
+    }>;
+    waitForRestoration?: (restorationId: string, options?: {
+        signal?: AbortSignal;
+    }) => Promise<void>;
+}
+interface BulkInsertError {
+    rowIndex: number;
+    message?: string;
+    code?: string;
+}
+interface BulkInsertResult {
+    succeeded?: number;
+    failed?: number;
+    errors?: BulkInsertError[];
+}
+/**
+ * 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[];
+}
+/** Item data access shared by both pagination modes. `find` (on
+ *  `CollectionBackend`) is the only required call — the rest are capabilities
+ *  a source provides when it (or its consumer) supports them. */
+interface CollectionBackendBase<T = Record<string, unknown>> {
+    get?: (entityId: string) => Promise<T>;
+    create?: (entity: Partial<T>) => Promise<T>;
+    update?: (entity: T, context?: CollectionUpdateContext<T>) => Promise<T>;
+    delete?: (entityId: string) => Promise<void>;
+    bulkDelete?: (entityIds: string[]) => Promise<void>;
+    move?: (id: string, params: {
+        moveAfterId: string | null | undefined;
+    }) => Promise<void>;
+    backup?: BackupConfig;
+    bulkInsert?: (entities: Partial<T>[]) => Promise<BulkInsertResult>;
+}
+/** Per-call search scope the query layer passes to a backend's `find`. */
+interface FindOptions {
+    searchableFieldIds?: string[];
+}
+/**
+ * The query-layer fetch-data fns plus the optional `find` options the runtime
+ * already accepts. Kept separate so the shared `OffsetFetchDataFn`/
+ * `CursorFetchDataFn` used by `fetchData` stay unchanged.
+ */
+type OffsetFindFn<T, F extends FiltersMap> = (query: OffsetQuery<F>, options?: FindOptions) => Promise<OffsetQueryResult<T>>;
+type CursorFindFn<T, F extends FiltersMap> = (query: CursorQuery<F>, options?: FindOptions) => Promise<CursorQueryResult<T>>;
+/**
+ * A source's item data access. The source declares its `paginationMode`
+ * (offset by default) together with the matching `find`, same as core's
+ * `PaginationModeConfig`.
+ */
+type CollectionBackend<T = Record<string, unknown>, F extends FiltersMap = OptionalFiltersMap> = CollectionBackendBase<T> & ({
+    paginationMode?: 'offset';
+    find: OffsetFindFn<T, F>;
+} | {
+    paginationMode: 'cursor';
+    find: CursorFindFn<T, F>;
+    fetchTotal?: FetchTotalFn;
+});
+/**
+ * Whatever the source's settings section collected in the add/edit field modal.
+ * The modal and the collection layer only carry it; the source that produced it
+ * is the only one that looks inside, so it declares its own shape on `addField`
+ * and `editField` (both are methods, so a narrower parameter type is allowed).
+ */
+type FieldSettings = unknown;
+/** Field-management actions. All optional — a read-only source provides none. */
+interface FieldActions {
+    /**
+     * Field-mutating actions return the collection's updated fields map so the
+     * caller can merge its local state from the response, without reloading the
+     * schema. (`renameField` is the exception — nothing consumes its result yet.)
+     */
+    addField?(field: Field, settings?: FieldSettings): Promise<Schema['fields']>;
+    /**
+     * Adds several fields in a single mutation, each under its `field.id` key
+     * (callers decide the keys up front — e.g. CSV import uploads values under
+     * them), unlike `addField`, which derives a fresh key from the display name.
+     */
+    addFields?: (fields: Field[]) => Promise<Schema['fields']>;
+    editField?(fieldId: string, updates: Partial<Field>, settings?: FieldSettings): Promise<Schema['fields']>;
+    deleteField?: (fieldId: string) => Promise<Schema['fields']>;
+    renameField?: (fieldId: string, newName: string) => Promise<void>;
+    makePrimary?: (fieldId: string) => Promise<Schema['fields']>;
+    duplicateField?: (fieldId: string) => Promise<Schema['fields']>;
+    duplicateFieldWithContent?: (fieldId: string) => Promise<Schema['fields']>;
+}
+/** Everything a source provides for a collection. */
+interface LoadedSchema<T = Record<string, unknown>> {
+    schema: Schema;
+    backend: CollectionBackend<T>;
+    fieldActions?: FieldActions;
+}
+
+/** Presentation for one existing field, without changing its type or behavior. */
+interface FieldPresentation {
+    typeDisplay?: Partial<FieldTypeDisplay>;
+    collectionInputLabel?: string;
+}
+/** Read/write permission defaults a source supports, per audience. */
+interface FieldPermissions {
+    installedApps?: {
+        hide?: boolean;
+        defaultRead?: boolean;
+        defaultWrite?: boolean;
+    };
+    siteVisitors?: {
+        hide?: boolean;
+        defaultRead?: boolean;
+        defaultWrite?: boolean;
+    };
+}
+/** The add-modal subtitle: a line of text, an optional second note line, and an
+ *  optional "learn more" link. */
+interface FieldModalSubtitle {
+    text: string;
+    note?: string;
+    learnMore?: {
+        label: string;
+        href: string;
+    };
+}
+/** The text a source supplies for the add/edit field modal. */
+interface FieldModalText {
+    addTitle: string;
+    editTitle: string;
+    /** Subtitle for the add modal; omit for none. */
+    addSubtitle?: FieldModalSubtitle;
+    /** Label of the collapsible section below the main fields. */
+    settingsLabel?: string;
+}
+/** A warning shown under the PII toggle, with an optional action button. */
+interface FieldPiiWarning {
+    text: string;
+    action?: {
+        label: string;
+        onClick: () => void;
+    };
+}
+interface FieldModalCollectionOption {
+    id: string;
+    label: string;
+}
+type FieldModalCollectionOptionsLoader = () => Promise<FieldModalCollectionOption[]>;
+interface FieldModalCollectionAction {
+    label: string;
+    icon?: ComponentType;
+    disabled?: boolean;
+    /** Return an option to select, or undefined on cancellation. The option may
+     *  be pending creation; persistence remains the source's responsibility. */
+    onClick: () => Promise<FieldModalCollectionOption | undefined>;
+}
+/** Extra collection picker a field type can add to the main modal body. */
+interface FieldModalCollectionInput {
+    label?: string;
+    placeholder?: string;
+    emptyStateMessage?: string;
+    errorMessage?: string;
+    required?: boolean;
+    loadOptions?: FieldModalCollectionOptionsLoader;
+    /** An action below the options, also shown when no options match. */
+    dropdownAction?: FieldModalCollectionAction;
+    /** Restores the picker value from an existing field. */
+    getValue?: (field: Field) => string | undefined;
+    /** Adds picker-derived values to the source-owned settings payload. */
+    getSettings?: (collectionId: string) => FieldSettings;
+}
+interface FieldSettingsProps {
+    /** The picked field type, or absent before one is picked. */
+    fieldType?: string;
+    /** Validation rules the section should render as fixed, not user-editable.
+     *  A section ignores any entry it doesn't recognize. */
+    lockedRules?: readonly string[];
+}
+/**
+ * The collapsible section below the main add/edit field inputs, supplied by the
+ * source. The modal renders it, blocks confirm while it has an error, and hands
+ * its values to the source's own `addField`/`editField` — it never looks inside.
+ */
+interface FieldSettingsSection {
+    Component: ComponentType<FieldSettingsProps>;
+    /** True keeps the modal open on confirm. The section shows the error itself. */
+    hasError(fieldType?: string): boolean;
+    /** Passed to `FieldActions.addField`/`editField` as-is. */
+    getValues(fieldType?: string): FieldSettings;
+    /**
+     * Fills the inputs when the modal opens: the field being edited, or nothing
+     * for a new field. Pushed in rather than read from a prop, so the values are
+     * there whether or not the section has been rendered yet.
+     */
+    setValues(field?: Field): void;
+    /**
+     * Prefills a new field's rules from the caller's requested initial values —
+     * there is no backing `Field` yet, so this is separate from `setValues`.
+     * Absent ⇒ the section doesn't support prefilling any rule this way, and
+     * the modal drops that rule from `lockedProperties` rather than locking a
+     * control at a value it could never actually apply.
+     */
+    setInitialValues?(initial: {
+        required?: boolean;
+    }): void;
+}
+
+/**
+ * `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 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;
+};
+interface Focusable {
+    focus: () => void;
+}
+type EditTrigger = {
+    kind: 'type';
+    key: string;
+} | 'enter' | 'click' | 'doubleClick';
+interface CellViewProps<V> {
+    value: V;
+    typeConfig?: unknown;
+    validation?: ValidationRule[];
+    /** Stable id of the column. Cell components can use it to derive unique DOM ids. */
+    columnId: string;
+    /** Stable key of the row. Cell components can use it to derive unique DOM ids. */
+    rowKey: string;
+    /** Whether the cell is editable. Used to conditionally render placeholders (don't show them for read-only cells). */
+    isEditable?: boolean;
+}
+interface CellEditProps<V> {
+    value: V;
+    onChange(value: V): void;
+    onCommit: () => void;
+    onCancel: () => void;
+    /**
+     * Signals that the cell is starting an editing operation that will move focus
+     * outside the table (e.g., opening a media manager or a modal). Calling this
+     * sets isEditing=true so the table does not clear cell focus while the
+     * external UI is open. Pair with onCommit (after the operation succeeds)
+     * or onCancel (if the user dismisses without a value change).
+     */
+    onStartEdit?: () => void;
+    /** Ref to the focusable input element. Used for type-to-edit (focusing the input when user starts typing on a focused cell). */
+    inputRef?: MutableRefObject<Focusable | undefined | null>;
+    typeConfig?: unknown;
+    /** How edit mode was triggered. Edit components can use this to customize behavior (e.g., date picker auto-opens on 'type'). */
+    editTrigger?: EditTrigger | null;
+    /** Column-level validation rules. Edit components can derive UI behavior (e.g., maxLength blocking/tooltip) from these. */
+    validation?: ValidationRule[];
+    /** Stable id of the column. Cell components can use it to derive unique DOM ids. */
+    columnId: string;
+    /** Stable key of the row. Cell components can use it to derive unique DOM ids. */
+    rowKey: string;
+}
+/**
+ * Props passed to a cell type's optional `EditWrapper`. The table mounts the
+ * wrapper around the cell content and keeps it mounted across the edit↔view
+ * transition, so the wrapper can own behavior that must outlive the inline
+ * editor (e.g. a reference cell navigating to an overlay and refreshing on
+ * return). The wrapper hands anything the editor needs down via its own context.
+ */
+interface CellEditWrapperProps {
+    /** The column's typeConfig (same value handed to the cell's Edit/View). */
+    typeConfig?: unknown;
+    /** Stable id of the column. */
+    columnId: string;
+    /** Stable key of the row. */
+    rowKey: string;
+    /** The cell content (the Edit or View component) to render inside the wrapper. */
+    children: ReactNode;
+}
+type EditableCellContextMenuAction = 'copy' | 'cut' | 'paste' | 'clear';
+interface EditableCellContextMenuActionContext<V> {
+    /** Current cell value, including pending or draft edits. */
+    value: V;
+    /** Field metadata associated with the column, when available. */
+    field?: Field;
+    /** Stable key of the row. */
+    rowKey: string;
+    /** Stable id of the column. */
+    columnId: string;
+}
+interface EditableCellContextMenuActionConfig<V> {
+    /** Returning a non-empty string disables the action and shows the tooltip. */
+    disabledTooltip(context: EditableCellContextMenuActionContext<V>): string | undefined;
+}
+/**
+ * The editable-cell slot of a field type definition: how a cell of that type
+ * renders, edits, and moves through the clipboard. The definition's key
+ * identifies the type and the definition's `value` owns validation, so the
+ * slot carries neither.
+ *
+ * Members that take `V` use method syntax so a definition typed with a
+ * concrete value type stays assignable where a loosely typed definition is
+ * expected (see `FieldTypeDefinition`).
+ */
+interface EditableCellConfig<V> {
+    /** Render cell in view mode (read-only display). */
+    ViewComponent(props: CellViewProps<V>): ReactElement | null;
+    /** Render cell in edit mode (inline editor). Optional — omit for view-only cells. */
+    EditComponent?(props: CellEditProps<V>): ReactElement | null;
+    /** Serialize value to clipboard string. */
+    serialize?(value: V): string;
+    /** Deserialize clipboard string to value. */
+    deserialize?(raw: string): V;
+    /** Can this cell type be edited? (default: true) */
+    editable?: boolean;
+    /** Availability of Cairo's built-in cell context-menu actions. */
+    contextMenu?: Partial<Record<EditableCellContextMenuAction, EditableCellContextMenuActionConfig<V>>>;
+    /** Toggle value on single click (e.g., boolean checkbox). Skips focus→edit flow. */
+    toggleValue?(value: V): V;
+    /** Enter edit mode on single click (e.g., image cell with no value). */
+    editOnClick?(value: V): boolean;
+    /** Show the EditComponent when the cell is focused, without entering edit mode.
+     *  Keyboard navigation remains active. Similar to toggleValue but without toggling. */
+    showEditWhenFocused?: boolean;
+    /** Optional wrapper component the cell type defines to own behavior that must
+     *  outlive the inline editor. Mounted around the cell content and kept mounted
+     *  across the edit↔view transition. */
+    EditWrapper?: ComponentType<CellEditWrapperProps>;
+    /** Cell content can grow past row height when focused. Only applies to
+     *  showEditWhenFocused cells. */
+    growable?: boolean;
+    /** Called on type-to-edit. Return object with cleared value and/or prevent flag.
+     *  Return undefined to block the key. Return {} to enter edit mode without changing the value. */
+    onTypeToEdit?(params: {
+        key: string;
+        validation?: ValidationRule[];
+    }): {
+        value?: V;
+    } | undefined;
+    /** Optional hook to normalize the committed value (e.g. auto-prepend https://).
+     *  Called before the edit commits; the value is written back before committing. */
+    normalizeOnCommit?(value: V): V;
+    /** When true, type-to-edit flushes the edit-mode render synchronously and
+     *  focuses the input within the same keydown event, then lets the browser's
+     *  default action deliver the keystroke to the now-focused input naturally.
+     *  Use for cells that wrap a controlled input whose value can't be seeded via props. */
+    nativeTypeToEdit?: boolean;
+}
+/** The props the filter builder passes to a definition's toolbar filter
+ *  component — the same contract the built-in filter elements receive. */
+interface FilterTypeComponentProps<V = any> {
+    filter: Filter<V>;
+    toolbarItemProps?: {
+        label?: ReactNode;
+    };
+    toolbarTagProps?: {
+        label?: string;
+    };
+    accordionItemProps?: {
+        label?: string;
+    };
+}
+/** The filter slot of a field type definition: the filter state registered on
+ *  the collection query and the toolbar element that renders it. */
+interface FilterTypeConfig {
+    createFilter: (field: Field) => Filter<any>;
+    Component: ComponentType<FilterTypeComponentProps>;
+}
+/**
+ * The read-only table slot of a field type definition: how a cell of that
+ * type renders in the table, and the column's layout. Independent of
+ * `editableTable` — neither slot falls back to the other.
+ */
+/** What a read-only table cell is told about itself. */
+interface TableCellProps<V> {
+    value: V;
+    /** Stable id of the column. Cell components can use it to derive unique DOM ids. */
+    columnId: string;
+    /** The row this cell belongs to, so a cell can act on its item and not just
+     *  display it. Typed loosely for the same reason as `FieldsSource.getCellValue`:
+     *  the row shape belongs to the source, not to Cairo. */
+    row: unknown;
+}
+interface TableCellConfig<V> {
+    /** Render the cell. Method syntax keeps the definition assignable to
+     *  `FieldTypeDefinition<unknown>` (see FieldTypeDefinition). */
+    CellComponent(props: TableCellProps<V>): ReactElement | null;
+    /** Column width. Required — custom types get no built-in layout default. */
+    width: string;
+    /** Default: 'start'. */
+    align?: 'start' | 'center' | 'end';
+}
+/** An extra menu item a field type definition adds to a field's actions menu. */
+interface FieldTypeActionItem {
+    key: string;
+    label: string;
+    icon?: ReactNode;
+    skin?: 'destructive';
+    onClick: (field: Field) => void;
+    /** Default: visible. */
+    visible?: (field: Field) => boolean;
+    /** Returning a string disables the item and shows the tooltip. */
+    disabledTooltip?: (field: Field) => string | undefined;
+}
+/** The actions slot of a field type definition: extra items for the field's "more actions" menu. */
+interface FieldActionsConfig {
+    items?: FieldTypeActionItem[];
+}
+/** Display metadata for a field type: menu label and type icons. */
+interface FieldTypeDisplay {
+    label: string;
+    icons: {
+        Small: ComponentType;
+        Medium: ComponentType;
+    };
+}
+/** Value semantics of a field type, independent of any rendering surface.
+ *  Members use method syntax so a definition typed with a concrete value type
+ *  stays assignable where a loosely typed definition is expected. */
+interface FieldValueBehavior<V> {
+    defaultValue?: V;
+    isEmpty?(value: V): boolean;
+    /** Returns an error message, or null when the value is valid. Every surface
+     *  that validates a field of this type runs this. */
+    validate?(value: V, rules?: ValidationRule[]): string | null;
+}
+interface FieldCapabilities {
+    sortable: boolean;
+}
+/** The field-modal slot of a field type definition: opts the type into the
+ *  add/edit-field modal's type picker and describes its entry there. */
+interface FieldModalConfig {
+    /** True ⇒ the add-field modal offers this type. */
+    creatable: boolean;
+    /** Placeholder for the name input. Absent ⇒ the modal's generic placeholder. */
+    namePlaceholder?: string;
+    /** One-line description under the type in the picker. */
+    subtitle?: string;
+    /** Group heading this type is listed under in the picker. */
+    group?: string;
+    /** Whether a field of this type can be marked PII. Absent ⇒ follows the
+     *  source-wide setting. */
+    supportsPii?: boolean;
+    /** Warning shown while the PII toggle is on. Read on every render, so it can
+     *  use data that only exists once the schema has loaded. Default: none. */
+    piiWarning?: () => FieldPiiWarning | undefined;
+    /** This type's collapsible settings section — the same contract a
+     *  source-declared type option carries (see `FieldSettingsSection`). */
+    settingsSection?: FieldSettingsSection;
+    /** Collection picker shown in the main add/edit field form. */
+    collectionInput?: FieldModalCollectionInput;
+}
+/**
+ * Props the entity-page form dispatcher passes to a field type's form
+ * component. The dispatcher owns the form wiring (registration, validation
+ * from the definition's `value.validate`) and the field UI (label, required
+ * marker, error message); the component renders the input: read `value`,
+ * report edits through `onChange`, and hand back the focusable control
+ * through `inputRef` so a blocked save can reach it.
+ */
+interface FormFieldComponentProps<V> {
+    field: Field;
+    value: V;
+    onChange(value: V): void;
+    /** Call when the input loses focus — marks the field touched, so error
+     *  timing matches the built-in renderers. */
+    onBlur: () => void;
+    /** Ref to the focusable input element. Used to focus the field when a
+     *  blocked save reports an error on it. Absent ⇒ the entity page brings the
+     *  field into view and focuses the first control it finds inside. */
+    inputRef?: MutableRefObject<Focusable | undefined | null>;
+    dataHook?: string;
+}
+/** The entity-page form slot of a field type definition. */
+interface FormTypeConfig<V = unknown> {
+    /** Renders the input. Method syntax keeps the definition assignable to
+     *  `FieldTypeDefinition<unknown>` (see FieldTypeDefinition). */
+    Component(props: FormFieldComponentProps<V>): ReactElement | null;
+}
+/**
+ * A consumer-defined field type. Defined once on the fields source; every
+ * entry point that renders the field resolves its slot from here. `V` is the
+ * field's value type — `defineFieldType` infers it, and it keeps all the
+ * slots consistent with each other.
+ *
+ * Sources hold definitions of mixed value types in one
+ * `FieldTypeDefinition[]` (= `FieldTypeDefinition<unknown>[]`) array. That
+ * works because every member that takes `V` is declared with method syntax,
+ * which TypeScript checks bivariantly — so `FieldTypeDefinition<number>` is
+ * assignable to `FieldTypeDefinition<unknown>` without casts.
+ */
+interface FieldTypeDefinition<V = unknown> {
+    /** Unique key for the type. A built-in type uses its `PatternsFieldType`; a
+     *  consumer-defined type uses the string its fields reference via `customType`. */
+    type: string;
+    display: FieldTypeDisplay;
+    /** Filter behavior, or an explicit opt-out — never silently absent. */
+    filter: FilterTypeConfig | {
+        filterable: false;
+    };
+    value?: FieldValueBehavior<V>;
+    capabilities?: FieldCapabilities;
+    /** Absent ⇒ the field renders with the default cell in the read-only table. */
+    table?: TableCellConfig<V>;
+    /** Absent ⇒ the field renders as a read-only cell in editable surfaces. */
+    editableTable?: EditableCellConfig<V>;
+    /** Required once a field of this type renders on an entity page:
+     *  development throws without it; production skips the field. */
+    form?: FormTypeConfig<V>;
+    /** Extra items for the field's "more actions" menu. */
+    actions?: FieldActionsConfig;
+    /** Absent ⇒ the add/edit field modal never offers this type. Fields of the
+     *  type created elsewhere still open in the modal for name/PII edits. */
+    fieldModal?: FieldModalConfig;
+}
+
+/** A field type the add/edit field modal offers, with everything that type
+ *  brings to it. Declare one entry per `patternsType` — the type is the entry's
+ *  identity. Nothing here reaches the table or the filters; that is `fieldTypes`
+ *  (`FieldTypeDefinition[]`). */
+interface FieldTypeOption {
+    patternsType: PatternsFieldType;
+    /** Custom display name. Absent ⇒ the UI's standard name for this type. */
+    label?: string;
+    /** Custom name-input placeholder. Absent ⇒ the UI's standard placeholder. */
+    namePlaceholder?: string;
+    /** A one-line description shown under the type in the add-field menu. */
+    subtitle?: string;
+    /** The group heading this type is listed under in the add-field menu, in
+     *  first-seen order. Types sharing a heading form one group. Absent ⇒
+     *  ungrouped. */
+    group?: string;
+    /** Whether a field of this type can be marked PII. Absent ⇒ follows the
+     *  source's `supportsPii`. */
+    supportsPii?: boolean;
+    /** Warning shown while the PII toggle is on. Read on every render, so it can
+     *  use data that only exists once the schema has loaded. Default: none. */
+    piiWarning?: () => FieldPiiWarning | undefined;
+    /** This type's own part of the collapsible section in the add/edit field
+     *  modal. Default: none. */
+    settingsSection?: FieldSettingsSection;
+    /** Collection picker shown in the main add/edit field form. */
+    collectionInput?: FieldModalCollectionInput;
+}
+/** Everything the add/edit field modal shows for this source. */
+interface FieldModalInput {
+    /** Title and subtitle. Default: generic titles. */
+    text?: FieldModalText;
+    /** Default option loader for reference-like built-in field types. */
+    loadReferenceableCollectionOptions?: FieldModalCollectionOptionsLoader;
+    /** The types the modal offers, in display order. Default: none. */
+    types?: FieldTypeOption[];
+}
+/** Copy shown before deleting a field. Strings are translated by the caller. */
+interface DeleteFieldConfirmation {
+    title: string;
+    description: string;
+    /** When provided, confirmation requires this checkbox to be checked. */
+    confirmationCheckboxLabel?: string;
+}
+/** Identifies the collection behind a table on BI events. */
+interface SchemaBiParams {
+    tableId?: string;
+    tableName?: string;
+    tableType?: string;
+}
+/** What a caller passes. Only `collectionId` and `loadSchema` are required. */
+interface SchemaSourceInput<T> {
+    collectionId: string;
+    loadSchema: () => Promise<LoadedSchema<T>>;
+    /** Sources for collections this one references, keyed by the referenced
+     *  collection id. A renderer resolves a reference field through the matching
+     *  entry — its `loadSchema` gives the referenced schema and `sourceFetchData`
+     *  queries the referenced items. Default: none. */
+    references?: Record<string, SchemaSource<any>>;
+    /** Lazy source lookup for a referenced collection that is not in `references`.
+     *  Is used when a reference field is created in the add field modal.
+     *  The returned source owns its own async schema/item loading. */
+    getReferencedCollectionSource?: (collectionId: string) => SchemaSource<any> | undefined;
+    paginationMode?: 'offset';
+    /** Stable row identity. Default: `row[idField]`. */
+    itemKey?: (item: T) => string;
+    /** Row display label. Default: `row[displayField]`. */
+    itemName?: (item: T) => string;
+    /** Fields free-text search runs against. Default: `[displayField]`. */
+    searchableFieldIds?: (schema: Schema) => string[];
+    /** What the add/edit field modal shows. Default: no types, generic titles. */
+    fieldModal?: FieldModalInput;
+    /** Consumer-defined field types: how a field of that type renders, filters and
+     *  validates wherever it appears. A field with `type: 'CUSTOM'` resolves its
+     *  definition here by `customType`. The add/edit field modal never reads this
+     *  — see `fieldModal`. Default: none. */
+    fieldTypes?: FieldTypeDefinition[];
+    /** Overrides one existing field's type label, icons and collection-picker
+     *  label. Does not change its type, values or add-field options. */
+    getFieldPresentation?: (field: Field) => FieldPresentation | undefined;
+    /** Default: `schemaPermissions.createField`. */
+    canAddFields?: (schema: Schema) => boolean;
+    /** Default: `schemaPermissions.updateField`, except for system fields and
+     *  the id field. */
+    canEditField?: (field: Field, schema: Schema) => boolean;
+    /** Default: `schemaPermissions.deleteField`, except for system fields and
+     *  the id field. */
+    canDeleteField?: (field: Field, schema: Schema) => boolean;
+    /** Resolved when deletion is requested. Undefined keeps the default dialog. */
+    getDeleteFieldConfirmation?: (field: Field, schema: Schema) => DeleteFieldConfirmation | undefined;
+    /** Permission defaults shown in the modal. Absent ⇒ no permissions section. */
+    fieldPermissions?: FieldPermissions;
+    /** Default: `false`. */
+    supportsPii?: boolean;
+    /** The value of a field on an item. Default: `item[field.id]`. */
+    getFieldValue?: (item: T, field: Field) => unknown;
+    /** Writes a field's value on an item, returning the updated item.
+     *  Default: `{ ...item, [field.id]: value }`. */
+    setFieldValue?: (item: T, field: Field, value: unknown) => T;
+}
+/** 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;
+}
+/** The collection fetch derived from a source: loads once, then queries the
+ *  backend's `find`.
+ *
+ *  Free-text search covers the columns the page is showing: the table keeps
+ *  `query.columns` in sync with them, so the scope comes off the query rather
+ *  than being threaded in. Falls back to the source's own `searchableFieldIds`
+ *  before any columns are known (or with no table attached). */
+declare function sourceFetchData<T>(source: SchemaSource<T>): (query: OffsetQuery) => Promise<OffsetQueryResult<T>>;
+/** Fills source-neutral defaults over `input` and memoizes the load so the collection
+ *  query and the table columns share a single fetch. */
+declare function defineSchemaSource<T>(input: SchemaSourceInput<T>): SchemaSource<T>;
+
+export { defineSchemaSource, sourceFetchData };
+export type { DeleteFieldConfirmation, FieldModalInput, FieldTypeOption, SchemaBiParams, SchemaSource, SchemaSourceInput };