livechat 0.4.8 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7f0dd913b9f9ac88756a298d2ad57cf69c78d3f8bf31c08941171a6d13626a16
-  data.tar.gz: 1148803aaf1b0d465afd5526ee6196d0814f23f0a3c75d4f9a7cfbd3ba96f6ee
+  metadata.gz: c43b02b890218a998865cc1e5e48d03aa292a120cac3a07045bf18e52f92f33b
+  data.tar.gz: eb8be46400159aef252e0d2bcd2ffed67a086f9c98cc7b4e2d055543e52e657c
 SHA512:
-  metadata.gz: 8eff7b6fff9df34b825dd647d41eabc4e415572bd5dd282465f52de3e2ac4fa3ee648a6123b426dc67615f064d82e3354762b0cc9103ea9d724d251de5e769c8
-  data.tar.gz: 57905952ca50aaa60b2103577ab54f6ee433f0729329ee5ea999e7a4bade5100a9e585ce9702842857962209f3b63369db9dde0b03358a723d4a9bb960e48251
+  metadata.gz: a73f3a61db23291760581906d03b2886dff33ff58a68eeceb5f52ce1826deff66e2c0867d3ac4d058824ba297aa923515e9c42a5675d8a9b5705977b945223b6
+  data.tar.gz: 81b7e4f24815ccd1c549f7fbc885ed108a800e3906e7d168f91c4a33a4a269dd596ee14ac2066d6a98e0f34e13c10caba60fb0702b0569a3f89540466173db11

data/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.5.0
+
+- The full-screen mobile panel now survives the on-screen keyboard. On phones
+  the panel is a fixed `100dvh` box, and iOS Safari draws the keyboard over it
+  without resizing it — so the composer and send button ended up hidden behind
+  the keyboard with a big empty gap above. The widget now pins the open panel
+  to the `visualViewport` (the area left visible above the keyboard), shrinking
+  its height and following the viewport offset so the composer sits just above
+  the keyboard and the newest message stays in view. Desktop popover behaviour
+  is unchanged (the pinning only runs while the mobile full-screen media query
+  matches), and browsers without the `visualViewport` API simply keep the old
+  CSS behaviour.
+- The desktop-only expand/collapse control is now actually hidden on phones,
+  where the panel is already full-screen. (The mobile rule existed but lost on
+  specificity to the base button style, so the button was still showing.)
+
 ## 0.4.8
 
 - A conversation with image attachments now opens scrolled to the bottom, not

data/README.md

