repolho 0.1.8 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fd3898009be42319daf8afaa54b0a064b8952d107a8cef3ad0d3d5692c2d17ad
-  data.tar.gz: dabe5fac8684e094140bf276d14cddfef3c3ba03693b66049ea5d2a68de30fd5
+  metadata.gz: 8f4aac6b18333e8a6d790ad2e130f681419393b0771b98b35368cc34bb11ec7f
+  data.tar.gz: 327ddea1d9ecf3bcae6897eed05daba40fc6c1897e5390d0feb4552c19decbc3
 SHA512:
-  metadata.gz: d89cf51d6df90425a07e33e666f3a6e63434e0ec7085b1701d10777e371cef6149e43d16b408f809360211ea934f1e514037747dcdede233938f752146e11661
-  data.tar.gz: 3f9ec0ebbeaa07dc650c05f6a7ed488d289febc9712c5ac96547a4cc6875a63093b254c1f58ed4bbf723263eb43b6f459e75f3a923b8f7803b2c3921e6bcb510
+  metadata.gz: d9f15437ff86ee242205fdd24dd52f994a9da1c2dcd0d83814a5ef6b6ca04c69927acc4a014d9c3946686dd2063e31c16b10f246107cfbad95b9d7d8f13eb00a
+  data.tar.gz: 4cf688c47fc6658d4c112246f1073f10bad0db3dfa10b85edf47151dd3379c0e002a12a6fdb45ce7cf90bcdc1cff59bd102f8d6f048a4ee32e63021384a9af36

checksums.yaml.gz.sig

@@ -1,4 +1,3 @@
-S�Jtg��+Ը�,
R��	�|;ez4`jp���}����D7��H!
-���$�ۚ5�*�P�p-O�߼�ֺ4-���9�
��#�5���H�Cp�ܰ;����o�-�8W	;�׊wLY,)g���
-��,S����3��q�鞟g�(� �bq���7��,@|��v��>��M!��
�(i:����VՈ��t
-R@���<��;σZ��Ϧ	Yp��}�Zv12ؽV�5.�\0�iH����܎&q(��<���Zڹ�r�(܌���7t�uQ��B��@��w���� "Y����x����ކ�"��2�l������Oۅ
����d�gk��)V�l�qK���B:�G�w>D���)��t����򪎵tm��be�fL
+H�2�q�=V���8�Vό��_�Q��ˢ�y-�s�;B����hUdCi�0C���3���x�
+}�C���σ���G�+D�Y�ص�`�s���NN��Ak�d��+�,d
�`�:�>>��`eB�.��c�S�y�^����B��qw�˧4������9��`����q8����Va,(E�Wi<��>>�K�W�P(���0��
+>��^�AZ$I��,��Yx!oWM��2`��.����;zq>�

data/README.md

@@ -48,19 +48,89 @@ render html: html.html_safe
 # or File.write("report.html", html)
 ```
 
+## Generating a template
+
+`Repolho::TemplateGenerator` creates a `.rep.erb` file from a base template
+and column metadata. The base template must already contain a `<report-page>`
+element (the page is required, matching the runtime) and two markers:
+
+- `<!-- REPORT:HEADERS -->` — replaced by the generated `<th>` cells
+- `<!-- REPORT:ROW -->` — replaced by the generated `<report-row>`
+
+Column names are taken from the data source without executing the full query
+when possible (`ActiveRecord::Result#columns`, a Relation's selected columns
+or model column names, an array of hashes/models, or an explicit array of
+column names).
+
+```ruby
+# From a Relation or Result (columns only)
+Repolho::TemplateGenerator.new(
+  "app/views/reports/base.rep.erb",
+  Order.where(status: "paid")
+).write("app/views/reports/orders.rep.erb")
+
+# Explicit columns + custom labels + numeric formatting
+Repolho::TemplateGenerator.new(
+  "app/views/reports/base.rep.erb",
+  %w[id customer_name total],
+  labels:  { "total" => "Total (R$)" },
+  numeric: %w[total]
+).write("app/views/reports/orders.rep.erb")
+```
+
+When running under Rails (or whenever `I18n` is available), header labels are
+looked up case-insensitively under
+`activerecord.attributes.<model>.<column>` (if a `model:` is given) or
+`repolho.attributes.<column>`. The lookup tries the original key, the
+downcase form and the upcase form. If no translation is found, a simple
+humanized name is used.
+
+Base template skeleton:
+
+```html
+<report>
+  <report-page rows="40">
+    <report-header>
+      <tr>
+        <!-- REPORT:HEADERS -->
+      </tr>
+    </report-header>
+
+    <!-- REPORT:ROW -->
+
+    <report-footer>
+      <!-- optional page totals -->
+    </report-footer>
+  </report-page>
+</report>
+```
+
 ## Template (`.rep.erb`)
 
 Repolho uses a few custom elements inside a normal HTML document. Everything
 outside `<report>…</report>` is copied as-is (the `previous` and `after`
 sections). Everything inside the custom elements is processed as ERB.
 
