@oxy.so/services 1.0.0

package/src/ui/hooks/useSettingToggle.ts

@@ -0,0 +1,151 @@
+import { useState, useCallback, useEffect } from 'react';
+import { toast } from '@oxy.so/bloom/toast';
+
+interface UseSettingToggleOptions {
+    /** Initial value of the setting */
+    initialValue: boolean;
+    /** Function to save the setting to the server */
+    onSave: (value: boolean) => Promise<void>;
+    /** Success message when saving */
+    successMessage?: string;
+    /** Error message when save fails */
+    errorMessage?: string;
+    /** Whether to revert on error (default: true) */
+    revertOnError?: boolean;
+    /** Whether to show success toast (default: false) */
+    showSuccessToast?: boolean;
+}
+
+interface UseSettingToggleReturn {
+    /** Current value */
+    value: boolean;
+    /** Whether the setting is being saved */
+    isSaving: boolean;
+    /** Toggle the setting (optimistic update with revert on error) */
+    toggle: () => Promise<void>;
+    /** Set the value directly */
+    setValue: (value: boolean) => void;
+}
+
+/**
+ * Hook for handling boolean toggle settings with optimistic updates.
+ * Automatically reverts to the previous value if the save fails.
+ *
+ * @example
+ * const { value, toggle, isSaving } = useSettingToggle({
+ *   initialValue: user.notificationsEnabled,
+ *   onSave: (value) => api.updateNotifications(value),
+ *   errorMessage: 'Failed to update notifications',
+ * });
+ *
+ * <Switch value={value} onValueChange={toggle} disabled={isSaving} />
+ */
+export function useSettingToggle(options: UseSettingToggleOptions): UseSettingToggleReturn {
+    const {
+        initialValue,
+        onSave,
+        successMessage,
+        errorMessage = 'Failed to save setting',
+        revertOnError = true,
+        showSuccessToast = false,
+    } = options;
+
+    const [value, setValue] = useState(initialValue);
+    const [isSaving, setIsSaving] = useState(false);
+
+    // Update value when initialValue changes (e.g., from server)
+    useEffect(() => {
+        setValue(initialValue);
+    }, [initialValue]);
+
+    const toggle = useCallback(async () => {
+        const previousValue = value;
+        const newValue = !value;
+
+        // Optimistic update
+        setValue(newValue);
+        setIsSaving(true);
+
+        try {
+            await onSave(newValue);
+
+            if (showSuccessToast && successMessage) {
+                toast.success(successMessage);
+            }
+        } catch (err: unknown) {
+            // Revert on error
+            if (revertOnError) {
+                setValue(previousValue);
+            }
+
+            toast.error(errorMessage || (err instanceof Error ? err.message : null) || 'An error occurred');
+        } finally {
+            setIsSaving(false);
+        }
+    }, [value, onSave, successMessage, errorMessage, revertOnError, showSuccessToast]);
+
+    return { value, isSaving, toggle, setValue };
+}
+
+/**
+ * Hook for managing multiple toggle settings at once.
+ * Useful when you have several related boolean settings.
+ */
+export function useSettingToggles<T extends { [K in keyof T]: boolean }>(options: {
+    initialValues: T;
+    onSave: (key: keyof T, value: boolean) => Promise<void>;
+    errorMessage?: string | ((key: keyof T) => string);
+    revertOnError?: boolean;
+}): {
+    values: T;
+    savingKeys: Set<keyof T>;
+    toggle: (key: keyof T) => Promise<void>;
+    setValues: (values: Partial<T>) => void;
+} {
+    const { initialValues, onSave, errorMessage = 'Failed to save setting', revertOnError = true } = options;
+
+    const [values, setValues] = useState<T>(initialValues);
+    const [savingKeys, setSavingKeys] = useState<Set<keyof T>>(new Set());
+
+    // Update values when initialValues change
+    useEffect(() => {
+        setValues(initialValues);
+    }, [initialValues]);
+
+    const toggle = useCallback(async (key: keyof T) => {
+        const previousValue = values[key];
+        const newValue = !previousValue;
+
+        // Optimistic update
+        setValues(prev => ({ ...prev, [key]: newValue }));
+        setSavingKeys(prev => new Set(prev).add(key));
+
+        try {
+            await onSave(key, newValue);
+        } catch (err: unknown) {
+            // Revert on error
+            if (revertOnError) {
+                setValues(prev => ({ ...prev, [key]: previousValue }));
+            }
+
+            const message = typeof errorMessage === 'function'
+                ? errorMessage(key)
+                : errorMessage;
+            toast.error(message || (err instanceof Error ? err.message : null) || 'An error occurred');
+        } finally {
+            setSavingKeys(prev => {
+                const next = new Set(prev);
+                next.delete(key);
+                return next;
+            });
+        }
+    }, [values, onSave, errorMessage, revertOnError]);
+
+    const setValuesExternal = useCallback((newValues: Partial<T>) => {
+        setValues(prev => ({ ...prev, ...newValues }));
+    }, []);
+
+    return { values, savingKeys, toggle, setValues: setValuesExternal };
+}
+
+export default useSettingToggle;

