super-time-tracker-ui 0.1.2

package/lib/read_stored_sheet_tag_filters.ts

@@ -0,0 +1,28 @@
+import { SHEET_TAG_FILTERS_STORAGE_KEY } from '@/lib/types/ui_settings'
+
+/**
+ * Reads per-sheet tag filter selections from localStorage.
+ */
+export function read_stored_sheet_tag_filters(): Record<string, string[]> {
+  if (typeof window === 'undefined') {
+    return {}
+  }
+
+  try {
+    const raw = window.localStorage.getItem(SHEET_TAG_FILTERS_STORAGE_KEY)
+
+    if (raw === null) {
+      return {}
+    }
+
+    const parsed = JSON.parse(raw) as Record<string, string[]>
+
+    if (parsed === null || typeof parsed !== 'object') {
+      return {}
+    }
+
+    return parsed
+  } catch {
+    return {}
+  }
+}

package/lib/read_stored_theme.ts

@@ -0,0 +1,18 @@
+import { THEME_STORAGE_KEY, type Theme } from "@/lib/types/theme";
+
+/**
+ * Reads the persisted theme from localStorage, if present.
+ */
+export function read_stored_theme(): Theme | null {
+  if (typeof window === "undefined") {
+    return null;
+  }
+
+  const stored = window.localStorage.getItem(THEME_STORAGE_KEY);
+
+  if (stored === "light" || stored === "dark") {
+    return stored;
+  }
+
+  return null;
+}

package/lib/rename_sheet.ts

@@ -0,0 +1,39 @@
+import { get_sheet } from "@/lib/get_sheet";
+import { read_db } from "@/lib/read_db";
+import { write_db } from "@/lib/write_db";
+
+export interface RenameSheetArgs {
+  sheet_name: string;
+  new_name: string;
+}
+
+/**
+ * Renames a sheet and updates the active sheet pointer when needed.
+ */
+export async function rename_sheet(args: RenameSheetArgs): Promise<void> {
+  const { sheet_name } = args;
+  const trimmed = args.new_name.trim();
+
+  if (trimmed.length === 0) {
+    throw new Error("Sheet name must not be empty");
+  }
+
+  if (trimmed === sheet_name) {
+    return;
+  }
+
+  const db = await read_db();
+  const sheet = get_sheet(db, sheet_name);
+
+  if (db.sheets.some(({ name }) => name === trimmed)) {
+    throw new Error(`Sheet ${trimmed} already exists`);
+  }
+
+  sheet.name = trimmed;
+
+  if (db.activeSheetName === sheet_name) {
+    db.activeSheetName = trimmed;
+  }
+
+  await write_db(db);
+}

package/lib/rename_tag_across_db.ts

@@ -0,0 +1,19 @@
+import {
+  merge_tags_across_db,
+  type MergeTagsAcrossDbResult,
+} from '@/lib/merge_tags_across_db'
+import { tags_are_equal } from '@/lib/tags_are_equal'
+
+/**
+ * Renames a tag on every entry that uses it.
+ */
+export async function rename_tag_across_db(
+  from_tag: string,
+  to_tag: string,
+): Promise<MergeTagsAcrossDbResult> {
+  if (tags_are_equal(from_tag, to_tag)) {
+    throw new Error('Choose a different name for the tag.')
+  }
+
+  return merge_tags_across_db([from_tag], to_tag)
+}

package/lib/resolve_active_sheet_name.ts

@@ -0,0 +1,36 @@
+import { DEFAULT_SHEET_NAME } from '@/lib/config'
+import { type TimeTrackerDB } from '@/lib/types'
+
+/**
+ * Chooses which sheet to show: session preference, stored active sheet, then a running entry.
+ */
+export function resolve_active_sheet_name(
+  db: TimeTrackerDB,
+  preferred_sheet_name?: string | null,
+): string {
+  const trimmed_preference = preferred_sheet_name?.trim() ?? ''
+
+  if (
+    trimmed_preference.length > 0 &&
+    db.sheets.some((sheet) => sheet.name === trimmed_preference)
+  ) {
+    return trimmed_preference
+  }
+
+  if (
+    db.activeSheetName !== null &&
+    db.sheets.some((sheet) => sheet.name === db.activeSheetName)
+  ) {
+    return db.activeSheetName
+  }
+
+  const sheet_with_active_entry = db.sheets.find(
+    (sheet) => sheet.activeEntryID !== null,
+  )
+
+  if (sheet_with_active_entry !== undefined) {
+    return sheet_with_active_entry.name
+  }
+
+  return db.sheets[0]?.name ?? DEFAULT_SHEET_NAME
+}

