unmagic-components 0.1.0 → 0.2.0

data/lib/unmagic/components/skeleton.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Unmagic
+  module Components
+    # Placeholder shapes for blocking out an interface while it loads. The same
+    # object is what `skeleton do |s|` yields and what the standalone helpers
+    # (skeleton_text, skeleton_circle, …) call, so the two forms can't differ. See
+    # ActionViewHelpers#skeleton.
+    #
+    # Every shape is hidden from assistive technology; a group says "Loading…" once
+    # for all of them.
+    class Skeleton
+      BUTTON_SIZES = %i[small large].freeze
+
+      # The last line of a paragraph is shorter, so a block of text reads as one.
+      LAST_LINE_WIDTH = "60%"
+
+      # A status region around some shapes, announced once.
+      def self.group(view, label: nil, **options)
+        view.tag.div(**options, role: "status", class: view.class_names("UnmagicSkeletonGroup", options[:class])) do
+          view.safe_join [ hidden_label(view, label), yield ]
+        end
+      end
+
+      # The words a screen reader hears in place of the shapes.
+      def self.hidden_label(view, label = nil)
+        label ||= I18n.t("unmagic.components.skeleton.loading", default: "Loading…")
+        view.tag.span(label, class: "UnmagicVisuallyHidden")
+      end
+
+      def initialize(view)
+        @view = view
+      end
+
+      # A line of text, sized by the font it sits in: it takes exactly one line box,
+      # so the text that replaces it lands in the same space. lines: renders a
+      # paragraph instead, with a shorter last line; width: then applies to the whole.
+      # class: and style: go on the line, width: on its bar.
+      def text(width: nil, lines: 1, **options)
+        raise ArgumentError, "skeleton text needs at least one line (got #{lines.inspect})" unless lines.to_i >= 1
+
+        return line(width: width, **options) if lines == 1
+
+        lines = Array.new(lines) { |index| line(width: (LAST_LINE_WIDTH if index == lines - 1)) }
+        view.tag.span(view.safe_join(lines), **options, "aria-hidden": "true",
+          class: view.class_names("UnmagicSkeletonText", options[:class]), style: style(options[:style], width: width))
+      end
+
+      # An avatar or a round icon.
+      def circle(size: "2.5rem", **options)
+        shape("circle", width: size, height: size, **options)
+      end
+
+      # An image, a chart, a map: anything rectangular. Full width unless given one.
+      def block(height: "8rem", width: nil, **options)
+        shape("block", width: width, height: height, **options)
+      end
+
+      # The size of a button_classes button, so a row of actions keeps its height.
+      def button(size: nil, width: nil, **options)
+        unless size.nil? || BUTTON_SIZES.include?(size)
+          raise ArgumentError, "unknown skeleton button size #{size.inspect} (expected one of #{BUTTON_SIZES.inspect})"
+        end
+
+        shape("button", width: width, modifier: ("UnmagicSkeleton--#{size}" if size), **options)
+      end
+
+      private
+
+      attr_reader :view
+
+      # One line box of the surrounding font (1lh tall) with the bar centred in it.
+      # The bar is thinner than the text so it reads as a placeholder, and the line
+      # box, not margins around the bar, supplies the rest of the height: margins
+      # would collapse through their container and the skeleton would come out
+      # shorter than the text it stands in for.
+      def line(width: nil, **options)
+        view.tag.span(**options, "aria-hidden": "true",
+          class: view.class_names("UnmagicSkeletonLine", options[:class]), style: style(options[:style])) do
+          shape("text", width: width)
+        end
+      end
+
+      def shape(kind, width: nil, height: nil, modifier: nil, **options)
+        view.tag.span(**options, "aria-hidden": "true",
+          class: view.class_names("UnmagicSkeleton", "UnmagicSkeleton--#{kind}", modifier, options[:class]),
+          style: style(options[:style], width: width, height: height))
+      end
+
+      def style(extra, **dimensions)
+        rules = dimensions.compact.map { |property, value| "#{property}: #{value}" }
+        rules << extra if extra.present?
+        rules.join("; ").presence
+      end
+    end
+  end
+end

