appquery 0.7.0.rc3 → 0.7.0.rc4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b8cd0e15eb5369cdc045b147a86ad399c46d3db98788466ca97c34aad3ffdbff
-  data.tar.gz: '09bc151be68fb86f52be75f0cb39c8574230f36df041106ca6ee360f8952c08b'
+  metadata.gz: 7a14a392efa76c538933b7e3a41ded16c0b424411401fe6bfbba25e04fdd5d58
+  data.tar.gz: '090b6b2dc6fc90bad886bcf204112e96375bac828aa940d275deed236a74956e'
 SHA512:
-  metadata.gz: 5bca51f56f82a9e89a9d3e958f380845841c9da122e748cc89e0c67d55397d63d529f511f5ffe255ce905c0895d0a911f9df9e943a452d1ef8c8a83240d727c4
-  data.tar.gz: 29e39bca885b03ef0e54a6c68e803b8819e24baedb85e7dcd0b1c6a13c9496b97fe9cce98555653e9eeebb6a9cbb82188ab3d078243f0f8d3bfcdedc2797633a
+  metadata.gz: ba9661f71020f4d1925f7ed059831017b0f4348049a3146be3a5a94ba78199006f99ebde72a38f6da31a172a677402663cbacdbfab03f72ec837fe29a5ea9162
+  data.tar.gz: e603c2c8b6cdb2bed56bdfc52ee568d5065c30e291e91c154dd4e9dccc35068493dde970682515f9566d8a7e313f3ac9dfbf6fd401af5a01089d29fbb393cd6b

data/.yard/templates/default/fulldoc/html/js/app.js

