unmagic-components 0.1.0 → 0.2.0

data/lib/unmagic/components/copy_button.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Unmagic
+  module Components
+    # A button that copies text to the clipboard. See ActionViewHelpers#copy_button.
+    class CopyButton
+      def initialize(view, text:, from:, label:, **options)
+        raise ArgumentError, "copy_button needs the text to copy, or from: an element id" if text.nil? && from.nil?
+
+        @view = view
+        @text = text
+        @from = from
+        @label = label || I18n.t("unmagic.components.clipboard.copy", default: "Copy")
+        @options = options
+      end
+
+      # The live region says "Copied" for a screen reader, since the icon swap is
+      # only seen.
+      def render(content)
+        copied = I18n.t("unmagic.components.clipboard.copied", default: "Copied")
+
+        view.content_tag("unmagic-clipboard", value: @text, for: @from, class: "UnmagicClipboard",
+          data: { copied_label: copied }) do
+          safe_join [ button(content), tag.span(class: "UnmagicVisuallyHidden", "aria-live": "polite") ]
+        end
+      end
+
+      private
+
+      attr_reader :view
+
+      delegate :tag, :safe_join, to: :view, private: true
+
+      def button(content)
+        if content
+          tag.button(content, type: "button", **@options,
+            class: view.class_names(Button.classes, "UnmagicClipboard__button", @options[:class]))
+        else
+          tag.button(type: "button", **@options, "aria-label": @label, title: @label,
+            class: view.class_names(Button.classes(:icon), "UnmagicClipboard__button", @options[:class])) do
+            safe_join [
+              Icons.svg(view, :copy, class: "UnmagicClipboard__idle"),
+              Icons.svg(view, :check, class: "UnmagicClipboard__done")
+            ]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/unmagic/components/detail_list.rb

@@ -7,13 +7,17 @@ module Unmagic
     class DetailList
       VARIANTS = %i[inline stacked].freeze
 
-      def initialize(view, variant:, **options)
+      # Values vary in length, so a skeleton's bars do too.
+      SKELETON_WIDTHS = %w[55% 40% 70% 35% 60%].freeze
+
+      def initialize(view, variant:, skeleton: false, **options)
         unless VARIANTS.include?(variant)
           raise ArgumentError, "unknown detail_list variant #{variant.inspect} (expected one of #{VARIANTS.inspect})"
         end
 
         @view = view
         @variant = variant
+        @skeleton = skeleton
         @classes = options[:class]
         @items = []
       end
@@ -30,9 +34,12 @@ module Unmagic
           @classes,
         )
 
-        tag.dl class: classes do
+        list = tag.dl class: classes do
           safe_join @items.map { |item| stacked? ? stacked_item(item) : inline_item(item) }
         end
+
+        # A <dl> may only hold its items, so the loading label goes around it.
+        @skeleton ? Skeleton.group(view) { list } : list
       end
 
       private
@@ -53,8 +60,11 @@ module Unmagic
         end
       end
 
+      # A skeleton keeps the real labels and stands a bar in for each value.
       def value(item)
-        if item.block
+        if @skeleton
+          Skeleton.new(view).text(width: SKELETON_WIDTHS[@items.index(item) % SKELETON_WIDTHS.size])
+        elsif item.block
           view.capture(&item.block).presence || "—"
         else
           item.value

data/lib/unmagic/components/dialog.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Unmagic
+  module Components
+    # The panel chrome inside a dialog: a titled header with a close button, the
+    # body, and an optional footer of actions. Shared by the frame modal (`dialog`),
+    # the same-page dialog (`dialog_tag`), and the modal's own loading and error
+    # states, so every dialog is framed identically. See ActionViewHelpers#dialog.
+    class Dialog
+      SIZES = %i[default wide].freeze
+
+      attr_reader :title_id
+
+      def titled? = @title.present?
+
+      def initialize(view, title: nil, size: :default, close: true, **options)
+        unless SIZES.include?(size)
+          raise ArgumentError, "unknown dialog size #{size.inspect} (expected one of #{SIZES.inspect})"
+        end
+
+        @view = view
+        @title = title
+        @size = size
+        @close = close
+        @options = options
+        @title_id = "unmagic_dialog_#{SecureRandom.hex(4)}_title"
+        @footer = nil
+      end
+
+      # The bottom row of actions — usually the form's submit.
+      def footer(content = nil, &block)
+        @footer = block ? view.capture(&block) : content
+        nil
+      end
+
+      def render(body)
+        classes = view.class_names("UnmagicDialog", { "UnmagicDialog--wide" => @size == :wide }, @options[:class])
+
+        tag.div(**@options, class: classes) do
+          safe_join [
+            header,
+            tag.div(body, class: "UnmagicDialog__body"),
+            (tag.div(@footer, class: "UnmagicDialog__footer") if @footer.present?)
+          ].compact
+        end
+      end
+
+      # The close button on its own, for chrome built by hand.
+      def self.close_button(view)
+        label = I18n.t("unmagic.components.dialog.close", default: "Close")
+
+        view.tag.button(
+          Icons.svg(view, :x),
+          type: "button", class: "#{Button.classes(:icon)} UnmagicDialog__close",
+          "aria-label": label, data: { unmagic_dialog_close: "" }
+        )
+      end
+
+      private
+
+      attr_reader :view
+
+      delegate :tag, :safe_join, to: :view, private: true
+
+      def header
+        return if @title.blank? && !@close
+
+        tag.header class: "UnmagicDialog__header" do
+          safe_join [
+            (tag.h2(@title, id: title_id, class: "UnmagicDialog__title") if @title.present?),
+            (self.class.close_button(view) if @close)
+          ].compact
+        end
+      end
+    end
+  end
+end

