Reactions Widgets and Documentation (#24)

- Added a Reactions view component
- Added documentation for using Reactions
- Added Open-source documentation section
- Improved the documentation intro

Author: coolsam726

README.md

@@ -1,4 +1,4 @@
-# Add Nested comments/replies to filament forms, infolists and resources
+# Filament Nested Comments & Emoji Reactions
 
 [![Latest Version on Packagist](https://img.shields.io/packagist/v/coolsam/nested-comments.svg?style=flat-square)](https://packagist.org/packages/coolsam/nested-comments)
 [![GitHub Tests Action Status](https://img.shields.io/github/actions/workflow/status/coolsam726/nested-comments/run-tests.yml?branch=main&label=tests&style=flat-square)](https://github.com/coolsam726/nested-comments/actions?query=workflow%3Arun-tests+branch%3Amain)
@@ -7,7 +7,6 @@
 [![Total Downloads](https://img.shields.io/packagist/dt/coolsam/nested-comments.svg?style=flat-square)](https://packagist.org/packages/coolsam/nested-comments)
 
 
-
 This package allows you to incorporate comments and replies in your Filament forms, infolists, pages, widgets etc, or even simply in your livewire components. Comment replies can be nested as deep as you want, using the Nested Set data structure. Additionally, the package comes with a Reactions feature to enable your users to react to any of your models (e.g comments or posts) with selected emoji reactions.
 
 ![image](https://github.com/user-attachments/assets/2900e2a4-9ad2-40e2-8819-2650b6d70803)
@@ -210,13 +209,144 @@ $record = Conference::find(1); // Get your record from the database then,
 <livewire:nested-comments::comments :record="$record"/>
 ```
 
+### Mentions
+The package uses Filament TipTap Editor which supports mentions. You can mention users in your comments by typing `@` followed by the user's name. The package will automatically resolve the user and send them a notification.
+You can customize how to fetch mentions by changing the `.closures.getMentionsUsing` closure in the config file. Two sample methods have been included in the main class for getting all users in the DB or only users that have been mentioned in the current thread (default). Customize this however you wish.
+
+**Get only users mentioned in the current thread:**
+
+```php
+[
+    'getMentionsUsing' => fn (
+            string $query,
+            Model $commentable
+        ) => app(\Coolsam\NestedComments\NestedComments::class)->getCurrentThreadUsers($query, $commentable),
+]
+```
+
+**Get all users from your database**
+
+```php
+[
+    'getMentionsUsing' => 'getMentionsUsing' => fn (string $query, Model $commentable) => app(\Coolsam\NestedComments\NestedComments::class)->getUserMentions($query),
+]
+```
+![image](https://github.com/user-attachments/assets/bd7a395a-fc32-4057-b6bc-24763132f555)
+
+
+## Usage: Emoji Reactions
+This package also allows you to add emoji reactions to your models. You can use the `HasReactions` trait to add reactions to any model. The reactions are stored in a separate table, and you can customize the reactions that are available via the configuration file.
+The Comments model that powers the comments feature described above already uses emoji reactions.
+
+In order to start using reactions for your model, add the `HasReactions` trait to your model. You can then use the `reactions` method to get the reactions for the model.
+
+```php
+use Coolsam\NestedComments\Traits\HasReactions;
+
+class Conference extends Model
+{
+    use HasReactions;
+
+    // ...
+}
+```
+The above trait adds the `react()` method to your model, allowing you to toggle a reaction for the model. You can also use the `reactions` method to get the reactions for the model.
+
+```php
+$conference = Conference::find(1);
+$comference->react('👍'); // React to the conference with a thumbs up emoji
+```
+You can also use the `reactions` method to get the reactions for the model.
+
+```php
+$conference = Conference::find(1);
+$reactions = $conference->reactions; // Get the reactions for the conference
+```
+Other useful methods include
+```php
+/**
+* @var \Illuminate\Database\Eloquent\Model&\Coolsam\NestedComments\Concerns\HasReactions $conference
+ */
+$conference = Conference::find(1);
+$conference->total_reactions; // Get the total number of reactions for the conference
+$conference->reactions_counts; // Get the no of reactions for each emoji for the model
+$conference->my_reactions; // Get the reactions for the current user
+$conference->emoji_reactors // Get the list of users who reacted to the model, grouped by emoji
+$conference->isAllowed('👍') // check if the app allows the user to react with the specified emoji
+$conference->reactions_map // return the map of all the reactions for the model, grouped by emoji. This tells you the number of reactions for each emoji, and whether the current user has reacted with that emoji
+```
+To interact with the methods above with ease within and even outside Filament, this package comes with the following handy components:
+
+### Reactions Infolist Entry
+```php
+use Coolsam\NestedComments\Filament\Infolists\ReactionsEntry;
+
+public static function infolist(Infolist $infolist): Infolist
+{
+    return $infolist
+        ->schema([
+            Section::make('Basic Details')
+                ->schema([
+                    TextEntry::make('name'),
+                    TextEntry::make('start_date')
+                        ->dateTime(),
+                    TextEntry::make('end_date')
+                        ->dateTime(),
+                    TextEntry::make('created_at')
+                        ->dateTime(),
+                        // Add the reactions entry
+                    ReactionsEntry::make('reactions')->columnSpanFull(),
+                ])->columns(4),
+        ]);
+}
+```
+![image](https://github.com/user-attachments/assets/06ae7e76-1668-4e92-9a4f-a125f7d94b03)
+
+### Reactions Blade Component
+Just include the blade component anywhere in your blade file and pass the model record to it.
+```php
+$record = Conference::find(1); // Get your record from the database then,
+```
+In your view:
+```bladehtml
+<x-nested-comments::reactions :record="$record"/>
+```
+
+### Reactions Livewire Component
+Similar to the blade component, you can use the Livewire component anywhere in your Livewire component and pass the model record to it.
+```php
+$record = Conference::find(1); // Get your record from the database then,
+```
+In your view:
+```bladehtml
+<livewire:nested-comments::reaction-panel :record="$record"/>
+```
+The two components can be used anywhere, in resource pages, custom pages, actions, form fields, widgets, livewire components or just plain blade views. Here is a sample screenshot of how the components will be rendered:
+![image](https://github.com/user-attachments/assets/0162f294-0477-454c-ae5c-67424edc207f)
+
+
+## Package Customization
+You can customize the package by changing most of the default values in the config file after publishing it.
 
 ## Testing
 
 ```bash
 composer test
 ```
 
+## Open Source Dependencies
+
+This package uses the following awesome open source packages, among many others under the hood:
+
+* [Filament](https://filamentphp.com/)
+* [Livewire](https://livewire.laravel.com/)
+* [Laravel](https://laravel.com/)
+* [AlpineJS](https://alpinejs.dev/)
+* [Laravel NestedSet](https://github.com/lazychaser/laravel-nestedset)
+* [Filament Tiptap Editor](https://github.com/awcodes/filament-tiptap-editor)
+
+I am grateful for the work that has been put into these packages. They have made it possible to build this package in a short time.
+
 ## Changelog
 
 Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.

resources/views/components/reactions.blade.php

@@ -0,0 +1,10 @@
+@props([
+    'record'
+])
+@if(isset($record))
+    @if(app(\Coolsam\NestedComments\NestedComments::class)->classHasTrait($record, \Coolsam\NestedComments\Concerns\HasReactions::class))
+        <livewire:nested-comments::reaction-panel :record="$record"/>
+    @else
+        <p>__('The current record is not configured for reactions. Please include the `HasReactions` trait to the model.')</p>
+    @endif
+@endif

resources/views/filament/infolists/reactions-entry.blade.php

@@ -0,0 +1,3 @@
+<x-dynamic-component :component="$getEntryWrapperView()" :entry="$entry">
+    <x-nested-comments::reactions :record="$getRecord()" />
+</x-dynamic-component>

src/Concerns/HasReactions.php

@@ -32,18 +32,20 @@ public function getReactionsCountsAttribute()
         });
     }
 
-    public function getEmojiReactors()
+    public function getEmojiReactorsAttribute()
     {
-        return $this->reactions()->get(['id', 'emoji', 'user_id', 'guest_id'])->groupBy('emoji')->map(function ($item) {
-            return $item->map(function ($reaction) {
-                return [
-                    'id' => $reaction->getKey(),
-                    'user_id' => $reaction->getAttribute('user_id'),
-                    'guest_id' => $reaction->getAttribute('guest_id'),
-                    'name' => $reaction->getAttribute('user_id') ? call_user_func(config('nested-comments.closures.getUserNameUsing'), $reaction->getAttribute('user')) : $reaction->getAttribute('guest_name'),
-                ];
+        return $this->reactions()->get(['id', 'emoji', 'user_id', 'guest_id', 'guest_name'])
+            ->groupBy('emoji')
+            ->map(function (Collection $item) {
+                return $item->map(function ($reaction) {
+                    return [
+                        'id' => $reaction->getKey(),
+                        'user_id' => $reaction->getAttribute('user_id'),
+                        'guest_id' => $reaction->getAttribute('guest_id'),
+                        'name' => $reaction->getAttribute('user_id') ? call_user_func(config('nested-comments.closures.getUserNameUsing'), $reaction->getAttribute('user')) : $reaction->getAttribute('guest_name'),
+                    ];
+                });
             });
-        });
     }
 
     public function getMyReactionsAttribute(): array

src/Filament/Infolists/ReactionsEntry.php

@@ -0,0 +1,11 @@
+<?php
+
+namespace Coolsam\NestedComments\Filament\Infolists;
+
+use Filament\Infolists\Components\Entry;
+
+class ReactionsEntry extends Entry
+{
+    /** @phpstan-ignore-next-line */
+    protected string $view = 'nested-comments::filament.infolists.reactions-entry';
+}