@focus8/settings-registry 0.1.0

package/src/index.ts

@@ -0,0 +1,715 @@
+/**
+ * Settings Registry — single source of truth for ALL FocusPlanner app settings.
+ *
+ * This shared package defines every setting key, its category, data type,
+ * default value, and whether it should be synced to the server.
+ *
+ * Used by:
+ *   - The mobile app (local SQLite settings table, React Query hooks)
+ *   - The API (validate & serialize settings profiles)
+ *   - The web portal (render settings viewer/editor)
+ *
+ * App-specific defaults (theme, locale, enrolled mode) are parameterized
+ * via `createRegistry(config)`.
+ */
+
+// ---------------------------------------------------------------------------
+// Setting types shared across mobile, API, and web
+// ---------------------------------------------------------------------------
+
+export type ThemeSetting = 'light' | 'dark' | 'system';
+export type AlarmSound =
+  | 'none'
+  | 'alarm1'
+  | 'alarm2'
+  | 'alarm3'
+  | 'alarm4'
+  | 'alarm5'
+  | 'alarm6'
+  | 'alarm7'
+  | 'alarm8'
+  | 'alarm9';
+export type LocaleCode = 'en' | 'nb';
+
+export type CalendarType = 'chronological' | 'time-based';
+export type ClockType = 'digital' | 'analog';
+export type TimePickerMode = 'dials' | 'keypad';
+export type AlarmTimeout = 1 | 2 | 3 | 5 | 10;
+export const ALARM_TIMEOUTS: AlarmTimeout[] = [1, 2, 3, 5, 10];
+export type CalendarViewMode =
+  | 'day'
+  | '3-days'
+  | '5-days'
+  | '7-days'
+  | 'week'
+  | 'month'
+  | 'overview';
+export type CalendarDayViewCellZoom = 15 | 30 | 60;
+export type InactivityTimeoutMinutes = 1 | 5 | 10 | 15 | 30 | 45;
+export type LockScreenClockDisplay = 'none' | 'digital' | 'analog';
+export type LockScreenImageMode = 'none' | 'background' | 'photoFrame';
+export type PhotoFrameIntervalSeconds = 30 | 60 | 120 | 300;
+export type EventVisibility = 'Public' | 'Private' | 'Custom';
+export type SuggestEndTimeUnit = 'minutes' | 'hours';
+
+export type WeatherLocation = {
+  address: string;
+  name?: string;
+  latitude: number;
+  longitude: number;
+  placeId?: string;
+};
+
+export type LockScreenImage = {
+  uri: string;
+  filePath: string;
+  fileName?: string;
+  fileSize?: number;
+  width?: number;
+  height?: number;
+  order: number;
+};
+
+export const LOCK_SCREEN_MAX_IMAGES = 10;
+
+export type AllDayPreset = {
+  daysBefore: number;
+  time: string;
+};
+
+// ---------------------------------------------------------------------------
+// Setting categories — used for UI grouping and profile organization
+// ---------------------------------------------------------------------------
+
+export const SETTINGS_CATEGORIES = [
+  'appearance',
+  'calendarView',
+  'calendars',
+  'sound',
+  'timer',
+  'media',
+  'lockScreen',
+  'touch',
+  'device',
+  'language',
+  'notification',
+  'chronological',
+  'eventForm',
+  'chronologicalEventForm',
+] as const;
+
+export type SettingsCategory = (typeof SETTINGS_CATEGORIES)[number];
+
+// ---------------------------------------------------------------------------
+// Data type discriminator — stored alongside each setting in the DB
+// ---------------------------------------------------------------------------
+
+export type SettingsDataType = 'string' | 'number' | 'boolean' | 'json';
+
+// ---------------------------------------------------------------------------
+// Single registry entry definition
+// ---------------------------------------------------------------------------
+
+export type SettingDef<T = unknown> = {
+  category: SettingsCategory;
+  type: SettingsDataType;
+  default: T;
+  /** Whether this setting should be synced to the server. Default true. */
+  sync: boolean;
+};
+
+// ---------------------------------------------------------------------------
+// Configuration for app-specific defaults
+// ---------------------------------------------------------------------------
+
+export type RegistryConfig = {
+  /** Whether the device is in enrolled/kiosk mode */
+  isEnrolled: boolean;
+  /** Default theme code */
+  defaultTheme: ThemeSetting;
+  /** Default locale code */
+  defaultLocale: LocaleCode;
+};
+
+/** Default config for non-enrolled mode */
+export const DEFAULT_REGISTRY_CONFIG: RegistryConfig = {
+  isEnrolled: false,
+  defaultTheme: 'system',
+  defaultLocale: 'nb',
+};
+
+// ---------------------------------------------------------------------------
+// Helper
+// ---------------------------------------------------------------------------
+
+function def<T>(
+  category: SettingsCategory,
+  type: SettingsDataType,
+  defaultValue: T,
+  sync = true,
+): SettingDef<T> {
+  return { category, type, default: defaultValue, sync };
+}
+
+// ---------------------------------------------------------------------------
+// Entry builder (internal — used by SettingsRegistry class and factory)
+// ---------------------------------------------------------------------------
+
+function buildEntries(config: RegistryConfig) {
+  return {
+    // ═══════════════════════════════════════════════════════════════════════
+    // Appearance
+    // ═══════════════════════════════════════════════════════════════════════
+    'appearance.theme': def<ThemeSetting>(
+      'appearance',
+      'string',
+      config.defaultTheme,
+    ),
+    'appearance.clockType': def<ClockType>('appearance', 'string', 'digital'),
+    'appearance.enableDayColors': def<boolean>('appearance', 'boolean', false),
+
+    // ═══════════════════════════════════════════════════════════════════════
+    // Calendar view
+    // ═══════════════════════════════════════════════════════════════════════
+    'calendarView.type': def<CalendarType>(
+      'calendarView',
+      'string',
+      'time-based',
+    ),
+    'calendarView.view': def<CalendarViewMode>('calendarView', 'string', 'day'),
+    'calendarView.dayViewZoom': def<CalendarDayViewCellZoom>(
+      'calendarView',
+      'number',
+      60,
+    ),
+    'calendarView.weekViewZoom': def<CalendarDayViewCellZoom>(
+      'calendarView',
+      'number',
+      60,
+    ),
+    'calendarView.splitView': def<boolean>('calendarView', 'boolean', false),
+    'calendarView.showCalendarNames': def<boolean>(
+      'calendarView',
+      'boolean',
+      true,
+    ),
+    'calendarView.calendarColumns': def<unknown[]>('calendarView', 'json', []),
+    'calendarView.autoReturnToTodayEnabled': def<boolean>(
+      'calendarView',
+      'boolean',
+      config.isEnrolled,
+    ),
+    'calendarView.autoReturnToTodayTimeoutSeconds': def<number>(
+      'calendarView',
+      'number',
+      300,
+    ),
+    'calendarView.showWeatherOnEvents': def<boolean>(
+      'calendarView',
+      'boolean',
+      false,
+    ),
+    'calendarView.showWeatherOnTimeline': def<boolean>(
+      'calendarView',
+      'boolean',
+      false,
+    ),
+    'calendarView.weatherLocation': def<WeatherLocation | null>(
+      'calendarView',
+      'json',
+      null,
+    ),
+
+    // ═══════════════════════════════════════════════════════════════════════
+    // Event form field visibility (time-based)
+    // ═══════════════════════════════════════════════════════════════════════
+    'eventForm.recurrence': def<boolean>('eventForm', 'boolean', true),
+    'eventForm.reminders': def<boolean>('eventForm', 'boolean', true),
+    'eventForm.emailReminders': def<boolean>('eventForm', 'boolean', false),
+    'eventForm.location': def<boolean>('eventForm', 'boolean', true),
+    'eventForm.travelTime': def<boolean>('eventForm', 'boolean', false),
+    'eventForm.description': def<boolean>('eventForm', 'boolean', true),
+    'eventForm.checklist': def<boolean>('eventForm', 'boolean', true),
+    'eventForm.images': def<boolean>('eventForm', 'boolean', false),
+    'eventForm.audioClips': def<boolean>('eventForm', 'boolean', false),
+    'eventForm.notificationReceivers': def<boolean>(
+      'eventForm',
+      'boolean',
+      true,
+    ),
+    'eventForm.visibility': def<boolean>('eventForm', 'boolean', false),
+
+    // ═══════════════════════════════════════════════════════════════════════
+    // Sound & alerts
+    // ═══════════════════════════════════════════════════════════════════════
+    'sound.timerVolume': def<number>('sound', 'number', 0.5),
+    'sound.reminderVolume': def<number>('sound', 'number', 0.5),
+    'sound.mediaVolume': def<number>('sound', 'number', 0.5),
+    'sound.alarmSound': def<AlarmSound>('sound', 'string', 'alarm1'),
+    'sound.reminderAlarmSound': def<AlarmSound>('sound', 'string', 'alarm1'),
+    'sound.timerAlarmSound': def<AlarmSound>('sound', 'string', 'alarm1'),
+    'sound.timerAlarmTimeout': def<AlarmTimeout>('sound', 'number', 3),
+    'sound.reminderAlarmTimeout': def<AlarmTimeout>('sound', 'number', 3),
+    'sound.allowCustomReminderSounds': def<boolean>('sound', 'boolean', false),
+    'sound.ttsEnabled': def<boolean>('sound', 'boolean', config.isEnrolled),
+    'sound.ttsRate': def<number>('sound', 'number', 1.0),
+
+    // ═══════════════════════════════════════════════════════════════════════
+    // Timer
+    // ═══════════════════════════════════════════════════════════════════════
+    'timer.showTimeRemaining': def<boolean>('timer', 'boolean', true),
+    'timer.showEndTime': def<boolean>('timer', 'boolean', true),
+    'timer.showRestartButton': def<boolean>('timer', 'boolean', true),
+    'timer.showPauseButton': def<boolean>('timer', 'boolean', true),
+
+    // ═══════════════════════════════════════════════════════════════════════
+    // Lock screen
+    // ═══════════════════════════════════════════════════════════════════════
+    'lockScreen.pin': def<string>('lockScreen', 'string', ''),
+    'lockScreen.inactivityLockEnabled': def<boolean>(
+      'lockScreen',
+      'boolean',
+      false,
+    ),
+    'lockScreen.inactivityTimeoutMinutes': def<InactivityTimeoutMinutes>(
+      'lockScreen',
+      'number',
+      5,
+    ),
+    'lockScreen.clockDisplay': def<LockScreenClockDisplay>(
+      'lockScreen',
+      'string',
+      'digital',
+    ),
+    'lockScreen.showDate': def<boolean>('lockScreen', 'boolean', true),
+    'lockScreen.showHourNumbers': def<boolean>('lockScreen', 'boolean', true),
+    'lockScreen.imageMode': def<LockScreenImageMode>(
+      'lockScreen',
+      'string',
+      'none',
+    ),
+    'lockScreen.backgroundImage': def<string | null>(
+      'lockScreen',
+      'json',
+      null,
+    ),
+    'lockScreen.photoFrameImages': def<LockScreenImage[]>(
+      'lockScreen',
+      'json',
+      [],
+    ),
+    'lockScreen.photoFrameIntervalSeconds': def<PhotoFrameIntervalSeconds>(
+      'lockScreen',
+      'number',
+      60,
+    ),
+
+    // ═══════════════════════════════════════════════════════════════════════
+    // Touch / gestures
+    // ═══════════════════════════════════════════════════════════════════════
+    'touch.enableTapToCreate': def<boolean>('touch', 'boolean', false),
+    'touch.enableDragDrop': def<boolean>('touch', 'boolean', false),
+
+    // ═══════════════════════════════════════════════════════════════════════
+    // Device (not synced unless noted)
+    // ═══════════════════════════════════════════════════════════════════════
+    'device.id': def<string>('device', 'string', '', false),
+    'device.timePickerMode': def<TimePickerMode>('device', 'string', 'dials'),
+    'device.devMenuEnabled': def<boolean>('device', 'boolean', false, false),
+    'device.authWarningDismissTtlDays': def<number>(
+      'device',
+      'number',
+      3,
+      false,
+    ),
+
+    // ═══════════════════════════════════════════════════════════════════════
+    // Language
+    // ═══════════════════════════════════════════════════════════════════════
+    'language.locale': def<LocaleCode>(
+      'language',
+      'string',
+      config.defaultLocale,
+    ),
+
+    // ═══════════════════════════════════════════════════════════════════════
+    // Notifications
+    // ═══════════════════════════════════════════════════════════════════════
+    'notification.enabled': def<boolean>('notification', 'boolean', false),
+    'notification.notifyAllCalendars': def<boolean>(
+      'notification',
+      'boolean',
+      true,
+    ),
+    'notification.enabledCalendarIds': def<string[]>(
+      'notification',
+      'json',
+      [],
+    ),
+    'notification.hasBeenPrompted': def<boolean>(
+      'notification',
+      'boolean',
+      false,
+      false,
+    ),
+
+    // ═══════════════════════════════════════════════════════════════════════
+    // Chronological features (header, footer, menu, quick settings, timer)
+    // ═══════════════════════════════════════════════════════════════════════
+    // Header
+    'chronological.header.showNavigationArrows': def<boolean>(
+      'chronological',
+      'boolean',
+      true,
+    ),
+    'chronological.header.showClock': def<boolean>(
+      'chronological',
+      'boolean',
+      true,
+    ),
+    'chronological.header.showCurrentYearInDate': def<boolean>(
+      'chronological',
+      'boolean',
+      false,
+    ),
+    'chronological.header.showTimeOfDay': def<boolean>(
+      'chronological',
+      'boolean',
+      false,
+    ),
+    // Footer
+    'chronological.footer.showMenuButton': def<boolean>(
+      'chronological',
+      'boolean',
+      true,
+    ),
+    'chronological.footer.showViewSwitcherDay': def<boolean>(
+      'chronological',
+      'boolean',
+      true,
+    ),
+    'chronological.footer.showViewSwitcherWeek': def<boolean>(
+      'chronological',
+      'boolean',
+      true,
+    ),
+    'chronological.footer.showViewSwitcherMonth': def<boolean>(
+      'chronological',
+      'boolean',
+      true,
+    ),
+    'chronological.footer.showTimerButton': def<boolean>(
+      'chronological',
+      'boolean',
+      true,
+    ),
+    'chronological.footer.showNewEventButton': def<boolean>(
+      'chronological',
+      'boolean',
+      true,
+    ),
+    'chronological.footer.showSettingsButton': def<boolean>(
+      'chronological',
+      'boolean',
+      true,
+    ),
+    // Timer features
+    'chronological.timer.showNewCountdown': def<boolean>(
+      'chronological',
+      'boolean',
+      true,
+    ),
+    'chronological.timer.showFromTemplate': def<boolean>(
+      'chronological',
+      'boolean',
+      true,
+    ),
+    'chronological.timer.showEditTemplate': def<boolean>(
+      'chronological',
+      'boolean',
+      true,
+    ),
+    'chronological.timer.showDeleteTemplate': def<boolean>(
+      'chronological',
+      'boolean',
+      true,
+    ),
+    'chronological.timer.showAddTemplate': def<boolean>(
+      'chronological',
+      'boolean',
+      true,
+    ),
+    // Menu
+    'chronological.menu.showSettingsButton': def<boolean>(
+      'chronological',
+      'boolean',
+      true,
+    ),
+    // Quick settings
+    'chronological.quickSettings.showTimerVolume': def<boolean>(
+      'chronological',
+      'boolean',
+      true,
+    ),
+    'chronological.quickSettings.showReminderVolume': def<boolean>(
+      'chronological',
+      'boolean',
+      true,
+    ),
+    'chronological.quickSettings.showMediaVolume': def<boolean>(
+      'chronological',
+      'boolean',
+      true,
+    ),
+    'chronological.quickSettings.showBrightness': def<boolean>(
+      'chronological',
+      'boolean',
+      true,
+    ),
+    'chronological.quickSettings.showLockScreen': def<boolean>(
+      'chronological',
+      'boolean',
+      true,
+    ),
+    // Time-of-day periods
+    'chronological.timeOfDay.morningStart': def<number>(
+      'chronological',
+      'number',
+      6,
+    ),
+    'chronological.timeOfDay.forenoonStart': def<number>(
+      'chronological',
+      'number',
+      9,
+    ),
+    'chronological.timeOfDay.afternoonStart': def<number>(
+      'chronological',
+      'number',
+      12,
+    ),
+    'chronological.timeOfDay.eveningStart': def<number>(
+      'chronological',
+      'number',
+      18,
+    ),
+    'chronological.timeOfDay.nightStart': def<number>(
+      'chronological',
+      'number',
+      0,
+    ),
+
+    // ═══════════════════════════════════════════════════════════════════════
+    // Chronological event form
+    // ═══════════════════════════════════════════════════════════════════════
+    // Toggleable fields
+    'chronologicalEventForm.field.description': def<boolean>(
+      'chronologicalEventForm',
+      'boolean',
+      true,
+    ),
+    'chronologicalEventForm.field.recurrence': def<boolean>(
+      'chronologicalEventForm',
+      'boolean',
+      true,
+    ),
+    'chronologicalEventForm.field.acknowledge': def<boolean>(
+      'chronologicalEventForm',
+      'boolean',
+      true,
+    ),
+    'chronologicalEventForm.field.checklist': def<boolean>(
+      'chronologicalEventForm',
+      'boolean',
+      true,
+    ),
+    'chronologicalEventForm.field.extraImages': def<boolean>(
+      'chronologicalEventForm',
+      'boolean',
+      true,
+    ),
+    'chronologicalEventForm.field.reminders': def<boolean>(
+      'chronologicalEventForm',
+      'boolean',
+      true,
+    ),
+    'chronologicalEventForm.field.audioClips': def<boolean>(
+      'chronologicalEventForm',
+      'boolean',
+      true,
+    ),
+    // Fixed fields
+    'chronologicalEventForm.fixedField.allDay': def<boolean>(
+      'chronologicalEventForm',
+      'boolean',
+      true,
+    ),
+    'chronologicalEventForm.fixedField.endTime': def<boolean>(
+      'chronologicalEventForm',
+      'boolean',
+      true,
+    ),
+    'chronologicalEventForm.fixedField.visibility': def<boolean>(
+      'chronologicalEventForm',
+      'boolean',
+      true,
+    ),
+    // Suggest end time
+    'chronologicalEventForm.suggestEndTime.enabled': def<boolean>(
+      'chronologicalEventForm',
+      'boolean',
+      false,
+    ),
+    'chronologicalEventForm.suggestEndTime.value': def<number>(
+      'chronologicalEventForm',
+      'number',
+      30,
+    ),
+    'chronologicalEventForm.suggestEndTime.unit': def<SuggestEndTimeUnit>(
+      'chronologicalEventForm',
+      'string',
+      'minutes',
+    ),
+    // Default visibility
+    'chronologicalEventForm.defaultVisibility': def<EventVisibility>(
+      'chronologicalEventForm',
+      'string',
+      'Private',
+    ),
+    // Reminder presets
+    'chronologicalEventForm.reminderPresets.timed': def<number[]>(
+      'chronologicalEventForm',
+      'json',
+      [5, 15, 30, 60, 120, 1440],
+    ),
+    'chronologicalEventForm.reminderPresets.allDay': def<AllDayPreset[]>(
+      'chronologicalEventForm',
+      'json',
+      [
+        { daysBefore: 0, time: '09:00' },
+        { daysBefore: 1, time: '18:00' },
+        { daysBefore: 2, time: '09:00' },
+      ],
+    ),
+  } as const satisfies Record<string, SettingDef>;
+}
+
+// ---------------------------------------------------------------------------
+// Derived types (based on entry shape — all configs produce the same keys)
+// ---------------------------------------------------------------------------
+
+type SettingsEntries = ReturnType<typeof buildEntries>;
+
+/** Union type of every valid setting key */
+export type SettingKey = keyof SettingsEntries;
+
+/** Type-safe value type for a given setting key */
+export type SettingValue<K extends SettingKey> = SettingsEntries[K]['default'];
+
+/** Complete settings map — all keys resolved to their value types */
+export type SettingsMap = {
+  [K in SettingKey]: SettingValue<K>;
+};
+
+// ---------------------------------------------------------------------------
+// Registry class
+// ---------------------------------------------------------------------------
+
+export class SettingsRegistry {
+  /** The raw setting definitions (category, type, default, sync) */
+  readonly entries: SettingsEntries;
+
+  /** All setting keys as an array */
+  readonly keys: SettingKey[];
+
+  constructor(config: Partial<RegistryConfig> = {}) {
+    const full: RegistryConfig = { ...DEFAULT_REGISTRY_CONFIG, ...config };
+    this.entries = buildEntries(full);
+    this.keys = Object.keys(this.entries) as SettingKey[];
+  }
+
+  /** Get the default value for a setting */
+  getDefault<K extends SettingKey>(key: K): SettingValue<K> {
+    return this.entries[key].default as SettingValue<K>;
+  }
+
+  /** Get a complete map of all default values */
+  getAllDefaults(): SettingsMap {
+    const defaults = {} as Record<string, unknown>;
+    for (const key of this.keys) {
+      defaults[key] = this.entries[key].default;
+    }
+    return defaults as SettingsMap;
+  }
+
+  /** Get the data type for a setting key */
+  getDataType(key: SettingKey): SettingsDataType {
+    return this.entries[key].type;
+  }
+
+  /** Check whether a setting should be synced */
+  isSynced(key: SettingKey): boolean {
+    return this.entries[key].sync;
+  }
+
+  /** Get all setting keys for a category */
+  getByCategory(category: SettingsCategory): SettingKey[] {
+    return this.keys.filter((key) => this.entries[key].category === category);
+  }
+
+  /** Serialize a setting value to a string for DB storage */
+  serialize(key: SettingKey, value: unknown): string {
+    const dataType = this.getDataType(key);
+    switch (dataType) {
+      case 'string':
+        return String(value ?? '');
+      case 'number':
+        return String(value ?? 0);
+      case 'boolean':
+        return value ? 'true' : 'false';
+      case 'json':
+        return JSON.stringify(value);
+    }
+  }
+
+  /** Deserialize a DB string back to a typed setting value */
+  deserialize<K extends SettingKey>(
+    key: K,
+    raw: string | null,
+  ): SettingValue<K> {
+    if (raw === null || raw === undefined) {
+      return this.getDefault(key);
+    }
+
+    const dataType = this.getDataType(key);
+    switch (dataType) {
+      case 'string':
+        return raw as SettingValue<K>;
+      case 'number':
+        return Number(raw) as SettingValue<K>;
+      case 'boolean':
+        return (raw === 'true') as SettingValue<K>;
+      case 'json':
+        try {
+          return JSON.parse(raw) as SettingValue<K>;
+        } catch {
+          return this.getDefault(key);
+        }
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Default registry instance (non-enrolled, system theme, nb locale)
+// ---------------------------------------------------------------------------
+
+export const defaultRegistry = new SettingsRegistry();
+
+// ---------------------------------------------------------------------------
+// Factory function — returns raw entry map for local type derivation.
+// Consumers that need precise generic inference (e.g. useQuery<K>) can use
+// this to anchor types on a local const variable.
+// ---------------------------------------------------------------------------
+
+export function createSettingsRegistry(config: Partial<RegistryConfig> = {}) {
+  return buildEntries({ ...DEFAULT_REGISTRY_CONFIG, ...config });
+}