gravity-dnd 1.1.6

package/README.md

@@ -0,0 +1,292 @@
+# Gravity - Stardust UI's drag-n-drop component.
+
+![Vercel Deploy](https://deploy-badge.vercel.app/vercel/gravity-dnd) ![Dynamic JSON Badge](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2Fandromika%2Fgravity-dnd%2Frefs%2Fheads%2Fmain%2Fpackage.json&query=%24.version&label=version)
+ **[>> Check the Demo](https://gravity-dnd.vercel.app/?path=/docs/gravity-librarydemo--docs)** 
+
+Originally created back in 2019 for [Pollux.gg](https://pollux.gg)'s Medal Picker from the profile
+ editor dashboard ([Original source](https://github.com/PolestarLabs/dashboard/blob/96cdfd6a8b49612c807a38230ab909aaf75ca944/src/views/dashboard/pages/profile_edit.pug)). Original was done in pure frontend Vue2
+ and Pug using [vuedraggable](https://www.npmjs.com/package/vuedraggable). 
+
+This package ports it over for more general use as a lightweight, composable
+drag-and-drop system for Vue 3.
+It has been redesigned for use in component libraries and applications where you want
+customizable drop targets, drag sources, and flexible collision behavior.
+
+Component structural styles are bundled with the Vue components. Visual color and border treatments are opt-in and come from the package stylesheet.
+
+```ts
+import 'gravity-dnd/styles.css';
+```
+
+*Renamed to **Gravity** to keep on-theme with all of other Pollux's side-libs and elements. Mainly its parent component lib: **Stardust UI***
+
+---
+
+## Core Concepts
+
+### GravityProvider
+Wrap any part of your app that uses drag/drop in a single `GravityProvider`.
+It provides context for all draggables, slots, and pools.
+
+```html
+<template>
+  <GravityProvider>
+    <!-- drag/drop components here -->
+  </GravityProvider>
+</template>
+
+<script setup>
+import 'gravity-dnd/styles.css';
+import { GravityProvider } from '@/ui/gravity';
+</script>
+```
+
+### GravityDraggable
+Represents a draggable item.
+
+Key props:
+- `draggable-id` (string): unique id for the drag instance
+- `item` (any): the data payload carried during drag
+- `source-id` (string): identifies the container the drag originates from
+- `source-kind` (`'pool' | 'slot' | 'custom'`): used for identifying what type of container a drag comes from
+- `source-index` (number): index within the container
+- `drop-mode` (`'target' | 'floating'`): controls whether drop is evaluated by hover targets or by pointer release
+
+Example:
+
+```html
+<GravityDraggable
+  draggable-id="draggable-1"
+  :item="item"
+  source-id="my-pool"
+  source-kind="pool"
+  :source-index="index"
+>
+  <template #default="{ dragging }">
+    <div :style="{ opacity:  dragging ? .9 : 1 }">{{ item.label }}</div>
+  </template>
+</GravityDraggable>
+```
+
+### GravitySlot
+A drop target that accepts one item at a time.
+It emits `drop` events when an item is dropped.
+
+Key props:
+- `slot-id` (string): unique identifier for the slot
+- `item` (any): current item in the slot (optional)
+- `onDropCollision` (`'replace' | 'swap' | 'reject'`): how to handle collisions when slot already contains an item
+- `accepts` (function): optional predicate to allow/reject drops based on item + source
+
+```html
+<GravitySlot
+  slot-id="my-slot"
+  :item="currentItem"
+  onDropCollision="swap"
+  :accepts="(item) => item.type === 'allowed'"
+  @drop="handleDrop"
+>
+  <template #default="{ hovering, accepting }">
+    <div :class="{ hover: hovering, accept: accepting }">
+      {{ currentItem ? currentItem.label : 'Drop here' }}
+    </div>
+  </template>
+</GravitySlot>
+```
+
+### GravityPool
+A container that supports reordering items within the pool and receiving items from other sources.
+
+Key events:
+- `@reorder` when items inside the pool are reordered
+- `@receive` when an item is dropped into the pool from another source
+
+```html
+<GravityPool pool-id="my-pool" :items="items" @reorder="onReorder" @receive="onReceive">
+  <template #item="{ item, index }">
+    <GravityDraggable
+      :draggable-id="`pool-${item.id}`"
+      :item="item"
+      source-id="my-pool"
+      source-kind="pool"
+      :source-index="index"
+    >
+      <template #default="{ dragging }">
+        <div :style="{ opacity:  dragging ? .9 : 1 }">{{ item.label }}</div>
+      </template>
+    </GravityDraggable>
+  </template>
+</GravityPool>
+```
+
+---
+
+## Collision Modes (`onDropCollision`)
+
+`GravitySlot` supports three collision behaviors when a drop occurs and the slot is already occupied:
+
+| Mode     | Behavior |
+|---------|----------|
+| `replace` | Overwrites the current slot item with the dropped item. The existing item is discarded. |
+| `swap`    | Swaps the dropped item with the existing slot item. The existing item is returned to the drag source. |
+| `reject`  | Prevents the drop. The dragged item is returned to its source container. |
+
+If `onDropCollision` is not configured, the component uses the older `swap` behavior when `swap=true`, otherwise `replace`.
+
+---
+
+## Drop event payload (for slots)
+
+Drop handlers receive a `GravitySlotDropEvent<TItem>` with the following shape:
+
+```ts
+interface GravitySlotDropEvent<TItem> {
+  draggableId: string;
+  item: TItem;
+  source: {
+    containerId: string;
+    kind: 'slot' | 'pool' | 'custom';
+    index: number;
+  };
+  target: {
+    kind: 'slot' | 'pool' | 'floating';
+    containerId: string | null;
+    index: number;
+  };
+  slotId: string;
+  swap: boolean;
+  collision: 'replace' | 'swap' | 'reject';
+  replacedItem?: TItem;
+}
+```
+
+- `collision`: the configured collision rule in effect.
+- `replacedItem`: the item that was in the slot prior to the drop (available for `swap`/`replace`).
+
+---
+
+## Extending / Customizing Behavior
+
+### Custom Accept Logic
+Use `accepts` to fine-tune which items can be dropped into a slot.
+
+```html
+<GravitySlot
+  slot-id="custom-slot"
+  :accepts="(item, { sourceContainerId }) => sourceContainerId === 'trusted-pool'"
+  @drop="onDrop"
+/>
+```
+
+### Custom Slot Rendering
+Use the slot scope values to render feedback:
+
+- `hovering`: whether the pointer is hovering the slot
+- `accepting`: whether the current drag is accepted
+
+```html
+<GravitySlot slot-id="styled-slot" @drop="onDrop">
+  <template #default="{ hovering, accepting }">
+    <div :class="{ 'hovering': hovering, 'accepting': accepting }">
+      <!-- custom status UI -->
+    </div>
+  </template>
+</GravitySlot>
+```
+
+### Extending drop logic in parent components
+Use event handlers to implement complex behavior (e.g., persistence, undo, analytics).
+
+```ts
+function handleSlotDrop(event: GravitySlotDropEvent<MyItem>) {
+  // apply app-specific rules
+  if (event.collision === 'swap') {
+    // maybe persist both items
+  }
+  updateLocalState(event);
+}
+```
+
+---
+
+## Use Cases
+
+### 1) Drag-to-slot with swap behavior
+- Use case: a single slot that accepts an item, but dropping another item should return the original back to its source.
+- Configure:
+  - `onDropCollision="swap"`
+
+### 2) Drag-to-slot with replace behavior
+- Use case: a slot that always accepts the newest item and discards the previous.
+- Configure:
+  - `onDropCollision="replace"` (or `swap=false`)
+
+### 3) Drop rejection based on slot fullness
+- Use case: only allow a drop when the slot is empty.
+- Configure:
+  - `onDropCollision="reject"`
+
+### 4) Ordered pool with receive/reorder
+- Use case: a list of draggable items where items can be reordered and new items can be dropped in.
+- Use `GravityPool` + `@reorder` + `@receive`.
+
+---
+
+## Quick Start (smallest sample)
+
+```html
+<template>
+  <GravityProvider>
+    <GravitySlot slot-id="target" onDropCollision="swap" @drop="onDrop">
+      <template #default="{ hovering, accepting }">
+        <div :style="{ background: hovering ? (accepting ? '#e0f7ff' : '#ffeaea') : '#fff' }">
+          Drop an item here
+        </div>
+      </template>
+    </GravitySlot>
+
+    <GravityPool pool-id="pool" :items="items" @receive="onReceive" @reorder="onReorder">
+      <template #item="{ item, index }">
+        <GravityDraggable
+          :draggable-id="`item-${item.id}`"
+          :item="item"
+          source-id="pool"
+          source-kind="pool"
+          :source-index="index"
+        >
+          <template #default="{ dragging }">
+            <div :style="{ opacity: dragging ? 0.3 : 1 }">{{ item.label }}</div>
+          </template>
+        </GravityDraggable>
+      </template>
+    </GravityPool>
+  </GravityProvider>
+</template>
+
+<script setup lang="ts">
+import 'gravity-dnd/styles.css';
+import { ref } from 'vue';
+import { GravityProvider, GravityPool, GravitySlot, GravityDraggable } from '@/ui/gravity';
+
+const items = ref([{ id: 'a', label: 'A' }, { id: 'b', label: 'B' }]);
+
+function onDrop(event) {
+  // handle drop
+}
+function onReceive(event) {
+  // handle received item
+}
+function onReorder(event) {
+  // handle reorder
+}
+</script>
+```
+
+---
+
+## Notes
+- This drag/drop system is intentionally lightweight and does not have built-in keyboard accessibility.
+- For production use, wrap drag-drop logic in safe state updates (avoid mutating arrays directly in complex UIs).
+- The `onDropCollision` API is designed for specific use-cases from Pollux.gg's dashboard, its implementation might be a bit stiff.
+- Better mobile support is planned for future iterations
+- React support is being considered.

package/index.ts

@@ -0,0 +1,19 @@
+export { default as GravityProvider } from './src/components/Draggable/DragDropProvider.vue';
+export { default as GravityDraggable } from './src/components/Draggable/Draggable.vue';
+export { default as GravitySlot } from './src/components/Slot/Slot.vue';
+export { default as GravityPool } from './src/components/Pool/Pool.vue';
+
+export type {
+  GravityBoundary,
+  GravityCanDragContext,
+  GravityContainerKind,
+  GravityDropEvent,
+  GravityDropTarget,
+  GravityDraggableDropEvent,
+  GravityHoverTarget,
+  GravityMode,
+  GravityPoolReceiveEvent,
+  GravityPoolReorderEvent,
+  GravitySlotDropEvent,
+  GravitySource,
+} from './src/components/Draggable/contracts';

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "gravity-dnd",
+  "private": false,
+  "version": "1.1.6",
+  "type": "module",
+  "authors": [
+    {
+      "name": "L Reis / Flicky / Andromika",
+      "email": "github@amarok.com"
+    },
+    {
+      "name": "Polestar Labs",
+      "email": "hello@pollux.gg"
+    }
+  ],
+  "description": "A Vue 3 drag-and-drop component library.",
+  "exports": {
+    ".": "./index.ts",
+    "./styles.css": "./styles.css",
+    "./styles.scss": "./styles.scss"
+  },
+  "scripts": {
+    "start": "npm run storybook -- --ci --port 6007",
+    "build": "npm run build:storybook",
+    "build-storybook": "npm run build:storybook",
+    "storybook": "storybook dev -p 6007 --ci",
+    "build:storybook": "storybook build --output-dir dist",
+    "lint": "eslint . --ext .ts,.tsx,.vue",
+    "preview": "vite preview"
+  },
+  "keywords": [
+    "vue",
+    "dnd",
+    "drag-and-drop",
+    "component-library"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "vue": "^3.4.0"
+  },
+  "devDependencies": {
+    "@storybook/addon-a11y": "^10.2.19",
+    "@storybook/addon-docs": "^10.2.19",
+    "@storybook/builder-vite": "^10.2.19",
+    "@storybook/vue3-vite": "^10.2.19",
+    "@vitejs/plugin-vue": "^6.0.5",
+    "@vue/compiler-sfc": "^3.4.0",
+    "chromatic": "^15.3.0",
+    "eslint": "^8.0.0",
+    "eslint-plugin-storybook": "10.2.19",
+    "eslint-plugin-vue": "^9.0.0",
+    "prismjs": "^1.29.0",
+    "pug": "^3.0.4",
+    "pug-plain-loader": "^1.1.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "sass-embedded": "^1.98.0",
+    "storybook": "^10.2.19",
+    "typescript": "^5.0.0",
+    "vite": "^8.0.0",
+    "vite-plugin-dts": "^4.0.0"
+  }
+}

package/src/Gravity.stories.ts

@@ -0,0 +1,207 @@
+import type { Meta, StoryObj } from '@storybook/vue3-vite';
+import { ref } from 'vue';
+import docs from '../README.md?raw';
+import {
+  GravityDraggable,
+  GravityPool,
+  GravityProvider,
+  GravitySlot,
+  type GravityPoolReceiveEvent,
+  type GravityPoolReorderEvent,
+  type GravitySlotDropEvent,
+} from '../index';
+
+interface DemoItem {
+  id: string;
+  label: string;
+}
+
+const meta: Meta = {
+  title: 'Gravity/LibraryDemo',
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component: docs,
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Playground: Story = {
+  render: () => ({
+    setup() {
+      const loose = ref<DemoItem | null>({ id: 'loose', label: 'Loose Token' });
+      const slotItem = ref<DemoItem | null>(null);
+      const pool = ref<DemoItem[]>([
+        { id: 'pool-a', label: 'A' },
+        { id: 'pool-b', label: 'B' },
+        { id: 'pool-c', label: 'C' },
+      ]);
+
+      function takeFromSource(sourceContainerId: string, sourceIndex: number): DemoItem | null {
+        if (sourceContainerId === 'pool-main') {
+          const [moved] = pool.value.splice(sourceIndex, 1);
+          return moved || null;
+        }
+        if (sourceContainerId === 'slot-main') {
+          const moved = slotItem.value;
+          slotItem.value = null;
+          return moved;
+        }
+        if (sourceContainerId === 'loose-main') {
+          const moved = loose.value;
+          loose.value = null;
+          return moved;
+        }
+        return null;
+      }
+
+      function putIntoSource(sourceContainerId: string, sourceIndex: number, item: DemoItem) {
+        if (sourceContainerId === 'pool-main') {
+          const insertIndex = Math.max(0, Math.min(sourceIndex, pool.value.length));
+          pool.value.splice(insertIndex, 0, item);
+          return;
+        }
+        if (sourceContainerId === 'slot-main') {
+          slotItem.value = item;
+          return;
+        }
+        if (sourceContainerId === 'loose-main') {
+          loose.value = item;
+          return;
+        }
+      }
+
+      function onSlotDrop(event: GravitySlotDropEvent<unknown>) {
+        const moved = takeFromSource(event.source.containerId, event.source.index);
+        if (!moved) return;
+
+        // Handle collision rules (replace / swap / reject)
+        if (event.collision === 'reject') {
+          // Put the moved item back into the source
+          putIntoSource(event.source.containerId, event.source.index, moved);
+          return;
+        }
+
+        const existing = slotItem.value;
+        slotItem.value = moved;
+
+        if (event.collision === 'swap' && event.replacedItem) {
+          putIntoSource(event.source.containerId, event.source.index, event.replacedItem as DemoItem);
+        }
+      }
+
+      function onPoolReorder(event: GravityPoolReorderEvent<unknown>) {
+        if (event.fromIndex === event.toIndex) return;
+        const [moved] = pool.value.splice(event.fromIndex, 1);
+        if (!moved) return;
+        let insertIndex = event.toIndex;
+        if (event.fromIndex < event.toIndex) insertIndex -= 1;
+        pool.value.splice(Math.max(0, Math.min(insertIndex, pool.value.length)), 0, moved as DemoItem);
+      }
+
+      function onPoolReceive(event: GravityPoolReceiveEvent<unknown>) {
+        const moved = takeFromSource(event.source.containerId, event.source.index);
+        if (!moved) return;
+        const insertIndex = Math.max(0, Math.min(event.insertIndex, pool.value.length));
+        pool.value.splice(insertIndex, 0, moved);
+      }
+
+      return {
+        loose,
+        slotItem,
+        pool,
+        onSlotDrop,
+        onPoolReorder,
+        onPoolReceive,
+      };
+    },
+    components: { GravityProvider, GravityDraggable, GravitySlot, GravityPool },
+    template: `
+      <div style="width: 640px; max-width: 96vw; font-family: system-ui, sans-serif;">
+        <GravityProvider>
+          <div style="display: grid; gap: 16px;">
+            <div style="display: grid; grid-template-columns: 1fr 1fr; gap: 12px;">
+              <div>
+                <div style="font-size: 13px; font-weight: 600; margin-bottom: 8px;">Loose Draggable</div>
+                <GravityDraggable
+                  v-if="loose"
+                  draggable-id="gravity-loose-item"
+                  :item="loose"
+                  source-id="loose-main"
+                  source-kind="custom"
+                  :source-index="0"
+                >
+                  <template #default="{ dragging }">
+                    <div
+                      :style="{
+                        display: 'inline-flex',
+                        padding: '8px 12px',
+                        borderRadius: '8px',
+                        border: '1px solid #d1d5db',
+                        background: '#f9fafb',
+                        opacity:  dragging ? .9 : 1
+                      }"
+                    >
+                      {{ loose.label }}
+                    </div>
+                  </template>
+                </GravityDraggable>
+              </div>
+
+              <div>
+                <div style="font-size: 13px; font-weight: 600; margin-bottom: 8px;">Slot</div>
+                <GravitySlot slot-id="slot-main" :item="slotItem" onDropCollision="swap" @drop="onSlotDrop">
+                  <template #default="{ hovering, accepting }">
+                    <div
+                      style="min-height: 54px; border-radius: 8px; border: 1px solid #d1d5db; display: flex; align-items: center; justify-content: center;"
+                      :style="{ background: hovering ? (accepting ? '#ecfeff' : '#fff1f2') : '#fff' }"
+                    >
+                      {{ slotItem ? slotItem.label : 'Drop here' }}
+                    </div>
+                  </template>
+                </GravitySlot>
+              </div>
+            </div>
+
+            <div>
+              <div style="font-size: 13px; font-weight: 600; margin-bottom: 8px;">Pool (reorder + receive)</div>
+              <GravityPool pool-id="pool-main" :items="pool" @reorder="onPoolReorder" @receive="onPoolReceive">
+                <template #item="{ item, index }">
+                  <GravityDraggable
+                    :draggable-id="'gravity-pool-item-' + item.id"
+                    :item="item"
+                    source-id="pool-main"
+                    source-kind="pool"
+                    :source-index="index"
+                  >
+                    <template #default="{ dragging }">
+                      <div
+                        :style="{
+                          padding: '6px 10px',
+                          minWidth: '56px',
+                          textAlign: 'center',
+                          borderRadius: '6px',
+                          border: '1px solid #d1d5db',
+                          background: '#f9fafb',
+                          opacity:  dragging ? .9 : 1
+                        }"
+                      >
+                        {{ item.label }}
+                      </div>
+                    </template>
+                  </GravityDraggable>
+                </template>
+              </GravityPool>
+            </div>
+          </div>
+        </GravityProvider>
+      </div>
+    `,
+  }),
+};

package/src/components/DragAndDrop/DragAndDrop.scss

@@ -0,0 +1,4 @@
+.st-profile-medalpicker2-dnd {
+  position: relative;
+  user-select: none;
+}