data/lib/unmagic/components/tabs.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Unmagic
+  module Components
+    # A row of tabs: either panels switched in the page, or links to separate URLs.
+    # See ActionViewHelpers#tabs.
+    class Tabs
+      def initialize(view, id: nil, **options)
+        @view = view
+        @id = id
+        @base = id || "unmagic_tabs_#{SecureRandom.hex(4)}"
+        @options = options
+        @tabs = []
+        @panels = []
+      end
+
+      def tab(label, disabled: nil, href: nil, active: false)
+        @tabs << { label: label, disabled: disabled, href: href, active: active }
+        nil
+      end
+
+      def panel(&block)
+        @panels << view.capture(&block)
+        nil
+      end
+
+      def render
+        links = @tabs.any? { |tab| tab[:href] }
+        raise ArgumentError, "tabs can't mix href: tabs with panels" if links && @panels.any?
+
+        links ? links_bar : switcher
+      end
+
+      private
+
+      attr_reader :view
+
+      delegate :tag, :safe_join, to: :view, private: true
+
+      def enabled = @tabs.reject { |tab| tab[:disabled] }
+
+      # Panels line up with the enabled tabs in order; a disabled tab takes none.
+      def switcher
+        if enabled.size != @panels.size
+          raise ArgumentError, "tabs has #{enabled.size} enabled tabs but #{@panels.size} panels"
+        end
+
+        selected = enabled.index { |tab| tab[:active] } || 0
+        index = -1
+
+        list = @tabs.map do |tab|
+          next disabled_tab(tab) if tab[:disabled]
+
+          index += 1
+          tag.button tab[:label], type: "button", role: "tab", id: "#{@base}_tab_#{index}", class: "UnmagicTabs__tab",
+            "aria-controls": "#{@base}_panel_#{index}", "aria-selected": (index == selected).to_s,
+            tabindex: (index == selected ? 0 : -1)
+        end
+
+        panels = @panels.each_with_index.map do |content, i|
+          tag.div content, role: "tabpanel", id: "#{@base}_panel_#{i}", class: "UnmagicTabs__panel",
+            "aria-labelledby": "#{@base}_tab_#{i}", tabindex: 0, hidden: i != selected
+        end
+
+        view.content_tag("unmagic-tabs", **@options, id: @id, class: view.class_names("UnmagicTabs", @options[:class])) do
+          safe_join [ tag.div(safe_join(list), role: "tablist", class: "UnmagicTabs__list"), *panels ]
+        end
+      end
+
+      # Each tab its own URL, rendered on the server: navigation, not a widget, so it
+      # needs no script and marks the current page rather than a selected tab.
+      def links_bar
+        tag.nav(**@options, id: @id, class: view.class_names("UnmagicTabs", @options[:class])) do
+          tag.div class: "UnmagicTabs__list" do
+            safe_join(@tabs.map do |tab|
+              next disabled_tab(tab) if tab[:disabled]
+
+              view.link_to tab[:label], tab[:href], class: "UnmagicTabs__tab", "aria-current": ("page" if tab[:active])
+            end)
+          end
+        end
+      end
+
+      def disabled_tab(tab)
+        reason = tab[:disabled] unless tab[:disabled] == true
+
+        tag.span class: "UnmagicTabs__tab", "aria-disabled": "true" do
+          safe_join [ tab[:label], (tag.span("(#{reason})", class: "UnmagicTabs__reason") if reason) ].compact, " "
+        end
+      end
+    end
+  end
+end

data/lib/unmagic/components/toast.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Unmagic
+  module Components
+    # One toast, and the inert <template> the <unmagic-toasts> element pops it from.
+    # A toast arrives as a template rather than as the toast itself so a morph or a
+    # stream can deliver it without it rendering in place; the element clones it
+    # into the stack. See ActionViewHelpers#flash_toasts.
+    class Toast
+      TONES = %i[good warn bad info].freeze
+
+      # The <unmagic-toasts> element's id, which a stream appends templates to.
+      TARGET = "unmagic_toasts"
+
+      def initialize(view, message, tone:)
+        unless TONES.include?(tone)
+          raise ArgumentError, "unknown toast tone #{tone.inspect} (expected one of #{TONES.inspect})"
+        end
+
+        @view = view
+        @message = message
+        @tone = tone
+      end
+
+      def template
+        tag.template(render, data: { unmagic_toast_template: "" })
+      end
+
+      # A bad toast interrupts (role="alert"); the rest are announced politely by
+      # the stack's own live region.
+      def render
+        tag.div class: "UnmagicToast UnmagicToast--#{@tone}", role: ("alert" if @tone == :bad),
+          data: { unmagic_toast: "" } do
+          safe_join [
+            Icons.svg(view, Icons::TONE_ICONS.fetch(@tone), class: "UnmagicToast__icon"),
+            tag.div(@message, class: "UnmagicToast__message"),
+            tag.button(
+              Icons.svg(view, :x),
+              type: "button", class: "UnmagicToast__dismiss",
+              "aria-label": I18n.t("unmagic.components.toast.dismiss", default: "Dismiss"),
+              data: { unmagic_toast_dismiss: "" }
+            )
+          ]
+        end
+      end
+
+      private
+
+      attr_reader :view
+
+      delegate :tag, :safe_join, to: :view, private: true
+    end
+  end
+end

