unmagic-components 0.2.0 → 0.3.0

data/lib/unmagic/components/action_view_helpers.rb

@@ -164,6 +164,22 @@ module Unmagic
         Components::Button.classes(variant, size: size)
       end
 
+      # The class string for a form control outside a form builder, so a select_tag
+      # or a hand-written input matches the controls the builder styles.
+      #
+      #   <%= select_tag "status", options_for_select(%w[Open Closed]), class: control_classes(:select) %>
+      #   <%= search_field_tag "q", params[:q], class: control_classes(:input, size: :small) %>
+      #
+      # kind: :input, :text_area, :password, :date, :select, :check or :radio.
+      # size: :small or :large sits a box level with a button_classes button of the
+      # same size; a check or radio takes none. The classes come from
+      # config.control_class, so they follow the app's own when it has some, and
+      # size: only adds the gem's modifier while the gem's class is in use. Rails'
+      # own *_tag helpers are never restyled; this is how to opt one in.
+      def control_classes(kind, size: nil)
+        Components::Control.classes(self, kind, size: size)
+      end
+
       # Mounts the shared modal: a <dialog> around the turbo frame modal links load
       # into. Render it once, in the layout.
       #
@@ -483,7 +499,7 @@ module Unmagic
 
       # text_area_tag, growing with its content. See FormBuilder#autogrow_text_area.
       def autogrow_text_area_tag(name, content = nil, **options)
-        Components::Autogrow.wrap(self, text_area_tag(name, content, options))
+        Components::Autogrow.wrap(self, text_area_tag(name, content, Components::Control.merge(self, options, :text_area)))
       end
 
       # A hidden field holding a fresh UUIDv7, outside a form builder. See

data/lib/unmagic/components/configuration.rb

@@ -7,7 +7,7 @@ module Unmagic
     # library. An app that already owns these concerns points them at its own
     # versions in an initializer.
     class Configuration
-      attr_writer :empty_state, :pagination, :pagy_for, :submit_class, :modal_frame_id, :flash_tones
+      attr_writer :empty_state, :pagination, :pagy_for, :submit_class, :control_class, :modal_frame_id, :flash_tones
 
       # The tone each flash type's toast wears, keyed by the flash type as a string.
       # A type that isn't listed is :info.
@@ -49,6 +49,13 @@ module Unmagic
       def submit_class
         @submit_class ||= ->(_view, variant) { "UnmagicButton UnmagicButton--#{variant}" }
       end
+
+      # The classes on a form control. Called with (view, kind), where kind is one
+      # of Control::CLASSES' keys (:input, :select, :check…); return an app's own
+      # classes, or nil to leave the control unstyled.
+      def control_class
+        @control_class ||= ->(_view, kind) { Control::CLASSES.fetch(kind) }
+      end
     end
   end
 end

data/lib/unmagic/components/control.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Unmagic
+  module Components
+    # The class a form control wears, by kind. FormBuilder and control_classes both
+    # ask here, and this asks the configured control_class seam, so an app with
+    # input styles of its own swaps them in, or opts out, in one place. See
+    # ActionViewHelpers#control_classes.
+    module Control
+      # Each kind of control the components render, and the gem's class for it.
+      CLASSES = {
+        input: "UnmagicInput",
+        text_area: "UnmagicInput",
+        password: "UnmagicInput",
+        date: "UnmagicInput",
+        select: "UnmagicSelect",
+        check: "UnmagicCheck",
+        radio: "UnmagicRadio"
+      }.freeze
+
+      SIZES = %i[small large].freeze
+
+      # Only the boxes you type into or pick from have a size; a checkbox or radio
+      # is sized by the text beside it.
+      SIZED = %i[input text_area password date select].freeze
+
+      # The classes for a kind of control, or nil when the seam gives none. size:
+      # adds the gem's modifier, but only while the gem's own class is in use: an
+      # app that swapped in its own classes has no rules for the modifier.
+      def self.classes(view, kind, size: nil)
+        validate!(kind, size)
+
+        base = Components.configuration.control_class.call(view, kind)
+        modifier = "#{CLASSES[kind]}--#{size}" if size && base.to_s.split.include?(CLASSES[kind])
+        view.class_names(base, modifier).presence
+      end
+
+      # A copy of options with the kind's classes in front of any class: the caller
+      # gave, so the caller's can override the gem's.
+      def self.merge(view, options, kind)
+        options = (options || {}).dup
+        given = options.delete(:class) || options.delete("class")
+
+        merged = view.class_names(classes(view, kind), given)
+        options[:class] = merged if merged.present?
+        options
+      end
+
+      def self.validate!(kind, size)
+        unless CLASSES.key?(kind)
+          raise ArgumentError, "unknown control kind #{kind.inspect} (expected one of #{CLASSES.keys.inspect})"
+        end
+        return if size.nil?
+
+        unless SIZES.include?(size)
+          raise ArgumentError, "unknown control size #{size.inspect} (expected one of #{SIZES.inspect})"
+        end
+        raise ArgumentError, "a #{kind} control has no size" unless SIZED.include?(kind)
+      end
+    end
+  end
+end