+### Why `<report>` instead of `<repolho>`?
+
+The element names are intentionally generic (`<report>`, `<report-page>`,
+`<report-group>`, etc.) rather than namespaced under the gem (`<repolho>`,
+`<repolho-page>`, …).
+
+Using `repolho` would tie the markup to this specific tool. With `report`,
+the template describes a report structure, not a Ruby library. Someone
+working in another language or with another report engine can reuse the same
+markup (or a close subset of it) without carrying Repolho-specific names.
+The goal is a small, readable convention for report templates — not a
+proprietary dialect.
+
 ### Custom elements
 
 | Element | Purpose | Attributes |
 |---------|---------|------------|
-| `<report>` | Root container of the report | `pagination` (optional, `"true"`): enables client-side page navigation. Also accepts `pagination-first`, `pagination-prev`, `pagination-next`, `pagination-last` for custom labels.<br>`orientation` (optional, `"portrait"` or `"landscape"`): page orientation for print.<br>`paper` (optional, e.g. `"A4"`, `"Letter"`): paper size for print. If either is present, a `@media print` style is injected at the end of `<body>`. |
+| `<report>` | Root container of the report | `pagination` (optional, `"true"`): enables client-side page navigation. Also accepts `pagination-first`, `pagination-prev`, `pagination-next`, `pagination-last` for custom labels.<br>`orientation` (optional, `"portrait"` or `"landscape"`): page orientation for print.<br>`paper` (optional, e.g. `"A4"`, `"Letter"`): paper size for print. If either is present, a `@media print` style is injected at the end of `<body>`.<br>`min-row-for-break` (optional, integer): when a group has `page-break-after="true"`, the forced break is skipped if the current page row number is less than or equal to this value. Prevents an extra break when a page has just started. |
 | `<report-page>` | Defines a page (required, only one) | `rows` (required): max data rows per page |
-| `<report-group>` | Nested grouping | `id` (required), `attr` (required), `reprint-header-on-page-break` (optional, `"true"`) |
+| `<report-group>` | Nested grouping | `id` (required), `attr` (required), `reprint-header-on-page-break` (optional, `"true"`), `page-break-after` (optional, `"true"`): after the group ends and its footer is emitted on the current page, fill the remaining rows with blanks and force a page break so the next group starts on a fresh page. Respects `min-row-for-break` on `<report>`. |
 | `<report-header>` | Header of the current container | — |
 | `<report-footer>` | Footer of the current container | — |
 | `<report-row>` | Template for each data row (inside the innermost group) | — |

data/lib/repolho/container.rb

@@ -6,7 +6,7 @@ require_relative "stats"
 
 module Repolho
   class Container
-    attr_accessor :header, :footer, :containers, :row_template, :attr, :page, :report, :status, :reprint_header_on_page_break
+    attr_accessor :header, :footer, :containers, :row_template, :attr, :page, :report, :status, :reprint_header_on_page_break, :page_break_after, :footer_rows
     attr_reader :id, :number, :stats
 
     UNSTARTED = 0
@@ -28,6 +28,8 @@ module Repolho
       @attr         = nil
       @page         = nil
       @report       = nil
+      @page_break_after = false
+      @footer_rows  = 0
 
       create_locals
     end
@@ -164,12 +166,32 @@ module Repolho
           container.status = FINISHED
         end
 