package/src/ui/hooks/useStorage.ts

@@ -0,0 +1,52 @@
+import { useEffect, useRef, useState } from 'react';
+import type { ApiError } from '@oxy.so/core';
+import { createPlatformStorage, type StorageInterface } from '../utils/storageHelpers';
+
+export interface UseStorageOptions {
+  onError?: (error: ApiError) => void;
+  logger?: (message: string, error?: unknown) => void;
+}
+
+export interface UseStorageResult {
+  storage: StorageInterface | null;
+  isReady: boolean;
+}
+
+/**
+ * Simple React hook that initializes platform-appropriate storage.
+ * Returns storage instance once ready, or null if initialization failed.
+ */
+export const useStorage = ({
+  onError,
+  logger,
+}: UseStorageOptions = {}): UseStorageResult => {
+  const [storage, setStorage] = useState<StorageInterface | null>(null);
+  const initRef = useRef<Promise<void> | null>(null);
+
+  useEffect(() => {
+    // Prevent multiple initializations
+    if (initRef.current) return;
+
+    initRef.current = (async () => {
+      try {
+        const storageInstance = await createPlatformStorage();
+        setStorage(storageInstance);
+      } catch (err) {
+        const message = err instanceof Error ? err.message : 'Failed to initialize storage';
+        if (logger) {
+          logger(message, err);
+        }
+        onError?.({
+          message,
+          code: 'STORAGE_INIT_ERROR',
+          status: 500,
+        });
+      }
+    })();
+  }, [logger, onError]);
+
+  return {
+    storage,
+    isReady: storage !== null,
+  };
+};

package/src/ui/hooks/useSurfaceHeader.ts

