add tests for tag match type (backend + e2e)

[Added]
- Introduced a tag filter feature allowing users to specify whether tags should be included or excluded in time entry filters. This supports 'contains' and 'not_contains' modes.

app/Enums/TagMatchType.php

@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Enums;
+
+use Datomatic\LaravelEnumHelper\LaravelEnumHelper;
+
+enum TagMatchType: string
+{
+    use LaravelEnumHelper;
+
+    case Contains = 'contains';
+
+    case NotContains = 'not_contains';
+}

app/Http/Controllers/Api/V1/Public/ReportController.php

@@ -59,7 +59,7 @@ class ReportController extends Controller
         $filter->addBillable($properties->billable);
         $filter->addMemberIdsFilter($properties->memberIds?->toArray());
         $filter->addProjectIdsFilter($properties->projectIds?->toArray());
-        $filter->addTagIdsFilter($properties->tagIds?->toArray());
+        $filter->addTagIdsFilter($properties->tagIds?->toArray(), $properties->tagMatchType);
         $filter->addTaskIdsFilter($properties->taskIds?->toArray());
         $filter->addClientIdsFilter($properties->clientIds?->toArray());
         $timeEntriesQuery = $filter->get();

app/Http/Controllers/Api/V1/ReportController.php

@@ -96,6 +96,7 @@ class ReportController extends Controller
         $properties->setClientIds($request->input('properties.client_ids', null));
         $properties->setProjectIds($request->input('properties.project_ids', null));
         $properties->setTagIds($request->input('properties.tag_ids', null));
+        $properties->setTagMatchType($request->getPropertyTagMatchType());
         $properties->setTaskIds($request->input('properties.task_ids', null));
         $properties->weekStart = $request->has('properties.week_start') ? Weekday::from($request->input('properties.week_start')) : $user->week_start;
         $timezone = $user->timezone;

app/Http/Controllers/Api/V1/TimeEntryController.php

@@ -203,7 +203,7 @@ class TimeEntryController extends Controller
         $filter->addMemberIdFilter($member);
         $filter->addMemberIdsFilter($request->input('member_ids'));
         $filter->addProjectIdsFilter($request->input('project_ids'));
-        $filter->addTagIdsFilter($request->input('tag_ids'));
+        $filter->addTagIdsFilter($request->input('tag_ids'), $request->getTagMatchType());
         $filter->addTaskIdsFilter($request->input('task_ids'));
         $filter->addClientIdsFilter($request->input('client_ids'));
         $filter->addBillableFilter($request->input('billable'));
@@ -559,7 +559,7 @@ class TimeEntryController extends Controller
         $filter->addMemberIdFilter($member);
         $filter->addMemberIdsFilter($request->input('member_ids'));
         $filter->addProjectIdsFilter($request->input('project_ids'));
-        $filter->addTagIdsFilter($request->input('tag_ids'));
+        $filter->addTagIdsFilter($request->input('tag_ids'), $request->getTagMatchType());
         $filter->addTaskIdsFilter($request->input('task_ids'));
         $filter->addClientIdsFilter($request->input('client_ids'));
         $filter->addBillableFilter($request->input('billable'));

app/Http/Requests/V1/Report/ReportStoreRequest.php

@@ -4,6 +4,7 @@ declare(strict_types=1);
 
 namespace App\Http\Requests\V1\Report;
 
+use App\Enums\TagMatchType;
 use App\Enums\TimeEntryAggregationType;
 use App\Enums\TimeEntryAggregationTypeInterval;
 use App\Enums\TimeEntryRoundingType;
@@ -124,6 +125,11 @@ class ReportStoreRequest extends BaseFormRequest
                     }
                 },
             ],
+            'properties.tag_match_type' => [
+                'nullable',
+                'string',
+                Rule::enum(TagMatchType::class),
+            ],
             'properties.task_ids' => [
                 'nullable',
                 'array',
@@ -249,6 +255,15 @@ class ReportStoreRequest extends BaseFormRequest
         return TimeEntryAggregationTypeInterval::from($this->input('properties.history_group'));
     }
 
+    public function getPropertyTagMatchType(): ?TagMatchType
+    {
+        if (! $this->has('properties.tag_match_type') || $this->input('properties.tag_match_type') === null) {
+            return null;
+        }
+
+        return TagMatchType::from($this->input('properties.tag_match_type'));
+    }
+
     public function getPropertyRoundingType(): ?TimeEntryRoundingType
     {
         if (! $this->has('properties.rounding_type') || $this->input('properties.rounding_type') === null) {

app/Http/Requests/V1/TimeEntry/TimeEntryAggregateExportRequest.php

@@ -5,6 +5,7 @@ declare(strict_types=1);
 namespace App\Http\Requests\V1\TimeEntry;
 
 use App\Enums\ExportFormat;
+use App\Enums\TagMatchType;
 use App\Enums\TimeEntryAggregationType;
 use App\Enums\TimeEntryAggregationTypeInterval;
 use App\Enums\TimeEntryRoundingType;
@@ -139,6 +140,10 @@ class TimeEntryAggregateExportRequest extends BaseFormRequest
                     })->uuid()->validate($attribute, $value, $fail);
                 },
             ],
+            'tag_match_type' => [
+                'string',
+                Rule::enum(TagMatchType::class),
+            ],
             // Filter by task IDs, task IDs are OR combined
             'task_ids' => [
                 'array',
@@ -246,6 +251,15 @@ class TimeEntryAggregateExportRequest extends BaseFormRequest
         return ExportFormat::from($this->validated('format'));
     }
 
+    public function getTagMatchType(): ?TagMatchType
+    {
+        if (! $this->has('tag_match_type') || $this->validated('tag_match_type') === null) {
+            return null;
+        }
+
+        return TagMatchType::from($this->validated('tag_match_type'));
+    }
+
     public function getRoundingType(): ?TimeEntryRoundingType
     {
         if (! $this->has('rounding_type') || $this->validated('rounding_type') === null) {

app/Http/Requests/V1/TimeEntry/TimeEntryAggregateRequest.php

@@ -4,6 +4,7 @@ declare(strict_types=1);
 
 namespace App\Http\Requests\V1\TimeEntry;
 
+use App\Enums\TagMatchType;
 use App\Enums\TimeEntryAggregationType;
 use App\Enums\TimeEntryRoundingType;
 use App\Http\Requests\V1\BaseFormRequest;
@@ -125,6 +126,10 @@ class TimeEntryAggregateRequest extends BaseFormRequest
                     })->uuid()->validate($attribute, $value, $fail);
                 },
             ],
