nti_receipt_builder 0.1.0

data/lib/nti_receipt_builder/layout_validator.rb

@@ -0,0 +1,285 @@
+# frozen_string_literal: true
+
+module NtiReceiptBuilder
+  # Structural + whitelist validation of a template's jsonb `layout`. This is the single
+  # place that decides whether a submitted layout is safe to persist and render — it never
+  # trusts client-side snap/clamp/whitelist checks, since those are UX conveniences only.
+  #
+  # Allowed variable keys and order-line column keys come from the host's variables class,
+  # so this validator holds no domain vocabulary of its own.
+  class LayoutValidator
+    GEOMETRY_KEYS = %w[x_mm y_mm width_mm height_mm].freeze
+
+    def initialize(layout:, paper_width_mm:, paper_height_mm:, margin_top_mm:, margin_right_mm:,
+                   margin_bottom_mm:, margin_left_mm:, height_mode:,
+                   variables_class: NtiReceiptBuilder.variables_class)
+      @layout = layout
+      @paper_width_mm = paper_width_mm
+      @paper_height_mm = paper_height_mm
+      @margin_top_mm = margin_top_mm
+      @margin_right_mm = margin_right_mm
+      @margin_bottom_mm = margin_bottom_mm
+      @margin_left_mm = margin_left_mm
+      @height_mode = height_mode
+      @variables_class = variables_class
+      @errors = []
+    end
+
+    def call
+      unless @layout.is_a?(Array)
+        @errors << 'must be an array of elements'
+        return @errors
+      end
+
+      if @layout.size > Elements::MAX_ELEMENTS
+        @errors << "may contain at most #{Elements::MAX_ELEMENTS} elements (has #{@layout.size})"
+      end
+
+      seen_ids = Set.new
+      @layout.each_with_index { |element, index| validate_element(element, index, seen_ids) }
+
+      @errors
+    end
+
+    private
+
+    def validate_element(element, index, seen_ids)
+      tag = "element ##{index + 1}"
+
+      unless element.is_a?(Hash)
+        @errors << "#{tag} must be an object"
+        return
+      end
+
+      validate_id(element, tag, seen_ids)
+
+      type = element['type']
+      unless Elements::TYPES.include?(type)
+        @errors << "#{tag} has an unknown type (#{type.inspect})"
+        return
+      end
+
+      validate_geometry(element, tag)
+      validate_z_index(element, tag)
+      validate_visibility(element, tag)
+      validate_styles(element, tag)
+
+      case type
+      when 'variable' then validate_variable(element, tag)
+      when 'text' then validate_text(element, tag)
+      when 'order_lines' then validate_order_lines(element, tag)
+      end
+    end
+
+    def validate_id(element, tag, seen_ids)
+      id = element['id']
+      if !id.is_a?(String) || id.blank?
+        @errors << "#{tag} is missing a valid id"
+      elsif seen_ids.include?(id)
+        @errors << "#{tag} has a duplicate id (#{id})"
+      else
+        seen_ids << id
+      end
+    end
+
+    def validate_geometry(element, tag)
+      return unless numeric_geometry?(element, tag)
+
+      validate_position(element, tag)
+      validate_dimensions(element, tag)
+      validate_paper_bounds(element, tag)
+    end
+
+    # A single non-numeric coordinate stops geometry validation — the remaining checks would
+    # all report on coerced zeros and bury the real problem.
+    def numeric_geometry?(element, tag)
+      offending = GEOMETRY_KEYS.find { |key| !element[key].is_a?(Numeric) }
+      return true if offending.nil?
+
+      @errors << "#{tag} has a non-numeric #{offending}"
+      false
+    end
+
+    def validate_position(element, tag)
+      return unless element['x_mm'].to_f.negative? || element['y_mm'].to_f.negative?
+
+      @errors << "#{tag} has a negative position"
+    end
+
+    def validate_dimensions(element, tag)
+      too_small = element['width_mm'].to_f < Elements::MIN_ELEMENT_DIMENSION_MM ||
+                  element['height_mm'].to_f < Elements::MIN_ELEMENT_DIMENSION_MM
+      return unless too_small
+
+      @errors << "#{tag} is smaller than the minimum size of #{Elements::MIN_ELEMENT_DIMENSION_MM}mm"
+    end
+
+    def validate_paper_bounds(element, tag)
+      x_mm = element['x_mm'].to_f
+      y_mm = element['y_mm'].to_f
+
+      @errors << "#{tag} extends beyond the paper width" if x_mm + element['width_mm'].to_f > @paper_width_mm
+
+      return if @height_mode == 'content'
+
+      @errors << "#{tag} extends beyond the paper height" if y_mm + element['height_mm'].to_f > @paper_height_mm
+    end
+
+    def validate_z_index(element, tag)
+      return unless element.key?('z_index')
+
+      value = element['z_index']
+      return if value.is_a?(Integer) && value.between?(Elements::Z_INDEX_MIN, Elements::Z_INDEX_MAX)
+
+      @errors << "#{tag} has an invalid z_index"
+    end
+
+    def validate_visibility(element, tag)
+      return unless element.key?('visible')
+
+      @errors << "#{tag} has an invalid visible flag" unless [true, false].include?(element['visible'])
+    end
+
+    def validate_styles(element, tag)
+      styles = element['styles']
+      return if styles.nil?
+
+      unless styles.is_a?(Hash)
+        @errors << "#{tag} has invalid styles"
+        return
+      end
+
+      styles.each { |key, value| validate_style_property(key, value, tag) }
+    end
+
+    def validate_style_property(key, value, tag)
+      rule = Elements::STYLE_WHITELIST[key]
+      unless rule
+        @errors << "#{tag} has a disallowed style property (#{key})"
+        return
+      end
+
+      case rule[:type]
+      when :numeric
+        unless value.is_a?(Numeric) && value.between?(rule[:min], rule[:max])
+          @errors << "#{tag} has an out-of-range #{key}"
+        end
+      when :enum
+        @errors << "#{tag} has an invalid #{key}" unless rule[:values].include?(value)
+      end
+    end
+
+    def validate_variable(element, tag)
+      key = element['variable_key']
+      unless key.is_a?(String) && @variables_class.scalar_keys.include?(key)
+        @errors << "#{tag} has an unknown variable_key (#{key.inspect})"
+      end
+
+      validate_optional_string(element, 'fallback', Elements::FALLBACK_MAX_LENGTH, tag)
+      validate_optional_string(element, 'prefix', Elements::PREFIX_MAX_LENGTH, tag)
+      validate_optional_string(element, 'suffix', Elements::SUFFIX_MAX_LENGTH, tag)
+    end
+
+    def validate_optional_string(element, key, max_length, tag)
+      return unless element.key?(key)
+
+      value = element[key]
+      @errors << "#{tag} has an invalid #{key}" unless value.is_a?(String) && value.length <= max_length
+    end
+
+    def validate_text(element, tag)
+      text = element['text']
+      return if text.is_a?(String) && text.present? && text.length <= Elements::TEXT_MAX_LENGTH
+
+      @errors << "#{tag} has a missing or too-long text value"
+    end
+
+    def validate_order_lines(element, tag)
+      config = element['config']
+      unless config.is_a?(Hash)
+        @errors << "#{tag} is missing its order_lines config"
+        return
+      end
+
+      if config.key?('show_header') && ![true, false].include?(config['show_header'])
+        @errors << "#{tag} has an invalid show_header"
+      end
+
+      validate_row_spacing(config, tag)
+      validate_order_lines_font_size(config, tag)
+      validate_order_line_columns(config['columns'], tag)
+    end
+
+    def validate_row_spacing(config, tag)
+      return unless config.key?('row_spacing_mm')
+
+      value = config['row_spacing_mm']
+      in_range = value.is_a?(Numeric) &&
+                 value.between?(Elements::ROW_SPACING_MIN_MM, Elements::ROW_SPACING_MAX_MM)
+      @errors << "#{tag} has an out-of-range row_spacing_mm" unless in_range
+    end
+
+    def validate_order_lines_font_size(config, tag)
+      return unless config.key?('font_size_pt')
+
+      rule = Elements::STYLE_WHITELIST['font_size_pt']
+      value = config['font_size_pt']
+      return if value.is_a?(Numeric) && value.between?(rule[:min], rule[:max])
+
+      @errors << "#{tag} has an out-of-range font_size_pt"
+    end
+
+    # Only a lower bound is checked. Every key must be one of the host's declared collection
+    # columns and duplicates are rejected below, so the column count cannot exceed the host's
+    # own vocabulary — capping it here would reject a legitimately wider host.
+    def validate_order_line_columns(columns, tag)
+      unless columns.is_a?(Array) && columns.size >= Elements::MIN_ORDER_LINE_COLUMNS
+        @errors << "#{tag} must have at least #{Elements::MIN_ORDER_LINE_COLUMNS} order_lines column"
+        return
+      end
+
+      seen_keys = Set.new
+      columns.each_with_index { |column, index| validate_order_line_column(column, index, tag, seen_keys) }
+    end
+
+    def validate_order_line_column(column, index, tag, seen_keys)
+      col_tag = "#{tag} column ##{index + 1}"
+
+      unless column.is_a?(Hash)
+        @errors << "#{col_tag} must be an object"
+        return
+      end
+
+      validate_order_line_column_key(column, col_tag, seen_keys)
+      validate_order_line_column_label(column, col_tag)
+      validate_order_line_column_geometry(column, col_tag)
+    end
+
+    def validate_order_line_column_label(column, col_tag)
+      label = column['label']
+      return if label.is_a?(String) && label.present? && label.length <= Elements::COLUMN_LABEL_MAX_LENGTH
+
+      @errors << "#{col_tag} has an invalid label"
+    end
+
+    def validate_order_line_column_geometry(column, col_tag)
+      width_mm = column['width_mm']
+      @errors << "#{col_tag} has an invalid width_mm" unless width_mm.is_a?(Numeric) && width_mm.positive?
+
+      @errors << "#{col_tag} has an invalid align" unless Elements::TEXT_ALIGNS.include?(column['align'])
+    end
+
+    def validate_order_line_column_key(column, col_tag, seen_keys)
+      key = column['key']
+      allowed = @variables_class.collection_definition&.column_keys || []
+
+      if !key.is_a?(String) || !allowed.include?(key)
+        @errors << "#{col_tag} has an unknown key (#{key.inspect})"
+      elsif seen_keys.include?(key)
+        @errors << "#{col_tag} duplicates column key #{key}"
+      else
+        seen_keys << key
+      end
+    end
+  end
+end

