first-aid-reference

# first-aid-reference

A Progressive Web App (PWA) that provides offline-capable first aid guides. All content is static JSON bundled at build time. No account required, no data collected.

## When to use

- Looking up step-by-step first aid instructions for a specific condition
- Searching for guides by symptom, keyword, or category
- Checking whether a condition is classed as EMERGENCY, URGENT, or ROUTINE
- Managing bookmarked guides
- Adding or reviewing emergency contacts
- Installing the app to a mobile device's home screen
- Understanding what is and is not cached for offline use

## Base URL

This is a client-side SPA with no API server. All functionality runs in the browser.

```
http://localhost:5173   (dev server)
http://localhost:4173   (preview build)
```

After a production build, serve from any static file host:
```bash
pnpm build
pnpm preview
```

## Navigation

| Path | Page |
|---|---|
| / | Home - category grid and recent guides |
| /category/:id | All guides in a category |
| /article/:id | Full guide with steps |
| /search?q=query | Search results |
| /bookmarks | Saved guides |
| /settings | Display preferences |

## Content Categories

| id | name | emergency level |
|---|---|---|
| cardiac | Cardiac Arrest | all emergency |
| breathing | Breathing Problems | all emergency |
| bleeding | Bleeding | mixed |
| burns | Burns | mixed |
| choking | Choking | all emergency |
| fractures | Fractures | routine |
| poisoning | Poisoning | emergency |
| shock | Shock | all emergency |
| allergic | Allergic Reaction | emergency |
| bites | Bites and Stings | mixed |

## Offline Capability

The service worker (Workbox via vite-plugin-pwa) precaches all build output on first load. This includes:
- All React component bundles
- `articles.json` and `categories.json`
- PWA icons and manifest

After the first visit, the app works with no internet connection.

## Deploying the PWA

### Build

```bash
pnpm install
pnpm build
# Output: dist/
```

The `dist/` folder contains a fully static site including:
- `index.html`
- `sw.js` (service worker)
- `manifest.webmanifest`
- All assets

### Deploy to Netlify

```bash
# Install Netlify CLI
pnpm add -g netlify-cli

# Deploy
netlify deploy --prod --dir=dist
```

Add a `_headers` file in `public/` for CSP headers:
```
/*
  Content-Security-Policy: default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline' https://fonts.googleapis.com; font-src 'self' https://fonts.gstatic.com; img-src 'self' data:
  X-Frame-Options: DENY
  X-Content-Type-Options: nosniff
```

### Deploy to Vercel

```bash
pnpm add -g vercel
vercel --prod
```

### Deploy with Docker (static nginx)

```dockerfile
FROM nginx:alpine
COPY dist/ /usr/share/nginx/html/
COPY nginx.conf /etc/nginx/conf.d/default.conf
EXPOSE 80
```

`nginx.conf` must include `try_files $uri $uri/ /index.html;` for SPA routing.

### Deploy to a static file server

```bash
# Python simple server (dev only)
cd dist && python3 -m http.server 8080

# Node serve
npx serve dist -p 8080
```

## Customizing content: adding guides

Guides are stored in `src/data/articles.json`. Each guide follows this structure:

```json
{
  "id": "my-guide-id",
  "category": "burns",
  "title": "My Guide Title",
  "emergency": false,
  "steps": [
    { "order": 1, "text": "Step one instruction.", "note": "Optional clarifying note." }
  ],
  "doNot": ["Do not do this.", "Do not do that."],
  "symptoms": ["Symptom one", "Symptom two"],
  "whenToCall": ["If condition X occurs"],
  "tags": ["keyword1", "keyword2"],
  "relatedIds": ["other-guide-id"]
}
```

After editing `articles.json`, run `pnpm build` to rebuild the app.

To validate content structure before building:
```bash
pnpm tsx scripts/validate-content.ts
```

## Configuring emergency contacts

Emergency contacts are stored in `localStorage` under the key `first-aid-contacts`. They can be managed from the Contacts page (`/contacts`) in the app. Contacts are never transmitted to any server.

```javascript
// Read contacts from localStorage (for debugging)
JSON.parse(localStorage.getItem('first-aid-contacts') ?? '[]')
```

## Installing on iOS

iOS Safari does not support the `beforeinstallprompt` event. Manual install instructions:
1. Open the app URL in Safari
2. Tap the Share button (box with arrow)
3. Scroll down and tap "Add to Home Screen"
4. Tap "Add"

The app will appear as a standalone icon and open without browser chrome.

## Installing on Android

Chrome and Edge on Android support automatic install prompts. The `InstallPrompt` component captures the `beforeinstallprompt` event and shows an install banner.

Users can also install manually:
1. Open in Chrome
2. Tap the three-dot menu
3. Tap "Add to Home screen"

## Accessibility features

- All interactive elements are keyboard-accessible with visible focus ring (2px solid `--border-focus`)
- Step numbers have `aria-label="Step N of M"`
- Emergency banner uses `role="alert"` and `aria-live="assertive"`
- SeverityBadge has `role="status"` with full text
- High contrast mode increases border widths and font weights (toggled in Settings)
- Minimum tap target size: 44x44px on mobile
- Color is never the sole indicator of status - text labels always accompany color

## Environment variables (build time only)

| Variable | Default | Description |
|---|---|---|
| VITE_APP_NAME | first-aid-reference | App display name in manifest |
| VITE_APP_VERSION | 1.0.0 | Shown in Settings page |

## Medical disclaimer

Every article page displays:

> "This information is for general educational purposes only. Always call emergency services (000, 112, or your local emergency number) for life-threatening situations. This app does not replace professional medical advice."

This disclaimer is rendered by `DisclaimerBanner.tsx` and must never be removed or hidden.