stimeo-ui 0.11.0 → 0.12.0

package/dist/controllers/smart_sticky_header_controller.js

@@ -1,19 +1,32 @@
 import { Controller } from '@hotwired/stimulus';
 
 // src/controllers/smart_sticky_header_controller.ts
+var DEFAULT_OFFSET = 80;
 var SmartStickyHeaderController = class extends Controller {
   static values = {
     containerSelector: { type: String, default: "" },
-    offset: { type: Number, default: 80 },
+    offset: { type: Number, default: DEFAULT_OFFSET },
     tolerance: { type: Number, default: 4 }
   };
   static events = ["change"];
+  #connected = false;
   #frame = null;
   /** The scroll source resolved at connect — disconnect must unbind the SAME node. */
   #scrollerEl = window;
+  /** The validated `containerSelector`, or `""` when the declaration cannot be parsed. */
+  #containerSelector = "";
   #lastY = 0;
   /** Last published state, so `change` fires only on transitions. */
   #hidden = null;
+  /**
+   * The depth that never hides. A declaration that is not a finite number reads
+   * as the default, so the comparison path never sees `NaN` — which would
+   * answer `false` to every comparison and hide the header inside the very
+   * zone the value exists to protect.
+   */
+  get #offset() {
+    return Number.isFinite(this.offsetValue) ? this.offsetValue : DEFAULT_OFFSET;
+  }
   #onScroll = () => {
     if (this.#frame !== null) return;
     this.#frame = requestAnimationFrame(() => {
@@ -26,15 +39,25 @@ var SmartStickyHeaderController = class extends Controller {
    * hold while focus *stays* inside is the `#apply` hide invariant.
    */
   #onFocusin = () => this.#apply(false);
+  /** Validates `containerSelector` once so connect never parses a selector that throws. */
+  containerSelectorValueChanged() {
+    this.#containerSelector = this.#validSelector(this.containerSelectorValue);
+  }
+  /** Re-decides when application code (or a Turbo morph) changes `offset` at runtime. */
+  offsetValueChanged() {
+    if (this.#connected) this.#measure();
+  }
   connect() {
     this.#hidden = null;
     this.#scrollerEl = this.#resolveScroller();
     this.#lastY = this.#scrollY;
     this.#scrollerEl.addEventListener("scroll", this.#onScroll, { passive: true });
     this.element.addEventListener("focusin", this.#onFocusin);
-    this.#apply(false);
+    this.#apply(false, false);
+    this.#connected = true;
   }
   disconnect() {
+    this.#connected = false;
     this.#scrollerEl.removeEventListener("scroll", this.#onScroll);
     this.element.removeEventListener("focusin", this.#onFocusin);
     if (this.#frame !== null) cancelAnimationFrame(this.#frame);
@@ -42,32 +65,51 @@ var SmartStickyHeaderController = class extends Controller {
   }
   /** Resolves the scroll source: the `containerSelector` match, else the window. */
   #resolveScroller() {
-    if (this.containerSelectorValue) {
-      const container = document.querySelector(this.containerSelectorValue);
+    if (this.#containerSelector) {
+      const container = document.querySelector(this.#containerSelector);
       if (container) return container;
     }
     return window;
   }
+  /** Returns `declared` when it parses as a selector, and `""` when it does not. */
+  #validSelector(declared) {
+    if (declared.length > 0) {
+      try {
+        this.element.matches(declared);
+        return declared;
+      } catch {
+      }
+    }
+    return "";
+  }
   get #scrollY() {
     const scroller = this.#scrollerEl;
     return scroller === window ? window.scrollY : scroller.scrollTop;
   }
   #measure() {
     const y = this.#scrollY;
+    if (y <= this.#offset) {
+      this.#lastY = y;
+      this.#apply(false);
+      return;
+    }
     const delta = y - this.#lastY;
     if (Math.abs(delta) < this.toleranceValue) return;
     this.#lastY = y;
-    if (y <= this.offsetValue) this.#apply(false);
-    else if (delta > 0) this.#apply(true);
-    else this.#apply(false);
+    this.#apply(delta > 0);
   }
-  /** Reflects the state onto the hook and emits `change` on transitions. */
-  #apply(hidden) {
+  /**
+   * Reflects the state onto the hook and emits `change` on transitions.
+   *
+   * @param notify - whether a transition announces itself. The reflection
+   *   `connect()` performs is the current state, not a change.
+   */
+  #apply(hidden, notify = true) {
     if (hidden && this.element.contains(document.activeElement)) return;
     if (hidden === this.#hidden) return;
     this.#hidden = hidden;
     this.element.setAttribute("data-header-hidden", hidden ? "true" : "false");
-    this.dispatch("change", { detail: { hidden } });
+    if (notify) this.dispatch("change", { detail: { hidden } });
   }
 };
 

package/dist/controllers/smart_sticky_header_controller.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/controllers/smart_sticky_header_controller.ts"],"names":[],"mappings":"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","file":"smart_sticky_header_controller.js","sourcesContent":["import { Controller } from \"@hotwired/stimulus\";\n\n/**\n * Headless **smart sticky header**: hides the header on scroll-down and\n * reveals it on scroll-up, published as a `data-header-hidden` hook the\n * consumer's CSS translates away (`stimeo--sticky-observer` detects *stuck*,\n * but has no direction sense; this adds it). Core (zero dependencies).\n *\n * Markup contract (identifier: `stimeo--smart-sticky-header`):\n *   <header data-controller=\"stimeo--smart-sticky-header\"\n *           style=\"position: sticky; top: 0;\">…</header>\n *\n * The scroll source is the window by default; inside an overflow container,\n * point `containerSelector` at it (the header usually sits inside it too).\n *   <!-- [data-header-hidden=\"true\"] { transform: translateY(-100%); } -->\n *\n * Scrolling down past `offset` px sets `data-header-hidden=\"true\"`; any\n * scroll-up (beyond the `tolerance` jitter guard) or returning above `offset`\n * reveals it again. Focus reaching the header always reveals it, and while\n * focus stays inside the header a scroll-down never hides it — a keyboard\n * user must be able to see where focus went AND keep seeing the element that\n * owns it (WCAG 2.4.7 / 2.4.11).\n *\n * `change` dispatches `{ hidden }`.\n *\n * @remarks\n * Behavior only — `position: sticky`, the translate animation, and\n * reduced-motion handling are the consumer's CSS (`prefers-reduced-motion`\n * should disable the transition, not the behavior). Scroll work is\n * rAF-throttled; listeners and any pending frame are released on\n * `disconnect()`, and `connect()` resets the transient hook (a Turbo cache\n * snapshot must not restore a hidden header at scroll top).\n */\nexport class SmartStickyHeaderController extends Controller<HTMLElement> {\n  static override values = {\n    containerSelector: { type: String, default: \"\" },\n    offset: { type: Number, default: 80 },\n    tolerance: { type: Number, default: 4 },\n  };\n  static events = [\"change\"] as const;\n\n  declare containerSelectorValue: string;\n  declare offsetValue: number;\n  declare toleranceValue: number;\n\n  #frame: number | null = null;\n  /** The scroll source resolved at connect — disconnect must unbind the SAME node. */\n  #scrollerEl: HTMLElement | Window = window;\n  #lastY = 0;\n  /** Last published state, so `change` fires only on transitions. */\n  #hidden: boolean | null = null;\n\n  readonly #onScroll = (): void => {\n    if (this.#frame !== null) return;\n    this.#frame = requestAnimationFrame(() => {\n      this.#frame = null;\n      this.#measure();\n    });\n  };\n\n  /**\n   * Focus inside a hidden header must reveal it (WCAG 2.4.7 / 2.4.11); the\n   * hold while focus *stays* inside is the `#apply` hide invariant.\n   */\n  readonly #onFocusin = (): void => this.#apply(false);\n\n  override connect(): void {\n    // The hook is scroll-derived: recompute from the live scroll position\n    // instead of trusting a cached snapshot (which may say hidden at y=0).\n    this.#hidden = null;\n    this.#scrollerEl = this.#resolveScroller();\n    this.#lastY = this.#scrollY;\n    this.#scrollerEl.addEventListener(\"scroll\", this.#onScroll, { passive: true });\n    this.element.addEventListener(\"focusin\", this.#onFocusin);\n    this.#apply(false);\n  }\n\n  override disconnect(): void {\n    this.#scrollerEl.removeEventListener(\"scroll\", this.#onScroll);\n    this.element.removeEventListener(\"focusin\", this.#onFocusin);\n    if (this.#frame !== null) cancelAnimationFrame(this.#frame);\n    this.#frame = null;\n  }\n\n  /** Resolves the scroll source: the `containerSelector` match, else the window. */\n  #resolveScroller(): HTMLElement | Window {\n    if (this.containerSelectorValue) {\n      const container = document.querySelector<HTMLElement>(this.containerSelectorValue);\n      if (container) return container;\n    }\n    return window;\n  }\n\n  get #scrollY(): number {\n    const scroller = this.#scrollerEl;\n    // Identity check, not `instanceof Window` — cross-realm/test DOMs fail it.\n    return scroller === window ? window.scrollY : (scroller as HTMLElement).scrollTop;\n  }\n\n  #measure(): void {\n    const y = this.#scrollY;\n    const delta = y - this.#lastY;\n    if (Math.abs(delta) < this.toleranceValue) return;\n    this.#lastY = y;\n\n    if (y <= this.offsetValue) this.#apply(false);\n    else if (delta > 0) this.#apply(true);\n    else this.#apply(false);\n  }\n\n  /** Reflects the state onto the hook and emits `change` on transitions. */\n  #apply(hidden: boolean): void {\n    // Invariant: a header holding focus is never hidden — `focusin` revealed\n    // it, and no transition may slide the focus owner away mid-interaction\n    // (WCAG 2.4.7 / 2.4.11). Vetoed here at the single state-transition choke\n    // point (not in each caller), so any future hide path — a timer, an\n    // action — cannot bypass it. Reveals are never vetoed.\n    if (hidden && this.element.contains(document.activeElement)) return;\n    if (hidden === this.#hidden) return;\n    this.#hidden = hidden;\n    this.element.setAttribute(\"data-header-hidden\", hidden ? \"true\" : \"false\");\n    this.dispatch(\"change\", { detail: { hidden } });\n  }\n}\n"]}
+{"version":3,"sources":["../../src/controllers/smart_sticky_header_controller.ts"],"names":[],"mappings":"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","file":"smart_sticky_header_controller.js","sourcesContent":["import { Controller } from \"@hotwired/stimulus\";\n\n/** The depth that never hides, used when `offset` is not a finite number. */\nconst DEFAULT_OFFSET = 80;\n\n/**\n * Headless **smart sticky header**: hides the header on scroll-down and\n * reveals it on scroll-up, published as a `data-header-hidden` hook the\n * consumer's CSS translates away (`stimeo--sticky-observer` detects *stuck*,\n * but has no direction sense; this adds it). Core (zero dependencies).\n *\n * Markup contract (identifier: `stimeo--smart-sticky-header`):\n *   <header data-controller=\"stimeo--smart-sticky-header\"\n *           style=\"position: sticky; top: 0;\">…</header>\n *\n * The scroll source is the window by default; inside an overflow container,\n * point `containerSelector` at it (the header usually sits inside it too). A\n * declaration that cannot be parsed as a selector reads as the window, so a\n * typo costs the container binding rather than the whole header.\n *   <!-- [data-header-hidden=\"true\"] { transform: translateY(-100%); } -->\n *\n * Scrolling down past `offset` px sets `data-header-hidden=\"true\"`, and a\n * scroll-up beyond the `tolerance` jitter guard reveals it again. Within the\n * `offset` zone the header is always revealed, decided ahead of that jitter\n * guard: a header stranded off-screen near the top cannot be scrolled back\n * into view. Focus reaching the header always reveals it, and while focus\n * stays inside the header a scroll-down never hides it — a keyboard user must\n * be able to see where focus went AND keep seeing the element that owns it\n * (WCAG 2.4.7 / 2.4.11).\n *\n * `change` dispatches `{ hidden }` on transitions only: the reflection\n * `connect()` performs is the current state rather than a change.\n *\n * @remarks\n * Behavior only — `position: sticky`, the translate animation, and\n * reduced-motion handling are the consumer's CSS (`prefers-reduced-motion`\n * should disable the transition, not the behavior). Scroll work is\n * rAF-throttled; listeners and any pending frame are released on\n * `disconnect()`, and `connect()` resets the transient hook (a Turbo cache\n * snapshot must not restore a hidden header at scroll top).\n */\nexport class SmartStickyHeaderController extends Controller<HTMLElement> {\n  static override values = {\n    containerSelector: { type: String, default: \"\" },\n    offset: { type: Number, default: DEFAULT_OFFSET },\n    tolerance: { type: Number, default: 4 },\n  };\n  static events = [\"change\"] as const;\n\n  declare containerSelectorValue: string;\n  declare offsetValue: number;\n  declare toleranceValue: number;\n\n  #connected = false;\n  #frame: number | null = null;\n  /** The scroll source resolved at connect — disconnect must unbind the SAME node. */\n  #scrollerEl: HTMLElement | Window = window;\n  /** The validated `containerSelector`, or `\"\"` when the declaration cannot be parsed. */\n  #containerSelector = \"\";\n  #lastY = 0;\n  /** Last published state, so `change` fires only on transitions. */\n  #hidden: boolean | null = null;\n\n  /**\n   * The depth that never hides. A declaration that is not a finite number reads\n   * as the default, so the comparison path never sees `NaN` — which would\n   * answer `false` to every comparison and hide the header inside the very\n   * zone the value exists to protect.\n   */\n  get #offset(): number {\n    return Number.isFinite(this.offsetValue) ? this.offsetValue : DEFAULT_OFFSET;\n  }\n\n  readonly #onScroll = (): void => {\n    if (this.#frame !== null) return;\n    this.#frame = requestAnimationFrame(() => {\n      this.#frame = null;\n      this.#measure();\n    });\n  };\n\n  /**\n   * Focus inside a hidden header must reveal it (WCAG 2.4.7 / 2.4.11); the\n   * hold while focus *stays* inside is the `#apply` hide invariant.\n   */\n  readonly #onFocusin = (): void => this.#apply(false);\n\n  /** Validates `containerSelector` once so connect never parses a selector that throws. */\n  containerSelectorValueChanged(): void {\n    this.#containerSelector = this.#validSelector(this.containerSelectorValue);\n  }\n\n  /** Re-decides when application code (or a Turbo morph) changes `offset` at runtime. */\n  offsetValueChanged(): void {\n    if (this.#connected) this.#measure();\n  }\n\n  override connect(): void {\n    // The hook is scroll-derived: recompute from the live scroll position\n    // instead of trusting a cached snapshot (which may say hidden at y=0).\n    this.#hidden = null;\n    this.#scrollerEl = this.#resolveScroller();\n    this.#lastY = this.#scrollY;\n    this.#scrollerEl.addEventListener(\"scroll\", this.#onScroll, { passive: true });\n    this.element.addEventListener(\"focusin\", this.#onFocusin);\n    this.#apply(false, false);\n    this.#connected = true;\n  }\n\n  override disconnect(): void {\n    this.#connected = false;\n    this.#scrollerEl.removeEventListener(\"scroll\", this.#onScroll);\n    this.element.removeEventListener(\"focusin\", this.#onFocusin);\n    if (this.#frame !== null) cancelAnimationFrame(this.#frame);\n    this.#frame = null;\n  }\n\n  /** Resolves the scroll source: the `containerSelector` match, else the window. */\n  #resolveScroller(): HTMLElement | Window {\n    if (this.#containerSelector) {\n      const container = document.querySelector<HTMLElement>(this.#containerSelector);\n      if (container) return container;\n    }\n    return window;\n  }\n\n  /** Returns `declared` when it parses as a selector, and `\"\"` when it does not. */\n  #validSelector(declared: string): string {\n    if (declared.length > 0) {\n      try {\n        this.element.matches(declared);\n        return declared;\n      } catch {\n        // Unparsable selector: fall through to the default below.\n      }\n    }\n    return \"\";\n  }\n\n  get #scrollY(): number {\n    const scroller = this.#scrollerEl;\n    // Identity check, not `instanceof Window` — cross-realm/test DOMs fail it.\n    return scroller === window ? window.scrollY : (scroller as HTMLElement).scrollTop;\n  }\n\n  #measure(): void {\n    const y = this.#scrollY;\n    // The offset zone decides before the jitter guard: a move small enough to\n    // be jitter can still be the one that re-enters the zone, and a header\n    // left hidden there cannot be scrolled back into view.\n    if (y <= this.#offset) {\n      this.#lastY = y;\n      this.#apply(false);\n      return;\n    }\n\n    const delta = y - this.#lastY;\n    if (Math.abs(delta) < this.toleranceValue) return;\n    this.#lastY = y;\n    this.#apply(delta > 0);\n  }\n\n  /**\n   * Reflects the state onto the hook and emits `change` on transitions.\n   *\n   * @param notify - whether a transition announces itself. The reflection\n   *   `connect()` performs is the current state, not a change.\n   */\n  #apply(hidden: boolean, notify = true): void {\n    // Invariant: a header holding focus is never hidden — `focusin` revealed\n    // it, and no transition may slide the focus owner away mid-interaction\n    // (WCAG 2.4.7 / 2.4.11). Vetoed here at the single state-transition choke\n    // point (not in each caller), so any future hide path — a timer, an\n    // action — cannot bypass it. Reveals are never vetoed.\n    if (hidden && this.element.contains(document.activeElement)) return;\n    if (hidden === this.#hidden) return;\n    this.#hidden = hidden;\n    this.element.setAttribute(\"data-header-hidden\", hidden ? \"true\" : \"false\");\n    if (notify) this.dispatch(\"change\", { detail: { hidden } });\n  }\n}\n"]}

package/dist/controllers/sortable_controller.d.ts

@@ -7,7 +7,7 @@ import { Controller } from '@hotwired/stimulus';
  * layer keeps its job: `pointer-drag` (on every item) emits the normalized drag
  * signal with its built-in keyboard alternative, `roving` (on the list) keeps
  * the handles a single Tab stop, and this controller interprets the signal —
- * live-reordering the DOM, announcing each step through a `status` live region,
+ * live-reordering the DOM, handing each step to the page's shared announcer,
  * and reporting the final `reorder`. No dedicated APG pattern exists for
  * drag-and-drop; the keyboard model (grab → arrows → drop / Escape) comes from
  * `pointer-drag` and the announcements make it non-visually trackable
@@ -27,7 +27,6 @@ import { Controller } from '@hotwired/stimulus';
  *       </li>
  *       …
  *     </ul>
- *     <span role="status" data-stimeo--sortable-target="status"></span>
  *   </div>
  *
  * The composed values must follow the sort axis: roving's `orientation`
@@ -41,10 +40,11 @@ import { Controller } from '@hotwired/stimulus';
  * `dir="rtl"` reverses both, since DOM order then runs right-to-left while
  * `pointer-drag` reports physical coordinates. Dropping dispatches
  * `reorder` (`{ item, from, to }`, zero-based) when the position changed;
- * Escape / `pointercancel` restores the pickup position. Every step is mirrored
- * into the `status` live region (localizable via `data-grabbed` / `data-moved`
- * / `data-dropped` / `data-canceled` templates with `%{name}` / `%{position}` /
- * `%{total}` placeholders; terse English is the fallback).
+ * Escape / `pointercancel` restores the pickup position. Every step is handed to
+ * the page's shared `stimeo--announcer` as the consumer's own wording —
+ * `announceGrabbedText` / `announceMovedText` / `announceDroppedText` /
+ * `announceCanceledText`, with `{name}` / `{position}` / `{total}` placeholders —
+ * and an unset one announces nothing.
  *
  * @remarks
  * Behavior only — the ghost/placeholder/drop-hint visuals are the consumer's
@@ -67,16 +67,46 @@ declare class SortableController extends Controller<HTMLElement> {
             type: StringConstructor;
             default: string;
         };
+        announceGrabbedText: {
+            type: StringConstructor;
+            default: string;
+        };
+        announceMovedText: {
+            type: StringConstructor;
+            default: string;
+        };
+        announceDroppedText: {
+            type: StringConstructor;
+            default: string;
+        };
+        announceCanceledText: {
+            type: StringConstructor;
+            default: string;
+        };
     };
     static events: readonly ["reorder"];
     readonly hasListTarget: boolean;
     readonly listTarget: HTMLElement;
     readonly itemTargets: HTMLElement[];
-    readonly hasStatusTarget: boolean;
-    readonly statusTarget: HTMLElement;
     orientationValue: string;
+    announceGrabbedTextValue: string;
+    announceMovedTextValue: string;
+    announceDroppedTextValue: string;
+    announceCanceledTextValue: string;
     connect(): void;
     disconnect(): void;
+    /**
+     * Ends a session whose item left the item set.
+     *
+     * The controller's own reorder detaches and reattaches the item inside one
+     * mutation batch, so the loss is only real once the batch has settled — the
+     * check therefore runs a microtask later and asks whether the item is a target
+     * again. Without it a deleted row (a broadcast that drops it from the board)
+     * or a morph that strips the item's target attribute would hold the
+     * one-at-a-time session for the rest of the page's life, with the root hook
+     * stuck on and every later grab refused with no way out.
+     */
+    itemTargetDisconnected(item: HTMLElement): void;
 }
 
 export { SortableController };

