Initial commit: CRDC Arrests API demo app

React + Vite static site demonstrating the CRDC School Arrest Rate API.
Features 6 interactive charts comparing observed arrest data against Bayesian
model estimates across U.S. school districts, with Civilytics visual identity.

- State selector and district search with 'interesting' suggestions (top arrests)
- Animated histogram loading grid showing posterior draw progress
- Charts: time series, rate by group, district vs national, model comparison quadrants, density proxy, exceedance probability
- Static JSON fixture for national rates (no API changes needed)
- Dockerfile + docker-compose.yml for self-hosted deployment
- GitHub Actions workflow and _config.yml for Git Pages

src/hooks/useApi.js

@@ -0,0 +1,123 @@
+/**
+ * Civilytics CRDC Arrest Rate API client.
+ * Wraps fetch() with retry, backoff, and typed error handling.
+ * Base URL: https://crdc-api.civilytics.org/api/v1
+ */
+
+const BASE_URL = import.meta.env.VITE_API_BASE || 'https://crdc-api.civilytics.org/api/v1'
+
+// Student group labels matching the API enum (race=AM|BL|HI|WH; sex=F|M)
+export const STUDENT_GROUPS = [
+  { race: 'WH', sex: 'F', label: 'White Female' },
+  { race: 'WH', sex: 'M', label: 'White Male' },
+  { race: 'BL', sex: 'F', label: 'Black Female' },
+  { race: 'BL', sex: 'M', label: 'Black Male' },
+  { race: 'HI', sex: 'F', label: 'Hispanic Female' },
+  { race: 'HI', sex: 'M', label: 'Hispanic Male' },
+  { race: 'AM', sex: 'F', label: 'American Indian\nFemale' },
+  { race: 'AM', sex: 'M', label: 'American Indian\nMale' },
+]
+
+// CRDC wave labels (year=15-16|17-18|21-22)
+export const CRDC_WAVES = [
+  { value: '15-16', label: '2015–16' },
+  { value: '17-18', label: '2017–18' },
+  { value: '21-22', label: '2021–22' },
+]
+
+// Model IDs returned by /models endpoint
+export const MODEL_IDS = [
+  'unified_m1_mod', 'unified_m2_mod', 'unified_m3_mod', 'unified_m4_mod', 'unified_m5_mod',
+  'stratified_m1_mod', 'stratified_m2_mod', 'stratified_m3_mod', 'stratified_m4_mod', 'stratified_m5_mod',
+]
+
+// The "four quadrants" for distribution charts (Chart 4–6)
+export const MODEL_QUADRANTS = [
+  { model: 'unified_m1_mod', label: 'One-year, no covariate', row: 0, col: 0 },
+  { model: 'unified_m2_mod', label: 'One-year + referral rate', row: 1, col: 0 },
+  { model: 'unified_m3_mod', label: 'Three-year, no covariate', row: 0, col: 1 },
+  { model: 'unified_m4_mod', label: 'Three-year + referral rate', row: 1, col: 1 },
+]
+
+// Default/recommended model (from validate.R)
+export const DEFAULT_MODEL = 'unified_m2_mod'
+
+/** Exponential backoff fetch wrapper */
+async function apiFetch(path, { retries = 3, delay = 500 } = {}) {
+  const url = `${BASE_URL}${path}`
+  let lastError
+
+  for (let attempt = 0; attempt <= retries; attempt++) {
+    try {
+      const res = await fetch(url, { signal: AbortSignal.timeout(30000) })
+      if (!res.ok) throw new Error(`HTTP ${res.status}: ${res.statusText}`)
+
+      /** @type {{status:string,data:any,error?:string,meta:object}} */
+      const envelope = await res.json()
+      if (envelope.status === 'success') return envelope.data
+      throw new Error(envelope.error || 'Unknown API error')
+    } catch (err) {
+      lastError = err
+      if (attempt < retries && !(err instanceof DOMException)) {
+        const wait = delay * Math.pow(2, attempt) + Math.random() * 100
+        await new Promise((r) => setTimeout(r, wait))
+      } else {
+        throw lastError
+      }
+    }
+  }
+
+  throw lastError
+}
+
+// ——— API endpoint wrappers (return the `data` array from the envelope) ———
+
+/** GET /models — static list of available Bayesian model specifications */
+export async function fetchModels() {
+  return apiFetch('/models')
+}
+
+/** GET /districts?q=<partial>&state=XX — name/geo lookup → LEAID */
+export async function searchDistricts(query, state) {
+  const params = new URLSearchParams({ q: query, state })
+  return apiFetch(`/districts?${params}`)
+}
+
+/** GET /estimates/{leaid}?model=X&year=Y — all demographics for one district/year/model */
+export async function fetchDistrictEstimates(leaid, options = {}) {
+  const params = new URLSearchParams()
+  if (options.model) params.set('model', options.model)
+  if (options.year) params.set('year', options.year)
+  if (options.race) params.set('race', options.race)
+  if (options.sex) params.set('sex', options.sex)
+
+  const qs = params.toString()
+  return apiFetch(`/estimates/${leaid}${qs ? `?${qs}` : ''}`)
+}
+
+/** GET /states/{state}?race=X&sex=Y&year=Z — state-level aggregate for one group */
+export async function fetchStateEstimates(state, options = {}) {
+  const params = new URLSearchParams()
+  if (options.race) params.set('race', options.race)
+  if (options.sex) params.set('sex', options.sex)
+  if (options.year) params.set('year', options.year)
+
+  const qs = params.toString()
+  return apiFetch(`/states/${state}${qs ? `?${qs}` : ''}`)
+}
+
+/** GET /estimates?state=XX&year=Y — all districts in a state for "interesting" suggestions */
+export async function fetchStateDistricts(state, year = '21-22', limit = 500) {
+  return apiFetch(`/estimates?state=${state}&year=${year}&limit=${limit}`)
+}
+
+/** GET /draws?... — returns HF parquet shard URL + DuckDB SQL (bulk only, not used in browser app) */
+export async function fetchDrawLocation(state, race, sex, year, model) {
+  const params = new URLSearchParams({ state })
+  if (race) params.set('race', race)
+  if (sex) params.set('sex', sex)
+  if (year) params.set('year', year)
+  if (model) params.set('model', model)
+
+  return apiFetch(`/draws?${params}`)
+}