stimeo-ui 0.16.0 → 0.18.0

package/dist/controllers/direct_upload_controller.d.ts

@@ -4,7 +4,7 @@ import { Controller } from '@hotwired/stimulus';
  * Headless progress UI for ActiveStorage Direct Uploads: subscribes to the
  * `direct-upload:*` events and renders a per-file progress row (no dedicated APG
  * pattern; the rows follow the `role="progressbar"` practice). The companion to
- * {@link FileDropzoneController}, which leaves transport out of scope.
+ * `stimeo--file-dropzone`, which leaves transport out of scope.
  *
  * Markup contract (identifier: `stimeo--direct-upload`):
  *   <div data-controller="stimeo--direct-upload"
@@ -25,8 +25,8 @@ import { Controller } from '@hotwired/stimulus';
  * fills `[data-field="name"]` and becomes the row's `aria-label` unless the
  * template already authors one. The aggregate across live rows is mirrored on
  * the controller element as `data-upload-progress` plus the same custom
- * property, recomputed whenever a row is added, updated, or removed, and
- * withdrawn entirely once no rows remain.
+ * property, recomputed whenever a row is added, updated, or removed, or a `list`
+ * leaves, and withdrawn entirely once no rows remain.
  *
  * A row leaves `uploading` exactly once: `direct-upload:error` settles it as
  * `error`, and `direct-upload:end` — which ActiveStorage fires after success
@@ -49,7 +49,8 @@ import { Controller } from '@hotwired/stimulus';
  * - `stimeo--direct-upload:done` dispatches `{ id: string }` when an upload
  *   completes successfully.
  * - `stimeo--direct-upload:reconcile` dispatches `{ ids: string[] }` — the uploads
- *   the Turbo cache rewind discarded, none of which can still finish.
+ *   whose rows a page restored from the Turbo cache still showed, none of which can
+ *   still finish.
  * - `stimeo--direct-upload:error` dispatches `{ id: string, error: string }`
  *   when an upload fails.
  *
@@ -57,10 +58,18 @@ import { Controller } from '@hotwired/stimulus';
  * Behavior only — no bars are drawn. The `direct-upload:*` listeners live on
  * `document` (the events bubble there) and are removed on `disconnect()` (Turbo
  * navigation included), along with any pending removal timers, so a callback
- * that arrives after teardown never touches a detached row. Rows are transient
- * UI: just before Turbo caches the page they are removed and the aggregate is
- * withdrawn, so a restored snapshot starts pristine instead of replaying stale
- * rows (a dead upload cannot resume after restoration). The live DOM stays the
+ * that arrives after teardown never touches a detached row. `removeOnDone` follows a
+ * change made while connected: turning it off cancels every pending removal, turning
+ * it on arms one for each completed row still shown, with the full delay from then,
+ * and a row never holds more than one pending removal. Rows are transient
+ * UI, and each carries `data-<identifier>-generated` with its upload id. A page Turbo
+ * restores from its cache is a copy that still shows them, so a connection holding no
+ * row of its own removes the marked rows in its list, withdraws the aggregate and
+ * reports the discarded ids as `reconcile` (a dead upload cannot resume after
+ * restoration). Nothing is removed on `turbo:before-cache`, which Turbo also
+ * dispatches on pages that stay — a promoted frame navigation, a state-less
+ * `popstate`, a refresh of a cached URL, a `data-turbo-permanent` element carried to
+ * the next page — where the uploads are still running. The live DOM stays the
  * source of truth — a row removed or replaced outside this controller is
  * forgotten and rebuilt on the next event for its id, and a clone stranded
  * outside the current `list` (a re-pointed target) is removed outright, so
@@ -106,6 +115,14 @@ declare class DirectUploadController extends Controller<HTMLElement> {
     disconnect(): void;
     /** Validates `scope` once so the per-event path never parses or throws. */
     scopeValueChanged(): void;
+    /**
+     * Follows `removeOnDone` changed at runtime: off cancels every pending removal, on
+     * arms one for each completed row that has none, with the full delay from now.
+     * Stimulus also calls this ahead of `connect()`, which arms the removals itself.
+     */
+    removeOnDoneValueChanged(): void;
+    /** Recounts the aggregate once a list leaves, retiring rows outside the list that stays. */
+    listTargetDisconnected(): void;
 }
 
 export { DirectUploadController };

