Filament Rich Editor Heroicons Laravel Package

Getting Started

Minimal Setup

1. Install the package:

   composer require oliwol/filament-rich-editor-heroicons
   

2. Add to a RichEditor component:

   use Oliwol\FilamentRichEditorHeroicons\FilamentRichEditorHeroicons;
   
   RichEditor::make('content')
       ->toolbarButtons([
           'bold', 'italic', 'addHeroicon', // Add the heroicon button
       ])
       ->plugins([
           FilamentRichEditorHeroicons::make(),
       ]);
   

First Use Case

• Insert an icon: Click the addHeroicon toolbar button, search for an icon (e.g., bell), select a style (e.g., outline), and insert it into the editor.
• Edit an icon: Click the inserted icon to reopen the picker and modify its properties (size, color, alignment, or accessibility label).

Implementation Patterns

Workflows

1. Content Creation Workflow:

   • Use the addHeroicon button in the RichEditor toolbar to open the modal.
   • Search for icons (e.g., arrow, check-circle) and preview them in the dropdown.
   • Configure icon properties (style, size, color, alignment, accessibility label) via the modal.
   • Insert the icon into the editor content.

2. Rendering Stored Content:

   • Use RichContentRenderer to render saved content with icons in Blade views or model accessors:

     RichContentRenderer::make($this->html)
         ->plugins([
             FilamentRichEditorHeroicons::make(),
         ]);
     

3. Customizing Icon Behavior:

   • Restrict available styles (e.g., only outline and solid):

     FilamentRichEditorHeroicons::make()
         ->styles(['outline', 'solid']);
     

   • Set default size and customize available sizes:

     FilamentRichEditorHeroicons::make()
         ->defaultSize('lg')
         ->sizes([
             'sm' => 16,
             'md' => 24,
             'lg' => 32,
             'xl' => 48,
         ]);
     

Integration Tips

• Toolbar Placement: Position the addHeroicon button logically in the toolbar (e.g., near other formatting tools like bold or italic).
• Accessibility: Always provide an accessibility label for meaningful icons (e.g., aria-label="warning" for a exclamation-circle icon).
• Consistency: Use the same size and style configurations across all instances of the plugin in your application.
• Localization: Publish translations if your application supports multiple languages:

  php artisan vendor:publish --tag="filament-rich-editor-heroicons-translations"
  

Gotchas and Tips

Pitfalls

1. Missing Plugin Registration:

   • Forgetting to add FilamentRichEditorHeroicons::make() to the plugins() array of RichEditor will prevent the heroicon button from working.
   • Fix: Ensure the plugin is registered in both the editor and RichContentRenderer for rendering.

2. Unrendered Icons:

   • Icons may not display if RichContentRenderer is not configured to include the plugin when rendering saved content.
   • Fix: Always include the plugin in RichContentRenderer:

     RichContentRenderer::make($html)->plugins([FilamentRichEditorHeroicons::make()]);
     

3. Style or Size Mismatches:

   • If icons appear broken or misaligned, verify that the styles() and sizes() configurations match the expected Heroicon styles (e.g., outline, solid, mini).
   • Fix: Double-check the available styles and sizes in the Heroicons documentation.

4. SVG Sanitization Issues:

   • Custom SVG attributes or malformed icons may cause rendering errors.
   • Fix: Use the default configurations or ensure SVG attributes are valid (e.g., fill, aria-hidden).

5. Toolbar Button Visibility:

   • The addHeroicon button may not appear if not explicitly added to toolbarButtons().
   • Fix: Include 'addHeroicon' in the toolbarButtons() array.

Debugging

• Check Console Logs: Open browser dev tools (F12) to inspect errors related to the Heroicons script or TipTap extensions.
• Inspect Rendered HTML: Verify that inserted icons include the correct data-* attributes (e.g., data-icon, data-svg) when rendered.
• Test with Default Config: Temporarily use default configurations to isolate issues:

  FilamentRichEditorHeroicons::make() // No customizations
  

Extension Points

1. Custom Icon Sets:

   • Extend the package to support additional icon libraries by modifying the HeroiconPicker component or creating a custom TipTap extension.

2. Dynamic Icon Properties:

   • Override the modal logic to fetch icon properties dynamically (e.g., from an API) by extending the HeroiconPicker class.

3. Additional Attributes:

   • Add custom attributes to icons (e.g., data-tooltip) by extending the TipTap node or SVG rendering logic.

4. Theming:

   • Customize the modal or icon appearance by overriding the Blade views or CSS classes (e.g., heroicon-picker-modal).

Configuration Quirks

• Mini Icons: Mini-style icons use a fixed 20x20 viewport by default. Adjust sizes carefully to avoid distortion.
• Color Picker: The default color is black (#000000). Customize via the modal or by overriding the color picker logic.
• Alignment: Icons with alignment="left" or alignment="right" may require additional CSS to handle block-level behavior consistently.

Performance Tips

• Lazy-Load Icons: For large applications, consider lazy-loading the Heroicons script or preloading critical icons.
• Cache Rendered Icons: If rendering icons server-side, cache the SVG output to reduce processing overhead.