data/lib/nti_receipt_builder/presenters/collection.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require 'action_view'
+
+module NtiReceiptBuilder
+  module Presenters
+    # Presents one `order_lines` layout element: whitelisted columns, per-row formatted cells,
+    # and the dynamically computed content height that drives overflow detection. An empty
+    # collection renders a single muted "no line items" row rather than collapsing to nothing.
+    #
+    # `columns`, `rows` and `total_column_width_mm` are memoised per instance so cell rendering
+    # stays O(rows x columns) rather than recomputing the width sum once per cell. Instances are
+    # short-lived — one per render — so nothing here outlives the response.
+    class Collection
+      include ActionView::Helpers::NumberHelper
+
+      DEFAULT_ROW_SPACING_MM = 1.0
+      DEFAULT_FONT_SIZE_PT = 9
+      MM_PER_PT = 0.3528
+      # Tight leading — receipt rows sit directly under one another. Anything near 1.6
+      # double-spaces the table and pushes the line items apart.
+      LINE_HEIGHT_FACTOR = 1.25
+
+      def initialize(element, rows, definition: nil)
+        @element = element
+        @collection_rows = rows || []
+        @definition = definition
+      end
+
+      def id = element['id']
+      def type = 'order_lines'
+      def x_mm = element['x_mm'].to_f
+      def y_mm = element['y_mm'].to_f
+      def width_mm = element['width_mm'].to_f
+      def z_index = element['z_index'] || 0
+
+      def columns
+        @columns ||= (config['columns'] || []).map { |column| build_column(column) }
+      end
+
+      # Configured column widths are treated as ratios, not absolutes: normalising them to
+      # percentages lets `table-layout: fixed` fill the row edge-to-edge whatever the mm happen
+      # to sum to. Falls back to even columns when the template configures no widths at all.
+      def column_width_pct(column)
+        return (100.0 / columns.size).round(4) unless total_column_width_mm.positive?
+
+        (column['width_mm'] / total_column_width_mm * 100).round(4)
+      end
+
+      def show_header? = config.fetch('show_header', true)
+      def row_spacing_mm = config['row_spacing_mm'] || DEFAULT_ROW_SPACING_MM
+      def font_size_pt = config['font_size_pt'] || DEFAULT_FONT_SIZE_PT
+
+      # The line box for one row of text. Cells render at exactly this line-height with
+      # row_spacing_mm as padding below, so a row's drawn height always equals row_height_mm
+      # and content_height_mm stays honest for overflow detection.
+      def text_line_height_mm
+        (font_size_pt * MM_PER_PT * LINE_HEIGHT_FACTOR).round(4)
+      end
+
+      def row_height_mm = text_line_height_mm + row_spacing_mm
+
+      # The header is just a bold row — same typography, same height.
+      def header_height_mm = show_header? ? row_height_mm : 0.0
+
+      def empty? = collection_rows.blank?
+
+      def rows
+        @rows ||= build_rows
+      end
+
+      def content_height_mm
+        header_height_mm + (rows.size * row_height_mm)
+      end
+
+      private
+
+      attr_reader :element, :collection_rows, :definition
+
+      def config
+        @config ||= element['config'].is_a?(Hash) ? element['config'] : {}
+      end
+
+      def total_column_width_mm
+        @total_column_width_mm ||= columns.sum { |column| column['width_mm'] }
+      end
+
+      def build_column(column)
+        {
+          'key' => column['key'],
+          'label' => column['label'],
+          'width_mm' => column['width_mm'].to_f,
+          'align' => column['align']
+        }
+      end
+
+      def build_rows
+        return [] if empty?
+
+        collection_rows.map do |row|
+          columns.each_with_object({}) do |column, cells|
+            key = column['key']
+            cells[key] = format_cell(key, row[key])
+          end
+        end
+      end
+
+      # The declared column type wins; otherwise the value's class decides. The gem does not
+      # know what "unit_price" means — the host's variables class does.
+      def format_cell(key, value)
+        case definition&.column_type(key) || TypeInference.call(value)
+        when :currency then format_currency(value)
+        else value.to_s
+        end
+      end
+
+      def format_currency(value)
+        return '' if value.nil?
+
+        number_to_currency(value, unit: NtiReceiptBuilder.config.currency_unit)
+      rescue StandardError
+        value.to_s
+      end
+    end
+  end
+end

