turbo_chat 0.1.3 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8b3acc495a5c2ed02fb0e34b695abcc886324ddd36a2e74908fff04e3804cbcd
-  data.tar.gz: 540a69f756787516f4425d5c6f02f9d48d48be1668099d7be3c46852cce0cb59
+  metadata.gz: 87e5b68d4722dd1f28ae30a9926da8445184f2c3116b66f55c8f948e15e923f8
+  data.tar.gz: 4654ef43284576a86f56c64c24d93bf3f6a15da709a81720af9fe38f331f5d6c
 SHA512:
-  metadata.gz: 5bd0b0a533a8dc5ff85d27abc937cb3a56cd1ec0a469b109a34dae24443134eac7740b3dbe65afeab4d394401a68ae632502de9849a81fb6711366c934e5da7b
-  data.tar.gz: 5e70673d9dc958fde377576d1332fc9f869b60d92401a0930045b5e3e70d4f23f1f78afc7a0a7ca98ba5389794b9e2ac50c0453356fc7088f4cabf88f872e1c5
+  metadata.gz: 1cfa9becf70f4e79fb3d5907dacefd722e87849b8f0cb3cbc75a6b7baa82680bdee3dc82b9d600bf4ddaee56ceaddbb278611a70b462bf8ff1604947f536e951
+  data.tar.gz: b5e6106acb66c2e01447ef4a2b104d28da4206a712bf42a3076f5b981e3165d388e787b2307d70793d89ff550cfefdf73dceaea9e100b7ee50489d3284c8eda0

data/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+All notable changes to `turbo_chat` will be documented in this file.
+
+## [0.1.4] - 2026-02-22
+
+### Added
+- Searchable invite picker for chat invitations.
+- Collapsible members panel with fixed-height member list shell.
+- Role management and Turbo member list synchronization in chat UI.
+- Lifecycle system messages for join/leave/moderation events.
+- Config toggles for chat member visibility and composer controls.
+
+### Changed
+- Expanded initializer template guidance and README setup/docs.
+- Refactored core chat modules for simpler internal structure.
+- Improved invite row UX and chat composer behavior.
+
+### Fixed
+- Turbo Stream helper errors in member entry rendering.
+- CI setup to prepare the test database before running `test:all`.
+
+## [0.1.3] - 2026-02-19
+- Initial RubyGems release.

data/README.md

@@ -1,65 +1,45 @@
 # TurboChat
 
-TurboChat is a mountable Rails chat engine for server-rendered apps.
+TurboChat is a mountable Rails chat engine for server-rendered applications.
 
-What you get:
-- Turbo Stream chat UI.
-- Role-based permissions.
-- Mentions, typing signals, invites, moderation.
-- Practical customization hooks without rewriting everything.
+Status: actively maintained.
 
-What this is not:
-- A hosted chat service.
-- A React-first component library.
-- A "just add JS" widget.
+## What You Get
 
-## Use This If
-
-Use TurboChat if your app is Rails-first and you want chat now, not after building a custom permission/event/moderation system.
+- Turbo Stream chat UI.
+- Role-based permissions.
+- Mentions, invitations, moderation, and typing signals.
+- A Rails-first path to ship chat quickly.
 
-Skip it if you want fully custom frontend architecture from day one.
+## Basic Setup
 
-## Install
+Add the gem:
 
 ```ruby
 # Gemfile
 gem "turbo_chat"
 ```
 
+Install and migrate:
+
 ```bash
 bundle install
 bin/rails generate turbo_chat:install
 bin/rails db:migrate
 ```
 
-Mount with an explicit helper prefix:
+Mount the engine:
 
 ```ruby
 # config/routes.rb
-mount TurboChat::Engine => "/chat", as: "turbo_chat"
+mount TurboChat::Engine => "/", as: "turbo_chat"
 ```
 
-Opinionated recommendation: mount under `/chat` (or another scoped path), not root.
-
-## Participant Resolution (Most Important Section)
-
-This is where installs usually fail. TurboChat now resolves the current participant in this order:
+This gives you chat routes like `/` (chat index), `/chats`, and `/chats/:id`.
 
-1. `current_chat_participant` on your host `ApplicationController` (preferred explicit hook).
-2. `config.current_participant_resolver` (custom resolver lambda).
-3. `current_user` (if your app exposes it).
+## Host App Requirements
 