data/lib/unmagic/components/dialog_responder.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module Unmagic
+  module Components
+    # The success response for a create or update whose form opened in the frame
+    # modal. A turbo_stream.refresh morphs the page in place — updating the list the
+    # dialog was launched from — and the modal closes in that same render, so the
+    # page repaints once, straight to the new state. A visit without Turbo falls back
+    # to a plain redirect.
+    #
+    #   class LabelsController < ApplicationController
+    #     include Unmagic::Components::DialogResponder
+    #
+    #     def update
+    #       if @label.update(label_params)
+    #         refresh_or_redirect labels_path, notice: "Label saved."
+    #       else
+    #         render :edit, status: :unprocessable_content
+    #       end
+    #     end
+    #   end
+    #
+    # The request_id is dropped so the refresh isn't suppressed on the very tab that
+    # submitted it — Turbo's guard against echoing a tab's own broadcasts keys off it.
+    #
+    # A plain redirect_to works from a modal form too: the modal visits the page it
+    # lands on and closes. The refresh is the smoother of the two, keeping scroll
+    # position and any state the page holds.
+    module DialogResponder
+      extend ActiveSupport::Concern
+
+      private
+
+      def refresh_or_redirect(url, **flash_options)
+        flash_options.each { |type, message| flash[type] = message }
+
+        respond_to do |format|
+          format.turbo_stream { render turbo_stream: turbo_stream.refresh(request_id: nil) }
+          format.html { redirect_to url }
+        end
+      end
+    end
+  end
+end

data/lib/unmagic/components/engine.rb

@@ -13,6 +13,14 @@ module Unmagic
         end
       end
 
+      # turbo_stream.toast. turbo-rails runs this hook when its tag builder loads, so
+      # an app without Turbo never sees it.
+      initializer "unmagic_components.turbo_streams" do
+        ActiveSupport.on_load(:turbo_streams_tag_builder) do
+          include Unmagic::Components::TurboStreamActions
+        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
@@ -24,10 +32,11 @@ module Unmagic
         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).
+      # The components' JavaScript: custom elements and the `upsert` Turbo Stream
+      # action. Pinned rather than served so the host imports each by name
+      # ("unmagic/components", or "unmagic/components/modal"). importmap-rails is
+      # optional; an app without it never sees the pins and wires the files up its
+      # own way.
       initializer "unmagic_components.importmap", before: "importmap" do |app|
         next unless app.config.respond_to?(:importmap)
 

data/lib/unmagic/components/form_builder.rb

@@ -133,6 +133,30 @@ module Unmagic
         @template.content_tag(:button, options) { block ? @template.capture(&block) : value }
       end
 
+      # A textarea that grows with what's typed, from its rows up to its CSS
+      # max-height, then scrolls. Works as a field's control too:
+      #
+      #   <%= form.field :body, "Message", as: :autogrow_text_area, rows: 2 %>
+      #
+      # Needs import "unmagic/components/autogrow".
+      def autogrow_text_area(method, options = {})
+        Components::Autogrow.wrap(@template, text_area(method, options))
+      end
+
+      # A hidden field holding a fresh, time-ordered UUIDv7, so the form submits an
+      # id the client already knows: to match an optimistically rendered element to
+      # the record the server creates under the same id.
+      #
+      #   <%= form.uuid_field :id %>
+      #
+      # A new id is minted when the element upgrades and every time the form is
+      # reset, so a form that clears itself after each submit sends a fresh one.
+      # Without the script the server's own id is sent. Needs import
+      # "unmagic/components/uuid_input".
+      def uuid_field(method, options = {})
+        Components::UuidInput.new(@template, field_name(method), **options).render
+      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

