### Install Package

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/_autodocs/07-quick-start.md

Run this command to install the package via Composer.

```bash
composer require awcodes/filament-tiptap-editor:"^3.0"
```

--------------------------------

### Install Dev Version

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/_autodocs/10-service-provider.md

Use these commands if installing the package from the development branch.

```bash
composer require awcodes/filament-tiptap-editor:dev-main
composer dump-autoload
```

--------------------------------

### Install Filament Tiptap Editor Package

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/README.md

Use composer to install the package. Ensure you specify the version for compatibility.

```bash
composer require awcodes/filament-tiptap-editor:"^3.0"
```

--------------------------------

### Using the TiptapConverter Facade

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/_autodocs/10-service-provider.md

Example of importing and using the TiptapConverter facade to convert content to HTML.

```php
use FilementTiptapEditor\Facades\TiptapConverter;

TiptapConverter::asHTML($content);
```

--------------------------------

### Database Migration and Model Setup

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/_autodocs/07-quick-start.md

Database configuration for HTML, JSON, and Text output formats.

```php
// Migration
$table->text('content')->nullable();

// Model - no cast needed
```

```php
// Migration
$table->json('content')->nullable();

// Model
protected $casts = [
    'content' => 'json',
];
```

```php
// Migration
$table->text('content')->nullable();

// Model - no cast needed
```

--------------------------------

### Configure Custom Theme

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/_autodocs/07-quick-start.md

Setup required CSS and Tailwind configuration for the editor.

```css
@import '<path-to-vendor>/awcodes/filament-tiptap-editor/resources/css/plugin.css';
```

```js
content: [
    ...
    '<path-to-vendor>/awcodes/filament-tiptap-editor/resources/**/*.blade.php',
]
```

```js
module.exports = {
    plugins: {
        'tailwindcss/nesting': {},
        tailwindcss: {},
        autoprefixer: {},
    },
}
```

--------------------------------

### Define Custom Extension Structure

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/_autodocs/05-configuration.md

Example structure for registering a custom extension with an ID, name, button component, parser class, and optional source file.

```php
'extensions' => [
    [
        'id' => 'hero',              // Unique identifier
        'name' => 'Hero',            // Display name
        'button' => 'tools.hero',    // Blade component path
        'parser' => \App\TiptapExtensions\Hero::class,  // PHP parser
        'source' => 'resources/js/tiptap/extensions.js', // Optional JS
    ],
]
```

--------------------------------

### Get Tiptap Editor Instance

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/_autodocs/02-tiptap-converter.md

Lazily initializes and returns the Tiptap editor instance with all registered extensions.

```php
$editor = tiptap_converter()->getEditor();
$editor->setContent($html)->getJSON();
```

--------------------------------

### Regenerate Autoload

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/_autodocs/10-service-provider.md

Run this command to ensure the package is properly installed and autoloaded.

```bash
composer dump-autoload
```

--------------------------------

### Mention Search Strategy

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/README.md

Configure the search strategy for mentions. Defaults to 'starts with', but can be set to 'Tokenized' for multi-keyword matching.

```php
TiptapEditor::make(name: 'content')
    // You can also use MentionSearchStrategy::Tokenized
    ->mentionSearchStrategy(MentionSearchStrategy::StartsWith)
```

--------------------------------

### Styling Tiptap Output

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/_autodocs/07-quick-start.md

Example CSS using Tailwind CSS @apply directives to style rendered Tiptap content.

```css
.tiptap-content {
    & h1 { @apply text-3xl font-bold; }
    & h2 { @apply text-2xl font-bold mt-6 mb-3; }
    & p { @apply my-3; }
    & blockquote { @apply border-l-4 border-gray-300 pl-4 italic text-gray-600; }
    & code { @apply bg-gray-100 px-2 py-1 rounded text-sm; }
    & pre { @apply bg-gray-900 text-gray-100 p-4 rounded overflow-auto; }
}
```

--------------------------------

### Example JSON API Response

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/_autodocs/09-data-classes.md

The expected JSON structure for a mention item returned by the API.

```json
[
  {
    "id": 1,
    "label": "John Doe",
    "type": null,
    "href": null,
    "target": "_blank",
    "image": "https://example.com/avatars/john.jpg",
    "roundedImage": false,
    "data": {}
  }
]
```

--------------------------------

### PHP Parser for Custom Extension

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/README.md

Create a PHP version of your custom extension for database reading and rendering. This example defines a PHP `Hero` node.

```php
namespace App\TiptapExtensions;

use Tiptap\Core\Node;

class Hero extends Node
{
    public static $name = 'hero';
    ...
}

```

--------------------------------

### Configure Tiptap Editor Field

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/README.md

Example of how to configure the TiptapEditor field within a Filament form, including setting profiles, tools, disk, directory, file types, max size, output format, and content width.

```php
use FilamentTiptapEditor\TiptapEditor;
use FilamentTiptapEditor\Enums\TiptapOutput;

TiptapEditor::make('content')
    ->profile('default|simple|minimal|none|custom')
    ->tools([]) // individual tools to use in the editor, overwrites profile
    ->disk('string') // optional, defaults to config setting
    ->directory('string or Closure returning a string') // optional, defaults to config setting
    ->acceptedFileTypes(['array of file types']) // optional, defaults to config setting
    ->maxSize('integer in KB') // optional, defaults to config setting
    ->output(TiptapOutput::Html) // optional, change the format for saved data, default is html
    ->maxContentWidth('5xl')
    ->required();
```

--------------------------------

### Publish Configuration

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/_autodocs/10-service-provider.md

Use this command to publish the package configuration file to your application.

```bash
php artisan vendor:publish --tag="filament-tiptap-editor-config"
```

