Search Behaviours (#1320)

* Update setSearchDebounce, add setSearchThrottle/setSearchBlur

* Remove Lazy Tests - Update Docs

---------

Co-authored-by: lrljoe <lrljoe@users.noreply.github.com>

CHANGELOG.md

@@ -50,6 +50,7 @@ All notable changes to `laravel-livewire-tables` will be documented in this file
             - Added SetSearchLive to allow for the search to be "live", with tests
             - Added capability for external CSS file
             - Custom CSS/JS and Alpine components are now stored in an external file, which has configurable injection options
+            - Added setSearchLive(), setSearchThrottle(int $milliseconds) and setSearchBlur() options for Search behaviour
 
 - Test Changes
     - Temporarily removed the sort_events_apply_correctly and filter_events_apply_correctly due to LW3 not using Emit anymore.

docs/search/available-methods.md

@@ -122,14 +122,38 @@ public function configure(): void
 }
 ```
 
-## setSearchLazy
+## setSearchLive
 
-Tell Livewire to use the `lazy` modifier.
+Tell Livewire to immediately update the search
 
 ```php
 public function configure(): void
 {
-    // Send the request when the user clicks away from the search box.
-    $this->setSearchLazy();
+    // Send the search request immediately
+    $this->setSearchLive();
+}
+```
+
+## setSearchBlur
+
+Tell Livewire to update the search when focus is changed from the text box.
+
+```php
+public function configure(): void
+{
+    // Send the search request once focus changes
+    $this->setSearchBlur();
+}
+```
+
+## setSearchThrottle
+
+Tell Livewire to throttle updates
+
+```php
+public function configure(): void
+{
+    // Search will throttle to every 1 second
+    $this->setSearchThrottle(1000);
 }
 ```

src/Traits/Configuration/SearchConfiguration.php

@@ -64,8 +64,8 @@ public function setSearchVisibilityDisabled(): self
      */
     public function setSearchDebounce(int $milliseconds): self
     {
-        if ($this->hasSearchDefer() || $this->hasSearchLazy() || $this->hasSearchLive()) {
-            throw new DataTableConfigurationException('You can only set one search filter option per table: debounce, defer, or lazy.');
+        if ($this->hasSearchBlur() || $this->hasSearchDefer() || $this->hasSearchLazy() || $this->hasSearchLive() || $this->hasSearchThrottle()) {
+            throw new DataTableConfigurationException('You can only set one search filter option per table: live, blur, throttle, debounce, defer, or lazy.');
         }
 
         $this->searchFilterDebounce = $milliseconds;
@@ -78,8 +78,8 @@ public function setSearchDebounce(int $milliseconds): self
      */
     public function setSearchDefer(): self
     {
-        if ($this->hasSearchDebounce() || $this->hasSearchLazy() || $this->hasSearchLive()) {
-            throw new DataTableConfigurationException('You can only set one search filter option per table: debounce, defer, or lazy.');
+        if ($this->hasSearchBlur() || $this->hasSearchDebounce() || $this->hasSearchLazy() || $this->hasSearchLive() || $this->hasSearchThrottle()) {
+            throw new DataTableConfigurationException('You can only set one search filter option per table: live, blur, throttle, debounce, defer, or lazy.');
         }
 
         $this->searchFilterDefer = true;
@@ -92,22 +92,50 @@ public function setSearchDefer(): self
      */
     public function setSearchLive(): self
     {
-        if ($this->hasSearchDebounce() || $this->hasSearchLazy() || $this->hasSearchDefer()) {
-            throw new DataTableConfigurationException('You can only set one search filter option per table: debounce, defer, or lazy.');
+        if ($this->hasSearchBlur() || $this->hasSearchDebounce() || $this->hasSearchDefer() || $this->hasSearchLazy() || $this->hasSearchThrottle()) {
+            throw new DataTableConfigurationException('You can only set one search filter option per table: live, blur, throttle, debounce, defer, or lazy.');
         }
 
         $this->searchFilterLive = true;
 
         return $this;
     }
 
+    /**
+     * @throws DataTableConfigurationException
+     */
+    public function setSearchThrottle(int $milliseconds): self
+    {
+        if ($this->hasSearchBlur() || $this->hasSearchDebounce() || $this->hasSearchDefer() || $this->hasSearchLazy() || $this->hasSearchLive()) {
+            throw new DataTableConfigurationException('You can only set one search filter option per table: live, blur, throttle, debounce, defer, or lazy.');
+        }
+
+        $this->searchFilterThrottle = $milliseconds;
+
+        return $this;
+    }
+
+    /**
+     * @throws DataTableConfigurationException
+     */
+    public function setSearchBlur(): self
+    {
+        if ($this->hasSearchDebounce() || $this->hasSearchDefer() || $this->hasSearchLazy() || $this->hasSearchLive() || $this->hasSearchThrottle()) {
+            throw new DataTableConfigurationException('You can only set one search filter option per table: live, blur, throttle, debounce, defer, or lazy.');
+        }
+
+        $this->searchFilterBlur = true;
+
+        return $this;
+    }
+
     /**
      * @throws DataTableConfigurationException
      */
     public function setSearchLazy(): self
     {
-        if ($this->hasSearchDebounce() || $this->hasSearchDefer() || $this->hasSearchLive()) {
-            throw new DataTableConfigurationException('You can only set one search filter option per table: debounce, defer, or lazy.');
+        if ($this->hasSearchBlur() || $this->hasSearchDebounce() || $this->hasSearchDefer() || $this->hasSearchLive() || $this->hasSearchThrottle()) {
+            throw new DataTableConfigurationException('You can only set one search filter option per table: live, blur, throttle, debounce, defer, or lazy.');
         }
 
         $this->searchFilterLazy = true;

src/Traits/Helpers/SearchHelpers.php

@@ -77,10 +77,25 @@ public function hasSearchLive(): bool
         return $this->searchFilterLive !== null;
     }
 
+    public function hasSearchThrottle(): bool
+    {
+        return $this->searchFilterThrottle !== null;
+    }
+
+    public function getSearchThrottle(): ?int
+    {
+        return $this->searchFilterThrottle;
+    }
+
+    public function hasSearchBlur(): bool
+    {
+        return $this->searchFilterBlur !== null;
+    }
+
     public function getSearchOptions(): string
     {
         if ($this->hasSearchDebounce()) {
-            return '.debounce.'.$this->getSearchDebounce().'ms';
+            return '.live.debounce.'.$this->getSearchDebounce().'ms';
         }
 
         if ($this->hasSearchDefer()) {
@@ -91,8 +106,16 @@ public function getSearchOptions(): string
             return '.live';
         }
 
+        if ($this->hasSearchBlur()) {
+            return '.blur';
+        }
+
         if ($this->hasSearchLazy()) {
-            return '.lazy';
+            return '.live.lazy';
+        }
+
+        if ($this->hasSearchThrottle()) {
+            return '.live.throttle.'.$this->getSearchThrottle().'ms';
         }
 
         return '';

src/Traits/WithSearch.php

@@ -17,6 +17,8 @@ trait WithSearch
 
     public bool $searchVisibilityStatus = true;
 
+    public ?bool $searchFilterBlur = null;
+
     public ?int $searchFilterDebounce = null;
 
     public ?bool $searchFilterDefer = null;
@@ -25,6 +27,8 @@ trait WithSearch
 
     public ?bool $searchFilterLive = null;
 
+    public ?int $searchFilterThrottle = null;
+
     public ?string $searchPlaceholder = null;
 
     // TODO

tests/Traits/Configuration/SearchConfigurationTest.php

@@ -70,7 +70,7 @@ public function can_set_search_debounce(): void
 
         $this->assertTrue($this->basicTable->hasSearchDebounce());
         $this->assertSame(1000, $this->basicTable->getSearchDebounce());
-        $this->assertSame('.debounce.1000ms', $this->basicTable->getSearchOptions());
+        $this->assertSame('.live.debounce.1000ms', $this->basicTable->getSearchOptions());
     }
 
     /** @test */
@@ -103,24 +103,24 @@ public function cant_set_search_defer_with_other_search_modifiers(): void
     }
 
     /** @test */
-    public function can_set_search_lazy(): void
+    /*public function can_set_search_lazy(): void
     {
         $this->assertFalse($this->basicTable->hasSearchLazy());
 
         $this->basicTable->setSearchLazy();
 
         $this->assertTrue($this->basicTable->hasSearchLazy());
         $this->assertSame('.lazy', $this->basicTable->getSearchOptions());
-    }
+    }*/
 
     /** @test */
-    public function cant_set_search_lazy_with_other_search_modifiers(): void
+    /*public function cant_set_search_lazy_with_other_search_modifiers(): void
     {
         $this->expectException(DataTableConfigurationException::class);
 
         $this->basicTable->setSearchLazy();
         $this->basicTable->setSearchDebounce(1000);
-    }
+    }*/
 
     /** @test */
     public function can_set_search_live(): void
@@ -142,6 +142,47 @@ public function cant_set_search_live_with_other_search_modifiers(): void
         $this->basicTable->setSearchDebounce(1000);
     }
 
+    /** @test */
+    public function can_set_search_blur(): void
+    {
+        $this->assertFalse($this->basicTable->hasSearchBlur());
+
+        $this->basicTable->setSearchBlur();
+
+        $this->assertTrue($this->basicTable->hasSearchBlur());
+        $this->assertSame('.blur', $this->basicTable->getSearchOptions());
+    }
+
+    /** @test */
+    public function cant_set_search_blur_with_other_search_modifiers(): void
+    {
+        $this->expectException(DataTableConfigurationException::class);
+
+        $this->basicTable->setSearchBlur();
+        $this->basicTable->setSearchDefer();
+    }
+
+    /** @test */
+    public function can_set_search_throttle(): void
+    {
+        $this->assertFalse($this->basicTable->hasSearchThrottle());
+
+        $this->basicTable->setSearchThrottle(1000);
+
+        $this->assertTrue($this->basicTable->hasSearchThrottle());
+        $this->assertSame(1000, $this->basicTable->getSearchThrottle());
+        $this->assertSame('.live.throttle.1000ms', $this->basicTable->getSearchOptions());
+    }
+
+    /** @test */
+    public function cant_set_search_throttle_with_other_search_modifiers(): void
+    {
+        $this->expectException(DataTableConfigurationException::class);
+
+        $this->basicTable->setSearchThrottle(1000);
+        $this->basicTable->setSearchDefer();
+    }
+
     /** @test */
     public function can_set_search_placeholder(): void
     {

tests/Traits/Helpers/SearchHelpersTest.php

@@ -85,13 +85,33 @@ public function can_check_if_search_defer_is_set(): void
     }
 
     /** @test */
-    public function can_check_if_search_lazy_is_set(): void
+    public function can_check_if_search_blur_is_set(): void
+    {
+        $this->assertFalse($this->basicTable->hasSearchBlur());
+
+        $this->basicTable->setSearchBlur();
+
+        $this->assertTrue($this->basicTable->hasSearchBlur());
+    }
+
+    /** @test */
+    /*public function can_check_if_search_lazy_is_set(): void
     {
         $this->assertFalse($this->basicTable->hasSearchLazy());
 
         $this->basicTable->setSearchLazy();
 
         $this->assertTrue($this->basicTable->hasSearchLazy());
+    }*/
+
+    /** @test */
+    public function can_check_if_search_throttle_is_set(): void
+    {
+        $this->assertFalse($this->basicTable->hasSearchThrottle());
+
+        $this->basicTable->setSearchThrottle(180);
+
+        $this->assertSame(180, $this->basicTable->getSearchThrottle());
     }
 
     /** @test */

tests/Traits/Visuals/SearchVisualsTest.php

@@ -46,26 +46,35 @@ public function search_clear_button_shows_when_there_is_input(): void
     public function search_debounce_filter_is_applied(): void
     {
         Livewire::test(PetsTable::class)
-            ->assertDontSeeHtml('wire:model.debounce.1000ms="search"')
+            ->assertDontSeeHtml('wire:model.live.debounce.1000ms="search"')
             ->call('setSearchDebounce', 1000)
-            ->assertSeeHtml('wire:model.debounce.1000ms="search"');
+            ->assertSeeHtml('wire:model.live.debounce.1000ms="search"');
     }
 
     /** @test */
-    public function search_defer_filter_is_applied(): void
+    public function search_throttle_filter_is_applied(): void
     {
         Livewire::test(PetsTable::class)
-            ->call('setSearchDefer')
-            ->assertSeeHtml('wire:model="search"');
+            ->assertDontSeeHtml('wire:model.live.throttle.1000ms="search"')
+            ->call('setSearchThrottle', 1000)
+            ->assertSeeHtml('wire:model.live.throttle.1000ms="search"');
     }
 
     /** @test */
-    public function search_lazy_filter_is_applied(): void
+    public function search_blur_filter_is_applied(): void
     {
         Livewire::test(PetsTable::class)
-            ->assertDontSeeHtml('wire:model.lazy="search"')
-            ->call('setSearchLazy')
-            ->assertSeeHtml('wire:model.lazy="search"');
+            ->assertDontSeeHtml('wire:model.blur="search"')
+            ->call('setSearchBlur')
+            ->assertSeeHtml('wire:model.blur="search"');
+    }
+
+    /** @test */
+    public function search_defer_filter_is_applied(): void
+    {
+        Livewire::test(PetsTable::class)
+            ->call('setSearchDefer')
+            ->assertSeeHtml('wire:model="search"');
     }
 
     /** @test */