@retiregolden/planner-ui 0.1.0

package/src/longevity/LongevityWizard.tsx

@@ -0,0 +1,305 @@
+import { useMemo, useState } from 'react'
+import type {
+  Activity,
+  Alcohol,
+  BmiCategory,
+  Diabetes,
+  LongevityAnswers,
+  ParentalLongevity,
+  SelfRatedHealth,
+  Sex,
+  Smoking,
+} from '@retiregolden/engine/longevity/types'
+import { computeLongevity } from './model'
+import { saveLongevity, saveLongevityPartner } from './storage'
+
+const defaultAnswers = (): LongevityAnswers => ({
+  age: 55,
+  sex: 'average',
+  bmiCategory: 'normal',
+  smoking: 'never',
+  alcohol: 'moderate',
+  activity: 'moderate',
+  diabetes: 'no',
+  selfRatedHealth: 'good',
+  parentalLongevity: 'unknown',
+})
+
+type Step =
+  | 'age'
+  | 'sex'
+  | 'bmi'
+  | 'smoking'
+  | 'alcohol'
+  | 'activity'
+  | 'diabetes'
+  | 'health'
+  | 'parents'
+
+const STEPS: Step[] = [
+  'age',
+  'sex',
+  'bmi',
+  'smoking',
+  'alcohol',
+  'activity',
+  'diabetes',
+  'health',
+  'parents',
+]
+
+function mergeInitial(initial?: Partial<LongevityAnswers>): LongevityAnswers {
+  return { ...defaultAnswers(), ...initial }
+}
+
+export interface LongevityWizardProps {
+  initialAnswers?: Partial<LongevityAnswers>
+  onComplete: () => void
+  /** Which localStorage slot to write on completion (default primary). */
+  storageTarget?: 'primary' | 'partner'
+}
+
+export function LongevityWizard({
+  initialAnswers,
+  onComplete,
+  storageTarget = 'primary',
+}: LongevityWizardProps) {
+  const [answers, setAnswers] = useState<LongevityAnswers>(() => mergeInitial(initialAnswers))
+  const [stepIndex, setStepIndex] = useState(0)
+  const step = STEPS[stepIndex]!
+
+  const canNext = useMemo(() => {
+    if (step === 'age') {
+      return Number.isFinite(answers.age) && answers.age >= 18 && answers.age <= 110
+    }
+    return true
+  }, [step, answers.age])
+
+  function patch<K extends keyof LongevityAnswers>(key: K, value: LongevityAnswers[K]) {
+    setAnswers((a) => ({ ...a, [key]: value }))
+  }
+
+  function goNext() {
+    if (stepIndex < STEPS.length - 1) setStepIndex((i) => i + 1)
+    else {
+      const result = computeLongevity(answers)
+      const payload = {
+        version: 1 as const,
+        answers,
+        result,
+        updatedAt: new Date().toISOString(),
+      }
+      if (storageTarget === 'partner') {
+        saveLongevityPartner(payload)
+      } else {
+        saveLongevity(payload)
+      }
+      onComplete()
+    }
+  }
+
+  function goBack() {
+    if (stepIndex > 0) setStepIndex((i) => i - 1)
+  }
+
+  return (
+    <div className="wizard">
+      <p className="wizard-progress">
+        Step {stepIndex + 1} of {STEPS.length}
+      </p>
+
+      {step === 'age' && (
+        <fieldset className="wizard-fieldset">
+          <legend>Your current age</legend>
+          <label className="field">
+            <span>Age (whole years)</span>
+            <input
+              type="number"
+              min={18}
+              max={110}
+              value={answers.age}
+              onChange={(e) => patch('age', Number.parseInt(e.target.value, 10) || 0)}
+            />
+          </label>
+          <p className="field-hint">Use 18–110. We use this to read the SSA period life table row.</p>
+        </fieldset>
+      )}
+
+      {step === 'sex' && (
+        <fieldset className="wizard-fieldset">
+          <legend>Life table column</legend>
+          <p className="field-hint">
+            SSA publishes separate male and female period expectancies. Pick the row to use, or
+            average both.
+          </p>
+          <RadioRow
+            name="sex"
+            value={answers.sex}
+            onChange={(v) => patch('sex', v as Sex)}
+            options={[
+              { value: 'male', label: 'Male table' },
+              { value: 'female', label: 'Female table' },
+              { value: 'average', label: 'Average of male and female' },
+            ]}
+          />
+        </fieldset>
+      )}
+
+      {step === 'bmi' && (
+        <fieldset className="wizard-fieldset">
+          <legend>BMI category</legend>
+          <p className="field-hint">Pick the closest category; this is a coarse adjustment only.</p>
+          <RadioRow
+            name="bmi"
+            value={answers.bmiCategory}
+            onChange={(v) => patch('bmiCategory', v as BmiCategory)}
+            options={[
+              { value: 'underweight', label: 'Underweight' },
+              { value: 'normal', label: 'Normal' },
+              { value: 'overweight', label: 'Overweight' },
+              { value: 'obese_i', label: 'Obese (class I)' },
+              { value: 'obese_ii_plus', label: 'Obese (class II or higher)' },
+            ]}
+          />
+        </fieldset>
+      )}
+
+      {step === 'smoking' && (
+        <fieldset className="wizard-fieldset">
+          <legend>Smoking</legend>
+          <RadioRow
+            name="smoking"
+            value={answers.smoking}
+            onChange={(v) => patch('smoking', v as Smoking)}
+            options={[
+              { value: 'never', label: 'Never smoked' },
+              { value: 'former_15y', label: 'Former, quit 15+ years ago' },
+              { value: 'former_lt15y', label: 'Former, quit less than 15 years ago' },
+              { value: 'current_light', label: 'Current, light / occasional' },
+              { value: 'current_moderate', label: 'Current, about a pack per day' },
+              { value: 'current_heavy', label: 'Current, more than a pack per day' },
+            ]}
+          />
+        </fieldset>
+      )}
+
+      {step === 'alcohol' && (
+        <fieldset className="wizard-fieldset">
+          <legend>Alcohol</legend>
+          <RadioRow
+            name="alcohol"
+            value={answers.alcohol}
+            onChange={(v) => patch('alcohol', v as Alcohol)}
+            options={[
+              { value: 'never', label: 'None / rarely' },
+              { value: 'light', label: 'Light (e.g. 1–4 drinks per week)' },
+              { value: 'moderate', label: 'Moderate' },
+              { value: 'heavy', label: 'Heavy' },
+            ]}
+          />
+        </fieldset>
+      )}
+
+      {step === 'activity' && (
+        <fieldset className="wizard-fieldset">
+          <legend>Physical activity</legend>
+          <RadioRow
+            name="activity"
+            value={answers.activity}
+            onChange={(v) => patch('activity', v as Activity)}
+            options={[
+              { value: 'high', label: 'High (most days, 30+ minutes)' },
+              { value: 'moderate', label: 'Moderate (weekly exercise)' },
+              { value: 'low', label: 'Low (occasional)' },
+              { value: 'sedentary', label: 'Mostly sedentary' },
+            ]}
+          />
+        </fieldset>
+      )}
+
+      {step === 'diabetes' && (
+        <fieldset className="wizard-fieldset">
+          <legend>Diabetes</legend>
+          <RadioRow
+            name="diabetes"
+            value={answers.diabetes}
+            onChange={(v) => patch('diabetes', v as Diabetes)}
+            options={[
+              { value: 'no', label: 'No' },
+              { value: 'yes_controlled', label: 'Yes — generally controlled' },
+              { value: 'yes_uncontrolled', label: 'Yes — often not well controlled' },
+            ]}
+          />
+        </fieldset>
+      )}
+
+      {step === 'health' && (
+        <fieldset className="wizard-fieldset">
+          <legend>Overall health (self-rated)</legend>
+          <RadioRow
+            name="health"
+            value={answers.selfRatedHealth}
+            onChange={(v) => patch('selfRatedHealth', v as SelfRatedHealth)}
+            options={[
+              { value: 'excellent', label: 'Excellent' },
+              { value: 'good', label: 'Good' },
+              { value: 'fair', label: 'Fair' },
+              { value: 'poor', label: 'Poor' },
+              { value: 'very_poor', label: 'Very poor' },
+            ]}
+          />
+        </fieldset>
+      )}
+
+      {step === 'parents' && (
+        <fieldset className="wizard-fieldset">
+          <legend>Parents lived to age 80 or older?</legend>
+          <p className="field-hint">Rough family-longevity signal; skip if unsure.</p>
+          <RadioRow
+            name="parents"
+            value={answers.parentalLongevity}
+            onChange={(v) => patch('parentalLongevity', v as ParentalLongevity)}
+            options={[
+              { value: 'both_80', label: 'Both did' },
+              { value: 'one_80', label: 'One did' },
+              { value: 'neither_80', label: 'Neither / not to 80' },
+              { value: 'unknown', label: 'Unknown / not applicable' },
+            ]}
+          />
+        </fieldset>
+      )}
+
+      <div className="wizard-actions">
+        <button type="button" className="btn btn-secondary" onClick={goBack} disabled={stepIndex === 0}>
+          Back
+        </button>
+        <button type="button" className="btn btn-primary" onClick={goNext} disabled={!canNext}>
+          {stepIndex === STEPS.length - 1 ? 'See results' : 'Next'}
+        </button>
+      </div>
+    </div>
+  )
+}
+
+function RadioRow<T extends string>({
+  name,
+  value,
+  onChange,
+  options,
+}: {
+  name: string
+  value: T
+  onChange: (v: string) => void
+  options: { value: T; label: string }[]
+}) {
+  return (
+    <div className="radio-stack" role="radiogroup" aria-label={name}>
+      {options.map((o) => (
+        <label key={o.value} className="radio-option">
+          <input type="radio" name={name} value={o.value} checked={value === o.value} onChange={() => onChange(o.value)} />
+          <span>{o.label}</span>
+        </label>
+      ))}
+    </div>
+  )
+}

