cardProjection
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:
| Field | Type | Description |
|---|---|---|
htmlEvent | { clientX: number; clientY: number } | null | Pointer position of the latest dragover. null before the pointer reaches the board |
card | Partial<KanbanCard> | Card data to add on drop. The widget writes the destination column and swimlane into it through the accessors |
target | CardProjectionTarget | null | Drop position resolved by the widget. null when the pointer isn't over an expanded, rendered card cell |
CardProjectionTarget:
| Field | Type | Description |
|---|---|---|
column | ColumnID | Destination column |
swimlane | SwimlaneID | Destination swimlane, on boards with swimlanes |
before | CardID | null | Card to insert before. null means the end of the cell |
Both types are exported from @svar-ui/vue-kanban.
Details
The descriptor goes through four steps:
- On
dragstart, set{ htmlEvent: null, card }. Leave out the source item'sid, so Kanban generates the card id. - On every
dragoverof the wrapper element, replace the descriptor with{ ...cardProjection, htmlEvent: event }and callpreventDefault(). The widget reads onlyclientXandclientY. It never touchesDataTransfer. - After each change, the widget resolves the point with the same hit testing as internal card drag. It then writes
targetand the destination membership intocard. It may replace thecardobject, so readcardProjection.cardon drop. - On
drop, iftargetisn'tnull, callexec("add-card", { card: cardProjection.card, before: cardProjection.target.before })and set the prop back tonull. Clear it ondragendtoo.
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 setup lang="ts">
import { ref } from "vue";
import { Kanban, type CardProjection } from "@svar-ui/vue-kanban";
const props = defineProps({
cards: {},
columns: {},
task: {},
});
const api = ref(null);
const cardProjection = ref<CardProjection | null>(null);
const dragStart = (task) =>
(cardProjection.value = { htmlEvent: null, card: { label: task.text } });
function dragOver(event: DragEvent) {
if (!cardProjection.value) return;
cardProjection.value = { ...cardProjection.value, htmlEvent: event };
event.preventDefault();
}
function drop(event: DragEvent) {
if (!api.value || !cardProjection.value?.target) return;
event.preventDefault();
api.value.exec("add-card", {
card: cardProjection.value.card,
before: cardProjection.value.target.before,
});
cardProjection.value = null;
}
</script>
<template>
<div @dragover="dragOver" @drop="drop">
<div
draggable="true"
@dragstart="dragStart(task)"
@dragend="cardProjection = null"
>
{{ task.text }}
</div>
<Kanban
ref="api"
:cards="cards"
:columns="columns"
:cardProjection="cardProjection"
/>
</div>
</template>