package/lib/resolve_session_preferred_sheet.ts

@@ -0,0 +1,37 @@
+import { type DefaultSheetSessionMode } from '@/lib/types/ui_settings'
+import { type TimeTrackerDB } from '@/lib/types'
+
+/**
+ * Resolves which sheet name to prefer on a new session before DB fallbacks.
+ */
+export function resolve_session_preferred_sheet(
+  db: TimeTrackerDB,
+  mode: DefaultSheetSessionMode,
+  last_viewed_sheet: string | null,
+  fixed_sheet_name: string | null,
+): string | null {
+  switch (mode) {
+    case 'fixed': {
+      const trimmed = fixed_sheet_name?.trim() ?? ''
+
+      if (
+        trimmed.length > 0 &&
+        db.sheets.some((sheet) => sheet.name === trimmed)
+      ) {
+        return trimmed
+      }
+
+      return null
+    }
+    case 'active_timer': {
+      const sheet_with_timer = db.sheets.find(
+        (sheet) => sheet.activeEntryID !== null,
+      )
+
+      return sheet_with_timer?.name ?? null
+    }
+    case 'last_viewed':
+    default:
+      return last_viewed_sheet
+  }
+}

package/lib/resolve_theme.ts

@@ -0,0 +1,18 @@
+import { type Theme } from "@/lib/types/theme";
+
+/**
+ * Resolves the initial theme from storage or system preference.
+ */
+export function resolve_theme(stored: Theme | null): Theme {
+  if (stored !== null) {
+    return stored;
+  }
+
+  if (typeof window === "undefined") {
+    return "dark";
+  }
+
+  return window.matchMedia("(prefers-color-scheme: light)").matches
+    ? "light"
+    : "dark";
+}

package/lib/resolve_theme_mode_to_theme.ts

@@ -0,0 +1,19 @@
+import { type ThemeMode } from '@/lib/types/ui_preferences'
+import { type Theme } from '@/lib/types/theme'
+
+/**
+ * Resolves a theme mode preference to the applied light/dark theme.
+ */
+export function resolve_theme_mode_to_theme(mode: ThemeMode): Theme {
+  if (mode === 'light' || mode === 'dark') {
+    return mode
+  }
+
+  if (typeof window === 'undefined') {
+    return 'dark'
+  }
+
+  return window.matchMedia('(prefers-color-scheme: light)').matches
+    ? 'light'
+    : 'dark'
+}

package/lib/restore_db_from_uploaded_json.ts

@@ -0,0 +1,24 @@
+import { convert_json_db } from '@/lib/convert_json_db'
+import { is_json_time_tracker_db } from '@/lib/is_json_time_tracker_db'
+import { migrate_json_db } from '@/lib/migrate_json_db'
+import { write_db } from '@/lib/write_db'
+
+/**
+ * Replaces the on-disk database with an uploaded backup after validation.
+ */
+export async function restore_db_from_uploaded_json(
+  uploaded: unknown,
+): Promise<void> {
+  if (!is_json_time_tracker_db(uploaded)) {
+    throw new Error('Invalid backup file: expected a time tracker database.')
+  }
+
+  const { json_db } = migrate_json_db(uploaded)
+  const db = convert_json_db(json_db)
+
+  if (db.sheets.length === 0) {
+    throw new Error('Invalid backup file: the database must include at least one sheet.')
+  }
+
+  await write_db(db)
+}

package/lib/serialize_entry.ts

@@ -0,0 +1,27 @@
+import { get_entry_duration_ms } from "@/lib/get_entry_duration_ms";
+import { type SerializedEntry } from "@/lib/types/tracker_state";
+import { type TimeSheetEntry } from "@/lib/types";
+
+/**
+ * Converts an in-memory entry into a JSON-safe tracker payload.
+ */
+export function serialize_entry(
+  entry: TimeSheetEntry,
+  sheet_name: string,
+  is_active: boolean,
+): SerializedEntry {
+  return {
+    id: entry.id,
+    description: entry.description,
+    start: entry.start.toISOString(),
+    end: entry.end === null ? null : entry.end.toISOString(),
+    tags: entry.tags,
+    notes: entry.notes.map(({ timestamp, text }) => ({
+      timestamp: timestamp.toISOString(),
+      text,
+    })),
+    sheetName: sheet_name,
+    durationMs: get_entry_duration_ms(entry),
+    isActive: is_active,
+  };
+}

package/lib/serialize_reporting_source_sheets.ts

