unmagic-components 0.3.0 → 0.4.0

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

@@ -0,0 +1,206 @@
+# frozen_string_literal: true
+
+module Unmagic
+  module Components
+    module AIChat
+      # The agent asking something it can't work out on its own, with the answers
+      # right there. One component, two faces: choices, or a form the caller
+      # builds. See ActionViewHelpers#ai_chat_request.
+      class Request
+        STATES = %i[waiting accepted declined cancelled timed_out].freeze
+
+        OUTCOMES = { accepted: "Submitted", declined: "Declined", cancelled: "Cancelled",
+                     timed_out: "Timed out" }.freeze
+
+        OUTCOME_ICONS = { accepted: :circle_check, declined: :ban, cancelled: :circle_x, timed_out: :clock }.freeze
+
+        Question = Struct.new(:text, :header, :multiple, :options, :picked)
+        Option = Struct.new(:label, :description)
+
+        # Collects a question's options.
+        class QuestionBuilder
+          attr_reader :options
+
+          def initialize
+            @options = []
+          end
+
+          def option(label, description: nil)
+            @options << Option.new(label, description)
+            nil
+          end
+        end
+
+        def initialize(view, state:, url: nil, method: :patch, prompt: nil, label: nil, scope: :response,
+          live: false, **options)
+          AIChat.validate!("ai_chat_request", :state, state, STATES)
+          raise ArgumentError, "a waiting ai_chat_request needs a url: to answer to" if state == :waiting && url.blank?
+
+          @view = view
+          @state = state
+          @url = url
+          @method = method
+          @prompt = prompt
+          @label = label
+          @scope = scope
+          @live = live
+          @options = options
+          @questions = []
+          @form = nil
+          @answers = []
+          @decline = nil
+          @aside = nil
+        end
+
+        # picked: is what was chosen, for an answered request; the options go, and
+        # the question stays, because it is most of what the card is worth later.
+        def question(text, header: nil, multiple: false, picked: nil, &block)
+          builder = QuestionBuilder.new
+          view.capture(builder, &block) if block # capture, so the block's own whitespace stays out of the page
+          @questions << Question.new(text, header, multiple, builder.options, Array(picked))
+          nil
+        end
+
+        # The caller's own fields, given the form builder while waiting.
+        def form(&block)
+          @form = block
+          nil
+        end
+
+        # What was sent back, for an answered form.
+        def answer(label, value)
+          @answers << [ label, value ]
+          nil
+        end
+
+        def decline(label = nil)
+          @decline = label || AIChat.t("request.decline", default: "Decline")
+          nil
+        end
+
+        def aside(text)
+          @aside = text
+          nil
+        end
+
+        def render
+          raise ArgumentError, "an ai_chat_request asks with questions or a form, not both" if @questions.any? && @form
+
+          view.content_tag(:div, **@options,
+            role: ("alert" if @live && waiting?),
+            class: view.class_names("UnmagicAIChatRequest", "UnmagicAIChatRequest--#{@state}", @options[:class])) do
+            safe_join [ head, (tag.p(@prompt, class: "UnmagicAIChatRequest__prompt") if @prompt.present?), body ].compact
+          end
+        end
+
+        private
+
+        attr_reader :view
+
+        delegate :tag, :safe_join, to: :view, private: true
+
+        def waiting? = @state == :waiting
+
+        # Past tense once answered: a heading still saying somebody wants something
+        # would be the one line in the card that's no longer true.
+        def head
+          tag.div(class: "UnmagicAIChatRequest__head") do
+            safe_join [
+              Icons.svg(view, :circle_question_mark),
+              tag.span(waiting? ? AIChat.t("request.waiting", default: "Wants to know") : AIChat.t("request.asked", default: "Wanted to know")),
+              (outcome unless waiting?)
+            ].compact
+          end
+        end
+
+        def outcome
+          tag.span(class: "UnmagicAIChatRequest__outcome") do
+            safe_join [ Icons.svg(view, OUTCOME_ICONS.fetch(@state)), AIChat.t("request.#{@state}", default: OUTCOMES.fetch(@state)) ]
+          end
+        end
+
+        def body
+          if waiting?
+            view.form_with(url: @url, method: @method, scope: @scope, builder: Components::FormBuilder,
+              class: "UnmagicAIChatRequest__form") do |form|
+              safe_join [ questions, (view.capture(form, &@form) if @form), actions ].compact
+            end
+          else
+            safe_join [ questions, answers ].compact
+          end
+        end
+
+        def questions
+          return if @questions.empty?
+
+          safe_join(@questions.each_with_index.map { |question, index| fieldset(question, index) })
+        end
+
+        def fieldset(question, index)
+          tag.fieldset(class: "UnmagicAIChatRequest__question") do
+            safe_join [
+              tag.legend(class: "UnmagicAIChatRequest__legend") do
+                safe_join [
+                  (tag.span(question.header, class: "UnmagicAIChatRequest__header") if question.header.present?),
+                  tag.span(question.text, class: "UnmagicAIChatRequest__label")
+                ].compact
+              end,
+              waiting? ? choices(question, index) : picked(question)
+            ]
+          end
+        end
+
+        # A single choice is required, so a question skipped by accident isn't one
+        # the agent has to ask again.
+        def choices(question, index)
+          kind = question.multiple ? :check : :radio
+
+          tag.div(class: "UnmagicAIChatRequest__options") do
+            safe_join(question.options.map do |option|
+              tag.label(class: "UnmagicAIChatRequest__option") do
+                safe_join [
+                  tag.input(type: question.multiple ? "checkbox" : "radio", name: "answers[#{index}][]",
+                    value: option.label, required: !question.multiple, class: Control.classes(view, kind)),
+                  tag.span(class: "UnmagicAIChatRequest__choice") do
+                    safe_join [
+                      tag.span(option.label, class: "UnmagicAIChatRequest__choiceLabel"),
+                      (tag.span(option.description, class: "UnmagicAIChatRequest__choiceDescription") if option.description.present?)
+                    ].compact
+                  end
+                ]
+              end
+            end)
+          end
+        end
+
+        def picked(question)
+          text = question.picked.presence&.to_sentence || AIChat.t("request.unanswered", default: "No answer.")
+          tag.p(text, class: view.class_names("UnmagicAIChatRequest__picked",
+            "UnmagicAIChatRequest__picked--none" => question.picked.empty?))
+        end
+
+        def answers
+          return if @answers.empty?
+
+          tag.dl(class: "UnmagicAIChatRequest__answers") do
+            safe_join(@answers.map do |label, value|
+              tag.div(safe_join([ tag.dt(label), tag.dd(value) ]), class: "UnmagicAIChatRequest__answer")
+            end)
+          end
+        end
+
+        # Decline posts the same form with a flag and skips validation, so it is one
+        # form with no nested button_to and needs nothing filled in.
+        def actions
+          tag.div(class: "UnmagicAIChatRequest__actions") do
+            safe_join [
+              tag.button(@label || AIChat.t("request.answer", default: "Answer"), type: "submit", class: Button.classes(:primary)),
+              (tag.button(@decline, type: "submit", name: "decline", value: "1", formnovalidate: true, class: Button.classes) if @decline),
+              (tag.p(@aside, class: "UnmagicAIChatRequest__aside") if @aside.present?)
+            ].compact
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Unmagic
+  module Components
+    module AIChat
+      # The collapsible panel section a plan and a workspace share: a glyph, a
+      # title, a count and a chevron over a body. Always rendered, empty or not,
+      # because both are broadcast targets.
+      class Section
+        def initialize(view, block:, icon:, title:, count:, open:, collapsible:, title_tag:, options:)
+          @view = view
+          @block = block
+          @icon = icon
+          @title = title
+          @count = count
+          @open = open
+          @collapsible = collapsible
+          @title_tag = title_tag
+          @options = options
+        end
+
+        def render(body)
+          classes = view.class_names(@block, { "#{@block}--static" => !@collapsible }, @options[:class])
+
+          if @collapsible
+            tag.details(**@options, open: @open, class: classes) do
+              safe_join [ tag.summary(head(chevron: true), class: "#{@block}__head"), body ]
+            end
+          else
+            tag.section(**@options, class: classes) do
+              safe_join [ tag.div(head(chevron: false), class: "#{@block}__head"), body ]
+            end
+          end
+        end
+
+        private
+
+        attr_reader :view
+
+        delegate :tag, :safe_join, to: :view, private: true
+
+        def head(chevron:)
+          safe_join [
+            Icons.svg(view, @icon, class: "#{@block}__icon"),
+            view.content_tag(@title_tag, @title, class: "#{@block}__title"),
+            (Icons.svg(view, :chevron_right, class: "UnmagicAIChatChevron") if chevron),
+            (tag.span(@count, class: "#{@block}__count") if @count.present?)
+          ].compact
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Unmagic
+  module Components
+    module AIChat
+      # Commands offered on a slash, rendered with every item and filtered in the
+      # browser, so what can be offered is only ever what exists. See
+      # ActionViewHelpers#ai_chat_slash_menu.
+      class SlashMenu
+        Item = Struct.new(:name, :description, :arguments)
+
+        def initialize(view, for: nil, id: nil, trigger: "/", above: false, insert: nil, **options)
+          raise ArgumentError, "ai_chat_slash_menu trigger must be one character" unless trigger.to_s.length == 1
+
+          @view = view
+          @for = binding.local_variable_get(:for)
+          @id = id || AIChat.random_id("slash_menu")
+          @trigger = trigger
+          @above = above
+          @insert = insert
+          @options = options
+          @items = []
+        end
+
+        def item(name, description: nil, arguments: [])
+          @items << Item.new(name.to_s, description, Array(arguments))
+          nil
+        end
+
+        # An agent with no commands has no menu, not an empty one.
+        def render
+          return "".html_safe if @items.empty?
+
+          label = AIChat.t("slash_menu.label", default: "Commands")
+
+          view.content_tag("unmagic-slash-menu", **@options,
+            for: @for, trigger: @trigger, insert: @insert, hidden: true,
+            class: view.class_names("UnmagicAIChatSlashMenu", { "UnmagicAIChatSlashMenu--above" => @above }, @options[:class])) do
+            tag.ul(id: "#{@id}_listbox", role: "listbox", "aria-label": label, class: "UnmagicAIChatSlashMenu__list") do
+              safe_join(@items.each_with_index.map { |item, index| option(item, index) })
+            end
+          end
+        end
+
+        private
+
+        attr_reader :view
+
+        delegate :tag, :safe_join, to: :view, private: true
+
+        def option(item, index)
+          tag.li(id: "#{@id}_#{index}", role: "option", "aria-selected": index.zero?.to_s, data: { name: item.name },
+            class: "UnmagicAIChatSlashMenu__item") do
+            safe_join [
+              tag.span(class: "UnmagicAIChatSlashMenu__name") do
+                safe_join [
+                  "#{@trigger}#{item.name}",
+                  *item.arguments.map { |argument| tag.span("[#{argument}]", class: "UnmagicAIChatSlashMenu__argument") }
+                ], " "
+              end,
+              (tag.span(item.description, class: "UnmagicAIChatSlashMenu__description") if item.description.present?)
+            ].compact
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+module Unmagic
+  module Components
+    module AIChat
+      # One reach for a tool, from the ask through to the answer, as a row in a
+      # timeline. See ActionViewHelpers#ai_chat_tool_call.
+      class ToolCall
+        STATES = %i[queued running waiting done failed].freeze
+
+        GLYPHS = { queued: :circle_dashed, running: :loader_circle, waiting: :circle_question_mark,
+                   done: :circle_check, failed: :circle_x }.freeze
+
+        LABELS = { queued: "Queued", running: "Running", waiting: "Waiting on you", done: "Done",
+                   failed: "Failed" }.freeze
+
+        def initialize(view, name:, state:, id: nil, icon: nil, open: false, timeline: true, **options)
+          AIChat.validate!("ai_chat_tool_call", :state, state, STATES)
+
+          @view = view
+          @name = name
+          @state = state
+          @id = id
+          @icon = icon
+          @open = open
+          @timeline = timeline
+          @options = options
+          @summary = nil
+          @timing = nil
+          @failures = nil
+          @progress = nil
+          @payloads = []
+          @made = nil
+        end
+
+        # What the call was actually about, beside the name: three identical labels
+        # say nothing, "search_messages · car seat" does.
+        def summary(text)
+          @summary = text
+          nil
+        end
+
+        # A live clock while running, what it took once done, nothing if neither is
+        # known — a zero would be a reading, and there isn't one.
+        def timing(started_at: nil, duration: nil)
+          @timing = { started_at: started_at, duration: duration }
+          nil
+        end
+
+        def asked(payload, **options)
+          @payloads << Payload.new(view, payload, label: AIChat.t("tool_call.asked", default: "Asked"), **options)
+          nil
+        end
+
+        def answered(payload, **options)
+          @payloads << Payload.new(view, payload, label: AIChat.t("tool_call.answered", default: "Answered"), **options)
+          nil
+        end
+
+        # How much of a batch didn't work, for a call that otherwise did. Nothing for
+        # zero, and nothing for a call that failed outright, which already says so.
+        def failures(count)
+          @failures = count
+          nil
+        end
+
+        # What the tool is saying while it works. Rendered with its own id so the host
+        # can replace just this line as reports come in.
+        def progress(text)
+          @progress = text
+          nil
+        end
+
+        # What the call produced. It stays outside the fold: it is the reason the
+        # call happened, and hiding it behind a chevron is the wrong way round.
+        def made(content = nil, &block)
+          @made = block ? view.capture(&block) : content
+          nil
+        end
+
+        def render
+          payloads = @payloads.map(&:render).select(&:present?)
+
+          view.content_tag(:div, **@options,
+            id: @id,
+            "aria-busy": ("true" if @state == :running),
+            data: { ai_chat_timeline: ("row" if @timeline) }.merge(@options[:data] || {}),
+            class: view.class_names("UnmagicAIChatToolCall", "UnmagicAIChatToolCall--#{@state}", @options[:class])) do
+            safe_join [
+              (tag.span(class: "UnmagicAIChatToolCall__join", "aria-hidden": "true") if @timeline),
+              payloads.any? ? disclosure(payloads) : tag.div(row(chevron: false), class: "UnmagicAIChatToolCall__row"),
+              (tag.div(safe_join([ rail, @made ]), class: "UnmagicAIChatToolCall__made") if @made.present?)
+            ].compact
+          end
+        end
+
+        private
+
+        attr_reader :view
+
+        delegate :tag, :safe_join, to: :view, private: true
+
+        # <details> so the disclosure needs no script and no state to restore after
+        # a broadcast replaces the row, which happens on every change of state.
+        def disclosure(payloads)
+          tag.details(open: @open, class: "UnmagicAIChatToolCall__disclosure") do
+            safe_join [
+              tag.summary(row(chevron: true), class: "UnmagicAIChatToolCall__row"),
+              tag.div(safe_join([ rail, *payloads ]), class: "UnmagicAIChatToolCall__body")
+            ]
+          end
+        end
+
+        def row(chevron:)
+          safe_join [
+            glyph,
+            tag.code(@name, class: "UnmagicAIChatToolCall__name"),
+            (tag.span(@summary, class: "UnmagicAIChatToolCall__summary") if @summary.present?),
+            (Icons.svg(view, :chevron_right, class: "UnmagicAIChatChevron") if chevron),
+            readings,
+            (progress_line if @state == :running && @progress.present?)
+          ].compact
+        end
+
+        # A call that simply worked is the common case, so its glyph says what it was
+        # about (icon:) rather than repeating a tick down the whole timeline.
+        def glyph
+          name = @state == :done && @icon ? @icon : GLYPHS.fetch(@state)
+
+          tag.span(class: "UnmagicAIChatToolCall__glyph") do
+            safe_join [
+              Icons.svg(view, name, class: ("UnmagicAIChatSpinner" if @state == :running)),
+              tag.span(AIChat.t("tool_call.#{@state}", default: LABELS.fetch(@state)), class: "UnmagicVisuallyHidden")
+            ]
+          end
+        end
+
+        def readings
+          items = [ failures_reading, timing_reading ].compact
+          tag.span(safe_join(items), class: "UnmagicAIChatToolCall__readings") if items.any?
+        end
+
+        def failures_reading
+          return if @failures.to_i.zero? || @state == :failed
+
+          reading(:triangle_alert, AIChat.t("tool_call.partly_failed", default: "Partly failed"),
+            AIChat.t("tool_call.failures", count: @failures, default: "%{count} failed"), modifier: "warn")
+        end
+
+        def timing_reading
+          return unless @timing
+
+          if @state == :running && @timing[:started_at]
+            reading(:timer, AIChat.t("tool_call.running_for", default: "Running for"),
+              Elapsed.new(view, @timing[:started_at], direction: :up).render)
+          elsif @timing[:duration]
+            reading(:timer, AIChat.t("tool_call.took", default: "Took"), Duration.format(@timing[:duration]))
+          end
+        end
+
+        # Each reading leads with a glyph, so a run of small grey numbers can be told
+        # apart before the digits are read.
+        def reading(icon, label, value, modifier: nil)
+          tag.span(class: view.class_names("UnmagicAIChatToolCall__reading",
+            "UnmagicAIChatToolCall__reading--#{modifier}" => modifier)) do
+            safe_join [ Icons.svg(view, icon), tag.span(label, class: "UnmagicVisuallyHidden"), value ]
+          end
+        end
+
+        def progress_line
+          tag.span(@progress, id: ("#{@id}_progress" if @id), class: "UnmagicAIChatToolCall__progress")
+        end
+
+        # The timeline carried down the side of whatever hangs under a row.
+        def rail
+          tag.span(class: "UnmagicAIChatToolCall__rail", "aria-hidden": "true")
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Unmagic
+  module Components
+    module AIChat
+      # The scrolling region a conversation's turns are rendered into, and the
+      # spacing between them. It renders no entries of its own: the host keeps a
+      # partial per entry type. See ActionViewHelpers#ai_chat.
+      class Transcript
+        def initialize(view, id:, scroller: nil, follow: true, scroll_to_latest: true, **options)
+          raise ArgumentError, "ai_chat needs an id: for entries to be broadcast into" if id.blank?
+
+          @view = view
+          @id = id
+          @scroller = scroller
+          @follow = follow
+          @scroll_to_latest = scroll_to_latest
+          @options = options
+          @welcome = nil
+        end
+
+        # Shown while the conversation is empty. It renders inside the log, so the
+        # first entry streamed in hides it (see the CSS) without another request.
+        def welcome(content = nil, &block)
+          @welcome = block ? view.capture(&block) : content
+          nil
+        end
+
+        # Always renders the log, empty or not: a broadcast can only land in an
+        # element that is already on the page.
+        def render(entries)
+          log = view.content_tag(:div, **@options,
+            id: @id,
+            role: "log",
+            "aria-live": "polite",
+            "aria-relevant": "additions",
+            "aria-label": AIChat.t("transcript.label", default: "Conversation"),
+            class: view.class_names("UnmagicAIChat", @options[:class])) do
+            safe_join [ (tag.div(@welcome, class: "UnmagicAIChat__welcome") if @welcome && entries.blank?), entries ].compact
+          end
+
+          return log unless @follow
+
+          view.content_tag("unmagic-autoscroll", scroller: @scroller, class: "UnmagicAutoscroll") do
+            safe_join [ log, (latest if @scroll_to_latest) ].compact
+          end
+        end
+
+        private
+
+        attr_reader :view
+
+        delegate :tag, :safe_join, to: :view, private: true
+
+        # A real button in the tab order, shown by <unmagic-autoscroll> only while
+        # the reader has scrolled away from the bottom.
+        def latest
+          label = AIChat.t("transcript.latest", default: "Jump to latest")
+
+          tag.div(class: "UnmagicAIChat__latest") do
+            tag.button(Icons.svg(view, :arrow_down), type: "button", hidden: true, "data-autoscroll-latest": "",
+              "aria-label": label, title: label, class: "UnmagicAIChat__latestButton")
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Unmagic
+  module Components
+    module AIChat
+      # What an empty conversation says, and the suggestions that start one. See
+      # ActionViewHelpers#ai_chat_welcome.
+      class Welcome
+        Suggestion = Struct.new(:label, :icon, :fill, :value)
+
+        def initialize(view, heading:, heading_tag: :h2, composer: "composer", field: nil, **options)
+          @view = view
+          @heading = heading
+          @heading_tag = heading_tag
+          @composer = composer
+          @field = field
+          @options = options
+          @body = nil
+          @suggestions = []
+        end
+
+        def body(text)
+          @body = text
+          nil
+        end
+
+        # fill: true puts the text in the box without sending it, for a prompt that
+        # can't be sent as it stands.
+        def suggestion(label, icon: nil, fill: false, value: nil)
+          @suggestions << Suggestion.new(label, icon, fill, value)
+          nil
+        end
+
+        def render
+          view.content_tag(:div, **@options, class: view.class_names("UnmagicAIChatWelcome", @options[:class])) do
+            safe_join [
+              view.content_tag(@heading_tag, @heading, class: "UnmagicAIChatWelcome__heading"),
+              (tag.p(@body, class: "UnmagicAIChatWelcome__body") if @body.present?),
+              suggestions
+            ].compact
+          end
+        end
+
+        private
+
+        attr_reader :view
+
+        delegate :tag, :safe_join, to: :view, private: true
+
+        # Buttons, not links: a suggestion puts text in a box on this page.
+        def suggestions
+          return if @suggestions.empty?
+
+          tag.ul(class: "UnmagicAIChatWelcome__suggestions") do
+            safe_join(@suggestions.map do |suggestion|
+              tag.li do
+                tag.button(type: "button", class: "UnmagicAIChatWelcome__suggestion",
+                  data: {
+                    ai_chat_suggestion: suggestion.value || suggestion.label,
+                    ai_chat_suggestion_form: @composer,
+                    ai_chat_suggestion_field: @field,
+                    ai_chat_suggestion_fill: ("" if suggestion.fill)
+                  }.compact) do
+                  safe_join [ (Icons.svg(view, suggestion.icon) if suggestion.icon), suggestion.label ].compact
+                end
+              end
+            end)
+          end
+        end
+      end
+    end
+  end
+end