@startsimpli/ui 0.4.167 → 0.4.169

package/src/components/timer/useRunningTimer.ts

@@ -0,0 +1,209 @@
+'use client'
+
+import { useCallback, useEffect, useRef, useState } from 'react'
+import {
+  elapsedMs,
+  isStatus,
+  planIdleResolution,
+  type EntryId,
+  type IdleChoice,
+  type IntervalStore,
+  type TimedEntry,
+} from './interval-logic'
+
+export interface StartInput {
+  projectId?: EntryId | null
+  note?: string
+}
+
+export interface UseRunningTimerOptions {
+  store: IntervalStore
+  /** Clock, injectable for tests. */
+  now?: () => number
+  /** Re-render period while running; 0 disables the interval (tests). */
+  tickMs?: number
+  /** Called with the running entry (or null) whenever it changes, once loaded. Drives the tray. */
+  onChange?: (entry: TimedEntry | null) => void
+}
+
+export interface RunningTimer {
+  status: 'loading' | 'stopped' | 'running'
+  entry: TimedEntry | null
+  /** Milliseconds since the running entry started; 0 when stopped. */
+  elapsed: number
+  /** Set by pause(), cleared by stop() and resume(): what Resume would reopen. */
+  paused: TimedEntry | null
+  busy: boolean
+  error: Error | null
+  /** 'already-running': a start lost to an interval running elsewhere, which is now shown. */
+  notice: 'already-running' | null
+  start(input?: StartInput): Promise<void>
+  /** Closes the interval and keeps its project and note for resume(). */
+  pause(): Promise<void>
+  /** Closes the interval. */
+  stop(): Promise<void>
+  resume(): Promise<void>
+  refresh(): Promise<void>
+  resolveIdle(input: { idleSince: number; now: number; choice: IdleChoice }): Promise<void>
+  clearNotice(): void
+}
+
+/**
+ * The running interval, as the store sees it. The server is the authority: a
+ * start that loses the one-open-interval race (409) adopts the winner, a write
+ * against a moved row (412) re-reads once, and the tray/other windows are
+ * reconciled by refreshing on focus.
+ */
+export function useRunningTimer({ store, now = Date.now, tickMs = 1000, onChange }: UseRunningTimerOptions): RunningTimer {
+  const [entry, setEntry] = useState<TimedEntry | null>(null)
+  const [loaded, setLoaded] = useState(false)
+  const [paused, setPaused] = useState<TimedEntry | null>(null)
+  const [busy, setBusy] = useState(false)
+  const [error, setError] = useState<Error | null>(null)
+  const [notice, setNotice] = useState<'already-running' | null>(null)
+  const [, setTick] = useState(0)
+  const entryRef = useRef(entry)
+  entryRef.current = entry
+  const onChangeRef = useRef(onChange)
+  onChangeRef.current = onChange
+
+  const refresh = useCallback(async () => {
+    try {
+      setEntry(await store.findRunning())
+    } catch (e) {
+      setError(e as Error)
+    } finally {
+      setLoaded(true)
+    }
+  }, [store])
+
+  useEffect(() => {
+    void refresh()
+  }, [refresh])
+
+  useEffect(() => {
+    if (!loaded) return
+    onChangeRef.current?.(entry)
+  }, [entry, loaded])
+
+  useEffect(() => {
+    if (!entry || tickMs <= 0) return
+    const id = setInterval(() => setTick((n) => n + 1), tickMs)
+    return () => clearInterval(id)
+  }, [entry, tickMs])
+
+  useEffect(() => {
+    if (typeof window === 'undefined') return
+    const onFocus = () => void refresh()
+    window.addEventListener('focus', onFocus)
+    return () => window.removeEventListener('focus', onFocus)
+  }, [refresh])
+
+  const guarded = useCallback(async (fn: () => Promise<void>) => {
+    setBusy(true)
+    setError(null)
+    try {
+      await fn()
+    } catch (e) {
+      setError(e as Error)
+    } finally {
+      setBusy(false)
+    }
+  }, [])
+
+  /** Runs `fn` against the held row; on a stale version re-reads the running row and tries once more. */
+  const withFresh = useCallback(
+    async <T,>(fn: (e: TimedEntry) => Promise<T>): Promise<T | undefined> => {
+      const current = entryRef.current
+      if (!current) return undefined
+      try {
+        return await fn(current)
+      } catch (err) {
+        if (!isStatus(err, 412)) throw err
+        const fresh = await store.findRunning()
+        setEntry(fresh)
+        if (!fresh) return undefined
+        return fn(fresh)
+      }
+    },
+    [store],
+  )
+
+  const start = useCallback(
+    (input: StartInput = {}) =>
+      guarded(async () => {
+        setNotice(null)
+        try {
+          const created = await store.create({
+            startedAt: new Date(now()).toISOString(),
+            endedAt: null,
+            projectId: input.projectId ?? null,
+            note: input.note ?? '',
+          })
+          setEntry(created)
+        } catch (err) {
+          if (!isStatus(err, 409)) throw err
+          // Another window or the tray won the race: show what is running.
+          const winner = await store.findRunning()
+          setEntry(winner)
+          if (winner) setNotice('already-running')
+          else throw err
+        }
+      }),
+    [guarded, store, now],
+  )
+
+  const close = useCallback(
+    (keep: boolean) =>
+      guarded(async () => {
+        const closed = await withFresh((e) => store.update(e, { endedAt: new Date(now()).toISOString() }))
+        setPaused(keep && closed ? closed : null)
+        setEntry(null)
+      }),
+    [guarded, withFresh, store, now],
+  )
+  const stop = useCallback(() => close(false), [close])
+  const pause = useCallback(() => close(true), [close])
+
+  const resume = useCallback(async () => {
+    const from = paused
+    await start({ projectId: from?.projectId ?? null, note: from?.note ?? '' })
+    setPaused(null)
+  }, [start, paused])
+
+  const resolveIdle = useCallback(
+    (input: { idleSince: number; now: number; choice: IdleChoice }) =>
+      guarded(async () => {
+        const current = entryRef.current
+        if (!current) return
+        const ops = planIdleResolution({ entry: current, ...input })
+        try {
+          for (const op of ops) {
+            if (op.kind === 'update') await withFresh((e) => store.update(e, op.patch))
+            else await store.create(op.input)
+          }
+        } finally {
+          // Whatever landed, the server's view is the truth.
+          await refresh()
+        }
+      }),
+    [guarded, withFresh, store, refresh],
+  )
+
+  return {
+    status: !loaded ? 'loading' : entry ? 'running' : 'stopped',
+    entry,
+    elapsed: entry ? elapsedMs(entry.startedAt, now()) : 0,
+    paused,
+    busy,
+    error,
+    notice,
+    start,
+    pause,
+    stop,
+    resume,
+    refresh,
+    resolveIdle,
+    clearNotice: () => setNotice(null),
+  }
+}