data/lib/unmagic/components/toasts.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Unmagic
+  module Components
+    # The mount point for toasts: the <unmagic-toasts> element, its stack, and a
+    # template for each of the request's flashes. See ActionViewHelpers#flash_toasts.
+    class Toasts
+      def initialize(view, flashes, duration:)
+        @view = view
+        @flashes = flashes
+        @duration = duration
+      end
+
+      # The stack is data-turbo-permanent, so a toast on screen — and its dismiss
+      # timer — survives a Drive visit or a morph refresh. It is a manual popover
+      # so the element can lift it into the top layer, above an open dialog.
+      def render
+        view.content_tag("unmagic-toasts", id: Toast::TARGET, duration: @duration) do
+          safe_join [
+            tag.div(class: "UnmagicToasts__stack", id: "#{Toast::TARGET}_stack", popover: "manual",
+              "aria-live": "polite", data: { turbo_permanent: "" }),
+            *templates
+          ]
+        end
+      end
+
+      private
+
+      attr_reader :view
+
+      delegate :tag, :safe_join, to: :view, private: true
+
+      def templates
+        tones = Components.configuration.flash_tones
+
+        @flashes.each_with_object([]) do |(type, messages), templates|
+          tone = tones.fetch(type.to_s, :info)
+
+          Array(messages).each do |message|
+            templates << Toast.new(view, message, tone: tone).template if message.present?
+          end
+        end
+      end
+    end
+  end
+end

data/lib/unmagic/components/tooltip.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Unmagic
+  module Components
+    # A hint shown on hover or focus. See ActionViewHelpers#tooltip.
+    class Tooltip
+      PLACEMENTS = %i[top bottom].freeze
+
+      def initialize(view, text:, placement:, term:, **options)
+        unless PLACEMENTS.include?(placement)
+          raise ArgumentError, "unknown tooltip placement #{placement.inspect} (expected one of #{PLACEMENTS.inspect})"
+        end
+
+        @view = view
+        @text = text
+        @placement = placement
+        @term = term
+        @options = options
+      end
+
+      def render(content)
+        classes = view.class_names("UnmagicTooltip", { "UnmagicTooltip--term" => @term }, @options[:class])
+
+        view.content_tag("unmagic-tooltip", content, **@options, text: @text, placement: @placement, class: classes)
+      end
+
+      private
+
+      attr_reader :view
+    end
+  end
+end

data/lib/unmagic/components/turbo_stream_actions.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Unmagic
+  module Components
+    # Mixed into turbo-rails' stream tag builder by the engine.
+    module TurboStreamActions
+      # Pops a toast from a stream response — for something that happened outside
+      # the flash cycle, where there is no redirect or render to carry a flash.
+      #
+      #   render turbo_stream: turbo_stream.toast("Invitation sent.")
+      #   render turbo_stream: turbo_stream.toast("Couldn't reach Slack.", tone: :bad)
+      #
+      # tone: :good (default), :warn, :bad or :info. Needs flash_toasts on the page.
+      def toast(message, tone: :good)
+        append Toast::TARGET, Toast.new(@view_context, message, tone: tone).template
+      end
+    end
+  end
+end

data/lib/unmagic/components/uuid_input.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Unmagic
+  module Components
+    # A hidden field holding a client-known UUIDv7. See FormBuilder#uuid_field.
+    class UuidInput
+      def initialize(view, name, **options)
+        @view = view
+        @name = name
+        @options = options
+      end
+
+      # The server renders an id of its own so the form still submits one without
+      # the script; the element replaces it as it upgrades, and again on each reset.
+      def render
+        @view.content_tag("unmagic-uuid-input", name: @name, **@options) do
+          @view.hidden_field_tag(@name, SecureRandom.uuid_v7, id: nil, autocomplete: "off")
+        end
+      end
+    end
+  end
+end

data/lib/unmagic/components/version.rb

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

data/lib/unmagic/components.rb

