stimeo-ui 0.11.0 → 0.12.0

data/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() {

data/dist/controllers/sticky_observer_controller.js

@@ -9,6 +9,14 @@ function isBeforeRootStart(entry) {
   const rootTop = entry.rootBounds?.top ?? 0;
   return rect.bottom <= rootTop;
 }
+function queryRoot(selector) {
+  if (!selector) return null;
+  try {
+    return document.querySelector(selector);
+  } catch {
+  }
+  return null;
+}
 var IntersectionWatcher = class {
   #onEntries;
   #observer = null;
@@ -30,7 +38,10 @@ var IntersectionWatcher = class {
    * the watcher inert — without `IntersectionObserver` support (very old
    * browsers; the caller's no-JS fallback stays in charge) or with no targets.
    * If initial construction with the configured options fails, the watcher
-   * warns and retries once with the same root and platform defaults.
+   * warns and retries once with the same root and platform defaults. A
+   * `rootSelector` that does not parse resolves to the viewport (see
+   * {@link IntersectionWatchOptions.rootSelector}), so a typo never fails the
+   * call.
    *
    * @throws The fallback constructor error if both construction attempts fail,
    *   or whatever the platform throws from `observe()`. The exception is passed
@@ -43,7 +54,7 @@ var IntersectionWatcher = class {
     if (typeof IntersectionObserver === "undefined") return false;
     const list = Array.isArray(targets) ? targets : [targets];
     if (list.length === 0) return false;
-    const root = "root" in options ? options.root ?? null : options.rootSelector ? document.querySelector(options.rootSelector) : null;
+    const root = "root" in options ? options.root ?? null : queryRoot(options.rootSelector);
     let observer = null;
     try {
       const onEntries = (entries) => {