--------------------------------

### Blade Components

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/_autodocs/10-service-provider.md

Examples of Blade components registered by the package for use in views.

```blade
<x-filament-tiptap-editor::table-of-contents :headings="$toc" />
<x-filament-tiptap-editor::tiptap-editor />
<x-filament-tiptap-editor::button />
{{-- etc. --}}
```

--------------------------------

### Initialize Basic Tiptap Editor

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/_autodocs/00-index.md

Basic implementation of the editor field in a Filament form.

```php
TiptapEditor::make('content')->required()
```

--------------------------------

### Project File Structure

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/_autodocs/00-index.md

Visual representation of the package directory layout.

```text
awcodes/filament-tiptap-editor/
├── src/
│   ├── TiptapEditor.php                 # Main form field
│   ├── TiptapConverter.php              # Content conversion
│   ├── TiptapBlock.php                  # Block base class
│   ├── Enums/
│   │   ├── TiptapOutput.php
│   │   ├── TippyPlacement.php
│   │   └── MentionSearchStrategy.php
│   ├── Data/
│   │   └── MentionItem.php
│   ├── Concerns/                        # Traits
│   ├── Extensions/                      # Tiptap nodes/marks
│   ├── Actions/                         # Modal actions
│   └── Facades/
│       └── TiptapConverter.php
├── config/
│   └── filament-tiptap-editor.php
├── resources/
│   ├── css/
│   ├── js/
│   └── views/
└── composer.json
```

--------------------------------

### Configure Media Uploads

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/_autodocs/00-index.md

Define disk, directory, and file size constraints for media uploads.

```php
TiptapEditor::make('content')
    ->disk('public')
    ->directory('images')
    ->maxSize(2048)
```

--------------------------------

### TiptapEditor::make

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/_autodocs/00-index.md

Initializes a new Tiptap editor instance within a Filament form schema.

```APIDOC
## TiptapEditor::make(string $name)

### Description
Creates a new instance of the Tiptap editor component.

### Methods
- `profile(string $name)`: Sets the editor profile.
- `output(TiptapOutput $output)`: Sets the output format (Html, Json, or Text).
- `required()`: Marks the field as required.
- `blocks(array $blocks)`: Registers custom blocks for the editor.
- `mentionItems(array $items)`: Sets static mention items.
- `getMentionItemsUsing(callable $callback)`: Sets a callback to fetch mention items dynamically.
```

--------------------------------

### Converting MentionItem to Array

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/_autodocs/09-data-classes.md

Usage of the toArray method to prepare data for serialization, including a collection mapping example.

```php
$item = new MentionItem(
    id: 1,
    label: 'Alice Smith',
    href: 'https://example.com/users/alice',
    image: 'https://example.com/avatars/alice.jpg',
    roundedImage: true,
    data: ['department' => 'Engineering', 'verified' => true]
);

$array = $item->toArray();
// Returns:
// [
//     'id' => 1,
//     'label' => 'Alice Smith',
//     'type' => null,
//     'href' => 'https://example.com/users/alice',
//     'target' => '_blank',
//     'image' => 'https://example.com/avatars/alice.jpg',
//     'roundedImage' => true,
//     'data' => ['department' => 'Engineering', 'verified' => true],
// ]
```

```php
$items = collect($mentionItems)
    ->map(fn ($item) => $item->toArray())
    ->toArray();
```

--------------------------------

### Create a Custom Tiptap Block Class

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/README.md

Define a custom block by extending `TiptapBlock`. Specify the preview and rendered view paths, and define the form schema for block settings.

```php
use FilamentTiptapEditor	TiptapBlock;

class BatmanBlock extends TiptapBlock
{
    public string $preview = 'blocks.previews.batman';

    public string $rendered = 'blocks.rendered.batman';

    public function getFormSchema(): array
    {
        return [
            TextInput::make('name'),
            TextInput::make('color'),
            Select::make('side')
                ->options([
                    'Hero' => 'Hero',
                    'Villain' => 'Villain',
                ])
                ->default('Hero')
        ];
    }
}
```

--------------------------------

### Custom CSS for Tiptap Extensions

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/README.md

Add custom CSS for your extensions, scoped to the parent class of `.tiptap-content`. This example styles a `.hero-block`.

```css
.tiptap-content {
    .hero-block {
        ...
    }
}

```

--------------------------------

### Publishing Assets via Artisan

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/_autodocs/10-service-provider.md

Commands to publish CSS, views, configuration, or all package assets to the local project.

```bash
# CSS
php artisan vendor:publish --tag="filament-tiptap-editor-assets"

# Views
php artisan vendor:publish --tag="filament-tiptap-editor-views"

# Config
php artisan vendor:publish --tag="filament-tiptap-editor-config"

# Everything
php artisan vendor:publish --provider="FilementTiptapEditor\FilamentTiptapEditorServiceProvider"
```

--------------------------------

### Inject TiptapConverter

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/_autodocs/10-service-provider.md

Demonstrates dependency injection of the TiptapConverter into a controller to convert content to HTML.

```php
namespace App\Http\Controllers;

use FilementTiptapEditor\TiptapConverter;

class ArticleController
{
    public function show(Article $article, TiptapConverter $converter)
    {
        $html = $converter->asHTML($article->content);
        
        return view('articles.show', ['html' => $html]);
    }
}
```

--------------------------------

### Custom JavaScript Tiptap Extension

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/README.md

Define a custom Tiptap node extension in JavaScript. This example shows the basic structure for creating a 'hero' node.

```js
import { Node, mergeAttributes } from "@tiptap/core";

const Hero = Node.create({
    name: "hero",
    ...
})

export default Hero

```

--------------------------------