+            'tag_match_type' => [
+                'string',
+                Rule::enum(TagMatchType::class),
+            ],
             // Filter by task IDs, task IDs are OR combined
             'task_ids' => [
                 'array',
@@ -208,6 +213,15 @@ class TimeEntryAggregateRequest extends BaseFormRequest
         return $this->input('end') !== null ? Carbon::createFromFormat('Y-m-d\TH:i:s\Z', $this->input('end'), 'UTC') : null;
     }
 
+    public function getTagMatchType(): ?TagMatchType
+    {
+        if (! $this->has('tag_match_type') || $this->validated('tag_match_type') === null) {
+            return null;
+        }
+
+        return TagMatchType::from($this->validated('tag_match_type'));
+    }
+
     public function getRoundingType(): ?TimeEntryRoundingType
     {
         if (! $this->has('rounding_type') || $this->validated('rounding_type') === null) {

app/Http/Requests/V1/TimeEntry/TimeEntryIndexExportRequest.php

@@ -5,6 +5,7 @@ declare(strict_types=1);
 namespace App\Http\Requests\V1\TimeEntry;
 
 use App\Enums\ExportFormat;
+use App\Enums\TagMatchType;
 use App\Enums\TimeEntryRoundingType;
 use App\Models\Client;
 use App\Models\Member;
@@ -110,6 +111,10 @@ class TimeEntryIndexExportRequest extends TimeEntryIndexRequest
                     })->uuid()->validate($attribute, $value, $fail);
                 },
             ],
+            'tag_match_type' => [
+                'string',
+                Rule::enum(TagMatchType::class),
+            ],
             // Filter by task IDs, task IDs are OR combined
             'task_ids' => [
                 'array',
@@ -215,6 +220,15 @@ class TimeEntryIndexExportRequest extends TimeEntryIndexRequest
         return ExportFormat::from($this->validated('format'));
     }
 
+    public function getTagMatchType(): ?TagMatchType
+    {
+        if (! $this->has('tag_match_type') || $this->validated('tag_match_type') === null) {
+            return null;
+        }
+
+        return TagMatchType::from($this->validated('tag_match_type'));
+    }
+
     public function getRoundingType(): ?TimeEntryRoundingType
     {
         if (! $this->has('rounding_type') || $this->validated('rounding_type') === null) {

app/Http/Requests/V1/TimeEntry/TimeEntryIndexRequest.php

@@ -4,6 +4,7 @@ declare(strict_types=1);
 
 namespace App\Http\Requests\V1\TimeEntry;
 
+use App\Enums\TagMatchType;
 use App\Enums\TimeEntryRoundingType;
 use App\Http\Requests\V1\BaseFormRequest;
 use App\Models\Client;
@@ -103,6 +104,10 @@ class TimeEntryIndexRequest extends BaseFormRequest
                     })->uuid()->validate($attribute, $value, $fail);
                 },
             ],
+            'tag_match_type' => [
+                'string',
+                Rule::enum(TagMatchType::class),
+            ],
             // Filter by task IDs, task IDs are OR combined
             'task_ids' => [
                 'array',
@@ -190,6 +195,15 @@ class TimeEntryIndexRequest extends BaseFormRequest
         return $this->has('offset') ? (int) $this->validated('offset', 0) : 0;
     }
 
+    public function getTagMatchType(): ?TagMatchType
+    {
+        if (! $this->has('tag_match_type') || $this->validated('tag_match_type') === null) {
+            return null;
+        }
+
+        return TagMatchType::from($this->validated('tag_match_type'));
+    }
+
     public function getRoundingType(): ?TimeEntryRoundingType
     {
         if (! $this->has('rounding_type') || $this->validated('rounding_type') === null) {

app/Http/Resources/V1/Report/DetailedReportResource.php

@@ -56,6 +56,8 @@ class DetailedReportResource extends BaseResource
                 'project_ids' => $this->resource->properties->projectIds?->toArray(),
                 /** @var array<string>|null $tags_ids Filter by tag IDs, tag IDs are OR combined */
                 'tag_ids' => $this->resource->properties->tagIds?->toArray(),
+                /** @var string|null $tag_match_type Tag match type */
+                'tag_match_type' => $this->resource->properties->tagMatchType?->value,
                 /** @var array<string>|null $task_ids Filter by task IDs, task IDs are OR combined */
                 'task_ids' => $this->resource->properties->taskIds?->toArray(),
                 /** @var string|null $rounding_type Rounding type for time entries */

app/Service/Dto/ReportPropertiesDto.php

@@ -4,6 +4,7 @@ declare(strict_types=1);
 
 namespace App\Service\Dto;
 
+use App\Enums\TagMatchType;
 use App\Enums\TimeEntryAggregationType;
 use App\Enums\TimeEntryAggregationTypeInterval;
 use App\Enums\TimeEntryRoundingType;
@@ -56,6 +57,8 @@ class ReportPropertiesDto implements Castable
      */
     public ?Collection $tagIds = null;
 
+    public ?TagMatchType $tagMatchType = null;
+
     /**
      * @var Collection<int, string>|null
      */
@@ -115,6 +118,7 @@ class ReportPropertiesDto implements Castable
                 $dto->clientIds = $data->clientIds !== null ? ReportPropertiesDto::idArrayToCollection($data->clientIds) : null;
                 $dto->projectIds = $data->projectIds !== null ? ReportPropertiesDto::idArrayToCollection($data->projectIds) : null;
                 $dto->tagIds = $data->tagIds !== null ? ReportPropertiesDto::idArrayToCollection($data->tagIds) : null;
+                $dto->tagMatchType = isset($data->tagMatchType) ? TagMatchType::from($data->tagMatchType) : null;
                 $dto->taskIds = $data->taskIds ? ReportPropertiesDto::idArrayToCollection($data->taskIds) : null;
                 $dto->group = TimeEntryAggregationType::from($data->group);
                 $dto->subGroup = TimeEntryAggregationType::from($data->subGroup);
@@ -144,6 +148,7 @@ class ReportPropertiesDto implements Castable
                     'clientIds' => $value->clientIds?->toArray(),
                     'projectIds' => $value->projectIds?->toArray(),
                     'tagIds' => $value->tagIds?->toArray(),
+                    'tagMatchType' => $value->tagMatchType?->value,
                     'taskIds' => $value->taskIds?->toArray(),
                     'group' => $value->group->value,
                     'subGroup' => $value->subGroup->value,
@@ -216,6 +221,11 @@ class ReportPropertiesDto implements Castable
         $this->tagIds = $tagIds !== null ? ReportPropertiesDto::idArrayToCollection($tagIds) : null;
     }
 
+    public function setTagMatchType(?TagMatchType $tagMatchType): void
+    {
+        $this->tagMatchType = $tagMatchType;
+    }
+
     /**
      * @param  array<mixed>|null  $taskIds
      */

app/Service/TimeEntryFilter.php

@@ -4,6 +4,7 @@ declare(strict_types=1);
 
 namespace App\Service;
 
+use App\Enums\TagMatchType;
 use App\Models\Member;
 use App\Models\TimeEntry;
 use Illuminate\Database\Eloquent\Builder;
@@ -192,15 +193,21 @@ class TimeEntryFilter
     /**
      * @param  array<string>|null  $tagIds
      */
-    public function addTagIdsFilter(?array $tagIds): self
+    public function addTagIdsFilter(?array $tagIds, ?TagMatchType $tagMatchType = TagMatchType::Contains): self
     {
         if ($tagIds === null) {
             return $this;
         }
+        $tagMatchType ??= TagMatchType::Contains;
         $includeNone = in_array(self::NONE_VALUE, $tagIds, true);
         $tagIds = array_values(array_filter($tagIds, fn (string $id): bool => $id !== self::NONE_VALUE));
+        // An empty selection (no tag IDs and not filtering for "none") is no constraint, so apply nothing.
+        // This also prevents the not-contains branch from collapsing into "only entries with null tags".
+        if (count($tagIds) === 0 && ! $includeNone) {
+            return $this;
+        }
 
-        $this->builder->where(function (Builder $builder) use ($tagIds, $includeNone): void {
+        $tagCondition = function (Builder $builder) use ($tagIds, $includeNone): void {
             foreach ($tagIds as $tagId) {
                 $builder->orWhereJsonContains('tags', $tagId);
             }
@@ -209,7 +216,18 @@ class TimeEntryFilter
                     $query->whereJsonLength('tags', 0)->orWhereNull('tags');
                 });
             }
-        });
+        };
+
+        if ($tagMatchType === TagMatchType::NotContains) {
+            $this->builder->where(function (Builder $builder) use ($tagCondition, $includeNone): void {
+                $builder->whereNot($tagCondition);
+                if (! $includeNone) {
+                    $builder->orWhereNull('tags');
+                }
+            });
+        } else {
+            $this->builder->where($tagCondition);
+        }
 
         return $this;
     }

