super-time-tracker-ui 0.1.2

package/lib/get_initial_preferred_sheet_name.ts

@@ -0,0 +1,34 @@
+import { parse_default_sheet_session_mode } from '@/lib/parse_default_sheet_session_mode'
+import { resolve_session_preferred_sheet } from '@/lib/resolve_session_preferred_sheet'
+import { type TimeTrackerDB } from '@/lib/types'
+
+export interface InitialPreferredSheetCookies {
+  session_mode?: string
+  fixed_sheet_name?: string
+  last_viewed_sheet?: string
+}
+
+/**
+ * Chooses the preferred sheet for a new session from cookies and the database.
+ */
+export function get_initial_preferred_sheet_name(
+  db: TimeTrackerDB,
+  cookies: InitialPreferredSheetCookies,
+): string | null {
+  const mode = parse_default_sheet_session_mode(cookies.session_mode)
+  const last_viewed_sheet =
+    cookies.last_viewed_sheet !== undefined
+      ? decodeURIComponent(cookies.last_viewed_sheet).trim() || null
+      : null
+  const fixed_sheet_name =
+    cookies.fixed_sheet_name !== undefined
+      ? decodeURIComponent(cookies.fixed_sheet_name).trim() || null
+      : null
+
+  return resolve_session_preferred_sheet(
+    db,
+    mode,
+    last_viewed_sheet,
+    fixed_sheet_name,
+  )
+}

package/lib/get_initial_reporting_range_inputs.ts

@@ -0,0 +1,31 @@
+import { default_reporting_range_preference } from '@/lib/preferences/default_reporting_range_preference'
+import { get_reporting_date_range_shortcut_inputs } from '@/lib/get_reporting_date_range_shortcut_inputs'
+import {
+  type DefaultReportingRange,
+  type WeekStartsOn,
+} from '@/lib/types/ui_preferences'
+import { type ReportingDateRangeInputs } from '@/lib/types/reporting'
+import { week_starts_on_to_index } from '@/lib/week_starts_on_to_index'
+
+const empty_range: ReportingDateRangeInputs = {
+  from_date: '',
+  to_date: '',
+}
+
+/**
+ * Returns the initial reporting date range from the user's preference.
+ */
+export function get_initial_reporting_range_inputs(
+  range: DefaultReportingRange = default_reporting_range_preference.read(),
+  week_starts_on: WeekStartsOn = 'monday',
+): ReportingDateRangeInputs {
+  if (range === 'none') {
+    return empty_range
+  }
+
+  return get_reporting_date_range_shortcut_inputs(
+    range,
+    new Date(),
+    week_starts_on_to_index(week_starts_on),
+  )
+}

package/lib/get_input_class_name.ts

@@ -0,0 +1,15 @@
+export type InputSize = 'default' | 'compact'
+
+/**
+ * Returns Tailwind classes for themed text inputs and selects.
+ */
+export function get_input_class_name(size: InputSize = 'default'): string {
+  const base =
+    'box-border max-w-full min-w-0 w-full rounded-[0.65rem] border border-panel-border bg-input-bg px-3 py-2.5 font-inherit text-inherit transition-[background-color,border-color] duration-200 focus:border-input-focus-border focus:outline-none'
+
+  if (size === 'compact') {
+    return `${base} px-2.5 py-2`
+  }
+
+  return base
+}

package/lib/get_merge_tags_confirm_dialog.ts

@@ -0,0 +1,25 @@
+import { type ConfirmDialogOptions } from '@/lib/types/confirm_dialog'
+import { format_display_tag } from '@/lib/format_display_tag'
+
+/**
+ * Builds confirm dialog options for merging tags.
+ */
+export function get_merge_tags_confirm_dialog(
+  source_tags: string[],
+  target_tag: string,
+  entry_count: number,
+): ConfirmDialogOptions {
+  const source_label = source_tags.map((tag) => format_display_tag(tag)).join(', ')
+  const target_label = format_display_tag(target_tag)
+  const entry_note =
+    entry_count === 1
+      ? '1 entry will be updated.'
+      : `${entry_count} entries will be updated.`
+
+  return {
+    title: 'Merge tags?',
+    message: `Merge ${source_label} into ${target_label}? ${entry_note}`,
+    confirmLabel: 'Merge tags',
+    variant: 'danger',
+  }
+}

package/lib/get_period_range_ms.ts