@@ -0,0 +1,19 @@
+import { type ReportingSourceSheet } from '@/lib/types/reporting'
+import { type TimeSheet } from '@/lib/types'
+
+/**
+ * Serializes time sheets for client-side reporting calculations.
+ */
+export function serialize_reporting_source_sheets(
+  sheets: TimeSheet[],
+): ReportingSourceSheet[] {
+  return sheets.map((sheet) => ({
+    name: sheet.name,
+    activeEntryID: sheet.activeEntryID,
+    entries: sheet.entries.map((entry) => ({
+      id: entry.id,
+      start: entry.start.toISOString(),
+      end: entry.end === null ? null : entry.end.toISOString(),
+    })),
+  }))
+}

package/lib/serialize_sheet_entries.ts

@@ -0,0 +1,18 @@
+import { serialize_entry } from '@/lib/serialize_entry'
+import { type SerializedEntry } from '@/lib/types/tracker_state'
+import { type TimeSheet } from '@/lib/types'
+
+/**
+ * Serializes every entry on a time sheet for the web UI.
+ */
+export function serialize_sheet_entries(sheet: TimeSheet): SerializedEntry[] {
+  const { activeEntryID, entries, name } = sheet
+
+  return entries.map((entry) =>
+    serialize_entry(
+      entry,
+      name,
+      activeEntryID === entry.id && entry.end === null,
+    ),
+  )
+}

package/lib/set_accent_color.ts

@@ -0,0 +1,12 @@
+import { accent_color_preference } from '@/lib/preferences/accent_color_preference'
+import { apply_accent_color } from '@/lib/apply_accent_color'
+import { type AccentColor } from '@/lib/types/ui_preferences'
+
+/**
+ * Persists the accent color preference, applies it, and notifies subscribers.
+ */
+export function set_accent_color(value: AccentColor): void {
+  accent_color_preference.write(value)
+  apply_accent_color(value)
+  accent_color_preference.notify()
+}

package/lib/set_active_sheet.ts

@@ -0,0 +1,18 @@
+import { gen_sheet } from "@/lib/gen_db";
+import { read_db } from "@/lib/read_db";
+import { write_db } from "@/lib/write_db";
+
+/**
+ * Switches the active sheet, creating it when missing.
+ */
+export async function set_active_sheet(sheet_name: string): Promise<void> {
+  const db = await read_db();
+  const exists = db.sheets.some(({ name }) => name === sheet_name);
+
+  if (!exists) {
+    db.sheets.push(gen_sheet(sheet_name));
+  }
+
+  db.activeSheetName = sheet_name;
+  await write_db(db);
+}

package/lib/set_color_palette.ts

@@ -0,0 +1,12 @@
+import { apply_color_palette } from '@/lib/apply_color_palette'
+import { color_palette_preference } from '@/lib/preferences/color_palette_preference'
+import { type ColorPalette } from '@/lib/types/ui_preferences'
+
+/**
+ * Persists the color palette preference, applies it, and notifies subscribers.
+ */
+export function set_color_palette(value: ColorPalette): void {
+  color_palette_preference.write(value)
+  apply_color_palette(value)
+  color_palette_preference.notify()
+}

package/lib/set_compact_lists.ts

@@ -0,0 +1,12 @@
+import { apply_compact_lists } from "@/lib/apply_compact_lists";
+import { notify_compact_lists_subscribers } from "@/lib/subscribe_compact_lists";
+import { write_stored_compact_lists } from "@/lib/write_stored_compact_lists";
+
+/**
+ * Updates the compact lists UI setting in the DOM and localStorage.
+ */
+export function set_compact_lists(enabled: boolean): void {
+  apply_compact_lists(enabled);
+  write_stored_compact_lists(enabled);
+  notify_compact_lists_subscribers();
+}

package/lib/set_default_sheet_fixed_name.ts

@@ -0,0 +1,8 @@
+import { write_stored_default_sheet_fixed_name } from '@/lib/write_stored_default_sheet_fixed_name'
+
+/**
+ * Updates which sheet opens when the session mode is set to a specific sheet.
+ */
+export function set_default_sheet_fixed_name(sheet_name: string): void {
+  write_stored_default_sheet_fixed_name(sheet_name)
+}

package/lib/set_default_sheet_session_mode.ts

@@ -0,0 +1,11 @@
+import { write_stored_default_sheet_session_mode } from '@/lib/write_stored_default_sheet_session_mode'
+import { type DefaultSheetSessionMode } from '@/lib/types/ui_settings'
+
+/**
+ * Updates the default sheet session mode preference.
+ */
+export function set_default_sheet_session_mode(
+  mode: DefaultSheetSessionMode,
+): void {
+  write_stored_default_sheet_session_mode(mode)
+}

