add timesheet unit and e2e tests; add unit test CI setup

resources/js/Components/Timesheet/TimesheetCell.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, it } from 'vitest';
+import { mount } from '@vue/test-utils';
+import { nextTick } from 'vue';
+import TimesheetCell from './TimesheetCell.vue';
+import { formatHumanReadableDuration } from '@/packages/ui/src/utils/time';
+import type { TimesheetCell as TimesheetCellType } from '@/utils/useTimesheetGrid';
+
+function buildCell(totalSeconds: number): TimesheetCellType {
+    return {
+        dayIndex: 0,
+        date: '2026-04-13',
+        entries: [],
+        totalSeconds,
+    };
+}
+
+function mountTimesheetCell(totalSeconds = 2 * 3600) {
+    return mount(TimesheetCell, {
+        props: {
+            cell: buildCell(totalSeconds),
+            dayIndex: 0,
+            date: '2026-04-13',
+            isToday: false,
+            hasRunningEntry: false,
+        },
+    });
+}
+
+describe('TimesheetCell', () => {
+    it('emits 0 when the cleared value is committed on blur', async () => {
+        const wrapper = mountTimesheetCell();
+        const input = wrapper.get('input');
+
+        await input.trigger('focus');
+        await input.setValue('');
+        await input.trigger('blur');
+
+        expect(wrapper.emitted('update')).toEqual([[0]]);
+    });
+
+    it('emits 0 when the cleared value is committed with Enter', async () => {
+        const wrapper = mountTimesheetCell();
+        const input = wrapper.get('input');
+
+        await input.trigger('focus');
+        await input.setValue('');
+        await input.trigger('keydown', { key: 'Enter' });
+
+        expect(wrapper.emitted('update')).toEqual([[0]]);
+    });
+
+    it('restores the previous value and emits nothing on Escape', async () => {
+        const wrapper = mountTimesheetCell();
+        const input = wrapper.get('input');
+        const previousValue = formatHumanReadableDuration(2 * 3600, 'hours-minutes', 'point');
+
+        await input.trigger('focus');
+        await input.setValue('');
+        await input.trigger('keydown', { key: 'Escape' });
+        await nextTick();
+
+        expect(wrapper.emitted('update')).toBeUndefined();
+        expect((input.element as HTMLInputElement).value).toBe(previousValue);
+    });
+});

resources/js/packages/ui/src/TimeTracker/TimeTrackerProjectTaskDropdown.test.ts

@@ -0,0 +1,90 @@
+/* eslint-disable vue/one-component-per-file */
+import { mount } from '@vue/test-utils';
+import { describe, expect, it, vi } from 'vitest';
+import { defineComponent, h, nextTick, onMounted } from 'vue';
+import TimeTrackerProjectTaskDropdown from './TimeTrackerProjectTaskDropdown.vue';
+import type { Client, Project, Task } from '@/packages/api/src';
+
+const DropdownStub = defineComponent({
+    props: {
+        modelValue: {
+            type: Boolean,
+            default: false,
+        },
+    },
+    emits: ['update:modelValue'],
+    setup(_, { emit, slots }) {
+        onMounted(() => emit('update:modelValue', true));
+        return () => h('div', [slots.trigger?.(), slots.content?.()]);
+    },
+});
+
+const FocusTrapStub = defineComponent({
+    setup(_, { slots }) {
+        return () => h('div', slots.default?.());
+    },
+});
+
+function mountDropdown(props: Record<string, unknown> = {}) {
+    return mount(TimeTrackerProjectTaskDropdown, {
+        props: {
+            project: null,
+            task: null,
+            projects: [] as Project[],
+            tasks: [] as Task[],
+            clients: [] as Client[],
+            createProject: vi.fn(),
+            createClient: vi.fn(),
+            currency: 'EUR',
+            enableEstimatedTime: false,
+            organizationBillableRate: null,
+            canCreateProject: false,
+            ...props,
+        },
+        global: {
+            stubs: {
+                Dropdown: DropdownStub,
+                UseFocusTrap: FocusTrapStub,
+            },
+        },
+    });
+}
+
+async function openDropdown() {
+    const wrapper = mountDropdown();
+    await nextTick();
+    await nextTick();
+    return wrapper;
+}
+
+describe('TimeTrackerProjectTaskDropdown', () => {
+    it('keeps the existing empty-string no-project value by default', async () => {
+        const wrapper = await openDropdown();
+
+        await wrapper.find('[data-project-id=""]').trigger('click');
+
+        expect(wrapper.emitted('update:project')?.at(-1)).toEqual(['']);
+        expect(wrapper.emitted('changed')?.at(-1)).toEqual(['', null]);
+    });
+
+    it('can emit null for no-project consumers that use null as the domain value', async () => {
+        const wrapper = mountDropdown({ project: 'p-1', noProjectValue: null });
+        await nextTick();
+        await nextTick();
+
+        await wrapper.find('[data-project-id=""]').trigger('click');
+
+        expect(wrapper.emitted('update:project')?.at(-1)).toEqual([null]);
+        expect(wrapper.emitted('changed')?.at(-1)).toEqual([null, null]);
+    });
+
+    it('still exposes "No Project" when projects are empty and project creation is allowed', async () => {
+        const wrapper = mountDropdown({ canCreateProject: true });
+        await nextTick();
+        await nextTick();
+
+        await wrapper.find('[data-project-id=""]').trigger('click');
+
+        expect(wrapper.emitted('changed')?.at(-1)).toEqual(['', null]);
+    });
+});

resources/js/packages/ui/src/utils/time.test.ts

@@ -0,0 +1,44 @@
+import { describe, expect, test } from 'vitest';
+import { formatHumanReadableDuration, formatReportingDuration } from './time';
+
+const seconds = 14 * 3600 + 45 * 60 + 6; // 14h 45m 06s
+
+describe('formatHumanReadableDuration', () => {
+    test('decimal', () => {
+        expect(formatHumanReadableDuration(seconds, 'decimal', 'comma-point')).toBe('14.75 h');
+    });
+
+    test('hours-minutes', () => {
+        expect(formatHumanReadableDuration(seconds, 'hours-minutes')).toBe('14h 45min');
+    });
+
+    test('hours-minutes-colon-separated', () => {
+        expect(formatHumanReadableDuration(seconds, 'hours-minutes-colon-separated')).toBe('14:45');
+    });
+
+    test('hours-minutes-seconds-colon-separated', () => {
+        expect(formatHumanReadableDuration(seconds, 'hours-minutes-seconds-colon-separated')).toBe(
+            '14:45:06'
+        );
+    });
+});
+
+describe('formatReportingDuration', () => {
+    test('decimal', () => {
+        expect(formatReportingDuration(seconds, 'decimal', 'comma-point')).toBe('14.75 h');
+    });
+
+    test('hours-minutes', () => {
+        expect(formatReportingDuration(seconds, 'hours-minutes')).toBe('14:45:06');
+    });
+
+    test('hours-minutes-colon-separated', () => {
+        expect(formatReportingDuration(seconds, 'hours-minutes-colon-separated')).toBe('14:45:06');
+    });
+
+    test('hours-minutes-seconds-colon-separated', () => {
+        expect(formatReportingDuration(seconds, 'hours-minutes-seconds-colon-separated')).toBe(
+            '14:45:06'
+        );
+    });
+});

resources/js/test-setup.ts

@@ -0,0 +1,20 @@
+// Vitest setup file. Wires up the globals that the production code reads
+// off `window` (`getTimezoneSetting`, `getWeekStartSetting`, `getNumberFormat`,
+// `getIntervalFormat`) so that helpers under test don't crash when imported
+// outside the running app.
+
+import { vi } from 'vitest';
+
+declare global {
+    interface Window {
+        getTimezoneSetting: () => string;
+        getWeekStartSetting: () => string;
+        getNumberFormat: () => string;
+        getIntervalFormat: () => string;
+    }
+}
+
+window.getTimezoneSetting = vi.fn(() => 'UTC');
+window.getWeekStartSetting = vi.fn(() => 'monday');
+window.getNumberFormat = vi.fn(() => 'point');
+window.getIntervalFormat = vi.fn(() => 'hours-minutes');

resources/js/utils/timesheet/cellMath.test.ts