### Configure Grid Layouts

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/_autodocs/07-quick-start.md

Define available grid layout options for the editor instance.

```php
TiptapEditor::make('content')
    ->gridLayouts([
        'two-columns',
        'three-columns',
        'fixed-two-columns',
        'asymmetric-left-thirds',
    ])
```

--------------------------------

### Set Custom Initial Document

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/_autodocs/01-tiptap-editor.md

Defines the initial document content using a JSON or HTML string.

```php
TiptapEditor::make('content')
    ->customDocument('{"type":"doc","content":[...]}')
```

--------------------------------

### Configure Output Format

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/_autodocs/05-configuration.md

Set the default storage format for the editor content.

```php
'output' => FilamentTiptapEditor\Enums\TiptapOutput::Html,
```

--------------------------------

### Toolbar Button for Custom Extension

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/README.md

Create a dedicated view component for your custom extension's toolbar button. This example uses a `x-filament-tiptap-editor::button` component for a 'Hero' button.

```blade
<x-filament-tiptap-editor::button
    label="Hero"
    active="hero"
    action="editor().commands.toggleHero()"
>
    <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24"><path fill="currentColor" d="M5 21q-.825 0-1.413-.588T3 19V5q0-.825.588-1.413T5 3h14q.825 0 1.413.588T21 5v14q0 .825-.588 1.413T19 21H5Zm0-2h14v-5H5v5Z"/></svg>
    
    <span class="sr-only">{{ $label }}</span>
</x-filament-tiptap-editor::button>

```

--------------------------------

### Initialize TiptapEditor Component

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/_autodocs/00-index.md

Use the TiptapEditor component within a Filament form schema to render the editor.

```php
use FilementTiptapEditor\TiptapEditor;

TiptapEditor::make('content')
    ->profile('default')
    ->output(TiptapOutput::Html)
    ->required()
```

--------------------------------

### Define a basic static mention

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/_autodocs/09-data-classes.md

Initialize a simple MentionItem and pass it to the TiptapEditor component.

```php
use FilamentTiptapEditor\Data\MentionItem;

$item = new MentionItem(
    id: 1,
    label: 'John Doe'
);

TiptapEditor::make('content')
    ->mentionItems([$item])
```

--------------------------------

### Configure Tiptap Editor Actions

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/_autodocs/05-configuration.md

Define custom action classes for media, links, grids, and oembeds in the configuration file.

```php
'media_action' => FilamentTiptapEditor\Actions\MediaAction::class,
'edit_media_action' => FilamentTiptapEditor\Actions\EditMediaAction::class,
'link_action' => FilamentTiptapEditor\Actions\LinkAction::class,
'grid_builder_action' => FilamentTiptapEditor\Actions\GridBuilderAction::class,
'oembed_action' => FilamentTiptapEditor\Actions\OEmbedAction::class,
```

--------------------------------

### Accessing MentionItem Properties

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/_autodocs/09-data-classes.md

Demonstrates instantiation and direct property access for a MentionItem object.

```php
$item = new MentionItem(id: 1, label: 'John Doe');

$item->id;              // int
$item->label;           // string
$item->type;            // string|null
$item->href;            // string|null
$item->target;          // string
$item->image;           // string|null
$item->roundedImage;    // bool
$item->data;            // array
```

--------------------------------

### Implement Mentions

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/_autodocs/00-index.md

Provide a callback to fetch and format mentionable items.

```php
TiptapEditor::make('content')
    ->getMentionItemsUsing(fn ($query) => User::search($query)->get()->map(...)->toArray())
```

--------------------------------

### Extend Filament Tiptap Editor Service Provider

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/_autodocs/10-service-provider.md

Create a custom provider class extending the base provider to override register or boot methods.

```php
namespace App\Providers;

use FilementTiptapEditor\FilamentTiptapEditorServiceProvider as BaseProvider;

class TiptapEditorServiceProvider extends BaseProvider
{
    public function register()
    {
        parent::register();
        
        // Custom registration logic
    }
    
    public function boot()
    {
        parent::boot();
        
        // Custom boot logic
    }
}
```

--------------------------------

### Configure Tippy Toolbar Placement

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/README.md

Configure the placement of the tippy toolbar using the 'tippyPlacement' method with predefined placement options.

```php
TiptapEditor::make('content')
    ->tippyPlacement(TippyPlacement::Left)
```

--------------------------------

### Configure Media Upload Settings

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/_autodocs/05-configuration.md

Define global settings for file uploads, including disk, directory, and image processing constraints.

```php
'accepted_file_types' => ['image/jpeg', 'image/png', 'image/webp', 'image/svg+xml', 'application/pdf'],
'disk' => 'public',
'directory' => 'images',
'visibility' => 'public',
'preserve_file_names' => false,
'max_file_size' => 2042,  // KB
'min_file_size' => 0,     // KB
'image_resize_mode' => null,
'image_crop_aspect_ratio' => null,
'image_resize_target_width' => null,
'image_resize_target_height' => null,
'use_relative_paths' => true,
```

--------------------------------

### Service container resolution methods

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/_autodocs/08-facades-and-helpers.md

Demonstrates equivalent ways to resolve the TiptapConverter from the service container.

```php
// These are equivalent:
app('tiptap-converter')
app(\FilementTiptapEditor\TiptapConverter::class)
tiptap_converter()
```

--------------------------------

### Configure mention with avatar and link

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/_autodocs/09-data-classes.md

Include optional image and URL properties to enhance the mention display.

```php
$item = new MentionItem(
    id: 1,
    label: 'John Doe',
    href: 'https://example.com/users/john-doe',
    image: 'https://example.com/avatars/john.jpg',
    roundedImage: true,
);
```

--------------------------------