e2e/reporting-tag-match.spec.ts

@@ -0,0 +1,72 @@
+import { expect } from '@playwright/test';
+import { test } from '../playwright/fixtures';
+import {
+    goToReportingDetailed,
+    waitForDetailedReportingUpdate,
+} from './utils/reporting';
+import { createTimeEntryWithTagViaApi } from './utils/api';
+
+// Each test registers a new user and creates test data via the API
+test.describe.configure({ timeout: 30000 });
+
+test('detailed reporting: "Does Not Contain" excludes entries with the selected tag', async ({
+    page,
+    ctx,
+}) => {
+    const tagA = 'MatchTagA ' + Math.floor(Math.random() * 10000);
+    const tagB = 'MatchTagB ' + Math.floor(Math.random() * 10000);
+    await createTimeEntryWithTagViaApi(ctx, tagA, '1h');
+    await createTimeEntryWithTagViaApi(ctx, tagB, '2h');
+
+    await goToReportingDetailed(page);
+    await expect(page.getByText(`Entry with tag ${tagA}`).first()).toBeVisible();
+    await expect(page.getByText(`Entry with tag ${tagB}`).first()).toBeVisible();
+
+    // Open the Tags dropdown, select tagA, then switch the match mode to "Does Not Contain"
+    await page.getByRole('button', { name: 'Tags' }).click();
+    await Promise.all([
+        waitForDetailedReportingUpdate(page),
+        page.getByRole('option').filter({ hasText: tagA }).click(),
+    ]);
+    await Promise.all([
+        waitForDetailedReportingUpdate(page),
+        page.getByRole('radio', { name: 'Does Not Contain', exact: true }).click(),
+    ]);
+    await page.keyboard.press('Escape');
+
+    // The entry with tagA is excluded; the entry with tagB remains
+    await expect(page.getByText(`Entry with tag ${tagA}`)).toHaveCount(0);
+    await expect(page.getByText(`Entry with tag ${tagB}`).first()).toBeVisible();
+});
+
+test('detailed reporting: toggling between "Contains" and "Does Not Contain" flips the result', async ({
+    page,
+    ctx,
+}) => {
+    const tagA = 'ToggleTagA ' + Math.floor(Math.random() * 10000);
+    const tagB = 'ToggleTagB ' + Math.floor(Math.random() * 10000);
+    await createTimeEntryWithTagViaApi(ctx, tagA, '1h');
+    await createTimeEntryWithTagViaApi(ctx, tagB, '2h');
+
+    await goToReportingDetailed(page);
+    await page.getByRole('button', { name: 'Tags' }).click();
+    await Promise.all([
+        waitForDetailedReportingUpdate(page),
+        page.getByRole('option').filter({ hasText: tagA }).click(),
+    ]);
+
+    // "Contains" tagA -> only the tagA entry is listed
+    await page.keyboard.press('Escape');
+    await expect(page.getByText(`Entry with tag ${tagA}`).first()).toBeVisible();
+    await expect(page.getByText(`Entry with tag ${tagB}`)).toHaveCount(0);
+
+    // "Does Not Contain" tagA -> flips to the tagB entry
+    await page.getByRole('button', { name: 'Tags' }).click();
+    await Promise.all([
+        waitForDetailedReportingUpdate(page),
+        page.getByRole('radio', { name: 'Does Not Contain', exact: true }).click(),
+    ]);
+    await page.keyboard.press('Escape');
+    await expect(page.getByText(`Entry with tag ${tagB}`).first()).toBeVisible();
+    await expect(page.getByText(`Entry with tag ${tagA}`)).toHaveCount(0);
+});

resources/js/Components/Common/Reporting/ReportingFilterBar.vue

@@ -1,6 +1,13 @@
 <script setup lang="ts">
 import { CheckCircleIcon, TagIcon, UserGroupIcon } from '@heroicons/vue/20/solid';
 import { FolderIcon } from '@heroicons/vue/16/solid';
+import { Check } from '@lucide/vue';
+import {
+    RadioGroupIndicator,
+    RadioGroupItem,
+    RadioGroupRoot,
+    type AcceptableValue,
+} from 'reka-ui';
 import BillableIcon from '@/packages/ui/src/Icons/BillableIcon.vue';
 import ReportingRoundingControls from '@/Components/Common/Reporting/ReportingRoundingControls.vue';
 import TaskMultiselectDropdown from '@/Components/Common/Task/TaskMultiselectDropdown.vue';
