unmagic-components 0.3.0 → 0.4.0

data/lib/unmagic/components/duration.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Unmagic
+  module Components
+    # A stretch of time as somebody would say it: 640ms, 2s, 3m 5s, 1h 4m 2s. Prose
+    # about a wait rather than a clock, so the larger units are left off until they
+    # are needed. Anything under a second is milliseconds, since most tool calls
+    # answer in a fraction of one and "0s" says nothing about which fraction.
+    #
+    # <unmagic-elapsed> writes the same words while a clock is running (elapsed.js),
+    # so a reading doesn't change shape the moment it settles. Change both together.
+    module Duration
+      def self.format(seconds)
+        return if seconds.nil?
+
+        if seconds.positive? && seconds < 1
+          return I18n.t("unmagic.components.elapsed.milliseconds", count: (seconds * 1000).round, default: "%{count}ms")
+        end
+
+        whole = seconds.round
+        hours, remainder = whole.divmod(3600)
+        minutes, secs = remainder.divmod(60)
+
+        if whole < 60
+          I18n.t("unmagic.components.elapsed.seconds", count: whole, default: "%{count}s")
+        elsif whole < 3600
+          I18n.t("unmagic.components.elapsed.minutes", minutes: minutes, seconds: secs, default: "%{minutes}m %{seconds}s")
+        else
+          I18n.t("unmagic.components.elapsed.hours", hours: hours, minutes: minutes, seconds: secs,
+            default: "%{hours}h %{minutes}m %{seconds}s")
+        end
+      end
+    end
+  end
+end

data/lib/unmagic/components/elapsed.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Unmagic
+  module Components
+    # A clock counting up from a moment the server named, or down to one. See
+    # ActionViewHelpers#elapsed_tag.
+    class Elapsed
+      DIRECTIONS = %i[up down].freeze
+
+      def initialize(view, time, direction:, **options)
+        unless DIRECTIONS.include?(direction)
+          raise ArgumentError, "unknown elapsed_tag direction #{direction.inspect} (expected one of #{DIRECTIONS.inspect})"
+        end
+
+        @view = view
+        @time = time.in_time_zone
+        @direction = direction
+        @options = options
+      end
+
+      # The server writes the reading the element would, so it is right before the
+      # script loads. Whole seconds, floored going up and ceiled going down: a
+      # stopwatch says how long it has been, not how long it nearly has been.
+      def render
+        attribute = @direction == :up ? :since : :until
+
+        view.content_tag("unmagic-elapsed", Duration.format(seconds), **@options,
+          attribute => @time.utc.iso8601(3),
+          title: I18n.l(@time, format: :long),
+          class: view.class_names("UnmagicElapsed", @options[:class]))
+      end
+
+      private
+
+      attr_reader :view
+
+      def seconds
+        if @direction == :up
+          [ (Time.current - @time).floor, 0 ].max
+        else
+          [ (@time - Time.current).ceil, 0 ].max
+        end
+      end
+    end
+  end
+end

data/lib/unmagic/components/engine.rb

@@ -7,10 +7,19 @@ module Unmagic
     class Engine < ::Rails::Engine
       isolate_namespace Unmagic::Components
 
+      # Both hooks, because a helper test never touches ActionView::Base. The :action_view hook
+      # mixes into Base, which is what a template renders through — but ActionView::TestCase builds
+      # its own view class and calls the helper under test on the test case itself. So a host helper
+      # that composes one of these (badge, button_classes) works in the app and raises NoMethodError
+      # in its own spec, which is a confusing place to send someone.
       initializer "unmagic_components.helpers" do
         ActiveSupport.on_load(:action_view) do
           include Unmagic::Components::ActionViewHelpers
         end
+
+        ActiveSupport.on_load(:action_view_test_case) do
+          include Unmagic::Components::ActionViewHelpers
+        end
       end
 
       # turbo_stream.toast. turbo-rails runs this hook when its tag builder loads, so

data/lib/unmagic/components/icons.rb

@@ -1,39 +1,47 @@
 # frozen_string_literal: true
 
+require "unmagic_icon"
+
 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).
+    # The glyphs the components draw for themselves — a close button, a toast's
+    # tone, a tool call's state. Rendered inline through unmagic-icon from a subset
+    # of Lucide the gem ships in app/assets/icons/lucide (ISC, see the LICENSE
+    # beside the files), so a host needs no icon set of its own: kp2 downloads
+    # Phosphor, not Lucide, and the components still draw.
+    #
+    # The library is read from the gem's own directory rather than looked up in
+    # unmagic-icon's registry, which only learns about engine icons when the host
+    # leaves unmagic-icon to initialise itself. Under Rails the same files are also
+    # registered as "unmagic_components:lucide", for a host that wants to draw them.
     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
+      DIRECTORY = File.expand_path("../../../app/assets/icons/lucide", __dir__)
 
       # 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}" }
