stimeo-ui 0.16.0 → 0.17.0

data/dist/controllers/local_time_controller.js

@@ -1,8 +1,5 @@
 import { Controller } from '@hotwired/stimulus';
 
-// src/controllers/local_time_controller.ts
-
-// src/utils/intl_format.ts
 var formatters = /* @__PURE__ */ new WeakMap();
 function intlFormatter(factory, locale, options, fallbackLocale) {
   const cache = cacheFor(factory);
@@ -31,32 +28,37 @@ function construct(factory, locale, options, fallbackLocale) {
   }
 }
 
-// src/utils/locale.ts
 function resolveLocale(element, declared = "") {
   return declared || element.closest("[lang]")?.getAttribute("lang") || void 0;
 }
 
-// src/utils/microtask_coalescer.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;
-  /** @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;
@@ -69,7 +71,31 @@ var MicrotaskCoalescer = class {
   }
 };
 
-// src/controllers/local_time_controller.ts
+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();
+  }
+  disconnect() {
+    this.#listeners.dispose();
+    this.#pass.cancel();
+    this.#element = null;
+  }
+};
+
 var STYLES = /* @__PURE__ */ new Set(["full", "long", "medium", "short"]);
 function toStyle(value) {
   return STYLES.has(value) ? value : void 0;
@@ -83,55 +109,48 @@ var LocalTimeController = class extends Controller {
     titleFormat: { type: String, default: "" }
   };
   static events = ["format"];
-  /** Collapses a morph that swaps several render inputs at once into one repaint. */
-  #resync = new MicrotaskCoalescer(() => this.#render());
-  /**
-   * Watches the one render input that is not a Value. Only `datetime` is filtered
-   * in, so the text and `title` this controller writes cannot re-enter the pass.
-   */
+  #resync = new MorphRenderWatcher(() => {
+    const datetimeChanged = this.#datetimeWatch.takeRecords().length > 0;
+    const notify = this.#formatPending || datetimeChanged;
+    this.#formatPending = false;
+    this.#render(notify);
+  });
+  #formatPending = false;
   #datetimeWatch = new MutationObserver(() => {
+    this.#formatPending = true;
     this.#resync.schedule();
   });
   connect() {
-    this.#resync.activate();
+    this.#resync.observe(this.element);
     this.#datetimeWatch.observe(this.element, { attributeFilter: ["datetime"] });
+    this.#formatPending = false;
     this.#render();
   }
   disconnect() {
-    this.#resync.cancel();
+    this.#resync.disconnect();
     this.#datetimeWatch.disconnect();
   }
-  /** Repaints when application code (or a Turbo morph) changes `locale` at runtime. */
   localeValueChanged() {
+    this.#formatPending = true;
     this.#resync.schedule();
   }
-  /** Repaints when application code (or a Turbo morph) changes `timeZone` at runtime. */
   timeZoneValueChanged() {
+    this.#formatPending = true;
     this.#resync.schedule();
   }
-  /** Repaints when application code (or a Turbo morph) changes `dateStyle` at runtime. */
   dateStyleValueChanged() {
+    this.#formatPending = true;
     this.#resync.schedule();
   }
-  /** Repaints when application code (or a Turbo morph) changes `timeStyle` at runtime. */
   timeStyleValueChanged() {
+    this.#formatPending = true;
     this.#resync.schedule();
   }
-  /** Repaints when application code (or a Turbo morph) changes `titleFormat` at runtime. */
   titleFormatValueChanged() {
+    this.#formatPending = true;
     this.#resync.schedule();
   }
-  /**
-   * Formats the instant in `datetime` against the current Values and writes it out.
-   *
-   * The `format` event rides with every pass, including a repaint a morph triggers:
-   * its condition is that formatting was applied, and a repaint applies it with a
-   * new result. A pass that cannot format writes nothing and emits nothing, so the
-   * authored absolute text stays as the fallback.
-   *
-   * @stimeoRenderRoot
-   */
-  #render() {
+  #render(notify = true) {
     const date = this.#parse();
     if (date === null) return;
     const formatted = this.#applyFormat(date, this.dateStyleValue, this.timeStyleValue);
@@ -139,31 +158,14 @@ var LocalTimeController = class extends Controller {
     this.element.textContent = formatted;
     const title = this.#title(date);
     if (title !== null) this.element.setAttribute("title", title);
-    this.dispatch("format", { detail: { formatted } });
+    if (notify) this.dispatch("format", { detail: { formatted } });
   }
-  /**
-   * Parses the UTC `datetime` attribute into a {@link Date}, or `null`. Whitespace
-   * around the attribute value is tolerated.
-   */
   #parse() {
     const raw = this.element.getAttribute("datetime");
     if (!raw) return null;
     const ms = Date.parse(this.#asUtc(raw.trim()));
     return Number.isNaN(ms) ? null : new Date(ms);
   }
-  /**
-   * Reads a timezone-less date-time as UTC — the input contract of this
-   * controller — since `Date.parse` would otherwise read `"2026-06-08T12:30:00"` in
-   * the *runtime's* local zone, contradicting "the server emits UTC". Values that
-   * already carry `Z` or a `±hh:mm` offset (and bare `YYYY-MM-DD` dates, already
-   * parsed as UTC) are returned unchanged.
-   *
-   * HTML accepts a space where ISO 8601 wants `T`, and `Date.parse` of that form is
-   * left to each engine, so a whole value shaped that way is normalized to the `T`
-   * separator first. The pattern is anchored: a value trailing anything else — a
-   * zone word such as `"2026-06-08 12:30:00 UTC"` — is handed to `Date.parse` as
-   * authored instead of being turned into a string nothing can parse.
-   */
   #asUtc(value) {
     const isoLike = value.replace(
       /^(\d{4}-\d{2}-\d{2}) (\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:?\d{2})?)$/,
@@ -173,21 +175,10 @@ var LocalTimeController = class extends Controller {
     const hasZone = /(Z|[+-]\d{2}:?\d{2})$/.test(isoLike);
     return hasTime && !hasZone ? `${isoLike}Z` : isoLike;
   }
-  /**
-   * Builds the optional detailed `title`. `titleFormat` is an `Intl` style
-   * keyword applied to *both* date and time; empty (the default) adds no title.
-   */
   #title(date) {
     if (this.titleFormatValue.length === 0) return null;
     return this.#applyFormat(date, this.titleFormatValue, this.titleFormatValue);
   }
-  /**
-   * Formats `date` with `Intl.DateTimeFormat`, including each style only when it
-   * is a valid keyword (so a consumer can show date-only or time-only by clearing
-   * the other). Returns `null` when neither style is usable or the declaration
-   * names a locale or time zone `Intl` rejects, so the caller can leave the
-   * authored text untouched.
-   */
   #applyFormat(date, dateStyle, timeStyle) {
     const options = {
       dateStyle: toStyle(dateStyle),
@@ -205,5 +196,4 @@ var LocalTimeController = class extends Controller {
 };
 
 export { LocalTimeController };
-//# sourceMappingURL=local_time_controller.js.map
 //# sourceMappingURL=local_time_controller.js.map

data/dist/controllers/masonry_controller.js

@@ -1,19 +1,14 @@
 import { Controller } from '@hotwired/stimulus';
 
-// src/controllers/masonry_controller.ts
-
-// src/utils/layout_observer.ts
 var LayoutObserver = class {
   #callback;
   #resizeObserverFactory;
   #resizeObserver = null;
   #observingViewport = false;
   #loadContainer = null;
-  /** Stable bound handler so add/removeEventListener target the same reference. */
   #handleViewportResize = () => {
     this.#callback();
   };
-  /** Stable bound handler for the capture-phase `load`; see {@link observeDescendantLoads}. */
   #handleDescendantLoad = () => {
     this.#callback();
   };
@@ -21,11 +16,6 @@ var LayoutObserver = class {
     this.#callback = callback;
     this.#resizeObserverFactory = options.resizeObserverFactory ?? (typeof ResizeObserver === "undefined" ? null : (cb) => new ResizeObserver(cb));
   }