@@ -14,6 +21,7 @@ import DateRangePicker from '@/packages/ui/src/Input/DateRangePicker.vue';
 import TagDropdown from '@/packages/ui/src/Tag/TagDropdown.vue';
 import { useTagsQuery } from '@/utils/useTagsQuery';
 import { useTagsStore } from '@/utils/useTags';
+import type { TagMatchType } from '@/types/reporting';
 
 type TimeEntryRoundingType = 'up' | 'down' | 'nearest';
 
@@ -22,6 +30,7 @@ const selectedProjects = defineModel<string[]>('selectedProjects', { required: t
 const selectedTasks = defineModel<string[]>('selectedTasks', { required: true });
 const selectedClients = defineModel<string[]>('selectedClients', { required: true });
 const selectedTags = defineModel<string[]>('selectedTags', { required: true });
+const tagMatchType = defineModel<TagMatchType>('tagMatchType', { required: true });
 const billable = defineModel<'true' | 'false' | null>('billable', { required: true });
 const roundingEnabled = defineModel<boolean>('roundingEnabled', { required: true });
 const roundingType = defineModel<TimeEntryRoundingType>('roundingType', { required: true });
@@ -35,6 +44,16 @@ const emit = defineEmits<{
 
 const { tags } = useTagsQuery();
 
+const tagMatchOptions: { value: TagMatchType; label: string }[] = [
+    { value: 'contains', label: 'Contains' },
+    { value: 'not_contains', label: 'Does Not Contain' },
+];
+
+function selectTagMatchType(value: AcceptableValue) {
+    tagMatchType.value = value as TagMatchType;
+    emit('submit');
+}
+
 async function createTag(name: string) {
     return await useTagsStore().createTag(name);
 }
@@ -93,6 +112,34 @@ async function createTag(name: string) {
                             title="Tags"
                             :icon="TagIcon" />
                     </template>
+                    <template #content-before-list>
+                        <div class="mt-2 border-b border-card-background-separator pb-2">
+                            <div
+                                id="tag-match-type-label"
+                                class="mb-1.5 px-2 text-xs font-medium text-text-tertiary uppercase">
+                                Match
+                            </div>
+                            <RadioGroupRoot
+                                :model-value="tagMatchType"
+                                aria-labelledby="tag-match-type-label"
+                                class="space-y-1"
+                                @update:model-value="selectTagMatchType">
+                                <RadioGroupItem
+                                    v-for="option in tagMatchOptions"
+                                    :key="option.value"
+                                    :value="option.value"
+                                    class="relative flex w-full items-center rounded-md py-1.5 pl-2 pr-8 text-left text-sm font-medium text-text-secondary hover:bg-card-background-active data-[state=checked]:text-text-primary">
+                                    {{ option.label }}
+                                    <span
+                                        class="absolute right-2 flex h-3.5 w-3.5 items-center justify-center">
+                                        <RadioGroupIndicator>
+                                            <Check class="h-4 w-4" />
+                                        </RadioGroupIndicator>
+                                    </span>
+                                </RadioGroupItem>
+                            </RadioGroupRoot>
+                        </div>
+                    </template>
                 </TagDropdown>
 
                 <Select v-model="billable" @update:model-value="emit('submit')">

resources/js/Components/Common/Reporting/ReportingOverview.vue

@@ -49,6 +49,7 @@ import type { ExportFormat } from '@/types/reporting';
 import { getRandomColorWithSeed } from '@/packages/ui/src/utils/color';
 import { useProjectsQuery } from '@/utils/useProjectsQuery';
 import { useAggregatedTimeEntriesQuery } from '@/utils/useAggregatedTimeEntriesQuery';
+import type { TagMatchType } from '@/types/reporting';
 
 type TimeEntryRoundingType = 'up' | 'down' | 'nearest';
 
@@ -67,6 +68,7 @@ const selectedProjects = ref<string[]>([]);
 const selectedMembers = ref<string[]>([]);
 const selectedTasks = ref<string[]>([]);
 const selectedClients = ref<string[]>([]);
+const tagMatchType = ref<TagMatchType>('contains');
 
 const billable = ref<'true' | 'false' | null>(null);
 const roundingEnabled = ref<boolean>(false);
@@ -122,6 +124,7 @@ const filterParams = computed<AggregatedTimeEntriesQueryParams>(() => {
         task_ids: selectedTasks.value.length > 0 ? selectedTasks.value : undefined,
         client_ids: selectedClients.value.length > 0 ? selectedClients.value : undefined,
         tag_ids: selectedTags.value.length > 0 ? selectedTags.value : undefined,
+        tag_match_type: selectedTags.value.length > 0 ? tagMatchType.value : undefined,
         billable: billable.value !== null ? billable.value : undefined,
         member_id: getCurrentRole() === 'employee' ? getCurrentMembershipId() : undefined,
         rounding_type: roundingEnabled.value ? roundingType.value : undefined,
@@ -366,6 +369,7 @@ const tableData = computed(() => {
         v-model:selected-tasks="selectedTasks"
         v-model:selected-clients="selectedClients"
         v-model:selected-tags="selectedTags"
+        v-model:tag-match-type="tagMatchType"
         v-model:billable="billable"
         v-model:rounding-enabled="roundingEnabled"
         v-model:rounding-type="roundingType"

resources/js/Pages/ReportingDetailed.vue

@@ -67,6 +67,7 @@ import ReportingFilterBar from '@/Components/Common/Reporting/ReportingFilterBar
 import { useTimeEntriesReportQuery } from '@/utils/useTimeEntriesReportQuery';
 import { useTimeEntriesMutations } from '@/utils/useTimeEntriesMutations';
 import { useOrganizationQuery } from '@/utils/useOrganizationQuery';
+import type { TagMatchType } from '@/types/reporting';
 
 // TimeEntryRoundingType is now defined in ReportingRoundingControls component
 type TimeEntryRoundingType = 'up' | 'down' | 'nearest';
@@ -84,6 +85,7 @@ const selectedProjects = ref<string[]>([]);
 const selectedMembers = ref<string[]>([]);
 const selectedTasks = ref<string[]>([]);
 const selectedClients = ref<string[]>([]);
+const tagMatchType = ref<TagMatchType>('contains');
 const billable = ref<'true' | 'false' | null>(null);
 const roundingEnabled = ref<boolean>(false);
 const roundingType = ref<TimeEntryRoundingType>('nearest');
@@ -115,6 +117,7 @@ function getFilterAttributes() {
         task_ids: selectedTasks.value.length > 0 ? selectedTasks.value : undefined,
         client_ids: selectedClients.value.length > 0 ? selectedClients.value : undefined,
         tag_ids: selectedTags.value.length > 0 ? selectedTags.value : undefined,
+        tag_match_type: selectedTags.value.length > 0 ? tagMatchType.value : undefined,
         billable: billable.value !== null ? billable.value : undefined,
         rounding_type: roundingEnabled.value ? roundingType.value : undefined,
         rounding_minutes: roundingEnabled.value ? roundingMinutes.value : undefined,
@@ -337,6 +340,7 @@ async function downloadExport(format: ExportFormat) {
             v-model:selected-tasks="selectedTasks"
             v-model:selected-clients="selectedClients"
             v-model:selected-tags="selectedTags"
+            v-model:tag-match-type="tagMatchType"
             v-model:billable="billable"
             v-model:rounding-enabled="roundingEnabled"
             v-model:rounding-type="roundingType"

resources/js/packages/api/src/openapi.json.client.ts

@@ -448,6 +448,7 @@ const ReportStoreRequest = z
                 client_ids: z.union([z.array(z.string()), z.null()]).optional(),
                 project_ids: z.union([z.array(z.string()), z.null()]).optional(),
                 tag_ids: z.union([z.array(z.string()), z.null()]).optional(),
+                tag_match_type: z.enum(['contains', 'not_contains']).optional(),
                 task_ids: z.union([z.array(z.string()), z.null()]).optional(),
                 group: TimeEntryAggregationType,
                 sub_group: TimeEntryAggregationType,
@@ -481,6 +482,7 @@ const DetailedReportResource = z
                 client_ids: z.union([z.array(z.string()), z.null()]),
                 project_ids: z.union([z.array(z.string()), z.null()]),
                 tag_ids: z.union([z.array(z.string()), z.null()]),
+                tag_match_type: z.union([z.enum(['contains', 'not_contains']), z.null()]),
                 task_ids: z.union([z.array(z.string()), z.null()]),
                 rounding_type: z.union([z.string(), z.null()]),
                 rounding_minutes: z.union([z.number(), z.null()]),
@@ -3784,6 +3786,11 @@ Users with the permission `time-entries:view:own` can only use this en
                 type: 'Query',
                 schema: z.array(z.string()).min(1).optional(),
             },
+            {
+                name: 'tag_match_type',
+                type: 'Query',
+                schema: z.enum(['contains', 'not_contains']).optional(),
+            },
             {
                 name: 'task_ids',
                 type: 'Query',
@@ -4165,6 +4172,11 @@ If the group parameters are all set to `null` or are all missing, the
                 type: 'Query',
                 schema: z.array(z.string()).min(1).optional(),
             },
+            {
+                name: 'tag_match_type',
+                type: 'Query',
+                schema: z.enum(['contains', 'not_contains']).optional(),
+            },
             {
                 name: 'task_ids',
                 type: 'Query',
@@ -4359,6 +4371,11 @@ If the group parameters are all set to `null` or are all missing, the
                 type: 'Query',
                 schema: z.array(z.string()).min(1).optional(),
             },
+            {
+                name: 'tag_match_type',
+                type: 'Query',
+                schema: z.enum(['contains', 'not_contains']).optional(),
+            },
             {
                 name: 'task_ids',
                 type: 'Query',
@@ -4487,6 +4504,11 @@ If the group parameters are all set to `null` or are all missing, the
                 type: 'Query',
                 schema: z.array(z.string()).min(1).optional(),
             },
+            {
+                name: 'tag_match_type',
+                type: 'Query',
+                schema: z.enum(['contains', 'not_contains']).optional(),
+            },
             {
                 name: 'task_ids',
                 type: 'Query',

resources/js/packages/ui/src/Tag/TagDropdown.vue

@@ -114,6 +114,7 @@ const showCreateTagModal = ref(false);
                         class="w-full rounded-md border border-input-border bg-input-background px-3 py-1.5 text-sm text-text-primary placeholder:text-text-tertiary focus:outline-none"
                         placeholder="Search for a Tag..." />
                 </ComboboxAnchor>
+                <slot name="content-before-list"></slot>
                 <ComboboxContent
                     :dismiss-able="false"
                     position="inline"

resources/js/types/reporting.ts

@@ -1 +1,2 @@
 export type ExportFormat = 'xlsx' | 'csv' | 'ods' | 'pdf';
+export type TagMatchType = 'contains' | 'not_contains';

tests/Unit/Endpoint/Api/V1/Public/PublicReportEndpointTest.php

@@ -4,6 +4,7 @@ declare(strict_types=1);
 
 namespace Tests\Unit\Endpoint\Api\V1\Public;
 
+use App\Enums\TagMatchType;
 use App\Enums\TimeEntryAggregationType;
 use App\Enums\TimeEntryAggregationTypeInterval;
 use App\Enums\Weekday;
@@ -667,4 +668,58 @@ class PublicReportEndpointTest extends ApiEndpointTestAbstract
             ],
         ]);
     }
+
+    public function test_show_applies_not_contains_tag_match_type(): void
+    {
+        // Arrange
+        $organization = Organization::factory()->create();
+        $tagA = Tag::factory()->forOrganization($organization)->create();
+        $tagB = Tag::factory()->forOrganization($organization)->create();
+
+        // Entry with tagA (should be excluded by "does not contain tagA")
+        TimeEntry::factory()->forOrganization($organization)
+            ->startWithDuration(now()->subDay(), 100)
+            ->create([
+                'tags' => [$tagA->getKey()],
+            ]);
+        // Entry with a different tag (should be included)
+        TimeEntry::factory()->forOrganization($organization)
+            ->startWithDuration(now()->subDay(), 200)
+            ->create([
+                'tags' => [$tagB->getKey()],
+            ]);
+        // Entry without tags (should be included)
+        TimeEntry::factory()->forOrganization($organization)
+            ->startWithDuration(now()->subDay(), 50)
+            ->create();
+
+        $reportDto = new ReportPropertiesDto;
+        $reportDto->start = now()->subDays(2);
+        $reportDto->end = now();
+        $reportDto->group = TimeEntryAggregationType::Project;
+        $reportDto->subGroup = TimeEntryAggregationType::Task;
+        $reportDto->historyGroup = TimeEntryAggregationTypeInterval::Day;
+        $reportDto->weekStart = Weekday::Monday;
+        $reportDto->timezone = 'Europe/Vienna';
+        $reportDto->setTagIds([$tagA->getKey()]);
+        $reportDto->setTagMatchType(TagMatchType::NotContains);
+        $report = Report::factory()->forOrganization($organization)->public()->create([
+            'public_until' => null,
+            'properties' => $reportDto,
+        ]);
+
+        // Act
+        $response = $this->getJson(route('api.v1.public.reports.show'), [
+            'X-Api-Key' => $report->share_secret,
+        ]);
+
+        // Assert: tagA entry (100s) excluded; tagB (200s) + untagged (50s) included
+        $response->assertOk();
+        $response->assertJson([
+            'data' => [
+                'seconds' => 250,
+                'grouped_type' => TimeEntryAggregationType::Project->value,
+            ],
+        ]);
+    }
 }

tests/Unit/Endpoint/Api/V1/ReportEndpointTest.php

@@ -4,6 +4,7 @@ declare(strict_types=1);
 
 namespace Tests\Unit\Endpoint\Api\V1;
 
+use App\Enums\TagMatchType;
 use App\Enums\TimeEntryAggregationType;
 use App\Enums\TimeEntryRoundingType;
 use App\Enums\Weekday;
@@ -685,4 +686,64 @@ class ReportEndpointTest extends ApiEndpointTestAbstract
             'id' => $report->getKey(),
         ]);
     }
+
+    public function test_store_endpoint_persists_tag_match_type(): void
+    {
+        // Arrange
+        $data = $this->createUserWithPermission([
+            'reports:create',
+        ]);
+        $tag = Tag::factory()->forOrganization($data->organization)->create();
+        Passport::actingAs($data->user);
+
+        // Act
+        $response = $this->withoutExceptionHandling()->postJson(route('api.v1.reports.store', [$data->organization->getKey()]), [
+            'name' => 'Report with tag match type',
+            'is_public' => false,
+            'properties' => [
+                'start' => Carbon::now()->subDays(30)->toIso8601ZuluString(),
+                'end' => Carbon::now()->toIso8601ZuluString(),
+                'group' => TimeEntryAggregationType::Project->value,
+                'sub_group' => TimeEntryAggregationType::Task->value,
+                'history_group' => TimeEntryAggregationType::Day->value,
+                'tag_ids' => [$tag->getKey()],
+                'tag_match_type' => TagMatchType::NotContains->value,
+            ],
+        ]);
+
+        // Assert
+        $response->assertStatus(201);
+        /** @var Report $report */
+        $report = Report::query()->findOrFail($response->json('data.id'));
+        $this->assertSame(TagMatchType::NotContains, $report->properties->tagMatchType);
+        // DetailedReportResource exposes the match type in the response
+        $response->assertJsonPath('data.properties.tag_match_type', TagMatchType::NotContains->value);
+    }
+
+    public function test_store_endpoint_rejects_invalid_tag_match_type(): void
+    {
+        // Arrange
+        $data = $this->createUserWithPermission([
+            'reports:create',
+        ]);
+        Passport::actingAs($data->user);
+
+        // Act
+        $response = $this->postJson(route('api.v1.reports.store', [$data->organization->getKey()]), [
+            'name' => 'Report with invalid tag match type',
+            'is_public' => false,
+            'properties' => [
+                'start' => Carbon::now()->subDays(30)->toIso8601ZuluString(),
+                'end' => Carbon::now()->toIso8601ZuluString(),
+                'group' => TimeEntryAggregationType::Project->value,
+                'sub_group' => TimeEntryAggregationType::Task->value,
+                'history_group' => TimeEntryAggregationType::Day->value,
+                'tag_match_type' => 'invalid_value',
+            ],
+        ]);
+
+        // Assert
+        $response->assertStatus(422);
+        $response->assertInvalid(['properties.tag_match_type']);
+    }
 }

tests/Unit/Endpoint/Api/V1/TimeEntryEndpointTest.php

@@ -6,6 +6,7 @@ namespace Tests\Unit\Endpoint\Api\V1;
 
 use App\Enums\ExportFormat;
 use App\Enums\Role;
+use App\Enums\TagMatchType;
 use App\Enums\TimeEntryAggregationType;
 use App\Enums\TimeEntryAggregationTypeInterval;
 use App\Enums\TimeEntryRoundingType;
@@ -4351,4 +4352,153 @@ class TimeEntryEndpointTest extends ApiEndpointTestAbstract
         $response->assertJsonCount(1, 'data');
         $response->assertJsonPath('data.0.id', $timeEntryWithoutTag->getKey());
     }