@@ -0,0 +1,43 @@
+import {
+  endOfDay,
+  endOfMonth,
+  endOfWeek,
+  startOfDay,
+  startOfMonth,
+  startOfWeek,
+} from 'date-fns'
+
+export type ReportingPeriod = 'today' | 'week' | 'month'
+
+export interface PeriodRangeMs {
+  startMs: number
+  endMs: number
+}
+
+/**
+ * Returns inclusive millisecond bounds for a reporting calendar period.
+ */
+export function get_period_range_ms(
+  period: ReportingPeriod,
+  reference: Date = new Date(),
+  week_starts_on: 0 | 1 = 1,
+): PeriodRangeMs {
+  switch (period) {
+    case 'week':
+      return {
+        startMs: +startOfWeek(reference, { weekStartsOn: week_starts_on }),
+        endMs: +endOfWeek(reference, { weekStartsOn: week_starts_on }),
+      }
+    case 'month':
+      return {
+        startMs: +startOfMonth(reference),
+        endMs: +endOfMonth(reference),
+      }
+    case 'today':
+    default:
+      return {
+        startMs: +startOfDay(reference),
+        endMs: +endOfDay(reference),
+      }
+  }
+}

package/lib/get_reporting_date_range_shortcut_inputs.ts

@@ -0,0 +1,84 @@
+import {
+  endOfMonth,
+  endOfWeek,
+  endOfYear,
+  format,
+  startOfDay,
+  startOfMonth,
+  startOfWeek,
+  startOfYear,
+  subDays,
+  subMonths,
+  subYears,
+} from 'date-fns'
+
+import {
+  type ReportingDateRangeInputs,
+  type ReportingDateRangeShortcut,
+} from '@/lib/types/reporting'
+
+/**
+ * Returns date input values for a reporting range shortcut.
+ */
+export function get_reporting_date_range_shortcut_inputs(
+  shortcut: ReportingDateRangeShortcut,
+  reference: Date = new Date(),
+  week_starts_on: 0 | 1 = 1,
+): ReportingDateRangeInputs {
+  const format_input_date = (date: Date): string => format(date, 'yyyy-MM-dd')
+
+  switch (shortcut) {
+    case 'yesterday': {
+      const day = subDays(reference, 1)
+
+      return {
+        from_date: format_input_date(startOfDay(day)),
+        to_date: format_input_date(startOfDay(day)),
+      }
+    }
+    case 'week':
+      return {
+        from_date: format_input_date(
+          startOfWeek(reference, { weekStartsOn: week_starts_on }),
+        ),
+        to_date: format_input_date(
+          endOfWeek(reference, { weekStartsOn: week_starts_on }),
+        ),
+      }
+    case 'month':
+      return {
+        from_date: format_input_date(startOfMonth(reference)),
+        to_date: format_input_date(endOfMonth(reference)),
+      }
+    case 'last_month': {
+      const last_month = subMonths(reference, 1)
+
+      return {
+        from_date: format_input_date(startOfMonth(last_month)),
+        to_date: format_input_date(endOfMonth(last_month)),
+      }
+    }
+    case 'year':
+      return {
+        from_date: format_input_date(startOfYear(reference)),
+        to_date: format_input_date(endOfYear(reference)),
+      }
+    case 'last_year': {
+      const last_year = subYears(reference, 1)
+
+      return {
+        from_date: format_input_date(startOfYear(last_year)),
+        to_date: format_input_date(endOfYear(last_year)),
+      }
+    }
+    case 'today':
+    default: {
+      const day = startOfDay(reference)
+
+      return {
+        from_date: format_input_date(day),
+        to_date: format_input_date(day),
+      }
+    }
+  }
+}

package/lib/get_reporting_period_totals.ts

@@ -0,0 +1,39 @@
+import { get_period_range_ms } from '@/lib/get_period_range_ms'
+import { get_sheets_duration_in_range } from '@/lib/get_sheets_duration_in_range'
+import { type ReportingPeriodTotals } from '@/lib/types/reporting'
+import { type TimeSheet } from '@/lib/types'
+
+/**
+ * Builds today, week, and month totals with duration clipped to each period.
+ */
+export function get_reporting_period_totals(
+  sheets: TimeSheet[],
+  reference: Date = new Date(),
+  now: number = Date.now(),
+  week_starts_on: 0 | 1 = 1,
+): ReportingPeriodTotals {
+  const today_range = get_period_range_ms('today', reference, week_starts_on)
+  const week_range = get_period_range_ms('week', reference, week_starts_on)
+  const month_range = get_period_range_ms('month', reference, week_starts_on)
+
+  return {
+    todayMs: get_sheets_duration_in_range(
+      sheets,
+      today_range.startMs,
+      today_range.endMs,
+      now,
+    ),
+    weekMs: get_sheets_duration_in_range(
+      sheets,
+      week_range.startMs,
+      week_range.endMs,
+      now,
+    ),
+    monthMs: get_sheets_duration_in_range(
+      sheets,
+      month_range.startMs,
+      month_range.endMs,
+      now,
+    ),
+  }
+}

