@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/timeTrackingSettingsForm.ts

@@ -0,0 +1,168 @@
+/**
+ * Pure state for the module settings screen (T7.1, screen 16).
+ *
+ * The screen edits two numbers that are legitimately empty-able or bounded
+ * (`targets.dailyHours` may be blank = no target; `access.assignmentGraceDays` is
+ * an integer day count), so the draft keeps them as the TEXT the user typed and
+ * converts only at the edges. Stripping a half-typed number back into the field is
+ * the same defect `DurationInput` was built to avoid.
+ *
+ * `buildRoundingExamples` is the screen's most load-bearing function: note 1 of the
+ * mockup requires the worked examples to recompute live, because rounding is a rule
+ * people misread and its effect is otherwise invisible until an invoice. It calls
+ * `roundMinutes` — the same function the write path calls — so a preview that
+ * disagreed with reality is not expressible here.
+ */
+
+import { formatDuration } from '../time-tracking/duration'
+import { roundMinutes, type RoundingSettings, type RoundingUnitMinutes } from '../time-tracking/rounding'
+import { contributedTimeTrackingSettingKeys } from '../time-tracking/settingKeys'
+import { readTimeTrackingSettingValue, type TimeTrackingSettings } from '../time-tracking/settings'
+
+export const ROUNDING_UNIT_OPTIONS: readonly RoundingUnitMinutes[] = [0, 5, 10, 15]
+
+/**
+ * The four cases from the mockup: just over a unit, past the halfway point, a
+ * minimum-charge case, and one that is already exact and must not move.
+ */
+export const ROUNDING_EXAMPLE_MINUTES: readonly number[] = [62, 76, 3, 120]
+
+export type RoundingExample = {
+  rawMinutes: number
+  roundedMinutes: number
+  rawLabel: string
+  roundedLabel: string
+}
+
+export function buildRoundingExamples(rounding: RoundingSettings): RoundingExample[] {
+  return ROUNDING_EXAMPLE_MINUTES.map((rawMinutes) => {
+    const roundedMinutes = roundMinutes(rawMinutes, rounding)
+    return {
+      rawMinutes,
+      roundedMinutes,
+      rawLabel: formatDuration(rawMinutes, 'clock'),
+      roundedLabel: formatDuration(roundedMinutes, 'clock'),
+    }
+  })
+}
+
+/** `+38:15` / `−12:30` / `0:00`, for the impact card's delta against raw time. */
+export function formatSignedMinutes(minutes: number): string {
+  const safe = Number.isFinite(minutes) ? Math.round(minutes) : 0
+  const magnitude = formatDuration(Math.abs(safe), 'clock')
+  if (safe > 0) return `+${magnitude}`
+  if (safe < 0) return `−${magnitude}`
+  return magnitude
+}
+
+export type TimeTrackingSettingsDraft = {
+  roundingUnitMinutes: RoundingUnitMinutes
+  roundingDirection: RoundingSettings['direction']
+  defaultsBillable: boolean
+  defaultsChainStartFromPreviousEnd: boolean
+  /** Free text: empty means "no daily target", which is a real, storable value. */
+  dailyHoursText: string
+  warningsOverlap: boolean
+  warningsRunningTimer: boolean
+  assignmentGraceDaysText: string
+  /**
+   * EP-42 — every contributed setting key, by its `<group>.<key>` id, carried through
+   * the draft untouched so the page's own Save round-trips a contribution it knows
+   * nothing about. The eight built-ins are NOT in here: the page renders those itself.
+   */
+  contributed: Record<string, unknown>
+}
+
+
+export const MAX_ASSIGNMENT_GRACE_DAYS_INPUT = 365
+
+export function toSettingsDraft(settings: TimeTrackingSettings): TimeTrackingSettingsDraft {
+  return {
+    roundingUnitMinutes: settings.rounding.unitMinutes,
+    roundingDirection: settings.rounding.direction,
+    defaultsBillable: settings.defaults.billable,
+    defaultsChainStartFromPreviousEnd: settings.defaults.chainStartFromPreviousEnd,
+    dailyHoursText: settings.targets.dailyHours === null ? '' : String(settings.targets.dailyHours),
+    warningsOverlap: settings.warnings.overlap,
+    warningsRunningTimer: settings.warnings.runningTimer,
+    assignmentGraceDaysText: String(settings.access.assignmentGraceDays),
+    contributed: Object.fromEntries(
+      contributedTimeTrackingSettingKeys().map((entry) => [
+        entry.id,
+        readTimeTrackingSettingValue(settings, entry.id),
+      ]),
+    ),
+  }
+}
+
+export type SettingsDraftFieldError = 'dailyHours' | 'assignmentGraceDays'
+
+function parseDailyHours(text: string): number | null | undefined {
+  const trimmed = text.trim()
+  if (trimmed.length === 0) return null
+  const parsed = Number(trimmed.replace(',', '.'))
+  if (!Number.isFinite(parsed) || parsed < 0 || parsed > 24) return undefined
+  return parsed
+}
+
+function parseGraceDays(text: string): number | undefined {
+  const trimmed = text.trim()
+  if (trimmed.length === 0) return undefined
+  const parsed = Number(trimmed)
+  if (!Number.isInteger(parsed) || parsed < 0 || parsed > MAX_ASSIGNMENT_GRACE_DAYS_INPUT) return undefined
+  return parsed
+}
+
+/** Which fields currently hold text that cannot be saved. Empty means the draft is valid. */
+export function settingsDraftErrors(draft: TimeTrackingSettingsDraft): SettingsDraftFieldError[] {
+  const errors: SettingsDraftFieldError[] = []
+  if (parseDailyHours(draft.dailyHoursText) === undefined) errors.push('dailyHours')
+  if (parseGraceDays(draft.assignmentGraceDaysText) === undefined) errors.push('assignmentGraceDays')
+  return errors
+}
+
+export function draftRounding(draft: TimeTrackingSettingsDraft): RoundingSettings {
+  return { unitMinutes: draft.roundingUnitMinutes, direction: draft.roundingDirection }
+}
+
+/** The PUT body. Returns null when the draft still holds unsaveable text. */
+export function toSettingsPayload(draft: TimeTrackingSettingsDraft): TimeTrackingSettings | null {
+  const dailyHours = parseDailyHours(draft.dailyHoursText)
+  const assignmentGraceDays = parseGraceDays(draft.assignmentGraceDaysText)
+  if (dailyHours === undefined || assignmentGraceDays === undefined) return null
+  const payload: TimeTrackingSettings = {
+    rounding: draftRounding(draft),
+    defaults: {
+      billable: draft.defaultsBillable,
+      chainStartFromPreviousEnd: draft.defaultsChainStartFromPreviousEnd,
+    },
+    targets: { dailyHours },
+    warnings: { overlap: draft.warningsOverlap, runningTimer: draft.warningsRunningTimer },
+    access: { assignmentGraceDays },
+  }
+  for (const entry of contributedTimeTrackingSettingKeys()) {
+    const group = (payload[entry.group] ?? {}) as Record<string, unknown>
+    group[entry.key] = draft.contributed[entry.id]
+    payload[entry.group] = group
+  }
+  return payload
+}
+
+export function isSettingsDraftDirty(
+  draft: TimeTrackingSettingsDraft,
+  baseline: TimeTrackingSettingsDraft,
+): boolean {
+  return (
+    draft.roundingUnitMinutes !== baseline.roundingUnitMinutes ||
+    draft.roundingDirection !== baseline.roundingDirection ||
+    draft.defaultsBillable !== baseline.defaultsBillable ||
+    draft.defaultsChainStartFromPreviousEnd !== baseline.defaultsChainStartFromPreviousEnd ||
+    draft.dailyHoursText.trim() !== baseline.dailyHoursText.trim() ||
+    draft.warningsOverlap !== baseline.warningsOverlap ||
+    draft.warningsRunningTimer !== baseline.warningsRunningTimer ||
+    draft.assignmentGraceDaysText.trim() !== baseline.assignmentGraceDaysText.trim() ||
+    contributedTimeTrackingSettingKeys().some(
+      (entry) => !Object.is(draft.contributed[entry.id], baseline.contributed[entry.id]),
+    )
+  )
+}

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