data/lib/nti_receipt_builder/presenters/element.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module NtiReceiptBuilder
+  module Presenters
+    # Presents one `variable` or `text` layout element: a whitelisted inline style string and
+    # a plain (un-escaped-by-us) display string. ERB's default auto-escaping in the render
+    # partials is what actually escapes the text — this presenter never marks anything
+    # html_safe.
+    class Element
+      def initialize(element, resolved_variables)
+        @element = element
+        @resolved_variables = resolved_variables
+      end
+
+      def id = element['id']
+      def type = element['type']
+      def x_mm = element['x_mm'].to_f
+      def y_mm = element['y_mm'].to_f
+      def width_mm = element['width_mm'].to_f
+      def height_mm = element['height_mm'].to_f
+      def z_index = element['z_index'] || 0
+
+      def css_style
+        declarations = [
+          'position: absolute',
+          "left: #{x_mm}mm",
+          "top: #{y_mm}mm",
+          "width: #{width_mm}mm",
+          "height: #{height_mm}mm",
+          "z-index: #{z_index}"
+        ]
+        declarations.concat(style_declarations).join('; ')
+      end
+
+      def display_text
+        case type
+        when 'variable' then variable_display_text
+        when 'text' then element['text'].to_s
+        end
+      end
+
+      private
+
+      attr_reader :element, :resolved_variables
+
+      def style_declarations
+        styles = element['styles']
+        return [] unless styles.is_a?(Hash)
+
+        styles.filter_map do |key, value|
+          case key
+          when 'font_size_pt' then "font-size: #{value}pt"
+          when 'font_weight' then "font-weight: #{value}"
+          when 'text_align' then "text-align: #{value}"
+          when 'line_height' then "line-height: #{value}"
+          end
+        end
+      end
+
+      def variable_display_text
+        value = resolved_variables[element['variable_key']]
+        value = element['fallback'] if value.blank?
+
+        "#{element['prefix']}#{value}#{element['suffix']}"
+      end
+    end
+  end
+end