-If none are available, TurboChat raises `NotImplementedError` with guidance.
-
-Return value must be:
-- `nil` (unauthenticated), or
-- a model that uses `acts_as_chat_participant`.
-
-If you use Devise and your `User` model is a chat participant, this works out of the box.
-
-## Host Contract
-
-### Participant model opt-in
+### 1. Mark your participant model
 
 ```ruby
 class User < ApplicationRecord
@@ -67,7 +47,11 @@ class User < ApplicationRecord
 end
 ```
 
-### Optional explicit hook (recommended for clarity)
+### 2. Resolve the current participant
+
+Define `current_chat_participant` in your host `ApplicationController`.
+
+Recommended hook:
 
 ```ruby
 class ApplicationController < ActionController::Base
@@ -77,7 +61,12 @@ class ApplicationController < ActionController::Base
 end
 ```
 
-### Optional custom resolver (for non-`current_user` auth)
+Fallback behavior (only if you do not define `current_chat_participant`):
+
+1. `config.current_participant_resolver`
+2. `current_user`
+
+Optional resolver for non-`current_user` auth:
 
 ```ruby
 TurboChat.configure do |config|
@@ -85,35 +74,24 @@ TurboChat.configure do |config|
 end
 ```
 
-## First Working Usage
+## First Working Example
+
+Create a chat and add an admin membership:
 
 ```ruby
 chat = TurboChat::Chat.create!(title: "Support")
 TurboChat::ChatMembership.create!(chat: chat, participant: current_user, role: :admin)
 ```
 
+Link to it:
+
 ```erb
 <%= link_to "Open chat", turbo_chat.chat_path(chat) %>
 ```
 
-## Routes You Actually Need
-
-From the mounted engine:
-- `GET /chats`
-- `GET /chats/:id`
-- `POST /chats`
-- `PATCH /chats/:id/accept`
-- `PATCH /chats/:id/decline`
-- `PATCH /chats/:id/leave`
-- `PATCH /chats/:id/close`
-- `PATCH /chats/:id/reopen`
-- `POST /chats/:chat_id/chat_memberships`
-- `POST /chats/:chat_id/chat_messages`
-- `PATCH /chats/:chat_id/chat_messages/:id`
-
-## Recommended Baseline Config
+## Essential Configuration
 
-Keep this simple initially:
+Start with a minimal initializer and only expand when needed:
 
 ```ruby
 TurboChat.configure do |config|
@@ -122,11 +100,8 @@ TurboChat.configure do |config|
   config.max_chat_participants = 10
   config.max_message_length = 1000
   config.message_history_limit = 200
-  config.active_chat_window = 5.minutes
 
   config.enable_mentions = true
-  config.mention_filter_exclude_self = true
-  config.mention_filter_hide_roles = true
   config.enable_emoji_aliases = true
 
   config.blocked_words = []
@@ -136,38 +111,25 @@ TurboChat.configure do |config|
   config.show_timestamp = true
   config.show_role = false
 
-  config.emit_typing_events = false
-  config.emit_message_events = false
-  config.emit_mention_events = false
-  config.emit_invitation_events = false
-  config.emit_chat_lifecycle_events = false
   config.emit_moderation_events = false
   config.emit_blocked_words_events = false
+  config.emit_mention_events = false
 end
 ```
 
-Opinionated defaults:
-- Leave HTML rendering off unless required.
-- Leave event emission off unless consumed.
-- Keep permissions adapter default until you have a concrete policy gap.
-
-## Roles and Permissions
+## Roles
 
 Built-in roles:
+
 - `member`
 - `moderator`
 - `admin`
 
-Behavior summary:
-- `member`: view/post and member mentions.
-- `moderator`: invite, `@all`, role mentions, mute/timeout/ban, delete lower-rank messages.
-- `admin`: moderator powers plus close/reopen chat.
+Role behavior:
 
-Hard rules:
-- Moderation is rank-based.
-- No self-moderation.
-- Closed chat blocks posting.
-- Muted/timed-out members cannot post.
+- `member`: can view/post and mention members.
+- `moderator`: can invite, mention `@all`/roles, mute/timeout/ban, and delete lower-rank messages.
+- `admin`: can do moderator actions plus close/reopen chats.
 
 Custom role example:
 
