unmagic-components 0.3.0 → 0.4.0

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

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module Unmagic
+  module Components
+    module AIChat
+      # Files attached to a turn: the tiles a sent turn carries. The drop zone that
+      # takes them is Dropzone. See ActionViewHelpers#ai_chat_attachments.
+      class Attachments
+        ALIGNMENTS = %i[start end].freeze
+
+        File = Struct.new(:name, :size, :url, :thumbnail)
+
+        def initialize(view, align: :start, **options)
+          AIChat.validate!("ai_chat_attachments", :align, align, ALIGNMENTS)
+
+          @view = view
+          @align = align
+          @options = options
+          @files = []
+        end
+
+        def file(name, size: nil, url: nil, thumbnail: nil)
+          @files << File.new(name.to_s, size, url, thumbnail)
+          nil
+        end
+
+        def render
+          return "".html_safe if @files.empty?
+
+          view.content_tag(:ul, **@options,
+            class: view.class_names("UnmagicAIChatAttachments", "UnmagicAIChatAttachments--#{@align}", @options[:class])) do
+            safe_join(@files.map { |file| item(file) })
+          end
+        end
+
+        private
+
+        attr_reader :view
+
+        delegate :tag, :safe_join, to: :view, private: true
+
+        # A thumbnail is decoration: the name beside it is the name.
+        def item(file)
+          content = safe_join [
+            (file.thumbnail ? tag.img(src: file.thumbnail, alt: "", class: "UnmagicAIChatAttachments__thumb") : Icons.svg(view, :file, class: "UnmagicAIChatAttachments__glyph")),
+            tag.span(file.name, class: "UnmagicAIChatAttachments__name"),
+            (tag.span(view.number_to_human_size(file.size), class: "UnmagicAIChatAttachments__size") if file.size)
+          ].compact
+
+          tag.li(class: "UnmagicAIChatAttachments__file") do
+            file.url ? view.link_to(content, file.url, class: "UnmagicAIChatAttachments__link") : content
+          end
+        end
+      end
+
+      # A region that takes dropped and pasted files. See
+      # ActionViewHelpers#ai_chat_dropzone.
+      class Dropzone
+        def initialize(view, input:, url: nil, field: nil, chips: nil, label: nil, **options)
+          raise ArgumentError, "ai_chat_dropzone needs an input: (dragging is never the only way in)" if input.blank?
+          raise ArgumentError, "an uploading ai_chat_dropzone needs a field: to post the uploads under" if url && field.blank?
+
+          @view = view
+          @input = input
+          @url = url
+          @field = field
+          @chips = chips
+          @label = label
+          @options = options
+        end
+
+        # The overlay can't take the pointer, or it would swallow the drop it
+        # advertises; and it's only feedback for a gesture no keyboard can make.
+        def render(content)
+          label = @label || AIChat.t("attachments.drop", default: "Drop to attach")
+
+          view.content_tag("unmagic-dropzone", **@options,
+            input: @input, url: @url, field: @field, chips: @chips,
+            data: {
+              attached: AIChat.t("attachments.attached", name: "{name}", default: "%{name} attached"),
+              failed: AIChat.t("attachments.failed", name: "{name}", default: "Couldn't attach %{name}"),
+              remove: AIChat.t("attachments.remove", name: "{name}", default: "Remove %{name}")
+            }.merge(@options[:data] || {}),
+            class: view.class_names("UnmagicAIChatDropzone", @options[:class])) do
+            safe_join [
+              tag.div(tag.p(safe_join([ Icons.svg(view, :paperclip), label ])),
+                class: "UnmagicAIChatDropzone__overlay", "aria-hidden": "true"),
+              content,
+              tag.span(class: "UnmagicVisuallyHidden", "aria-live": "polite", "data-dropzone-status": ""),
+              chip
+            ].compact
+          end
+        end
+
+        private
+
+        attr_reader :view
+
+        delegate :tag, :safe_join, to: :view, private: true
+
+        # What an attached file looks like before it's sent. The element clones it,
+        # so the chip is the server's markup rather than HTML built in script.
+        def chip
+          tag.template("data-dropzone-chip": "") do
+            tag.div(class: "UnmagicAIChatAttachments__file") do
+              safe_join [
+                Icons.svg(view, :file, class: "UnmagicAIChatAttachments__glyph"),
+                tag.span(class: "UnmagicAIChatAttachments__name", "data-dropzone-name": ""),
+                tag.span(class: "UnmagicAIChatAttachments__size", "data-dropzone-size": ""),
+                tag.button(Icons.svg(view, :x), type: "button", class: "UnmagicAIChatAttachments__remove",
+                  "data-dropzone-remove": "")
+              ]
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Unmagic
+  module Components
+    module AIChat
+      # Walking between alternative versions of a turn. It renders counts and
+      # follows links; what a branch is stays the host's business. See
+      # ActionViewHelpers#ai_chat_branch_picker.
+      class BranchPicker
+        def initialize(view, index:, count:, previous: nil, next: nil, method: :get, **options)
+          raise ArgumentError, "ai_chat_branch_picker count must be at least 1 (got #{count.inspect})" unless count.to_i >= 1
+          unless (1..count).cover?(index)
+            raise ArgumentError, "ai_chat_branch_picker index #{index.inspect} is outside 1..#{count}"
+          end
+
+          @view = view
+          @index = index
+          @count = count
+          @previous = previous
+          @next = binding.local_variable_get(:next)
+          @method = method
+          @options = options
+        end
+
+        # One version isn't a branch, and a 1/1 on every turn is noise on every turn.
+        def render
+          return "".html_safe if @count == 1
+
+          label = AIChat.t("branch_picker.label", index: @index, count: @count, default: "Version %{index} of %{count}")
+
+          view.content_tag(:div, **@options, role: "group", "aria-label": label,
+            class: view.class_names("UnmagicAIChatBranchPicker", @options[:class])) do
+            safe_join [
+              step(@previous, :chevron_left, AIChat.t("branch_picker.previous", default: "Previous version")),
+              tag.span("#{@index}/#{@count}", class: "UnmagicAIChatBranchPicker__count", "aria-hidden": "true"),
+              step(@next, :chevron_right, AIChat.t("branch_picker.next", default: "Next version"))
+            ]
+          end
+        end
+
+        private
+
+        attr_reader :view
+
+        delegate :tag, :safe_join, to: :view, private: true
+
+        # An end with nowhere to go is a span, not a disabled link: there's no such
+        # thing, and it would be a lie to the keyboard.
+        def step(url, icon, label)
+          classes = "UnmagicAIChatBranchPicker__step"
+          glyph = Icons.svg(view, icon)
+
+          if url.nil?
+            tag.span(glyph, "aria-disabled": "true", title: label, class: classes)
+          elsif @method == :get
+            view.link_to(glyph, url, "aria-label": label, title: label, class: classes)
+          else
+            view.button_to(url, method: @method, "aria-label": label, title: label, class: classes,
+              form: { class: "UnmagicAIChatBranchPicker__form" }) { glyph }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Unmagic
+  module Components
+    module AIChat
+      # A quotation of a record the application holds, rendered from the record
+      # rather than from the model's paraphrase of it. See
+      # ActionViewHelpers#ai_chat_citation.
+      class Citation
+        def initialize(view, compact: false, **options)
+          @view = view
+          @compact = compact
+          @options = options
+          @avatar = nil
+          @who = nil
+          @when = nil
+          @quote = nil
+        end
+
+        # With no block, the gem's own avatar for whoever who: names, hidden from
+        # assistive technology since the name is read beside it.
+        def avatar(content = nil, src: nil, &block)
+          @avatar = block ? view.capture(&block) : (content || { src: src })
+          nil
+        end
+
+        def who(text)
+          @who = text
+          nil
+        end
+
+        def when(time, url: nil)
+          @when = [ time, url ]
+          nil
+        end
+
+        # Plain text, escaped, newlines kept. The quoted record can't inject markup
+        # through it, and neither can the model that chose to quote it.
+        def quote(text)
+          @quote = text.to_s
+          nil
+        end
+
+        def render
+          return "".html_safe if [ @who, @when, @quote ].all?(&:blank?)
+
+          view.content_tag(:figure, **@options,
+            class: view.class_names("UnmagicAIChatCitation", "not-prose",
+              { "UnmagicAIChatCitation--compact" => @compact }, @options[:class])) do
+            safe_join [
+              (tag.div(avatar_markup, class: "UnmagicAIChatCitation__avatar") if @avatar && !@compact),
+              tag.div(class: "UnmagicAIChatCitation__main") do
+                safe_join [ caption, (tag.blockquote(@quote, cite: @when&.last, class: "UnmagicAIChatCitation__quote") if @quote.present?) ].compact
+              end
+            ].compact
+          end
+        end
+
+        private
+
+        attr_reader :view
+
+        delegate :tag, :safe_join, to: :view, private: true
+
+        def avatar_markup
+          return @avatar unless @avatar.is_a?(Hash)
+
+          Avatar.new(view, @who, src: @avatar[:src], size: :small, "aria-hidden": "true").render
+        end
+
+        def caption
+          return if @who.blank? && @when.nil?
+
+          tag.figcaption(class: "UnmagicAIChatCitation__caption") do
+            safe_join [ (tag.span(@who, class: "UnmagicAIChatCitation__who") if @who.present?), timestamp ].compact
+          end
+        end
+
+        def timestamp
+          return unless @when
+
+          time, url = @when
+          stamp = view.local_time_tag(time)
+          url ? view.link_to(stamp, url, class: "UnmagicAIChatCitation__when") : tag.span(stamp, class: "UnmagicAIChatCitation__when")
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+module Unmagic
+  module Components
+    module AIChat
+      # The box a person types into, and the one button at the end of it. See
+      # ActionViewHelpers#ai_chat_composer.
+      class Composer
+        STATES = %i[idle running stopping waiting].freeze
+        STOP_FORM = "stop_turn"
+
+        class << self
+          # The action region on its own: Send, or Stop while a turn runs. Neither
+          # button is nested in the form it submits (both name it with form=), which
+          # is what lets a broadcast redraw this region without a form builder and
+          # without taking the half-typed draft with it.
+          def action(view, form:, state:, label: nil, stop_form: STOP_FORM)
+            AIChat.validate!("ai_chat_composer", :state, state, STATES)
+
+            view.tag.div(id: "#{form}_action", class: "UnmagicAIChatComposer__action", "aria-live": "polite") do
+              case state
+              when :idle then send_button(view, form, label)
+              when :running then stop_button(view, stop_form)
+              when :stopping then stopping_button(view)
+              when :waiting
+                view.safe_join [
+                  view.tag.span(AIChat.t("composer.waiting", default: "Waiting for your input…"),
+                    class: "UnmagicAIChatComposer__hint"),
+                  stop_button(view, stop_form)
+                ]
+              end
+            end
+          end
+
+          private
+
+          def send_button(view, form, label)
+            label ||= AIChat.t("composer.send", default: "Send")
+            view.tag.button(type: "submit", form: form, class: Button.classes(:primary)) do
+              view.safe_join [ view.tag.span(label), Icons.svg(view, :arrow_up) ]
+            end
+          end
+
+          def stop_button(view, stop_form)
+            view.tag.button(type: "submit", form: stop_form,
+              class: view.class_names(Button.classes, "UnmagicAIChatComposer__stop")) do
+              view.safe_join [ Icons.svg(view, :circle_stop), AIChat.t("composer.stop", default: "Stop") ]
+            end
+          end
+
+          # Asked, not yet granted: a button still reading Stop looks like one that
+          # didn't work, and gets pressed again.
+          def stopping_button(view)
+            view.tag.button(type: "button", disabled: true, class: Button.classes) do
+              view.safe_join [
+                Icons.svg(view, :loader_circle, class: "UnmagicAIChatSpinner"),
+                AIChat.t("composer.stopping", default: "Stopping…")
+              ]
+            end
+          end
+        end
+
+        def initialize(view, form:, field:, state: :idle, label: nil, stop_form: STOP_FORM, placeholder: nil,
+          rows: 2, **options)
+          form_id = form.options[:id]
+          raise ArgumentError, "ai_chat_composer needs its form to have an id: (the Send button names it)" if form_id.blank?
+
+          AIChat.validate!("ai_chat_composer", :state, state, STATES)
+
+          @view = view
+          @form = form
+          @form_id = form_id.to_s
+          @field = field
+          @state = state
+          @label = label
+          @stop_form = stop_form
+          @placeholder = placeholder
+          @rows = rows
+          @options = options
+          @optimistic = nil
+          @attach = nil
+          @menu = nil
+          @actions = nil
+        end
+
+        # Draw the question into the transcript the moment it's sent, under an id
+        # the form mints and the server's own row will come back with.
+        def optimistic(id:, container:)
+          @optimistic = { id: id, container: container }
+          nil
+        end
+
+        def attach(content = nil, &block)
+          @attach = block ? view.capture(&block) : content
+          nil
+        end
+
+        def menu(content = nil, &block)
+          @menu = block ? view.capture(&block) : content
+          nil
+        end
+
+        def actions(content = nil, &block)
+          @actions = block ? view.capture(&block) : content
+          nil
+        end
+
+        def render
+          box = tag.div(class: "UnmagicAIChatComposer__box") do
+            safe_join [
+              (view.uuid_input_tag(@optimistic[:id]) if @optimistic),
+              field,
+              (tag.div(@attach, class: "UnmagicAIChatComposer__attach") if @attach.present?),
+              (tag.div(@actions, class: "UnmagicAIChatComposer__actions") if @actions.present?),
+              self.class.action(view, form: @form_id, state: @state, label: @label, stop_form: @stop_form)
+            ].compact
+          end
+
+          view.content_tag(:div, **@options, class: view.class_names("UnmagicAIChatComposer", @options[:class])) do
+            safe_join [
+              @menu.presence,
+              tag.div(class: "UnmagicAIChatComposer__chips", "data-ai-chat-chips": ""),
+              (@optimistic ? optimistic_wrapper(box) : box)
+            ].compact
+          end
+        end
+
+        private
+
+        attr_reader :view
+
+        delegate :tag, :safe_join, to: :view, private: true
+
+        # The textarea is the composer's own chrome rather than a styled control:
+        # the box around it is the control and carries the focus ring, so it skips
+        # the control_class seam that would give it a border of its own. It is
+        # never disabled, whatever the state — only the button changes.
+        def field
+          label = @placeholder.presence || AIChat.t("composer.label", default: "Message")
+          value = @form.object.try(@field) if @form.object.respond_to?(@field)
+
+          Autogrow.wrap(view, view.text_area_tag(@form.field_name(@field), value,
+            id: @form.field_id(@field), rows: @rows, required: true, placeholder: @placeholder,
+            "aria-label": label, class: "UnmagicAIChatComposer__field", "data-ai-chat-composer-field": ""))
+        end
+
+        def optimistic_wrapper(box)
+          text = @form.field_name(@field)
+
+          view.content_tag("unmagic-optimistic", container: @optimistic[:container], class: "UnmagicOptimistic") do
+            safe_join [
+              box,
+              tag.template(Message.new(view, role: :user, optimistic: { id: @optimistic[:id], text: text }).render(""))
+            ]
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Unmagic
+  module Components
+    module AIChat
+      # A turn that fell over, and what it fell over on. See
+      # ActionViewHelpers#ai_chat_failure.
+      class Failure
+        def initialize(view, live: false, **options)
+          @view = view
+          @live = live
+          @options = options
+          @cause = nil
+          @details = []
+          @retry = nil
+        end
+
+        # One line naming the error, above the fold.
+        def cause(text)
+          @cause = text
+          nil
+        end
+
+        # A row inside the disclosure, for whoever is working on the assistant.
+        def detail(label, payload, language: nil)
+          @details << Payload.new(view, payload, label: label, language: language)
+          nil
+        end
+
+        def retry(content = nil, &block)
+          @retry = block ? view.capture(&block) : content
+          nil
+        end
+
+        # The sentence is always the caller's: the raw exception is for the logs,
+        # never for whoever asked. role="alert" only when streamed in, or every past
+        # failure in a reloaded transcript would be announced.
+        def render(message)
+          details = @details.map(&:render).select(&:present?)
+
+          view.content_tag(:div, **@options, role: ("alert" if @live),
+            class: view.class_names("UnmagicAIChatFailure", @options[:class])) do
+            safe_join [
+              tag.div(class: "UnmagicAIChatFailure__head") do
+                safe_join [
+                  Icons.svg(view, :circle_x, class: "UnmagicAIChatFailure__icon"),
+                  tag.div(class: "UnmagicAIChatFailure__text") do
+                    safe_join [
+                      tag.p(message, class: "UnmagicAIChatFailure__message"),
+                      (tag.p(@cause, class: "UnmagicAIChatFailure__cause") if @cause.present?)
+                    ].compact
+                  end
+                ]
+              end,
+              (disclosure(details) if details.any?),
+              (tag.div(@retry, class: "UnmagicAIChatFailure__retry") if @retry.present?)
+            ].compact
+          end
+        end
+
+        private
+
+        attr_reader :view
+
+        delegate :tag, :safe_join, to: :view, private: true
+
+        def disclosure(details)
+          tag.details(class: "UnmagicAIChatFailure__details") do
+            safe_join [
+              tag.summary(class: "UnmagicAIChatFailure__summary") do
+                safe_join [ AIChat.t("failure.details", default: "Details"), Icons.svg(view, :chevron_right, class: "UnmagicAIChatChevron") ]
+              end,
+              tag.div(safe_join(details), class: "UnmagicAIChatFailure__body")
+            ]
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+module Unmagic
+  module Components
+    module AIChat
+      # One turn: a user's bubble of plain text, or an assistant's unbubbled
+      # prose. See ActionViewHelpers#ai_chat_message.
+      class Message
+        ROLES = %i[user assistant].freeze
+
+        def initialize(view, role:, id: nil, streaming: false, final: false, optimistic: nil, **options)
+          AIChat.validate!("ai_chat_message", :role, role, ROLES)
+          if optimistic && role != :user
+            raise ArgumentError, "only a user turn can be optimistic (the composer draws what was typed)"
+          end
+          if optimistic && !(optimistic.key?(:id) && optimistic.key?(:text))
+            raise ArgumentError, "optimistic: needs id: and text:, naming the form fields to fill them from"
+          end
+
+          @view = view
+          @role = role
+          @id = id
+          @streaming = streaming
+          @final = final
+          @optimistic = optimistic
+          @options = options
+          @reasoning = nil
+          @actions = nil
+          @branches = nil
+          @attachments = nil
+        end
+
+        # A collapsed "thought process" above the body. Takes ai_chat_reasoning's
+        # options; the body is the block.
+        def reasoning(content = nil, **options, &block)
+          @reasoning = Reasoning.new(view, id: ("#{@id}_reasoning" if @id), **options)
+            .render(block ? view.capture(&block) : content)
+          nil
+        end
+
+        def actions(content = nil, &block)
+          @actions = block ? view.capture(&block) : content
+          nil
+        end
+
+        def branches(content = nil, &block)
+          @branches = block ? view.capture(&block) : content
+          nil
+        end
+
+        # Above a user's bubble, which is the order it happened in.
+        def attachments(content = nil, &block)
+          @attachments = block ? view.capture(&block) : content
+          nil
+        end
+
+        def render(body)
+          @role == :user ? user(body) : assistant(body)
+        end
+
+        private
+
+        attr_reader :view
+
+        delegate :tag, :safe_join, to: :view, private: true
+
+        def user(body)
+          data = @optimistic ? { optimistic_id: @optimistic[:id], optimistic: "" } : {}
+
+          root(data: data) do
+            safe_join [
+              role_label,
+              (tag.div(@attachments, class: "UnmagicAIChatMessage__attachments") if @attachments.present?),
+              tag.div(@optimistic ? "" : trimmed(body), class: "UnmagicAIChatMessage__bubble",
+                data: (@optimistic ? { optimistic_text: @optimistic[:text] } : {})),
+              footer
+            ].compact
+          end
+        end
+
+        # A settled turn with nothing to say is hidden rather than dropped, so a
+        # broadcast can still key on its id. A turn still streaming is never empty:
+        # it shows the thinking spinner until its first token replaces it.
+        def assistant(body)
+          blank = body.blank? && @reasoning.blank? && !@streaming
+
+          root(hidden: blank) do
+            safe_join [ role_label, @reasoning.presence, content(body), footer ].compact
+          end
+        end
+
+        # The body is always the streaming element when the turn has an id, even once
+        # it has settled: the settled render upserts over the streaming one, and the
+        # element carries the reveal across that swap.
+        def content(body)
+          body = thinking if body.blank? && @streaming && !@final
+          return tag.div(body, class: "UnmagicAIChatMessage__body UnmagicProse") unless @id
+
+          StreamingMarkdown.new(view, id: "#{@id}_content", final: @final, streaming: @streaming,
+            class: "UnmagicAIChatMessage__body UnmagicProse").render(body)
+        end
+
+        # The bubble keeps the line breaks that were typed, so a block's own leading
+        # newline and indentation would show as a blank first line. Trimming the ends
+        # can't make markup, so already-escaped content stays safe.
+        def trimmed(body)
+          return body.to_s.strip unless body.respond_to?(:html_safe?) && body.html_safe?
+
+          body.to_str.strip.html_safe # rubocop:disable Rails/OutputSafety -- escaped content, only whitespace removed
+        end
+
+        def thinking
+          tag.span(class: "UnmagicAIChatMessage__thinking") do
+            safe_join [
+              Icons.svg(view, :loader_circle, class: "UnmagicAIChatSpinner"),
+              tag.span(AIChat.t("message.thinking", default: "Thinking"), class: "UnmagicVisuallyHidden")
+            ]
+          end
+        end
+
+        def footer
+          return if @actions.blank? && @branches.blank?
+
+          tag.div(safe_join([ @branches.presence, @actions.presence ].compact), class: "UnmagicAIChatMessage__footer")
+        end
+
+        def role_label
+          default = @role == :user ? "You said" : "Assistant said"
+          tag.span(AIChat.t("message.#{@role}", default: default), class: "UnmagicVisuallyHidden")
+        end
+
+        def root(hidden: false, data: {}, &block)
+          view.content_tag(:div, **@options,
+            id: (@id unless @optimistic),
+            hidden: hidden,
+            data: data.merge(@options[:data] || {}),
+            class: view.class_names("UnmagicAIChatMessage", "UnmagicAIChatMessage--#{@role}", @options[:class]), &block)
+        end
+      end
+    end
+  end
+end