package/lib/set_sheet_tag_filter.ts

@@ -0,0 +1,13 @@
+import { notify_sheet_tag_filters_subscribers } from '@/lib/subscribe_sheet_tag_filters'
+import { write_sheet_tag_filter } from '@/lib/write_sheet_tag_filter'
+
+/**
+ * Replaces the tag filter list for a sheet.
+ */
+export function set_sheet_tag_filter(
+  sheet_name: string,
+  filter_tags: string[],
+): void {
+  write_sheet_tag_filter(sheet_name, filter_tags)
+  notify_sheet_tag_filters_subscribers()
+}

package/lib/set_theme_mode.ts

@@ -0,0 +1,19 @@
+import { apply_theme } from '@/lib/apply_theme'
+import { notify_theme_subscribers } from '@/lib/subscribe_theme'
+import { resolve_theme_mode_to_theme } from '@/lib/resolve_theme_mode_to_theme'
+import { theme_mode_preference } from '@/lib/preferences/theme_mode_preference'
+import { write_stored_theme } from '@/lib/write_stored_theme'
+import { type ThemeMode } from '@/lib/types/ui_preferences'
+
+/**
+ * Persists the theme mode, applies the resolved theme, and notifies subscribers.
+ */
+export function set_theme_mode(mode: ThemeMode): void {
+  theme_mode_preference.write(mode)
+  theme_mode_preference.notify()
+
+  const resolved = resolve_theme_mode_to_theme(mode)
+  apply_theme(resolved)
+  write_stored_theme(resolved)
+  notify_theme_subscribers()
+}

package/lib/sheet_tag_filter_snapshots.ts

@@ -0,0 +1,48 @@
+/**
+ * Stable empty tag filter list for useSyncExternalStore snapshots.
+ */
+export const EMPTY_SHEET_TAG_FILTER: readonly string[] = []
+
+interface SheetTagFilterSnapshotCache {
+  sheet_name: string
+  tags_key: string
+  snapshot: readonly string[]
+}
+
+let snapshot_cache: SheetTagFilterSnapshotCache | null = null
+
+/**
+ * Clears the cached sheet tag filter snapshot.
+ */
+export function reset_sheet_tag_filter_snapshot_cache(): void {
+  snapshot_cache = null
+}
+
+/**
+ * Returns a stable snapshot reference for the given tag list.
+ */
+export function get_stable_sheet_tag_filter_snapshot(
+  sheet_name: string,
+  tags: string[],
+): readonly string[] {
+  const tags_key = tags.join('\0')
+
+  if (
+    snapshot_cache !== null &&
+    snapshot_cache.sheet_name === sheet_name &&
+    snapshot_cache.tags_key === tags_key
+  ) {
+    return snapshot_cache.snapshot
+  }
+
+  const snapshot =
+    tags.length === 0 ? EMPTY_SHEET_TAG_FILTER : Object.freeze([...tags])
+
+  snapshot_cache = {
+    sheet_name,
+    tags_key,
+    snapshot,
+  }
+
+  return snapshot
+}

package/lib/sort_serialized_entries.ts

@@ -0,0 +1,35 @@
+import { type EntryListSort } from '@/lib/types/ui_preferences'
+import { type SerializedEntry } from '@/lib/types/tracker_state'
+
+/**
+ * Sorts serialized entries for display in the entry list.
+ */
+export function sort_serialized_entries(
+  entries: SerializedEntry[],
+  sort: EntryListSort,
+): SerializedEntry[] {
+  const sorted = [...entries]
+
+  switch (sort) {
+    case 'oldest':
+      return sorted.sort(
+        (left, right) =>
+          new Date(left.start).getTime() - new Date(right.start).getTime(),
+      )
+    case 'duration':
+      return sorted.sort((left, right) => right.durationMs - left.durationMs)
+    case 'description':
+      return sorted.sort((left, right) => {
+        const left_label = left.description.trim() || 'Untitled entry'
+        const right_label = right.description.trim() || 'Untitled entry'
+
+        return left_label.localeCompare(right_label)
+      })
+    case 'newest':
+    default:
+      return sorted.sort(
+        (left, right) =>
+          new Date(right.start).getTime() - new Date(left.start).getTime(),
+      )
+  }
+}

package/lib/sort_sheet_report_stats.ts