package/lib/get_reporting_stats.ts

@@ -0,0 +1,25 @@
+import { build_reporting_stats } from '@/lib/build_reporting_stats'
+import { read_db } from '@/lib/read_db'
+import { serialize_reporting_source_sheets } from '@/lib/serialize_reporting_source_sheets'
+import {
+  type ReportingSourceSheet,
+  type ReportingStats,
+} from '@/lib/types/reporting'
+
+export interface ReportingPageData {
+  sourceSheets: ReportingSourceSheet[]
+  stats: ReportingStats
+}
+
+/**
+ * Loads reporting source data and the default all-time snapshot.
+ */
+export async function get_reporting_stats(): Promise<ReportingPageData> {
+  const db = await read_db()
+  const source_sheets = serialize_reporting_source_sheets(db.sheets)
+
+  return {
+    sourceSheets: source_sheets,
+    stats: build_reporting_stats(db.sheets),
+  }
+}

package/lib/get_restore_db_confirm_dialog.ts

@@ -0,0 +1,14 @@
+import { type ConfirmDialogOptions } from '@/lib/types/confirm_dialog'
+
+/**
+ * Builds confirm dialog options for restoring a database backup.
+ */
+export function get_restore_db_confirm_dialog(): ConfirmDialogOptions {
+  return {
+    title: 'Restore backup?',
+    message:
+      'This will replace your current time tracker data with the uploaded backup file. This cannot be undone.',
+    confirmLabel: 'Restore',
+    variant: 'danger',
+  }
+}

package/lib/get_running_entry_key.ts

@@ -0,0 +1,8 @@
+import { type SerializedEntry } from '@/lib/types/tracker_state'
+
+/**
+ * Stable key for a running entry across tracker state updates.
+ */
+export function get_running_entry_key(entry: SerializedEntry): string {
+  return `${entry.sheetName}:${entry.id}`
+}

package/lib/get_serialized_entries_total_ms.ts

@@ -0,0 +1,10 @@
+import { type SerializedEntry } from '@/lib/types/tracker_state'
+
+/**
+ * Sums duration milliseconds across serialized entries.
+ */
+export function get_serialized_entries_total_ms(
+  entries: SerializedEntry[],
+): number {
+  return entries.reduce((total, entry) => total + entry.durationMs, 0)
+}

package/lib/get_sheet.ts

@@ -0,0 +1,14 @@
+import { type TimeSheet, type TimeTrackerDB } from "@/lib/types";
+
+/**
+ * Returns a sheet by name or throws when it does not exist.
+ */
+export function get_sheet(db: TimeTrackerDB, sheet_name: string): TimeSheet {
+  const sheet = db.sheets.find(({ name }) => name === sheet_name);
+
+  if (sheet === undefined) {
+    throw new Error(`Sheet ${sheet_name} not found`);
+  }
+
+  return sheet;
+}

package/lib/get_sheet_report_stats.ts

@@ -0,0 +1,22 @@
+import { get_average_entry_ms } from '@/lib/get_average_entry_ms'
+import { get_serialized_entries_total_ms } from '@/lib/get_serialized_entries_total_ms'
+import { serialize_sheet_entries } from '@/lib/serialize_sheet_entries'
+import { type SheetReportStats } from '@/lib/types/reporting'
+import { type TimeSheet } from '@/lib/types'
+
+/**
+ * Builds per-sheet time-tracking aggregates from a time sheet.
+ */
+export function get_sheet_report_stats(sheet: TimeSheet): SheetReportStats {
+  const entries = serialize_sheet_entries(sheet)
+  const entry_count = sheet.entries.length
+  const total_ms = get_serialized_entries_total_ms(entries)
+
+  return {
+    sheetName: sheet.name,
+    totalMs: total_ms,
+    entryCount: entry_count,
+    averageEntryMs: get_average_entry_ms(total_ms, entry_count),
+    hasActiveEntry: sheet.activeEntryID !== null,
+  }
+}

package/lib/get_sheet_report_stats_for_range.ts

