chats 0.1.1 → 0.6.2

data/app/controllers/chats/messages_controller.rb

@@ -6,20 +6,13 @@ module Chats
     before_action :set_conversation
     before_action :set_message, only: %i[show update destroy]
     before_action :require_ownership!, only: %i[update destroy]
+    # A locked conversation refuses every write, not just new messages.
+    # `create` is NOT in this list: its own validation produces the same
+    # response, and going through the model keeps the "locked since you
+    # opened the composer" race in one place.
+    before_action :refuse_when_locked!, only: %i[update destroy]
 
-    # Per-sender send throttle via Rails 8's built-in controller rate
-    # limiting (https://api.rubyonrails.org/classes/ActionController/RateLimiting.html).
-    # Feature-detected so the gem still loads on Rails 7.1 (where this is
-    # simply not enforced). Keyed by messager, not IP — one abusive account
-    # behind a corporate NAT must not silence the rest.
-    if respond_to?(:rate_limit) && Chats.config.send_rate_limit
-      rate_limit(
-        **Chats.config.send_rate_limit,
-        only: :create,
-        by: -> { send(Chats.config.current_messager_method)&.to_gid&.to_s || request.remote_ip },
-        with: -> { head :too_many_requests }
-      )
-    end
+    include Chats::SendRateLimited
 
     # A single bubble, re-rendered. Exists for one delightful reason: it's
     # the "cancel edit" target — replacing the inline edit form back with the
@@ -40,6 +33,17 @@ module Chats
           format.turbo_stream
           format.html { redirect_to conversation_path(@conversation) }
         end
+      elsif locked?
+        # The subject closed the conversation (Chats::ChatSubject#
+        # chat_locked?) — possibly while this composer sat open. Swap the
+        # composer for the locked notice instead of flashing an error at
+        # someone whose screen is now lying to them. 422, never a raise.
+        respond_to do |format|
+          format.turbo_stream { render :locked, status: :unprocessable_entity }
+          format.html do
+            redirect_to conversation_path(@conversation), alert: @conversation.locked_notice
+          end
+        end
       else
         respond_to do |format|
           format.turbo_stream { render :errors, status: :unprocessable_entity }
@@ -85,6 +89,24 @@ module Chats
       @conversation = find_conversation(params[:conversation_id])
     end
 
+    # Did THIS save fail because the conversation is locked? Reads the error
+    # type, not the conversation, so a message that also failed validation
+    # for another reason still reports that reason.
+    def locked?
+      @message.errors.of_kind?(:base, :locked)
+    end
+
+    # Gate the action, explain it in place: the composer becomes the locked
+    # notice (422), or a plain redirect carrying the notice without Turbo.
+    def refuse_when_locked!
+      return unless @conversation.locked?
+
+      respond_to do |format|
+        format.turbo_stream { render :locked, status: :unprocessable_entity }
+        format.html { redirect_to conversation_path(@conversation), alert: @conversation.locked_notice }
+      end
+    end
+
     def set_message
       @message = @conversation.messages.find(params[:id])
     end

data/app/controllers/chats/reactions_controller.rb

@@ -9,6 +9,7 @@ module Chats
     def create
       conversation = find_conversation(params[:conversation_id])
       message = conversation.messages.find(params[:message_id])