@@ -0,0 +1,399 @@
+window.__app = function () {
+  var localStorage = {},
+    sessionStorage = {};
+  try {
+    localStorage = window.localStorage;
+  } catch (e) {}
+  try {
+    sessionStorage = window.sessionStorage;
+  } catch (e) {}
+
+  function createSourceLinks() {
+    $(".method_details_list .source_code").before(
+      "<span class='showSource'>[<a href='#' class='toggleSource'>View source</a>]</span>"
+    );
+    $(".toggleSource").toggle(
+      function () {
+        $(this).parent().nextAll(".source_code").slideDown(100);
+        $(this).text("Hide source");
+      },
+      function () {
+        $(this).parent().nextAll(".source_code").slideUp(100);
+        $(this).text("View source");
+      }
+    );
+  }
+
+  function createDefineLinks() {
+    var tHeight = 0;
+    $(".defines").after(" <a href='#' class='toggleDefines'>more...</a>");
+    $(".toggleDefines").toggle(
+      function () {
+        tHeight = $(this).parent().prev().height();
+        $(this).prev().css("display", "inline");
+        $(this).parent().prev().height($(this).parent().height());
+        $(this).text("(less)");
+      },
+      function () {
+        $(this).prev().hide();
+        $(this).parent().prev().height(tHeight);
+        $(this).text("more...");
+      }
+    );
+  }
+
+  function createFullTreeLinks() {
+    var tHeight = 0;
+    $(".inheritanceTree").toggle(
+      function () {
+        tHeight = $(this).parent().prev().height();
+        $(this).parent().toggleClass("showAll");
+        $(this).text("(hide)");
+        $(this).parent().prev().height($(this).parent().height());
+      },
+      function () {
+        $(this).parent().toggleClass("showAll");
+        $(this).parent().prev().height(tHeight);
+        $(this).text("show all");
+      }
+    );
+  }
+
+  function searchFrameButtons() {
+    $(".full_list_link").click(function () {
+      toggleSearchFrame(this, $(this).attr("href"));
+      return false;
+    });
+    window.addEventListener("message", function (e) {
+      if (e.data === "navEscape") {
+        $("#nav").slideUp(100);
+        $("#search a").removeClass("active inactive");
+        $(window).focus();
+      }
+    });
+
+    $(window).resize(function () {
+      if ($("#search:visible").length === 0) {
+        $("#nav").removeAttr("style");
+        $("#search a").removeClass("active inactive");
+        $(window).focus();
+      }
+    });
+  }
+
+  function toggleSearchFrame(id, link) {
+    var frame = $("#nav");
+    $("#search a").removeClass("active").addClass("inactive");
+    if (frame.attr("src") === link && frame.css("display") !== "none") {
+      frame.slideUp(100);
+      $("#search a").removeClass("active inactive");
+    } else {
+      $(id).addClass("active").removeClass("inactive");
+      if (frame.attr("src") !== link) frame.attr("src", link);
+      frame.slideDown(100);
+    }
+  }
+
+  function linkSummaries() {
+    $(".summary_signature").click(function () {
+      document.location = $(this).find("a").attr("href");
+    });
+  }
+
+  function summaryToggle() {
+    $(".summary_toggle").click(function (e) {
+      e.preventDefault();
+      localStorage.summaryCollapsed = $(this).text();
+      $(".summary_toggle").each(function () {
+        $(this).text($(this).text() == "collapse" ? "expand" : "collapse");
+        var next = $(this).parent().parent().nextAll("ul.summary").first();
+        if (next.hasClass("compact")) {
+          next.toggle();
+          next.nextAll("ul.summary").first().toggle();
+        } else if (next.hasClass("summary")) {
+          var list = $('<ul class="summary compact" />');
+          list.html(next.html());
+          list.find(".summary_desc, .note").remove();
+          list.find("a").each(function () {
+            $(this).html($(this).find("strong").html());
+            $(this).parent().html($(this)[0].outerHTML);
+          });
+          next.before(list);
+          next.toggle();
+        }
+      });
+      return false;
+    });
+    if (localStorage.summaryCollapsed == "collapse") {
+      $(".summary_toggle").first().click();
+    } else {
+      localStorage.summaryCollapsed = "expand";
+    }
+  }
+
+  function constantSummaryToggle() {
+    $(".constants_summary_toggle").click(function (e) {
+      e.preventDefault();
+      localStorage.summaryCollapsed = $(this).text();
+      $(".constants_summary_toggle").each(function () {
+        $(this).text($(this).text() == "collapse" ? "expand" : "collapse");
+        var next = $(this).parent().parent().nextAll("dl.constants").first();
+        if (next.hasClass("compact")) {
+          next.toggle();
+          next.nextAll("dl.constants").first().toggle();
+        } else if (next.hasClass("constants")) {
+          var list = $('<dl class="constants compact" />');
+          list.html(next.html());
+          list.find("dt").each(function () {
+            $(this).addClass("summary_signature");
+            $(this).text($(this).text().split("=")[0]);
+            if ($(this).has(".deprecated").length) {
+              $(this).addClass("deprecated");
+            }
+          });
+          // Add the value of the constant as "Tooltip" to the summary object
+          list.find("pre.code").each(function () {
+            var dt_element = $(this).parent().prev();
+            var tooltip = $(this).text();
+            if (dt_element.hasClass("deprecated")) {
+              tooltip = "Deprecated. " + tooltip;
+            }
+            dt_element.attr("title", tooltip);
+          });
+          list.find(".docstring, .tags, dd").remove();
+          next.before(list);
+          next.toggle();
+        }
+      });
+      return false;
+    });
+    if (localStorage.summaryCollapsed == "collapse") {
+      $(".constants_summary_toggle").first().click();
+    } else {
+      localStorage.summaryCollapsed = "expand";
+    }
+  }
+
+  function generateTOC() {
+    if ($("#filecontents").length === 0) return;
+    var _toc = $('<ol class="top"></ol>');
+    var show = false;
+    var toc = _toc;
+    var counter = 0;
+    var tags = ["h2", "h3", "h4", "h5", "h6"];
+    var i;
+    var curli;
+    if ($("#filecontents h1").length > 1) tags.unshift("h1");
+    for (i = 0; i < tags.length; i++) {
+      tags[i] = "#filecontents " + tags[i];
+    }
+    var lastTag = parseInt(tags[0][1], 10);
+    $(tags.join(", ")).each(function () {
+      if ($(this).parents(".method_details .docstring").length != 0) return;
+      if (this.id == "filecontents") return;
+      show = true;
+      var thisTag = parseInt(this.tagName[1], 10);
+      if (this.id.length === 0) {
+        var proposedId = $(this).attr("toc-id");
+        if (typeof proposedId != "undefined") this.id = proposedId;
+        else {
+          var proposedId = $(this)
+            .text()
+            .replace(/[^a-z0-9-]/gi, "_");
+          if ($("#" + proposedId).length > 0) {
+            proposedId += counter;
+            counter++;
+          }
+          this.id = proposedId;
+        }
+      }
+      if (thisTag > lastTag) {
+        for (i = 0; i < thisTag - lastTag; i++) {
+          if (typeof curli == "undefined") {
+            curli = $("<li/>");
+            toc.append(curli);
+          }
+          toc = $("<ol/>");
+          curli.append(toc);
+          curli = undefined;
+        }
+      }
+      if (thisTag < lastTag) {
+        for (i = 0; i < lastTag - thisTag; i++) {
+          toc = toc.parent();
+          toc = toc.parent();
+        }
+      }
+      var title = $(this).attr("toc-title");
+      if (typeof title == "undefined") title = $(this).text();
+      curli = $('<li><a href="#' + this.id + '">' + title + "</a></li>");
+      toc.append(curli);
+      lastTag = thisTag;
+    });
+    if (!show) return;
+    html =
+      '<div id="toc"><p class="title hide_toc"><a href="#"><strong>Table of Contents</strong></a></p></div>';
+    $("#content").prepend(html);
+    $("#toc").append(_toc);
+    $("#toc .hide_toc").toggle(
+      function () {
+        $("#toc .top").slideUp("fast");
+        $("#toc").toggleClass("hidden");
+        $("#toc .title small").toggle();
+      },
+      function () {
+        $("#toc .top").slideDown("fast");
+        $("#toc").toggleClass("hidden");
+        $("#toc .title small").toggle();
+      }
+    );
+  }
+
+  function navResizer() {
+    const resizer = document.getElementById("resizer");
+    resizer.addEventListener(
+      "pointerdown",
+      function (e) {
+        resizer.setPointerCapture(e.pointerId);
+        e.preventDefault();
+        e.stopPropagation();
+      },
+      false
+    );
+    resizer.addEventListener(
+      "pointerup",
+      function (e) {
+        resizer.releasePointerCapture(e.pointerId);
+        e.preventDefault();
+        e.stopPropagation();
+      },
+      false
+    );
+    resizer.addEventListener(
+      "pointermove",
+      function (e) {
+        if ((e.buttons & 1) === 0) {
+          return;
+        }
+
+        sessionStorage.navWidth = e.pageX.toString();
+        $(".nav_wrap").css("width", Math.max(200, e.pageX));
+        e.preventDefault();
+        e.stopPropagation();
+      },
+      false
+    );
+
+    if (sessionStorage.navWidth) {
+      $(".nav_wrap").css(
+        "width",
+        Math.max(200, parseInt(sessionStorage.navWidth, 10))
+      );
+    }
+  }
+
+  function navExpander() {
+    if (typeof pathId === "undefined") return;
+    var done = false,
+      timer = setTimeout(postMessage, 500);
+    function postMessage() {
+      if (done) return;
+      clearTimeout(timer);
+      var opts = { action: "expand", path: pathId };
+      document.getElementById("nav").contentWindow.postMessage(opts, "*");
+      done = true;
+    }
+  }
+
+  function mainFocus() {
+    var hash = window.location.hash;
+    if (hash !== "" && $(hash)[0]) {
+      $(hash)[0].scrollIntoView();
+    }
+
+    setTimeout(function () {
+      $("#main").focus();
+    }, 10);
+  }
+
+  function navigationChange() {
+    // This works around the broken anchor navigation with the YARD template.
+    window.onpopstate = function () {
+      var hash = window.location.hash;
+      if (hash !== "" && $(hash)[0]) {
+        $(hash)[0].scrollIntoView();
+      }
+    };
+  }
+
+  $(document).ready(function () {
+    navResizer();
+    navExpander();
+    createSourceLinks();
+    createDefineLinks();
+    createFullTreeLinks();
+    searchFrameButtons();
+    linkSummaries();
+    summaryToggle();
+    constantSummaryToggle();
+    generateTOC();
+    mainFocus();
+    navigationChange();
+  });
+};
+window.__app();
+
+window.addEventListener(
+  "message",
+  async (e) => {
+    if (e.data.action === "navigate") {
+      // Fix: resolve URL relative to the iframe's base (root), not current page
+      const nav = document.getElementById("nav");
+      const baseUrl = new URL(nav.src, window.location.href).href.replace(/[^/]*$/, '');
+      const absoluteUrl = new URL(e.data.url, baseUrl).href;
+      const response = await fetch(absoluteUrl);
+      const text = await response.text();
+      const parser = new DOMParser();
+      const doc = parser.parseFromString(text, "text/html");
+
+      const classListLink =
+        document.getElementById("class_list_link").classList;
+
+      const content = doc.querySelector("#main").innerHTML;
+      document.querySelector("#main").innerHTML = content;
+      document.title = doc.head.querySelector("title").innerText;
+      document.head.querySelectorAll("script").forEach((script) => {
+        if (
+          !script.type ||
+          (script.type.includes("text/javascript") && !script.src)
+        ) {
+          script.remove();
+        }
+      });
+
+      doc.head.querySelectorAll("script").forEach((script) => {
+        if (
+          !script.type ||
+          (script.type.includes("text/javascript") && !script.src)
+        ) {
+          const newScript = document.createElement("script");
+          newScript.type = "text/javascript";
+          newScript.textContent = script.textContent;
+          document.head.appendChild(newScript);
+        }
+      });
+
+      window.__app();
+
+      document.getElementById("class_list_link").classList = classListLink;
+
+      const url = new URL(e.data.url, "https://localhost");
+      const hash = decodeURIComponent(url.hash ?? "");
+      if (hash) {
+        document.getElementById(hash.substring(1)).scrollIntoView();
+      }
+      history.pushState({}, document.title, absoluteUrl);
+    }
+  },
+  false
+);

