@focus8/settings-registry 0.7.0 → 0.8.0

package/src/index.ts

@@ -285,7 +285,7 @@ export const SETTINGS_GROUPS: readonly SettingsGroupDef[] = [
     id: 'calendarType',
     labelKey: 'Settings.CalendarType',
     icon: 'ArrowLeftRight',
-    keys: ['calendarView.type', 'calendarView.view'],
+    keys: ['calendarView.type'],
   },
   {
     id: 'calendarView',
@@ -294,9 +294,9 @@ export const SETTINGS_GROUPS: readonly SettingsGroupDef[] = [
     keys: [
       'calendarView.showCalendarNames',
       'calendarView.splitView',
-      'calendarView.calendarColumns',
       'calendarView.dayViewZoom',
       'calendarView.weekViewZoom',
+      'calendarView.calendarColumns',
     ],
   },
   {
@@ -310,9 +310,9 @@ export const SETTINGS_GROUPS: readonly SettingsGroupDef[] = [
     labelKey: 'Settings.DateWeather',
     icon: 'CloudSun',
     keys: [
-      'calendarView.showWeatherOnEvents',
       'calendarView.showWeatherOnTimeline',
       'calendarView.weatherLocation',
+      'calendarView.showWeatherOnEvents',
     ],
   },
   {
@@ -322,13 +322,13 @@ export const SETTINGS_GROUPS: readonly SettingsGroupDef[] = [
     keys: [
       'sound.reminderVolume',
       'sound.mediaVolume',
-      'sound.alarmSound',
       'sound.reminderAlarmSound',
       'sound.reminderAlarmTimeout',
       'sound.allowCustomReminderSounds',
+      'notification.',
       'sound.ttsEnabled',
       'sound.ttsRate',
-      'notification.',
+      'sound.alarmSound',
     ],
   },
   {
@@ -336,10 +336,11 @@ export const SETTINGS_GROUPS: readonly SettingsGroupDef[] = [
     labelKey: 'Settings.TimerTitle',
     icon: 'Timer',
     keys: [
-      'sound.timerVolume',
+      'chronological.timer.',
+      'timer.',
       'sound.timerAlarmSound',
       'sound.timerAlarmTimeout',
-      'timer.',
+      'sound.timerVolume',
     ],
     appMode: 'ENROLLED',
   },
@@ -389,6 +390,9 @@ export const EXCLUDED_DEVICE_SETTINGS: ReadonlySet<string> = new Set([
   'device.id',
   'device.devMenuEnabled',
   'device.authWarningDismissTtlDays',
+  'notification.enabled',
+  'notification.notifyAllCalendars',
+  'notification.enabledCalendarIds',
   'notification.hasBeenPrompted',
 ]);
 
@@ -647,6 +651,33 @@ function matchesGroup(key: string, group: SettingsGroupDef): boolean {
   );
 }
 
+/** Return the index of the first matching key pattern in the group, for sorting. */
+function groupKeyIndex(key: string, keys: readonly string[]): number {
+  for (let i = 0; i < keys.length; i++) {
+    const matcher = keys[i];
+    if (key === matcher || (matcher.endsWith('.') && key.startsWith(matcher))) {
+      return i;
+    }
+  }
+  return keys.length;
+}
+
+/**
+ * Lazy-initialized map from setting key → declaration index in buildEntries.
+ * Used as a tiebreaker when multiple keys share the same prefix group index.
+ */
+let _registryKeyOrder: Map<string, number> | undefined;
+function registryKeyOrder(): Map<string, number> {
+  if (!_registryKeyOrder) {
+    _registryKeyOrder = new Map();
+    const keys = Object.keys(buildEntries(DEFAULT_REGISTRY_CONFIG));
+    for (let i = 0; i < keys.length; i++) {
+      _registryKeyOrder.set(keys[i], i);
+    }
+  }
+  return _registryKeyOrder;
+}
+
 /**
  * Group parsed setting entries into user-facing groups matching the mobile
  * app's settings menu structure.
@@ -674,6 +705,14 @@ export function groupSettingsForDevice(
     if (!isChronological && s.key.startsWith('chronologicalEventForm.')) {
       return false;
     }
+    // Per-setting calendar type restriction
+    if (s.calendarType && s.calendarType !== calendarType) {
+      return false;
+    }
+    // Per-setting app mode restriction
+    if (s.appMode && s.appMode !== appMode) {
+      return false;
+    }
     return true;
   });
 
@@ -703,6 +742,18 @@ export function groupSettingsForDevice(
       continue;
     }
 
+    // Sort matched settings by the order defined in group.keys,
+    // with registry declaration order as tiebreaker for prefix matches
+    const order = registryKeyOrder();
+    matched.sort((a, b) => {
+      const aIdx = groupKeyIndex(a.key, group.keys);
+      const bIdx = groupKeyIndex(b.key, group.keys);
+      if (aIdx !== bIdx) {
+        return aIdx - bIdx;
+      }
+      return (order.get(a.key) ?? Infinity) - (order.get(b.key) ?? Infinity);
+    });
+
     for (const s of matched) {
       claimed.add(s.key);
     }
@@ -740,6 +791,10 @@ export type SettingDef<T = unknown> = {
   options?: readonly SettingOption<T>[];
   /** Slider configuration for SLIDER-type settings */
   sliderConfig?: SliderConfig;
+  /** Only show this setting for enrolled/kiosk devices (undefined = always) */
+  appMode?: 'ENROLLED';
+  /** Only show this setting for a specific calendar type (undefined = always) */
+  calendarType?: CalendarType;
 };
 
 // ---------------------------------------------------------------------------
@@ -790,7 +845,7 @@ const ALARM_TIMEOUT_OPTIONS: readonly SettingOption<AlarmTimeout>[] = [
 const DAY_VIEW_ZOOM_OPTIONS: readonly SettingOption<CalendarDayViewCellZoom>[] = [
   { value: 15, labelKey: 'Settings.Option.DayViewZoom.15min' },
   { value: 30, labelKey: 'Settings.Option.DayViewZoom.30min' },
-  { value: 60, labelKey: 'Settings.Option.DayViewZoom.60min' },
+  { value: 60, labelKey: 'Settings.Option.DayViewZoom.1hour' },
 ];
 
 const TIME_OF_DAY_SLIDER: SliderConfig = { min: 0, max: 23, step: 1 };
@@ -808,6 +863,8 @@ function def<T>(
     sync?: boolean;
     options?: readonly SettingOption<T>[];
     sliderConfig?: SliderConfig;
+    appMode?: 'ENROLLED';
+    calendarType?: CalendarType;
   },
 ): SettingDef<T> {
   const result: SettingDef<T> = {
@@ -823,6 +880,12 @@ function def<T>(
   if (extra?.sliderConfig) {
     result.sliderConfig = extra.sliderConfig;
   }
+  if (extra?.appMode) {
+    result.appMode = extra.appMode;
+  }
+  if (extra?.calendarType) {
+    result.calendarType = extra.calendarType;
+  }
   return result;
 }
 
@@ -858,6 +921,7 @@ function buildEntries(config: RegistryConfig) {
           { value: 'digital', labelKey: 'Settings.Option.ClockType.Digital' },
           { value: 'analog', labelKey: 'Settings.Option.ClockType.Analog' },
         ],
+        appMode: 'ENROLLED',
       },
     ),
     'appearance.enableDayColors': def<boolean>(
@@ -865,6 +929,7 @@ function buildEntries(config: RegistryConfig) {
       'boolean',
       false,
       'TOGGLE',
+      { calendarType: 'chronological' },
     ),
 
     // ═══════════════════════════════════════════════════════════════════════
@@ -925,14 +990,14 @@ function buildEntries(config: RegistryConfig) {
       'number',
       60,
       'SELECT',
-      { options: DAY_VIEW_ZOOM_OPTIONS },
+      { options: DAY_VIEW_ZOOM_OPTIONS, calendarType: 'time-based' },
     ),
     'calendarView.weekViewZoom': def<CalendarDayViewCellZoom>(
       'calendarView',
       'number',
       60,
       'SELECT',
-      { options: DAY_VIEW_ZOOM_OPTIONS },
+      { options: DAY_VIEW_ZOOM_OPTIONS, calendarType: 'time-based' },
     ),
     'calendarView.splitView': def<boolean>(
       'calendarView',
@@ -988,10 +1053,10 @@ function buildEntries(config: RegistryConfig) {
     // Event form field visibility (time-based)
     // ═══════════════════════════════════════════════════════════════════════
     'eventForm.recurrence': def<boolean>('eventForm', 'boolean', true, 'TOGGLE'),
-    'eventForm.reminders': def<boolean>('eventForm', 'boolean', true, 'TOGGLE'),
-    'eventForm.emailReminders': def<boolean>('eventForm', 'boolean', false, 'TOGGLE'),
     'eventForm.location': def<boolean>('eventForm', 'boolean', true, 'TOGGLE'),
     'eventForm.travelTime': def<boolean>('eventForm', 'boolean', false, 'TOGGLE'),
+    'eventForm.reminders': def<boolean>('eventForm', 'boolean', true, 'TOGGLE'),
+    'eventForm.emailReminders': def<boolean>('eventForm', 'boolean', false, 'TOGGLE'),
     'eventForm.description': def<boolean>('eventForm', 'boolean', true, 'TOGGLE'),
     'eventForm.checklist': def<boolean>('eventForm', 'boolean', true, 'TOGGLE'),
     'eventForm.images': def<boolean>('eventForm', 'boolean', false, 'TOGGLE'),
@@ -1008,8 +1073,8 @@ function buildEntries(config: RegistryConfig) {
     // Sound & alerts
     // ═══════════════════════════════════════════════════════════════════════
     'sound.timerVolume': def<number>('sound', 'number', 0.5, 'VOLUME_SLIDER'),
-    'sound.reminderVolume': def<number>('sound', 'number', 0.5, 'VOLUME_SLIDER'),
-    'sound.mediaVolume': def<number>('sound', 'number', 0.5, 'VOLUME_SLIDER'),
+    'sound.reminderVolume': def<number>('sound', 'number', 0.5, 'VOLUME_SLIDER', { appMode: 'ENROLLED' }),
+    'sound.mediaVolume': def<number>('sound', 'number', 0.5, 'VOLUME_SLIDER', { appMode: 'ENROLLED' }),
     'sound.alarmSound': def<AlarmSound>(
       'sound',
       'string',
@@ -1056,13 +1121,14 @@ function buildEntries(config: RegistryConfig) {
       'boolean',
       config.isEnrolled,
       'TOGGLE',
+      { appMode: 'ENROLLED' },
     ),
     'sound.ttsRate': def<number>(
       'sound',
       'number',
       1.0,
       'SLIDER',
-      { sliderConfig: { min: 0.5, max: 2, step: 0.1 } },
+      { sliderConfig: { min: 0.5, max: 2, step: 0.1 }, appMode: 'ENROLLED' },
     ),
 
     // ═══════════════════════════════════════════════════════════════════════
@@ -1076,7 +1142,6 @@ function buildEntries(config: RegistryConfig) {
     // ═══════════════════════════════════════════════════════════════════════
     // Lock screen
     // ═══════════════════════════════════════════════════════════════════════
-    'lockScreen.pin': def<string>('lockScreen', 'string', '', 'PIN_INPUT'),
     'lockScreen.inactivityLockEnabled': def<boolean>(
       'lockScreen',
       'boolean',
@@ -1099,6 +1164,7 @@ function buildEntries(config: RegistryConfig) {
         ],
       },
     ),
+    'lockScreen.pin': def<string>('lockScreen', 'string', '', 'PIN_INPUT'),
     'lockScreen.clockDisplay': def<LockScreenClockDisplay>(
       'lockScreen',
       'string',
@@ -1118,13 +1184,13 @@ function buildEntries(config: RegistryConfig) {
         ],
       },
     ),
-    'lockScreen.showDate': def<boolean>(
+    'lockScreen.showHourNumbers': def<boolean>(
       'lockScreen',
       'boolean',
       true,
       'TOGGLE',
     ),
-    'lockScreen.showHourNumbers': def<boolean>(
+    'lockScreen.showDate': def<boolean>(
       'lockScreen',
       'boolean',
       true,
@@ -1155,12 +1221,6 @@ function buildEntries(config: RegistryConfig) {
       null,
       'CUSTOM_IMAGE',
     ),
-    'lockScreen.photoFrameImages': def<LockScreenImage[]>(
-      'lockScreen',
-      'json',
-      [],
-      'CUSTOM_IMAGE_ARRAY',
-    ),
     'lockScreen.photoFrameIntervalSeconds': def<PhotoFrameIntervalSeconds>(
       'lockScreen',
       'number',
@@ -1176,6 +1236,13 @@ function buildEntries(config: RegistryConfig) {
       },
     ),
 
+    'lockScreen.photoFrameImages': def<LockScreenImage[]>(
+      'lockScreen',
+      'json',
+      [],
+      'CUSTOM_IMAGE_ARRAY',
+    ),
+
     // ═══════════════════════════════════════════════════════════════════════
     // Touch / gestures
     // ═══════════════════════════════════════════════════════════════════════
@@ -1271,16 +1338,16 @@ function buildEntries(config: RegistryConfig) {
       true,
       'TOGGLE',
     ),
-    'chronological.header.showClock': def<boolean>(
+    'chronological.header.showCurrentYearInDate': def<boolean>(
       'chronological',
       'boolean',
-      true,
+      false,
       'TOGGLE',
     ),
-    'chronological.header.showCurrentYearInDate': def<boolean>(
+    'chronological.header.showClock': def<boolean>(
       'chronological',
       'boolean',
-      false,
+      true,
       'TOGGLE',
     ),
     'chronological.header.showTimeOfDay': def<boolean>(
@@ -1345,19 +1412,19 @@ function buildEntries(config: RegistryConfig) {
       true,
       'TOGGLE',
     ),
-    'chronological.timer.showEditTemplate': def<boolean>(
+    'chronological.timer.showAddTemplate': def<boolean>(
       'chronological',
       'boolean',
       true,
       'TOGGLE',
     ),
-    'chronological.timer.showDeleteTemplate': def<boolean>(
+    'chronological.timer.showEditTemplate': def<boolean>(
       'chronological',
       'boolean',
       true,
       'TOGGLE',
     ),
-    'chronological.timer.showAddTemplate': def<boolean>(
+    'chronological.timer.showDeleteTemplate': def<boolean>(
       'chronological',
       'boolean',
       true,
@@ -1441,63 +1508,63 @@ function buildEntries(config: RegistryConfig) {
     // ═══════════════════════════════════════════════════════════════════════
     // Chronological event form
     // ═══════════════════════════════════════════════════════════════════════
-    // Toggleable fields
-    'chronologicalEventForm.field.description': def<boolean>(
+    // Fixed fields
+    'chronologicalEventForm.fixedField.allDay': def<boolean>(
       'chronologicalEventForm',
       'boolean',
       true,
       'TOGGLE',
     ),
-    'chronologicalEventForm.field.recurrence': def<boolean>(
+    'chronologicalEventForm.fixedField.endTime': def<boolean>(
       'chronologicalEventForm',
       'boolean',
       true,
       'TOGGLE',
     ),
-    'chronologicalEventForm.field.acknowledge': def<boolean>(
+    'chronologicalEventForm.fixedField.visibility': def<boolean>(
       'chronologicalEventForm',
       'boolean',
       true,
       'TOGGLE',
     ),
-    'chronologicalEventForm.field.checklist': def<boolean>(
+    // Toggleable fields
+    'chronologicalEventForm.field.acknowledge': def<boolean>(
       'chronologicalEventForm',
       'boolean',
       true,
       'TOGGLE',
     ),
-    'chronologicalEventForm.field.extraImages': def<boolean>(
+    'chronologicalEventForm.field.description': def<boolean>(
       'chronologicalEventForm',
       'boolean',
       true,
       'TOGGLE',
     ),
-    'chronologicalEventForm.field.reminders': def<boolean>(
+    'chronologicalEventForm.field.recurrence': def<boolean>(
       'chronologicalEventForm',
       'boolean',
       true,
       'TOGGLE',
     ),
-    'chronologicalEventForm.field.audioClips': def<boolean>(
+    'chronologicalEventForm.field.checklist': def<boolean>(
       'chronologicalEventForm',
       'boolean',
       true,
       'TOGGLE',
     ),
-    // Fixed fields
-    'chronologicalEventForm.fixedField.allDay': def<boolean>(
+    'chronologicalEventForm.field.extraImages': def<boolean>(
       'chronologicalEventForm',
       'boolean',
       true,
       'TOGGLE',
     ),
-    'chronologicalEventForm.fixedField.endTime': def<boolean>(
+    'chronologicalEventForm.field.reminders': def<boolean>(
       'chronologicalEventForm',
       'boolean',
       true,
       'TOGGLE',
     ),
-    'chronologicalEventForm.fixedField.visibility': def<boolean>(
+    'chronologicalEventForm.field.audioClips': def<boolean>(
       'chronologicalEventForm',
       'boolean',
       true,
@@ -1641,8 +1708,21 @@ export class SettingsRegistry {
       case 'number':
         return String(value ?? 0);
       case 'boolean':
+        if (typeof value === 'string') {
+          return value === 'true' ? 'true' : 'false';
+        }
         return value ? 'true' : 'false';
       case 'json':
+        // If already a serialized JSON string, return as-is to avoid
+        // double-wrapping (e.g. JSON.stringify("[]") → "\"[]\"")
+        if (typeof value === 'string') {
+          try {
+            JSON.parse(value);
+            return value;
+          } catch {
+            return JSON.stringify(value);
+          }
+        }
         return JSON.stringify(value);
     }
   }
@@ -1666,7 +1746,17 @@ export class SettingsRegistry {
         return (raw === 'true') as SettingValue<K>;
       case 'json':
         try {
-          return JSON.parse(raw) as SettingValue<K>;
+          let result: unknown = JSON.parse(raw);
+          // Unwrap multiply-escaped JSON strings caused by repeated
+          // double-serialization (each push/pull cycle added a layer)
+          while (typeof result === 'string') {
+            try {
+              result = JSON.parse(result);
+            } catch {
+              break;
+            }
+          }
+          return result as SettingValue<K>;
         } catch {
           return this.getDefault(key);
         }
@@ -1731,6 +1821,10 @@ export type ParsedSettingEntry = {
   options?: readonly SettingOption[];
   /** Slider configuration for SLIDER-type settings */
   sliderConfig?: SliderConfig;
+  /** Only show this setting for enrolled/kiosk devices (undefined = always) */
+  appMode?: 'ENROLLED';
+  /** Only show this setting for a specific calendar type (undefined = always) */
+  calendarType?: CalendarType;
 };
 
 export type ParsedSettingsGroup = {
@@ -1802,6 +1896,8 @@ export function parseSettingsSnapshot(
       uiType: entryDef?.uiType ?? 'TEXT_INPUT',
       ...(entryDef?.options && { options: entryDef.options as readonly SettingOption[] }),
       ...(entryDef?.sliderConfig && { sliderConfig: entryDef.sliderConfig }),
+      ...(entryDef?.appMode && { appMode: entryDef.appMode }),
+      ...(entryDef?.calendarType && { calendarType: entryDef.calendarType }),
     });
   }
 
@@ -1845,6 +1941,51 @@ export function formatSettingValue(value: unknown): string {
   return String(value);
 }
 
+/**
+ * Serialize a settings object (with mixed native types) into a
+ * string-values-only snapshot suitable for pushing to a mobile device.
+ *
+ * Uses the registry's `serialize()` method for known keys so that
+ * booleans become "true"/"false", numbers become digit strings, etc.
+ * Unknown keys are converted with `String(value)`.
+ */
+export function serializeSettingsSnapshot(
+  settings: Record<string, unknown>,
+  registry: SettingsRegistry,
+): Record<string, string> {
+  const result: Record<string, string> = {};
+  for (const [key, value] of Object.entries(settings)) {
+    if (key in registry.entries) {
+      result[key] = registry.serialize(key as SettingKey, value);
+    } else {
+      result[key] = String(value ?? '');
+    }
+  }
+  return result;
+}
+
+/**
+ * Deserialize a settings snapshot (string values from the server/DB) into
+ * native-typed values using the registry.
+ *
+ * This ensures local state always contains native types (boolean, number, etc.)
+ * so that subsequent `serializeSettingsSnapshot` calls produce correct results.
+ */
+export function deserializeSettingsSnapshot(
+  snapshot: Record<string, unknown>,
+  registry: SettingsRegistry = defaultRegistry,
+): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(snapshot)) {
+    if (typeof value === 'string' && key in registry.entries) {
+      result[key] = registry.deserialize(key as SettingKey, value);
+    } else {
+      result[key] = value;
+    }
+  }
+  return result;
+}
+
 // ---------------------------------------------------------------------------
 // Default registry instance (non-enrolled, system theme, nb locale)
 // ---------------------------------------------------------------------------