+        # Emit this group's footer on the current page (it stays with its data).
         @page << finish
         reset_stats
         @status = FINISHED
+
+        # Then, if requested, fill the rest of the page with blanks and force
+        # a break so the *next* group starts on a fresh page.
+        # min-row-for-break skips this when the page has barely started
+        # (e.g. the footer itself already caused a break).
+        if page_break_after && should_force_page_break?
+          @page.pad_and_break
+        end
       end
     end
 
+    def should_force_page_break?
+      return false unless @page
+
+      min = @page.min_row_for_break
+      return true if min.nil? || min <= 0
+
+      # Only force when the current page has progressed past the threshold.
+      # Prevents a second break when the page has just started (e.g. row 5 < 35).
+      @page.row_number > min
+    end
+
     def check_page_break
       return unless self.is_a?(Page)
       return unless @row_number >= @valid_rows

data/lib/repolho/main.rb

@@ -247,6 +247,10 @@ module Repolho
       @orientation = report_node["orientation"]&.downcase
       @paper       = report_node["paper"]
 
+      if report_node["min-row-for-break"]
+        @page.min_row_for_break = report_node["min-row-for-break"].to_i
+      end
+
       if @pagination
         @pagination_labels[:first] = report_node["pagination-first"] if report_node["pagination-first"]
         @pagination_labels[:prev]  = report_node["pagination-prev"]  if report_node["pagination-prev"]
@@ -297,14 +301,23 @@ module Repolho
     def build_group(element)
       container = Container.new(element["id"], @locals, make_stats)
       container.header = info(element.search("> report-header").first)
-      container.footer = info(element.search("> report-footer").first)
+      footer_info = info(element.search("> report-footer").first)
+      container.footer = footer_info
+      container.footer_rows = count_trs(footer_info[:content])
       container.attr   = element["attr"]
       container.reprint_header_on_page_break = element["reprint-header-on-page-break"] == "true"
+      container.page_break_after = element["page-break-after"] == "true"
       container.page   = @page
       container.report = @report
       container
     end
 
+    def count_trs(html)
+      return 0 if html.nil? || html.strip.empty?
+
+      Nokogiri::HTML(html).search("tr").size
+    end
+
     def info(element)
       return { content: "" } unless element
 

data/lib/repolho/page.rb

@@ -4,6 +4,7 @@
 module Repolho
   class Page < Container
     attr_reader :content, :row_number, :rows, :page_number
+    attr_accessor :min_row_for_break
 
     def initialize(id, locals, stats)
       super(id, locals, stats)
@@ -43,6 +44,35 @@ module Repolho
       end
     end
 
+    # Fills the current page with blank rows up to the limit and forces a break
+    # using the existing page-break path. Called *after* a group footer has
+    # already been emitted, so the footer stays on the current page and the
+    # next group starts on a fresh page.
+    #
+    # After the break, the new page is opened and its header is emitted
+    # immediately so subsequent content (the group footer) appears *after*
+    # the page header, not before it.
+    def pad_and_break
+      remaining = @valid_rows - @row_number
+      if remaining > 0
+        blank = %(<tr><td colspan="200">&nbsp;</td></tr>)
+        remaining.times { self << blank }
+      end
+      check_page_break
+
+      # Open the new page and emit its header right away.
+      # check_page_break left status as FINISHED; we start the page now
+      # so later check_started does not emit the header again (late).
+      return if @page_open
+
+      open_page
+      if @status == FINISHED
+        header_html = start
+        self << header_html if header_html && !header_html.to_s.strip.empty?
+        @status = STARTED
+      end
+    end
+
     def <<(content)
       return unless content
 

data/lib/repolho/template_generator.rb

