super-time-tracker-ui 0.1.2

package/lib/persist_ui_preference.ts

@@ -0,0 +1,18 @@
+import { notify_settings_saved } from '@/lib/notify_settings_saved'
+import { type UiPreferenceStore } from '@/lib/ui_preference_store'
+
+/**
+ * Writes a UI preference, notifies subscribers, and shows the saved toast.
+ */
+export function persist_ui_preference<T extends string>(
+  store: UiPreferenceStore<T>,
+  value: T,
+): void {
+  if (store.read() === value) {
+    return
+  }
+
+  store.write(value)
+  store.notify()
+  notify_settings_saved()
+}

package/lib/post_tracker_action.ts

@@ -0,0 +1,22 @@
+import { type TrackerState } from "@/lib/types/tracker_state";
+
+/**
+ * Posts a JSON body to a tracker API route and returns updated state.
+ */
+export async function post_tracker_action(
+  path: string,
+  body: unknown,
+): Promise<TrackerState> {
+  const response = await fetch(path, {
+    method: "POST",
+    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;
+}

package/lib/preferences/accent_color_preference.ts

@@ -0,0 +1,21 @@
+import { create_ui_preference_store } from '@/lib/ui_preference_store'
+import {
+  ACCENT_COLOR_DEFAULT,
+  ACCENT_COLOR_STORAGE_KEY,
+  ACCENT_COLOR_VALUES,
+  type AccentColor,
+} from '@/lib/types/ui_preferences'
+
+const valid_set = new Set<string>(ACCENT_COLOR_VALUES)
+
+const is_accent_color = (value: string): value is AccentColor =>
+  valid_set.has(value)
+
+/**
+ * Accent color preset preference store.
+ */
+export const accent_color_preference = create_ui_preference_store<AccentColor>({
+  storage_key: ACCENT_COLOR_STORAGE_KEY,
+  default_value: ACCENT_COLOR_DEFAULT,
+  is_valid: is_accent_color,
+})

package/lib/preferences/check_in_form_collapsed_preference.ts

@@ -0,0 +1,20 @@
+import { create_ui_preference_store } from '@/lib/ui_preference_store'
+import {
+  CHECK_IN_FORM_COLLAPSED_DEFAULT,
+  CHECK_IN_FORM_COLLAPSED_STORAGE_KEY,
+  type CheckInFormCollapsed,
+} from '@/lib/types/ui_preferences'
+
+const is_check_in_form_collapsed = (
+  value: string,
+): value is CheckInFormCollapsed => value === 'true' || value === 'false'
+
+/**
+ * Whether the check-in form should be collapsed by default.
+ */
+export const check_in_form_collapsed_preference =
+  create_ui_preference_store<CheckInFormCollapsed>({
+    storage_key: CHECK_IN_FORM_COLLAPSED_STORAGE_KEY,
+    default_value: CHECK_IN_FORM_COLLAPSED_DEFAULT,
+    is_valid: is_check_in_form_collapsed,
+  })

package/lib/preferences/clear_tag_filters_on_sheet_change_preference.ts

@@ -0,0 +1,20 @@
+import { create_ui_preference_store } from '@/lib/ui_preference_store'
+import {
+  CLEAR_TAG_FILTERS_ON_SHEET_CHANGE_DEFAULT,
+  CLEAR_TAG_FILTERS_ON_SHEET_CHANGE_STORAGE_KEY,
+  type ClearTagFiltersOnSheetChange,
+} from '@/lib/types/ui_preferences'
+
+const is_clear_tag_filters_on_sheet_change = (
+  value: string,
+): value is ClearTagFiltersOnSheetChange => value === 'true' || value === 'false'
+
+/**
+ * Whether tag filters reset whenever the active sheet changes.
+ */
+export const clear_tag_filters_on_sheet_change_preference =
+  create_ui_preference_store<ClearTagFiltersOnSheetChange>({
+    storage_key: CLEAR_TAG_FILTERS_ON_SHEET_CHANGE_STORAGE_KEY,
+    default_value: CLEAR_TAG_FILTERS_ON_SHEET_CHANGE_DEFAULT,
+    is_valid: is_clear_tag_filters_on_sheet_change,
+  })

package/lib/preferences/color_palette_preference.ts

@@ -0,0 +1,21 @@
+import { create_ui_preference_store } from '@/lib/ui_preference_store'
+import {
+  COLOR_PALETTE_DEFAULT,
+  COLOR_PALETTE_STORAGE_KEY,
+  COLOR_PALETTE_VALUES,
+  type ColorPalette,
+} from '@/lib/types/ui_preferences'
+
+const valid_set = new Set<string>(COLOR_PALETTE_VALUES)
+
+const is_color_palette = (value: string): value is ColorPalette =>
+  valid_set.has(value)
+
+/**
+ * Base color palette preference store (surfaces and backgrounds).
+ */
+export const color_palette_preference = create_ui_preference_store<ColorPalette>({
+  storage_key: COLOR_PALETTE_STORAGE_KEY,
+  default_value: COLOR_PALETTE_DEFAULT,
+  is_valid: is_color_palette,
+})

package/lib/preferences/confirm_before_checkout_preference.ts

@@ -0,0 +1,20 @@
+import { create_ui_preference_store } from '@/lib/ui_preference_store'
+import {
+  CONFIRM_BEFORE_CHECKOUT_DEFAULT,
+  CONFIRM_BEFORE_CHECKOUT_STORAGE_KEY,
+  type ConfirmBeforeCheckout,
+} from '@/lib/types/ui_preferences'
+
+const is_confirm_before_checkout = (
+  value: string,
+): value is ConfirmBeforeCheckout => value === 'true' || value === 'false'
+
+/**
+ * Whether to confirm before checking out of an active timer.
+ */
+export const confirm_before_checkout_preference =
+  create_ui_preference_store<ConfirmBeforeCheckout>({
+    storage_key: CONFIRM_BEFORE_CHECKOUT_STORAGE_KEY,
+    default_value: CONFIRM_BEFORE_CHECKOUT_DEFAULT,
+    is_valid: is_confirm_before_checkout,
+  })

package/lib/preferences/confirm_destructive_actions_preference.ts

@@ -0,0 +1,20 @@
+import { create_ui_preference_store } from '@/lib/ui_preference_store'
+import {
+  CONFIRM_DESTRUCTIVE_ACTIONS_DEFAULT,
+  CONFIRM_DESTRUCTIVE_ACTIONS_STORAGE_KEY,
+  type ConfirmDestructiveActions,
+} from '@/lib/types/ui_preferences'
+
+const is_confirm_destructive_actions = (
+  value: string,
+): value is ConfirmDestructiveActions => value === 'true' || value === 'false'
+
+/**
+ * Whether to show a confirm dialog before deleting entries or sheets.
+ */
+export const confirm_destructive_actions_preference =
+  create_ui_preference_store<ConfirmDestructiveActions>({
+    storage_key: CONFIRM_DESTRUCTIVE_ACTIONS_STORAGE_KEY,
+    default_value: CONFIRM_DESTRUCTIVE_ACTIONS_DEFAULT,
+    is_valid: is_confirm_destructive_actions,
+  })

package/lib/preferences/default_reporting_range_preference.ts

@@ -0,0 +1,21 @@
+import { create_ui_preference_store } from '@/lib/ui_preference_store'
+import {
+  DEFAULT_REPORTING_RANGE_DEFAULT,
+  DEFAULT_REPORTING_RANGE_STORAGE_KEY,
+  type DefaultReportingRange,
+} from '@/lib/types/ui_preferences'
+
+const is_default_reporting_range = (
+  value: string,
+): value is DefaultReportingRange =>
+  value === 'none' || value === 'today' || value === 'week'
+
+/**
+ * Initial date range when opening the reporting view.
+ */
+export const default_reporting_range_preference =
+  create_ui_preference_store<DefaultReportingRange>({
+    storage_key: DEFAULT_REPORTING_RANGE_STORAGE_KEY,
+    default_value: DEFAULT_REPORTING_RANGE_DEFAULT,
+    is_valid: is_default_reporting_range,
+  })

package/lib/preferences/default_reporting_sort_preference.ts

@@ -0,0 +1,24 @@
+import { create_ui_preference_store } from '@/lib/ui_preference_store'
+import {
+  DEFAULT_REPORTING_SORT_DEFAULT,
+  DEFAULT_REPORTING_SORT_STORAGE_KEY,
+  type DefaultReportingSort,
+} from '@/lib/types/ui_preferences'
+
+const is_default_reporting_sort = (
+  value: string,
+): value is DefaultReportingSort =>
+  value === 'duration' ||
+  value === 'name' ||
+  value === 'entry_count' ||
+  value === 'active_first'
+
+/**
+ * Default reporting sort preference store.
+ */
+export const default_reporting_sort_preference =
+  create_ui_preference_store<DefaultReportingSort>({
+    storage_key: DEFAULT_REPORTING_SORT_STORAGE_KEY,
+    default_value: DEFAULT_REPORTING_SORT_DEFAULT,
+    is_valid: is_default_reporting_sort,
+  })

package/lib/preferences/duration_format_preference.ts

@@ -0,0 +1,19 @@
+import { create_ui_preference_store } from '@/lib/ui_preference_store'
+import {
+  DURATION_FORMAT_DEFAULT,
+  DURATION_FORMAT_STORAGE_KEY,
+  type DurationFormat,
+} from '@/lib/types/ui_preferences'
+
+const is_duration_format = (value: string): value is DurationFormat =>
+  value === 'humanized' || value === 'clock' || value === 'decimal'
+
+/**
+ * Duration format preference store: humanized, clock, or decimal.
+ */
+export const duration_format_preference =
+  create_ui_preference_store<DurationFormat>({
+    storage_key: DURATION_FORMAT_STORAGE_KEY,
+    default_value: DURATION_FORMAT_DEFAULT,
+    is_valid: is_duration_format,
+  })

package/lib/preferences/entry_list_sort_preference.ts

@@ -0,0 +1,21 @@
+import { create_ui_preference_store } from '@/lib/ui_preference_store'
+import {
+  ENTRY_LIST_SORT_DEFAULT,
+  ENTRY_LIST_SORT_STORAGE_KEY,
+  type EntryListSort,
+} from '@/lib/types/ui_preferences'
+
+const is_entry_list_sort = (value: string): value is EntryListSort =>
+  value === 'newest' ||
+  value === 'oldest' ||
+  value === 'duration' ||
+  value === 'description'
+
+/**
+ * Default sort order for entry lists on the tracker home view.
+ */
+export const entry_list_sort_preference = create_ui_preference_store<EntryListSort>({
+  storage_key: ENTRY_LIST_SORT_STORAGE_KEY,
+  default_value: ENTRY_LIST_SORT_DEFAULT,
+  is_valid: is_entry_list_sort,
+})

package/lib/preferences/tag_filter_mode_preference.ts

@@ -0,0 +1,18 @@
+import { create_ui_preference_store } from '@/lib/ui_preference_store'
+import {
+  TAG_FILTER_MODE_DEFAULT,
+  TAG_FILTER_MODE_STORAGE_KEY,
+  type TagFilterMode,
+} from '@/lib/types/ui_preferences'
+
+const is_tag_filter_mode = (value: string): value is TagFilterMode =>
+  value === 'all' || value === 'any'
+
+/**
+ * Tag filter match mode: require all selected tags or any one.
+ */
+export const tag_filter_mode_preference = create_ui_preference_store<TagFilterMode>({
+  storage_key: TAG_FILTER_MODE_STORAGE_KEY,
+  default_value: TAG_FILTER_MODE_DEFAULT,
+  is_valid: is_tag_filter_mode,
+})

package/lib/preferences/theme_mode_preference.ts

@@ -0,0 +1,18 @@
+import { create_ui_preference_store } from '@/lib/ui_preference_store'
+import {
+  THEME_MODE_DEFAULT,
+  THEME_MODE_STORAGE_KEY,
+  type ThemeMode,
+} from '@/lib/types/ui_preferences'
+
+const is_theme_mode = (value: string): value is ThemeMode =>
+  value === 'light' || value === 'dark' || value === 'system'
+
+/**
+ * Theme preference store: light, dark, or follow system.
+ */
+export const theme_mode_preference = create_ui_preference_store<ThemeMode>({
+  storage_key: THEME_MODE_STORAGE_KEY,
+  default_value: THEME_MODE_DEFAULT,
+  is_valid: is_theme_mode,
+})

package/lib/preferences/time_format_preference.ts

@@ -0,0 +1,18 @@
+import { create_ui_preference_store } from '@/lib/ui_preference_store'
+import {
+  TIME_FORMAT_DEFAULT,
+  TIME_FORMAT_STORAGE_KEY,
+  type TimeFormat,
+} from '@/lib/types/ui_preferences'
+
+const is_time_format = (value: string): value is TimeFormat =>
+  value === '12h' || value === '24h'
+
+/**
+ * Time format preference store: 12h or 24h.
+ */
+export const time_format_preference = create_ui_preference_store<TimeFormat>({
+  storage_key: TIME_FORMAT_STORAGE_KEY,
+  default_value: TIME_FORMAT_DEFAULT,
+  is_valid: is_time_format,
+})

package/lib/preferences/timer_in_title_preference.ts

@@ -0,0 +1,18 @@
+import { create_ui_preference_store } from '@/lib/ui_preference_store'
+import {
+  TIMER_IN_TITLE_DEFAULT,
+  TIMER_IN_TITLE_STORAGE_KEY,
+  type TimerInTitle,
+} from '@/lib/types/ui_preferences'
+
+const is_timer_in_title = (value: string): value is TimerInTitle =>
+  value === 'true' || value === 'false'
+
+/**
+ * Whether the browser tab title shows the live timer while tracking.
+ */
+export const timer_in_title_preference = create_ui_preference_store<TimerInTitle>({
+  storage_key: TIMER_IN_TITLE_STORAGE_KEY,
+  default_value: TIMER_IN_TITLE_DEFAULT,
+  is_valid: is_timer_in_title,
+})

package/lib/preferences/timer_show_seconds_preference.ts

@@ -0,0 +1,19 @@
+import { create_ui_preference_store } from '@/lib/ui_preference_store'
+import {
+  TIMER_SHOW_SECONDS_DEFAULT,
+  TIMER_SHOW_SECONDS_STORAGE_KEY,
+  type TimerShowSeconds,
+} from '@/lib/types/ui_preferences'
+
+const is_timer_show_seconds = (value: string): value is TimerShowSeconds =>
+  value === 'true' || value === 'false'
+
+/**
+ * Whether the active timer displays seconds.
+ */
+export const timer_show_seconds_preference =
+  create_ui_preference_store<TimerShowSeconds>({
+    storage_key: TIMER_SHOW_SECONDS_STORAGE_KEY,
+    default_value: TIMER_SHOW_SECONDS_DEFAULT,
+    is_valid: is_timer_show_seconds,
+  })

package/lib/preferences/week_starts_on_preference.ts

@@ -0,0 +1,19 @@
+import { create_ui_preference_store } from '@/lib/ui_preference_store'
+import {
+  WEEK_STARTS_ON_DEFAULT,
+  WEEK_STARTS_ON_STORAGE_KEY,
+  type WeekStartsOn,
+} from '@/lib/types/ui_preferences'
+
+const is_week_starts_on = (value: string): value is WeekStartsOn =>
+  value === 'monday' || value === 'sunday'
+
+/**
+ * Week start preference store: monday or sunday.
+ */
+export const week_starts_on_preference =
+  create_ui_preference_store<WeekStartsOn>({
+    storage_key: WEEK_STARTS_ON_STORAGE_KEY,
+    default_value: WEEK_STARTS_ON_DEFAULT,
+    is_valid: is_week_starts_on,
+  })

package/lib/prompt_check_out_at.ts

@@ -0,0 +1,17 @@
+/**
+ * Prompts for a natural-language checkout time such as "30 minutes ago".
+ */
+export function prompt_check_out_at(): string | null {
+  const value = window.prompt(
+    "Check out at what time?",
+    "30 minutes ago",
+  );
+
+  if (value === null) {
+    return null;
+  }
+
+  const trimmed = value.trim();
+
+  return trimmed.length === 0 ? null : trimmed;
+}

package/lib/prompt_entry_note.ts

@@ -0,0 +1,14 @@
+/**
+ * Prompts for note text to attach to a time sheet entry.
+ */
+export function prompt_entry_note(): string | null {
+  const value = window.prompt("Add note", "");
+
+  if (value === null) {
+    return null;
+  }
+
+  const trimmed = value.trim();
+
+  return trimmed.length === 0 ? null : trimmed;
+}

package/lib/prune_sheet_tag_filter.ts

@@ -0,0 +1,27 @@
+import { read_sheet_tag_filter } from '@/lib/read_sheet_tag_filter'
+import { set_sheet_tag_filter } from '@/lib/set_sheet_tag_filter'
+import { tags_are_equal } from '@/lib/tags_are_equal'
+
+/**
+ * Drops filter tags that no longer appear on the sheet.
+ */
+export function prune_sheet_tag_filter(
+  sheet_name: string,
+  available_tags: string[],
+): void {
+  const current = read_sheet_tag_filter(sheet_name)
+
+  if (current.length === 0) {
+    return
+  }
+
+  const pruned = current.filter((filter_tag) =>
+    available_tags.some((available_tag) =>
+      tags_are_equal(filter_tag, available_tag),
+    ),
+  )
+
+  if (pruned.length !== current.length) {
+    set_sheet_tag_filter(sheet_name, pruned)
+  }
+}

package/lib/read_db.ts

@@ -0,0 +1,49 @@
+import path from "node:path";
+import { promises as fs } from "node:fs";
+
+import { DB_PATH } from "@/lib/config";
+import { convert_json_db } from "@/lib/convert_json_db";
+import { ensure_dir_exists } from "@/lib/ensure_dir_exists";
+import { gen_db } from "@/lib/gen_db";
+import { migrate_json_db } from "@/lib/migrate_json_db";
+import { write_db } from "@/lib/write_db";
+import { type JSONTimeTrackerDB, type TimeTrackerDB } from "@/lib/types";
+
+/**
+ * Loads the tracker database from disk, migrating when needed.
+ */
+export async function read_db(
+  db_path: string = DB_PATH,
+): Promise<TimeTrackerDB> {
+  const db_path_dir = path.dirname(db_path);
+  await ensure_dir_exists(db_path_dir);
+
+  try {
+    await fs.access(db_path);
+  } catch {
+    const db = gen_db();
+    await write_db(db, db_path);
+    return db;
+  }
+
+  const db_json = await fs.readFile(db_path, "utf-8");
+  let json_db: JSONTimeTrackerDB;
+
+  try {
+    json_db = JSON.parse(db_json) as JSONTimeTrackerDB;
+  } catch (parse_err: unknown) {
+    throw new Error(`DB at ${db_path} is invalid JSON: ${String(parse_err)}`, {
+      cause: parse_err,
+    });
+  }
+
+  const migration_result = migrate_json_db(json_db);
+  json_db = migration_result.json_db;
+  const db = convert_json_db(json_db);
+
+  if (migration_result.did_migrate) {
+    await write_db(db, db_path);
+  }
+
+  return db;
+}

package/lib/read_db_backup_contents.ts

@@ -0,0 +1,22 @@
+import { promises as fs } from 'node:fs'
+
+import { DB_PATH } from '@/lib/config'
+import { read_db } from '@/lib/read_db'
+import { write_db } from '@/lib/write_db'
+
+/**
+ * Reads the on-disk database JSON used for backup downloads.
+ */
+export async function read_db_backup_contents(
+  db_path: string = DB_PATH,
+): Promise<string> {
+  try {
+    return await fs.readFile(db_path, 'utf-8')
+  } catch {
+    const db = await read_db(db_path)
+
+    await write_db(db, db_path)
+
+    return await fs.readFile(db_path, 'utf-8')
+  }
+}

package/lib/read_document_compact_lists.ts

@@ -0,0 +1,12 @@
+/**
+ * Reads whether compact lists are enabled on the document element.
+ */
+export function read_document_compact_lists(): boolean {
+  if (typeof document === "undefined") {
+    return false;
+  }
+
+  return (
+    document.documentElement.getAttribute("data-compact-lists") === "true"
+  );
+}

package/lib/read_document_theme.ts

@@ -0,0 +1,14 @@
+import { type Theme } from "@/lib/types/theme";
+
+/**
+ * Reads the theme currently applied on the document element.
+ */
+export function read_document_theme(): Theme {
+  if (typeof document === "undefined") {
+    return "dark";
+  }
+
+  return document.documentElement.getAttribute("data-theme") === "light"
+    ? "light"
+    : "dark";
+}

package/lib/read_sheet_tag_filter.ts

@@ -0,0 +1,26 @@
+import { normalize_stored_tag } from '@/lib/normalize_stored_tag'
+import { read_stored_sheet_tag_filters } from '@/lib/read_stored_sheet_tag_filters'
+
+/**
+ * Returns stored tag filters for a sheet, normalized and deduplicated.
+ */
+export function read_sheet_tag_filter(sheet_name: string): string[] {
+  const stored = read_stored_sheet_tag_filters()[sheet_name] ?? []
+  const normalized: string[] = []
+  const seen = new Set<string>()
+
+  for (const tag of stored) {
+    try {
+      const name = normalize_stored_tag(tag)
+
+      if (!seen.has(name)) {
+        seen.add(name)
+        normalized.push(name)
+      }
+    } catch {
+      continue
+    }
+  }
+
+  return normalized
+}

package/lib/read_stored_active_sheet.ts

@@ -0,0 +1,14 @@
+import { ACTIVE_SHEET_STORAGE_KEY } from '@/lib/types/ui_settings'
+
+/**
+ * Reads the last opened sheet from localStorage (client-only).
+ */
+export function read_stored_active_sheet(): string | null {
+  try {
+    const value = window.localStorage.getItem(ACTIVE_SHEET_STORAGE_KEY)?.trim() ?? ''
+
+    return value.length > 0 ? value : null
+  } catch {
+    return null
+  }
+}

package/lib/read_stored_compact_lists.ts

@@ -0,0 +1,24 @@
+import {
+  COMPACT_LISTS_STORAGE_KEY,
+} from "@/lib/types/ui_settings";
+
+/**
+ * Reads the persisted compact lists setting from localStorage.
+ */
+export function read_stored_compact_lists(): boolean | null {
+  if (typeof window === "undefined") {
+    return null;
+  }
+
+  const stored = window.localStorage.getItem(COMPACT_LISTS_STORAGE_KEY);
+
+  if (stored === "true") {
+    return true;
+  }
+
+  if (stored === "false") {
+    return false;
+  }
+
+  return null;
+}

package/lib/read_stored_default_sheet_fixed_name.ts

@@ -0,0 +1,16 @@
+import { DEFAULT_SHEET_FIXED_NAME_STORAGE_KEY } from '@/lib/types/ui_settings'
+
+/**
+ * Reads the fixed default sheet name from localStorage.
+ */
+export function read_stored_default_sheet_fixed_name(): string | null {
+  try {
+    const value =
+      window.localStorage.getItem(DEFAULT_SHEET_FIXED_NAME_STORAGE_KEY)?.trim() ??
+      ''
+
+    return value.length > 0 ? value : null
+  } catch {
+    return null
+  }
+}

package/lib/read_stored_default_sheet_session_mode.ts

@@ -0,0 +1,18 @@
+import { parse_default_sheet_session_mode } from '@/lib/parse_default_sheet_session_mode'
+import {
+  DEFAULT_SHEET_SESSION_MODE_STORAGE_KEY,
+  type DefaultSheetSessionMode,
+} from '@/lib/types/ui_settings'
+
+/**
+ * Reads the default sheet session mode from localStorage.
+ */
+export function read_stored_default_sheet_session_mode(): DefaultSheetSessionMode {
+  try {
+    const value = window.localStorage.getItem(DEFAULT_SHEET_SESSION_MODE_STORAGE_KEY)
+
+    return parse_default_sheet_session_mode(value)
+  } catch {
+    return parse_default_sheet_session_mode(null)
+  }
+}