nti_receipt_builder 0.1.0

data/lib/nti_receipt_builder/variable_definition.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module NtiReceiptBuilder
+  # One receipt placeholder: where its value comes from, how it is labelled, how it is
+  # formatted, and what stands in for it in the designer preview.
+  #
+  # Frozen on construction — these are read on every render and must never be mutated.
+  class VariableDefinition
+    DEFAULT_SAMPLE_ROW_COUNT = 3
+    # Matches the builder's default order_lines element width, so freshly dropped tables fill it.
+    DEFAULT_COLLECTION_WIDTH_MM = 60.0
+    DEFAULT_COLUMN_ALIGN = 'left'
+
+    attr_reader :key, :method_name, :label, :type, :columns
+
+    def initialize(key:, method_name:, label:, type: nil, sample: nil, columns: nil)
+      @key = -key.to_s
+      @method_name = -method_name.to_s
+      @label = -label.to_s
+      @type = type
+      @sample = sample
+      @columns = columns
+      freeze
+    end
+
+    # A variable that declares `columns:` IS the collection — there is no separate marker.
+    def collection? = !@columns.nil?
+
+    def column_keys = collection? ? @columns.keys : []
+
+    def column_label(column_key)
+      @columns&.dig(column_key, :label) || column_key.to_s.titleize
+    end
+
+    def column_type(column_key)
+      @columns&.dig(column_key, :type)
+    end
+
+    # The column set the builder uses when a designer drops a fresh table onto the canvas.
+    # Without this the builder would have to hardcode column keys, and any host whose columns
+    # differ would get a layout its own validator rejects.
+    def default_columns_config
+      return [] unless collection?
+
+      even_width_mm = (DEFAULT_COLLECTION_WIDTH_MM / column_keys.size).round(2)
+
+      column_keys.map do |column_key|
+        {
+          'key' => column_key,
+          'label' => column_label(column_key),
+          'width_mm' => @columns.dig(column_key, :width_mm) || even_width_mm,
+          'align' => @columns.dig(column_key, :align) || DEFAULT_COLUMN_ALIGN
+        }
+      end
+    end
+
+    # The declared sample, or a derived stand-in. Only ever called on the preview path, so
+    # nothing is memoised — a frozen object cannot memoise, and previews are not hot.
+    def sample
+      declared = @sample.respond_to?(:call) ? @sample.call : @sample
+      return declared unless declared.nil?
+
+      collection? ? derived_collection_sample : label
+    end
+
+    private
+
+    def derived_collection_sample
+      Array.new(DEFAULT_SAMPLE_ROW_COUNT) do |index|
+        column_keys.index_with { |column_key| "#{column_label(column_key)} #{index + 1}" }
+      end
+    end
+  end
+end

data/lib/nti_receipt_builder/variable_resolver.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require 'action_view'
+
+module NtiReceiptBuilder
+  # Resolves every scalar variable to a formatted (not yet escaped) string. Missing keys
+  # resolve to nil so presenters can apply their own fallback.
+  #
+  # A declared type wins; otherwise the value's class decides. Collection variables are
+  # skipped — the collection presenter formats its own cells.
+  class VariableResolver
+    include ActionView::Helpers::NumberHelper
+
+    def initialize(data, definitions:)
+      @data = data || {}
+      @definitions = definitions
+    end
+
+    def call
+      definitions.each_with_object({}) do |(key, definition), resolved|
+        next if definition.collection?
+
+        resolved[key] = format_value(definition, data[key])
+      end
+    end
+
+    private
+
+    attr_reader :data, :definitions
+
+    def format_value(definition, value)
+      return nil if value.nil?
+
+      case definition.type || TypeInference.call(value)
+      when :currency then format_currency(value)
+      when :datetime then format_datetime(value)
+      else value.to_s
+      end
+    end
+
+    def format_currency(value)
+      number_to_currency(value, unit: NtiReceiptBuilder.config.currency_unit)
+    rescue StandardError
+      nil
+    end
+
+    def format_datetime(value)
+      return value.to_s unless value.respond_to?(:strftime)
+
+      value.strftime(NtiReceiptBuilder.config.datetime_format)
+    rescue StandardError
+      nil
+    end
+  end
+end