@@ -0,0 +1,348 @@
+import { describe, it, expect } from 'vitest';
+import dayjs from 'dayjs';
+import utc from 'dayjs/plugin/utc';
+import timezone from 'dayjs/plugin/timezone';
+import { findFreeWindowOnDay, freeGapSecondsAfter, NoFreeWindowError } from './cellMath';
+import type { TimeEntry } from '@/packages/api/src';
+
+dayjs.extend(utc);
+dayjs.extend(timezone);
+
+// All times in the tests are in UTC for clarity. The "day" we search is
+// 2026-04-10 in UTC (so we use tz='UTC' to avoid local-machine surprises).
+const TZ = 'UTC';
+const DATE = '2026-04-10';
+
+/** Build a fake TimeEntry from UTC ISO timestamps. */
+function entry(start: string, end: string | null, id = `e-${start}-${end}`): TimeEntry {
+    const startMs = dayjs.utc(start).valueOf();
+    const endMs = end ? dayjs.utc(end).valueOf() : startMs;
+    return {
+        id,
+        start,
+        end,
+        duration: end ? Math.floor((endMs - startMs) / 1000) : null,
+        description: '',
+        member_id: 'm-1',
+        project_id: null,
+        task_id: null,
+        billable: false,
+        tags: [],
+        // The grid only reads the fields above; the rest are placeholders
+        // to satisfy the TimeEntry type without pulling in real fixtures.
+        user_id: 'u-1',
+        organization_id: 'o-1',
+    } as unknown as TimeEntry;
+}
+
+const HOUR = 3600;
+
+describe('findFreeWindowOnDay', () => {
+    // ── Empty / trivial cases ──────────────────────────────────────
+
+    it('returns the start of the day for a totally empty day', () => {
+        const result = findFreeWindowOnDay([], DATE, HOUR, TZ);
+        expect(result).toEqual({
+            start: '2026-04-10T00:00:00Z',
+            end: '2026-04-10T01:00:00Z',
+        });
+    });
+
+    it('returns null for zero or negative required seconds', () => {
+        expect(findFreeWindowOnDay([], DATE, 0, TZ)).toBeNull();
+        expect(findFreeWindowOnDay([], DATE, -1, TZ)).toBeNull();
+    });
+
+    it('refuses any duration > 24h on principle (single-day constraint)', () => {
+        const result = findFreeWindowOnDay([], DATE, 25 * HOUR, TZ);
+        expect(result).toBeNull();
+    });
+
+    // ── Single obstacle, basic gap finding ────────────────────────
+
+    it('finds the gap before a single obstacle if it fits', () => {
+        const obs = [entry('2026-04-10T10:00:00Z', '2026-04-10T11:00:00Z')];
+        const result = findFreeWindowOnDay(obs, DATE, HOUR, TZ);
+        expect(result?.start).toBe('2026-04-10T00:00:00Z');
+        expect(result?.end).toBe('2026-04-10T01:00:00Z');
+    });
+
+    it('finds the gap after a single obstacle when preferredStart skips earlier gaps', () => {
+        const obs = [entry('2026-04-10T10:00:00Z', '2026-04-10T11:00:00Z')];
+        const result = findFreeWindowOnDay(obs, DATE, HOUR, TZ, '2026-04-10T11:00:00Z');
+        expect(result?.start).toBe('2026-04-10T11:00:00Z');
+        expect(result?.end).toBe('2026-04-10T12:00:00Z');
+    });
+
+    // ── Multi-obstacle gap walking ────────────────────────────────
+
+    it('finds a gap between two obstacles', () => {
+        const obs = [
+            entry('2026-04-10T08:00:00Z', '2026-04-10T10:00:00Z'),
+            entry('2026-04-10T12:00:00Z', '2026-04-10T14:00:00Z'),
+        ];
+        // Search for 2h, expecting the [00:00, 08:00) gap (8h available)
+        const result = findFreeWindowOnDay(obs, DATE, 2 * HOUR, TZ);
+        expect(result?.start).toBe('2026-04-10T00:00:00Z');
+    });
+
+    it('walks past gaps that are too small', () => {
+        const obs = [
+            entry('2026-04-10T00:30:00Z', '2026-04-10T10:00:00Z'),
+            entry('2026-04-10T11:00:00Z', '2026-04-10T12:00:00Z'),
+        ];
+        // First gap is 30min, second gap is 1h, third is 12h.
+        // Asking for 90min → first two gaps are too small, third fits.
+        const result = findFreeWindowOnDay(obs, DATE, 90 * 60, TZ);
+        expect(result?.start).toBe('2026-04-10T12:00:00Z');
+    });
+
+    it('uses preferredStart even when it lands inside a gap', () => {
+        const obs = [
+            entry('2026-04-10T00:00:00Z', '2026-04-10T08:00:00Z'),
+            entry('2026-04-10T12:00:00Z', '2026-04-10T14:00:00Z'),
+        ];
+        // preferredStart 09:00 → gap is [09:00, 12:00) = 3h
+        const result = findFreeWindowOnDay(obs, DATE, 2 * HOUR, TZ, '2026-04-10T09:00:00Z');
+        expect(result?.start).toBe('2026-04-10T09:00:00Z');
+        expect(result?.end).toBe('2026-04-10T11:00:00Z');
+    });
+
+    it('skips ahead when preferredStart lands inside an obstacle', () => {
+        const obs = [entry('2026-04-10T08:00:00Z', '2026-04-10T12:00:00Z')];
+        // preferredStart 10:00 lands inside [08:00, 12:00). We must
+        // advance to the next free position (12:00).
+        const result = findFreeWindowOnDay(obs, DATE, HOUR, TZ, '2026-04-10T10:00:00Z');
+        expect(result?.start).toBe('2026-04-10T12:00:00Z');
+    });
+
+    // ── Spillover from previous day ───────────────────────────────
+
+    it('treats an entry that started yesterday but ends today as an obstacle', () => {
+        // Yesterday 23:00 → today 02:00 → blocks the first 2h of today.
+        const obs = [entry('2026-04-09T23:00:00Z', '2026-04-10T02:00:00Z')];
+        const result = findFreeWindowOnDay(obs, DATE, HOUR, TZ);
+        expect(result?.start).toBe('2026-04-10T02:00:00Z');
+    });
+
+    it('ignores an entry that ended exactly at the start of the day', () => {
+        // Yesterday 22:00 → today 00:00 (exclusive) → does NOT block today.
+        const obs = [entry('2026-04-09T22:00:00Z', '2026-04-10T00:00:00Z')];
+        const result = findFreeWindowOnDay(obs, DATE, HOUR, TZ);
+        expect(result?.start).toBe('2026-04-10T00:00:00Z');
+    });
+
+    // ── Running entries ────────────────────────────────────────────
+
+    it('treats a running entry as blocking up to "now"', () => {
+        const obs = [entry('2026-04-10T08:00:00Z', null)];
+        const now = '2026-04-10T10:30:00Z';
+        // The running entry blocks 08:00–10:30 → first free window is
+        // either before 08:00 (8h available, fits a 1h request).
+        const result = findFreeWindowOnDay(obs, DATE, HOUR, TZ, null, now);
+        expect(result?.start).toBe('2026-04-10T00:00:00Z');
+    });
+
+    it('places after a running entry when preferredStart pushes past it', () => {
+        const obs = [entry('2026-04-10T08:00:00Z', null)];
+        const now = '2026-04-10T10:30:00Z';
+        const result = findFreeWindowOnDay(obs, DATE, HOUR, TZ, '2026-04-10T09:00:00Z', now);
+        // preferredStart 09:00 lands inside the running entry's blocked
+        // range [08:00, 10:30) → must skip to 10:30.
+        expect(result?.start).toBe('2026-04-10T10:30:00Z');
+    });
+
+    // ── Midnight refusal ──────────────────────────────────────────
+
+    it('refuses to return a window that would cross midnight', () => {
+        const obs = [entry('2026-04-10T00:00:00Z', '2026-04-10T22:30:00Z')];
+        // Only 90min remain in the day. Asking for 2h → null.
+        const result = findFreeWindowOnDay(obs, DATE, 2 * HOUR, TZ);
+        expect(result).toBeNull();
+    });
+
+    it('accepts a window that ends exactly at midnight', () => {
+        const obs = [entry('2026-04-10T00:00:00Z', '2026-04-10T22:00:00Z')];
+        // Exactly 2h remain → 22:00–00:00.
+        const result = findFreeWindowOnDay(obs, DATE, 2 * HOUR, TZ);
+        expect(result?.start).toBe('2026-04-10T22:00:00Z');
+        expect(result?.end).toBe('2026-04-11T00:00:00Z');
+    });
+
+    // ── Pre-existing overlapping obstacles ────────────────────────
+
+    it('merges overlapping obstacles before computing gaps', () => {
+        const obs = [
+            entry('2026-04-10T09:00:00Z', '2026-04-10T11:00:00Z'),
+            entry('2026-04-10T10:00:00Z', '2026-04-10T13:00:00Z'),
+            entry('2026-04-10T15:00:00Z', '2026-04-10T16:00:00Z'),
+        ];
+        // Effective obstacles: [09:00, 13:00) and [15:00, 16:00)
+        // First gap is [00:00, 09:00) = 9h. Asking for 2h → 00:00.
+        const result = findFreeWindowOnDay(obs, DATE, 2 * HOUR, TZ);
+        expect(result?.start).toBe('2026-04-10T00:00:00Z');
+    });
+
+    // ── Day full ──────────────────────────────────────────────────
+
+    it('returns null when no gap is large enough', () => {
+        const obs = [
+            entry('2026-04-10T00:00:00Z', '2026-04-10T11:00:00Z'),
+            entry('2026-04-10T11:30:00Z', '2026-04-10T22:00:00Z'),
+            entry('2026-04-10T22:30:00Z', '2026-04-10T23:30:00Z'),
+        ];
+        // Gaps: 30min, 30min, 30min. Asking for 1h → null.
+        const result = findFreeWindowOnDay(obs, DATE, HOUR, TZ);
+        expect(result).toBeNull();
+    });
+
+    // ── Timezone awareness ────────────────────────────────────────
+
+    it('respects the user timezone for day boundaries', () => {
+        // In Pacific/Auckland (+13 in April 2026), 2026-04-10 starts at
+        // 2026-04-09T11:00:00Z (NZDT was UTC+13 until April 5 2026, then
+        // NZST UTC+12 — let's pick a date in NZST so the offset is +12).
+        // 2026-04-10 NZST = 2026-04-09T12:00:00Z to 2026-04-10T12:00:00Z
+        const tz = 'Pacific/Auckland';
+        const obs = [
+            // This entry is at 2026-04-10T08:00:00Z = 2026-04-10T20:00 NZ
+            // → falls in the NZ day for 2026-04-10. So it blocks from
+            // 20:00 to 21:00 NZ time.
+            entry('2026-04-10T08:00:00Z', '2026-04-10T09:00:00Z'),
+        ];
+        const result = findFreeWindowOnDay(obs, '2026-04-10', HOUR, tz);
+        // Day starts at 2026-04-09T12:00:00Z in NZST. First gap is the
+        // 20h before the obstacle starts.
+        expect(result?.start).toBe('2026-04-09T12:00:00Z');
+    });
+
+    it('does not place work past local midnight on spring-forward days', () => {
+        const tz = 'Europe/Vienna';
+        const obs = [entry('2026-03-28T23:00:00Z', '2026-03-29T22:00:00Z')];
+
+        const result = findFreeWindowOnDay(obs, '2026-03-29', HOUR, tz);
+
+        expect(result).toBeNull();
+    });
+
+    it('can use the final local hour on fall-back days', () => {
+        const tz = 'Europe/Vienna';
+
+        const result = findFreeWindowOnDay([], '2026-10-25', HOUR, tz, '2026-10-25T22:00:00Z');
+
+        expect(result).toEqual({
+            start: '2026-10-25T22:00:00Z',
+            end: '2026-10-25T23:00:00Z',
+        });
+    });
+});
+
+describe('freeGapSecondsAfter', () => {
+    it('returns the rest of the day for an empty day', () => {
+        const result = freeGapSecondsAfter([], DATE, TZ, '2026-04-10T09:00:00Z');
+        // 09:00 → 24:00 = 15 hours
+        expect(result).toBe(15 * HOUR);
+    });
+
+    it('returns 0 when cursor is at end-of-day', () => {
+        const result = freeGapSecondsAfter([], DATE, TZ, '2026-04-11T00:00:00Z');
+        expect(result).toBe(0);
+    });
+
+    it('returns 0 when cursor is after end-of-day', () => {
+        const result = freeGapSecondsAfter([], DATE, TZ, '2026-04-11T05:00:00Z');
+        expect(result).toBe(0);
+    });
+
+    it('returns 0 when cursor is before the day starts', () => {
+        const result = freeGapSecondsAfter([], DATE, TZ, '2026-04-09T23:00:00Z');
+        expect(result).toBe(0);
+    });
+
+    it('returns the gap to the next obstacle', () => {
+        const obs = [entry('2026-04-10T11:00:00Z', '2026-04-10T12:00:00Z')];
+        // cursor 09:00 → next obstacle 11:00 → 2h gap
+        const result = freeGapSecondsAfter(obs, DATE, TZ, '2026-04-10T09:00:00Z');
+        expect(result).toBe(2 * HOUR);
+    });
+
+    it('returns 0 when cursor sits inside an obstacle', () => {
+        const obs = [entry('2026-04-10T08:00:00Z', '2026-04-10T12:00:00Z')];
+        const result = freeGapSecondsAfter(obs, DATE, TZ, '2026-04-10T10:00:00Z');
+        expect(result).toBe(0);
+    });
+
+    it('returns the rest of the day when no obstacle is ahead', () => {
+        const obs = [entry('2026-04-10T08:00:00Z', '2026-04-10T09:00:00Z')];
+        const result = freeGapSecondsAfter(obs, DATE, TZ, '2026-04-10T09:00:00Z');
+        // 09:00 → 24:00 = 15h
+        expect(result).toBe(15 * HOUR);
+    });
+
+    it('skips obstacles strictly before the cursor', () => {
+        const obs = [
+            entry('2026-04-10T08:00:00Z', '2026-04-10T09:00:00Z'),
+            entry('2026-04-10T15:00:00Z', '2026-04-10T16:00:00Z'),
+        ];
+        // cursor 09:00 → first obstacle (08-09) is behind, next is 15:00 → 6h
+        const result = freeGapSecondsAfter(obs, DATE, TZ, '2026-04-10T09:00:00Z');
+        expect(result).toBe(6 * HOUR);
+    });
+
+    it('treats a running entry as blocking up to "now"', () => {
+        const obs = [entry('2026-04-10T08:00:00Z', null)];
+        const now = '2026-04-10T10:00:00Z';
+        // cursor 11:00 is after the running entry's effective end (10:00),
+        // so the gap is the rest of the day = 13h
+        const result = freeGapSecondsAfter(obs, DATE, TZ, '2026-04-10T11:00:00Z', now);
+        expect(result).toBe(13 * HOUR);
+    });
+
+    it('returns 0 when cursor is inside a running entry (cursor < now)', () => {
+        const obs = [entry('2026-04-10T08:00:00Z', null)];
+        const now = '2026-04-10T12:00:00Z';
+        // cursor 10:00 falls inside [08:00, 12:00) → blocked
+        const result = freeGapSecondsAfter(obs, DATE, TZ, '2026-04-10T10:00:00Z', now);
+        expect(result).toBe(0);
+    });
+
+    it('clips the gap to midnight, never beyond', () => {
+        const obs = [entry('2026-04-10T08:00:00Z', '2026-04-10T09:00:00Z')];
+        // cursor 23:00 → 1h until midnight
+        const result = freeGapSecondsAfter(obs, DATE, TZ, '2026-04-10T23:00:00Z');
+        expect(result).toBe(HOUR);
+    });
+
+    it('clips spring-forward days at the next local midnight', () => {
+        const result = freeGapSecondsAfter(
+            [],
+            '2026-03-29',
+            'Europe/Vienna',
+            '2026-03-29T22:00:00Z'
+        );
+
+        expect(result).toBe(0);
+    });
+
+    it('includes the final local hour on fall-back days', () => {
+        const result = freeGapSecondsAfter(
+            [],
+            '2026-10-25',
+            'Europe/Vienna',
+            '2026-10-25T22:00:00Z'
+        );
+
+        expect(result).toBe(HOUR);
+    });
+});
+
+describe('NoFreeWindowError', () => {
+    it('carries the date and required seconds', () => {
+        const err = new NoFreeWindowError('2026-04-10', 7200);
+        expect(err.code).toBe('no_free_window');
+        expect(err.date).toBe('2026-04-10');
+        expect(err.requiredSeconds).toBe(7200);
+        expect(err.message).toContain('2026-04-10');
+        expect(err instanceof Error).toBe(true);
+    });
+});