@@ -0,0 +1,151 @@
+# typed: false
+# frozen_string_literal: true
+
+require "cgi"
+
+module Repolho
+  # Generates a .rep.erb template from a base template and column metadata.
+  #
+  # The base template must contain a <report-page> element and the markers
+  # <!-- REPORT:HEADERS --> and <!-- REPORT:ROW -->. The page element is
+  # required, matching the runtime expectation.
+  #
+  # Column labels are resolved case-insensitively (original, downcase, upcase)
+  # via I18n when available. Otherwise a simple humanized form of the column
+  # name is used.
+  class TemplateGenerator
+    HEADERS_MARKER = "<!-- REPORT:HEADERS -->"
+    ROW_MARKER     = "<!-- REPORT:ROW -->"
+
+    def initialize(base_path, data, model: nil, labels: {}, numeric: [])
+      @base_path = base_path
+      @data      = data
+      @model     = model
+      @labels    = labels.transform_keys(&:to_s)
+      @numeric   = Array(numeric).map(&:to_s)
+    end
+
+    # Returns the generated template content as a String.
+    def generate
+      content = File.read(@base_path)
+      validate_base!(content)
+
+      columns = extract_columns(@data)
+      raise ArgumentError, "No columns could be extracted from the given data" if columns.empty?
+
+      headers = generate_headers(columns)
+      row     = generate_row(columns)
+
+      content
+        .gsub(HEADERS_MARKER, headers)
+        .gsub(ROW_MARKER, row)
+    end
+
+    # Writes the generated template to output_path.
+    def write(output_path)
+      File.write(output_path, generate)
+    end
+
+    private
+
+    def validate_base!(content)
+      unless content.include?("<report-page")
+        raise ArgumentError, "Base template must contain a <report-page> element"
+      end
+
+      unless content.include?(HEADERS_MARKER)
+        raise ArgumentError, "Base template must contain the marker #{HEADERS_MARKER}"
+      end
+
+      unless content.include?(ROW_MARKER)
+        raise ArgumentError, "Base template must contain the marker #{ROW_MARKER}"
+      end
+    end
+
+    def extract_columns(data)
+      return data.map(&:to_s) if explicit_column_list?(data)
+
+      if data.respond_to?(:columns)
+        return data.columns.map(&:to_s)
+      end
+
+      if data.respond_to?(:klass) && data.klass.respond_to?(:column_names)
+        if data.respond_to?(:select_values) && data.select_values.any?
+          return data.select_values.map { |v| extract_column_name(v) }
+        end
+        return data.klass.column_names.map(&:to_s)
+      end
+
+      extract_from_rows(data)
+    end
+
+    def explicit_column_list?(data)
+      data.is_a?(Array) && data.all? { |c| c.is_a?(String) || c.is_a?(Symbol) }
+    end
+
+    def extract_column_name(value)
+      value.to_s.split(".").last.gsub(/["'`]/, "").strip
+    end
+
+    def extract_from_rows(data)
+      rows = data.respond_to?(:to_a) ? data.to_a : Array(data)
+      return [] if rows.empty?
+
+      first = rows.first
+      if first.respond_to?(:attributes)
+        first.attributes.keys.map(&:to_s)
+      elsif first.is_a?(Hash)
+        first.keys.map(&:to_s)
+      else
+        []
+      end
+    end
+
+    def generate_headers(columns)
+      columns.map { |col| "<th>#{CGI.escapeHTML(column_label(col))}</th>" }.join("\n            ")
+    end
+
+    def generate_row(columns)
+      cells = columns.map do |col|
+        expr = if @numeric.include?(col)
+                 %(<%= number_with_precision(attr(:#{col}), precision: 2) %>)
+               else
+                 %(<%= attr(:#{col}) %>)
+               end
+        "<td>#{expr}</td>"
+      end
+
+      <<~HTML.strip
+        <report-row>
+          <tr>
+            #{cells.join("\n            ")}
+          </tr>
+        </report-row>
+      HTML
+    end
+
+    def column_label(column)
+      column = column.to_s
+      return @labels[column] if @labels.key?(column)
+
+      return humanize(column) unless defined?(I18n)
+
+      [column, column.downcase, column.upcase].uniq.each do |key|
+        full_key = if @model
+                     "activerecord.attributes.#{@model.model_name.i18n_key}.#{key}"
+                   else
+                     "repolho.attributes.#{key}"
+                   end
+
+        result = I18n.t(full_key, default: nil)
+        return result if result
+      end
+
+      humanize(column)
+    end
+
+    def humanize(column)
+      column.to_s.tr("_", " ").capitalize
+    end
+  end
+end

data/lib/repolho/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Repolho
-  VERSION = "0.1.8"
+  VERSION = "0.2.1"
 end

data/lib/repolho.rb

@@ -6,6 +6,7 @@ require_relative "repolho/container"
 require_relative "repolho/page"
 require_relative "repolho/report"
 require_relative "repolho/main"
+require_relative "repolho/template_generator"
 
 module Repolho
   # Includes Rails helper modules into Container so they become available
@@ -14,6 +15,11 @@ module Repolho
   # By default includes ActionView::Helpers::NumberHelper.
   # Pass additional modules if needed.
   #
+  # The method is idempotent: modules already included are skipped.
+  #
+  # Outside a full Rails environment you must load the helpers correctly
+  # before calling this method (see README).
+  #
   # Example:
   #   Repolho.include_rails_helpers!
   #   Repolho.include_rails_helpers!(ActionView::Helpers::NumberHelper, ActionView::Helpers::TextHelper)
@@ -24,5 +30,7 @@ module Repolho
 
       Container.include(mod)
     end
+
   end
+
 end

data/test/main_test.rb

@@ -457,5 +457,71 @@ module Repolho
     ensure
       template&.unlink
     end
+
+    def test_page_break_after_group_pads_and_breaks
+      data = [
+        { "id" => 1, "name" => "Alice", "value" => 10.0, "state" => "SP" },
+        { "id" => 2, "name" => "Bob",   "value" => 20.0, "state" => "SP" },
+        { "id" => 3, "name" => "Carol", "value" => 15.0, "state" => "RJ" },
+        { "id" => 4, "name" => "Dave",  "value" => 25.0, "state" => "RJ" }
+      ]
+
+      template_content = GROUP_TEMPLATE.gsub(
+        '<report-group id="state" attr="state">',
+        '<report-group id="state" attr="state" page-break-after="true">'
+      ).gsub(
+        '<report-page rows="10">',
+        '<report-page rows="6">'
+      )
+
+      template = write_temp_template(template_content)
+      main = Main.new(template.path, data)
+      main.run
+      html = main.content.join
+      doc = html_doc(html)
+
+      pages = page_tbodies(doc)
+      assert pages.size >= 2, "Expected a forced page break after group, got #{pages.size}"
+
+      # Blank padding rows should be present
+      assert_includes html, "&nbsp;"
+
+      # Group footer of the first group should appear, and the second group header too
+      assert_includes html, "State total"
+      assert_includes html, "State: RJ"
+    ensure
+      template&.unlink
+    end
+
+    def test_min_row_for_break_skips_early_page
+      data = [
+        { "id" => 1, "name" => "Alice", "value" => 10.0, "state" => "SP" },
+        { "id" => 2, "name" => "Bob",   "value" => 20.0, "state" => "RJ" }
+      ]
+
+      # High threshold: page has barely started, so no forced break
+      template_content = GROUP_TEMPLATE.gsub(
+        "<report>",
+        '<report min-row-for-break="20">'
+      ).gsub(
+        '<report-group id="state" attr="state">',
+        '<report-group id="state" attr="state" page-break-after="true">'
+      ).gsub(
+        '<report-page rows="10">',
+        '<report-page rows="30">'
+      )
+
+      template = write_temp_template(template_content)
+      main = Main.new(template.path, data)
+      main.run
+      html = main.content.join
+      doc = html_doc(html)
+
+      pages = page_tbodies(doc)
+      assert_equal 1, pages.size, "Threshold should have prevented an early forced break"
+      refute_includes html, "&nbsp;"
+    ensure
+      template&.unlink
+    end
   end
 end

data/test/template_generator_test.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require_relative "test_helper"
+
+class TemplateGeneratorTest < Minitest::Test
+  include TestHelpers
+
+  def setup
+    @base = <<~HTML
+      <!DOCTYPE html>
+      <html>
+        <body>
+          <table>
+            <report>
+              <report-page rows="40">
+                <report-header>
+                  <tr>
+                    <!-- REPORT:HEADERS -->
+                  </tr>
+                </report-header>
+
+                <!-- REPORT:ROW -->
+
+                <report-footer>
+                  <tr><td colspan="99">Footer</td></tr>
+                </report-footer>
+              </report-page>
+            </report>
+          </table>
+        </body>
+      </html>
+    HTML
+  end
+
+  def test_generates_headers_and_row_from_array_of_hashes
+    data = [{ "id" => 1, "name" => "Alice", "total" => 10.5 }]
+    file = write_temp_template(@base)
+
+    generator = Repolho::TemplateGenerator.new(file.path, data)
+    result = generator.generate
+
+    assert_includes result, "<th>Id</th>"
+    assert_includes result, "<th>Name</th>"
+    assert_includes result, "<th>Total</th>"
+    assert_includes result, "<report-row>"
+    assert_includes result, "<%= attr(:id) %>"
+    assert_includes result, "<%= attr(:name) %>"
+    assert_includes result, "<%= attr(:total) %>"
+    refute_includes result, "<!-- REPORT:HEADERS -->"
+    refute_includes result, "<!-- REPORT:ROW -->"
+  ensure
+    file.unlink
+  end
+
+  def test_uses_explicit_column_list
+    file = write_temp_template(@base)
+    generator = Repolho::TemplateGenerator.new(file.path, %w[id customer_name])
+    result = generator.generate
+
+    assert_includes result, "<th>Id</th>"
+    assert_includes result, "<th>Customer name</th>"
+    assert_includes result, "<%= attr(:customer_name) %>"
+  ensure
+    file.unlink
+  end
+
+  def test_custom_labels_override
+    file = write_temp_template(@base)
+    generator = Repolho::TemplateGenerator.new(
+      file.path,
+      %w[id total],
+      labels: { "total" => "Total (R$)" }
+    )
+    result = generator.generate
+
+    assert_includes result, "<th>Total (R$)</th>"
+    assert_includes result, "<th>Id</th>"
+  ensure
+    file.unlink
+  end
+
+  def test_numeric_columns_use_number_helper
+    file = write_temp_template(@base)
+    generator = Repolho::TemplateGenerator.new(
+      file.path,
+      %w[id total],
+      numeric: %w[total]
+    )
+    result = generator.generate
+
+    assert_includes result, "<%= number_with_precision(attr(:total), precision: 2) %>"
+    assert_includes result, "<%= attr(:id) %>"
+  ensure
+    file.unlink
+  end
+
+  def test_raises_when_page_missing
+    bad = @base.gsub("<report-page rows=\"40\">", "").gsub("</report-page>", "")
+    file = write_temp_template(bad)
+
+    generator = Repolho::TemplateGenerator.new(file.path, %w[id])
+    error = assert_raises(ArgumentError) { generator.generate }
+    assert_match(/report-page/, error.message)
+  ensure
+    file.unlink
+  end
+
+  def test_raises_when_markers_missing
+    bad = @base.gsub("<!-- REPORT:HEADERS -->", "").gsub("<!-- REPORT:ROW -->", "")
+    file = write_temp_template(bad)
+
+    generator = Repolho::TemplateGenerator.new(file.path, %w[id])
+    error = assert_raises(ArgumentError) { generator.generate }
+    assert_match(/REPORT:HEADERS/, error.message)
+  ensure
+    file.unlink
+  end
+
+  def test_write_creates_file
+    file = write_temp_template(@base)
+    output = Tempfile.new(["out", ".rep.erb"])
+    output.close
+
+    generator = Repolho::TemplateGenerator.new(file.path, %w[id name])
+    generator.write(output.path)
+
+    content = File.read(output.path)
+    assert_includes content, "<report-row>"
+    assert_includes content, "<%= attr(:name) %>"
+  ensure
+    file.unlink
+    output.unlink
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: repolho
 version: !ruby/object:Gem::Version
-  version: 0.1.8
+  version: 0.2.1
 platform: ruby
 authors:
 - Eustáquio Rangel
@@ -97,6 +97,7 @@ files:
 - lib/repolho/page.rb
 - lib/repolho/report.rb
 - lib/repolho/stats.rb
+- lib/repolho/template_generator.rb
 - lib/repolho/version.rb
 - test/container_test.rb
 - test/fixtures/simple.rep.erb
@@ -104,6 +105,7 @@ files:
 - test/page_test.rb
 - test/report_test.rb
 - test/stats_test.rb
+- test/template_generator_test.rb
 - test/test_helper.rb
 homepage: https://github.com/taq/repolho
 licenses: