mat_views 0.2.0 → 0.3.0

data/app/javascript/mat_views/controllers/tabs_controller.js

@@ -0,0 +1,67 @@
+/**
+ * Copyright Codevedas Inc. 2025-present
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import { Controller } from "@hotwired/stimulus";
+
+export default class extends Controller {
+  static targets = ["link", "panel"];
+
+  connect() {
+    const qs = new URLSearchParams(window.location.search);
+    const name = qs.get("tab") || this.linkTargets[0]?.dataset?.name;
+    setTimeout(() => {
+      if (name) this.showByName(name, false);
+      else if (this.panelTargets[0])
+        this._ensureFrameLoaded(this.panelTargets[0]);
+    });
+  }
+
+  show(e) {
+    e.preventDefault();
+    const name = e.currentTarget.dataset.name;
+    this.showByName(name, true);
+  }
+
+  showByName(name, pushState) {
+    this.linkTargets.forEach((a) => {
+      const on = a.dataset.name === name;
+      a.classList.toggle("mv-tab--on", on);
+      a.setAttribute("aria-selected", on ? "true" : "false");
+    });
+
+    this.panelTargets.forEach((p) => {
+      p.hidden = p.dataset.name !== name;
+    });
+
+    const active = this.panelTargets.find((p) => p.dataset.name === name);
+    if (active) this._ensureFrameLoaded(active);
+
+    if (pushState) {
+      const url = new URL(window.location);
+      url.searchParams.set("tab", name);
+
+      if (name == "definitions") {
+        url.searchParams.delete("mat_view_definition_id");
+        url.searchParams.delete("operation");
+        url.searchParams.delete("status");
+      }
+
+      history.replaceState({}, "", url);
+    }
+  }
+
+  _ensureFrameLoaded(panel) {
+    const frame = panel.querySelector("turbo-frame");
+
+    if (!frame) return;
+    if (!frame.getAttribute("src")) {
+      const src = frame.dataset.src;
+      if (src) frame.setAttribute("src", src);
+    }
+
+    frame.reload();
+  }
+}

data/app/javascript/mat_views/controllers/timezone_controller.js

@@ -0,0 +1,16 @@
+/**
+ * Copyright Codevedas Inc. 2025-present
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import { Controller } from "@hotwired/stimulus";
+
+export default class extends Controller {
+  connect() {
+    const tz = Intl.DateTimeFormat().resolvedOptions().timeZone;
+    if (document.cookie.indexOf(`browser_tz=${tz}`) === -1) {
+      document.cookie = `browser_tz=${tz}; path=/`;
+    }
+  }
+}

data/app/javascript/mat_views/controllers/tooltip_controller.js

@@ -0,0 +1,328 @@
+/**
+ * Copyright Codevedas Inc. 2025-present
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import { Controller } from "@hotwired/stimulus";
+
+/**
+ * Usage:
+ * <button
+ *   data-controller="tooltip"
+ *   data-tooltip-text-value="Save"
+ *   data-tooltip-placement="bottom"
+ * >
+ *   Save
+ * </button>
+ */
+export default class extends Controller {
+  static values = {
+    text: String,
+    placement: { type: String, default: "top" },
+    delay: { type: Number, default: 120 },
+    hideDelay: { type: Number, default: 80 },
+    disabled: { type: Boolean, default: false },
+    gap: { type: Number, default: 8 },
+    margin: { type: Number, default: 8 },
+  };
+
+  // ──────────────────────────────────────────────
+  // Lifecycle
+  // ──────────────────────────────────────────────
+  connect() {
+    this.tooltipEl = this._ensureTooltipEl();
+    this.contentEl = this.tooltipEl.querySelector(".mv-tooltip__content");
+    this.element.classList.add("mv-cursor-pointer");
+    this._bindHandlers();
+    this._addListeners();
+  }
+
+  disconnect() {
+    this._clearAllTimers();
+    this._removeListeners();
+    this._restoreTitle();
+    this._clearDescribedBy();
+  }
+
+  // ──────────────────────────────────────────────
+  // Public actions
+  // ──────────────────────────────────────────────
+  show() {
+    if (this.disabledValue) return;
+    this._clearTimer("_hideTimer");
+    this._schedule("_showTimer", () => this._actuallyShow(), this.delayValue);
+  }
+
+  hide() {
+    this._clearTimer("_showTimer");
+    this._schedule(
+      "_hideTimer",
+      () => this._actuallyHide(),
+      this.hideDelayValue,
+    );
+  }
+
+  toggle() {
+    this._isVisible() ? this.hide() : this.show();
+  }
+
+  forceHide() {
+    this._clearAllTimers();
+    this._actuallyHide(true);
+  }
+
+  // ──────────────────────────────────────────────
+  // Internals: show/hide
+  // ──────────────────────────────────────────────
+  _actuallyShow() {
+    const text = this._resolveText();
+    if (!text) return;
+
+    // Remove native title to avoid default browser tooltip
+    this._saveAndRemoveTitle();
+
+    // Fill content
+    this.contentEl.textContent = text;
+
+    // Prep, place, show
+    this._prepareForMeasure();
+    const rect = this.element.getBoundingClientRect();
+    const ttRect = this.tooltipEl.getBoundingClientRect();
+    const placement = this._resolvePlacement();
+    const { x, y } = this._computePosition(
+      rect,
+      ttRect,
+      placement,
+      this.gapValue,
+      this.marginValue,
+    );
+
+    this._applyPlacementClass(placement);
+    this._setTransform(x, y);
+    this._setVisible(true);
+    this._setDescribedBy();
+  }
+
+  _actuallyHide(immediate = false) {
+    this._setVisible(false);
+
+    if (immediate) {
+      this._offscreen();
+    } else {
+      // Allow CSS transition to finish before moving offscreen (if not reopened)
+      setTimeout(() => {
+        if (!this._isVisible()) this._offscreen();
+      }, 150);
+    }
+
+    this._restoreTitle();
+    this._clearDescribedBy();
+  }
+
+  // ──────────────────────────────────────────────
+  // Internals: listeners and handlers
+  // ──────────────────────────────────────────────
+  _bindHandlers() {
+    this._onEnter = this.show.bind(this);
+    this._onLeave = this.hide.bind(this);
+    this._onFocus = this.show.bind(this);
+    this._onBlur = this.hide.bind(this);
+    this._onKey = (e) => {
+      if (e.key === "Escape") this.forceHide();
+    };
+    this._onTouch = (e) => {
+      e.preventDefault();
+      this.show();
+      this._clearTimer("_touchTimer");
+      this._touchTimer = setTimeout(() => this.hide(), 1500);
+    };
+  }
+
+  _addListeners() {
+    const el = this.element;
+    el.addEventListener("mouseenter", this._onEnter);
+    el.addEventListener("mouseleave", this._onLeave);
+    el.addEventListener("focus", this._onFocus);
+    el.addEventListener("blur", this._onBlur);
+    el.addEventListener("keydown", this._onKey);
+    // preventDefault() requires passive: false
+    el.addEventListener("touchstart", this._onTouch, { passive: false });
+  }
+
+  _removeListeners() {
+    const el = this.element;
+    if (!el) return;
+    el.removeEventListener("mouseenter", this._onEnter);
+    el.removeEventListener("mouseleave", this._onLeave);
+    el.removeEventListener("focus", this._onFocus);
+    el.removeEventListener("blur", this._onBlur);
+    el.removeEventListener("keydown", this._onKey);
+    el.removeEventListener("touchstart", this._onTouch, { passive: false });
+  }
+
+  // ──────────────────────────────────────────────
+  // Internals: DOM helpers
+  // ──────────────────────────────────────────────
+  _ensureTooltipEl() {
+    let el = document.getElementById("mv-tooltip");
+    if (el) return el;
+
+    el = document.createElement("div");
+    el.id = "mv-tooltip";
+    el.setAttribute("role", "tooltip");
+    el.className = "mv-tooltip";
+    Object.assign(el.style, {
+      position: "fixed",
+      top: "0",
+      left: "0",
+      pointerEvents: "none",
+      opacity: "0",
+      transform: "translate(-9999px,-9999px)",
+    });
+    el.innerHTML =
+      '<div class="mv-tooltip__content"></div><div class="mv-tooltip__arrow" data-arrow></div>';
+    document.body.appendChild(el);
+    return el;
+  }
+
+  _prepareForMeasure() {
+    this.tooltipEl.style.opacity = "0";
+    this._offscreen();
+    this._removeAllPlacementClasses();
+  }
+
+  _applyPlacementClass(placement) {
+    this._removeAllPlacementClasses();
+    this.tooltipEl.classList.add(`mv-tooltip--${placement}`);
+  }
+
+  _removeAllPlacementClasses() {
+    this.tooltipEl.classList.remove(
+      "mv-tooltip--top",
+      "mv-tooltip--right",
+      "mv-tooltip--bottom",
+      "mv-tooltip--left",
+    );
+  }
+
+  _setTransform(x, y) {
+    this.tooltipEl.style.transform = `translate(${x}px, ${y}px)`;
+  }
+
+  _offscreen() {
+    this.tooltipEl.style.transform = "translate(-9999px,-9999px)";
+  }
+
+  _setVisible(visible) {
+    if (visible) {
+      this.tooltipEl.style.opacity = "1";
+      this.tooltipEl.setAttribute("data-show", "true");
+    } else {
+      this.tooltipEl.removeAttribute("data-show");
+      this.tooltipEl.style.opacity = "0";
+    }
+  }
+
+  _setDescribedBy() {
+    this.element.setAttribute("aria-describedby", "mv-tooltip");
+  }
+
+  _clearDescribedBy() {
+    this.element.removeAttribute("aria-describedby");
+  }
+
+  // ──────────────────────────────────────────────
+  // Internals: data/text/title
+  // ──────────────────────────────────────────────
+  _resolveText() {
+    return (
+      this.textValue ||
+      this.element.getAttribute("aria-label") ||
+      this.element.getAttribute("title")
+    );
+  }
+
+  _resolvePlacement() {
+    return (
+      this.element.getAttribute("data-tooltip-placement") || this.placementValue
+    );
+  }
+
+  _saveAndRemoveTitle() {
+    if (this.element.hasAttribute("title")) {
+      this._savedTitle = this.element.getAttribute("title");
+      this.element.removeAttribute("title");
+    }
+  }
+
+  _restoreTitle() {
+    if (this._savedTitle) {
+      this.element.setAttribute("title", this._savedTitle);
+      this._savedTitle = null;
+    }
+  }
+
+  // ──────────────────────────────────────────────
+  // Internals: timers & state helpers
+  // ──────────────────────────────────────────────
+  _schedule(name, fn, ms) {
+    this._clearTimer(name);
+    this[name] = setTimeout(fn, ms);
+  }
+
+  _clearTimer(name) {
+    if (this[name]) {
+      clearTimeout(this[name]);
+      this[name] = null;
+    }
+  }
+
+  _clearAllTimers() {
+    this._clearTimer("_showTimer");
+    this._clearTimer("_hideTimer");
+    this._clearTimer("_touchTimer");
+  }
+
+  _isVisible() {
+    return this.tooltipEl?.getAttribute("data-show") === "true";
+  }
+
+  // ──────────────────────────────────────────────
+  // Geometry
+  // ──────────────────────────────────────────────
+  _computePosition(targetRect, ttRect, placement, gap, margin) {
+    const coords = this._coordsFor(placement, targetRect, ttRect, gap);
+    const x = this._clampX(coords.x, ttRect.width, margin);
+    const y = this._clampY(coords.y, ttRect.height, margin);
+    return { x: Math.round(x), y: Math.round(y) };
+  }
+
+  _coordsFor(placement, r, tt, gap) {
+    switch (placement) {
+      case "top":
+        return {
+          x: r.left + (r.width - tt.width) / 2,
+          y: r.top - tt.height - gap,
+        };
+      case "bottom":
+        return { x: r.left + (r.width - tt.width) / 2, y: r.bottom + gap };
+      case "left":
+        return {
+          x: r.left - tt.width - gap,
+          y: r.top + (r.height - tt.height) / 2,
+        };
+      case "right":
+      default:
+        return { x: r.right + gap, y: r.top + (r.height - tt.height) / 2 };
+    }
+  }
+
+  _clampX(x, width, margin) {
+    return Math.max(margin, Math.min(x, window.innerWidth - width - margin));
+  }
+
+  _clampY(y, height, margin) {
+    return Math.max(margin, Math.min(y, window.innerHeight - height - margin));
+  }
+}

