stimeo-ui 0.14.0 → 0.16.0

data/dist/controllers/file_dropzone_controller.js

@@ -103,6 +103,25 @@ var DetachGate = class _DetachGate {
   }
 };
 
+// src/utils/element_part.ts
+function matchingPart(root, selector) {
+  return root.matches(selector) ? root : root.querySelector(selector);
+}
+function writeLabel(slot, text) {
+  if (slot.childElementCount === 0) {
+    slot.textContent = text;
+    return;
+  }
+  let first = null;
+  for (const node of Array.from(slot.childNodes)) {
+    if (node.nodeType !== Node.TEXT_NODE) continue;
+    if (first) node.remove();
+    else first = node;
+  }
+  if (first) first.nodeValue = text;
+  else slot.prepend(text);
+}
+
 // src/utils/focus_candidate.ts
 function inheritsFieldsetDisabled(control) {
   let fieldset = control.closest("fieldset[disabled]");
@@ -114,10 +133,93 @@ function inheritsFieldsetDisabled(control) {
   return false;
 }
 
+// src/utils/target_selector.ts
+function targetSelector(identifier, name) {
+  return `[data-${identifier}-target~="${name}"]`;
+}
+
+// src/utils/template_row.ts
+function cloneTemplateRoot(template) {
+  const root = template.content.firstElementChild;
+  return root instanceof HTMLElement ? root.cloneNode(true) : null;
+}
+var TemplateRow = class {
+  #options;
+  #warned = false;
+  constructor(options) {
+    this.#options = options;
+  }
+  /** The attribute selector for one declared part, in this controller's namespace. */
+  selector(name) {
+    return targetSelector(this.#options.identifier, name);
+  }
+  /** Re-arms the once-per-connection diagnostic. */
+  connect() {
+    this.#warned = false;
+  }
+  /**
+   * Names one missing part on the console, at most once per connection, and
+   * returns `null` so a caller can hand it straight back.
+   */
+  report(missing) {
+    return this.#say(`lacks ${missing}`);
+  }
+  /** Writes one diagnostic per connection, saying what the template got wrong. */
+  #say(problem) {
+    if (this.#warned) return null;
+    this.#warned = true;
+    const { identifier, outcome, noun } = this.#options;
+    console.warn(`Stimeo UI: "${identifier}" ${outcome} because its ${noun} ${problem}.`);
+    return null;
+  }
+  /**
+   * Clones the row and resolves its parts, or names what the template got wrong
+   * and returns `null`. `values` fills the button's authored `aria-label`.
+   */
+  instantiate(template, values) {
+    const { root: rootName, required, optional, button: buttonName } = this.#options;
+    const root = cloneTemplateRoot(template);
+    if (!root?.matches(this.selector(rootName))) {
+      return this.report(`${this.#article(rootName)} "${rootName}" root`);
+    }
+    const count = template.content.children.length;
+    if (count !== 1) {
+      return this.#say(`holds ${count} elements, and the row has to be its only one`);
+    }
+    const slots = {};
+    for (const name2 of required) {
+      const part = this.#resolve(root, name2);
+      if (!part) return this.report(`${this.#article(name2)} "${name2}" target`);
+      slots[name2] = part;
+    }
+    for (const name2 of optional ?? []) slots[name2] = this.#resolve(root, name2);
+    const named = this.#resolve(root, buttonName);
+    if (!(named instanceof HTMLButtonElement)) {
+      return this.report(`${this.#article(buttonName)} "${buttonName}" target <button>`);
+    }
+    const button = named;
+    const name = button.getAttribute("aria-label")?.trim() ?? "";
+    if (name === "") return this.report(`a non-empty aria-label on its "${buttonName}" target`);
+    button.setAttribute("aria-label", fillTemplate(name, values));
+    return { root, slots, button };
+  }
+  /** The row may be its own part; otherwise the first descendant carrying the target. */
+  #resolve(root, name) {
+    return matchingPart(root, this.selector(name));
+  }
+  #article(name) {
+    return /^[aeiou]/i.test(name) ? "an" : "a";
+  }
+};
+
 // src/controllers/file_dropzone_controller.ts
 var DRAGOVER_ATTRIBUTE = "data-dragover";