data/lib/app_query/base_query.rb

@@ -9,42 +9,46 @@ module AppQuery
   # BaseQuery provides a structured way to work with SQL queries compared to
   # using `AppQuery[:my_query]` directly.
   #
+  # @see Paginatable Middleware for pagination support
+  # @see Mappable Middleware for mapping results to objects
+  #
   # ## Benefits over AppQuery[:my_query]
   #
   # ### 1. Explicit parameter declaration
   # Declare required binds and vars upfront with defaults:
   #
-  #   class ArticlesQuery < AppQuery::BaseQuery
-  #     bind :author_id              # required
-  #     bind :status, default: nil   # optional
-  #     var :order_by, default: "created_at DESC"
-  #   end
+  #     class ArticlesQuery < AppQuery::BaseQuery
+  #       bind :author_id              # required
+  #       bind :status, default: nil   # optional
+  #       var :order_by, default: "created_at DESC"
+  #     end
   #
   # ### 2. Unknown parameter validation
   # Raises ArgumentError for typos or unknown parameters:
   #
-  #   ArticlesQuery.new(athor_id: 1)  # => ArgumentError: Unknown param(s): athor_id
+  #     ArticlesQuery.new(athor_id: 1)
+  #     # => ArgumentError: Unknown param(s): athor_id
   #
   # ### 3. Self-documenting queries
   # Query classes show exactly what parameters are available:
   #