### Publish Blade Components

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/_autodocs/10-service-provider.md

Use this command to publish the package views for customization.

```bash
php artisan vendor:publish --tag="filament-tiptap-editor-views"
```

--------------------------------

### Configure Editor Menus

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/_autodocs/05-configuration.md

Settings to toggle floating, bubble, and toolbar menus, and define the tools available in each.

```php
'disable_floating_menus' => false,
'disable_bubble_menus' => false,
'disable_toolbar_menus' => false,

'bubble_menu_tools' => ['bold', 'italic', 'strike', 'underline', 'superscript', 'subscript', 'lead', 'small', 'link'],
'floating_menu_tools' => ['media', 'grid-builder', 'details', 'table', 'oembed', 'code-block', 'blocks'],
```

--------------------------------

### Tiptap Block Preview Blade View

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/README.md

Create a standard Blade view for the block's preview. Note that Livewire components cannot be used in block previews due to the `wire:ignore` requirement.

```html
<div class="flex items-center gap-6">
    <div class="text-5xl">
        @php
            echo match($name) {
                'robin' => '🐤',
                'ivy' => '🥀',
                'joker' => '🤡',
                default => '🦇'
            }
        @endphp
    </div>
    <div>
        <p>Name: {{ $name }}</p>
        <p style="color: {{ $color }};">Color: {{ $color }}</p>
        <p>Side: {{ $side ?? 'Good' }}</p>
    </div>
</div>
```

--------------------------------

### Define and Use Custom Profile

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/_autodocs/07-quick-start.md

Configures a custom profile in the configuration file and applies it to the editor instance.

```php
'profiles' => [
    'blog' => [
        'heading', '|',
        'bold', 'italic', 'link', '|',
        'bullet-list', 'ordered-list', '|',
        'media', 'code-block',
    ],
]
```

```php
TiptapEditor::make('content')
    ->profile('blog')
```

--------------------------------

### Configure Mentions

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/_autodocs/00-index.md

Define mention items or use a callback to fetch them dynamically.

```php
TiptapEditor::make('content')
    ->mentionItems([
        new MentionItem(id: 1, label: 'John Doe'),
    ])
    ->getMentionItemsUsing(function (string $query) { ... })
```

--------------------------------

### Define Toolbar Profiles

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/_autodocs/04-types.md

Configure toolbar groups and available tools within the filament-tiptap-editor.php configuration file.

```php
'profiles' => [
    'profile_name' => [
        'bold',
        'italic',
        '|',  // Separator for toolbar groups
        'link',
        'media',
    ],
]
```

--------------------------------

### Package Configuration

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/_autodocs/00-index.md

Global settings for the editor, including output format, storage, and profiles, defined in config/filament-tiptap-editor.php.

```php
return [
    'output' => TiptapOutput::Html,              // Html, Json, or Text
    'direction' => 'ltr',                         // ltr or rtl
    'max_content_width' => '5xl',                 // Tailwind size
    'disk' => 'public',                           // Storage disk
    'directory' => 'images',                      // Upload directory
    'max_file_size' => 2042,                      // KB
    'profiles' => [
        'default' => [ /* tools */ ],
        'simple' => [ /* tools */ ],
        'minimal' => [ /* tools */ ],
    ],
    'preset_colors' => [],                        // Color picker colors
];
```

--------------------------------

### Configure minimum file size

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/_autodocs/06-traits.md

Sets the minimum required file size in kilobytes.

```php
TiptapEditor::make('content')
    ->minSize(10)  // At least 10KB
```

--------------------------------

### Configure Custom Storage

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/_autodocs/07-quick-start.md

Sets dynamic storage paths and visibility for uploaded files.

```php
TiptapEditor::make('content')
    ->disk('s3')
    ->directory(fn () => 'user-' . auth()->id() . '/uploads')
    ->visibility('private')
```

--------------------------------

### Fluent Configuration Chaining

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/_autodocs/07-quick-start.md

Use the fluent API to configure editor settings such as output format, storage, and validation.

```php
TiptapEditor::make('content')
    ->profile('default')
    ->output(TiptapOutput::Json)
    ->disk('public')
    ->directory('articles')
    ->maxSize(2048)
    ->disableBubbleMenus()
    ->mentionItems($mentions)
    ->mergeTags(['author', 'date'])
    ->required()
```

--------------------------------

### Creating Tiptap Blocks

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/_autodocs/10-service-provider.md

Artisan command to scaffold a new TiptapBlock class in the application.

```bash
php artisan make:tiptap-block {name}
```

--------------------------------

### Simple Placeholder

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/_autodocs/07-quick-start.md

Set a default placeholder text for the editor.

```php
TiptapEditor::make('content')
    ->placeholder('Write your article...')
```

--------------------------------

### Configure Minimal Branded Editor

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/_autodocs/05-configuration.md

Customize the editor with specific tools, brand colors, and menu behavior.

```php
// config/filament-tiptap-editor.php
return [
    'profiles' => [
        'marketing' => [
            'bold', 'italic', 'link', 'color', 'highlight',
            '|',
            'heading', 'blockquote',
        ],
    ],
    'preset_colors' => [
        'brand-primary' => '#2563eb',
        'brand-secondary' => '#10b981',
    ],
    'bubble_menu_tools' => ['bold', 'italic', 'link'],
    'disable_floating_menus' => true,
];
```

--------------------------------

### getExtensions()

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/_autodocs/02-tiptap-converter.md

Returns the full array of Tiptap extensions currently configured for the editor.

```APIDOC
## getExtensions()

### Description
Returns the full array of Tiptap extensions used by the editor, including core extensions, custom marks, and custom nodes.

### Returns
- **array** - Extension instances
```

--------------------------------

