Merge branch 'develop' into issues/15661/template-page

Author: 8sami

.example.env

@@ -47,6 +47,9 @@ REACT_SENTRY_ENVIRONMENT=
 # Flag to allow some fields in patient registration to be non-mandatory
 REACT_ENABLE_MINIMAL_PATIENT_REGISTRATION=true
 
+# Flag to bypass patient edit access permissions
+REACT_PATIENT_GLOBAL_EDIT_ACCESS_ENABLED=false
+
 # Minimum number of geo-organization levels required during patient registration
 # If not set, disables the requirement
 REACT_PATIENT_REG_MIN_GEO_ORG_LEVELS_REQUIRED=

CLAUDE.md

@@ -2,20 +2,122 @@
 
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
+## What is CARE?
+
+CARE is a Digital Public Good building an open source EMR + Hospital Management system. This is the React frontend (React 19 + TypeScript + Vite).
+
 ## Build/Lint/Test Commands
-- `npm run dev`: Start development server
-- `npm run build`: Build for production 
-- `npm run lint`: Run ESLint
-- `npm run lint-fix`: Run ESLint with auto-fix
-- `npm run format`: Format code with Prettier
-- `npm run playwright:test`: Run Playwright tests in headless mode
-- `npm run playwright:test:ui`: Run Playwright tests in interactive UI mode
+
+- `npm run dev` — Start dev server at http://localhost:4000
+- `npm run build` — Production build (takes 2+ minutes, set timeout to 180s+)
+- `npm run lint` — Run ESLint (takes 85s+, set timeout to 120s+)
+- `npm run lint-fix` — ESLint with auto-fix
+- `npm run format` — Prettier formatting
+- `npm run playwright:test` — Run all Playwright E2E tests headlessly
+- `npm run playwright:test -- tests/auth/login.spec.ts` — Run a single test file
+- `npm run playwright:test -- -g "test name"` — Run tests matching a pattern
+- `npm run playwright:test:ui` — Interactive Playwright UI mode
+
+Playwright requires a local backend running (`REACT_CARE_API_URL=http://127.0.0.1:9000` in `.env.local`) and `npm run playwright:install` for browsers.
 
 ## Code Style Guidelines
-- **TypeScript**: Strict mode, ES2022 target, path aliases (`@/*` for src)
+
+- **TypeScript**: Strict mode, ES2022 target, path aliases (`@/*` → `src/*`, `@careConfig` → `care.config.ts`)
 - **Formatting**: Double quotes, 2-space indent, semicolons required
