nti_receipt_builder 0.1.0

data/app/views/nti_receipt_builder/templates/new.html.erb

@@ -0,0 +1,115 @@
+<%= content_for :title, 'New Receipt Template' %>
+
+<%= form_with model: @receipt_template, url: url_for(action: :create), scope: :receipt_template do |f| %>
+  <h3 class="card-title">Receipt Template</h3>
+  <div id="errors">
+    <% if @errors.present? %>
+      <%= render 'nti_receipt_builder/templates/errors', errors: @errors %>
+    <% end %>
+  </div>
+
+  <div class="row g-3">
+    <div class="col-md-6">
+      <div class="form-group mb-3">
+        <%= f.label :name, 'Template Name', class: 'form-label' %>
+        <%= f.text_field :name, class: 'form-control', placeholder: 'e.g. Main Branch Receipt' %>
+      </div>
+
+      <div class="form-group mb-3">
+        <%= f.label :paper_size_key, 'Paper Size', class: 'form-label' %>
+        <%= f.select :paper_size_key,
+            NtiReceiptBuilder::Template::PAPER_PRESETS.map { |key, preset| [preset[:label], key] },
+            {},
+            class: 'form-select' %>
+      </div>
+
+      <div class="row g-3">
+        <div class="col">
+          <div class="form-group mb-3">
+            <%= f.label :paper_width_mm, 'Width (mm)', class: 'form-label' %>
+            <%= f.number_field :paper_width_mm, step: 0.1,
+                min: NtiReceiptBuilder::Template::MIN_PAPER_DIMENSION_MM,
+                max: NtiReceiptBuilder::Template::MAX_PAPER_DIMENSION_MM,
+                class: 'form-control' %>
+          </div>
+        </div>
+        <div class="col">
+          <div class="form-group mb-3">
+            <%= f.label :paper_height_mm, 'Height (mm)', class: 'form-label' %>
+            <%= f.number_field :paper_height_mm, step: 0.1,
+                min: NtiReceiptBuilder::Template::MIN_PAPER_DIMENSION_MM,
+                max: NtiReceiptBuilder::Template::MAX_PAPER_DIMENSION_MM,
+                class: 'form-control' %>
+          </div>
+        </div>
+      </div>
+
+      <div class="row g-3">
+        <div class="col">
+          <div class="form-group mb-3">
+            <%= f.label :orientation, 'Orientation', class: 'form-label' %>
+            <%= f.select :orientation,
+                NtiReceiptBuilder::Template::ORIENTATIONS.map { |value| [value.titleize, value] },
+                {},
+                class: 'form-select' %>
+          </div>
+        </div>
+        <div class="col">
+          <div class="form-group mb-3">
+            <%= f.label :height_mode, 'Height Mode', class: 'form-label' %>
+            <%= f.select :height_mode,
+                [['Fixed Height', 'fixed'], ['Grows With Content', 'content']],
+                {},
+                class: 'form-select' %>
+          </div>
+        </div>
+      </div>
+    </div>
+
+    <div class="col-md-6">
+      <label class="form-label">Margins (mm)</label>
+      <div class="row g-3">
+        <div class="col-6">
+          <div class="form-group mb-3">
+            <%= f.label :margin_top_mm, 'Top', class: 'form-label' %>
+            <%= f.number_field :margin_top_mm, step: 0.1,
+                min: NtiReceiptBuilder::Template::MIN_MARGIN_MM, max: NtiReceiptBuilder::Template::MAX_MARGIN_MM,
+                class: 'form-control' %>
+          </div>
+        </div>
+        <div class="col-6">
+          <div class="form-group mb-3">
+            <%= f.label :margin_right_mm, 'Right', class: 'form-label' %>
+            <%= f.number_field :margin_right_mm, step: 0.1,
+                min: NtiReceiptBuilder::Template::MIN_MARGIN_MM, max: NtiReceiptBuilder::Template::MAX_MARGIN_MM,
+                class: 'form-control' %>
+          </div>
+        </div>
+        <div class="col-6">
+          <div class="form-group mb-3">
+            <%= f.label :margin_bottom_mm, 'Bottom', class: 'form-label' %>
+            <%= f.number_field :margin_bottom_mm, step: 0.1,
+                min: NtiReceiptBuilder::Template::MIN_MARGIN_MM, max: NtiReceiptBuilder::Template::MAX_MARGIN_MM,
+                class: 'form-control' %>
+          </div>
+        </div>
+        <div class="col-6">
+          <div class="form-group mb-3">
+            <%= f.label :margin_left_mm, 'Left', class: 'form-label' %>
+            <%= f.number_field :margin_left_mm, step: 0.1,
+                min: NtiReceiptBuilder::Template::MIN_MARGIN_MM, max: NtiReceiptBuilder::Template::MAX_MARGIN_MM,
+                class: 'form-control' %>
+          </div>
+        </div>
+      </div>
+      <p class="text-secondary">
+        You'll drag variables, text, and the order-lines block onto the canvas on the next step.
+      </p>
+    </div>
+  </div>
+
+  <div class="d-flex justify-content-end gap-2">
+    <%= link_to 'Cancel', url_for(action: :index), class: 'btn btn-secondary' %>
+    <%= f.submit 'Continue to Layout Builder', class: 'btn btn-primary' %>
+  </div>
+<% end %>