### getOutput()

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/_autodocs/06-traits.md

Returns the resolved output format based on instance settings or configuration defaults.

```APIDOC
## getOutput()

### Description
Returns the resolved output format, from instance or config.

### Returns
- **TiptapOutput** - The resolved output format
```

--------------------------------

### Render Block Preview in Editor

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/_autodocs/03-tiptap-block.md

Implement getPreview to return the HTML string used for the block's preview within the editor UI.

```php
class BatmanBlock extends TiptapBlock {
    public string $preview = 'blocks.previews.batman';
    
    public function getPreview(?array $data = null, ?Component $component = null): string {
        return view($this->preview, [
            ...$data,
            'component' => $component,
        ])->render();
    }
}
```

--------------------------------

### Media Upload Configuration

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/README.md

Configure settings for media uploads, including accepted file types, storage disk, directory, visibility, and maximum file size.

```php
[
    'accepted_file_types' => ['image/jpeg', 'image/png', 'image/webp', 'image/svg+xml', 'application/pdf'],
    'disk' => 'public',
    'directory' => 'images',
    'visibility' => 'public',
    'preserve_file_names' => false,
    'max_file_size' => 2042,
    'image_crop_aspect_ratio' => null,
    'image_resize_target_width' => null,
    'image_resize_target_height' => null,
]
```

--------------------------------

### Configure floating menu tools

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/_autodocs/06-traits.md

Define the specific tools to display within the floating menu.

```php
TiptapEditor::make('content')
    ->floatingMenuTools(['media', 'link', 'table'])
```

--------------------------------

### Chain methods using the TiptapConverter container instance

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/_autodocs/08-facades-and-helpers.md

Access the service via the container to enable method chaining, such as configuring merge tags before conversion.

```php
use FilementTiptapEditor\TiptapConverter;

$converter = app(TiptapConverter::class);
$html = $converter
    ->mergeTagsMap(['name' => 'John'])
    ->asHTML($content);
```

--------------------------------

### Configure Default Floating and Bubble Menu Tools

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/README.md

Overwrite default tools for the floating and bubble menus via the config file using 'floating_menu_tools' and 'bubble_menu_tools' keys.

```php
'floating_menu_tools' => ['media', 'grid-builder', 'details', 'table', 'oembed', 'code-block'],
'bubble_menu_tools' => ['bold', 'italic', 'strike', 'underline', 'superscript', 'subscript', 'lead', 'small', 'link'],
```

--------------------------------

### Configure bubble menu tools

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/_autodocs/06-traits.md

Define the specific tools to display within the bubble menu.

```php
TiptapEditor::make('content')
    ->bubbleMenuTools(['bold', 'italic', 'link'])
```

--------------------------------

### Configure JSON Output with Blocks

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/_autodocs/05-configuration.md

Set the editor to output JSON format and include block support, requiring appropriate database casting.

```php
// config/filament-tiptap-editor.php
return [
    'output' => FilamentTiptapEditor\Enums\TiptapOutput::Json,
    'profiles' => [
        'default' => [
            // ... tools
            'blocks',
        ],
    ],
];

// In migration:
// $table->json('content')->nullable();

// In model:
// protected $casts = ['content' => 'json'];
```

--------------------------------

### Configure Custom Extensions

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/_autodocs/05-configuration.md

Settings for defining custom extension scripts, styles, and definitions.

```php
'extensions_script' => null,
'extensions_styles' => null,
'extensions' => [],
```

--------------------------------

### profile(string $profile)

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/_autodocs/01-tiptap-editor.md

Sets the editor toolbar profile (e.g., default, simple, minimal).

```APIDOC
## profile(string $profile)

### Description
Sets the editor toolbar profile to control available tools.

### Parameters
- **profile** (string) - Required - Profile name from config

### Returns
- **static** - Fluent interface
```

--------------------------------

### Set menu placement via Tippy.js

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/_autodocs/06-traits.md

Configure the positioning of the menu using TippyPlacement enums or string values.

```php
use FilementTiptapEditor\Enums\TippyPlacement;

TiptapEditor::make('content')
    ->tippyPlacement(TippyPlacement::Left)
    // ->tippyPlacement('top-start')
```

--------------------------------

### Configure Grid Layouts for Tiptap Editor

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/README.md

Customize the available grid layouts in the dropdown by passing an array of layout names to the `gridLayouts()` method.

```php
TiptapEditor::make('content')
    ->gridLayouts([
        'two-columns',
        'three-columns',
        'four-columns',
        'five-columns',
        'fixed-two-columns',
        'fixed-three-columns',
        'fixed-four-columns',
        'fixed-five-columns',
        'asymmetric-left-thirds',
        'asymmetric-right-thirds',
        'asymmetric-left-fourths',
        'asymmetric-right-fourths',
    ]);
```

--------------------------------

### Configure Text Output

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/_autodocs/07-quick-start.md

Set the editor to output plain text.

```php
TiptapEditor::make('content')
    ->output(TiptapOutput::Text)
```

--------------------------------

### TiptapEditor Media and Mentions

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/_autodocs/00-index.md

Configuring media uploads and mention search functionality for the editor.

```APIDOC
## TiptapEditor Configuration

### Media Upload
```php
TiptapEditor::make('content')
    ->disk('public')
    ->directory('images')
    ->maxSize(2048)
```

### Mentions
```php
TiptapEditor::make('content')
    ->getMentionItemsUsing(fn ($query) => User::search($query)->get()->map(...)->toArray())
```
```

--------------------------------

### Define Custom Editor Profile with Media Upload

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/_autodocs/05-configuration.md

Configure a specific editor profile with custom tools and media upload settings.