package/src/longevity/constants.ts

@@ -0,0 +1,15 @@
+import { STORAGE_KEYS } from '../data/localStore'
+
+/** localStorage key for saved longevity answers + last result (primary / household member A) */
+export const LONGEVITY_STORAGE_KEY = STORAGE_KEYS.longevity
+
+/** Second saved profile for Social Security couple survivor overlay (partner / household member B) */
+export const LONGEVITY_PARTNER_STORAGE_KEY = STORAGE_KEYS.longevityPartner
+
+/** SSA period life table vintage embedded in `ssaPeriod2022.ts` */
+export const BASELINE_CITATION = {
+  label: 'SSA period life table, 2022 (2025 Trustees Report)',
+  url: 'https://www.ssa.gov/oact/STATS/table4c6.html',
+  note:
+    '“Life expectancy” column is average remaining years for Social Security area population, by sex, using 2022 mortality rates.',
+} as const

package/src/longevity/factors.ts

@@ -0,0 +1,125 @@
+/**
+ * Conservative multipliers applied to **population remaining life expectancy**.
+ * These are illustrative adjustments for UX/education — not individualized medical
+ * underwriting. Magnitudes kept small; combined product is clamped in `model.ts`.
+ */
+import type {
+  Activity,
+  Alcohol,
+  BmiCategory,
+  Diabetes,
+  LongevityAnswers,
+  ParentalLongevity,
+  SelfRatedHealth,
+  Smoking,
+} from '@retiregolden/engine/longevity/types'
+
+export function bmiMultiplier(c: BmiCategory): number {
+  switch (c) {
+    case 'underweight':
+      return 0.97
+    case 'normal':
+      return 1
+    case 'overweight':
+      return 0.96
+    case 'obese_i':
+      return 0.92
+    case 'obese_ii_plus':
+      return 0.86
+  }
+}
+
+export function smokingMultiplier(s: Smoking): number {
+  switch (s) {
+    case 'never':
+      return 1
+    case 'former_15y':
+      return 0.98
+    case 'former_lt15y':
+      return 0.95
+    case 'current_light':
+      return 0.9
+    case 'current_moderate':
+      return 0.82
+    case 'current_heavy':
+      return 0.72
+  }
+}
+
+export function alcoholMultiplier(a: Alcohol): number {
+  switch (a) {
+    case 'never':
+      return 1
+    case 'light':
+      return 1.01
+    case 'moderate':
+      return 1
+    case 'heavy':
+      return 0.92
+  }
+}
+
+export function activityMultiplier(a: Activity): number {
+  switch (a) {
+    case 'high':
+      return 1.03
+    case 'moderate':
+      return 1
+    case 'low':
+      return 0.96
+    case 'sedentary':
+      return 0.91
+  }
+}
+
+export function diabetesMultiplier(d: Diabetes): number {
+  switch (d) {
+    case 'no':
+      return 1
+    case 'yes_controlled':
+      return 0.92
+    case 'yes_uncontrolled':
+      return 0.85
+  }
+}
+
+export function selfRatedHealthMultiplier(h: SelfRatedHealth): number {
+  switch (h) {
+    case 'excellent':
+      return 1.03
+    case 'good':
+      return 1.01
+    case 'fair':
+      return 0.94
+    case 'poor':
+      return 0.86
+    case 'very_poor':
+      return 0.76
+  }
+}
+
+export function parentalMultiplier(p: ParentalLongevity): number {
+  switch (p) {
+    case 'both_80':
+      return 1.02
+    case 'one_80':
+      return 1
+    case 'neither_80':
+      return 0.98
+    case 'unknown':
+      return 1
+  }
+}
+
+/** Product of all category multipliers (uncapped). */
+export function combinedMultiplier(a: LongevityAnswers): number {
+  return (
+    bmiMultiplier(a.bmiCategory) *
+    smokingMultiplier(a.smoking) *
+    alcoholMultiplier(a.alcohol) *
+    activityMultiplier(a.activity) *
+    diabetesMultiplier(a.diabetes) *
+    selfRatedHealthMultiplier(a.selfRatedHealth) *
+    parentalMultiplier(a.parentalLongevity)
+  )
+}