-- **Imports**: Order by 3rd-party → library → CAREUI → UI → components → hooks → utils → relative
-- **Types**: Use `interface` for objects, avoid explicit `any`, proper nullability
-- **Naming**: PascalCase for components/classes, camelCase for variables/functions
-- **Components**: Organized by feature, maintain separation of concerns
-- **Error Handling**: Use dedicated error handlers, TypeScript strict null checks
+- **Imports**: Order by 3rd-party → library → CAREUI → UI → components → hooks → utils → relative. Prettier plugin auto-sorts on format.
+- **Types**: Use `interface` for objects, avoid `any`, prefer maps over enums
+- **Naming**: PascalCase for component files (`AuthWizard.tsx`), camelCase for hooks/utils (`useAuth.ts`), kebab-case for directories
+- **Components**: Functional components only, named exports preferred, one component per file
+- **i18n**: All user-facing strings must use i18next. English translations go in `public/locale/en.json`. Non-English managed via Crowdin — do not edit directly.
+
+## Architecture
+
+### Routing (Raviger)
+
+Routes defined in `src/Routers/routes/` (e.g., `FacilityRoutes.tsx`, `PatientRoutes.tsx`). Combined in `src/Routers/AppRouter.tsx`. Three routers: `PublicRouter`, `PatientRouter`, `AppRouter` — selected by auth state. Plugin routes injected via `usePluginRoutes()`.
+
+```typescript
+const FacilityRoutes: AppRoutes = {
+  "/facility/:facilityId/overview": ({ facilityId }) => <FacilityOverview facilityId={facilityId} />,
+};
+```
+
+Use `navigate()` from raviger for programmatic navigation.
+
+### API Layer (TanStack Query + custom wrappers)
+
+API routes defined in `src/types/{domain}/{domain}Api.ts` using typed route objects:
+
+```typescript
+export default {
+  list: {
+    path: "/api/v1/users/",
+    method: HttpMethod.GET,
+    TRes: Type<PaginatedResponse<UserReadMinimal>>(),
+  },
+} as const;
+```
+
+Queries use `query()` wrapper from `src/Utils/request/query.ts`:
+
+```typescript
+const { data } = useQuery({
+  queryKey: ["users"],
+  queryFn: query(userApi.list),
+});
+// With path/query params:
+queryFn: query(userApi.get, { pathParams: { username }, queryParams: { search } })
+```
+
+Mutations use `mutate()` wrapper from `src/Utils/request/mutate.ts`:
+
+```typescript
+const { mutate } = useMutation({
+  mutationFn: mutate(userApi.create),
+});
+```
+
+Also available: `query.debounced()` and `query.paginated()` for specialized use cases.
+
+Errors handled globally — session expiry redirects to `/session-expired`, 400/406 show toast notifications. Use `silent: true` to suppress.
+
+### State Management
+
+- **TanStack Query** — Server state (API data caching, refetching)
+- **Jotai atoms** (`src/atoms/`) — Lightweight client state (user, nav, filters)
+- **React Context** (`src/context/`) — Permissions (`PermissionContext`), keyboard shortcuts
+
+### UI Components
+
+Built on **shadcn/uishadcn/ui** + **Radix UI primitives** + **Tailwind CSS v4** (shadcn/ui pattern):
+- `src/components/ui/` — Base UI primitives (Button, Dialog, Form, Select, etc.). Do not modify these directly.
+- `src/CAREUI/` — Custom healthcare icon library, use `lucide-react` unless you are explicitly asked to use CAREUI icons. 
+- Forms use `react-hook-form` + `zod` validation with the custom `<Form>` component
+
+### Plugin System (Module Federation)
+
+Micro-frontend architecture via `@originjs/vite-plugin-federation`. Plugins configured via `REACT_ENABLED_APPS` env var. Plugin manifests define routes, components, tabs, and devices they provide. Key files: `src/PluginEngine.tsx`, `src/pluginTypes.ts`.
+
+### Auth Flow
+
+JWT tokens in localStorage. `AuthUserProvider` handles login/logout, token refresh (every 5 minutes), 2FA, and cross-tab session sync. Patient login uses separate OTP-based flow via `PatientRouter`.
+
+### Key Directories
+
+- `src/components/` — Feature-organized components (Auth, Facility, Patient, Encounter, Medicine, etc.)
+- `src/pages/` — Page components by feature (Admin, Appointments, Facility, Organization, Patient)
+- `src/types/` — Domain type definitions with corresponding `*Api.ts` route files
+- `src/Utils/request/` — API request infrastructure (query, mutate, error handling)
+- `src/hooks/` — Custom React hooks (auth, file management, plugins, etc.)
+- `src/Providers/` — Auth, history, patient user providers
+- `src/Routers/` — App routing and route definitions
+
+### Configuration
+
+`care.config.ts` centralizes runtime config (API URLs, feature flags, locale settings, plugin config). Environment variables prefixed with `REACT_`.
+
+## Git Workflow
+
+- Branch naming: `issues/{issue#}/{short-name}`
+- Default branch: `develop` (staging auto-deploys)
+- Pre-commit hooks via husky run Prettier and ESLint on staged files

care.config.ts

@@ -249,6 +249,11 @@ const careConfig = {
       env.REACT_ENABLE_MINIMAL_PATIENT_REGISTRATION,
       false,
     ),
+
+    globalPatientEditAccessEnabled: booleanFromString(
+      env.REACT_PATIENT_GLOBAL_EDIT_ACCESS_ENABLED,
+      false,
+    ),
   },
 
   i18nUrl: env.REACT_CUSTOM_REMOTE_I18N_URL,

package-lock.json

@@ -116,7 +116,7 @@
     "normalize-wheel": "^1.0.1",
     "pigeon-maps": "^0.22.1",
     "qrcode.react": "^4.1.0",
-    "raviger": "^5.0.0-2",
+    "raviger": "^5.3.0",
     "react": "19.1.1",
     "react-day-picker": "^9.6.3",
     "react-dom": "19.1.1",

package.json

@@ -2455,6 +2455,7 @@
   "failed_to_cancel_invoice": "Failed to cancel invoice",
   "failed_to_cancel_payment": "Failed to cancel payment",
   "failed_to_capture_image": "Failed to capture image",
+  "failed_to_check_appointments": "Failed to check appointments",
   "failed_to_create_appointment": "Failed to create an appointment",
   "failed_to_create_category": "Failed to create category",
   "failed_to_create_invoice": "Failed to create invoice",
@@ -3480,6 +3481,7 @@
   "no_allergies_recorded_description": "No Allergies have been recorded",
   "no_alternative_names_added": "No alternative names added",
   "no_appointments": "No appointments found",
+  "no_appointments_found_for_today": "No matching appointment found for today. Redirecting to Patient Home...",
   "no_attachments_found": "This communication has no attachments.",
   "no_availabilities_yet": "No availabilities yet",
   "no_available_beds_found": "No available beds found",
@@ -5940,6 +5942,10 @@
   "token_queue": "Token Queue",
   "token_queues": "Token Queues",
   "token_revoked_successfully": "Token revoked successfully",
+  "token_status__called": "Call Next",
+  "token_status__recall": "Recall",
+  "token_status__serving": "Serving",
+  "token_status__waiting": "Waiting",
   "token_warning_message": "This token will only be shown once. Make sure to copy and store it securely before closing this dialog.",
   "tokens": "Tokens",
   "tokens_left": "{{ count }} left",