@@ -0,0 +1,225 @@
+/**
+ * The reading half of the timesheet (screens 11 and 12) — day buckets, load
+ * bars, the period footer and the two "smart" defaults the mockups ask for.
+ *
+ * Kept pure and out of the React tree for the same reason as `timesheetPeriod`:
+ * every number a consultant will later defend in front of a client should be
+ * testable as arithmetic.
+ *
+ * Three decisions are encoded here rather than in a component:
+ *
+ *  1. **A load bar has a scale even without a target.** Screen 11 note 6 is
+ *     explicit that `targets.dailyHours` is a proposal; when a tenant clears it
+ *     the bars scale to the longest day of the period instead of disappearing,
+ *     so "light day vs heavy day" (US-E3) still reads at a glance.
+ *  2. **Weekends do not raise the target but do raise the total** (screen 12
+ *     note 4). `countWorkingDays` supplies the target; the totals sum every day.
+ *  3. **Money is never summed across currencies** — this module deliberately
+ *     exposes no money total at all. The timesheet is a time surface; cost lives
+ *     on the entries list and the report, both of which subtotal per currency.
+ */
+
+import {
+  countWorkingDays,
+  eachDayIso,
+  isWeekendIso,
+  type TimesheetDateRange,
+} from './timesheetPeriod'
+import { toTimeEntryListRow, type TimeEntryDirectory, type TimeEntryListRow } from './timeEntryListData'
+import { readRowString, type ApiRow } from './timeEntryDialogState'
+
+/**
+ * A timesheet row is an entries-list row plus the person who logged it — a Team
+ * Leader filtering to "everyone" needs the author on the line (screen 12 note 1),
+ * and a Team Member never sees a row that is not theirs anyway.
+ */
+export type TimesheetEntry = TimeEntryListRow & {
+  staffMemberId: string | null
+}
+
+export function toTimesheetEntry(row: ApiRow, directory?: TimeEntryDirectory): TimesheetEntry | null {
+  const base = toTimeEntryListRow(row, directory)
+  if (!base) return null
+  return { ...base, staffMemberId: readRowString(row, 'staff_member_id', 'staffMemberId') }
+}
+
+export type TimesheetDay = {
+  date: string
+  isWeekend: boolean
+  entries: TimesheetEntry[]
+  totalMinutes: number
+  billableMinutes: number
+}
+
+export function buildTimesheetDays(
+  range: TimesheetDateRange,
+  entries: readonly TimesheetEntry[],
+): TimesheetDay[] {
+  const byDate = new Map<string, TimesheetEntry[]>()
+  for (const entry of entries) {
+    const bucket = byDate.get(entry.date)
+    if (bucket) bucket.push(entry)
+    else byDate.set(entry.date, [entry])
+  }
+  return eachDayIso(range).map((date) => {
+    const dayEntries = (byDate.get(date) ?? []).slice().sort(compareEntriesByClock)
+    let totalMinutes = 0
+    let billableMinutes = 0
+    for (const entry of dayEntries) {
+      const minutes = Number.isFinite(entry.durationMinutes) ? entry.durationMinutes : 0
+      totalMinutes += minutes
+      if (entry.isBillable) billableMinutes += minutes
+    }
+    return { date, isWeekend: isWeekendIso(date), entries: dayEntries, totalMinutes, billableMinutes }
+  })
+}
+
+/** Entries read top-to-bottom in the order the day was worked; clock-less ones last. */
+function compareEntriesByClock(left: TimesheetEntry, right: TimesheetEntry): number {
+  if (left.startText && right.startText) return left.startText.localeCompare(right.startText)
+  if (left.startText) return -1
+  if (right.startText) return 1
+  return 0
+}
+
+export type TimesheetSummary = {
+  totalMinutes: number
+  billableMinutes: number
+  /** `null` when the tenant cleared `targets.dailyHours` — there is then nothing to be over or under. */
+  targetMinutes: number | null
+  deltaMinutes: number | null
+  workingDays: number
+}
+
+export function summarizeTimesheet(
+  days: readonly TimesheetDay[],
+  range: TimesheetDateRange,
+  dailyHours: number | null | undefined,
+): TimesheetSummary {
+  let totalMinutes = 0
+  let billableMinutes = 0
+  for (const day of days) {
+    totalMinutes += day.totalMinutes
+    billableMinutes += day.billableMinutes
+  }
+  const workingDays = countWorkingDays(range)
+  const hasTarget = typeof dailyHours === 'number' && Number.isFinite(dailyHours) && dailyHours > 0
+  const targetMinutes = hasTarget ? Math.round(workingDays * dailyHours * 60) : null
+  return {
+    totalMinutes,
+    billableMinutes,
+    targetMinutes,
+    deltaMinutes: targetMinutes === null ? null : totalMinutes - targetMinutes,
+    workingDays,
+  }
+}
+
+/**
+ * The scale a day's bar is drawn against. With a daily target it is that target,
+ * so 8:00 fills the bar; without one it is the longest day in the period, so the
+ * bars still rank the days against each other (screen 11 note 6).
+ */
+export function resolveLoadScaleMinutes(
+  days: readonly TimesheetDay[],
+  dailyHours: number | null | undefined,
+): number | null {
+  if (typeof dailyHours === 'number' && Number.isFinite(dailyHours) && dailyHours > 0) {
+    return Math.round(dailyHours * 60)
+  }
+  let longest = 0
+  for (const day of days) {
+    if (day.totalMinutes > longest) longest = day.totalMinutes
+  }
+  return longest > 0 ? longest : null
+}
+
+/** 0–100. A day over target pins at 100 — the bar reads "full", the number reads the overage. */
+export function loadPercent(totalMinutes: number, scaleMinutes: number | null): number {
+  if (!scaleMinutes || scaleMinutes <= 0) return 0
+  if (totalMinutes <= 0) return 0
+  return Math.min(100, Math.round((totalMinutes / scaleMinutes) * 100))
+}
+
+/**
+ * Screen 12 note 2 — "only the day that deviates from the target is expanded".
+ *
+ * Deviation is measured against the daily target on working days that have
+ * already happened; a Thursday nobody has worked yet is not a gap, it is the
+ * future. The largest shortfall wins, later days breaking ties, so closing out a
+ * week always opens on the day that still needs attention. With no target (or no
+ * shortfall) the most recent day carrying entries is opened instead, because an
+ * all-collapsed list gives the user nothing to act on.
+ */
+export function pickDefaultExpandedDay(
+  days: readonly TimesheetDay[],
+  dailyHours: number | null | undefined,
+  todayIsoValue: string,
+): string | null {
+  const past = days.filter((day) => day.date <= todayIsoValue)
+  if (past.length === 0) return null
+  const hasTarget = typeof dailyHours === 'number' && Number.isFinite(dailyHours) && dailyHours > 0
+  if (hasTarget) {
+    const target = Math.round(dailyHours * 60)
+    let best: { date: string; shortfall: number } | null = null
+    for (const day of past) {
+      if (day.isWeekend) continue
+      const shortfall = target - day.totalMinutes
+      if (shortfall <= 0) continue
+      if (!best || shortfall > best.shortfall || (shortfall === best.shortfall && day.date > best.date)) {
+        best = { date: day.date, shortfall }
+      }
+    }
+    if (best) return best.date
+  }
+  for (let index = past.length - 1; index >= 0; index -= 1) {
+    if (past[index].entries.length > 0) return past[index].date
+  }
+  return null
+}
+
+const CLOCK_PATTERN = /^(\d{1,2}):(\d{2})$/
+
+function clockToMinutes(value: string): number | null {
+  const match = CLOCK_PATTERN.exec(value)
+  if (!match) return null
+  const hours = Number(match[1])
+  const minutes = Number(match[2])
+  if (hours > 23 || minutes > 59) return null
+  return hours * 60 + minutes
+}
+
+/**
+ * Screen 12 note 3 — the quick-add row's start time is prefilled with the end of
+ * the previous entry of that day. The latest end wins rather than the last row in
+ * document order, so an entry added out of sequence cannot drag the suggestion
+ * backwards. Returns `null` for a day whose entries carry no clocks, in which
+ * case the field simply opens empty.
+ */
+export function suggestNextStartClock(day: TimesheetDay | null | undefined): string | null {
+  if (!day) return null
+  let latest: { minutes: number; text: string } | null = null
+  for (const entry of day.entries) {
+    if (!entry.endText) continue
+    const minutes = clockToMinutes(entry.endText)
+    if (minutes === null) continue
+    if (!latest || minutes > latest.minutes) latest = { minutes, text: entry.endText }
+  }
+  return latest?.text ?? null
+}
+
+export type TimesheetDayIndex = ReadonlyMap<string, TimesheetDay>
+
+export function indexDaysByDate(days: readonly TimesheetDay[]): TimesheetDayIndex {
+  const index = new Map<string, TimesheetDay>()
+  for (const day of days) index.set(day.date, day)
+  return index
+}
+
+/**
+ * The chip label inside a calendar cell — the project when we know it, the task
+ * when we do not, and the description as a last resort. A cell that shows a bare
+ * dash tells the user nothing, so something always renders.
+ */
+export function entryChipLabel(entry: TimesheetEntry, fallback: string): string {
+  return entry.projectLabel ?? entry.taskTitle ?? entry.description ?? fallback
+}

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

