super-time-tracker-ui 0.1.2

package/lib/apply_accent_color.ts

@@ -0,0 +1,12 @@
+import { type AccentColor } from '@/lib/types/ui_preferences'
+
+/**
+ * Sets the active accent color on the document element.
+ */
+export function apply_accent_color(value: AccentColor): void {
+  if (typeof document === 'undefined') {
+    return
+  }
+
+  document.documentElement.setAttribute('data-accent', value)
+}

package/lib/apply_color_palette.ts

@@ -0,0 +1,12 @@
+import { type ColorPalette } from '@/lib/types/ui_preferences'
+
+/**
+ * Sets the active color palette on the document element.
+ */
+export function apply_color_palette(value: ColorPalette): void {
+  if (typeof document === 'undefined') {
+    return
+  }
+
+  document.documentElement.setAttribute('data-palette', value)
+}

package/lib/apply_compact_lists.ts

@@ -0,0 +1,9 @@
+/**
+ * Applies the compact lists setting to the document root element.
+ */
+export function apply_compact_lists(enabled: boolean): void {
+  document.documentElement.setAttribute(
+    "data-compact-lists",
+    enabled ? "true" : "false",
+  );
+}

package/lib/apply_tag_autocomplete_selection.ts

@@ -0,0 +1,26 @@
+import { format_display_tag } from '@/lib/format_display_tag'
+import { type TagAutocompleteContext } from '@/lib/get_tag_autocomplete_context'
+
+export interface TagAutocompleteSelectionResult {
+  next_text: string
+  next_cursor: number
+}
+
+/**
+ * Inserts a selected tag into the description at the active @ token.
+ */
+export function apply_tag_autocomplete_selection(
+  text: string,
+  context: TagAutocompleteContext,
+  tag: string,
+): TagAutocompleteSelectionResult {
+  const formatted_tag = format_display_tag(tag)
+  const before = text.slice(0, context.start_index)
+  const after = text.slice(context.end_index)
+  const next_text = `${before}${formatted_tag}${after}`
+
+  return {
+    next_text,
+    next_cursor: before.length + formatted_tag.length,
+  }
+}

package/lib/apply_theme.ts

@@ -0,0 +1,8 @@
+import { type Theme } from "@/lib/types/theme";
+
+/**
+ * Applies the theme to the document root element.
+ */
+export function apply_theme(theme: Theme): void {
+  document.documentElement.setAttribute("data-theme", theme);
+}

package/lib/build_reporting_stats.ts

@@ -0,0 +1,55 @@
+import { get_average_entry_ms } from '@/lib/get_average_entry_ms'
+import { type PeriodRangeMs } from '@/lib/get_period_range_ms'
+import { get_reporting_period_totals } from '@/lib/get_reporting_period_totals'
+import { get_sheet_report_stats } from '@/lib/get_sheet_report_stats'
+import { get_sheet_report_stats_for_range } from '@/lib/get_sheet_report_stats_for_range'
+import { partition_sheet_report_stats } from '@/lib/partition_sheet_report_stats'
+import { type ReportingStats } from '@/lib/types/reporting'
+import { type TimeSheet } from '@/lib/types'
+
+/**
+ * Builds a full reporting snapshot, optionally clipped to a date range.
+ */
+export function build_reporting_stats(
+  sheets: TimeSheet[],
+  range: PeriodRangeMs | null = null,
+  now: number = Date.now(),
+  week_starts_on: 0 | 1 = 1,
+): ReportingStats {
+  const sheet_stats = sheets.map((sheet) =>
+    range === null
+      ? get_sheet_report_stats(sheet)
+      : get_sheet_report_stats_for_range(
+          sheet,
+          range.startMs,
+          range.endMs,
+          now,
+        ),
+  )
+  const { activeSheets, idleSheets } = partition_sheet_report_stats(sheet_stats)
+  const grand_total_ms = sheet_stats.reduce(
+    (total, sheet) => total + sheet.totalMs,
+    0,
+  )
+  const total_entry_count = sheet_stats.reduce(
+    (total, sheet) => total + sheet.entryCount,
+    0,
+  )
+
+  return {
+    activeSheets,
+    idleSheets,
+    grandTotalMs: grand_total_ms,
+    totalEntryCount: total_entry_count,
+    grandAverageEntryMs: get_average_entry_ms(grand_total_ms, total_entry_count),
+    periodTotals:
+      range === null
+        ? get_reporting_period_totals(
+            sheets,
+            new Date(now),
+            now,
+            week_starts_on,
+          )
+        : { todayMs: 0, weekMs: 0, monthMs: 0 },
+  }
+}