resources/js/utils/timesheet/useTimesheetCellMutations.test.ts

@@ -0,0 +1,551 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { ref } from 'vue';
+import { createPinia, setActivePinia } from 'pinia';
+import { useTimesheetCellMutations } from './useTimesheetCellMutations';
+import { api } from '@/packages/api/src';
+import type { TimesheetRow, TimesheetCell } from '@/utils/useTimesheetGrid';
+import type { TimeEntry } from '@/packages/api/src';
+
+const addNotification = vi.fn();
+
+vi.mock('@/utils/useUser', () => ({
+    getCurrentOrganizationId: vi.fn(() => 'org-1'),
+    getCurrentMembershipId: vi.fn(() => 'mem-1'),
+}));
+
+vi.mock('@tanstack/vue-query', () => ({
+    useQueryClient: () => ({
+        invalidateQueries: vi.fn(),
+    }),
+}));
+
+vi.mock('@/utils/notification', () => ({
+    useNotificationsStore: () => ({
+        addNotification,
+    }),
+}));
+
+vi.mock('@/packages/api/src', () => ({
+    api: {
+        createTimeEntry: vi.fn(async () => ({ data: { id: 'new-id' } })),
+        updateTimeEntry: vi.fn(async () => undefined),
+        deleteTimeEntry: vi.fn(async () => undefined),
+        deleteTimeEntries: vi.fn(async () => undefined),
+    },
+}));
+
+// All scenarios use UTC so the local "day" matches the UTC day exactly
+// (the test-setup mocks getTimezoneSetting to return 'UTC').
+
+const DATE = '2026-04-10';
+const HOUR = 3600;
+
+function entry(start: string, end: string | null, overrides: Partial<TimeEntry> = {}): TimeEntry {
+    const startMs = new Date(start).valueOf();
+    const endMs = end ? new Date(end).valueOf() : startMs;
+    return {
+        id: overrides.id ?? `e-${start}-${end ?? 'running'}`,
+        start,
+        end,
+        duration: end ? Math.floor((endMs - startMs) / 1000) : null,
+        description: '',
+        member_id: 'm-1',
+        project_id: 'p-1',
+        task_id: null,
+        billable: false,
+        tags: [],
+        ...overrides,
+    } as unknown as TimeEntry;
+}
+
+function buildCell(entries: TimeEntry[]): TimesheetCell {
+    return {
+        dayIndex: 0,
+        date: DATE,
+        entries,
+        totalSeconds: entries.reduce((sum, e) => sum + (e.duration ?? 0), 0),
+    };
+}
+
+function buildRow(
+    projectId: string | null,
+    entries: TimeEntry[],
+    key = `${projectId}:null`
+): TimesheetRow {
+    const cell = buildCell(entries);
+    return {
+        key,
+        projectId,
+        taskId: null,
+        billable: false,
+        tags: [],
+        cells: new Map([[0, cell]]),
+        totalSeconds: cell.totalSeconds,
+    };
+}
+
+function buildEmptyRow(projectId: string | null, key = `${projectId}:null`): TimesheetRow {
+    return {
+        key,
+        projectId,
+        taskId: null,
+        billable: false,
+        tags: [],
+        cells: new Map(),
+        totalSeconds: 0,
+    };
+}
+
+/** Shape of the body the cell-mutation logic passes to api.createTimeEntry. */
+interface CapturedEntry {
+    id?: string;
+    start: string;
+    end: string | null;
+    project_id?: string | null;
+    task_id?: string | null;
+    description?: string | null;
+}
+
+const apiMocks = vi.mocked(api);
+
+function firstArg(
+    mock: typeof apiMocks.createTimeEntry | typeof apiMocks.updateTimeEntry
+): CapturedEntry {
+    return mock.mock.calls[0]?.[0] as unknown as CapturedEntry;
+}
+
+function setup(
+    allEntries: TimeEntry[],
+    rowsValue: TimesheetRow[] = [],
+    removeSlot: (key: string) => void = () => undefined
+) {
+    const cellMutations = useTimesheetCellMutations(
+        ref([
+            DATE,
+            '2026-04-11',
+            '2026-04-12',
+            '2026-04-13',
+            '2026-04-14',
+            '2026-04-15',
+            '2026-04-16',
+        ]),
+        ref(allEntries),
+        ref(rowsValue),
+        removeSlot
+    );
+
+    return { cellMutations };
+}
+
+beforeEach(() => {
+    setActivePinia(createPinia());
+    apiMocks.createTimeEntry.mockClear();
+    apiMocks.updateTimeEntry.mockClear();
+    apiMocks.deleteTimeEntry.mockClear();
+    apiMocks.deleteTimeEntries.mockClear();
+    addNotification.mockClear();
+    // Lock the clock to mid-afternoon on the test day so running-entry
+    // tests have a deterministic "now". Past 12:00 to make spillover
+    // scenarios meaningful.
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date('2026-04-10T14:00:00Z'));
+});
+
+afterEach(() => {
+    vi.useRealTimers();
+});
+
+describe('useTimesheetCellMutations.handleCellUpdate', () => {
+    // ── No-op ─────────────────────────────────────────────────────
+
+    it('does nothing when the diff is zero', async () => {
+        const { cellMutations } = setup([]);
+        const row = buildRow('p-1', [entry('2026-04-10T09:00:00Z', '2026-04-10T10:00:00Z')]);
+        await cellMutations.handleCellUpdate(row, 0, HOUR);
+
+        expect(apiMocks.createTimeEntry).not.toHaveBeenCalled();
+        expect(apiMocks.updateTimeEntry).not.toHaveBeenCalled();
+        expect(apiMocks.deleteTimeEntry).not.toHaveBeenCalled();
+        expect(apiMocks.deleteTimeEntries).not.toHaveBeenCalled();
+    });
+
+    // ── Delete cell ───────────────────────────────────────────────
+
+    it('clearing a cell deletes all entries in it', async () => {
+        const cellEntry = entry('2026-04-10T09:00:00Z', '2026-04-10T10:00:00Z');
+        const { cellMutations } = setup([cellEntry]);
+        const row = buildRow('p-1', [cellEntry]);
+
+        await cellMutations.handleCellUpdate(row, 0, 0);
+
+        expect(apiMocks.deleteTimeEntries).toHaveBeenCalledTimes(1);
+        const [, options] = apiMocks.deleteTimeEntries.mock.calls[0]!;
+        expect(options?.queries?.ids).toEqual([cellEntry.id]);
+        expect(options?.params?.organization).toBe('org-1');
+    });
+
+    // ── Create cell (Phase 1) ──────────────────────────────────────
+
+    describe('createCell', () => {
+        it('places a new entry at 09:00 on an empty day', async () => {
+            const { cellMutations } = setup([]);
+            const row = buildEmptyRow('p-1');
+
+            await cellMutations.handleCellUpdate(row, 0, HOUR);
+
+            expect(apiMocks.createTimeEntry).toHaveBeenCalledTimes(1);
+            const arg = firstArg(apiMocks.createTimeEntry);
+            expect(arg.start).toBe('2026-04-10T09:00:00Z');
+            expect(arg.end).toBe('2026-04-10T10:00:00Z');
+            expect(arg.project_id).toBe('p-1');
+        });
+
+        it('passes no-project rows to the API as null', async () => {
+            const { cellMutations } = setup([]);
+            const row = buildEmptyRow(null);
+
+            await cellMutations.handleCellUpdate(row, 0, HOUR);
+
+            expect(apiMocks.createTimeEntry).toHaveBeenCalledTimes(1);
+            expect(firstArg(apiMocks.createTimeEntry).project_id).toBeNull();
+        });
+
+        it('collapses an empty duplicate row after its first entry is created', async () => {
+            const removeSlot = vi.fn();
+            const existingRow = buildEmptyRow('p-1', 'existing-slot');
+            const duplicateRow = buildEmptyRow('p-1', 'duplicate-slot');
+            const { cellMutations } = setup([], [existingRow, duplicateRow], removeSlot);
+
+            await cellMutations.handleCellUpdate(duplicateRow, 0, HOUR);
+
+            expect(apiMocks.createTimeEntry).toHaveBeenCalledTimes(1);
+            expect(removeSlot).toHaveBeenCalledWith('duplicate-slot');
+            expect(addNotification).toHaveBeenCalledWith(
+                'success',
+                'Merged into matching row',
+                'Another row with the same project, task, billable status and tags already exists.'
+            );
+        });
+
+        it("falls back to the start of the day when 09:00 wouldn't fit", async () => {
+            // Block 09:00 → 23:30 with another row's entry. The only
+            // gap big enough for 1h is 00:00 → 09:00.
+            const blocker = entry('2026-04-10T09:00:00Z', '2026-04-10T23:30:00Z', {
+                id: 'blocker',
+            });
+            const { cellMutations } = setup([blocker]);
+            const row = buildEmptyRow('p-1');
+
+            await cellMutations.handleCellUpdate(row, 0, HOUR);
+
+            expect(apiMocks.createTimeEntry).toHaveBeenCalledTimes(1);
+            const arg = firstArg(apiMocks.createTimeEntry);
+            expect(arg.start).toBe('2026-04-10T00:00:00Z');
+            expect(arg.end).toBe('2026-04-10T01:00:00Z');
+        });
+
+        it('avoids overlapping with another row on the same day (Scenario #4)', async () => {
+            // Another row has an entry 09:00 → 10:00. The new entry must
+            // not overlap it.
+            const blocker = entry('2026-04-10T09:00:00Z', '2026-04-10T10:00:00Z', {
+                id: 'blocker',
+            });
+            const { cellMutations } = setup([blocker]);
+            const row = buildEmptyRow('p-1');
+
+            await cellMutations.handleCellUpdate(row, 0, HOUR);
+
+            const arg = firstArg(apiMocks.createTimeEntry);
+            // 09:00 is blocked → must place after, at 10:00
+            expect(arg.start).toBe('2026-04-10T10:00:00Z');
+            expect(arg.end).toBe('2026-04-10T11:00:00Z');
+        });
+
+        it('treats a running entry as a blocker (Scenario #1)', async () => {
+            const running = entry('2026-04-10T08:00:00Z', null, { id: 'running' });
+            const { cellMutations } = setup([running]);
+            const row = buildEmptyRow('p-1');
+
+            await cellMutations.handleCellUpdate(row, 0, HOUR);
+
+            const arg = firstArg(apiMocks.createTimeEntry);
+            // The running entry blocks [08:00, now=14:00). The 09:00
+            // work-hours default lands inside that block, so the
+            // search advances the cursor to 14:00 and places the new
+            // entry at 14:00 → 15:00. Critically, this does NOT
+            // overlap the running timer.
+            expect(arg.start).toBe('2026-04-10T14:00:00Z');
+            expect(arg.end).toBe('2026-04-10T15:00:00Z');
+        });
+
+        it('avoids spillover from the previous day (Scenario #2)', async () => {
+            // An entry from yesterday spills into today's first 4h.
+            const spillover = entry('2026-04-09T22:00:00Z', '2026-04-10T04:00:00Z', {
+                id: 'spillover',
+            });
+            const { cellMutations } = setup([spillover]);
+            const row = buildEmptyRow('p-1');
+
+            await cellMutations.handleCellUpdate(row, 0, HOUR);
+
+            const arg = firstArg(apiMocks.createTimeEntry);
+            // 09:00 is free (the spillover ends at 04:00).
+            expect(arg.start).toBe('2026-04-10T09:00:00Z');
+        });
+
+        it('refuses to cross midnight (Scenario #3)', async () => {
+            // Block all of the day except the last 2h. Asking for 3h
+            // → no single-day window fits → notification, no API call.
+            const blocker = entry('2026-04-10T00:00:00Z', '2026-04-10T22:00:00Z', {
+                id: 'blocker',
+            });
+            const { cellMutations } = setup([blocker]);
+            const row = buildEmptyRow('p-1');
+
+            await cellMutations.handleCellUpdate(row, 0, 3 * HOUR);
+
+            expect(apiMocks.createTimeEntry).not.toHaveBeenCalled();
+        });
+    });
+
+    // ── Extend cell (Phase 2) ──────────────────────────────────────
+
+    describe('extendCell', () => {
+        it("extends the cell's latest-ended entry forward when there is room", async () => {
+            const cellEntry = entry('2026-04-10T09:00:00Z', '2026-04-10T10:00:00Z', {
+                id: 'extend-me',
+            });
+            const { cellMutations } = setup([cellEntry]);
+            const row = buildRow('p-1', [cellEntry]);
+
+            // Cell is 1h, request 2h total → +1h
+            await cellMutations.handleCellUpdate(row, 0, 2 * HOUR);
+
+            expect(apiMocks.updateTimeEntry).toHaveBeenCalledTimes(1);
+            const updated = firstArg(apiMocks.updateTimeEntry);
+            expect(updated.id).toBe('extend-me');
+            expect(updated.end).toBe('2026-04-10T11:00:00Z');
+            expect(apiMocks.createTimeEntry).not.toHaveBeenCalled();
+        });
+
+        it('picks the latest-END entry when nested entries exist (Scenario #6)', async () => {
+            // Outer entry 09:00 → 12:00, inner entry 10:00 → 11:00.
+            // The latest START is "inner" but the latest END is "outer".
+            // Extending should grow the OUTER entry, not the inner.
+            const outer = entry('2026-04-10T09:00:00Z', '2026-04-10T12:00:00Z', { id: 'outer' });
+            const inner = entry('2026-04-10T10:00:00Z', '2026-04-10T11:00:00Z', { id: 'inner' });
+            const { cellMutations } = setup([outer, inner]);
+            const row = buildRow('p-1', [outer, inner]);
+
+            // Cell total = 3h + 1h = 4h. Bump to 5h → +1h.
+            await cellMutations.handleCellUpdate(row, 0, 5 * HOUR);
+
+            expect(apiMocks.updateTimeEntry).toHaveBeenCalledTimes(1);
+            const updated = firstArg(apiMocks.updateTimeEntry);
+            expect(updated.id).toBe('outer');
+            expect(updated.end).toBe('2026-04-10T13:00:00Z');
+        });
+
+        it('splits the extension when another row blocks the path (Scenario #5)', async () => {
+            // Cell entry: 09:00 → 10:00 (1h). Blocker on another row:
+            // 10:30 → 11:30. Bump cell to 3h (+2h):
+            //   - 30 minutes fit in the gap [10:00, 10:30) → extend to 10:30
+            //   - 90 minutes remain → place a NEW entry in the next free
+            //     window (11:30 → 13:00)
+            const cellEntry = entry('2026-04-10T09:00:00Z', '2026-04-10T10:00:00Z', {
+                id: 'cell-entry',
+            });
+            const blocker = entry('2026-04-10T10:30:00Z', '2026-04-10T11:30:00Z', {
+                id: 'blocker',
+                project_id: 'other-project',
+            });
+            const { cellMutations } = setup([cellEntry, blocker]);
+            const row = buildRow('p-1', [cellEntry]);
+
+            await cellMutations.handleCellUpdate(row, 0, 3 * HOUR);
+
+            expect(apiMocks.updateTimeEntry).toHaveBeenCalledTimes(1);
+            const updated = firstArg(apiMocks.updateTimeEntry);
+            expect(updated.id).toBe('cell-entry');
+            expect(updated.end).toBe('2026-04-10T10:30:00Z');
+
+            expect(apiMocks.createTimeEntry).toHaveBeenCalledTimes(1);
+            const created = firstArg(apiMocks.createTimeEntry);
+            // Remainder = 2h - 30min = 90min, placed in next free window
+            // (11:30 → 13:00)
+            expect(created.start).toBe('2026-04-10T11:30:00Z');
+            expect(created.end).toBe('2026-04-10T13:00:00Z');
+        });
+
+        it("places everything as a new entry when the cell's tail abuts another row immediately (Scenario #5 zero-gap)", async () => {
+            // Cell entry: 09:00 → 10:00. Another row starts EXACTLY at 10:00.
+            // Gap after cell entry = 0. The whole add becomes a new entry
+            // somewhere else.
+            const cellEntry = entry('2026-04-10T09:00:00Z', '2026-04-10T10:00:00Z', {
+                id: 'cell-entry',
+            });
+            const blocker = entry('2026-04-10T10:00:00Z', '2026-04-10T11:00:00Z', {
+                id: 'blocker',
+                project_id: 'other-project',
+            });
+            const { cellMutations } = setup([cellEntry, blocker]);
+            const row = buildRow('p-1', [cellEntry]);
+
+            // Bump cell from 1h to 2h → +1h
+            await cellMutations.handleCellUpdate(row, 0, 2 * HOUR);
+
+            // No update to cell entry (gap is zero)
+            expect(apiMocks.updateTimeEntry).not.toHaveBeenCalled();
+            // New entry placed in next free window: 11:00 → 12:00
+            expect(apiMocks.createTimeEntry).toHaveBeenCalledTimes(1);
+            const created = firstArg(apiMocks.createTimeEntry);
+            expect(created.start).toBe('2026-04-10T11:00:00Z');
+            expect(created.end).toBe('2026-04-10T12:00:00Z');
+        });
+
+        it('falls back to creating a new entry when the latest cell entry is running (Scenario #8)', async () => {
+            // Cell contains only a running timer.
+            const running = entry('2026-04-10T08:00:00Z', null, {
+                id: 'running',
+                duration: null,
+            });
+            // The grid would treat the cell total as 0 because duration is
+            // null, so we fake a non-zero totalSeconds via a manual cell.
+            const cell: TimesheetCell = {
+                dayIndex: 0,
+                date: DATE,
+                entries: [running],
+                // Pretend we computed 1h so that handleCellUpdate sees a
+                // diff > 0 and routes through extendCell rather than
+                // createCell.
+                totalSeconds: HOUR,
+            };
+            const row: TimesheetRow = {
+                key: 'p-1:null',
+                projectId: 'p-1',
+                taskId: null,
+                billable: false,
+                tags: [],
+                cells: new Map([[0, cell]]),
+                totalSeconds: HOUR,
+            };
+
+            const { cellMutations } = setup([running]);
+            // Bump from 1h to 2h → +1h. extendCell sees the running entry
+            // as the latest-end and falls through to createCell.
+            await cellMutations.handleCellUpdate(row, 0, 2 * HOUR);
+
+            expect(apiMocks.updateTimeEntry).not.toHaveBeenCalled();
+            expect(apiMocks.createTimeEntry).toHaveBeenCalledTimes(1);
+            // Running entry blocks [08:00, now=14:00). 09:00 lands inside
+            // → cursor advances to 14:00. Crucially the running entry is
+            // never modified.
+            const created = firstArg(apiMocks.createTimeEntry);
+            expect(created.start).toBe('2026-04-10T14:00:00Z');
+            expect(created.end).toBe('2026-04-10T15:00:00Z');
+        });
+
+        it('places the remainder strictly after the just-extended end (no stale-overlap)', async () => {
+            // Regression: timeEntries.value is stale right after the
+            // updateEntry call (still shows candidate.end at the old
+            // value). Without an explicit floor, findFreeWindowOnDay
+            // would propose a window inside the gap we just filled —
+            // overlapping the now-extended candidate.
+            //
+            // Cell entry: 09:00 → 10:00 (1h). Blocker on another row at
+            // 11:00 → 12:00. Gap is 1h. Bump cell to 2.5h (+1.5h):
+            //   - extend by 1h → newEnd = 11:00
+            //   - remainder = 30 min must land AFTER 11:00, not in the
+            //     stale-looking [10:00, 11:00] window.
+            const cellEntry = entry('2026-04-10T09:00:00Z', '2026-04-10T10:00:00Z', {
+                id: 'cell-entry',
+            });
+            const blocker = entry('2026-04-10T11:00:00Z', '2026-04-10T12:00:00Z', {
+                id: 'blocker',
+                project_id: 'other-project',
+            });
+            const { cellMutations } = setup([cellEntry, blocker]);
+            const row = buildRow('p-1', [cellEntry]);
+
+            await cellMutations.handleCellUpdate(row, 0, Math.round(2.5 * HOUR));
+
+            expect(apiMocks.updateTimeEntry).toHaveBeenCalledTimes(1);
+            const updated = firstArg(apiMocks.updateTimeEntry);
+            expect(updated.id).toBe('cell-entry');
+            expect(updated.end).toBe('2026-04-10T11:00:00Z');
+
+            expect(apiMocks.createTimeEntry).toHaveBeenCalledTimes(1);
+            const created = firstArg(apiMocks.createTimeEntry);
+            // Next free window after blocker, at 12:00.
+            expect(created.start).toBe('2026-04-10T12:00:00Z');
+            expect(created.end).toBe('2026-04-10T12:30:00Z');
+        });
+
+        it('refuses extension that would cross midnight before patching the server (Scenario #7)', async () => {
+            // Cell entry 22:00 → 23:00. Bump to 4h (+3h). Only 1h is
+            // available before midnight. Because the remaining 2h don't
+            // fit anywhere else on the day, the mutation now aborts
+            // before issuing the PATCH, leaving the entry untouched.
+            const cellEntry = entry('2026-04-10T22:00:00Z', '2026-04-10T23:00:00Z', {
+                id: 'cell-entry',
+            });
+            const fillEarly = entry('2026-04-10T00:00:00Z', '2026-04-10T22:00:00Z', {
+                id: 'fill',
+                project_id: 'other-project',
+            });
+            const { cellMutations } = setup([cellEntry, fillEarly]);
+            const row = buildRow('p-1', [cellEntry]);
+
+            // Bump from 1h to 4h → +3h
+            await cellMutations.handleCellUpdate(row, 0, 4 * HOUR);
+
+            // Nothing should be patched or created because the preflight
+            // fit-check rejects the whole edit.
+            expect(apiMocks.updateTimeEntry).not.toHaveBeenCalled();
+            expect(apiMocks.createTimeEntry).not.toHaveBeenCalled();
+        });
+    });
+
+    // ── Shrink (unchanged behavior, still correct) ─────────────────
+
+    describe('shrinkFromEnd', () => {
+        it('shortens the latest entry by the requested amount', async () => {
+            const cellEntry = entry('2026-04-10T09:00:00Z', '2026-04-10T12:00:00Z', {
+                id: 'shrink-me',
+            });
+            const { cellMutations } = setup([cellEntry]);
+            const row = buildRow('p-1', [cellEntry]);
+
+            // 3h → 2h: shrink by 1h
+            await cellMutations.handleCellUpdate(row, 0, 2 * HOUR);
+
+            expect(apiMocks.updateTimeEntry).toHaveBeenCalledTimes(1);
+            const updated = firstArg(apiMocks.updateTimeEntry);
+            expect(updated.end).toBe('2026-04-10T11:00:00Z');
+        });
+
+        it('deletes entries that are entirely consumed', async () => {
+            const a = entry('2026-04-10T09:00:00Z', '2026-04-10T10:00:00Z', {
+                id: 'a',
+            });
+            const b = entry('2026-04-10T11:00:00Z', '2026-04-10T12:00:00Z', {
+                id: 'b',
+            });
+            const { cellMutations } = setup([a, b]);
+            const row = buildRow('p-1', [a, b]);
+
+            // Cell = 2h, shrink to 0.5h: must delete b entirely (1h) and
+            // shorten a from 1h to 30min.
+            await cellMutations.handleCellUpdate(row, 0, 1800);
+
+            expect(apiMocks.deleteTimeEntry).toHaveBeenCalledTimes(1);
+            const [, deleteOptions] = apiMocks.deleteTimeEntry.mock.calls[0]!;
+            expect(deleteOptions?.params?.timeEntry).toBe('b');
+
+            expect(apiMocks.updateTimeEntry).toHaveBeenCalledTimes(1);
+            const updated = firstArg(apiMocks.updateTimeEntry);
+            expect(updated.id).toBe('a');
+            expect(updated.end).toBe('2026-04-10T09:30:00Z');
+        });
+    });
+});