@@ -0,0 +1,278 @@
+/**
+ * The timesheet's sense of "when" (T5.1, US-E1).
+ *
+ * Everything here is pure date arithmetic on `YYYY-MM-DD` strings, kept out of
+ * the React tree so the one rule the user story actually states can be tested as
+ * arithmetic: **switching the period kind preserves the current date context.**
+ *
+ * That rule is why the state this module is driven by is a single ANCHOR DAY
+ * rather than a range. A range would have to be re-derived on every switch and
+ * the obvious derivation ("take the range start") is exactly the bug US-E1
+ * forbids — a month range starting 1 July, switched to `year`, would land on
+ * 1 January and the user would be looking at a different part of their life. An
+ * anchor never moves on a kind switch, so week↔month↔quarter↔year always stays
+ * "around now".
+ *
+ * Navigation moves the anchor by one unit of the current kind and deliberately
+ * does NOT snap it to the period start, for the same reason: after
+ * month → previous → week the anchor is still the same day-of-month, so the week
+ * shown is the one containing it.
+ */
+
+export type TimesheetPeriodKind = 'year' | 'quarter' | 'month' | 'week'
+
+export const TIMESHEET_PERIOD_KINDS: readonly TimesheetPeriodKind[] = ['year', 'quarter', 'month', 'week']
+
+export type TimesheetDateRange = {
+  from: string
+  to: string
+}
+
+const ISO_DAY_PATTERN = /^(\d{4})-(\d{2})-(\d{2})$/
+
+export function isTimesheetPeriodKind(value: unknown): value is TimesheetPeriodKind {
+  return typeof value === 'string' && (TIMESHEET_PERIOD_KINDS as readonly string[]).includes(value)
+}
+
+/** Local calendar day of a `Date`, because an entry is addressed by its day and not by an instant. */
+export 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}`
+}
+
+/** `YYYY-MM-DD` → local midnight. Invalid text answers `null` rather than an Invalid Date. */
+export function parseIsoDay(value: string): Date | null {
+  const match = ISO_DAY_PATTERN.exec(value)
+  if (!match) return null
+  const year = Number(match[1])
+  const month = Number(match[2])
+  const day = Number(match[3])
+  const parsed = new Date(year, month - 1, day)
+  if (Number.isNaN(parsed.getTime())) return null
+  if (parsed.getFullYear() !== year || parsed.getMonth() !== month - 1 || parsed.getDate() !== day) return null
+  return parsed
+}
+
+function safeParse(value: string, fallback: Date): Date {
+  return parseIsoDay(value) ?? fallback
+}
+
+export function todayIso(now: Date = new Date()): string {
+  return toIsoDay(now)
+}
+
+export function addDaysIso(iso: string, days: number): string {
+  const base = parseIsoDay(iso)
+  if (!base) return iso
+  const next = new Date(base.getFullYear(), base.getMonth(), base.getDate() + days)
+  return toIsoDay(next)
+}
+
+/**
+ * Adds whole months, clamping the day into the target month — 31 Jan + 1 month is
+ * 28/29 Feb, never 2/3 March. Without the clamp, paging forward through the year
+ * from a 31st would skip February entirely.
+ */
+export function addMonthsIso(iso: string, months: number): string {
+  const base = parseIsoDay(iso)
+  if (!base) return iso
+  const targetMonthFirst = new Date(base.getFullYear(), base.getMonth() + months, 1)
+  const daysInTarget = new Date(targetMonthFirst.getFullYear(), targetMonthFirst.getMonth() + 1, 0).getDate()
+  const day = Math.min(base.getDate(), daysInTarget)
+  return toIsoDay(new Date(targetMonthFirst.getFullYear(), targetMonthFirst.getMonth(), day))
+}
+
+/** Monday of the week containing `iso` — the module's week starts on Monday everywhere. */
+export function startOfWeekIso(iso: string): string {
+  const base = parseIsoDay(iso)
+  if (!base) return iso
+  const weekday = (base.getDay() + 6) % 7
+  return addDaysIso(iso, -weekday)
+}
+
+export function startOfMonthIso(iso: string): string {
+  const base = parseIsoDay(iso)
+  if (!base) return iso
+  return toIsoDay(new Date(base.getFullYear(), base.getMonth(), 1))
+}
+
+export function endOfMonthIso(iso: string): string {
+  const base = parseIsoDay(iso)
+  if (!base) return iso
+  return toIsoDay(new Date(base.getFullYear(), base.getMonth() + 1, 0))
+}
+
+export function quarterOfIso(iso: string): number {
+  const base = parseIsoDay(iso)
+  if (!base) return 1
+  return Math.floor(base.getMonth() / 3) + 1
+}
+
+/** ISO-8601 week number, matching the mockup's `Tydzień 29`. */
+export function isoWeekNumber(iso: string): number {
+  const base = parseIsoDay(iso)
+  if (!base) return 1
+  const utc = new Date(Date.UTC(base.getFullYear(), base.getMonth(), base.getDate()))
+  utc.setUTCDate(utc.getUTCDate() + 4 - (utc.getUTCDay() || 7))
+  const yearStart = new Date(Date.UTC(utc.getUTCFullYear(), 0, 1))
+  return Math.ceil(((utc.getTime() - yearStart.getTime()) / 86_400_000 + 1) / 7)
+}
+
+export function resolvePeriodRange(kind: TimesheetPeriodKind, anchorIso: string): TimesheetDateRange {
+  const base = safeParse(anchorIso, new Date())
+  const anchor = toIsoDay(base)
+  if (kind === 'week') {
+    const from = startOfWeekIso(anchor)
+    return { from, to: addDaysIso(from, 6) }
+  }
+  if (kind === 'month') {
+    return { from: startOfMonthIso(anchor), to: endOfMonthIso(anchor) }
+  }
+  if (kind === 'quarter') {
+    const firstMonth = Math.floor(base.getMonth() / 3) * 3
+    const from = toIsoDay(new Date(base.getFullYear(), firstMonth, 1))
+    const to = toIsoDay(new Date(base.getFullYear(), firstMonth + 3, 0))
+    return { from, to }
+  }
+  return {
+    from: toIsoDay(new Date(base.getFullYear(), 0, 1)),
+    to: toIsoDay(new Date(base.getFullYear(), 11, 31)),
+  }
+}
+
+/**
+ * One period earlier (`-1`) or later (`+1`), expressed as a new anchor day.
+ *
+ * The anchor keeps its day-of-month / day-of-week, so paging never drifts and a
+ * later kind switch still lands "around" the day the user was looking at.
+ */
+export function shiftPeriodAnchor(kind: TimesheetPeriodKind, anchorIso: string, direction: 1 | -1): string {
+  if (kind === 'week') return addDaysIso(anchorIso, 7 * direction)
+  if (kind === 'month') return addMonthsIso(anchorIso, direction)
+  if (kind === 'quarter') return addMonthsIso(anchorIso, 3 * direction)
+  return addMonthsIso(anchorIso, 12 * direction)
+}
+
+export function eachDayIso(range: TimesheetDateRange): string[] {
+  const start = parseIsoDay(range.from)
+  const end = parseIsoDay(range.to)
+  if (!start || !end || end.getTime() < start.getTime()) return []
+  const days: string[] = []
+  let cursor = range.from
+  // Bounded by a year and a bit, so a corrupt range can never spin forever.
+  for (let guard = 0; guard < 400; guard += 1) {
+    days.push(cursor)
+    if (cursor === range.to) break
+    cursor = addDaysIso(cursor, 1)
+  }
+  return days
+}
+
+export function isWeekendIso(iso: string): boolean {
+  const parsed = parseIsoDay(iso)
+  if (!parsed) return false
+  const day = parsed.getDay()
+  return day === 0 || day === 6
+}
+
+/**
+ * Mon–Fri days inside the range. Screen 11's footer scales its target by this
+ * ("Cel (14 dni × 8h)"), and screen 12 note 4 is explicit that a weekend does not
+ * raise the target even though time logged on one still raises the total.
+ */
+export function countWorkingDays(range: TimesheetDateRange): number {
+  return eachDayIso(range).filter((iso) => !isWeekendIso(iso)).length
+}
+
+export function periodTargetMinutes(range: TimesheetDateRange, dailyHours: number | null | undefined): number | null {
+  if (dailyHours === null || dailyHours === undefined || !Number.isFinite(dailyHours) || dailyHours <= 0) return null
+  return Math.round(countWorkingDays(range) * dailyHours * 60)
+}
+
+export type TimesheetCalendarCell = {
+  date: string
+  dayOfMonth: number
+  inPeriod: boolean
+  isWeekend: boolean
+  isToday: boolean
+}
+
+/**
+ * The month grid of screen 11: whole Monday-to-Sunday weeks covering the month,
+ * with the leading/trailing days of the neighbouring months kept as `inPeriod:
+ * false` cells so the grid stays rectangular (the mockup draws `29 cze` and
+ * `30 cze` in the first row).
+ */
+export function buildCalendarWeeks(anchorIso: string, todayIsoValue: string = todayIso()): TimesheetCalendarCell[][] {
+  const range = resolvePeriodRange('month', anchorIso)
+  const gridStart = startOfWeekIso(range.from)
+  const lastWeekStart = startOfWeekIso(range.to)
+  const gridEnd = addDaysIso(lastWeekStart, 6)
+  const days = eachDayIso({ from: gridStart, to: gridEnd })
+  const weeks: TimesheetCalendarCell[][] = []
+  for (let index = 0; index < days.length; index += 7) {
+    weeks.push(
+      days.slice(index, index + 7).map((date) => {
+        const parsed = parseIsoDay(date)
+        return {
+          date,
+          dayOfMonth: parsed ? parsed.getDate() : 0,
+          inPeriod: date >= range.from && date <= range.to,
+          isWeekend: isWeekendIso(date),
+          isToday: date === todayIsoValue,
+        }
+      }),
+    )
+  }
+  return weeks
+}
+
+function formatWithIntl(date: Date, locale: string | undefined, options: Intl.DateTimeFormatOptions): string {
+  try {
+    return new Intl.DateTimeFormat(locale, options).format(date)
+  } catch {
+    return toIsoDay(date)
+  }
+}
+
+/**
+ * `Lipiec 2026`, `Q3 2026`, `2026`, `13–19 lip 2026 · W29` — the label beside the
+ * prev/next arrows. Month and day names come from the runtime locale, the same
+ * way every other date in the backoffice is rendered.
+ */
+export function formatPeriodLabel(
+  kind: TimesheetPeriodKind,
+  anchorIso: string,
+  locale?: string,
+): string {
+  const range = resolvePeriodRange(kind, anchorIso)
+  const from = parseIsoDay(range.from)
+  const to = parseIsoDay(range.to)
+  if (!from || !to) return anchorIso
+  if (kind === 'year') return String(from.getFullYear())
+  if (kind === 'quarter') return `Q${quarterOfIso(range.from)} ${from.getFullYear()}`
+  if (kind === 'month') {
+    const label = formatWithIntl(from, locale, { month: 'long', year: 'numeric' })
+    return label.charAt(0).toUpperCase() + label.slice(1)
+  }
+  const fromLabel = formatWithIntl(from, locale, { day: 'numeric', month: 'short' })
+  const toLabel = formatWithIntl(to, locale, { day: 'numeric', month: 'short', year: 'numeric' })
+  return `${fromLabel} – ${toLabel} · W${isoWeekNumber(range.from)}`
+}
+
+/** `pon 13 lip` — the row label of screen 12's day bars. */
+export function formatDayLabel(iso: string, locale?: string): string {
+  const parsed = parseIsoDay(iso)
+  if (!parsed) return iso
+  return formatWithIntl(parsed, locale, { weekday: 'short', day: 'numeric', month: 'short' })
+}
+
+/** `Piątek 17 lipca` — the heading of an expanded day. */
+export function formatLongDayLabel(iso: string, locale?: string): string {
+  const parsed = parseIsoDay(iso)
+  if (!parsed) return iso
+  const label = formatWithIntl(parsed, locale, { weekday: 'long', day: 'numeric', month: 'long' })
+  return label.charAt(0).toUpperCase() + label.slice(1)
+}