@@ -14,8 +14,29 @@ require_relative "components/table_tag"
 require_relative "components/table/column"
 require_relative "components/table"
 require_relative "components/form_builder"
+require_relative "components/skeleton"
 require_relative "components/detail_list/item"
 require_relative "components/detail_list"
+require_relative "components/icons"
+require_relative "components/button"
+require_relative "components/dialog"
+require_relative "components/modal"
+require_relative "components/confirm_template"
+require_relative "components/dialog_responder"
+require_relative "components/toast"
+require_relative "components/toasts"
+require_relative "components/turbo_stream_actions"
+require_relative "components/badge"
+require_relative "components/callout"
+require_relative "components/card"
+require_relative "components/page_header"
+require_relative "components/local_time"
+require_relative "components/tooltip"
+require_relative "components/menu"
+require_relative "components/tabs"
+require_relative "components/copy_button"
+require_relative "components/autogrow"
+require_relative "components/uuid_input"
 require_relative "components/action_view_helpers"
 # ActionView pulls in a partial Rails namespace, so this checks for the constant it
 # actually needs rather than for Rails.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: unmagic-components
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Keith Pitt
@@ -79,11 +79,12 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '13.0'
-description: Server-rendered view builders in the spirit of form_for. table_for for
-  index tables — sortable headers, deferred turbo-frame loading with a matching skeleton,
-  empty states, pagination, and rows a Turbo Stream can keep up to date. detail_list
-  for description lists, and a form builder for the chrome around a control. Plain
-  Rails helpers, themed through CSS custom properties.
+description: UI components for Rails views in the spirit of form_for. Builders for
+  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.
 email:
 - keith@unreasonable-magic.com
 executables: []
@@ -93,22 +94,55 @@ files:
 - CHANGELOG.md
 - LICENSE
 - README.md
+- app/assets/javascripts/unmagic/components.js
+- app/assets/javascripts/unmagic/components/autogrow.js
+- app/assets/javascripts/unmagic/components/clipboard.js
+- app/assets/javascripts/unmagic/components/confirm.js
+- app/assets/javascripts/unmagic/components/dialog.js
+- app/assets/javascripts/unmagic/components/menu.js
+- app/assets/javascripts/unmagic/components/modal.js
+- app/assets/javascripts/unmagic/components/tabs.js
+- app/assets/javascripts/unmagic/components/time.js
+- app/assets/javascripts/unmagic/components/toasts.js
+- 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
 - config/importmap.rb
 - lib/unmagic-components.rb
 - lib/unmagic/components.rb
 - lib/unmagic/components/action_view_helpers.rb
+- lib/unmagic/components/autogrow.rb
+- lib/unmagic/components/badge.rb
+- lib/unmagic/components/button.rb
+- lib/unmagic/components/callout.rb
+- lib/unmagic/components/card.rb
 - lib/unmagic/components/configuration.rb
+- lib/unmagic/components/confirm_template.rb
+- lib/unmagic/components/copy_button.rb
 - lib/unmagic/components/detail_list.rb
 - lib/unmagic/components/detail_list/item.rb
+- lib/unmagic/components/dialog.rb
+- lib/unmagic/components/dialog_responder.rb
 - lib/unmagic/components/engine.rb
 - lib/unmagic/components/form_builder.rb
+- lib/unmagic/components/icons.rb
+- lib/unmagic/components/local_time.rb
+- lib/unmagic/components/menu.rb
+- lib/unmagic/components/modal.rb
+- lib/unmagic/components/page_header.rb
 - lib/unmagic/components/renderers/empty_state.rb
 - lib/unmagic/components/renderers/pagination.rb
+- lib/unmagic/components/skeleton.rb
 - lib/unmagic/components/table.rb
 - lib/unmagic/components/table/column.rb
 - lib/unmagic/components/table_tag.rb
+- lib/unmagic/components/tabs.rb
+- lib/unmagic/components/toast.rb
+- lib/unmagic/components/toasts.rb
+- lib/unmagic/components/tooltip.rb
+- lib/unmagic/components/turbo_stream_actions.rb
+- lib/unmagic/components/uuid_input.rb
 - lib/unmagic/components/version.rb
 homepage: https://github.com/unreasonable-magic/unmagic-components
 licenses:
@@ -133,5 +167,6 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.10
 specification_version: 4
-summary: Declarative table, detail-list and form builders for Rails views
+summary: 'Server-rendered UI components for Rails: tables, forms, dialogs, toasts
+  and more'
 test_files: []