+      class << self
+        # An icon by its Lucide name as a symbol, :circle_check for circle-check.
+        # Decorative unless the caller says otherwise, so aria-hidden is on by default.
+        def svg(view, name, **options)
+          library.find(name.to_s.tr("_", "-")).render(
+            "aria-hidden": "true", **options, class: view.class_names("UnmagicIcon", options[:class])
+          )
+        rescue Unmagic::Icon::IconNotFoundError
+          raise ArgumentError, "unknown icon #{name.inspect}"
+        end
+
+        def names
+          Dir[File.join(DIRECTORY, "*.svg")].map { |path| File.basename(path, ".svg").tr("-", "_").to_sym }.sort
+        end
+
+        private
 
-        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])
-        )
+        # The library's manifest-free lookup falls back to nothing, so an unknown
+        # name raises rather than drawing some other glyph.
+        def library
+          @library ||= Unmagic::Icon::Library.new(name: "unmagic_components:lucide", path: DIRECTORY)
+        end
       end
     end
   end

data/lib/unmagic/components/modal.rb

@@ -56,7 +56,7 @@ module Unmagic
 
         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") ]
+            safe_join [ Icons.svg(view, :rotate_cw), I18n.t("unmagic.components.modal.retry", default: "Try again") ]
           end
         end
 

data/lib/unmagic/components/page_header.rb

@@ -41,6 +41,14 @@ module Unmagic
         nil
       end
 
+      # Markup beside the title, as it is — the counterpart to leading, and the way to put badges
+      # there that something else has already rendered: a status partial, a row a helper returns.
+      # Those can't go through badge, which would wrap a badge in a badge.
+      def trailing(content = nil, &block)
+        @badges << (block ? view.capture(&block) : content)
+        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.

data/lib/unmagic/components/sortable.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+
+module Unmagic
+  module Components
+    # Drag-and-drop ordering: a list whose items can be dragged, or moved with the
+    # keyboard, and dropped in a new place, here or in another list that shares its
+    # namespace. See ActionViewHelpers#sortable_list.
+    module Sortable
+      ORIENTATIONS = %i[vertical horizontal grid].freeze
+
+      # What the element says to a screen reader as an item is picked up, moved,
+      # dropped or put back. {item}, {list}, {position} and {count} are filled in by
+      # the element as it goes.
+      ANNOUNCEMENTS = {
+        instructions: "Press Space to pick up. While holding it, use the arrow keys to move it, Space to drop it, " \
+                      "and Escape to cancel.",
+        picked: "Picked up {item}. Position {position} of {count} in {list}.",
+        moved: "{item} moved to position {position} of {count} in {list}.",
+        dropped: "Dropped {item} at position {position} of {count} in {list}.",
+        cancelled: "Cancelled. {item} is back at position {position} of {count} in {list}."
+      }.freeze
+
+      def self.announcements
+        ANNOUNCEMENTS.to_h do |key, default|
+          [ key, I18n.t("unmagic.components.sortable.#{key}", default: default) ]
+        end
+      end
+
+      # The <unmagic-sortable-list> and the items recorded into it.
+      class List
+        def initialize(view, namespace: nil, params: {}, url: nil, orientation: :vertical, label: nil, **options)
+          unless ORIENTATIONS.include?(orientation)
+            raise ArgumentError, "unknown sortable_list orientation #{orientation.inspect} (expected one of #{ORIENTATIONS.inspect})"
+          end
+
+          @view = view
+          @namespace = namespace
+          @params = params
+          @url = url.nil? ? Components.configuration.sortable_url.call(view) : url
+          @orientation = orientation
+          @label = label
+          @options = options
+          @items = []
+        end
+
+        # An item for a record (its key and rank come from config.sortable_item), or
+        # for key: and rank: given directly. label: is what a screen reader hears it
+        # called; without it, its text.
+        def item(record = nil, key: nil, rank: nil, label: nil, tag: "unmagic-sortable-item", **options, &block)
+          attributes = record ? Components.configuration.sortable_item.call(view, record) : {}
+          key ||= attributes[:key]
+          rank ||= attributes[:rank]
+          raise ArgumentError, "a sortable item needs a record or a key:" if key.blank?
+
+          rank = rank.to_s("F") if rank.is_a?(BigDecimal)
+          @items << view.content_tag(tag, block ? view.capture(&block) : nil, **options,
+            key: key,
+            "data-sortable-rank": rank,
+            "data-sortable-label": label,
+            class: view.class_names("UnmagicSortableItem", options[:class]))
+          nil
+        end
+
+        def render(extra = nil)
+          announcements = Sortable.announcements
+
+          view.content_tag("unmagic-sortable-list", **@options,
+            namespace: @namespace.presence,
+            url: @url.presence,
+            orientation: (@orientation unless @orientation == :vertical),
+            label: @label,
+            data: announcements.transform_keys { |key| "sortable_#{key}" }.merge(@options[:data] || {}),
+            class: view.class_names("UnmagicSortableList", "UnmagicSortableList--#{@orientation}", @options[:class])) do
+            view.safe_join [
+              *@params.map { |name, value| view.content_tag("unmagic-sortable-param", "", name: name, value: value) },
+              *@items,
+              extra
+            ].compact
+          end
+        end
+
+        private
+
+        attr_reader :view
+      end
+
+      # The grip an item is dragged by. With one in an item, only the grip starts a
+      # drag, so the rest of the item stays clickable, and it is the item's keyboard
+      # stop.
+      def self.handle(view, label: nil, **options)
+        label ||= I18n.t("unmagic.components.sortable.handle", default: "Drag to reorder")
+
+        view.tag.button(type: "button", **options,
+          "aria-label": label, title: label,
+          "data-sortable-handle": "",
+          class: view.class_names(Button.classes(:icon), "UnmagicSortableHandle", options[:class])) do
+          Icons.svg(view, :grip_vertical)
+        end
+      end
+    end
+  end
+end

