unmagic-components 0.1.0

data/lib/unmagic/components/engine.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative "action_view_helpers"
+
+module Unmagic
+  module Components
+    class Engine < ::Rails::Engine
+      isolate_namespace Unmagic::Components
+
+      initializer "unmagic_components.helpers" do
+        ActiveSupport.on_load(:action_view) do
+          include Unmagic::Components::ActionViewHelpers
+        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.
+      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
+
+      # The one piece of JavaScript here: the `upsert` Turbo Stream action a live
+      # table's broadcasts use. Pinned rather than served so the host imports it by
+      # name; importmap-rails is optional, and an app without it simply never sees
+      # the pin (and cannot broadcast into a table).
+      initializer "unmagic_components.importmap", before: "importmap" do |app|
+        next unless app.config.respond_to?(:importmap)
+
+        app.config.importmap.paths << Engine.root.join("config/importmap.rb")
+        app.config.importmap.cache_sweepers << Engine.root.join("app/assets/javascripts")
+      end
+    end
+  end
+end

data/lib/unmagic/components/form_builder.rb

@@ -0,0 +1,205 @@
+# frozen_string_literal: true
+
+require "action_view"
+require "action_view/helpers"
+
+module Unmagic
+  module Components
+    # The chrome around a form control: the wrapper, the label and its required
+    # marker, the hint, and the error line — the part every app writes the same way
+    # and then repeats in every view.
+    #
+    #   <%= form_with model: @label, builder: Unmagic::Components::FormBuilder do |form| %>
+    #     <%= form.errors_summary %>
+    #     <%= form.field :name, "Name", required: true, hint: "Shown in the sidebar." %>
+    #     <%= 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.
+    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 ->
+      # Creating, Add -> Adding, Continue -> Continuing.
+      SUBMIT_GERUNDS = {
+        "submit" => "Submitting",
+        "set" => "Setting",
+        "get" => "Getting",
+        "log" => "Logging",
+        "run" => "Running"
+      }.freeze
+
+      # 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:`.
+      #
+      #   <%= form.field :email, "Email", required: true, as: :email_field %>
+      #   <%= form.field :role, "Role" do %>
+      #     <%= form.select :role, Role.all %>
+      #   <% end %>
+      def field(method, label_text = nil, required: false, hint: nil, as: :text_field, **options, &block)
+        options = options.merge(required: true) if required && !block
+
+        errors = errors_for(method)
+        options = options.merge("aria-invalid" => "true") if errors.any? && !block
+
+        control = block ? @template.capture(&block) : public_send(as, method, options)
+
+        @template.content_tag(:div, class: field_classes, data: { field: "" }) do
+          @template.safe_join [
+            (field_label(method, label_text, required) if label_text),
+            control,
+            (@template.content_tag(:p, hint, class: "UnmagicHint") if hint),
+            (@template.content_tag(:p, errors.to_sentence, class: "UnmagicError") if errors.any?)
+          ].compact
+        end
+      end
+
+      def label(method, text = nil, options = {}, &block)
+        options = options.dup
+        options[:class] = @template.class_names("UnmagicLabel", options[:class])
+        super
+      end
+
+      # Lay the contained fields out in a row — a first-name / last-name pair above
+      # other stacked fields. With inline: true they render compact and auto-width,
+      # for a filter toolbar. Groups can't nest.
+      def group(inline: false, **options, &block)
+        @group = inline ? :inline : :row
+        content = @template.capture(&block)
+        @group = nil
+
+        classes = @template.class_names(inline ? "UnmagicFieldGroup--inline" : "UnmagicFieldGroup", options[:class])
+        @template.content_tag(:div, content, class: classes)
+      end
+
+      # The record's whole-object errors, read as a sentence. Attribute errors show
+      # under their own field; these have nowhere else to go.
+      def errors_summary
+        errors = errors_for(:base)
+        return if errors.none?
+
+        @template.content_tag(:div, errors.to_sentence, class: "UnmagicFormErrors", role: "alert")
+      end
+
+      # A checkbox with its label beside it, and an optional hint under that.
+      def check_box_field(method, label_text, hint: nil, **options)
+        @template.content_tag(:label, class: "UnmagicCheckField") do
+          text = [ @template.content_tag(:span, label_text, class: "UnmagicCheckField__label") ]
+          text << @template.content_tag(:span, hint, class: "UnmagicHint") if hint
+
+          @template.safe_join [
+            check_box(method, options),
+            @template.content_tag(:span, @template.safe_join(text), class: "UnmagicCheckField__text")
+          ]
+        end
+      end
+
+      # A vertical list of checkboxes from a collection — Rails' collection_check_boxes
+      # with the labelling and spacing baked in. inline: true flows them in a row.
+      def check_box_collection(method, collection, value_method, text_method, inline: false, **options)
+        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),
+              @template.content_tag(:span, check_box.text, class: "UnmagicCheckField__label")
+            ]
+          end
+        end
+
+        @template.content_tag(:div, body, class: inline ? "UnmagicCheckList--inline" : "UnmagicCheckList")
+      end
+
+      # A submit button that says what it is doing while it does it: Turbo swaps the
+      # label for the conjugated verb ("Save" -> "Saving…") for the length of the
+      # submit. Pass submitting: false to leave the label alone, or a string to
+      # choose it.
+      def submit(value = nil, options = {}, &block)
+        options = options.dup
+        variant = options.delete(:variant) || :primary
+        submitting = options.delete(:submitting)
+        value ||= "Save"
+
+        options[:type] = "submit"
+        options[:class] = @template.class_names(
+          Components.configuration.submit_class.call(@template, variant), options[:class]
+        )
+        options[:data] = with_submitting_text(options[:data], value, submitting)
+
+        # A block is the caller's own button content — an icon beside the label —
+        # while `value` stays the label the submitting text is conjugated from.
+        @template.content_tag(:button, options) { block ? @template.capture(&block) : value }
+      end
+
+      # The value to show for a field, whether the object is a model or something
+      # hash-ish (a JSON Schema instance, a params object). Reads what the user
+      # actually typed when the object tracks that, so a rejected cast still shows
+      # their input rather than nil.
+      def form_value_for(method)
+        if hash_value_object?
+          @object.key?(method.to_s) ? @object[method.to_s] : @object[method.to_sym]
+        elsif @object.respond_to?("#{method}_before_type_cast") && form_value_came_from_user?(method)
+          @object.public_send("#{method}_before_type_cast")
+        elsif @object.respond_to?(method)
+          @object.public_send(method)
+        end
+      end
+
+      private
+
+      def field_classes
+        case @group
+        when :row then "UnmagicField UnmagicField--in-row"
+        when :inline then "UnmagicField UnmagicField--inline"
+        else "UnmagicField"
+        end
+      end
+
+      def field_label(method, text, required)
+        return label(method, text) unless required
+
+        label(method) do
+          @template.safe_join [ text, " ", @template.content_tag(:span, "*", class: "UnmagicLabel__required") ]
+        end
+      end
+
+      def errors_for(method)
+        return [] unless @object.respond_to?(:errors)
+
+        @object.errors[method]
+      end
+
+      def hash_value_object?
+        @object.respond_to?(:key?) && @object.respond_to?(:[]) && @object.respond_to?(:to_h)
+      end
+
+      def form_value_came_from_user?(method)
+        came_from_user = "#{method}_came_from_user?"
+        !@object.respond_to?(came_from_user) || @object.public_send(came_from_user)
+      end
+
+      # data-turbo-submits-with, unless the caller opted out or set their own.
+      def with_submitting_text(data, value, submitting)
+        return data if submitting == false
+
+        text = submitting.is_a?(String) ? submitting : submitting_text(value)
+        return data unless text
+
+        data = (data || {}).dup
+        data[:turbo_submits_with] = text unless data.key?(:turbo_submits_with)
+        data
+      end
+
+      # "Save" -> "Saving…", "Add label" -> "Adding label…".
+      def submitting_text(value)
+        verb, *rest = value.to_s.split
+        return unless verb
+
+        gerund = SUBMIT_GERUNDS[verb.downcase] || "#{verb.sub(/e\z/i, "")}ing"
+        "#{[ gerund, *rest ].join(" ")}…"
+      end
+    end
+  end
+end