public/locale/en.json

@@ -117,6 +117,7 @@ const envSchema = z
     REACT_JWT_TOKEN_REFRESH_INTERVAL: numberAsString.optional(),
     REACT_DISABLE_PATIENT_LOGIN: booleanAsStringSchema.optional(),
     REACT_ENABLE_MINIMAL_PATIENT_REGISTRATION: booleanAsStringSchema.optional(),
+    REACT_PATIENT_GLOBAL_EDIT_ACCESS_ENABLED: booleanAsStringSchema.optional(),
     REACT_APPOINTMENTS_DEFAULT_DATE_FILTER: numberAsString.optional(),
     REACT_PAYMENT_LOCATION_REQUIRED: booleanAsStringSchema.optional(),
     REACT_ENCOUNTER_DEFAULT_DATE_FILTER: numberAsString.optional(),

scripts/validate-env.ts

@@ -172,7 +172,7 @@ function FacilityPrintLayout({
   const pageStyle = buildPageStyle(printTemplate);
 
   return (
-    <>
+    <div className="flex flex-col min-h-[calc(100vh-80px)] print:min-h-[100vh]">
       {pageStyle && <style>{pageStyle}</style>}
       {headerImage?.url ? (
         <div className="flex justify-between items-start mb-4 pb-2">
@@ -209,9 +209,9 @@ function FacilityPrintLayout({
           />
         </div>
       )}
-      {children}
+      <div className="flex-1">{children}</div>
       {footerImage?.url && (
-        <div className="mt-4 pt-2">
+        <div className="mt-auto pt-2">
           <img
             src={footerImage.url}
             alt="Footer"
@@ -224,6 +224,6 @@ function FacilityPrintLayout({
           />
         </div>
       )}
-    </>
+    </div>
   );
 }

src/CAREUI/misc/PrintPreview.tsx

@@ -7,18 +7,23 @@ export const ResetHistoryContext = createContext(() => {});
 
 export default function HistoryAPIProvider(props: { children: ReactNode }) {
   const [history, setHistory] = useState<string[]>([]);
-
   useLocationChange(
-    (newLocation) => {
-      const newPath = newLocation.fullPath + newLocation.search;
-      setHistory((history) => {
-        if (history.length && newPath === history[0])
-          // Ignore push if navigate to same path (for some weird unknown reasons?)
-          return history;
+    (location) => {
+      const newPath = location.fullPath + location.search;
+      const action = location.initiatedBy;
 
-        if (history.length > 1 && newPath === history[1])
-          // Pop current path if navigate back to previous path
+      setHistory((history) => {
+        // Pop current path if navigate back to previous path
+        if (
+          (history.length > 1 && newPath === history[1]) ||
+          action === "pop"
+        ) {
           return history.slice(1);
+        }
+
+        if (action === "replace") {
+          return [newPath, ...history.slice(1)];
+        }
 
         // Otherwise just push the current path
         return [newPath, ...history];

src/Providers/HistoryAPIProvider.tsx

@@ -41,17 +41,20 @@ interface CompactConditionEditorProps {
   availableMetrics: Metrics[];
   onChange: (conditions: ConditionForm[]) => void;
   className?: string;
+  facilityId?: string;
 }
 
 // Keep only TagSelector as a separate component since it needs to use a hook
 function TagSelector({
   value,
   onChange,
   resource,
+  facilityId,
 }: {
   value: TagOperationValue;
   onChange: (value: TagOperationValue) => void;
   resource: TagResource;
+  facilityId?: string;
 }) {
   const { tagIds } = extractTagInformation(value);
 
@@ -78,6 +81,7 @@ function TagSelector({
         resource={resource}
         onChange={handleChange}
         className="h-9 w-full"
+        facilityId={facilityId}
       />
     </div>
   );
@@ -87,10 +91,12 @@ function RenderInput({
   metric,
   operation,
   form,
+  facilityId,
 }: {
   metric: string;
   operation: ConditionOperation;
   form: UseFormReturn<ConditionForm, unknown, ConditionForm>;
+  facilityId?: string;
 }) {
   const { t } = useTranslation();
   // For patient_gender with equality operation
@@ -310,6 +316,7 @@ function RenderInput({
                   field.onChange(value);
                 }}
                 resource={tagResource}
+                facilityId={facilityId}
               />
             </FormControl>
           </FormItem>
@@ -392,6 +399,7 @@ export function CompactConditionEditor({
   availableMetrics,
   onChange,
   className = "",
+  facilityId,
 }: CompactConditionEditorProps) {
   const { t } = useTranslation();
   const [isAdding, setIsAdding] = useState(false);
@@ -564,7 +572,12 @@ export function CompactConditionEditor({
                 )}
               />
 
-              <RenderInput metric={metric} operation={operation} form={form} />
+              <RenderInput
+                metric={metric}
+                operation={operation}
+                form={form}
+                facilityId={facilityId}
+              />
             </div>
             {/* Error Summary */}
             {Object.keys(form.formState.errors).length > 0 && (