data/lib/unmagic/components/streaming_markdown.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Unmagic
+  module Components
+    # Server-rendered HTML, revealed at a steady pace as later renders of it are
+    # streamed in. See ActionViewHelpers#streaming_markdown_tag.
+    class StreamingMarkdown
+      def initialize(view, id:, final: false, streaming: false, **options)
+        raise ArgumentError, "streaming_markdown_tag needs an id: to stream into" if id.blank?
+
+        @view = view
+        @id = id
+        @final = final
+        @streaming = streaming
+        @options = options
+      end
+
+      # aria-busy only while the caller says a reply is live. It is what stops a
+      # transcript's live region announcing every flush, and a settled reply
+      # rendered busy would be skipped by a screen reader if the script never ran.
+      def render(content)
+        view.content_tag("unmagic-streaming-markdown", content, **@options,
+          id: @id,
+          final: ("" if @final),
+          "aria-busy": ("true" if @streaming && !@final),
+          class: view.class_names("UnmagicStreamingMarkdown", @options[:class]))
+      end
+
+      private
+
+      attr_reader :view
+    end
+  end
+end

data/lib/unmagic/components/turbo_stream_actions.rb

@@ -14,6 +14,22 @@ module Unmagic
       def toast(message, tone: :good)
         append Toast::TARGET, Toast.new(@view_context, message, tone: tone).template
       end
+
+      # Hands the whole of a reply rendered so far to the <unmagic-streaming-markdown>
+      # with that id, which paces its way toward it. Send the full render every
+      # time, not the new part: the element works out what is new.
+      #
+      #   turbo_stream.stream_markdown "message_1_content", Markdown.render(message.content)
+      #
+      # From a model, the same action through Turbo::Broadcastable:
+      #
+      #   broadcast_action_to chat, action: :stream_markdown, target: "#{dom_id(self)}_content",
+      #     html: Markdown.render(content)
+      #
+      # Needs import "unmagic/components/streaming_markdown".
+      def stream_markdown(target, content = nil, **rendering, &block)
+        action :stream_markdown, target, content, **rendering, &block
+      end
     end
   end
 end

data/lib/unmagic/components/version.rb

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

data/lib/unmagic/components.rb

@@ -38,10 +38,39 @@ require_relative "components/tabs"
 require_relative "components/copy_button"
 require_relative "components/autogrow"
 require_relative "components/uuid_input"
+require_relative "components/duration"
+require_relative "components/elapsed"
+require_relative "components/streaming_markdown"
+require_relative "components/avatar"
+require_relative "components/sortable"
+require_relative "components/board"
+require_relative "components/ai_chat"
+require_relative "components/ai_chat/payload"
+require_relative "components/ai_chat/reasoning"
+require_relative "components/ai_chat/message"
+require_relative "components/ai_chat/transcript"
+require_relative "components/ai_chat/tool_call"
+require_relative "components/ai_chat/failure"
+require_relative "components/ai_chat/section"
+require_relative "components/ai_chat/plan"
+require_relative "components/ai_chat/workspace"
+require_relative "components/ai_chat/composer"
+require_relative "components/ai_chat/request"
+require_relative "components/ai_chat/permission"
+require_relative "components/ai_chat/proposal"
+require_relative "components/ai_chat/citation"
+require_relative "components/ai_chat/welcome"
+require_relative "components/ai_chat/attachments"
+require_relative "components/ai_chat/slash_menu"
+require_relative "components/ai_chat/action_bar"
+require_relative "components/ai_chat/branch_picker"
 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.
-require_relative "components/engine" if defined?(Rails::Engine)
+if defined?(Rails::Engine)
+  require_relative "components/engine"
+  require_relative "components/browser"
+end
 
 module Unmagic
   module Components