package/src/utils/__tests__/xlsx.test.ts

@@ -0,0 +1,36 @@
+import * as XLSX from 'xlsx'
+import { csvFromRows } from '../csv'
+import { xlsxFromRows } from '../xlsx'
+
+const rows: (string | number)[][] = [
+  ['Period', 'Entries', 'Minutes', 'Earnings'],
+  ['2026-07', 3, 255, 195],
+  ['2026-08', 1, 60, 50],
+  ['Total', 4, 315, 245],
+]
+
+describe('xlsxFromRows', () => {
+  it('writes numbers as numbers so a spreadsheet can sum them', () => {
+    const wb = XLSX.read(xlsxFromRows(rows, { sheetName: 'Hours' }), { type: 'array' })
+    expect(wb.SheetNames).toEqual(['Hours'])
+    const back = XLSX.utils.sheet_to_json<(string | number)[]>(wb.Sheets.Hours, { header: 1 })
+    expect(back).toEqual(rows)
+    expect(typeof back[1][2]).toBe('number')
+  })
+
+  it('does not turn a formula-looking string into a formula', () => {
+    const wb = XLSX.read(xlsxFromRows([['=1+1', '@x']]), { type: 'array' })
+    const cell = wb.Sheets[wb.SheetNames[0]].A1
+    expect(cell.t).toBe('s')
+    expect(cell.f).toBeUndefined()
+    expect(cell.v).toBe('=1+1')
+  })
+
+  it('agrees with the CSV writer on every cell', () => {
+    const wb = XLSX.read(xlsxFromRows(rows), { type: 'array' })
+    const fromXlsx = XLSX.utils.sheet_to_csv(wb.Sheets[wb.SheetNames[0]], { rawNumbers: true })
+    expect(fromXlsx.trim().split('\n').map((l) => l.split(','))).toEqual(
+      csvFromRows(rows.map((r) => r.map(String))).trim().split('\r\n').map((l) => l.split(',')),
+    )
+  })
+})

package/src/utils/index.ts

@@ -8,6 +8,7 @@ export {
   downloadBlob,
   type CsvColumn,
 } from './csv'
+export { xlsxFromRows, downloadXlsx, XLSX_MIME, type XlsxCell } from './xlsx'
 
 /**
  * Generate a random ID with optional prefix

package/src/utils/xlsx.ts

@@ -0,0 +1,35 @@
+import * as XLSX from 'xlsx'
+import { downloadBlob } from './csv'
+
+/**
+ * A spreadsheet from rows, written so a spreadsheet can use it.
+ *
+ * Numbers stay numbers (a total column can be summed), strings stay strings -
+ * a `=...` string is stored as text, never as a formula, so no guard prefix is
+ * needed here (the CSV writer needs one; this format has a cell type for text).
+ * Returns the bytes so a test, a server or a download can all consume it;
+ * `downloadXlsx` is the thin browser wrapper. Pairs with `csvFromRows`: give
+ * both the same matrix and the two files hold the same values.
+ *
+ * Uses `xlsx` (SheetJS), already a dependency of this package for the table
+ * export. Only the write path is used; the parse path with the published
+ * advisories is not reachable from here.
+ */
+export type XlsxCell = string | number | boolean | null
+
+export function xlsxFromRows(rows: XlsxCell[][], opts: { sheetName?: string } = {}): Uint8Array {
+  const ws = XLSX.utils.aoa_to_sheet(rows)
+  const widths = rows[0]?.map((_, i) => ({
+    wch: Math.min(50, Math.max(...rows.map((r) => String(r[i] ?? '').length)) + 2),
+  }))
+  if (widths) ws['!cols'] = widths
+  const wb = XLSX.utils.book_new()
+  XLSX.utils.book_append_sheet(wb, ws, (opts.sheetName ?? 'Sheet1').slice(0, 31))
+  return new Uint8Array(XLSX.write(wb, { bookType: 'xlsx', type: 'array' }))
+}
+
+export const XLSX_MIME = 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'
+
+export function downloadXlsx(filename: string, rows: XlsxCell[][], opts: { sheetName?: string } = {}): void {
+  downloadBlob(filename, new Blob([xlsxFromRows(rows, opts) as BlobPart], { type: XLSX_MIME }))
+}