@startsimpli/ui 0.4.167 → 0.4.169

package/src/components/timer/__tests__/timer-components.test.tsx

@@ -0,0 +1,147 @@
+import { fireEvent, render, screen, within } from '@testing-library/react'
+import { ColorPicker, PROJECT_COLORS } from '../ColorPicker'
+import { ProjectSwatch } from '../ProjectSwatch'
+import { TimerBar } from '../TimerBar'
+import { IdlePromptDialog } from '../IdlePromptDialog'
+import { EntryFormDialog } from '../EntryFormDialog'
+import { EntryList } from '../EntryList'
+
+const projects = [
+  { id: 'p1', name: 'Alpha', color: '#3366ff' },
+  { id: 'p2', name: 'Beta', color: '#e11d48' },
+]
+
+describe('ColorPicker', () => {
+  it('is a radiogroup that reports the picked colour', () => {
+    const onChange = jest.fn()
+    render(<ColorPicker value={PROJECT_COLORS[0]} onChange={onChange} />)
+    const group = screen.getByRole('radiogroup', { name: /colour/i })
+    const radios = within(group).getAllByRole('radio')
+    expect(radios).toHaveLength(PROJECT_COLORS.length)
+    expect(radios[0]).toHaveAttribute('aria-checked', 'true')
+    fireEvent.click(radios[2])
+    expect(onChange).toHaveBeenCalledWith(PROJECT_COLORS[2])
+  })
+  it('every preset is a 6-digit hex the schema regex accepts', () => {
+    for (const c of PROJECT_COLORS) expect(c).toMatch(/^#[0-9a-fA-F]{6}$/)
+  })
+})
+
+describe('ProjectSwatch', () => {
+  it('paints the dot with the colour and falls back to grey', () => {
+    const { rerender } = render(<ProjectSwatch color="#3366ff" />)
+    expect(screen.getByTestId('swatch')).toHaveStyle({ backgroundColor: '#3366ff' })
+    rerender(<ProjectSwatch color={null} />)
+    expect(screen.getByTestId('swatch')).toHaveStyle({ backgroundColor: '#9ca3af' })
+  })
+})
+
+describe('TimerBar', () => {
+  const base = { projects, projectId: 'p1', note: '', onProjectChange: jest.fn(), onNoteChange: jest.fn(), busy: false, notice: null }
+  it('stopped: one Start action, no elapsed ticker', () => {
+    const onStart = jest.fn()
+    render(<TimerBar {...base} status="stopped" elapsed={0} paused={false} onStart={onStart} onPause={jest.fn()} onStop={jest.fn()} onResume={jest.fn()} />)
+    fireEvent.click(screen.getByRole('button', { name: 'Start' }))
+    expect(onStart).toHaveBeenCalled()
+    expect(screen.queryByRole('button', { name: 'Stop' })).toBeNull()
+  })
+  it('running: shows elapsed with Pause and Stop', () => {
+    const onPause = jest.fn()
+    const onStop = jest.fn()
+    render(<TimerBar {...base} status="running" elapsed={3_661_000} paused={false} onStart={jest.fn()} onPause={onPause} onStop={onStop} onResume={jest.fn()} />)
+    expect(screen.getByRole('timer')).toHaveTextContent('1:01:01')
+    fireEvent.click(screen.getByRole('button', { name: 'Pause' }))
+    fireEvent.click(screen.getByRole('button', { name: 'Stop' }))
+    expect(onPause).toHaveBeenCalled()
+    expect(onStop).toHaveBeenCalled()
+  })
+  it('paused: Resume is the main action', () => {
+    const onResume = jest.fn()
+    render(<TimerBar {...base} status="stopped" elapsed={0} paused onStart={jest.fn()} onPause={jest.fn()} onStop={jest.fn()} onResume={onResume} />)
+    fireEvent.click(screen.getByRole('button', { name: 'Resume' }))
+    expect(onResume).toHaveBeenCalled()
+  })
+  it('says so when the timer was already running elsewhere', () => {
+    render(<TimerBar {...base} status="running" elapsed={1000} paused={false} notice="already-running" onStart={jest.fn()} onPause={jest.fn()} onStop={jest.fn()} onResume={jest.fn()} />)
+    expect(screen.getByRole('status')).toHaveTextContent(/already running/i)
+  })
+  it('changing project and note reports through the callbacks', () => {
+    const onProjectChange = jest.fn()
+    const onNoteChange = jest.fn()
+    render(<TimerBar {...base} onProjectChange={onProjectChange} onNoteChange={onNoteChange} status="stopped" elapsed={0} paused={false} onStart={jest.fn()} onPause={jest.fn()} onStop={jest.fn()} onResume={jest.fn()} />)
+    fireEvent.change(screen.getByLabelText('Project'), { target: { value: 'p2' } })
+    expect(onProjectChange).toHaveBeenCalledWith('p2')
+    fireEvent.change(screen.getByLabelText('What are you working on?'), { target: { value: 'x' } })
+    expect(onNoteChange).toHaveBeenCalledWith('x')
+  })
+})
+
+describe('IdlePromptDialog', () => {
+  const props = { open: true, seconds: 1260, projects, currentProjectId: 'p1', busy: false, onKeep: jest.fn(), onDiscard: jest.fn(), onAssign: jest.fn() }
+  it('states the idle duration and offers keep, discard, assign', () => {
+    const onKeep = jest.fn()
+    const onDiscard = jest.fn()
+    const onAssign = jest.fn()
+    render(<IdlePromptDialog {...props} onKeep={onKeep} onDiscard={onDiscard} onAssign={onAssign} />)
+    expect(screen.getByText(/21 min/)).toBeInTheDocument()
+    fireEvent.click(screen.getByRole('button', { name: 'Keep' }))
+    fireEvent.click(screen.getByRole('button', { name: 'Discard' }))
+    expect(onKeep).toHaveBeenCalled()
+    expect(onDiscard).toHaveBeenCalled()
+    fireEvent.change(screen.getByLabelText('Assign to'), { target: { value: 'p2' } })
+    fireEvent.click(screen.getByRole('button', { name: 'Assign' }))
+    expect(onAssign).toHaveBeenCalledWith('p2')
+  })
+})
+
+describe('EntryFormDialog', () => {
+  it('adds a manual entry from local datetimes', () => {
+    const onSubmit = jest.fn()
+    render(<EntryFormDialog open mode="add" projects={projects} busy={false} onSubmit={onSubmit} onClose={jest.fn()} />)
+    fireEvent.change(screen.getByLabelText('Start'), { target: { value: '2026-10-31T09:00' } })
+    fireEvent.change(screen.getByLabelText('End'), { target: { value: '2026-10-31T10:30' } })
+    fireEvent.change(screen.getByLabelText('Project'), { target: { value: 'p2' } })
+    fireEvent.change(screen.getByLabelText('Note'), { target: { value: 'review' } })
+    fireEvent.click(screen.getByRole('button', { name: 'Add entry' }))
+    const arg = onSubmit.mock.calls[0][0]
+    expect(new Date(arg.endedAt).getTime() - new Date(arg.startedAt).getTime()).toBe(90 * 60_000)
+    expect(arg).toMatchObject({ projectId: 'p2', note: 'review' })
+  })
+  it('refuses an end before the start', () => {
+    const onSubmit = jest.fn()
+    render(<EntryFormDialog open mode="add" projects={projects} busy={false} onSubmit={onSubmit} onClose={jest.fn()} />)
+    fireEvent.change(screen.getByLabelText('Start'), { target: { value: '2026-10-31T10:00' } })
+    fireEvent.change(screen.getByLabelText('End'), { target: { value: '2026-10-31T09:00' } })
+    fireEvent.click(screen.getByRole('button', { name: 'Add entry' }))
+    expect(onSubmit).not.toHaveBeenCalled()
+    expect(screen.getByRole('alert')).toHaveTextContent(/after/i)
+  })
+  it('edit prefills and offers delete', () => {
+    const onDelete = jest.fn()
+    render(
+      <EntryFormDialog open mode="edit" projects={projects} busy={false} onSubmit={jest.fn()} onDelete={onDelete} onClose={jest.fn()}
+        initial={{ startedAt: '2026-10-31T09:00:00.000Z', endedAt: '2026-10-31T10:00:00.000Z', projectId: 'p1', note: 'old' }} />,
+    )
+    expect(screen.getByLabelText('Note')).toHaveValue('old')
+    expect(screen.getByLabelText('Project')).toHaveValue('p1')
+    fireEvent.click(screen.getByRole('button', { name: 'Delete' }))
+    expect(onDelete).toHaveBeenCalled()
+  })
+})
+
+describe('EntryList', () => {
+  it('shows colour, project, note, span and duration, and edits on click', () => {
+    const onEdit = jest.fn()
+    const entries = [{ id: 'e1', startedAt: '2026-10-31T09:00:00.000Z', endedAt: '2026-10-31T10:30:00.000Z', projectId: 'p1', note: 'spec' }]
+    render(<EntryList entries={entries} projects={projects} onEdit={onEdit} />)
+    expect(screen.getByText('Alpha')).toBeInTheDocument()
+    expect(screen.getByText('spec')).toBeInTheDocument()
+    expect(screen.getByText('1:30:00')).toBeInTheDocument()
+    fireEvent.click(screen.getByRole('button', { name: /edit/i }))
+    expect(onEdit).toHaveBeenCalledWith(entries[0])
+  })
+  it('says when there is nothing yet', () => {
+    render(<EntryList entries={[]} projects={projects} onEdit={jest.fn()} />)
+    expect(screen.getByText(/no entries/i)).toBeInTheDocument()
+  })
+})

package/src/components/timer/__tests__/useIdleReturn.test.tsx

@@ -0,0 +1,59 @@
+import { renderHook, act } from '@testing-library/react'
+import { useIdleReturn, type IdleSignal } from '../useIdleReturn'
+
+function bus() {
+  const subs = new Set<(e: IdleSignal) => void>()
+  return {
+    subscribe: (cb: (e: IdleSignal) => void) => {
+      subs.add(cb)
+      return () => subs.delete(cb)
+    },
+    emit: (e: IdleSignal) => subs.forEach((s) => s(e)),
+  }
+}
+
+const t = (s: string) => new Date(s).getTime()
+const idleSince = t('2026-10-31T10:00:00.000Z')
+const ts = t('2026-10-31T10:20:00.000Z')
+
+describe('useIdleReturn', () => {
+  it('opens a prompt on idle-end while a timer runs, with the idle duration', () => {
+    const b = bus()
+    const { result } = renderHook(() => useIdleReturn({ subscribe: b.subscribe, runningSince: t('2026-10-31T09:00:00.000Z') }))
+    expect(result.current.prompt).toBeNull()
+    act(() => b.emit({ type: 'idle-start', ts: idleSince, idleSince }))
+    expect(result.current.prompt).toBeNull()
+    act(() => b.emit({ type: 'idle-end', ts, idleSince }))
+    expect(result.current.prompt).toEqual({ idleSince, until: ts, seconds: 1200 })
+  })
+
+  it('ignores a return when no timer is running', () => {
+    const b = bus()
+    const { result } = renderHook(() => useIdleReturn({ subscribe: b.subscribe, runningSince: null }))
+    act(() => b.emit({ type: 'idle-end', ts, idleSince }))
+    expect(result.current.prompt).toBeNull()
+  })
+
+  it('ignores idle shorter than the minimum', () => {
+    const b = bus()
+    const { result } = renderHook(() => useIdleReturn({ subscribe: b.subscribe, runningSince: 0, minSeconds: 600 }))
+    act(() => b.emit({ type: 'idle-end', ts: idleSince + 120_000, idleSince }))
+    expect(result.current.prompt).toBeNull()
+  })
+
+  it('dismiss clears it, and non-idle events never open it', () => {
+    const b = bus()
+    const { result } = renderHook(() => useIdleReturn({ subscribe: b.subscribe, runningSince: 0 }))
+    act(() => b.emit({ type: 'lock', ts }))
+    expect(result.current.prompt).toBeNull()
+    act(() => b.emit({ type: 'idle-end', ts, idleSince }))
+    expect(result.current.prompt).not.toBeNull()
+    act(() => result.current.dismiss())
+    expect(result.current.prompt).toBeNull()
+  })
+
+  it('works without a subscription (browser build)', () => {
+    const { result } = renderHook(() => useIdleReturn({ subscribe: undefined, runningSince: 0 }))
+    expect(result.current.prompt).toBeNull()
+  })
+})

package/src/components/timer/__tests__/useRunningTimer.test.tsx

@@ -0,0 +1,167 @@
+import { renderHook, act, waitFor } from '@testing-library/react'
+import { useRunningTimer } from '../useRunningTimer'
+import type { IntervalStore, TimedEntry } from '../interval-logic'
+
+const conflict = () => Object.assign(new Error('conflict'), { status: 409 })
+const stale = () => Object.assign(new Error('stale'), { status: 412 })
+
+function fakeStore(initial: TimedEntry | null = null) {
+  let running = initial
+  let seq = 0
+  const calls: string[] = []
+  const store: IntervalStore & { calls: string[]; setRunning(e: TimedEntry | null): void; failNext: { create?: Error; update?: Error } } = {
+    calls,
+    failNext: {},
+    setRunning(e) {
+      running = e
+    },
+    async findRunning() {
+      calls.push('find')
+      return running
+    },
+    async create(input) {
+      calls.push(`create:${input.endedAt ?? 'open'}`)
+      if (store.failNext.create) {
+        const e = store.failNext.create
+        store.failNext.create = undefined
+        throw e
+      }
+      const e: TimedEntry = { id: `n${++seq}`, version: 1, startedAt: input.startedAt, endedAt: input.endedAt, projectId: input.projectId ?? null, note: input.note ?? '' }
+      if (!input.endedAt) running = e
+      return e
+    },
+    async update(entry, patch) {
+      calls.push(`update:${JSON.stringify(patch)}`)
+      if (store.failNext.update) {
+        const e = store.failNext.update
+        store.failNext.update = undefined
+        throw e
+      }
+      const next = { ...entry, ...patch, version: (entry.version ?? 0) + 1 } as TimedEntry
+      if (running?.id === entry.id) running = next.endedAt ? null : next
+      return next
+    },
+    async remove() {},
+  }
+  return store
+}
+
+const open = (over: Partial<TimedEntry> = {}): TimedEntry => ({
+  id: 'r1', version: 1, startedAt: '2026-10-31T09:00:00.000Z', endedAt: null, projectId: 'p1', note: 'n', ...over,
+})
+
+describe('useRunningTimer', () => {
+  it('loads an already running entry and counts elapsed from now()', async () => {
+    const store = fakeStore(open())
+    const now = jest.fn(() => new Date('2026-10-31T09:00:10.000Z').getTime())
+    const { result } = renderHook(() => useRunningTimer({ store, now, tickMs: 0 }))
+    await waitFor(() => expect(result.current.status).toBe('running'))
+    expect(result.current.elapsed).toBe(10_000)
+  })
+
+  it('starts with the chosen project and note', async () => {
+    const store = fakeStore()
+    const now = () => new Date('2026-10-31T09:00:00.000Z').getTime()
+    const { result } = renderHook(() => useRunningTimer({ store, now, tickMs: 0 }))
+    await waitFor(() => expect(result.current.status).toBe('stopped'))
+    await act(() => result.current.start({ projectId: 'p2', note: 'hi' }))
+    expect(result.current.status).toBe('running')
+    expect(result.current.entry).toMatchObject({ projectId: 'p2', note: 'hi', startedAt: '2026-10-31T09:00:00.000Z' })
+  })
+
+  it('on 409 adopts the entry running elsewhere and says so', async () => {
+    const store = fakeStore()
+    const { result } = renderHook(() => useRunningTimer({ store, tickMs: 0 }))
+    await waitFor(() => expect(result.current.status).toBe('stopped'))
+    store.failNext.create = conflict()
+    store.setRunning(open({ id: 'other' }))
+    await act(() => result.current.start({}))
+    expect(result.current.status).toBe('running')
+    expect(result.current.entry?.id).toBe('other')
+    expect(result.current.notice).toBe('already-running')
+    expect(result.current.error).toBeNull()
+  })
+
+  it('pause closes the entry; resume reopens with the same project and note', async () => {
+    const store = fakeStore(open())
+    const { result } = renderHook(() => useRunningTimer({ store, tickMs: 0 }))
+    await waitFor(() => expect(result.current.status).toBe('running'))
+    await act(() => result.current.pause())
+    expect(result.current.status).toBe('stopped')
+    expect(result.current.paused).toMatchObject({ projectId: 'p1', note: 'n' })
+    await act(() => result.current.resume())
+    expect(result.current.status).toBe('running')
+    expect(result.current.entry).toMatchObject({ projectId: 'p1', note: 'n' })
+    expect(result.current.entry?.id).not.toBe('r1')
+  })
+
+  it('stop forgets the paused interval, so there is nothing to resume', async () => {
+    const store = fakeStore(open())
+    const { result } = renderHook(() => useRunningTimer({ store, tickMs: 0 }))
+    await waitFor(() => expect(result.current.status).toBe('running'))
+    await act(() => result.current.stop())
+    expect(result.current.paused).toBeNull()
+  })
+
+  it('stop on a stale version re-reads and closes the fresh row once', async () => {
+    const store = fakeStore(open())
+    const { result } = renderHook(() => useRunningTimer({ store, tickMs: 0 }))
+    await waitFor(() => expect(result.current.status).toBe('running'))
+    store.failNext.update = stale()
+    store.setRunning(open({ version: 2 }))
+    await act(() => result.current.stop())
+    expect(result.current.status).toBe('stopped')
+    expect(result.current.error).toBeNull()
+  })
+
+  it('stop when another window already stopped it just refreshes to stopped', async () => {
+    const store = fakeStore(open())
+    const { result } = renderHook(() => useRunningTimer({ store, tickMs: 0 }))
+    await waitFor(() => expect(result.current.status).toBe('running'))
+    store.failNext.update = stale()
+    store.setRunning(null)
+    await act(() => result.current.stop())
+    expect(result.current.status).toBe('stopped')
+  })
+
+  it('surfaces other errors without losing the running entry', async () => {
+    const store = fakeStore(open())
+    const { result } = renderHook(() => useRunningTimer({ store, tickMs: 0 }))
+    await waitFor(() => expect(result.current.status).toBe('running'))
+    store.failNext.update = new Error('boom')
+    await act(() => result.current.stop())
+    expect(result.current.error?.message).toBe('boom')
+    expect(result.current.status).toBe('running')
+  })
+
+  it('reports each state change through onChange (tray sync)', async () => {
+    const store = fakeStore()
+    const onChange = jest.fn()
+    const { result } = renderHook(() => useRunningTimer({ store, tickMs: 0, onChange }))
+    await waitFor(() => expect(result.current.status).toBe('stopped'))
+    await act(() => result.current.start({ note: 'x' }))
+    expect(onChange).toHaveBeenLastCalledWith(expect.objectContaining({ id: expect.any(String), note: 'x' }))
+    await act(() => result.current.stop())
+    expect(onChange).toHaveBeenLastCalledWith(null)
+  })
+
+  it('resolves idle time through the planned writes, close before create', async () => {
+    const store = fakeStore(open())
+    const { result } = renderHook(() => useRunningTimer({ store, tickMs: 0 }))
+    await waitFor(() => expect(result.current.status).toBe('running'))
+    store.calls.length = 0
+    await act(() =>
+      result.current.resolveIdle({
+        idleSince: new Date('2026-10-31T10:00:00.000Z').getTime(),
+        now: new Date('2026-10-31T10:20:00.000Z').getTime(),
+        choice: { kind: 'assign', projectId: 'p2' },
+      }),
+    )
+    expect(store.calls.filter((c) => c !== 'find')).toEqual([
+      'update:{"endedAt":"2026-10-31T10:00:00.000Z"}',
+      'create:2026-10-31T10:20:00.000Z',
+      'create:open',
+    ])
+    expect(result.current.entry?.startedAt).toBe('2026-10-31T10:20:00.000Z')
+  })
+})

package/src/components/timer/index.ts

@@ -0,0 +1,20 @@
+export * from './interval-logic'
+export { useRunningTimer } from './useRunningTimer'
+export type { RunningTimer, StartInput, UseRunningTimerOptions } from './useRunningTimer'
+export { useIdleReturn } from './useIdleReturn'
+export type { IdlePrompt, IdleSignal, UseIdleReturnOptions } from './useIdleReturn'
+export { ProjectSwatch, NO_COLOR } from './ProjectSwatch'
+export { ColorPicker, PROJECT_COLORS } from './ColorPicker'
+export type { ColorPickerProps } from './ColorPicker'
+export { ProjectSelect } from './ProjectSelect'
+export type { ProjectOption, ProjectSelectProps } from './ProjectSelect'
+export { TimerBar } from './TimerBar'
+export type { TimerBarProps } from './TimerBar'
+export { IdlePromptDialog, formatIdle } from './IdlePromptDialog'
+export type { IdlePromptDialogProps } from './IdlePromptDialog'
+export { EntryFormDialog } from './EntryFormDialog'
+export type { EntryFormDialogProps, EntryFormValue } from './EntryFormDialog'
+export { EntryList } from './EntryList'
+export type { EntryListProps } from './EntryList'
+export { ProjectsDialog } from './ProjectsDialog'
+export type { ProjectsDialogProps, ProjectSave, ClientOption } from './ProjectsDialog'

package/src/components/timer/interval-logic.ts

@@ -0,0 +1,140 @@
+/**
+ * Pure logic for a running-interval timer: one open interval per owner,
+ * closed intervals everywhere else. Nothing here names time tracking beyond
+ * "started" and "ended"; a shift clock or a checkout ledger fits the same shape.
+ *
+ * PAUSE IS NOT A STATE. Pausing closes the interval; resuming opens a new one
+ * with the same project and note. Every row stays one closed interval, so a
+ * report is a sum of rows, and the store needs no attribute beyond the two
+ * timestamps (bd startsim-i2t09).
+ */
+
+export type EntryId = string | number
+
+/** One interval. `endedAt` null means it is running. Timestamps are UTC ISO-8601. */
+export interface TimedEntry {
+  id: EntryId
+  /** Row version for the store's optimistic write; opaque here. */
+  version?: number
+  startedAt: string
+  endedAt: string | null
+  projectId: EntryId | null
+  note: string
+  /**
+   * Store-owned passthrough for attributes the timer does not model. A backend whose
+   * update replaces the whole record must send them back or they are lost.
+   */
+  extra?: Record<string, unknown>
+}
+
+export interface NewEntry {
+  startedAt: string
+  endedAt: string | null
+  projectId?: EntryId | null
+  note?: string
+}
+
+export interface EntryPatch {
+  startedAt?: string
+  endedAt?: string | null
+  projectId?: EntryId | null
+  note?: string
+}
+
+/**
+ * What a backend must offer. `create` with `endedAt: null` is "start"; an
+ * `update` with `endedAt` set is "stop". A second open interval for the same
+ * owner must be refused with an error carrying `status: 409`.
+ */
+export interface IntervalStore {
+  findRunning(): Promise<TimedEntry | null>
+  create(input: NewEntry): Promise<TimedEntry>
+  update(entry: TimedEntry, patch: EntryPatch): Promise<TimedEntry>
+  remove(entry: TimedEntry): Promise<void>
+}
+
+export function isStatus(err: unknown, status: number): boolean {
+  return typeof err === 'object' && err !== null && (err as { status?: unknown }).status === status
+}
+
+export function elapsedMs(startedAt: string, nowMs: number): number {
+  return Math.max(0, nowMs - new Date(startedAt).getTime())
+}
+
+/** `h:mm:ss`, hours unbounded (a 100 hour interval reads `100:00:00`). */
+export function formatElapsed(ms: number): string {
+  const total = Math.max(0, Math.floor(ms / 1000))
+  const h = Math.floor(total / 3600)
+  const m = Math.floor((total % 3600) / 60)
+  const s = total % 60
+  return `${h}:${String(m).padStart(2, '0')}:${String(s).padStart(2, '0')}`
+}
+
+const iso = (ms: number) => new Date(ms).toISOString()
+
+export type IdleChoice = { kind: 'keep' } | { kind: 'discard' } | { kind: 'assign'; projectId: EntryId }
+
+export type IdleOp =
+  | { kind: 'update'; patch: EntryPatch }
+  | { kind: 'create'; input: Required<Pick<NewEntry, 'startedAt' | 'endedAt'>> & { projectId: EntryId | null; note: string } }
+
+/**
+ * The ordered writes that resolve an idle window `[idleSince, now]` on the
+ * running `entry`. Order matters: the open-interval rule refuses a second open
+ * row, so the running row is always closed before a new one is created.
+ *
+ * `update` ops target `entry`. All timestamps are UTC ISO strings: the server
+ * compares them as text, so mixed offsets would sort wrong.
+ */
+export function planIdleResolution(input: {
+  entry: TimedEntry
+  idleSince: number
+  now: number
+  choice: IdleChoice
+}): IdleOp[] {
+  const { entry, idleSince, now, choice } = input
+  if (choice.kind === 'keep') return []
+  const startedInsideIdle = new Date(entry.startedAt).getTime() >= idleSince
+  const resumed: IdleOp = {
+    kind: 'create',
+    input: { startedAt: iso(now), endedAt: null, projectId: entry.projectId, note: entry.note },
+  }
+
+  if (startedInsideIdle) {
+    // Nothing before the idle window to keep: the entry itself is the idle time.
+    if (choice.kind === 'discard') return [{ kind: 'update', patch: { startedAt: iso(now) } }]
+    return [{ kind: 'update', patch: { endedAt: iso(now), projectId: choice.projectId } }, resumed]
+  }
+
+  const close: IdleOp = { kind: 'update', patch: { endedAt: iso(idleSince) } }
+  if (choice.kind === 'discard') return [close, resumed]
+  return [
+    close,
+    { kind: 'create', input: { startedAt: iso(idleSince), endedAt: iso(now), projectId: choice.projectId, note: '' } },
+    resumed,
+  ]
+}
+
+const pad = (n: number) => String(n).padStart(2, '0')
+
+/** ISO instant -> the `yyyy-mm-ddThh:mm` a datetime-local input shows (local zone). */
+export function toLocalInput(isoString: string): string {
+  const d = new Date(isoString)
+  if (Number.isNaN(d.getTime())) return ''
+  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}T${pad(d.getHours())}:${pad(d.getMinutes())}`
+}
+
+/** A datetime-local value -> UTC ISO, or null when blank or unparsable. */
+export function fromLocalInput(value: string): string | null {
+  if (!value) return null
+  const d = new Date(value)
+  return Number.isNaN(d.getTime()) ? null : d.toISOString()
+}
+
+export function validateRange(startedAt: string | null, endedAt: string | null): string | null {
+  if (!startedAt) return 'Enter a start time.'
+  if (endedAt && new Date(endedAt).getTime() <= new Date(startedAt).getTime()) {
+    return 'The end must be after the start.'
+  }
+  return null
+}

package/src/components/timer/useIdleReturn.ts

@@ -0,0 +1,49 @@
+'use client'
+
+import { useCallback, useEffect, useState } from 'react'
+
+/** The slice of the shell's idle events this hook reads (matches @startsimpli/desktop). */
+export type IdleSignal =
+  | { type: 'idle-start'; ts: number; idleSince: number; idleSeconds?: number }
+  | { type: 'idle-end'; ts: number; idleSince: number; idleSeconds?: number }
+  | { type: 'lock' | 'unlock' | 'suspend' | 'resume'; ts: number }
+
+export interface IdlePrompt {
+  /** When the idle stretch began (epoch ms). */
+  idleSince: number
+  /** When the user came back (epoch ms). */
+  until: number
+  seconds: number
+}
+
+export interface UseIdleReturnOptions {
+  /** Subscribe to idle events; undefined outside the desktop shell. */
+  subscribe: ((cb: (e: IdleSignal) => void) => () => void) | undefined
+  /** Epoch ms the running interval started; null when nothing is running. */
+  runningSince: number | null
+  /** Idle shorter than this is not worth asking about. */
+  minSeconds?: number
+}
+
+/**
+ * Turns the shell's idle-end event into a prompt, but only when an interval was
+ * running before the idle stretch began. The timer itself keeps running
+ * through idle; policy (keep, discard, assign) is applied by the caller.
+ */
+export function useIdleReturn({ subscribe, runningSince, minSeconds = 0 }: UseIdleReturnOptions) {
+  const [prompt, setPrompt] = useState<IdlePrompt | null>(null)
+
+  useEffect(() => {
+    if (!subscribe) return
+    return subscribe((e) => {
+      if (e.type !== 'idle-end') return
+      if (runningSince === null) return
+      const seconds = Math.round((e.ts - e.idleSince) / 1000)
+      if (seconds < minSeconds) return
+      setPrompt({ idleSince: e.idleSince, until: e.ts, seconds })
+    })
+  }, [subscribe, runningSince, minSeconds])
+
+  const dismiss = useCallback(() => setPrompt(null), [])
+  return { prompt, dismiss }
+}