Cross-table transfer and conflict options

comins-table@0.2.2React

Moves between tables sharing the same coordinator object and scope with distinct tableIds. The coordinator does not own data; apply next source and target state together in one application update.

Compatibility and conflicts

Only Flat → Flat and Grouped → Grouped are supported. Do not combine with Tree, Viewport, columnFiltering, infiniteScroll, or lazyLoad. Group membership changes require the target setRowGroupId. Selection, row-detail, and group-expansion states are not transferred automatically.

The target owns canTransfer and resolveConflict. Duplicate IDs default to reject; undefined/invalid resolver returns also reject. overwrite replaces the conflicting target row. Group overwrite removes the target group and all its members, then inserts the source group bundle; it does not merge groups.

No success notification is emitted for incompatible coordinator/scope, duplicate registrations, stale/unmounted targets, or changed IDs. See parent-state integration and pure transfer functions.

CominsTableTransferConfig

coordinator

coordinator: CominsTableTransferCoordinator<TData, TGroup>;

Required shared factory-created object. Keep it stable across renders.

scope

scope: string;

Required non-empty transfer scope; transfers do not cross scopes.

tableId

tableId: string;

Required unique non-empty table ID within the scope.

canTransfer

canTransfer?: (intent: CominsTableTransferIntent<TData, TGroup>) => boolean;

Synchronous target-side permission callback. Omission accepts moves passing other checks. A false veto does not produce a duplicate-id rejection notification.

resolveConflict

resolveConflict?: CominsTableTransferConflictResolver<TData, TGroup>;

Target duplicate-ID resolver. Defaults to reject; overwrite requires an explicit return value.

rejectionFeedback

rejectionFeedback?: false | CominsTableTransferRejectionFeedback<TData, TGroup>;

Shows default duplicate-rejection tooltip/outline. Disable with false or set duration/renderTooltip. onTransferRejected is independent.

CominsTableTransferCoordinatorOptions

onTransfer

onTransfer: (result: CominsTableTransferResult<TData, TGroup>) => void;

Required. One success result contains both next source/target models; apply them in one parent-state update.

onTransferRejected

onTransferRejected?: (rejection: CominsTableTransferRejection<TData, TGroup>) => void;

No callback by default. Reports confirmed duplicate-id rejection after pointer drop; not called for null results from pure helpers.

CominsTableTransferRejectionFeedback

duration

duration?: number;

Default 1800ms. Display duration is bounded to 500–10000ms.

renderTooltip

renderTooltip?: (rejection: CominsTableTransferRejection<TData, TGroup>) => React.ReactNode;

Returns rejection-tooltip content; defaults to Duplicate ID messaging.

createCominsTableTransferCoordinator

export declare function createCominsTableTransferCoordinator<TData, TGroup = never>(options: CominsTableTransferCoordinatorOptions<TData, TGroup>): CominsTableTransferCoordinator<TData, TGroup>;

Import from comins-table. options.onTransfer is required. Returns a branded coordinator; do not substitute a handwritten object. Components handle registration/unregistration; the public coordinator type has no destroy method.

CominsTableTransferIntent

export type CominsTableTransferIntent<TData, TGroup> = {
    kind: "row";
    row: TData;
    sourceRowId: CominsRowId;
    sourceTableId: string;
    targetGroupId?: CominsRowId;
    targetRowId?: CominsRowId;
    targetTableId: string;
} | {
    group: TGroup;
    kind: "group";
    rows: readonly TData[];
    sourceGroupId: CominsRowId;
    sourceTableId: string;
    targetGroupId?: CominsRowId;
    targetTableId: string;
};

kind row carries the row/sourceRowId; kind group carries the group/member rows/sourceGroupId. Both table IDs are required; target row/group IDs depend on the destination.

CominsTableTransferConflict

export type CominsTableTransferConflict<TData, TGroup> = {
    kind: "row";
    rowId: CominsRowId;
    source: CominsTableTransferRowEndpoint<TData>;
    target: CominsTableTransferRowEndpoint<TData>;
} | {
    groupId: CominsRowId;
    kind: "group";
    source: CominsTableTransferGroupEndpoint<TData, TGroup>;
    target: CominsTableTransferGroupEndpoint<TData, TGroup>;
};

kind row compares source/target rows sharing rowId; group compares groups and their members sharing groupId.

CominsTableTransferConflictResolver

export type CominsTableTransferConflictResolver<TData, TGroup> = (conflict: CominsTableTransferConflict<TData, TGroup>) => CominsTableTransferConflictPolicy | undefined;

Synchronously returns reject/overwrite or undefined. undefined means reject.

CominsTableTransferRejection

export type CominsTableTransferRejection<TData, TGroup = never> = {
    conflict: CominsTableTransferConflict<TData, TGroup>;
    kind: "group" | "row";
    reason: "duplicate-id";
    sourceTableId: string;
    targetTableId: string;
};

reason is duplicate-id. conflict is the rejected conflict; kind denotes the transfer kind, distinct from the conflict kind.

tooltip?: {
        render?: (rejection: CominsTableTransferRejection<TData, TGroup>) => React.ReactNode;
    };

See the 0.2.2 migration guide for rendering precedence and return values.