```php
// config/filament-tiptap-editor.php
return [
    'profiles' => [
        'blog' => [
            'heading', 'bold', 'italic', 'link',
            'bullet-list', 'ordered-list',
            '|',
            'media', 'code-block',
        ],
    ],
    'disk' => 'blog-uploads',
    'directory' => 'articles',
    'max_file_size' => 5120,  // 5MB
];
```

--------------------------------

### Apply a Profile to the Editor

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/_autodocs/05-configuration.md

Use the profile method on the TiptapEditor component to apply a specific configuration.

```php
TiptapEditor::make('content')->profile('minimal')
```

--------------------------------

### Prepare email content

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/_autodocs/08-facades-and-helpers.md

Convert content to both HTML and plain text formats for Mailable classes.

```php
namespace App\Mail;

use Illuminate\Mail\Mailable;

class NewsletterMailable extends Mailable
{
    public function build()
    {
        $htmlContent = tiptap_converter()->asHTML($this->newsletter->content);
        $textContent = tiptap_converter()->asText($this->newsletter->content);
        
        return $this
            ->html($htmlContent)
            ->text($textContent);
    }
}
```

--------------------------------

### Convert Content with Helper

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/_autodocs/04-types.md

Transform content to HTML or JSON using the tiptap_converter helper.

```php
$html = tiptap_converter()->asHTML($content);
$json = tiptap_converter()->asJSON($content, decoded: true);
```

--------------------------------

### output(TiptapOutput $output)

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/_autodocs/06-traits.md

Sets the output format for the stored content.

```APIDOC
## output(TiptapOutput $output)

### Description
Sets the output format for stored content.

### Parameters
- **output** (TiptapOutput) - Required - Output enum case

### Returns
- **static** - Fluent interface
```

--------------------------------

### Configure Database for HTML or Text Output

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/_autodocs/00-index.md

Use a text column for HTML or plain text storage. No model casting is required.

```php
// Migration
$table->text('content')->nullable();

// Model (no cast)
```

--------------------------------

### Set dynamic mention loader

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/_autodocs/06-traits.md

Defines a callback to fetch mention suggestions based on a search query.

```php
TiptapEditor::make('content')
    ->getMentionItemsUsing(function (string $query) {
        return User::where('name', 'like', "%$query%")
            ->get()
            ->map(fn ($u) => new MentionItem(id: $u->id, label: $u->name))
            ->toArray();
    })
```

--------------------------------

### Define Tiptap Editor Profiles

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/_autodocs/05-configuration.md

Configure predefined toolbar sets within the profiles array to control available editor features.

```php
'profiles' => [
    'default' => [
        'heading', 'bullet-list', 'ordered-list', 'checked-list', 'blockquote', 'hr', '|',
        'bold', 'italic', 'strike', 'underline', 'superscript', 'subscript', 'lead', 'small', 
        'color', 'highlight', 'align-left', 'align-center', 'align-right', '|',
        'link', 'media', 'oembed', 'table', 'grid-builder', 'details', '|', 
        'code', 'code-block', 'source', 'blocks',
    ],
    'simple' => [
        'heading', 'hr', 'bullet-list', 'ordered-list', 'checked-list', '|', 
        'bold', 'italic', 'lead', 'small', '|', 
        'link', 'media',
    ],
    'minimal' => [
        'bold', 'italic', 'link', 'bullet-list', 'ordered-list',
    ],
    'none' => [],
],
```

--------------------------------

### Configure Tiptap Block Modal and Icon

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/README.md

Customize the modal width, enable slide-over presentation, and set an icon for the block. Icons are currently only displayed in the drag-and-drop block panel.

```php
class BatmanBlock extends TiptapBlock
{
    public string $width = 'xl';
    
    public bool $slideOver = true;
    
    public ?string $icon = 'heroicon-o-film';
}
```

--------------------------------

### Configure Node Placeholders

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/_autodocs/01-tiptap-editor.md

Sets custom placeholder text for specific node types like headings or paragraphs.

```php
TiptapEditor::make('content')
    ->nodePlaceholders([
        'heading' => 'What\'s the title?',
        'paragraph' => 'Start writing here...',
    ])
```

--------------------------------

### View JSON and HTML rendering formats

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/_autodocs/09-data-classes.md

Observe how mention nodes are represented in the editor's JSON state and the final HTML output.

```json
{
  "type": "mention",
  "attrs": {
    "id": 1,
    "label": "John Doe",
    "href": "https://example.com/users/john",
    "image": "https://example.com/avatars/john.jpg",
    "roundedImage": true,
    "type": "user",
    "data": { "email": "john@example.com" }
  }
}
```

```html
<a data-type="mention" data-id="1" href="https://example.com/users/john">@John Doe</a>
```

--------------------------------

### TiptapEditor::getMentionItemsUsing

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/_autodocs/09-data-classes.md

Configures a dynamic callback to fetch mention items based on user input.

```APIDOC
## TiptapEditor::getMentionItemsUsing

### Description
Provides a callback function to dynamically search and return mention items based on the user's search query.

### Parameters
- **callback** (callable) - Required - A function receiving the search string and returning an array of `MentionItem` objects.
```

--------------------------------

### tippyPlacement

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/_autodocs/06-traits.md

Sets the menu placement using Tippy.js.

```APIDOC
## tippyPlacement(string | TippyPlacement | Closure $placement): static

### Description
Sets menu placement via Tippy.js.

### Parameters
- **placement** (string | TippyPlacement | Closure) - Required - Placement value

### Returns
- **static** - The editor instance.
```

--------------------------------

### Customize Floating Menu Tools

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/README.md

Provide custom tools for the floating menu using the 'floatingMenuTools' method on a per-instance basis.

