Add offset parameter

DOCUMENTATION.md

@@ -204,6 +204,7 @@ Tag pair that returns the next X event dates.
 * `event` - optional - if used, it gets occurrences from the given event only, and ignores `collection` parameter
 * `limit` - required, number of occurrences to return
 * `collapse_multi_days` - optional, only relevant on multi-day, all-day events. When `true`, multi-day events will only show up once in the event list.
+* `offset` – optional – if used, it skips a specified number of occurrences.
 
 *Example*:
 

src/Events.php

@@ -31,6 +31,8 @@ class Events
 
     private array $filters = [];
 
+    private ?int $offset = null;
+
     private ?int $page = null;
 
     private ?int $perPage = null;
@@ -92,6 +94,13 @@ public function filter(string $fieldCondition, $value): self
         return $this;
     }
 
+    public function offset(int $offset): self
+    {
+        $this->offset = $offset;
+
+        return $this;
+    }
+
     public function pagination(int $page = 1, int $perPage = 10): self
     {
         $this->page = $page;
@@ -139,6 +148,10 @@ private function output(callable $type): EntryCollection|LengthAwarePaginator
     {
         $occurrences = $this->entries()->occurrences(generator: $type);
 
+        if ($this->offset) {
+            $occurrences = $occurrences->slice(offset: $this->offset);
+        }
+
         return $this->page ? $this->paginate(occurrences: $occurrences) : $occurrences;
     }
 

src/Tags/Events.php

@@ -140,6 +140,9 @@ private function generator(): Generator
             )->when(
                 value: $this->parseFilters(),
                 callback: fn (Generator $generator, array $filters) => $generator->filters(filters: $filters)
+            )-> when(
+                value: $this->params->int('offset'),
+                callback: fn (Generator $generator, int $offset) => $generator->offset(offset: $offset)
             )->when(
                 value: $this->params->int('paginate'),
                 callback: fn (Generator $generator, int $perPage) => $generator->pagination(

tests/Feature/EventsOffsetTest.php

@@ -0,0 +1,120 @@
+<?php
+
+namespace TransformStudios\Events\Tests\Feature;
+
+use Illuminate\Support\Carbon;
+use Statamic\Facades\Cascade;
+use Statamic\Facades\Entry;
+use TransformStudios\Events\Tags\Events;
+use TransformStudios\Events\Tests\PreventSavingStacheItemsToDisk;
+use TransformStudios\Events\Tests\TestCase;
+
+class EventsOffsetTest extends TestCase
+{
+  use PreventSavingStacheItemsToDisk;
+
+  private Events $tag;
+
+  public function setUp(): void
+  {
+      parent::setUp();
+
+      Entry::make()
+          ->collection('events')
+          ->slug('recurring-event')
+          ->id('recurring-event')
+          ->data([
+              'title' => 'Recurring Event',
+              'start_date' => Carbon::now()->toDateString(),
+              'start_time' => '11:00',
+              'end_time' => '12:00',
+              'recurrence' => 'weekly',
+              'categories' => ['one'],
+          ])->save();
+
+      $this->tag = app(Events::class);
+  }
+
+  /** @test */
+  public function canOffsetUpcomingOccurrences()
+  {
+    Carbon::setTestNow(now()->setTimeFromTimeString('10:00'));
+
+    $this->tag
+        ->setContext([])
+        ->setParameters([
+            'collection' => 'events',
+            'limit' => 5,
+            'offset' => 2,
+        ]);
+
+    $occurrences = $this->tag->upcoming();
+
+    $this->assertCount(3, $occurrences);
+  }
+
+  /** @test */
+  public function canOffsetBetweenOccurrences()
+  {
+    Carbon::setTestNow(now()->setTimeFromTimeString('10:00'));
+
+    $this->tag->setContext([])
+        ->setParameters([
+            'collection' => 'events',
+            'from' => Carbon::now()->toDateString(),
+            'to' => Carbon::now()->addWeek(3),
+            'offset' => 2,
+        ]);
+
+    $occurrences = $this->tag->between();
+
+    $this->assertCount(2, $occurrences);
+  }
+
+  /** @test */
+  public function canOffsetTodayOccurrences()
+  {
+    Carbon::setTestNow(now()->setTimeFromTimeString('12:01'));
+
+    Entry::make()
+        ->collection('events')
+        ->slug('single-event')
+        ->data([
+            'title' => 'Single Event',
+            'start_date' => Carbon::now()->toDateString(),
+            'start_time' => '13:00',
+            'end_time' => '15:00',
+        ])->save();
+
+    $this->tag->setContext([])
+        ->setParameters([
+            'collection' => 'events',
+            'offset' => 1,
+        ]);
+
+    $this->assertCount(1, $this->tag->today());
+
+    $this->tag->setContext([])
+        ->setParameters([
+            'collection' => 'events',
+            'ignore_finished' => true,
+            'offset' => 1,
+        ]);
+
+    $this->assertCount(0, $this->tag->today());
+  }
+
+  /** @test */
+  public function canOffsetSingleDayOccurrences()
+  {
+    Carbon::setTestNow(now()->setTimeFromTimeString('10:00'));
+
+    $this->tag->setContext([])
+        ->setParameters([
+            'collection' => 'events',
+            'offset' => 1,
+        ]);
+
+    $this->assertCount(0, $this->tag->today());
+  }
+}