feat: Categories Editor — browse, search, and import .comapeocat category sets (closes #143)

screenshots/screenshot/mobile-settings.png.argos.json → screenshots/screenshot/mobile-observation-detail.png.argos.json

@@ -1,21 +1,21 @@
 {
-  "url": "http://localhost:5173/settings",
+  "url": "http://localhost:5173/data/observations/nonexistent-id",
   "colorScheme": "light",
   "mediaType": "screen",
   "test": {
-    "id": "99fb1864c5a05941a39e-216675ff9df5f526e28e",
-    "title": "mobile-settings light",
+    "id": "99fb1864c5a05941a39e-a72832ff12247d95f3c8",
+    "title": "mobile-observation-detail light",
     "titlePath": [
       "mobile-audit.screenshots.ts",
       "Mobile audit screenshots",
-      "mobile-settings light"
+      "mobile-observation-detail light"
     ],
     "retry": 0,
     "retries": 0,
     "repeat": 0,
     "location": {
       "file": "tests/e2e/mobile-audit.screenshots.ts",
-      "line": 207,
+      "line": 146,
       "column": 3
     },
     "annotations": []

src/app/router.tsx

@@ -8,6 +8,7 @@ import {
 import { AuthenticatedLayout } from '@/components/layout/authenticated-layout';
 import { AlertDetailScreen } from '@/screens/AlertDetailScreen';
 import { AlertsScreen } from '@/screens/AlertsScreen';
+import { CategoriesEditorScreen } from '@/screens/CategoriesEditor';
 import { CreateAlertScreen } from '@/screens/CreateAlertScreen';
 import { DataScreen } from '@/screens/DataScreen';
 import { HomeScreen } from '@/screens/Home/HomeScreen';
@@ -93,6 +94,18 @@ const settingsRoute = createRoute({
   component: SettingsScreen,
 });
 
+const categoriesRoute = createRoute({
+  getParentRoute: () => _authenticatedRoute,
+  path: '/categories',
+  component: CategoriesEditorScreen,
+});
+
+const categoryDetailRoute = createRoute({
+  getParentRoute: () => _authenticatedRoute,
+  path: '/categories/$categoryId',
+  component: CategoriesEditorScreen,
+});
+
 const inviteRoute = createRoute({
   getParentRoute: () => rootRoute,
   path: '/invite',
@@ -112,6 +125,8 @@ const routeTree = rootRoute.addChildren([
     createAlertRoute,
     alertDetailRoute,
     settingsRoute,
+    categoriesRoute,
+    categoryDetailRoute,
   ]),
 ]);
 
@@ -136,6 +151,8 @@ export {
   createAlertRoute,
   alertDetailRoute,
   settingsRoute,
+  categoriesRoute,
+  categoryDetailRoute,
 };
 
 // Export route tree for testing

src/components/layout/authenticated-layout.tsx

@@ -26,6 +26,7 @@ const messages = defineMessages({
   data: { id: 'data.title', defaultMessage: 'Data' },
   alerts: { id: 'alerts.title', defaultMessage: 'Alerts' },
   map: { id: 'map.title', defaultMessage: 'Map' },
+  categories: { id: 'categories.title', defaultMessage: 'Categories' },
   settings: { id: 'settings.title', defaultMessage: 'Settings' },
   appTitle: { id: 'app.title', defaultMessage: 'CoMapeo Cloud' },
 });
@@ -112,6 +113,21 @@ function SettingsIcon(): ReactNode {
   );
 }
 
+function CategoriesIcon(): ReactNode {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      width={20}
+      height={20}
+      viewBox="0 0 20 20"
+      fill="currentColor"
+      aria-hidden="true"
+    >
+      <path d="M2 4a2 2 0 012-2h4a2 2 0 012 2v4a2 2 0 01-2 2H4a2 2 0 01-2-2V4zm10 0a2 2 0 012-2h4a2 2 0 012 2v4a2 2 0 01-2 2h-4a2 2 0 01-2-2V4zM2 12a2 2 0 012-2h4a2 2 0 012 2v4a2 2 0 01-2 2H4a2 2 0 01-2-2v-4zm10 0a2 2 0 012-2h4a2 2 0 012 2v4a2 2 0 01-2 2h-4a2 2 0 01-2-2v-4z" />
+    </svg>
+  );
+}
+
 /** Normalize a URL for comparison by stripping trailing slashes. */
 function normalizeUrl(url: string): string {
   return url.trim().replace(/\/+$/, '');
@@ -250,6 +266,11 @@ function AuthenticatedLayoutInner() {
       label: intl.formatMessage(messages.map),
       icon: <MapIcon />,
     },
+    {
+      path: '/categories',
+      label: intl.formatMessage(messages.categories),
+      icon: <CategoriesIcon />,
+    },
     {
       path: '/settings',
       label: intl.formatMessage(messages.settings),

src/hooks/useApiPresets.ts

@@ -0,0 +1,16 @@
+import { useQuery } from '@tanstack/react-query';
+
+import { apiClient } from '@/lib/api-client';
+
+/** Fetches presets directly from the archive server API (wire format).
+ * Uses the project's remoteId (server projectPublicId, base32) — NOT the
+ * local DB id (hex). Required because the server route parameter is validated
+ * against a base32 regex pattern. */
+export function useApiPresets(projectRemoteId: string | null) {
+  return useQuery({
+    queryKey: ['api-presets', projectRemoteId],
+    queryFn: () => apiClient.getPresets(projectRemoteId!),
+    enabled: projectRemoteId !== null,
+    select: (data) => data.data,
+  });
+}

src/hooks/useCategories.ts

@@ -0,0 +1,127 @@
+interface PresetInput {
+  docId: string;
+  name: string;
+  tags: Record<string, unknown>;
+  fieldRefs: Array<{ docId: string }>;
+  iconRef?: { docId: string };
+}
+
+export interface Category {
+  docId: string;
+  label: string;
+  fieldRefs: Array<{ docId: string; label?: string }>;
+  color?: string;
+  iconRef?: { docId: string };
+}
+
+export interface CategoryGroup {
+  type: string;
+  categories: Category[];
+}
+
+const ACCENT_RE = /[\u0300-\u036f]/g;
+
+function stripDiacritics(s: string): string {
+  return s.normalize('NFD').replace(ACCENT_RE, '');
+}
+
+function normalizeSearch(s: string): string {
+  return stripDiacritics(s).toLowerCase();
+}
+
+function resolveLocaleName(
+  tags: Record<string, unknown>,
+  locale: string,
+  sourceName: string,
+): string {
+  const localeKey = `name:${locale}`;
+  if (typeof tags[localeKey] === 'string') return tags[localeKey] as string;
+
+  if (locale !== 'en') {
+    const enKey = 'name:en';
+    if (typeof tags[enKey] === 'string') return tags[enKey] as string;
+  }
+
+  return sourceName;
+}
+
+function matchesSearch(
+  preset: PresetInput,
+  searchNormalized: string,
+  locale: string,
+  fieldLabels?: Map<string, string>,
+): boolean {
+  const label = resolveLocaleName(preset.tags, locale, preset.name);
+  if (normalizeSearch(label).includes(searchNormalized)) return true;
+
+  for (const ref of preset.fieldRefs) {
+    const resolvedLabel = fieldLabels?.get(ref.docId);
+    if (
+      resolvedLabel &&
+      normalizeSearch(resolvedLabel).includes(searchNormalized)
+    ) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+export function normalizeCategories(
+  data: PresetInput[],
+  locale: string,
+  searchQuery: string,
+  fieldLabels?: Map<string, string>,
+): CategoryGroup[] {
+  if (data.length === 0) return [];
+
+  const searchNormalized = normalizeSearch(searchQuery);
+
+  const groups = new Map<string, Category[]>();
+
+  for (const preset of data) {
+    if (
+      searchNormalized &&
+      !matchesSearch(preset, searchNormalized, locale, fieldLabels)
+    ) {
+      continue;
+    }
+
+    const rawType = preset.tags.type;
+    const type =
+      typeof rawType === 'string' && rawType.trim() !== '' ? rawType : ''; // sentinel — translated at render (CategoryGrid)
+
+    const label = resolveLocaleName(preset.tags, locale, preset.name);
+
+    if (!groups.has(type)) {
+      groups.set(type, []);
+    }
+    groups.get(type)!.push({
+      docId: preset.docId,
+      label,
+      fieldRefs: preset.fieldRefs.map((ref) => ({
+        docId: ref.docId,
+        label: fieldLabels?.get(ref.docId),
+      })),
+      color:
+        typeof preset.tags.color === 'string' ? preset.tags.color : undefined,
+      iconRef:
+        typeof preset.iconRef === 'object' &&
+        preset.iconRef !== null &&
+        'docId' in preset.iconRef
+          ? { docId: (preset.iconRef as { docId: string }).docId }
+          : undefined,
+    });
+  }
+
+  const result: CategoryGroup[] = [];
+  const sortedTypes = [...groups.keys()].sort();
+
+  for (const type of sortedTypes) {
+    const categories = groups.get(type)!;
+    categories.sort((a, b) => a.label.localeCompare(b.label));
+    result.push({ type, categories });
+  }
+
+  return result;
+}

src/hooks/useCategorySets.ts

@@ -0,0 +1,63 @@
+import { useCallback, useEffect, useState } from 'react';
+
+import { type CategorySetRecord, categoriesDb } from '@/lib/categories-db';
+
+export interface CategorySetSummary {
+  setId: string;
+  name: string;
+  importedAt: string;
+  categoryCount: number;
+}
+
+function toSummary(record: CategorySetRecord): CategorySetSummary {
+  return {
+    setId: record.setId,
+    name: record.name,
+    importedAt: record.importedAt,
+    categoryCount: Object.keys(record.categories).length,
+  };
+}
+
+export function useCategorySets() {
+  const [sets, setSets] = useState<CategorySetSummary[]>([]);
+  const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    let cancelled = false;
+    categoriesDb.categorySets
+      .toArray()
+      .then((records) => {
+        if (!cancelled) {
+          setSets(records.map(toSummary));
+          setError(null);
+        }
+      })
+      .catch((err: unknown) => {
+        if (!cancelled) {
+          setError(err instanceof Error ? err.message : 'Failed to load sets');
+        }
+      })
+      .finally(() => {
+        if (!cancelled) setIsLoading(false);
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+
+  const refresh = useCallback(async () => {
+    setIsLoading(true);
+    setError(null);
+    try {
+      const records = await categoriesDb.categorySets.toArray();
+      setSets(records.map(toSummary));
+    } catch (err: unknown) {
+      setError(err instanceof Error ? err.message : 'Failed to refresh sets');
+    } finally {
+      setIsLoading(false);
+    }
+  }, []);
+
+  return { sets, isLoading, error, refresh };
+}