@tapestry-ui/sortable 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Brandon Minton
+
+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

@@ -1,3 +1,114 @@
-# Temporary Holding Version
+# @tapestry-ui/sortable
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Reordering by hand, for Preact. **Headless: you render, it reorders.**
+
+Part of [Tapestry UI](https://github.com/ryurage/brandonminton). Extracted from a
+kanban board where the touch behaviour was worked out the hard way.
+
+```bash
+npm i @tapestry-ui/sortable
+```
+
+```tsx
+import { useSortable } from '@tapestry-ui/sortable';
+import '@tapestry-ui/sortable/styles.css'; // two rules, both behavioural
+
+const sortable = useSortable({ ids, onReorder: setIds, labelOf, onAnnounce: setSaid });
+
+<ul>
+  {ids.map((id) => (
+    <li key={id} {...sortable.itemProps(id)}
+        class={sortable.dragging === id ? 'tui-sortable__item--lifted' : undefined}>
+      <span {...sortable.gripProps}>⠿</span>
+      {label(id)}
+      <button onClick={() => sortable.moveBy(id, -1)}>up</button>
+    </li>
+  ))}
+</ul>
+<p role="status" aria-live="polite">{said}</p>
+```
+
+## Three ways to move the same item
+
+One is never enough.
+
+| | How |
+|---|---|
+| **Mouse / pen** | press anywhere on the item and drag |
+| **Touch** | press **the grip** and drag |
+| **Keyboard / button** | `moveBy(id, ±1)` |
+
+**A finger only drags from the grip, and that is the whole design.** A list you
+cannot scroll is worse than a list you cannot reorder, so a finger anywhere else
+must scroll the page. A mouse has no competing gesture, so it drags from
+anywhere.
+
+The keyboard path is not a fallback — it is the one that works one-handed, and
+the one a screen reader can follow. **Every move announces the same way, however
+it was made**, so wire `onAnnounce` to a live region and all three are equal.
+
+## Two things that are easy to get wrong
+
+**The drag is held in a ref, not in state.** A `pointerup` can arrive in the same
+frame as the last `pointermove`, before any re-render — and a handler created
+during render would close over a stale `null` and silently drop the drop. This
+package was shipped with that bug for about an hour; the test that caught it
+dispatches move and up with no await between them, which is the realistic case.
+
+**`touch-action: none` on the grip is behaviour, not decoration.** Without it the
+browser claims the gesture for scrolling and `pointermove` stops arriving. It is
+in `styles.css`, along with `pointer-events: none` for the lifted item — without
+*that*, `elementFromPoint` keeps finding the thing being dragged instead of the
+thing underneath it.
+
+## API
+
+```ts
+useSortable({
+  ids: string[],                       // the order; the hook holds no state of its own
+  onReorder: (ids: string[]) => void,
+  disabled?: boolean,
+  labelOf?: (id: string) => string,    // for announcements; defaults to the id
+  onAnnounce?: (message: string) => void,
+  threshold?: number,                  // px before a press is a drag (default 4)
+  gripSelector?: string,               // default '[data-sortable-grip]'
+  ignoreSelector?: string,             // default 'input, button, select, textarea, a, [data-no-drag]'
+}) => {
+  dragging: string | null,             // lifted item, once past the threshold
+  overId: string | null,               // what it is over, for a placeholder
+  offset: { dx, dy },                  // for a transform
+  itemProps(id),                       // spread onto each item
+  gripProps,                           // spread onto the grip
+  moveBy(id, step),
+}
+```
+
+The pure parts are exported and are where the logic actually lives:
+`reorder(ids, id, index)`, `nudge(ids, id, step)`, `dropOn(ids, id, overId)`.
+Each returns **the same array** when nothing moves, so a consumer can skip the
+write.
+
+Escape always abandons a drag, including one the pointer never returned from.
+
+## Testing against it
+
+jsdom implements no Pointer Events, and that bites in a non-obvious way: Preact
+picks an event's registered name with `name.toLowerCase() in dom`, so without
+`onpointerdown` on the element it registers `"PointerDown"` — capital P — and a
+dispatched `"pointerdown"` never arrives. Declare the handler properties first:
+
+```ts
+for (const name of ['onpointerdown', 'onpointermove', 'onpointerup', 'onpointercancel']) {
+  if (!(name in HTMLElement.prototype)) {
+    Object.defineProperty(HTMLElement.prototype, name, { value: null, writable: true });
+  }
+}
+HTMLElement.prototype.setPointerCapture ??= function () {};
+```
+
+You will also want to stub `document.elementFromPoint`, which is how the drop
+target is found and which jsdom cannot answer without layout.
+
+## License
+
+MIT © Brandon Minton

package/dist/sortable.d.ts

@@ -0,0 +1,74 @@
+import { type JSX } from 'preact';
+export interface Drag {
+    id: string;
+    /** The one pointer that owns this drag; a second finger is ignored. */
+    pointerId: number;
+    startX: number;
+    startY: number;
+    dx: number;
+    dy: number;
+    /** Item the pointer is currently over, or null when it is over nothing. */
+    overId: string | null;
+}
+/**
+ * Everything this hook says out loud. Functions rather than templates, because
+ * a string with a placeholder in it cannot pluralise: "1 item" / "2 items" is an
+ * English rule, and Polish has three forms. The target language decides.
+ */
+export interface SortableStrings {
+    moved: (label: string, position: number, total: number) => string;
+    alreadyFirst: (label: string) => string;
+    alreadyLast: (label: string) => string;
+    cancelled: string;
+}
+export declare const EN_SORTABLE: SortableStrings;
+export interface SortableOptions {
+    /** The order, as ids. This is the single source of truth; the hook holds none. */
+    ids: string[];
+    /** The new order, when a move happens. */
+    onReorder: (ids: string[]) => void;
+    disabled?: boolean;
+    /** Human-readable name for an id, used in announcements. Defaults to the id. */
+    labelOf?: (id: string) => string;
+    /** Said after every move, however it was made. Wire it to a live region. */
+    onAnnounce?: (message: string) => void;
+    /** Replace any of the words this hook says. Defaults are English. */
+    strings?: Partial<SortableStrings>;
+    threshold?: number;
+    gripSelector?: string;
+    ignoreSelector?: string;
+}
+/** Move the item with `id` to `index`, clamped. Pure, so it is the testable part. */
+export declare function reorder(ids: string[], id: string, index: number): string[];
+/** Nudge an item by `step` places. Off either end is a no-op, never a wrap. */
+export declare function nudge(ids: string[], id: string, step: number): string[];
+/** Put `id` directly where `overId` sits — what a drop means. */
+export declare function dropOn(ids: string[], id: string, overId: string): string[];
+type Spreadable = Omit<JSX.HTMLAttributes<HTMLElement>, 'ref'>;
+/** What goes on an item's root: the drag handlers plus the id the drop lookup reads. */
+export type ItemProps = Spreadable & {
+    'data-sortable-id': string;
+};
+/** What goes on the grip: the marker the touch rule looks for. */
+export type GripProps = Spreadable & {
+    'data-sortable-grip': true;
+};
+export interface Sortable {
+    /** The lifted item, or null. Only set once the press has travelled far enough. */
+    dragging: string | null;
+    /** Item the lifted one is currently over, for drawing a placeholder. */
+    overId: string | null;
+    /** How far the lifted item has travelled, for a transform. */
+    offset: {
+        dx: number;
+        dy: number;
+    };
+    /** Spread onto each item's root element. */
+    itemProps: (id: string) => ItemProps;
+    /** Spread onto the grip inside an item — the only place a finger may drag from. */
+    gripProps: GripProps;
+    /** Move by keyboard or a button. Announces, like every other path. */
+    moveBy: (id: string, step: number) => void;
+}
+export declare function useSortable(options: SortableOptions): Sortable;
+export {};

package/dist/sortable.js

@@ -0,0 +1,167 @@
+// @tapestry-ui/sortable — reordering by hand (Tapestry UI citizen #7).
+//
+// Extracted from the kanban board's editor, where the touch behaviour was
+// worked out the hard way: a finger anywhere on a card has to scroll the page,
+// because a list you cannot scroll is worse than a list you cannot reorder. So
+// TOUCH DRAGS ONLY FROM A GRIP. A mouse or pen drags from anywhere, because a
+// mouse has no competing gesture.
+//
+// Headless, like the rest: this hook never renders anything. It hands you props
+// to spread and tells you what is lifted and what it is over; the markup, the
+// placeholder and every pixel of styling are yours.
+//
+// THREE WAYS TO MOVE THE SAME ITEM, because one is never enough:
+//   mouse/pen  — press anywhere on the item and drag
+//   touch      — press the grip and drag
+//   keyboard   — moveBy(id, ±1), which you wire to buttons or arrow keys
+// The keyboard path is not a fallback. It is the one that works while holding a
+// coffee, and the one a screen reader can follow, which is why every move —
+// however it was made — goes through the same announcement.
+import { useCallback, useEffect, useRef, useState } from 'preact/hooks';
+/** Pointer travel, in px, before a press counts as a drag rather than a tap. */
+const DEFAULT_THRESHOLD_PX = 4;
+/** Presses on these belong to the control, not to the drag. */
+const DEFAULT_IGNORE = 'input, button, select, textarea, a, [data-no-drag]';
+/** A touch starts a drag only from here, so a finger elsewhere still scrolls. */
+const DEFAULT_GRIP = '[data-sortable-grip]';
+export const EN_SORTABLE = {
+    moved: (label, position, total) => `${label} moved to position ${position} of ${total}`,
+    alreadyFirst: (label) => `${label} is already first`,
+    alreadyLast: (label) => `${label} is already last`,
+    cancelled: 'Move cancelled',
+};
+/** Move the item with `id` to `index`, clamped. Pure, so it is the testable part. */
+export function reorder(ids, id, index) {
+    const from = ids.indexOf(id);
+    if (from === -1)
+        return ids;
+    const to = Math.max(0, Math.min(index, ids.length - 1));
+    if (to === from)
+        return ids;
+    const next = [...ids];
+    next.splice(from, 1);
+    next.splice(to, 0, id);
+    return next;
+}
+/** Nudge an item by `step` places. Off either end is a no-op, never a wrap. */
+export function nudge(ids, id, step) {
+    const from = ids.indexOf(id);
+    if (from === -1)
+        return ids;
+    const to = from + step;
+    if (to < 0 || to >= ids.length)
+        return ids;
+    return reorder(ids, id, to);
+}
+/** Put `id` directly where `overId` sits — what a drop means. */
+export function dropOn(ids, id, overId) {
+    const to = ids.indexOf(overId);
+    return to === -1 ? ids : reorder(ids, id, to);
+}
+export function useSortable(options) {
+    const { ids, onReorder, disabled = false, threshold = DEFAULT_THRESHOLD_PX, gripSelector = DEFAULT_GRIP, ignoreSelector = DEFAULT_IGNORE, } = options;
+    // The drag lives in a REF, and the state is only a mirror for rendering.
+    // Handlers created during render close over whatever `drag` was at the time,
+    // and a pointerup can arrive in the same frame as the last pointermove — before
+    // any re-render — so a handler reading state would see a stale null and drop
+    // the drop. The ref is always current; the state only has to redraw.
+    const dragRef = useRef(null);
+    const say_ = { ...EN_SORTABLE, ...options.strings };
+    const [drag, setDragState] = useState(null);
+    const setDrag = useCallback((next) => {
+        dragRef.current = next;
+        setDragState(next);
+    }, []);
+    const labelOf = options.labelOf ?? ((id) => id);
+    // the list can change under a drag (an item removed elsewhere); keep the
+    // handlers reading the current one rather than the one they closed over
+    const latest = useRef({ ids, onReorder, labelOf, onAnnounce: options.onAnnounce, words: say_ });
+    latest.current = { ids, onReorder, labelOf, onAnnounce: options.onAnnounce, words: say_ };
+    const announce = useCallback((message) => {
+        latest.current.onAnnounce?.(message);
+    }, []);
+    const say = useCallback((id, next) => {
+        const at = next.indexOf(id);
+        announce(latest.current.words.moved(latest.current.labelOf(id), at + 1, next.length));
+    }, [announce]);
+    const moveBy = useCallback((id, step) => {
+        const next = nudge(latest.current.ids, id, step);
+        if (next === latest.current.ids) {
+            const label = latest.current.labelOf(id);
+            announce(step < 0 ? latest.current.words.alreadyFirst(label) : latest.current.words.alreadyLast(label));
+            return;
+        }
+        latest.current.onReorder(next);
+        say(id, next);
+    }, [announce, say]);
+    // A drag can be left mid-air if the pointer never comes back; Escape always
+    // abandons it. Registered once rather than per-drag, so there is no window
+    // where the drag has started and the listener has not been attached yet.
+    useEffect(() => {
+        const abandon = (event) => {
+            if (event.key !== 'Escape' || !dragRef.current)
+                return;
+            setDrag(null);
+            announce(latest.current.words.cancelled);
+        };
+        window.addEventListener('keydown', abandon);
+        return () => window.removeEventListener('keydown', abandon);
+    }, [announce, setDrag]);
+    /** Which item is under this point — the drop target. */
+    const idAtPoint = (x, y) => {
+        const under = document.elementFromPoint?.(x, y);
+        return under?.closest?.('[data-sortable-id]')?.getAttribute('data-sortable-id') ?? null;
+    };
+    /** A mouse or pen drags from anywhere on the item; a finger only from the grip,
+     *  so the page still scrolls. Presses on a control belong to that control. */
+    const startsADrag = (event) => {
+        const pressed = event.target;
+        if (pressed.closest?.(ignoreSelector))
+            return false;
+        return event.pointerType !== 'touch' || Boolean(pressed.closest?.(gripSelector));
+    };
+    const itemProps = (id) => ({
+        'data-sortable-id': id,
+        onPointerDown: (event) => {
+            if (disabled || dragRef.current || !startsADrag(event))
+                return;
+            event.currentTarget.setPointerCapture?.(event.pointerId);
+            event.preventDefault(); // no text selection under a mouse, no page scroll under a finger
+            setDrag({ id, pointerId: event.pointerId, startX: event.clientX, startY: event.clientY, dx: 0, dy: 0, overId: id });
+        },
+        onPointerMove: (event) => {
+            const current = dragRef.current;
+            if (!current || current.pointerId !== event.pointerId)
+                return;
+            setDrag({
+                ...current,
+                dx: event.clientX - current.startX,
+                dy: event.clientY - current.startY,
+                overId: idAtPoint(event.clientX, event.clientY),
+            });
+        },
+        onPointerUp: (event) => {
+            const current = dragRef.current;
+            if (!current || current.pointerId !== event.pointerId)
+                return;
+            setDrag(null);
+            if (current.overId === null || current.overId === current.id)
+                return;
+            const next = dropOn(latest.current.ids, current.id, current.overId);
+            if (next === latest.current.ids)
+                return;
+            latest.current.onReorder(next);
+            say(current.id, next);
+        },
+        onPointerCancel: () => setDrag(null),
+    });
+    const lifted = drag !== null && Math.hypot(drag.dx, drag.dy) > threshold;
+    return {
+        dragging: lifted ? drag.id : null,
+        overId: lifted ? drag.overId : null,
+        offset: drag ? { dx: drag.dx, dy: drag.dy } : { dx: 0, dy: 0 },
+        itemProps,
+        gripProps: { 'data-sortable-grip': true, 'aria-hidden': 'true' },
+        moveBy,
+    };
+}

package/package.json

@@ -1,6 +1,57 @@
 {
   "name": "@tapestry-ui/sortable",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "A WCAG 2.1 AA sortable list for Preact \u2014 pointer drag, touch from a grip so the page still scrolls, keyboard moves, announcements. Headless: you render, it reorders.",
+  "license": "MIT",
+  "author": "Brandon Minton",
+  "type": "module",
+  "sideEffects": [
+    "*.css"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/sortable.d.ts",
+      "default": "./dist/sortable.js"
+    },
+    "./styles.css": "./styles.css"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "styles.css",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "prepublishOnly": "npm run test && npm run build"
+  },
+  "peerDependencies": {
+    "preact": ">=10.24.0"
+  },
+  "devDependencies": {
+    "jsdom": "^25.0.1",
+    "preact": "^10.29.4",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.10"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ryurage/brandonminton.git",
+    "directory": "packages/tapestry-ui/sortable"
+  },
+  "keywords": [
+    "preact",
+    "sortable",
+    "drag-and-drop",
+    "reorder",
+    "dnd",
+    "touch",
+    "a11y",
+    "wcag",
+    "headless",
+    "tapestry-ui"
+  ]
+}

package/styles.css

@@ -0,0 +1,19 @@
+/* @tapestry-ui/sortable — STRUCTURAL styles only, and barely any: the hook
+   renders nothing, so there is almost nothing to style. These exist because two
+   of them are not decoration but behaviour. */
+
+/* touch-action:none is REQUIRED, not cosmetic. Without it the browser claims the
+   gesture for scrolling and the pointermove events stop arriving mid-drag. */
+[data-sortable-grip] {
+  touch-action: none;
+  cursor: grab;
+}
+[data-sortable-grip]:active { cursor: grabbing; }
+
+/* A lifted item must stop answering hit tests, or elementFromPoint keeps finding
+   the thing being dragged instead of the thing underneath it. */
+.tui-sortable__item--lifted {
+  pointer-events: none;
+  position: relative;
+  z-index: var(--tui-sortable-lifted-z, 5);
+}