Filament Univer Sheet Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require qalainau/filament-univer-sheet
   php artisan filament:assets
   

2. Register Plugin in PanelServiceProvider:

   public function panel(Panel $panel): Panel {
       return $panel->plugins([
           UniverSheetPlugin::make(),
       ]);
   }
   

3. First Use Case: Add a spreadsheet field to a form:

   SpreadsheetField::make('data')
       ->columnSpanFull()
   

Where to Look First

• README.md#Usage: Quickstart examples for forms, infolists, and tables.
• API Reference: Method signatures for customization (e.g., ->showToolbar(false)).
• Config File: Global defaults after publishing (php artisan vendor:publish --tag=filament-univer-sheet-config).

Implementation Patterns

Core Workflows

1. Form Integration

• Pattern: Replace textareas or JSON fields for tabular data.
• Example:

  SpreadsheetField::make('pricing_schedule')
      ->height('500px')
      ->ribbonType('collapsed')
      ->rules(['required', 'array'])
  

• Tip: Use ->columnSpanFull() for dedicated spreadsheet sections in multi-field forms.

2. Infolist Display

• Pattern: Show read-only spreadsheets in resource views.
• Example:

  SpreadsheetEntry::make('audit_log')
      ->height('400px')
      ->showToolbar(false) // Disable editing
  

• Tip: Combine with MarkdownEntry for mixed content (e.g., "Here’s the latest data:" + spreadsheet).

3. Table Previews

• Pattern: Compact grid previews for quick validation.
• Example:

  SpreadsheetColumn::make('inventory')
      ->previewRows(5)
      ->previewColumns(3)
  

• Tip: Use ->sortable() if the underlying data is sortable.

4. Database Handling

• Pattern: Store as json cast (no manual serialization).
• Migration:

  $table->json('data')->nullable(); // Laravel 11+
  

• Model:

  protected $casts = ['data' => 'json'];
  

Advanced Patterns

Dynamic Configuration

• Use Case: Toggle features based on user roles.
• Example:

  SpreadsheetField::make('data')
      ->showToolbar(fn (User $user) => $user->can('edit-spreadsheets'))
  

Localization

• Use Case: Support Japanese/English interfaces.
• Config:

  UniverSheetPlugin::make()->locale('ja-JP');
  

• Note: Only 2 locales are bundled; extend via Univer Sheet’s i18n system.

Custom Toolbars

• Use Case: Hide rarely used features (e.g., showContextMenu(false)).
• Example:

  SpreadsheetField::make('data')
      ->showFormulaBar(false)
      ->showSheetTabs(false)
  

Validation

• Use Case: Ensure data integrity.
• Example:

  SpreadsheetField::make('data')
      ->rules([
          'required',
          'array',
          function ($attribute, $value, $fail) {
              if (empty($value['sheets'][0]['cells'])) {
                  $fail('Spreadsheet cannot be empty.');
              }
          },
      ])
  

Gotchas and Tips

Pitfalls

1. Double JSON Encoding

   • Issue: Using dehydrateStateUsing corrupts data.
   • Fix: Rely on Eloquent’s json cast:

     // ❌ Avoid
     protected function dehydrateStateUsing($state) {
         return json_encode($state);
     }
     // ✅ Use
     protected $casts = ['data' => 'json'];
     

2. Performance with Large Datasets

   • Issue: Univer Sheet lags with >10K cells.
   • Fix: Limit rows/columns in previews:

     SpreadsheetColumn::make('data')
         ->previewRows(10)
         ->previewColumns(6)
     

3. Formula Limitations

   • Issue: Complex formulas (e.g., VLOOKUP) may fail.
   • Fix: Test with your specific formulas; refer to Univer’s formula docs.

4. Dark Mode Quirks

   • Issue: Custom CSS may override Univer’s dark mode.
   • Fix: Use Filament’s dark: modifier:

     ->extraAttributes(['class' => 'dark:bg-gray-800'])
     

Debugging Tips

1. Inspect Raw Data

   • Dump the JSON payload to verify structure:

     dd($record->data); // Should match Univer’s sheet format
     

2. Clear Filament Cache

   • After config changes:

     php artisan filament:cache-clear
     

3. Check Console for Errors

   • Univer Sheet logs errors to the browser console (e.g., missing dependencies).

Extension Points

1. Custom Cell Rendering

   • How: Extend Univer Sheet’s cell renderer via JavaScript.
   • Example: Add a custom button to cells:

     // In a Filament resource’s JS file
     document.addEventListener('DOMContentLoaded', () => {
         const cells = document.querySelectorAll('.univer-cell');
         cells.forEach(cell => {
             cell.addEventListener('click', (e) => {
                 if (e.target.classList.contains('custom-action')) {
                     // Handle click
                 }
             });
         });
     });
     

2. Plugin-Level Overrides

   • How: Publish the config and override defaults:

     // config/univer-sheet.php
     return [
         'show_toolbar' => false, // Disable globally
     ];
     

3. Localization Extensions

   • How: Add translations via Univer’s i18n system.
   • Example:

     // In a Filament resource’s JS file
     UniverSheet.locale('es-ES', {
         'Home': 'Inicio',
         'Insert': 'Insertar',
         // ...
     });
     

Pro Tips

• Use ->extraAttributes() for custom styling:

  SpreadsheetField::make('data')
      ->extraAttributes(['data-testid' => 'spreadsheet-field'])
  

• Combine with Filament Actions: Add a "Export to CSV" action:

  use Filament\Actions\Action;
  
  Action::make('export')
      ->action(fn ($record) => {
          // Use Maatwebsite/Excel to export $record->data
      }),
  

• Leverage Univer’s API: Access spreadsheet methods via JavaScript:

  const sheet = document.querySelector('.univer-sheet');
  sheet.univerSheet.getActiveSheet().getCell('A1').value; // Read cell