data/lib/unmagic/components/icons.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Unmagic
+  module Components
+    # The handful of glyphs the components draw for themselves — a close button, a
+    # toast's tone, a copy button's confirmation. Inline SVG so the gem depends on no
+    # icon library and no host helper. Paths are from Lucide (ISC licence).
+    module Icons
+      PATHS = {
+        x: '<path d="M18 6 6 18"/><path d="m6 6 12 12"/>',
+        check: '<path d="M20 6 9 17l-5-5"/>',
+        circle_check: '<circle cx="12" cy="12" r="10"/><path d="m9 12 2 2 4-4"/>',
+        circle_x: '<circle cx="12" cy="12" r="10"/><path d="m15 9-6 6"/><path d="m9 9 6 6"/>',
+        triangle_alert: '<path d="m21.73 18-8-14a2 2 0 0 0-3.48 0l-8 14A2 2 0 0 0 4 21h16a2 2 0 0 0 1.73-3"/>' \
+          '<path d="M12 9v4"/><path d="M12 17h.01"/>',
+        info: '<circle cx="12" cy="12" r="10"/><path d="M12 16v-4"/><path d="M12 8h.01"/>',
+        copy: '<rect width="14" height="14" x="8" y="8" rx="2" ry="2"/>' \
+          '<path d="M4 16c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2h10c1.1 0 2 .9 2 2"/>',
+        rotate: '<path d="M21 12a9 9 0 1 1-9-9c2.52 0 4.93 1 6.74 2.74L21 8"/><path d="M21 3v5h-5"/>',
+        ellipsis_vertical: '<circle cx="12" cy="12" r="1"/><circle cx="12" cy="5" r="1"/><circle cx="12" cy="19" r="1"/>',
+        arrow_left: '<path d="m12 19-7-7 7-7"/><path d="M19 12H5"/>',
+        chevron_down: '<path d="m6 9 6 6 6-6"/>'
+      }.freeze
+
+      # The glyph a tone leads with, where it has one.
+      TONE_ICONS = { good: :circle_check, warn: :triangle_alert, bad: :circle_x, info: :info }.freeze
+
+      def self.svg(view, name, **options)
+        paths = PATHS.fetch(name) { raise ArgumentError, "unknown icon #{name.inspect}" }
+
+        view.tag.svg(
+          paths.html_safe, # rubocop:disable Rails/OutputSafety -- the constant markup above, never input
+          xmlns: "http://www.w3.org/2000/svg", viewBox: "0 0 24 24", fill: "none", stroke: "currentColor",
+          "stroke-width": 2, "stroke-linecap": "round", "stroke-linejoin": "round", "aria-hidden": "true",
+          **options, class: view.class_names("UnmagicIcon", options[:class])
+        )
+      end
+    end
+  end
+end

data/lib/unmagic/components/local_time.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Unmagic
+  module Components
+    # A timestamp the browser rewrites in the viewer's own locale and time zone.
+    # The server renders a readable fallback, in Time.zone, for the moment before
+    # the element upgrades. See ActionViewHelpers#local_time_tag.
+    class LocalTime
+      FORMATS = %i[short medium long full date time relative].freeze
+
+      # The server fallback for each absolute format, in I18n's time formats.
+      I18N_FORMATS = { short: :short, medium: :default, long: :long, full: :long }.freeze
+
+      def initialize(view, time, format:, compact:, **options)
+        unless FORMATS.include?(format)
+          raise ArgumentError, "unknown local_time_tag format #{format.inspect} (expected one of #{FORMATS.inspect})"
+        end
+
+        @view = view
+        @time = time.in_time_zone
+        @format = format
+        @compact = compact
+        @options = options
+      end
+
+      # The attributes live on the element, where a morph that changes them is
+      # seen; the inner <time> keeps the markup meaningful without the script.
+      def render
+        datetime = @time.utc.iso8601
+
+        view.content_tag("unmagic-time", datetime: datetime, format: @format, compact: ("" if @compact), **@options) do
+          tag.time(fallback, datetime: datetime, title: (I18n.l(@time, format: :long) if relative?))
+        end
+      end
+
+      private
+
+      attr_reader :view
+
+      delegate :tag, to: :view, private: true
+
+      def relative? = @format == :relative
+
+      def fallback
+        case @format
+        when :relative then relative_phrase
+        when :date then I18n.l(@time.to_date, format: :long)
+        when :time then I18n.l(@time, format: "%H:%M")
+        else I18n.l(@time, format: I18N_FORMATS.fetch(@format))
+        end
+      end
+
+      def relative_phrase
+        distance = view.distance_of_time_in_words(Time.current, @time)
+
+        if @time.past?
+          I18n.t("unmagic.components.time.past", distance: distance, default: "%{distance} ago")
+        else
+          I18n.t("unmagic.components.time.future", distance: distance, default: "in %{distance}")
+        end
+      end
+    end
+  end
+end