package/lib/build_resume_description.ts

@@ -0,0 +1,15 @@
+import { format_display_tag } from "@/lib/format_display_tag";
+
+/**
+ * Builds a check-in description from a prior entry's text and tags.
+ */
+export function build_resume_description(
+  description: string,
+  tags: string[],
+): string {
+  const trimmed = description.trim();
+  const base = trimmed.length > 0 ? trimmed : "Untitled entry";
+  const tag_text = tags.map((tag) => format_display_tag(tag)).join(" ");
+
+  return tag_text.length > 0 ? `${base} ${tag_text}`.trim() : base;
+}

package/lib/check_in_entry.ts

@@ -0,0 +1,81 @@
+import { gen_sheet } from "@/lib/gen_db";
+import { get_sheet } from "@/lib/get_sheet";
+import { parse_entry_from_input } from "@/lib/parse_entry_from_input";
+import { parse_natural_language_date } from "@/lib/parse_natural_language_date";
+import { read_db } from "@/lib/read_db";
+import { write_db } from "@/lib/write_db";
+import { type TimeSheetEntry, type TimeTrackerDB } from "@/lib/types";
+
+export interface CheckInEntryArgs {
+  description: string;
+  sheet_name?: string;
+  note?: string;
+  at?: string;
+}
+
+/**
+ * Starts a new active entry on the requested or active sheet.
+ */
+export async function check_in_entry(
+  args: CheckInEntryArgs,
+): Promise<TimeSheetEntry> {
+  const { at, description, note, sheet_name: input_sheet_name } = args;
+  const db = await read_db();
+  const active_sheet_name = db.activeSheetName;
+  const sheet_name =
+    input_sheet_name === undefined || input_sheet_name.length === 0
+      ? active_sheet_name
+      : input_sheet_name;
+
+  if (sheet_name === null) {
+    throw new Error("No active sheet");
+  }
+
+  const sheet_exists = db.sheets.some(({ name }) => name === sheet_name);
+  const sheet = sheet_exists
+    ? get_sheet(db, sheet_name)
+    : add_sheet_to_db(db, sheet_name);
+
+  if (sheet.activeEntryID !== null) {
+    const entry = sheet.entries.find(({ id }) => id === sheet.activeEntryID);
+
+    if (entry !== undefined) {
+      throw new Error(
+        `An entry is already active (${entry.id}): ${entry.description}`,
+      );
+    }
+
+    sheet.activeEntryID = null;
+  }
+
+  const start_date =
+    at === undefined || at.trim().length === 0
+      ? new Date()
+      : parse_natural_language_date(at);
+
+  const id = sheet.entries.length;
+  const parsed = parse_entry_from_input(id, description, start_date);
+  const entry: TimeSheetEntry = {
+    ...parsed,
+    description:
+      parsed.description.length > 0 ? parsed.description : description.trim(),
+  };
+
+  if (note !== undefined && note.length > 0) {
+    entry.notes.push({ timestamp: new Date(), text: note });
+  }
+
+  sheet.entries.push(entry);
+  sheet.activeEntryID = id;
+  db.activeSheetName = sheet.name;
+
+  await write_db(db);
+
+  return entry;
+}
+
+function add_sheet_to_db(db: TimeTrackerDB, sheet_name: string) {
+  const sheet = gen_sheet(sheet_name);
+  db.sheets.push(sheet);
+  return sheet;
+}

package/lib/check_out_entry.ts