+      return refuse_when_locked(conversation) if conversation.locked?
 
       Chats::Reaction.toggle!(
         message: message,
@@ -29,5 +30,18 @@ module Chats
     rescue ActiveRecord::RecordInvalid
       head :unprocessable_entity
     end
+
+    private
+
+    # Same shape as the messages controller: swap the composer for the
+    # reason, 422, never an exception page.
+    def refuse_when_locked(conversation)
+      @conversation = conversation
+
+      respond_to do |format|
+        format.turbo_stream { render "chats/messages/locked", status: :unprocessable_entity }
+        format.html { redirect_to conversation_path(conversation), alert: conversation.locked_notice }
+      end
+    end
   end
 end

data/app/helpers/chats/engine_helper.rb

@@ -5,6 +5,19 @@ module Chats
   # HOST app's views (mixed into ActionView via the engine's on_load hook,
   # the same pattern the moderate gem uses for `report_link`).
   module EngineHelper
+    # Every slot the bundled views render, and the whole list of them. A
+    # host drops `app/views/chats/slots/_<name>.html.erb` in and it appears;
+    # a name that isn't here renders nothing.
+    SLOTS = %w[
+      inbox_top
+      inbox_empty
+      conversation_header_actions
+      composer_actions
+      locked_composer
+      message_meta
+      dock_panel_footer
+    ].freeze
+
     # The "message this person" affordance for host pages — a listing, a
     # profile, an order. Renders nothing when there's no viewer, the viewer
     # IS the target, or policy/blocks forbid the pair, so it's always safe
@@ -12,18 +25,24 @@ module Chats
     #
     #   <%= chat_button_to @driver, about: @ride, label: "Chat with driver" %>
     #
+    # `dock: true` opens the conversation in a floating window of the
+    # messaging dock (`chats_dock`) instead of navigating to it. It belongs
+    # with `chats_dock` on the same page: without the dock the button's Turbo
+    # Stream has nowhere to land and nothing happens.
+    #
     # The recipient/subject travel as SIGNED GlobalIDs (purpose-scoped,
     # minted here, verified in Chats::ConversationsController#create), so the
     # endpoint never trusts raw polymorphic params. `expires_in: nil` because
     # these buttons sit on long-lived pages — the default 1-month sgid expiry
     # would quietly break stale tabs.
-    def chat_button_to(other, about: nil, label: nil, **html_options)
+    def chat_button_to(other, about: nil, label: nil, dock: false, **html_options)
       viewer = chats_viewer
       return if viewer.nil? || other.nil? || viewer == other
       return unless Chats.can_message?(viewer, other)
 
       params = { recipient_sgid: other.to_sgid(expires_in: nil, for: :chats_recipient).to_s }
       params[:subject_sgid] = about.to_sgid(expires_in: nil, for: :chats_subject).to_s if about
+      params[:dock] = 1 if dock
 
       button_to(
         label || I18n.t("chats.buttons.chat"),
@@ -38,13 +57,97 @@ module Chats
     # tab docks). Subscribes to the messager's badge stream so it updates in
     # real time without refreshing the page it sits on (see
     # Chats::Broadcasts for why badges get their own stream).
+    #
+    # The viewer's own badge also catches up on updates its stream missed
+    # (the chats--unread-badge controller asks GET /badge on a reconnect, on
+    # a return to a hidden page, on a restored page). Its wrapper is
+    # `display: contents` in chats.css, so it changes no layout.
     def chats_unread_badge(messager = chats_viewer)
       return if messager.nil?
 
-      safe_join([
-                  turbo_stream_from(messager, :chats_badge),
-                  render(partial: "chats/shared/unread_badge", locals: { count: messager.unread_chats_count })
-                ])
+      badge = safe_join([
+                          turbo_stream_from(messager, :chats_badge),
+                          render(partial: "chats/shared/unread_badge", locals: { count: messager.unread_chats_count })
+                        ])
+      return badge unless messager == chats_viewer
+
+      tag.span(badge, class: "chats-unread-badge-live",
+                      data: { controller: "chats--unread-badge",
+                              "chats--unread-badge-url-value": chats_routes.badge_conversations_path })
+    end
+
+    # The messaging dock, LinkedIn / Steam style: a bar in the bottom-right
+    # corner with the unread badge, a panel of recent conversations, and
+    # floating conversation windows. One line in the host's layout:
+    #
+    #   <%= chats_dock %>
+    #
+    # Renders nothing for a signed-out visitor, and nothing on the engine's
+    # own pages (the inbox, a thread): those already ARE the messaging UI,
+    # and a window there would duplicate the thread's DOM ids the live
+    # streams address. The dock is permanent across Turbo visits, so the
+    # server can't take it away on the next page: it also hides ITSELF on
+    # any page carrying `data-chats-dock-hide` (the engine's pages do; put
+    # it on your own messaging pages). `everywhere: true` renders it on the
+    # engine's pages and ignores data-chats-dock-hide (it still never opens
+    # a window for a conversation the page itself shows).
+    #
+    #   windows:   how many windows may be open at once (3, and never more
+    #              than fit beside the panel: 2 at 1280px, 1 at 768px)
+    #   recent:    how many conversations the panel lists (10)
+    #   launcher:  false drops the phone's floating button, for a host that
+    #              opens the sheet from its own nav (see chats_dock_toggle)
+    def chats_dock(windows: 3, recent: 10, launcher: true, everywhere: false)
+      viewer = chats_viewer
+      return if viewer.nil?
+      return if chats_engine_page? && !everywhere
+
+      render(partial: "chats/dock/dock",
+             locals: { viewer: viewer, windows: windows, recent: recent, launcher: launcher, everywhere: everywhere })
+    end
+
+    # The data that makes ANY link to a conversation — a recent-list row, a
+    # host's own link — open that conversation's dock window instead of
+    # navigating, when a dock is on the page. The link stays a real link: a
+    # modified click, a page without the dock, or no JavaScript navigates.
+    #
+    #   <%= link_to "Chat", chats.conversation_path(c), data: chats_dock_opener(c) %>
+    def chats_dock_opener(conversation)
+      { chats_dock_conversation_id: conversation.id }
+    end
+
+    # The data that makes a host's own Messages link open the dock's panel
+    # (the full-screen sheet on a phone) instead of navigating, when a dock
+    # is on the page. Pair it with `chats_dock(launcher: false)` to replace
+    # the phone's floating button with your nav's. Without the dock, or
+    # without JavaScript, the link goes where its href says.
+    #
+    #   <%= link_to "Messages", chats.conversations_path, data: chats_dock_toggle %>
+    def chats_dock_toggle
+      { chats_dock_toggle: true }
+    end
+
+    # The CLDR plural categories JavaScript's Intl.PluralRules answers with.
+    PLURAL_CATEGORIES = %i[zero one two few many other].freeze
+
+    # Every plural form of +key+ the current locale provides, for client-side
+    # pluralization ({ one: "…", few: "…", other: "…" }). The gem ships
+    # one/other; a host adds the forms its languages need (Polish few/many,
+    # Arabic zero/two…) in its own locale files. Empty when the key is
+    # missing, never a "translation missing" string.
+    def chats_plural_forms(key)
+      forms = I18n.t(key, default: {})
+      forms.is_a?(Hash) ? forms.slice(*PLURAL_CATEGORIES) : {}
+    end
+
+    # Whether +viewer+ muted +conversation+, read from the preloaded seats
+    # (the inbox loads them), so a row costs no query for it.
+    def chats_muted?(conversation, viewer)
+      return false if viewer.nil?
+
+      conversation.participants.any? do |seat|
+        seat.muted? && seat.messager_type == viewer.class.polymorphic_name && seat.messager_id == viewer.id
+      end
     end
 
     # An avatar for any messager: whatever `config.messager_avatar` returns
@@ -117,8 +220,7 @@ module Chats
     # initials disc from the group name.
     def chats_conversation_avatar(conversation, viewer)
       if conversation.direct?
-        other = conversation.other_participants(viewer).first
-        chats_messager_avatar(other&.messager)
+        chats_messager_avatar(conversation.counterpart_for(viewer))
       else
         initials = conversation.title_for(viewer).split.first(2).map { |word| word[0] }.join.upcase
         tag.span(initials.presence || "👥", class: "chats-avatar chats-avatar--initials chats-avatar--group",
@@ -126,6 +228,122 @@ module Chats
       end
     end
 
+    # --- Slots ----------------------------------------------------------------
+    #
+    # Named extension points the bundled views render WHEN a partial exists
+    # at `chats/slots/_<name>`. Hosts (and engines mounted on top of chats,
+    # like support_desk) drop a file in and it appears; nobody has to eject
+    # a whole screen to add one row or one button. Absent slots cost one
+    # memoized template lookup and render nothing.
+    #
+    #   app/views/chats/slots/_inbox_top.html.erb
+    #
+    # The slots: inbox_top, inbox_empty, conversation_header_actions,
+    # composer_actions, locked_composer, message_meta, dock_panel_footer.
+    def chats_slot(name, **locals)
+      return unless chats_slot?(name)
+
+      render(partial: "chats/slots/#{name}", locals: locals)
+    end
+
+    # Whether a slot partial exists. Memoized per view instance, so a slot
+    # rendered inside a collection costs ONE lookup per request, not one per
+    # row. Anything outside SLOTS is ignored rather than looked up: the slot
+    # names are a contract, and a typo should render nothing instead of
+    # quietly becoming a new extension point nobody documented.
+    def chats_slot?(name)
+      key = name.to_s
+      return false unless Chats::EngineHelper::SLOTS.include?(key)
+
+      @chats_slots ||= {}
+      return @chats_slots[key] if @chats_slots.key?(key)
+
+      @chats_slots[key] = lookup_context.exists?("chats/slots/#{key}", [], true)
+    end
+
+    # --- Messager display -----------------------------------------------------
+
+    # Whether block/report affordances apply to this messager. False for
+    # `acts_as_messager blockable: false` (a support desk, a bot) — the
+    # bundled views hide the affordance instead of asking hosts to branch on
+    # class.
+    def chats_blockable?(messager)
+      Chats.blockable?(messager)
+    end
+
+    # A messager's profile URL per `config.messager_url`, or nil.
+    def chats_messager_url(messager)
+      Chats.messager_url_for(messager)
+    end
+
+    # A messager's name, linked to their profile when `config.messager_url`
+    # gives one and plain text when it doesn't — so the gem never renders a
+    # dead anchor or assumes a `user_path` exists.
+    def chats_messager_name(messager, css_class: nil)
+      name = Chats.display_name_for(messager)
+      url = chats_messager_url(messager)
+
+      url.present? ? link_to(name, url, class: css_class) : tag.span(name, class: css_class)
+    end
+
+    # The "official account" mark for a messager declared `acts_as_messager
+    # verified: true`, and NIL for everyone else — so any view, bundled or
+    # host, can drop it next to a name unconditionally:
+    #
+    #   <%= chats_messager_name(author) %><%= chats_verified_badge(author) %>
+    #
+    # `config.verified_badge` swaps the glyph for the host's own design
+    # system; the default renders `chats/shared/_verified_badge`, whose
+    # colour is the `--chats-verified` CSS variable.
+    def chats_verified_badge(messager)
+      return unless Chats.verified?(messager)
+
+      custom = Chats.config.verified_badge
+      return custom.call(messager) if custom
+
+      render(partial: "chats/shared/verified_badge", locals: { messager: messager })
+    end
+
+    # The signature line under a signed message ("— Lucía G."), or nil.
+    def chats_message_signature(message)
+      Chats.message_signature_for(message)
+    end
+
+    # --- Grouped inbox rows ---------------------------------------------------
+
+    # Where a stacked inbox row goes: straight to the thread when the stack
+    # holds exactly one conversation, otherwise to the stack itself.
+    def chats_group_path(group)
+      return chats_routes.conversation_path(group.conversation) if group.single?
+
+      chats_group_path_for(group.messager)
+    end
+
+    # The stack list for a messager: the host's `group_path:` callable when
+    # `acts_as_messager` declared one (support_desk points it at its own
+    # screen), else chats' own filtered inbox.
+    def chats_group_path_for(messager)
+      custom = messager.class.try(:chat_group_path)
+      path = custom&.call(chats_viewer)
+
+      path.presence || chats_routes.conversations_path(with: Chats.inbox_with_sgid(messager))
+    end
+
+    # The messaging page's title: the inbox's, or +conversation+'s.
+    # `config.page_title` when the host sets one, else the localized
+    # `chats.page_title.*`. ONE source for both ways a conversation opens:
+    # the bundled pages hand it to `content_for :title` on a full visit, and
+    # the two-pane page's pane carries it (`data-title`) for chats--split to
+    # give the tab when a row opens it, since Turbo leaves <head> alone then.
+    def chats_page_title(conversation = nil)
+      viewer = chats_current_messager
+      custom = Chats.config.page_title&.call(conversation, viewer)
+      return custom.to_s if custom.present?
+      return t("chats.page_title.inbox") unless conversation
+
+      t("chats.page_title.conversation", name: conversation.title_for(viewer))
+    end
+
     # The gem's bundled stylesheet (CSS-variable themed — see chats.css).
     # Called from the engine's own views; hosts that eject + restyle the
     # views with their own framework simply don't include it.
@@ -163,6 +381,11 @@ module Chats
       respond_to?(method_name) ? send(method_name) : nil
     end
 
+    # Whether this view is one of the engine's own screens.
+    def chats_engine_page?
+      respond_to?(:controller) && controller.is_a?(Chats::ApplicationController)
+    end
+
     # Active Storage routes are drawn on the host app, not on this isolated
     # engine. A bare `image_tag variant` is fine in normal host views, but
     # inside engine views it asks the engine route set to polymorphically

data/app/javascript/chats/composer_controller.js

@@ -76,8 +76,11 @@ export default class extends Controller {
   // are disabled while editing (edits are body-only by design).
 
   beginEdit(event) {
-    const { id, body } = event.detail || {}
+    const { id, body, thread } = event.detail || {}
     if (!id || !this.hasInputTarget) return
+    // Several threads can share a page (the dock's windows): only the
+    // composer of the thread the message lives in edits it.
+    if (thread && !thread.contains(this.element)) return
 
     this.createAction ||= this.element.action
     this.element.action = `${this.createAction}/${id}`
@@ -112,6 +115,16 @@ export default class extends Controller {
     this.inputTarget.setSelectionRange(this.inputTarget.value.length, this.inputTarget.value.length)
   }
 
+  // Escape while editing cancels the edit, and only that: the dock (if the
+  // composer is in one of its windows) sees the event handled and leaves
+  // the window alone.
+  escape(event) {
+    if (!this.editing) return
+
+    event.preventDefault()
+    this.cancelEdit()
+  }
+
   cancelEdit(event) {
     event?.preventDefault()
     this.exitEdit()