```php
TiptapEditor::make('content')
    ->floatingMenuTools(['grid-builder', 'media', 'link'])
```

--------------------------------

### TiptapEditor::mentionItems

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/_autodocs/09-data-classes.md

Configures static mention items for the Tiptap editor instance.

```APIDOC
## TiptapEditor::mentionItems

### Description
Sets a static list of mentionable items that users can select within the editor.

### Parameters
- **items** (array<MentionItem|array>) - Required - An array of `MentionItem` objects or associative arrays containing the mention properties.
```

--------------------------------

### Convert MentionItem to Array

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/_autodocs/04-types.md

Demonstrates creating a MentionItem instance and converting it to an associative array using toArray().

```php
$item = new MentionItem(
    id: 1,
    label: 'John Doe',
    href: 'https://example.com/users/john',
    image: 'https://example.com/avatars/john.jpg',
    roundedImage: true,
    data: ['department' => 'Engineering']
);

$item->toArray();
// Returns:
// [
//     'id' => 1,
//     'label' => 'John Doe',
//     'type' => null,
//     'href' => 'https://example.com/users/john',
//     'target' => '_blank',
//     'image' => 'https://example.com/avatars/john.jpg',
//     'roundedImage' => true,
//     'data' => ['department' => 'Engineering'],
// ]
```

--------------------------------

### TiptapConverter Facade

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/_autodocs/00-index.md

Utility methods for converting and displaying Tiptap content.

```APIDOC
## TiptapConverter

### Display HTML
```blade
{!! tiptap_converter()->asHTML($post->content) !!}
```

### Display Table of Contents
```blade
{!! tiptap_converter()->asToc($post->content) !!}
```
```

--------------------------------

### Conversion Methods (asHTML, asJSON, asText)

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/_autodocs/02-tiptap-converter.md

Methods for converting Tiptap content into various formats.

```APIDOC
## asHTML($content, toc: bool)

### Description
Converts Tiptap JSON content into an HTML string.

## asJSON($content, decoded: bool)

### Description
Converts Tiptap content into a JSON structure.

## asText($content)

### Description
Converts Tiptap content into plain text, useful for search indexing or previews.
```

--------------------------------

### Using the TiptapConverter Blade Facade

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/_autodocs/00-index.md

Convert Tiptap content to HTML, JSON, or plain text using the TiptapConverter facade.

```php
use FilementTiptapEditor\Facades\TiptapConverter;

TiptapConverter::asHTML($content);
TiptapConverter::asJSON($content, decoded: true);
TiptapConverter::asText($content);
```

--------------------------------

### Define Configuration Array

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/_autodocs/05-configuration.md

The base structure for the configuration file located at config/filament-tiptap-editor.php.

```php
<?php

return [
    // ... all options below
];
```

--------------------------------

### Create a Static Custom Tiptap Block

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/README.md

For blocks without settings, extend `TiptapBlock` without implementing `getFormSchema`. This allows direct insertion into the editor without a modal.

```php
use FilamentTiptapEditor	TiptapBlock;

class StaticBlock extends TiptapBlock
{
    public string $preview = 'blocks.previews.static';

    public string $rendered = 'blocks.rendered.static';
}
```

--------------------------------

### Configure image resize mode

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/_autodocs/06-traits.md

Sets the strategy used for resizing images.

```php
TiptapEditor::make('content')
    ->imageResizeMode('cover')
    // ->imageResizeMode('contain')
    // ->imageResizeMode('stretch')
```

--------------------------------

### Retrieve Plain Text Output

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/_autodocs/06-traits.md

Converts the current editor state into a plain text string.

```php
$text = $editor->getText();
```

--------------------------------

### Define Merge Tags

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/_autodocs/01-tiptap-editor.md

Sets the available keys for placeholder replacement within the editor.

```php
TiptapEditor::make('content')
    ->mergeTags(['first_name', 'last_name', 'email'])
```

--------------------------------

### Configure image resize target width

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/_autodocs/06-traits.md

Sets the target width in pixels for image resizing.

```php
TiptapEditor::make('content')
    ->imageResizeTargetWidth('1200')
```

--------------------------------

### Configure RTL Arabic Editor

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/_autodocs/05-configuration.md

Enable right-to-left text direction for the editor interface.

```php
// config/filament-tiptap-editor.php
return [
    'direction' => 'rtl',
    'profiles' => [
        'default' => [
            'heading', 'align-right', 'align-center', 'align-left',
            '|',
            'bold', 'italic', 'link',
            'bullet-list', 'ordered-list',
        ],
    ],
];
```

--------------------------------

### Configure TiptapEditor output format

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/_autodocs/02-tiptap-converter.md

Set the output format for the TiptapEditor component to automatically handle data dehydration.

```php
TiptapEditor::make('content')->output(TiptapOutput::Html)
// Internally uses TiptapConverter to dehydrate state
```

--------------------------------

### Mention Configuration

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/_autodocs/07-quick-start.md

Customize the trigger character, search strategy, and UI labels for mentions.

```php
use FilimentTiptapEditor\Enums\MentionSearchStrategy;

TiptapEditor::make('content')
    ->mentionTrigger('@')
    ->mentionSearchStrategy(MentionSearchStrategy::Tokenized)
    ->mentionItemsPlaceholder('Search for people...')
    ->mentionItemsLoading('Searching...')
    ->emptyMentionItemsMessage('No people found')
    ->maxMentionItems(10)
```

--------------------------------

### Configure Blocks

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/_autodocs/02-tiptap-converter.md

Registers block classes for the TiptapBlock node extension before editor creation.

```php
tiptap_converter()
    ->blocks([CustomBlock::class, OtherBlock::class])
    ->asHTML($content)
```

--------------------------------