-var INVALID_ATTRIBUTE = "data-stimeo--file-dropzone-invalid";
+var INVALID_ATTRIBUTE = "invalid";
 var FileDropzoneController = class extends Controller {
+  /** The hook above, in the namespace this controller is registered under. */
+  get #invalidAttribute() {
+    return `data-${this.identifier}-${INVALID_ATTRIBUTE}`;
+  }
   static targets = [
     "zone",
     "trigger",
@@ -147,14 +249,22 @@ var FileDropzoneController = class extends Controller {
   #entries = [];
   /** 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;
+  /** Builds one preview item from the authored template and owns its diagnostic. */
+  #rows = new TemplateRow({
+    identifier: this.identifier,
+    root: "item",
+    required: ["name"],
+    optional: ["thumb"],
+    button: "remove",
+    outcome: "added no file",
+    noun: "item template"
+  });
   #gate = new DetachGate();
   #beforeCache = new BeforeCacheReset(() => this.#rewindForCache());
   /** Subscribes to the Turbo cache rewind and re-arms the template diagnostic. */
   connect() {
     this.#gate.cancel();
-    this.#warnedTemplate = false;
+    this.#rows.connect();
     this.#beforeCache.activate();
   }
   /**
@@ -246,15 +356,20 @@ var FileDropzoneController = class extends Controller {
    */
   #onItemClick = (event) => {
     const button = event.target.closest(
-      'button[data-stimeo--file-dropzone-target~="remove"]'
+      `button${this.#rows.selector("remove")}`
     );
     const index = this.#entries.findIndex((entry) => entry.item.contains(button));
     if (index !== -1) this.#removeAt(index);
   };
-  /** Validates each incoming file, renders the accepted ones, and reports the batch. */
+  /**
+   * Validates each incoming file, renders the accepted ones, and reports the batch.
+   *
+   * @stimeoRuntimeOnly The limits decide which files of this one drop are taken, and the texts word
+   *   the announcements it makes.
+   */
   #addFiles(files) {
     this.#rehome();
