outro_rails 0.1.4 → 0.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b57460d8171563b6c440d80d129e02e0426b1ac3fcd6886dc40994a525e39abb
-  data.tar.gz: 1c749d767f9c6b0680509069176ec0d454ea4dd2a8bfb0476e15f704a647e10b
+  metadata.gz: b9a61b44de4d831dd78c2ef49903677777792cfe812a6f77211dbf4e846ffb35
+  data.tar.gz: 60ee9af6996b28da00252dc296e40d5869c0f877ed8335e126d8650ae6b8d462
 SHA512:
-  metadata.gz: 178b499ca5c588f4ad584a540ac3f2bd43188b6bdbaba8886db6c34d213d0c1210bc7c137caf90d5327cdd56fb94e8dbae6ee99a4b925000c10a7297c4b1a7a4
-  data.tar.gz: 315e08ed8694798be6d319b8f55fcc5254853e5d7f254db938945b1aaa938f75cfe5f8e3ab4354d01741c6ed2ba846d2d9e8f2fbce0500d62a49335447ae394b
+  metadata.gz: 153b0d96d98f43b44c323a06fa7b3106b2ea06d0e92ca2c4a9e33f74bb3a6555b109bffbb880c3969d5147ca0aa3e43ba573060111b073c36e80f7958911c4ac
+  data.tar.gz: 91a29abfb552a60757fcdc0ded4883d921000fa9fb2c2a31e4a855e5cca628689b9def02844da3f88f736fba6c44ac4b9ff4e5280d50bb736b532bd6b5d67096

data/README.md

@@ -50,7 +50,8 @@ quickest version is to add two tags to your layout:
 ```
 
 If you'd rather fold the engine's assets into your existing bundles, see
-[Assets](#assets) below.
+[Assets](#assets) below. If you'd rather style the form controls with your
+own CSS framework, see [Control classes](#control-classes).
 
 ## Assets
 
@@ -161,6 +162,61 @@ yarn build
 yarn build:css
 ```
 
+### Form Control Classes
+
+Out of the box the engine's text fields, textareas, selects, and labels
+carry its own classes, styled by the stylesheet above:
+
+| Element    | Setting                    | Default          |
+| ---------- | -------------------------- | ---------------- |
+| `button`   | `OutroRails.button_class`   | `outro-button`    |
+| `input`    | `OutroRails.input_class`    | `outro-input`    |
+| `label`    | `OutroRails.label_class`    | `outro-label`    |
+| `select`   | `OutroRails.select_class`   | `outro-select`   |
+| `textarea` | `OutroRails.textarea_class` | `outro-textarea` |
+
+If your app already has a form style (Bootstrap, Tailwind, your own classes)
+point these at it in an initializer and the engine will render your classes
+instead:
+
+```ruby
+# config/initializers/outro_rails.rb
+OutroRails.configure do |config|
+  config.button_class   = "btn btn-sm"
+  config.input_class    = "form-control"
+  config.label_class    = "form-label"
+  config.select_class   = "form-select"
+  config.textarea_class = "form-control"
+end
+```
+
+Each setting is a plain string and can also be assigned on its own
+(`OutroRails.select_class = "form-select"`).
+
+These apply everywhere the engine renders a form control.
+
+#### Per render
+
+The same four names are accepted as locals on the chart partial and as
+options on `chord_chart_area` for a page that needs something other than
+the application-wide setting:
+
+```erb
+<%= form.chord_chart_area :chord_sheet,
+      button_class: "btn-primary",
+      input_class: "form-control",
+      label_class: "form-label",
+      select_class: "form-select",
+      textarea_class: "form-control font-monospace" %>
+```
+
+```erb
+<%= render "outro_rails/chord_charts/chart",
+      chord_chart: @song.chord_sheet,
+      select_class: "form-select",
+      label_class: "form-label" %>
+```
+
 ## Usage
 To view the chord library and music theory tools, mount the engine in your
 routes.rb:
@@ -200,9 +256,38 @@ This gives the model `chord_sheet`/`chord_sheet=`/`chord_sheet?`, backed by a
 (title), `tuning`, `capo`, `key`, and `body`). A model can attach more
 than one chart under different names.
 
+#### Required or Optional
+
+By default the chart is required: `song.chord_sheet` always returns a chart
+(building an unsaved one on first access), and saving the record with the
+artist or song blank fails validation with errors.
+
+Pass `required: false` to let the chart be left out entirely:
+
+```ruby
+class Song < ApplicationRecord
+  has_chord_chart :chord_sheet, required: false
+end
+```
+
+With an optional chart:
+
+* `song.chord_sheet` returns `nil` until someone fills it in, and
+  `song.chord_sheet?` reports whether one exists.
+* A form submitted with the artist, song, and body all blank saves the
+  record with no chart. Filling in *some* of those fields still
+  validates as usual, so the user sees what's missing.
+* Clearing every field on a record that already had a chart removes that
+  chart when the record saves. If the record itself fails validation,
+  nothing is deleted.
+* `song.chord_sheet = nil` removes a chart; `song.chord_sheet = { ... }`
+  builds one if needed and assigns the given attributes.
+
+`song.chord_sheet_required?` reports which way the model was declared.
+
 ### Forms: chord_chart_area
 
