policyengine-household-wizard 0.1.0

package/src/styles.css

@@ -0,0 +1,183 @@
+/**
+ * Shared wizard primitive styles. Uses CSS variables from the PolicyEngine
+ * ui-kit theme where available, with safe fallbacks so the package also works
+ * in apps that haven't imported the ui-kit theme.
+ */
+
+.pe-wizard-progress {
+  display: flex;
+  flex-direction: column;
+  gap: 0.5rem;
+}
+
+.pe-wizard-progress-topline {
+  display: flex;
+  justify-content: space-between;
+  align-items: baseline;
+  font-size: 0.875rem;
+  color: var(--muted-foreground, var(--color-gray-600, #555));
+}
+
+.pe-wizard-progress-track {
+  height: 0.375rem;
+  background: var(--muted, var(--color-gray-200, #e5e7eb));
+  border-radius: 999px;
+  overflow: hidden;
+}
+
+.pe-wizard-progress-bar {
+  height: 100%;
+  background: var(--primary, var(--color-teal-600, #2c7a7b));
+  transition: width 0.25s ease-out;
+}
+
+.pe-wizard-option-card {
+  display: flex;
+  flex-direction: column;
+  align-items: flex-start;
+  gap: 0.25rem;
+  text-align: left;
+  width: 100%;
+  padding: 1rem 1.25rem;
+  background: var(--background, white);
+  color: var(--foreground, inherit);
+  border: 1.5px solid var(--border, var(--color-gray-200, #e5e7eb));
+  border-radius: var(--radius, 0.75rem);
+  cursor: pointer;
+  transition: border-color 0.15s ease, background 0.15s ease;
+  font: inherit;
+}
+
+.pe-wizard-option-card:hover:not(:disabled) {
+  border-color: var(--primary, var(--color-teal-500, #319795));
+  background: var(--accent, var(--color-teal-50, #e6fffa));
+}
+
+.pe-wizard-option-card:focus-visible {
+  outline: 2px solid var(--ring, var(--color-teal-500, #319795));
+  outline-offset: 2px;
+}
+
+.pe-wizard-option-card--selected {
+  border-color: var(--primary, var(--color-teal-600, #2c7a7b));
+  background: var(--accent, var(--color-teal-50, #e6fffa));
+}
+
+.pe-wizard-option-card:disabled,
+.pe-wizard-option-card[aria-disabled="true"] {
+  cursor: not-allowed;
+  opacity: 0.6;
+}
+
+.pe-wizard-option-card-title {
+  font-weight: 600;
+  font-size: 0.95rem;
+}
+
+.pe-wizard-option-card-description {
+  font-size: 0.85rem;
+  color: var(--muted-foreground, var(--color-gray-600, #555));
+  line-height: 1.4;
+}
+
+.pe-wizard-nav {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.75rem;
+  align-items: center;
+}
+
+.pe-wizard-nav-leading {
+  margin-right: auto;
+}
+
+.pe-wizard-nav-trailing {
+  margin-left: auto;
+}
+
+.pe-wizard-nav-back,
+.pe-wizard-nav-primary {
+  font: inherit;
+  border-radius: var(--radius, 0.5rem);
+  padding: 0.625rem 1.25rem;
+  cursor: pointer;
+  border: 1.5px solid transparent;
+  transition: background 0.15s ease, border-color 0.15s ease, color 0.15s ease;
+}
+
+.pe-wizard-nav-back {
+  background: transparent;
+  color: var(--foreground, inherit);
+  border-color: var(--border, var(--color-gray-300, #d1d5db));
+}
+
+.pe-wizard-nav-back:hover:not(:disabled) {
+  background: var(--muted, var(--color-gray-100, #f3f4f6));
+}
+
+.pe-wizard-nav-back:focus-visible,
+.pe-wizard-nav-primary:focus-visible {
+  outline: 2px solid var(--ring, var(--color-teal-500, #319795));
+  outline-offset: 2px;
+}
+
+.pe-wizard-nav-primary {
+  background: var(--primary, var(--color-teal-600, #2c7a7b));
+  color: var(--primary-foreground, white);
+}
+
+.pe-wizard-nav-primary:hover:not(:disabled) {
+  filter: brightness(1.05);
+}
+
+.pe-wizard-nav-back:disabled,
+.pe-wizard-nav-primary:disabled {
+  cursor: not-allowed;
+  opacity: 0.55;
+}
+
+.pe-wizard-review-list {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(15rem, 1fr));
+  gap: 0.75rem;
+}
+
+.pe-wizard-review-item {
+  display: flex;
+  flex-direction: column;
+  align-items: flex-start;
+  gap: 0.25rem;
+  text-align: left;
+  padding: 0.75rem 1rem;
+  background: var(--background, white);
+  border: 1px solid var(--border, var(--color-gray-200, #e5e7eb));
+  border-radius: var(--radius, 0.5rem);
+  font: inherit;
+  cursor: pointer;
+  transition: border-color 0.15s ease;
+}
+
+.pe-wizard-review-item[role="listitem"]:not(button) {
+  cursor: default;
+}
+
+.pe-wizard-review-item:hover:not(:disabled):not([role="listitem"]:not(button)) {
+  border-color: var(--primary, var(--color-teal-500, #319795));
+}
+
+.pe-wizard-review-item-label {
+  font-size: 0.8rem;
+  color: var(--muted-foreground, var(--color-gray-600, #555));
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+}
+
+.pe-wizard-review-item-value {
+  font-weight: 600;
+  font-size: 0.95rem;
+}
+
+.pe-wizard-review-item--missing .pe-wizard-review-item-value {
+  color: var(--destructive, var(--color-red-600, #dc2626));
+  font-weight: 500;
+}

package/src/us-household/adapters/index.ts

@@ -0,0 +1,15 @@
+export {
+  toV1HouseholdPayload,
+  toV1HouseholdSituation,
+  type V1EntityCollection,
+  type V1EntityRecord,
+  type V1FieldValue,
+  type V1GroupCollection,
+  type V1GroupRecord,
+  type V1HouseholdEnvelope,
+  type V1HouseholdSituation,
+  type V1PersonCollection,
+  type V1PersonRecord,
+  type V1ValueMap,
+  type ToV1PayloadOptions,
+} from './v1Payload';

package/src/us-household/adapters/v1Payload.ts

@@ -0,0 +1,213 @@
+import type {
+  USHouseholdDraft,
+  USPersonDraft,
+  USPersonFlags,
+  USPersonIncomes,
+} from '../types';
+
+/**
+ * The shape of a PolicyEngine US "situation" / household-creation payload at
+ * the wire level. Variables are year-keyed; person/group keys are arbitrary
+ * strings (callers pick them).
+ */
+export type V1ValueMap = Record<string, number | string | boolean | null>;
+export type V1FieldValue = V1ValueMap | string[] | undefined;
+
+/**
+ * A person record carries only year-keyed variable maps. `members` belongs on
+ * group records, never on people.
+ */
+export type V1PersonRecord = Record<string, V1ValueMap | undefined>;
+
+/**
+ * A group record always carries `members` plus zero-or-more year-keyed
+ * variable maps.
+ */
+export type V1GroupRecord = { members: string[] } & Record<string, V1FieldValue>;
+
+export type V1EntityRecord = V1PersonRecord | V1GroupRecord;
+export type V1PersonCollection = Record<string, V1PersonRecord>;
+export type V1GroupCollection = Record<string, V1GroupRecord>;
+/** @deprecated Prefer V1PersonCollection or V1GroupCollection. */
+export type V1EntityCollection = Record<string, V1EntityRecord>;
+
+export interface V1HouseholdSituation {
+  people: V1PersonCollection;
+  families?: V1GroupCollection;
+  marital_units?: V1GroupCollection;
+  tax_units?: V1GroupCollection;
+  spm_units?: V1GroupCollection;
+  households?: V1GroupCollection;
+}
+
+/**
+ * Matches policyengine-app-v2's `V1HouseholdCreateEnvelope` so `fromUSDraft`
+ * adapters can pass the envelope straight into `Household.fromV1CreationPayload`.
+ */
+export interface V1HouseholdEnvelope {
+  country_id: 'us';
+  label?: string | null;
+  data: V1HouseholdSituation;
+}
+
+export interface ToV1PayloadOptions {
+  /**
+   * Optional override for group keys. Defaults to short, lower-case keys
+   * (`"household"`, `"tax_unit"`, etc.). Pass `"verbose"` for `"your household"`
+   * style names compatible with app-v2's builder.
+   */
+  groupKeyStyle?: 'short' | 'verbose';
+  /**
+   * If true, attaches member ids to the marital unit. Off by default because
+   * cliff-watch and other consumers send `marital_units: {}` and have it work.
+   */
+  includeMaritalUnit?: boolean;
+  /**
+   * Optional label for the envelope. Surfaces as `label` on the V1
+   * creation/metadata response.
+   */
+  label?: string | null;
+}
+
+const SHORT_KEYS = {
+  household: 'household',
+  family: 'family',
+  taxUnit: 'tax_unit',
+  spmUnit: 'spm_unit',
+  maritalUnit: 'marital_unit',
+} as const;
+
+const VERBOSE_KEYS = {
+  household: 'your household',
+  family: 'your family',
+  taxUnit: 'your tax unit',
+  spmUnit: 'your household', // app-v2 uses the same label for SPM unit
+  maritalUnit: 'your marital unit',
+} as const;
+
+const FLAG_TO_VARIABLE: Record<keyof USPersonFlags, string> = {
+  isDisabled: 'is_disabled',
+  isBlind: 'is_blind',
+  isFullTimeStudent: 'is_full_time_student',
+  isPregnant: 'is_pregnant',
+  needsCare: 'is_incapable_of_self_care',
+};
+
+const INCOME_TO_VARIABLE: Record<keyof USPersonIncomes, string> = {
+  employmentIncome: 'employment_income',
+  selfEmploymentIncome: 'self_employment_income',
+  socialSecurityIncome: 'social_security',
+  ssiAmount: 'ssi',
+  ssdiAmount: 'social_security_disability',
+  pensionIncome: 'taxable_pension_income',
+  dividendIncome: 'qualified_dividend_income',
+  taxableInterestIncome: 'taxable_interest_income',
+  rentalIncome: 'rental_income',
+  unemploymentCompensation: 'unemployment_compensation',
+  childSupportReceived: 'child_support_received',
+  miscellaneousIncome: 'miscellaneous_income',
+};
+
+function yearMap(year: string, value: number | string | boolean): V1ValueMap {
+  return { [year]: value };
+}
+
+function buildPersonVariables(person: USPersonDraft, year: string): V1PersonRecord {
+  const record: V1PersonRecord = {};
+
+  if (person.age !== null && person.age !== undefined) {
+    record.age = yearMap(year, person.age);
+  }
+
+  if (person.kind === 'dependent') {
+    record.is_tax_unit_dependent = yearMap(year, true);
+  }
+
+  for (const [draftKey, variable] of Object.entries(FLAG_TO_VARIABLE)) {
+    const value = (person as USPersonDraft)[draftKey as keyof USPersonFlags];
+    if (value !== undefined) {
+      record[variable] = yearMap(year, value);
+    }
+  }
+
+  for (const [draftKey, variable] of Object.entries(INCOME_TO_VARIABLE)) {
+    const value = (person as USPersonDraft)[draftKey as keyof USPersonIncomes];
+    if (value !== undefined && value !== null) {
+      record[variable] = yearMap(year, value);
+    }
+  }
+
+  return record;
+}
+
+export function toV1HouseholdPayload(
+  draft: USHouseholdDraft,
+  options: ToV1PayloadOptions = {},
+): V1HouseholdEnvelope {
+  const { groupKeyStyle = 'short', includeMaritalUnit = false, label = null } = options;
+  const keys = groupKeyStyle === 'verbose' ? VERBOSE_KEYS : SHORT_KEYS;
+  const year = String(draft.year);
+
+  const memberIds = draft.people.map((person) => person.id);
+
+  const people: V1PersonCollection = {};
+  for (const person of draft.people) {
+    people[person.id] = buildPersonVariables(person, year);
+  }
+
+  const householdRecord: V1GroupRecord = {
+    members: [...memberIds],
+  };
+  if (draft.state) {
+    householdRecord.state_name = yearMap(year, draft.state);
+  }
+  if (draft.county) {
+    householdRecord.county = yearMap(year, draft.county);
+  }
+
+  const families: V1GroupCollection = {
+    [keys.family]: { members: [...memberIds] },
+  };
+  const taxUnits: V1GroupCollection = {
+    [keys.taxUnit]: { members: [...memberIds] },
+  };
+  const spmUnits: V1GroupCollection = {
+    [keys.spmUnit]: { members: [...memberIds] },
+  };
+  const households: V1GroupCollection = {
+    [keys.household]: householdRecord,
+  };
+
+  const maritalUnits: V1GroupCollection = {};
+  if (includeMaritalUnit) {
+    const adults = draft.people.filter((person) => person.kind === 'adult');
+    maritalUnits[keys.maritalUnit] = {
+      members: adults.slice(0, 2).map((person) => person.id),
+    };
+  }
+
+  return {
+    country_id: 'us',
+    label,
+    data: {
+      people,
+      families,
+      marital_units: maritalUnits,
+      tax_units: taxUnits,
+      spm_units: spmUnits,
+      households,
+    },
+  };
+}
+
+/**
+ * Convenience that returns just the inner `V1HouseholdSituation` — useful for
+ * callers that POST to `/calculate` or otherwise need the situation directly
+ * without the envelope wrapper.
+ */
+export function toV1HouseholdSituation(
+  draft: USHouseholdDraft,
+  options: ToV1PayloadOptions = {},
+): V1HouseholdSituation {
+  return toV1HouseholdPayload(draft, options).data;
+}

package/src/us-household/counties.ts

@@ -0,0 +1,96 @@
+import countiesByState from './data/counties-by-state.json' with { type: 'json' };
+
+export interface County {
+  /** PolicyEngine US county enum code (e.g. "ALAMEDA_COUNTY_CA"). */
+  code: string;
+  /** Display name without the trailing state segment (e.g. "Alameda County"). */
+  name: string;
+}
+
+const DATA = countiesByState as Record<string, County[]>;
+
+/**
+ * Counties grouped by two-letter state code, sorted by name. The data ships
+ * inline with the package so the wizard can render a county dropdown without
+ * any network call.
+ *
+ * To refresh from PolicyEngine US metadata, run `bun run regenerate-counties`.
+ */
+export function getCountiesByState(stateCode: string | null | undefined): County[] {
+  if (!stateCode) {
+    return [];
+  }
+  return DATA[stateCode] ?? [];
+}
+
+const COUNTY_CODES: Set<string> = new Set(
+  Object.values(DATA)
+    .flat()
+    .map((county) => county.code),
+);
+
+const COUNTY_NAMES_BY_STATE: Map<string, Map<string, string>> = new Map(
+  Object.entries(DATA).map(([stateCode, list]) => [
+    stateCode,
+    new Map(list.map((county) => [normalizeName(county.name), county.code])),
+  ]),
+);
+
+function normalizeName(value: string): string {
+  return value
+    .normalize('NFKD')
+    .replace(/[̀-ͯ]/g, '')
+    .toLowerCase()
+    .replace(/\bcounty\b|\bparish\b|\bborough\b|\bcensus area\b|\bmunicipality\b/g, '')
+    .replace(/[^a-z0-9]+/g, ' ')
+    .trim();
+}
+
+export function isCountyCode(value: unknown): value is string {
+  return typeof value === 'string' && COUNTY_CODES.has(value);
+}
+
+export function getCountyName(code: string | null | undefined): string | null {
+  if (!code) {
+    return null;
+  }
+  for (const list of Object.values(DATA)) {
+    for (const county of list) {
+      if (county.code === code) {
+        return county.name;
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Resolve a free-text county name (legacy input shape used by Coverage Compass
+ * and others) to a PolicyEngine county code. Matching is case-insensitive and
+ * ignores common suffixes like "County", "Parish", "Borough".
+ */
+export function resolveCountyCode(
+  stateCode: string | null | undefined,
+  countyInput: string | null | undefined,
+): string | null {
+  if (!stateCode || !countyInput) {
+    return null;
+  }
+
+  // If the caller already passed a known county code, return it unchanged.
+  if (isCountyCode(countyInput)) {
+    return countyInput;
+  }
+
+  const lookup = COUNTY_NAMES_BY_STATE.get(stateCode);
+  if (!lookup) {
+    return null;
+  }
+  const key = normalizeName(countyInput);
+  if (!key) {
+    return null;
+  }
+  return lookup.get(key) ?? null;
+}
+
+export { DATA as _rawCountyData };