stimeo-ui 0.7.0 → 0.8.0

data/dist/controllers/file_dropzone_controller.js

@@ -1,36 +1,179 @@
 import { Controller } from '@hotwired/stimulus';
 
 // src/controllers/file_dropzone_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/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/detach_gate.ts
+var DetachGate = class _DetachGate {
+  /** Set while a probe is queued, waiting for a reconnect to cancel it. */
+  #pending = false;
+  /**
+   * True while a probe is queued — the last disconnect was ambiguous and no
+   * reconnect has cancelled it yet. Read it from `connect()` to tell the
+   * reconnect half of an in-page move from a first connect: a controller whose
+   * initialisation restarts a measurement (a min-duration floor, an elapsed
+   * counter) must skip it for the move, where nothing actually restarted.
+   */
+  get pending() {
+    return this.#pending;
+  }
+  /**
+   * True when the disconnect is definitely a real detach — the element left
+   * the document, or `data-controller` no longer lists the identifier. False
+   * means ambiguous (in-page move or observed-root exit), NOT "alive".
+   */
+  static isDetached(host) {
+    if (!host.element.isConnected) return true;
+    const tokens = (host.element.getAttribute("data-controller") ?? "").split(/\s+/);
+    return !tokens.includes(host.identifier);
+  }
+  /**
+   * Call from `disconnect()`: runs `teardown` synchronously on a definite
+   * detach (fast path), otherwise defers it one microtask — a reconnect
+   * ({@link cancel} from `connect()`) keeps the state, no reconnect runs it.
+   * One microtask is the whole probe window: Stimulus reconnects a moved
+   * element within the same mutation batch, before the checkpoint drains.
+   */
+  disconnected(host, teardown) {
+    if (_DetachGate.isDetached(host)) {
+      this.#pending = false;
+      teardown();
+      return;
+    }
+    this.#pending = true;
+    queueMicrotask(() => {
+      if (!this.#pending) return;
+      this.#pending = false;
+      teardown();
+    });
+  }
+  /**
+   * Disarms a pending probe. Call from `connect()` (the reconnect that proves
+   * an in-page move) and from the head of any teardown path not routed through
+   * {@link disconnected} (disabled-toggle, Escape), so an orphaned probe can
+   * never run the teardown a second time.
+   */
+  cancel() {
+    this.#pending = false;
+  }
+};
+
+// src/utils/focus_candidate.ts
+function inheritsFieldsetDisabled(control) {
+  let fieldset = control.closest("fieldset[disabled]");
+  while (fieldset) {
+    const legend = Array.from(fieldset.children).find((child) => child.tagName === "LEGEND");
+    if (!legend?.contains(control)) return true;
+    fieldset = fieldset.parentElement?.closest("fieldset[disabled]") ?? null;
+  }
+  return false;
+}
+
+// src/controllers/file_dropzone_controller.ts
+var DRAGOVER_ATTRIBUTE = "data-dragover";
+var INVALID_ATTRIBUTE = "data-stimeo--file-dropzone-invalid";
 var FileDropzoneController = class extends Controller {
-  static targets = ["zone", "trigger", "input", "list", "item", "itemTemplate", "status"];
+  static targets = [
+    "zone",
+    "trigger",
+    "input",
+    "list",
+    "item",
+    "itemTemplate",
+    "name",
+    "thumb",
+    "remove"
+  ];
   static values = {
     maxSize: { type: Number, default: 0 },
     maxFiles: { type: Number, default: 0 },
-    dragLabel: { type: String, default: "Drop files to add them" }
+    allowDuplicates: { type: Boolean, default: false },
+    announceDragText: { type: String, default: "" },
+    announceAddedText: { type: String, default: "" },
+    announceRemovedText: { type: String, default: "" },
+    announceRejectedTypeText: { type: String, default: "" },
+    announceRejectedSizeText: { type: String, default: "" },
+    announceRejectedDuplicateText: { type: String, default: "" },
+    announceRejectedCountText: { type: String, default: "" }
   };
   static actions = ["onChange", "onDragLeave", "onDragOver", "onDrop", "openDialog"];
-  static events = ["change", "reject"];
+  static events = ["change", "reject", "reconcile"];
   /** Selected files paired with their rendered item and any preview objectURL. */
   #entries = [];
-  /** Prevents initial and teardown target callbacks from binding outside controller lifetime. */
-  #connected = false;
-  /** Wires file removal as a delegated listener on the list container. */
+  /** Whether a drag is currently over the zone; the source for `data-dragover`. */
+  #dragging = false;
+  /** Whether this connection already reported its unusable item template. */
+  #warnedTemplate = false;
+  #gate = new DetachGate();
+  #beforeCache = new BeforeCacheReset(() => this.#rewindForCache());
+  /** Subscribes to the Turbo cache rewind and re-arms the template diagnostic. */
   connect() {
-    this.#connected = true;
-    if (this.hasListTarget) this.#bindList(this.listTarget);
+    this.#gate.cancel();
+    this.#warnedTemplate = false;
+    this.#beforeCache.activate();
   }
-  /** Revokes any outstanding preview URLs so none leaks across navigations. */
+  /**
+   * Releases the delegated listeners. The selection itself survives an in-page
+   * move and is released only once the gate proves a real detach — revoking a
+   * preview URL on a move would leave a live item pointing at a dead `blob:`.
+   */
   disconnect() {
-    this.#connected = false;
     for (const list of this.listTargets) list.removeEventListener("click", this.#onItemClick);
-    for (const entry of this.#entries) {
-      if (entry.url) URL.revokeObjectURL(entry.url);
-    }
-    this.#entries.length = 0;
+    this.#beforeCache.deactivate();
+    this.#gate.disconnected(this, () => this.#teardown());
   }
-  /** Rebinds removal and restores client-only previews when Turbo replaces the list target. */
+  /**
+   * Binds removal and restores client-only previews for every list this controller
+   * renders into — the one present at connect and any Turbo puts in its place.
+   * This is the only place the listener is attached, so the pair with
+   * {@link listTargetDisconnected} keeps it from outliving the element it is on.
+   */
   listTargetConnected(list) {
-    if (!this.#connected) return;
     this.#bindList(list);
   }
   /** Releases only the list target that actually disconnected. */
@@ -46,82 +189,147 @@ var FileDropzoneController = class extends Controller {
   }
   /** Opens the native file dialog. Bound via `data-action` (trigger click). */
   openDialog() {
+    if (this.#isDisabled) return;
     this.inputTarget.click();
   }
-  /** Adds the files chosen through the native dialog. */
+  /**
+   * Adds the files chosen through the native dialog. The input holds only what
+   * the dialog just returned, so the accepted set is written back over it once
+   * the batch is validated.
+   */
   onChange() {
-    if (this.inputTarget.files) this.#addFiles(this.inputTarget.files);
-    this.inputTarget.value = "";
+    const files = this.inputTarget.files;
+    if (files) this.#addFiles(files);
+    else this.#syncInput();
   }
-  /** Marks the zone as a drop target and announces the affordance in words. */
+  /**
+   * Marks the zone as a drop target and announces the affordance once per drag.
+   * Bound via `data-action` (dragover). Leaving the default alone is what refuses
+   * the drop, so a disabled field and a drag an inner dropzone already claimed
+   * both fall through untouched.
+   */
   onDragOver(event) {
+    if (event.defaultPrevented || this.#isDisabled) return;
     event.preventDefault();
-    if (this.hasZoneTarget) this.zoneTarget.setAttribute("data-dragover", "");
-    this.#setStatus(this.dragLabelValue);
+    if (this.#dragging) return;
+    this.#dragging = true;
+    if (this.hasZoneTarget) this.zoneTarget.setAttribute(DRAGOVER_ATTRIBUTE, "");
+    announce(fillTemplate(this.announceDragTextValue, { total: this.#entries.length }));
   }
-  /** Clears the drag-over flag when the pointer leaves the zone. */
-  onDragLeave() {
-    if (this.hasZoneTarget) this.zoneTarget.removeAttribute("data-dragover");
+  /**
+   * Clears the drag-over flag when the pointer leaves the zone. Bound via
+   * `data-action` (dragleave). `dragleave` bubbles from every descendant the
+   * pointer crosses, so the flag only drops when the element being entered is
+   * outside the zone (or there is none, the pointer having left the window).
+   */
+  onDragLeave(event) {
+    const next = event.relatedTarget;
+    if (this.hasZoneTarget && next instanceof Node && this.zoneTarget.contains(next)) return;
+    this.#endDrag();
   }
-  /** Accepts dropped files, clearing the drag-over state. */
+  /** Accepts dropped files, clearing the drag-over state. Bound via `data-action` (drop). */
   onDrop(event) {
+    if (event.defaultPrevented) return;
+    this.#endDrag();
+    if (this.#isDisabled) return;
     event.preventDefault();
-    if (this.hasZoneTarget) this.zoneTarget.removeAttribute("data-dragover");
     if (event.dataTransfer?.files) this.#addFiles(event.dataTransfer.files);
   }
   /**
    * Removes the file whose remove button was clicked. Delegated on the list
    * container rather than bound per item via `data-action`, so it works the instant
    * an item is appended without waiting on Stimulus to wire a freshly created element.
+   * Only the item's declared `remove` target counts, so an authored second control
+   * inside an item does what it says instead of silently discarding the file. The
+   * button has to belong to a tracked item, which is what makes a list this
+   * controller no longer renders into inert — its items moved out with it.
    */
   #onItemClick = (event) => {
-    const list = event.currentTarget;
-    const button = event.target.closest("button");
-    if (!this.#connected || !list || !button || !this.hasListTarget || list !== this.listTarget || !list.contains(button)) {
-      return;
-    }
+    const button = event.target.closest(
+      'button[data-stimeo--file-dropzone-target~="remove"]'
+    );
     const index = this.#entries.findIndex((entry) => entry.item.contains(button));
     if (index !== -1) this.#removeAt(index);
   };
-  /** Validates each incoming file and renders the accepted ones. */
+  /** Validates each incoming file, renders the accepted ones, and reports the batch. */
   #addFiles(files) {
-    let changed = false;
-    if (this.hasZoneTarget) this.zoneTarget.removeAttribute("data-stimeo--file-dropzone-invalid");
+    this.#rehome();
+    if (this.hasZoneTarget) this.zoneTarget.removeAttribute(INVALID_ATTRIBUTE);
+    const rejected = /* @__PURE__ */ new Map();
+    const turnedAway = [];
+    let addedName = "";
+    let added = 0;
     for (const file of Array.from(files)) {
       const reason = this.#validate(file);
-      if (reason) {
-        if (this.hasZoneTarget) {
-          this.zoneTarget.setAttribute("data-stimeo--file-dropzone-invalid", "");
-        }
-        this.#setStatus(file.name);
-        this.dispatch("reject", { detail: { file, reason } });
+      if (reason !== null) {
+        if (this.hasZoneTarget) this.zoneTarget.setAttribute(INVALID_ATTRIBUTE, "");
+        const batch = rejected.get(reason);
+        if (batch) batch.count += 1;
+        else rejected.set(reason, { name: file.name, count: 1 });
+        turnedAway.push({ file, reason });
         continue;
       }
-      this.#appendFile(file);
-      this.#setStatus(file.name);
-      changed = true;
+      if (!this.#appendFile(file)) continue;
+      if (added === 0) addedName = file.name;
+      added += 1;
+    }
+    this.#syncInput();
+    if (added > 0) {
+      this.#announce(this.announceAddedTextValue, addedName, added);
+      this.dispatch("change", { detail: { files: this.#files } });
+    }
+    for (const { file, reason } of turnedAway) {
+      this.dispatch("reject", { detail: { file, reason } });
+    }
+    for (const [reason, batch] of rejected) {
+      this.#announce(this.#rejectText(reason), batch.name, batch.count);
     }
-    if (changed) this.dispatch("change", { detail: { files: this.#files } });
   }
-  /** Returns the rejection reason for `file`, or `null` when it is acceptable. */
+  /**
+   * Returns the rejection reason for `file`, or `null` when it is acceptable.
+   * The file's own defects are decided first, so a full list still tells the user
+   * which files it would never have taken.
+   */
   #validate(file) {
-    const limit = this.#effectiveMaxFiles;
-    if (limit > 0 && this.#entries.length >= limit) return "count";
     if (!this.#matchesAccept(file)) return "type";
     if (this.maxSizeValue > 0 && file.size > this.maxSizeValue) return "size";
+    if (!this.allowDuplicatesValue && this.#entries.some((entry) => this.#isSame(entry.file, file))) {
+      return "duplicate";
+    }
+    const limit = this.#effectiveMaxFiles;
+    if (limit > 0 && this.#entries.length >= limit) return "count";
     return null;
   }
-  /** Builds one preview item (name, optional thumbnail, remove button). */
+  /**
+   * Whether two files are the same selection. `File` objects from separate picks
+   * are never the same reference, so identity is the triple the platform exposes.
+   */
+  #isSame(a, b) {
+    return a.name === b.name && a.size === b.size && a.lastModified === b.lastModified;
+  }
+  /**
+   * Builds one preview item (name, optional thumbnail, remove button) and reports
+   * whether it was rendered.
+   */
   #appendFile(file) {
-    if (!this.hasItemTemplateTarget || !this.hasListTarget) return;
+    if (!this.hasListTarget) return this.#warnTemplate('a "list" target to render into');
+    if (!this.hasItemTemplateTarget) return this.#warnTemplate('an "itemTemplate" target');
     const fragment = this.itemTemplateTarget.content.cloneNode(true);
-    const item = fragment.querySelector('[data-stimeo--file-dropzone-target="item"]');
-    const name = fragment.querySelector('[data-file-dropzone-slot="name"]');
-    const thumb = fragment.querySelector('[data-file-dropzone-slot="thumb"]');
-    const button = fragment.querySelector("button");
-    if (!item) return;
-    if (name) name.textContent = file.name;
-    if (button) button.setAttribute("aria-label", `Remove ${file.name}`);
+    const item = this.#slot(fragment, "item");
+    const name = this.#slot(fragment, "name");
+    const thumb = this.#slot(fragment, "thumb");
+    const button = fragment.querySelector(
+      'button[data-stimeo--file-dropzone-target~="remove"]'
+    );
+    const removeName = button?.getAttribute("aria-label")?.trim() ?? "";
+    if (!item) return this.#warnTemplate('an "item" root');
+    if (!name) return this.#warnTemplate('a "name" element');
+    if (!button) return this.#warnTemplate('a "remove" target <button>');
+    if (removeName === "") {
+      return this.#warnTemplate('a non-empty aria-label on its "remove" target');
+    }
+    name.textContent = file.name;
+    button.setAttribute("aria-label", fillTemplate(removeName, { name: file.name }));
     let url;
     if (thumb && file.type.startsWith("image/")) {
       url = URL.createObjectURL(file);
@@ -133,6 +341,29 @@ var FileDropzoneController = class extends Controller {
     }
     this.listTarget.appendChild(fragment);
     this.#entries.push({ file, item, url });
+    return true;
+  }
+  /** Resolves one declared part inside a cloned item template. */
+  #slot(fragment, name) {
+    return fragment.querySelector(`[data-stimeo--file-dropzone-target~="${name}"]`);
+  }
+  /**
+   * Reports an unusable item template to the author, once per connection.
+   *
+   * The addition itself stays a no-op — nothing about the selection, the native
+   * input, the announcements, or the events changes. Without this line the only
+   * symptom is a picker that accepts no file at all, and the causes the Inspector
+   * cannot see statically (a server-rendered template, a name that renders empty
+   * from a missing translation) would have no diagnostic anywhere.
+   */
+  #warnTemplate(missing) {
+    if (!this.#warnedTemplate) {
+      this.#warnedTemplate = true;
+      console.warn(
+        `Stimeo UI: "${this.identifier}" added no file because its item template lacks ${missing}.`
+      );
+    }
+    return false;
   }
   /** Removes entry `index`, revokes its preview, and re-homes focus. */
   #removeAt(index) {
@@ -141,7 +372,8 @@ var FileDropzoneController = class extends Controller {
     if (entry.url) URL.revokeObjectURL(entry.url);
     entry.item.remove();
     this.#entries.splice(index, 1);
-    this.#setStatus(entry.file.name);
+    this.#syncInput();
+    this.#announce(this.announceRemovedTextValue, entry.file.name, 1);
     this.dispatch("change", { detail: { files: this.#files } });
     const buttons = this.#removeButtons;
     if (buttons.length === 0) {
@@ -164,18 +396,109 @@ var FileDropzoneController = class extends Controller {
       return type === token;
     });
   }
-  /** Updates the live region so assistive tech announces the change. */
-  #setStatus(text) {
-    if (this.hasStatusTarget) this.statusTarget.textContent = text;
+  /**
+   * Sends one consumer-worded message to the page's shared announcer. `{name}` is
+   * the file the message is about, `{count}` how many files it covers, and
+   * `{total}` how many are selected once the batch has settled.
+   */
+  #announce(template, name, count) {
+    announce(fillTemplate(template, { name, count, total: this.#entries.length }));
+  }
+  /** The consumer's wording for one rejection reason. */
+  #rejectText(reason) {
+    switch (reason) {
+      case "type":
+        return this.announceRejectedTypeTextValue;
+      case "size":
+        return this.announceRejectedSizeTextValue;
+      case "duplicate":
+        return this.announceRejectedDuplicateTextValue;
+      case "count":
+        return this.announceRejectedCountTextValue;
+    }
+  }
+  /**
+   * Mirrors the accepted set onto the native input, so a plain form submit carries
+   * the dropped files. Skipped where `DataTransfer` cannot be constructed: the
+   * widget keeps working and the consumer still receives every `File` on `change`.
+   */
+  #syncInput() {
+    if (!this.hasInputTarget) return;
+    const transfer = this.#newTransfer();
+    if (!transfer) return;
+    for (const entry of this.#entries) transfer.items.add(entry.file);
+    this.inputTarget.files = transfer.files;
+  }
+  /** A usable empty `DataTransfer`, or `null` where the platform has none. */
+  #newTransfer() {
+    try {
+      return new DataTransfer();
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Moves surviving preview items back under the current list. A morph that
+   * empties the list in place leaves the selection with no rendering, and the
+   * files it holds cannot be rebuilt from the DOM, so the items are re-homed
+   * rather than forgotten.
+   */
+  #rehome() {
+    if (!this.hasListTarget) return;
+    for (const entry of this.#entries) {
+      if (!this.listTarget.contains(entry.item)) this.listTarget.appendChild(entry.item);
+    }
+  }
+  /** Drops the drag-over state, whether the drag ended in a drop or left the zone. */
+  #endDrag() {
+    this.#dragging = false;
+    if (this.hasZoneTarget) this.zoneTarget.removeAttribute(DRAGOVER_ATTRIBUTE);
+  }
+  /**
+   * Discards the selection and every state attribute this controller wrote, so
+   * neither a cached snapshot nor a stranded subtree keeps items whose files are
+   * gone. Silent: `change` means a selection the user changed, and the cache
+   * rewind reports itself as `reconcile` instead.
+   */
+  #rewindForCache() {
+    const had = this.#entries.length > 0;
+    this.#reset();
+    if (had) this.dispatch("reconcile", { detail: { files: this.#files } });
+  }
+  #reset() {
+    for (const entry of this.#entries) {
+      if (entry.url) URL.revokeObjectURL(entry.url);
+      entry.item.remove();
+    }
+    this.#entries.length = 0;
+    this.#syncInput();
+    this.#endDrag();
+    if (this.hasZoneTarget) this.zoneTarget.removeAttribute(INVALID_ATTRIBUTE);
+  }
+  /** Releases the selection once the disconnect is known to be a real detach. */
+  #teardown() {
+    this.#gate.cancel();
+    this.#reset();
+  }
+  /** Whether the field refuses input, natively or through an ancestor `fieldset`. */
+  get #isDisabled() {
+    return this.inputTarget.disabled || inheritsFieldsetDisabled(this.inputTarget);
   }
   /** Effective file cap: `maxFiles`, or 1 when the input is single-select. */
   get #effectiveMaxFiles() {
     if (this.maxFilesValue > 0) return this.maxFilesValue;
     return this.inputTarget.multiple ? 0 : 1;
   }
-  /** The remove buttons currently in the list, in order. */
+  /** The declared remove button of each rendered item, in selection order. */
   get #removeButtons() {
-    return Array.from(this.listTarget.querySelectorAll("button"));
+    const buttons = [];
+    for (const entry of this.#entries) {
+      const button = entry.item.querySelector(
+        'button[data-stimeo--file-dropzone-target~="remove"]'
+      );
+      if (button) buttons.push(button);
+    }
+    return buttons;
   }
   /** The accepted files in selection order. */
   get #files() {

data/dist/controllers/flash_controller.js

@@ -129,7 +129,7 @@ var FlashController = class extends Controller {
     max: { type: Number, default: 0 }
   };
   static actions = ["dismiss"];
-  static events = ["show", "dismiss"];
+  static events = ["show", "dismiss", "reconcile"];
   #timers = new SafeTimeout();
   #observer = null;
   /** Whether the controller is between `connect()` and `disconnect()`. */
@@ -175,12 +175,14 @@ var FlashController = class extends Controller {
    * only: `dismiss` reports a dismissal, and freezing the page is not one.
    */
   #rewindForCache() {
+    const removed = this.#order.length;
     for (const message of [...this.#order]) {
       message.remove();
       this.#forget(message);
     }
     for (const message of this.#leaving) message.remove();
     this.#leaving.clear();
+    if (removed > 0) this.dispatch("reconcile", { detail: { removed } });
   }
   /** Follows a `region` element swapped in — or arriving — at runtime (Turbo Stream). */
   regionTargetConnected() {

data/dist/controllers/frame_loading_controller.js

@@ -213,7 +213,7 @@ var FrameLoadingController = class extends Controller {
     minDuration: { type: Number, default: 0 },
     restoreFocus: { type: Boolean, default: true }
   };
-  static events = ["start", "end"];
+  static events = ["start", "end", "reconcile"];
   #timeouts = new SafeTimeout();
   #floor = new MinDurationFloor(this.#timeouts);
   #gate = new DetachGate();
@@ -289,6 +289,7 @@ var FrameLoadingController = class extends Controller {
     this.#loading = false;
     this.#floor.cancel();
     this.#rewindHooks();
+    this.dispatch("reconcile", { detail: {} });
   }
   /**
    * Clears every hook the loading state writes. Shared by the three ways a load can