data/app/views/nti_receipt_builder/templates/preview.html.erb

@@ -0,0 +1,24 @@
+<% content_for :title, "Preview: #{@receipt_template.name}" %>
+<% content_for :cardless, true %>
+
+<div class="nrb-receipt-topbar">
+  <div>
+    <span class="nrb-receipt-topbar-name"><%= @receipt_template.name %></span>
+    <span class="text-secondary"><%= @receipt_template.paper_width_mm %>mm &times; <%= @receipt_template.paper_height_mm %>mm</span>
+  </div>
+  <div class="d-flex justify-content-end gap-2">
+    <%= link_to url_for(action: :print, id: @receipt_template.id),
+        class: 'btn btn-outline-secondary', target: '_blank', rel: 'noopener' do %>
+      <span class="material-symbols-outlined pe-1">print</span>Print
+    <% end %>
+    <%= link_to 'Back to Editor', url_for(action: :edit, id: @receipt_template.id), class: 'btn btn-secondary' %>
+  </div>
+</div>
+
+<% if @render_result.overflow? %>
+  <%= render 'nti_receipt_builder/render/overflow_banner' %>
+<% end %>
+
+<div class="nrb-receipt-preview-frame">
+  <%= render 'nti_receipt_builder/render/paper', receipt_template: @receipt_template, render_result: @render_result %>
+</div>

data/app/views/nti_receipt_builder/templates/print.html.erb

@@ -0,0 +1,31 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <title><%= @receipt_template.name %></title>
+
+    <%= render 'nti_receipt_builder/templates/print_assets' %>
+
+    <style>
+      @page {
+        size: <%= @receipt_template.paper_width_mm.to_f %>mm <%= @receipt_template.paper_height_mm.to_f %>mm;
+        margin: 0;
+      }
+
+      html, body {
+        margin: 0;
+        padding: 0;
+        background: #fff;
+      }
+
+      .nrb-receipt-paper-render {
+        margin: 0;
+        box-shadow: none;
+        border: none;
+      }
+    </style>
+  </head>
+  <body data-controller="nrb-print">
+    <%= render 'nti_receipt_builder/render/paper', receipt_template: @receipt_template, render_result: @render_result %>
+  </body>
+</html>

data/app/views/nti_receipt_builder/templates/render_preview.turbo_stream.erb

@@ -0,0 +1,26 @@
+<%= turbo_stream.open_modal size: 'modal-lg' do %>
+  <div class="modal-header">
+    <h1 class="modal-title">Live Preview</h1>
+    <button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button>
+  </div>
+  <div class="modal-body nrb-receipt-preview-modal">
+    <p class="text-secondary nrb-receipt-hint">
+      Rendered with sample data from your unsaved changes &mdash; nothing has been saved yet.
+    </p>
+
+    <% if @draft_errors.present? %>
+      <%= render 'nti_receipt_builder/templates/errors', errors: @draft_errors %>
+    <% else %>
+      <% if @render_result.overflow? %>
+        <%= render 'nti_receipt_builder/render/overflow_banner' %>
+      <% end %>
+
+      <div class="nrb-receipt-preview-frame">
+        <%= render 'nti_receipt_builder/render/paper', receipt_template: @draft, render_result: @render_result %>
+      </div>
+    <% end %>
+  </div>
+  <div class="modal-footer">
+    <button type="button" class="btn btn-primary" data-bs-dismiss="modal">Close</button>
+  </div>
+<% end %>

