stimeo-ui 0.16.0 → 0.18.0

data/dist/positioning/index.js

@@ -1,7 +1,120 @@
 import { computePosition, autoUpdate, offset, flip, shift } from '@floating-ui/dom';
 import { Controller } from '@hotwired/stimulus';
 
-// src/positioning/index.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 }};
+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 PLACEMENTS = /* @__PURE__ */ new Set([
   "top",
   "top-start",
@@ -16,7 +129,8 @@ var PLACEMENTS = /* @__PURE__ */ new Set([
   "left-start",
   "left-end"
 ]);
-var AnchoredController = class extends Controller {
+var AnchoredController = class _AnchoredController extends Controller {
+  #numbers = new NumberValueReader();
   static targets = ["anchor", "floating"];
   static values = {
     placement: { type: String, default: "bottom" },
@@ -27,32 +141,29 @@ var AnchoredController = class extends Controller {
     strategy: { type: String, default: "absolute" },
     active: { type: Boolean, default: true }
   };
+  static valueConstraints = {
+    offset: NUMBER_BOUNDS.finite,
+    padding: NUMBER_BOUNDS.finite
+  };
   static events = ["position"];
-  /** `autoUpdate` cleanup while tracking; `null` when detached. */
   #stop = null;
-  /** Identity of the live attach; `null` when detached — see {@link #onComputed}. */
   #attachId = null;
-  /** True between connect and disconnect (Stimulus may fire value callbacks before connect). */
   #connected = false;
-  /**
-   * Serialized options as of the last reconcile, empty only before the first one —
-   * a value no serialization produces, so it can never match a real key.
-   */
+  #position = null;
+  #morphRender = new MorphRenderWatcher(() => this.#sync());
   #appliedKey = "";
-  /** Elements the live observer holds, or `null` when detached — see {@link #sync}. */
   #appliedAnchor = null;
   #appliedFloating = null;
   connect() {
+    this.#morphRender.observe(this.element);
     this.#connected = true;
     this.#sync();
   }
   disconnect() {
+    this.#morphRender.disconnect();
     this.#connected = false;
     this.#sync();
   }
-  // Every value change (active or an option) and every target arrival or
-  // departure re-syncs. `#sync` is idempotent and order-independent, so no Value
-  // has to be declared in a particular position.
   anchorTargetConnected() {
     this.#sync();
   }
@@ -86,41 +197,23 @@ var AnchoredController = class extends Controller {
   strategyValueChanged() {
     this.#sync();
   }
-  /** Current Values mapped to the positioning engine's options. */
   get #options() {
     return {
-      // Narrow every free-form Value to what the engine can use. A placement
-      // outside the set would be published on the hook as a resolved side it is
-      // not, and a non-finite distance poisons the coordinate it feeds until the
-      // browser drops the whole declaration and leaves that axis unplaced.
       placement: PLACEMENTS.has(this.placementValue) ? this.placementValue : "bottom",
-      offset: Number.isFinite(this.offsetValue) ? this.offsetValue : 0,
+      offset: this.#safeOffset,
       flip: this.flipValue,
       shift: this.shiftValue,
-      padding: Number.isFinite(this.paddingValue) ? this.paddingValue : 0,
+      padding: this.#safePadding,
       strategy: this.strategyValue === "fixed" ? "fixed" : "absolute"
     };
   }
-  /**
-   * Reconciles the live observer with the desired state — track iff connected,
-   * `active`, and both targets exist — re-attaching only when that state, the
-   * options, or the elements actually changed. Stimulus fires the value-changed
-   * callbacks on connect in declaration order and may run them before or after
-   * `connect()`; keying on what is applied collapses that whole burst (in any
-   * order) to a single attach, while an option or target change at runtime
-   * re-attaches exactly once. So correctness never depends on `active` being
-   * declared last. The elements are part of the key because the engine holds the
-   * pair it was handed: a swap leaves the same options behind and would otherwise
-   * keep measuring the node that just left the document.
-   *
-   * @stimeoRenderRoot
-   */
   #sync() {
     const shouldTrack = this.#connected && this.activeValue && this.hasAnchorTarget && this.hasFloatingTarget;
     const anchor = shouldTrack ? this.anchorTarget : null;
     const floating = shouldTrack ? this.floatingTarget : null;
     const key = JSON.stringify(this.#options);
     if (key === this.#appliedKey && anchor === this.#appliedAnchor && floating === this.#appliedFloating) {
+      if (floating && this.#position) this.#reflectPosition(floating, this.#position);
       return;
     }
     this.#detach();
@@ -143,27 +236,42 @@ var AnchoredController = class extends Controller {
     this.#stop?.();
     this.#stop = null;
     this.#attachId = null;
+    this.#position = null;
   }
-  /**
-   * Reflects the resolved side onto the CSS hook and announces the placement.
-   *
-   * The pass carries the attach that started it and the element it positioned,
-   * and lands only while that attach is still the live one: `autoUpdate`'s
-   * cleanup stops further updates but cannot cancel one already computing, so a
-   * pass superseded mid-flight would otherwise write and dispatch afterwards.
-   * The element cannot stand in for that identity — an option change re-attaches
-   * against the very same pair.
-   */
   #onComputed(id, floating, result) {
     if (id !== this.#attachId) return;
-    floating.setAttribute("data-anchored-placement", result.placement);
+    this.#position = result;
+    this.#reflectPosition(floating, result);
     this.dispatch("position", {
       detail: { placement: result.placement, x: result.x, y: result.y }
     });
   }
+  #reflectPosition(floating, result) {
+    floating.setAttribute("data-anchored-placement", result.placement);
+    floating.style.position = this.#options.strategy ?? "absolute";
+    floating.style.left = `${result.x}px`;
+    floating.style.top = `${result.y}px`;
+  }
+  get #safeOffset() {
+    return this.#numbers.read(
+      this,
+      "offset",
+      this.offsetValue,
+      _AnchoredController.values.offset.default,
+      _AnchoredController.valueConstraints.offset
+    );
+  }
+  get #safePadding() {
+    return this.#numbers.read(
+      this,
+      "padding",
+      this.paddingValue,
+      _AnchoredController.values.padding.default,
+      _AnchoredController.valueConstraints.padding
+    );
+  }
 };
 
-// src/positioning/index.ts
 function buildMiddleware(options) {
   const padding = options.padding ?? 0;
   const middleware = [];
@@ -202,5 +310,4 @@ function registerPositioning(application) {
 }
 
 export { AnchoredController, attachPositioning, position, positioningControllers, registerPositioning };
-//# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

data/lib/generators/stimeo/install/install_generator.rb

@@ -12,8 +12,10 @@ module Stimeo
     # Sets up an importmap-rails app to use Stimeo UI without npm:
     #   1. vendors the gem's prebuilt JS into vendor/javascript/stimeo/
     #   2. pins "stimeo-ui" in config/importmap.rb
-    #   3. registers every stimeo--* controller with the app's Stimulus
-    #      application (app/javascript/controllers/stimeo.js)
+    #   3. registers the "stimeo-ui" entry point's controllers (registerStimeo) with the
+    #      app's Stimulus application (app/javascript/controllers/stimeo.js); the
+    #      positioning and cable subpaths stay opt-in: their pins and registrations
+    #      are written commented out in config/importmap.rb and controllers/stimeo.js
     #
     # Re-running is safe: the vendor copy is refreshed in place, while pins
     # and imports are only appended when missing — so after a gem update you
@@ -60,6 +62,9 @@ module Stimeo
             pin "stimeo-ui", to: "stimeo/index.js"
             # Opt-in positioning module — also pin @floating-ui/dom if you enable it:
             # pin "stimeo-ui/positioning", to: "stimeo/positioning/index.js"
+            # Opt-in cable module — also pin @rails/actioncable if you enable it:
+            # pin "stimeo-ui/cable", to: "stimeo/cable/index.js"
+            # pin "@rails/actioncable", to: "actioncable.esm.js"
           RUBY
         end
       end

data/lib/generators/stimeo/install/templates/stimeo.js

@@ -1,12 +1,25 @@
-// Registers every stimeo--* controller with the app's Stimulus application.
+// Registers the controllers of the "stimeo-ui" entry point with the app's
+// Stimulus application. The opt-in "stimeo-ui/positioning" and "stimeo-ui/cable"
+// entry points register theirs separately (registerPositioning / registerCable):
+// pin the entry point and its peer in config/importmap.rb, then uncomment its
+// import and call below. An app that already owns an Action Cable consumer passes
+// it to setCableConsumer (also from "stimeo-ui/cable") before registerCable, so
+// both share one websocket.
 // Generated by `rails g stimeo:install`. Safe to edit.
 //
-// To cherry-pick instead of registering all controllers, import them
-// individually from "stimeo-ui/controllers/<name>" and register under your own
-// identifiers. Note: with a JS bundler this works as-is; with importmap-rails
-// each "stimeo-ui/controllers/<name>" needs its own pin (this generator only
-// pins the "stimeo-ui" entrypoint), so add those pins to config/importmap.rb.
+// To cherry-pick instead of registering the whole entry point, import controllers
+// individually from "stimeo-ui/controllers/<name>_controller" and register under
+// your own identifiers. Note: with a JS bundler this works as-is; with
+// importmap-rails each "stimeo-ui/controllers/<name>_controller" needs its own pin
+// (this generator only pins the "stimeo-ui" entrypoint), so add those pins to
+// config/importmap.rb.
 import { application } from "controllers/application";
 import { registerStimeo } from "stimeo-ui";
 
 registerStimeo(application);
+
+// import { registerPositioning } from "stimeo-ui/positioning";
+// registerPositioning(application);
+
+// import { registerCable } from "stimeo-ui/cable";
+// registerCable(application);

data/lib/stimeo/ui/version.rb

@@ -5,6 +5,6 @@ module Stimeo
     # Kept in lockstep with package.json (stable versions share the same
     # notation; a prerelease maps npm `-beta.N` ⇔ gem `.pre.beta.N` because
     # RubyGems forbids dashes). Bump both together.
-    VERSION = "0.16.0"
+    VERSION = "0.18.0"
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: stimeo-ui
 version: !ruby/object:Gem::Version
-  version: 0.16.0
+  version: 0.18.0
 platform: ruby
 authors:
 - Stimeo Labs
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-26 00:00:00.000000000 Z
+date: 2026-10-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: railties
@@ -119,7 +119,7 @@ files:
 - dist/controllers/read_more_controller.js
 - dist/controllers/reading_progress_controller.js
 - dist/controllers/relative_time_controller.js
-- dist/controllers/reset_before_cache_controller.js
+- dist/controllers/reset_on_restore_controller.js
 - dist/controllers/resizable_controller.js
 - dist/controllers/roving_controller.js
 - dist/controllers/scroll_area_controller.js