### Configure JSON Output

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/_autodocs/07-quick-start.md

Set the editor to output JSON and configure the database model.

```php
use FilimentTiptapEditor\Enums\TiptapOutput;

TiptapEditor::make('content')
    ->output(TiptapOutput::Json)
```

```php
$table->json('content')->nullable();

// In model:
protected $casts = ['content' => 'json'];
```

--------------------------------

### MentionItem Constructor Definition

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/_autodocs/09-data-classes.md

The constructor signature for initializing a new MentionItem instance.

```php
public function __construct(
    int $id,
    string $label,
    ?string $type = null,
    ?string $href = null,
    ?string $target = '_blank',
    ?string $image = null,
    bool $roundedImage = false,
    array $data = []
)
```

--------------------------------

### Configure upload directory

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/_autodocs/06-traits.md

Sets the directory path for uploaded files, supporting both static strings and dynamic closures.

```php
TiptapEditor::make('content')
    ->directory('articles/2024')
    // Or dynamic:
    ->directory(fn () => 'user-' . auth()->id() . '/uploads')
```

--------------------------------

### Register Custom Extensions in Config

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/_autodocs/10-service-provider.md

Define custom extensions within the configuration file to have them automatically loaded by the service provider.

```php
// config/filament-tiptap-editor.php
return [
    'extensions' => [
        [
            'id' => 'custom-hero',
            'name' => 'Hero Block',
            'button' => 'tools.hero',
            'parser' => \App\TiptapExtensions\Hero::class,
            'source' => 'resources/js/tiptap/extensions.js',
        ],
    ],
];
```

--------------------------------

### Retrieve HTML Output

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/_autodocs/06-traits.md

Converts the current editor state into an HTML string.

```php
$html = $editor->getHTML();
```

--------------------------------

### Clear Service Provider Cache

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/_autodocs/10-service-provider.md

Execute these commands to resolve issues where the service is not resolving correctly.

```bash
php artisan config:clear
php artisan cache:clear
```

--------------------------------

### customDocument(string | Closure | null $customDocument)

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/_autodocs/01-tiptap-editor.md

Sets a custom initial document in JSON or HTML format instead of the default.

```APIDOC
## customDocument(string | Closure | null $customDocument)

### Description
Sets a custom initial document JSON/HTML instead of default.

### Parameters
- **customDocument** (string | Closure | null) - Required - Document JSON/HTML

### Returns
- **static** (fluent)
```

--------------------------------

### Control Placeholder Visibility

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/README.md

Use `showOnlyCurrentPlaceholder(false)` to display placeholders for all nodes simultaneously, rather than only the currently active node.

```php
TiptapEditor::make('content')
    // All nodes will immediately be displayed, instead of only the selected node
    ->showOnlyCurrentPlaceholder(false)
```

--------------------------------

### Register Custom Blocks Globally

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/_autodocs/10-service-provider.md

Use the configureUsing method to register custom blocks for all editor instances.

```php
use FilementTiptapEditor\TiptapEditor;
use App\TiptapBlocks\QuoteBlock;
use App\TiptapBlocks\BatmanBlock;

// In register() or boot()
TiptapEditor::configureUsing(function (TiptapEditor $component) {
    $component->blocks([
        QuoteBlock::class,
        BatmanBlock::class,
    ]);
});
```

--------------------------------

### Set custom oembed action

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/_autodocs/06-traits.md

Configures a custom action class for oembed insertion.

```php
TiptapEditor::make('content')
    ->oembedAction(CustomOEmbedAction::class)
```

--------------------------------

### Create a custom builder for type safety

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/_autodocs/09-data-classes.md

Encapsulate MentionItem creation logic within a service class for cleaner code.

```php
namespace App\Services;

use FilementTiptapEditor\Data\MentionItem;
use App\Models\User;

class MentionItemBuilder
{
    public static function fromUser(User $user): MentionItem
    {
        return new MentionItem(
            id: $user->id,
            label: $user->name,
            href: route('users.show', $user),
            image: $user->avatar_url,
            roundedImage: true,
            type: 'user',
            data: [
                'email' => $user->email,
                'department' => $user->department?->name,
            ]
        );
    }
}

// Usage:
$items = User::all()
    ->map(fn ($u) => MentionItemBuilder::fromUser($u))
    ->toArray();
```

--------------------------------

### Dynamic Mentions with getMentionItemsUsing

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/README.md

Enable dynamic mention suggestions by using the getMentionItemsUsing method, which accepts a callback to fetch items based on a query.

```php
TiptapEditor::make(name: 'content')
    ->getMentionItemsUsing(function (string $query) {
        // Get suggestions based of the $query
        return User::search($query)->get()->map(fn ($user) => new MentionItem(
            id: $user->id,
            label: $user->name
        ))->take(5)->toArray();
    })
```

--------------------------------

### Queue Tiptap conversions

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/_autodocs/08-facades-and-helpers.md

Offload expensive conversion operations to a background queue to improve performance.

```php
use Illuminate\Support\Facades\Queue;

Queue::push(function () use ($post) {
    $html = tiptap_converter()->asHTML($post->content);
    $post->update(['cached_html' => $html]);
});
```

--------------------------------

### Rebuild Custom Theme

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/README.md

After making configuration changes, rebuild your custom theme's assets using npm. This command compiles your CSS and JavaScript.

```sh
npm run build
```

--------------------------------

### Configure Mentions via Array

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/_autodocs/04-types.md

Provides an alternative way to define mention items using simple associative arrays.

```php
TiptapEditor::make('content')
    ->mentionItems([
        ['id' => 1, 'label' => 'Alice Smith'],
        ['id' => 2, 'label' => 'Bob Johnson'],
    ])
```