@@ -0,0 +1,194 @@
+import { createContext, useContext, useLayoutEffect, useRef } from 'react';
+import type { DialogHeaderConfig } from '@oxy.so/bloom/dialog';
+
+/**
+ * The header content a mounted surface screen contributes at runtime: its
+ * (translated) title/subtitle and optional slot nodes. Back/close affordances
+ * are owned by the surface host (`SurfaceScreen`) — a screen never wires them.
+ *
+ * Alongside the classic slots (`left`/`right`) a screen can declare the rich
+ * design-system fields Bloom's nav header supports: the single trailing
+ * `primaryAction` CTA (Upload / Save), a trailing icon `actions` row, a header
+ * `search` / `segments` in the large-title zone, an `onImage` `tone` over media,
+ * and a wizard `progress` bar.
+ *
+ * Only the NODE fields (`left`/`right`/`titleContent`, and an action's `icon`)
+ * must be referentially stable — a node can only be compared by identity, so an
+ * inline one thrashes the header. The rich OBJECT fields are compared by value
+ * (see {@link surfaceHeaderContentEqual}), so an inline `primaryAction` /
+ * `actions` / `search` / `segments` / `progress` is safe to pass.
+ */
+export type SurfaceHeaderContent = Pick<
+  DialogHeaderConfig,
+  | 'title'
+  | 'titleContent'
+  | 'subtitle'
+  | 'largeTitle'
+  | 'left'
+  | 'right'
+  | 'onBack'
+  | 'primaryAction'
+  | 'actions'
+  | 'search'
+  | 'segments'
+  | 'tone'
+  | 'progress'
+>;
+
+interface SurfaceHeaderContextValue {
+  setContent: (content: SurfaceHeaderContent | null) => void;
+}
+
+/**
+ * Provided by {@link ../components/SurfaceScreen}. Bridges a screen's runtime
+ * header contribution up to the host, which merges it with the back/close
+ * wiring and drives the Dialog's own nav header. `null` outside a surface (or in
+ * a headerless surface), so {@link useSurfaceHeader} is a safe no-op there.
+ */
+export const SurfaceHeaderContext = createContext<SurfaceHeaderContextValue | null>(null);
+
+type HeaderPrimaryAction = NonNullable<SurfaceHeaderContent['primaryAction']>;
+type HeaderAction = NonNullable<SurfaceHeaderContent['actions']>[number];
+type HeaderSearch = NonNullable<SurfaceHeaderContent['search']>;
+type HeaderSegments = NonNullable<SurfaceHeaderContent['segments']>;
+type HeaderProgress = NonNullable<SurfaceHeaderContent['progress']>;
+
+function primaryActionEqual(
+  a: HeaderPrimaryAction | undefined,
+  b: HeaderPrimaryAction | undefined,
+): boolean {
+  if (a === b) return true;
+  if (!a || !b) return false;
+  // `onPress` is a fresh closure each render — its identity never changes what
+  // the button renders, so compare only the render-affecting scalars.
+  return a.label === b.label && !!a.disabled === !!b.disabled && !!a.loading === !!b.loading;
+}
+
+function actionsEqual(a: HeaderAction[] | undefined, b: HeaderAction[] | undefined): boolean {
+  if (a === b) return true;
+  if (!a || !b || a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i += 1) {
+    const x = a[i];
+    const y = b[i];
+    if (!x || !y) return false;
+    // `icon` is a node (identity); `onPress` is ignored, like `primaryAction`'s.
+    if (
+      x.accessibilityLabel !== y.accessibilityLabel ||
+      !!x.disabled !== !!y.disabled ||
+      x.icon !== y.icon
+    ) {
+      return false;
+    }
+  }
+  return true;
+}
+
+function searchEqual(a: HeaderSearch | undefined, b: HeaderSearch | undefined): boolean {
+  if (a === b) return true;
+  if (!a || !b) return false;
+  return a.value === b.value && a.placeholder === b.placeholder;
+}
+
+function segmentsEqual(a: HeaderSegments | undefined, b: HeaderSegments | undefined): boolean {
+  if (a === b) return true;
+  if (!a || !b || a.value !== b.value || a.items.length !== b.items.length) return false;
+  for (let i = 0; i < a.items.length; i += 1) {
+    const x = a.items[i];
+    const y = b.items[i];
+    if (!x || !y || x.key !== y.key || x.label !== y.label) return false;
+  }
+  return true;
+}
+
+function progressEqual(a: HeaderProgress | undefined, b: HeaderProgress | undefined): boolean {
+  if (a === b) return true;
+  if (!a || !b) return false;
+  return a.step === b.step && a.total === b.total;
+}
+
+/**
+ * Value-equality for a surface's header contribution.
+ *
+ * This MIRRORS Bloom's own `configsEqual` (`@oxy.so/bloom/dialog`), which guards
+ * the header store one layer down — deliberately field for field. The two must
+ * not diverge: this comparator is the gate that decides whether the host's
+ * `setContent` fires, so a comparator STRICTER than Bloom's re-introduces the
+ * update loop Bloom's own guard was written to prevent.
+ *
+ * Scalars (`title`/`subtitle`/`largeTitle`/`tone`) compare by value. The rich
+ * object fields (`primaryAction`/`actions`/`search`/`segments`/`progress`)
+ * compare by their render-affecting scalars, so a screen may build them inline:
+ * a fresh object with unchanged contents is NOT a change. Only the node fields
+ * (`titleContent`/`left`/`right`, and an action's `icon`) compare by identity —
+ * there is nothing else to compare a `ReactNode` by — so those, and only those,
+ * carry the memoize-me contract.
+ *
+ * Function-typed affordances compare by PRESENCE, never identity: `onBack`
+ * legitimately gets a fresh closure each render and its identity never changes
+ * what the header renders, so it must not count as a change (that is exactly
+ * what would drive the update loop).
+ */
+function surfaceHeaderContentEqual(
+  a: SurfaceHeaderContent | null,
+  b: SurfaceHeaderContent | null,
+): boolean {
+  if (a === b) return true;
+  if (!a || !b) return false;
+  return (
+    a.title === b.title &&
+    a.titleContent === b.titleContent &&
+    a.subtitle === b.subtitle &&
+    a.largeTitle === b.largeTitle &&
+    a.left === b.left &&
+    a.right === b.right &&
+    !!a.onBack === !!b.onBack &&
+    a.tone === b.tone &&
+    primaryActionEqual(a.primaryAction, b.primaryAction) &&
+    actionsEqual(a.actions, b.actions) &&
+    searchEqual(a.search, b.search) &&
+    segmentsEqual(a.segments, b.segments) &&
+    progressEqual(a.progress, b.progress)
+  );
+}
+
+/**
+ * Declare the Dialog nav header's content from within a surface screen — its
+ * title/subtitle and any action slot. Merges over nothing (the host owns
+ * back/close), replaces on change, and clears on unmount. Call it unconditionally;
+ * it is a no-op outside a header-mode surface.
+ *
+ * Screens pass an INLINE `content` object (a fresh reference every render), so the
+ * push is guarded by {@link surfaceHeaderContentEqual}: the host's `setContent` is
+ * called only when the VALUE actually changes. Without that guard the setState
+ * would fire every render → the screen re-renders → the effect runs again → an
+ * infinite update loop (React error #185) in any consumer that does not memoize
+ * the object for us (i.e. anything not compiled by the React Compiler).
+ */
+export function useSurfaceHeader(content: SurfaceHeaderContent | null | undefined): void {
+  const ctx = useContext(SurfaceHeaderContext);
+  const set = ctx?.setContent;
+  const setRef = useRef(set);
+  setRef.current = set;
+  // The last value pushed to the host; `undefined` until the first push.
+  const lastRef = useRef<SurfaceHeaderContent | null | undefined>(undefined);
+
+  // Runs after EVERY commit (no deps array) so the bar/title fill in the same
+  // layout phase — but only pushes on a real value change, never on reference churn.
+  useLayoutEffect(() => {
+    const s = setRef.current;
+    if (!s) return;
+    const next = content ?? null;
+    if (lastRef.current !== undefined && surfaceHeaderContentEqual(lastRef.current, next)) return;
+    lastRef.current = next;
+    s(next);
+  });
+
+  // Clear this surface's contribution when the screen unmounts.
+  useLayoutEffect(
+    () => () => {
+      lastRef.current = undefined;
+      setRef.current?.(null);
+    },
+    [],
+  );
+}

package/src/ui/icons/Ionicons.ts

@@ -0,0 +1,11 @@
+import createIconSet from '@expo/vector-icons/createIconSet';
+import font from '../../assets/fonts/icons/OxyServicesIonicons.ttf';
+import { ioniconsGlyphMap } from './subsetGlyphMaps';
+
+const Ionicons = createIconSet(
+  ioniconsGlyphMap,
+  'OxyServicesIonicons',
+  font,
+);
+
+export default Ionicons;

package/src/ui/icons/MaterialCommunityIcons.ts

@@ -0,0 +1,11 @@
+import createIconSet from '@expo/vector-icons/createIconSet';
+import font from '../../assets/fonts/icons/OxyServicesMaterialCommunityIcons.ttf';
+import { materialCommunityIconsGlyphMap } from './subsetGlyphMaps';
+
+const MaterialCommunityIcons = createIconSet(
+  materialCommunityIconsGlyphMap,
+  'OxyServicesMaterialCommunityIcons',
+  font,
+);
+
+export default MaterialCommunityIcons;