package/src/longevity/model.ts

@@ -0,0 +1,31 @@
+import { combinedMultiplier } from './factors'
+import { baselineRemainingYears } from '@retiregolden/engine/longevity/ssaPeriod2022'
+import type { LongevityAnswers, LongevityResult } from '@retiregolden/engine/longevity/types'
+
+const MULT_MIN = 0.55
+const MULT_MAX = 1.12
+
+/** Narrow illustrative band around central estimate (not a confidence interval). */
+const BAND_LOW = 0.9
+const BAND_HIGH = 1.08
+
+export function computeLongevity(answers: LongevityAnswers): LongevityResult {
+  const baseline = baselineRemainingYears(answers.age, answers.sex)
+  const raw = combinedMultiplier(answers)
+  const applied = Math.min(MULT_MAX, Math.max(MULT_MIN, raw))
+  const central = baseline * applied
+  const bandLow = central * BAND_LOW
+  const bandHigh = central * BAND_HIGH
+  const illustrativePlanningAge =
+    answers.age + Math.max(0, Math.round(central))
+
+  return {
+    baselineRemainingYears: baseline,
+    rawMultiplier: raw,
+    appliedMultiplier: applied,
+    centralRemainingYears: central,
+    bandLowRemainingYears: bandLow,
+    bandHighRemainingYears: bandHigh,
+    illustrativePlanningAge,
+  }
+}