-    if (this.hasZoneTarget) this.zoneTarget.removeAttribute(INVALID_ATTRIBUTE);
+    if (this.hasZoneTarget) this.zoneTarget.removeAttribute(this.#invalidAttribute);
     const rejected = /* @__PURE__ */ new Map();
     const turnedAway = [];
     let addedName = "";
@@ -262,7 +377,7 @@ var FileDropzoneController = class extends Controller {
     for (const file of Array.from(files)) {
       const reason = this.#validate(file);
       if (reason !== null) {
-        if (this.hasZoneTarget) this.zoneTarget.setAttribute(INVALID_ATTRIBUTE, "");
+        if (this.hasZoneTarget) this.zoneTarget.setAttribute(this.#invalidAttribute, "");
         const batch = rejected.get(reason);
         if (batch) batch.count += 1;
         else rejected.set(reason, { name: file.name, count: 1 });
@@ -310,26 +425,25 @@ var FileDropzoneController = class extends Controller {
   /**
    * Builds one preview item (name, optional thumbnail, remove button) and reports
    * whether it was rendered.
+   *
+   * A refused row leaves the addition a no-op — nothing about the selection, the
+   * native input, the announcements, or the events changes — and the row reports
+   * why on the console once per connection.
    */
   #appendFile(file) {
-    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 = 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');
+    if (!this.hasListTarget) {
+      this.#rows.report('a "list" target to render into');
+      return false;
+    }
+    if (!this.hasItemTemplateTarget) {
+      this.#rows.report('an "itemTemplate" target');
+      return false;
     }
-    name.textContent = file.name;
-    button.setAttribute("aria-label", fillTemplate(removeName, { name: file.name }));
+    const row = this.#rows.instantiate(this.itemTemplateTarget, { name: file.name });
+    if (!row) return false;
+    const item = row.root;
+    writeLabel(row.slots.name, file.name);
+    const thumb = row.slots.thumb;
     let url;
     if (thumb && file.type.startsWith("image/")) {
       url = URL.createObjectURL(file);
@@ -339,32 +453,10 @@ var FileDropzoneController = class extends Controller {
     } else if (thumb) {
       thumb.hidden = true;
     }
-    this.listTarget.appendChild(fragment);
+    this.listTarget.appendChild(item);
     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) {
     const entry = this.#entries[index];
@@ -473,7 +565,7 @@ var FileDropzoneController = class extends Controller {
     this.#entries.length = 0;
     this.#syncInput();
     this.#endDrag();
-    if (this.hasZoneTarget) this.zoneTarget.removeAttribute(INVALID_ATTRIBUTE);
+    if (this.hasZoneTarget) this.zoneTarget.removeAttribute(this.#invalidAttribute);
   }
   /** Releases the selection once the disconnect is known to be a real detach. */
   #teardown() {
@@ -493,8 +585,9 @@ var FileDropzoneController = class extends Controller {
   get #removeButtons() {
     const buttons = [];
     for (const entry of this.#entries) {
-      const button = entry.item.querySelector(
-        'button[data-stimeo--file-dropzone-target~="remove"]'
+      const button = matchingPart(
+        entry.item,
+        `button${this.#rows.selector("remove")}`
       );
       if (button) buttons.push(button);
     }

data/dist/controllers/filter_controller.js

@@ -9,6 +9,12 @@ var FilterController = class extends Controller {
   #onChange = () => {
     this.apply();
   };
+  /**
+   * The outcome the last `change` reported, which the next evaluation is compared
+   * with; `null` until the first evaluation after `connect()`, which reports
+   * whatever it finds.
+   */
+  #reported = null;
   /**
    * Gates the declaration callback to the connected window.
    *
@@ -18,6 +24,7 @@ var FilterController = class extends Controller {
    */
   #connected = false;
   connect() {
+    this.#reported = null;
     this.#evaluate();
     this.element.addEventListener("change", this.#onChange);
     this.#connected = true;
@@ -44,7 +51,10 @@ var FilterController = class extends Controller {
   }
   /**
    * The evaluation itself: every item's visibility from the active tokens, then
-   * the groups and the empty element, then the `change` event.
+   * the groups and the empty element, then `change` when the outcome moved from
+   * the one last reported. Several triggers can land on the same outcome — a
+   * `clear` evaluates, and a toggle group wired to `apply` reports the presses it
+   * turned off — so an evaluation that changes nothing reports nothing.
    *
    * @stimeoRenderRoot
    */
@@ -62,9 +72,13 @@ var FilterController = class extends Controller {
     for (const empty of this.emptyTargets) {
       empty.hidden = visibleCount > 0;
     }
-    this.dispatch("change", {
-      detail: { active, visible: visibleCount, total: this.itemTargets.length }
-    });
+    const total = this.itemTargets.length;
+    const reported = this.#reported;
+    if (reported !== null && reported.visibleCount === visibleCount && reported.total === total && reported.active.length === active.length && reported.active.every((token, index) => token === active[index])) {
+      return;
+    }
+    this.#reported = { active, visibleCount, total };
+    this.dispatch("change", { detail: { active: [...active], visibleCount, total } });
   }
   /** Turns every control off (uncheck / aria-pressed="false") and re-applies. */
   clear() {
@@ -92,7 +106,7 @@ var FilterController = class extends Controller {
   }
   /** A control's token: explicit `data-stimeo--filter-token`, else `data-value` / value. */
   #tokenOf(control) {
-    const explicit = control.getAttribute("data-stimeo--filter-token") ?? control.dataset.value;
+    const explicit = control.getAttribute(`data-${this.identifier}-token`) ?? control.dataset.value;
     if (explicit) return explicit;
     return control instanceof HTMLInputElement ? control.value : "";
   }
@@ -104,7 +118,7 @@ var FilterController = class extends Controller {
   }
   /** An item's declared tokens (`data-stimeo--filter-tokens`, space-separated). */
   #tokensOf(item) {
-    return (item.getAttribute("data-stimeo--filter-tokens") ?? "").split(/\s+/).filter(Boolean);
+    return (item.getAttribute(`data-${this.identifier}-tokens`) ?? "").split(/\s+/).filter(Boolean);
   }
   /** Whether a group still contains at least one non-hidden item. */
   #hasVisibleItem(group) {