data/lib/nti_receipt_builder/variables.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+module NtiReceiptBuilder
+  # Base class for a host application's receipt variable vocabulary.
+  #
+  #   class OrderReceiptVariables < NtiReceiptBuilder::Variables
+  #     MAPPINGS = {
+  #       'ORDER_REFERENCE' => 'order_reference',
+  #       'STORE_NAME'      => 'store_name'
+  #     }.freeze
+  #
+  #     def order_reference = receipt_object.reference
+  #     def store_name      = receipt_object.address.name
+  #   end
+  #
+  # MAPPINGS supplies the placeholder keys and the method producing each value. Everything
+  # else — label, formatting type, preview sample — is derived, and overridden per key with
+  # `variable`. The key that declares `columns:` is the collection.
+  #
+  # The schema is built once on first read and frozen, so render-path reads take no lock.
+  # It is memoised on the subclass itself, so a host code reload discards it along with the
+  # class it describes — there is no separate cache to invalidate and nothing that outlives
+  # what it points at.
+  class Variables
+    Schema = Struct.new(:definitions, :labels, :scalar_keys, :collection_key, keyword_init: true)
+    private_constant :Schema
+
+    class << self
+      # Override any derived aspect of a key already present in MAPPINGS.
+      #
+      #   variable 'ORDER_DATETIME', label: 'Order Date/Time', sample: -> { Time.current }
+      #   variable 'ORDER_LINES',    columns: { 'description' => { label: 'Item' } }
+      #
+      # Column options: label:, type:, width_mm:, align: — all optional.
+      def variable(key, label: nil, type: nil, sample: nil, columns: nil)
+        overrides[key.to_s] = { label: label, type: type, sample: sample, columns: columns }
+        @schema = nil
+        self
+      end
+
+      def definitions = schema.definitions
+      def labels = schema.labels
+      def scalar_keys = schema.scalar_keys
+      def collection_key = schema.collection_key
+      def keys = definitions.keys
+      def collection_definition = collection_key && definitions[collection_key]
+
+      def sample_data
+        definitions.transform_values(&:sample)
+      end
+
+      def overrides
+        @overrides ||= {}
+      end
+
+      private
+
+      def schema
+        @schema ||= build_schema
+      end
+
+      def mappings
+        unless const_defined?(:MAPPINGS, false)
+          raise InvalidVariablesError, "#{inspect} must define a MAPPINGS constant"
+        end
+
+        const_get(:MAPPINGS, false)
+      end
+
+      def build_schema
+        raw = mappings
+        raise InvalidVariablesError, "#{inspect}: MAPPINGS must be a Hash" unless raw.is_a?(Hash)
+
+        validate_override_keys!(raw)
+        validate_mapped_methods!(raw)
+
+        definitions = build_definitions(raw)
+        validate_single_collection!(definitions)
+
+        Schema.new(
+          definitions: definitions,
+          labels: definitions.transform_values(&:label).freeze,
+          scalar_keys: definitions.reject { |_, definition| definition.collection? }.keys.freeze,
+          collection_key: definitions.each_value.find(&:collection?)&.key
+        ).freeze
+      end
+
+      def build_definitions(raw)
+        raw.each_with_object({}) do |(key, method_name), acc|
+          string_key = key.to_s
+          override = overrides.fetch(string_key, {})
+
+          acc[string_key] = VariableDefinition.new(
+            key: string_key,
+            method_name: method_name,
+            label: override[:label] || string_key.titleize,
+            type: override[:type],
+            sample: override[:sample],
+            columns: normalize_columns(override[:columns])
+          )
+        end.freeze
+      end
+
+      def normalize_columns(columns)
+        return nil if columns.nil?
+
+        columns.each_with_object({}) do |(column_key, options), acc|
+          acc[column_key.to_s] = {
+            label: options[:label],
+            type: options[:type],
+            width_mm: options[:width_mm],
+            align: options[:align]
+          }.compact.freeze
+        end.freeze
+      end
+
+      def validate_override_keys!(raw)
+        unknown = overrides.keys - raw.keys.map(&:to_s)
+        return if unknown.empty?
+
+        raise InvalidVariablesError,
+              "#{inspect}: `variable` called for keys not in MAPPINGS: #{unknown.join(', ')}"
+      end
+
+      def validate_mapped_methods!(raw)
+        missing = raw.values.map(&:to_s).reject do |method_name|
+          method_defined?(method_name) || private_method_defined?(method_name)
+        end
+        return if missing.empty?
+
+        raise InvalidVariablesError,
+              "#{inspect}: MAPPINGS references undefined methods: #{missing.join(', ')}"
+      end
+
+      def validate_single_collection!(definitions)
+        collections = definitions.each_value.select(&:collection?).map(&:key)
+        return if collections.size <= 1
+
+        raise InvalidVariablesError,
+              "#{inspect}: only one variable may declare `columns:` (got #{collections.join(', ')})"
+      end
+    end
+
+    attr_reader :receipt_object
+
+    def initialize(receipt_object)
+      @receipt_object = receipt_object
+    end
+
+    # Raw values, unformatted — VariableResolver applies formatting. An error raised by a
+    # mapping method propagates deliberately: a receipt printing silently without its total
+    # is worse than a visible failure.
+    def resolve
+      self.class.definitions.each_with_object({}) do |(key, definition), acc|
+        acc[key] = send(definition.method_name)
+      end
+    end
+  end
+end