package/src/longevity/persistedGuard.ts

@@ -0,0 +1,129 @@
+import type { LongevityAnswers, LongevityPersisted, LongevityResult } from '@retiregolden/engine/longevity/types'
+
+const SEX: LongevityAnswers['sex'][] = ['male', 'female', 'average']
+const BMI: LongevityAnswers['bmiCategory'][] = [
+  'underweight',
+  'normal',
+  'overweight',
+  'obese_i',
+  'obese_ii_plus',
+]
+const SMOKING: LongevityAnswers['smoking'][] = [
+  'never',
+  'former_15y',
+  'former_lt15y',
+  'current_light',
+  'current_moderate',
+  'current_heavy',
+]
+const ALCOHOL: LongevityAnswers['alcohol'][] = ['never', 'light', 'moderate', 'heavy']
+const ACTIVITY: LongevityAnswers['activity'][] = ['high', 'moderate', 'low', 'sedentary']
+const DIABETES: LongevityAnswers['diabetes'][] = ['no', 'yes_controlled', 'yes_uncontrolled']
+const HEALTH: LongevityAnswers['selfRatedHealth'][] = [
+  'excellent',
+  'good',
+  'fair',
+  'poor',
+  'very_poor',
+]
+const PARENTS: LongevityAnswers['parentalLongevity'][] = [
+  'both_80',
+  'one_80',
+  'neither_80',
+  'unknown',
+]
+
+function isRecord(x: unknown): x is Record<string, unknown> {
+  return typeof x === 'object' && x !== null && !Array.isArray(x)
+}
+
+function num(x: unknown): number | null {
+  return typeof x === 'number' && Number.isFinite(x) ? x : null
+}
+
+function str(x: unknown): string | null {
+  return typeof x === 'string' ? x : null
+}
+
+function oneOf<T extends string>(x: unknown, allowed: readonly T[]): T | null {
+  return typeof x === 'string' && (allowed as readonly string[]).includes(x) ? (x as T) : null
+}
+
+function parseAnswers(raw: unknown): LongevityAnswers | null {
+  if (!isRecord(raw)) return null
+  const age = num(raw.age)
+  if (age == null || age < 18 || age > 110) return null
+  const sex = oneOf(raw.sex, SEX)
+  const bmiCategory = oneOf(raw.bmiCategory, BMI)
+  const smoking = oneOf(raw.smoking, SMOKING)
+  const alcohol = oneOf(raw.alcohol, ALCOHOL)
+  const activity = oneOf(raw.activity, ACTIVITY)
+  const diabetes = oneOf(raw.diabetes, DIABETES)
+  const selfRatedHealth = oneOf(raw.selfRatedHealth, HEALTH)
+  const parentalLongevity = oneOf(raw.parentalLongevity, PARENTS)
+  if (
+    !sex ||
+    !bmiCategory ||
+    !smoking ||
+    !alcohol ||
+    !activity ||
+    !diabetes ||
+    !selfRatedHealth ||
+    !parentalLongevity
+  ) {
+    return null
+  }
+  return {
+    age,
+    sex,
+    bmiCategory,
+    smoking,
+    alcohol,
+    activity,
+    diabetes,
+    selfRatedHealth,
+    parentalLongevity,
+  }
+}
+
+function parseResult(raw: unknown): LongevityResult | null {
+  if (!isRecord(raw)) return null
+  const baselineRemainingYears = num(raw.baselineRemainingYears)
+  const rawMultiplier = num(raw.rawMultiplier)
+  const appliedMultiplier = num(raw.appliedMultiplier)
+  const centralRemainingYears = num(raw.centralRemainingYears)
+  const bandLowRemainingYears = num(raw.bandLowRemainingYears)
+  const bandHighRemainingYears = num(raw.bandHighRemainingYears)
+  const illustrativePlanningAge = num(raw.illustrativePlanningAge)
+  if (
+    baselineRemainingYears == null ||
+    rawMultiplier == null ||
+    appliedMultiplier == null ||
+    centralRemainingYears == null ||
+    bandLowRemainingYears == null ||
+    bandHighRemainingYears == null ||
+    illustrativePlanningAge == null
+  ) {
+    return null
+  }
+  return {
+    baselineRemainingYears,
+    rawMultiplier,
+    appliedMultiplier,
+    centralRemainingYears,
+    bandLowRemainingYears,
+    bandHighRemainingYears,
+    illustrativePlanningAge,
+  }
+}
+
+/** Returns null if JSON shape does not match v1 persisted longevity (schema drift / corruption). */
+export function parseLongevityPersistedLoose(raw: unknown): LongevityPersisted | null {
+  if (!isRecord(raw)) return null
+  if (raw.version !== 1) return null
+  const answers = parseAnswers(raw.answers)
+  const result = parseResult(raw.result)
+  const updatedAt = str(raw.updatedAt)
+  if (!answers || !result || !updatedAt) return null
+  return { version: 1, answers, result, updatedAt }
+}