package/dist/controllers/direct_upload_controller.js

@@ -1,8 +1,12 @@
 import { Controller } from '@hotwired/stimulus';
 
-// src/controllers/direct_upload_controller.ts
+function fillTemplate(template, values) {
+  return template.replace(/\{([a-zA-Z][a-zA-Z0-9]*)\}/g, (match, name) => {
+    const replacement = Object.hasOwn(values, name) ? values[name] : void 0;
+    return replacement === void 0 ? match : String(replacement);
+  });
+}
 
-// src/utils/announce.ts
 function announce(message, options = {}) {
   const text = message.trim();
   if (text.length === 0) return;
@@ -12,43 +16,7 @@ function announce(message, options = {}) {
     })
   );
 }
-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/before_cache_reset.ts
-var BeforeCacheReset = class _BeforeCacheReset {
-  /** Every subscribed instance, iterated by the one shared document listener. */
-  static #subscribers = /* @__PURE__ */ new Set();
-  /** The shared listener; installed while at least one instance is subscribed. */
-  static #onBeforeCache = () => {
-    for (const subscriber of _BeforeCacheReset.#subscribers) subscriber.#rewind();
-  };
-  #rewind;
-  /** @param rewind - the pass that returns this controller's state to its initial form. */
-  constructor(rewind) {
-    this.#rewind = rewind;
-  }
-  /** Subscribes to `turbo:before-cache`; call from `connect()`. Idempotent. */
-  activate() {
-    const first = _BeforeCacheReset.#subscribers.size === 0;
-    _BeforeCacheReset.#subscribers.add(this);
-    if (first) {
-      document.addEventListener("turbo:before-cache", _BeforeCacheReset.#onBeforeCache);
-    }
-  }
-  /** Unsubscribes; call from `disconnect()`. Safe when never subscribed. */
-  deactivate() {
-    _BeforeCacheReset.#subscribers.delete(this);
-    if (_BeforeCacheReset.#subscribers.size > 0) return;
-    document.removeEventListener("turbo:before-cache", _BeforeCacheReset.#onBeforeCache);
-  }
-};
 
-// src/utils/declared_value.ts
 function parseDeclared(raw, parse, fallback) {
   try {
     return parse(raw);
@@ -68,43 +36,24 @@ function validSelector(element, raw, fallback) {
   );
 }
 
-// src/utils/safe_timeout.ts
 var TimerRegistry = class {
-  /** Live timer ids that have not yet been cleared (or, for timeouts, fired). */
   ids = /* @__PURE__ */ new Set();
-  /**
-   * Cancels a single tracked timer.
-   *
-   * No-ops if the id is unknown (already cleared, fired, or never owned by this
-   * registry), so callers can clear defensively without guarding.
-   */
   clear(id) {
     if (this.ids.delete(id)) {
       this.cancel(id);
     }
   }
-  /**
-   * Cancels every tracked timer. Call this from a controller's `disconnect()`
-   * to guarantee no timer outlives the element.
-   */
   clearAll() {
     for (const id of this.ids) {
       this.cancel(id);
     }
     this.ids.clear();
   }
-  /** Number of timers currently tracked (pending). */
   get size() {
     return this.ids.size;
   }
 };
 var SafeTimeout = class extends TimerRegistry {
-  /**
-   * Schedules `callback` after `delay` ms and returns the timer id.
-   *
-   * The id is removed from the registry automatically when the timeout fires,
-   * so {@link TimerRegistry.size | size} reflects only still-pending timers.
-   */
   set(callback, delay) {
     const id = this.schedule(() => {
       this.ids.delete(id);
@@ -121,14 +70,48 @@ var SafeTimeout = class extends TimerRegistry {
   }
 };
 
-// src/utils/template_row.ts
+var KeyedTimers = class {
+  #timers = new SafeTimeout();
+  #pending = /* @__PURE__ */ new Map();
+  set(key, callback, delay) {
+    this.clear(key);
+    const id = this.#timers.set(() => {
+      this.#pending.delete(key);
+      callback();
+    }, delay);
+    this.#pending.set(key, id);
+  }
+  clear(key) {
+    this.#timers.clear(this.#pending.get(key) ?? -1);
+    this.#pending.delete(key);
+  }
+  clearAll() {
+    this.#timers.clearAll();
+    this.#pending.clear();
+  }
+  has(key) {
+    return this.#pending.has(key);
+  }
+};
+
+var ListenerSet = class {
+  #abort = new AbortController();
+  add(target, type, handler, options) {
+    target.addEventListener(type, handler, { ...options, signal: this.#abort.signal });
+  }
+  dispose() {
+    this.#abort.abort();
+    this.#abort = new AbortController();
+  }
+};
+
 function cloneTemplateRoot(template) {
   const root = template.content.firstElementChild;
   return root instanceof HTMLElement ? root.cloneNode(true) : null;
 }
 
-// src/controllers/direct_upload_controller.ts
 var REMOVE_DELAY = 4e3;
+var GENERATED_ATTRIBUTE = "generated";
 var DirectUploadController = class extends Controller {
   static targets = ["list", "row"];
   static values = {
@@ -138,10 +121,9 @@ var DirectUploadController = class extends Controller {
     scope: { type: String, default: "" }
   };
   static events = ["progress", "done", "error", "reconcile"];
-  #timeouts = new SafeTimeout();
+  #removals = new KeyedTimers();
   #rows = /* @__PURE__ */ new Map();
-  #beforeCache = new BeforeCacheReset(() => this.#rewindForCache());
-  /** The validated `scope` selector; a broken declaration falls back to `""`. */
+  #connected = false;
   #scopeSelector = "";
   #onInitialize = (event) => {
     if (!this.#inScope(event)) return;
@@ -164,27 +146,46 @@ var DirectUploadController = class extends Controller {
     const detail = this.#detail(event);
     this.#complete(this.#key(detail.id), this.#name(detail));
   };
+  #listeners = new ListenerSet();
   connect() {
-    document.addEventListener("direct-upload:initialize", this.#onInitialize);
-    document.addEventListener("direct-upload:progress", this.#onProgress);
-    document.addEventListener("direct-upload:error", this.#onError);
-    document.addEventListener("direct-upload:end", this.#onEnd);
-    this.#beforeCache.activate();
-    this.#rescheduleRemovals();
+    this.#connected = true;
+    this.#listeners.add(document, "direct-upload:initialize", this.#onInitialize);
+    this.#listeners.add(document, "direct-upload:progress", this.#onProgress);
+    this.#listeners.add(document, "direct-upload:error", this.#onError);
+    this.#listeners.add(document, "direct-upload:end", this.#onEnd);
+    this.#discardInherited();
+    this.#syncRemovals();
   }
   disconnect() {
-    document.removeEventListener("direct-upload:initialize", this.#onInitialize);
-    document.removeEventListener("direct-upload:progress", this.#onProgress);
-    document.removeEventListener("direct-upload:error", this.#onError);
-    document.removeEventListener("direct-upload:end", this.#onEnd);
-    this.#beforeCache.deactivate();
-    this.#timeouts.clearAll();
-  }
-  /** Validates `scope` once so the per-event path never parses or throws. */
+    this.#connected = false;
+    this.#listeners.dispose();
+    this.#removals.clearAll();
+  }
+  get #generatedAttribute() {
+    return `data-${this.identifier}-${GENERATED_ATTRIBUTE}`;
+  }
+  #discardInherited() {
+    if (this.#rows.size > 0 || !this.hasListTarget) return;
+    const ids = [];
+    for (const row of Array.from(this.listTarget.children)) {
+      const id = row.getAttribute(this.#generatedAttribute);
+      if (id === null) continue;
+      row.remove();
+      ids.push(id);
+    }
+    if (ids.length === 0) return;
+    this.#syncAggregate();
+    this.dispatch("reconcile", { detail: { ids } });
+  }
   scopeValueChanged() {
     this.#scopeSelector = validSelector(this.element, this.scopeValue, "");
   }
-  /** Updates a row's progress and the aggregate, emitting `progress`. */
+  removeOnDoneValueChanged() {
+    if (this.#connected) this.#syncRemovals();
+  }
+  listTargetDisconnected() {
+    if (this.#connected) this.#syncAggregate();
+  }
   #updateProgress(id, percent, name) {
     const row = this.#rowFor(id, name);
     if (row === null || this.#isSettled(row)) return;
@@ -192,12 +193,6 @@ var DirectUploadController = class extends Controller {
     this.#syncAggregate();
     this.dispatch("progress", { detail: { id, percent: clamped } });
   }
-  /**
-   * Marks a not-yet-settled row done at 100%, announces it, and emits `done`.
-   *
-   * @stimeoRuntimeOnly `announceDoneText` words the one announcement of this completion and
-   *   `removeOnDone` decides whether it arms the row's removal.
-   */
   #complete(id, name) {
     const row = this.#rowFor(id, name);
     if (row === null || this.#isSettled(row)) return;
@@ -206,18 +201,8 @@ var DirectUploadController = class extends Controller {
     this.#syncAggregate();
     this.#announce(this.announceDoneTextValue, name, row);
     this.dispatch("done", { detail: { id } });
-    if (this.removeOnDoneValue) {
-      this.#timeouts.set(() => this.#removeRow(id), REMOVE_DELAY);
-    }
+    if (this.removeOnDoneValue) this.#scheduleRemoval(id, row);
   }
-  /**
-   * Marks a not-yet-settled row failed, announces it, and emits `error`.
-   * Returns whether the failure is rendered by this widget (used to decide the
-   * `direct-upload:error` default), which also holds when the row already
-   * displays an earlier failure.
-   *
-   * @stimeoRuntimeOnly `announceErrorText` words the one announcement of this failure.
-   */
   #fail(id, error, name) {
     const row = this.#rowFor(id, name);
     if (row === null) return false;
@@ -227,27 +212,25 @@ var DirectUploadController = class extends Controller {
     this.dispatch("error", { detail: { id, error } });
     return true;
   }
-  /** Whether the row reached a terminal state; settled rows are never rewritten. */
   #isSettled(row) {
     const state = row.getAttribute("data-upload-state");
     return state === "done" || state === "error";
   }
-  /**
-   * Re-arms `removeOnDone` for completed rows after a reconnect.
-   *
-   * @stimeoRuntimeOnly `removeOnDone` decides whether reconnecting arms the removal of finished
-   *   rows again.
-   */
-  #rescheduleRemovals() {
-    if (!this.removeOnDoneValue) return;
+  #syncRemovals() {
+    if (!this.removeOnDoneValue) {
+      this.#removals.clearAll();
+      return;
+    }
     this.#prune();
     for (const [id, row] of this.#rows) {
-      if (row.getAttribute("data-upload-state") === "done") {
-        this.#timeouts.set(() => this.#removeRow(id), REMOVE_DELAY);
+      if (row.getAttribute("data-upload-state") === "done" && !this.#removals.has(id)) {
+        this.#scheduleRemoval(id, row);
       }
     }
   }
-  /** Returns the live row for `id`, creating (and labeling) one on first sight. */
+  #scheduleRemoval(id, row) {
+    this.#removals.set(id, () => this.#removeRow(row), REMOVE_DELAY);
+  }
   #rowFor(id, name) {
     const key = this.#key(id);
     const existing = this.#rows.get(key);
@@ -256,13 +239,13 @@ var DirectUploadController = class extends Controller {
         this.#applyName(existing, name);
         return existing;
       }
-      existing.remove();
-      this.#rows.delete(key);
+      this.#retire(key, existing);
     }
     if (!this.hasRowTarget || !this.hasListTarget) return null;
     const clone = cloneTemplateRoot(this.rowTarget);
     if (!clone) return null;
     this.#applyName(clone, name);
+    clone.setAttribute(this.#generatedAttribute, key);
     clone.setAttribute("data-upload-state", "uploading");
     this.#applyProgress(clone, 0);
     this.listTarget.appendChild(clone);
@@ -270,20 +253,12 @@ var DirectUploadController = class extends Controller {
     this.#syncAggregate();
     return clone;
   }
-  /**
-   * Writes the event's file name into `[data-field="name"]` and, unless the row
-   * already carries a non-blank `aria-label` — authored on the template or
-   * applied by an earlier event — makes it the accessible name too. The visible
-   * name never depends on the label: an authored label keeps its wording while
-   * the field still shows which file this row tracks.
-   */
   #applyName(row, name) {
     if (name.length === 0) return;
     this.#setField(row, "name", name);
     if ((row.getAttribute("aria-label") ?? "").trim().length > 0) return;
     row.setAttribute("aria-label", name);
   }
-  /** Writes one progress value to every per-row hook; returns the clamped percent. */
   #applyProgress(row, percent) {
     const clamped = Math.max(0, Math.min(100, Math.round(percent)));
     row.setAttribute("aria-valuenow", String(clamped));
@@ -292,17 +267,10 @@ var DirectUploadController = class extends Controller {
     this.#setField(row, "percent", `${clamped}%`);
     return clamped;
   }
-  #removeRow(id) {
-    const row = this.#rows.get(id);
-    if (row === void 0) return;
+  #removeRow(row) {
     row.remove();
-    this.#rows.delete(id);
     this.#syncAggregate();
   }
-  /**
-   * Reflects the average progress across live rows on the controller element,
-   * withdrawing both hooks once no rows remain.
-   */
   #syncAggregate() {
     this.#prune();
     if (this.#rows.size === 0) {
@@ -318,50 +286,21 @@ var DirectUploadController = class extends Controller {
     this.element.setAttribute("data-upload-progress", String(overall));
     this.element.style.setProperty("--stimeo--upload-progress", `${overall}%`);
   }
-  /**
-   * Whether a bookkept row is still this widget's live UI: connected, and — when
-   * a `list` target is present — inside the *current* one, so re-pointing the
-   * target attribute at a new element retires rows kept alive in the old list.
-   */
   #tracksRow(row) {
     if (!row.isConnected) return false;
     return !this.hasListTarget || this.listTarget.contains(row);
   }
-  /**
-   * Retires rows that left the live UI (list swap, external removal). A retired
-   * clone is removed outright — generated rows only ever live under the current
-   * `list`, so the before-cache rewind never has an untracked leftover to miss.
-   */
   #prune() {
     for (const [id, row] of this.#rows) {
       if (this.#tracksRow(row)) continue;
-      row.remove();
-      this.#rows.delete(id);
+      this.#retire(id, row);
     }
   }
-  /**
-   * Rewinds for the snapshot and reports what that discarded. An upload in flight
-   * cannot survive the navigation, so a consumer mirroring the rows would keep a
-   * progress bar that never resolves.
-   */
-  #rewindForCache() {
-    const ids = [...this.#rows.keys()];
-    this.#reset();
-    if (ids.length > 0) this.dispatch("reconcile", { detail: { ids } });
-  }
-  #reset() {
-    for (const row of this.#rows.values()) row.remove();
-    this.#rows.clear();
-    this.#timeouts.clearAll();
-    this.#syncAggregate();
+  #retire(id, row) {
+    row.remove();
+    this.#rows.delete(id);
+    this.#removals.clear(id);
   }
-  /**
-   * Sends one consumer-worded message to the page's shared announcer. `{name}`
-   * resolves to the row's displayed name first — the event that settles an
-   * upload may omit the file although an earlier event already named the row —
-   * then the event's own name, then the accessible name (which an authored
-   * label owns, so it is the last resort, not the primary source).
-   */
   #announce(template, name, row) {
     const stored = this.#field(row, "name")?.textContent ?? "";
     const label = stored.length > 0 ? stored : name.length > 0 ? name : row.getAttribute("aria-label") ?? "";
@@ -377,17 +316,9 @@ var DirectUploadController = class extends Controller {
   #detail(event) {
     return event.detail ?? {};
   }
-  /** The event's file name, or `""` when it carries none. */
   #name(detail) {
     return detail.file?.name ?? "";
   }
-  /**
-   * Whether an event belongs to this controller. With `scope` set, only events
-   * whose target (the file input) sits inside an element matching `scope` are
-   * handled, so several upload widgets on one page do not cross-populate.
-   * Resolved with `closest()` from the target itself, so the chatty `progress`
-   * stream never pays a document-wide query. Empty `scope` handles all.
-   */
   #inScope(event) {
     if (this.#scopeSelector.length === 0) return true;
     const target = event.target;
@@ -399,5 +330,4 @@ var DirectUploadController = class extends Controller {
 };
 
 export { DirectUploadController };
-//# sourceMappingURL=direct_upload_controller.js.map
 //# sourceMappingURL=direct_upload_controller.js.map