stimeo-ui 0.16.0 → 0.18.0

data/dist/controllers/smart_sticky_header_controller.js

@@ -1,8 +1,5 @@
 import { Controller } from '@hotwired/stimulus';
 
-// src/controllers/smart_sticky_header_controller.ts
-
-// src/utils/declared_value.ts
 function parseDeclared(raw, parse, fallback) {
   try {
     return parse(raw);
@@ -22,14 +19,8 @@ function validSelector(element, raw, fallback) {
   );
 }
 
-// src/utils/frame_coalescer.ts
 var FrameCoalescer = class {
   #frame = null;
-  /**
-   * Runs `run` on the next frame, unless a frame is already pending — the first
-   * request of a burst wins and the rest are dropped. The pending frame is
-   * released before `run`, so `run` may request the next one.
-   */
   schedule(run) {
     if (this.#frame !== null) return;
     this.#frame = requestAnimationFrame(() => {
@@ -37,14 +28,6 @@ var FrameCoalescer = class {
       run();
     });
   }
-  /**
-   * Drops the pending frame, and reaches the platform only when there is one.
-   *
-   * There is no handle value that stands for "nothing pending":
-   * `cancelAnimationFrame` takes an `unsigned long`, so a negative placeholder
-   * arrives as a large positive number that the same allocator can hand out, and
-   * an idle cancel would then drop a frame belonging to someone else.
-   */
   cancel() {
     if (this.#frame === null) return;
     cancelAnimationFrame(this.#frame);
@@ -52,7 +35,121 @@ var FrameCoalescer = class {
   }
 };
 
-// src/utils/scroll_source.ts
+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();
+  }
+};
+
+var MicrotaskCoalescer = class {
+  #run;
+  #queued = false;
+  #active = false;
+  #generation = 0;
+  constructor(run) {
+    this.#run = run;
+  }
+  activate() {
+    this.#active = true;
+  }
+  cancel() {
+    this.#active = false;
+    this.#queued = false;
+    this.#generation += 1;
+  }
+  get pending() {
+    return this.#queued;
+  }
+  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();
+    });
+  }
+};
+
+var MorphRenderWatcher = class {
+  #listeners = new ListenerSet();
+  #pass;
+  #element = null;
+  #onMorph = () => this.#pass.schedule();
+  constructor(run) {
+    this.#pass = new MicrotaskCoalescer(run);
+  }
+  observe(element) {
+    if (this.#element === element) return;
+    this.disconnect();
+    this.#element = element;
+    this.#pass.activate();
+    this.#listeners.add(element, "turbo:morph-element", this.#onMorph);
+  }
+  schedule() {
+    this.#pass.schedule();
+  }
+  get pending() {
+    return this.#pass.pending;
+  }
+  disconnect() {
+    this.#listeners.dispose();
+    this.#pass.cancel();
+    this.#element = null;
+  }
+};
+
+var NUMBER_BOUNDS = {
+  finite: { finite: true },
+  nonNegative: { finite: true, min: 0 }};
+function matchesNumberBounds(value, bounds) {
+  if (!Number.isFinite(value)) {
+    const direction = value === Infinity ? "positive" : value === -Infinity ? "negative" : null;
+    if (direction === null) return false;
+    if (bounds.allowInfinity !== "both" && bounds.allowInfinity !== direction) return false;
+  }
+  if (bounds.min !== void 0 && value < bounds.min) return false;
+  if (bounds.max !== void 0 && value > bounds.max) return false;
+  if (bounds.exclusiveMin !== void 0 && value <= bounds.exclusiveMin) return false;
+  if (bounds.integer && !Number.isInteger(value)) return false;
+  if (bounds.allowedValues !== void 0 && !bounds.allowedValues.includes(value)) return false;
+  return true;
+}
+
+function readNumber(raw, fallback, bounds) {
+  return matchesNumberBounds(raw, bounds) ? raw : fallback;
+}
+
+var NumberValueReader = class {
+  #lastRejected = /* @__PURE__ */ new Map();
+  read(owner, name, raw, fallback, bounds) {
+    const resolved = readNumber(raw, fallback, bounds);
+    if (matchesNumberBounds(raw, bounds)) {
+      this.#lastRejected.delete(name);
+      return resolved;
+    }
+    const attribute = `data-${owner.identifier}-${name.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`)}-value`;
+    const literal = owner.element.getAttribute(attribute);
+    if (literal === null) {
+      this.#lastRejected.delete(name);
+      return resolved;
+    }
+    if (this.#lastRejected.get(name) !== literal) {
+      this.#lastRejected.set(name, literal);
+      console.warn(
+        `Stimeo UI: "${owner.identifier}" has an invalid number Value "${name}" declaration ${JSON.stringify(literal)}; using ${fallback}.`
+      );
+    }
+    return resolved;
+  }
+};
+
 function resolveScrollContainer(selector) {
   const match = selector ? document.querySelector(selector) : null;
   return match instanceof HTMLElement ? match : null;
@@ -64,64 +161,66 @@ function scrollOffset(source) {
   return source === window ? window.scrollY ?? window.pageYOffset ?? 0 : source.scrollTop;
 }
 
-// src/controllers/smart_sticky_header_controller.ts
 var DEFAULT_OFFSET = 80;
-var SmartStickyHeaderController = class extends Controller {
+var SmartStickyHeaderController = class _SmartStickyHeaderController extends Controller {
+  #numbers = new NumberValueReader();
   static values = {
     containerSelector: { type: String, default: "" },
     offset: { type: Number, default: DEFAULT_OFFSET },
     tolerance: { type: Number, default: 4 }
   };
+  static valueConstraints = {
+    offset: NUMBER_BOUNDS.finite,
+    tolerance: NUMBER_BOUNDS.nonNegative
+  };
   static events = ["change"];
-  #connected = false;
-  /** Coalesces scroll bursts into one measurement per frame. */
   #frames = new FrameCoalescer();
-  /** The scroll source resolved at connect — disconnect must unbind the SAME node. */
   #scrollerEl = window;
-  /** The validated `containerSelector`, or `""` when the declaration cannot be parsed. */
+  #scrollListeners = new ListenerSet();
+  #listeners = new ListenerSet();
   #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;
+    return this.#safeOffset;
   }
   #onScroll = () => this.#frames.schedule(() => this.#measure());
-  /**
-   * Focus inside a hidden header must reveal it (WCAG 2.4.7 / 2.4.11); the
-   * 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 = validSelector(this.element, this.containerSelectorValue, "");
+    this.#morphRender.schedule();
   }
-  /** Re-decides when application code (or a Turbo morph) changes `offset` at runtime. */
   offsetValueChanged() {
-    if (this.#connected) this.#measure();
+    this.#morphRender.schedule();
   }
+  #morphRender = new MorphRenderWatcher(() => {
+    this.#followSource();
+    this.#measure();
+  });
   connect() {
+    this.#morphRender.observe(this.element);
     this.#hidden = null;
-    this.#scrollerEl = resolveScrollSource(this.#containerSelector);
-    this.#lastY = scrollOffset(this.#scrollerEl);
-    this.#scrollerEl.addEventListener("scroll", this.#onScroll, { passive: true });
-    this.element.addEventListener("focusin", this.#onFocusin);
+    this.#listenTo(resolveScrollSource(this.#containerSelector));
+    this.#listeners.add(this.element, "focusin", this.#onFocusin);
     this.#apply(false, false);
-    this.#connected = true;
   }
   disconnect() {
-    this.#connected = false;
-    this.#scrollerEl.removeEventListener("scroll", this.#onScroll);
-    this.element.removeEventListener("focusin", this.#onFocusin);
+    this.#morphRender.disconnect();
+    this.#scrollListeners.dispose();
+    this.#listeners.dispose();
     this.#frames.cancel();
   }
-  /** @stimeoRenderRoot */
+  #followSource() {
+    const source = resolveScrollSource(this.#containerSelector);
+    if (source === this.#scrollerEl) return;
+    this.#scrollListeners.dispose();
+    this.#listenTo(source);
+  }
+  #listenTo(source) {
+    this.#scrollerEl = source;
+    this.#lastY = scrollOffset(source);
+    this.#scrollListeners.add(source, "scroll", this.#onScroll, { passive: true });
+  }
   #measure() {
     const y = scrollOffset(this.#scrollerEl);
     if (y <= this.#offset) {
@@ -130,34 +229,42 @@ var SmartStickyHeaderController = class extends Controller {
       return;
     }
     const delta = y - this.#lastY;
-    if (this.#isJitter(delta)) return;
+    if (this.#isJitter(delta)) {
+      this.#apply(this.#hidden ?? false);
+      return;
+    }
     this.#lastY = y;
     this.#apply(delta > 0);
   }
-  /**
-   * Whether one scroll step is too small to act on.
-   *
-   * @stimeoRuntimeOnly `tolerance` is the allowance one scroll step is compared against; the
-   *   header's state at rest does not depend on it.
-   */
   #isJitter(delta) {
-    return Math.abs(delta) < this.toleranceValue;
-  }
-  /**
-   * 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.
-   */
+    return Math.abs(delta) < this.#safeTolerance;
+  }
   #apply(hidden, notify = true) {
     if (hidden && this.element.contains(document.activeElement)) return;
-    if (hidden === this.#hidden) return;
+    const changed = hidden !== this.#hidden;
     this.#hidden = hidden;
     this.element.setAttribute("data-header-hidden", hidden ? "true" : "false");
-    if (notify) this.dispatch("change", { detail: { hidden } });
+    if (notify && changed) this.dispatch("change", { detail: { hidden } });
+  }
+  get #safeOffset() {
+    return this.#numbers.read(
+      this,
+      "offset",
+      this.offsetValue,
+      _SmartStickyHeaderController.values.offset.default,
+      _SmartStickyHeaderController.valueConstraints.offset
+    );
+  }
+  get #safeTolerance() {
+    return this.#numbers.read(
+      this,
+      "tolerance",
+      this.toleranceValue,
+      _SmartStickyHeaderController.values.tolerance.default,
+      _SmartStickyHeaderController.valueConstraints.tolerance
+    );
   }
 };
 
 export { SmartStickyHeaderController };
-//# sourceMappingURL=smart_sticky_header_controller.js.map
 //# sourceMappingURL=smart_sticky_header_controller.js.map

data/dist/controllers/sortable_controller.js

@@ -1,8 +1,12 @@
 import { Controller } from '@hotwired/stimulus';
 
-// src/controllers/sortable_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,39 +16,41 @@ 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/logical_scroll.ts
+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 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. */
+  get pending() {
+    return this.#queued;
+  }
   schedule() {
     if (!this.#active || this.#queued) return;
     this.#queued = true;
@@ -57,19 +63,16 @@ var MicrotaskCoalescer = class {
   }
 };
 
-// src/utils/transient_hooks.ts
 var TransientHooks = class {
   #attributes;
   constructor(options) {
     this.#attributes = options.attributes;
   }
-  /** Drops the declared hooks from `element`; what it carries besides stays. */
   reset(element) {
     for (const attribute of this.#attributes) element.removeAttribute(attribute);
   }
 };
 
-// src/controllers/sortable_controller.ts
 var TRANSIENT = new TransientHooks({ attributes: ["data-sortable-dragging"] });
 var SortableController = class extends Controller {
   static targets = ["list", "item"];
@@ -82,36 +85,22 @@ var SortableController = class extends Controller {
   };
   static events = ["reorder"];
   #session = null;
-  /** Defers the lost-item check to after the mutation batch (see below). */
   #settle = new MicrotaskCoalescer(() => this.#dropLostSession());
+  #listeners = new ListenerSet();
   connect() {
     TRANSIENT.reset(this.element);
     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);
-    this.element.addEventListener("stimeo--pointer-drag:cancel", this.#onDragCancel);
+    this.#listeners.add(this.element, "stimeo--pointer-drag:start", this.#onDragStart);
+    this.#listeners.add(this.element, "stimeo--pointer-drag:move", this.#onDragMove);
+    this.#listeners.add(this.element, "stimeo--pointer-drag:end", this.#onDragEnd);
+    this.#listeners.add(this.element, "stimeo--pointer-drag:cancel", this.#onDragCancel);
   }
   disconnect() {
-    this.element.removeEventListener("stimeo--pointer-drag:start", this.#onDragStart);
-    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.#listeners.dispose();
     this.#settle.cancel();
     this.#session = null;
     this.element.removeAttribute("data-sortable-dragging");
   }
-  /**
-   * 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();
@@ -125,7 +114,6 @@ var SortableController = class extends Controller {
     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 items = this.#items();
@@ -153,7 +141,6 @@ var SortableController = class extends Controller {
       this.#followPointer(session, detail, items);
     }
   };
-  /** Drops the item: announces, then reports `reorder` if the position changed. */
   #onDragEnd = (event) => {
     const session = this.#session;
     if (!session) return;
@@ -168,7 +155,6 @@ var SortableController = class extends Controller {
       this.dispatch("reorder", { detail: { item: session.item, from, to } });
     }
   };
-  /** Restores the pickup position (Escape / OS `pointercancel`). */
   #onDragCancel = (event) => {
     const session = this.#session;
     if (!session) return;
@@ -179,16 +165,6 @@ var SortableController = class extends Controller {
     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) {
@@ -202,7 +178,6 @@ var SortableController = class extends Controller {
     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;
@@ -212,17 +187,6 @@ var SortableController = class extends Controller {
       slot
     );
   }
-  /**
-   * Keyboard stepping: `pointer-drag` reports *cumulative* synthetic deltas, so
-   * the difference from the last consumed value is one arrow press — its sign is
-   * the direction. Cross-axis arrows never change the primary delta (no move).
-   *
-   * The sign is physical (`ArrowRight` is always `+dx`), so a right-to-left row
-   * has to invert it: there, moving the item rightward means moving it *earlier*
-   * in the DOM. Skipping this would also split the two halves of one keypress —
-   * `roving` already moves focus logically, so the same arrow would send the
-   * focus and the grabbed item opposite ways.
-   */
   #stepFromKeyboard(session, detail, items) {
     const primary = Number(this.#isVertical ? detail.dy : detail.dx) || 0;
     const delta = primary - session.lastPrimary;
@@ -239,18 +203,6 @@ var SortableController = class extends Controller {
     );
     this.#announce("moved", session.item);
   }
-  /**
-   * Pointer following: the item moves to the slot whose siblings' midpoints the
-   * 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, items) {
     const pointer = Number(this.#isVertical ? detail.y : detail.x) || 0;
     const vertical = this.#isVertical;
@@ -272,18 +224,6 @@ var SortableController = class extends Controller {
     this.#insertAt(session.item, laidOut, target);
     this.#announce("moved", session.item);
   }
-  /**
-   * 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;
@@ -297,20 +237,6 @@ var SortableController = class extends Controller {
     parent.insertBefore(item, ahead ?? neighbour.nextSibling);
     if (hadFocus) active.focus();
   }
-  /**
-   * 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.
-   *
-   * @stimeoRuntimeOnly The texts word the steps of one reorder, spoken as they happen.
-   */
   #announce(key, item) {
     const template = this.#announceTemplate(key);
     if (template.length === 0) return;
@@ -323,7 +249,6 @@ var SortableController = class extends Controller {
       })
     );
   }
-  /** The consumer's wording for one step, or `""` when they authored none. */
   #announceTemplate(key) {
     switch (key) {
       case "grabbed":
@@ -336,52 +261,28 @@ var SortableController = class extends Controller {
         return this.announceCanceledTextValue;
     }
   }
-  /** The announced item name: the authored override, else its collapsed text. */
   #nameOf(item) {
     const authored = item.getAttribute(`data-${this.identifier}-name`);
     if (authored) return authored;
     return (item.textContent ?? "").replace(/\s+/g, " ").trim();
   }
-  /**
-   * 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() {
     return this.itemTargets;
   }
-  /** The reorder container: the `list` target when present, else the element. */
   get #list() {
     return this.hasListTarget ? this.listTarget : this.element;
   }
   get #isVertical() {
     return this.orientationValue !== "horizontal";
   }
-  /**
-   * Whether DOM order runs opposite to the primary coordinate — true only for a
-   * horizontal row under `dir="rtl"`, where the first item sits at the largest
-   * `x`. Both drag paths reach this controller in physical terms (`pointer-drag`
-   * documents its deltas as physical and hands RTL to its consumer, which is
-   * this controller), so both have to be mapped back onto DOM order here.
-   *
-   * Read from the list, the element that lays the items out — never from the
-   * dragged item, which may carry its own `dir`. The list inherits the computed
-   * direction, so authoring `dir` on the root works too. A vertical list is
-   * unaffected: writing direction does not mirror the block axis.
-   */
   get #isReversed() {
     return !this.#isVertical && isRtl(this.#list);
   }
 };
 
 export { SortableController };
-//# sourceMappingURL=sortable_controller.js.map
 //# sourceMappingURL=sortable_controller.js.map