data/app/views/nti_receipt_builder/templates/update.turbo_stream.erb

@@ -0,0 +1,7 @@
+<% if @errors.empty? %>
+  <%= turbo_stream.toast('Receipt template saved!', type: :success) %>
+  <%= turbo_stream.replace 'lock_version_field', partial: 'nti_receipt_builder/templates/lock_version_field', locals: { receipt_template: @receipt_template } %>
+  <%= turbo_stream.update 'errors', '' %>
+<% else %>
+  <%= turbo_stream.update 'errors', partial: 'nti_receipt_builder/templates/errors', locals: { errors: @errors } %>
+<% end %>

data/config/importmap.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+pin_all_from NtiReceiptBuilder::Engine.root.join('app/assets/javascripts/nti_receipt_builder'),
+             under: 'nti_receipt_builder'

data/lib/generators/nti_receipt_builder/install_generator.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+require 'rails/generators/active_record'
+
+module NtiReceiptBuilder
+  module Generators
+    # rails generate nti_receipt_builder:install
+    class InstallGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path('templates', __dir__)
+
+      desc 'Creates the nti_receipt_builder initializer, migration, and (if absent) the ' \
+           'Turbo Stream helpers the gem views depend on.'
+
+      def create_initializer
+        template 'initializer.rb', 'config/initializers/nti_receipt_builder.rb'
+      end
+
+      def create_migration_file
+        migration_template 'create_nti_receipt_templates.rb',
+                           'db/migrate/create_nti_receipt_templates.rb'
+      end
+
+      # Only for hosts that do not already extend Turbo::Streams::TagBuilder. A host that
+      # already defines open_modal has its own conventions; overwriting them would be wrong.
+      def create_turbo_stream_helpers
+        if turbo_stream_helpers_present?
+          say_status :skip, 'config/initializers/turbo_stream_tags.rb (host already defines open_modal)', :yellow
+          return
+        end
+
+        template 'turbo_stream_tags.rb', 'config/initializers/turbo_stream_tags.rb'
+      end
+
+      private
+
+      def turbo_stream_helpers_present?
+        defined?(Turbo::Streams::TagBuilder) &&
+          Turbo::Streams::TagBuilder.method_defined?(:open_modal)
+      end
+
+      def migration_version
+        "[#{ActiveRecord::VERSION::MAJOR}.#{ActiveRecord::VERSION::MINOR}]"
+      end
+    end
+  end
+end

data/lib/generators/nti_receipt_builder/templates/create_nti_receipt_templates.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+class CreateNtiReceiptTemplates < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :nti_receipt_templates do |t|
+      t.string :owner_type, null: false
+      t.bigint :owner_id, null: false
+      t.string :name, null: false
+      t.string :paper_size_key, default: 'custom', null: false
+      t.string :orientation, default: 'portrait', null: false
+      t.string :height_mode, default: 'fixed', null: false
+      t.decimal :paper_width_mm, precision: 8, scale: 2, null: false
+      t.decimal :paper_height_mm, precision: 8, scale: 2, null: false
+      t.decimal :margin_top_mm, precision: 6, scale: 2, default: '0.0', null: false
+      t.decimal :margin_right_mm, precision: 6, scale: 2, default: '0.0', null: false
+      t.decimal :margin_bottom_mm, precision: 6, scale: 2, default: '0.0', null: false
+      t.decimal :margin_left_mm, precision: 6, scale: 2, default: '0.0', null: false
+      t.jsonb :layout, default: [], null: false
+      t.boolean :is_default, default: false, null: false
+      t.integer :lock_version, default: 0, null: false
+
+      t.timestamps
+    end
+
+    add_index :nti_receipt_templates, %i[owner_type owner_id],
+              name: 'index_nti_receipt_templates_on_owner'
+  end
+end

