super-time-tracker-ui 0.1.2

package/lib/edit_entry.ts

@@ -0,0 +1,56 @@
+import { get_sheet } from "@/lib/get_sheet";
+import { has_string_value } from "@/lib/has_string_value";
+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 EditEntryArgs {
+  sheet_name: string;
+  entry_id: number;
+  start?: string;
+  end?: string;
+  description?: string;
+}
+
+/**
+ * Updates an entry's description and/or start and end times.
+ */
+export async function edit_entry(args: EditEntryArgs): Promise<TimeSheetEntry> {
+  const { description, end, entry_id, sheet_name, start } = 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}`);
+  }
+
+  let did_update = false;
+
+  if (has_string_value(description)) {
+    entry.description = description.trim();
+    did_update = true;
+  }
+
+  if (has_string_value(start)) {
+    entry.start = parse_natural_language_date(start);
+    did_update = true;
+  }
+
+  if (has_string_value(end)) {
+    entry.end = parse_natural_language_date(end);
+    did_update = true;
+  }
+
+  if (!did_update) {
+    throw new Error("No changes provided");
+  }
+
+  validate_entry_times(entry.start, entry.end);
+
+  await write_db(db);
+
+  return entry;
+}

package/lib/edit_note_on_entry.ts

@@ -0,0 +1,49 @@
+import { get_sheet } from "@/lib/get_sheet";
+import { read_db } from "@/lib/read_db";
+import { write_db } from "@/lib/write_db";
+
+export interface EditNoteOnEntryArgs {
+  text: string;
+  note_timestamp: string;
+  sheet_name: string;
+  entry_id: number;
+}
+
+/**
+ * Updates the text of an existing note on a time sheet entry.
+ */
+export async function edit_note_on_entry(
+  args: EditNoteOnEntryArgs,
+): Promise<void> {
+  const { entry_id, note_timestamp, sheet_name, text } = args;
+  const trimmed = text.trim();
+
+  if (trimmed.length === 0) {
+    throw new Error("Note text is required");
+  }
+
+  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 = entry.notes.find(
+    ({ timestamp }) => timestamp.getTime() === target_ms,
+  );
+
+  if (note === undefined) {
+    throw new Error("Note not found on entry");
+  }
+
+  note.text = trimmed;
+  await write_db(db);
+}

package/lib/ensure_dir_exists.ts

@@ -0,0 +1,22 @@
+import { promises as fs } from "node:fs";
+
+/**
+ * Ensures a directory exists, creating it recursively when missing.
+ */
+export async function ensure_dir_exists(dir_path: string): Promise<void> {
+  try {
+    await fs.mkdir(dir_path, { recursive: true });
+  } catch (err: unknown) {
+    const code =
+      err !== null &&
+      typeof err === "object" &&
+      "code" in err &&
+      typeof err.code === "string"
+        ? err.code
+        : null;
+
+    if (code !== "EEXIST") {
+      throw err;
+    }
+  }
+}

package/lib/entry_matches_tag_filter.ts

@@ -0,0 +1,26 @@
+import { tags_are_equal } from '@/lib/tags_are_equal'
+import { type TagFilterMode } from '@/lib/types/ui_preferences'
+import { type SerializedEntry } from '@/lib/types/tracker_state'
+
+/**
+ * Returns whether an entry matches the selected tag filter tags.
+ */
+export function entry_matches_tag_filter(
+  entry: SerializedEntry,
+  filter_tags: readonly string[],
+  mode: TagFilterMode = 'all',
+): boolean {
+  if (filter_tags.length === 0) {
+    return true
+  }
+
+  if (mode === 'any') {
+    return filter_tags.some((filter_tag) =>
+      entry.tags.some((entry_tag) => tags_are_equal(entry_tag, filter_tag)),
+    )
+  }
+
+  return filter_tags.every((filter_tag) =>
+    entry.tags.some((entry_tag) => tags_are_equal(entry_tag, filter_tag)),
+  )
+}

package/lib/fetch_tracker_state.ts

@@ -0,0 +1,15 @@
+import { type TrackerState } from "@/lib/types/tracker_state";
+
+/**
+ * Loads tracker state from the API.
+ */
+export async function fetch_tracker_state(): Promise<TrackerState> {
+  const response = await fetch("/api/state", { cache: "no-store" });
+
+  if (!response.ok) {
+    const body = (await response.json()) as { error?: string };
+    throw new Error(body.error ?? "Failed to load tracker state");
+  }
+
+  return (await response.json()) as TrackerState;
+}

package/lib/filter_entries_by_tags.ts

@@ -0,0 +1,20 @@
+import { entry_matches_tag_filter } from '@/lib/entry_matches_tag_filter'
+import { type TagFilterMode } from '@/lib/types/ui_preferences'
+import { type SerializedEntry } from '@/lib/types/tracker_state'
+
+/**
+ * Returns entries that match the selected filter tags.
+ */
+export function filter_entries_by_tags(
+  entries: SerializedEntry[],
+  filter_tags: readonly string[],
+  mode: TagFilterMode = 'all',
+): SerializedEntry[] {
+  if (filter_tags.length === 0) {
+    return entries
+  }
+
+  return entries.filter((entry) =>
+    entry_matches_tag_filter(entry, filter_tags, mode),
+  )
+}

package/lib/filter_known_tags.ts

@@ -0,0 +1,20 @@
+/**
+ * Returns known tags whose name matches the partial query after @.
+ */
+export function filter_known_tags(
+  known_tags: string[],
+  query: string,
+  limit: number = 10,
+): string[] {
+  const normalized_query = query.toLowerCase()
+
+  return known_tags
+    .filter((tag) => {
+      const name = tag.replace(/^@/, '').toLowerCase()
+
+      return (
+        normalized_query.length === 0 || name.startsWith(normalized_query)
+      )
+    })
+    .slice(0, limit)
+}

package/lib/find_all_serialized_active_entries.ts

@@ -0,0 +1,28 @@
+import { serialize_entry } from '@/lib/serialize_entry'
+import { type SerializedEntry } from '@/lib/types/tracker_state'
+import { type TimeTrackerDB } from '@/lib/types'
+
+/**
+ * Returns every running entry across all sheets, in sheet order.
+ */
+export function find_all_serialized_active_entries(
+  db: TimeTrackerDB,
+): SerializedEntry[] {
+  const results: SerializedEntry[] = []
+
+  for (const sheet of db.sheets) {
+    const { activeEntryID, entries, name } = sheet
+
+    if (activeEntryID === null) {
+      continue
+    }
+
+    const entry = entries.find(({ id }) => id === activeEntryID)
+
+    if (entry !== undefined && entry.end === null) {
+      results.push(serialize_entry(entry, name, true))
+    }
+  }
+
+  return results
+}

package/lib/find_serialized_active_entry.ts

@@ -0,0 +1,12 @@
+import { find_all_serialized_active_entries } from '@/lib/find_all_serialized_active_entries'
+import { type SerializedEntry } from '@/lib/types/tracker_state'
+import { type TimeTrackerDB } from '@/lib/types'
+
+/**
+ * Returns the first running entry from any sheet, if one exists.
+ */
+export function find_serialized_active_entry(
+  db: TimeTrackerDB,
+): SerializedEntry | null {
+  return find_all_serialized_active_entries(db)[0] ?? null
+}

package/lib/find_serialized_active_entry_for_sheet.ts

@@ -0,0 +1,31 @@
+import { serialize_entry } from '@/lib/serialize_entry'
+import { type SerializedEntry } from '@/lib/types/tracker_state'
+import { type TimeTrackerDB } from '@/lib/types'
+
+/**
+ * Returns the running entry on a specific sheet, if one exists.
+ */
+export function find_serialized_active_entry_for_sheet(
+  db: TimeTrackerDB,
+  sheet_name: string,
+): SerializedEntry | null {
+  const sheet = db.sheets.find(({ name }) => name === sheet_name)
+
+  if (sheet === undefined) {
+    return null
+  }
+
+  const { activeEntryID, entries, name } = sheet
+
+  if (activeEntryID === null) {
+    return null
+  }
+
+  const entry = entries.find(({ id }) => id === activeEntryID)
+
+  if (entry === undefined) {
+    return null
+  }
+
+  return serialize_entry(entry, name, entry.end === null)
+}

package/lib/find_sheet_with_active_entry.ts

@@ -0,0 +1,16 @@
+import { type TimeSheet, type TimeTrackerDB } from '@/lib/types'
+
+/**
+ * Returns the sheet that has a running entry, if one exists.
+ */
+export function find_sheet_with_active_entry(
+  db: TimeTrackerDB,
+): TimeSheet | null {
+  for (const sheet of db.sheets) {
+    if (sheet.activeEntryID !== null) {
+      return sheet
+    }
+  }
+
+  return null
+}

package/lib/format_display_tag.ts

@@ -0,0 +1,6 @@
+/**
+ * Formats a tag for display, ensuring it is prefixed with @.
+ */
+export function format_display_tag(tag: string): string {
+  return tag.startsWith("@") ? tag : `@${tag}`;
+}

package/lib/format_duration.ts

@@ -0,0 +1,45 @@
+import humanizeDuration from 'humanize-duration'
+
+import { type DurationFormat } from '@/lib/types/ui_preferences'
+
+const pad = (value: number): string => value.toString().padStart(2, '0')
+
+const format_clock = (duration_ms: number): string => {
+  const sign = duration_ms < 0 ? '-' : ''
+  const total_seconds = Math.round(Math.abs(duration_ms) / 1000)
+  const hours = Math.floor(total_seconds / 3600)
+  const minutes = Math.floor((total_seconds % 3600) / 60)
+  const seconds = total_seconds % 60
+
+  return `${sign}${pad(hours)}:${pad(minutes)}:${pad(seconds)}`
+}
+
+const format_decimal = (duration_ms: number): string => {
+  const hours = duration_ms / 3_600_000
+
+  return `${hours.toFixed(2)}h`
+}
+
+/**
+ * Formats a duration in milliseconds using the preferred format.
+ */
+export function format_duration(
+  duration_ms: number,
+  duration_format: DurationFormat = 'humanized',
+  show_seconds = false,
+): string {
+  if (duration_format === 'clock') {
+    return format_clock(duration_ms)
+  }
+
+  if (duration_format === 'decimal') {
+    return format_decimal(duration_ms)
+  }
+
+  return humanizeDuration(duration_ms, {
+    largest: show_seconds ? 3 : 2,
+    round: !show_seconds,
+    spacer: ' ',
+    delimiter: ' ',
+  })
+}

package/lib/gen_db.ts

@@ -0,0 +1,43 @@
+import { DB_VERSION, DEFAULT_SHEET_NAME } from "@/lib/config";
+import {
+  type TimeSheet,
+  type TimeSheetEntry,
+  type TimeTrackerDB,
+} from "@/lib/types";
+
+/**
+ * Creates an empty sheet with optional entries and active entry.
+ */
+export function gen_sheet(
+  name: string,
+  entries: TimeSheetEntry[] = [],
+  active_entry_id: number | null = null,
+): TimeSheet {
+  if (name.length === 0) {
+    throw new Error("New sheet name must not be empty");
+  }
+
+  if (
+    active_entry_id !== null &&
+    entries.find(({ id }) => id === active_entry_id) === undefined
+  ) {
+    throw new Error("New sheet active entry does not exist");
+  }
+
+  return {
+    name,
+    entries,
+    activeEntryID: active_entry_id,
+  };
+}
+
+/**
+ * Creates a fresh time tracker database with the default sheet.
+ */
+export function gen_db(): TimeTrackerDB {
+  return {
+    version: DB_VERSION,
+    sheets: [gen_sheet(DEFAULT_SHEET_NAME)],
+    activeSheetName: DEFAULT_SHEET_NAME,
+  };
+}

package/lib/get_active_panel_class_name.ts

@@ -0,0 +1,20 @@
+/**
+ * Returns Tailwind classes for the active entry panel container.
+ */
+export function get_active_panel_class_name(
+  in_bar: boolean,
+  is_editing: boolean,
+): string {
+  const base =
+    'flex flex-col gap-4 rounded-lg border border-accent-border p-[1.1rem] shadow-sm'
+
+  if (!in_bar) {
+    return `${base} bg-[image:var(--active-panel-bg)]`
+  }
+
+  if (is_editing) {
+    return `${base} rounded-md border border-accent-border bg-[color-mix(in_srgb,var(--panel)_70%,var(--background))] p-3.5`
+  }
+
+  return 'flex flex-col gap-3.5 border-0 bg-transparent p-0 shadow-none'
+}

package/lib/get_average_entry_ms.ts

@@ -0,0 +1,13 @@
+/**
+ * Returns mean duration per entry, or zero when there are no entries.
+ */
+export function get_average_entry_ms(
+  total_ms: number,
+  entry_count: number,
+): number {
+  if (entry_count === 0) {
+    return 0
+  }
+
+  return total_ms / entry_count
+}

package/lib/get_button_class_name.ts

@@ -0,0 +1,24 @@
+export type ButtonVariant = 'primary' | 'ghost' | 'danger'
+export type ButtonSize = 'default' | 'small'
+
+/**
+ * Returns Tailwind classes for themed buttons.
+ */
+export function get_button_class_name(
+  variant: ButtonVariant = 'ghost',
+  size: ButtonSize = 'default',
+): string {
+  const base =
+    'cursor-pointer rounded-[0.65rem] border border-transparent font-inherit font-semibold disabled:cursor-not-allowed disabled:opacity-55'
+  const sizes: Record<ButtonSize, string> = {
+    default: 'px-3.5 py-2.5',
+    small: 'px-2.5 py-1.5 text-xs',
+  }
+  const variants: Record<ButtonVariant, string> = {
+    primary: 'bg-accent text-accent-text-on',
+    ghost: 'border-panel-border bg-ghost-bg text-inherit',
+    danger: 'border-danger-border bg-danger-soft text-danger',
+  }
+
+  return `${base} ${sizes[size]} ${variants[variant]}`
+}

package/lib/get_check_out_confirm_dialog.ts

@@ -0,0 +1,19 @@
+import { type ConfirmDialogOptions } from '@/lib/types/confirm_dialog'
+
+/**
+ * Builds confirm dialog options for checking out of an active timer.
+ */
+export function get_check_out_confirm_dialog(at?: string): ConfirmDialogOptions {
+  const trimmed_at = at?.trim() ?? ''
+  const message =
+    trimmed_at.length > 0
+      ? `Stop the timer and check out at "${trimmed_at}"?`
+      : 'Stop the active timer and save this entry?'
+
+  return {
+    title: 'Check out?',
+    message,
+    confirmLabel: 'Check out',
+    variant: 'danger',
+  }
+}

package/lib/get_clipped_entry_duration_ms.ts

@@ -0,0 +1,18 @@
+import { type TimeSheetEntry } from '@/lib/types'
+
+/**
+ * Returns entry duration in milliseconds clipped to an inclusive time range.
+ */
+export function get_clipped_entry_duration_ms(
+  entry: TimeSheetEntry,
+  range_start_ms: number,
+  range_end_ms: number,
+  now: number = Date.now(),
+): number {
+  const entry_start_ms = +entry.start
+  const entry_end_ms = entry.end === null ? now : +entry.end
+  const clipped_start_ms = Math.max(entry_start_ms, range_start_ms)
+  const clipped_end_ms = Math.min(entry_end_ms, range_end_ms)
+
+  return Math.max(0, clipped_end_ms - clipped_start_ms)
+}

package/lib/get_compact_lists_snapshot.ts

@@ -0,0 +1,15 @@
+import { read_document_compact_lists } from "@/lib/read_document_compact_lists";
+
+/**
+ * Returns the compact lists snapshot from the document (client-only).
+ */
+export function get_compact_lists_snapshot(): boolean {
+  return read_document_compact_lists();
+}
+
+/**
+ * Returns the compact lists snapshot used during server rendering.
+ */
+export function get_compact_lists_server_snapshot(): boolean {
+  return false;
+}

package/lib/get_date_range_ms_from_inputs.ts

@@ -0,0 +1,31 @@
+import { endOfDay, parse, startOfDay } from 'date-fns'
+
+import { type PeriodRangeMs } from '@/lib/get_period_range_ms'
+
+/**
+ * Converts date input values into inclusive millisecond bounds, or null when unset.
+ */
+export function get_date_range_ms_from_inputs(
+  from_date: string,
+  to_date: string,
+): PeriodRangeMs | null {
+  if (from_date.length === 0 || to_date.length === 0) {
+    return null
+  }
+
+  const range_start = parse(from_date, 'yyyy-MM-dd', new Date())
+  const range_end = parse(to_date, 'yyyy-MM-dd', new Date())
+
+  if (Number.isNaN(+range_start) || Number.isNaN(+range_end)) {
+    return null
+  }
+
+  if (+range_start > +range_end) {
+    return null
+  }
+
+  return {
+    startMs: +startOfDay(range_start),
+    endMs: +endOfDay(range_end),
+  }
+}

package/lib/get_delete_entries_confirm_dialog.ts

@@ -0,0 +1,21 @@
+import { type ConfirmDialogOptions } from '@/lib/types/confirm_dialog'
+import { type SerializedEntry } from '@/lib/types/tracker_state'
+
+/**
+ * Builds confirm dialog options for deleting multiple time sheet entries.
+ */
+export function get_delete_entries_confirm_dialog(
+  entries: SerializedEntry[],
+): ConfirmDialogOptions {
+  const count = entries.length
+  const has_active = entries.some((entry) => entry.isActive)
+  const active_note = has_active ? ' This will stop the active timer.' : ''
+  const label = count === 1 ? '1 entry' : `${count} entries`
+
+  return {
+    title: count === 1 ? 'Delete entry?' : 'Delete entries?',
+    message: `Permanently delete ${label}?${active_note}`,
+    confirmLabel: 'Delete',
+    variant: 'danger',
+  }
+}

package/lib/get_delete_entry_confirm_dialog.ts

@@ -0,0 +1,19 @@
+import { type ConfirmDialogOptions } from '@/lib/types/confirm_dialog'
+import { type SerializedEntry } from '@/lib/types/tracker_state'
+
+/**
+ * Builds confirm dialog options for deleting a time sheet entry.
+ */
+export function get_delete_entry_confirm_dialog(
+  entry: SerializedEntry,
+): ConfirmDialogOptions {
+  const description = entry.description.trim() || 'Untitled entry'
+  const active_note = entry.isActive ? ' This will stop the active timer.' : ''
+
+  return {
+    title: 'Delete entry?',
+    message: `Delete "${description}" on sheet "${entry.sheetName}"?${active_note}`,
+    confirmLabel: 'Delete',
+    variant: 'danger',
+  }
+}

package/lib/get_delete_note_confirm_dialog.ts

@@ -0,0 +1,21 @@
+import { type ConfirmDialogOptions } from '@/lib/types/confirm_dialog'
+
+/**
+ * Builds confirm dialog options for deleting a note on an entry.
+ */
+export function get_delete_note_confirm_dialog(
+  note_text: string,
+): ConfirmDialogOptions {
+  const trimmed = note_text.trim()
+  const preview =
+    trimmed.length > 80 ? `${trimmed.slice(0, 80)}…` : trimmed
+  const message =
+    preview.length > 0 ? `Remove this note? "${preview}"` : 'Remove this note?'
+
+  return {
+    title: 'Delete note?',
+    message,
+    confirmLabel: 'Delete',
+    variant: 'danger',
+  }
+}

package/lib/get_delete_sheet_confirm_dialog.ts

@@ -0,0 +1,25 @@
+import { type ConfirmDialogOptions } from '@/lib/types/confirm_dialog'
+
+/**
+ * Builds confirm dialog options for deleting a time sheet.
+ */
+export function get_delete_sheet_confirm_dialog(
+  sheet_name: string,
+  entry_count: number,
+  has_active_entry: boolean,
+): ConfirmDialogOptions {
+  const entry_note =
+    entry_count === 0
+      ? ''
+      : ` This will delete ${entry_count} ${
+          entry_count === 1 ? 'entry' : 'entries'
+        }.`
+  const active_note = has_active_entry ? ' This will stop the active timer.' : ''
+
+  return {
+    title: 'Delete sheet?',
+    message: `Delete "${sheet_name}"?${entry_note}${active_note}`,
+    confirmLabel: 'Delete sheet',
+    variant: 'danger',
+  }
+}

package/lib/get_entry_duration_ms.ts

@@ -0,0 +1,14 @@
+import { type TimeSheetEntry } from "@/lib/types";
+
+/**
+ * Returns entry duration in milliseconds, using now when still active.
+ */
+export function get_entry_duration_ms(
+  entry: TimeSheetEntry,
+  now: number = Date.now(),
+): number {
+  const { end, start } = entry;
+  const effective_end = end === null ? now : +end;
+
+  return Math.max(0, effective_end - +start);
+}

package/lib/get_entry_row_key.ts

@@ -0,0 +1,8 @@
+import { type SerializedEntry } from "@/lib/types/tracker_state";
+
+/**
+ * Returns a stable row key for an entry in list UIs.
+ */
+export function get_entry_row_key(entry: SerializedEntry): string {
+  return `${entry.sheetName}-${entry.id}`;
+}