@@ -182,53 +144,11 @@ TurboChat.configure do |config|
 end
 ```
 
-## Invitations
-
-- Invite creation: `POST /chats/:chat_id/chat_memberships`
-- Accept: `PATCH /chats/:id/accept`
-- Decline: `PATCH /chats/:id/decline`
-
-Important constraints:
-- Invite type must match inviter participant base class.
-- Participant limits apply to active memberships.
-- Re-invite reactivates existing memberships.
-
-## Messages, Mentions, Signals
-
-### Messages
-- Realtime append/update/remove via Turbo Streams.
-- Inline edit for your own messages (permission-gated).
-- History capped by `message_history_limit`.
-
-### Mentions
-- `@username`, `@all`, `@ROLE`.
-- Server-side mention permission validation.
-- Autocomplete defaults: excludes self, hides roles.
-
-### Signals
-Automatic typing loop is built in.
-
-Manual APIs:
-
-```ruby
-TurboChat::Signals.start!(chat: chat, participant: current_user, signal_type: :thinking)
-TurboChat::Signals.replace!(chat: chat, participant: current_user, signal_type: :planning)
-TurboChat::Signals.clear!(chat: chat, participant: current_user)
-```
-
-```ruby
-TurboChat::Signals.with(chat: chat, participant: current_user, signal_type: :thinking) do
-  # work
-end
-```
-
 ## Moderation API
 
 ```ruby
 TurboChat::Moderation.mute_member!(actor: moderator, membership: membership)
-TurboChat::Moderation.unmute_member!(actor: moderator, membership: membership)
 TurboChat::Moderation.timeout_member!(actor: moderator, membership: membership, until_time: 30.minutes.from_now)
-TurboChat::Moderation.clear_timeout!(actor: moderator, membership: membership)
 TurboChat::Moderation.ban_member!(actor: moderator, membership: membership)
 TurboChat::Moderation.delete_message!(actor: moderator, message: message)
 TurboChat::Moderation.close_chat!(actor: admin, chat: chat)
@@ -236,74 +156,89 @@ TurboChat::Moderation.reopen_chat!(actor: admin, chat: chat)
 ```
 
 Raises:
+
 - `TurboChat::Moderation::AuthorizationError`
 - `TurboChat::Moderation::InvalidActionError`
 
-## Browser Events
-
-Enable with config flags.
-
-Event names:
-- `turbo-chat:typing-started`
-- `turbo-chat:typing-ended`
-- `turbo-chat:message-sent`
-- `turbo-chat:mention`
-- `turbo-chat:invitation-accepted`
-- `turbo-chat:chat-invited`
-- `turbo-chat:chat-joined`
-- `turbo-chat:chat-declined`
-- `turbo-chat:chat-left`
-- `turbo-chat:chat-closed`
-- `turbo-chat:chat-reopened`
+## Signals API
 
-```js
-document.addEventListener("turbo-chat:message-sent", function (event) {
-  console.log(event.detail.chatId);
-});
+```ruby
+TurboChat::Signals.start!(chat: chat, participant: current_user, signal_type: :typing)
+TurboChat::Signals.clear!(chat: chat, participant: current_user)
 ```
 
-Client namespace: `window.TurboChatUI`
+## Event Emissions
 
-## ActiveSupport::Notifications
+All event emissions are opt-in.
 
-Moderation (`emit_moderation_events = true`):
-- `turbo_chat.moderation.member_muted`
-- `turbo_chat.moderation.member_unmuted`
-- `turbo_chat.moderation.member_timed_out`
-- `turbo_chat.moderation.member_timeout_cleared`
-- `turbo_chat.moderation.member_banned`
-- `turbo_chat.moderation.message_deleted`
-- `turbo_chat.moderation.chat_closed`
-- `turbo_chat.moderation.chat_reopened`
+Enable only what you consume:
 
-Blocked words (`emit_blocked_words_events = true`):
-- `turbo_chat.blocked_words.detected`
-- `turbo_chat.blocked_words.rejected`
-- `turbo_chat.blocked_words.scrambled`
+```ruby
+TurboChat.configure do |config|
+  config.emit_typing_events = true
+  config.emit_message_events = true
+  config.emit_mention_events = true
+  config.emit_invitation_events = true
+  config.emit_chat_lifecycle_events = true
+  config.emit_moderation_events = true
+  config.emit_blocked_words_events = true
+end
+```
 