data/lib/nti_receipt_builder/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module NtiReceiptBuilder
+  VERSION = '0.1.0'
+end

data/lib/nti_receipt_builder.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require 'active_support'
+require 'active_support/core_ext/string/inflections'
+require 'active_support/core_ext/object/blank'
+require 'active_support/core_ext/enumerable'
+
+require_relative 'nti_receipt_builder/version'
+require_relative 'nti_receipt_builder/errors'
+require_relative 'nti_receipt_builder/configuration'
+require_relative 'nti_receipt_builder/type_inference'
+require_relative 'nti_receipt_builder/variable_definition'
+require_relative 'nti_receipt_builder/variables'
+require_relative 'nti_receipt_builder/elements'
+require_relative 'nti_receipt_builder/layout_validator'
+require_relative 'nti_receipt_builder/variable_resolver'
+require_relative 'nti_receipt_builder/presenters/element'
+require_relative 'nti_receipt_builder/presenters/collection'
+require_relative 'nti_receipt_builder/render_result'
+require_relative 'nti_receipt_builder/renderer'
+require_relative 'nti_receipt_builder/set_default'
+require_relative 'nti_receipt_builder/template_form'
+require_relative 'nti_receipt_builder/engine' if defined?(Rails::Engine)
+
+# A receipt template builder and renderer.
+#
+#   NtiReceiptBuilder.configure { |config| config.variables_class = OrderReceiptVariables }
+#
+# The configured Variables subclass supplies the placeholder vocabulary, so the gem itself
+# carries no domain terms. See NtiReceiptBuilder::Variables.
+module NtiReceiptBuilder
+  class << self
+    def configure
+      yield(config) if block_given?
+      config
+    end
+
+    def config
+      @config ||= Configuration.new
+    end
+
+    # Resets configuration to defaults. Intended for test suites.
+    def reset_config!
+      @config = Configuration.new
+    end
+
+    def variables_class = config.variables_class
+    def template_class = config.template_class
+  end
+end

metadata

