| name | frontend-patterns |
| description | Rubree's frontend conventions — when to use Alpine.js vs Stimulus, how Turbo Frame and form submission work, ERB whitespace rules for preformatted output, inline helper methods, and SVG safety. Use when writing or reviewing Stimulus controllers, Alpine.js components, ERB templates, Turbo Frames, or anything that touches the client-side rendering pipeline. |
Frontend Patterns
Alpine.js vs Stimulus
Both are used in this project. The distinction is what the state represents:
-
Alpine.js — use for purely client-side state that does not survive a Turbo navigation and
has no server interaction. In Rubree this covers the wrap/showInvisibles toggles in the
results panel (persisted in localStorage) and the show/hide toggle in the Ruby code
snippet. Alpine initialises inline with x-data and reacts without a separate controller file.
-
Stimulus — use for anything that coordinates with Turbo events, reads the DOM on
connect/disconnect, or calls back to the server. In Rubree this covers form submission
(regexp-form), the diagram modal (diagram-modal), clipboard copy, permalink generation,
and the examples panel (regexp-examples).
<%# ✅ Alpine for localStorage-persisted toggle — co-located, no controller file needed %>
<div x-data="{ wrap: localStorage.getItem('wrap') !== 'false',
init() { this.$watch('wrap', v => localStorage.setItem('wrap', v)) } }">
<%# ✅ Stimulus for Turbo event coordination — needs connect/disconnect lifecycle %>
<form data-controller="regexp-form" data-action="input->regexp-form#submit">
Don't reach for Stimulus just because something is interactive — if the state is local and
ephemeral (or only needs localStorage), Alpine keeps the logic co-located with the markup.
Turbo Frame and form submission flow
The entire results area lives inside a single Turbo Frame named regexp:
<%= turbo_frame_tag "regexp" do %>
<%# match results, diagram, substitution, ruby code — all re-rendered on submit %>
<% end %>
The form's data-turbo-frame="regexp" directs the response back into that frame on submit, so
only the results panel updates — no full page reload.
Form submission is debounced: regexp-form controller calls requestSubmit() after a
200 ms delay on each keystroke, preventing the WASM runtime from being flooded while typing.
Loading overlay is delayed 300 ms: the spinner only appears if the response takes longer
than 300 ms (regexp_form_controller.js sets a setTimeout(..., 300) before showing the
overlay). Fast WASM responses complete before the timer fires, so there is no spinner flash on
typical inputs. The timeout is cancelled on turbo:frame-render for the regexp frame.
ERB whitespace in preformatted output
When a container is styled with whitespace-pre or font-mono, the <%= %> tag must be placed
flush against the opening element's closing > with no intervening newline or space. ERB
emits any surrounding whitespace verbatim, and whitespace-pre renders it as a leading blank
character or extra line in the browser:
<%# ✅ ERB flush against the opening tag — no leading whitespace in the rendered output %>
<div class="whitespace-pre font-mono ..."><%= regular_expression.substitution_result %></div>
<%# ❌ newline before ERB tag — visible as a leading blank line inside the preformatted box %>
<div class="whitespace-pre font-mono ...">
<%= regular_expression.substitution_result %>
</div>
For the same reason, the match-span highlighting loop in _match.html.erb is written as a
single semicolon-separated expression starting immediately after the > of the container
<div>. Breaking it across lines would inject whitespace before the first highlighted character.
ERB Lint may flag these as "line too long" — this is acceptable for preformatted output blocks.
Do not reformat them.
Helper methods defined inside ERB templates
escape_invisibles — which converts \n, \t, \r to visible symbols like ⏎, ⇥, ␍
— is defined with a bare def inside the ERB template rather than in app/helpers/. This is
intentional: the function is only needed within the two <template x-if="showInvisibles"> blocks
of a single partial, and adding it to ApplicationHelper would pollute the global helper
namespace for a purely local concern. The inline def creates a method in the template's binding
scope.
If escape_invisibles ever needs to be shared across multiple partials, move it to
app/helpers/regular_expressions_helper.rb at that point.
SVG output is sanitized — do not bypass it
RailroadDiagram#diagram_svg passes the generated SVG through
ActionController::Base.helpers.sanitize(...) with an explicit allowlist before returning it.
The result is an ActiveSupport::SafeBuffer (html-safe), which is why <%= diagram_svg %> in
the view renders without double-escaping.
Do not call raw(...) or .html_safe on unsanitized SVG. A crafted regex pattern could
otherwise inject arbitrary HTML/JavaScript via the SVG output.
ActionController::Base.helpers.sanitize(
raw_svg,
tags: %w[svg g path rect circle line text style defs title desc],
attributes: %w[d fill stroke x y cx cy r width height viewBox xmlns class type
transform text-anchor font stroke-width rx ry]
)
raw(regular_expression.diagram_svg)
Review checklist — frontend
When reviewing a PR or diff that touches the client-side layer:
Client-side philosophy
Browser compatibility