-In a form, pair it with the `chord_chart_area` form builder method:
+In a form, use the `chord_chart_area` form builder method:
 
 ```erb
 <%= form_with model: @song do |form| %>
@@ -211,10 +296,29 @@ In a form, pair it with the `chord_chart_area` form builder method:
 <% end %>
 ```
 
-`chord_chart_area` renders artist/song/tuning/capo/key/body fields. Tuning
-options are pulled from `Instruments::Guitar::Tunings`, capo options are capped
-at fret 7 (`Instruments::Guitar::Capo::FRETS`), and key options are set from
-from `Theory::Key`.
+`chord_chart_area` renders a fieldset with a heading and
+artist/song/tuning/capo/key/body fields. Tuning options are pulled from
+`Instruments::Guitar::Tunings`, capo options are capped at fret 7
+(`Instruments::Guitar::Capo::FRETS`). Key options are set from
+`Theory::Key`.
+
+The heading defaults to "Chord Chart". Set `legend:` to change it, or pass
+`false` when the surrounding page already has a heading for this section:
+
+```erb
+<%= form.chord_chart_area :chord_sheet, legend: "Lead sheet" %>
+<%= form.chord_chart_area :chord_sheet, legend: false %>
+```
+
+When the model declares the chart with `required: false`, the fieldset is
+labeled "Optional" and tells the user to leave the fields blank if there's
+no chord chart.
+
+The fields inside the fieldset use the engine's own control classes. Pass
+`input_class:`, `textarea_class:`, `select_class:`, or `label_class:` to
+render them with your app's classes for this form, or set them once
+application-wide — see [Control classes](#control-classes). Any other
+option is passed through to `fields_for`, as before.
 
 ### Controller: Permitting the Parameters
 
@@ -233,15 +337,13 @@ class SongsController < ApplicationController
   def song_params
     params.require(:song).permit(
       :description,
-      chord_chart_chord_sheet_attributes: %i[artist body capo key song tuning]
+      chord_chart_chord_sheet_attributes: %i[id artist body capo key song tuning]
     )
   end
 end
 ```
 
-The six permitted attributes are exactly the fields `chord_chart_area`
-renders. `record` and `name` are managed by the engine and should not be
-permitted. If a model attaches more than one chart, each one needs its own
+If a model attaches more than one chart, each one needs its own
 key: `has_chord_chart :lead_sheet` is permitted as
 `chord_chart_lead_sheet_attributes`.
 
@@ -264,6 +366,11 @@ This renders the chart's metadata, an instrument toggle, a transpose-to-key
 picker, the chart body with recognized chords highlighted, and a
 diagram for every chord the body references.
 
+The partial accepts `chord_chart: nil`, so it can be handed an optional
+chart that hasn't been filled in yet; it renders a short "No chord chart."
+placeholder in that case. Check `@song.chord_sheet?` instead if you'd
+rather show nothing at all.
+
 ### Using Your Own Layout
 
 By default the engine renders its pages in its own layout,
@@ -426,7 +533,6 @@ It seeds the chord library and four example songs (`spec/dummy/db/seeds.rb`).
 The example songs are listed on the home page. To illustrate permissions,
 the dummy app sets even record ids as editable and odd ones as view-only.
 
-
 ## Publishing a New Version
 
 **1. Bump the version.** Edit `lib/outro_rails/version.rb`

data/app/assets/stylesheets/outro_rails/outro_rails.css

@@ -11,8 +11,7 @@
    from `currentColor`, so they adapt to light and dark host themes.
    ========================================================================== */
 
-.outro,
-.outro-page {
+:root {
   --outro-container-width: 66rem;
   --outro-radius: 14px;
   --outro-radius-sm: 6px;
@@ -54,8 +53,7 @@
 
 @supports not (color: color-mix(in srgb, currentColor 50%, transparent)) {
 
-  .outro,
-  .outro-page {
+  :root {
     --outro-muted: rgba(128, 128, 128, 0.9);
     --outro-border: rgba(128, 128, 128, 0.3);
     --outro-border-strong: rgba(128, 128, 128, 0.5);
@@ -129,8 +127,6 @@
   align-items: center;
   gap: 0.4rem;
   min-width: 0;
-  align-items: center;
-  min-width: 0;
   margin: 0;
   padding: 0.3rem clamp(0.6rem, 2vw, 0.95rem);
   border: 1px solid var(--outro-border);
@@ -307,21 +303,6 @@
   font: inherit;
 }
 
-.outro-button {
-  display: inline-flex;
-  align-items: center;
-  gap: 0.45rem;
-  padding: 0.4rem 0.9rem;
-  border: 1px solid var(--outro-border-strong);
-  border-radius: var(--outro-radius-sm);
-  background-color: var(--outro-surface, transparent);
-  color: inherit;
-  font: inherit;
-  line-height: 1.2;
-  text-decoration: none;
-  cursor: pointer;
-}
-
 .outro-card--link {
   transition: transform 0.16s ease, box-shadow 0.16s ease,
     border-color 0.16s ease;
@@ -415,13 +396,6 @@
   }
 }
 
-.outro-panel {
-  padding: var(--outro-card-padding);
-  border: 1px solid var(--outro-border);
-  border-radius: var(--outro-radius);
-  background-color: var(--outro-surface, transparent);
-}
-
 .outro-empty {
   padding: clamp(1.25rem, 4vw, 2rem);
   border: 1px dashed var(--outro-border-strong);
@@ -438,17 +412,6 @@
   margin-bottom: 0;
 }
 
-.outro-select,
-.outro-input,
-.outro-textarea {
-  padding: var(--outro-control-padding);
-  border: 1px solid var(--outro-border-strong);
-  border-radius: var(--outro-radius-sm);
-  background-color: var(--outro-surface, transparent);
-  color: inherit;
-  font: inherit;
-}
-
 .outro-button {
   display: inline-flex;
   align-items: center;
@@ -727,7 +690,6 @@
 .outro-guitar {
   display: flex;
   flex-direction: column;
-  align-items: center;
   gap: 14px;
   width: 100%;
   max-width: 100%;
@@ -735,7 +697,6 @@
   border-radius: var(--outro-instrument-radius);
   background-color: var(--outro-instrument-bg);
   overflow-x: auto;
-  align-items: center;
   align-items: safe center;
 }
 
@@ -910,7 +871,6 @@
 .outro-piano {
   display: flex;
   flex-direction: column;
-  align-items: center;
   gap: 14px;
   width: 100%;
   max-width: 100%;
@@ -918,7 +878,6 @@
   border-radius: var(--outro-instrument-radius);
   background-color: var(--outro-instrument-bg);
   overflow-x: auto;
-  align-items: center;
   align-items: safe center;
 }
 
@@ -1207,6 +1166,15 @@
   position: relative;
 }
 
+.outro-chord-chart-fields__legend {
+  float: none;
+}
+
+legend.outro-chord-chart-fields__legend {
+  float: none;
+  margin-bottom: 0;
+}
+
 .outro-chord-chart__body {
   margin: 0;
   padding: 0.85rem;
@@ -1259,6 +1227,12 @@
   border: 0;
 }
 
+.outro-chord-chart-fields__hint {
+  margin: 0;
+  font-size: 0.9rem;
+  color: var(--outro-muted);
+}
+
 .outro-inline-form {
   display: inline;
 }

data/app/helpers/outro_rails/chord_charts_helper.rb

@@ -3,6 +3,7 @@
 module OutroRails
   module ChordChartsHelper
     include CapoHelper
+    include ClassNamesHelper
     include InstrumentsHelper
     include TransposerHelper
 
@@ -24,13 +25,19 @@ module OutroRails
       Instruments::ALL.map { |instrument| [ instrument.titleize, instrument ] }
     end
 
-    def chord_chart_area(form, method, **options)
-      chord_chart = form.object.public_send(method)
+    def chord_chart_area(form, method, legend: "Chord chart", **options)
+      record = form.object
+      required = record.public_send(:"#{method}_required?")
+
+      chord_chart = record.public_send(method) ||
+                    OutroRails::ChordChart.new(name: method.to_s)
 
       form.fields_for(:"chord_chart_#{method}",
                       chord_chart, **options) do |chord_chart_form|
         render partial: "outro_rails/chord_charts/fields",
-               locals: { f: chord_chart_form }
+               locals: { f: chord_chart_form,
+                         required: required,
+                         legend: legend }
       end
     end
 

data/app/helpers/outro_rails/class_names_helper.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module OutroRails
+  module ClassNamesHelper
+    def outro_button_class(*modifiers)
+      outro_element_class(:button, *modifiers)
+    end
+
+    def outro_input_class(*modifiers)
+      outro_element_class(:input, *modifiers)
+    end
+
+    def outro_label_class(*modifiers)
+      outro_element_class(:label, *modifiers)
+    end
+
+    def outro_select_class(*modifiers)
+      outro_element_class(:select, *modifiers)
+    end
+
+    def outro_textarea_class(*modifiers)
+      outro_element_class(:textarea, *modifiers)
+    end
+
+    def outro_element_class(element, *modifiers)
+      tokens = [ OutroRails.class_for(element), *modifiers ]
+                 .flat_map { |token| token.to_s.split(/\s+/) }
+                 .reject(&:empty?)
+                 .uniq
+
+      tokens.join(" ").presence
+    end
+  end
+end

data/app/models/outro_rails/chord_chart.rb

@@ -9,6 +9,8 @@ module OutroRails
       Theory::Key.canonical(:minor).map(&:to_s)
     ).freeze
 
+    CONTENT_ATTRIBUTES = %w[artist song body].freeze
+
     belongs_to :record, polymorphic: true, touch: true
 
     has_many :voicings,
@@ -22,7 +24,6 @@ module OutroRails
     validates :name, presence: true
     validates :artist, presence: true
     validates :song, presence: true
-    validates :body, presence: true
     validates :tuning,
               inclusion: { in: Instruments::Guitar::Tunings.slugs },
               allow_blank: true
@@ -31,6 +32,15 @@ module OutroRails
               allow_nil: true
     validates :key, inclusion: { in: KEY_OPTIONS }, allow_blank: true
 
+    def self.blank_attributes?(attributes)
+      return true if attributes.nil?
+
+      attributes = attributes.to_h if attributes.respond_to?(:permitted?)
+      attributes = attributes.to_h.with_indifferent_access
+
+      CONTENT_ATTRIBUTES.all? { |field| attributes[field].blank? }
+    end
+
     def to_key
       Theory::Key.parse(key.presence || "C")
     end

data/app/views/outro_rails/caged/show.html.erb

@@ -16,27 +16,27 @@
   <%= form_with url: caged_picker_path, method: :get,
         class: "outro-picker" do %>
     <label class="outro-picker__field">
-      <span class="outro-label">Root</span>
+      <%= tag.span "Root", class: outro_label_class %>
       <%= select_tag :root,
             options_for_select(scale_root_options, @root.path_slug),
-            class: "outro-select",
+            class: outro_select_class,
             onchange: "this.form.requestSubmit()" %>
     </label>
 
     <label class="outro-picker__field">
-      <span class="outro-label">Shape</span>
+      <%= tag.span "Shape", class: outro_label_class %>
       <%= select_tag :shape,
             options_for_select(
               OutroRails::Instruments::Guitar::ChordShapes::CAGED_LETTERS
                 .map { |l| [ "#{l} shape", l.downcase ] },
               @letter.downcase
             ),
-            class: "outro-select",
+            class: outro_select_class,
             onchange: "this.form.requestSubmit()" %>
     </label>
 
     <%= button_tag type: :submit, name: nil,
-      class: "outro-button",
+      class: outro_button_class,
       "aria-label": "Show Shapes" do %>
       <%= image_tag "outro_rails/shapes.svg", class: 'outro-button__icon' %>
       Show Shapes

data/app/views/outro_rails/capo/show.html.erb

@@ -14,7 +14,8 @@
       ] %>
 
   <div class="outro-panel outro-filters">
-    <span class="outro-label" id="capo-position-label">Capo position</span>
+    <%= tag.span "Capo position", id: "capo-position-label",
+          class: outro_label_class %>
     <nav class="outro-chip-row outro-capo-frets"
          aria-labelledby="capo-position-label">
       <% OutroRails::Instruments::Guitar::Capo::FRETS.each do |fret| %>

data/app/views/outro_rails/chord_charts/_chart.html.erb

@@ -88,7 +88,7 @@
         <span class="outro-label">Instrument</span>
         <%= select_tag :instrument,
               options_for_select(chord_chart_instrument_options, instrument),
-              class: "outro-select",
+              class: outro_select_class,
               onchange: "this.form.requestSubmit()" %>
         <%= hidden_field_tag :to_key, to_key if to_key %>
       <% end %>
@@ -99,15 +99,18 @@
         <%= select_tag :to_key,
               grouped_options_for_select(chord_chart_key_options,
                                          to_key || chord_chart.key),
-              class: "outro-select",
+              class: outro_select_class,
               onchange: "this.form.requestSubmit()" %>
         <%= hidden_field_tag :instrument, instrument %>
       <% end %>
 
       <% if transposed %>
-        <%= link_to "Reset to #{chord_chart.key}",
-              url_for(request.query_parameters.except("to_key")),
-              class: "outro-chip outro-chip--link" %>
+        <%= link_to url_for(request.query_parameters.except("to_key")),
+              class: outro_button_class do %>
+          <%= image_tag "outro_rails/undo.svg",
+                class: "outro-button__icon" %>
+          <%= "Reset to #{chord_chart.key}" %>
+        <% end %>
       <% end %>
     </div>
   </section>
@@ -186,7 +189,7 @@
                   <% if all_voicings.many? %>
                     <div class="outro-voicing-cycler__nav">
                       <button type="button" data-voicing-prev
-                              class="outro-button
+                              class="<%= outro_button_class %>
                                      outro-voicing-cycler__arrow"
                               aria-label=
                                 "Previous voicing for <%= symbol %>">
@@ -195,7 +198,7 @@
                       <span class="outro-voicing-cycler__counter"
                             data-voicing-counter aria-live="polite"></span>
                       <button type="button" data-voicing-next
-                              class="outro-button
+                              class="<%= outro_button_class %>
                                      outro-voicing-cycler__arrow"
                               aria-label=
                                 "Next voicing for <%= symbol %>">
@@ -231,7 +234,7 @@
                           )
                         %>
                         <%= button_to revert_path,
-                              method: :delete, class: "outro-button",
+                              method: :delete, class: outro_button_class,
                               form_class: "outro-inline-form" do %>
                           <%= image_tag "outro_rails/undo.svg",
                                 class: "outro-button__icon" %>
@@ -259,7 +262,7 @@
                           )
                         %>
                         <%= button_to revert_path,
-                              method: :delete, class: "outro-button",
+                              method: :delete, class: outro_button_class,
                               form_class: "outro-inline-form" do %>
                           <%= image_tag "outro_rails/undo.svg",
                                 class: "outro-button__icon" %>

data/app/views/outro_rails/chord_charts/_fields.html.erb

@@ -5,46 +5,80 @@
 
     form_with model: @song do |form|
       form.chord_chart_area :chord_sheet
+      form.chord_chart_area :chord_sheet, legend: "Lead sheet"
+      form.chord_chart_area :chord_sheet, legend: false
     end
+
+  Locals:
+    f        - the nested form builder for the chord chart
+    required - whether the owner declared the chart with `required: true`
+               (the default). When false, leaving every field blank
+               saves the record without a chart.
+    legend   - heading shown above the fields, default "Chord chart".
+               Pass false to leave it out (when the host page already has
+               its own heading for this section).
+%>
+
+<%
+  required = local_assigns.fetch(:required, true)
+  legend   = local_assigns.fetch(:legend, "Chord Chart")
 %>
 
 <fieldset class="outro-chord-chart-fields">
+  <% if legend %>
+    <legend class="outro-chord-chart-fields__legend">
+      <span class="outro-section-heading">
+        <%= legend %>
+        <% unless required %>
+          <span class="outro-symbol-list__detail">Optional</span>
+        <% end %>
+      </span>
+    </legend>
+  <% end %>
+
+  <% unless required %>
+    <p class="outro-chord-chart-fields__hint">
+      Leave artist, song, and chords blank if there is no chord chart.
+    </p>
+  <% end %>
+
   <div class="outro-picker outro-picker--grid outro-picker--cols-2">
     <label class="outro-picker__field">
-      <span class="outro-label">Artist</span>
-      <%= f.text_field :artist, class: "outro-input" %>
+      <%= tag.span "Artist", class: outro_label_class %>
+      <%= f.text_field :artist, class: outro_input_class %>
     </label>
 
     <label class="outro-picker__field">
-      <span class="outro-label">Song</span>
-      <%= f.text_field :song, class: "outro-input" %>
+      <%= tag.span "Song", class: outro_label_class %>
+      <%= f.text_field :song, class: outro_input_class %>
     </label>
   </div>
 
   <div class="outro-picker outro-picker--grid outro-picker--cols-3">
     <label class="outro-picker__field">
-      <span class="outro-label">Tuning</span>
+      <%= tag.span "Tuning", class: outro_label_class %>
       <%= f.select :tuning, chord_chart_tuning_options, {},
-            class: "outro-select" %>
+            class: outro_select_class %>
     </label>
 
     <label class="outro-picker__field">
-      <span class="outro-label">Capo</span>
+      <%= tag.span "Capo", class: outro_label_class %>
       <%= f.select :capo, chord_chart_capo_options,
-            { include_blank: "None" }, class: "outro-select" %>
+            { include_blank: "None" }, class: outro_select_class %>
     </label>
 
     <label class="outro-picker__field">
-      <span class="outro-label">Key</span>
-      <%= f.select :key, chord_chart_key_options, {}, class: "outro-select" %>
+      <%= tag.span "Key", class: outro_label_class %>
+      <%= f.select :key, chord_chart_key_options, {},
+            class: outro_select_class %>
     </label>
   </div>
 
   <label class="outro-transposer__field">
-    <span class="outro-label">Chords &amp; lyrics</span>
+    <%= tag.span "Chords & lyrics (Optional)", class: outro_label_class %>
     <%= f.text_area :body,
           rows: 16,
           placeholder: "Paste or type a chord chart here.",
-          class: "outro-textarea outro-transposer__textarea" %>
+          class: outro_textarea_class("outro-transposer__textarea") %>
   </label>
 </fieldset>

data/app/views/outro_rails/chords/_filter.html.erb

@@ -5,9 +5,9 @@
     <%= search_field_tag :q, params[:missing],
           placeholder: "F#m7b5 or fsharpm7flat5",
           "aria-label": "Go to chord by symbol or slug",
-          class: "outro-input outro-filters__search-input" %>
+          class: outro_input_class("outro-filters__search-input") %>
     <%= button_tag type: :submit, name: nil,
-      class: "outro-button",
+      class: outro_button_class,
       "aria-label": "Search" do %>
       <%= image_tag "outro_rails/search.svg", class: 'outro-button__icon' %>
       Search
@@ -18,52 +18,52 @@
   <%= form_with url: chords_path, method: :get,
         class: "outro-picker outro-filters__facets" do %>
     <label class="outro-picker__field">
-      <span class="outro-label">Root</span>
+      <%= tag.span "Root", class: outro_label_class %>
       <%= select_tag :root,
             options_for_select(chord_root_options, @filters[:root]),
             include_blank: "Any",
-            class: "outro-select",
+            class: outro_select_class,
             onchange: "this.form.requestSubmit()" %>
     </label>
 
     <label class="outro-picker__field">
-      <span class="outro-label">Quality</span>
+      <%= tag.span "Quality", class: outro_label_class %>
       <%= select_tag :quality,
             options_for_select(chord_quality_options, @filters[:quality]),
             include_blank: "Any",
-            class: "outro-select",
+            class: outro_select_class,
             onchange: "this.form.requestSubmit()" %>
     </label>
 
     <label class="outro-picker__field">
-      <span class="outro-label">Extension</span>
+      <%= tag.span "Extension", class: outro_label_class %>
       <%= select_tag :extension,
             options_for_select(chord_extension_options, @filters[:extension]),
             include_blank: "Any",
-            class: "outro-select",
+            class: outro_select_class,
             onchange: "this.form.requestSubmit()" %>
     </label>
 
     <label class="outro-picker__field">
-      <span class="outro-label">Alteration</span>
+      <%= tag.span "Alteration", class: outro_label_class %>
       <%= select_tag :alteration,
             options_for_select(chord_alteration_options, @filters[:alteration]),
             include_blank: "Any",
-            class: "outro-select",
+            class: outro_select_class,
             onchange: "this.form.requestSubmit()" %>
     </label>
 
     <label class="outro-picker__field">
-      <span class="outro-label">Added tone</span>
+      <%= tag.span "Added tone", class: outro_label_class %>
       <%= select_tag :added_tone,
             options_for_select(chord_added_tone_options, @filters[:added_tone]),
             include_blank: "Any",
-            class: "outro-select",
+            class: outro_select_class,
             onchange: "this.form.requestSubmit()" %>
     </label>
 
     <%= button_tag type: :submit, name: nil,
-      class: "outro-button",
+      class: outro_button_class,
       "aria-label": "Filter" do %>
       <%= image_tag "outro_rails/filter.svg", class: 'outro-button__icon' %>
       Filter
@@ -71,7 +71,7 @@
 
     <% if filters_active? %>
       <%= link_to chords_path,
-        class: "outro-button",
+        class: outro_button_class,
         "aria-label": "Clear" do %>
         <%= image_tag "outro_rails/clear.svg", class: 'outro-button__icon' %>
         Clear

data/app/views/outro_rails/chords/index.html.erb

@@ -19,7 +19,7 @@
     <div class="outro-empty">
       <p>No chords match those filters.</p>
       <%= link_to chords_path,
-        class: "outro-button",
+        class: outro_button_class,
         "aria-label": "Clear Filters" do %>
         <%= image_tag "outro_rails/clear.svg", class: 'outro-button__icon' %>
         Clear Filters

data/app/views/outro_rails/circle_of_fifths/show.html.erb

@@ -63,9 +63,8 @@
       </dl>
 
       <div class="outro-card__footer">
-        <span class="outro-label" id="scale-instruments-label">
-          See this scale on
-        </span>
+        <%= tag.span "See this scale on", id: "scale-instruments-label",
+              class: outro_label_class %>
         <div class="outro-chip-row" role="group"
              aria-labelledby="scale-instruments-label">
           <% OutroRails::ScalesController::INSTRUMENTS.each do |instrument| %>

data/app/views/outro_rails/instruments/_guitar.html.erb

@@ -12,17 +12,17 @@
       <%= hidden_field_tag :instrument, @instrument %>
 
       <label class="outro-picker__field">
-        <span class="outro-label">Tuning</span>
+        <%= tag.span "Tuning", class: outro_label_class %>
         <%= select_tag :tuning,
               options_for_select(guitar_tuning_options, tuning.slug),
-              class: "outro-select",
+              class: outro_select_class,
               onchange: "this.form.requestSubmit()" %>
       </label>
 
       <%# Fallback for keyboard users / no JS; the select auto-submits
           on change. %>
       <%= button_tag type: :submit, name: nil,
-        class: "outro-button",
+        class: outro_button_class,
         "aria-label": "Show Tuning" do %>
         <%= image_tag "outro_rails/guitar.svg", class: 'outro-button__icon' %>
         Show Tuning

data/app/views/outro_rails/scales/_picker.html.erb

@@ -3,33 +3,33 @@
   <%= hidden_field_tag :instrument, @instrument %>
 
   <label class="outro-picker__field">
-    <span class="outro-label">Root</span>
+    <%= tag.span "Root", class: outro_label_class %>
     <%= select_tag :root,
           options_for_select(scale_root_options, @scale.root.path_slug),
-          class: "outro-select",
+          class: outro_select_class,
           onchange: "this.form.requestSubmit()" %>
   </label>
 
   <label class="outro-picker__field">
-    <span class="outro-label">Scale</span>
+    <%= tag.span "Scale", class: outro_label_class %>
     <%= select_tag :type,
           options_for_select(scale_type_options, @scale.slug),
-          class: "outro-select",
+          class: outro_select_class,
           onchange: "this.form.requestSubmit()" %>
   </label>
 
   <% if @instrument == "guitar" %>
     <label class="outro-picker__field">
-      <span class="outro-label">Tuning</span>
+      <%= tag.span "Tuning", class: outro_label_class %>
       <%= select_tag :tuning,
             options_for_select(guitar_tuning_options, @tuning&.slug),
-            class: "outro-select",
+            class: outro_select_class,
             onchange: "this.form.requestSubmit()" %>
     </label>
   <% end %>
 
   <%= button_tag type: :submit, name: nil,
-    class: "outro-button",
+    class: outro_button_class,
     "aria-label": "Show Scale" do %>
     <%= image_tag "outro_rails/scales.svg", class: 'outro-button__icon' %>
     Show Scale

data/app/views/outro_rails/scales/show.html.erb

@@ -77,9 +77,8 @@
   <% others = OutroRails::ScalesController::INSTRUMENTS - [ @instrument ] %>
   <% if others.any? %>
     <div class="outro-switch">
-      <span class="outro-label" id="scale-switch-label">
-        View this scale on
-      </span>
+      <%= tag.span "View this scale on", id: "scale-switch-label",
+            class: outro_label_class %>
       <div class="outro-chip-row" role="group"
            aria-labelledby="scale-switch-label">
         <% others.each do |other| %>

data/app/views/outro_rails/transposer/show.html.erb

@@ -21,39 +21,39 @@
             class: "outro-transposer" do %>
         <div class="outro-picker outro-picker--flush">
           <label class="outro-picker__field">
-            <span class="outro-label">Convert</span>
+            <%= tag.span "Convert", class: outro_label_class %>
             <%= select_tag :mode,
                   options_for_select(transposer_mode_options, @mode),
-                  class: "outro-select" %>
+                  class: outro_select_class %>
           </label>
 
           <label class="outro-picker__field">
-            <span class="outro-label">Original key</span>
+            <%= tag.span "Original key", class: outro_label_class %>
             <%= select_tag :from_key,
                   grouped_options_for_select(transposer_key_options,
                                              @from_key.to_s),
-                  class: "outro-select" %>
+                  class: outro_select_class %>
           </label>
 
           <label class="outro-picker__field">
-            <span class="outro-label">New key</span>
+            <%= tag.span "New key", class: outro_label_class %>
             <%= select_tag :to_key,
                   grouped_options_for_select(transposer_key_options,
                                              @to_key.to_s),
-                  class: "outro-select" %>
+                  class: outro_select_class %>
           </label>
         </div>
 
         <label class="outro-transposer__field">
-          <span class="outro-label">Chords and lyrics</span>
+          <%= tag.span "Chords and lyrics", class: outro_label_class %>
           <%= text_area_tag :text, @text,
                 rows: 8,
                 placeholder: "Paste a chord chart here.",
-                class: "outro-textarea outro-transposer__textarea" %>
+                class: outro_textarea_class("outro-transposer__textarea") %>
         </label>
 
         <%= button_tag type: :submit, name: nil,
-          class: "outro-button",
+          class: outro_button_class,
           "aria-label": "Transpose" do %>
           <%= image_tag "outro_rails/transposer.svg",
                 class: 'outro-button__icon' %>

data/lib/outro_rails/chord_chart_attribute.rb

@@ -5,7 +5,7 @@ module OutroRails
     extend ActiveSupport::Concern
 
     class_methods do
-      def has_chord_chart(name, dependent: :destroy)
+      def has_chord_chart(name, required: true, dependent: :destroy)
         association_name = :"chord_chart_#{name}"
 
         has_one association_name,
@@ -14,25 +14,77 @@ module OutroRails
                 as: :record,
                 inverse_of: :record,
                 autosave: true,
+                validate: false,
                 dependent: dependent
 
         accepts_nested_attributes_for association_name
 
+        validate do
+          chart = association(association_name).target
+          next if chart.nil? || chart.destroyed? || chart.marked_for_destruction?
+          next unless chart.changed_for_autosave?
+          next if chart.valid?
+
+          chart.errors.each do |error|
+            attribute = error.attribute == :base ? name : :"#{name}.#{error.attribute}"
+            errors.import(error, attribute: attribute)
+          end
+        end
+
+        fallback = if required
+                     "build_#{association_name}(name: #{name.to_s.inspect})"
+                   else
+                     "nil"
+                   end
+
         class_eval <<-CODE, __FILE__, __LINE__ + 1
           def #{name}
-            #{association_name} ||
-              build_#{association_name}(name: #{name.to_s.inspect})
+            chart = #{association_name}
+            return chart if chart && !chart.destroyed? &&
+                            !chart.marked_for_destruction?
+
+            #{fallback}
           end
 
           def #{name}?
-            #{association_name}.present?
+            chart = #{association_name}
+            !chart.nil? && !chart.destroyed? && !chart.marked_for_destruction?
           end
 
           def #{name}=(attributes)
-            #{name}.assign_attributes(attributes)
+            if attributes.nil?
+              self.#{association_name} = nil
+            else
+              chart = #{association_name} ||
+                      build_#{association_name}(name: #{name.to_s.inspect})
+              chart.assign_attributes(attributes)
+            end
+          end
+
+          def #{name}_required?
+            #{required}
           end
         CODE
 
+        unless required
+          class_eval <<-CODE, __FILE__, __LINE__ + 1
+            def #{association_name}_attributes=(attributes)
+              unless OutroRails::ChordChart.blank_attributes?(attributes)
+                return super
+              end
+
+              chart = #{association_name}
+              return unless chart
+
+              if chart.persisted?
+                chart.mark_for_destruction
+              else
+                self.#{association_name} = nil
+              end
+            end
+          CODE
+        end
+
         scope :"with_#{name}", -> { includes(association_name) }
       end
     end

data/lib/outro_rails/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module OutroRails
-  VERSION = "0.1.4"
+  VERSION = "0.1.6"
 end

data/lib/outro_rails.rb

@@ -18,4 +18,35 @@ module OutroRails
     !!chord_chart_voicing_authorization.call(chord_chart: chord_chart,
                                              controller:  controller)
   end
+
+  ELEMENT_CLASS_DEFAULTS = {
+    button:   "outro-button",
+    input:    "outro-input",
+    label:    "outro-label",
+    select:   "outro-select",
+    textarea: "outro-textarea"
+  }.freeze
+
+  mattr_accessor :button_class,   default: ELEMENT_CLASS_DEFAULTS[:button]
+  mattr_accessor :input_class,    default: ELEMENT_CLASS_DEFAULTS[:input]
+  mattr_accessor :label_class,    default: ELEMENT_CLASS_DEFAULTS[:label]
+  mattr_accessor :select_class,   default: ELEMENT_CLASS_DEFAULTS[:select]
+  mattr_accessor :textarea_class, default: ELEMENT_CLASS_DEFAULTS[:textarea]
+
+  def self.configure
+    yield self
+    self
+  end
+
+  def self.class_for(element)
+    key = element.to_sym
+
+    unless ELEMENT_CLASS_DEFAULTS.key?(key)
+      raise ArgumentError,
+            "unknown element #{element.inspect}; expected one of " \
+            "#{ELEMENT_CLASS_DEFAULTS.keys.map(&:inspect).join(', ')}"
+    end
+
+    public_send(:"#{key}_class")
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: outro_rails
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.1.6
 platform: ruby
 authors:
 - endtoendpaper
@@ -79,6 +79,7 @@ files:
 - app/helpers/outro_rails/chord_charts_helper.rb
 - app/helpers/outro_rails/chords_helper.rb
 - app/helpers/outro_rails/circle_of_fifths_helper.rb
+- app/helpers/outro_rails/class_names_helper.rb
 - app/helpers/outro_rails/instruments_helper.rb
 - app/helpers/outro_rails/scales_helper.rb
 - app/helpers/outro_rails/transposer_helper.rb