data/lib/unmagic/components/menu.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Unmagic
+  module Components
+    # A dropdown of actions behind a trigger, built on <details>. See
+    # ActionViewHelpers#menu.
+    class Menu
+      ALIGNMENTS = %i[start end].freeze
+      TONES = %i[default danger].freeze
+
+      def initialize(view, label:, align:, **options)
+        unless ALIGNMENTS.include?(align)
+          raise ArgumentError, "unknown menu align #{align.inspect} (expected one of #{ALIGNMENTS.inspect})"
+        end
+
+        @view = view
+        @label = label
+        @align = align
+        @options = options
+        @items = []
+      end
+
+      # A link item. Takes link_to's arguments, block form included.
+      def link(name = nil, url = nil, tone: :default, **options, &block)
+        name, url = view.capture(&block), name if block
+        @items << view.link_to(name, url, **options, role: "menuitem", class: item_classes(tone, options[:class]))
+        nil
+      end
+
+      # A button_to item, for an action that isn't a GET. Takes button_to's
+      # arguments, block form included, so form: { data: { turbo_confirm: } } works.
+      def button(name = nil, url = nil, tone: :default, **options, &block)
+        name, url = view.capture(&block), name if block
+        @items << view.button_to(url, **options, role: "menuitem", class: item_classes(tone, options[:class]),
+          form_class: "UnmagicMenu__form") { name }
+        nil
+      end
+
+      def divider
+        @items << tag.hr(class: "UnmagicMenu__divider", role: "separator")
+        nil
+      end
+
+      def render
+        view.content_tag("unmagic-menu", **@options, class: view.class_names("UnmagicMenu", @options[:class])) do
+          tag.details class: "UnmagicMenu__details" do
+            safe_join [
+              trigger,
+              tag.div(safe_join(@items), class: "UnmagicMenu__panel UnmagicMenu__panel--#{@align}", role: "menu")
+            ]
+          end
+        end
+      end
+
+      private
+
+      attr_reader :view
+
+      delegate :tag, :safe_join, to: :view, private: true
+
+      def trigger
+        if @label
+          tag.summary(class: "#{Button.classes} UnmagicMenu__trigger", "aria-haspopup": "menu") do
+            safe_join [ @label, Icons.svg(view, :chevron_down) ]
+          end
+        else
+          label = I18n.t("unmagic.components.menu.label", default: "More actions")
+          tag.summary(Icons.svg(view, :ellipsis_vertical), class: "#{Button.classes(:icon)} UnmagicMenu__trigger",
+            "aria-haspopup": "menu", "aria-label": label, title: label)
+        end
+      end
+
+      def item_classes(tone, extra)
+        unless TONES.include?(tone)
+          raise ArgumentError, "unknown menu item tone #{tone.inspect} (expected one of #{TONES.inspect})"
+        end
+
+        view.class_names("UnmagicMenu__item", { "UnmagicMenu__item--danger" => tone == :danger }, extra)
+      end
+    end
+  end
+end

