@celestia-island/hikari 0.55.115 → 0.55.116

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celestia-island/hikari",
-  "version": "0.55.115",
+  "version": "0.55.116",
   "private": false,
   "type": "module",
   "description": "Hikari Vue 3 component library — production-grade UI components based on shittim-chest design system",

package/src/components/HkAdminTablePage.tsx

@@ -50,8 +50,14 @@ export const HkAdminTablePage = defineComponent({
     rowKey: { type: String, default: "id" },
     emptyTitle: { type: String, default: "" },
     emptyDescription: { type: String as PropType<string | undefined>, default: undefined },
+    /** Left grip column with drag-to-reorder (forwarded to HTable; the
+     *  `reorder` event is forwarded verbatim — indices into `rows`). */
+    draggable: { type: Boolean, default: false },
   },
-  setup(props, { slots }) {
+  emits: {
+    reorder: (_fromIndex: number, _toIndex: number) => true,
+  },
+  setup(props, { emit, slots }) {
 
     return () => {
       const { t } = useI18n();
@@ -96,7 +102,13 @@ export const HkAdminTablePage = defineComponent({
             <div class="hk-admin-table-page-body">{slots.body()}</div>
           ) : (
             <HCard padded={false}>
-              <HTable columns={props.columns} rows={props.rows} rowKey={props.rowKey}>
+              <HTable
+                columns={props.columns}
+                rows={props.rows}
+                rowKey={props.rowKey}
+                draggable={props.draggable}
+                onReorder={(from: number, to: number) => emit("reorder", from, to)}
+              >
                 {slots}
               </HTable>
             </HCard>

package/src/components/HkTable.drag.test.tsx

@@ -0,0 +1,499 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createApp, h, nextTick, ref } from "vue";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import HTable from "./HkTable";
+
+/**
+ * HkTable drag-to-reorder contract:
+ * - no grip column unless `draggable`
+ * - a focused handle's ArrowUp/Down nudges the row one slot and emits
+ *   `reorder(from, to)` as indices into `rows` (the consumer applies
+ *   moveTo(rows, from, to) — insert-at-target)
+ * - a pointer drag past the neighbours' midpoints emits the same pair
+ * - the emit is INERT while a column sort is active (a derived arrangement
+ *   cannot be reproduced by a two-index move) and the grips announce it
+ * - a cancelled gesture never emits
+ * - HkAdminTablePage forwards `draggable` + `reorder` (source contract)
+ *
+ * (Repo test convention: raw createApp + document queries, no
+ * @vue/test-utils; happy-dom ships no layout engine, so row geometry is
+ * pinned by hand — 40px rows stacked along y.)
+ */
+
+const mounts: Array<{ app: ReturnType<typeof createApp>; container: HTMLElement }> = [];
+
+afterEach(() => {
+  while (mounts.length) {
+    const { app, container } = mounts.pop()!;
+    app.unmount();
+    container.remove();
+  }
+});
+
+interface RowsRef {
+  rows: ReturnType<typeof ref<Record<string, unknown>[]>>;
+  emitted: Array<[number, number]>;
+}
+
+/** Mount a draggable table of `count` rows `{ name, n }`, pinning each
+ *  body row to a 40px band (y = i*40) the way a real layout engine would.
+ *  `sortable` mounts with sortable columns for the inert-while-sorted
+ *  case. Returns the reactive rows, the emitted reorder pairs and the
+ *  contract's moveTo applier. */
+function mountTable(
+  count: number,
+  opts: { sortable?: boolean } = {},
+): RowsRef & {
+  container: HTMLElement;
+  apply(from: number, to: number): Promise<void>;
+  setOrder(next: Record<string, unknown>[]): Promise<void>;
+} {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  const rows = ref<Record<string, unknown>[]>(
+    Array.from({ length: count }, (_, i) => ({ name: `Row-${i}`, n: count - i })),
+  );
+  const emitted: Array<[number, number]> = [];
+  const app = createApp({
+    render: () =>
+      h(HTable, {
+        columns: [
+          { key: "name", title: "Name" },
+          { key: "n", title: "N", sortable: opts.sortable === true },
+        ],
+        rows: rows.value,
+        rowKey: "name",
+        draggable: true,
+        onReorder: (from: number, to: number) => emitted.push([from, to]),
+      }),
+  });
+  mounts.push({ app, container });
+  app.mount(container);
+  const host = container;
+  // Pin geometry: the row `tr`s in display order.
+  const trs = host.querySelectorAll("tbody .hk-table-row");
+  trs.forEach((tr, i) => {
+    const start = i * 40;
+    const box = { left: 0, right: 300, top: start, bottom: start + 40, width: 300, height: 40, x: 0, y: start };
+    Object.defineProperty(tr, "getBoundingClientRect", { configurable: true, value: () => box as DOMRect });
+  });
+  return {
+    rows,
+    emitted,
+    container: host,
+    /** Apply the contract's moveTo to the array and flush. */
+    async apply(from: number, to: number): Promise<void> {
+      const next = rows.value.slice();
+      const [moved] = next.splice(from, 1);
+      next.splice(to, 0, moved!);
+      rows.value = next;
+      await nextTick();
+    },
+    /** Replace the consumer's array outright (any reorder, including ones a
+     *  single moveTo cannot express) and flush. */
+    async setOrder(next: Record<string, unknown>[]): Promise<void> {
+      rows.value = next;
+      await nextTick();
+      // Re-pin geometry: the keyed `tr`s move with the data, so display
+      // order changed under the same elements.
+      host.querySelectorAll("tbody .hk-table-row").forEach((tr, i) => {
+        const start = i * 40;
+        const box = { left: 0, right: 300, top: start, bottom: start + 40, width: 300, height: 40, x: 0, y: start };
+        Object.defineProperty(tr, "getBoundingClientRect", { configurable: true, value: () => box as DOMRect });
+      });
+    },
+  };
+}
+
+function handles(host: HTMLElement): NodeListOf<HTMLButtonElement> {
+  return host.querySelectorAll<HTMLButtonElement>(".hk-table-drag-handle");
+}
+
+async function pressKey(handle: HTMLButtonElement, key: string): Promise<void> {
+  handle.dispatchEvent(
+    new KeyboardEvent("keydown", { key, bubbles: true, cancelable: true }),
+  );
+  await nextTick();
+}
+
+function pointer(type: string, x: number, y: number): PointerEvent {
+  return new PointerEvent(type, {
+    bubbles: true,
+    cancelable: true,
+    pointerId: 7,
+    button: 0,
+    // A move with no button held is a released pointer the page never saw
+    // the release of — the engine ignores it (its doc'd contract), so the
+    // gesture here must carry the pressed button until the final up.
+    buttons: type === "pointerup" ? 0 : 1,
+    clientX: x,
+    clientY: y,
+  });
+}
+
+describe("HkTable drag-to-reorder", () => {
+  it("renders no grip column unless draggable", async () => {
+    const container = document.createElement("div");
+    document.body.appendChild(container);
+    const app = createApp({
+      render: () =>
+        h(HTable, {
+          columns: [{ key: "name", title: "Name" }],
+          rows: [{ name: "a" }],
+        }),
+    });
+    mounts.push({ app, container });
+    app.mount(container);
+    expect(container.querySelectorAll(".hk-table-drag-handle").length).toBe(0);
+    expect(container.querySelectorAll("thead th").length).toBe(1);
+  });
+
+  it("renders one grip per row with an accessible name from the first column", async () => {
+    const t = mountTable(3);
+    const grips = handles(t.container);
+    expect(grips.length).toBe(3);
+    expect(grips[0]?.getAttribute("aria-label")).toBe("Reorder Row-0");
+    expect(grips[0]?.getAttribute("aria-keyshortcuts")).toBe("ArrowUp ArrowDown");
+  });
+
+  it("interpolates the row label literally (a $& label is not a replacement pattern)", async () => {
+    const container = document.createElement("div");
+    document.body.appendChild(container);
+    const app = createApp({
+      render: () =>
+        h(HTable, {
+          columns: [{ key: "name", title: "Name" }],
+          rows: [{ name: "Cash $& more" }],
+          rowKey: "name",
+          draggable: true,
+        }),
+    });
+    mounts.push({ app, container });
+    app.mount(container);
+    // String.replace would expand `$&` into the matched text; the
+    // split/join interpolation must keep the label verbatim.
+    expect(handles(container)[0]?.getAttribute("aria-label")).toBe("Reorder Cash $& more");
+  });
+
+  it("ArrowDown on a focused handle emits (from, from+1) into rows and the move lands", async () => {
+    const t = mountTable(3);
+    await pressKey(handles(t.container)[0]!, "ArrowDown");
+    expect(t.emitted).toEqual([[0, 1]]);
+    await t.apply(0, 1);
+    // The leading data cell (the grip cell carries .hk-table-cell too).
+    expect(
+      t.container.querySelector("tbody .hk-table-row td:not(.hk-table-drag-cell)")?.textContent,
+    ).toBe("Row-1");
+  });
+
+  it("ArrowUp on the first row consumes the key but emits nothing", async () => {
+    const t = mountTable(3);
+    await pressKey(handles(t.container)[0]!, "ArrowUp");
+    expect(t.emitted).toEqual([]);
+  });
+
+  it("ArrowDown on the last row consumes the key but emits nothing", async () => {
+    const t = mountTable(3);
+    await pressKey(handles(t.container)[2]!, "ArrowDown");
+    expect(t.emitted).toEqual([]);
+  });
+
+  it("a pointer drag past the neighbours' midpoints emits the drop pair", async () => {
+    const t = mountTable(3);
+    const grip = handles(t.container)[0]!;
+    grip.dispatchEvent(pointer("pointerdown", 18, 20));
+    // Past the threshold (6px) and past rows 1–2 midpoints (60/100): the
+    // drop slot resolves to the END of the strip → insert-at-target = 2.
+    window.dispatchEvent(pointer("pointermove", 18, 101));
+    window.dispatchEvent(pointer("pointerup", 18, 101));
+    await nextTick();
+    expect(t.emitted).toEqual([[0, 2]]);
+    // The gesture is over: no row keeps its lift.
+    expect(t.container.querySelectorAll('tbody [data-dragging]').length).toBe(0);
+  });
+
+  it("a short press stays a click (no drag, no emit)", async () => {
+    const t = mountTable(3);
+    const grip = handles(t.container)[0]!;
+    grip.dispatchEvent(pointer("pointerdown", 18, 20));
+    window.dispatchEvent(pointer("pointermove", 18, 23));
+    window.dispatchEvent(pointer("pointerup", 18, 23));
+    await nextTick();
+    expect(t.emitted).toEqual([]);
+  });
+
+  it("a cancelled gesture never emits", async () => {
+    const t = mountTable(3);
+    const grip = handles(t.container)[0]!;
+    grip.dispatchEvent(pointer("pointerdown", 18, 20));
+    window.dispatchEvent(pointer("pointermove", 18, 101));
+    window.dispatchEvent(new PointerEvent("pointercancel", { bubbles: true, pointerId: 7 }));
+    await nextTick();
+    expect(t.emitted).toEqual([]);
+    expect(t.container.querySelectorAll('tbody [data-dragging]').length).toBe(0);
+  });
+
+  it("paints the insertion cue on the row the pointer resolves to", async () => {
+    const t = mountTable(3);
+    const grip = handles(t.container)[0]!;
+    grip.dispatchEvent(pointer("pointerdown", 18, 20));
+    window.dispatchEvent(pointer("pointermove", 18, 70));
+    await nextTick();
+    // Pointer between rows 1 (mid 60) and 2 (mid 100): the walk stops at
+    // display row 2 (main=70 < mid 100) → slot 2, from=0 → insert-at-target
+    // = 1 (drop row 0 ON row 1); the cue rides display row 1's top edge.
+    const trs = t.container.querySelectorAll("tbody .hk-table-row");
+    expect(trs[1]?.getAttribute("data-drop")).toBe("before");
+    window.dispatchEvent(pointer("pointerup", 18, 70));
+    await nextTick();
+    expect(trs[1]?.getAttribute("data-drop")).toBeNull();
+  });
+
+  it("is inert while a column sort is active — grips announce disabled and emits never fire", async () => {
+    const t = mountTable(3, { sortable: true });
+    // Activate the sort the way a user does: click the column header.
+    const header = t.container.querySelectorAll<HTMLElement>("thead th")[2]!;
+    header.click();
+    await nextTick();
+    const grips = handles(t.container);
+    // Sorted desc on n (rows were built n = count-i): display order is
+    // Row-0 first still — but the SORT state is what matters here.
+    expect(header.classList.contains("hk-table-header-sorted")).toBe(true);
+    for (const grip of grips) {
+      expect(grip.getAttribute("aria-disabled")).toBe("true");
+    }
+    await pressKey(grips[0]!, "ArrowDown");
+    expect(t.emitted).toEqual([]);
+    gripDragAttempt(t);
+    expect(t.emitted).toEqual([]);
+  });
+
+  it("clears the sort on a third header click, re-enabling the grips", async () => {
+    const t = mountTable(3, { sortable: true });
+    const header = t.container.querySelectorAll<HTMLElement>("thead th")[2]!;
+    header.click();
+    await nextTick();
+    expect(header.classList.contains("hk-table-header-sorted")).toBe(true);
+    header.click();
+    await nextTick();
+    // Still sorted (descending) — the grips stay inert.
+    expect(header.classList.contains("hk-table-header-sorted")).toBe(true);
+    expect(handles(t.container)[0]!.getAttribute("aria-disabled")).toBe("true");
+
+    header.click();
+    await nextTick();
+    // Third click: the consumer's own order is back, so the grips are live
+    // again and a nudge emits.
+    expect(header.classList.contains("hk-table-header-sorted")).toBe(false);
+    expect(handles(t.container)[0]!.getAttribute("aria-disabled")).toBeNull();
+    await pressKey(handles(t.container)[0]!, "ArrowDown");
+    expect(t.emitted).toEqual([[0, 1]]);
+  });
+
+  it("paints no insertion cue while the pointer still resolves to the dragged row", async () => {
+    const t = mountTable(3);
+    const grip = handles(t.container)[0]!;
+    grip.dispatchEvent(pointer("pointerdown", 18, 20));
+    // Past the threshold but still inside row 0's own band (mid 20): the
+    // resolved slot is the row's own — a cue there would read as a no-op
+    // target.
+    window.dispatchEvent(pointer("pointermove", 18, 26));
+    await nextTick();
+    expect(t.container.querySelectorAll("tbody [data-drop]").length).toBe(0);
+    window.dispatchEvent(pointer("pointerup", 18, 26));
+    await nextTick();
+    expect(t.emitted).toEqual([]);
+  });
+
+  /** A pointer gesture against an inert table: press + travel + release. */
+  function gripDragAttempt(t: RowsRef & { container: HTMLElement }): void {
+    const grip = handles(t.container)[0]!;
+    grip.dispatchEvent(pointer("pointerdown", 18, 20));
+    window.dispatchEvent(pointer("pointermove", 18, 101));
+    window.dispatchEvent(pointer("pointerup", 18, 101));
+  }
+
+  it("still emits after a MIDDLE row is removed (stale registry tail)", async () => {
+    const t = mountTable(3);
+    // Vue calls the removed row's function ref with null, and the index that
+    // callback captured is the one the row held in the PREVIOUS render — the
+    // slot the survivor just slid into. A ref registry therefore ends up
+    // with a live row missing (or a stale duplicate), the drop resolves past
+    // the end and the bounds check swallows the emit — silently, for every
+    // later drag. The strip is read from the DOM, so it cannot drift.
+    const original = t.rows.value ?? [];
+    await t.setOrder([original[0]!, original[2]!]);
+
+    const grip = handles(t.container)[0]!;
+    grip.dispatchEvent(pointer("pointerdown", 18, 20));
+    window.dispatchEvent(pointer("pointermove", 18, 70));
+    window.dispatchEvent(pointer("pointerup", 18, 70));
+    await nextTick();
+    expect(t.emitted).toEqual([[0, 1]]);
+    // The drop lands: Row-2 takes Row-0's place.
+    await t.apply(0, 1);
+    expect((t.rows.value ?? []).map((r) => r.name)).toEqual(["Row-2", "Row-0"]);
+  });
+
+  it("re-resolves the strip after a deletion that follows a completed drag", async () => {
+    const t = mountTable(3);
+    // Read the strip once (a real drag), then remove a middle row and drag
+    // again: a strip cached at first read would silently stop emitting, and
+    // only this ORDERING catches it — the plain removal case reads the
+    // strip for the first time after the deletion.
+    const grip0 = handles(t.container)[0]!;
+    grip0.dispatchEvent(pointer("pointerdown", 18, 20));
+    window.dispatchEvent(pointer("pointermove", 18, 60));
+    window.dispatchEvent(pointer("pointerup", 18, 60));
+    await nextTick();
+    expect(t.emitted).toEqual([[0, 1]]);
+    await t.apply(0, 1);
+
+    const original = t.rows.value ?? [];
+    await t.setOrder([original[0]!, original[2]!]);
+    const grip = handles(t.container)[0]!;
+    grip.dispatchEvent(pointer("pointerdown", 18, 20));
+    window.dispatchEvent(pointer("pointermove", 18, 70));
+    window.dispatchEvent(pointer("pointerup", 18, 70));
+    await nextTick();
+    expect(t.emitted).toEqual([[0, 1], [0, 1]]);
+  });
+
+  it("ignores a nested table's rows when resolving the outer strip", async () => {
+    // A cell slot may render another HkTable; its rows are descendants of
+    // this host, so a bare descendant query would let an outer drag resolve
+    // onto them (R3 N1).
+    const t = mountTable(3);
+    const cell = t.container.querySelector("tbody .hk-table-row td:not(.hk-table-drag-cell)")!;
+    const nested = document.createElement("div");
+    cell.appendChild(nested);
+    const nestedApp = createApp({
+      render: () =>
+        h(HTable, {
+          columns: [{ key: "name", title: "Name" }],
+          rows: [{ name: "Inner-0" }, { name: "Inner-1" }],
+          rowKey: "name",
+        }),
+    });
+    mounts.push({ app: nestedApp, container: nested });
+    nestedApp.mount(nested);
+
+    const grip = handles(t.container)[0]!;
+    grip.dispatchEvent(pointer("pointerdown", 18, 20));
+    window.dispatchEvent(pointer("pointermove", 18, 101));
+    window.dispatchEvent(pointer("pointerup", 18, 101));
+    await nextTick();
+    // The strip is the OUTER table's three rows: dropping row 0 at the end
+    // is (0, 2) — not a slot among the five rows a descendant query sees.
+    expect(t.emitted).toEqual([[0, 2]]);
+  });
+
+  it("maps the drop onto the NEW array after a consumer reorder (reverse case)", async () => {
+    const t = mountTable(3);
+    // The consumer replaces the order outright — [Row-0, Row-1, Row-2] →
+    // [Row-2, Row-1, Row-0]. A row-element registry that kept birth indices
+    // would resolve the drag below against the OLD positions and emit
+    // nothing; the contract is indices into the array as it is NOW.
+    const reversed = [...(t.rows.value ?? [])].reverse();
+    await t.setOrder(reversed);
+    const grip = handles(t.container)[0]!;
+    grip.dispatchEvent(pointer("pointerdown", 18, 20));
+    // Past row 1's midpoint (60) but not row 2's (100) → insert-at-target 1.
+    window.dispatchEvent(pointer("pointermove", 18, 70));
+    window.dispatchEvent(pointer("pointerup", 18, 70));
+    await nextTick();
+    expect(t.emitted).toEqual([[0, 1]]);
+    // And the prescribed move lands the reversal the user saw.
+    const [first] = reversed.splice(0, 1);
+    reversed.splice(1, 0, first!);
+    expect(reversed.map((r) => r.name)).toEqual(["Row-1", "Row-2", "Row-0"]);
+  });
+
+  it("pulls the nearest vertically scrollable ancestor while the pointer rests near its edge", async () => {
+    const scroller = document.createElement("div");
+    document.body.appendChild(scroller);
+    // happy-dom has no layout: the ancestor must LOOK like a scroller
+    // (overflow style + metrics) for the resolver to pick it.
+    Object.defineProperty(scroller, "scrollHeight", { configurable: true, value: 1000 });
+    Object.defineProperty(scroller, "clientHeight", { configurable: true, value: 100 });
+    const scrollerBox = { left: 0, right: 300, top: 0, bottom: 100, width: 300, height: 100, x: 0, y: 0 };
+    Object.defineProperty(scroller, "getBoundingClientRect", {
+      configurable: true,
+      value: () => scrollerBox as DOMRect,
+    });
+    const realGCS = window.getComputedStyle.bind(window);
+    const spy = vi.spyOn(window, "getComputedStyle").mockImplementation((el: Element) => {
+      if (el === scroller) return { overflowY: "auto" } as CSSStyleDeclaration;
+      return realGCS(el as Element);
+    });
+
+    const container = document.createElement("div");
+    scroller.appendChild(container);
+    const rows = ref<Record<string, unknown>[]>([
+      { name: "Row-0" },
+      { name: "Row-1" },
+      { name: "Row-2" },
+    ]);
+    const emitted: Array<[number, number]> = [];
+    const app = createApp({
+      render: () =>
+        h(HTable, {
+          columns: [{ key: "name", title: "Name" }],
+          rows: rows.value,
+          rowKey: "name",
+          draggable: true,
+          onReorder: (from: number, to: number) => emitted.push([from, to]),
+        }),
+    });
+    mounts.push({ app, container });
+    app.mount(container);
+    container.querySelectorAll("tbody .hk-table-row").forEach((tr, i) => {
+      const start = i * 40;
+      const box = { left: 0, right: 300, top: start, bottom: start + 40, width: 300, height: 40, x: 0, y: start };
+      Object.defineProperty(tr, "getBoundingClientRect", { configurable: true, value: () => box as DOMRect });
+    });
+
+    const grip = handles(container)[0]!;
+    grip.dispatchEvent(pointer("pointerdown", 18, 20));
+    // Inside the scroller's bottom edge zone (rect 0..100, zone 24) → the
+    // engine starts pulling one frame at a time.
+    window.dispatchEvent(pointer("pointermove", 18, 95));
+    await nextTick();
+    for (let i = 0; i < 4; i += 1) {
+      await new Promise((resolve) => requestAnimationFrame(() => resolve(null)));
+    }
+    expect(scroller.scrollTop).toBeGreaterThan(0);
+    window.dispatchEvent(pointer("pointerup", 18, 95));
+    await nextTick();
+    spy.mockRestore();
+    scroller.remove();
+  });
+});
+
+describe("HkTable grip CSS (source contract)", () => {
+  const here = dirname(fileURLToPath(import.meta.url));
+  const scss = readFileSync(join(here, "HkTable.scss"), "utf-8");
+
+  it("keeps the grip cells' padding rule at size-variant specificity", () => {
+    // The regression this pins: a bare `.hk-table-drag-cell` selector is
+    // 0,1,0 and silently loses to `.hk-table-sm .hk-table-cell` (0,2,0), so
+    // the grip cell grows a full cell's right padding at sm/lg.
+    expect(scss).toMatch(/\.hk-table \.hk-table-drag-cell\s*\{/);
+    expect(scss).toMatch(/\.hk-table \.hk-table-drag-col\s*\{/);
+  });
+});
+
+describe("HkAdminTablePage drag passthrough (source contract)", () => {
+  const here = dirname(fileURLToPath(import.meta.url));
+  const pageTsx = readFileSync(join(here, "HkAdminTablePage.tsx"), "utf-8");
+
+  it("forwards draggable and the reorder event to HTable verbatim", () => {
+    expect(pageTsx).toContain("draggable: { type: Boolean, default: false }");
+    expect(pageTsx).toMatch(/emits:\s*\{\s*reorder:/);
+    expect(pageTsx).toMatch(/draggable=\{props\.draggable\}/);
+    expect(pageTsx).toMatch(/onReorder=\{\(from: number, to: number\) => emit\("reorder", from, to\)\}/);
+  });
+});

package/src/components/HkTable.scss

@@ -129,12 +129,98 @@
   }
 }
 
+/* Grip cells: tighter than a content cell and flush to the row's trailing
+   edge. Specificity 0,2,0 — equal to the size variants' `.hk-table-sm
+   .hk-table-cell` rules above but later in source order, which is what makes
+   the trim hold at EVERY size (a bare `.hk-table-drag-cell` is 0,1,0, so the
+   sm/lg padding silently won and the grip cell stayed wide). */
+.hk-table .hk-table-drag-col {
+  padding-right: 0;
+}
+
+.hk-table .hk-table-drag-cell {
+  padding-right: 0;
+  width: 36px;
+  white-space: nowrap;
+}
+
 .hk-table-empty {
   padding: var(--space-32, 32px) var(--space-16, 16px);
   text-align: center;
   color: var(--hi-color-text-secondary, #666666);
 }
 
+/* ── Drag-to-reorder (draggable) ─────────────────────────────────────── */
+
+.hk-table-drag-handle {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: var(--space-20, 20px);
+  height: var(--space-24, 24px);
+  padding: 0;
+  border: 0;
+  border-radius: var(--radius-sm, 4px);
+  background: transparent;
+  color: var(--hi-color-text-tertiary, #8b949e);
+  cursor: grab;
+  /* An explicit grip owns the gesture: the page must not pan under a
+     held drag (house pattern: HkDraggableList's handle). */
+  touch-action: none;
+
+  &:hover {
+    color: var(--hi-color-text-secondary, #666666);
+    background: var(--hi-color-bg-subtle, rgba(255, 255, 255, 0.04));
+  }
+
+  &:active {
+    cursor: grabbing;
+  }
+
+  &:focus-visible {
+    outline: none;
+    box-shadow: 0 0 0 2px var(--hi-color-bg-canvas, #0d1117), 0 0 0 4px var(--hi-color-primary, #7aa2f7);
+  }
+
+  /* A sorted table refuses to reorder (the emitted index pair could not
+     reproduce the visual move against a derived arrangement) — the grip
+     must LOOK inert, not merely be inert. */
+  &[data-disabled] {
+    color: var(--hi-color-text-tertiary, #8b949e);
+    opacity: 0.4;
+    cursor: not-allowed;
+  }
+}
+
+/* The row being dragged lifts in place (house pattern: HkTagInput's drag
+   lift — no floating ghost): dimmed, primary-tinted edge. A transform on
+   a <tr> is unreliable across engines, so the lift is paint-only. */
+.hk-table-draggable .hk-table-row[data-dragging] {
+  opacity: 0.45;
+  background: rgb(from var(--hi-color-primary, #7aa2f7) r g b / 0.06);
+  box-shadow: inset 0 0 0 1px var(--hi-color-primary, #7aa2f7);
+}
+
+/* Insertion cue: the slot the pointer resolves to paints a 2px line on
+   the edge the row would land across. */
+.hk-table-draggable .hk-table-row[data-drop="before"] {
+  box-shadow: inset 0 2px 0 0 var(--hi-color-primary, #7aa2f7);
+}
+
+.hk-table-draggable .hk-table-row[data-drop="after"] {
+  box-shadow: inset 0 -2px 0 0 var(--hi-color-primary, #7aa2f7);
+}
+
+/* Text under a live drag must not select (the press starts on the grip,
+   but a move across cells can start a native selection). */
+.hk-table-draggable .hk-table-row[data-dragging] .hk-table-cell {
+  user-select: none;
+  -webkit-user-select: none;
+}
+
+/* Reduced motion: the lift is paint-only already (no transform to snap);
+   the hover/press fades stay (house convention: HkDraggableList.scss). */
+
 /* Alignment helpers (start/end so aligned columns mirror in RTL; the
    tsx keeps emitting the hk-text-* names) */
 .hk-text-left {

package/src/components/HkTable.tsx

@@ -1,6 +1,7 @@
 import { computed, defineComponent, onBeforeUnmount, onMounted, ref, type PropType } from "vue";
 
 import { useI18n } from "../i18n/context";
+import { usePointerReorder } from "../composables/usePointerReorder";
 import { attachOverlayScrollbars, type OverlayScrollbarHandle } from "../composables/useOverlayScrollbar";
 import "./HkTable.scss";
 
@@ -25,10 +26,18 @@ export default defineComponent({
     hover: { type: Boolean, default: false },
     sortable: { type: Boolean, default: false },
     selectable: { type: Boolean, default: false },
+    /** Left grip column with pointer drag-to-reorder (and ArrowUp/Down on a
+     *  focused handle). The emitted indices are indices into `rows` — the
+     *  consumer applies `moveTo(rows, from, to)`. While a column sort is
+     *  active the displayed arrangement is derived, so two indices cannot
+     *  faithfully encode the visual move: reordering is INERT until the
+     *  sort is cleared (the handles render dimmed and refuse presses). */
+    draggable: { type: Boolean, default: false },
     emptyText: { type: String, default: "" },
   },
   emits: {
     "update:selectedRows": (_rows: Record<string, unknown>[]) => true,
+    reorder: (_fromIndex: number, _toIndex: number) => true,
   },
   setup(props, { emit, slots }) {
     const { t } = useI18n();
@@ -63,13 +72,23 @@ export default defineComponent({
       return String(index);
     }
 
+    /** Click-to-sort is TRI-state: ascending → descending → unsorted. The
+     *  third click restores the consumer's own array order, which is what
+     *  makes the state reachable again for a `draggable` table (reordering
+     *  is inert while an arrangement is derived from a sort — see
+     *  `reorderInert`). */
     function toggleSort(key: string) {
-      if (sortKey.value === key) {
-        sortDirection.value = sortDirection.value === "asc" ? "desc" : "asc";
-      } else {
+      if (sortKey.value !== key) {
         sortKey.value = key;
         sortDirection.value = "asc";
+        return;
+      }
+      if (sortDirection.value === "asc") {
+        sortDirection.value = "desc";
+        return;
       }
+      sortKey.value = null;
+      sortDirection.value = "asc";
     }
 
     const sortedRows = computed(() => {
@@ -117,23 +136,161 @@ export default defineComponent({
         selectedRowKeys.value.size === sortedRows.value.length
     );
 
+    // ── Drag-to-reorder (draggable) ─────────────────────────────────────
+    /** The strip the reorder engine measures: the body rows in display
+     *  order, read from the DOM on demand.
+     *
+     *  A ref registry cannot be trusted here. Vue calls a REMOVED row's
+     *  function ref with null, and the index that callback captured is the
+     *  one the row had in the PREVIOUS render — which, after a mid-list
+     *  deletion, is the very slot the row below just slid into. The stale
+     *  null lands last and erases a live registration (measured: rows
+     *  [Row-0, Row-2] render while the registry reads [Row-0, null]), so
+     *  every later pointer drop resolves past the end and is swallowed by
+     *  the bounds check. The DOM is the one source that cannot drift; the
+     *  engine re-reads it per resolution, which is also what keeps a list
+     *  that changes under a held press honest. */
+    function liveRowEls(): HTMLElement[] {
+      const host = wrapperHostRef.value;
+      // The host's FIRST table is this component's own (a nested table can
+      // only live inside one of its cells), and the `closest` filter keeps a
+      // nested table's rows out of the strip: they are descendants of the
+      // host too, and a bare descendant query would let an outer drag
+      // resolve onto them.
+      const own = host?.querySelector<HTMLElement>("table.hk-table") ?? null;
+      if (!own) return [];
+      return Array.from(own.querySelectorAll<HTMLElement>("tbody > .hk-table-row")).filter(
+        (row) => row.closest("table") === own,
+      );
+    }
+
+    /** Reordering is meaningful only over the array the consumer owns. A
+     *  column sort is an arrangement DERIVED from that array — the two
+     *  `reorder` indices could not tell the consumer how to reproduce the
+     *  visual move — so a sorted table refuses to drag (dimmed handles,
+     *  inert presses) rather than emit an edit that would land somewhere
+     *  the user did not drop it. Clicking the sorted header a third time
+     *  clears the sort (tri-state), which is the way back to dragging. */
+    const reorderInert = computed(() => sortKey.value !== null);
+
+    /** `moveTo` in the consumer's array: the entry at `from` takes `to`'s
+     *  place and the entries between shift by one (HkTagInput's drop
+     *  semantics — insert-at-target, what dropping a row ON another row
+     *  looks like). */
+    function onReorderDrop(from: number, to: number): void {
+      if (reorderInert.value) return;
+      if (from === to || from < 0 || to < 0) return;
+      if (from >= props.rows.length || to >= props.rows.length) return;
+      emit("reorder", from, to);
+    }
+
+    /** The scrollable ancestor a live drag pulls along, resolved on demand
+     *  (the engine re-reads it every frame while the pointer rests near an
+     *  edge): the nearest ancestor that actually overflows vertically — the
+     *  page shell, a modal body, a scroll container — or null when the
+     *  table sits fully in view, where there is nothing to scroll. */
+    function dragScrollContainer(): HTMLElement | null {
+      let el = wrapperHostRef.value?.parentElement ?? null;
+      while (el) {
+        const overflowY =
+          typeof getComputedStyle === "function" ? getComputedStyle(el).overflowY : "";
+        if ((overflowY === "auto" || overflowY === "scroll") && el.scrollHeight > el.clientHeight + 1) {
+          return el;
+        }
+        el = el.parentElement;
+      }
+      return null;
+    }
+
+    const rowDrag = usePointerReorder({
+      items: liveRowEls,
+      axis: "y",
+      onDrop: onReorderDrop,
+      scrollContainer: dragScrollContainer,
+    });
+
+    function onHandlePointerdown(e: PointerEvent, index: number): void {
+      if (reorderInert.value) return;
+      // The press's own row is looked up in the live strip: the render-time
+      // index is a fallback for a handle that somehow left the table.
+      const row = (e.currentTarget as HTMLElement | null)?.closest("tr");
+      const strip = row ? liveRowEls().indexOf(row as HTMLElement) : index;
+      if (strip >= 0) rowDrag.start(e, strip);
+    }
+
+    /** Keyboard twin of the drop: move one row one slot. Runs on a focused
+     *  handle, so plain ArrowUp/Down are unambiguous (no competing cursor
+     *  semantics on a button) and are consumed even at the ends, where the
+     *  row has nowhere to go. */
+    function onHandleKeydown(e: KeyboardEvent, index: number): void {
+      if (e.key !== "ArrowUp" && e.key !== "ArrowDown") return;
+      e.preventDefault();
+      if (reorderInert.value) return;
+      const delta = e.key === "ArrowUp" ? -1 : 1;
+      onReorderDrop(index, index + delta);
+    }
+
+    /** The handle's accessible name names the entry AND the action (house
+     *  pattern: HkTagInput's reorderLabel) — the first column's value is
+     *  the row's identity as far as this generic component can tell. */
+    function rowLabel(row: Record<string, unknown>): string {
+      const first = props.columns[0]?.key;
+      const value = first != null ? row[first] : undefined;
+      return value == null ? "" : String(value).trim();
+    }
+
+    function handleName(row: Record<string, unknown>): string {
+      const label = rowLabel(row);
+      if (!label) return t("hikari::table.dragHandle", "Drag to reorder");
+      const template = t("hikari::table.dragHandleRow", "Reorder {label}");
+      // split/join, not String.replace: a row label carrying `$&` / `$'`
+      // would otherwise be expanded as a replacement pattern (house
+      // interpolation, HkTagInput/HkAffixPicker).
+      const [before, after] = template.split("{label}");
+      if (after === undefined) return template;
+      return `${before}${label}${after}`;
+    }
+
+    /** Insertion cue for the slot the pointer currently resolves to:
+     *  `dragOver` is a slot (0..n) over the strip — the line paints on the
+     *  TOP edge of the row that would sit below the drop, or the BOTTOM
+     *  edge of the last row for the trailing slot. A slot that resolves
+     *  back onto the row being dragged paints nothing: the row already
+     *  carries its lift, and a "drop here" line on the row in hand reads
+     *  as a no-op target. */
+    const dropCue = computed<{ index: number; edge: "before" | "after" } | null>(() => {
+      if (!rowDrag.dragging.value || rowDrag.dragOver.value < 0) return null;
+      const slot = rowDrag.dragOver.value;
+      if (slot === rowDrag.dragFrom.value) return null;
+      const count = sortedRows.value.length;
+      if (slot >= count) return { index: count - 1, edge: "after" };
+      return { index: slot, edge: "before" };
+    });
+
     const tableCls = computed(() => [
       "hk-table",
       `hk-table-${props.size}`,
       props.bordered ? "hk-table-bordered" : "",
       props.striped ? "hk-table-striped" : "",
       props.hover ? "hk-table-hover" : "",
+      props.draggable ? "hk-table-draggable" : "",
     ]);
 
-    const totalCols = computed(() => props.columns.length + (props.selectable ? 1 : 0));
+    const totalCols = computed(
+      () => props.columns.length + (props.selectable ? 1 : 0) + (props.draggable ? 1 : 0)
+    );
 
-    return () => (
+    return () => {
+      return (
       <div ref={wrapperHostRef} class="hk-table-host">
         <div ref={wrapperRef} class="hk-table-wrapper">
         <table class={tableCls.value}>
           {props.caption && <caption class="hk-table-sr-only">{props.caption}</caption>}
           <thead>
             <tr class="hk-table-header-row">
+              {props.draggable && (
+                <th class="hk-table-header-cell hk-table-drag-col" style={{ width: "36px" }} aria-hidden="true" />
+              )}
               {props.selectable && (
                 <th class="hk-table-header-cell" style={{ width: "40px" }}>
                   <label class="hk-table-checkbox-label">
@@ -213,8 +370,46 @@ export default defineComponent({
             ) : (
               sortedRows.value.map((row, index) => {
                 const rowKey = getRowKey(row, index);
+                const dropCueEdge =
+                  dropCue.value && dropCue.value.index === index ? dropCue.value.edge : null;
                 return (
-                  <tr key={rowKey} class="hk-table-row">
+                  <tr
+                    key={rowKey}
+                    class="hk-table-row"
+                    data-dragging={rowDrag.dragging.value && rowDrag.dragFrom.value === index ? "" : undefined}
+                    data-drop={dropCueEdge || undefined}
+                  >
+                    {props.draggable && (
+                      <td class="hk-table-cell hk-table-drag-cell">
+                        {/* A span, not a <button>: the reorder engine (house
+                            rule, HkDraggableList's handle too) treats presses
+                            on interactive controls as ACTIVATION, not drag —
+                            the grip is a span so a press on it IS the drag
+                            gesture. Keyboard stays first-class: focusable,
+                            ArrowUp/Down nudges the row (aria-keyshortcuts). */}
+                        <span
+                          role="button"
+                          tabindex={0}
+                          class="hk-table-drag-handle"
+                          aria-label={handleName(row)}
+                          title={handleName(row)}
+                          aria-keyshortcuts="ArrowUp ArrowDown"
+                          aria-disabled={reorderInert.value || undefined}
+                          data-disabled={reorderInert.value || undefined}
+                          onPointerdown={(e: PointerEvent) => onHandlePointerdown(e, index)}
+                          onKeydown={(e: KeyboardEvent) => onHandleKeydown(e, index)}
+                        >
+                          <svg width="12" height="14" viewBox="0 0 12 14" fill="currentColor" aria-hidden="true">
+                            <circle cx="3.5" cy="3" r="1.2" />
+                            <circle cx="8.5" cy="3" r="1.2" />
+                            <circle cx="3.5" cy="7" r="1.2" />
+                            <circle cx="8.5" cy="7" r="1.2" />
+                            <circle cx="3.5" cy="11" r="1.2" />
+                            <circle cx="8.5" cy="11" r="1.2" />
+                          </svg>
+                        </span>
+                      </td>
+                    )}
                     {props.selectable && (
                       <td class="hk-table-cell" style={{ width: "40px" }}>
                         <label class="hk-table-checkbox-label">
@@ -266,6 +461,7 @@ export default defineComponent({
         </table>
         </div>
       </div>
-    );
+      );
+    };
   },
 });

package/src/i18n/locales/ar/components.json

@@ -170,6 +170,8 @@
     "hikari::statusBar.tier.ws": "WebSocket",
     "hikari::statusPill.ms": " مللي ثانية",
     "hikari::table.noData": "لا توجد بيانات",
+    "hikari::table.dragHandle": "اسحب لإعادة الترتيب",
+    "hikari::table.dragHandleRow": "إعادة ترتيب {label}",
     "hikari::tablePage.emptyTitle": "لا توجد بيانات",
     "hikari::tabs.add": "إضافة علامة تبويب",
     "hikari::theme.customThemeName": "سمة مخصصة",

package/src/i18n/locales/de/components.json

@@ -170,6 +170,8 @@
     "hikari::statusBar.tier.ws": "WebSocket",
     "hikari::statusPill.ms": " ms",
     "hikari::table.noData": "Keine Daten",
+    "hikari::table.dragHandle": "Zum Neuanordnen ziehen",
+    "hikari::table.dragHandleRow": "„{label}“ neu anordnen",
     "hikari::tablePage.emptyTitle": "Keine Daten",
     "hikari::tabs.add": "Tab hinzufügen",
     "hikari::theme.customThemeName": "Benutzerdefiniertes Thema",

package/src/i18n/locales/en/components.json

@@ -170,6 +170,8 @@
     "hikari::statusBar.tier.ws": "WebSocket",
     "hikari::statusPill.ms": " ms",
     "hikari::table.noData": "No data",
+    "hikari::table.dragHandle": "Drag to reorder",
+    "hikari::table.dragHandleRow": "Reorder {label}",
     "hikari::tablePage.emptyTitle": "No data",
     "hikari::tabs.add": "Add tab",
     "hikari::theme.customThemeName": "Custom theme",

package/src/i18n/locales/es/components.json

@@ -170,6 +170,8 @@
     "hikari::statusBar.tier.ws": "WebSocket",
     "hikari::statusPill.ms": " ms",
     "hikari::table.noData": "Sin datos",
+    "hikari::table.dragHandle": "Arrastra para reordenar",
+    "hikari::table.dragHandleRow": "Reordenar «{label}»",
     "hikari::tablePage.emptyTitle": "Sin datos",
     "hikari::tabs.add": "Añadir pestaña",
     "hikari::theme.customThemeName": "Tema personalizado",

package/src/i18n/locales/fr/components.json

@@ -170,6 +170,8 @@
     "hikari::statusBar.tier.ws": "WebSocket",
     "hikari::statusPill.ms": " ms",
     "hikari::table.noData": "Aucune donnée",
+    "hikari::table.dragHandle": "Glisser pour réordonner",
+    "hikari::table.dragHandleRow": "Réordonner « {label} »",
     "hikari::tablePage.emptyTitle": "Aucune donnée",
     "hikari::tabs.add": "Ajouter un onglet",
     "hikari::theme.customThemeName": "Thème personnalisé",

package/src/i18n/locales/ja/components.json

@@ -170,6 +170,8 @@
     "hikari::statusBar.tier.ws": "WebSocket",
     "hikari::statusPill.ms": " ミリ秒",
     "hikari::table.noData": "データなし",
+    "hikari::table.dragHandle": "ドラッグで並べ替え",
+    "hikari::table.dragHandleRow": "「{label}」の順序を変更",
     "hikari::tablePage.emptyTitle": "データがありません",
     "hikari::tabs.add": "タブを追加",
     "hikari::theme.customThemeName": "カスタムテーマ",

package/src/i18n/locales/ko/components.json

@@ -170,6 +170,8 @@
     "hikari::statusBar.tier.ws": "WebSocket",
     "hikari::statusPill.ms": " 밀리초",
     "hikari::table.noData": "데이터 없음",
+    "hikari::table.dragHandle": "드래그하여 순서 변경",
+    "hikari::table.dragHandleRow": "'{label}' 순서 변경",
     "hikari::tablePage.emptyTitle": "데이터 없음",
     "hikari::tabs.add": "탭 추가",
     "hikari::theme.customThemeName": "사용자 정의 테마",

package/src/i18n/locales/pt/components.json

@@ -170,6 +170,8 @@
     "hikari::statusBar.tier.ws": "WebSocket",
     "hikari::statusPill.ms": " ms",
     "hikari::table.noData": "Sem dados",
+    "hikari::table.dragHandle": "Arraste para reordenar",
+    "hikari::table.dragHandleRow": "Reordenar «{label}»",
     "hikari::tablePage.emptyTitle": "Sem dados",
     "hikari::tabs.add": "Adicionar separador",
     "hikari::theme.customThemeName": "Tema personalizado",

package/src/i18n/locales/ru/components.json

@@ -170,6 +170,8 @@
     "hikari::statusBar.tier.ws": "WebSocket",
     "hikari::statusPill.ms": " мс",
     "hikari::table.noData": "Нет данных",
+    "hikari::table.dragHandle": "Перетащите, чтобы изменить порядок",
+    "hikari::table.dragHandleRow": "Изменить порядок: {label}",
     "hikari::tablePage.emptyTitle": "Нет данных",
     "hikari::tabs.add": "Добавить вкладку",
     "hikari::theme.customThemeName": "Пользовательская тема",

package/src/i18n/locales/zh-Hans/components.json

@@ -170,6 +170,8 @@
     "hikari::statusBar.tier.ws": "WebSocket",
     "hikari::statusPill.ms": " 毫秒",
     "hikari::table.noData": "暂无数据",
+    "hikari::table.dragHandle": "拖动以调整顺序",
+    "hikari::table.dragHandleRow": "调整「{label}」的顺序",
     "hikari::tablePage.emptyTitle": "暂无数据",
     "hikari::tabs.add": "添加标签页",
     "hikari::theme.customThemeName": "自定义主题",

package/src/i18n/locales/zh-Hant/components.json

@@ -170,6 +170,8 @@
     "hikari::statusBar.tier.ws": "WebSocket",
     "hikari::statusPill.ms": " 毫秒",
     "hikari::table.noData": "暫無數據",
+    "hikari::table.dragHandle": "拖曳以調整順序",
+    "hikari::table.dragHandleRow": "調整「{label}」的順序",
     "hikari::tablePage.emptyTitle": "暫無資料",
     "hikari::tabs.add": "新增標籤頁",
     "hikari::theme.customThemeName": "自訂主題",