@open-mercato/core 0.7.1-develop.7178.1.ab93fbaf4e → 0.7.1-develop.7180.1.9717fbbb43

package/src/modules/staff/lib/time-tracking-ui/timeEntryDialogState.ts

@@ -0,0 +1,400 @@
+import {
+  deriveInterval,
+  formatClock,
+  parseClock,
+  type ComputedIntervalField,
+  type IntervalInput,
+} from '../time-tracking/interval'
+
+export type IntervalField = 'start' | 'end' | 'duration'
+
+/**
+ * The 2-of-3 state of screen 8. It keeps the three fields as the user left them
+ * plus the answer `deriveInterval` gave for the third one, so the badge and the
+ * hint can be read straight off the state instead of being recomputed in the
+ * render path.
+ */
+export type TimeIntervalState = {
+  /** Raw clock text, so half-typed input (`15:1`) is never rewritten. */
+  startText: string
+  endText: string
+  durationMinutes: number | null
+  /** `DurationInput` said the text does not parse — Save is blocked on this. */
+  durationInvalid: boolean
+  computed: ComputedIntervalField
+  crossesMidnight: boolean
+  /**
+   * Bumped only when the *derived* duration changes. The dialog uses it as the
+   * `key` of `DurationInput`, so a machine-filled duration re-renders while the
+   * text the user is typing there is left alone.
+   */
+  durationEpoch: number
+  lastEdited: IntervalField | null
+}
+
+export type TimeIntervalEdit =
+  | { field: 'start'; value: string }
+  | { field: 'end'; value: string }
+  | { field: 'duration'; minutes: number | null; invalid: boolean }
+  /** "Snap start to 13:30" — moves the start and keeps the duration. */
+  | { field: 'snapStart'; value: string }
+
+type RawInterval = {
+  startText: string
+  endText: string
+  durationMinutes: number | null
+}
+
+/**
+ * Which field yields when all three are filled. `start` is the anchor a person
+ * thinks in, so editing the end restates the duration (screen 8 note 1) rather
+ * than sliding the start backwards.
+ */
+const ANCHOR_PRIORITY: readonly IntervalField[] = ['start', 'end', 'duration']
+
+function hasValue(raw: RawInterval, field: IntervalField): boolean {
+  if (field === 'duration') return raw.durationMinutes !== null
+  return parseClock(field === 'start' ? raw.startText : raw.endText) !== null
+}
+
+function chooseAnchors(raw: RawInterval, lastEdited: IntervalField | null): IntervalField[] {
+  const present = ANCHOR_PRIORITY.filter((field) => hasValue(raw, field))
+  if (present.length <= 2) return present
+  if (!lastEdited) return present.slice(0, 2)
+  const second = ANCHOR_PRIORITY.find((field) => field !== lastEdited && hasValue(raw, field))
+  return second ? [lastEdited, second] : [lastEdited]
+}
+
+function buildInput(raw: RawInterval, anchors: readonly IntervalField[]): IntervalInput {
+  const input: IntervalInput = {}
+  if (anchors.includes('start')) input.start = raw.startText
+  if (anchors.includes('end')) input.end = raw.endText
+  // With both clocks anchored the duration is still handed over: `deriveInterval`
+  // then answers `computed: null` for values that already agree, which is what
+  // keeps a freshly loaded entry from opening with a spurious badge.
+  if (anchors.includes('duration') || (anchors.includes('start') && anchors.includes('end'))) {
+    input.durationMinutes = raw.durationMinutes
+  }
+  return input
+}
+
+function applyDerivation(
+  raw: RawInterval,
+  previous: TimeIntervalState,
+  lastEdited: IntervalField | null,
+  anchors: readonly IntervalField[],
+): TimeIntervalState {
+  const derived = deriveInterval(buildInput(raw, anchors))
+  const durationMinutes = derived.computed === 'duration' ? derived.durationMinutes : raw.durationMinutes
+  const durationChanged = derived.computed === 'duration' && durationMinutes !== previous.durationMinutes
+  return {
+    startText: derived.computed === 'start' && derived.start ? derived.start : raw.startText,
+    endText: derived.computed === 'end' && derived.end ? derived.end : raw.endText,
+    durationMinutes,
+    durationInvalid: derived.computed === 'duration' ? false : previous.durationInvalid,
+    computed: derived.computed,
+    crossesMidnight: derived.crossesMidnight,
+    durationEpoch: durationChanged ? previous.durationEpoch + 1 : previous.durationEpoch,
+    lastEdited,
+  }
+}
+
+const EMPTY_STATE: TimeIntervalState = {
+  startText: '',
+  endText: '',
+  durationMinutes: null,
+  durationInvalid: false,
+  computed: null,
+  crossesMidnight: false,
+  durationEpoch: 0,
+  lastEdited: null,
+}
+
+export function createIntervalState(seed: {
+  start?: string | null
+  end?: string | null
+  durationMinutes?: number | null
+}): TimeIntervalState {
+  const raw: RawInterval = {
+    startText: seed.start ?? '',
+    endText: seed.end ?? '',
+    durationMinutes: seed.durationMinutes ?? null,
+  }
+  return applyDerivation(raw, EMPTY_STATE, null, chooseAnchors(raw, null))
+}
+
+/**
+ * Re-seeds the three fields for a different entry — or for the next one after
+ * "save and add another" — and always advances `durationEpoch`, so the duration
+ * field remounts and drops whatever text was left in it.
+ */
+export function resetIntervalState(
+  previous: TimeIntervalState,
+  seed: { start?: string | null; end?: string | null; durationMinutes?: number | null },
+): TimeIntervalState {
+  const next = createIntervalState(seed)
+  return { ...next, durationEpoch: previous.durationEpoch + 1 }
+}
+
+export function reduceIntervalState(state: TimeIntervalState, edit: TimeIntervalEdit): TimeIntervalState {
+  if (edit.field === 'snapStart') {
+    const raw: RawInterval = { ...toRaw(state), startText: edit.value }
+    // The suggestion moves the start and keeps the length of the work, so the
+    // end is the field that follows — never the duration the user already typed.
+    const anchors: IntervalField[] = raw.durationMinutes !== null ? ['start', 'duration'] : ['start', 'end']
+    return applyDerivation(raw, state, 'start', anchors)
+  }
+  if (edit.field === 'duration') {
+    const raw: RawInterval = { ...toRaw(state), durationMinutes: edit.minutes }
+    const next = applyDerivation(raw, state, 'duration', chooseAnchors(raw, 'duration'))
+    return { ...next, durationInvalid: edit.invalid }
+  }
+  const raw: RawInterval =
+    edit.field === 'start'
+      ? { ...toRaw(state), startText: edit.value }
+      : { ...toRaw(state), endText: edit.value }
+  return applyDerivation(raw, state, edit.field, chooseAnchors(raw, edit.field))
+}
+
+function toRaw(state: TimeIntervalState): RawInterval {
+  return { startText: state.startText, endText: state.endText, durationMinutes: state.durationMinutes }
+}
+
+const DATE_PATTERN = /^(\d{4})-(\d{2})-(\d{2})$/
+
+export function shiftIsoDate(date: string, days: number): string {
+  const match = DATE_PATTERN.exec(date)
+  if (!match) return date
+  const shifted = new Date(Date.UTC(Number(match[1]), Number(match[2]) - 1, Number(match[3]) + days))
+  const month = String(shifted.getUTCMonth() + 1).padStart(2, '0')
+  const day = String(shifted.getUTCDate()).padStart(2, '0')
+  return `${shifted.getUTCFullYear()}-${month}-${day}`
+}
+
+export function todayIsoDate(now: Date = new Date()): string {
+  const month = String(now.getMonth() + 1).padStart(2, '0')
+  const day = String(now.getDate()).padStart(2, '0')
+  return `${now.getFullYear()}-${month}-${day}`
+}
+
+/**
+ * Wall clock plus calendar day into the instant the API stores. `plusDays` is 1
+ * for the end of an entry that crosses midnight (D-8): the work started on
+ * `date` and finished the following calendar day.
+ */
+export function combineDateAndClock(date: string, clock: string, plusDays = 0): string | null {
+  const match = DATE_PATTERN.exec(date)
+  const minutesOfDay = parseClock(clock)
+  if (!match || minutesOfDay === null) return null
+  const composed = new Date(
+    Number(match[1]),
+    Number(match[2]) - 1,
+    Number(match[3]) + plusDays,
+    Math.floor(minutesOfDay / 60),
+    minutesOfDay % 60,
+    0,
+    0,
+  )
+  if (Number.isNaN(composed.getTime())) return null
+  return composed.toISOString()
+}
+
+/** Accepts the wall clock the form sends and the timestamp the timer persists. */
+export function clockFromApiValue(value: unknown): string {
+  if (typeof value !== 'string' || value.trim().length === 0) return ''
+  const trimmed = value.trim()
+  const direct = parseClock(trimmed)
+  if (direct !== null) return formatClock(direct)
+  const parsed = new Date(trimmed)
+  if (Number.isNaN(parsed.getTime())) return ''
+  return formatClock(parsed.getHours() * 60 + parsed.getMinutes())
+}
+
+export function dateFromApiValue(value: unknown): string {
+  if (typeof value !== 'string' || value.trim().length === 0) return ''
+  const match = /^(\d{4}-\d{2}-\d{2})/.exec(value.trim())
+  if (match) return match[1]
+  const parsed = new Date(value)
+  if (Number.isNaN(parsed.getTime())) return ''
+  return todayIsoDate(parsed)
+}
+
+export type TimeEntryRecord = {
+  id: string
+  date: string
+  startText: string
+  endText: string
+  durationMinutes: number | null
+  description: string
+  taskId: string | null
+  timeProjectId: string | null
+  isBillable: boolean
+  rateOverrideAmount: number | null
+  currencyCode: string | null
+  tagIds: string[]
+  isLocked: boolean
+  lockedReportId: string | null
+  updatedAt: string | null
+}
+
+export type ApiRow = Record<string, unknown>
+
+export function readRowString(row: ApiRow, ...keys: string[]): string | null {
+  for (const key of keys) {
+    const value = row[key]
+    if (typeof value === 'string' && value.trim().length > 0) return value
+  }
+  return null
+}
+
+export function readRowNumber(row: ApiRow, ...keys: string[]): number | null {
+  for (const key of keys) {
+    const value = row[key]
+    if (typeof value === 'number' && Number.isFinite(value)) return value
+    if (typeof value === 'string' && value.trim().length > 0) {
+      const parsed = Number(value)
+      if (Number.isFinite(parsed)) return parsed
+    }
+  }
+  return null
+}
+
+export function readRowBoolean(row: ApiRow, fallback: boolean, ...keys: string[]): boolean {
+  for (const key of keys) {
+    const value = row[key]
+    if (typeof value === 'boolean') return value
+  }
+  return fallback
+}
+
+export function readRowItems(payload: unknown): ApiRow[] {
+  const items = (payload as { items?: unknown } | null)?.items
+  return Array.isArray(items) ? (items.filter((item) => !!item && typeof item === 'object') as ApiRow[]) : []
+}
+
+export function toTimeEntryRecord(row: ApiRow): TimeEntryRecord | null {
+  const id = readRowString(row, 'id')
+  if (!id) return null
+  const tags = Array.isArray(row.tags) ? row.tags : []
+  return {
+    id,
+    date: dateFromApiValue(readRowString(row, 'date')),
+    startText: clockFromApiValue(readRowString(row, 'started_at', 'startedAt')),
+    endText: clockFromApiValue(readRowString(row, 'ended_at', 'endedAt')),
+    durationMinutes: readRowNumber(row, 'duration_minutes', 'durationMinutes'),
+    description: readRowString(row, 'description', 'notes') ?? '',
+    taskId: readRowString(row, 'task_id', 'taskId'),
+    timeProjectId: readRowString(row, 'time_project_id', 'timeProjectId'),
+    isBillable: readRowBoolean(row, true, 'is_billable', 'isBillable'),
+    rateOverrideAmount: readRowNumber(row, 'rate_override_amount', 'rateOverrideAmount'),
+    currencyCode: readRowString(row, 'currencyCode', 'rate_currency_code', 'rateCurrencyCode'),
+    tagIds: tags
+      .map((tag) => (tag && typeof tag === 'object' ? readRowString(tag as ApiRow, 'id') : null))
+      .filter((value): value is string => value !== null),
+    isLocked: readRowBoolean(row, false, 'isLocked', 'is_locked'),
+    lockedReportId: readRowString(row, 'lockedReportId', 'locked_report_id'),
+    updatedAt: readRowString(row, 'updated_at', 'updatedAt'),
+  }
+}
+
+export type TaskOption = {
+  id: string
+  title: string
+  /** `<project code>-<n>` — frozen at creation, quoted in reports. */
+  reference: string | null
+  timeProjectId: string | null
+  /** Drives the picker's status dot. */
+  taskStatusId: string | null
+  /** Inclusive rollup from the tasks enricher; shown as context, never edited. */
+  loggedMinutes: number | null
+}
+
+export type TagOption = {
+  id: string
+  label: string
+  /** A `PROJECT_COLOR_KEYS` key, resolved to a hex at render time. */
+  color: string | null
+}
+
+export type ProjectOption = {
+  id: string
+  name: string
+  customerName: string | null
+  hourlyRate: number | null
+  currencyCode: string | null
+  billableByDefault: boolean | null
+}
+
+export function toTaskOption(row: ApiRow): TaskOption | null {
+  const id = readRowString(row, 'id')
+  const title = readRowString(row, 'title')
+  if (!id || !title) return null
+  const logged = row.loggedMinutes ?? row.logged_minutes
+  return {
+    id,
+    title,
+    reference: readRowString(row, 'reference'),
+    timeProjectId: readRowString(row, 'time_project_id', 'timeProjectId'),
+    taskStatusId: readRowString(row, 'task_status_id', 'taskStatusId'),
+    loggedMinutes: typeof logged === 'number' ? logged : null,
+  }
+}
+
+export function toProjectOption(row: ApiRow): ProjectOption | null {
+  const id = readRowString(row, 'id')
+  if (!id) return null
+  const snapshot = row.customer_snapshot ?? row.customerSnapshot
+  const customerName =
+    snapshot && typeof snapshot === 'object' ? readRowString(snapshot as ApiRow, 'name', 'displayName') : null
+  return {
+    id,
+    name: readRowString(row, 'name') ?? id,
+    customerName,
+    hourlyRate: readRowNumber(row, 'hourly_rate', 'hourlyRate'),
+    currencyCode: readRowString(row, 'currency_code', 'currencyCode'),
+    billableByDefault:
+      typeof row.billable_by_default === 'boolean'
+        ? row.billable_by_default
+        : typeof row.billableByDefault === 'boolean'
+          ? row.billableByDefault
+          : null,
+  }
+}
+
+/** `Migracja koszyka B2B — Nordvik — migracja B2B` (screen 8's task option). */
+/**
+ * The reference leads, because it is what people actually say to each other about
+ * a task ("I put two hours on APOLLO-14") and what a client-facing report quotes.
+ * A list keyed on the title alone makes the picker unusable the moment two
+ * projects both have a "Consulting / workshops".
+ */
+export function describeTaskOption(task: TaskOption, project: ProjectOption | null | undefined): string {
+  const label = [task.title, project?.customerName ?? null, project?.name ?? null]
+    .filter((part): part is string => !!part && part.trim().length > 0)
+    .join(' — ')
+  return task.reference ? `${task.reference} · ${label}` : label
+}
+
+export type OverlapEntry = {
+  id: string
+  startText: string
+  endText: string
+  durationMinutes: number
+  taskTitle: string | null
+  projectName: string | null
+  description: string | null
+}
+
+export function toOverlapEntry(row: ApiRow): OverlapEntry | null {
+  const id = readRowString(row, 'id')
+  if (!id) return null
+  return {
+    id,
+    startText: clockFromApiValue(readRowString(row, 'started_at', 'startedAt')),
+    endText: clockFromApiValue(readRowString(row, 'ended_at', 'endedAt')),
+    durationMinutes: readRowNumber(row, 'duration_minutes', 'durationMinutes') ?? 0,
+    taskTitle: readRowString(row, 'task_title', 'taskTitle'),
+    projectName: readRowString(row, 'project_name', 'projectName'),
+    description: readRowString(row, 'notes', 'description'),
+  }
+}