data/lib/generators/nti_receipt_builder/templates/initializer.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+NtiReceiptBuilder.configure do |config|
+  # Required. A NtiReceiptBuilder::Variables subclass declaring this application's receipt
+  # placeholders. Assign the class or its name — the gem stores only the name, so a reloadable
+  # application class is never pinned across a code reload.
+  # config.variables_class = 'OrderReceiptVariables'
+
+  # Optional. Point at a subclass of NtiReceiptBuilder::Template to attach your own concerns
+  # (audit, status, tenancy) while sharing the same table.
+  # config.template_class = 'ReceiptTemplate'
+
+  # Optional formatting.
+  # config.currency_unit   = '₱'
+  # config.datetime_format = '%m/%d/%Y %I:%M %p'
+end

data/lib/generators/nti_receipt_builder/templates/turbo_stream_tags.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+# The Turbo Stream actions nti_receipt_builder's views emit. Pair them with matching
+# turbo_stream action handlers in your JavaScript (app_modal, close_modal, toast,
+# reload_datatable). Delete this file if your application already provides them.
+Turbo::Streams::TagBuilder.class_eval do
+  def open_modal(size: 'modal-md', &)
+    content = @view_context.capture(&)
+
+    @view_context.turbo_stream_action_tag(
+      :app_modal,
+      size: size,
+      template: content
+    )
+  end
+
+  def close_modal
+    @view_context.turbo_stream_action_tag(:close_modal)
+  end
+
+  def toast(message, type: :success)
+    @view_context.turbo_stream_action_tag(
+      :toast,
+      message: message,
+      type: type
+    )
+  end
+
+  def reload_datatable(table_id, url: nil)
+    @view_context.turbo_stream_action_tag(
+      :reload_datatable,
+      'table-id': table_id,
+      url: url
+    )
+  end
+end

data/lib/nti_receipt_builder/configuration.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module NtiReceiptBuilder
+  # Runtime configuration.
+  #
+  # Class references are held by NAME, never as Class objects. Retaining a reloadable
+  # application class here would pin that class and its whole constant tree past every
+  # development reload, and would serve a stale class after the host reloads its code.
+  class Configuration
+    DEFAULT_CURRENCY_UNIT = '₱'
+    DEFAULT_DATETIME_FORMAT = '%m/%d/%Y %I:%M %p'
+    DEFAULT_TEMPLATE_CLASS = 'NtiReceiptBuilder::Template'
+    DEFAULT_PRINT_STYLESHEET = 'nti_receipt_builder'
+
+    attr_accessor :currency_unit, :datetime_format
+    # Stylesheet(s) the standalone print document loads — a name or an array of names. Defaults
+    # to the gem's own so print output is correct without host configuration. A host whose
+    # bundle does not include this gem's CSS should list both, e.g. ['app', 'nti_receipt_builder'].
+    attr_accessor :print_stylesheet
+    attr_reader :variables_class_name, :template_class_name
+
+    def initialize
+      @currency_unit = DEFAULT_CURRENCY_UNIT
+      @datetime_format = DEFAULT_DATETIME_FORMAT
+      @print_stylesheet = DEFAULT_PRINT_STYLESHEET
+      @variables_class_name = nil
+      @template_class_name = DEFAULT_TEMPLATE_CLASS
+    end
+
+    def variables_class=(value)
+      @variables_class_name = class_name_for(value)
+    end
+
+    def variables_class
+      if @variables_class_name.nil?
+        raise NotConfiguredError,
+              'NtiReceiptBuilder.config.variables_class must be set to a NtiReceiptBuilder::Variables subclass'
+      end
+
+      @variables_class_name.constantize
+    end
+
+    def template_class=(value)
+      @template_class_name = class_name_for(value)
+    end
+
+    def template_class
+      @template_class_name.constantize
+    end
+
+    private
+
+    def class_name_for(value)
+      return value.to_s unless value.is_a?(Class)
+
+      value.name || raise(Error, 'cannot configure an anonymous class — give it a name or pass a String')
+    end
+  end
+end