@@ -0,0 +1,75 @@
+import { find_sheet_with_active_entry } from "@/lib/find_sheet_with_active_entry";
+import { get_sheet } from "@/lib/get_sheet";
+import { parse_natural_language_date } from "@/lib/parse_natural_language_date";
+import { read_db } from "@/lib/read_db";
+import { validate_entry_times } from "@/lib/validate_entry_times";
+import { write_db } from "@/lib/write_db";
+import { type TimeSheetEntry } from "@/lib/types";
+
+export interface CheckOutEntryArgs {
+  sheet_name?: string;
+  note?: string;
+  at?: string;
+}
+
+/**
+ * Checks out of the active entry on the requested or active sheet.
+ */
+export async function check_out_entry(
+  args: CheckOutEntryArgs = {},
+): Promise<TimeSheetEntry> {
+  const { at, note, sheet_name: input_sheet_name } = args;
+  const db = await read_db();
+  const sheet = resolve_check_out_sheet(db, input_sheet_name);
+  const { activeEntryID, name: sheet_name } = sheet;
+
+  if (activeEntryID === null) {
+    throw new Error(`No active entry for sheet ${sheet_name}`);
+  }
+
+  const entry = sheet.entries.find(({ id }) => id === activeEntryID);
+
+  if (entry === undefined) {
+    throw new Error(`No entry found with ID ${activeEntryID}`);
+  }
+
+  const end_date =
+    at === undefined || at.trim().length === 0
+      ? new Date()
+      : parse_natural_language_date(at);
+
+  entry.end = end_date;
+  sheet.activeEntryID = null;
+  validate_entry_times(entry.start, entry.end);
+
+  if (note !== undefined && note.length > 0) {
+    entry.notes.push({ timestamp: new Date(), text: note });
+  }
+
+  await write_db(db);
+
+  return entry;
+}
+
+function resolve_check_out_sheet(
+  db: Awaited<ReturnType<typeof read_db>>,
+  input_sheet_name: string | undefined,
+) {
+  if (input_sheet_name !== undefined && input_sheet_name.length > 0) {
+    return get_sheet(db, input_sheet_name);
+  }
+
+  const sheet_with_running_entry = find_sheet_with_active_entry(db);
+
+  if (sheet_with_running_entry !== null) {
+    return sheet_with_running_entry;
+  }
+
+  const active_sheet_name = db.activeSheetName;
+
+  if (active_sheet_name === null) {
+    throw new Error("No active sheet");
+  }
+
+  return get_sheet(db, active_sheet_name);
+}

package/lib/collect_known_tags.ts

@@ -0,0 +1,22 @@
+import { type TimeTrackerDB } from '@/lib/types'
+
+/**
+ * Collects unique tags from every entry in the database.
+ */
+export function collect_known_tags(db: TimeTrackerDB): string[] {
+  const tags = new Set<string>()
+
+  for (const sheet of db.sheets) {
+    for (const entry of sheet.entries) {
+      for (const tag of entry.tags) {
+        const trimmed = tag.trim()
+
+        if (trimmed.length > 0) {
+          tags.add(trimmed)
+        }
+      }
+    }
+  }
+
+  return [...tags].sort((left, right) => left.localeCompare(right))
+}

package/lib/collect_tag_stats.ts

@@ -0,0 +1,27 @@
+import { normalize_stored_tag } from '@/lib/normalize_stored_tag'
+import { type TagStat } from '@/lib/types/tag_management'
+import { type TimeTrackerDB } from '@/lib/types'
+
+/**
+ * Builds tag usage counts from every entry in the database.
+ */
+export function collect_tag_stats(db: TimeTrackerDB): TagStat[] {
+  const counts = new Map<string, number>()
+
+  for (const sheet of db.sheets) {
+    for (const entry of sheet.entries) {
+      for (const tag of entry.tags) {
+        try {
+          const normalized = normalize_stored_tag(tag)
+          counts.set(normalized, (counts.get(normalized) ?? 0) + 1)
+        } catch {
+          continue
+        }
+      }
+    }
+  }
+
+  return [...counts.entries()]
+    .map(([name, entryCount]) => ({ name, entryCount }))
+    .sort((left, right) => left.name.localeCompare(right.name))
+}

package/lib/collect_tags_from_entries.ts