resources/js/utils/timesheet/useTimesheetRowMutations.test.ts

@@ -0,0 +1,272 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { ref } from 'vue';
+import type { Project, TimeEntry } from '@/packages/api/src';
+import type { TimesheetCell, TimesheetRow } from '@/utils/useTimesheetGrid';
+import { useTimesheetRowMutations } from './useTimesheetRowMutations';
+
+const addNotification = vi.fn();
+
+vi.mock('@/utils/notification', () => ({
+    useNotificationsStore: () => ({
+        addNotification,
+    }),
+}));
+
+function project(id: string, isBillable: boolean): Project {
+    return {
+        id,
+        name: id,
+        is_billable: isBillable,
+    } as unknown as Project;
+}
+
+function entry(id: string): TimeEntry {
+    return {
+        id,
+        start: '2026-04-10T09:00:00Z',
+        end: '2026-04-10T10:00:00Z',
+        duration: 3600,
+        description: '',
+        member_id: 'm-1',
+        project_id: 'p-1',
+        task_id: null,
+        billable: false,
+        tags: [],
+    } as unknown as TimeEntry;
+}
+
+function buildCell(entries: TimeEntry[]): TimesheetCell {
+    return {
+        dayIndex: 0,
+        date: '2026-04-10',
+        entries,
+        totalSeconds: entries.reduce((sum, item) => sum + (item.duration ?? 0), 0),
+    };
+}
+
+function buildRow(key: string, projectId: string | null, entries: TimeEntry[]): TimesheetRow {
+    const cells = entries.length > 0 ? new Map([[0, buildCell(entries)]]) : new Map();
+    const totalSeconds = entries.reduce((sum, item) => sum + (item.duration ?? 0), 0);
+
+    return {
+        key,
+        projectId,
+        taskId: null,
+        billable: false,
+        tags: [],
+        cells,
+        totalSeconds,
+    };
+}
+
+describe('useTimesheetRowMutations', () => {
+    beforeEach(() => {
+        addNotification.mockClear();
+    });
+
+    it('collapses a populated row into an existing matching row after identity change', async () => {
+        const existingRow = buildRow('row-a', 'p-1', [entry('e-a')]);
+        const editedRow = buildRow('row-b', 'p-2', [entry('e-b')]);
+        const rows = ref([existingRow, editedRow]);
+        const updateTimeEntries = vi.fn().mockResolvedValue(undefined);
+        const addSlot = vi.fn();
+        const updateSlot = vi.fn();
+        const removeSlot = vi.fn();
+
+        const { handleRowIdentityChange } = useTimesheetRowMutations(
+            { updateTimeEntries },
+            ref<Project[]>([]),
+            rows,
+            addSlot,
+            updateSlot,
+            removeSlot
+        );
+
+        await handleRowIdentityChange(editedRow, { projectId: 'p-1' });
+
+        expect(updateTimeEntries).toHaveBeenCalledWith({
+            ids: ['e-b'],
+            changes: { project_id: 'p-1' },
+        });
+        expect(removeSlot).toHaveBeenCalledWith('row-b');
+        expect(updateSlot).not.toHaveBeenCalled();
+        expect(addNotification).toHaveBeenCalledWith(
+            'success',
+            'Merged into matching row',
+            'Another row with the same project, task, billable status and tags already exists.'
+        );
+    });
+
+    it('translates identity fields to snake_case API field names', async () => {
+        const row = buildRow('row-a', 'p-1', [entry('e-a')]);
+        const rows = ref([row]);
+        const updateTimeEntries = vi.fn().mockResolvedValue(undefined);
+
+        const { handleRowIdentityChange } = useTimesheetRowMutations(
+            { updateTimeEntries },
+            ref<Project[]>([]),
+            rows,
+            vi.fn(),
+            vi.fn(),
+            vi.fn()
+        );
+
+        await handleRowIdentityChange(row, {
+            projectId: 'p-2',
+            taskId: 't-1',
+            billable: true,
+            tags: ['tag-1'],
+        });
+
+        expect(updateTimeEntries).toHaveBeenCalledWith({
+            ids: ['e-a'],
+            changes: {
+                project_id: 'p-2',
+                task_id: 't-1',
+                billable: true,
+                tags: ['tag-1'],
+            },
+        });
+    });
+
+    it('only includes touched fields in the API changeset', async () => {
+        const row = buildRow('row-a', 'p-1', [entry('e-a')]);
+        const rows = ref([row]);
+        const updateTimeEntries = vi.fn().mockResolvedValue(undefined);
+
+        const { handleRowIdentityChange } = useTimesheetRowMutations(
+            { updateTimeEntries },
+            ref<Project[]>([]),
+            rows,
+            vi.fn(),
+            vi.fn(),
+            vi.fn()
+        );
+
+        await handleRowIdentityChange(row, { tags: ['tag-1'] });
+
+        expect(updateTimeEntries).toHaveBeenCalledWith({
+            ids: ['e-a'],
+            changes: { tags: ['tag-1'] },
+        });
+    });
+
+    it('keeps an empty duplicate row until it receives time', async () => {
+        const existingRow = buildRow('row-a', 'p-1', [entry('e-a')]);
+        const emptyRow = buildRow('row-b', 'p-2', []);
+        const rows = ref([existingRow, emptyRow]);
+        const updateTimeEntries = vi.fn().mockResolvedValue(undefined);
+        const addSlot = vi.fn();
+        const updateSlot = vi.fn();
+        const removeSlot = vi.fn();
+
+        const { handleRowIdentityChange } = useTimesheetRowMutations(
+            { updateTimeEntries },
+            ref<Project[]>([]),
+            rows,
+            addSlot,
+            updateSlot,
+            removeSlot
+        );
+
+        await handleRowIdentityChange(emptyRow, { projectId: 'p-1' });
+
+        expect(updateTimeEntries).not.toHaveBeenCalled();
+        expect(updateSlot).toHaveBeenCalledWith('row-b', {
+            projectId: 'p-1',
+            taskId: null,
+            billable: false,
+            tags: [],
+        });
+        expect(removeSlot).not.toHaveBeenCalled();
+    });
+
+    it('sends null project updates when an existing row changes to no project', async () => {
+        const row = buildRow('row-a', 'p-1', [entry('e-a')]);
+        const rows = ref([row]);
+        const updateTimeEntries = vi.fn().mockResolvedValue(undefined);
+        const updateSlot = vi.fn();
+
+        const { handleRowIdentityChange } = useTimesheetRowMutations(
+            { updateTimeEntries },
+            ref<Project[]>([]),
+            rows,
+            vi.fn(),
+            updateSlot,
+            vi.fn()
+        );
+
+        await handleRowIdentityChange(row, { projectId: null });
+
+        expect(updateTimeEntries).toHaveBeenCalledWith({
+            ids: ['e-a'],
+            changes: { project_id: null },
+        });
+        expect(updateSlot).toHaveBeenCalledWith('row-a', {
+            projectId: null,
+            taskId: null,
+            billable: false,
+            tags: [],
+        });
+    });
+
+    it('defaults billable from the selected project when an empty row picks its first project', async () => {
+        const emptyRow = buildRow('row-a', null, []);
+        const rows = ref([emptyRow]);
+        const updateTimeEntries = vi.fn().mockResolvedValue(undefined);
+        const updateSlot = vi.fn();
+
+        const { handleRowIdentityChange } = useTimesheetRowMutations(
+            { updateTimeEntries },
+            ref([project('p-billable', true)]),
+            rows,
+            vi.fn(),
+            updateSlot,
+            vi.fn()
+        );
+
+        await handleRowIdentityChange(emptyRow, { projectId: 'p-billable' });
+
+        expect(updateTimeEntries).not.toHaveBeenCalled();
+        expect(updateSlot).toHaveBeenCalledWith('row-a', {
+            projectId: 'p-billable',
+            taskId: null,
+            billable: true,
+            tags: [],
+        });
+    });
+
+    it('handleAddRow defaults billable from the selected project metadata', () => {
+        const addSlot = vi.fn();
+
+        const { handleAddRow } = useTimesheetRowMutations(
+            { updateTimeEntries: vi.fn() },
+            ref([project('p-billable', true)]),
+            ref<TimesheetRow[]>([]),
+            addSlot,
+            vi.fn(),
+            vi.fn()
+        );
+
+        handleAddRow('p-billable', 't-1');
+
+        expect(addSlot).toHaveBeenCalledWith('p-billable', 't-1', true, []);
+    });
+
+    it('can add a no-project row', () => {
+        const addSlot = vi.fn();
+
+        const { handleAddRow } = useTimesheetRowMutations(
+            { updateTimeEntries: vi.fn() },
+            ref([project('p-billable', true)]),
+            ref<TimesheetRow[]>([]),
+            addSlot,
+            vi.fn(),
+            vi.fn()
+        );
+
+        handleAddRow(null, null);
+
+        expect(addSlot).toHaveBeenCalledWith(null, null, false, []);
+    });
+});