data/lib/unmagic/components/engine.rb

@@ -21,14 +21,13 @@ module Unmagic
         end
       end
 
-      # The components' stylesheet is a plain CSS file, deliberately not part of any
-      # Tailwind build: Tailwind only generates classes it can see, and it does not
-      # scan installed gems. Serving it through the asset pipeline keeps the gem's
-      # look self-contained and themeable through --unmagic-* custom properties.
+      # The components' JavaScript, served through the asset pipeline. There is no
+      # stylesheet to serve: the styles are Tailwind source in
+      # app/assets/tailwind/unmagic_components/engine.css, which tailwindcss-rails
+      # finds by this engine's name and the host's own Tailwind build compiles.
       initializer "unmagic_components.assets" do |app|
         next unless app.config.respond_to?(:assets)
 
-        app.config.assets.paths << Engine.root.join("app/assets/stylesheets")
         app.config.assets.paths << Engine.root.join("app/assets/javascripts")
       end
 

data/lib/unmagic/components/form_builder.rb

@@ -15,10 +15,13 @@ module Unmagic
     #     <%= form.submit "Add label" %>
     #   <% end %>
     #
-    # What the control itself looks like is deliberately not decided here. Apps
-    # style inputs in incompatible ways — a class on every input, or a bare-element
-    # rule — and a component library that picked one would be wrong in the other. So
-    # the builder emits structure and leaves the control's own appearance alone.
+    # The controls it builds are styled too. Each wears a class for its kind —
+    # UnmagicInput, UnmagicSelect, UnmagicCheck — which comes from the
+    # control_class seam (see Control). The styles hang off those classes and never
+    # off bare elements, so an input the gem didn't render keeps whatever the app
+    # gives it, and an app with input styles of its own points the seam at them, or
+    # returns nil to opt out. Rails' check_box and radio_button are left as they
+    # are: a checkbox is styled where the builder lays it out beside its label.
     class FormBuilder < ::ActionView::Helpers::FormBuilder
       # Verbs the plain "drop a trailing -e, add -ing" rule gets wrong (consonant
       # doubling). Everything else the rule handles: Save -> Saving, Create ->
@@ -31,6 +34,51 @@ module Unmagic
         "run" => "Running"
       }.freeze
 
