nti_receipt_builder 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4493131823c3d523ede3d5e0c57b77caf81245f191dca1019ba5536cdf1dbc55
+  data.tar.gz: ce594bac64cd068754246e4cf62b90eed741e87c3dc5224dcdd570da267616db
+SHA512:
+  metadata.gz: e8b7e1012da9720f4bba538fd3363a93fe4d349c75f6fd8de4c7d66c5dbc094c08b62603e643ebd19579494af386ed9931e9551dab09193cf2becf610006bbce
+  data.tar.gz: 916a9a7b7f8d7101e663227821564cd5d9391352189c95e465e16d5bd41069cbbcef1cfc915c17dcd481a70f7aac3e7ab37112619439b9b4c33adbc16ec5f61b

data/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+## [0.1.0] - 2026-08-02
+
+Initial release, extracted from SalesWiz's receipt builder.
+
+- `NtiReceiptBuilder::Variables` — host-declared receipt vocabulary. `MAPPINGS` supplies keys
+  and value methods; label, formatting type and preview sample are derived and overridable per
+  key with `variable`. The key declaring `columns:` is the collection.
+- `NtiReceiptBuilder::Template` — paper geometry, validations and jsonb layout, with
+  `inheritance_column = nil` so hosts can subclass and share the table without STI.
+- `NtiReceiptBuilder::LayoutValidator` — structural and whitelist validation driven by the
+  host's declared variable and column keys.
+- `NtiReceiptBuilder::Renderer` — one render path for both the designer preview and printed
+  output; omit `receipt_object:` to render declared samples.
+- `NtiReceiptBuilder::TemplatesController` — the builder's actions as a concern, scoped through
+  an abstract `receipt_owner` the host must define.
+- Builder UI: five Stimulus controllers, builder and print views, and a `nrb-receipt-*`
+  stylesheet themable via `--nrb-accent`.
+- `rails generate nti_receipt_builder:install` — initializer, migration, and Turbo Stream
+  helpers for hosts that lack them.

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,10 @@
+# Code of Conduct
+
+"nti_receipt_builder" follows [The Ruby Community Conduct Guideline](https://www.ruby-lang.org/en/conduct) in all "collaborative space", which is defined as community communications channels (such as mailing lists, submitted patches, commit comments, etc.):
+
+* Participants will be tolerant of opposing views.
+* Participants must ensure that their language and actions are free of personal attacks and disparaging personal remarks.
+* When interpreting the words and actions of others, participants should always assume good intentions.
+* Behaviour which can be reasonably considered harassment will not be tolerated.
+
+If you have any concerns about behaviour within this project, please contact us at ["denmarkmeralpis@gmail.com"](mailto:"denmarkmeralpis@gmail.com").

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Den Meralpis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,272 @@
+# NtiReceiptBuilder
+
+A drag-and-drop receipt template designer and millimetre-accurate renderer, packaged as a
+Rails engine.
+
+The gem ships the whole vertical — model, layout validation, renderer, print views, and a
+Stimulus builder UI — but carries **no domain vocabulary of its own**. Your application
+declares a `Variables` subclass mapping receipt placeholders to methods on whatever object it
+prints receipts for, and the gem drives the designer, the validator and the renderer from it.
+
+## Installation
+
+```ruby
+# Gemfile
+gem 'nti_receipt_builder'
+```
+
+```bash
+bundle install
+bin/rails generate nti_receipt_builder:install
+bin/rails db:migrate
+```
+
+The generator creates:
+
+- `config/initializers/nti_receipt_builder.rb`
+- a migration creating `nti_receipt_templates`
+- `config/initializers/turbo_stream_tags.rb` — **skipped** if your app already defines
+  `open_modal` on `Turbo::Streams::TagBuilder`
+
+## Declaring your variables
+
+`MAPPINGS` supplies the placeholder keys and the method that produces each value. Everything
+else is derived, and overridden per key with `variable` only where the derived default is
+wrong.
+
+```ruby
+class OrderReceiptVariables < NtiReceiptBuilder::Variables
+  MAPPINGS = {
+    'CUSTOMER_NAME'   => 'customer_name',
+    'ORDER_REFERENCE' => 'order_reference',
+    'ORDER_SUBTOTAL'  => 'order_subtotal',
+    'ORDER_DATETIME'  => 'order_datetime',
+    'ORDER_LINES'     => 'order_lines'
+  }.freeze
+
+  variable 'CUSTOMER_NAME',  sample: 'Juan Dela Cruz'
+  variable 'ORDER_SUBTOTAL', sample: BigDecimal('275.00')
+  variable 'ORDER_DATETIME', label: 'Order Date/Time',
+                             sample: -> { Time.zone.local(2026, 7, 31, 14, 32) }
+  variable 'ORDER_LINES', columns: {
+    'description' => { label: 'Description', width_mm: 24 },
+    'quantity'    => { label: 'Qty',         width_mm: 8,  align: 'center' },
+    'unit_price'  => { label: 'Unit Price',  width_mm: 12, align: 'right' },
+    'line_total'  => { label: 'Total',       width_mm: 12, align: 'right' }
+  }
+
+  def customer_name   = receipt_object.customer.name
+  def order_reference = receipt_object.reference
+  def order_subtotal  = receipt_object.subtotal
+  def order_datetime  = receipt_object.created_at
+
+  def order_lines
+    receipt_object.order_lines.order(:order_line_number).map do |line|
+      { 'description' => line.product_name, 'quantity'   => line.quantity,
+        'unit_price'  => line.retail_price,  'line_total' => line.subtotal }
+    end
+  end
+end
+```
+
+`receipt_object` is whatever you pass to the renderer — an order, an invoice, a booking.
+
+### What is derived, and what you can override
+
+| Aspect | Derived default | Override |
+|---|---|---|
+| Label | `key.titleize` — `'STORE_NAME'` → `'Store Name'` | `label:` |
+| Formatting type | the value's class at render time: `BigDecimal` → currency, responds to `strftime` → datetime, `Array` → collection, other `Numeric` → plain, else string | `type:` |
+| Preview sample | the label as a string; a collection gets three filler rows | `sample:` — a value or a lambda |
+| Collection | the one key declaring `columns:` **is** the collection | — |
+
+Type is decided at format time, not declaration time, so real data and preview samples travel
+the same path. `type:` exists for the cases inference cannot get right — a pre-formatted
+`String` that should be currency, say.
+
+Column options are `label:`, `type:`, `width_mm:` and `align:`, all optional. They whitelist
+the column keys a saved layout may use, seed the builder when a designer drops a fresh table,
+and decide cell formatting.
+
+A malformed class fails when its schema is first read — missing `MAPPINGS`, a mapped method
+that does not exist, a `variable` call for a key absent from `MAPPINGS`, or two keys declaring
+`columns:` all raise `NtiReceiptBuilder::InvalidVariablesError`. Typos surface in development
+rather than at print time.
+
+An error raised inside a mapping method propagates. That is deliberate: a receipt printing
+silently without its total is worse than a visible failure.
+
+## Configuration
+
+```ruby
+NtiReceiptBuilder.configure do |config|
+  config.variables_class = 'OrderReceiptVariables'   # required
+  config.template_class  = 'ReceiptTemplate'         # default 'NtiReceiptBuilder::Template'
+  config.currency_unit   = '₱'
+  config.datetime_format = '%m/%d/%Y %I:%M %p'
+  config.print_stylesheet = 'nti_receipt_builder'    # nil to load none
+end
+```
+
+Class references may be given as a `Class` or a `String`; either way the gem retains only the
+**name** and resolves it per access. Holding a reloadable application class in configuration
+would pin that class and its constant tree past every development reload, and would serve a
+stale class after your code reloads.
+
+## Wiring a controller
+
+The gem ships its actions as a concern. Your controller keeps routing, authorization and
+tenant scoping.
+
+```ruby
+class Partner::ReceiptTemplatesController < PartnerController
+  include NtiReceiptBuilder::TemplatesController
+
+  def index
+    # yours — datatable, decorators, whatever you already use
+  end
+
+  private
+
+  def receipt_owner = current_account
+end
+```
+
+```ruby
+# config/routes.rb
+resources :receipt_templates do
+  member do
+    get   :preview
+    post  :render_preview
+    get   :print
+    patch :set_default
+  end
+end
+```
+
+`receipt_owner` is mandatory: every query the concern makes is scoped through it, so the
+tenant boundary stays visible in your code rather than in a configured lambda. A controller
+that omits it raises `NotImplementedError` instead of running an unscoped query.
+
+The concern provides `new`, `create`, `edit`, `update`, `destroy`, `preview`,
+`render_preview`, `print` and `set_default`. Define any of them in your controller to take
+over — a method on the including class wins. SalesWiz overrides `destroy`, for instance, to
+archive rather than delete. The navigation hooks `after_create_path`, `after_destroy_path` and
+`after_set_default_path` are overridable too, and worth overriding if you have named routes.
+
+### Subclassing the model
+
+Point `template_class` at a subclass to attach your own concerns while sharing the table:
+
+```ruby
+class ReceiptTemplate < NtiReceiptBuilder::Template
+  # See the note below — these two lines go together.
+  def self.base_class = self
+  self.table_name = 'nti_receipt_templates'
+
+  include Auditable
+  has_assignable_status
+
+  validates :is_default, uniqueness: { scope: %i[owner_type owner_id],
+                                       conditions: -> { where(is_default: true) } }
+end
+```
+
+The parent sets `inheritance_column = nil`, so the subclass shares `nti_receipt_templates`
+with no STI type condition and no `type` column to maintain. Host-specific columns go in your
+own migration against the same table.
+
+**If you subclass, override `base_class` and re-declare the table.** Rails resolves
+`base_class` up the superclass chain, so without the override it returns
+`NtiReceiptBuilder::Template`. Anything that records a class name from `base_class` —
+PaperTrail's `item_type`, polymorphic `*_type` columns — would then store the gem's class name
+rather than yours, and your own queries would not find those rows. Returning `self` is safe
+precisely because there is no STI to disturb.
+
+The two lines are a pair: once the subclass is its own `base_class`, Rails derives the table
+name from *it*, which would give `receipt_templates`. Naming the engine's table explicitly
+keeps them on the same rows.
+
+### Overriding a view
+
+Host view prefixes are searched before the gem's, so dropping
+`app/views/partner/receipt_templates/edit.html.erb` into your app shadows the gem's copy with
+no configuration. The same trick works for `_print_assets.html.erb` if you want exact control
+over what the standalone print document loads.
+
+## Rendering a receipt
+
+```ruby
+@render_result = NtiReceiptBuilder::Renderer.new(
+  template: template, receipt_object: order
+).call
+
+render template: 'nti_receipt_builder/templates/print', layout: false
+```
+
+Omit `receipt_object:` and the renderer uses your declared samples without calling a single
+mapping method — that is what the designer's preview does.
+
+`RenderResult` exposes `elements` (presenters in paint order), `overflow?` and
+`content_height_mm`. Preload whatever associations your scalar mappings traverse; the gem
+cannot know them.
+
+## JavaScript and CSS
+
+```js
+// app/javascript/controllers/index.js
+import { registerNtiReceiptBuilder } from 'nti_receipt_builder'
+
+registerNtiReceiptBuilder(application)
+```
+
+```css
+/* app/assets/stylesheets/application.css */
+@import 'nti_receipt_builder';
+```
+
+Identifiers are `nrb-builder`, `nrb-canvas`, `nrb-draggable`, `nrb-print` and `nrb-properties`.
+Set `--nrb-accent` and `--nrb-accent-rgb` to tint the builder's selection and palette
+affordances; both fall back to Tabler's primary.
+
+## Host requirements
+
+1. **Tabler 1.x with Bootstrap JS** in the layout — the builder chrome uses Tabler's card,
+   button and form classes, and the preview modal uses Bootstrap's dismiss behaviour.
+2. **`Turbo::Streams::TagBuilder` responding to** `open_modal(size:, &block)`, `close_modal`,
+   `toast(message, type:)` and `reload_datatable(id)`, with matching `turbo_stream` action
+   handlers in your JavaScript. The install generator supplies these if you lack them.
+3. **`receipt_owner`** on the controller including the concern.
+4. Optional: a global `window.Toast` with `.warning(message)` for the element-limit notice.
+   The builder degrades silently without it.
+5. Optional: the `material-symbols-outlined` icon font, used for palette and toolbar icons.
+
+## Limits
+
+Enforced by `LayoutValidator` before anything persists, which is what bounds the memory a
+single template can consume:
+
+| Limit | Value |
+|---|---|
+| Elements per template | 60 |
+| Minimum element dimension | 1.0mm |
+| Text length | 500 |
+| Fallback / prefix / suffix | 200 / 50 / 50 |
+| Order-line columns | 1–6 |
+| Font size | 6–72pt |
+| `z-index` | 0–1000 |
+
+## Development
+
+```bash
+bin/setup
+createdb nti_receipt_builder_test    # specs need PostgreSQL — layout is jsonb
+bundle exec rspec
+bundle exec rubocop
+```
+
+Specs run against a minimal dummy Rails app in `spec/dummy`.
+
+## License
+
+MIT.

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+require 'rubocop/rake_task'
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/app/assets/javascripts/nti_receipt_builder/index.js

@@ -0,0 +1,16 @@
+import ReceiptBuilderController from "nti_receipt_builder/receipt_builder_controller"
+import ReceiptCanvasController from "nti_receipt_builder/receipt_canvas_controller"
+import ReceiptDraggableController from "nti_receipt_builder/receipt_draggable_controller"
+import ReceiptPrintController from "nti_receipt_builder/receipt_print_controller"
+import ReceiptPropertiesController from "nti_receipt_builder/receipt_properties_controller"
+
+// Identifiers are registered explicitly rather than derived from file paths, so they stay short
+// and stable regardless of where a host mounts the gem's JavaScript. They must match the
+// data-controller attributes in the gem's views.
+export function registerNtiReceiptBuilder(application) {
+  application.register("nrb-builder", ReceiptBuilderController)
+  application.register("nrb-canvas", ReceiptCanvasController)
+  application.register("nrb-draggable", ReceiptDraggableController)
+  application.register("nrb-print", ReceiptPrintController)
+  application.register("nrb-properties", ReceiptPropertiesController)
+}

data/app/assets/javascripts/nti_receipt_builder/receipt_builder_controller.js

@@ -0,0 +1,297 @@
+import { Controller } from "@hotwired/stimulus"
+
+const MAX_ELEMENTS = 60
+const Z_INDEX_MAX = 1000
+
+const DEFAULT_DIMENSIONS = {
+  variable: { widthMm: 40, heightMm: 5 },
+  text: { widthMm: 40, heightMm: 6 },
+  order_lines: { widthMm: 60, heightMm: 20 }
+}
+
+// Connects to data-controller="nrb-builder"
+export default class extends Controller {
+  static targets = [
+    "layoutField",
+    "elementCount",
+    "paperSizeSelect",
+    "widthInput",
+    "heightInput",
+    "orientationSelect",
+    "heightModeSelect",
+    "marginTopInput",
+    "marginRightInput",
+    "marginBottomInput",
+    "marginLeftInput"
+  ]
+
+  static values = { layout: Array, presets: Object, collectionColumns: Array }
+  static outlets = ["nrb-canvas", "nrb-properties"]
+
+  initialize() {
+    this.selectedId = null
+    this.paletteDragHandler = null
+  }
+
+  // Stimulus calls this on connect and after every assignment to layoutValue — adding, patching,
+  // moving, resizing and deleting all route through one of those, so the hidden field is never
+  // stale.
+  //
+  // Serialising here rather than on submit is deliberate and load-bearing. Turbo builds the
+  // request body in the FormSubmission constructor, which runs BEFORE turbo:submit-start is
+  // dispatched from requestStarted(). A listener on that event writes the field after the body
+  // has already been snapshotted, so every edit was dropped and the server silently re-saved the
+  // layout the page was rendered with.
+  layoutValueChanged() {
+    this.serializeLayout()
+  }
+
+  disconnect() {
+    this.cancelPaletteDrag()
+  }
+
+  nrbCanvasOutletConnected() {
+    this.renderAll()
+  }
+
+  // Palette drag/drop
+
+  // The pointerup is attached to `document` because the gesture can end anywhere on the page.
+  // `{ once: true }` alone is not enough: if the pointerup never arrives — Turbo navigates away
+  // mid-gesture, or the pointer is released outside the document — the handler stays on
+  // `document` holding a closure over this controller, leaking one listener and one controller
+  // per visit. So keep a reference and detach it in disconnect().
+  cancelPaletteDrag() {
+    if (!this.paletteDragHandler) return
+
+    document.removeEventListener("pointerup", this.paletteDragHandler)
+    this.paletteDragHandler = null
+  }
+
+  startPaletteDrag(event) {
+    event.preventDefault()
+    const type = event.params.type
+    const key = event.params.key || null
+
+    this.cancelPaletteDrag()
+    this.paletteDragHandler = (upEvent) => {
+      this.paletteDragHandler = null
+      this.finishPaletteDrag(upEvent, type, key)
+    }
+    document.addEventListener("pointerup", this.paletteDragHandler, { once: true })
+  }
+
+  finishPaletteDrag(event, type, key) {
+    if (this.layoutValue.length >= MAX_ELEMENTS) {
+      this.showLimitReachedMessage()
+      return
+    }
+
+    const dimensions = DEFAULT_DIMENSIONS[type] || DEFAULT_DIMENSIONS.variable
+    let position = { xMm: 0, yMm: 0 }
+
+    if (this.hasNrbCanvasOutlet) {
+      const canvas = this.nrbCanvasOutlet
+      const target = document.elementFromPoint(event.clientX, event.clientY)
+      const droppedOnPaper = target && target.closest('[data-nrb-canvas-target="paper"]')
+
+      const raw = droppedOnPaper
+        ? canvas.pointToMm(event.clientX, event.clientY)
+        : canvas.centerMm(dimensions.widthMm, dimensions.heightMm)
+
+      position = canvas.clampPosition(raw.xMm, raw.yMm, dimensions.widthMm, dimensions.heightMm)
+    }
+
+    this.addElement(type, key, position, dimensions)
+  }
+
+  addElement(type, key, position, dimensions) {
+    const element = {
+      id: crypto.randomUUID(),
+      type,
+      x_mm: position.xMm,
+      y_mm: position.yMm,
+      width_mm: dimensions.widthMm,
+      height_mm: dimensions.heightMm,
+      z_index: this.nextZIndex(),
+      visible: true
+    }
+
+    if (type === "variable") {
+      element.styles = this.defaultStyles()
+      element.variable_key = key
+      element.fallback = ""
+      element.prefix = ""
+      element.suffix = ""
+    } else if (type === "text") {
+      element.styles = this.defaultStyles()
+      element.text = "New text"
+    } else {
+      element.config = this.defaultOrderLinesConfig()
+    }
+
+    this.layoutValue = [...this.layoutValue, element]
+    this.selectElement(element.id)
+  }
+
+  defaultStyles() {
+    return { font_size_pt: 10, font_weight: "normal", text_align: "left", line_height: 1.2 }
+  }
+
+  // Columns come from the host's variables class, not from here. Hardcoding keys would emit a
+  // layout the server-side validator rejects for any host whose collection differs.
+  defaultOrderLinesConfig() {
+    return {
+      show_header: true,
+      row_spacing_mm: 1.0,
+      font_size_pt: 8,
+      columns: this.collectionColumnsValue.map((column) => ({
+        key: column.key,
+        label: column.label,
+        width_mm: column.width_mm,
+        align: column.align
+      }))
+    }
+  }
+
+  nextZIndex() {
+    const max = this.layoutValue.reduce((acc, element) => Math.max(acc, element.z_index || 0), 0)
+    return Math.min(Z_INDEX_MAX, max + 1)
+  }
+
+  showLimitReachedMessage() {
+    if (window.Toast) window.Toast.warning(`You can add up to ${MAX_ELEMENTS} elements per template.`)
+  }
+
+  // Selection
+
+  elementSelected(event) {
+    this.selectElement(event.detail.id)
+  }
+
+  deselect() {
+    this.selectElement(null)
+  }
+
+  selectElement(id) {
+    if (id === this.selectedId) return
+
+    this.selectedId = id
+    this.renderAll()
+    this.syncProperties()
+  }
+
+  syncProperties() {
+    if (!this.hasNrbPropertiesOutlet) return
+
+    const element = this.selectedId ? this.layoutValue.find((candidate) => candidate.id === this.selectedId) : null
+    this.nrbPropertiesOutlet.render(element || null)
+  }
+
+  // Geometry / property changes
+
+  elementMoved(event) {
+    this.applyPatch(event.detail.id, { x_mm: event.detail.xMm, y_mm: event.detail.yMm })
+  }
+
+  elementResized(event) {
+    this.applyPatch(event.detail.id, {
+      x_mm: event.detail.xMm,
+      y_mm: event.detail.yMm,
+      width_mm: event.detail.widthMm,
+      height_mm: event.detail.heightMm
+    })
+  }
+
+  propertiesChanged(event) {
+    this.applyPatch(event.detail.id, event.detail.patch, { refreshProperties: false })
+  }
+
+  applyPatch(id, patch, { refreshProperties = true } = {}) {
+    this.layoutValue = this.layoutValue.map((element) => (element.id === id ? this.mergePatch(element, patch) : element))
+    this.renderAll()
+    if (refreshProperties && id === this.selectedId) this.syncProperties()
+  }
+
+  mergePatch(element, patch) {
+    const merged = { ...element, ...patch }
+    if (patch.styles) merged.styles = { ...(element.styles || {}), ...patch.styles }
+    if (patch.config) merged.config = { ...(element.config || {}), ...patch.config }
+    return merged
+  }
+
+  removeSelected(event) {
+    const id = (event && event.detail && event.detail.id) || this.selectedId
+    if (!id) return
+
+    this.layoutValue = this.layoutValue.filter((element) => element.id !== id)
+    if (this.selectedId === id) this.selectedId = null
+    this.renderAll()
+    this.syncProperties()
+  }
+
+  // Settings panel reactivity
+
+  settingsChanged() {
+    if (!this.hasNrbCanvasOutlet) return
+    const canvas = this.nrbCanvasOutlet
+
+    if (this.hasWidthInputTarget) {
+      const value = parseFloat(this.widthInputTarget.value)
+      if (!Number.isNaN(value)) canvas.widthMmValue = value
+    }
+    if (this.hasHeightInputTarget) {
+      const value = parseFloat(this.heightInputTarget.value)
+      if (!Number.isNaN(value)) canvas.heightMmValue = value
+    }
+    if (this.hasHeightModeSelectTarget) canvas.heightModeValue = this.heightModeSelectTarget.value
+    if (this.hasMarginTopInputTarget) canvas.marginTopMmValue = parseFloat(this.marginTopInputTarget.value) || 0
+    if (this.hasMarginRightInputTarget) canvas.marginRightMmValue = parseFloat(this.marginRightInputTarget.value) || 0
+    if (this.hasMarginBottomInputTarget) canvas.marginBottomMmValue = parseFloat(this.marginBottomInputTarget.value) || 0
+    if (this.hasMarginLeftInputTarget) canvas.marginLeftMmValue = parseFloat(this.marginLeftInputTarget.value) || 0
+  }
+
+  paperPresetChanged() {
+    const preset = this.presetsValue[this.paperSizeSelectTarget.value]
+    if (!preset) return
+
+    if (this.hasWidthInputTarget) this.widthInputTarget.value = preset.width_mm
+    if (this.hasHeightInputTarget) this.heightInputTarget.value = preset.height_mm
+    if (this.hasOrientationSelectTarget) this.orientationSelectTarget.value = preset.orientation
+
+    this.settingsChanged()
+  }
+
+  // Rendering / serialization
+
+  renderAll() {
+    if (this.hasNrbCanvasOutlet) {
+      this.nrbCanvasOutlet.renderElements(this.layoutValue, this.selectedId)
+    }
+    this.updateElementCount()
+  }
+
+  updateElementCount() {
+    if (!this.hasElementCountTarget) return
+    const count = this.layoutValue.length
+    this.elementCountTarget.textContent = `${count} element${count === 1 ? "" : "s"}`
+  }
+
+  // Guarded because layoutValueChanged fires during initialization, before targets connect. The
+  // field is server-rendered with the current layout, so a skipped first call loses nothing.
+  serializeLayout() {
+    if (!this.hasLayoutFieldTarget) return
+
+    this.layoutFieldTarget.value = JSON.stringify(this.layoutValue)
+  }
+
+  // Last line of defence at submit time, for a layout mutated in place without reassigning
+  // layoutValue. `new FormData(form)` dispatches formdata on the form, so this runs while Turbo
+  // is still assembling the body — early enough to change what is sent, which is exactly what
+  // turbo:submit-start was not.
+  writeLayoutToFormData(event) {
+    if (!this.hasLayoutFieldTarget) return
+
+    event.formData.set(this.layoutFieldTarget.name, JSON.stringify(this.layoutValue))
+  }
+}