package/dist/controllers/sortable_controller.js

@@ -2,21 +2,78 @@ import { Controller } from '@hotwired/stimulus';
 
 // src/controllers/sortable_controller.ts
 
+// src/utils/announce.ts
+function announce(message, options = {}) {
+  const text = message.trim();
+  if (text.length === 0) return;
+  window.dispatchEvent(
+    new CustomEvent("stimeo--announcer:announce", {
+      detail: { message: text, assertive: options.assertive === true }
+    })
+  );
+}
+function fillTemplate(template, values) {
+  return template.replace(/\{([a-zA-Z][a-zA-Z0-9]*)\}/g, (match, name) => {
+    const replacement = values[name];
+    return replacement === void 0 ? match : String(replacement);
+  });
+}
+
 // src/utils/logical_scroll.ts
 function isRtl(element) {
   return window.getComputedStyle(element).direction === "rtl";
 }
 
+// src/utils/microtask_coalescer.ts
+var MicrotaskCoalescer = class {
+  #run;
+  #queued = false;
+  #active = false;
+  #generation = 0;
+  /** @param run - the single reconciliation pass, invoked at most once per batch. */
+  constructor(run) {
+    this.#run = run;
+  }
+  /** Opens the window in which {@link schedule} is honoured; call from `connect()`. */
+  activate() {
+    this.#active = true;
+  }
+  /** Closes the window and drops any pending pass; call from `disconnect()`. */
+  cancel() {
+    this.#active = false;
+    this.#queued = false;
+    this.#generation += 1;
+  }
+  /** Requests one pass after the batch settles. Idempotent; inert outside the window. */
+  schedule() {
+    if (!this.#active || this.#queued) return;
+    this.#queued = true;
+    const generation = this.#generation;
+    queueMicrotask(() => {
+      if (generation !== this.#generation || !this.#queued || !this.#active) return;
+      this.#queued = false;
+      this.#run();
+    });
+  }
+};
+
 // src/controllers/sortable_controller.ts
 var SortableController = class extends Controller {
-  static targets = ["list", "item", "status"];
+  static targets = ["list", "item"];
   static values = {
-    orientation: { type: String, default: "vertical" }
+    orientation: { type: String, default: "vertical" },
+    announceGrabbedText: { type: String, default: "" },
+    announceMovedText: { type: String, default: "" },
+    announceDroppedText: { type: String, default: "" },
+    announceCanceledText: { type: String, default: "" }
   };
   static events = ["reorder"];
   #session = null;
+  /** Defers the lost-item check to after the mutation batch (see below). */
+  #settle = new MicrotaskCoalescer(() => this.#dropLostSession());
   connect() {
     this.element.removeAttribute("data-sortable-dragging");
+    this.#settle.activate();
     this.element.addEventListener("stimeo--pointer-drag:start", this.#onDragStart);
     this.element.addEventListener("stimeo--pointer-drag:move", this.#onDragMove);
     this.element.addEventListener("stimeo--pointer-drag:end", this.#onDragEnd);
@@ -27,49 +84,121 @@ var SortableController = class extends Controller {
     this.element.removeEventListener("stimeo--pointer-drag:move", this.#onDragMove);
     this.element.removeEventListener("stimeo--pointer-drag:end", this.#onDragEnd);
     this.element.removeEventListener("stimeo--pointer-drag:cancel", this.#onDragCancel);
+    this.#settle.cancel();
     this.#session = null;
     this.element.removeAttribute("data-sortable-dragging");
   }
-  /** Picks the item up: remembers its origin and announces the grab. */
+  /**
+   * Ends a session whose item left the item set.
+   *
+   * The controller's own reorder detaches and reattaches the item inside one
+   * mutation batch, so the loss is only real once the batch has settled — the
+   * check therefore runs a microtask later and asks whether the item is a target
+   * again. Without it a deleted row (a broadcast that drops it from the board)
+   * or a morph that strips the item's target attribute would hold the
+   * one-at-a-time session for the rest of the page's life, with the root hook
+   * stuck on and every later grab refused with no way out.
+   */
+  itemTargetDisconnected(item) {
+    if (this.#session?.item !== item) return;
+    this.#settle.schedule();
+  }
+  #dropLostSession() {
+    const session = this.#session;
+    if (!session) return;
+    const items = this.#items();
+    if (items.includes(session.item)) return;
+    this.#session = null;
+    this.element.removeAttribute("data-sortable-dragging");
+    if (session.item.isConnected) this.#restore(session, items);
+  }
+  /** Picks the item up: remembers its neighbours and announces the grab. */
   #onDragStart = (event) => {
     if (this.#session) return;
-    const item = this.#itemFor(event.target);
+    const items = this.#items();
+    const item = this.#itemFor(event.target, items);
     if (!item) return;
-    this.#session = { item, from: this.#items().indexOf(item), lastPrimary: 0 };
+    const index = items.indexOf(item);
+    this.#session = {
+      item,
+      anchor: items[index + 1] ?? null,
+      predecessor: items[index - 1] ?? null,
+      lastPrimary: 0
+    };
     this.element.setAttribute("data-sortable-dragging", "true");
     this.#announce("grabbed", item);
   };
   #onDragMove = (event) => {
     const session = this.#session;
+    if (!session) return;
+    const items = this.#items();
+    if (this.#itemFor(event.target, items) !== session.item) return;
     const detail = event.detail;
-    if (!session || this.#itemFor(event.target) !== session.item) return;
     if (detail.pointerType === "keyboard") {
-      this.#stepFromKeyboard(session, detail);
+      this.#stepFromKeyboard(session, detail, items);
     } else {
-      this.#followPointer(session, detail);
+      this.#followPointer(session, detail, items);
     }
   };
   /** Drops the item: announces, then reports `reorder` if the position changed. */
   #onDragEnd = (event) => {
     const session = this.#session;
-    if (!session || this.#itemFor(event.target) !== session.item) return;
+    if (!session) return;
+    const items = this.#items();
+    if (this.#itemFor(event.target, items) !== session.item) return;
     this.#session = null;
     this.element.removeAttribute("data-sortable-dragging");
     this.#announce("dropped", session.item);
-    const to = this.#items().indexOf(session.item);
-    if (to !== session.from) {
-      this.dispatch("reorder", { detail: { item: session.item, from: session.from, to } });
+    const to = items.indexOf(session.item);
+    const from = this.#pickupSlot(session, items) ?? to;
+    if (to !== from) {
+      this.dispatch("reorder", { detail: { item: session.item, from, to } });
     }
   };
   /** Restores the pickup position (Escape / OS `pointercancel`). */
   #onDragCancel = (event) => {
     const session = this.#session;
-    if (!session || this.#itemFor(event.target) !== session.item) return;
+    if (!session) return;
+    const items = this.#items();
+    if (this.#itemFor(event.target, items) !== session.item) return;
     this.#session = null;
     this.element.removeAttribute("data-sortable-dragging");
-    this.#moveTo(session.item, session.from);
+    this.#restore(session, items);
     this.#announce("canceled", session.item);
   };
+  /**
+   * The slot the item was picked up from, read back through the neighbours it
+   * had then — `null` when neither survives and the item itself is gone.
+   *
+   * The anchor is the item that followed it, so restoring means "before that one
+   * again". When the anchor was deleted mid-drag the predecessor answers the
+   * same question from the other side. With both gone the item's current slot is
+   * the honest answer: nothing is known to have moved, so no reorder is reported
+   * and a cancel leaves the item where it is.
+   */
+  #pickupSlot(session, items) {
+    const others = items.filter((candidate) => candidate !== session.item);
+    if (session.anchor) {
+      const at = others.indexOf(session.anchor);
+      if (at !== -1) return at;
+    }
+    if (session.predecessor) {
+      const at = others.indexOf(session.predecessor);
+      if (at !== -1) return at + 1;
+    }
+    const here = items.indexOf(session.item);
+    return here === -1 ? null : here;
+  }
+  /** Puts the item back where it was picked up from. */
+  #restore(session, items) {
+    const slot = this.#pickupSlot(session, items);
+    if (slot === null) return;
+    this.#insertAt(
+      session.item,
+      items.filter((candidate) => candidate !== session.item),
+      slot
+    );
+  }
   /**
    * Keyboard stepping: `pointer-drag` reports *cumulative* synthetic deltas, so
    * the difference from the last consumed value is one arrow press — its sign is
@@ -81,77 +210,116 @@ var SortableController = class extends Controller {
    * `roving` already moves focus logically, so the same arrow would send the
    * focus and the grabbed item opposite ways.
    */
-  #stepFromKeyboard(session, detail) {
+  #stepFromKeyboard(session, detail, items) {
     const primary = Number(this.#isVertical ? detail.dy : detail.dx) || 0;
     const delta = primary - session.lastPrimary;
     session.lastPrimary = primary;
     if (delta === 0) return;
-    const items = this.#items();
     const index = items.indexOf(session.item);
     const step = (delta > 0 ? 1 : -1) * (this.#isReversed ? -1 : 1);
     const next = Math.max(0, Math.min(index + step, items.length - 1));
     if (next === index) return;
-    this.#moveTo(session.item, next);
+    this.#insertAt(
+      session.item,
+      items.filter((candidate) => candidate !== session.item),
+      next
+    );
     this.#announce("moved", session.item);
   }
   /**
    * Pointer following: the item moves to the slot whose siblings' midpoints the
-   * pointer has passed (per `orientation`). Skipped when the list has no layout
-   * geometry (every rect is zero — nothing meaningful to compare against).
+   * pointer has passed (per `orientation`).
+   *
+   * Only siblings that occupy space take part. A row with no layout box — a
+   * filtered-out item, a `display: none` ancestor, a collapsed `<details>` — is
+   * reported with an empty rect at the document origin, and its midpoint of `0`
+   * sits below every pointer position: counted, it would read as passed on the
+   * very first move and send the item across a slot the pointer never crossed.
+   * With no laid-out sibling at all there is nothing to compare against and the
+   * move is skipped entirely.
    */
-  #followPointer(session, detail) {
+  #followPointer(session, detail, items) {
     const pointer = Number(this.#isVertical ? detail.y : detail.x) || 0;
-    const others = this.#items().filter((item) => item !== session.item);
-    if (others.length === 0) return;
-    let laidOut = false;
-    let target = 0;
+    const vertical = this.#isVertical;
     const reversed = this.#isReversed;
-    for (const other of others) {
-      const rect = other.getBoundingClientRect();
-      if (rect.width > 0 || rect.height > 0) laidOut = true;
-      const midpoint = this.#isVertical ? rect.top + rect.height / 2 : rect.left + rect.width / 2;
-      const precedes = reversed ? pointer < midpoint : pointer > midpoint;
-      if (precedes) target += 1;
-    }
-    if (!laidOut) return;
-    const current = this.#items().indexOf(session.item);
-    if (target !== current) {
-      this.#moveTo(session.item, target);
-      this.#announce("moved", session.item);
-    }
+    const here = items.indexOf(session.item);
+    const laidOut = [];
+    let target = 0;
+    let current = 0;
+    items.forEach((item, index) => {
+      if (item === session.item) return;
+      const rect = item.getBoundingClientRect();
+      if (rect.width === 0 && rect.height === 0) return;
+      if (index < here) current += 1;
+      laidOut.push(item);
+      const midpoint = vertical ? rect.top + rect.height / 2 : rect.left + rect.width / 2;
+      if (reversed ? pointer < midpoint : pointer > midpoint) target += 1;
+    });
+    if (laidOut.length === 0 || target === current) return;
+    this.#insertAt(session.item, laidOut, target);
+    this.#announce("moved", session.item);
   }
-  /** Reinserts `item` so it lands at `index` among the list's items. */
-  #moveTo(item, index) {
-    const others = this.#items().filter((candidate) => candidate !== item);
-    const clamped = Math.max(0, Math.min(index, others.length));
-    const reference = others[clamped] ?? null;
+  /**
+   * Reinserts `item` at `index` among `scope`, relative to the sibling already
+   * standing there.
+   *
+   * The reorder is defined against the items, not against a container: the
+   * neighbour's own parent is where the item belongs. A `list` target that is
+   * not the items' parent — or none at all, which the markup contract allows —
+   * therefore still lands the move in the right place instead of throwing, and
+   * the last slot is *after the last item* rather than after whatever else the
+   * container holds (a live region, a footer), which would put the row outside
+   * the reading order the list publishes.
+   */
+  #insertAt(item, scope, index) {
+    const clamped = Math.max(0, Math.min(index, scope.length));
+    const ahead = scope[clamped] ?? null;
+    const behind = ahead ? null : scope[scope.length - 1] ?? null;
+    const neighbour = ahead ?? behind;
+    if (!neighbour) return;
+    const parent = neighbour.parentNode;
+    if (!parent) return;
     const active = document.activeElement;
     const hadFocus = active instanceof HTMLElement && item.contains(active);
-    this.#list.insertBefore(item, reference);
+    parent.insertBefore(item, ahead ?? neighbour.nextSibling);
     if (hadFocus) active.focus();
   }
   /**
-   * Mirrors a step into the `status` live region. Copy is localizable through
-   * `data-grabbed` / `data-moved` / `data-dropped` / `data-canceled` templates on
-   * the status element (`%{name}` / `%{position}` / `%{total}` placeholders);
-   * terse English is the fallback.
+   * Hands one step to the page's shared announcer.
+   *
+   * The library carries no live region and no English copy: the wording is the
+   * consumer's, written into `announceGrabbedText` / `announceMovedText` /
+   * `announceDroppedText` / `announceCanceledText` with `{name}` / `{position}` /
+   * `{total}` placeholders, and an unset one announces nothing.
+   *
+   * Only transitions reach here — the pickup, a step that actually changed the
+   * landing slot, and the single end of the session — so a pointer crossing the
+   * same slot twice or an arrow clamped at an end stays silent.
    */
   #announce(key, item) {
-    if (!this.hasStatusTarget) return;
-    const position = String(this.#items().indexOf(item) + 1);
-    const total = String(this.#items().length);
-    const name = this.#nameOf(item);
-    const fallback = {
-      grabbed: `Grabbed ${name}, position ${position} of ${total}`,
-      moved: `${name}, position ${position} of ${total}`,
-      dropped: `Dropped ${name} at position ${position} of ${total}`,
-      canceled: `Reorder canceled, ${name} returned to position ${position} of ${total}`
-    };
-    const values = { name, position, total };
-    const template = this.statusTarget.dataset[key];
-    this.statusTarget.textContent = template ? template.replace(/%\{(name|position|total)\}/g, (match, token) => {
-      return values[token] ?? match;
-    }) : fallback[key];
+    const template = this.#announceTemplate(key);
+    if (template.length === 0) return;
+    const items = this.#items();
+    announce(
+      fillTemplate(template, {
+        name: this.#nameOf(item),
+        position: items.indexOf(item) + 1,
+        total: items.length
+      })
+    );
+  }
+  /** The consumer's wording for one step, or `""` when they authored none. */
+  #announceTemplate(key) {
+    switch (key) {
+      case "grabbed":
+        return this.announceGrabbedTextValue;
+      case "moved":
+        return this.announceMovedTextValue;
+      case "dropped":
+        return this.announceDroppedTextValue;
+      case "canceled":
+        return this.announceCanceledTextValue;
+    }
   }
   /** The announced item name: the authored override, else its collapsed text. */
   #nameOf(item) {
@@ -159,11 +327,17 @@ var SortableController = class extends Controller {
     if (authored) return authored;
     return (item.textContent ?? "").replace(/\s+/g, " ").trim();
   }
-  /** Resolves the sortable item owning a bubbled `pointer-drag` event. */
-  #itemFor(target) {
-    const node = target;
-    if (!node) return null;
-    return this.#items().find((item) => item === node || item.contains(node)) ?? null;
+  /**
+   * Resolves the sortable item owning a bubbled `pointer-drag` event.
+   *
+   * `pointer-drag` dispatches on its own element, and the markup contract puts
+   * one on each item, so the owner is the item that **is** the target. Matching
+   * an ancestor instead would make a card's own inner draggable — a knob, a
+   * split pane, anything the primitive is composed into — drive the card.
+   */
+  #itemFor(target, items) {
+    if (!target) return null;
+    return items.find((item) => item === target) ?? null;
   }
   /** The items in live DOM order (targets re-query the DOM on every access). */
   #items() {