-  /**
-   * Starts observing an element's size. Repeated calls observe additional
-   * elements through the same shared observer. No-ops when no
-   * `ResizeObserver` implementation is available.
-   */
   observe(element) {
     if (!this.#resizeObserverFactory) return;
     if (!this.#resizeObserver) {
@@ -35,47 +25,28 @@ var LayoutObserver = class {
     }
     this.#resizeObserver.observe(element);
   }
-  /** Stops observing a single element while leaving any others in place. */
   unobserve(element) {
     this.#resizeObserver?.unobserve(element);
   }
-  /** Starts observing viewport resizes. Idempotent: the listener is added once. */
   observeViewport() {
     if (this.#observingViewport) return;
     this.#observingViewport = true;
     window.addEventListener("resize", this.#handleViewportResize);
   }
-  /** Stops observing viewport resizes without affecting element observation. */
   unobserveViewport() {
     if (!this.#observingViewport) return;
     this.#observingViewport = false;
     window.removeEventListener("resize", this.#handleViewportResize);
   }
-  /**
-   * Starts reporting a `load` from anywhere inside `container` — an image or a
-   * frame settling changes the box it sits in, and it measures as zero high until
-   * then. `load` does not bubble, so the subscription is a capture-phase listener
-   * on the container itself and nothing the caller spells.
-   *
-   * **One container at a time.** A further call moves the observation, so a widget
-   * whose content element is swapped at runtime releases the element it let go by
-   * naming the new one — there is no second place for the release to drift from.
-   */
   observeDescendantLoads(container) {
     this.unobserveDescendantLoads();
     this.#loadContainer = container;
     container.addEventListener("load", this.#handleDescendantLoad, true);
   }
-  /** Stops reporting descendant loads without affecting element or viewport observation. */
   unobserveDescendantLoads() {
     this.#loadContainer?.removeEventListener("load", this.#handleDescendantLoad, true);
     this.#loadContainer = null;
   }
-  /**
-   * Releases every observation: disconnects the {@link ResizeObserver} and removes
-   * the viewport and descendant-load listeners. Safe to call multiple times. Call
-   * this from a controller's `disconnect()`.
-   */
   disconnect() {
     this.#resizeObserver?.disconnect();
     this.#resizeObserver = null;
@@ -84,27 +55,22 @@ var LayoutObserver = class {
   }
 };
 
-// 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;
@@ -117,69 +83,87 @@ var MicrotaskCoalescer = class {
   }
 };
 
-// src/controllers/masonry_controller.ts
+var NUMBER_BOUNDS = {
+  finite: { finite: true }};
+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;
+  }
+};
+
 var COLUMNS_PROPERTY = "--stimeo--masonry-columns";
 var DEFAULT_MIN_COLUMN_WIDTH = 240;
 var DEFAULT_GAP = 16;
-function usableNumber(value, fallback) {
-  return Number.isFinite(value) ? value : fallback;
-}
-var MasonryController = class extends Controller {
+var MasonryController = class _MasonryController extends Controller {
+  #numbers = new NumberValueReader();
   static targets = ["item"];
   static values = {
     minColumnWidth: { type: Number, default: DEFAULT_MIN_COLUMN_WIDTH },
     gap: { type: Number, default: DEFAULT_GAP }
   };
+  static valueConstraints = {
+    minColumnWidth: NUMBER_BOUNDS.finite,
+    gap: NUMBER_BOUNDS.finite
+  };
   static events = ["layout"];
-  /**
-   * The declared numbers after validation, so the layout path never sees a value
-   * it cannot compute with. Both are resolved once per declaration change rather
-   * than on every pass.
-   */
   #minColumnWidth = DEFAULT_MIN_COLUMN_WIDTH;
   #gap = DEFAULT_GAP;
-  /**
-   * Collapses every re-layout trigger of one DOM mutation into a single pass, and
-   * refuses to run before `connect()` or after `disconnect()`.
-   *
-   * The triggers arrive in bursts — a resize stream, a morph that syncs several
-   * attributes, a batch of rows — and each pass measures every item, so folding
-   * them keeps the work proportional to the batch rather than to the events in it.
-   */
   #reconcile = new MicrotaskCoalescer(() => this.#relayout());
-  /** Items that left the target set and still carry the column hook. */
   #released = /* @__PURE__ */ new Set();
   #layout = new LayoutObserver(() => this.#reconcile.schedule());
   #mutationObserver = null;
-  /** Last published column count, so `layout` fires only on real changes. */
   #lastColumns = 0;
-  /** Resolves the declared column width once, falling back when it is unreadable. */
   minColumnWidthValueChanged() {
-    this.#minColumnWidth = usableNumber(this.minColumnWidthValue, DEFAULT_MIN_COLUMN_WIDTH);
+    this.#minColumnWidth = this.#safeMinColumnWidth;
     this.#reconcile.schedule();
   }
-  /** Resolves the declared gap once, falling back when it is unreadable. */
   gapValueChanged() {
-    this.#gap = usableNumber(this.gapValue, DEFAULT_GAP);
+    this.#gap = this.#safeGap;
     this.#reconcile.schedule();
   }
-  /** Packs an element that became an item without moving in the DOM. */
   itemTargetConnected() {
     this.#reconcile.schedule();
   }
-  /**
-   * Queues the column hook of an element that stopped being an item for removal.
-   *
-   * The removal is queued rather than immediate because teardown reports every
-   * target as disconnected: doing it here would strip the whole grid just before
-   * a Turbo snapshot is taken. The coalescer's `cancel` drops the queue
-   * with the pass, so only a genuine target change reaches it.
-   */
   itemTargetDisconnected(item) {
     this.#released.add(item);
     this.#reconcile.schedule();
   }
-  /** Observes size/content changes and performs the first layout pass. */
   connect() {
     this.#layout.observe(this.element);
     this.#layout.observeViewport();
@@ -191,31 +175,13 @@ var MasonryController = class extends Controller {
     this.#relayout();
     this.#reconcile.activate();
   }
-  /** Releases every observation so nothing fires after detach. */
   disconnect() {
     this.#reconcile.cancel();
-    this.#released.clear();
     this.#layout.disconnect();
     this.#mutationObserver?.disconnect();
     this.#mutationObserver = null;
     this.#lastColumns = 0;
   }
-  /**
-   * Recomputes the column count and assigns every item to the shortest column.
-   * Runs automatically on connect, on resize, on item add/remove, when a declared
-   * number changes, and when a descendant resource loads (private — there is no
-   * public action; the observers, the target callbacks and the capture-phase
-   * `load` listener drive it). Items are walked in DOM order; each lands in the
-   * column with the least accumulated height, which keeps the packing balanced
-   * without reordering the DOM.
-   *
-   * Every box is measured before anything is written. Interleaving the two would
-   * make a consumer's `data-column` rule invalidate style once per item, and the
-   * next measurement then has to settle layout again — once per item instead of
-   * once per pass. The assignment is independent of the measurement because the
-   * columns are uniform in width, so the order of the two passes does not change
-   * the result.
-   */
   #relayout() {
     const items = this.itemTargets;
     const columns = this.#columnCount();
@@ -251,20 +217,31 @@ var MasonryController = class extends Controller {
       this.dispatch("layout", { detail: { columns } });
     }
   }
-  /**
-   * Derives how many columns fit: `floor((width + gap) / (minColumnWidth + gap))`,
-   * never fewer than one. When the width is unmeasurable (detached, or a layout
-   * engine that reports `0`), it falls back to a single column so every item still
-   * gets a valid `data-column`.
-   */
   #columnCount() {
     const width = this.element.getBoundingClientRect().width;
     const denominator = this.#minColumnWidth + this.#gap;
     if (width <= 0 || denominator <= 0) return 1;
     return Math.max(1, Math.floor((width + this.#gap) / denominator));
   }
+  get #safeMinColumnWidth() {
+    return this.#numbers.read(
+      this,
+      "minColumnWidth",
+      this.minColumnWidthValue,
+      _MasonryController.values.minColumnWidth.default,
+      _MasonryController.valueConstraints.minColumnWidth
+    );
+  }
+  get #safeGap() {
+    return this.#numbers.read(
+      this,
+      "gap",
+      this.gapValue,
+      _MasonryController.values.gap.default,
+      _MasonryController.valueConstraints.gap
+    );
+  }
 };
 
 export { MasonryController };
-//# sourceMappingURL=masonry_controller.js.map
 //# sourceMappingURL=masonry_controller.js.map