Slidewire Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require wendelladriel/slidewire
   php artisan vendor:publish --provider="WendellAdriel\SlideWire\SlideWireServiceProvider" --tag="slidewire-config"
   

   Publish the config to customize defaults (e.g., themes, transitions).

2. Create a Presentation:

   php artisan make:slidewire MyFirstDeck
   

   This generates:

   • A Blade file (resources/views/slidewire/my-first-deck.blade.php) for slide content.
   • A Livewire component (app/Livewire/Presentations/MyFirstDeck.php) to handle logic.
   • A route (routes/web.php) via the slidewire() helper.

3. First Slide: Edit resources/views/slidewire/my-first-deck.blade.php:

   <slide>
       <h1>Hello, SlideWire!</h1>
       <p>This is my first interactive presentation.</p>
   </slide>
   

   Access it at /my-first-deck (or the route defined in slidewire()).

First Use Case: Markdown + Code Demo

Use the markdown directive for quick content:

<slide>
    @markdown
        # Laravel Livewire Integration

        SlideWire leverages Livewire for **real-time updates**.
        Example:
        ```php
        public function mount() {
            $this->data = 'Dynamic content!';
        }
        ```
    @endmarkdown
</slide>

Key: No manual HTML—write Markdown, and SlideWire handles syntax highlighting (via Phiki) and theming.

Implementation Patterns

1. Deck Structure

Organize slides into horizontal groups (default) or vertical stacks (for nested content):

<!-- resources/views/slidewire/onboarding.blade.php -->
<slidewire>
    <!-- Horizontal slides (default) -->
    <slide>
        <h2>Step 1: Setup</h2>
        @code('php', file: 'setup.php')
    </slide>

    <!-- Vertical stack (grouped slides) -->
    <slide vertical>
        <slide>Detail A</slide>
        <slide>Detail B</slide>
    </slide>
</slidewire>

Pattern: Use vertical for sub-sections (e.g., FAQs, code walkthroughs).

2. Dynamic Data with Livewire

Bind presentation state to Livewire properties:

// app/Livewire/Presentations/MetricsDeck.php
public $quarter = 'Q1';

public function updateQuarter($quarter) {
    $this->quarter = $quarter;
    $this->emit('slidewire:refresh'); // Force slide re-render
}

<!-- Blade -->
<slide>
    <h1>Metrics for {{ $quarter }}</h1>
    @foreach($metrics[$quarter] as $metric)
        <div>{{ $metric }}</div>
    @endforeach
</slide>

Tip: Use wire:model for interactive elements (e.g., dropdowns to switch slides).

3. Theming and Reusability

Extend SlideWire’s default theme via slidewire.php config:

'theme' => [
    'extends' => 'default',
    'colors' => [
        'primary' => '#2563eb', // Tailwind blue-800
    ],
],

Pattern: Create a base theme in resources/views/vendor/slidewire/themes/custom.blade.php:

@push('slidewire-styles')
    <style>
        .custom-slide { background: #f8fafc; }
    </style>
@endpush

4. Auto-Slides and Timers

Configure per-slide or deck-wide timers:

<slide auto-slide="3"> <!-- 3-second delay -->
    <h2>Auto-advancing Slide</h2>
</slide>

Global config (slidewire.php):

'auto_slide' => [
    'default' => 5, // seconds
    'paused_on_interaction' => true,
],

5. Fragments and Navigation

Link to specific slides via URL hashes:

<a href="#/my-deck?slide=3">Jump to Slide 3</a>

Livewire Navigation:

public function navigateToSlide($slideNumber) {
    $this->redirect("/my-deck?slide={$slideNumber}");
}

6. Custom Components

Extend SlideWire’s built-in components (e.g., Code, Diagram):

<diagram type="mermaid">
    graph TD;
        A[Start] --> B{Decision};
        B -->|Yes| C[Result];
</diagram>

Pattern: Create a DiagramComponent in app/Livewire/Components for complex logic.

Gotchas and Tips

Pitfalls

1. Livewire State Persistence:

   • Issue: Unbounded data in slides (e.g., large datasets) can bloat Livewire’s session.
   • Fix: Use wire:ignore or lazy-load data:

     <div wire:ignore>{{ $largeDataset->chunk(10) }}</div>
     

2. Markdown Parsing Quirks:

   • Issue: Custom Markdown (e.g., tables) may break syntax highlighting.
   • Fix: Preprocess content with Str::of($markdown)->markdown() or use @code blocks for code.

3. Theme Overrides:

   • Issue: Tailwind/Alpine conflicts with SlideWire’s default CSS.
   • Fix: Scope SlideWire styles:

     @push('slidewire-styles')
         @tailwind base; @tailwind components;
         .slidewire-slide { @apply bg-white; }
     @endpush
     

4. Auto-Slide Conflicts:

   • Issue: auto-slide ignores keyboard/mouse events if not configured.
   • Fix: Set paused_on_interaction: true in slidewire.php.

5. Vertical Slides and Mobile:

   • Issue: Touch swipe may not work on mobile for vertical stacks.
   • Fix: Add data-slidewire-vertical and test with:

     document.querySelector('[data-slidewire-vertical]').addEventListener('touchmove', (e) => e.preventDefault());
     

Debugging Tips

1. Slide Context: Use {{ dd($this->slideContext) }} in Blade to inspect current slide data (e.g., slideNumber, vertical).

2. Playwright Test Failures:

   • Common Cause: Missing npx playwright install or stale browser cache.
   • Fix:

     npx playwright install chromium
     npx playwright test --debug
     

3. Transition Glitches:

   • Issue: Flickering during slide transitions.
   • Fix: Disable CSS transitions temporarily:

     <style> .slidewire-transition { transition: none !important; } </style>
     

Extension Points

1. Custom Slide Types: Extend SlideWire\Component\Slide to add logic (e.g., quiz slides):

   class QuizSlide extends Slide {
       public function render() {
           return view('livewire.slidewire.quiz', ['question' => $this->question]);
       }
   }
   

2. Pre-Rendering: Compile slides at build time (e.g., for static sites):

   use WendellAdriel\SlideWire\SlideWire;
   
   $slideWire = new SlideWire();
   $html = $slideWire->render('my-deck');
   file_put_contents('public/decks/my-deck.html', $html);
   

3. Database-Backed Decks: Store slide content in a table and hydrate dynamically:

   public function getSlides() {
       return Slide::where('deck_id', $this->deckId)->orderBy('order')->get();
   }
   

Performance Optimizations

1. Lazy-Load Images:

   <img src="{{ $image->path }}" loading="lazy" alt="...">
   

2. Debounce Auto-Slides:

   // app/Livewire/Presentations/MyDeck.php
   protected $listeners = ['slidewire:auto-slide' => 'debounceAutoSlide'];
   
   public function debounceAutoSlide() {
       $this->dispatch('slidewire:pause-auto-slide')->after(1000);
   }
   

3. Cache Compiled Slides:

   // slidewire.php
   'cache' => [
       'enabled' => env('SLIDEWIRE_CACHE', false),
       'ttl' => 60, // minutes
   ],