@@ -0,0 +1,35 @@
+import { normalize_stored_tag } from '@/lib/normalize_stored_tag'
+import { type TagStat } from '@/lib/types/tag_management'
+import { type SerializedEntry } from '@/lib/types/tracker_state'
+
+/**
+ * Builds tag usage counts from a list of serialized entries.
+ */
+export function collect_tags_from_entries(
+  entries: SerializedEntry[],
+): TagStat[] {
+  const counts = new Map<string, number>()
+
+  for (const entry of entries) {
+    const seen_on_entry = new Set<string>()
+
+    for (const tag of entry.tags) {
+      try {
+        const normalized = normalize_stored_tag(tag)
+
+        if (seen_on_entry.has(normalized)) {
+          continue
+        }
+
+        seen_on_entry.add(normalized)
+        counts.set(normalized, (counts.get(normalized) ?? 0) + 1)
+      } catch {
+        continue
+      }
+    }
+  }
+
+  return [...counts.entries()]
+    .map(([name, entryCount]) => ({ name, entryCount }))
+    .sort((left, right) => left.name.localeCompare(right.name))
+}

package/lib/config.ts

@@ -0,0 +1,9 @@
+import os from "node:os";
+import path from "node:path";
+
+export const DB_FILE_NAME = "db.json";
+export const DEFAULT_SHEET_NAME = "main";
+export const STORAGE_DIR_NAME = ".super-time-tracker";
+export const STORAGE_PATH = path.join(os.homedir(), STORAGE_DIR_NAME);
+export const DB_PATH = path.join(STORAGE_PATH, DB_FILE_NAME);
+export const DB_VERSION = 3;

package/lib/convert_json_db.ts

@@ -0,0 +1,49 @@
+import { type JSONTimeTrackerDB, type TimeTrackerDB } from "@/lib/types";
+
+/**
+ * Converts a JSON-serialized DB into in-memory Date instances.
+ */
+export function convert_json_db(json_db: JSONTimeTrackerDB): TimeTrackerDB {
+  const {
+    sheets: json_sheets,
+    version: json_version,
+    activeSheetName: json_active_sheet_name,
+  } = json_db;
+
+  const sheets = json_sheets.map(
+    ({
+      name: json_name,
+      entries: json_entries,
+      activeEntryID: json_active_entry_id,
+    }) => ({
+      name: json_name,
+      activeEntryID: json_active_entry_id,
+      entries: json_entries.map(
+        ({
+          id: json_id,
+          start: json_start,
+          end: json_end,
+          description: json_description,
+          tags: json_tags,
+          notes: json_notes,
+        }) => ({
+          id: json_id,
+          description: json_description,
+          tags: json_tags,
+          notes: json_notes.map(({ timestamp, text }) => ({
+            text,
+            timestamp: new Date(timestamp),
+          })),
+          start: new Date(json_start),
+          end: json_end === null ? null : new Date(json_end),
+        }),
+      ),
+    }),
+  );
+
+  return {
+    version: json_version,
+    activeSheetName: json_active_sheet_name,
+    sheets,
+  };
+}

package/lib/delete_entries.ts

@@ -0,0 +1,62 @@
+import { get_sheet } from '@/lib/get_sheet'
+import { read_db } from '@/lib/read_db'
+import { write_db } from '@/lib/write_db'
+
+export interface DeleteEntryRef {
+  sheet_name: string
+  entry_id: number
+}
+
+export interface DeleteEntriesArgs {
+  entries: DeleteEntryRef[]
+}
+
+/**
+ * Deletes multiple entries across sheets in a single database write.
+ */
+export async function delete_entries(args: DeleteEntriesArgs): Promise<void> {
+  const { entries } = args
+
+  if (entries.length === 0) {
+    throw new Error('No entries selected')
+  }
+
+  const db = await read_db()
+  const seen = new Set<string>()
+  const by_sheet = new Map<string, number[]>()
+
+  for (const { entry_id, sheet_name } of entries) {
+    const key = `${sheet_name}:${entry_id}`
+
+    if (seen.has(key)) {
+      continue
+    }
+
+    seen.add(key)
+
+    const list = by_sheet.get(sheet_name) ?? []
+    list.push(entry_id)
+    by_sheet.set(sheet_name, list)
+  }
+
+  for (const [sheet_name, ids] of by_sheet) {
+    const sheet = get_sheet(db, sheet_name)
+    const ids_to_remove = [...ids].sort((left, right) => right - left)
+
+    for (const entry_id of ids_to_remove) {
+      const entry_index = sheet.entries.findIndex(({ id }) => id === entry_id)
+
+      if (entry_index === -1) {
+        continue
+      }
+
+      if (sheet.activeEntryID === entry_id) {
+        sheet.activeEntryID = null
+      }
+
+      sheet.entries.splice(entry_index, 1)
+    }
+  }
+
+  await write_db(db)
+}

