policyengine-household-wizard 0.1.0 → 0.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +50 -5
- package/dist/WizardReviewList-DhLx8Bla.cjs +1 -0
- package/dist/WizardReviewList-oY1HqmLw.js +354 -0
- package/dist/index-B_OXaS4a.cjs +1 -0
- package/dist/index-CIL8FXNR.cjs +1 -0
- package/dist/index-DWM0giHt.js +220 -0
- package/dist/index-fgLnXugs.js +225 -0
- package/dist/index.cjs +1 -1
- package/dist/index.d.ts +2 -2
- package/dist/index.js +34 -28
- package/dist/primitives/WizardReviewList.d.ts +3 -2
- package/dist/primitives/WizardReviewList.d.ts.map +1 -1
- package/dist/primitives/index.d.ts +12 -10
- package/dist/primitives/index.d.ts.map +1 -1
- package/dist/primitives/types.d.ts +18 -0
- package/dist/primitives/types.d.ts.map +1 -1
- package/dist/primitives/useWizardStepFocus.d.ts +13 -0
- package/dist/primitives/useWizardStepFocus.d.ts.map +1 -0
- package/dist/primitives/useWizardSteps.d.ts +2 -2
- package/dist/primitives/useWizardSteps.d.ts.map +1 -1
- package/dist/primitives.cjs +1 -1
- package/dist/primitives.d.ts +1 -1
- package/dist/primitives.js +5 -4
- package/dist/uk-household/adapters/householdImpactRequest.d.ts +91 -0
- package/dist/uk-household/adapters/householdImpactRequest.d.ts.map +1 -0
- package/dist/uk-household/adapters/index.d.ts +2 -0
- package/dist/uk-household/adapters/index.d.ts.map +1 -0
- package/dist/uk-household/children.d.ts +18 -0
- package/dist/uk-household/children.d.ts.map +1 -0
- package/dist/uk-household/codes.d.ts +22 -0
- package/dist/uk-household/codes.d.ts.map +1 -0
- package/dist/uk-household/defaults.d.ts +56 -0
- package/dist/uk-household/defaults.d.ts.map +1 -0
- package/dist/uk-household/draft.d.ts +37 -0
- package/dist/uk-household/draft.d.ts.map +1 -0
- package/dist/uk-household/index.d.ts +10 -0
- package/dist/uk-household/index.d.ts.map +1 -0
- package/dist/uk-household/serialize.d.ts +4 -0
- package/dist/uk-household/serialize.d.ts.map +1 -0
- package/dist/uk-household/statePension.d.ts +42 -0
- package/dist/uk-household/statePension.d.ts.map +1 -0
- package/dist/uk-household/types.d.ts +134 -0
- package/dist/uk-household/types.d.ts.map +1 -0
- package/dist/uk-household/validate.d.ts +59 -0
- package/dist/uk-household/validate.d.ts.map +1 -0
- package/dist/uk-household-adapters.cjs +1 -0
- package/dist/uk-household-adapters.d.ts +1 -0
- package/dist/uk-household-adapters.js +5 -0
- package/dist/uk-household.cjs +1 -0
- package/dist/uk-household.d.ts +1 -0
- package/dist/uk-household.js +220 -0
- package/dist/us-household/adapters/index.d.ts +1 -1
- package/dist/us-household/adapters/v1Payload.d.ts +119 -3
- package/dist/us-household/adapters/v1Payload.d.ts.map +1 -1
- package/dist/us-household/amount.d.ts +8 -0
- package/dist/us-household/amount.d.ts.map +1 -0
- package/dist/us-household/draft.d.ts +1 -1
- package/dist/us-household/index.d.ts +9 -8
- package/dist/us-household/index.d.ts.map +1 -1
- package/dist/us-household/normalize.d.ts +1 -1
- package/dist/us-household/normalize.d.ts.map +1 -1
- package/dist/us-household/serialize.d.ts +1 -1
- package/dist/us-household/serialize.d.ts.map +1 -1
- package/dist/us-household/tippedOccupations.d.ts +40 -0
- package/dist/us-household/tippedOccupations.d.ts.map +1 -0
- package/dist/us-household/types.d.ts +138 -18
- package/dist/us-household/types.d.ts.map +1 -1
- package/dist/us-household/validate.d.ts +1 -1
- package/dist/us-household/validate.d.ts.map +1 -1
- package/dist/us-household-adapters.cjs +1 -1
- package/dist/us-household-adapters.d.ts +1 -1
- package/dist/us-household-adapters.js +3 -90
- package/dist/us-household.cjs +1 -1
- package/dist/us-household.d.ts +1 -1
- package/dist/us-household.js +346 -246
- package/dist/validation.d.ts +16 -0
- package/dist/validation.d.ts.map +1 -0
- package/package.json +16 -2
- package/src/primitives/WizardReviewList.tsx +35 -18
- package/src/primitives/index.ts +3 -0
- package/src/primitives/types.ts +20 -0
- package/src/primitives/useWizardStepFocus.ts +42 -0
- package/src/primitives/useWizardSteps.ts +181 -84
- package/src/styles.css +9 -0
- package/src/uk-household/adapters/householdImpactRequest.ts +164 -0
- package/src/uk-household/adapters/index.ts +9 -0
- package/src/uk-household/children.ts +23 -0
- package/src/uk-household/codes.ts +67 -0
- package/src/uk-household/defaults.ts +101 -0
- package/src/uk-household/draft.ts +138 -0
- package/src/uk-household/index.ts +75 -0
- package/src/uk-household/serialize.ts +189 -0
- package/src/uk-household/statePension.ts +69 -0
- package/src/uk-household/types.ts +159 -0
- package/src/uk-household/validate.ts +190 -0
- package/src/us-household/adapters/v1Payload.ts +211 -18
- package/src/us-household/amount.ts +10 -0
- package/src/us-household/index.ts +11 -0
- package/src/us-household/normalize.ts +79 -4
- package/src/us-household/serialize.ts +5 -1
- package/src/us-household/tippedOccupations.ts +145 -0
- package/src/us-household/types.ts +144 -15
- package/src/us-household/validate.ts +101 -4
- package/src/validation.ts +12 -0
- package/dist/WizardReviewList-De9RTK_4.js +0 -245
- package/dist/WizardReviewList-tfP9LcqU.cjs +0 -1
|
@@ -1,6 +1,9 @@
|
|
|
1
|
+
import { toAmount } from '../amount';
|
|
2
|
+
import { toTippedOccupationCode } from '../tippedOccupations';
|
|
1
3
|
import type {
|
|
2
4
|
USHouseholdDraft,
|
|
3
5
|
USPersonDraft,
|
|
6
|
+
USPersonExpenses,
|
|
4
7
|
USPersonFlags,
|
|
5
8
|
USPersonIncomes,
|
|
6
9
|
} from '../types';
|
|
@@ -58,8 +61,10 @@ export interface ToV1PayloadOptions {
|
|
|
58
61
|
*/
|
|
59
62
|
groupKeyStyle?: 'short' | 'verbose';
|
|
60
63
|
/**
|
|
61
|
-
* If true,
|
|
62
|
-
*
|
|
64
|
+
* If true, puts the first two adults in one marital unit. Off by default for
|
|
65
|
+
* compatibility. With `marital_units: {}`, policyengine-core gives each
|
|
66
|
+
* person their own marital unit, so a married couple gets individual SSI
|
|
67
|
+
* rates instead of the couple rate; pass true for married drafts.
|
|
63
68
|
*/
|
|
64
69
|
includeMaritalUnit?: boolean;
|
|
65
70
|
/**
|
|
@@ -85,22 +90,121 @@ const VERBOSE_KEYS = {
|
|
|
85
90
|
maritalUnit: 'your marital unit',
|
|
86
91
|
} as const;
|
|
87
92
|
|
|
88
|
-
|
|
93
|
+
/*
|
|
94
|
+
* Variables PolicyEngine US computes must be sent for every person or for no
|
|
95
|
+
* one. policyengine-core stores one array per variable and period for a whole
|
|
96
|
+
* entity: the first person with an input allocates it, filled with the
|
|
97
|
+
* variable's default, so everyone without an input holds that default and the
|
|
98
|
+
* formula never runs for them. A `{year: null}` value does not help, because
|
|
99
|
+
* policyengine-core skips it. So each person gets input variables, which
|
|
100
|
+
* have no formula and whose stored default is what the model would use
|
|
101
|
+
* anyway, plus computed variables only when every person has an answer. The
|
|
102
|
+
* exceptions are `employment_income`, `self_employment_income` and
|
|
103
|
+
* `long_term_capital_gains`, computed totals that policyengine-us's Simulation
|
|
104
|
+
* moves onto the inputs `employment_income_before_lsr`,
|
|
105
|
+
* `self_employment_income_before_lsr` and
|
|
106
|
+
* `long_term_capital_gains_before_response` (reviewed in
|
|
107
|
+
* `REVIEWED_PARTIAL_COMPUTED` in the invariant tests).
|
|
108
|
+
*
|
|
109
|
+
* - `is_tax_unit_dependent` comes from `kind`, which every person has.
|
|
110
|
+
* - `isFullTimeStudent` is sent as the input `is_full_time_college_student`,
|
|
111
|
+
* not the computed `is_full_time_student`.
|
|
112
|
+
* - `ssi` is sent only when every person has an `ssiAmount`; an entered 0 is
|
|
113
|
+
* also sent as the input `takes_up_ssi_if_eligible: false`.
|
|
114
|
+
*
|
|
115
|
+
* `tests/us-household/v1PayloadInvariants.test.ts` checks this against the
|
|
116
|
+
* PolicyEngine US variable graph.
|
|
117
|
+
*/
|
|
118
|
+
|
|
119
|
+
/**
|
|
120
|
+
* Person flags and the PolicyEngine US variables they set. Exported for tests
|
|
121
|
+
* and tooling; not part of the package entry points. Only true and false are
|
|
122
|
+
* sent; anything else (such as null in a JSON draft) counts as not answered.
|
|
123
|
+
*
|
|
124
|
+
* `is_full_time_student` is computed as `is_full_time_college_student` or
|
|
125
|
+
* `is_in_k12_school`, and the model counts everyone aged 5 to 17 as a K-12
|
|
126
|
+
* student. So `isFullTimeStudent` is sent as full-time college enrollment,
|
|
127
|
+
* and only from `COLLEGE_MIN_AGE`: sending it for a child would make them a
|
|
128
|
+
* college student (for example, for New Jersey's exemption for dependents
|
|
129
|
+
* attending college), and sending the computed total would take K-12 status
|
|
130
|
+
* away from every other child in the household.
|
|
131
|
+
*/
|
|
132
|
+
export const FLAG_TO_VARIABLE: Readonly<Record<keyof USPersonFlags, string>> = {
|
|
89
133
|
isDisabled: 'is_disabled',
|
|
90
134
|
isBlind: 'is_blind',
|
|
91
|
-
isFullTimeStudent: '
|
|
135
|
+
isFullTimeStudent: 'is_full_time_college_student',
|
|
92
136
|
isPregnant: 'is_pregnant',
|
|
93
137
|
needsCare: 'is_incapable_of_self_care',
|
|
94
138
|
};
|
|
95
139
|
|
|
96
|
-
|
|
140
|
+
/**
|
|
141
|
+
* The youngest age at which `isFullTimeStudent` is sent. PolicyEngine US's
|
|
142
|
+
* `is_in_k12_school` covers ages 5 to 17, so a full-time student aged 18 or
|
|
143
|
+
* over is taken to be in college. A person with no age is sent the flag,
|
|
144
|
+
* because the model then assumes an adult age.
|
|
145
|
+
*/
|
|
146
|
+
export const COLLEGE_MIN_AGE = 18;
|
|
147
|
+
|
|
148
|
+
/**
|
|
149
|
+
* An entered 0 in `ssiAmount` is sent as this variable, set to false. It is an
|
|
150
|
+
* input (default true), so it sets that person's SSI to 0 without affecting
|
|
151
|
+
* anyone else. In policyengine-us 1.764.6 only `ssi` reads it. In 2.49.2,
|
|
152
|
+
* the shared state-supplement helper and a county General Relief rule read it
|
|
153
|
+
* too, so a 0 also means no supplement from that helper. Some states compute
|
|
154
|
+
* their own supplement from federal SSI instead: California's is its payment
|
|
155
|
+
* standard less SSI and countable income, so a 0 raises it.
|
|
156
|
+
*/
|
|
157
|
+
export const SSI_TAKE_UP_VARIABLE = 'takes_up_ssi_if_eligible';
|
|
158
|
+
|
|
159
|
+
/**
|
|
160
|
+
* Person income fields and the PolicyEngine US variables they set. Exported
|
|
161
|
+
* for tests and tooling; not part of the package entry points.
|
|
162
|
+
*
|
|
163
|
+
* Where PolicyEngine US defines a variable as the sum of components (`adds`),
|
|
164
|
+
* an input on the total replaces that sum: components sent alongside it are
|
|
165
|
+
* left out of the total and everything computed from it, and components not
|
|
166
|
+
* sent read as zero where rules use them directly. `social_security` adds
|
|
167
|
+
* retirement, disability, survivors, and dependents benefits, so
|
|
168
|
+
* `socialSecurityIncome` sets `social_security_retirement` and `ssdiAmount`
|
|
169
|
+
* sets `social_security_disability`; the model sums them.
|
|
170
|
+
*
|
|
171
|
+
* Likewise `taxable_pension_income` adds public and private pensions, and
|
|
172
|
+
* state rules read those components. `publicPensionIncome` and
|
|
173
|
+
* `privatePensionIncome` set them. A pension of unknown source
|
|
174
|
+
* (`pensionIncome`) is sent as private. Fields that share a variable are
|
|
175
|
+
* summed. Numeric strings are read as numbers and other amounts that are not
|
|
176
|
+
* finite numbers are skipped, so a bad value in one field cannot corrupt a
|
|
177
|
+
* shared sum.
|
|
178
|
+
*
|
|
179
|
+
* `ssi` is computed, so `ssiAmount` follows the household rule above: the
|
|
180
|
+
* amounts are sent as `ssi` for everyone when every person has one, and
|
|
181
|
+
* otherwise the model computes everyone's SSI. `validate()` asks for the
|
|
182
|
+
* missing amounts in that case.
|
|
183
|
+
*
|
|
184
|
+
* Three totals are set directly: `employment_income`, `self_employment_income`
|
|
185
|
+
* and `long_term_capital_gains`. Each adds an input and a behavioral response,
|
|
186
|
+
* and PolicyEngine US's Simulation moves an input on the total onto that
|
|
187
|
+
* component input (`employment_income_before_lsr`,
|
|
188
|
+
* `self_employment_income_before_lsr`, `long_term_capital_gains_before_response`).
|
|
189
|
+
*
|
|
190
|
+
* `tests/us-household/v1PayloadInvariants.test.ts` checks this mapping against
|
|
191
|
+
* the PolicyEngine US variable graph, including the few totals that are safe
|
|
192
|
+
* to set directly.
|
|
193
|
+
*/
|
|
194
|
+
export const INCOME_TO_VARIABLE: Readonly<Record<keyof USPersonIncomes, string>> = {
|
|
97
195
|
employmentIncome: 'employment_income',
|
|
196
|
+
tipIncome: 'tip_income',
|
|
98
197
|
selfEmploymentIncome: 'self_employment_income',
|
|
99
|
-
socialSecurityIncome: '
|
|
198
|
+
socialSecurityIncome: 'social_security_retirement',
|
|
100
199
|
ssiAmount: 'ssi',
|
|
101
200
|
ssdiAmount: 'social_security_disability',
|
|
102
|
-
pensionIncome: '
|
|
201
|
+
pensionIncome: 'taxable_private_pension_income',
|
|
202
|
+
publicPensionIncome: 'taxable_public_pension_income',
|
|
203
|
+
privatePensionIncome: 'taxable_private_pension_income',
|
|
103
204
|
dividendIncome: 'qualified_dividend_income',
|
|
205
|
+
nonQualifiedDividendIncome: 'non_qualified_dividend_income',
|
|
206
|
+
shortTermCapitalGains: 'short_term_capital_gains',
|
|
207
|
+
longTermCapitalGains: 'long_term_capital_gains',
|
|
104
208
|
taxableInterestIncome: 'taxable_interest_income',
|
|
105
209
|
rentalIncome: 'rental_income',
|
|
106
210
|
unemploymentCompensation: 'unemployment_compensation',
|
|
@@ -108,6 +212,58 @@ const INCOME_TO_VARIABLE: Record<keyof USPersonIncomes, string> = {
|
|
|
108
212
|
miscellaneousIncome: 'miscellaneous_income',
|
|
109
213
|
};
|
|
110
214
|
|
|
215
|
+
/**
|
|
216
|
+
* Income fields that PolicyEngine US also counts inside another variable, and
|
|
217
|
+
* that variable. Exported for tests and tooling; not part of the package entry
|
|
218
|
+
* points.
|
|
219
|
+
*
|
|
220
|
+
* PolicyEngine US counts tips as part of wages: `employment_income` is wages
|
|
221
|
+
* "including tips and commissions", and income and payroll taxes read it
|
|
222
|
+
* (through `irs_employment_income` and `payroll_tax_gross_wages`). A few rules
|
|
223
|
+
* read `tip_income` on its own: the qualified tips deduction, Georgia's cash
|
|
224
|
+
* tip exclusion, and Washington's long-term care premium (which subtracts it
|
|
225
|
+
* from wages). So `tipIncome` is sent as `tip_income` and also added to
|
|
226
|
+
* `employment_income`; without the second, tips would be deducted but never
|
|
227
|
+
* taxed. One rule departs from this convention: Florida School Readiness
|
|
228
|
+
* adds `tip_income` to `employment_income` and so counts tips twice
|
|
229
|
+
* (PolicyEngine/policyengine-us#10262).
|
|
230
|
+
*/
|
|
231
|
+
export const INCOME_ALSO_ADDED_TO: Readonly<Partial<Record<keyof USPersonIncomes, string>>> = {
|
|
232
|
+
tipIncome: 'employment_income',
|
|
233
|
+
};
|
|
234
|
+
|
|
235
|
+
/**
|
|
236
|
+
* Person expense fields and the PolicyEngine US input variables they set.
|
|
237
|
+
* Exported for tests and tooling; not part of the package entry points.
|
|
238
|
+
*
|
|
239
|
+
* `mortgageInterest` sets `home_mortgage_interest`, the input. PolicyEngine US
|
|
240
|
+
* computes `mortgage_interest` as the sum of deductible and non-deductible
|
|
241
|
+
* interest, and its federal interest deduction reads the input, so an amount
|
|
242
|
+
* sent as `mortgage_interest` changes no federal deduction. (North Carolina,
|
|
243
|
+
* Hawaii and Alabama rules read the computed total, which includes the input.)
|
|
244
|
+
*/
|
|
245
|
+
export const EXPENSE_TO_VARIABLE: Readonly<Record<keyof USPersonExpenses, string>> = {
|
|
246
|
+
charitableCashDonations: 'charitable_cash_donations',
|
|
247
|
+
mortgageInterest: 'home_mortgage_interest',
|
|
248
|
+
realEstateTaxes: 'real_estate_taxes',
|
|
249
|
+
};
|
|
250
|
+
|
|
251
|
+
/**
|
|
252
|
+
* `tippedOccupationCode` is sent as this variable, an integer input whose
|
|
253
|
+
* default 0 means no listed occupation. Only listed codes and 0 are sent.
|
|
254
|
+
* Amounts are sent as entered and checked by `validate()`, but an unlisted
|
|
255
|
+
* code is dropped: the model reads any code above 0 as a listed occupation,
|
|
256
|
+
* so a stray one would claim the deduction.
|
|
257
|
+
*/
|
|
258
|
+
export const TIPPED_OCCUPATION_VARIABLE = 'treasury_tipped_occupation_code';
|
|
259
|
+
|
|
260
|
+
/** Every amount field, with each variable it is added to. */
|
|
261
|
+
const AMOUNT_TO_VARIABLES: ReadonlyArray<[string, string]> = [
|
|
262
|
+
...Object.entries(INCOME_TO_VARIABLE),
|
|
263
|
+
...(Object.entries(INCOME_ALSO_ADDED_TO) as Array<[string, string]>),
|
|
264
|
+
...Object.entries(EXPENSE_TO_VARIABLE),
|
|
265
|
+
];
|
|
266
|
+
|
|
111
267
|
function yearMap(year: string, value: number | string | boolean): V1ValueMap {
|
|
112
268
|
return { [year]: value };
|
|
113
269
|
}
|
|
@@ -119,27 +275,50 @@ function buildPersonVariables(person: USPersonDraft, year: string): V1PersonReco
|
|
|
119
275
|
record.age = yearMap(year, person.age);
|
|
120
276
|
}
|
|
121
277
|
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
}
|
|
278
|
+
// Every person has a kind, so every person carries this computed variable.
|
|
279
|
+
record.is_tax_unit_dependent = yearMap(year, person.kind === 'dependent');
|
|
125
280
|
|
|
281
|
+
// Children's student status comes from the model's K-12 age rule.
|
|
282
|
+
const age = toAmount(person.age);
|
|
283
|
+
const belowCollegeAge = age !== undefined && age < COLLEGE_MIN_AGE;
|
|
126
284
|
for (const [draftKey, variable] of Object.entries(FLAG_TO_VARIABLE)) {
|
|
127
285
|
const value = (person as USPersonDraft)[draftKey as keyof USPersonFlags];
|
|
128
|
-
if (
|
|
286
|
+
if (draftKey === 'isFullTimeStudent' && belowCollegeAge) {
|
|
287
|
+
continue;
|
|
288
|
+
}
|
|
289
|
+
if (typeof value === 'boolean') {
|
|
129
290
|
record[variable] = yearMap(year, value);
|
|
130
291
|
}
|
|
131
292
|
}
|
|
132
293
|
|
|
133
|
-
for (const [draftKey, variable] of
|
|
134
|
-
const value = (person as
|
|
135
|
-
if (value !== undefined &&
|
|
136
|
-
record[variable]
|
|
294
|
+
for (const [draftKey, variable] of AMOUNT_TO_VARIABLES) {
|
|
295
|
+
const value = toAmount((person as unknown as Record<string, unknown>)[draftKey]);
|
|
296
|
+
if (value !== undefined && draftKey !== 'ssiAmount') {
|
|
297
|
+
const sharedWith = record[variable]?.[year];
|
|
298
|
+
const total = typeof sharedWith === 'number' ? sharedWith + value : value;
|
|
299
|
+
record[variable] = yearMap(year, total);
|
|
137
300
|
}
|
|
138
301
|
}
|
|
139
302
|
|
|
303
|
+
const occupationCode = toTippedOccupationCode(person.tippedOccupationCode);
|
|
304
|
+
if (occupationCode !== undefined) {
|
|
305
|
+
record[TIPPED_OCCUPATION_VARIABLE] = yearMap(year, occupationCode);
|
|
306
|
+
}
|
|
307
|
+
|
|
140
308
|
return record;
|
|
141
309
|
}
|
|
142
310
|
|
|
311
|
+
/**
|
|
312
|
+
* Build the PolicyEngine API V1 household payload for a draft. Everyone shares
|
|
313
|
+
* one family, tax unit, SPM unit and household. Check the draft with
|
|
314
|
+
* `validate()` first:
|
|
315
|
+
*
|
|
316
|
+
* - A person with no age is sent without one, and PolicyEngine US then uses
|
|
317
|
+
* its default age of 40 (`validate()` requires ages by default).
|
|
318
|
+
* - SSI amounts are sent only when every person has one. If some are
|
|
319
|
+
* missing, the entered amounts are dropped and the model computes
|
|
320
|
+
* everyone's SSI (`validate()` reports `person.ssiAmount.requiredWhenAnyReceives`).
|
|
321
|
+
*/
|
|
143
322
|
export function toV1HouseholdPayload(
|
|
144
323
|
draft: USHouseholdDraft,
|
|
145
324
|
options: ToV1PayloadOptions = {},
|
|
@@ -150,10 +329,24 @@ export function toV1HouseholdPayload(
|
|
|
150
329
|
|
|
151
330
|
const memberIds = draft.people.map((person) => person.id);
|
|
152
331
|
|
|
332
|
+
// `ssi` goes to everyone or no one; see the note above FLAG_TO_VARIABLE.
|
|
333
|
+
const ssiAmounts = draft.people.map((person) => toAmount(person.ssiAmount));
|
|
334
|
+
const sendSsi =
|
|
335
|
+
ssiAmounts.every((amount) => amount !== undefined) &&
|
|
336
|
+
ssiAmounts.some((amount) => amount !== 0);
|
|
337
|
+
|
|
153
338
|
const people: V1PersonCollection = {};
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
339
|
+
draft.people.forEach((person, index) => {
|
|
340
|
+
const record = buildPersonVariables(person, year);
|
|
341
|
+
const ssiAmount = ssiAmounts[index];
|
|
342
|
+
if (ssiAmount === 0) {
|
|
343
|
+
record[SSI_TAKE_UP_VARIABLE] = yearMap(year, false);
|
|
344
|
+
}
|
|
345
|
+
if (sendSsi && ssiAmount !== undefined) {
|
|
346
|
+
record[INCOME_TO_VARIABLE.ssiAmount] = yearMap(year, ssiAmount);
|
|
347
|
+
}
|
|
348
|
+
people[person.id] = record;
|
|
349
|
+
});
|
|
157
350
|
|
|
158
351
|
const householdRecord: V1GroupRecord = {
|
|
159
352
|
members: [...memberIds],
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* An entered amount as a finite number, or `undefined` when nothing usable was
|
|
3
|
+
* entered. Drafts parsed from JSON or forms can carry numeric strings, null,
|
|
4
|
+
* NaN, or Infinity. `validate()` and the V1 adapter both use this, so they
|
|
5
|
+
* agree on which amounts count as entered.
|
|
6
|
+
*/
|
|
7
|
+
export function toAmount(value: unknown): number | undefined {
|
|
8
|
+
const amount = typeof value === 'string' && value.trim() !== '' ? Number(value) : value;
|
|
9
|
+
return typeof amount === 'number' && Number.isFinite(amount) ? amount : undefined;
|
|
10
|
+
}
|
|
@@ -2,9 +2,11 @@ export type {
|
|
|
2
2
|
USHouseholdDraft,
|
|
3
3
|
USMaritalStatus,
|
|
4
4
|
USPersonDraft,
|
|
5
|
+
USPersonExpenses,
|
|
5
6
|
USPersonFlags,
|
|
6
7
|
USPersonIncomes,
|
|
7
8
|
USPersonKind,
|
|
9
|
+
USPersonOccupation,
|
|
8
10
|
ValidationIssue,
|
|
9
11
|
ValidationResult,
|
|
10
12
|
} from './types';
|
|
@@ -34,6 +36,15 @@ export {
|
|
|
34
36
|
type USState,
|
|
35
37
|
} from './states';
|
|
36
38
|
|
|
39
|
+
export {
|
|
40
|
+
NOT_A_TIPPED_OCCUPATION,
|
|
41
|
+
TIPPED_OCCUPATIONS,
|
|
42
|
+
getTippedOccupation,
|
|
43
|
+
isTippedOccupationCode,
|
|
44
|
+
toTippedOccupationCode,
|
|
45
|
+
type TippedOccupation,
|
|
46
|
+
} from './tippedOccupations';
|
|
47
|
+
|
|
37
48
|
export {
|
|
38
49
|
getCountiesByState,
|
|
39
50
|
getCountyName,
|
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import { resolveCountyCode } from './counties';
|
|
2
2
|
import { getStateFromZip, isUSStateCode } from './states';
|
|
3
|
+
import { toTippedOccupationCode } from './tippedOccupations';
|
|
3
4
|
import { DEFAULT_HOUSEHOLD_YEAR, createBlankDraft } from './draft';
|
|
4
5
|
import type {
|
|
5
6
|
USHouseholdDraft,
|
|
@@ -68,6 +69,29 @@ interface LegacyPerson {
|
|
|
68
69
|
ssiAmount?: number;
|
|
69
70
|
ssdiAmount?: number;
|
|
70
71
|
social_security_annual?: number;
|
|
72
|
+
pensionIncome?: number;
|
|
73
|
+
pension_income_annual?: number;
|
|
74
|
+
publicPensionIncome?: number;
|
|
75
|
+
public_pension_income_annual?: number;
|
|
76
|
+
privatePensionIncome?: number;
|
|
77
|
+
private_pension_income_annual?: number;
|
|
78
|
+
tipIncome?: number;
|
|
79
|
+
tip_income?: number;
|
|
80
|
+
nonQualifiedDividendIncome?: number;
|
|
81
|
+
non_qualified_dividend_income?: number;
|
|
82
|
+
shortTermCapitalGains?: number;
|
|
83
|
+
short_term_capital_gains?: number;
|
|
84
|
+
longTermCapitalGains?: number;
|
|
85
|
+
long_term_capital_gains?: number;
|
|
86
|
+
charitableCashDonations?: number;
|
|
87
|
+
charitable_cash_donations?: number;
|
|
88
|
+
mortgageInterest?: number;
|
|
89
|
+
home_mortgage_interest?: number;
|
|
90
|
+
mortgage_interest?: number;
|
|
91
|
+
realEstateTaxes?: number;
|
|
92
|
+
real_estate_taxes?: number;
|
|
93
|
+
tippedOccupationCode?: number | string;
|
|
94
|
+
treasury_tipped_occupation_code?: number | string;
|
|
71
95
|
}
|
|
72
96
|
|
|
73
97
|
interface LegacyDraftShape {
|
|
@@ -107,8 +131,13 @@ function coerceNumber(value: unknown): number | undefined {
|
|
|
107
131
|
return Number.isFinite(parsed) ? parsed : undefined;
|
|
108
132
|
}
|
|
109
133
|
|
|
134
|
+
function positiveOrUndefined(value: unknown): number | undefined {
|
|
135
|
+
const parsed = coerceNumber(value);
|
|
136
|
+
return parsed !== undefined && parsed > 0 ? parsed : undefined;
|
|
137
|
+
}
|
|
138
|
+
|
|
110
139
|
function coerceBoolean(value: unknown): boolean | undefined {
|
|
111
|
-
if (value === undefined) {
|
|
140
|
+
if (value === undefined || value === null) {
|
|
112
141
|
return undefined;
|
|
113
142
|
}
|
|
114
143
|
return Boolean(value);
|
|
@@ -121,6 +150,16 @@ function normalizePerson(
|
|
|
121
150
|
): USPersonDraft {
|
|
122
151
|
const id =
|
|
123
152
|
kind === 'adult' ? `adult-${ordinal}` : `dependent-${ordinal}`;
|
|
153
|
+
const tips = coerceNumber(legacy.tipIncome) ?? coerceNumber(legacy.tip_income);
|
|
154
|
+
// Legacy `employment_income` and `earned_income` follow PolicyEngine US,
|
|
155
|
+
// where wages include tips; the draft's `employmentIncome` excludes them,
|
|
156
|
+
// because the V1 adapter adds `tipIncome` back. So tips come out of a
|
|
157
|
+
// legacy wage total, and the payload's `employment_income` equals the
|
|
158
|
+
// legacy figure. A camelCase `employmentIncome` is already the draft's.
|
|
159
|
+
// Tips above the legacy total leave negative wages, which `validate()`
|
|
160
|
+
// flags (`person.employmentIncome.negative`) so the app can ask.
|
|
161
|
+
const legacyWages =
|
|
162
|
+
coerceNumber(legacy.employment_income) ?? coerceNumber(legacy.earned_income);
|
|
124
163
|
return {
|
|
125
164
|
id,
|
|
126
165
|
kind,
|
|
@@ -134,12 +173,48 @@ function normalizePerson(
|
|
|
134
173
|
needsCare: coerceBoolean(legacy.needsCare ?? legacy.is_incapable_of_self_care),
|
|
135
174
|
employmentIncome:
|
|
136
175
|
coerceNumber(legacy.employmentIncome) ??
|
|
137
|
-
|
|
138
|
-
coerceNumber(legacy.earned_income),
|
|
176
|
+
(legacyWages === undefined ? undefined : legacyWages - (tips ?? 0)),
|
|
139
177
|
selfEmploymentIncome: coerceNumber(legacy.self_employment_income_annual),
|
|
140
|
-
|
|
178
|
+
// Legacy snake_case drafts (cliff-watch) default `ssi_amount` to 0 and
|
|
179
|
+
// send SSI only when it is positive, so their 0 means "not entered".
|
|
180
|
+
ssiAmount: coerceNumber(legacy.ssiAmount) ?? positiveOrUndefined(legacy.ssi_amount),
|
|
141
181
|
ssdiAmount: coerceNumber(legacy.ssdiAmount ?? legacy.ssdi_amount),
|
|
182
|
+
// `socialSecurityIncome` excludes SSDI; a legacy total that includes it
|
|
183
|
+
// would count SSDI twice next to `ssdiAmount`.
|
|
142
184
|
socialSecurityIncome: coerceNumber(legacy.social_security_annual),
|
|
185
|
+
// A legacy pension with no source stays in the unknown-source field
|
|
186
|
+
// rather than being guessed as public or private. The three fields are
|
|
187
|
+
// disjoint: a legacy total that already includes the public or private
|
|
188
|
+
// amount would count it twice.
|
|
189
|
+
pensionIncome: coerceNumber(legacy.pensionIncome ?? legacy.pension_income_annual),
|
|
190
|
+
publicPensionIncome: coerceNumber(
|
|
191
|
+
legacy.publicPensionIncome ?? legacy.public_pension_income_annual,
|
|
192
|
+
),
|
|
193
|
+
privatePensionIncome: coerceNumber(
|
|
194
|
+
legacy.privatePensionIncome ?? legacy.private_pension_income_annual,
|
|
195
|
+
),
|
|
196
|
+
tipIncome: tips,
|
|
197
|
+
nonQualifiedDividendIncome: coerceNumber(
|
|
198
|
+
legacy.nonQualifiedDividendIncome ?? legacy.non_qualified_dividend_income,
|
|
199
|
+
),
|
|
200
|
+
shortTermCapitalGains: coerceNumber(
|
|
201
|
+
legacy.shortTermCapitalGains ?? legacy.short_term_capital_gains,
|
|
202
|
+
),
|
|
203
|
+
longTermCapitalGains: coerceNumber(
|
|
204
|
+
legacy.longTermCapitalGains ?? legacy.long_term_capital_gains,
|
|
205
|
+
),
|
|
206
|
+
charitableCashDonations: coerceNumber(
|
|
207
|
+
legacy.charitableCashDonations ?? legacy.charitable_cash_donations,
|
|
208
|
+
),
|
|
209
|
+
// A legacy `mortgage_interest` is the interest the user paid, written to
|
|
210
|
+
// PolicyEngine US's computed total by mistake; it belongs in the input.
|
|
211
|
+
mortgageInterest: coerceNumber(
|
|
212
|
+
legacy.mortgageInterest ?? legacy.home_mortgage_interest ?? legacy.mortgage_interest,
|
|
213
|
+
),
|
|
214
|
+
realEstateTaxes: coerceNumber(legacy.realEstateTaxes ?? legacy.real_estate_taxes),
|
|
215
|
+
tippedOccupationCode: toTippedOccupationCode(
|
|
216
|
+
legacy.tippedOccupationCode ?? legacy.treasury_tipped_occupation_code,
|
|
217
|
+
),
|
|
143
218
|
};
|
|
144
219
|
}
|
|
145
220
|
|
|
@@ -10,6 +10,8 @@ import type { USHouseholdDraft, USPersonDraft } from './types';
|
|
|
10
10
|
* &p=adult:35:e50000,adult:33:e20000,dep:6`
|
|
11
11
|
*
|
|
12
12
|
* Fields are pipe-separated within each person; people are comma-separated.
|
|
13
|
+
* Only the keys below are written: other person fields, such as tips,
|
|
14
|
+
* investment income and expenses, are dropped from links for now.
|
|
13
15
|
* Income/flag keys are single letters to keep the URL short:
|
|
14
16
|
* - `e` = employmentIncome
|
|
15
17
|
* - `s` = ssiAmount
|
|
@@ -42,7 +44,9 @@ function serializePerson(person: USPersonDraft): string {
|
|
|
42
44
|
];
|
|
43
45
|
for (const [key, letter] of INCOME_KEYS) {
|
|
44
46
|
const value = person[key] as number | undefined;
|
|
45
|
-
|
|
47
|
+
// An SSI amount of 0 is an answer ("receives none") that the V1 adapter
|
|
48
|
+
// sends; other zero amounts give the same results as a blank.
|
|
49
|
+
if (value !== undefined && value !== null && (value !== 0 || key === 'ssiAmount')) {
|
|
46
50
|
segments.push(`${letter}${value}`);
|
|
47
51
|
}
|
|
48
52
|
}
|
|
@@ -0,0 +1,145 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Treasury Tipped Occupation Codes (TTOCs): the occupations whose tips can
|
|
3
|
+
* qualify for the federal deduction for qualified tips (26 U.S.C. 224) in tax
|
|
4
|
+
* years 2025 through 2028.
|
|
5
|
+
*
|
|
6
|
+
* Source: Table 1 to paragraph (h) of 26 CFR 1.224-1, "Occupations that
|
|
7
|
+
* Customarily and Regularly Received Tips on or Before December 31, 2024",
|
|
8
|
+
* final regulations T.D. 10044, Internal Revenue Bulletin 2026-18
|
|
9
|
+
* (April 27, 2026), https://www.irs.gov/pub/irs-irbs/irb26-18.pdf. The final
|
|
10
|
+
* table lists 71 occupations; it adds 509, 510 and 810 to the proposed
|
|
11
|
+
* regulations' list (IRB 2025-42) and renames 103, 506 and 606. Labels are the
|
|
12
|
+
* table's occupation titles in sentence case.
|
|
13
|
+
*
|
|
14
|
+
* PolicyEngine US reads the code as `treasury_tipped_occupation_code`, where 0
|
|
15
|
+
* means the person did not receive tips in a listed occupation. Its deduction
|
|
16
|
+
* checks only that the code is above 0, so the code itself does not change
|
|
17
|
+
* results; the list lets apps ask the question the law asks.
|
|
18
|
+
*/
|
|
19
|
+
|
|
20
|
+
export interface TippedOccupation {
|
|
21
|
+
/** Treasury Tipped Occupation Code. */
|
|
22
|
+
code: number;
|
|
23
|
+
/** Occupation title, in sentence case. */
|
|
24
|
+
label: string;
|
|
25
|
+
/** The table's category heading, in sentence case. */
|
|
26
|
+
category: string;
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
/** The code for "no listed occupation", which PolicyEngine US also uses. */
|
|
30
|
+
export const NOT_A_TIPPED_OCCUPATION = 0;
|
|
31
|
+
|
|
32
|
+
const CATEGORIES: Record<number, string> = {
|
|
33
|
+
1: 'Beverage and food service',
|
|
34
|
+
2: 'Entertainment and events',
|
|
35
|
+
3: 'Hospitality and guest services',
|
|
36
|
+
4: 'Home services',
|
|
37
|
+
5: 'Personal services',
|
|
38
|
+
6: 'Personal appearance and wellness',
|
|
39
|
+
7: 'Recreation and instruction',
|
|
40
|
+
8: 'Transportation and delivery',
|
|
41
|
+
};
|
|
42
|
+
|
|
43
|
+
const TITLES: ReadonlyArray<[number, string]> = [
|
|
44
|
+
[101, 'Bartenders'],
|
|
45
|
+
[102, 'Wait staff'],
|
|
46
|
+
[103, 'Food or beverage servers, non-restaurant'],
|
|
47
|
+
[104, 'Dining room and cafeteria attendants and bartender helpers'],
|
|
48
|
+
[105, 'Chefs and cooks'],
|
|
49
|
+
[106, 'Food preparation workers'],
|
|
50
|
+
[107, 'Fast food and counter workers'],
|
|
51
|
+
[108, 'Dishwashers'],
|
|
52
|
+
[109, 'Host staff, restaurant, lounge, and coffee shop'],
|
|
53
|
+
[110, 'Bakers'],
|
|
54
|
+
[201, 'Gambling dealers'],
|
|
55
|
+
[202, 'Gambling change persons and booth cashiers'],
|
|
56
|
+
[203, 'Gambling cage workers'],
|
|
57
|
+
[204, 'Gambling and sports book writers and runners'],
|
|
58
|
+
[205, 'Dancers'],
|
|
59
|
+
[206, 'Musicians and singers'],
|
|
60
|
+
[207, 'Disc jockeys, except radio'],
|
|
61
|
+
[208, 'Entertainers and performers'],
|
|
62
|
+
[209, 'Digital content creators'],
|
|
63
|
+
[210, 'Ushers, lobby attendants, and ticket takers'],
|
|
64
|
+
[211, 'Locker room, coatroom, and dressing room attendants'],
|
|
65
|
+
[301, 'Baggage porters and bellhops'],
|
|
66
|
+
[302, 'Concierges'],
|
|
67
|
+
[303, 'Hotel, motel, and resort desk clerks'],
|
|
68
|
+
[304, 'Maids and housekeeping cleaners'],
|
|
69
|
+
[401, 'Home maintenance and repair workers'],
|
|
70
|
+
[402, 'Home landscaping and groundskeeping workers'],
|
|
71
|
+
[403, 'Home electricians'],
|
|
72
|
+
[404, 'Home plumbers'],
|
|
73
|
+
[405, 'Home heating and air conditioning mechanics and installers'],
|
|
74
|
+
[406, 'Home appliance installers and repairers'],
|
|
75
|
+
[407, 'Home cleaning service workers'],
|
|
76
|
+
[408, 'Locksmiths'],
|
|
77
|
+
[409, 'Roadside assistance workers'],
|
|
78
|
+
[501, 'Personal care and service workers'],
|
|
79
|
+
[502, 'Private event planners'],
|
|
80
|
+
[503, 'Private event and portrait photographers'],
|
|
81
|
+
[504, 'Private event videographers'],
|
|
82
|
+
[505, 'Event officiants'],
|
|
83
|
+
[506, 'Pet and show animal caretakers'],
|
|
84
|
+
[507, 'Tutors'],
|
|
85
|
+
[508, 'Nannies and babysitters'],
|
|
86
|
+
[509, 'Visual artists'],
|
|
87
|
+
[510, 'Floral designers'],
|
|
88
|
+
[601, 'Skincare specialists'],
|
|
89
|
+
[602, 'Massage therapists'],
|
|
90
|
+
[603, 'Barbers, hairdressers, hairstylists, and cosmetologists'],
|
|
91
|
+
[604, 'Shampooers'],
|
|
92
|
+
[605, 'Manicurists and pedicurists'],
|
|
93
|
+
[606, 'Eyebrow and eyelash technicians'],
|
|
94
|
+
[607, 'Makeup artists'],
|
|
95
|
+
[608, 'Exercise trainers and group fitness instructors'],
|
|
96
|
+
[609, 'Tattoo artists and piercers'],
|
|
97
|
+
[610, 'Tailors'],
|
|
98
|
+
[611, 'Shoe and leather workers and repairers'],
|
|
99
|
+
[701, 'Golf caddies'],
|
|
100
|
+
[702, 'Self-enrichment teachers'],
|
|
101
|
+
[703, 'Recreational and tour pilots'],
|
|
102
|
+
[704, 'Tour guides'],
|
|
103
|
+
[705, 'Travel guides'],
|
|
104
|
+
[706, 'Sports and recreation instructors'],
|
|
105
|
+
[801, 'Parking and valet attendants'],
|
|
106
|
+
[802, 'Taxi and rideshare drivers and chauffeurs'],
|
|
107
|
+
[803, 'Shuttle drivers'],
|
|
108
|
+
[804, 'Goods delivery people'],
|
|
109
|
+
[805, 'Personal vehicle and equipment cleaners'],
|
|
110
|
+
[806, 'Private and charter bus drivers'],
|
|
111
|
+
[807, 'Water taxi operators and charter boat workers'],
|
|
112
|
+
[808, 'Rickshaw, pedicab, and carriage drivers'],
|
|
113
|
+
[809, 'Home movers'],
|
|
114
|
+
[810, 'Gas pump attendant'],
|
|
115
|
+
];
|
|
116
|
+
|
|
117
|
+
/** Every listed occupation, in code order. */
|
|
118
|
+
export const TIPPED_OCCUPATIONS: ReadonlyArray<TippedOccupation> = TITLES.map(
|
|
119
|
+
([code, label]) => ({ code, label, category: CATEGORIES[Math.floor(code / 100)] }),
|
|
120
|
+
);
|
|
121
|
+
|
|
122
|
+
const BY_CODE = new Map(TIPPED_OCCUPATIONS.map((occupation) => [occupation.code, occupation]));
|
|
123
|
+
|
|
124
|
+
export function getTippedOccupation(code: number): TippedOccupation | undefined {
|
|
125
|
+
return BY_CODE.get(code);
|
|
126
|
+
}
|
|
127
|
+
|
|
128
|
+
export function isTippedOccupationCode(code: unknown): code is number {
|
|
129
|
+
return typeof code === 'number' && BY_CODE.has(code);
|
|
130
|
+
}
|
|
131
|
+
|
|
132
|
+
/**
|
|
133
|
+
* An entered occupation code as a number the V1 adapter sends: a listed code,
|
|
134
|
+
* or 0 for "not a listed occupation". Strings of decimal digits are read as
|
|
135
|
+
* numbers. Anything else, including codes the table does not list, reads as
|
|
136
|
+
* not answered, so a stray value cannot claim the deduction.
|
|
137
|
+
*/
|
|
138
|
+
export function toTippedOccupationCode(value: unknown): number | undefined {
|
|
139
|
+
const code = typeof value === 'string' && /^\s*\d+\s*$/.test(value) ? Number(value) : value;
|
|
140
|
+
if (code === NOT_A_TIPPED_OCCUPATION) {
|
|
141
|
+
// Also reads -0 as 0.
|
|
142
|
+
return NOT_A_TIPPED_OCCUPATION;
|
|
143
|
+
}
|
|
144
|
+
return isTippedOccupationCode(code) ? code : undefined;
|
|
145
|
+
}
|