data/app/javascript/mat_views/controllers/turbo_frame_lifecycle_controller.js

@@ -0,0 +1,49 @@
+/**
+ * Copyright Codevedas Inc. 2025-present
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import { Controller } from "@hotwired/stimulus";
+
+export default class extends Controller {
+  connect() {
+    this.elements = document.querySelectorAll("turbo-frame");
+    this.elements.forEach((el) => {
+      el.addEventListener("turbo:before-fetch-request", this._addBusyAttribute);
+      el.addEventListener("turbo:frame-load", this._removeBusyAttribute);
+      el.addEventListener(
+        "turbo:fetch-request-error",
+        this._removeBusyAttribute,
+      );
+    });
+  }
+
+  disconnect() {
+    this.elements.forEach((el) => {
+      el.removeEventListener(
+        "turbo:before-fetch-request",
+        this._addBusyAttribute,
+      );
+      el.removeEventListener("turbo:frame-load", this._removeBusyAttribute);
+      el.removeEventListener(
+        "turbo:fetch-request-error",
+        this._removeBusyAttribute,
+      );
+    });
+  }
+
+  _addBusyAttribute = (event) => {
+    document.body.setAttribute("aria-busy", "true");
+    document.body.setAttribute("busy", "");
+    event.target.setAttribute("aria-busy", "true");
+    event.target.setAttribute("busy", "");
+  };
+
+  _removeBusyAttribute = (event) => {
+    document.body.removeAttribute("aria-busy");
+    document.body.removeAttribute("busy");
+    event.target.removeAttribute("aria-busy");
+    event.target.removeAttribute("busy");
+  };
+}

data/app/jobs/mat_views/application_job.rb

@@ -8,7 +8,7 @@
 ##
 # Top-level namespace for the mat_views engine.
 #
-# All classes, modules, and services for materialized view management
+# All classes, modules, and services for materialised view management
 # are defined under this namespace.
 #
 # @example Accessing a job
@@ -29,7 +29,7 @@ module MatViews
   #
   # @example Defining a custom job
   #   class MyCustomJob < MatViews::ApplicationJob
-  #     def perform(definition_id)
+  #     def perform(mat_view_definition_id)
   #       # custom logic here
   #     end
   #   end

data/app/jobs/mat_views/create_view_job.rb

@@ -9,7 +9,7 @@
 # Top-level namespace for the mat_views engine.
 module MatViews
   ##
-  # ActiveJob that handles *creation* of PostgreSQL materialized views for a
+  # ActiveJob that handles *creation* of PostgreSQL materialised views for a
   # given {MatViews::MatViewDefinition}.
   #
   # The job:
@@ -17,7 +17,7 @@ module MatViews
   # 2. Looks up the target {MatViews::MatViewDefinition}.
   # 3. Starts a {MatViews::MatViewRun} row to track lifecycle/timing, with `operation: :create`.
   # 4. Executes {MatViews::Services::CreateView}.
-  # 5. Finalizes the run with success/failure, duration, and payload meta.
+  # 5. Finalizes the run with success/failure, duration, and meta.
   #
   # @see MatViews::Services::CreateView
   # @see MatViews::MatViewDefinition
@@ -40,28 +40,29 @@ module MatViews
     queue_as { MatViews.configuration.job_queue || :default }
 
     ##
-    # Perform the create job for the given materialized view definition.
+    # Perform the create job for the given materialised view definition.
     #
     # @api public
     #
-    # @param definition_id [Integer, String] ID of {MatViews::MatViewDefinition}.
+    # @param mat_view_definition_id [Integer, String] ID of {MatViews::MatViewDefinition}.
     # @param force_arg [Boolean, Hash, nil] Optional flag or hash (`{ force: true }`)
     # @param row_count_strategy_arg [:Symbol, String] One of: `:estimated`, `:exact`, `:none` or `nil`.
     #
     # @return [Hash] Serialized {MatViews::ServiceResponse#to_h}:
     #   - `:status` [Symbol]
-    #   - `:payload` [Hash]
     #   - `:error` [String, nil]
     #   - `:duration_ms` [Integer]
     #   - `:meta` [Hash]
     #
     # @raise [StandardError] Re-raised on unexpected failure after marking the run failed.
     #
-    def perform(definition_id, force_arg = nil, row_count_strategy_arg = nil)
-      definition = MatViews::MatViewDefinition.find(definition_id)
+    def perform(mat_view_definition_id, force_arg = nil, row_count_strategy_arg = nil)
+      definition = MatViews::MatViewDefinition.find(mat_view_definition_id)
 
       record_run(definition, :create) do
-        MatViews::Services::CreateView.new(definition, force: force?(force_arg), row_count_strategy: normalize_strategy(row_count_strategy_arg)).run
+        MatViews::Services::CreateView.new(definition,
+                                           force: force?(force_arg),
+                                           row_count_strategy: normalize_strategy(row_count_strategy_arg)).call
       end
     end
 

data/app/jobs/mat_views/delete_view_job.rb

@@ -9,7 +9,7 @@
 # Top-level namespace for the mat_views engine.
 module MatViews
   ##
-  # ActiveJob that handles *deletion* of PostgreSQL materialized views via
+  # ActiveJob that handles *deletion* of PostgreSQL materialised views via
   # {MatViews::Services::DeleteView}.
   #
   # This job mirrors {MatViews::CreateViewJob} and {MatViews::RefreshViewJob}:
@@ -39,28 +39,28 @@ module MatViews
     queue_as { MatViews.configuration.job_queue || :default }
 
     ##
-    # Perform the job for the given materialized view definition.
+    # Perform the job for the given materialised view definition.
     #
     # @api public
     #
-    # @param definition_id [Integer, String] ID of {MatViews::MatViewDefinition}.
+    # @param mat_view_definition_id [Integer, String] ID of {MatViews::MatViewDefinition}.
     # @param cascade_arg [Boolean, String, Integer, Hash, nil] Cascade option.
     # @param row_count_strategy_arg [:Symbol, String] One of: `:estimated`, `:exact`, `:none` or `nil`.
     #
     # @return [Hash] Serialized {MatViews::ServiceResponse#to_h}:
     #   - `:status` [Symbol]
-    #   - `:payload` [Hash]
     #   - `:error` [String, nil]
     #   - `:duration_ms` [Integer]
     #   - `:meta` [Hash]
     #
     # @raise [StandardError] Re-raised on unexpected failure after marking the run failed.
     #
-    def perform(definition_id, cascade_arg = nil, row_count_strategy_arg = nil)
-      definition = MatViews::MatViewDefinition.find(definition_id)
+    def perform(mat_view_definition_id, cascade_arg = nil, row_count_strategy_arg = nil)
+      definition = MatViews::MatViewDefinition.find(mat_view_definition_id)
       record_run(definition, :drop) do
-        MatViews::Services::DeleteView.new(definition, cascade: cascade?(cascade_arg),
-                                                       row_count_strategy: normalize_strategy(row_count_strategy_arg)).run
+        MatViews::Services::DeleteView.new(definition,
+                                           cascade: cascade?(cascade_arg),
+                                           row_count_strategy: normalize_strategy(row_count_strategy_arg)).call
       end
     end
 

data/app/jobs/mat_views/refresh_view_job.rb

@@ -23,9 +23,9 @@ module MatViews
   # - otherwise      → {MatViews::Services::RegularRefresh}
   #
   # Row count reporting can be controlled via `row_count_strategy`:
-  # - `:estimated` (default) — fast, approximate via reltuples
-  # - `:exact` — accurate `COUNT(*)`
-  # - `nil` — skip counting
+  # - `:estimated` (default) - fast, approximate via reltuples
+  # - `:exact` - accurate `COUNT(*)`
+  # - `nil` - skip counting
   #
   # @see MatViews::MatViewDefinition
   # @see MatViews::MatViewRun
@@ -48,26 +48,25 @@ module MatViews
     queue_as { MatViews.configuration.job_queue || :default }
 
     ##
-    # Perform the refresh job for the given materialized view definition.
+    # Perform the refresh job for the given materialised view definition.
     #
     # @api public
     #
-    # @param definition_id [Integer, String] ID of {MatViews::MatViewDefinition}.
+    # @param mat_view_definition_id [Integer, String] ID of {MatViews::MatViewDefinition}.
     # @param row_count_strategy_arg [:Symbol, String] One of: `:estimated`, `:exact`, `:none` or `nil`.
     #
     # @return [Hash] Serialized {MatViews::ServiceResponse#to_h}:
     #   - `:status` [Symbol]
-    #   - `:payload` [Hash]
     #   - `:error` [String, nil]
     #   - `:duration_ms` [Integer]
     #   - `:meta` [Hash]
     #
     # @raise [StandardError] Re-raised on unexpected failure after marking the run failed.
     #
-    def perform(definition_id, row_count_strategy_arg = nil)
-      definition = MatViews::MatViewDefinition.find(definition_id)
+    def perform(mat_view_definition_id, row_count_strategy_arg = nil)
+      definition = MatViews::MatViewDefinition.find(mat_view_definition_id)
       record_run(definition, :refresh) do
-        service(definition).new(definition, row_count_strategy: normalize_strategy(row_count_strategy_arg)).run
+        service(definition).new(definition, row_count_strategy: normalize_strategy(row_count_strategy_arg)).call
       end
     end