package/lib/delete_entry.ts

@@ -0,0 +1,29 @@
+import { get_sheet } from "@/lib/get_sheet";
+import { read_db } from "@/lib/read_db";
+import { write_db } from "@/lib/write_db";
+
+export interface DeleteEntryArgs {
+  sheet_name: string;
+  entry_id: number;
+}
+
+/**
+ * Deletes an entry from a sheet.
+ */
+export async function delete_entry(args: DeleteEntryArgs): Promise<void> {
+  const { entry_id, sheet_name } = args;
+  const db = await read_db();
+  const sheet = get_sheet(db, sheet_name);
+  const entry_index = sheet.entries.findIndex(({ id }) => id === entry_id);
+
+  if (entry_index === -1) {
+    throw new Error(`Entry ${entry_id} not found in sheet ${sheet_name}`);
+  }
+
+  if (sheet.activeEntryID === entry_id) {
+    sheet.activeEntryID = null;
+  }
+
+  sheet.entries.splice(entry_index, 1);
+  await write_db(db);
+}

package/lib/delete_note_on_entry.ts

@@ -0,0 +1,42 @@
+import { get_sheet } from '@/lib/get_sheet'
+import { read_db } from '@/lib/read_db'
+import { write_db } from '@/lib/write_db'
+
+export interface DeleteNoteOnEntryArgs {
+  note_timestamp: string
+  sheet_name: string
+  entry_id: number
+}
+
+/**
+ * Removes a note from a time sheet entry by timestamp.
+ */
+export async function delete_note_on_entry(
+  args: DeleteNoteOnEntryArgs,
+): Promise<void> {
+  const { entry_id, note_timestamp, sheet_name } = args
+  const db = await read_db()
+  const sheet = get_sheet(db, sheet_name)
+  const entry = sheet.entries.find(({ id }) => id === entry_id)
+
+  if (entry === undefined) {
+    throw new Error(`Entry ${entry_id} not found in sheet ${sheet_name}`)
+  }
+
+  const target_ms = new Date(note_timestamp).getTime()
+
+  if (Number.isNaN(target_ms)) {
+    throw new Error('Invalid note timestamp')
+  }
+
+  const note_index = entry.notes.findIndex(
+    ({ timestamp }) => timestamp.getTime() === target_ms,
+  )
+
+  if (note_index === -1) {
+    throw new Error('Note not found on entry')
+  }
+
+  entry.notes.splice(note_index, 1)
+  await write_db(db)
+}

package/lib/delete_sheet.ts

@@ -0,0 +1,30 @@
+import { read_db } from "@/lib/read_db";
+import { write_db } from "@/lib/write_db";
+
+/**
+ * Removes a sheet and clears the active sheet when it was selected.
+ */
+export async function delete_sheet(sheet_name: string): Promise<void> {
+  const db = await read_db();
+  const sheet_index = db.sheets.findIndex(({ name }) => name === sheet_name);
+
+  if (sheet_index === -1) {
+    throw new Error(`Sheet ${sheet_name} not found`);
+  }
+
+  if (db.activeSheetName === sheet_name) {
+    db.activeSheetName = null;
+  }
+
+  db.sheets.splice(sheet_index, 1);
+
+  if (db.sheets.length === 0) {
+    throw new Error("Cannot delete the last sheet");
+  }
+
+  if (db.activeSheetName === null) {
+    db.activeSheetName = db.sheets[0]?.name ?? null;
+  }
+
+  await write_db(db);
+}

package/lib/delete_tracker_action.ts

@@ -0,0 +1,22 @@
+import { type TrackerState } from '@/lib/types/tracker_state'
+
+/**
+ * Sends a DELETE request to a tracker API route and returns updated state.
+ */
+export async function delete_tracker_action(
+  path: string,
+  body: unknown,
+): Promise<TrackerState> {
+  const response = await fetch(path, {
+    method: 'DELETE',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(body),
+  })
+
+  if (!response.ok) {
+    const payload = (await response.json()) as { error?: string }
+    throw new Error(payload.error ?? 'Request failed')
+  }
+
+  return (await response.json()) as TrackerState
+}