data/lib/nti_receipt_builder/elements.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module NtiReceiptBuilder
+  # Canonical whitelist of layout-element shapes, style properties and size limits a
+  # template's jsonb `layout` may contain. LayoutValidator is the only reader.
+  #
+  # Column keys are deliberately NOT here — they are declared by the host's variables class
+  # on the collection variable, so the gem carries no domain vocabulary.
+  #
+  # MAX_ELEMENTS and the length caps are what bound the memory a single template can consume;
+  # they are enforced before persistence, not by convention.
+  module Elements
+    TYPES = %w[variable text order_lines].freeze
+
+    MAX_ELEMENTS = 60
+    MIN_ELEMENT_DIMENSION_MM = 1.0
+
+    Z_INDEX_MIN = 0
+    Z_INDEX_MAX = 1000
+
+    TEXT_ALIGNS = %w[left center right].freeze
+    FONT_WEIGHTS = %w[normal bold].freeze
+
+    STYLE_WHITELIST = {
+      'font_size_pt' => { type: :numeric, min: 6, max: 72 },
+      'font_weight' => { type: :enum, values: FONT_WEIGHTS },
+      'text_align' => { type: :enum, values: TEXT_ALIGNS },
+      'line_height' => { type: :numeric, min: 0.8, max: 3.0 }
+    }.freeze
+
+    TEXT_MAX_LENGTH = 500
+    FALLBACK_MAX_LENGTH = 200
+    PREFIX_MAX_LENGTH = 50
+    SUFFIX_MAX_LENGTH = 50
+
+    # There is deliberately no maximum: the host declares the column vocabulary, and
+    # LayoutValidator rejects unknown and duplicated keys, so that vocabulary is already the
+    # ceiling. A constant here would reject a host whose collection is simply wider than the
+    # gem happened to anticipate.
+    MIN_ORDER_LINE_COLUMNS = 1
+    COLUMN_LABEL_MAX_LENGTH = 40
+
+    ROW_SPACING_MIN_MM = 0.0
+    ROW_SPACING_MAX_MM = 10.0
+  end
+end

data/lib/nti_receipt_builder/engine.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module NtiReceiptBuilder
+  # Non-isolated on purpose: host controllers include NtiReceiptBuilder::TemplatesController
+  # and must resolve this engine's views through the ordinary view-path chain. A non-isolated
+  # engine contributes app/views, app/models, app/helpers and app/controllers/concerns to the
+  # host automatically.
+  class Engine < ::Rails::Engine
+    # Propshaft picks up app/assets automatically; javascripts needs naming explicitly so the
+    # Stimulus controllers are servable.
+    initializer 'nti_receipt_builder.assets' do |app|
+      next unless app.config.respond_to?(:assets)
+
+      app.config.assets.paths << root.join('app/assets/javascripts')
+      app.config.assets.paths << root.join('app/assets/stylesheets')
+    end
+
+    initializer 'nti_receipt_builder.importmap', before: 'importmap' do |app|
+      next unless app.config.respond_to?(:importmap)
+
+      app.config.importmap.paths << root.join('config/importmap.rb')
+    end
+
+    # The render partials are rendered from whichever host controller prints a receipt, not
+    # just the builder's own, so paper_style has to be available everywhere.
+    initializer 'nti_receipt_builder.helpers' do
+      ActiveSupport.on_load(:action_controller_base) do
+        helper NtiReceiptBuilder::RenderHelper
+      end
+    end
+  end
+end

data/lib/nti_receipt_builder/errors.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module NtiReceiptBuilder
+  class Error < StandardError; end
+
+  # Raised when the gem is used before required configuration has been supplied.
+  class NotConfiguredError < Error; end
+
+  # Raised when a Variables subclass is malformed — MAPPINGS missing or not a Hash, a mapped
+  # method that does not exist, an override for a key absent from MAPPINGS, or more than one
+  # key declaring `columns:`.
+  class InvalidVariablesError < Error; end
+end