data/lib/unmagic/components/renderers/empty_state.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Unmagic
+  module Components
+    module Renderers
+      # The blank slate a table falls back to when its collection is empty.
+      module EmptyState
+        class << self
+          def default
+            method(:render).to_proc
+          end
+
+          # Extra options from `table.empty` are for a host's own renderer; the
+          # built-in one takes only a class.
+          def render(view, content, **options)
+            view.tag.div(content, class: view.class_names("UnmagicEmptyState", options[:class]))
+          end
+        end
+      end
+    end
+  end
+end

data/lib/unmagic/components/renderers/pagination.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Unmagic
+  module Components
+    module Renderers
+      # A prev/next pager over a Pagy object. Pagy is an optional dependency: the
+      # default resolver looks for the controller's @pagy and the renderer bails
+      # out unless the object it gets speaks the parts of Pagy's API it needs, so
+      # an app without Pagy simply never renders a pager.
+      module Pagination
+        class << self
+          def default
+            ->(view, pagy:, turbo_frame: nil) { render(view, pagy: pagy, turbo_frame: turbo_frame) }
+          end
+
+          def default_pagy_for
+            method(:resolve).to_proc
+          end
+
+          # A count-aware collection (search results reporting #found) can build its
+          # own pagy, which forces a lazy collection only on the render that shows
+          # it. Anything else falls back to whatever the action assigned.
+          def resolve(view, collection)
+            if defined?(::Pagy) && collection.respond_to?(:found) && view.respond_to?(:pagy, true)
+              view.send(:pagy, :offset, collection, count: collection.found, limit: collection.per_page).first
+            else
+              view.instance_variable_get(:@pagy)
+            end
+          end
+
+          def render(view, pagy:, turbo_frame: nil)
+            return unless pageable?(pagy)
+            return if pagy.previous.nil? && pagy.next.nil?
+
+            data = ({ turbo_frame: turbo_frame, turbo_action: "advance" } if turbo_frame)
+
+            view.tag.nav(class: "UnmagicPagination", "aria-label": "Pagination") do
+              view.safe_join [
+                link(view, pagy, :previous, "Previous", data),
+                link(view, pagy, :next, "Next", data)
+              ]
+            end
+          end
+
+          private
+
+          def pageable?(pagy)
+            pagy.respond_to?(:previous) && pagy.respond_to?(:next) && pagy.respond_to?(:page_url)
+          end
+
+          def link(view, pagy, direction, label, data)
+            if pagy.public_send(direction)
+              view.link_to(label, pagy.page_url(direction), class: "UnmagicPagination__link", data: data)
+            else
+              view.tag.span(label, class: "UnmagicPagination__link", "aria-disabled": "true")
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/unmagic/components/table/column.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Unmagic
+  module Components
+    class Table
+      class Column
+        attr_reader :title, :attribute, :sort, :direction, :block, :width
+
+        def initialize(title:, attribute:, block:, sort: nil, direction: :asc, align: nil,
+                       numeric: false, width: nil, **options)
+          @title = title
+          @attribute = attribute
+          @block = block
+          @sort = sort
+          @direction = direction.to_sym
+          @align = align
+          @numeric = numeric
+          @width = width
+          @classes = options[:class]
+        end
+
+        def right_aligned? = @align == :right || @numeric
+
+        def centered? = @align == :center
+
+        def header_classes
+          alignment
+        end
+
+        def cell_classes
+          [ alignment, ("is-numeric" if @numeric), @classes ].compact.presence&.join(" ")
+        end
+
+        private
+
+        def alignment
+          if right_aligned?
+            "is-right"
+          elsif centered?
+            "is-center"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/unmagic/components/table.rb

