@startsimpli/ui 0.4.168 → 0.4.169

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/ui",
-  "version": "0.4.168",
+  "version": "0.4.169",
   "description": "Shared UI components package for StartSimpli applications",
   "license": "MIT",
   "homepage": "https://startsimpli.com",
@@ -44,7 +44,8 @@
     "./session": "./src/components/session/index.ts",
     "./session-console": "./src/components/session/AgentSessionConsole.tsx",
     "./tailwind": "./tailwind.preset.js",
-    "./track-changes": "./src/components/track-changes/index.ts"
+    "./track-changes": "./src/components/track-changes/index.ts",
+    "./timer": "./src/components/timer/index.ts"
   },
   "files": [
     "src",
@@ -66,9 +67,9 @@
     "@codemirror/language": "^6.0.0",
     "@codemirror/state": "^6.0.0",
     "@codemirror/view": "^6.0.0",
-    "@startsimpli/auth": "^0.4.48",
-    "@startsimpli/api": "^0.5.70",
-    "@startsimpli/i18n": "^0.1.4"
+    "@startsimpli/auth": "^0.4.47",
+    "@startsimpli/api": "^0.5.69",
+    "@startsimpli/i18n": "^0.1.3"
   },
   "peerDependenciesMeta": {
     "@startsimpli/api": {
@@ -163,8 +164,8 @@
     "tailwindcss": "^3.4.19",
     "tsup": "^8.5.1",
     "typescript": "^6.0.3",
-    "@startsimpli/realtime": "0.0.3",
-    "@startsimpli/i18n": "0.1.4"
+    "@startsimpli/i18n": "0.1.3",
+    "@startsimpli/realtime": "0.0.2"
   },
   "keywords": [
     "ui",

package/src/components/charts/PeriodBars.tsx

@@ -0,0 +1,36 @@
+'use client'
+
+import * as React from 'react'
+import { Bar, BarChart, CartesianGrid, ResponsiveContainer, Tooltip, XAxis, YAxis } from 'recharts'
+import { SERIES_COLORS } from './TimeSeriesChart'
+
+export interface PeriodBarsDatum {
+  /** X axis label for the period. */
+  label: string
+  value: number
+}
+
+export interface PeriodBarsProps {
+  data: PeriodBarsDatum[]
+  /** What the bars measure, for the tooltip and the accessible name. */
+  unit: string
+  height?: number
+  ariaLabel?: string
+}
+
+/** One bar per period. Categorical axis, so a gap period is simply absent. */
+export function PeriodBars({ data, unit, height = 220, ariaLabel }: PeriodBarsProps) {
+  return (
+    <div role="img" aria-label={ariaLabel ?? `${unit} per period`} style={{ width: '100%', height }}>
+      <ResponsiveContainer width="100%" height="100%">
+        <BarChart data={data} margin={{ top: 8, right: 8, bottom: 0, left: 0 }}>
+          <CartesianGrid vertical={false} strokeOpacity={0.3} />
+          <XAxis dataKey="label" tick={{ fontSize: 12 }} interval="preserveStartEnd" />
+          <YAxis tick={{ fontSize: 12 }} width={44} />
+          <Tooltip formatter={(v) => [String(v), unit]} />
+          <Bar dataKey="value" fill={SERIES_COLORS[0]} radius={[3, 3, 0, 0]} isAnimationActive={false} />
+        </BarChart>
+      </ResponsiveContainer>
+    </div>
+  )
+}

package/src/components/charts/index.ts

@@ -1,6 +1,8 @@
 // Charts live behind their own subpath (`@startsimpli/ui/charts`) so recharts
 // is only bundled by apps that draw one.
 export { TimeSeriesChart, SERIES_COLORS, SERIES_DASHES, seriesStroke } from './TimeSeriesChart'
+export { PeriodBars } from './PeriodBars'
+export type { PeriodBarsProps, PeriodBarsDatum } from './PeriodBars'
 export type { TimeSeriesChartProps, TimeSeriesReferenceLine } from './TimeSeriesChart'
 export type {
   TimeSeries,

package/src/components/index.ts

@@ -120,6 +120,9 @@ export * from './email-dialogs'
 // Dashboard components (MetricCard, PeriodSelector, SparklineTrend, DashboardGrid, DashboardSection)
 export * from './dashboard'
 
+// Period reports (PeriodReport, ExportButtons) - grouped table + totals, caller owns data and export
+export * from './reports'
+
 // SystemHealth blocks (HealthCard, PipelineHealth, SourceFreshness, DeliveryHealth, AttentionFeed)
 export * from './health'
 

package/src/components/reports/ExportButtons.tsx

@@ -0,0 +1,28 @@
+'use client'
+
+import * as React from 'react'
+import { Button } from '../ui/button'
+
+export type ReportExportFormat = 'csv' | 'xlsx'
+
+export interface ExportButtonsProps {
+  onExport: (format: ReportExportFormat) => void
+  /** Disables both while a file is being built. */
+  busy?: boolean
+  formats?: ReportExportFormat[]
+}
+
+const LABEL: Record<ReportExportFormat, string> = { csv: 'Export CSV', xlsx: 'Export Excel' }
+
+/** One button per format. The caller builds and saves the file. */
+export function ExportButtons({ onExport, busy, formats = ['csv', 'xlsx'] }: ExportButtonsProps) {
+  return (
+    <>
+      {formats.map((f) => (
+        <Button key={f} type="button" variant="outline" size="sm" disabled={busy} onClick={() => onExport(f)}>
+          {LABEL[f]}
+        </Button>
+      ))}
+    </>
+  )
+}

package/src/components/reports/PeriodReport.tsx

@@ -0,0 +1,124 @@
+'use client'
+
+import * as React from 'react'
+import { cn } from '../../lib/utils'
+import { PeriodSelector, type PeriodOption } from '../dashboard/PeriodSelector'
+
+export interface PeriodReportColumn<R> {
+  key: string
+  label: string
+  numeric?: boolean
+  render: (row: R) => React.ReactNode
+}
+
+export interface PeriodReportProps<R extends { key: string }> {
+  groupBy: string
+  groupOptions: PeriodOption[]
+  onGroupByChange: (value: string) => void
+  rows: R[]
+  /** Rendered as the last row. Derived by the caller from the same data as `rows`. */
+  totals: R
+  columns: PeriodReportColumn<R>[]
+  /** Headline figures above the table (hours, earnings, entries...), pre-formatted. */
+  totalsBar: { label: string; value: React.ReactNode }[]
+  /** Filters and search, wired by the caller. */
+  toolbar?: React.ReactNode
+  /** Export buttons and the like. */
+  actions?: React.ReactNode
+  /** A chart of `rows`; a slot so this file never pulls in a chart library. */
+  chart?: React.ReactNode
+  loading?: boolean
+  emptyMessage?: string
+  className?: string
+}
+
+/**
+ * A report grouped by period: a toolbar, a totals bar, a chart slot and one
+ * table row per period plus a totals row. Presentational - the caller owns the
+ * data, the filters and the export, so the screen and the file are built from
+ * the same rows.
+ */
+export function PeriodReport<R extends { key: string }>({
+  groupBy,
+  groupOptions,
+  onGroupByChange,
+  rows,
+  totals,
+  columns,
+  totalsBar,
+  toolbar,
+  actions,
+  chart,
+  loading,
+  emptyMessage = 'No entries match these filters.',
+  className,
+}: PeriodReportProps<R>) {
+  const cell = (c: PeriodReportColumn<R>) =>
+    cn('px-3 py-2 text-sm', c.numeric ? 'text-right tabular-nums' : 'text-left')
+
+  return (
+    <div className={cn('space-y-4', className)}>
+      <div className="flex flex-wrap items-center gap-3">
+        <PeriodSelector periods={groupOptions} selected={groupBy} onChange={onGroupByChange} />
+        {toolbar}
+        {actions ? <div className="ml-auto flex items-center gap-2">{actions}</div> : null}
+      </div>
+
+      <div data-testid="report-totals" className="grid grid-cols-2 gap-3 sm:grid-cols-4">
+        {totalsBar.map((t) => (
+          <div key={t.label} className="rounded-lg border border-gray-200 bg-white p-3">
+            <div className="text-xs uppercase tracking-wide text-gray-500">{t.label}</div>
+            <div className="mt-1 text-2xl font-semibold tabular-nums text-gray-900">{t.value}</div>
+          </div>
+        ))}
+      </div>
+
+      {loading ? (
+        <p className="text-sm text-gray-500" role="status">
+          Loading report
+        </p>
+      ) : (
+        <>
+          {chart && rows.length > 0 ? <div>{chart}</div> : null}
+          {rows.length === 0 ? (
+            <p className="text-sm text-gray-500">{emptyMessage}</p>
+          ) : (
+            <div className="overflow-auto rounded-lg border border-gray-200 bg-white">
+              <table className="w-full">
+                <thead className="bg-gray-50">
+                  <tr>
+                    {columns.map((c) => (
+                      <th key={c.key} className={cn(cell(c), 'font-medium text-gray-600')}>
+                        {c.label}
+                      </th>
+                    ))}
+                  </tr>
+                </thead>
+                <tbody>
+                  {rows.map((r) => (
+                    <tr key={r.key} className="border-t border-gray-100">
+                      {columns.map((c) => (
+                        <td key={c.key} className={cell(c)}>
+                          {c.render(r)}
+                        </td>
+                      ))}
+                    </tr>
+                  ))}
+                </tbody>
+                <tfoot>
+                  <tr data-testid="report-total-row" className="border-t-2 border-gray-300 bg-gray-50 font-semibold">
+                    {columns.map((c, i) => (
+                      <td key={c.key} className={cell(c)}>
+                        {i === 0 ? 'Total' : c.render(totals)}
+                      </td>
+                    ))}
+                  </tr>
+                </tfoot>
+              </table>
+            </div>
+          )}
+        </>
+      )}
+    </div>
+  )
+}

package/src/components/reports/__tests__/PeriodReport.test.tsx

@@ -0,0 +1,75 @@
+import { render, screen, fireEvent, within } from '@testing-library/react'
+import { PeriodReport, type PeriodReportColumn } from '../PeriodReport'
+import { ExportButtons } from '../ExportButtons'
+
+interface Row { key: string; entries: number; hours: number }
+const rows: Row[] = [
+  { key: '2026-07', entries: 3, hours: 4.25 },
+  { key: '2026-08', entries: 1, hours: 1 },
+]
+const totals: Row = { key: 'total', entries: 4, hours: 5.25 }
+const columns: PeriodReportColumn<Row>[] = [
+  { key: 'key', label: 'Period', render: (r) => r.key },
+  { key: 'entries', label: 'Entries', numeric: true, render: (r) => String(r.entries) },
+  { key: 'hours', label: 'Hours', numeric: true, render: (r) => r.hours.toFixed(2) },
+]
+const base = {
+  groupBy: 'month',
+  groupOptions: [
+    { value: 'day', label: 'Day' },
+    { value: 'month', label: 'Month' },
+  ],
+  onGroupByChange: () => {},
+  rows,
+  totals,
+  columns,
+  totalsBar: [{ label: 'Hours', value: '5.25' }, { label: 'Entries', value: '4' }],
+}
+
+describe('PeriodReport', () => {
+  it('shows a totals bar, one row per period and a totals row', () => {
+    render(<PeriodReport {...base} />)
+    expect(screen.getByTestId('report-totals')).toHaveTextContent('5.25')
+    expect(screen.getAllByRole('row')).toHaveLength(1 + 2 + 1)
+    const foot = screen.getByTestId('report-total-row')
+    expect(within(foot).getByText('5.25')).toBeInTheDocument()
+  })
+
+  it('reports a grouping change', () => {
+    const onGroupByChange = jest.fn()
+    render(<PeriodReport {...base} onGroupByChange={onGroupByChange} />)
+    fireEvent.click(screen.getByRole('button', { name: 'Day' }))
+    expect(onGroupByChange).toHaveBeenCalledWith('day')
+    expect(screen.getByRole('button', { name: 'Month' })).toHaveAttribute('aria-pressed', 'true')
+  })
+
+  it('renders toolbar, actions and chart slots, and an empty state', () => {
+    const { rerender } = render(
+      <PeriodReport {...base} toolbar={<span>filters</span>} actions={<span>export</span>} chart={<div>chart</div>} />,
+    )
+    expect(screen.getByText('filters')).toBeInTheDocument()
+    expect(screen.getByText('export')).toBeInTheDocument()
+    expect(screen.getByText('chart')).toBeInTheDocument()
+    rerender(<PeriodReport {...base} rows={[]} chart={<div>chart</div>} emptyMessage="Nothing here" />)
+    expect(screen.getByText('Nothing here')).toBeInTheDocument()
+    expect(screen.queryByText('chart')).toBeNull()
+  })
+
+  it('shows a loading state instead of stale rows', () => {
+    render(<PeriodReport {...base} loading />)
+    expect(screen.getByText('Loading report')).toBeInTheDocument()
+    expect(screen.queryByTestId('report-total-row')).toBeNull()
+  })
+})
+
+describe('ExportButtons', () => {
+  it('calls back with the chosen format and disables while busy', () => {
+    const onExport = jest.fn()
+    const { rerender } = render(<ExportButtons onExport={onExport} />)
+    fireEvent.click(screen.getByRole('button', { name: /CSV/ }))
+    fireEvent.click(screen.getByRole('button', { name: /Excel/ }))
+    expect(onExport.mock.calls).toEqual([['csv'], ['xlsx']])
+    rerender(<ExportButtons onExport={onExport} busy />)
+    expect(screen.getByRole('button', { name: /CSV/ })).toBeDisabled()
+  })
+})

package/src/components/reports/index.ts

@@ -0,0 +1,4 @@
+export { PeriodReport } from './PeriodReport'
+export type { PeriodReportProps, PeriodReportColumn } from './PeriodReport'
+export { ExportButtons } from './ExportButtons'
+export type { ExportButtonsProps, ReportExportFormat } from './ExportButtons'

package/src/components/timer/ColorPicker.tsx

@@ -0,0 +1,43 @@
+'use client'
+
+/** Presets, all `#rrggbb` so they satisfy a 6-digit-hex colour attribute. */
+export const PROJECT_COLORS = [
+  '#3366ff',
+  '#0ea5e9',
+  '#14b8a6',
+  '#22c55e',
+  '#eab308',
+  '#f97316',
+  '#e11d48',
+  '#a855f7',
+  '#64748b',
+] as const
+
+export interface ColorPickerProps {
+  value: string | null | undefined
+  onChange: (color: string) => void
+  colors?: readonly string[]
+  label?: string
+}
+
+export function ColorPicker({ value, onChange, colors = PROJECT_COLORS, label = 'Colour' }: ColorPickerProps) {
+  return (
+    <div role="radiogroup" aria-label={label} className="flex flex-wrap gap-2">
+      {colors.map((c) => {
+        const checked = value?.toLowerCase() === c.toLowerCase()
+        return (
+          <button
+            key={c}
+            type="button"
+            role="radio"
+            aria-checked={checked}
+            aria-label={c}
+            onClick={() => onChange(c)}
+            className={`h-6 w-6 rounded-full border-2 ${checked ? 'border-gray-900' : 'border-transparent'} focus:outline-none focus:ring-2 focus:ring-indigo-500`}
+            style={{ backgroundColor: c }}
+          />
+        )
+      })}
+    </div>
+  )
+}

package/src/components/timer/EntryFormDialog.tsx

@@ -0,0 +1,104 @@
+'use client'
+
+import { useEffect, useState } from 'react'
+import { BaseDialog } from '../dialog/BaseDialog'
+import { Button } from '../ui/button'
+import { fromLocalInput, toLocalInput, validateRange, type EntryId, type NewEntry } from './interval-logic'
+import { ProjectSelect, type ProjectOption } from './ProjectSelect'
+
+export interface EntryFormValue {
+  startedAt: string
+  endedAt: string | null
+  projectId: EntryId | null
+  note: string
+}
+
+export interface EntryFormDialogProps {
+  open: boolean
+  mode: 'add' | 'edit'
+  projects: ProjectOption[]
+  busy: boolean
+  initial?: Partial<EntryFormValue>
+  onSubmit: (value: EntryFormValue & NewEntry) => void
+  onDelete?: () => void
+  onClose: () => void
+}
+
+/** Manual entry and edit share one form. Times are local datetimes, stored as UTC ISO. */
+export function EntryFormDialog(p: EntryFormDialogProps) {
+  const [start, setStart] = useState('')
+  const [end, setEnd] = useState('')
+  const [projectId, setProjectId] = useState<EntryId | null>(null)
+  const [note, setNote] = useState('')
+  const [problem, setProblem] = useState<string | null>(null)
+
+  useEffect(() => {
+    if (!p.open) return
+    setStart(p.initial?.startedAt ? toLocalInput(p.initial.startedAt) : '')
+    setEnd(p.initial?.endedAt ? toLocalInput(p.initial.endedAt) : '')
+    setProjectId(p.initial?.projectId ?? null)
+    setNote(p.initial?.note ?? '')
+    setProblem(null)
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [p.open])
+
+  function submit(e: React.FormEvent) {
+    e.preventDefault()
+    const startedAt = fromLocalInput(start)
+    const endedAt = fromLocalInput(end)
+    const bad = validateRange(startedAt, endedAt)
+    if (bad) return setProblem(bad)
+    if (p.mode === 'add' && !endedAt) return setProblem('Enter an end time, or use the timer.')
+    setProblem(null)
+    p.onSubmit({ startedAt: startedAt!, endedAt, projectId, note })
+  }
+
+  const field = 'h-9 w-full rounded-md border border-gray-300 px-2 text-sm'
+  return (
+    <BaseDialog open={p.open} onOpenChange={(o) => !o && p.onClose()} size="md" loading={p.busy}>
+      <form onSubmit={submit}>
+        <BaseDialog.Header>
+          <BaseDialog.Title>{p.mode === 'add' ? 'Add time' : 'Edit entry'}</BaseDialog.Title>
+        </BaseDialog.Header>
+        <BaseDialog.Body>
+          <div className="space-y-3">
+            <label className="block text-sm">
+              <span className="mb-1 block text-gray-700">Start</span>
+              <input aria-label="Start" type="datetime-local" value={start} onChange={(e) => setStart(e.target.value)} className={field} />
+            </label>
+            <label className="block text-sm">
+              <span className="mb-1 block text-gray-700">End</span>
+              <input aria-label="End" type="datetime-local" value={end} onChange={(e) => setEnd(e.target.value)} className={field} />
+            </label>
+            <div className="text-sm">
+              <span className="mb-1 block text-gray-700">Project</span>
+              <ProjectSelect projects={p.projects} value={projectId} onChange={setProjectId} />
+            </div>
+            <label className="block text-sm">
+              <span className="mb-1 block text-gray-700">Note</span>
+              <input aria-label="Note" value={note} onChange={(e) => setNote(e.target.value)} className={field} />
+            </label>
+            {problem ? (
+              <p role="alert" className="text-sm text-red-600">
+                {problem}
+              </p>
+            ) : null}
+          </div>
+        </BaseDialog.Body>
+        <BaseDialog.Footer>
+          {p.mode === 'edit' && p.onDelete ? (
+            <Button type="button" variant="outline" disabled={p.busy} onClick={p.onDelete}>
+              Delete
+            </Button>
+          ) : null}
+          <Button type="button" variant="outline" disabled={p.busy} onClick={p.onClose}>
+            Cancel
+          </Button>
+          <Button type="submit" disabled={p.busy}>
+            {p.mode === 'add' ? 'Add entry' : 'Save'}
+          </Button>
+        </BaseDialog.Footer>
+      </form>
+    </BaseDialog>
+  )
+}

package/src/components/timer/EntryList.tsx

@@ -0,0 +1,42 @@
+'use client'
+
+import { elapsedMs, formatElapsed, type TimedEntry } from './interval-logic'
+import { ProjectSwatch } from './ProjectSwatch'
+import type { ProjectOption } from './ProjectSelect'
+
+export interface EntryListProps {
+  entries: TimedEntry[]
+  projects: ProjectOption[]
+  onEdit: (entry: TimedEntry) => void
+}
+
+const clock = (iso: string) => new Date(iso).toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' })
+
+/** Closed intervals, newest first as given. Duration is end minus start; rounding is a report concern. */
+export function EntryList({ entries, projects, onEdit }: EntryListProps) {
+  if (entries.length === 0) return <p className="text-sm text-gray-500">No entries yet.</p>
+  return (
+    <ul className="divide-y divide-gray-100 rounded-lg border border-gray-200 bg-white">
+      {entries.map((e) => {
+        const project = projects.find((p) => String(p.id) === String(e.projectId ?? ''))
+        const end = e.endedAt ? new Date(e.endedAt).getTime() : Date.now()
+        return (
+          <li key={String(e.id)} className="flex items-center gap-3 px-4 py-2 text-sm">
+            <ProjectSwatch color={project?.color} />
+            <span className="w-32 truncate font-medium text-gray-900">{project?.name ?? 'No project'}</span>
+            <span className="flex-1 truncate text-gray-600">{e.note}</span>
+            <span className="text-gray-500">
+              {clock(e.startedAt)} to {e.endedAt ? clock(e.endedAt) : 'now'}
+            </span>
+            <span className="w-16 text-right font-mono tabular-nums text-gray-900">
+              {formatElapsed(end - new Date(e.startedAt).getTime())}
+            </span>
+            <button type="button" className="text-indigo-600 hover:underline" aria-label={`Edit entry ${e.note || ''}`.trim()} onClick={() => onEdit(e)}>
+              Edit
+            </button>
+          </li>
+        )
+      })}
+    </ul>
+  )
+}

package/src/components/timer/IdlePromptDialog.tsx

@@ -0,0 +1,65 @@
+'use client'
+
+import { useState } from 'react'
+import { BaseDialog } from '../dialog/BaseDialog'
+import { Button } from '../ui/button'
+import type { EntryId } from './interval-logic'
+import { ProjectSelect, type ProjectOption } from './ProjectSelect'
+
+export interface IdlePromptDialogProps {
+  open: boolean
+  seconds: number
+  projects: ProjectOption[]
+  currentProjectId: EntryId | null
+  busy: boolean
+  onKeep: () => void
+  onDiscard: () => void
+  onAssign: (projectId: EntryId) => void
+}
+
+export function formatIdle(seconds: number): string {
+  const min = Math.max(1, Math.round(seconds / 60))
+  if (min < 60) return `${min} min`
+  const h = Math.floor(min / 60)
+  const m = min % 60
+  return m === 0 ? `${h} h` : `${h} h ${m} min`
+}
+
+/** On return from idle: keep the time, discard it, or book it to another project. */
+export function IdlePromptDialog(p: IdlePromptDialogProps) {
+  const other = p.projects.find((x) => String(x.id) !== String(p.currentProjectId ?? ''))
+  const [target, setTarget] = useState<EntryId | null>(null)
+  const chosen = target ?? other?.id ?? null
+  return (
+    <BaseDialog open={p.open} onOpenChange={(o) => !o && !p.busy && p.onKeep()} size="md" loading={p.busy}>
+      <BaseDialog.Header>
+        <BaseDialog.Title>You were away</BaseDialog.Title>
+      </BaseDialog.Header>
+      <BaseDialog.Body>
+        <p className="text-sm text-gray-700">
+          The timer kept running while you were idle for {formatIdle(p.seconds)}. What should happen to that time?
+        </p>
+        <div className="mt-4 flex items-center gap-2">
+          <ProjectSelect
+            label="Assign to"
+            projects={p.projects.filter((x) => String(x.id) !== String(p.currentProjectId ?? ''))}
+            value={chosen}
+            onChange={setTarget}
+            noneLabel="Choose a project"
+          />
+          <Button variant="outline" disabled={p.busy || chosen === null} onClick={() => chosen !== null && p.onAssign(chosen)}>
+            Assign
+          </Button>
+        </div>
+      </BaseDialog.Body>
+      <BaseDialog.Footer>
+        <Button variant="outline" disabled={p.busy} onClick={p.onDiscard}>
+          Discard
+        </Button>
+        <Button disabled={p.busy} onClick={p.onKeep}>
+          Keep
+        </Button>
+      </BaseDialog.Footer>
+    </BaseDialog>
+  )
+}

package/src/components/timer/ProjectSelect.tsx

@@ -0,0 +1,52 @@
+'use client'
+
+import { ProjectSwatch } from './ProjectSwatch'
+import type { EntryId } from './interval-logic'
+
+export interface ProjectOption {
+  id: EntryId
+  name: string
+  color?: string | null
+  /** The client this project bills to, when the host models clients. */
+  clientId?: EntryId | null
+  /** Per-hour rate new time on this project defaults to. */
+  defaultRate?: number | null
+  /** Store-owned passthrough (the record's other attributes), so a whole-record update can send them back. */
+  extra?: Record<string, unknown>
+}
+
+export interface ProjectSelectProps {
+  projects: ProjectOption[]
+  value: EntryId | null | undefined
+  onChange: (id: EntryId | null) => void
+  label?: string
+  id?: string
+  noneLabel?: string
+}
+
+/** A native select (reliable in every shell) with the chosen project's colour beside it. */
+export function ProjectSelect({ projects, value, onChange, label = 'Project', id, noneLabel = 'No project' }: ProjectSelectProps) {
+  const chosen = projects.find((p) => String(p.id) === String(value ?? ''))
+  return (
+    <span className="inline-flex items-center gap-2">
+      <ProjectSwatch color={chosen?.color} />
+      <select
+        id={id}
+        aria-label={label}
+        value={value == null ? '' : String(value)}
+        onChange={(e) => {
+          const v = e.target.value
+          onChange(v === '' ? null : (projects.find((p) => String(p.id) === v)?.id ?? v))
+        }}
+        className="h-9 rounded-md border border-gray-300 bg-white px-2 text-sm"
+      >
+        <option value="">{noneLabel}</option>
+        {projects.map((p) => (
+          <option key={String(p.id)} value={String(p.id)}>
+            {p.name}
+          </option>
+        ))}
+      </select>
+    </span>
+  )
+}

package/src/components/timer/ProjectSwatch.tsx

@@ -0,0 +1,15 @@
+'use client'
+
+export const NO_COLOR = '#9ca3af'
+
+/** A project's colour as a dot. Decorative: the project name always sits beside it. */
+export function ProjectSwatch({ color, size = 10 }: { color?: string | null; size?: number }) {
+  return (
+    <span
+      data-testid="swatch"
+      aria-hidden="true"
+      className="inline-block shrink-0 rounded-full"
+      style={{ backgroundColor: color || NO_COLOR, width: size, height: size }}
+    />
+  )
+}