@@ -0,0 +1,175 @@
+--- !ruby/object:Gem::Specification
+name: nti_receipt_builder
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Den Meralpis
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: actionview
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: activemodel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+description: NtiReceiptBuilder ships a complete receipt designer — model, layout validation,
+  millimetre-accurate renderer, Stimulus builder UI and print views — as a Rails engine.
+  Host applications declare a Variables subclass that maps receipt placeholders to
+  methods on their own receipt object, so the gem carries no domain vocabulary of
+  its own.
+email:
+- denmark@nueca.com.ph
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- app/assets/javascripts/nti_receipt_builder/index.js
+- app/assets/javascripts/nti_receipt_builder/receipt_builder_controller.js
+- app/assets/javascripts/nti_receipt_builder/receipt_canvas_controller.js
+- app/assets/javascripts/nti_receipt_builder/receipt_draggable_controller.js
+- app/assets/javascripts/nti_receipt_builder/receipt_print_controller.js
+- app/assets/javascripts/nti_receipt_builder/receipt_properties_controller.js
+- app/assets/stylesheets/nti_receipt_builder.css
+- app/controllers/concerns/nti_receipt_builder/templates_controller.rb
+- app/helpers/nti_receipt_builder/render_helper.rb
+- app/models/nti_receipt_builder/template.rb
+- app/views/nti_receipt_builder/render/_order_lines_element.html.erb
+- app/views/nti_receipt_builder/render/_overflow_banner.html.erb
+- app/views/nti_receipt_builder/render/_paper.html.erb
+- app/views/nti_receipt_builder/render/_text_element.html.erb
+- app/views/nti_receipt_builder/render/_variable_element.html.erb
+- app/views/nti_receipt_builder/templates/_canvas.html.erb
+- app/views/nti_receipt_builder/templates/_elements_panel.html.erb
+- app/views/nti_receipt_builder/templates/_errors.html.erb
+- app/views/nti_receipt_builder/templates/_lock_version_field.html.erb
+- app/views/nti_receipt_builder/templates/_print_assets.html.erb
+- app/views/nti_receipt_builder/templates/_properties_panel.html.erb
+- app/views/nti_receipt_builder/templates/_settings_panel.html.erb
+- app/views/nti_receipt_builder/templates/create.turbo_stream.erb
+- app/views/nti_receipt_builder/templates/edit.html.erb
+- app/views/nti_receipt_builder/templates/new.html.erb
+- app/views/nti_receipt_builder/templates/preview.html.erb
+- app/views/nti_receipt_builder/templates/print.html.erb
+- app/views/nti_receipt_builder/templates/render_preview.turbo_stream.erb
+- app/views/nti_receipt_builder/templates/update.turbo_stream.erb
+- config/importmap.rb
+- lib/generators/nti_receipt_builder/install_generator.rb
+- lib/generators/nti_receipt_builder/templates/create_nti_receipt_templates.rb
+- lib/generators/nti_receipt_builder/templates/initializer.rb
+- lib/generators/nti_receipt_builder/templates/turbo_stream_tags.rb
+- lib/nti_receipt_builder.rb
+- lib/nti_receipt_builder/configuration.rb
+- lib/nti_receipt_builder/elements.rb
+- lib/nti_receipt_builder/engine.rb
+- lib/nti_receipt_builder/errors.rb
+- lib/nti_receipt_builder/layout_validator.rb
+- lib/nti_receipt_builder/presenters/collection.rb
+- lib/nti_receipt_builder/presenters/element.rb
+- lib/nti_receipt_builder/render_result.rb
+- lib/nti_receipt_builder/renderer.rb
+- lib/nti_receipt_builder/set_default.rb
+- lib/nti_receipt_builder/template_form.rb
+- lib/nti_receipt_builder/type_inference.rb
+- lib/nti_receipt_builder/variable_definition.rb
+- lib/nti_receipt_builder/variable_resolver.rb
+- lib/nti_receipt_builder/variables.rb
+- lib/nti_receipt_builder/version.rb
+homepage: https://github.com/nueca-tech/nti_receipt_builder
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/nueca-tech/nti_receipt_builder
+  source_code_uri: https://github.com/nueca-tech/nti_receipt_builder
+  changelog_uri: https://github.com/nueca-tech/nti_receipt_builder/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.4.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: A drag-and-drop receipt template builder and renderer for Rails.
+test_files: []