unmagic-components 0.3.0 → 0.4.0

data/lib/unmagic/components/ai_chat/payload.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Unmagic
+  module Components
+    module AIChat
+      # What went into a tool call or came back out of it, to be read exactly as it
+      # was written. See ActionViewHelpers#ai_chat_payload.
+      class Payload
+        def initialize(view, payload, label: nil, language: nil, duration: nil, copy: false, **options)
+          @view = view
+          @payload = payload
+          @label = label
+          @language = language
+          @duration = duration
+          @copy = copy
+          @options = options
+        end
+
+        # An absent payload renders nothing, not a dash: a response that hasn't
+        # arrived isn't an empty one.
+        def render
+          return "".html_safe if @payload.nil?
+
+          source, language = formatted
+
+          view.content_tag(:div, **@options, class: view.class_names("UnmagicAIChatPayload", @options[:class])) do
+            safe_join [ head(source), code(source, language) ].compact
+          end
+        end
+
+        private
+
+        attr_reader :view
+
+        delegate :tag, :safe_join, to: :view, private: true
+
+        # Structured data is laid out a key to a line; a string that turns out to be
+        # JSON is too. Anything else is shown as the text it is rather than being
+        # mis-tokenised.
+        def formatted
+          return [ @payload.to_s, @language ] if @language && !structured?(@payload)
+
+          value = @payload.is_a?(String) ? parse(@payload) : @payload
+          if structured?(value)
+            [ JSON.pretty_generate(value), @language || :json ]
+          else
+            [ @payload.to_s, @language || :plaintext ]
+          end
+        end
+
+        def structured?(value) = value.is_a?(Hash) || value.is_a?(Array)
+
+        def parse(string)
+          JSON.parse(string)
+        rescue JSON::ParserError
+          string
+        end
+
+        def head(source)
+          return if @label.blank? && @duration.nil? && !@copy
+
+          tag.div(class: "UnmagicAIChatPayload__head") do
+            safe_join [
+              tag.span(@label, class: "UnmagicAIChatPayload__label"),
+              (timing if @duration),
+              (view.copy_button(source, class: "UnmagicAIChatPayload__copy") if @copy)
+            ].compact
+          end
+        end
+
+        def timing
+          tag.span(class: "UnmagicAIChatPayload__timing") do
+            safe_join [
+              Icons.svg(view, :timer),
+              tag.span(AIChat.t("payload.took", default: "Took"), class: "UnmagicVisuallyHidden"),
+              Duration.format(@duration)
+            ]
+          end
+        end
+
+        # Scrollable, so reachable by keyboard and named for it: a region nobody can
+        # scroll without a mouse is a trap in reverse.
+        def code(source, language)
+          tag.div(Components.configuration.code_block.call(view, source, language),
+            class: "UnmagicAIChatPayload__code", tabindex: 0, role: "region",
+            "aria-label": @label.presence || AIChat.t("payload.label", default: "Payload"))
+        end
+      end
+    end
+  end
+end

