@urbanstudio/ua-sortable 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+All notable changes to `@urbanstudio/ua-sortable` will be documented in this file.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [1.0.0] — 2026-06-05
+
+### Added
+- Initial release
+- `UA_Sortable` class with full API (options, callbacks, instance + static methods)
+- Pointer Events based drag (mouse, touch, stylus — no separate handling)
+- `direction: "auto"` — detects `flex-direction` via `getComputedStyle`
+- Cross-list drag via `group` option
+- `confirm` callback for cross-list drops with async support
+- `onSort`, `onMove`, `onDragStart`, `onDragEnd` callbacks
+- `handle`, `filter`, `delay`, `delayOnTouchOnly` options
+- `UA_Sortable.get()`, `getGroup()`, `snapshot()` static methods
+- `UA_Sortable.initAll()` and `UA_Sortable.observe()` for declarative HTML API
+- `data-ua-sortable` attribute + `data-sortable-*` attributes for HTML init
+- `uaMakeSortable()` shorthand function
+- Auto-injected minimal CSS (`ua-sortable-ghost`, `ua-drag-handle`, etc.)
+- MutationObserver on container for auto-refresh on child changes
+- ESM build (`src/Sortable.js`) + IIFE/CJS build (`dist/ua-sortable.js`)

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marian Feiler, urbanstudio GmbH (https://urbanstudio.de)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,254 @@
+# ua-sortable
+
+**Pointer-Events-based drag-and-drop sorting for lists and grids.**  
+No dependencies. No jQuery. No CDN required. Pure browser APIs.
+
+[![npm](https://img.shields.io/npm/v/@urbanstudio/ua-sortable)](https://www.npmjs.com/package/@urbanstudio/ua-sortable)
+[![license](https://img.shields.io/npm/l/@urbanstudio/ua-sortable)](LICENSE)
+[![CDN](https://img.shields.io/badge/CDN-jsDelivr-orange)](https://cdn.jsdelivr.net/npm/@urbanstudio/ua-sortable/src/Sortable.js)
+
+---
+
+## What it does
+
+`UA_Sortable` makes any list or grid container sortable by drag-and-drop using native [Pointer Events](https://developer.mozilla.org/en-US/docs/Web/API/Pointer_events). Works with mouse, touch, and stylus — no special handling needed.
+
+```
+ua-sortable run myList
+```
+
+That is: one line to get a sortable list, one callback to persist the order, zero dependencies.
+
+---
+
+## Install
+
+**npm:**
+```sh
+npm install @urbanstudio/ua-sortable
+```
+
+**CDN (jsDelivr — ESM):**
+```html
+<script type="module">
+  import { UA_Sortable } from "https://cdn.jsdelivr.net/npm/@urbanstudio/ua-sortable/src/Sortable.js";
+</script>
+```
+
+**CDN (jsDelivr — browser global `<script>`):**
+```html
+<script src="https://cdn.jsdelivr.net/npm/@urbanstudio/ua-sortable/dist/ua-sortable.js"></script>
+```
+
+**CDN (unpkg):**
+```html
+<script src="https://unpkg.com/@urbanstudio/ua-sortable/dist/ua-sortable.js"></script>
+```
+
+---
+
+## Quick start
+
+```js
+import { UA_Sortable } from "@urbanstudio/ua-sortable";
+
+new UA_Sortable(document.querySelector("ul"), {
+    handle:    ".drag-handle",
+    animation: 150,
+    onSort:    (ids) => console.log("new order:", ids),
+});
+```
+
+Or with the shorthand:
+```js
+import { uaMakeSortable } from "@urbanstudio/ua-sortable";
+
+const sortable = uaMakeSortable(document.querySelector("ul"), {
+    handle: ".drag-handle",
+});
+```
+
+Or declarative HTML — auto-initialized by `UA_Sortable.observe()`:
+```html
+<ul data-ua-sortable data-sortable-handle=".drag-handle" data-sortable-group="tasks">
+  <li data-id="1">Item 1 <span class="drag-handle">⠿</span></li>
+  <li data-id="2">Item 2 <span class="drag-handle">⠿</span></li>
+</ul>
+
+<script type="module">
+  import { UA_Sortable } from "@urbanstudio/ua-sortable";
+  UA_Sortable.observe(document.body);
+</script>
+```
+
+---
+
+## Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `handle` | `string\|null` | `null` | CSS selector for drag handle. `null` = whole item is draggable. |
+| `filter` | `string\|null` | `null` | CSS selector for items excluded from drag. |
+| `group` | `string\|null` | `null` | Group name for cross-list drag. |
+| `direction` | `string` | `"auto"` | `"vertical"`, `"horizontal"`, or `"auto"` (reads `flex-direction`). |
+| `animation` | `number` | `150` | Ghost transition duration in ms. `0` = disabled. |
+| `dataIdAttr` | `string` | `"data-id"` | Attribute used to identify items in callbacks. |
+| `delay` | `number` | `0` | ms before drag starts after pointerdown. |
+| `delayOnTouchOnly` | `boolean` | `false` | Apply `delay` only for touch input. |
+| `disabled` | `boolean` | `false` | Disable drag on this instance. |
+| `ghostClass` | `string` | `"ua-sortable-ghost"` | Class added to the ghost clone. |
+| `dragClass` | `string` | `"ua-sortable-drag"` | Class added to the dragged item. |
+| `confirm` | `function\|null` | `null` | `(movedId, from, to) => Promise<bool>` — called before cross-list drop. Return `false` to cancel. |
+| `onDragStart` | `function\|null` | `null` | `(el)` — drag begins. |
+| `onDragEnd` | `function\|null` | `null` | `(el, didMove: bool)` — drag ends. |
+| `onSort` | `function\|null` | `null` | `(ids[], container)` — order changed within same list. |
+| `onMove` | `function\|null` | `null` | `(movedId, from, to, fromIds[], toIds[]) => bool\|Promise<bool>` — item moved to other list. |
+
+---
+
+## Instance methods
+
+| Method | Description |
+|--------|-------------|
+| `toArray()` | IDs of all draggable children in current DOM order. |
+| `enable()` | Enable drag. |
+| `disable()` | Disable drag. |
+| `refresh()` | Re-scan draggable children (after manual DOM changes). |
+| `destroy()` | Remove all listeners, disconnect observers, unregister. |
+| `option(name)` | Get option value. |
+| `option(name, value)` | Set option value at runtime. |
+
+---
+
+## Static methods
+
+| Method | Description |
+|--------|-------------|
+| `UA_Sortable.get(el)` | Instance for a container element. |
+| `UA_Sortable.getGroup(name)` | All instances with this group name. |
+| `UA_Sortable.snapshot(group?)` | `[{container, ids, group}]` — current order of all grouped instances. |
+| `UA_Sortable.initAll(root?)` | Initialize all `[data-ua-sortable]` in `root`. |
+| `UA_Sortable.observe(root)` | MutationObserver — auto-init new `[data-ua-sortable]` containers. |
+
+---
+
+## Cross-list drag
+
+Containers sharing the same `group` name accept each other's items:
+
+```js
+const opts = {
+    group: "tasks",
+    onMove: (id, from, to, fromIds, toIds) => {
+        api.moveTask(id, to.dataset.listId);
+    },
+};
+new UA_Sortable(document.querySelector("#todo"),  opts);
+new UA_Sortable(document.querySelector("#doing"), opts);
+new UA_Sortable(document.querySelector("#done"),  opts);
+```
+
+With a confirmation dialog before cross-list drop:
+```js
+new UA_Sortable(el, {
+    group: "rooms",
+    confirm: async (id, from, to) => confirm(`Move item to "${to.dataset.label}"?`),
+    onMove:  (id, from, to) => api.moveToSection(id, to.dataset.sectionId),
+});
+```
+
+---
+
+## Snapshot
+
+```js
+// Read current order of all containers in a group
+const state = UA_Sortable.snapshot("tasks");
+// [{ container: HTMLElement, ids: ["id1", "id2"], group: "tasks" }, ...]
+
+state.forEach(({ container, ids }) => {
+    api.saveOrder(container.dataset.listId, ids);
+});
+```
+
+---
+
+## CSS
+
+Minimal styles are **injected automatically** on first use — no stylesheet to include.
+
+```css
+.ua-sortable-ghost      { opacity: .4; }
+.ua-sortable-drag       { opacity: .4; }
+.ua-drag-handle         { cursor: grab; touch-action: none; }
+.ua-drag-handle:active  { cursor: grabbing; }
+```
+
+The drop indicator uses `--accent` (CSS custom property) with fallback `#2563eb`.  
+Override any of these in your own stylesheet.
+
+---
+
+## HTML attributes
+
+When using `UA_Sortable.observe()` or `UA_Sortable.initAll()`:
+
+| Attribute | Option |
+|-----------|--------|
+| `data-ua-sortable` | triggers init |
+| `data-sortable-handle` | `handle` |
+| `data-sortable-filter` | `filter` |
+| `data-sortable-group` | `group` |
+| `data-sortable-direction` | `direction` |
+| `data-sortable-animation` | `animation` |
+| `data-sortable-delay` | `delay` |
+
+---
+
+## Browser support
+
+Pointer Events: Chrome 55+, Firefox 59+, Safari 13+, Edge 79+.  
+No polyfills required.
+
+---
+
+## Design principles
+
+`ua-sortable` tries to stay small and predictable.
+
+It does not try to replace SortableJS.  
+It does not try to support IE11.  
+It does not ship a bundler, a build step, or a runtime dependency.
+
+It simply:
+1. listens for pointer events
+2. moves a placeholder element as you drag
+3. calls your callback with the new order
+
+For everything else, use the `onMove` / `onSort` callbacks.
+
+---
+
+## License
+
+MIT License
+
+Copyright (c) 2026 Marian Feiler, [urbanstudio GmbH](https://urbanstudio.de)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/ua-sortable.js

@@ -0,0 +1,356 @@
+/**
+ * UA_Sortable v1.0.0 — IIFE build (browser global)
+ * Pointer-Events-based drag-and-drop sorting. No dependencies.
+ *
+ * @author  Marian Feiler <mf@urbanstudio.de>
+ * @company urbanstudio GmbH — https://urbanstudio.de
+ * @license MIT
+ * @see     https://github.com/urbanstudioGmbH/ua-sortable
+ *
+ * Usage:
+ *   <script src="ua-sortable.js"></script>
+ *   <script>
+ *     new UA_Sortable(document.querySelector("ul"), { handle: ".drag-handle" });
+ *     // or shorthand:
+ *     uaMakeSortable(document.querySelector("ul"), { handle: ".drag-handle" });
+ *   </script>
+ */
+(function (global, factory) {
+    "use strict";
+    if (typeof module !== "undefined" && module.exports) {
+        // CommonJS / Node (no DOM, only class export)
+        module.exports = factory();
+    } else {
+        // Browser global
+        const exports = factory();
+        global.UA_Sortable   = exports.UA_Sortable;
+        global.uaMakeSortable = exports.uaMakeSortable;
+    }
+})(typeof globalThis !== "undefined" ? globalThis : typeof window !== "undefined" ? window : this, function () {
+    "use strict";
+
+    class UA_Sortable {
+
+        static #instanceRegistry = new WeakMap();
+        static #groupRegistry    = new Map();
+        static #globalObserver   = null;
+
+        #containerElement        = null;
+        #options                 = {};
+        #draggableElements       = [];
+        #ghostElement            = null;
+        #draggedElement          = null;
+        #placeholderElement      = null;
+        #sourceContainerElement  = null;
+        #currentContainerElement = null;
+        #pointerStartX           = 0;
+        #pointerStartY           = 0;
+        #delayTimer              = null;
+        #isDragging              = false;
+        #childObserver           = null;
+        #boundHandlePointerDown   = null;
+        #boundHandlePointerMove   = null;
+        #boundHandlePointerUp     = null;
+        #boundHandlePointerCancel = null;
+
+        constructor(containerElement, options = {}) {
+            if (!(containerElement instanceof HTMLElement)) {
+                throw new Error("UA_Sortable: first argument must be an HTMLElement");
+            }
+            if (UA_Sortable.#instanceRegistry.has(containerElement)) {
+                UA_Sortable.#instanceRegistry.get(containerElement).destroy();
+            }
+            this.#containerElement = containerElement;
+            this.#options = {
+                handle: null, filter: null, group: null, direction: "auto",
+                animation: 150, dataIdAttr: "data-id", delay: 0,
+                delayOnTouchOnly: false, disabled: false,
+                ghostClass: "ua-sortable-ghost", dragClass: "ua-sortable-drag",
+                confirm: null, onDragStart: null, onDragEnd: null,
+                onSort: null, onMove: null,
+                ...options,
+            };
+            this.#boundHandlePointerDown   = this.#handlePointerDown.bind(this);
+            this.#boundHandlePointerMove   = this.#handlePointerMove.bind(this);
+            this.#boundHandlePointerUp     = this.#handlePointerUp.bind(this);
+            this.#boundHandlePointerCancel = this.#handlePointerCancel.bind(this);
+            this.#registerInGlobals();
+            this.#attachContainerListeners();
+            this.#observeChildChanges();
+            this.#refreshDraggableList();
+        }
+
+        toArray() {
+            return this.#getDraggableChildren().map(el => el.getAttribute(this.#options.dataIdAttr) ?? "");
+        }
+        enable()  { this.option("disabled", false); }
+        disable() { this.option("disabled", true);  }
+        refresh() { this.#refreshDraggableList(); }
+        destroy() {
+            this.#detachContainerListeners();
+            this.#childObserver?.disconnect();
+            this.#childObserver = null;
+            this.#cleanupDragState();
+            this.#unregisterFromGlobals();
+        }
+        option(name, value = undefined) {
+            if (value === undefined) return this.#options[name];
+            this.#options[name] = value;
+            if (name === "filter" || name === "handle") this.#refreshDraggableList();
+        }
+
+        static get(containerElement) {
+            return UA_Sortable.#instanceRegistry.get(containerElement) ?? null;
+        }
+        static getGroup(groupName) {
+            return [...(UA_Sortable.#groupRegistry.get(groupName) ?? [])];
+        }
+        static snapshot(groupName = null) {
+            let instances;
+            if (groupName !== null) {
+                instances = UA_Sortable.getGroup(groupName);
+            } else {
+                instances = [];
+                UA_Sortable.#groupRegistry.forEach(g => instances.push(...g));
+            }
+            return instances.map(i => ({ container: i.#containerElement, ids: i.toArray(), group: i.#options.group }));
+        }
+        static initAll(root = document) {
+            root.querySelectorAll("[data-ua-sortable]").forEach(el => {
+                if (!UA_Sortable.#instanceRegistry.has(el)) UA_Sortable.#initFromDataAttributes(el);
+            });
+        }
+        static observe(root) {
+            if (UA_Sortable.#globalObserver) UA_Sortable.#globalObserver.disconnect();
+            UA_Sortable.#globalObserver = new MutationObserver(mutations => {
+                for (const m of mutations) {
+                    for (const node of m.addedNodes) {
+                        if (!(node instanceof HTMLElement)) continue;
+                        if (node.hasAttribute("data-ua-sortable") && !UA_Sortable.#instanceRegistry.has(node)) {
+                            UA_Sortable.#initFromDataAttributes(node);
+                        }
+                        node.querySelectorAll("[data-ua-sortable]").forEach(el => {
+                            if (!UA_Sortable.#instanceRegistry.has(el)) UA_Sortable.#initFromDataAttributes(el);
+                        });
+                    }
+                }
+            });
+            UA_Sortable.#globalObserver.observe(root, { childList: true, subtree: true });
+        }
+
+        static #initFromDataAttributes(el) {
+            const d = el.dataset, o = {};
+            if (d.sortableHandle    !== undefined) o.handle     = d.sortableHandle;
+            if (d.sortableFilter    !== undefined) o.filter     = d.sortableFilter;
+            if (d.sortableGroup     !== undefined) o.group      = d.sortableGroup;
+            if (d.sortableDirection !== undefined) o.direction  = d.sortableDirection;
+            if (d.sortableAnimation !== undefined) o.animation  = parseInt(d.sortableAnimation, 10);
+            if (d.sortableDataIdAttr!== undefined) o.dataIdAttr = d.sortableDataIdAttr;
+            if (d.sortableDelay     !== undefined) o.delay      = parseInt(d.sortableDelay, 10);
+            new UA_Sortable(el, o);
+        }
+        #registerInGlobals() {
+            UA_Sortable.#instanceRegistry.set(this.#containerElement, this);
+            const g = this.#options.group;
+            if (g) {
+                if (!UA_Sortable.#groupRegistry.has(g)) UA_Sortable.#groupRegistry.set(g, new Set());
+                UA_Sortable.#groupRegistry.get(g).add(this);
+            }
+        }
+        #unregisterFromGlobals() {
+            UA_Sortable.#instanceRegistry.delete(this.#containerElement);
+            const g = this.#options.group;
+            if (g && UA_Sortable.#groupRegistry.has(g)) UA_Sortable.#groupRegistry.get(g).delete(this);
+        }
+        #attachContainerListeners() {
+            this.#containerElement.addEventListener("pointerdown", this.#boundHandlePointerDown);
+        }
+        #detachContainerListeners() {
+            this.#containerElement.removeEventListener("pointerdown", this.#boundHandlePointerDown);
+            document.removeEventListener("pointermove",   this.#boundHandlePointerMove);
+            document.removeEventListener("pointerup",     this.#boundHandlePointerUp);
+            document.removeEventListener("pointercancel", this.#boundHandlePointerCancel);
+        }
+        #observeChildChanges() {
+            this.#childObserver = new MutationObserver(() => this.#refreshDraggableList());
+            this.#childObserver.observe(this.#containerElement, { childList: true });
+        }
+        #refreshDraggableList() { this.#draggableElements = this.#getDraggableChildren(); }
+        #getDraggableChildren() {
+            const c = [...this.#containerElement.children];
+            return this.#options.filter ? c.filter(el => !el.matches(this.#options.filter)) : c;
+        }
+        #handlePointerDown(e) {
+            if (this.#options.disabled) return;
+            if (e.button !== 0 && e.pointerType === "mouse") return;
+            const dragged = this.#findDraggableParent(e.target);
+            if (!dragged) return;
+            if (this.#options.filter && dragged.matches(this.#options.filter)) return;
+            if (this.#options.handle) {
+                const h = e.target.closest(this.#options.handle);
+                if (!h || !dragged.contains(h)) return;
+            }
+            this.#pointerStartX = e.clientX;
+            this.#pointerStartY = e.clientY;
+            const delay = this.#options.delay > 0 && (!this.#options.delayOnTouchOnly || e.pointerType === "touch");
+            if (delay) {
+                this.#delayTimer = setTimeout(() => this.#startDrag(e, dragged), this.#options.delay);
+                const cancel = mv => {
+                    if (Math.hypot(mv.clientX - this.#pointerStartX, mv.clientY - this.#pointerStartY) > 5) {
+                        clearTimeout(this.#delayTimer);
+                        document.removeEventListener("pointermove", cancel);
+                    }
+                };
+                document.addEventListener("pointermove", cancel);
+            } else {
+                this.#startDrag(e, dragged);
+            }
+        }
+        #startDrag(e, dragged) {
+            this.#isDragging = true;
+            this.#draggedElement = dragged;
+            this.#sourceContainerElement = this.#containerElement;
+            this.#currentContainerElement = this.#containerElement;
+            const r = dragged.getBoundingClientRect();
+            this.#ghostElement = dragged.cloneNode(true);
+            this.#ghostElement.classList.add(this.#options.ghostClass);
+            this.#ghostElement.style.cssText = `position:fixed;left:${r.left}px;top:${r.top}px;width:${r.width}px;height:${r.height}px;margin:0;pointer-events:none;z-index:9999;`;
+            document.body.appendChild(this.#ghostElement);
+            this.#placeholderElement = document.createElement(dragged.tagName);
+            this.#placeholderElement.style.cssText = `width:${r.width}px;height:${r.height}px;opacity:0;pointer-events:none;`;
+            dragged.parentNode.insertBefore(this.#placeholderElement, dragged);
+            dragged.classList.add(this.#options.dragClass);
+            dragged.style.opacity = "0.001";
+            this.#containerElement.classList.add("ua-sortable-active");
+            try { dragged.setPointerCapture(e.pointerId); } catch (_) {}
+            document.addEventListener("pointermove",   this.#boundHandlePointerMove);
+            document.addEventListener("pointerup",     this.#boundHandlePointerUp);
+            document.addEventListener("pointercancel", this.#boundHandlePointerCancel);
+            this.#options.onDragStart?.(dragged);
+        }
+        #handlePointerMove(e) {
+            if (!this.#isDragging) return;
+            const dx = e.clientX - this.#pointerStartX, dy = e.clientY - this.#pointerStartY;
+            const or = this.#draggedElement.getBoundingClientRect();
+            this.#ghostElement.style.left = `${or.left + dx}px`;
+            this.#ghostElement.style.top  = `${or.top  + dy}px`;
+            const tc = this.#findTargetContainer(e.clientX, e.clientY);
+            if (tc && tc !== this.#currentContainerElement) {
+                this.#currentContainerElement.classList.remove("ua-sortable-active");
+                tc.classList.add("ua-sortable-active");
+                this.#currentContainerElement = tc;
+            }
+            this.#updatePlaceholderPosition(e.clientX, e.clientY);
+        }
+        #handlePointerUp()     { if (this.#isDragging) this.#finalizeDrop(); }
+        #handlePointerCancel() { if (this.#isDragging) this.#revertDrag(); }
+        async #finalizeDrop() {
+            const dragged = this.#draggedElement;
+            const src = this.#sourceContainerElement;
+            const tgt = this.#currentContainerElement;
+            const moved = src !== tgt;
+            if (moved && this.#options.confirm) {
+                const ok = await Promise.resolve(this.#options.confirm(dragged.getAttribute(this.#options.dataIdAttr), src, tgt));
+                if (!ok) { this.#revertDrag(); return; }
+            }
+            tgt.insertBefore(dragged, this.#placeholderElement);
+            this.#cleanupDragState();
+            const id  = dragged.getAttribute(this.#options.dataIdAttr);
+            const ids = UA_Sortable.get(tgt)?.toArray() ?? [...tgt.children]
+                .filter(el => el !== this.#placeholderElement && (!this.#options.filter || !el.matches(this.#options.filter)))
+                .map(el => el.getAttribute(this.#options.dataIdAttr) ?? "");
+            if (moved) {
+                const srcIds = UA_Sortable.get(src)?.toArray() ?? [];
+                const ok = await this.#invokeOnMove(id, src, tgt, srcIds, ids);
+                if (ok === false) { src.appendChild(dragged); this.#options.onDragEnd?.(dragged, false); return; }
+            } else {
+                this.#options.onSort?.(ids, tgt);
+            }
+            this.#options.onDragEnd?.(dragged, true);
+        }
+        #revertDrag() {
+            if (this.#placeholderElement?.parentNode) {
+                this.#placeholderElement.parentNode.insertBefore(this.#draggedElement, this.#placeholderElement);
+            }
+            const d = this.#draggedElement;
+            this.#cleanupDragState();
+            this.#options.onDragEnd?.(d, false);
+        }
+        async #invokeOnMove(id, from, to, fromIds, toIds) {
+            if (!this.#options.onMove) return true;
+            return await Promise.resolve(this.#options.onMove(id, from, to, fromIds, toIds)) !== false;
+        }
+        #cleanupDragState() {
+            this.#ghostElement?.remove();
+            this.#placeholderElement?.remove();
+            if (this.#draggedElement) {
+                this.#draggedElement.classList.remove(this.#options.dragClass);
+                this.#draggedElement.style.opacity = "";
+            }
+            this.#containerElement.classList.remove("ua-sortable-active");
+            if (this.#currentContainerElement && this.#currentContainerElement !== this.#containerElement) {
+                this.#currentContainerElement.classList.remove("ua-sortable-active");
+            }
+            clearTimeout(this.#delayTimer);
+            document.removeEventListener("pointermove",   this.#boundHandlePointerMove);
+            document.removeEventListener("pointerup",     this.#boundHandlePointerUp);
+            document.removeEventListener("pointercancel", this.#boundHandlePointerCancel);
+            this.#ghostElement = this.#placeholderElement = this.#draggedElement =
+            this.#sourceContainerElement = this.#currentContainerElement = this.#delayTimer = null;
+            this.#isDragging = false;
+        }
+        #updatePlaceholderPosition(px, py) {
+            const tc = this.#currentContainerElement;
+            const children = [...tc.children].filter(c =>
+                c !== this.#draggedElement && c !== this.#ghostElement &&
+                c !== this.#placeholderElement &&
+                (!this.#options.filter || !c.matches(this.#options.filter))
+            );
+            const dir = this.#resolveDirection(tc);
+            let before = null;
+            for (const s of children) {
+                const sr  = s.getBoundingClientRect();
+                const mid = dir === "horizontal" ? sr.left + sr.width / 2 : sr.top + sr.height / 2;
+                if ((dir === "horizontal" ? px : py) < mid) { before = s; break; }
+            }
+            before ? tc.insertBefore(this.#placeholderElement, before) : tc.appendChild(this.#placeholderElement);
+        }
+        #resolveDirection(el) {
+            if (this.#options.direction !== "auto") return this.#options.direction;
+            const fd = getComputedStyle(el).flexDirection;
+            return (fd === "row" || fd === "row-reverse") ? "horizontal" : "vertical";
+        }
+        #findDraggableParent(el) {
+            let c = el;
+            while (c && c !== this.#containerElement) {
+                if (c.parentElement === this.#containerElement) return c;
+                c = c.parentElement;
+            }
+            return null;
+        }
+        #findTargetContainer(px, py) {
+            const g = this.#options.group;
+            if (!g) return this.#containerElement;
+            for (const inst of UA_Sortable.getGroup(g)) {
+                if (inst === this || inst.#options.disabled) continue;
+                const r = inst.#containerElement.getBoundingClientRect();
+                if (px >= r.left && px <= r.right && py >= r.top && py <= r.bottom) return inst.#containerElement;
+            }
+            return this.#containerElement;
+        }
+    }
+
+    // Inject minimal CSS
+    if (typeof document !== "undefined" && !document.getElementById("ua-sortable-styles")) {
+        const s = document.createElement("style");
+        s.id = "ua-sortable-styles";
+        s.textContent = ".ua-sortable-ghost{opacity:.4;}.ua-sortable-drag{opacity:.4;}.ua-sortable-active>.ua-sortable-over{border-top:2px solid var(--accent,#2563eb);}.ua-drag-handle{cursor:grab;touch-action:none;}.ua-drag-handle:active{cursor:grabbing;}";
+        document.head.appendChild(s);
+    }
+
+    function uaMakeSortable(el, options = {}) {
+        return new UA_Sortable(el, options);
+    }
+
+    return { UA_Sortable, uaMakeSortable };
+});

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@urbanstudio/ua-sortable",
+  "version": "1.0.0",
+  "description": "Pointer-Events-based drag-and-drop sorting for lists and grids. No dependencies.",
+  "author": "Marian Feiler <mf@urbanstudio.de> (https://urbanstudio.de)",
+  "license": "MIT",
+  "homepage": "https://github.com/urbanstudioGmbH/ua-sortable#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/urbanstudioGmbH/ua-sortable.git"
+  },
+  "bugs": {
+    "url": "https://github.com/urbanstudioGmbH/ua-sortable/issues"
+  },
+  "type": "module",
+  "main": "./dist/ua-sortable.js",
+  "module": "./src/Sortable.js",
+  "exports": {
+    ".": {
+      "import": "./src/Sortable.js",
+      "require": "./dist/ua-sortable.js"
+    },
+    "./dist": "./dist/ua-sortable.js"
+  },
+  "files": [
+    "src/",
+    "dist/",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "keywords": [
+    "drag-and-drop",
+    "sortable",
+    "sort",
+    "reorder",
+    "drag",
+    "pointer-events",
+    "touch",
+    "es6-module",
+    "zero-dependency",
+    "vanilla-js",
+    "list",
+    "grid"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=14"
+  }
+}

package/src/Sortable.js

@@ -0,0 +1,583 @@
+"use strict";
+
+/**
+ * UA_Sortable — Pointer-Events-based drag-and-drop sorting for lists and grids.
+ * No dependencies — no jQuery, no CDN, no external frameworks.
+ * Supports: simple sorting, cross-list groups, auto-direction, filter, delay.
+ *
+ * @author  Marian Feiler <mf@urbanstudio.de>
+ * @company urbanstudio GmbH — https://urbanstudio.de
+ * @license MIT
+ * @see     https://github.com/urbanstudioGmbH/ua-sortable
+ */
+export class UA_Sortable {
+
+    // --- Global registries ---
+    static #instanceRegistry = new WeakMap();   // containerElement → UA_Sortable
+    static #groupRegistry    = new Map();        // groupName → Set<UA_Sortable>
+    static #globalObserver   = null;
+
+    // --- Internal drag state ---
+    #containerElement        = null;
+    #options                 = {};
+    #draggableElements       = [];
+    #ghostElement            = null;
+    #draggedElement          = null;
+    #placeholderElement      = null;
+    #sourceContainerElement  = null;
+    #currentContainerElement = null;
+    #pointerStartX           = 0;
+    #pointerStartY           = 0;
+    #delayTimer              = null;
+    #isDragging              = false;
+    #childObserver           = null;
+
+    // Bound handler references for clean removeEventListener
+    #boundHandlePointerDown   = null;
+    #boundHandlePointerMove   = null;
+    #boundHandlePointerUp     = null;
+    #boundHandlePointerCancel = null;
+
+    /**
+     * @param {HTMLElement} containerElement
+     * @param {object} options
+     */
+    constructor(containerElement, options = {}) {
+        if (!(containerElement instanceof HTMLElement)) {
+            throw new Error("UA_Sortable: first argument must be an HTMLElement");
+        }
+        if (UA_Sortable.#instanceRegistry.has(containerElement)) {
+            UA_Sortable.#instanceRegistry.get(containerElement).destroy();
+        }
+
+        this.#containerElement = containerElement;
+        this.#options = {
+            handle:           null,
+            filter:           null,
+            group:            null,
+            direction:        "auto",
+            animation:        150,
+            dataIdAttr:       "data-id",
+            delay:            0,
+            delayOnTouchOnly: false,
+            disabled:         false,
+            ghostClass:       "ua-sortable-ghost",
+            dragClass:        "ua-sortable-drag",
+            confirm:          null,
+            onDragStart:      null,
+            onDragEnd:        null,
+            onSort:           null,
+            onMove:           null,
+            ...options,
+        };
+
+        this.#boundHandlePointerDown   = this.#handlePointerDown.bind(this);
+        this.#boundHandlePointerMove   = this.#handlePointerMove.bind(this);
+        this.#boundHandlePointerUp     = this.#handlePointerUp.bind(this);
+        this.#boundHandlePointerCancel = this.#handlePointerCancel.bind(this);
+
+        this.#registerInGlobals();
+        this.#attachContainerListeners();
+        this.#observeChildChanges();
+        this.#refreshDraggableList();
+    }
+
+    // =========================================================================
+    // PUBLIC API — Instance methods
+    // =========================================================================
+
+    /** Returns IDs of all draggable children in current DOM order. */
+    toArray() {
+        return this.#getDraggableChildren().map(el => el.getAttribute(this.#options.dataIdAttr) ?? "");
+    }
+
+    /** Enable dragging. */
+    enable() {
+        this.option("disabled", false);
+    }
+
+    /** Disable dragging. */
+    disable() {
+        this.option("disabled", true);
+    }
+
+    /** Re-scan draggable children and filtered elements. */
+    refresh() {
+        this.#refreshDraggableList();
+    }
+
+    /** Remove all listeners and observers, delete from global registry. */
+    destroy() {
+        this.#detachContainerListeners();
+        this.#childObserver?.disconnect();
+        this.#childObserver = null;
+        this.#cleanupDragState();
+        this.#unregisterFromGlobals();
+    }
+
+    /**
+     * Get or set an option at runtime.
+     * @param {string} name
+     * @param {*} [value]
+     */
+    option(name, value = undefined) {
+        if (value === undefined) return this.#options[name];
+        this.#options[name] = value;
+        if (name === "filter" || name === "handle") this.#refreshDraggableList();
+    }
+
+    // =========================================================================
+    // PUBLIC API — Static methods
+    // =========================================================================
+
+    /** Returns the UA_Sortable instance for a container element. */
+    static get(containerElement) {
+        return UA_Sortable.#instanceRegistry.get(containerElement) ?? null;
+    }
+
+    /** Returns all instances registered under a group name. */
+    static getGroup(groupName) {
+        return [...(UA_Sortable.#groupRegistry.get(groupName) ?? [])];
+    }
+
+    /**
+     * Returns a snapshot of current order for all grouped instances.
+     * @param {string} [groupName] — if omitted, all grouped instances
+     * @returns {{ container: HTMLElement, ids: string[], group: string|null }[]}
+     */
+    static snapshot(groupName = null) {
+        let instances;
+        if (groupName !== null) {
+            instances = UA_Sortable.getGroup(groupName);
+        } else {
+            instances = [];
+            UA_Sortable.#groupRegistry.forEach(groupSet => instances.push(...groupSet));
+        }
+        return instances.map(instance => ({
+            container: instance.#containerElement,
+            ids:       instance.toArray(),
+            group:     instance.#options.group,
+        }));
+    }
+
+    /**
+     * Initialize all [data-ua-sortable] containers within root.
+     * @param {HTMLElement|Document} [root=document]
+     */
+    static initAll(root = document) {
+        root.querySelectorAll("[data-ua-sortable]").forEach(containerElement => {
+            if (!UA_Sortable.#instanceRegistry.has(containerElement)) {
+                UA_Sortable.#initFromDataAttributes(containerElement);
+            }
+        });
+    }
+
+    /**
+     * Start a MutationObserver that auto-initializes new [data-ua-sortable] containers.
+     * @param {HTMLElement|Document} root
+     */
+    static observe(root) {
+        if (UA_Sortable.#globalObserver) UA_Sortable.#globalObserver.disconnect();
+        UA_Sortable.#globalObserver = new MutationObserver(mutationList => {
+            for (const mutation of mutationList) {
+                for (const addedNode of mutation.addedNodes) {
+                    if (!(addedNode instanceof HTMLElement)) continue;
+                    if (addedNode.hasAttribute("data-ua-sortable")) {
+                        UA_Sortable.#initFromDataAttributes(addedNode);
+                    }
+                    addedNode.querySelectorAll("[data-ua-sortable]").forEach(el => {
+                        if (!UA_Sortable.#instanceRegistry.has(el)) {
+                            UA_Sortable.#initFromDataAttributes(el);
+                        }
+                    });
+                }
+            }
+        });
+        UA_Sortable.#globalObserver.observe(root, { childList: true, subtree: true });
+    }
+
+    // =========================================================================
+    // PRIVATE — Initialization
+    // =========================================================================
+
+    static #initFromDataAttributes(containerElement) {
+        const dataset = containerElement.dataset;
+        const options = {};
+        if (dataset.sortableHandle    !== undefined) options.handle     = dataset.sortableHandle;
+        if (dataset.sortableFilter    !== undefined) options.filter     = dataset.sortableFilter;
+        if (dataset.sortableGroup     !== undefined) options.group      = dataset.sortableGroup;
+        if (dataset.sortableDirection !== undefined) options.direction  = dataset.sortableDirection;
+        if (dataset.sortableAnimation !== undefined) options.animation  = parseInt(dataset.sortableAnimation, 10);
+        if (dataset.sortableDataIdAttr!== undefined) options.dataIdAttr = dataset.sortableDataIdAttr;
+        if (dataset.sortableDelay     !== undefined) options.delay      = parseInt(dataset.sortableDelay, 10);
+        new UA_Sortable(containerElement, options);
+    }
+
+    #registerInGlobals() {
+        UA_Sortable.#instanceRegistry.set(this.#containerElement, this);
+        const groupName = this.#options.group;
+        if (groupName) {
+            if (!UA_Sortable.#groupRegistry.has(groupName)) {
+                UA_Sortable.#groupRegistry.set(groupName, new Set());
+            }
+            UA_Sortable.#groupRegistry.get(groupName).add(this);
+        }
+    }
+
+    #unregisterFromGlobals() {
+        UA_Sortable.#instanceRegistry.delete(this.#containerElement);
+        const groupName = this.#options.group;
+        if (groupName && UA_Sortable.#groupRegistry.has(groupName)) {
+            UA_Sortable.#groupRegistry.get(groupName).delete(this);
+        }
+    }
+
+    #attachContainerListeners() {
+        this.#containerElement.addEventListener("pointerdown", this.#boundHandlePointerDown);
+    }
+
+    #detachContainerListeners() {
+        this.#containerElement.removeEventListener("pointerdown", this.#boundHandlePointerDown);
+        document.removeEventListener("pointermove",   this.#boundHandlePointerMove);
+        document.removeEventListener("pointerup",     this.#boundHandlePointerUp);
+        document.removeEventListener("pointercancel", this.#boundHandlePointerCancel);
+    }
+
+    #observeChildChanges() {
+        this.#childObserver = new MutationObserver(() => this.#refreshDraggableList());
+        this.#childObserver.observe(this.#containerElement, { childList: true });
+    }
+
+    #refreshDraggableList() {
+        this.#draggableElements = this.#getDraggableChildren();
+    }
+
+    #getDraggableChildren() {
+        const children = [...this.#containerElement.children];
+        if (!this.#options.filter) return children;
+        return children.filter(child => !child.matches(this.#options.filter));
+    }
+
+    // =========================================================================
+    // PRIVATE — Pointer event handlers
+    // =========================================================================
+
+    #handlePointerDown(pointerEvent) {
+        if (this.#options.disabled) return;
+        if (pointerEvent.button !== 0 && pointerEvent.pointerType === "mouse") return;
+
+        const draggedElement = this.#findDraggableParent(pointerEvent.target);
+        if (!draggedElement) return;
+
+        if (this.#options.filter && draggedElement.matches(this.#options.filter)) return;
+
+        if (this.#options.handle) {
+            const handleElement = pointerEvent.target.closest(this.#options.handle);
+            if (!handleElement || !draggedElement.contains(handleElement)) return;
+        }
+
+        this.#pointerStartX = pointerEvent.clientX;
+        this.#pointerStartY = pointerEvent.clientY;
+
+        const shouldDelay = this.#options.delay > 0 &&
+            (!this.#options.delayOnTouchOnly || pointerEvent.pointerType === "touch");
+
+        if (shouldDelay) {
+            this.#delayTimer = setTimeout(() => {
+                this.#startDrag(pointerEvent, draggedElement);
+            }, this.#options.delay);
+            const cancelDelay = (moveEvent) => {
+                const distance = Math.hypot(
+                    moveEvent.clientX - this.#pointerStartX,
+                    moveEvent.clientY - this.#pointerStartY
+                );
+                if (distance > 5) {
+                    clearTimeout(this.#delayTimer);
+                    document.removeEventListener("pointermove", cancelDelay);
+                }
+            };
+            document.addEventListener("pointermove", cancelDelay, { once: false });
+        } else {
+            this.#startDrag(pointerEvent, draggedElement);
+        }
+    }
+
+    #startDrag(pointerEvent, draggedElement) {
+        this.#isDragging              = true;
+        this.#draggedElement          = draggedElement;
+        this.#sourceContainerElement  = this.#containerElement;
+        this.#currentContainerElement = this.#containerElement;
+
+        const boundingRect = draggedElement.getBoundingClientRect();
+        this.#ghostElement = draggedElement.cloneNode(true);
+        this.#ghostElement.classList.add(this.#options.ghostClass);
+        this.#ghostElement.style.cssText = [
+            "position:fixed",
+            `left:${boundingRect.left}px`,
+            `top:${boundingRect.top}px`,
+            `width:${boundingRect.width}px`,
+            `height:${boundingRect.height}px`,
+            "margin:0",
+            "pointer-events:none",
+            "z-index:9999",
+        ].join(";");
+        document.body.appendChild(this.#ghostElement);
+
+        this.#placeholderElement = document.createElement(draggedElement.tagName);
+        this.#placeholderElement.style.cssText = [
+            `width:${boundingRect.width}px`,
+            `height:${boundingRect.height}px`,
+            "opacity:0",
+            "pointer-events:none",
+        ].join(";");
+        draggedElement.parentNode.insertBefore(this.#placeholderElement, draggedElement);
+
+        draggedElement.classList.add(this.#options.dragClass);
+        draggedElement.style.opacity = "0.001";
+
+        this.#containerElement.classList.add("ua-sortable-active");
+
+        try { draggedElement.setPointerCapture(pointerEvent.pointerId); } catch (_) {}
+
+        document.addEventListener("pointermove",   this.#boundHandlePointerMove);
+        document.addEventListener("pointerup",     this.#boundHandlePointerUp);
+        document.addEventListener("pointercancel", this.#boundHandlePointerCancel);
+
+        this.#options.onDragStart?.(draggedElement);
+    }
+
+    #handlePointerMove(pointerEvent) {
+        if (!this.#isDragging) return;
+
+        const deltaX = pointerEvent.clientX - this.#pointerStartX;
+        const deltaY = pointerEvent.clientY - this.#pointerStartY;
+
+        const originalRect = this.#draggedElement.getBoundingClientRect();
+        this.#ghostElement.style.left = `${originalRect.left + deltaX}px`;
+        this.#ghostElement.style.top  = `${originalRect.top  + deltaY}px`;
+
+        const targetContainer = this.#findTargetContainer(pointerEvent.clientX, pointerEvent.clientY);
+        if (targetContainer && targetContainer !== this.#currentContainerElement) {
+            this.#currentContainerElement.classList.remove("ua-sortable-active");
+            targetContainer.classList.add("ua-sortable-active");
+            this.#currentContainerElement = targetContainer;
+        }
+
+        this.#updatePlaceholderPosition(pointerEvent.clientX, pointerEvent.clientY);
+    }
+
+    #handlePointerUp() {
+        if (!this.#isDragging) return;
+        this.#finalizeDrop();
+    }
+
+    #handlePointerCancel() {
+        if (!this.#isDragging) return;
+        this.#revertDrag();
+    }
+
+    // =========================================================================
+    // PRIVATE — Drop logic
+    // =========================================================================
+
+    async #finalizeDrop() {
+        const draggedElement         = this.#draggedElement;
+        const sourceContainerElement = this.#sourceContainerElement;
+        const targetContainerElement = this.#currentContainerElement;
+        const didChangeContainer     = sourceContainerElement !== targetContainerElement;
+
+        if (didChangeContainer && this.#options.confirm !== null) {
+            const confirmFunction = this.#options.confirm;
+            const confirmed = await Promise.resolve(
+                confirmFunction(
+                    draggedElement.getAttribute(this.#options.dataIdAttr),
+                    sourceContainerElement,
+                    targetContainerElement
+                )
+            );
+            if (!confirmed) {
+                this.#revertDrag();
+                return;
+            }
+        }
+
+        targetContainerElement.insertBefore(draggedElement, this.#placeholderElement);
+        this.#cleanupDragState();
+
+        const movedId          = draggedElement.getAttribute(this.#options.dataIdAttr);
+        const orderedTargetIds = UA_Sortable.get(targetContainerElement)?.toArray()
+            ?? [...targetContainerElement.children]
+                .filter(el => el !== this.#placeholderElement && (!this.#options.filter || !el.matches(this.#options.filter)))
+                .map(el => el.getAttribute(this.#options.dataIdAttr) ?? "");
+
+        if (didChangeContainer) {
+            const sourceInstance   = UA_Sortable.get(sourceContainerElement);
+            const orderedSourceIds = sourceInstance?.toArray() ?? [];
+
+            const shouldProceed = await this.#invokeOnMove(
+                movedId,
+                sourceContainerElement,
+                targetContainerElement,
+                orderedSourceIds,
+                orderedTargetIds
+            );
+            if (shouldProceed === false) {
+                sourceContainerElement.appendChild(draggedElement);
+                this.#options.onDragEnd?.(draggedElement, false);
+                return;
+            }
+        } else {
+            this.#options.onSort?.(orderedTargetIds, targetContainerElement);
+        }
+
+        this.#options.onDragEnd?.(draggedElement, true);
+    }
+
+    #revertDrag() {
+        if (this.#placeholderElement?.parentNode) {
+            this.#placeholderElement.parentNode.insertBefore(
+                this.#draggedElement,
+                this.#placeholderElement
+            );
+        }
+        const draggedElement = this.#draggedElement;
+        this.#cleanupDragState();
+        this.#options.onDragEnd?.(draggedElement, false);
+    }
+
+    async #invokeOnMove(movedId, fromContainer, toContainer, orderedFromIds, orderedToIds) {
+        if (!this.#options.onMove) return true;
+        const result = await Promise.resolve(
+            this.#options.onMove(movedId, fromContainer, toContainer, orderedFromIds, orderedToIds)
+        );
+        return result !== false;
+    }
+
+    #cleanupDragState() {
+        this.#ghostElement?.remove();
+        this.#placeholderElement?.remove();
+
+        if (this.#draggedElement) {
+            this.#draggedElement.classList.remove(this.#options.dragClass);
+            this.#draggedElement.style.opacity = "";
+        }
+
+        this.#containerElement.classList.remove("ua-sortable-active");
+        if (this.#currentContainerElement && this.#currentContainerElement !== this.#containerElement) {
+            this.#currentContainerElement.classList.remove("ua-sortable-active");
+        }
+
+        clearTimeout(this.#delayTimer);
+        document.removeEventListener("pointermove",   this.#boundHandlePointerMove);
+        document.removeEventListener("pointerup",     this.#boundHandlePointerUp);
+        document.removeEventListener("pointercancel", this.#boundHandlePointerCancel);
+
+        this.#ghostElement            = null;
+        this.#placeholderElement      = null;
+        this.#draggedElement          = null;
+        this.#sourceContainerElement  = null;
+        this.#currentContainerElement = null;
+        this.#isDragging              = false;
+        this.#delayTimer              = null;
+    }
+
+    // =========================================================================
+    // PRIVATE — Position & direction calculation
+    // =========================================================================
+
+    #updatePlaceholderPosition(pointerX, pointerY) {
+        const targetContainer = this.#currentContainerElement;
+        const children = [...targetContainer.children].filter(child =>
+            child !== this.#draggedElement &&
+            child !== this.#ghostElement &&
+            child !== this.#placeholderElement &&
+            (!this.#options.filter || !child.matches(this.#options.filter))
+        );
+
+        const direction = this.#resolveDirection(targetContainer);
+        let insertBeforeElement = null;
+
+        for (const sibling of children) {
+            const siblingRect     = sibling.getBoundingClientRect();
+            const siblingMidpoint = direction === "horizontal"
+                ? siblingRect.left + siblingRect.width  / 2
+                : siblingRect.top  + siblingRect.height / 2;
+            const pointerPosition = direction === "horizontal" ? pointerX : pointerY;
+
+            if (pointerPosition < siblingMidpoint) {
+                insertBeforeElement = sibling;
+                break;
+            }
+        }
+
+        if (insertBeforeElement) {
+            targetContainer.insertBefore(this.#placeholderElement, insertBeforeElement);
+        } else {
+            targetContainer.appendChild(this.#placeholderElement);
+        }
+    }
+
+    #resolveDirection(containerElement) {
+        if (this.#options.direction !== "auto") return this.#options.direction;
+        const flexDirection = getComputedStyle(containerElement).flexDirection;
+        return (flexDirection === "row" || flexDirection === "row-reverse")
+            ? "horizontal"
+            : "vertical";
+    }
+
+    #findDraggableParent(targetElement) {
+        let current = targetElement;
+        while (current && current !== this.#containerElement) {
+            if (current.parentElement === this.#containerElement) return current;
+            current = current.parentElement;
+        }
+        return null;
+    }
+
+    #findTargetContainer(pointerX, pointerY) {
+        const groupName = this.#options.group;
+        if (!groupName) return this.#containerElement;
+
+        const groupInstances = UA_Sortable.getGroup(groupName);
+        for (const instance of groupInstances) {
+            if (instance === this) continue;
+            if (instance.#options.disabled) continue;
+            const containerRect = instance.#containerElement.getBoundingClientRect();
+            if (
+                pointerX >= containerRect.left &&
+                pointerX <= containerRect.right &&
+                pointerY >= containerRect.top  &&
+                pointerY <= containerRect.bottom
+            ) {
+                return instance.#containerElement;
+            }
+        }
+        return this.#containerElement;
+    }
+}
+
+// --- Inject minimal CSS once ---
+(function injectUASortableCSS() {
+    if (typeof document === "undefined") return;
+    if (document.getElementById("ua-sortable-styles")) return;
+    const style = document.createElement("style");
+    style.id = "ua-sortable-styles";
+    style.textContent = [
+        ".ua-sortable-ghost{opacity:.4;}",
+        ".ua-sortable-drag{opacity:.4;}",
+        ".ua-sortable-active>.ua-sortable-over{border-top:2px solid var(--accent,#2563eb);}",
+        ".ua-drag-handle{cursor:grab;touch-action:none;}",
+        ".ua-drag-handle:active{cursor:grabbing;}",
+    ].join("");
+    document.head.appendChild(style);
+})();
+
+/**
+ * Shorthand: make a container element sortable.
+ * @param {HTMLElement} el
+ * @param {object} [options]
+ * @returns {UA_Sortable}
+ */
+export function uaMakeSortable(el, options = {}) {
+    return new UA_Sortable(el, options);
+}