qube_rails 0.2.0

data/app/views/qube_rails/_run_status.html.erb

@@ -0,0 +1,22 @@
+<%# Where record stands with QuickBooks for an operation, in a sentence, and what went wrong when
+    its run failed, or nothing before it's sent. Render it on the record's page, with
+    connection: when the page is about one company file (else it's the connection the latest run
+    went out on):
+      render "qube_rails/run_status", record: @invoice, operation: "create_invoice"
+    It builds a QubeRails::RunStatusView from QubeRails::SyncStatus and renders the
+    qube_rails/run_status/* pieces; override a piece by putting a file at its path in your app
+    (README, "Styling"). %>
+<% unless QubeRails.config.operation_class(operation) %>
+<%   raise ArgumentError, "QuBe Sync: no operation has the slug #{operation.inspect} (config.operations)" %>
+<% end %>
+<% sync = if local_assigns[:connection]
+           local_assigns[:connection].sync_status(record, operation: operation)
+         else
+           QubeRails::SyncStatus.latest(record, operation: operation)
+         end %>
+<%# Refreshed when the run's next event comes, in an app with turbo-rails (QubeRails.broadcast_refresh). %>
+<%= turbo_stream_from(record, :qube_rails) if respond_to?(:turbo_stream_from) %>
+<% error = flash[:qube_rails_error] %>
+<% flash.delete(:qube_rails_error) # shown once, by whichever partial comes first %>
+<%= render "qube_rails/run_status/status", run_status: QubeRails::RunStatusView.from_sync(sync, qube_rails, error: error,
+                                                                                    connection: local_assigns[:connection]) %>

data/app/views/qube_rails/question/_choice.html.erb

@@ -0,0 +1,20 @@
+<%# One choice (a QubeRails::ChoiceView): a form posting choice=<id> and data[...] for its fields
+    to choice.action_url, with your CSRF token. Its button is choice.style's (:primary, :secondary
+    or :ghost), with that ui_classes piece (choice.button_piece). %>
+<form class="<%= qube_classes(:choice, "qube-choice", choice.kind == :form ? "qube-choice-form" : nil) %>" method="post"
+      action="<%= choice.action_url %>" data-qube-choice="<%= choice.id %>" data-qube-choice-kind="<%= choice.kind %>">
+  <%= hidden_field_tag request_forgery_protection_token, form_authenticity_token, id: nil %>
+  <%= hidden_field_tag :choice, choice.id, id: nil %>
+<% choice.fields.each do |field| %>
+  <%= render field.partial, field: field %>
+<% end %>
+  <button type="submit" class="<%= qube_classes(choice.button_piece, "qube-choice-button") %>" data-qube-button="<%= choice.style %>">
+    <%= choice.label %>
+<% if choice.detail %>
+    <span class="<%= qube_classes(:choice_detail, "qube-choice-detail") %>"><%= choice.detail %></span>
+<% end %>
+  </button>
+<% if choice.description %>
+  <p class="<%= qube_classes(:choice_description, "qube-choice-description") %>"><%= choice.description %></p>
+<% end %>
+</form>

data/app/views/qube_rails/question/_details.html.erb

@@ -0,0 +1,6 @@
+<%# What the question is about: label and value rows (question.details). %>
+<table class="<%= qube_classes(:details, "qube-question-details") %>">
+<% question.details.each do |row| %>
+  <tr><th scope="row"><%= row.label %></th><td><%= row.value %></td></tr>
+<% end %>
+</table>

data/app/views/qube_rails/question/_field.html.erb

@@ -0,0 +1,15 @@
+<%# The wrapper every field piece renders its control (control, HTML) in: a choice's field gets
+    its label; inside a rows table, the control stands alone. %>
+<% if field.labelled? %>
+<div class="<%= qube_classes(:field, "qube-field", "qube-field-#{field.type}") %>">
+<%   if field.type == "boolean" %>
+  <%= control %>
+  <%= label_tag field.dom_id, field.label, class: qube_classes(:label, "qube-label") %>
+<%   else %>
+  <%= label_tag field.dom_id, field.label, class: qube_classes(:label, "qube-label") %>
+  <%= control %>
+<%   end %>
+</div>
+<% else %>
+<%= control %>
+<% end %>

data/app/views/qube_rails/question/_footer.html.erb

@@ -0,0 +1,7 @@
+<%# The exits (question.exits: none of these, cancel and the like) in a row; in a plain question
+    (no picks, no forms) every choice, the first primary. %>
+<div class="<%= qube_classes(:choice_footer, "qube-choice-footer") %>"<%= " data-qube-plain" if question.plain? %>>
+<% question.exits.each do |choice| %>
+  <%= render "qube_rails/question/choice", question: question, choice: choice %>
+<% end %>
+</div>

data/app/views/qube_rails/question/_message.html.erb

@@ -0,0 +1,2 @@
+<%# What the question asks, in a sentence or two. %>
+<p class="<%= qube_classes(:message, "qube-question-message") %>"><%= question.message %></p>

data/app/views/qube_rails/question/_pick.html.erb

@@ -0,0 +1,19 @@
+<%# One pick (a QubeRails::ChoiceView of kind :pick): an option row, a form posting choice=<id>
+    to choice.action_url with your CSRF token. %>
+<form class="qube-choice qube-pick-form" method="post" action="<%= choice.action_url %>" role="listitem"
+      data-qube-choice="<%= choice.id %>" data-qube-choice-kind="pick">
+  <%= hidden_field_tag request_forgery_protection_token, form_authenticity_token, id: nil %>
+  <%= hidden_field_tag :choice, choice.id, id: nil %>
+  <button type="submit" class="<%= qube_classes(:pick, "qube-pick") %>">
+    <span class="qube-pick-text">
+      <span class="qube-pick-label"><%= choice.label %></span>
+<% if choice.detail %>
+      <span class="<%= qube_classes(:pick_detail, "qube-pick-detail") %>"><%= choice.detail %></span>
+<% end %>
+<% if choice.description %>
+      <span class="qube-pick-description"><%= choice.description %></span>
+<% end %>
+    </span>
+    <span class="<%= qube_classes(:pick_action, "qube-pick-action") %>"><%= QubeRails.t("question.use_pick") %></span>
+  </button>
+</form>

data/app/views/qube_rails/question/_picks.html.erb

@@ -0,0 +1,6 @@
+<%# The question's picks (question.picks): option rows, one form each. %>
+<div class="<%= qube_classes(:picks, "qube-picks") %>" role="list">
+<% question.picks.each do |choice| %>
+  <%= render "qube_rails/question/pick", question: question, choice: choice %>
+<% end %>
+</div>

data/app/views/qube_rails/question/_question.html.erb

@@ -0,0 +1,24 @@
+<%# A question (a QubeRails::QuestionView): a refusal, its message, what it's about, then its
+    choices by kind: the picks (option rows), each form choice ("or" between), and the exits in a
+    footer. A question with neither picks nor forms shows its choices in one row. %>
+<section class="<%= qube_classes(:question, "qube-question") %>" data-qube-question="<%= question.token %>">
+  <%= render "qube_rails/error", message: question.error %>
+  <%= render "qube_rails/question/message", question: question %>
+<% if question.details.any? %>
+  <%= render "qube_rails/question/details", question: question %>
+<% end %>
+  <div class="qube-choices">
+<% if question.picks.any? %>
+    <%= render "qube_rails/question/picks", question: question %>
+<% end %>
+<% question.forms.each_with_index do |choice, n| %>
+<%   if n.positive? || question.picks.any? %>
+    <div class="<%= qube_classes(:choice_divider, "qube-choice-divider") %>" role="separator"><span><%= QubeRails.t("question.or") %></span></div>
+<%   end %>
+    <%= render "qube_rails/question/choice", question: question, choice: choice %>
+<% end %>
+<% if question.exits.any? %>
+    <%= render "qube_rails/question/footer", question: question %>
+<% end %>
+  </div>
+</section>

data/app/views/qube_rails/question/fields/_boolean.html.erb

@@ -0,0 +1,7 @@
+<%# A checkbox: ticked posts "true", sent as true; unticked, false. %>
+<% control = capture do %>
+<%= check_box_tag field.input_name, "true", false, id: field.dom_id, disabled: field.disabled,
+                  class: qube_classes(:checkbox, "qube-checkbox", field.cell? ? "qube-rows-input" : nil),
+                  "aria-label": (field.labelled? ? nil : field.label), data: field.data %>
+<% end %>
+<%= render "qube_rails/question/field", field: field, control: control %>

data/app/views/qube_rails/question/fields/_number.html.erb

@@ -0,0 +1,7 @@
+<%# A number field: posted as typed, sent as a number. %>
+<% control = capture do %>
+<%= number_field_tag field.input_name, nil, id: field.dom_id, step: "any", required: field.required,
+                     disabled: field.disabled, class: qube_classes(:input, "qube-input", field.cell? ? "qube-rows-input" : nil),
+                     "aria-label": (field.labelled? ? nil : field.label), data: field.data %>
+<% end %>
+<%= render "qube_rails/question/field", field: field, control: control %>

data/app/views/qube_rails/question/fields/_rows.html.erb

@@ -0,0 +1,23 @@
+<%# A rows field (field.rows, a QubeRails::RowsView): a block per record with the fields it asks,
+    posted as data[<field>][<row key>][<column>]. A field shows only while its "when" holds. "Set
+    all to:" sets the segmented column on every row, and "Use for all" copies one row's value to
+    the others (the behaviour script). %>
+<% rows = field.rows %>
+<% set_all = rows.set_all %>
+<div class="<%= qube_classes(:field, "qube-field", "qube-rows-field") %>" data-qube-rows
+     data-qube-text-use-for-all="<%= QubeRails.t("question.use_for_all", count: "%{count}") %>">
+  <p class="<%= qube_classes(:label, "qube-rows-label") %>"><%= rows.label %></p>
+<% if set_all %>
+  <div class="qube-rows-set-all" data-qube-rows-set-all="<%= set_all.name %>">
+    <span class="qube-rows-set-all-label"><%= QubeRails.t("question.set_all") %></span>
+<%   set_all.options.each do |option| %>
+    <button type="button" class="<%= qube_classes(:button_secondary, "qube-set-all-button") %>" data-qube-set-all="<%= option.value %>"><%= option.label %></button>
+<%   end %>
+  </div>
+<% end %>
+  <div class="<%= qube_classes(:rows, "qube-rows") %>" role="list">
+<% rows.rows.each do |row| %>
+    <%= render "qube_rails/question/rows/row", rows: rows, row: row %>
+<% end %>
+  </div>
+</div>

data/app/views/qube_rails/question/fields/_search.html.erb

@@ -0,0 +1,23 @@
+<%# A record field: what the user types is looked up at field.search_url (GET ?field=&q=&row=,
+    answering [{value, label, detail}]), and the match they pick fills the hidden input posted as
+    field.input_name. The behaviour script keys on the data-qube-* attributes; the box's
+    data-qube-text-* attributes are its words (I18n's qube_rails.question.*). %>
+<% inputs = capture do %>
+  <%= tag.input(type: "search", id: field.dom_id, class: qube_classes(:input, "qube-search-input"), maxlength: 100,
+                autocomplete: "off", required: field.required, disabled: field.disabled,
+                role: "combobox", "aria-autocomplete": "list", "aria-expanded": "false",
+                "aria-label": (field.labelled? ? nil : field.label), data: { "qube-search-input" => "" }) %>
+  <%= tag.input(type: "hidden", name: field.input_name, disabled: field.disabled,
+                class: ["qube-search-value", field.cell? ? "qube-rows-input" : nil].compact.join(" "),
+                data: field.data.merge("qube-search-value" => "")) %>
+  <div class="<%= qube_classes(:search_results, "qube-search-results") %>" data-qube-search-results aria-live="polite"></div>
+<% end %>
+<% control = content_tag(:div, inputs, class: qube_classes(:search, "qube-search"),
+                         data: { "qube-search" => field.search_url, "qube-field" => field.search_field,
+                                 "qube-row" => field.row_key,
+                                 "qube-result-class" => qube_classes(:search_result, "qube-search-result"),
+                                 "qube-text-no-matches" => QubeRails.t("question.no_matches"),
+                                 "qube-text-searching" => QubeRails.t("question.searching"),
+                                 "qube-text-search-failed" => QubeRails.t("question.search_failed"),
+                                 "qube-text-pick-a-match" => QubeRails.t("question.pick_a_match") }.compact) %>
+<%= render "qube_rails/question/field", field: field, control: control %>

data/app/views/qube_rails/question/fields/_select.html.erb

@@ -0,0 +1,8 @@
+<%# A fixed list (field.options, each value and label), with a blank first. %>
+<% control = capture do %>
+<%= select_tag field.input_name, options_for_select(field.options.map { |o| [o.label, o.value] }),
+               id: field.dom_id, include_blank: true, required: field.required, disabled: field.disabled,
+               class: qube_classes(:select, "qube-select", field.cell? ? "qube-rows-input" : nil),
+               "aria-label": (field.labelled? ? nil : field.label), data: field.data %>
+<% end %>
+<%= render "qube_rails/question/field", field: field, control: control %>

data/app/views/qube_rails/question/fields/_text.html.erb

@@ -0,0 +1,7 @@
+<%# A text field. %>
+<% control = capture do %>
+<%= text_field_tag field.input_name, nil, id: field.dom_id, required: field.required, disabled: field.disabled,
+                   class: qube_classes(:input, "qube-input", field.cell? ? "qube-rows-input" : nil),
+                   "aria-label": (field.labelled? ? nil : field.label), data: field.data %>
+<% end %>
+<%= render "qube_rails/question/field", field: field, control: control %>

data/app/views/qube_rails/question/rows/_cell.html.erb

@@ -0,0 +1,24 @@
+<%# One field of a row (a QubeRails::CellView): a segmented choice, a field with its label (and,
+    for a search or a select, "Use for all"), or what the row already has, read-only.
+    hidden / data-qube-hidden mark a field whose "when" doesn't hold yet (its input disabled and
+    not required, so it isn't sent); data-qube-required says to require it once shown. %>
+<% content = capture do %>
+<%   if cell.segmented? %>
+  <%= render "qube_rails/question/rows/segmented", field: cell.field %>
+<%   elsif cell.field %>
+  <%= render cell.field.partial, field: cell.field %>
+<%     if %w[search select].include?(cell.field.type) %>
+  <button type="button" class="<%= qube_classes(:use_for_all, "qube-use-for-all") %>" data-qube-use-for-all hidden></button>
+<%     end %>
+<%   else %>
+  <div class="qube-field qube-row-preset">
+    <span class="<%= qube_classes(:label, "qube-label") %>"><%= cell.label %></span>
+    <span class="qube-row-preset-value"><%= cell.preset %></span>
+  </div>
+<%   end %>
+<% end %>
+<%= content_tag :div, content, class: ["qube-row-cell", cell.segmented? ? "qube-row-cell-segmented" : nil].compact.join(" "),
+                               hidden: cell.hidden?,
+                               data: { "qube-col" => cell.column, "qube-when" => cell.when_json,
+                                       "qube-hidden" => (cell.hidden? ? "" : nil),
+                                       "qube-required" => (cell.required ? "" : nil) }.compact %>

data/app/views/qube_rails/question/rows/_row.html.erb

@@ -0,0 +1,22 @@
+<%# One record of a rows field (row, a QubeRails::RowView): its name, its segmented choice, then
+    the fields its answers so far call for. %>
+<% header_id = "qube-row-#{rows.input_name.gsub(/[^A-Za-z0-9]+/, "-")}#{row.index}".squeeze("-") %>
+<div class="<%= qube_classes(:row, "qube-row") %>" role="listitem" aria-labelledby="<%= header_id %>"
+     data-qube-row="<%= row.key %>" data-qube-values="<%= row.values_json %>">
+  <div class="<%= qube_classes(:row_header, "qube-row-header") %>" id="<%= header_id %>">
+    <span class="qube-row-label"><%= row.label %></span>
+<% if row.detail %>
+    <span class="qube-row-detail"><%= row.detail %></span>
+<% end %>
+  </div>
+  <div class="qube-row-body">
+<% row.segmented_cells.each do |cell| %>
+    <%= render "qube_rails/question/rows/cell", cell: cell %>
+<% end %>
+    <div class="<%= qube_classes(:row_fields, "qube-row-fields") %>">
+<% row.field_cells.each do |cell| %>
+      <%= render "qube_rails/question/rows/cell", cell: cell %>
+<% end %>
+    </div>
+  </div>
+</div>

data/app/views/qube_rails/question/rows/_segmented.html.erb

@@ -0,0 +1,14 @@
+<%# A short list (field.options, at most three) in a row as a segmented control: radios posted
+    as field.input_name, the column's label their group's name for screen readers. %>
+<fieldset class="qube-segmented-field">
+  <legend class="qube-visually-hidden"><%= field.label %></legend>
+  <div class="<%= qube_classes(:segmented, "qube-segmented") %>">
+<% field.options.each do |option| %>
+    <label class="<%= qube_classes(:segment, "qube-segment") %>">
+      <%= tag.input(type: "radio", name: field.input_name, value: option.value, required: field.required,
+                    disabled: field.disabled, class: "qube-segment-input qube-rows-input", data: field.data) %>
+      <span><%= option.label %></span>
+    </label>
+<% end %>
+  </div>
+</fieldset>

data/app/views/qube_rails/run_status/_detail.html.erb

@@ -0,0 +1,7 @@
+<%# Why a run failed or was cancelled (run_status.reason), then what to do about it (detail). %>
+<% if run_status.reason %>
+<p class="<%= qube_classes(:reason, "qube-run-reason") %>"><%= run_status.reason %></p>
+<% end %>
+<% if run_status.detail %>
+<p class="<%= qube_classes(:detail, "qube-run-error-detail") %>"><%= run_status.detail %></p>
+<% end %>

data/app/views/qube_rails/run_status/_redeliver.html.erb

@@ -0,0 +1,5 @@
+<%# A run that looks stuck: posts to redeliver_url, which asks QuBe Sync to send its latest event
+    again. The words are I18n's: qube_rails.status.quiet and .check_for_updates. %>
+<p class="qube-run-quiet"><%= run_status.quiet_text %></p>
+<%= button_to QubeRails.t("status.check_for_updates"), run_status.redeliver_url,
+              class: qube_classes(:button_secondary, "qube-redeliver"), form: { class: "qube-redeliver-form" } %>

data/app/views/qube_rails/run_status/_retry.html.erb

@@ -0,0 +1,4 @@
+<%# A start QuBe Sync hasn't confirmed for a minute: posts to retry_url, which sends it again with
+    the same reference. The words are I18n's: qube_rails.status.try_again. %>
+<%= button_to QubeRails.t("status.try_again"), run_status.retry_url, class: qube_classes(:button, "qube-retry-start"),
+              form: { class: "qube-retry-start-form" } %>

data/app/views/qube_rails/run_status/_stall.html.erb

@@ -0,0 +1,3 @@
+<%# Why a record waits: its connection stalled (run_status.stall, the reason; stall_text, what to
+    do, from I18n's qube_rails.status.stalled.*). %>
+<p class="<%= qube_classes(:stall, "qube-run-stall") %>"><%= run_status.stall_text %></p>

data/app/views/qube_rails/run_status/_status.html.erb

@@ -0,0 +1,21 @@
+<%# A record's status (run_status, a QubeRails::RunStatusView): the error, then the summary, the
+    failure's detail, why it waits on a stalled connection, and the buttons, or only the error
+    before it's sent. %>
+<%= render "qube_rails/error", message: run_status.error %>
+<% if run_status.visible? %>
+<div class="<%= qube_classes(:status, run_status.css_class) %>" data-qube-sync-status="<%= run_status.status %>"<% if run_status.stall %> data-qube-stall="<%= run_status.stall %>"<% end %>>
+  <%= render "qube_rails/run_status/summary", run_status: run_status %>
+<%   if run_status.reason || run_status.detail %>
+  <%= render "qube_rails/run_status/detail", run_status: run_status %>
+<%   end %>
+<%   if run_status.stall %>
+  <%= render "qube_rails/run_status/stall", run_status: run_status %>
+<%   end %>
+<%   if run_status.redeliver_url %>
+  <%= render "qube_rails/run_status/redeliver", run_status: run_status %>
+<%   end %>
+<%   if run_status.retry_url %>
+  <%= render "qube_rails/run_status/retry", run_status: run_status %>
+<%   end %>
+</div>
+<% end %>

data/app/views/qube_rails/run_status/_summary.html.erb

@@ -0,0 +1,2 @@
+<%# Where it stands, in a sentence: "Added to QuickBooks", "Failed: ...". %>
+<p class="<%= qube_classes(:summary, "qube-run-summary") %>"><%= run_status.summary %></p>

data/app/views/qube_rails/storyboard/show.html.erb

@@ -0,0 +1,86 @@
+<%# The storyboard: each screen (@screens, QubeRails::Storyboard) in a card with its name, a note,
+    the screen itself on a canvas, rendered by the engine's partials (or yours, where you've
+    overridden them), and the pieces to override for it. Its styles are the opt-in stylesheet's,
+    all under .qube-storyboard. %>
+<% single = @screens.size == 1 %>
+<% content_for :title, "QuickBooks screens" %>
+<div class="qube-storyboard" id="qube-storyboard">
+  <header class="qube-storyboard-header">
+    <div>
+      <h1>QuickBooks screens</h1>
+      <p class="qube-storyboard-note">
+        Every screen your users can meet, from sample data, in your layout. Override a piece by putting a
+        file at its path in your app; add classes with config.ui_classes. Nothing here reaches QuBe Sync.
+<% if single %>
+        <%= link_to "All screens", qube_rails.storyboard_path %>
+<% end %>
+      </p>
+    </div>
+    <fieldset class="qube-storyboard-theme">
+      <legend>Canvas</legend>
+<% [["app", "As your page"], ["light", "Light"], ["dark", "Dark"]].each do |value, label| %>
+      <label><input type="radio" name="qube-storyboard-canvas" value="<%= value %>" data-qube-canvas-theme="<%= value %>"<%= " checked" if value == "app" %>><%= label %></label>
+<% end %>
+    </fieldset>
+  </header>
+<% if flash[:qube_rails_storyboard] %>
+  <p class="qube-storyboard-notice" role="status"><%= flash[:qube_rails_storyboard] %></p>
+<% end %>
+  <div class="qube-storyboard-body">
+    <nav class="qube-storyboard-nav" aria-label="Screens">
+<% QubeRails::Storyboard.screens.group_by(&:group).each do |group, screens| %>
+      <div class="qube-storyboard-nav-group">
+        <p class="qube-storyboard-nav-title"><%= group %></p>
+        <ul>
+<%   screens.each do |screen| %>
+<%     href = single ? qube_rails.storyboard_screen_path(screen.key) : "#qube-storyboard-#{screen.key}" %>
+          <li><%= link_to screen.title, href, "aria-current": (single && @screens.first.key == screen.key ? "page" : nil) %></li>
+<%   end %>
+        </ul>
+      </div>
+<% end %>
+    </nav>
+    <div class="qube-storyboard-screens">
+<% @screens.each do |screen| %>
+<%   answer = qube_rails.storyboard_answer_path(screen.key) %>
+      <section class="qube-storyboard-panel" id="qube-storyboard-<%= screen.key %>" data-qube-storyboard="<%= screen.key %>"
+               aria-labelledby="qube-storyboard-<%= screen.key %>-title">
+        <header class="qube-storyboard-panel-head">
+          <h2 id="qube-storyboard-<%= screen.key %>-title"><a href="#qube-storyboard-<%= screen.key %>"><%= screen.title %></a></h2>
+          <span class="qube-storyboard-group"><%= screen.group %></span>
+<%   unless single %>
+          <%= link_to "Open on its own", qube_rails.storyboard_screen_path(screen.key), class: "qube-storyboard-open" %>
+<%   end %>
+        </header>
+        <p class="qube-storyboard-note"><%= screen.note %></p>
+        <div class="qube-storyboard-canvas" data-qube-storyboard-canvas>
+<%   if screen.kind == :run_status %>
+<%     view = QubeRails::Storyboard.run_status_view(screen, QubeRails::Storyboard::Urls.new(answer)) %>
+<%     if view.visible? %>
+          <%= render "qube_rails/run_status/status", run_status: view %>
+<%     else %>
+          <p class="qube-storyboard-empty">Nothing is shown before a record is sent.</p>
+<%     end %>
+<%   elsif screen.kind == :error %>
+          <%= render "qube_rails/error", message: screen.sample[:message] %>
+<%   else %>
+          <%= render "qube_rails/question/question",
+                     question: QubeRails::Storyboard.question_view(screen, answer, qube_rails.storyboard_search_path(screen.key)) %>
+<%   end %>
+        </div>
+<%   if screen.partials.any? %>
+        <details class="qube-storyboard-files">
+          <summary>Override files (<%= screen.partials.size %>)</summary>
+          <ul>
+<%     screen.partials.each do |partial| %>
+<%       path = QubeRails::Storyboard.override_path(partial) %>
+            <li><code><%= path %></code><button type="button" class="qube-storyboard-copy" data-qube-copy="<%= path %>">Copy</button></li>
+<%     end %>
+          </ul>
+        </details>
+<%   end %>
+      </section>
+<% end %>
+    </div>
+  </div>
+</div>

data/config/locales/en.yml

@@ -0,0 +1,46 @@
+# Everything the engine's screens say to your users. Override any key in your app's own
+# config/locales/*.yml (it loads after this file), or add another locale's file to translate them.
+# README, "Wording and translations", lists them.
+en:
+  qube_rails:
+    status:
+      in_quickbooks: "In QuickBooks"
+      added: "Added to QuickBooks"
+      done: "Done"
+      done_with: "Done: %{outcome}"
+      failed: "Couldn't sync"
+      not_started: "it couldn't be sent"
+      cancelled: "Cancelled"
+      cancel_reason: "it was stopped before it finished"
+      needs_answer: "Needs your answer"
+      starting: "Sending to QuickBooks"
+      unconfirmed: "Still waiting for QuickBooks"
+      running: "Syncing with QuickBooks"
+      quiet: "No update from QuickBooks for a while."
+      check_for_updates: "Check for updates"
+      try_again: "Try sending again"
+      waiting_for_quickbooks: "Waiting for QuickBooks"
+      stalled:
+        not_checking_in: "QuickBooks hasn't checked in for a while, so this is waiting. Make sure the computer with QuickBooks is on and the Web Connector is running."
+        quickbooks_unavailable: "The Web Connector is checking in but can't open QuickBooks. Open the company file in QuickBooks on that computer."
+        other: "Syncing with QuickBooks has stopped for now. Check the computer with QuickBooks and its Web Connector."
+    errors:
+      not_starting: "This was already sent, so there's nothing to try again."
+      not_quiet: "This was updated recently. Check again in a few minutes."
+      no_update_yet: "There's no update yet. Check again in a few minutes."
+      checked_just_now: "That was checked a moment ago. Try again in a minute."
+      unreachable: "Couldn't reach QuickBooks' sync service just now. Try again in a minute."
+      disconnect_unreachable: "Couldn't reach QuickBooks' sync service just now. Try disconnecting again in a minute."
+      still_syncing: "Something is still syncing with this company file. Let it finish, or answer its question, then disconnect."
+      question_changed: "This question changed after the page loaded, so your answer wasn't sent. The page now shows the latest."
+      answer_refused: "That answer couldn't be used. Check it and try again."
+      answer_refused_with: "That answer couldn't be used: %{detail}"
+    question:
+      set_all: "Set all to:"
+      use_pick: "Use this one"
+      use_for_all: "Use for all %{count}"
+      or: "or"
+      pick_a_match: "Pick one of the matches."
+      no_matches: "No matches"
+      searching: "Searching…"
+      search_failed: "Search isn't available right now. Try again in a moment."

data/config/routes.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+QubeRails::Engine.routes.draw do
+  # A "Connect QuickBooks Desktop" button posts here (with an optional name), for a new
+  # connection; a connection's "Set up again" posts to its onboarding. QuBe Sync's setup doesn't
+  # come back to your app: it tells the connection by webhook.
+  post "quickbooks/connections", to: "connections#create", as: :connections
+  post "quickbooks/connections/:id/onboarding", to: "connections#onboarding", as: :connection_onboarding
+  delete "quickbooks/connections/:id", to: "connections#destroy", as: :connection
+
+  # Each run's webhook URL is QUBE_WEBHOOK_URL/runs/<run id> (QubeRails::Run#webhook_url), and a
+  # connection's is QUBE_WEBHOOK_URL/connections/<connection id>.
+  post "webhooks/qube/runs/:id", to: "webhooks#run_event", as: :run_webhook
+  post "webhooks/qube/connections/:id", to: "webhooks#connection_event", as: :connection_webhook
+  # A plain request's: QUBE_WEBHOOK_URL/requests/<id> (QubeRails::QueuedRequest#webhook_url).
+  post "webhooks/qube/requests/:id", to: "webhooks#request_event", as: :request_webhook
+
+  # A start QuBe Sync never confirmed, sent again, from the run status partial.
+  post "qube/runs/:id/retry_start", to: "runs#retry_start", as: :retry_start
+
+  # A run that looks stuck, its latest event sent again, from the run status partial.
+  post "qube/runs/:id/redeliver", to: "runs#redeliver", as: :redeliver
+
+  # Your user's answer to a run's question, from the question partial, and a record field's
+  # search.
+  post "qube/questions/runs/:id", to: "questions#create", as: :question
+  get "qube/questions/runs/:id/search", to: "questions#search", as: :question_search
+
+  # Every screen with sample data, while config.storyboard is true: a search answered from the
+  # samples, and a no-op every form posts to.
+  get "qube/storyboard", to: "storyboard#index", as: :storyboard
+  get "qube/storyboard/:screen", to: "storyboard#show", as: :storyboard_screen
+  get "qube/storyboard/:screen/search", to: "storyboard#search", as: :storyboard_search
+  post "qube/storyboard/:screen/answer", to: "storyboard#answer", as: :storyboard_answer
+end

data/db/migrate/20261025000000_create_qube_tables.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+# QuBe Sync's tables (qube_rails): your customers' connections, the runs your app starts, the
+# notifications each run's handler has taken, and the QuickBooks ids your app learns, each against
+# its connection. Your own tables need nothing.
+#
+# The polymorphic ids (owner_id, record_id) are strings, so integer and UUID keys both fit.
+# input (what the run was started with, so a start can be resent unchanged), error (a failed
+# run's, as its event carried it), question and links are JSON kept as text (QubeRails::JSONCoder says why). The 100-character
+# limits keep the composite indexes inside MySQL's 3072-byte key limit under utf8mb4.
+class CreateQubeTables < ActiveRecord::Migration[5.2]
+  def change
+    create_table :qube_connections do |t|
+      t.string :owner_type, null: false, limit: 100
+      t.string :owner_id, null: false
+      t.string :qube_id
+      t.string :name
+      t.string :status, null: false, default: "pending"
+      t.string :stall_reason
+      t.integer :revision
+      t.timestamps null: false
+    end
+    add_index :qube_connections, :qube_id, unique: true, name: "index_qube_connections_on_qube_id"
+    add_index :qube_connections, [:owner_type, :owner_id], name: "index_qube_connections_on_owner"
+
+    create_table :qube_runs do |t|
+      t.bigint :connection_id, null: false
+      t.string :operation, null: false, limit: 100
+      t.string :record_type, null: false, limit: 100
+      t.string :record_id, null: false
+      t.string :reference, null: false
+      t.string :qube_run_id
+      t.text :input
+      t.integer :revision, null: false, default: 0
+      t.string :state, null: false, default: "starting"
+      t.string :outcome
+      t.text :error
+      t.text :cancel_reason
+      t.datetime :ended_at
+      t.text :question
+      t.text :links
+      t.string :run_url
+      t.string :cancel_url
+      t.timestamps null: false
+    end
+    add_index :qube_runs, :reference, unique: true, name: "index_qube_runs_on_reference"
+    add_index :qube_runs, :connection_id, name: "index_qube_runs_on_connection_id"
+    add_index :qube_runs, [:record_type, :record_id, :operation, :created_at],
+              name: "index_qube_runs_on_record_and_operation"
+    add_foreign_key :qube_runs, :qube_connections, column: :connection_id
+
+    # The notifications a run's handler has taken, by delivery_id, so a redelivery runs it once.
+    # Written in the same transaction as the handler, and deleted with the run.
+    create_table :qube_notifications do |t|
+      t.bigint :run_id, null: false
+      t.string :delivery_id, null: false, limit: 100
+      t.datetime :created_at, null: false
+    end
+    add_index :qube_notifications, [:run_id, :delivery_id], unique: true,
+              name: "index_qube_notifications_on_run_and_delivery"
+    add_foreign_key :qube_notifications, :qube_runs, column: :run_id, on_delete: :cascade
+
+    create_table :qube_quickbooks_records do |t|
+      t.bigint :connection_id, null: false
+      t.string :kind, null: false, limit: 100
+      t.string :list, null: false, limit: 100
+      t.string :qb_id, null: false, limit: 100
+      t.string :edit_sequence
+      t.string :name
+      t.string :record_type, limit: 100
+      t.string :record_id
+      t.timestamps null: false
+    end
+    # A ListID is unique within its list family (QubeRails::QuickbooksRecord.family_for), not
+    # within one kind: every item type shares a counter, and so do customers, vendors, employees
+    # and other names.
+    add_index :qube_quickbooks_records, [:connection_id, :list, :qb_id], unique: true,
+              name: "index_qube_quickbooks_records_on_qb_id"
+    add_index :qube_quickbooks_records, [:connection_id, :kind, :record_type, :record_id], unique: true,
+              name: "index_qube_quickbooks_records_on_record"
+    add_foreign_key :qube_quickbooks_records, :qube_connections, column: :connection_id
+  end
+end

data/db/migrate/20261026230000_add_qube_sync_status_indexes.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+# Indexes for QubeRails::SyncStatus and the connection's scopes (in_quickbooks, not_in_quickbooks,
+# needing_answer, sending): a record's link on a connection whatever its kind, and its runs of an
+# operation on a connection by state. Within MySQL's 3072-byte key limit under utf8mb4.
+class AddQubeSyncStatusIndexes < ActiveRecord::Migration[5.2]
+  def change
+    add_index :qube_quickbooks_records, [:connection_id, :record_type, :record_id],
+              name: "index_qube_quickbooks_records_on_connection_and_record"
+    add_index :qube_runs, [:connection_id, :record_type, :record_id, :operation, :state],
+              name: "index_qube_runs_on_connection_record_and_state"
+  end
+end