data/lib/unmagic/components/ai_chat/permission.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module Unmagic
+  module Components
+    module AIChat
+      # An agent asking to be allowed something, with the answer under the
+      # reasoning rather than in a dialog that arrived without it. See
+      # ActionViewHelpers#ai_chat_permission.
+      class Permission
+        STATES = %i[waiting granted refused lapsed].freeze
+
+        OUTCOMES = { granted: "Allowed.", refused: "Refused.",
+                     lapsed: "Answered in the chat — nothing was granted." }.freeze
+
+        def initialize(view, tool:, state:, url: nil, live: false, outcome: nil, **options)
+          AIChat.validate!("ai_chat_permission", :state, state, STATES)
+          raise ArgumentError, "a waiting ai_chat_permission needs a url: to answer to" if state == :waiting && url.blank?
+
+          @view = view
+          @tool = tool
+          @state = state
+          @url = url
+          @live = live
+          @outcome = outcome
+          @options = options
+          @arguments = []
+          @summary = nil
+          @reason = nil
+          @examples = []
+          @actions = []
+        end
+
+        # A name and value the grant is for, beside the tool in the ask line.
+        def argument(name, value)
+          @arguments << [ name, value ]
+          nil
+        end
+
+        def summary(content = nil, &block)
+          @summary = block ? view.capture(&block) : content
+          nil
+        end
+
+        def reason(content = nil, &block)
+          @reason = block ? view.capture(&block) : content
+          nil
+        end
+
+        def example(text)
+          @examples << text
+          nil
+        end
+
+        # Repeatable: the second is the wider grant, offered only when there is
+        # something left to widen. The host decides that; the gem can't know.
+        def allow(label = nil, params: {}, confirm: nil, method: :post)
+          @actions << [ :allow, label || AIChat.t("permission.allow", default: "Allow"), params, confirm, method ]
+          nil
+        end
+
+        def refuse(label = nil, params: {}, confirm: nil, method: :delete)
+          @actions << [ :refuse, label || AIChat.t("permission.refuse", default: "Refuse"), params, confirm, method ]
+          nil
+        end
+
+        def render
+          waiting = @state == :waiting
+
+          # Focus lands on the card, never on Allow, so a stray Enter grants nothing.
+          view.content_tag(:div, **@options,
+            role: ("alert" if @live && waiting),
+            tabindex: ("-1" if waiting),
+            class: view.class_names("UnmagicAIChatPermission", "UnmagicAIChatPermission--#{@state}", @options[:class])) do
+            safe_join [
+              head(waiting),
+              ask,
+              (tag.div(@summary, class: "UnmagicAIChatPermission__summary UnmagicProse") if @summary.present?),
+              (tag.div(@reason, class: "UnmagicAIChatPermission__reason UnmagicProse") if @reason.present?),
+              examples,
+              waiting ? actions : outcome
+            ].compact
+          end
+        end
+
+        private
+
+        attr_reader :view
+
+        delegate :tag, :safe_join, to: :view, private: true
+
+        def head(waiting)
+          tag.div(class: "UnmagicAIChatPermission__head") do
+            safe_join [
+              Icons.svg(view, :shield_alert),
+              waiting ? AIChat.t("permission.waiting", default: "Wants permission") : AIChat.t("permission.asked", default: "Wanted permission")
+            ]
+          end
+        end
+
+        # The tool's own name, untranslated: it is what will be called and what the
+        # permission is written down against.
+        def ask
+          tag.p(class: "UnmagicAIChatPermission__ask") do
+            safe_join [
+              tag.code(@tool, class: "UnmagicAIChatPermission__tool"),
+              *@arguments.map { |name, value| tag.span("#{name}: #{value}", class: "UnmagicAIChatPermission__argument") }
+            ], " "
+          end
+        end
+
+        def examples
+          return if @examples.empty?
+
+          tag.ul(safe_join(@examples.map { |text| tag.li(text) }), class: "UnmagicAIChatPermission__examples")
+        end
+
+        def actions
+          allows = 0
+
+          tag.div(class: "UnmagicAIChatPermission__actions") do
+            safe_join(@actions.map do |kind, label, params, confirm, method|
+              modifier =
+                if kind == :refuse then nil
+                elsif (allows += 1) == 1 then "UnmagicAIChatPermission__allow"
+                else "UnmagicAIChatPermission__widen"
+                end
+
+              # The block form, so it's a <button> whatever the host's Rails defaults.
+              view.button_to(@url, method: method, params: params,
+                form: { data: { turbo_confirm: confirm }.compact },
+                class: view.class_names(Button.classes, modifier)) { label }
+            end)
+          end
+        end
+
+        def outcome
+          text = @outcome || AIChat.t("permission.#{@state}", default: OUTCOMES.fetch(@state))
+          tag.p(text, class: "UnmagicAIChatPermission__outcome")
+        end
+      end
+    end
+  end
+end

