policyengine-household-wizard 0.2.0 → 0.4.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 +30 -4
- package/dist/{index-B_OXaS4a.cjs → index-BfoPBFne.cjs} +1 -1
- package/dist/index-CIL8FXNR.cjs +1 -0
- package/dist/{index-DWM0giHt.js → index-DoD0AXHz.js} +72 -70
- package/dist/index-fgLnXugs.js +225 -0
- package/dist/index.cjs +1 -1
- package/dist/index.d.ts +2 -2
- package/dist/index.js +1 -1
- package/dist/primitives/index.d.ts +12 -12
- package/dist/primitives/useWizardSteps.d.ts +1 -1
- package/dist/primitives.d.ts +1 -1
- 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 +1 -1
- package/dist/us-household/adapters/v1Payload.d.ts.map +1 -1
- package/dist/us-household/draft.d.ts +1 -1
- package/dist/us-household/draft.d.ts.map +1 -1
- package/dist/us-household/index.d.ts +9 -9
- 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/types.d.ts +9 -14
- 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 +1 -1
- package/dist/us-household.cjs +1 -1
- package/dist/us-household.d.ts +1 -1
- package/dist/us-household.js +213 -200
- package/dist/validation.d.ts +16 -0
- package/dist/validation.d.ts.map +1 -0
- package/package.json +13 -2
- 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 +4 -0
- package/src/us-household/draft.ts +1 -0
- package/src/us-household/normalize.ts +3 -0
- package/src/us-household/serialize.ts +6 -0
- package/src/us-household/types.ts +9 -11
- package/src/us-household/validate.ts +15 -0
- package/src/validation.ts +12 -0
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
/** One problem `validate()` found in a draft. Shared by the country models. */
|
|
2
|
+
export interface ValidationIssue {
|
|
3
|
+
/** Stable identifier for the rule (e.g. "state.required"). */
|
|
4
|
+
code: string;
|
|
5
|
+
/** Path into the draft (dotted), e.g. "state" or "people[1].age". */
|
|
6
|
+
path: string;
|
|
7
|
+
message: string;
|
|
8
|
+
}
|
|
9
|
+
export type ValidationResult = {
|
|
10
|
+
ok: true;
|
|
11
|
+
issues: never[];
|
|
12
|
+
} | {
|
|
13
|
+
ok: false;
|
|
14
|
+
issues: ValidationIssue[];
|
|
15
|
+
};
|
|
16
|
+
//# sourceMappingURL=validation.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,MAAM,WAAW,eAAe;IAC9B,8DAA8D;IAC9D,IAAI,EAAE,MAAM,CAAC;IACb,qEAAqE;IACrE,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,gBAAgB,GACxB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,KAAK,EAAE,CAAA;CAAE,GAC7B;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,eAAe,EAAE,CAAA;CAAE,CAAC"}
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "policyengine-household-wizard",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"description": "Shared wizard primitives and US household draft
|
|
3
|
+
"version": "0.4.0",
|
|
4
|
+
"description": "Shared wizard primitives and US and UK household draft contracts for PolicyEngine apps.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "dist/index.cjs",
|
|
7
7
|
"module": "dist/index.js",
|
|
@@ -27,6 +27,16 @@
|
|
|
27
27
|
"import": "./dist/us-household-adapters.js",
|
|
28
28
|
"require": "./dist/us-household-adapters.cjs"
|
|
29
29
|
},
|
|
30
|
+
"./uk-household": {
|
|
31
|
+
"types": "./dist/uk-household/index.d.ts",
|
|
32
|
+
"import": "./dist/uk-household.js",
|
|
33
|
+
"require": "./dist/uk-household.cjs"
|
|
34
|
+
},
|
|
35
|
+
"./uk-household/adapters": {
|
|
36
|
+
"types": "./dist/uk-household/adapters/index.d.ts",
|
|
37
|
+
"import": "./dist/uk-household-adapters.js",
|
|
38
|
+
"require": "./dist/uk-household-adapters.cjs"
|
|
39
|
+
},
|
|
30
40
|
"./styles.css": "./src/styles.css"
|
|
31
41
|
},
|
|
32
42
|
"files": [
|
|
@@ -35,6 +45,7 @@
|
|
|
35
45
|
],
|
|
36
46
|
"scripts": {
|
|
37
47
|
"build": "vite build && tsc -p tsconfig.build.json --emitDeclarationOnly && tsx scripts/emit-subpath-types.ts",
|
|
48
|
+
"check:consumer-types": "tsx scripts/check-consumer-types.ts",
|
|
38
49
|
"test": "vitest run",
|
|
39
50
|
"test:live": "POLICYENGINE_LIVE_API=1 vitest run tests/us-household/v1Payload.live.test.ts",
|
|
40
51
|
"test:watch": "vitest",
|
|
@@ -0,0 +1,164 @@
|
|
|
1
|
+
import { asksEducation } from '../children';
|
|
2
|
+
import { isRenting } from '../codes';
|
|
3
|
+
import { UK_DEFAULT_SPENDING, regionalRent } from '../defaults';
|
|
4
|
+
import {
|
|
5
|
+
atStatePensionAge,
|
|
6
|
+
statePensionEntered,
|
|
7
|
+
type UKStatePensionTable,
|
|
8
|
+
} from '../statePension';
|
|
9
|
+
import { UK_HOUSEHOLD_LIMITS } from '../validate';
|
|
10
|
+
import type { UKHouseholdDraft } from '../types';
|
|
11
|
+
|
|
12
|
+
/**
|
|
13
|
+
* The request body of the Autumn Budget 2026 dashboard's household impact
|
|
14
|
+
* API (`POST /api/household-impact`, `HouseholdImpactRequest` in
|
|
15
|
+
* PolicyEngine/uk-autumn-budget-dashboard-2026's src/uk_budget_data/api.py).
|
|
16
|
+
* The API refuses unknown fields with a 422, and reads the `partner_*`
|
|
17
|
+
* fields only when `has_partner` is true.
|
|
18
|
+
*/
|
|
19
|
+
export interface HouseholdImpactChild {
|
|
20
|
+
age: number;
|
|
21
|
+
/** Sent from 16 to 19 only. */
|
|
22
|
+
in_education?: boolean;
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
export interface HouseholdImpactHousehold {
|
|
26
|
+
age: number;
|
|
27
|
+
employment_income: number;
|
|
28
|
+
has_partner: boolean;
|
|
29
|
+
/** Left out without a partner when the draft's is not an age the API takes. */
|
|
30
|
+
partner_age?: number;
|
|
31
|
+
partner_employment_income: number;
|
|
32
|
+
children: HouseholdImpactChild[];
|
|
33
|
+
region: string;
|
|
34
|
+
claims_universal_credit: boolean;
|
|
35
|
+
tenure: string;
|
|
36
|
+
monthly_rent: number;
|
|
37
|
+
dividend_income: number;
|
|
38
|
+
savings_interest_income: number;
|
|
39
|
+
private_pension_income: number;
|
|
40
|
+
partner_private_pension_income: number;
|
|
41
|
+
property_income: number;
|
|
42
|
+
petrol_spending: number;
|
|
43
|
+
diesel_spending: number;
|
|
44
|
+
electricity_spending: number;
|
|
45
|
+
salary_sacrifice_pension_contributions: number;
|
|
46
|
+
student_loan_plan: string;
|
|
47
|
+
council_tax_band: string;
|
|
48
|
+
monthly_childcare: number;
|
|
49
|
+
salary_year: number;
|
|
50
|
+
state_pension?: number;
|
|
51
|
+
partner_state_pension?: number;
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
/** The slower parts of a calculation, asked for apart from the headline. */
|
|
55
|
+
export type HouseholdImpactPart = 'by_policy' | 'sweep';
|
|
56
|
+
|
|
57
|
+
export interface HouseholdImpactRequest {
|
|
58
|
+
year: number;
|
|
59
|
+
policies: string[];
|
|
60
|
+
household: HouseholdImpactHousehold;
|
|
61
|
+
include: HouseholdImpactPart[];
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
export interface ToHouseholdImpactRequestOptions {
|
|
65
|
+
/** The policy year (2027 is 2027-28). */
|
|
66
|
+
year: number;
|
|
67
|
+
/**
|
|
68
|
+
* The measures to compare the household under, sent as given: at least
|
|
69
|
+
* one, each an id the API knows (it refuses an empty list and an unknown
|
|
70
|
+
* id).
|
|
71
|
+
*/
|
|
72
|
+
policies: readonly string[];
|
|
73
|
+
/** The slower parts to compute besides the headline; none by default. */
|
|
74
|
+
include?: readonly HouseholdImpactPart[];
|
|
75
|
+
/** State Pension ages by year; left out, `UK_STATE_PENSION`. */
|
|
76
|
+
statePension?: UKStatePensionTable;
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
const { adultAge } = UK_HOUSEHOLD_LIMITS;
|
|
80
|
+
|
|
81
|
+
/** An age the API's `partner_age` field takes: a whole number from 16 to 100. */
|
|
82
|
+
const isAcceptedAge = (age: unknown) =>
|
|
83
|
+
typeof age === 'number' && Number.isInteger(age) && age >= adultAge.min && age <= adultAge.max;
|
|
84
|
+
|
|
85
|
+
/**
|
|
86
|
+
* The household impact API's request for a draft.
|
|
87
|
+
*
|
|
88
|
+
* Answers go as they are, so `validate()` first: the API refuses what it
|
|
89
|
+
* flags. The rules the request applies:
|
|
90
|
+
* - the partner's salary and pension are sent only with a partner, as 0
|
|
91
|
+
* otherwise. The partner's age is sent even without one, as the dashboard
|
|
92
|
+
* always has (the API reads it only with a partner); without a partner, an
|
|
93
|
+
* age the API would refuse (unanswered, or not a whole number from 16 to
|
|
94
|
+
* 100) is left out, so it cannot fail a single person's request;
|
|
95
|
+
* - children from 16 to 19 carry whether they are in full-time non-advanced
|
|
96
|
+
* education, yes unless answered `false`;
|
|
97
|
+
* - rent only when renting, as entered or else the region's average private
|
|
98
|
+
* rent; 0 otherwise;
|
|
99
|
+
* - childcare only with children; 0 otherwise;
|
|
100
|
+
* - a private pension left out is 0, and electricity left out is the
|
|
101
|
+
* average household's (`UK_DEFAULT_SPENDING.electricity`);
|
|
102
|
+
* - a State Pension only as entered and at State Pension age in `year`;
|
|
103
|
+
* left as prefilled (`null`), the API uses the full new State Pension.
|
|
104
|
+
*
|
|
105
|
+
* The keys come in a fixed order, so `JSON.stringify` of two requests for
|
|
106
|
+
* the same answers gives the same text (apps key caches on it).
|
|
107
|
+
*/
|
|
108
|
+
export function toHouseholdImpactRequest(
|
|
109
|
+
draft: UKHouseholdDraft,
|
|
110
|
+
{ year, policies, include = [], statePension }: ToHouseholdImpactRequestOptions,
|
|
111
|
+
): HouseholdImpactRequest {
|
|
112
|
+
const { head, partner, hasPartner } = draft;
|
|
113
|
+
const children = draft.children.map((child) =>
|
|
114
|
+
asksEducation(child.age)
|
|
115
|
+
? { age: child.age as number, in_education: child.inEducation !== false }
|
|
116
|
+
: { age: child.age as number },
|
|
117
|
+
);
|
|
118
|
+
const renting = isRenting(draft.tenure);
|
|
119
|
+
return {
|
|
120
|
+
year,
|
|
121
|
+
policies: [...policies],
|
|
122
|
+
household: {
|
|
123
|
+
age: head.age as number,
|
|
124
|
+
employment_income: head.employmentIncome,
|
|
125
|
+
has_partner: Boolean(hasPartner),
|
|
126
|
+
...(hasPartner || isAcceptedAge(partner.age) ? { partner_age: partner.age as number } : {}),
|
|
127
|
+
partner_employment_income: hasPartner ? partner.employmentIncome : 0,
|
|
128
|
+
children,
|
|
129
|
+
region: draft.region as string,
|
|
130
|
+
claims_universal_credit: Boolean(draft.claimsUniversalCredit),
|
|
131
|
+
tenure: draft.tenure as string,
|
|
132
|
+
monthly_rent: renting ? monthlyRentFor(draft) : 0,
|
|
133
|
+
dividend_income: head.dividendIncome,
|
|
134
|
+
savings_interest_income: head.savingsInterestIncome,
|
|
135
|
+
private_pension_income: head.privatePensionIncome ?? 0,
|
|
136
|
+
partner_private_pension_income: hasPartner ? (partner.privatePensionIncome ?? 0) : 0,
|
|
137
|
+
property_income: head.propertyIncome,
|
|
138
|
+
petrol_spending: draft.spending.petrol,
|
|
139
|
+
diesel_spending: draft.spending.diesel,
|
|
140
|
+
electricity_spending: draft.spending.electricity ?? UK_DEFAULT_SPENDING.electricity,
|
|
141
|
+
salary_sacrifice_pension_contributions: head.salarySacrificePensionContributions,
|
|
142
|
+
student_loan_plan: head.studentLoanPlan,
|
|
143
|
+
council_tax_band: draft.councilTaxBand as string,
|
|
144
|
+
monthly_childcare: children.length ? draft.monthlyChildcare : 0,
|
|
145
|
+
salary_year: draft.salaryYear,
|
|
146
|
+
...(statePensionEntered(head.statePension) && atStatePensionAge(head.age, year, statePension)
|
|
147
|
+
? { state_pension: head.statePension }
|
|
148
|
+
: {}),
|
|
149
|
+
...(hasPartner &&
|
|
150
|
+
statePensionEntered(partner.statePension) &&
|
|
151
|
+
atStatePensionAge(partner.age, year, statePension)
|
|
152
|
+
? { partner_state_pension: partner.statePension }
|
|
153
|
+
: {}),
|
|
154
|
+
},
|
|
155
|
+
include: [...include],
|
|
156
|
+
};
|
|
157
|
+
}
|
|
158
|
+
|
|
159
|
+
/** The rent a month: as entered, else the region's average private rent. */
|
|
160
|
+
export function monthlyRentFor(draft: Pick<UKHouseholdDraft, 'monthlyRent' | 'region'>): number {
|
|
161
|
+
return typeof draft.monthlyRent === 'number' && Number.isFinite(draft.monthlyRent)
|
|
162
|
+
? draft.monthlyRent
|
|
163
|
+
: regionalRent(draft.region);
|
|
164
|
+
}
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The oldest age a child can have. policyengine-uk's qualifying young person
|
|
3
|
+
* is under 20, and the household impact API refuses a child of 20 or over
|
|
4
|
+
* (`HouseholdChildRequest.age`, `le=19`).
|
|
5
|
+
*/
|
|
6
|
+
export const UK_OLDEST_CHILD_AGE = 19;
|
|
7
|
+
|
|
8
|
+
/**
|
|
9
|
+
* From this age, whether a child is in full-time non-advanced education
|
|
10
|
+
* decides whether they count as a dependant.
|
|
11
|
+
*/
|
|
12
|
+
export const UK_YOUNG_PERSON_AGE = 16;
|
|
13
|
+
|
|
14
|
+
/** What to tell someone who enters a child of 20 or over. */
|
|
15
|
+
export const UK_CHILD_AGE_MESSAGE =
|
|
16
|
+
'Children are 0 to 19. Someone aged 20 or over is not a dependant for Child Benefit or Universal Credit, so leave them out.';
|
|
17
|
+
|
|
18
|
+
/** Whether a child of `age` is asked about education: from 16 to 19. */
|
|
19
|
+
export const asksEducation = (age: number | null | undefined): boolean =>
|
|
20
|
+
(age as number) >= UK_YOUNG_PERSON_AGE && (age as number) <= UK_OLDEST_CHILD_AGE;
|
|
21
|
+
|
|
22
|
+
/** The age a new child starts at in a form that adds one (`setChildCount`). */
|
|
23
|
+
export const UK_NEW_CHILD_AGE = 5;
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
import type { UKCouncilTaxBand, UKRegion, UKStudentLoanPlan, UKTenure } from './types';
|
|
2
|
+
|
|
3
|
+
export interface UKRegionOption {
|
|
4
|
+
code: UKRegion;
|
|
5
|
+
/** policyengine-uk's own label for the region. */
|
|
6
|
+
name: string;
|
|
7
|
+
}
|
|
8
|
+
|
|
9
|
+
/** The regions, in policyengine-uk's order, with its labels. */
|
|
10
|
+
export const UK_REGIONS: readonly UKRegionOption[] = [
|
|
11
|
+
{ code: 'NORTH_EAST', name: 'North East' },
|
|
12
|
+
{ code: 'NORTH_WEST', name: 'North West' },
|
|
13
|
+
{ code: 'YORKSHIRE', name: 'Yorkshire and the Humber' },
|
|
14
|
+
{ code: 'EAST_MIDLANDS', name: 'East Midlands' },
|
|
15
|
+
{ code: 'WEST_MIDLANDS', name: 'West Midlands' },
|
|
16
|
+
{ code: 'EAST_OF_ENGLAND', name: 'East of England' },
|
|
17
|
+
{ code: 'LONDON', name: 'London' },
|
|
18
|
+
{ code: 'SOUTH_EAST', name: 'South East' },
|
|
19
|
+
{ code: 'SOUTH_WEST', name: 'South West' },
|
|
20
|
+
{ code: 'WALES', name: 'Wales' },
|
|
21
|
+
{ code: 'SCOTLAND', name: 'Scotland' },
|
|
22
|
+
{ code: 'NORTHERN_IRELAND', name: 'Northern Ireland' },
|
|
23
|
+
];
|
|
24
|
+
|
|
25
|
+
export const UK_TENURES: readonly UKTenure[] = [
|
|
26
|
+
'RENT_PRIVATELY',
|
|
27
|
+
'RENT_FROM_COUNCIL',
|
|
28
|
+
'RENT_FROM_HA',
|
|
29
|
+
'OWNED_WITH_MORTGAGE',
|
|
30
|
+
'OWNED_OUTRIGHT',
|
|
31
|
+
];
|
|
32
|
+
|
|
33
|
+
/** The tenures that pay rent: rent is read only for these. */
|
|
34
|
+
export const UK_RENTING_TENURES: readonly UKTenure[] = ['RENT_PRIVATELY', 'RENT_FROM_COUNCIL', 'RENT_FROM_HA'];
|
|
35
|
+
|
|
36
|
+
export const UK_STUDENT_LOAN_PLANS: readonly UKStudentLoanPlan[] = [
|
|
37
|
+
'NONE',
|
|
38
|
+
'PLAN_1',
|
|
39
|
+
'PLAN_2',
|
|
40
|
+
'PLAN_4',
|
|
41
|
+
'PLAN_5',
|
|
42
|
+
'POSTGRADUATE',
|
|
43
|
+
];
|
|
44
|
+
|
|
45
|
+
export const UK_COUNCIL_TAX_BANDS: readonly UKCouncilTaxBand[] = ['A', 'B', 'C', 'D', 'E', 'F', 'G', 'H', 'I'];
|
|
46
|
+
|
|
47
|
+
const has = <T extends string>(list: readonly T[], value: unknown): value is T =>
|
|
48
|
+
typeof value === 'string' && (list as readonly string[]).includes(value);
|
|
49
|
+
|
|
50
|
+
export const isUKRegion = (value: unknown): value is UKRegion =>
|
|
51
|
+
has(
|
|
52
|
+
UK_REGIONS.map((region) => region.code),
|
|
53
|
+
value,
|
|
54
|
+
);
|
|
55
|
+
export const isUKTenure = (value: unknown): value is UKTenure => has(UK_TENURES, value);
|
|
56
|
+
export const isUKStudentLoanPlan = (value: unknown): value is UKStudentLoanPlan =>
|
|
57
|
+
has(UK_STUDENT_LOAN_PLANS, value);
|
|
58
|
+
export const isUKCouncilTaxBand = (value: unknown): value is UKCouncilTaxBand =>
|
|
59
|
+
has(UK_COUNCIL_TAX_BANDS, value);
|
|
60
|
+
|
|
61
|
+
/** Whether a tenure pays rent. Anything else, unknown codes included, does not. */
|
|
62
|
+
export const isRenting = (tenure: unknown): boolean => has(UK_RENTING_TENURES, tenure);
|
|
63
|
+
|
|
64
|
+
/** policyengine-uk's label for a region, or the code itself if unknown. */
|
|
65
|
+
export function getRegionName(code: string): string {
|
|
66
|
+
return UK_REGIONS.find((region) => region.code === code)?.name ?? code;
|
|
67
|
+
}
|
|
@@ -0,0 +1,101 @@
|
|
|
1
|
+
import type { UKRegion } from './types';
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* Typical answers, with their sources, for apps that start every answer at a
|
|
5
|
+
* typical value (the Autumn Budget 2026 dashboard does). `createTypicalDraft()`
|
|
6
|
+
* puts them together.
|
|
7
|
+
*/
|
|
8
|
+
|
|
9
|
+
export interface UKDefaultSource {
|
|
10
|
+
/** What the figure is. */
|
|
11
|
+
statistic: string;
|
|
12
|
+
/** The publication and table it comes from. */
|
|
13
|
+
publication: string;
|
|
14
|
+
url: string;
|
|
15
|
+
}
|
|
16
|
+
|
|
17
|
+
/**
|
|
18
|
+
* The year salaries are entered for. The latest median salary (below) is for
|
|
19
|
+
* April 2026, so a form that asks for "salary in 2026" can start from it.
|
|
20
|
+
*/
|
|
21
|
+
export const UK_SALARY_YEAR = 2026;
|
|
22
|
+
|
|
23
|
+
/**
|
|
24
|
+
* The UK median salary, rounded: ONS, Annual Survey of Hours and Earnings
|
|
25
|
+
* (ASHE) 2026 provisional, Table 6.7a "Annual pay - Gross", all employee jobs,
|
|
26
|
+
* UK: median £34,229 in April 2026 (employees on adult rates in the same job
|
|
27
|
+
* for more than a year), rounded to £34,200.
|
|
28
|
+
*/
|
|
29
|
+
export const UK_DEFAULT_SALARY = 34200;
|
|
30
|
+
|
|
31
|
+
/** A sentence for forms that prefill the salary (the dashboard's hint). */
|
|
32
|
+
export const UK_DEFAULT_SALARY_NOTE =
|
|
33
|
+
'£34,200 is the UK median salary in April 2026 (ONS Annual Survey of Hours and Earnings, provisional).';
|
|
34
|
+
|
|
35
|
+
/**
|
|
36
|
+
* Average monthly private rent by region: ONS, Price Index of Private Rents
|
|
37
|
+
* (PIPR), September 2026 (Northern Ireland: July 2026, its latest month),
|
|
38
|
+
* published 21 October 2026.
|
|
39
|
+
*/
|
|
40
|
+
export const UK_REGIONAL_RENT: Readonly<Record<UKRegion, number>> = {
|
|
41
|
+
NORTH_EAST: 790,
|
|
42
|
+
NORTH_WEST: 975,
|
|
43
|
+
YORKSHIRE: 869,
|
|
44
|
+
EAST_MIDLANDS: 928,
|
|
45
|
+
WEST_MIDLANDS: 983,
|
|
46
|
+
EAST_OF_ENGLAND: 1298,
|
|
47
|
+
LONDON: 2338,
|
|
48
|
+
SOUTH_EAST: 1438,
|
|
49
|
+
SOUTH_WEST: 1251,
|
|
50
|
+
WALES: 848,
|
|
51
|
+
SCOTLAND: 1011,
|
|
52
|
+
NORTHERN_IRELAND: 879,
|
|
53
|
+
};
|
|
54
|
+
|
|
55
|
+
/** The UK's average monthly private rent in the same release. */
|
|
56
|
+
export const UK_AVERAGE_RENT = 1406;
|
|
57
|
+
|
|
58
|
+
/** The month each region's average rent is for. */
|
|
59
|
+
export const regionalRentMonth = (region: unknown): string =>
|
|
60
|
+
region === 'NORTHERN_IRELAND' ? 'July 2026' : 'September 2026';
|
|
61
|
+
|
|
62
|
+
/**
|
|
63
|
+
* The region's average monthly private rent, or the UK's for anything that
|
|
64
|
+
* is not a region code (`null` included).
|
|
65
|
+
*/
|
|
66
|
+
export function regionalRent(region: unknown): number {
|
|
67
|
+
return typeof region === 'string' && Object.prototype.hasOwnProperty.call(UK_REGIONAL_RENT, region)
|
|
68
|
+
? UK_REGIONAL_RENT[region as UKRegion]
|
|
69
|
+
: UK_AVERAGE_RENT;
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
/**
|
|
73
|
+
* Average household spending, pounds a year: ONS, Family Spending in the UK,
|
|
74
|
+
* FYE 2025, Workbook 1, Table A1, average weekly household spending times 52,
|
|
75
|
+
* rounded to £10. Petrol £11.90 a week (£620 a year), diesel £6.50 (£340),
|
|
76
|
+
* electricity (line 4.4.1) £20.00 (£1,040, the household impact API's own
|
|
77
|
+
* default for electricity).
|
|
78
|
+
*/
|
|
79
|
+
export const UK_DEFAULT_SPENDING = {
|
|
80
|
+
petrol: 620,
|
|
81
|
+
diesel: 340,
|
|
82
|
+
electricity: 1040,
|
|
83
|
+
} as const;
|
|
84
|
+
|
|
85
|
+
export const UK_DEFAULT_SOURCES: Readonly<Record<'salary' | 'rent' | 'spending', UKDefaultSource>> = {
|
|
86
|
+
salary: {
|
|
87
|
+
statistic: 'Median gross annual pay, all employee jobs, UK, April 2026 (provisional): £34,229',
|
|
88
|
+
publication: 'ONS, Annual Survey of Hours and Earnings 2026, Table 6.7a',
|
|
89
|
+
url: 'https://www.ons.gov.uk/employmentandlabourmarket/peopleinwork/earningsandworkinghours/datasets/agegroupashetable6',
|
|
90
|
+
},
|
|
91
|
+
rent: {
|
|
92
|
+
statistic: 'Average monthly private rent by region, September 2026 (Northern Ireland: July 2026)',
|
|
93
|
+
publication: 'ONS, Price Index of Private Rents, published 21 October 2026',
|
|
94
|
+
url: 'https://www.ons.gov.uk/economy/inflationandpriceindices/datasets/priceindexofprivaterentsukmonthlypricestatistics',
|
|
95
|
+
},
|
|
96
|
+
spending: {
|
|
97
|
+
statistic: 'Average weekly household spending on petrol, diesel and electricity, FYE 2025',
|
|
98
|
+
publication: 'ONS, Family Spending in the UK, FYE 2025, Workbook 1, Table A1',
|
|
99
|
+
url: 'https://www.ons.gov.uk/peoplepopulationandcommunity/personalandhouseholdfinances/expenditure/datasets/familyspendingworkbook1detailedexpenditureandtrends',
|
|
100
|
+
},
|
|
101
|
+
};
|
|
@@ -0,0 +1,138 @@
|
|
|
1
|
+
import { UK_NEW_CHILD_AGE } from './children';
|
|
2
|
+
import { UK_DEFAULT_SALARY, UK_DEFAULT_SPENDING, UK_SALARY_YEAR } from './defaults';
|
|
3
|
+
import type { UKAdultDraft, UKChildDraft, UKHeadDraft, UKHouseholdDraft } from './types';
|
|
4
|
+
|
|
5
|
+
/**
|
|
6
|
+
* A draft with nothing chosen: no region, ages, tenure, Council Tax band or
|
|
7
|
+
* Universal Credit answer, no partner or children, and amounts at zero. The
|
|
8
|
+
* app must capture each unanswered field before `validate()` accepts it.
|
|
9
|
+
* Rent, the State Pension and electricity start at their "left as prefilled"
|
|
10
|
+
* value (`null`).
|
|
11
|
+
*/
|
|
12
|
+
export function createBlankDraft(salaryYear: number = UK_SALARY_YEAR): UKHouseholdDraft {
|
|
13
|
+
return {
|
|
14
|
+
salaryYear,
|
|
15
|
+
region: null,
|
|
16
|
+
head: {
|
|
17
|
+
age: null,
|
|
18
|
+
employmentIncome: 0,
|
|
19
|
+
privatePensionIncome: 0,
|
|
20
|
+
statePension: null,
|
|
21
|
+
studentLoanPlan: 'NONE',
|
|
22
|
+
salarySacrificePensionContributions: 0,
|
|
23
|
+
dividendIncome: 0,
|
|
24
|
+
savingsInterestIncome: 0,
|
|
25
|
+
propertyIncome: 0,
|
|
26
|
+
},
|
|
27
|
+
hasPartner: false,
|
|
28
|
+
partner: { age: null, employmentIncome: 0, privatePensionIncome: 0, statePension: null },
|
|
29
|
+
children: [],
|
|
30
|
+
tenure: null,
|
|
31
|
+
monthlyRent: null,
|
|
32
|
+
councilTaxBand: null,
|
|
33
|
+
claimsUniversalCredit: null,
|
|
34
|
+
monthlyChildcare: 0,
|
|
35
|
+
spending: { petrol: 0, diesel: 0, electricity: null },
|
|
36
|
+
};
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
/**
|
|
40
|
+
* A draft with every answer at a typical value: the Autumn Budget 2026
|
|
41
|
+
* dashboard's starting answers. The salary, rent and spending are statistics
|
|
42
|
+
* (`UK_DEFAULT_SOURCES`); the rest are the dashboard's choices:
|
|
43
|
+
* - a single adult of 30 (and, if a partner is added, a partner of 30 on the
|
|
44
|
+
* median salary) in the North West, renting privately at the region's
|
|
45
|
+
* average rent (`monthlyRent: null`);
|
|
46
|
+
* - no student loan: policyengine-uk's repayment depends on the plan and
|
|
47
|
+
* income alone (the balance only caps a year's repayment);
|
|
48
|
+
* - Council Tax band D, the band the dashboard suggests when unsure;
|
|
49
|
+
* - claiming the Universal Credit the household is due;
|
|
50
|
+
* - the full new State Pension at State Pension age (`statePension: null`);
|
|
51
|
+
* - no other income, salary sacrifice, pensions or childcare.
|
|
52
|
+
*/
|
|
53
|
+
export function createTypicalDraft(salaryYear: number = UK_SALARY_YEAR): UKHouseholdDraft {
|
|
54
|
+
return {
|
|
55
|
+
salaryYear,
|
|
56
|
+
region: 'NORTH_WEST',
|
|
57
|
+
head: {
|
|
58
|
+
age: 30,
|
|
59
|
+
employmentIncome: UK_DEFAULT_SALARY,
|
|
60
|
+
privatePensionIncome: 0,
|
|
61
|
+
statePension: null,
|
|
62
|
+
studentLoanPlan: 'NONE',
|
|
63
|
+
salarySacrificePensionContributions: 0,
|
|
64
|
+
dividendIncome: 0,
|
|
65
|
+
savingsInterestIncome: 0,
|
|
66
|
+
propertyIncome: 0,
|
|
67
|
+
},
|
|
68
|
+
hasPartner: false,
|
|
69
|
+
partner: { age: 30, employmentIncome: UK_DEFAULT_SALARY, privatePensionIncome: 0, statePension: null },
|
|
70
|
+
children: [],
|
|
71
|
+
tenure: 'RENT_PRIVATELY',
|
|
72
|
+
monthlyRent: null,
|
|
73
|
+
councilTaxBand: 'D',
|
|
74
|
+
claimsUniversalCredit: true,
|
|
75
|
+
monthlyChildcare: 0,
|
|
76
|
+
spending: {
|
|
77
|
+
petrol: UK_DEFAULT_SPENDING.petrol,
|
|
78
|
+
diesel: UK_DEFAULT_SPENDING.diesel,
|
|
79
|
+
electricity: UK_DEFAULT_SPENDING.electricity,
|
|
80
|
+
},
|
|
81
|
+
};
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
const cloneExtras = (extras: Record<string, unknown> | undefined) =>
|
|
85
|
+
extras ? { extras: structuredClone(extras) } : {};
|
|
86
|
+
|
|
87
|
+
/** A deep copy: changing it never changes the original. */
|
|
88
|
+
export function cloneDraft(draft: UKHouseholdDraft): UKHouseholdDraft {
|
|
89
|
+
return {
|
|
90
|
+
...draft,
|
|
91
|
+
head: { ...draft.head, ...cloneExtras(draft.head.extras) },
|
|
92
|
+
partner: { ...draft.partner, ...cloneExtras(draft.partner.extras) },
|
|
93
|
+
children: draft.children.map((child) => ({ ...child, ...cloneExtras(child.extras) })),
|
|
94
|
+
spending: { ...draft.spending },
|
|
95
|
+
...cloneExtras(draft.extras),
|
|
96
|
+
};
|
|
97
|
+
}
|
|
98
|
+
|
|
99
|
+
export function updateHead(draft: UKHouseholdDraft, changes: Partial<UKHeadDraft>): UKHouseholdDraft {
|
|
100
|
+
return { ...draft, head: { ...draft.head, ...changes } };
|
|
101
|
+
}
|
|
102
|
+
|
|
103
|
+
export function updatePartner(draft: UKHouseholdDraft, changes: Partial<UKAdultDraft>): UKHouseholdDraft {
|
|
104
|
+
return { ...draft, partner: { ...draft.partner, ...changes } };
|
|
105
|
+
}
|
|
106
|
+
|
|
107
|
+
export function addChild(draft: UKHouseholdDraft, child: Partial<UKChildDraft> = {}): UKHouseholdDraft {
|
|
108
|
+
return { ...draft, children: [...draft.children, { age: null, ...child }] };
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
export function removeChild(draft: UKHouseholdDraft, index: number): UKHouseholdDraft {
|
|
112
|
+
return { ...draft, children: draft.children.filter((_, i) => i !== index) };
|
|
113
|
+
}
|
|
114
|
+
|
|
115
|
+
export function updateChild(
|
|
116
|
+
draft: UKHouseholdDraft,
|
|
117
|
+
index: number,
|
|
118
|
+
changes: Partial<UKChildDraft>,
|
|
119
|
+
): UKHouseholdDraft {
|
|
120
|
+
return {
|
|
121
|
+
...draft,
|
|
122
|
+
children: draft.children.map((child, i) => (i === index ? { ...child, ...changes } : child)),
|
|
123
|
+
};
|
|
124
|
+
}
|
|
125
|
+
|
|
126
|
+
/**
|
|
127
|
+
* Keep the first `count` children, or add children of `newChildAge` until
|
|
128
|
+
* there are `count`. A form with a "number of children" question uses this.
|
|
129
|
+
*/
|
|
130
|
+
export function setChildCount(
|
|
131
|
+
draft: UKHouseholdDraft,
|
|
132
|
+
count: number,
|
|
133
|
+
newChildAge: number = UK_NEW_CHILD_AGE,
|
|
134
|
+
): UKHouseholdDraft {
|
|
135
|
+
const children = draft.children.slice(0, Math.max(0, count));
|
|
136
|
+
while (children.length < count) children.push({ age: newChildAge });
|
|
137
|
+
return { ...draft, children };
|
|
138
|
+
}
|
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
export type {
|
|
2
|
+
UKAdultDraft,
|
|
3
|
+
UKChildDraft,
|
|
4
|
+
UKCouncilTaxBand,
|
|
5
|
+
UKHeadDraft,
|
|
6
|
+
UKHouseholdDraft,
|
|
7
|
+
UKHouseholdSpending,
|
|
8
|
+
UKRegion,
|
|
9
|
+
UKStudentLoanPlan,
|
|
10
|
+
UKTenure,
|
|
11
|
+
ValidationIssue,
|
|
12
|
+
ValidationResult,
|
|
13
|
+
} from './types';
|
|
14
|
+
|
|
15
|
+
export {
|
|
16
|
+
UK_COUNCIL_TAX_BANDS,
|
|
17
|
+
UK_REGIONS,
|
|
18
|
+
UK_RENTING_TENURES,
|
|
19
|
+
UK_STUDENT_LOAN_PLANS,
|
|
20
|
+
UK_TENURES,
|
|
21
|
+
getRegionName,
|
|
22
|
+
isRenting,
|
|
23
|
+
isUKCouncilTaxBand,
|
|
24
|
+
isUKRegion,
|
|
25
|
+
isUKStudentLoanPlan,
|
|
26
|
+
isUKTenure,
|
|
27
|
+
type UKRegionOption,
|
|
28
|
+
} from './codes';
|
|
29
|
+
|
|
30
|
+
export {
|
|
31
|
+
UK_AVERAGE_RENT,
|
|
32
|
+
UK_DEFAULT_SALARY,
|
|
33
|
+
UK_DEFAULT_SALARY_NOTE,
|
|
34
|
+
UK_DEFAULT_SOURCES,
|
|
35
|
+
UK_DEFAULT_SPENDING,
|
|
36
|
+
UK_REGIONAL_RENT,
|
|
37
|
+
UK_SALARY_YEAR,
|
|
38
|
+
regionalRent,
|
|
39
|
+
regionalRentMonth,
|
|
40
|
+
type UKDefaultSource,
|
|
41
|
+
} from './defaults';
|
|
42
|
+
|
|
43
|
+
export {
|
|
44
|
+
UK_STATE_PENSION,
|
|
45
|
+
atStatePensionAge,
|
|
46
|
+
statePensionEntered,
|
|
47
|
+
statePensionFor,
|
|
48
|
+
type UKStatePensionTable,
|
|
49
|
+
type UKStatePensionYear,
|
|
50
|
+
} from './statePension';
|
|
51
|
+
|
|
52
|
+
export {
|
|
53
|
+
UK_CHILD_AGE_MESSAGE,
|
|
54
|
+
UK_NEW_CHILD_AGE,
|
|
55
|
+
UK_OLDEST_CHILD_AGE,
|
|
56
|
+
UK_YOUNG_PERSON_AGE,
|
|
57
|
+
asksEducation,
|
|
58
|
+
} from './children';
|
|
59
|
+
|
|
60
|
+
export {
|
|
61
|
+
addChild,
|
|
62
|
+
cloneDraft,
|
|
63
|
+
createBlankDraft,
|
|
64
|
+
createTypicalDraft,
|
|
65
|
+
removeChild,
|
|
66
|
+
setChildCount,
|
|
67
|
+
updateChild,
|
|
68
|
+
updateHead,
|
|
69
|
+
updatePartner,
|
|
70
|
+
} from './draft';
|
|
71
|
+
|
|
72
|
+
export { UK_HOUSEHOLD_LIMITS, UK_POLICY_YEARS, isComplete, validate, type UKValidateOptions } from './validate';
|
|
73
|
+
export { deserializeDraft, serializeDraft } from './serialize';
|
|
74
|
+
|
|
75
|
+
export * from './adapters';
|