package/src/longevity/storage.ts

@@ -0,0 +1,40 @@
+import { readLocal, removeLocal, writeLocal } from '../data/localStore'
+import { LONGEVITY_PARTNER_STORAGE_KEY, LONGEVITY_STORAGE_KEY } from './constants'
+import { parseLongevityPersistedLoose } from './persistedGuard'
+import type { LongevityPersisted } from '@retiregolden/engine/longevity/types'
+
+export function loadLongevity(): LongevityPersisted | null {
+  try {
+    const raw = readLocal(LONGEVITY_STORAGE_KEY)
+    if (!raw) return null
+    return parseLongevityPersistedLoose(JSON.parse(raw) as unknown)
+  } catch {
+    return null
+  }
+}
+
+export function saveLongevity(data: LongevityPersisted): void {
+  writeLocal(LONGEVITY_STORAGE_KEY, JSON.stringify(data))
+}
+
+export function clearLongevity(): void {
+  removeLocal(LONGEVITY_STORAGE_KEY)
+}
+
+export function loadLongevityPartner(): LongevityPersisted | null {
+  try {
+    const raw = readLocal(LONGEVITY_PARTNER_STORAGE_KEY)
+    if (!raw) return null
+    return parseLongevityPersistedLoose(JSON.parse(raw) as unknown)
+  } catch {
+    return null
+  }
+}
+
+export function saveLongevityPartner(data: LongevityPersisted): void {
+  writeLocal(LONGEVITY_PARTNER_STORAGE_KEY, JSON.stringify(data))
+}
+
+export function clearLongevityPartner(): void {
+  removeLocal(LONGEVITY_PARTNER_STORAGE_KEY)
+}