+
+    public function test_index_endpoint_with_not_contains_tag_match_type_excludes_entries_with_tag(): void
+    {
+        // Arrange
+        $data = $this->createUserWithPermission([
+            'time-entries:view:all',
+        ]);
+        $tag = Tag::factory()->forOrganization($data->organization)->create();
+        $timeEntryWithTag = TimeEntry::factory()
+            ->forOrganization($data->organization)
+            ->forMember($data->member)
+            ->create([
+                'start' => Carbon::now()->subHour(),
+                'tags' => [$tag->getKey()],
+            ]);
+        $timeEntryWithEmptyTags = TimeEntry::factory()
+            ->forOrganization($data->organization)
+            ->forMember($data->member)
+            ->create([
+                'start' => Carbon::now()->subHour(),
+                'tags' => [],
+            ]);
+        $timeEntryWithNullTags = TimeEntry::factory()
+            ->forOrganization($data->organization)
+            ->forMember($data->member)
+            ->create([
+                'start' => Carbon::now()->subHour(),
+                'tags' => null,
+            ]);
+        Passport::actingAs($data->user);
+
+        // Act
+        $response = $this->getJson(route('api.v1.time-entries.index', [
+            $data->organization->getKey(),
+            'tag_ids' => [$tag->getKey()],
+            'tag_match_type' => TagMatchType::NotContains->value,
+            'start' => Carbon::now()->subDay()->toIso8601ZuluString(),
+            'end' => Carbon::now()->addDay()->toIso8601ZuluString(),
+        ]));
+
+        // Assert: the tagged entry is excluded; the untagged (empty + null) entries remain
+        $response->assertValid();
+        $this->assertResponseCode($response, 200);
+        $response->assertJsonCount(2, 'data');
+        $returnedIds = collect($response->json('data'))->pluck('id');
+        $this->assertTrue($returnedIds->contains($timeEntryWithEmptyTags->getKey()));
+        $this->assertTrue($returnedIds->contains($timeEntryWithNullTags->getKey()));
+        $this->assertFalse($returnedIds->contains($timeEntryWithTag->getKey()));
+    }
+
+    public function test_index_endpoint_with_contains_tag_match_type_returns_only_entries_with_tag(): void
+    {
+        // Arrange
+        $data = $this->createUserWithPermission([
+            'time-entries:view:all',
+        ]);
+        $tag = Tag::factory()->forOrganization($data->organization)->create();
+        $timeEntryWithTag = TimeEntry::factory()
+            ->forOrganization($data->organization)
+            ->forMember($data->member)
+            ->create([
+                'start' => Carbon::now()->subHour(),
+                'tags' => [$tag->getKey()],
+            ]);
+        TimeEntry::factory()
+            ->forOrganization($data->organization)
+            ->forMember($data->member)
+            ->create([
+                'start' => Carbon::now()->subHour(),
+                'tags' => [],
+            ]);
+        Passport::actingAs($data->user);
+
+        // Act
+        $response = $this->getJson(route('api.v1.time-entries.index', [
+            $data->organization->getKey(),
+            'tag_ids' => [$tag->getKey()],
+            'tag_match_type' => TagMatchType::Contains->value,
+            'start' => Carbon::now()->subDay()->toIso8601ZuluString(),
+            'end' => Carbon::now()->addDay()->toIso8601ZuluString(),
+        ]));
+
+        // Assert: only the entry that has the tag
+        $response->assertValid();
+        $this->assertResponseCode($response, 200);
+        $response->assertJsonCount(1, 'data');
+        $response->assertJsonPath('data.0.id', $timeEntryWithTag->getKey());
+    }
+
+    public function test_index_endpoint_rejects_invalid_tag_match_type(): void
+    {
+        // Arrange
+        $data = $this->createUserWithPermission([
+            'time-entries:view:all',
+        ]);
+        $tag = Tag::factory()->forOrganization($data->organization)->create();
+        Passport::actingAs($data->user);
+
+        // Act
+        $response = $this->getJson(route('api.v1.time-entries.index', [
+            $data->organization->getKey(),
+            'tag_ids' => [$tag->getKey()],
+            'tag_match_type' => 'invalid_value',
+            'start' => Carbon::now()->subDay()->toIso8601ZuluString(),
+            'end' => Carbon::now()->addDay()->toIso8601ZuluString(),
+        ]));
+
+        // Assert
+        $this->assertResponseCode($response, 422);
+        $response->assertInvalid(['tag_match_type']);
+    }
+
+    public function test_aggregate_endpoint_with_not_contains_tag_match_type_excludes_entries_with_tag(): void
+    {
+        // Arrange
+        $data = $this->createUserWithPermission([
+            'time-entries:view:all',
+        ]);
+        $tag = Tag::factory()->forOrganization($data->organization)->create();
+        TimeEntry::factory()
+            ->forOrganization($data->organization)
+            ->forMember($data->member)
+            ->startWithDuration(Carbon::now()->subHour(), 100)
+            ->create([
+                'tags' => [$tag->getKey()],
+            ]);
+        TimeEntry::factory()
+            ->forOrganization($data->organization)
+            ->forMember($data->member)
+            ->startWithDuration(Carbon::now()->subHour(), 200)
+            ->create([
+                'tags' => [],
+            ]);
+        Passport::actingAs($data->user);
+
+        // Act
+        $response = $this->getJson(route('api.v1.time-entries.aggregate', [
+            $data->organization->getKey(),
+            'tag_ids' => [$tag->getKey()],
+            'tag_match_type' => TagMatchType::NotContains->value,
+            'start' => Carbon::now()->subDay()->toIso8601ZuluString(),
+            'end' => Carbon::now()->addDay()->toIso8601ZuluString(),
+        ]));
+
+        // Assert: only the untagged entry (200s) is aggregated
+        $response->assertValid();
+        $this->assertResponseCode($response, 200);
+        $response->assertJsonPath('data.seconds', 200);
+    }
 }