+      # The builder's own controls and the kind each is styled as. Each keeps its
+      # Rails signature and gains the kind's class. Guarded because the set differs
+      # across Rails versions (textarea is Rails 8's name for text_area).
+      CONTROL_KINDS = {
+        text_field: :input, email_field: :input, number_field: :input, url_field: :input,
+        search_field: :input, telephone_field: :input, phone_field: :input,
+        password_field: :password,
+        text_area: :text_area, textarea: :text_area,
+        date_field: :date, time_field: :date, datetime_field: :date, datetime_local_field: :date,
+        month_field: :date, week_field: :date
+      }.freeze
+
+      CONTROL_KINDS.each do |name, kind|
+        next unless ::ActionView::Helpers::FormBuilder.method_defined?(name)
+
+        define_method(name) do |method, options = {}|
+          super(method, Components::Control.merge(@template, options, kind))
+        end
+      end
+
+      def select(method, choices = nil, options = {}, html_options = {}, &block)
+        super(method, choices, options, Components::Control.merge(@template, html_options, :select), &block)
+      end
+
+      def collection_select(method, collection, value_method, text_method, options = {}, html_options = {})
+        super(method, collection, value_method, text_method, options,
+          Components::Control.merge(@template, html_options, :select))
+      end
+
+      def grouped_collection_select(method, collection, group_method, group_label_method, option_key_method,
+        option_value_method, options = {}, html_options = {})
+        super(method, collection, group_method, group_label_method, option_key_method, option_value_method, options,
+          Components::Control.merge(@template, html_options, :select))
+      end
+
+      def time_zone_select(method, priority_zones = nil, options = {}, html_options = {})
+        super(method, priority_zones, options, Components::Control.merge(@template, html_options, :select))
+      end
+
+      if ::ActionView::Helpers::FormBuilder.method_defined?(:weekday_select)
+        def weekday_select(method, options = {}, html_options = {})
+          super(method, options, Components::Control.merge(@template, html_options, :select))
+        end
+      end
+
       # Label + control + hint + error, wrapped consistently. Pass a block to supply
       # a control the builder doesn't know how to make (a select, a file picker, two
       # inputs side by side); otherwise it is built from `as:`.
@@ -91,7 +139,7 @@ module Unmagic
           text << @template.content_tag(:span, hint, class: "UnmagicHint") if hint
 
           @template.safe_join [
-            check_box(method, options),
+            check_box(method, Components::Control.merge(@template, options, :check)),
             @template.content_tag(:span, @template.safe_join(text), class: "UnmagicCheckField__text")
           ]
         end
@@ -103,7 +151,7 @@ module Unmagic
         body = collection_check_boxes(method, collection, value_method, text_method) do |check_box|
           @template.content_tag(:label, class: "UnmagicCheckField") do
             @template.safe_join [
-              check_box.check_box(options),
+              check_box.check_box(Components::Control.merge(@template, options, :check)),
               @template.content_tag(:span, check_box.text, class: "UnmagicCheckField__label")
             ]
           end

data/lib/unmagic/components/version.rb

@@ -2,6 +2,6 @@
 
 module Unmagic
   module Components
-    VERSION = "0.2.0"
+    VERSION = "0.3.0"
   end
 end

data/lib/unmagic/components.rb

@@ -8,6 +8,7 @@ require "active_support/core_ext/string/output_safety"
 
 require_relative "components/version"
 require_relative "components/configuration"
+require_relative "components/control"
 require_relative "components/renderers/empty_state"
 require_relative "components/renderers/pagination"
 require_relative "components/table_tag"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: unmagic-components
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Keith Pitt
@@ -83,8 +83,9 @@ description: UI components for Rails views in the spirit of form_for. Builders f
   index tables (sortable, deferred, kept live by Turbo Streams), detail lists, forms,
   cards, page headers and loading skeletons; a Turbo Frame modal, a confirm dialog
   and flash toasts; menus, tabs, tooltips, local times, copy buttons, autogrowing
-  textareas and UUID inputs as self-registering custom elements. Plain helpers and
-  CSS themed through custom properties, with no Tailwind or Stimulus required.
+  textareas and UUID inputs as self-registering custom elements. Plain helpers styled
+  with Tailwind CSS v4 (required; the host's build compiles the gem's component CSS),
+  with no Stimulus.
 email:
 - keith@unreasonable-magic.com
 executables: []
@@ -107,7 +108,7 @@ files:
 - app/assets/javascripts/unmagic/components/tooltip.js
 - app/assets/javascripts/unmagic/components/upsert.js
 - app/assets/javascripts/unmagic/components/uuid_input.js
-- app/assets/stylesheets/unmagic/components.css
+- app/assets/tailwind/unmagic_components/engine.css
 - config/importmap.rb
 - lib/unmagic-components.rb
 - lib/unmagic/components.rb
@@ -119,6 +120,7 @@ files:
 - lib/unmagic/components/card.rb
 - lib/unmagic/components/configuration.rb
 - lib/unmagic/components/confirm_template.rb
+- lib/unmagic/components/control.rb
 - lib/unmagic/components/copy_button.rb
 - lib/unmagic/components/detail_list.rb
 - lib/unmagic/components/detail_list/item.rb