@@ -0,0 +1,254 @@
+# frozen_string_literal: true
+
+module Unmagic
+  module Components
+    # Collects the column definitions a `table_for` block declares, then renders
+    # them as a TableTag. See ActionViewHelpers#table_for for the public API.
+    class Table
+      SKELETON_ROWS = 8
+
+      # A pinned column sizes its bar as a fraction of itself; a content-sized one
+      # has no width to take a fraction of, so it falls back to a fixed bar.
+      SKELETON_WIDTHS = %w[8rem 5rem 7rem 4rem 6rem].freeze
+      SKELETON_FRACTIONS = %w[75% 50% 66% 40% 80%].freeze
+
+      def initialize(view, collection, headers: true, sorted_by: nil, sort_direction: nil,
+                     sort_url: nil, row_class: nil, rows_id: nil, row_id: nil, **attributes)
+        @view = view
+        @collection = collection
+        @headers = headers
+        @attributes = attributes
+        @rows_id = rows_id
+        @row_id = row_id
+        @sort_url = sort_url
+        @row_class = row_class
+        @sorted_by = (sorted_by || view.params[:sort]).presence&.to_s
+        @sort_direction = (sort_direction || view.params[:direction]).presence&.to_sym
+        @columns = []
+      end
+
+      def column(title = nil, attribute = nil, **options, &block)
+        @columns << Column.new(title: title, attribute: attribute, block: block, **options)
+        nil
+      end
+
+      # A full-width companion row rendered under a record's own. The block runs
+      # per record inside one colspan cell; rendering nothing skips the row, so
+      # other records stay single-line. The record row drops its bottom border so
+      # the pair reads as one row.
+      def details(&block)
+        @details_block = block
+        nil
+      end
+
+      # The blank slate for a genuinely empty dataset (no search/filter applied) —
+      # typically a prompt to create the first record.
+      # Any extra options are handed to the configured empty_state seam, so an
+      # app whose blank slate takes more than text (an icon, say) can ask for it
+      # per table.
+      def empty(text = nil, **options, &block)
+        @empty_text = text
+        @empty_block = block
+        @empty_options = options
+        nil
+      end
+
+      # The blank slate shown when a search/filter matched nothing, so a
+      # filtered-to-zero table doesn't read as "create your first one". Only
+      # reached when the collection reports filtered?.
+      def no_results(text = nil, **options, &block)
+        @no_results_text = text
+        @no_results_block = block
+        @no_results_options = options
+        nil
+      end
+
+      def render(pagy: nil, turbo_frame: nil)
+        @turbo_frame = turbo_frame
+
+        if @collection.blank?
+          empty_slate
+        else
+          safe_join [ table, pagination(pagy) ].compact
+        end
+      end
+
+      # The same header cells and the same column widths the loaded table renders —
+      # only the body is stand-in bars — so the frame swaps rows in without
+      # shifting the columns.
+      def skeleton
+        view.table_tag (skeleton_header_cells if @headers), skeleton_rows,
+          **table_attributes, widths: widths, caption: "Loading…", role: "status", "aria-busy": "true"
+      end
+
+      # The <tr> this table would render for one record, on its own — what a
+      # broadcast upserts into the tbody. The companion details row is left out:
+      # a stream action carries one element, and the pair is a page-render concern.
+      def row(record)
+        TableTag.new(view, nil, []).render_row(row_hash(record))
+      end
+
+      private
+
+      attr_reader :view
+
+      delegate :tag, :safe_join, :link_to, :class_names, to: :view, private: true
+
+      def table
+        view.table_tag((header_cells if @headers), row_data, widths: widths, rows_id: @rows_id, **table_attributes)
+      end
+
+      # Anything the caller put on table_for beyond the builder's own options rides
+      # on the <table>, so a view can space, identify or annotate it without
+      # wrapping it in a div.
+      def table_attributes = @attributes
+
+      # A record collection's columns/rows recast as the plain cells table_tag
+      # renders: the header carries its sort link and aria-sort, each row its dom
+      # id and row_class.
+      def header_cells
+        @columns.map do |column|
+          { content: header_label(column), class: column.header_classes, "aria-sort": aria_sort(column) }
+        end
+      end
+
+      def widths = @columns.map(&:width)
+
+      def row_data
+        @collection.flat_map do |record|
+          details = details_content(record)
+          row = row_hash(record, has_details: details.present?)
+          details.present? ? [ row, details_row(record, details) ] : [ row ]
+        end
+      end
+
+      def row_hash(record, has_details: false)
+        {
+          cells: @columns.map { |column| { content: cell_content(column, record), class: column.cell_classes } },
+          id: row_id(record),
+          class: class_names(@row_class&.call(record), "has-details" => has_details).presence
+        }
+      end
+
+      def details_content(record)
+        view.capture(record, &@details_block) if @details_block
+      end
+
+      def details_row(record, content)
+        {
+          cells: [ { content: content, colspan: @columns.size } ],
+          class: class_names("UnmagicTable__details", @row_class&.call(record))
+        }
+      end
+
+      def header_label(column)
+        column.sort ? sort_link(column) : column.title
+      end
+
+      def aria_sort(column)
+        if column.sort && sorted_by?(column)
+          sorted_direction(column) == :asc ? "ascending" : "descending"
+        end
+      end
+
+      def sort_link(column)
+        next_direction = sorted_by?(column) ? opposite(sorted_direction(column)) : column.direction
+
+        link_to sort_url(column.sort, next_direction), class: "UnmagicTable__sort", data: frame_data do
+          safe_join [ column.title, sort_arrow(column) ].compact, " "
+        end
+      end
+
+      def sort_arrow(column)
+        tag.span(sorted_direction(column) == :asc ? "↑" : "↓", "aria-hidden": "true") if sorted_by?(column)
+      end
+
+      def sorted_by?(column) = @sorted_by == column.sort.to_s
+
+      def sorted_direction(column)
+        if sorted_by?(column)
+          @sort_direction || column.direction
+        else
+          column.direction
+        end
+      end
+
+      def opposite(direction) = direction == :asc ? :desc : :asc
+
+      def sort_url(key, direction)
+        if @sort_url
+          @sort_url.call(key, direction)
+        else
+          query = view.request.query_parameters.except("page").merge("sort" => key, "direction" => direction)
+          "#{view.request.path}?#{query.to_query}"
+        end
+      end
+
+      # dom_id by default. A live table over a mixed collection needs to say
+      # otherwise: dom_id names the record's own class, so an STI table's ids carry
+      # different prefixes and sort by type rather than by id — which is the order
+      # the upsert action inserts on.
+      def row_id(record)
+        if @row_id
+          @row_id.call(record)
+        elsif record.respond_to?(:to_key)
+          view.dom_id(record)
+        end
+      end
+
+      def cell_content(column, record)
+        if column.block
+          view.capture(record, &column.block)
+        elsif column.attribute
+          record.public_send(column.attribute)
+        end
+      end
+
+      def empty_slate
+        content, options = filtered? ? no_results_slate : empty_dataset_slate
+        Components.configuration.empty_state.call(view, content, **options)
+      end
+
+      # A search result set knows whether a query/filter was applied; a plain
+      # relation or array doesn't, so it's treated as an unfiltered dataset.
+      def filtered? = @collection.respond_to?(:filtered?) && @collection.filtered?
+
+      def empty_dataset_slate
+        content = @empty_block ? view.capture(&@empty_block) : (@empty_text || "Nothing here yet.")
+        [ content, @empty_options || {} ]
+      end
+
+      def no_results_slate
+        content = @no_results_block ? view.capture(&@no_results_block) : (@no_results_text || "No matching results.")
+        [ content, @no_results_options || {} ]
+      end
+
+      def pagination(pagy)
+        return unless pagy
+
+        Components.configuration.pagination.call(view, pagy: pagy, turbo_frame: @turbo_frame)
+      end
+
+      def frame_data
+        { turbo_frame: @turbo_frame, turbo_action: "advance" } if @turbo_frame
+      end
+
+      def skeleton_header_cells
+        @columns.map { |column| { content: column.title, class: column.header_classes } }
+      end
+
+      def skeleton_rows
+        Array.new(SKELETON_ROWS) do |index|
+          @columns.map.with_index { |column, column_index| skeleton_bar(column, index + column_index) }
+        end
+      end
+
+      def skeleton_bar(column, seed)
+        scale = column.width.present? ? SKELETON_FRACTIONS : SKELETON_WIDTHS
+        classes = class_names("UnmagicSkeleton", "is-right" => column.right_aligned?)
+
+        tag.div class: classes, style: "width: #{scale[seed % scale.size]}"
+      end
+    end
+  end
+end