data/lib/nti_receipt_builder/render_result.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module NtiReceiptBuilder
+  # The output of one render: presenters in paint order, whether the content overflows the
+  # printable area, and how tall it actually is. Not cached — one per render, holding no
+  # references after the response.
+  class RenderResult
+    attr_reader :elements, :content_height_mm
+
+    def initialize(elements:, overflow:, content_height_mm:)
+      @elements = elements
+      @overflow = overflow
+      @content_height_mm = content_height_mm
+    end
+
+    def overflow? = @overflow
+  end
+end

data/lib/nti_receipt_builder/renderer.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module NtiReceiptBuilder
+  # The single entry point that assembles a template's visible layout elements into
+  # presenters. The designer preview and the printed receipt both call this — never two
+  # divergent render code paths.
+  #
+  # Pass a receipt_object for real data; omit it and the configured variables class supplies
+  # samples, without calling any mapping method.
+  class Renderer
+    def initialize(template:, receipt_object: nil, variables_class: NtiReceiptBuilder.variables_class)
+      @template = template
+      @receipt_object = receipt_object
+      @variables_class = variables_class
+    end
+
+    def call
+      data = resolve_data
+      resolved_variables = VariableResolver.new(data, definitions: variables_class.definitions).call
+      collection_rows = collection_key ? data[collection_key] || [] : []
+
+      presenters = visible_elements
+                   .map { |element| build_presenter(element, resolved_variables, collection_rows) }
+                   .sort_by(&:z_index)
+
+      RenderResult.new(
+        elements: presenters,
+        overflow: overflow?(presenters),
+        content_height_mm: content_height_mm(presenters)
+      )
+    end
+
+    private
+
+    attr_reader :template, :receipt_object, :variables_class
+
+    def resolve_data
+      return variables_class.sample_data if receipt_object.nil?
+
+      variables_class.new(receipt_object).resolve
+    end
+
+    def collection_key = variables_class.collection_key
+
+    def visible_elements
+      (template.layout || []).select { |element| element.fetch('visible', true) }
+    end
+
+    def build_presenter(element, resolved_variables, collection_rows)
+      if element['type'] == 'order_lines'
+        Presenters::Collection.new(element, collection_rows, definition: variables_class.collection_definition)
+      else
+        Presenters::Element.new(element, resolved_variables)
+      end
+    end
+
+    def bottom_edge_mm(presenter)
+      if presenter.is_a?(Presenters::Collection)
+        presenter.y_mm + presenter.content_height_mm
+      else
+        presenter.y_mm + presenter.height_mm
+      end
+    end
+
+    def content_height_mm(presenters)
+      return 0.0 if presenters.empty?
+
+      presenters.map { |presenter| bottom_edge_mm(presenter) }.max
+    end
+
+    def overflow?(presenters)
+      return false if template.content_layout?
+
+      available_height_mm = template.paper_height_mm.to_f - template.margin_bottom_mm.to_f
+      content_height_mm(presenters) > available_height_mm
+    end
+  end
+end