@@ -1,64 +1,17 @@
 # livechat
 
 [![Gem Version](https://img.shields.io/gem/v/livechat)](https://rubygems.org/gems/livechat)
+[![Downloads](https://img.shields.io/gem/dt/livechat)](https://rubygems.org/gems/livechat)
 [![CI](https://github.com/yshmarov/livechat/actions/workflows/ci.yml/badge.svg)](https://github.com/yshmarov/livechat/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue)](MIT-LICENSE)
 
-Open-source live chat for Rails. Alternative to Crisp, Intercom and
-Chatwoot — inside your Rails app, as a gem, not another service to deploy.
-
-Your users already have questions. `livechat` gives them a chat bubble and
-gives you an inbox, inside the app you already run. Visitors write — signed
-in or not. Your team answers — together, every reply signed with its author.
-Nobody is around? Visitors leave an email and the conversation continues
-there. Every word stays in your database.
-
-- **A gem, not a platform.** `bundle add livechat`, one migration, one line
-  in your layout. No second app to deploy, no third-party script on your
-  pages, no per-seat pricing. Ever.
-- **Zero UI dependencies.** The widget is plain JavaScript and styles itself.
-  No Tailwind, no Stimulus, no importmap, no build step, no websockets to
-  configure. Works with Turbo Drive and strict nonce-based CSPs out of the box.
-- **Honest about response time.** The widget says "We usually reply within a
-  few hours" (you choose the words), not a fake "we're online". Email
-  notifications — both directions — keep slow conversations alive.
-- **A team sport.** Any authorized teammate answers any thread; each message
-  carries its author. You decide what visitors see — full names, first
-  names, or an anonymous "Support team".
-- **Real attribution.** Signed-in visitors are identified server-side against
-  your user records and keep their thread across devices. Guests get a
-  cookie, and keep their history when they sign up.
-- **Send files, both ways.** Visitors and agents attach images and documents;
-  images show inline. Files are served through the engine — gated exactly like
-  the chat — never a public blob URL. Needs Active Storage; degrades to
-  text-only where it's absent.
-- **26 languages.** The widget follows your app's locale, RTL included.
+**Open-source live chat for Rails.** A chat bubble for your users, an inbox for
+your team — as a gem, not another service to deploy. Alternative to Crisp,
+Intercom and Chatwoot.
 
-## How it works
-
-1. Add `<%= livechat_tag %>` to your layout. A chat bubble appears
-   bottom-right (or open the panel from any element with
-   `data-livechat-open`, or `window.Livechat.open()`).
-2. A visitor writes. The message lands in `livechat_conversations` in your
-   database, and — if you configured it — in your team's email.
-3. Your team answers at the mount path (`/livechat`). Several people can
-   work the same thread; resolve it when done. A visitor writing again
-   reopens it — one thread per visitor, like a conversation, not tickets.
-4. The visitor sees the reply in the widget, or by email when they're gone.
+![The livechat widget open over a running Rails app](docs/screenshots/01-widget.png)
 
-Realtime is polling, on purpose: ~4s while the panel is open, ~30s in the
-background, nothing at all for visitors who never wrote. No Action Cable,
-no Redis, no infrastructure. At support-chat volume you will not notice;
-your ops person will notice there is nothing new to run. If you already run
-Action Cable and want replies to land the instant they're sent, turn it on
-(`config.action_cable = true`) — polling stays the fallback.
-
-## Requirements
-
-- Ruby >= 3.2
-- Rails >= 7.1
-
-## Installation
+## Install
 
 ```ruby
 # Gemfile
@@ -71,57 +24,140 @@ bin/rails generate livechat:install
 bin/rails db:migrate
 ```
 
-The generator writes `config/initializers/livechat.rb`, creates the
-migration, and mounts the engine at `/livechat`. Then add the widget to your
-layout:
-
 ```erb
+<%# app/views/layouts/application.html.erb %>
 <%= livechat_tag %>
 ```
 
 That's it. Visit any page, click the bubble, say hi. Answer yourself at
 `/livechat`.
 
-## Configuration
+> [!IMPORTANT]
+> The inbox defaults to **development only**. Set `authorize_agent` before you
+> deploy — see [Configure](#configure).
+
+Ruby >= 3.2 · Rails >= 7.1 · Active Storage only if you want file attachments.
+
+## What you get
+
+|               |                                                                          |
+| ------------- | ------------------------------------------------------------------------ |
+| **Widget**    | Chat bubble, expandable panel, drafts preserved, unread badges            |
+| **Inbox**     | Open / resolved tabs, search across everything, who-worked-what column    |
+| **Team**      | Any teammate answers any thread; every reply signed with its author       |
+| **Email**     | Both directions — one per unread stretch, not one per message             |
+| **Files**     | Images inline, documents as links. Served through the engine, never a blob URL |
+| **Realtime**  | Polling by default (no Redis, no Action Cable). Push is opt-in            |
+| **Threads**   | One per visitor — a conversation, not tickets. Writing again reopens it   |
+| **Deps**      | None. Plain JS — no Tailwind, no Stimulus, no importmap, no build step    |
+| **Auth**      | Lambdas over the raw request — Devise, Rails 8 auth, anything             |
+| **i18n**      | 26 languages, RTL included                                               |
+| **Turbo/CSP** | Turbo Drive and strict nonce-based CSP out of the box                     |
+
+## Why a gem
+
+|                        | `livechat`                     | Hosted chat SaaS            |
+| ---------------------- | ------------------------------ | --------------------------- |
+| Cost                   | Free, MIT                      | Per-seat, per-month         |
+| Where conversations live | Your database                | The vendor's                |
+| To deploy              | `bundle add livechat`          | A script tag, or a second app |
+| Visitor identity       | Server-side, from your session | Whatever the visitor types  |
+| Page weight            | One `<script>`, no CDN         | Third-party bundle          |
+| Infrastructure         | None. Polling by default       | Theirs, or your own Redis + Cable |
+| "Powered by" badge     | Never                          | Usually, until you pay      |
+
+## How it works
+
+1. Add `<%= livechat_tag %>` to your layout. A bubble appears bottom-right —
+   or open the panel from any element with `data-livechat-open`, or
+   `window.Livechat.open()`.
+2. A visitor writes. The message lands in `livechat_conversations` in your
+   database, and — if you configured it — in your team's email.
+3. Your team answers at `/livechat`. Several people can work the same thread;
+   resolve it when done. A visitor writing again reopens it.
+4. The visitor sees the reply in the widget, or by email when they're gone.
+
+**Realtime is polling, on purpose:** ~4s while the panel is open, ~30s in the
+background, nothing at all for visitors who never wrote. No Action Cable, no
+Redis, no infrastructure. At support-chat volume you will not notice; your ops
+person will notice there is nothing new to run. Already running Action Cable
+and want instant delivery? `config.action_cable = true` — polling stays the
+fallback.
+
+## The inbox
 
-Everything lives in `config/initializers/livechat.rb`; every option has a
-working default. The essentials:
+Open and resolved tabs, unread badges, search (visitor name, email, and
+everything anyone wrote), and a column showing which teammates have worked each
+thread. Reply with Cmd/Ctrl+Enter, resolve, reopen. Both pages keep themselves
+fresh while you watch — and never reload over a half-written reply or search.
+
+| The list | The thread |
+| --- | --- |
+| ![The inbox: open and resolved tabs, search, and a table of conversations](docs/screenshots/03-inbox.png) | ![A conversation: signed replies, timestamps, resolve event and composer](docs/screenshots/04-conversation.png) |
+
+Every reply carries its author and time, and resolving is recorded in the
+thread. Gated by `authorize_agent`.
+
+## Configure
+
+Everything is optional — a fresh install works with zero config. In
+`config/initializers/livechat.rb`:
+
+| Option | Default | What it does |
+| --- | --- | --- |
+| `authorize_agent` | development only | **Who can read the inbox.** Override before deploying |
+| `enabled` | everyone | Who sees the widget. `false` hides it and rejects posts |
+| `current_user` | `nil` | Identify the visitor. Receives the request |
+| `app_name` | Rails app name | Shown in the widget header |
+| `greeting` | localized default | First message visitors see |
+| `reply_time_text` | localized default | "We usually reply within a few hours" |
+| `launcher_label` | localized default | Text on the bubble |
+| `accent_color` | `nil` | One hex restyles launcher, header, bubbles, send button |
+| `show_launcher` | `true` | `false` hides the bubble — bring your own entry point |
+| `visitor_label` | name, else email | How a visitor is labelled in the inbox |
+| `agent_label` | name, else email | How an agent is labelled internally |
+| `agent_display_name` | the full label | What **visitors** see — trim it or anonymise it |
+| `mailer_from` | `nil` | Required for any email |
+| `agent_emails` | `nil` | Who gets notified of new visitor messages |
+| `on_visitor_message` | no-op | Runs after a visitor writes — Slack, etc. |
+| `on_agent_message` | no-op | Runs after an agent replies |
+| `attach_files` | `true` | File attachments (needs Active Storage) |
+| `max_attachments` | `5` | Per message |
+| `max_attachment_size` | `10.megabytes` | Enforced server-side |
+| `allowed_attachment_types` | `nil` (any) | Or an allowlist, e.g. `%w[image/png application/pdf]` |
+| `action_cable` | `false` | Opt into push delivery |
+| `action_cable_url` | `"/cable"` | Match your `mount ActionCable...` |
+| `rate_limit` | `{ to: 30, within: 1.minute }` | Per-IP throttle (Rails 7.2+). `nil` disables |
+| `mount_path` | `"/livechat"` | Keep in sync with `mount` in `routes.rb` |
+
+A typical initializer:
 
 ```ruby
 Livechat.configure do |config|
-  config.current_user = ->(request) { request.env["warden"]&.user }
-  config.authorize_agent = ->(request) { request.env["warden"]&.user&.admin? }
-  config.mailer_from = "chat@example.com"
-  config.agent_emails = -> { User.where(admin: true).pluck(:email) }
-  config.reply_time_text = "We usually reply within an hour."
+  config.current_user     = ->(request) { request.env["warden"]&.user }
+  config.authorize_agent  = ->(request) { request.env["warden"]&.user&.admin? }
+  config.mailer_from      = "chat@example.com"
+  config.agent_emails     = -> { User.where(admin: true).pluck(:email) }
+  config.reply_time_text  = "We usually reply within an hour."
+  config.accent_color     = "#7c3aed"
 end
 ```
 
-`current_user` (and any admin gate) receives the raw request, so it works
-with whatever auth you have:
+Gates receive the **raw request**, so they work with any auth:
 
 ```ruby
-# Devise / Warden:
+# Devise / Warden
 config.current_user = ->(request) { request.env["warden"]&.user }
 
-# Rails 8 built-in auth (bin/rails generate authentication):
+# Rails 8 built-in auth (bin/rails generate authentication)
 config.current_user = lambda do |request|
   token = request.cookies["session_token"]
   Session.find_signed(token)&.user if token
 end
 ```
 
-### Brand color
-
-```ruby
-config.accent_color = "#7c3aed"
-```
-
-One hex value restyles the launcher, header, visitor bubbles and send
-button; the widget picks black or white text automatically for contrast,
-in light and dark mode alike.
-
-### Who visitors talk to
+<details>
+<summary><b>Who visitors talk to</b></summary>
 
 Replies are signed. What visitors see is up to you:
 
@@ -130,22 +166,27 @@ config.agent_display_name = ->(label) { label.split.first }   # "Ada"
 config.agent_display_name = ->(_label) { "Support team" }     # anonymous
 ```
 
-### Email, both directions
+</details>
+
+<details>
+<summary><b>Email, both directions</b></summary>
 
-When a visitor writes and nobody has read it, the team gets one email — one
-per unread stretch, not one per message. When an agent replies and the
-visitor is away, the visitor gets one email (signed-in visitors
-automatically, guests once they leave an address — the widget asks, gently).
-Requires `config.mailer_from`; team notifications also need
-`config.agent_emails`.
+When a visitor writes and nobody has read it, the team gets one email — one per
+unread stretch, not one per message. When an agent replies and the visitor is
+away, the visitor gets one email (signed-in visitors automatically, guests once
+they leave an address — the widget asks, gently).
 
-For anything else, hook in:
+Requires `mailer_from`; team notifications also need `agent_emails`. For
+anything else, hook in:
 
 ```ruby
 config.on_visitor_message = ->(message) { SlackNotifier.ping(message) }
 ```
 
-### File attachments
+</details>
+
+<details>
+<summary><b>File attachments</b></summary>
 
 On by default wherever the app has Active Storage. If you don't already:
 
@@ -153,22 +194,18 @@ On by default wherever the app has Active Storage. If you don't already:
 bin/rails active_storage:install && bin/rails db:migrate
 ```
 
-Visitors get a paperclip in the composer; agents get a file field on the
-reply form. Images render inline in the thread, other files as download
-links. Every file is served through the engine's own route and gated the
-same way the chat is — an agent, or the visitor who owns that conversation —
-so nothing leaks through a guessable or long-lived blob URL.
-
-```ruby
-config.attach_files = true               # false turns it off even with Active Storage
-config.max_attachments = 5               # per message
-config.max_attachment_size = 10.megabytes
-config.allowed_attachment_types = nil    # or an allowlist, e.g. %w[image/png image/jpeg application/pdf]
-```
+Visitors get a paperclip in the composer; agents get a file field on the reply
+form. Images render inline, other files as download links. Every file is served
+through the engine's own route and gated the same way the chat is — an agent,
+or the visitor who owns that conversation — so nothing leaks through a
+guessable or long-lived blob URL.
 
 Where Active Storage isn't installed, the widget quietly stays text-only.
 
-### Realtime with Action Cable (optional)
+</details>
+
+<details>
+<summary><b>Realtime with Action Cable</b></summary>
 
 Polling is the default and needs nothing from your app. If you already run
 Action Cable, turn on push so a reply appears the instant it's sent:
@@ -178,51 +215,53 @@ config.action_cable = true
 config.action_cable_url = "/cable" # match your `mount ActionCable... => ...`
 ```
 
-A new message nudges the widget and the inbox to refresh at once; polling
-stays the fallback, so a dropped socket or a proxy that blocks WebSockets
-never means a missed message. The widget speaks the Action Cable protocol
-over a plain WebSocket — no `@rails/actioncable`, no build step — and only
-ever subscribes to a stream the server signed for it. Under a strict CSP,
-allow the socket with `connect-src 'self'`.
-
-## The inbox
+A new message nudges the widget and the inbox to refresh at once; polling stays
+the fallback, so a dropped socket or a proxy that blocks WebSockets never means
+a missed message. The widget speaks the Action Cable protocol over a plain
+WebSocket — no `@rails/actioncable`, no build step — and only ever subscribes
+to a stream the server signed for it. Under a strict CSP, allow the socket with
+`connect-src 'self'`.
 
-Browse at the mount path: open and resolved tabs, unread badges, search
-(visitor name, email, and everything anyone wrote), and a column showing
-which teammates have worked each thread. One click into a thread; reply
-(Cmd/Ctrl+Enter sends), resolve, reopen. Both pages keep themselves fresh
-while you watch — and never reload over a half-written reply or search.
-Gated by `config.authorize_agent` (development-only until you set it).
+</details>
 
 ## Widget API
 
-- `window.Livechat.open()` / `window.Livechat.close()` —
-  `open("Hi, I need help with…")` prefills the message box (never over a
-  visitor's draft)
-- Any element with `data-livechat-open` opens the panel on click; add
-  `data-livechat-message="…"` to prefill — great for contextual buttons
-  ("Request verification", "Ask about billing")
-- While replies are unread, every `data-livechat-open` element carries a
-  small count badge — so hiding the launcher doesn't hide the answer
-- `<%= livechat_button %>` renders a plain, unstyled opener button
-- `config.show_launcher = false` hides the bubble entirely — bring your own
-  entry point
+| | |
+| --- | --- |
+| `window.Livechat.open()` / `.close()` | `open("Hi, I need help with…")` prefills the box — never over a visitor's draft |
+| `data-livechat-open` | Any element opens the panel on click |
+| `data-livechat-message="…"` | Prefill from that element — great for contextual buttons |
+| `<%= livechat_button %>` | A plain, unstyled opener button |
+| `config.show_launcher = false` | Hide the bubble entirely |
+
+While replies are unread, every `data-livechat-open` element carries a small
+count badge — so hiding the launcher never hides the answer.
 
 ## What it doesn't do
 
 No AI bots, no canned responses, no omnichannel (WhatsApp, Messenger…), no
 visitor tracking, no "powered by" badge. If you need a support platform,
-[Chatwoot](https://github.com/chatwoot/chatwoot) is excellent. If you need
-your users to be able to reach you from inside your Rails app — this is a
-gem's worth of exactly that.
+[Chatwoot](https://github.com/chatwoot/chatwoot) is excellent. If you need your
+users to be able to reach you from inside your Rails app — this is a gem's
+worth of exactly that.
 
-## Testing
+## Development
 
 ```bash
 bundle exec rake test
 bundle exec rubocop
 ```
 
+## Also by the same author
+
+- [testimonials](https://github.com/yshmarov/testimonials) — testimonials,
+  reviews and NPS for Rails.
+- [ideasbugs](https://github.com/yshmarov/ideasbugs) — in-app bug reports and
+  feature requests.
+- [i18n_proofreading](https://github.com/yshmarov/i18n_proofreading) — in-context
+  translation proofreading.
+- [SupeRails](https://superails.com) — Rails screencasts.
+
 ## License
 
 MIT.

data/lib/livechat/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Livechat
-  VERSION = '0.4.8'
+  VERSION = '0.5.0'
 end

data/lib/livechat/widget.js

@@ -457,6 +457,7 @@
       panel.hidden = false;
       panel.setAttribute("aria-modal", isMobileModal() ? "true" : "false");
       if (isMobileModal()) lockScroll();
+      bindViewport(); // pin the panel above the keyboard on phones
       setUnread(0);
       poll();
       schedulePoll();
@@ -475,6 +476,7 @@
     sessionSet("livechat_open", "");
     var panel = document.getElementById("lvc-panel");
     if (panel) panel.hidden = true;
+    unbindViewport();
     unlockScroll();
     if (lastFocused && document.contains(lastFocused)) lastFocused.focus();
     schedulePoll();
@@ -546,6 +548,49 @@
     savedOverflow = null;
   }
 
+  // --- mobile keyboard: keep the full-screen panel above the keyboard ---------
+
+  // On phones the panel is position:fixed at height:100dvh. When the composer
+  // is focused, iOS Safari draws the keyboard OVER that fixed box without
+  // resizing it — the send row ends up hidden behind the keyboard and the
+  // layout breaks. The visualViewport API reports the actually-visible
+  // rectangle (viewport minus keyboard), so we pin the panel to it: its height
+  // shrinks to the visible area and its top follows any viewport offset, which
+  // sits the composer just above the keyboard. Desktop never runs this — the
+  // work is gated on the mobile media query, and we clear the inline styles the
+  // moment it stops matching (e.g. a phone rotated to a wide viewport).
+  function syncViewport() {
+    var panel = document.getElementById("lvc-panel");
+    if (!panel || !window.visualViewport) return;
+    if (isMobileModal()) {
+      panel.style.height = window.visualViewport.height + "px";
+      panel.style.top = window.visualViewport.offsetTop + "px";
+      scrollToBottom(); // newest message stays in view above the keyboard
+    } else {
+      // Not the mobile modal — hand height/top back to the stylesheet.
+      panel.style.height = "";
+      panel.style.top = "";
+    }
+  }
+
+  function bindViewport() {
+    if (!window.visualViewport) return; // older browsers: no-op, CSS stands
+    window.visualViewport.addEventListener("resize", syncViewport);
+    window.visualViewport.addEventListener("scroll", syncViewport);
+    syncViewport(); // apply once on open (covers a keyboard already up)
+  }
+
+  function unbindViewport() {
+    if (!window.visualViewport) return;
+    window.visualViewport.removeEventListener("resize", syncViewport);
+    window.visualViewport.removeEventListener("scroll", syncViewport);
+    var panel = document.getElementById("lvc-panel");
+    if (panel) {
+      panel.style.height = "";
+      panel.style.top = "";
+    }
+  }
+
   // --- polling ----------------------------------------------------------------
 
   function schedulePoll() {
@@ -953,7 +998,9 @@
       "{left:0;right:0;top:0;bottom:0;width:100%;max-width:100%;height:100dvh;max-height:100dvh;" +
       "border-radius:0;border:none}" +
       // The panel is already full-screen here, so there's nothing to expand.
-      "#lvc-expand{display:none}" +
+      // Two ids to outrank the base `#lvc-root #lvc-expand{display:flex}` rule —
+      // a bare `#lvc-expand` loses on specificity and never hides.
+      "#lvc-root #lvc-expand{display:none}" +
       // 16px stops iOS Safari from zoom-jumping into focused fields.
       "#lvc-root #lvc-input,#lvc-root #lvc-email input{font-size:16px}" +
       // Keep the composer box above the iPhone home indicator.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: livechat
 version: !ruby/object:Gem::Version
-  version: 0.4.8
+  version: 0.5.0
 platform: ruby
 authors:
 - Yaroslav Shmarov