data/lib/unmagic/components/modal.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Unmagic
+  module Components
+    # The one shared modal a layout mounts: a native <dialog> holding the turbo frame
+    # that modal links load into, plus inert templates for the loading and error
+    # states the <unmagic-modal> element swaps in. See ActionViewHelpers#modal_frame.
+    class Modal
+      def initialize(view, id:)
+        @view = view
+        @id = id
+      end
+
+      # overflow stays visible (see the CSS) so a dropdown inside a dialog form isn't
+      # clipped; a dialog keeps its content short enough to fit instead.
+      def render
+        view.content_tag("unmagic-modal") do
+          tag.dialog class: "UnmagicDialogBox", data: { unmagic_dialog: "" } do
+            safe_join [
+              view.turbo_frame_tag(@id),
+              tag.template(skeleton, data: { unmagic_modal_skeleton: "" }),
+              tag.template(error, data: { unmagic_modal_error: "" })
+            ]
+          end
+        end
+      end
+
+      private
+
+      attr_reader :view
+
+      delegate :tag, :safe_join, to: :view, private: true
+
+      # Framed like a real dialog, so the panel is sized before the form arrives and
+      # nothing jumps when it does.
+      def skeleton
+        tag.div class: "UnmagicDialog", role: "status" do
+          safe_join [
+            tag.span(I18n.t("unmagic.components.modal.loading", default: "Loading…"), class: "UnmagicVisuallyHidden"),
+            tag.header(bar("title"), class: "UnmagicDialog__header"),
+            tag.div(class: "UnmagicDialog__body") do
+              safe_join Array.new(3) { tag.div(safe_join([ bar("label"), bar("input") ]), class: "UnmagicDialog__skeleton-field") }
+            end,
+            tag.div(bar("button"), class: "UnmagicDialog__footer")
+          ]
+        end
+      end
+
+      def bar(kind)
+        tag.div class: "UnmagicSkeleton UnmagicDialog__skeleton-#{kind}"
+      end
+
+      def error
+        panel = Dialog.new(view, title: I18n.t("unmagic.components.modal.error_title", default: "Couldn’t load"),
+          role: "alert")
+
+        panel.footer do
+          tag.button type: "button", class: Button.classes(:primary), data: { unmagic_modal_retry: "" } do
+            safe_join [ Icons.svg(view, :rotate), I18n.t("unmagic.components.modal.retry", default: "Try again") ]
+          end
+        end
+
+        panel.render(
+          tag.div(class: "UnmagicDialog__error") do
+            safe_join [
+              Icons.svg(view, :circle_x),
+              tag.p(I18n.t("unmagic.components.modal.error_message",
+                default: "Something went wrong loading this. Check your connection and try again."))
+            ]
+          end
+        )
+      end
+    end
+  end
+end

data/lib/unmagic/components/page_header.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Unmagic
+  module Components
+    # The top of a page: an optional back link, the title with badges beside it,
+    # a description, and the page's actions on the right. See
+    # ActionViewHelpers#page_header.
+    class PageHeader
+      def initialize(view, title: nil, description: nil, back: nil, skeleton: false, **options)
+        @view = view
+        @title = title
+        @description = description
+        @back = back
+        @skeleton = skeleton
+        @options = options
+        @leading = nil
+        @badges = []
+      end
+
+      # Title markup richer than a string — a <code>, a link. Overrides title:.
+      def title(content = nil, &block)
+        @title = block ? view.capture(&block) : content
+        nil
+      end
+
+      # A description with markup in it. Overrides description:.
+      def description(content = nil, &block)
+        @description = block ? view.capture(&block) : content
+        nil
+      end
+
+      # Something before the title, such as an avatar.
+      def leading(content = nil, &block)
+        @leading = block ? view.capture(&block) : content
+        nil
+      end
+
+      # A badge beside the title. Call it once per badge.
+      def badge(content = nil, tone: :neutral, &block)
+        @badges << tag.span(block ? view.capture(&block) : content, class: Badge.classes(tone))
+        nil
+      end
+
+      # As a skeleton, anything given still renders for real, and the rest stands in
+      # as shapes: a title bar, a description line (unless description: false) and
+      # a button.
+      def render(actions)
+        actions = Skeleton.new(view).button if @skeleton && actions.blank?
+
+        tag.header(**@options, role: ("status" if @skeleton),
+          class: view.class_names("UnmagicPageHeader", @options[:class])) do
+          safe_join [
+            (Skeleton.hidden_label(view) if @skeleton),
+            back_link,
+            tag.div(class: "UnmagicPageHeader__row") do
+              safe_join [
+                tag.div(safe_join([ heading, description_tag ].compact), class: "UnmagicPageHeader__main"),
+                (tag.div(actions, class: "UnmagicPageHeader__actions") if actions.present?)
+              ].compact
+            end
+          ].compact
+        end
+      end
+
+      private
+
+      attr_reader :view
+
+      delegate :tag, :safe_join, to: :view, private: true
+
+      def back_link
+        return unless @back
+
+        text, path = @back.values_at(:text, :path)
+        view.link_to path, class: "UnmagicPageHeader__back" do
+          safe_join [ Icons.svg(view, :arrow_left), text ]
+        end
+      end
+
+      def heading
+        tag.div class: "UnmagicPageHeader__heading" do
+          title = @title.presence || (Skeleton.new(view).text(width: "14rem") if @skeleton)
+          safe_join [ @leading, tag.h1(title, class: "UnmagicPageHeader__title"), *@badges ].compact
+        end
+      end
+
+      def description_tag
+        if @description.present?
+          tag.div(@description, class: "UnmagicPageHeader__description")
+        elsif @skeleton && @description != false
+          tag.div(Skeleton.new(view).text(width: "32rem"), class: "UnmagicPageHeader__description")
+        end
+      end
+    end
+  end
+end