-## UI Customization
+Browser events (`CustomEvent`):
 
-Do this in order:
-1. Theme with config (`own_message_hex_color`, `role_message_hex_colors`, `mention_mark_hex_color`, formatters).
-2. Add class-level customization via `message_css_class_resolver`.
-3. Only then override markup partials.
+- `emit_typing_events`: `turbo-chat:typing-started`, `turbo-chat:typing-ended`
+- `emit_message_events`: `turbo-chat:message-sent`
+- `emit_mention_events`: `turbo-chat:mention`
+- `emit_invitation_events`: `turbo-chat:invitation-accepted`
+- `emit_chat_lifecycle_events`: `turbo-chat:chat-invited`, `turbo-chat:chat-joined`, `turbo-chat:chat-declined`, `turbo-chat:chat-left`, `turbo-chat:chat-closed`, `turbo-chat:chat-reopened`
 
-Primary partial override point:
-- `app/views/turbo_chat/chat_messages/_message.html.erb`
+Minimal browser listener:
 
-Keep `id="<%= dom_id(chat_message) %>"` on the message wrapper or Turbo replacements break.
+```js
+[
+  "turbo-chat:typing-started",
+  "turbo-chat:typing-ended",
+  "turbo-chat:message-sent",
+  "turbo-chat:mention",
+  "turbo-chat:invitation-accepted",
+  "turbo-chat:chat-invited",
+  "turbo-chat:chat-joined",
+  "turbo-chat:chat-declined",
+  "turbo-chat:chat-left",
+  "turbo-chat:chat-closed",
+  "turbo-chat:chat-reopened"
+].forEach(function (eventName) {
+  document.addEventListener(eventName, function (event) {
+    console.log(eventName, event.detail);
+  });
+});
+```
 
-## Internal Names
+Server-side notifications (`ActiveSupport::Notifications`):
 
-Use `TurboChat` in app code.
+- `emit_moderation_events`:
+  `turbo_chat.moderation.member_muted`,
+  `turbo_chat.moderation.member_unmuted`,
+  `turbo_chat.moderation.member_timed_out`,
+  `turbo_chat.moderation.member_timeout_cleared`,
+  `turbo_chat.moderation.member_banned`,
+  `turbo_chat.moderation.message_deleted`,
+  `turbo_chat.moderation.chat_closed`,
+  `turbo_chat.moderation.chat_reopened`
+- `emit_blocked_words_events`:
+  `turbo_chat.blocked_words.detected`,
+  `turbo_chat.blocked_words.rejected`,
+  `turbo_chat.blocked_words.scrambled`
 
-These are implementation identifiers used by the engine:
-- Engine namespace in source: `TurboChat`
-- Database table prefix: `turbo_chat_`
-- Browser event prefix: `turbo-chat:*`
-- `ActiveSupport::Notifications` prefix: `turbo_chat.*`
+Minimal Rails listener:
 
-Mount with `as: "turbo_chat"` and use `turbo_chat.*` route helpers.
+```ruby
+ActiveSupport::Notifications.subscribe(/turbo_chat\.(moderation|blocked_words)\./) do |*args|
+  event = ActiveSupport::Notifications::Event.new(*args)
+  Rails.logger.info("[TurboChat] #{event.name} #{event.payload.inspect}")
+end
+```
 
 ## Upgrade
 
@@ -317,10 +252,3 @@ bin/rails db:migrate
 - Ruby `>= 3.1`
 - Rails `>= 7.0`, `< 8.0`
 - `turbo-rails` `>= 1.4`, `< 3.0`
-- PostgreSQL or SQLite
-
-## Development
-
-```bash
-bundle exec rake test
-```

data/app/assets/config/turbo_chat_manifest.js

@@ -3,4 +3,5 @@
 //= link turbo_chat/shared.js
 //= link turbo_chat/messages.js
 //= link turbo_chat/realtime.js
+//= link turbo_chat/invite_picker.js
 //= link turbo_chat/lifecycle_events.js

data/app/assets/javascripts/turbo_chat/application.js

@@ -1,4 +1,5 @@
 //= require turbo_chat/shared
 //= require turbo_chat/messages
 //= require turbo_chat/realtime
+//= require turbo_chat/invite_picker
 //= require turbo_chat/lifecycle_events