-  #   ArticlesQuery.binds  # => {author_id: {default: nil}, status: {default: nil}}
-  #   ArticlesQuery.vars   # => {order_by: {default: "created_at DESC"}}
+  #     ArticlesQuery.binds  # => {author_id: {default: nil}, ...}
+  #     ArticlesQuery.vars   # => {order_by: {default: "created_at DESC"}}
   #
   # ### 4. Middleware support
   # Include concerns to add functionality:
   #
-  #   class ApplicationQuery < AppQuery::BaseQuery
-  #     include AppQuery::Paginatable
-  #     include AppQuery::Mappable
-  #   end
+  #     class ApplicationQuery < AppQuery::BaseQuery
+  #       include AppQuery::Paginatable
+  #       include AppQuery::Mappable
+  #     end
   #
   # ### 5. Casts
   # Define casts for columns:
   #
-  #   class ApplicationQuery < AppQuery::BaseQuery
-  #     cast metadata: :json
-  #   end
+  #     class ApplicationQuery < AppQuery::BaseQuery
+  #       cast metadata: :json
+  #     end
   #
   # ## Parameter types
   #
@@ -57,15 +61,13 @@ module AppQuery
   # - `ArticlesQuery` -> `articles.sql.erb`
   # - `Reports::MonthlyQuery` -> `reports/monthly.sql.erb`
   #
-  # ## Example
-  #
-  #   # app/queries/articles.sql.erb
+  # @example SQL template (app/queries/articles.sql.erb)
   #   SELECT * FROM articles
   #   WHERE author_id = :author_id
   #   <% if @status %>AND status = :status<% end %>
   #   ORDER BY <%= @order_by %>
   #
-  #   # app/queries/articles_query.rb
+  # @example Query class (app/queries/articles_query.rb)
   #   class ArticlesQuery < AppQuery::BaseQuery
   #     bind :author_id
   #     bind :status, default: nil