@@ -0,0 +1,43 @@
+import { type SheetReportSort, type SheetReportStats } from '@/lib/types/reporting'
+
+/**
+ * Returns a new array of sheet report stats in the requested order.
+ */
+export function sort_sheet_report_stats(
+  sheets: SheetReportStats[],
+  sort: SheetReportSort,
+): SheetReportStats[] {
+  const sorted = [...sheets]
+
+  switch (sort) {
+    case 'name':
+      sorted.sort((left, right) =>
+        left.sheetName.localeCompare(right.sheetName),
+      )
+      break
+    case 'entry_count':
+      sorted.sort((left, right) => {
+        if (right.entryCount !== left.entryCount) {
+          return right.entryCount - left.entryCount
+        }
+
+        return right.totalMs - left.totalMs
+      })
+      break
+    case 'active_first':
+      sorted.sort((left, right) => {
+        if (left.hasActiveEntry !== right.hasActiveEntry) {
+          return left.hasActiveEntry ? -1 : 1
+        }
+
+        return right.totalMs - left.totalMs
+      })
+      break
+    case 'duration':
+    default:
+      sorted.sort((left, right) => right.totalMs - left.totalMs)
+      break
+  }
+
+  return sorted
+}

package/lib/subscribe_compact_lists.ts

@@ -0,0 +1,25 @@
+type CompactListsListener = () => void;
+
+const compact_lists_listeners = new Set<CompactListsListener>();
+
+/**
+ * Subscribes to compact lists setting changes for useSyncExternalStore.
+ */
+export function subscribe_compact_lists(
+  listener: CompactListsListener,
+): () => void {
+  compact_lists_listeners.add(listener);
+
+  return () => {
+    compact_lists_listeners.delete(listener);
+  };
+}
+
+/**
+ * Notifies subscribers after the compact lists setting changes.
+ */
+export function notify_compact_lists_subscribers(): void {
+  compact_lists_listeners.forEach((listener) => {
+    listener();
+  });
+}

package/lib/subscribe_sheet_tag_filters.ts

@@ -0,0 +1,28 @@
+import { reset_sheet_tag_filter_snapshot_cache } from '@/lib/sheet_tag_filter_snapshots'
+
+type SheetTagFiltersListener = () => void
+
+const sheet_tag_filters_listeners = new Set<SheetTagFiltersListener>()
+
+/**
+ * Subscribes to sheet tag filter changes for useSyncExternalStore.
+ */
+export function subscribe_sheet_tag_filters(
+  listener: SheetTagFiltersListener,
+): () => void {
+  sheet_tag_filters_listeners.add(listener)
+
+  return () => {
+    sheet_tag_filters_listeners.delete(listener)
+  }
+}
+
+/**
+ * Notifies subscribers after sheet tag filters change.
+ */
+export function notify_sheet_tag_filters_subscribers(): void {
+  reset_sheet_tag_filter_snapshot_cache()
+  sheet_tag_filters_listeners.forEach((listener) => {
+    listener()
+  })
+}

package/lib/subscribe_theme.ts

@@ -0,0 +1,23 @@
+type ThemeListener = () => void;
+
+const theme_listeners = new Set<ThemeListener>();
+
+/**
+ * Subscribes to theme changes for useSyncExternalStore.
+ */
+export function subscribe_theme(listener: ThemeListener): () => void {
+  theme_listeners.add(listener);
+
+  return () => {
+    theme_listeners.delete(listener);
+  };
+}
+
+/**
+ * Notifies all theme subscribers after the DOM theme changes.
+ */
+export function notify_theme_subscribers(): void {
+  theme_listeners.forEach((listener) => {
+    listener();
+  });
+}

package/lib/sync_active_sheet_preference.ts

@@ -0,0 +1,19 @@
+import { write_active_sheet_preference } from '@/lib/write_active_sheet_preference'
+import { type TrackerState } from '@/lib/types/tracker_state'
+
+/**
+ * Updates stored sheet preference from the current tracker state.
+ */
+export function sync_active_sheet_preference(state: TrackerState): void {
+  if (typeof window === 'undefined') {
+    return
+  }
+
+  const sheet_name = state.activeSheetName
+
+  if (sheet_name === null) {
+    return
+  }
+
+  write_active_sheet_preference(sheet_name)
+}

package/lib/tags_are_equal.ts

@@ -0,0 +1,12 @@
+import { normalize_stored_tag } from '@/lib/normalize_stored_tag'
+
+/**
+ * Returns whether two stored tags refer to the same tag name.
+ */
+export function tags_are_equal(left: string, right: string): boolean {
+  try {
+    return normalize_stored_tag(left) === normalize_stored_tag(right)
+  } catch {
+    return false
+  }
+}