data/lib/unmagic/components/ai_chat/plan.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Unmagic
+  module Components
+    module AIChat
+      # The checklist an agent is working through. See
+      # ActionViewHelpers#ai_chat_plan.
+      class Plan
+        STATES = %i[pending in_progress waiting completed].freeze
+
+        # The glyph each state leads with. Waiting is the one in colour: the only
+        # state that won't move on its own.
+        GLYPHS = { pending: :circle_dashed, in_progress: :loader_circle, waiting: :circle_question_mark,
+                   completed: :circle_check }.freeze
+
+        LABELS = { pending: "To do", in_progress: "In progress", waiting: "Waiting on you", completed: "Done" }.freeze
+
+        Step = Struct.new(:title, :state, :detail)
+
+        def initialize(view, title: nil, completed: nil, total: nil, open: true, empty: nil, collapsible: true,
+          title_tag: :h2, **options)
+          @view = view
+          @title = title || AIChat.t("plan.title", default: "Plan")
+          @completed = completed
+          @total = total
+          @open = open
+          @empty = empty
+          @collapsible = collapsible
+          @title_tag = title_tag
+          @options = options
+          @steps = []
+        end
+
+        def step(title, state: :pending, &block)
+          AIChat.validate!("ai_chat_plan step", :state, state, STATES)
+
+          @steps << Step.new(title, state, (view.capture(&block) if block))
+          nil
+        end
+
+        def render
+          Section.new(view, block: "UnmagicAIChatPlan", icon: :list_checks, title: @title, count: count,
+            open: @open, collapsible: @collapsible, title_tag: @title_tag, options: @options).render(body)
+        end
+
+        private
+
+        attr_reader :view
+
+        delegate :tag, :safe_join, to: :view, private: true
+
+        # Given rather than counted when a panel shows only some of the steps, so the
+        # reading isn't worked out from the visible few.
+        def count
+          total = @total || @steps.size
+          return if total.zero?
+
+          "#{@completed || @steps.count { |step| step.state == :completed }}/#{total}"
+        end
+
+        def body
+          if @steps.empty?
+            tag.p(@empty || AIChat.t("plan.empty", default: "Nothing planned yet."), class: "UnmagicAIChatPlan__empty")
+          else
+            tag.ol(safe_join(@steps.map { |step| item(step) }), class: "UnmagicAIChatPlan__steps")
+          end
+        end
+
+        def item(step)
+          tag.li(class: "UnmagicAIChatPlan__step", data: { state: step.state }) do
+            safe_join [
+              tag.span(class: "UnmagicAIChatPlan__glyph") do
+                safe_join [
+                  Icons.svg(view, GLYPHS.fetch(step.state),
+                    class: ("UnmagicAIChatSpinner" if step.state == :in_progress)),
+                  tag.span(AIChat.t("plan.#{step.state}", default: LABELS.fetch(step.state)), class: "UnmagicVisuallyHidden")
+                ]
+              end,
+              tag.div(class: "UnmagicAIChatPlan__text") do
+                safe_join [
+                  tag.span(step.title, class: "UnmagicAIChatPlan__label"),
+                  (tag.div(step.detail, class: "UnmagicAIChatPlan__detail") if step.detail.present?)
+                ].compact
+              end
+            ]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/unmagic/components/ai_chat/proposal.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module Unmagic
+  module Components
+    module AIChat
+      # An offer the agent made in passing, with its actions while pending, settling
+      # into a quiet decided state. It doesn't stop the work. See
+      # ActionViewHelpers#ai_chat_proposal.
+      class Proposal
+        STATES = %i[pending accepted rejected].freeze
+
+        OUTCOMES = { accepted: "Saved", rejected: "Dismissed" }.freeze
+
+        def initialize(view, state: :pending, icon: :lightbulb, id: nil, **options)
+          AIChat.validate!("ai_chat_proposal", :state, state, STATES)
+
+          @view = view
+          @state = state
+          @icon = icon
+          @id = id
+          @options = options
+          @claim = nil
+          @meta = nil
+          @accept = nil
+          @reject = nil
+          @outcome = nil
+        end
+
+        def claim(content = nil, &block)
+          @claim = block ? view.capture(&block) : content
+          nil
+        end
+
+        def meta(text)
+          @meta = text
+          nil
+        end
+
+        def accept(content = nil, &block)
+          @accept = block ? view.capture(&block) : content
+          nil
+        end
+
+        def reject(content = nil, &block)
+          @reject = block ? view.capture(&block) : content
+          nil
+        end
+
+        def outcome(text)
+          @outcome = text
+          nil
+        end
+
+        # An <aside> named by its claim, so a reader tabbing through a reply hears
+        # what each card offers before reaching its buttons.
+        def render
+          claim_id = "#{@id || AIChat.random_id("proposal")}_claim"
+
+          view.content_tag(:aside, **@options,
+            id: @id,
+            "aria-labelledby": claim_id,
+            class: view.class_names("UnmagicAIChatProposal", "UnmagicAIChatProposal--#{@state}", "not-prose", @options[:class])) do
+            safe_join [
+              tag.div(class: "UnmagicAIChatProposal__body") do
+                safe_join [
+                  Icons.svg(view, @icon, class: "UnmagicAIChatProposal__glyph"),
+                  tag.div do
+                    safe_join [
+                      tag.p(@claim, id: claim_id, class: "UnmagicAIChatProposal__claim"),
+                      (tag.p(@meta, class: "UnmagicAIChatProposal__meta") if @meta.present?)
+                    ].compact
+                  end
+                ]
+              end,
+              side
+            ].compact
+          end
+        end
+
+        private
+
+        attr_reader :view
+
+        delegate :tag, :safe_join, to: :view, private: true
+
+        def side
+          if @state == :pending
+            actions = [ @accept, @reject ].select(&:present?)
+            tag.div(safe_join(actions), class: "UnmagicAIChatProposal__actions") if actions.any?
+          else
+            tag.span(class: "UnmagicAIChatProposal__outcome") do
+              safe_join [
+                Icons.svg(view, @state == :accepted ? :check : :x),
+                @outcome || AIChat.t("proposal.#{@state}", default: OUTCOMES.fetch(@state))
+              ]
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/unmagic/components/ai_chat/reasoning.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Unmagic
+  module Components
+    module AIChat
+      # The model's thinking, collapsed above the reply it led to. See
+      # ActionViewHelpers#ai_chat_reasoning.
+      class Reasoning
+        def initialize(view, title: nil, streaming: false, duration: nil, open: false, id: nil, **options)
+          @view = view
+          @title = title
+          @streaming = streaming
+          @duration = duration
+          @open = open
+          @id = id
+          @options = options
+          @blocks = []
+        end
+
+        def block(content = nil, &block)
+          @blocks << (block ? view.capture(&block) : content)
+          nil
+        end
+
+        # Nothing at all when there is no reasoning, unless it is still arriving: a
+        # turn that didn't think should leave no chrome behind.
+        def render(content = nil)
+          blocks = [ content, *@blocks ].select(&:present?)
+          return "".html_safe if blocks.empty? && !@streaming
+
+          tag.details(**@options, open: @open, class: view.class_names("UnmagicAIChatReasoning", @options[:class])) do
+            safe_join [ summary, *blocks.each_with_index.map { |markup, index| body(markup, index) } ]
+          end
+        end
+
+        private
+
+        attr_reader :view
+
+        delegate :tag, :safe_join, to: :view, private: true
+
+        def summary
+          tag.summary(class: "UnmagicAIChatReasoning__head", "aria-busy": ("true" if @streaming)) do
+            safe_join [
+              (Icons.svg(view, :loader_circle, class: "UnmagicAIChatSpinner") if @streaming),
+              tag.span(title, class: "UnmagicAIChatReasoning__title"),
+              Icons.svg(view, :chevron_right, class: "UnmagicAIChatChevron")
+            ].compact
+          end
+        end
+
+        def title
+          if @streaming
+            AIChat.t("reasoning.thinking", default: "Thinking…")
+          elsif @duration
+            AIChat.t("reasoning.duration", duration: Duration.format(@duration), default: "Thought for %{duration}")
+          else
+            @title || AIChat.t("reasoning.title", default: "Thought process")
+          end
+        end
+
+        # A block that is still arriving reveals at the reply's pace, so it needs
+        # an id to stream into; the first block takes the caller's.
+        def body(markup, index)
+          classes = "UnmagicAIChatReasoning__block UnmagicProse"
+          if @streaming && @id
+            StreamingMarkdown.new(view, id: index.zero? ? @id : "#{@id}_#{index}", streaming: true, class: classes).render(markup)
+          else
+            tag.div(markup, class: classes)
+          end
+        end
+      end
+    end
+  end
+end