Mention Feature

[thijskuilman]

Description

This PR integrates the mention extension. I wanted to implement this feature to support user mentions in my project, and noticed that others have expressed interest in a mention plugin as well. I have tried to make this feature as flexible as possible, since I realize it can be used in many ways. That's why you'll have full control over the mention suggestions and the data passed along.

Two types of mentions: static and dynamic

Ths implementation supports two approaches for providing mention suggestions:

• Static Suggestions: Pass a predefined array of mention suggestions directly.
• Dynamic Suggestions: Use the ->getMentionItemsUsing(function (string $query)) method to retrieve suggestions dynamically based on user input. This is perfect for when you want to fetch results from the database or from an API.

For detailed instructions and examples, please refer to the updated README.

Documentation

Please read the documentation to learn more about the usage of this feature.

How to test

I invite you to check out the README.md to read the instructions before you start testing. I have also added some quick examples below to make it easier for you to test:

Test 1

Pass a hardcoded array. You may use MentionItem as a convenience , but that's not required:

TiptapEditor::make(name: 'content')
  ->mentionItems([
      new MentionItem(id: 1, label: 'Apple'),
      new MentionItem(id: 2, label: 'Banana'),
      new MentionItem(id: 3, label: 'Cherry'),
      new MentionItem(id: 4, label: 'Date'),
      new MentionItem(id: 5, label: 'Elderberry'),
      new MentionItem(id: 6, label: 'Fig'),
      new MentionItem(id: 7, label: 'Grape'),
      new MentionItem(id: 8, label: 'Honeydew'),
      new MentionItem(id: 9, label: 'Indian Fig'),
      new MentionItem(id: 10, label: 'Jackfruit'),
  ])

Result

Test 2: Static User search with avatars

Let's add some images to our static mention items!

TiptapEditor::make(name: 'content')
  ->mentionItems([
      new MentionItem(id: 1, label: 'Jane', image: 'https://i.pravatar.cc/150?img=1', roundedImage: true),
      new MentionItem(id: 2, label: 'John', image: 'https://i.pravatar.cc/150?img=2', roundedImage: true),
      new MentionItem(id: 3, label: 'Alice', image: 'https://i.pravatar.cc/150?img=3', roundedImage: true),
      new MentionItem(id: 4, label: 'Bob', image: 'https://i.pravatar.cc/150?img=4', roundedImage: true),
      new MentionItem(id: 5, label: 'Eve', image: 'https://i.pravatar.cc/150?img=5', roundedImage: true),
      new MentionItem(id: 6, label: 'Charlie', image: 'https://i.pravatar.cc/150?img=6', roundedImage: true),
      new MentionItem(id: 7, label: 'Diana', image: 'https://i.pravatar.cc/150?img=7', roundedImage: true),
      new MentionItem(id: 8, label: 'Frank', image: 'https://i.pravatar.cc/150?img=8', roundedImage: true),
      new MentionItem(id: 9, label: 'Grace', image: 'https://i.pravatar.cc/150?img=9', roundedImage: true),
      new MentionItem(id: 10, label: 'Hank', image: 'https://i.pravatar.cc/150?img=10', roundedImage: true),
  ])

Result

Test 3: Dynamic User search with API

Make sure you have a User model with a name that can be searched. In the code example, only getMentionItemsUsing is required to make this work. However, I have added some additional customization methods so you can see how those work as well.

TiptapEditor::make(name: 'content')
  ->getMentionItemsUsing(fn (string $query) =>
      User::whereLike('full_name', "%{$query}%")
          ->limit(5)
          ->get()
          ->map(fn (User $user) => new MentionItem(
              id: $user->id,
              label: $user->full_name,
              image: $user->profile_image_url
          ))
          ->toArray()
  )
  ->mentionDebounce(debounceInMs: 300)
  ->maxMentionItems(5)
  ->mentionItemsPlaceholder("Search by name...")
  ->emptyMentionItemsMessage('No users found!')
  ->mentionTrigger('@')

Result

Test 4: Add some custom data

You might want to pass some additional data, for example the type of the mentions. You can do this by passing a data array:

TiptapEditor::make(name: 'content')
    ->mentionItems([
        new MentionItem(
            id: 1,
            label: 'Apple',
            data: ['mentionType' => 'fruit']
        ),
    ])

Output result

Test 5: Attach a URL

You can attach a URL which will be used in the output. For example:

TiptapEditor::make(name: 'content')
  ->mentionItems([
      new MentionItem(
          id: 1,
          label: 'Filament',
          href: 'https://filamentphp.com',
          target: '_blank'
      ),
  ])

Output result (HTML)

<a href="https://filamentphp.com" target="_blank" data-mention-id="1">Filament</a>

[awcodes]

Thank you for the detailed PR. It's a lot and I'll review as best I can as soon as I can.

[thijskuilman]

Thank you for the detailed PR. It's a lot and I'll review as best I can as soon as I can.

I just saw your update on X and I wish you a speedy recovery first and foremost. If you have any questions once you're able to review this (it's a pretty big PR indeed) then ask away. 👍

[awcodes]

Converting this to a draft for now since it looks like you are sill working on it. When you are feel free to change it back.

[thijskuilman]

@awcodes I was integrating user mentions in our project, so along the way I made some additional adjustments. It's all ready now! :)

I notice the CI pipelines are failing since this commit, but I can't see why. Is there anything obvious I miss? 🤔

[awcodes]

Can you merge in the latest updates from 3.x and resolve the conflicts please?

[thijskuilman]

Can you merge in the latest updates from 3.x and resolve the conflicts please?

@awcodes All done!