resources/js/utils/useTimesheetGrid.test.ts

@@ -0,0 +1,277 @@
+import { describe, expect, it } from 'vitest';
+import { nextTick, ref } from 'vue';
+import dayjs from 'dayjs';
+import utc from 'dayjs/plugin/utc';
+import type { Dayjs } from 'dayjs';
+import type { Project, Task, TimeEntry } from '@/packages/api/src';
+import { useTimesheetGrid } from './useTimesheetGrid';
+
+dayjs.extend(utc);
+
+const WEEK_DAYS = [
+    '2026-04-06',
+    '2026-04-07',
+    '2026-04-08',
+    '2026-04-09',
+    '2026-04-10',
+    '2026-04-11',
+    '2026-04-12',
+];
+
+function entry(start: string, end: string | null, overrides: Partial<TimeEntry> = {}): TimeEntry {
+    const startMs = new Date(start).valueOf();
+    const endMs = end ? new Date(end).valueOf() : startMs;
+
+    return {
+        id: overrides.id ?? `e-${start}-${end ?? 'running'}`,
+        start,
+        end,
+        duration: end ? Math.floor((endMs - startMs) / 1000) : null,
+        description: '',
+        member_id: 'm-1',
+        project_id: 'p-1',
+        task_id: null,
+        billable: false,
+        tags: [],
+        ...overrides,
+    } as unknown as TimeEntry;
+}
+
+function project(id: string, name: string, isBillable = false): Project {
+    return {
+        id,
+        name,
+        is_billable: isBillable,
+    } as unknown as Project;
+}
+
+function task(id: string, name: string, projectId: string): Task {
+    return {
+        id,
+        name,
+        project_id: projectId,
+    } as unknown as Task;
+}
+
+describe('useTimesheetGrid', () => {
+    it('seeds unseen identities and re-sorts seeded rows when project metadata changes', async () => {
+        const timeEntries = ref([
+            entry('2026-04-10T09:00:00Z', '2026-04-10T10:00:00Z', {
+                id: 'seed-b',
+                project_id: 'p-b',
+                task_id: null,
+            }),
+            entry('2026-04-10T10:00:00Z', '2026-04-10T11:00:00Z', {
+                id: 'seed-a-z',
+                project_id: 'p-a',
+                task_id: 't-z',
+            }),
+            entry('2026-04-10T11:00:00Z', '2026-04-10T12:00:00Z', {
+                id: 'seed-a-a',
+                project_id: 'p-a',
+                task_id: 't-a',
+            }),
+        ]);
+        const projects = ref([project('p-a', 'Bravo'), project('p-b', 'Alpha')]);
+        const tasks = ref([task('t-z', 'Zulu Task', 'p-a'), task('t-a', 'Alpha Task', 'p-a')]);
+
+        const { rows } = useTimesheetGrid(
+            timeEntries,
+            ref(WEEK_DAYS),
+            projects,
+            tasks,
+            ref<Dayjs | null>(null)
+        );
+
+        expect(rows.value.map((row) => `${row.projectId}:${row.taskId}`)).toEqual([
+            'p-b:null',
+            'p-a:t-a',
+            'p-a:t-z',
+        ]);
+
+        projects.value = [project('p-a', 'Aardvark'), project('p-b', 'Zulu')];
+        await nextTick();
+
+        expect(rows.value.map((row) => `${row.projectId}:${row.taskId}`)).toEqual([
+            'p-a:t-a',
+            'p-a:t-z',
+            'p-b:null',
+        ]);
+    });
+
+    it('keeps user-added slots below seeded rows in insertion order', async () => {
+        const timeEntries = ref([
+            entry('2026-04-10T09:00:00Z', '2026-04-10T10:00:00Z', {
+                id: 'seed-b',
+                project_id: 'p-seed-b',
+            }),
+            entry('2026-04-10T10:00:00Z', '2026-04-10T11:00:00Z', {
+                id: 'seed-a',
+                project_id: 'p-seed-a',
+            }),
+        ]);
+        const projects = ref([
+            project('p-seed-a', 'Bravo Seed'),
+            project('p-seed-b', 'Alpha Seed'),
+            project('p-user-1', 'Alpha User'),
+            project('p-user-2', 'Zulu User'),
+        ]);
+
+        const { rows, addSlot } = useTimesheetGrid(
+            timeEntries,
+            ref(WEEK_DAYS),
+            projects,
+            ref<Task[]>([]),
+            ref<Dayjs | null>(null)
+        );
+
+        addSlot('p-user-2', null, false, []);
+        addSlot('p-user-1', null, false, []);
+        await nextTick();
+
+        expect(rows.value.map((row) => row.projectId)).toEqual([
+            'p-seed-b',
+            'p-seed-a',
+            'p-user-2',
+            'p-user-1',
+        ]);
+
+        projects.value = [
+            project('p-seed-a', 'Zulu Seed'),
+            project('p-seed-b', 'Alpha Seed'),
+            project('p-user-1', 'Aardvark User'),
+            project('p-user-2', 'Bravo User'),
+        ];
+        await nextTick();
+
+        expect(rows.value.map((row) => row.projectId)).toEqual([
+            'p-seed-b',
+            'p-seed-a',
+            'p-user-2',
+            'p-user-1',
+        ]);
+    });
+
+    it('assigns entries to the first duplicate-identity slot and leaves later duplicates empty', async () => {
+        const timeEntries = ref<TimeEntry[]>([]);
+
+        const { rows, addSlot } = useTimesheetGrid(
+            timeEntries,
+            ref(WEEK_DAYS),
+            ref([project('p-1', 'Project One')]),
+            ref<Task[]>([]),
+            ref<Dayjs | null>(null)
+        );
+
+        const firstKey = addSlot('p-1', null, false, []);
+        const secondKey = addSlot('p-1', null, false, []);
+        await nextTick();
+
+        timeEntries.value = [
+            entry('2026-04-10T09:00:00Z', '2026-04-10T10:00:00Z', { project_id: 'p-1' }),
+        ];
+        await nextTick();
+
+        expect(rows.value).toHaveLength(2);
+        expect(rows.value[0]?.key).toBe(firstKey);
+        expect(rows.value[0]?.totalSeconds).toBe(3600);
+        expect(rows.value[1]?.key).toBe(secondKey);
+        expect(rows.value[1]?.totalSeconds).toBe(0);
+        expect(rows.value[1]?.cells.size).toBe(0);
+    });
+
+    it('keeps no-project user slots aligned with refetched no-project entries', async () => {
+        const timeEntries = ref<TimeEntry[]>([]);
+
+        const { rows, addSlot } = useTimesheetGrid(
+            timeEntries,
+            ref(WEEK_DAYS),
+            ref<Project[]>([]),
+            ref<Task[]>([]),
+            ref<Dayjs | null>(null)
+        );
+
+        const rowKey = addSlot(null, null, false, []);
+        await nextTick();
+
+        expect(rows.value).toHaveLength(1);
+        expect(rows.value[0]).toMatchObject({ key: rowKey, projectId: null });
+
+        timeEntries.value = [
+            entry('2026-04-10T09:00:00Z', '2026-04-10T10:00:00Z', {
+                id: 'no-project',
+                project_id: null,
+            }),
+        ];
+        await nextTick();
+
+        expect(rows.value).toHaveLength(1);
+        expect(rows.value[0]).toMatchObject({
+            key: rowKey,
+            projectId: null,
+            totalSeconds: 3600,
+        });
+    });
+
+    it('updates a slot identity in place and clearSlots removes all rows', async () => {
+        const { rows, slots, addSlot, updateSlot, clearSlots } = useTimesheetGrid(
+            ref<TimeEntry[]>([]),
+            ref(WEEK_DAYS),
+            ref([project('p-next', 'Next Project')]),
+            ref([task('t-1', 'Task One', 'p-next')]),
+            ref<Dayjs | null>(null)
+        );
+
+        const key = addSlot(null, null, false, []);
+        await nextTick();
+
+        updateSlot(key, {
+            projectId: 'p-next',
+            taskId: 't-1',
+            billable: true,
+            tags: ['b-tag', 'a-tag'],
+        });
+        await nextTick();
+
+        expect(rows.value).toHaveLength(1);
+        expect(rows.value[0]).toMatchObject({
+            key,
+            projectId: 'p-next',
+            taskId: 't-1',
+            billable: true,
+            tags: ['a-tag', 'b-tag'],
+        });
+
+        clearSlots();
+        await nextTick();
+
+        expect(rows.value).toHaveLength(0);
+        expect(slots.value).toHaveLength(0);
+    });
+
+    it('includes running entries in row and week totals using the live timer clock', () => {
+        const currentTime = ref(dayjs.utc('2026-04-10T10:00:00Z'));
+        const runningEntry = entry('2026-04-10T09:00:00Z', null, { id: 'running' });
+
+        const { rows, dayTotals, grandTotal } = useTimesheetGrid(
+            ref([runningEntry]),
+            ref(WEEK_DAYS),
+            ref<Project[]>([]),
+            ref<Task[]>([]),
+            currentTime
+        );
+
+        expect(rows.value).toHaveLength(1);
+        expect(rows.value[0]?.cells.get(4)?.totalSeconds).toBe(3600);
+        expect(rows.value[0]?.totalSeconds).toBe(3600);
+        expect(dayTotals.value[4]).toBe(3600);
+        expect(grandTotal.value).toBe(3600);
+
+        currentTime.value = dayjs.utc('2026-04-10T11:30:00Z');
+
+        expect(rows.value[0]?.cells.get(4)?.totalSeconds).toBe(9000);
+        expect(rows.value[0]?.totalSeconds).toBe(9000);
+        expect(dayTotals.value[4]).toBe(9000);
+        expect(grandTotal.value).toBe(9000);
+    });
+});