Skip to main content

cardProjection

PRO

The functionality is available in PRO Edition only. The MIT edition accepts the prop and ignores it.

Lets users drag HTML elements from outside the widget onto the board. The app handles the native drag events and the final add-card call. The widget resolves the drop position and shows the drop placeholder there.

Usage​

cardProjection?: CardProjection | null;

Default: null

type CardProjection = {
htmlEvent: { clientX: number; clientY: number } | null;
card: Partial<KanbanCard>;
target?: CardProjectionTarget | null; // written by the widget
};

type CardProjectionTarget = {
column: ColumnID;
swimlane?: SwimlaneID;
before: CardID | null; // null = end of the destination cell
};

CardProjection:

FieldTypeDescription
htmlEvent{ clientX: number; clientY: number } | nullPointer position of the latest dragover. null before the pointer reaches the board
cardPartial<KanbanCard>Card data to add on drop. The widget writes the destination column and swimlane into it through the accessors
targetCardProjectionTarget | nullDrop position resolved by the widget. null when the pointer isn't over an expanded, rendered card cell

CardProjectionTarget:

FieldTypeDescription
columnColumnIDDestination column
swimlaneSwimlaneIDDestination swimlane, on boards with swimlanes
beforeCardID | nullCard to insert before. null means the end of the cell

Both types are exported from @svar-ui/svelte-kanban.

Details​

The descriptor goes through four steps:

  1. On dragstart, set { htmlEvent: null, card }. Leave out the source item's id, so Kanban generates the card id.
  2. On every dragover of the wrapper element, replace the descriptor with { ...cardProjection, htmlEvent: event } and call preventDefault(). The widget reads only clientX and clientY. It never touches DataTransfer.
  3. After each change, the widget resolves the point with the same hit testing as internal card drag. It then writes target and the destination membership into card. It may replace the card object, so read cardProjection.card on drop.
  4. On drop, if target isn't null, call exec("add-card", { card: cardProjection.card, before: cardProjection.target.before }) and set the prop back to null. Clear it on dragend too.

target is null over column headers, gutters, collapsed columns or lanes, and other boards.

The preview never changes data. It hides no card and shows no drag ghost. An internal card drag takes precedence over the projection preview. The widget doesn't autoscroll during an external drag.

readonly doesn't block a projection. For a full lock, leave cardProjection unset and skip the add-card call.

A drop is one add-card action: one onaddcard event and one history step. Sorting may change the visible position of the new card. The standard RestDataProvider sends only the card data, so it doesn't save the position.

Example​

<script lang="ts">
import { Kanban, type CardProjection } from "@svar-ui/svelte-kanban";

let { cards, columns, task } = $props();
let api;
let cardProjection = $state<CardProjection | null>(null);

const dragStart = task =>
(cardProjection = { htmlEvent: null, card: { label: task.text } });

function dragOver(event: DragEvent) {
if (!cardProjection) return;
cardProjection = { ...cardProjection, htmlEvent: event };
event.preventDefault();
}

function drop(event: DragEvent) {
if (!api || !cardProjection?.target) return;
event.preventDefault();
api.exec("add-card", {
card: cardProjection.card,
before: cardProjection.target.before,
});
cardProjection = null;
}
</script>

<div ondragover={dragOver} ondrop={drop}>
<div
draggable="true"
ondragstart={() => dragStart(task)}
ondragend={() => (cardProjection = null)}
>
{task.text}
</div>
<Kanban bind:this={api} {cards} {columns} {cardProjection} />
</div>