@@ -73,7 +75,7 @@ module AppQuery
   #     cast published_at: :datetime
   #   end
   #
-  #   # Usage
+  # @example Usage
   #   ArticlesQuery.new(author_id: 1).entries
   #   ArticlesQuery.new(author_id: 1, status: "draft", order_by: "title").first
   #

data/lib/app_query/mappable.rb

@@ -3,10 +3,19 @@
 require "active_support/concern"
 
 module AppQuery
-  # Maps query results to Ruby objects (e.g., Data classes, Structs).
+  # Middleware concern that maps query results to Ruby objects in {BaseQuery} subclasses.
   #
-  # By default, looks for an `Item` constant in the query class.
-  # Use `map_to` to specify a different class.
+  # Include this module to automatically convert result hashes into typed objects
+  # like +Data+ classes or +Struct+s.
+  #
+  # By default, looks for an +Item+ constant in the query class.
+  # Use +map_to+ to specify a different class.
+  #
+  # @note This is a {BaseQuery} middleware. Include it in classes that inherit
+  #   from {BaseQuery} to transform hash results into typed objects.
+  #
+  # @see BaseQuery Base class for query objects
+  # @see Paginatable Another middleware for pagination support
   #
   # @example With default Item class
   #   class ArticlesQuery < ApplicationQuery
@@ -31,6 +40,18 @@ module AppQuery
   # @example Skip mapping with raw
   #   articles = ArticlesQuery.new.raw.entries
   #   articles.first  # => {"title" => "Hello", "url" => "..."}
+  #
+  # @example Combining with Paginatable
+  #   class ArticlesQuery < ApplicationQuery
+  #     include AppQuery::Paginatable
+  #     include AppQuery::Mappable
+  #
+  #     class Item < Data.define(:title, :url)
+  #     end
+  #   end
+  #
+  #   # Results are paginated AND mapped to Item objects
+  #   ArticlesQuery.new.paginate(page: 1).entries.first.title
   module Mappable
     extend ActiveSupport::Concern
 

data/lib/app_query/paginatable.rb

@@ -3,13 +3,20 @@
 require "active_support/concern"
 
 module AppQuery
-  # Adds pagination support to query classes.
+  # Middleware concern that adds pagination support to {BaseQuery} subclasses.
+  #
+  # Include this module in your query class to enable pagination with
+  # Kaminari-compatible result objects.
   #
   # Provides two modes:
   # - **With count**: Full pagination with page numbers (uses COUNT query)
   # - **Without count**: Simple prev/next for large datasets (uses limit+1 trick)
   #
-  # Compatible with Kaminari view helpers.
+  # @note This is a {BaseQuery} middleware. Include it in classes that inherit
+  #   from {BaseQuery} and use the +paginate+ ERB helper in your SQL template.
+  #
+  # @see BaseQuery Base class for query objects
+  # @see Mappable Another middleware for mapping results to objects
   #
   # @example Basic usage
   #   class ApplicationQuery < AppQuery::BaseQuery
@@ -29,6 +36,12 @@ module AppQuery
   #   # Without count (large datasets)
   #   articles = ArticlesQuery.new.paginate(page: 1, without_count: true).entries
   #   articles.next_page    # => 2 (or nil if last page)
+  #
+  # @example SQL template with pagination
+  #   -- app/queries/articles.sql
+  #   SELECT * FROM articles
+  #   ORDER BY published_on DESC
+  #   <%= paginate(page: page, per_page: per_page) %>
   module Paginatable
     extend ActiveSupport::Concern
 

data/lib/app_query/version.rb

@@ -3,5 +3,5 @@
 module AppQuery
   # This should just contain the .dev of the upcoming version.
   # When doing the actual release, CI will write the tag here before pushing the gem.
-  VERSION = "0.7.0.rc3"
+  VERSION = "0.7.0.rc4"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: appquery
 version: !ruby/object:Gem::Version
-  version: 0.7.0.rc3
+  version: 0.7.0.rc4
 platform: ruby
 authors:
 - Gert Goet
@@ -44,6 +44,7 @@ files:
 - ".rspec"
 - ".standard.yml"
 - ".yard/templates/default/fulldoc/html/css/dark.css"
+- ".yard/templates/default/fulldoc/html/js/app.js"
 - ".yard/templates/default/fulldoc/html/setup.rb"
 - ".yard/templates/default/layout/html/setup.rb"
 - ".yardopts"