chats 0.2.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c51ebc5c0e2da96363bb5b2e85d9a9c2a91e41f7ddb9d351ff10001654a48325
-  data.tar.gz: a06cde14d3953972e7061b2950b7a52c696f4292e25a2a91c9c7bb6ce7d269cb
+  metadata.gz: a0e116038dc60b864f51b65edb4f5b879305da0cabef4c8aa2db73e23464c674
+  data.tar.gz: '0179846f4e07b60cb1d07a9d50909a836456794636da584a6178843f0d39f8ff'
 SHA512:
-  metadata.gz: 5d23c31395edb382ec05fc6b7478a4e219b1878dc29f67092451101ef720bf2df556ae92976384665c0e108ca4607557ed9d1badf0af9357143182f1fdb57e6d
-  data.tar.gz: 3f02985c90410059af142a03fc3a3298540f71fb05d9b46991f39ea22999bfab64738f86beb92db7355e98c68e7962c2b6e79925335cf409d67842c1b1a7a5eb
+  metadata.gz: 1c3dc69a2bdba881bc7fc6543bc768885797e121f8d23b619e72a578cb3e7c6555c9b19c6dde52bec3085efe52d98e40dc277af932015bb08f65a7aaf67ca5c1
+  data.tar.gz: 4ab1a0ae08133bbe02240e12b1efa8efccb6dfe5bfbf53a1662acce5542a74ec4bb3adfc1eeaf10e6db94a961b17dc81523e8b2ac5044fa02ff22bba6904e303

data/CHANGELOG.md

@@ -4,6 +4,73 @@ All notable changes to this project are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.1] - 2026-09-16
+
+### Fixed
+- **The verified badge was a star, not a check.** 0.3.0 shipped a
+  five-pointed star as the "official account" mark, copied from a host icon
+  that was named `verified_badge` but drawn as a star. A star reads as
+  "favourite" or "rated", not "this account is really us", and at 14px a
+  solid star and a solid rosette are the same blob. It is now heroicons
+  `check-badge`: a scalloped rosette with a tick knocked out of it, which
+  is the mark people already read as verified. `fill-rule="evenodd"` is
+  what knocks the tick out — without it the rosette fills solid.
+
+## [0.3.0] - 2026-09-16
+
+Official accounts. Some counterparts are not people you met — they are a
+support desk, an organization, a shop, a brand — and a person should be able
+to tell at a glance. **Nothing changes until a model says so**: 0.2.x
+installs upgrade by bumping the gem, with no migration and no new
+configuration.
+
+### Added
+- **`acts_as_messager verified: true`.** A messager declares itself an
+  OFFICIAL account, and every bundled view that shows its name marks it: the
+  inbox row, the stacked inbox row, and the thread header. `Klass.
+  chat_verified?` is the class predicate and `Chats.verified?(messager)`
+  reads it duck-typed — false for a plain model, a nil, a non-messager — so
+  hosts can badge their own screens without a class check. The option is
+  independent of the headless ones: a desk is usually headless *and*
+  official, a shop is usually official and nothing else. Unlike its boolean
+  neighbours it refuses to coerce — `verified: "false"` raises
+  `Chats::ConfigurationError` at boot rather than quietly verifying an
+  account, because a badge is a trust claim and not a display preference.
+- **The badge itself**, `chats/shared/_verified_badge` — an inline rosette
+  that sizes itself from the text it sits beside. It is an image with a
+  name, not decoration: `role="img"` plus a localized label
+  (`chats.verified.label`, "Official account" / "Cuenta oficial"), and the
+  glyph is `aria-hidden` so a screen reader never announces it twice.
+- **`config.verified_badge`** `->(messager) { markup }` — swap the glyph for
+  your design system's own, vary it per messager, or return nil for no badge.
+  The default (nil) renders the gem's rosette.
+- **`--chats-verified`** (`#0284c7`) — the badge colour, a CSS custom
+  property like the rest of the gem's theming, inherited through
+  `currentColor`. Not the familiar `#1d9bf0`: the badge is a meaningful
+  graphic, so WCAG 1.4.11 asks 3:1 of it, and `#1d9bf0` is 3.00:1 on
+  `--chats-bg` but 2.73:1 on `--chats-surface` — the inbox row's HOVER
+  background, so it failed exactly while somebody was pointing at it.
+  `#0284c7` clears the bar on both grounds and on a dark one, so a host
+  inverting the palette inherits a badge that still passes.
+  `test/verified_badge_contrast_test.rb` computes it rather than trusting a
+  swatch.
+- **`chats_verified_badge(messager)`** — the view helper behind all three
+  surfaces, available in host views too. Nil for everyone who hasn't
+  declared `verified: true`, so it is safe to drop next to any name
+  unconditionally.
+- **`Chats::Conversation#counterpart_for(viewer)`** — the other messager in a
+  direct thread (nil for a group, and for a thread whose other seat left).
+  The title, the avatar and the badge on an inbox row now resolve the
+  counterpart through this one method, memoized per viewer, so a row that
+  cost one query in 0.2.0 still costs one.
+
+### Changed
+- The bundled inbox row wraps its title in `.chats-row__name`, and the thread
+  header wraps its name in `.chats-thread__name`, so a long name still
+  ellipsizes while the badge beside it stays visible. If you ejected these
+  views with `rails generate chats:views`, your copies are untouched and keep
+  working; re-run the generator only if you want the badge.
+
 ## [0.2.0] - 2026-09-16
 
 The release that makes `chats` a foundation other products can be built on:

data/README.md

@@ -97,7 +97,7 @@ Five concepts, namespaced and polymorphic from day one (no hard `User` coupling
 - **`Chats::Participant`** — a messager's seat in a conversation. Holds role, read horizon, mute, soft-leave, and notification bookkeeping.
 - **`Chats::Message`** — `text` (human) or `system` (posted by your app). Soft-deletes to a tombstone. Attachments via ActiveStorage.
 - **`Chats::Reaction`** — one row per (message, reactor, emoji); tap-to-toggle, race-safe.
-- **Any model with `acts_as_messager`** — users, organizations, support desks, bots: participants and senders are polymorphic. A messager that is not a person declares it (`notifications: false, blockable: false, inbox: :grouped`) and the gem stops treating it like one. See [`support_desk`](https://github.com/rameerez/support_desk) for the worked example.
+- **Any model with `acts_as_messager`** — users, organizations, support desks, bots: participants and senders are polymorphic. A messager that is not a person declares it (`notifications: false, blockable: false, inbox: :grouped`) and the gem stops treating it like one; an official one (`verified: true`) gets the badge everywhere its name appears. See [`support_desk`](https://github.com/rameerez/support_desk) for the worked example.
 
 Two deliberate design decisions worth knowing:
 
@@ -269,6 +269,53 @@ end
 
 That's the whole point of the option: **your notifiers and views stop asking `is_a?(User)`**. The predicates are on the class (`SupportDesk.chat_notifications?`, `.chat_blockable?`, `.chat_inbox_mode`) and duck-typed everywhere the gem reads them, so an ordinary `acts_as_messager` model behaves exactly as it always did.
 
+## ✅ Official accounts: the verified badge
+
+A support desk, an organization, a shop or a brand is an **official** counterpart, and the person talking to it should see that at a glance — the blue tick everyone already reads. Say it once, on the model, next to the other `acts_as_messager` options:
+
+```ruby
+class SupportDesk < ApplicationRecord
+  acts_as_messager verified: true
+end
+```
+
+Every bundled view that shows a messager's name now marks it: the inbox row, the stacked inbox row, and the thread header. The mark is an image with a name, not decoration — `role="img"` plus a localized label (`chats.verified.label`: "Official account" / "Cuenta oficial"), with the glyph itself `aria-hidden` so nothing is announced twice.
+
+`verified:` is **independent of everything else**. A desk is usually headless *and* official; a shop is usually official and completely ordinary otherwise. Combine what you need:
+
+```ruby
+acts_as_messager verified: true                                   # official, notifiable, blockable
+acts_as_messager notifications: false, inbox: :grouped, verified: true  # an official desk
+```
+
+It is the one boolean option that **refuses to coerce**, and that is deliberate — please don't "fix" it into a `!!` to match its neighbours. `notifications:` and `blockable:` coerce, so `notifications: "false"` quietly means `true`; on those two the damage is a stray notification. Here the same slip would hand an account the mark that tells people it is really us, and the strings that reach a model declaration come from exactly the places that produce `"false"`: an ENV var, a YAML round-trip, a settings row. So `verified: "false"` raises `Chats::ConfigurationError` at boot, where somebody is looking, rather than shipping a verified impostor nobody notices.
+
+Read it anywhere you render your own screens — duck-typed, never a class check:
+
+```ruby
+SupportDesk.chat_verified?       # the class predicate
+Chats.verified?(messager)        # false for a plain model, a nil, a non-messager
+chats_verified_badge(messager)   # the view helper: markup, or nil for everyone else
+```
+
+**Change the colour** with one CSS variable (the badge inherits it through `currentColor`):
+
+```css
+:root { --chats-verified: #0284c7; }
+```
+
+The default is `#0284c7` rather than the more familiar `#1d9bf0`. The badge is a meaningful graphic, so it owes 3:1 against what it sits on (WCAG 1.4.11), and `#1d9bf0` is 3.00:1 on the page but **2.73:1 on `--chats-surface`** — the inbox row's hover background, so it failed exactly while someone was pointing at it. `#0284c7` clears the bar on both (4.10 and 3.72) and on a dark ground too (4.33 on `#111827`), so inverting the palette doesn't leave you with a badge you have to remember to fix. If you override it, `test/verified_badge_contrast_test.rb` shows the arithmetic worth repeating.
+
+**Change the glyph** — to your design system's icon, a per-messager mark, or nothing — with a callable that gets the messager and returns html_safe markup (or `nil` for no badge):
+
+```ruby
+config.verified_badge = lambda do |messager|
+  ApplicationController.helpers.image_tag("official.svg", class: "badge", alt: "Official account")
+end
+```
+
+Or eject `app/views/chats/shared/_verified_badge.html.erb` with `rails generate chats:views` and rewrite it.
+
 ## 🗂️ Grouped inbox rows
 
 With `inbox: :grouped`, every direct conversation a viewer has with that messager folds into a single inbox row — a stack:
@@ -368,6 +415,7 @@ The bundled UI is intentionally framework-free (semantic `chats-*` classes + one
 :root {
   --chats-accent: #facc15;           /* own bubbles, send button, badges */
   --chats-accent-contrast: #111827;
+  --chats-verified: #0284c7;         /* the "official account" badge */
 }
 ```
 
@@ -429,6 +477,7 @@ Chats.configure do |config|
   config.messager_avatar = ->(messager) { messager.avatar }  # URL/attachment/variant or nil
   config.messager_url = ->(messager) { nil }                 # nil ⇒ names render as plain text
   config.message_signature = nil                             # ->(message) { } for signed bubbles
+  config.verified_badge = nil                                # ->(messager) { markup } for verified: true
 end
 ```
 
@@ -445,10 +494,12 @@ alice.chats                                   # inbox relation, newest first
 alice.unread_chats_count                      # conversations with unread messages
 alice.message!(bob, "hi", author: lucia)      # written by lucia, sent from alice's seat
 Chats::Inbox.for(alice)                       # [Conversation | InboxGroup] + #unread_count
+Chats.verified?(desk)                         # official account? (acts_as_messager verified: true)
 
 # Conversations
 conversation.participant?(user)               # active membership
 conversation.other_participants(user)
+conversation.counterpart_for(viewer)          # the other messager (nil for groups)
 conversation.title_for(viewer)                # counterpart name / group title
 conversation.subject_label                    # "Madrid → Barcelona"
 conversation.unread_count_for(user)

data/app/assets/stylesheets/chats.css

@@ -11,6 +11,7 @@
  *   :root {
  *     --chats-accent: #facc15;          /\* brand color: own bubbles, send button *\/
  *     --chats-accent-contrast: #111827; /\* text on top of the accent *\/
+ *     --chats-verified: #0284c7;        /\* the "official account" badge *\/
  *   }
  *
  * Want a completely different look? `rails g chats:views` ejects the
@@ -26,6 +27,7 @@
   --chats-border: rgba(0, 0, 0, 0.08);
   --chats-text: #111827;
   --chats-text-muted: #6b7280;
+  --chats-verified: #0284c7;
   --chats-bubble-bg: #f3f4f6;
   --chats-bubble-text: #111827;
   --chats-radius: 1.1rem;
@@ -79,6 +81,12 @@
   justify-content: space-between;
   gap: 0.75rem;
 }
+.chats-row__name {
+  display: flex;
+  align-items: center;
+  gap: 0.25rem;
+  min-width: 0;
+}
 .chats-row__title {
   font-weight: 650;
   white-space: nowrap;
@@ -147,6 +155,34 @@
   user-select: none;
 }
 
+/* --- Verified messagers ------------------------------------------------------
+ *
+ * The "official account" mark (`acts_as_messager verified: true`). It sizes
+ * itself from the text it sits next to, so it reads right in an inbox row and
+ * in the thread header without either one hard-coding a pixel value. Recolour
+ * it with --chats-verified; replace the glyph with config.verified_badge.
+ *
+ * On #0284c7 rather than the more familiar #1d9bf0: the badge is a meaningful
+ * graphic, so WCAG 1.4.11 asks for 3:1 against what it sits on, and #1d9bf0
+ * is 3.00:1 on --chats-bg but only 2.73:1 on --chats-surface — which is the
+ * row hover background, so the mark failed exactly while someone was pointing
+ * at it. #0284c7 clears 3:1 on both (4.10 and 3.72) and on a dark ground too
+ * (4.33 on #111827), so a host that inverts the palette inherits a badge that
+ * still passes instead of one it has to remember to fix. Pinned by
+ * test/verified_badge_contrast_test.rb.
+ */
+.chats-verified {
+  flex-shrink: 0;
+  display: inline-flex;
+  align-items: center;
+  color: var(--chats-verified);
+  line-height: 0;
+}
+.chats-verified__glyph {
+  width: 1em;
+  height: 1em;
+}
+
 /* --- Thread -------------------------------------------------------------------- */
 
 .chats-thread {
@@ -179,6 +215,12 @@
   font-size: 1rem;
   font-weight: 750;
   margin: 0;
+  display: flex;
+  align-items: center;
+  gap: 0.25rem;
+  min-width: 0;
+}
+.chats-thread__name {
   white-space: nowrap;
   overflow: hidden;
   text-overflow: ellipsis;

data/app/controllers/chats/conversations_controller.rb

@@ -189,10 +189,7 @@ module Chats
     def chats_counterpart
       return @chats_counterpart if defined?(@chats_counterpart)
 
-      @chats_counterpart =
-        if @conversation&.direct?
-          @conversation.other_participants(chats_current_messager).includes(:messager).first&.messager
-        end
+      @chats_counterpart = @conversation&.counterpart_for(chats_current_messager)
     end
   end
 end

data/app/helpers/chats/engine_helper.rb

@@ -128,8 +128,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",
@@ -195,6 +194,24 @@ module Chats
       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)

data/app/views/chats/conversations/_conversation_row.html.erb

@@ -7,7 +7,13 @@
 
     <span class="chats-row__body">
       <span class="chats-row__top">
-        <span class="chats-row__title"><%= conversation.title_for(viewer) %></span>
+        <%# The badge sits OUTSIDE the ellipsizing title so a long name
+            truncates without ever eating the mark. Nil for an ordinary
+            counterpart and for groups, so the row is unchanged. %>
+        <span class="chats-row__name">
+          <span class="chats-row__title"><%= conversation.title_for(viewer) %></span>
+          <%= chats_verified_badge(conversation.counterpart_for(viewer)) %>
+        </span>
         <time class="chats-row__time" datetime="<%= conversation.last_message_at&.iso8601 %>">
           <%= chats_timestamp(conversation.last_message_at) %>
         </time>

data/app/views/chats/conversations/_group.html.erb

@@ -13,7 +13,10 @@
 
     <span class="chats-row__body">
       <span class="chats-row__top">
-        <span class="chats-row__title"><%= group.title_for(viewer) %></span>
+        <span class="chats-row__name">
+          <span class="chats-row__title"><%= group.title_for(viewer) %></span>
+          <%= chats_verified_badge(group.messager) %>
+        </span>
         <time class="chats-row__time" datetime="<%= group.last_message_at&.iso8601 %>">
           <%= chats_timestamp(group.last_message_at) %>
         </time>

data/app/views/chats/conversations/show.html.erb

@@ -44,11 +44,15 @@
     <% end %>
 
     <div class="chats-thread__identity">
+      <%# Both arms wrap the name in .chats-thread__name: the <h1> is a flex
+          row (the badge is its second child), and only a real element can
+          carry the ellipsis. %>
       <h1 class="chats-thread__title">
         <% if chats_counterpart %>
-          <%= chats_messager_name(chats_counterpart) %>
+          <%= chats_messager_name(chats_counterpart, css_class: "chats-thread__name") %>
+          <%= chats_verified_badge(chats_counterpart) %>
         <% else %>
-          <%= @conversation.title_for(chats_current_messager) %>
+          <span class="chats-thread__name"><%= @conversation.title_for(chats_current_messager) %></span>
         <% end %>
       </h1>
       <% if @conversation.subject_label %>

data/app/views/chats/shared/_verified_badge.html.erb

@@ -0,0 +1,32 @@
+<%# The "official account" mark. Rendered next to a verified messager's name
+    (`acts_as_messager verified: true`) in every bundled view that shows one:
+    the inbox row, the stacked row and the thread header.
+
+    It is an IMAGE with a name, not decoration: the wrapper carries
+    role="img" plus the localized label, so a screen reader announces
+    "Cuenta oficial" / "Official account" where a sighted person sees the
+    badge, and the glyph itself is aria-hidden so it is never read twice.
+
+    The glyph is heroicons `check-badge` (24/solid): a scalloped rosette
+    with a TICK knocked out of it, which is the mark people already read as
+    "verified". It is deliberately not a plain star — a star says "favourite"
+    or "rated", and at 14px a solid star and a solid rosette are the same
+    blob, so the tick is the whole point. `fill-rule: evenodd` is what knocks
+    the tick out; without it the rosette fills solid and the mark is a blob.
+
+    Colour comes from the --chats-verified CSS variable (see chats.css) via
+    `fill: currentColor` — override that variable, or swap this whole partial
+    with `config.verified_badge`. %>
+<span class="chats-verified"
+      role="img"
+      title="<%= t("chats.verified.label") %>"
+      aria-label="<%= t("chats.verified.label") %>">
+  <svg xmlns="http://www.w3.org/2000/svg"
+       viewBox="0 0 24 24"
+       fill="currentColor"
+       class="chats-verified__glyph"
+       aria-hidden="true"
+       focusable="false">
+    <path fill-rule="evenodd" clip-rule="evenodd" d="M8.603 3.799A4.49 4.49 0 0 1 12 2.25c1.357 0 2.573.6 3.397 1.549a4.49 4.49 0 0 1 3.498 1.307 4.491 4.491 0 0 1 1.307 3.497A4.49 4.49 0 0 1 21.75 12a4.49 4.49 0 0 1-1.549 3.397 4.491 4.491 0 0 1-1.307 3.497 4.491 4.491 0 0 1-3.497 1.307A4.49 4.49 0 0 1 12 21.75a4.49 4.49 0 0 1-3.397-1.549 4.49 4.49 0 0 1-3.498-1.306 4.491 4.491 0 0 1-1.307-3.498A4.49 4.49 0 0 1 2.25 12c0-1.357.6-2.573 1.549-3.397a4.49 4.49 0 0 1 1.307-3.497 4.49 4.49 0 0 1 3.497-1.307Zm7.007 6.387a.75.75 0 1 0-1.22-.872l-3.236 4.53L9.53 12.22a.75.75 0 0 0-1.06 1.06l2.25 2.25a.75.75 0 0 0 1.14-.094l3.75-5.25Z" />
+  </svg>
+</span>

data/config/locales/en.yml

@@ -30,6 +30,8 @@ en:
       see_all: "See all"
     conversation:
       empty_title: "Conversation"
+    verified:
+      label: "Official account"
     message:
       deleted: "Message deleted"
       edited: "edited"

data/config/locales/es.yml

@@ -30,6 +30,8 @@ es:
       see_all: "Ver todas"
     conversation:
       empty_title: "Conversación"
+    verified:
+      label: "Cuenta oficial"
     message:
       deleted: "Mensaje eliminado"
       edited: "editado"

data/lib/chats/configuration.rb

@@ -153,6 +153,17 @@ module Chats
     # "— Author Name".
     attr_reader :message_signature
 
+    # ->(messager) { markup } — the badge shown next to an OFFICIAL
+    # account's name (`acts_as_messager verified: true`). nil (the default)
+    # renders the gem's own rosette, `chats/shared/_verified_badge`, coloured
+    # by the `--chats-verified` CSS variable.
+    #
+    # Return an html_safe value (anything `render`, `tag` or `image_tag`
+    # gives you) — a bare String is escaped, exactly as it would be anywhere
+    # else in a Rails view. Returning nil renders nothing, so a host can
+    # suppress the badge on some messagers without touching the models.
+    attr_reader :verified_badge
+
     def initialize
       @messager_class = "User"
       @parent_controller = "::ApplicationController"
@@ -187,6 +198,7 @@ module Chats
       @notifier = ->(_event, **_payload) {}
       @messager_url = ->(_messager) { nil }
       @message_signature = nil
+      @verified_badge = nil
 
       @messager_display_name = lambda do |messager|
         messager.try(:display_name) || messager.try(:name) ||
@@ -296,6 +308,10 @@ module Chats
       @message_signature = value.nil? ? nil : ensure_callable(value, "message_signature")
     end
 
+    def verified_badge=(value)
+      @verified_badge = value.nil? ? nil : ensure_callable(value, "verified_badge")
+    end
+
     def messager_display_name=(value)
       @messager_display_name = ensure_callable(value, "messager_display_name")
     end

data/lib/chats/macros.rb

@@ -29,18 +29,27 @@ module Chats
     #                          stacks into ONE inbox row (see Chats::Inbox).
     #   group_path: ->(viewer) { }  where that stacked row links to; defaults
     #                          to the filtered inbox (`?with=<sgid>`).
+    #   verified: true         this messager is an OFFICIAL account — a support
+    #                          desk, an organization, a brand. The bundled views
+    #                          mark its name with the rosette everyone already
+    #                          reads as "verified". Strictly true/false: a badge
+    #                          is a trust claim, so a stray "false" string must
+    #                          raise rather than quietly verify.
     #
     #   class Desk < ApplicationRecord
-    #     acts_as_messager notifications: false, blockable: false, inbox: :grouped
+    #     acts_as_messager notifications: false, blockable: false, inbox: :grouped,
+    #                      verified: true
     #   end
-    def acts_as_messager(notifications: true, blockable: true, inbox: :default, group_path: nil)
+    def acts_as_messager(notifications: true, blockable: true, inbox: :default, group_path: nil,
+                         verified: false)
       include Chats::Messager
 
       self.chat_options = Chats::Messager.normalize_options(
         notifications: notifications,
         blockable: blockable,
         inbox: inbox,
-        group_path: group_path
+        group_path: group_path,
+        verified: verified
       )
     end
 

data/lib/chats/models/concerns/messager.rb

@@ -22,14 +22,15 @@ module Chats
       notifications: true,
       blockable: true,
       inbox: :default,
-      group_path: nil
+      group_path: nil,
+      verified: false
     }.freeze
 
     INBOX_MODES = %i[default grouped].freeze
 
     # Validate + freeze the macro's options, failing at BOOT with a plain
     # English message rather than at 3am with a NoMethodError.
-    def self.normalize_options(notifications:, blockable:, inbox:, group_path:)
+    def self.normalize_options(notifications:, blockable:, inbox:, group_path:, verified: false)
       inbox = inbox.to_sym
       unless INBOX_MODES.include?(inbox)
         raise Chats::ConfigurationError,
@@ -41,11 +42,21 @@ module Chats
               "acts_as_messager group_path: must respond to #call (a proc/lambda), got #{group_path.inspect}"
       end
 
+      # Deliberately STRICTER than its boolean neighbours, which coerce with
+      # `!!`. "Official account" is a trust claim shown to everyone who talks
+      # to this messager, so `verified: "false"` (an ENV var, a YAML
+      # round-trip) has to fail at boot rather than quietly verify it.
+      unless [true, false].include?(verified)
+        raise Chats::ConfigurationError,
+              "acts_as_messager verified: must be true or false, got #{verified.inspect}"
+      end
+
       {
         notifications: !!notifications,
         blockable: !!blockable,
         inbox: inbox,
-        group_path: group_path
+        group_path: group_path,
+        verified: verified
       }.freeze
     end
 
@@ -76,6 +87,13 @@ module Chats
       def chat_group_path
         chat_options[:group_path]
       end
+
+      # True when declared with `acts_as_messager verified: true` — an
+      # OFFICIAL account (a support desk, an organization, a brand). The
+      # bundled views badge its name wherever they show it.
+      def chat_verified?
+        chat_options[:verified]
+      end
     end
 
     included do

data/lib/chats/models/conversation.rb

@@ -222,13 +222,30 @@ module Chats
       )
     end
 
+    # The OTHER messager in a direct thread, from +viewer+'s seat — nil for a
+    # group, and nil for a direct thread whose other seat has left. The one
+    # place the counterpart is resolved, so the title, the avatar and the
+    # verified badge on an inbox row always name the same person.
+    #
+    # Memoized per viewer: an inbox row asks for it two or three times, and a
+    # row that cost one query in 0.2.0 must not start costing three.
+    def counterpart_for(viewer)
+      return nil unless direct?
+
+      @counterparts ||= {}
+      key = viewer && Chats.messager_key(viewer)
+      return @counterparts[key] if @counterparts.key?(key)
+
+      @counterparts[key] = other_participants(viewer).includes(:messager).first&.messager
+    end
+
     # What this conversation is called from +viewer+'s seat: a direct thread
     # is named after the counterpart; a group after its title (or its
     # members, when untitled).
     def title_for(viewer)
       if direct?
-        other = other_participants(viewer).includes(:messager).first
-        other ? Chats.display_name_for(other.messager) : I18n.t("chats.conversation.empty_title")
+        other = counterpart_for(viewer)
+        other ? Chats.display_name_for(other) : I18n.t("chats.conversation.empty_title")
       else
         title.presence || participants.active.includes(:messager).limit(4).map do |p|
           Chats.display_name_for(p.messager)

data/lib/chats/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Chats
-  VERSION = "0.2.0"
+  VERSION = "0.3.1"
 end

data/lib/chats.rb

@@ -219,6 +219,14 @@ module Chats
       messager_option(messager, :chat_grouped_inbox?, default: false)
     end
 
+    # Whether +messager+ is an OFFICIAL account (`acts_as_messager verified:
+    # true`) — a support desk, an organization, a brand. The bundled views
+    # badge its name; hosts can read it to do the same on their own screens.
+    # Defaults to false: nothing is verified until a model says so.
+    def verified?(messager)
+      messager_option(messager, :chat_verified?, default: false)
+    end
+
     # The polymorphic type names of every registered messager class that
     # stacks (`inbox: :grouped`). Empty in an ordinary app — which is what
     # keeps the inbox query there byte-identical to 0.1.x. Used as a SQL

data/lib/generators/chats/templates/initializer.rb

@@ -19,8 +19,10 @@ Chats.configure do |config|
   #   class SupportDesk < ApplicationRecord
   #     acts_as_messager notifications: false,   # never notifiable
   #                      blockable:     false,   # no block/report affordances
-  #                      inbox:         :grouped # every thread with it is ONE
-  #                                              # inbox row (a "stack")
+  #                      inbox:         :grouped, # every thread with it is ONE
+  #                                               # inbox row (a "stack")
+  #                      verified:      true     # an OFFICIAL account: the
+  #                                              # views badge its name
   #   end
   #
   # `group_path:` says where that stacked row goes when it holds more than
@@ -200,6 +202,15 @@ Chats.configure do |config|
   # localized "— Agent Name":
   #
   # config.message_signature = ->(message) { "answered by #{message.author.first_name}" }
+  #
+  # The "official account" badge next to a `verified: true` messager's name.
+  # nil (the default) renders chats' own rosette, recoloured by the
+  # `--chats-verified` CSS variable. Set this to hand back your design
+  # system's mark instead — return html_safe markup, or nil for no badge:
+  #
+  # config.verified_badge = lambda do |messager|
+  #   ApplicationController.helpers.image_tag("official.svg", class: "badge", alt: "Official account")
+  # end
 
   # ==========================================================================
   # SLOTS — add one row or one button without ejecting a screen

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: chats
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.1
 platform: ruby
 authors:
 - rameerez
@@ -151,6 +151,7 @@ files:
 - app/views/chats/messages/errors.turbo_stream.erb
 - app/views/chats/messages/locked.turbo_stream.erb
 - app/views/chats/shared/_unread_badge.html.erb
+- app/views/chats/shared/_verified_badge.html.erb
 - config/importmap.rb
 - config/locales/en.yml
 - config/locales/es.yml