@@ -0,0 +1,46 @@
+import { get_average_entry_ms } from '@/lib/get_average_entry_ms'
+import { get_clipped_entry_duration_ms } from '@/lib/get_clipped_entry_duration_ms'
+import { type SheetReportStats } from '@/lib/types/reporting'
+import { type TimeSheet } from '@/lib/types'
+
+/**
+ * Builds per-sheet aggregates with durations clipped to a date range.
+ */
+export function get_sheet_report_stats_for_range(
+  sheet: TimeSheet,
+  range_start_ms: number,
+  range_end_ms: number,
+  now: number = Date.now(),
+): SheetReportStats {
+  let total_ms = 0
+  let entry_count = 0
+  let has_active_entry = false
+
+  for (const entry of sheet.entries) {
+    const clipped_ms = get_clipped_entry_duration_ms(
+      entry,
+      range_start_ms,
+      range_end_ms,
+      now,
+    )
+
+    if (clipped_ms <= 0) {
+      continue
+    }
+
+    total_ms += clipped_ms
+    entry_count += 1
+
+    if (sheet.activeEntryID === entry.id && entry.end === null) {
+      has_active_entry = true
+    }
+  }
+
+  return {
+    sheetName: sheet.name,
+    totalMs: total_ms,
+    entryCount: entry_count,
+    averageEntryMs: get_average_entry_ms(total_ms, entry_count),
+    hasActiveEntry: has_active_entry,
+  }
+}

package/lib/get_sheet_tag_filter_snapshot.ts

@@ -0,0 +1,22 @@
+import { read_sheet_tag_filter } from '@/lib/read_sheet_tag_filter'
+import {
+  EMPTY_SHEET_TAG_FILTER,
+  get_stable_sheet_tag_filter_snapshot,
+} from '@/lib/sheet_tag_filter_snapshots'
+
+/**
+ * Returns the sheet tag filter snapshot from localStorage (client-only).
+ */
+export function get_sheet_tag_filter_snapshot(sheet_name: string): readonly string[] {
+  return get_stable_sheet_tag_filter_snapshot(
+    sheet_name,
+    read_sheet_tag_filter(sheet_name),
+  )
+}
+
+/**
+ * Returns the sheet tag filter snapshot used during server rendering.
+ */
+export function get_sheet_tag_filter_server_snapshot(): readonly string[] {
+  return EMPTY_SHEET_TAG_FILTER
+}

package/lib/get_sheets_duration_in_range.ts

@@ -0,0 +1,27 @@
+import { get_clipped_entry_duration_ms } from '@/lib/get_clipped_entry_duration_ms'
+import { type TimeSheet } from '@/lib/types'
+
+/**
+ * Sums clipped entry durations across all sheets within a time range.
+ */
+export function get_sheets_duration_in_range(
+  sheets: TimeSheet[],
+  range_start_ms: number,
+  range_end_ms: number,
+  now: number = Date.now(),
+): number {
+  let total_ms = 0
+
+  for (const sheet of sheets) {
+    for (const entry of sheet.entries) {
+      total_ms += get_clipped_entry_duration_ms(
+        entry,
+        range_start_ms,
+        range_end_ms,
+        now,
+      )
+    }
+  }
+
+  return total_ms
+}

package/lib/get_tag_autocomplete_context.ts

@@ -0,0 +1,32 @@
+export interface TagAutocompleteContext {
+  query: string
+  start_index: number
+  end_index: number
+}
+
+/**
+ * Returns tag autocomplete context when the cursor is after an open @ token.
+ */
+export function get_tag_autocomplete_context(
+  text: string,
+  cursor_index: number,
+): TagAutocompleteContext | null {
+  const before_cursor = text.slice(0, cursor_index)
+  const at_index = before_cursor.lastIndexOf('@')
+
+  if (at_index === -1) {
+    return null
+  }
+
+  const query = before_cursor.slice(at_index + 1)
+
+  if (/\s/.test(query)) {
+    return null
+  }
+
+  return {
+    query,
+    start_index: at_index,
+    end_index: cursor_index,
+  }
+}

package/lib/get_theme_snapshot.ts

@@ -0,0 +1,16 @@
+import { read_document_theme } from "@/lib/read_document_theme";
+import { type Theme } from "@/lib/types/theme";
+
+/**
+ * Returns the theme snapshot read from the document (client-only).
+ */
+export function get_theme_snapshot(): Theme {
+  return read_document_theme();
+}
+
+/**
+ * Returns the theme snapshot used during server rendering.
+ */
+export function get_theme_server_snapshot(): Theme {
+  return "dark";
+}

package/lib/get_tracker_state.ts