package/src/modules/staff/lib/time-tracking-ui/timeEntryListData.ts

@@ -0,0 +1,271 @@
+/**
+ * The reading half of screen 10 — everything the entries list needs that is not
+ * React. Kept out of the page so the rules the mockup's notes describe can be
+ * tested as arithmetic rather than through a rendered table.
+ *
+ * Three of those rules live here:
+ *
+ *  1. **Money is never summed across currencies.** `summarizeTimeEntries`
+ *     returns one subtotal PER currency instead of a single number. A tenant
+ *     billing one client in PLN and another in EUR would otherwise read a
+ *     footer total that is arithmetically valid and financially meaningless.
+ *     The renderer decides between "one currency → show it" and "several →
+ *     show them apart", but it can never be handed a pre-added figure.
+ *  2. **A non-billable entry has no cost, not a zero cost.** The list route
+ *     already answers `null` for it (screen 10 note 5); nothing here turns that
+ *     into `0`, and the totals skip it rather than adding nothing to a currency
+ *     that would then appear in the footer.
+ *  3. **The lock and the copy-day refusal are read off the response body, not
+ *     off the status code.** `409` covers an optimistic-lock conflict, a locked
+ *     entry and a non-empty copy-day target, and each one needs a different
+ *     sentence in front of the user.
+ */
+
+import {
+  clockFromApiValue,
+  dateFromApiValue,
+  readRowBoolean,
+  readRowNumber,
+  readRowString,
+  type ApiRow,
+} from './timeEntryDialogState'
+
+/** The shared refusal code every write path answers when an entry is frozen in a report. */
+export const TIME_ENTRY_LOCKED_CODE = 'time_entry_locked'
+
+/** The refusal a second "copy yesterday" click gets instead of a doubled day. */
+export const COPY_DAY_TARGET_NOT_EMPTY_CODE = 'copy_day_target_not_empty'
+
+export type TimeEntryListRow = {
+  id: string
+  date: string
+  taskId: string | null
+  taskTitle: string | null
+  timeProjectId: string | null
+  projectLabel: string | null
+  description: string | null
+  startText: string
+  endText: string
+  durationMinutes: number
+  roundedMinutes: number | null
+  isBillable: boolean
+  cost: number | null
+  currencyCode: string | null
+  rateOverrideAmount: number | null
+  isLocked: boolean
+  lockedReportId: string | null
+  updatedAt: string | null
+  tagIds: string[]
+}
+
+export type TimeEntryDirectory = {
+  taskTitles: ReadonlyMap<string, string>
+  projectLabels: ReadonlyMap<string, string>
+}
+
+export const EMPTY_TIME_ENTRY_DIRECTORY: TimeEntryDirectory = {
+  taskTitles: new Map<string, string>(),
+  projectLabels: new Map<string, string>(),
+}
+
+function readTagIds(row: ApiRow): string[] {
+  const tags = Array.isArray(row.tags) ? row.tags : []
+  return tags
+    .map((tag) => (tag && typeof tag === 'object' ? readRowString(tag as ApiRow, 'id') : null))
+    .filter((value): value is string => value !== null)
+}
+
+export function toTimeEntryListRow(
+  row: ApiRow,
+  directory: TimeEntryDirectory = EMPTY_TIME_ENTRY_DIRECTORY,
+): TimeEntryListRow | null {
+  const id = readRowString(row, 'id')
+  if (!id) return null
+  const taskId = readRowString(row, 'task_id', 'taskId')
+  const timeProjectId = readRowString(row, 'time_project_id', 'timeProjectId')
+  return {
+    id,
+    date: dateFromApiValue(readRowString(row, 'date')),
+    taskId,
+    taskTitle: taskId ? directory.taskTitles.get(taskId) ?? null : null,
+    timeProjectId,
+    projectLabel: timeProjectId ? directory.projectLabels.get(timeProjectId) ?? null : null,
+    description: readRowString(row, 'description', 'notes'),
+    startText: clockFromApiValue(readRowString(row, 'started_at', 'startedAt')),
+    endText: clockFromApiValue(readRowString(row, 'ended_at', 'endedAt')),
+    durationMinutes: readRowNumber(row, 'duration_minutes', 'durationMinutes') ?? 0,
+    roundedMinutes: readRowNumber(row, 'rounded_minutes', 'roundedMinutes'),
+    isBillable: readRowBoolean(row, true, 'is_billable', 'isBillable'),
+    cost: readRowNumber(row, 'cost'),
+    currencyCode: readRowString(row, 'currencyCode', 'rate_currency_code', 'rateCurrencyCode'),
+    rateOverrideAmount: readRowNumber(row, 'rate_override_amount', 'rateOverrideAmount'),
+    isLocked: readRowBoolean(row, false, 'isLocked', 'is_locked'),
+    lockedReportId: readRowString(row, 'lockedReportId', 'locked_report_id'),
+    updatedAt: readRowString(row, 'updated_at', 'updatedAt'),
+    tagIds: readTagIds(row),
+  }
+}
+
+export type MoneySubtotal = {
+  currencyCode: string | null
+  amount: number
+}
+
+export type TimeEntriesSummary = {
+  visibleCount: number
+  totalMinutes: number
+  /** One entry per currency present among the priced rows; never pre-added. */
+  money: MoneySubtotal[]
+}
+
+/**
+ * The mockup's `Razem (5 z 23 wpisów) · 15:15 · 4 315,00 PLN`.
+ *
+ * The time total is the sum of the durations the table SHOWS, so the footer
+ * always reconciles against the column above it; cost is the server's `cost`,
+ * which is derived from rounded minutes and is therefore not a function of the
+ * displayed duration.
+ */
+export function summarizeTimeEntries(rows: readonly TimeEntryListRow[]): TimeEntriesSummary {
+  const byCurrency = new Map<string, MoneySubtotal>()
+  let totalMinutes = 0
+  for (const row of rows) {
+    totalMinutes += Number.isFinite(row.durationMinutes) ? row.durationMinutes : 0
+    if (row.cost === null || !Number.isFinite(row.cost)) continue
+    const key = row.currencyCode ?? ''
+    const current = byCurrency.get(key)
+    if (current) current.amount += row.cost
+    else byCurrency.set(key, { currencyCode: row.currencyCode ?? null, amount: row.cost })
+  }
+  return {
+    visibleCount: rows.length,
+    totalMinutes,
+    money: Array.from(byCurrency.values()),
+  }
+}
+
+type ErrorBag = Record<string, unknown>
+
+/**
+ * `raiseCrudError` spreads the response body onto the thrown Error, but a
+ * caller that re-wraps it can leave the payload one level down. Both shapes are
+ * read so a lock refusal never degrades into "something went wrong".
+ */
+function errorPayloads(error: unknown): ErrorBag[] {
+  if (!error || typeof error !== 'object') return []
+  const bags: ErrorBag[] = [error as ErrorBag]
+  const nested = (error as { body?: unknown }).body
+  if (nested && typeof nested === 'object') bags.push(nested as ErrorBag)
+  return bags
+}
+
+export function readErrorCode(error: unknown): string | null {
+  for (const bag of errorPayloads(error)) {
+    if (typeof bag.code === 'string' && bag.code.length > 0) return bag.code
+  }
+  return null
+}
+
+export function readErrorStatus(error: unknown): number | null {
+  for (const bag of errorPayloads(error)) {
+    if (typeof bag.status === 'number' && Number.isFinite(bag.status)) return bag.status
+  }
+  return null
+}
+
+/**
+ * True for the `409 time_entry_locked` every write path answers for an entry a
+ * closed report has frozen. `entry_locked` is accepted as well so a route that
+ * spells the code without its resource prefix still reads as a lock rather than
+ * as a generic failure.
+ */
+export function isEntryLockedError(error: unknown): boolean {
+  const code = readErrorCode(error)
+  return code === TIME_ENTRY_LOCKED_CODE || code === 'entry_locked'
+}
+
+export type CopyDayTargetConflict = {
+  toDate: string | null
+  existingEntryCount: number
+}
+
+/**
+ * The `409 copy_day_target_not_empty` that names what is already on the target
+ * day. Returning the count is the whole point: the user has to be told what
+ * they would be adding to before they are offered `allowDuplicates`.
+ */
+export function readCopyDayTargetConflict(error: unknown): CopyDayTargetConflict | null {
+  if (readErrorCode(error) !== COPY_DAY_TARGET_NOT_EMPTY_CODE) return null
+  for (const bag of errorPayloads(error)) {
+    if (bag.code !== COPY_DAY_TARGET_NOT_EMPTY_CODE) continue
+    const count = bag.existingEntryCount
+    const ids = Array.isArray(bag.existingEntryIds) ? bag.existingEntryIds.length : 0
+    return {
+      toDate: typeof bag.toDate === 'string' ? bag.toDate : null,
+      existingEntryCount: typeof count === 'number' && Number.isFinite(count) ? count : ids,
+    }
+  }
+  return { toDate: null, existingEntryCount: 0 }
+}
+
+export type IsoDateRange = {
+  from: string
+  to: string
+}
+
+function toIsoDay(date: Date): string {
+  const year = date.getFullYear()
+  const month = String(date.getMonth() + 1).padStart(2, '0')
+  const day = String(date.getDate()).padStart(2, '0')
+  return `${year}-${month}-${day}`
+}
+
+/**
+ * Monday-to-Sunday, matching the mockup's "Okres: ten tydzień" default. The
+ * week is computed in local time because a time entry is addressed by its
+ * calendar day, not by an instant.
+ */
+export function currentWeekRange(now: Date = new Date()): IsoDateRange {
+  const start = new Date(now.getFullYear(), now.getMonth(), now.getDate())
+  const weekday = (start.getDay() + 6) % 7
+  start.setDate(start.getDate() - weekday)
+  const end = new Date(start)
+  end.setDate(end.getDate() + 6)
+  return { from: toIsoDay(start), to: toIsoDay(end) }
+}
+
+/**
+ * `pon 20 lip` — the weekday the mockup leads each row with. The locale is left
+ * to the runtime by default, exactly as `formatDate`/`formatCurrency` do, so a
+ * date on this page reads the same way as a date anywhere else in the backoffice.
+ */
+export function formatEntryDay(isoDate: string, locale?: string): string {
+  if (!isoDate) return ''
+  const parsed = new Date(`${isoDate}T00:00:00`)
+  if (Number.isNaN(parsed.getTime())) return isoDate
+  try {
+    return new Intl.DateTimeFormat(locale, { weekday: 'short', day: 'numeric', month: 'short' }).format(parsed)
+  } catch {
+    return isoDate
+  }
+}
+
+/** `09:00 – 11:30`, or an em-dash when the entry carries no clock times. */
+export function formatEntryClockRange(row: Pick<TimeEntryListRow, 'startText' | 'endText'>): string | null {
+  if (!row.startText && !row.endText) return null
+  if (row.startText && row.endText) return `${row.startText} – ${row.endText}`
+  return row.startText || row.endText
+}
+
+export function collectDirectoryIds(rows: readonly TimeEntryListRow[]): {
+  taskIds: string[]
+  projectIds: string[]
+} {
+  const taskIds = new Set<string>()
+  const projectIds = new Set<string>()
+  for (const row of rows) {
+    if (row.taskId) taskIds.add(row.taskId)
+    if (row.timeProjectId) projectIds.add(row.timeProjectId)
+  }
+  return { taskIds: Array.from(taskIds), projectIds: Array.from(projectIds) }
+}