tests/Unit/Service/TimeEntryFilterTest.php

@@ -4,6 +4,7 @@ declare(strict_types=1);
 
 namespace Tests\Unit\Service;
 
+use App\Enums\TagMatchType;
 use App\Models\Client;
 use App\Models\Project;
 use App\Models\Tag;
@@ -250,4 +251,188 @@ class TimeEntryFilterTest extends TestCaseWithDatabase
         $this->assertTrue($timeEntries->contains($timeEntryWithNoTags));
         $this->assertFalse($timeEntries->contains($timeEntryWithTag2));
     }
+
+    public function test_add_tag_ids_filter_not_contains_includes_entries_without_matching_tag(): void
+    {
+        // Arrange
+        $tag1 = Tag::factory()->create();
+        $tag2 = Tag::factory()->create();
+        $timeEntryWithTag1 = TimeEntry::factory()->create([
+            'tags' => [$tag1->getKey()],
+        ]);
+        $timeEntryWithTag2 = TimeEntry::factory()->create([
+            'tags' => [$tag2->getKey()],
+        ]);
+        $timeEntryWithAllTags = TimeEntry::factory()->create([
+            'tags' => [$tag1->getKey(), $tag2->getKey()],
+        ]);
+        $timeEntryWithEmptyTags = TimeEntry::factory()->create([
+            'tags' => [],
+        ]);
+        $timeEntryWithNullTags = TimeEntry::factory()->create([
+            'tags' => null,
+        ]);
+
+        $builder = TimeEntry::query();
+        $filter = new TimeEntryFilter($builder);
+
+        // Act
+        $filter->addTagIdsFilter([$tag1->getKey()], TagMatchType::NotContains);
+
+        // Assert
+        $timeEntries = $builder->get();
+        $this->assertCount(3, $timeEntries);
+        $this->assertFalse($timeEntries->contains($timeEntryWithTag1));
+        $this->assertTrue($timeEntries->contains($timeEntryWithTag2));
+        $this->assertFalse($timeEntries->contains($timeEntryWithAllTags));
+        $this->assertTrue($timeEntries->contains($timeEntryWithEmptyTags));
+        $this->assertTrue($timeEntries->contains($timeEntryWithNullTags));
+    }
+
+    public function test_add_tag_ids_filter_not_contains_with_none_excludes_entries_without_tags(): void
+    {
+        // Arrange
+        $tag = Tag::factory()->create();
+        $timeEntryWithTag = TimeEntry::factory()->create([
+            'tags' => [$tag->getKey()],
+        ]);
+        $timeEntryWithEmptyTags = TimeEntry::factory()->create([
+            'tags' => [],
+        ]);
+        $timeEntryWithNullTags = TimeEntry::factory()->create([
+            'tags' => null,
+        ]);
+
+        $builder = TimeEntry::query();
+        $filter = new TimeEntryFilter($builder);
+
+        // Act
+        $filter->addTagIdsFilter([TimeEntryFilter::NONE_VALUE], TagMatchType::NotContains);
+
+        // Assert
+        $timeEntries = $builder->get();
+        $this->assertCount(1, $timeEntries);
+        $this->assertTrue($timeEntries->contains($timeEntryWithTag));
+        $this->assertFalse($timeEntries->contains($timeEntryWithEmptyTags));
+        $this->assertFalse($timeEntries->contains($timeEntryWithNullTags));
+    }
+
+    public function test_add_tag_ids_filter_not_contains_with_multiple_tags_excludes_entries_with_any_of_them(): void
+    {
+        // Arrange
+        $tag1 = Tag::factory()->create();
+        $tag2 = Tag::factory()->create();
+        $tag3 = Tag::factory()->create();
+        $timeEntryWithTag1 = TimeEntry::factory()->create(['tags' => [$tag1->getKey()]]);
+        $timeEntryWithTag2 = TimeEntry::factory()->create(['tags' => [$tag2->getKey()]]);
+        $timeEntryWithTag3 = TimeEntry::factory()->create(['tags' => [$tag3->getKey()]]);
+        // a filtered tag (tag1) mixed with an unrelated one (tag3): still excluded
+        $timeEntryWithTag1AndTag3 = TimeEntry::factory()->create(['tags' => [$tag1->getKey(), $tag3->getKey()]]);
+        $timeEntryWithoutTags = TimeEntry::factory()->create(['tags' => null]);
+
+        $builder = TimeEntry::query();
+        $filter = new TimeEntryFilter($builder);
+
+        // Act: "does not contain tag1 or tag2" (NOT (has tag1 OR has tag2))
+        $filter->addTagIdsFilter([$tag1->getKey(), $tag2->getKey()], TagMatchType::NotContains);
+
+        // Assert: only entries that have neither tag1 nor tag2 remain
+        $timeEntries = $builder->get();
+        $this->assertCount(2, $timeEntries);
+        $this->assertFalse($timeEntries->contains($timeEntryWithTag1));
+        $this->assertFalse($timeEntries->contains($timeEntryWithTag2));
+        $this->assertTrue($timeEntries->contains($timeEntryWithTag3));
+        $this->assertFalse($timeEntries->contains($timeEntryWithTag1AndTag3));
+        $this->assertTrue($timeEntries->contains($timeEntryWithoutTags));
+    }
+
+    public function test_add_tag_ids_filter_contains_mode_returns_only_entries_with_tag(): void
+    {
+        // Arrange
+        $tag1 = Tag::factory()->create();
+        $tag2 = Tag::factory()->create();
+        $timeEntryWithTag1 = TimeEntry::factory()->create(['tags' => [$tag1->getKey()]]);
+        $timeEntryWithTag2 = TimeEntry::factory()->create(['tags' => [$tag2->getKey()]]);
+        $timeEntryWithEmptyTags = TimeEntry::factory()->create(['tags' => []]);
+        $timeEntryWithNullTags = TimeEntry::factory()->create(['tags' => null]);
+
+        $builder = TimeEntry::query();
+        $filter = new TimeEntryFilter($builder);
+
+        // Act: explicit contains mode
+        $filter->addTagIdsFilter([$tag1->getKey()], TagMatchType::Contains);
+
+        // Assert: only the entry that has tag1
+        $timeEntries = $builder->get();
+        $this->assertCount(1, $timeEntries);
+        $this->assertTrue($timeEntries->contains($timeEntryWithTag1));
+        $this->assertFalse($timeEntries->contains($timeEntryWithTag2));
+        $this->assertFalse($timeEntries->contains($timeEntryWithEmptyTags));
+        $this->assertFalse($timeEntries->contains($timeEntryWithNullTags));
+    }
+
+    public function test_add_tag_ids_filter_not_contains_with_none_and_tag_excludes_tagged_and_untagged(): void
+    {
+        // Arrange
+        $tag1 = Tag::factory()->create();
+        $tag2 = Tag::factory()->create();
+        $timeEntryWithTag1 = TimeEntry::factory()->create(['tags' => [$tag1->getKey()]]);
+        $timeEntryWithTag2 = TimeEntry::factory()->create(['tags' => [$tag2->getKey()]]);
+        $timeEntryWithBothTags = TimeEntry::factory()->create(['tags' => [$tag1->getKey(), $tag2->getKey()]]);
+        $timeEntryWithEmptyTags = TimeEntry::factory()->create(['tags' => []]);
+        $timeEntryWithNullTags = TimeEntry::factory()->create(['tags' => null]);
+
+        $builder = TimeEntry::query();
+        $filter = new TimeEntryFilter($builder);
+
+        // Act: NOT (has tag1 OR has no tags) => has at least one tag and not tag1
+        $filter->addTagIdsFilter([$tag1->getKey(), TimeEntryFilter::NONE_VALUE], TagMatchType::NotContains);
+
+        // Assert
+        $timeEntries = $builder->get();
+        $this->assertCount(1, $timeEntries);
+        $this->assertFalse($timeEntries->contains($timeEntryWithTag1));
+        $this->assertTrue($timeEntries->contains($timeEntryWithTag2));
+        $this->assertFalse($timeEntries->contains($timeEntryWithBothTags));
+        $this->assertFalse($timeEntries->contains($timeEntryWithEmptyTags));
+        $this->assertFalse($timeEntries->contains($timeEntryWithNullTags));
+    }
+
+    public function test_add_tag_ids_filter_with_empty_array_applies_no_filter(): void
+    {
+        // Arrange
+        $tag = Tag::factory()->create();
+        TimeEntry::factory()->create(['tags' => [$tag->getKey()]]);
+        TimeEntry::factory()->create(['tags' => []]);
+        TimeEntry::factory()->create(['tags' => null]);
+
+        // Act + Assert: an empty selection is no constraint in either mode
+        $builderNotContains = TimeEntry::query();
+        (new TimeEntryFilter($builderNotContains))->addTagIdsFilter([], TagMatchType::NotContains);
+        $this->assertCount(3, $builderNotContains->get());
+
+        $builderContains = TimeEntry::query();
+        (new TimeEntryFilter($builderContains))->addTagIdsFilter([], TagMatchType::Contains);
+        $this->assertCount(3, $builderContains->get());
+    }
+
+    public function test_add_tag_ids_filter_with_null_match_type_defaults_to_contains(): void
+    {
+        // Arrange
+        $tag = Tag::factory()->create();
+        $timeEntryWithTag = TimeEntry::factory()->create(['tags' => [$tag->getKey()]]);
+        $timeEntryWithoutTag = TimeEntry::factory()->create(['tags' => null]);
+
+        $builder = TimeEntry::query();
+        $filter = new TimeEntryFilter($builder);
+
+        // Act: a null match type falls back to "contains"
+        $filter->addTagIdsFilter([$tag->getKey()], null);
+
+        // Assert
+        $timeEntries = $builder->get();
+        $this->assertCount(1, $timeEntries);
+        $this->assertTrue($timeEntries->contains($timeEntryWithTag));
+        $this->assertFalse($timeEntries->contains($timeEntryWithoutTag));
+    }
 }