@@ -0,0 +1,67 @@
+import { collect_known_tags } from '@/lib/collect_known_tags'
+import { DB_PATH } from '@/lib/config'
+import { get_sheet } from '@/lib/get_sheet'
+import { get_serialized_entries_total_ms } from '@/lib/get_serialized_entries_total_ms'
+import { read_db } from '@/lib/read_db'
+import { resolve_active_sheet_name } from '@/lib/resolve_active_sheet_name'
+import { find_all_serialized_active_entries } from '@/lib/find_all_serialized_active_entries'
+import { find_serialized_active_entry_for_sheet } from '@/lib/find_serialized_active_entry_for_sheet'
+import { serialize_sheet_entries } from '@/lib/serialize_sheet_entries'
+import { set_active_sheet } from '@/lib/set_active_sheet'
+import { sort_serialized_entries } from '@/lib/sort_serialized_entries'
+import {
+  type SerializedEntry,
+  type TrackerState,
+} from '@/lib/types/tracker_state'
+
+/**
+ * Builds the tracker snapshot consumed by the web UI.
+ */
+export async function get_tracker_state(
+  preferred_sheet_name?: string | null,
+): Promise<TrackerState> {
+  const db = await read_db()
+  const resolved_sheet_name = resolve_active_sheet_name(db, preferred_sheet_name)
+
+  if (db.activeSheetName !== resolved_sheet_name) {
+    await set_active_sheet(resolved_sheet_name)
+    db.activeSheetName = resolved_sheet_name
+  }
+
+  const { activeSheetName, sheets } = db
+
+  let active_sheet_entries: SerializedEntry[] = []
+
+  if (activeSheetName !== null) {
+    const sheet = get_sheet(db, activeSheetName)
+
+    active_sheet_entries = sort_serialized_entries(
+      serialize_sheet_entries(sheet),
+    )
+  }
+
+  const active_sheet_entry =
+    activeSheetName !== null
+      ? find_serialized_active_entry_for_sheet(db, activeSheetName)
+      : null
+  const running_entries = find_all_serialized_active_entries(db)
+  const running_entry = active_sheet_entry ?? running_entries[0] ?? null
+
+  return {
+    dbPath: DB_PATH,
+    activeSheetName,
+    knownTags: collect_known_tags(db),
+    sheets: sheets.map((sheet) => ({
+      name: sheet.name,
+      activeEntryID: sheet.activeEntryID,
+      entryCount: sheet.entries.length,
+      isActive: sheet.name === activeSheetName,
+      hasActiveEntry: sheet.activeEntryID !== null,
+    })),
+    activeEntry: active_sheet_entry,
+    runningEntry: running_entry,
+    runningEntries: running_entries,
+    activeSheetEntries: active_sheet_entries,
+    activeSheetTotalMs: get_serialized_entries_total_ms(active_sheet_entries),
+  }
+}

package/lib/has_string_value.ts

@@ -0,0 +1,6 @@
+/**
+ * Returns true when the value is a defined, non-empty string.
+ */
+export function has_string_value(value: string | undefined): value is string {
+  return value !== undefined && value.trim().length > 0;
+}

package/lib/is_entry_in_day.ts

@@ -0,0 +1,15 @@
+import { endOfDay, startOfDay } from "date-fns";
+
+import { type TimeSheetEntry } from "@/lib/types";
+
+/**
+ * Returns whether an entry overlaps any time on the given calendar day.
+ */
+export function is_entry_in_day(date: Date, entry: TimeSheetEntry): boolean {
+  const { end, start } = entry;
+  const start_of_day = startOfDay(date);
+  const end_of_day = endOfDay(date);
+  const effective_end = end ?? new Date();
+
+  return +start <= +end_of_day && +effective_end >= +start_of_day;
+}

package/lib/is_idle_sheet_report.ts

@@ -0,0 +1,8 @@
+import { type SheetReportStats } from '@/lib/types/reporting'
+
+/**
+ * Returns whether a sheet has no entries or no tracked time.
+ */
+export function is_idle_sheet_report(sheet: SheetReportStats): boolean {
+  return sheet.entryCount === 0 || sheet.totalMs === 0
+}

package/lib/is_json_time_tracker_db.ts

@@ -0,0 +1,14 @@
+import { type JSONTimeTrackerDB } from '@/lib/types'
+
+/**
+ * Returns whether a value looks like a serialized time tracker database.
+ */
+export function is_json_time_tracker_db(value: unknown): value is JSONTimeTrackerDB {
+  if (typeof value !== 'object' || value === null) {
+    return false
+  }
+
+  const candidate = value as JSONTimeTrackerDB
+
+  return Array.isArray(candidate.sheets)
+}