data/lib/nti_receipt_builder/set_default.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module NtiReceiptBuilder
+  # Makes one template the owner's default, clearing any previous default in a single UPDATE
+  # rather than loading the collection.
+  class SetDefault
+    def initialize(template:)
+      @template = template
+    end
+
+    def call
+      template.class
+              .where(owner_type: template.owner_type, owner_id: template.owner_id, is_default: true)
+              .where.not(id: template.id)
+              .update_all(is_default: false, updated_at: Time.current)
+
+      template.update!(is_default: true) unless template.is_default?
+    end
+
+    private
+
+    attr_reader :template
+  end
+end

data/lib/nti_receipt_builder/template_form.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require 'active_model'
+require 'json'
+
+module NtiReceiptBuilder
+  # Validates and coerces submitted template params.
+  #
+  # `layout` arrives as a JSON string from the builder's hidden field. Unparseable JSON is
+  # rejected rather than silently dropped — a designer whose layout failed to serialise must
+  # see an error, not a blank receipt.
+  class TemplateForm
+    include ActiveModel::Model
+
+    ATTRIBUTES = %i[name paper_size_key paper_width_mm paper_height_mm orientation height_mode
+                    margin_top_mm margin_right_mm margin_bottom_mm margin_left_mm layout
+                    lock_version].freeze
+
+    attr_accessor(*ATTRIBUTES)
+
+    validates :name, :paper_size_key, :orientation, :height_mode, presence: true
+    validates :paper_width_mm, :paper_height_mm, presence: true
+    validate :layout_must_be_valid_json
+
+    def attributes
+      {
+        name: name,
+        paper_size_key: paper_size_key,
+        paper_width_mm: paper_width_mm,
+        paper_height_mm: paper_height_mm,
+        orientation: orientation,
+        height_mode: height_mode,
+        margin_top_mm: margin_top_mm.presence || 0,
+        margin_right_mm: margin_right_mm.presence || 0,
+        margin_bottom_mm: margin_bottom_mm.presence || 0,
+        margin_left_mm: margin_left_mm.presence || 0,
+        layout: parsed_layout
+      }.tap { |attrs| attrs[:lock_version] = lock_version if lock_version.present? }
+    end
+
+    def parsed_layout
+      return [] if layout.blank?
+      return layout if layout.is_a?(Array)
+
+      JSON.parse(layout)
+    rescue JSON::ParserError
+      []
+    end
+
+    private
+
+    def layout_must_be_valid_json
+      return if layout.blank? || layout.is_a?(Array)
+
+      JSON.parse(layout)
+    rescue JSON::ParserError
+      errors.add(:layout, 'must be valid JSON')
+    end
+  end
+end

data/lib/nti_receipt_builder/type_inference.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require 'bigdecimal'
+
+module NtiReceiptBuilder
+  # Maps a resolved value to the formatting type used by VariableResolver and the collection
+  # presenter. Inference is the default so a host declares nothing for the common cases; a
+  # Variables subclass overrides it per key with `variable KEY, type: :currency`.
+  #
+  # Deciding at format time rather than declaration time means real data and preview samples
+  # travel the same path.
+  module TypeInference
+    module_function
+
+    def call(value)
+      case value
+      when nil then nil
+      when Array then :collection
+      when BigDecimal then :currency
+      when Numeric then :number
+      else
+        value.respond_to?(:strftime) ? :datetime : :string
+      end
+    end
+  end
+end