placementt-core 1.400.1039 → 1.400.1041

package/lib/destinations.d.ts

@@ -0,0 +1,140 @@
+import { DestinationCode, DestinationValue, InstituteData, LeaverDestination } from "./typeDefinitions";
+/**
+ * destinations.ts — the nine NCCIS codes plus whatever a school has added to them.
+ *
+ * NCCIS gives every leaver one of nine activity codes, and two of them — NEET and
+ * NK — cover situations that could hardly be less alike: a leaver in hospital, one
+ * in care, one in custody and one who simply hasn't decided are all the same row of
+ * the return. Schools with SEND cohorts need that row broken up, so a school can
+ * define its own categories (`InstituteData.leaverDestinations`) and every one of
+ * them names the NCCIS code it counts within.
+ *
+ * That mapping is the whole design: a custom category's id is what gets stored and
+ * counted, so the school's own charts get the finer breakdown, while anything
+ * statutory (Compass+, the LA MI return) resolves it back to one of the nine.
+ */
+export type LeaverDestinationMap = {
+    [id: string]: LeaverDestination;
+};
+/**
+ * One option as the forms and charts see it — standard and custom side by side, so
+ * nothing downstream has to know which it is unless it cares.
+ */
+export type DestinationOption = {
+    /** What gets stored: an NCCIS code, or a custom category's id. */
+    code: DestinationValue;
+    label: string;
+    /** The NCCIS code this counts within — its own code, for the standard nine. */
+    nccisCode: DestinationCode;
+    custom: boolean;
+    description?: string;
+    archived?: boolean;
+};
+/** Ids become Firestore field-path segments (`aggregates.destinations.<id>`), so
+ * they may not contain a dot, a slash or anything else a path splits on. */
+export declare const DESTINATION_ID_PATTERN: RegExp;
+/** Custom ids carry a prefix so nothing can shadow a standard code, now or when
+ * NCCIS adds one. */
+export declare const CUSTOM_DESTINATION_PREFIX = "custom_";
+/** The NCCIS codes that mean "not in education, employment or training, or we don't
+ * know" — the pair schools break down, and the pair a positive-destination rate
+ * counts against. */
+export declare const NEGATIVE_DESTINATION_CODES: DestinationCode[];
+/**
+ * A stable id for a new custom category, derived from its label.
+ *
+ * @param {string} label the category's display name.
+ * @param {object} [existing] categories already defined, so ids stay unique.
+ * @return {string} a field-path-safe id.
+ */
+export declare const customDestinationId: (label: string, existing?: LeaverDestinationMap) => string;
+/** The nine NCCIS codes as options, in the order the MI return lists them. */
+export declare const standardDestinationOptions: () => DestinationOption[];
+/**
+ * Every destination a school offers: the nine standard codes, then its own
+ * categories grouped after the NCCIS code each one belongs to.
+ *
+ * Archived categories are left out unless asked for — they exist so that historical
+ * records keep their label, not so that new leavers can pick them.
+ *
+ * @param {object} [customs] the institute's leaverDestinations map.
+ * @param {object} [opts] `includeArchived` to keep withdrawn categories in the list.
+ * @return {DestinationOption[]} the ordered option list.
+ */
+export declare const destinationOptions: (customs?: LeaverDestinationMap, opts?: {
+    includeArchived?: boolean;
+}) => DestinationOption[];
+/**
+ * A school's categories, plus the ones its trust supplies.
+ *
+ * A trust's categories are extra vocabulary, not a mandate: they are added to
+ * whatever the school has of its own, and the school can neither edit nor remove
+ * them. Nothing is copied onto the school — resolution is a read-time merge, so a
+ * school that leaves the trust simply stops seeing them (see ./trustPolicies for why
+ * that is how every trust-supplied setting works here).
+ *
+ * On an id collision the SCHOOL's entry wins. Both keys are the same, so responses
+ * and aggregates land in the same place either way; what differs is that the school
+ * keeps the category it made, and keeps being able to edit it.
+ *
+ * @param {object} [school] the school's own institute doc.
+ * @param {object} [trust] the trust's institute doc, when the school is in one.
+ * @return {object} the merged map, and the ids the trust owns.
+ */
+export declare const resolveLeaverDestinations: (school?: Pick<InstituteData, "leaverDestinations">, trust?: Pick<InstituteData, "leaverDestinations">) => {
+    destinations: LeaverDestinationMap;
+    trustIds: string[];
+};
+/**
+ * What to show for a stored destination — a standard label, or a school's own.
+ *
+ * A category defined by a DIFFERENT school (a student browsing trust-wide alumni
+ * meets these) isn't in the map we hold, so its id is turned back into words rather
+ * than shown raw: an id is derived from the label it was created with, which makes
+ * "custom_in_hospital" recoverable as "In hospital".
+ *
+ * @param {string} [code] the stored destination.
+ * @param {object} [customs] the institute's leaverDestinations map.
+ * @return {string|undefined} the display label.
+ */
+export declare const destinationLabel: (code?: DestinationValue, customs?: LeaverDestinationMap) => string | undefined;
+/**
+ * The NCCIS code a stored destination counts within. Statutory exports and the
+ * NEET/NK figures go through this, never through the raw value.
+ *
+ * @param {string} [code] the stored destination.
+ * @param {object} [customs] the institute's leaverDestinations map.
+ * @return {DestinationCode|undefined} the NCCIS code to report it as.
+ */
+export declare const destinationNccisCode: (code?: DestinationValue, customs?: LeaverDestinationMap) => DestinationCode | undefined;
+/**
+ * Whether a destination is one of the two the school is trying to shrink. Custom
+ * categories count exactly as the NCCIS code they name does.
+ *
+ * @param {string} [code] the stored destination.
+ * @param {object} [customs] the institute's leaverDestinations map.
+ * @return {boolean} true for NEET / NK and anything mapped to them.
+ */
+export declare const isNegativeDestination: (code?: DestinationValue, customs?: LeaverDestinationMap) => boolean;
+/**
+ * Re-keys a `{destination: count}` aggregate onto the nine NCCIS codes, folding each
+ * custom category into its parent. For anything that has to report in NCCIS terms
+ * while the raw aggregate stays as granular as the school made it.
+ *
+ * @param {object} [counts] the raw aggregate.
+ * @param {object} [customs] the institute's leaverDestinations map.
+ * @return {object} counts keyed by NCCIS code.
+ */
+export declare const rollUpDestinationCounts: (counts?: {
+    [code: string]: number;
+}, customs?: LeaverDestinationMap) => {
+    [code: string]: number;
+};
+/**
+ * Validates a set of custom categories before it is stored. Shared by the setup card
+ * and the callable so both refuse the same things.
+ *
+ * @param {object} destinations the map to check.
+ * @return {string|undefined} the first problem found, or undefined if it's valid.
+ */
+export declare const validateLeaverDestinations: (destinations: LeaverDestinationMap) => string | undefined;

package/lib/destinations.js

@@ -0,0 +1,220 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateLeaverDestinations = exports.rollUpDestinationCounts = exports.isNegativeDestination = exports.destinationNccisCode = exports.destinationLabel = exports.resolveLeaverDestinations = exports.destinationOptions = exports.standardDestinationOptions = exports.customDestinationId = exports.NEGATIVE_DESTINATION_CODES = exports.CUSTOM_DESTINATION_PREFIX = exports.DESTINATION_ID_PATTERN = void 0;
+const constants_1 = require("./constants");
+/** Ids become Firestore field-path segments (`aggregates.destinations.<id>`), so
+ * they may not contain a dot, a slash or anything else a path splits on. */
+exports.DESTINATION_ID_PATTERN = /^[A-Za-z0-9_]{1,60}$/;
+/** Custom ids carry a prefix so nothing can shadow a standard code, now or when
+ * NCCIS adds one. */
+exports.CUSTOM_DESTINATION_PREFIX = "custom_";
+/** The NCCIS codes that mean "not in education, employment or training, or we don't
+ * know" — the pair schools break down, and the pair a positive-destination rate
+ * counts against. */
+exports.NEGATIVE_DESTINATION_CODES = ["NEET", "NK"];
+/**
+ * A stable id for a new custom category, derived from its label.
+ *
+ * @param {string} label the category's display name.
+ * @param {object} [existing] categories already defined, so ids stay unique.
+ * @return {string} a field-path-safe id.
+ */
+const customDestinationId = (label, existing) => {
+    const slug = (label || "")
+        .trim().toLowerCase()
+        .replace(/[^a-z0-9]+/g, "_")
+        .replace(/^_+|_+$/g, "")
+        .slice(0, 40) || "category";
+    const base = `${exports.CUSTOM_DESTINATION_PREFIX}${slug}`;
+    if (!existing?.[base])
+        return base;
+    // Two categories can legitimately slug the same ("In care" / "In-care"), so the
+    // second one gets a suffix rather than silently overwriting the first.
+    let n = 2;
+    while (existing[`${base}_${n}`])
+        n++;
+    return `${base}_${n}`;
+};
+exports.customDestinationId = customDestinationId;
+/** The nine NCCIS codes as options, in the order the MI return lists them. */
+const standardDestinationOptions = () => Object.entries(constants_1.DESTINATION_CODES).map(([code, label]) => ({
+    code, label, nccisCode: code, custom: false,
+}));
+exports.standardDestinationOptions = standardDestinationOptions;
+/**
+ * Every destination a school offers: the nine standard codes, then its own
+ * categories grouped after the NCCIS code each one belongs to.
+ *
+ * Archived categories are left out unless asked for — they exist so that historical
+ * records keep their label, not so that new leavers can pick them.
+ *
+ * @param {object} [customs] the institute's leaverDestinations map.
+ * @param {object} [opts] `includeArchived` to keep withdrawn categories in the list.
+ * @return {DestinationOption[]} the ordered option list.
+ */
+const destinationOptions = (customs, opts) => {
+    const custom = Object.entries(customs ?? {})
+        .filter(([, d]) => d && (opts?.includeArchived || !d.archived))
+        .map(([id, d]) => ({
+        code: id,
+        label: d.label,
+        nccisCode: (constants_1.DESTINATION_CODES[d.nccisCode] ? d.nccisCode : "NEET"),
+        custom: true,
+        description: d.description,
+        archived: d.archived,
+    }))
+        .sort((a, b) => a.label.localeCompare(b.label));
+    // Grouped under their parent so "In hospital" reads as a kind of NEET rather than
+    // as a tenth code of its own.
+    return (0, exports.standardDestinationOptions)().flatMap((std) => [
+        std, ...custom.filter((c) => c.nccisCode === std.code),
+    ]);
+};
+exports.destinationOptions = destinationOptions;
+/**
+ * A school's categories, plus the ones its trust supplies.
+ *
+ * A trust's categories are extra vocabulary, not a mandate: they are added to
+ * whatever the school has of its own, and the school can neither edit nor remove
+ * them. Nothing is copied onto the school — resolution is a read-time merge, so a
+ * school that leaves the trust simply stops seeing them (see ./trustPolicies for why
+ * that is how every trust-supplied setting works here).
+ *
+ * On an id collision the SCHOOL's entry wins. Both keys are the same, so responses
+ * and aggregates land in the same place either way; what differs is that the school
+ * keeps the category it made, and keeps being able to edit it.
+ *
+ * @param {object} [school] the school's own institute doc.
+ * @param {object} [trust] the trust's institute doc, when the school is in one.
+ * @return {object} the merged map, and the ids the trust owns.
+ */
+const resolveLeaverDestinations = (school, trust) => {
+    const own = school?.leaverDestinations ?? {};
+    const fromTrust = trust?.leaverDestinations ?? {};
+    const trustIds = Object.keys(fromTrust).filter((id) => !own[id]);
+    return {
+        destinations: { ...fromTrust, ...own },
+        trustIds,
+    };
+};
+exports.resolveLeaverDestinations = resolveLeaverDestinations;
+/**
+ * What to show for a stored destination — a standard label, or a school's own.
+ *
+ * A category defined by a DIFFERENT school (a student browsing trust-wide alumni
+ * meets these) isn't in the map we hold, so its id is turned back into words rather
+ * than shown raw: an id is derived from the label it was created with, which makes
+ * "custom_in_hospital" recoverable as "In hospital".
+ *
+ * @param {string} [code] the stored destination.
+ * @param {object} [customs] the institute's leaverDestinations map.
+ * @return {string|undefined} the display label.
+ */
+const destinationLabel = (code, customs) => {
+    if (!code)
+        return undefined;
+    if (constants_1.DESTINATION_CODES[code])
+        return constants_1.DESTINATION_CODES[code];
+    const known = customs?.[code]?.label;
+    if (known)
+        return known;
+    if (!code.startsWith(exports.CUSTOM_DESTINATION_PREFIX))
+        return code;
+    const words = code.slice(exports.CUSTOM_DESTINATION_PREFIX.length).replace(/_/g, " ").trim();
+    return words ? words.charAt(0).toUpperCase() + words.slice(1) : code;
+};
+exports.destinationLabel = destinationLabel;
+/**
+ * The NCCIS code a stored destination counts within. Statutory exports and the
+ * NEET/NK figures go through this, never through the raw value.
+ *
+ * @param {string} [code] the stored destination.
+ * @param {object} [customs] the institute's leaverDestinations map.
+ * @return {DestinationCode|undefined} the NCCIS code to report it as.
+ */
+const destinationNccisCode = (code, customs) => {
+    if (!code)
+        return undefined;
+    if (constants_1.DESTINATION_CODES[code])
+        return code;
+    const custom = customs?.[code];
+    // An id we no longer recognise is still somebody's leaver: "not known" is the
+    // honest reading, and it keeps them in the cohort rather than dropping them.
+    if (!custom)
+        return "NK";
+    return constants_1.DESTINATION_CODES[custom.nccisCode] ? custom.nccisCode : "NEET";
+};
+exports.destinationNccisCode = destinationNccisCode;
+/**
+ * Whether a destination is one of the two the school is trying to shrink. Custom
+ * categories count exactly as the NCCIS code they name does.
+ *
+ * @param {string} [code] the stored destination.
+ * @param {object} [customs] the institute's leaverDestinations map.
+ * @return {boolean} true for NEET / NK and anything mapped to them.
+ */
+const isNegativeDestination = (code, customs) => {
+    const nccis = (0, exports.destinationNccisCode)(code, customs);
+    return Boolean(nccis && exports.NEGATIVE_DESTINATION_CODES.includes(nccis));
+};
+exports.isNegativeDestination = isNegativeDestination;
+/**
+ * Re-keys a `{destination: count}` aggregate onto the nine NCCIS codes, folding each
+ * custom category into its parent. For anything that has to report in NCCIS terms
+ * while the raw aggregate stays as granular as the school made it.
+ *
+ * @param {object} [counts] the raw aggregate.
+ * @param {object} [customs] the institute's leaverDestinations map.
+ * @return {object} counts keyed by NCCIS code.
+ */
+const rollUpDestinationCounts = (counts, customs) => {
+    const out = {};
+    for (const [code, n] of Object.entries(counts ?? {})) {
+        const key = (0, exports.destinationNccisCode)(code, customs) ?? "NK";
+        out[key] = (out[key] ?? 0) + (n ?? 0);
+    }
+    return out;
+};
+exports.rollUpDestinationCounts = rollUpDestinationCounts;
+/**
+ * Validates a set of custom categories before it is stored. Shared by the setup card
+ * and the callable so both refuse the same things.
+ *
+ * @param {object} destinations the map to check.
+ * @return {string|undefined} the first problem found, or undefined if it's valid.
+ */
+const validateLeaverDestinations = (destinations) => {
+    const entries = Object.entries(destinations ?? {});
+    if (entries.length > 50)
+        return "You can add up to 50 destination categories.";
+    const seen = new Set();
+    for (const [id, d] of entries) {
+        if (!d)
+            return "One of your categories is empty.";
+        if (!exports.DESTINATION_ID_PATTERN.test(id) || id !== d.id)
+            return "A category id is invalid.";
+        if (!id.startsWith(exports.CUSTOM_DESTINATION_PREFIX))
+            return "A category id is invalid.";
+        if (constants_1.DESTINATION_CODES[id])
+            return "A category can't reuse a standard destination code.";
+        const label = (d.label ?? "").trim();
+        if (!label)
+            return "Give every category a name.";
+        if (label.length > 60)
+            return "Category names must be 60 characters or fewer.";
+        if (!constants_1.DESTINATION_CODES[d.nccisCode])
+            return `Choose which group "${label}" counts within.`;
+        const key = label.toLowerCase();
+        if (seen.has(key))
+            return `You already have a category called "${label}".`;
+        // A category that duplicates a standard label would show twice in the picker
+        // with no way to tell them apart.
+        if (Object.values(constants_1.DESTINATION_CODES).some((l) => l.toLowerCase() === key)) {
+            return `"${label}" is already a standard destination.`;
+        }
+        seen.add(key);
+    }
+    return undefined;
+};
+exports.validateLeaverDestinations = validateLeaverDestinations;
+//# sourceMappingURL=destinations.js.map

package/lib/destinations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"destinations.js","sourceRoot":"","sources":["../src/destinations.ts"],"names":[],"mappings":"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"}

package/lib/destinations.test.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/destinations.test.js

@@ -0,0 +1,121 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const destinations_1 = require("./destinations");
+const customs = {
+    custom_in_hospital: { id: "custom_in_hospital", label: "In hospital", nccisCode: "NEET" },
+    custom_in_custody: { id: "custom_in_custody", label: "In custody", nccisCode: "NEET" },
+    custom_supported_internship: { id: "custom_supported_internship", label: "Supported internship", nccisCode: "EMP" },
+    custom_moved_away: { id: "custom_moved_away", label: "Moved away", nccisCode: "NK", archived: true },
+};
+describe("destinationOptions", () => {
+    it("lists the nine NCCIS codes when a school has added nothing", () => {
+        const options = (0, destinations_1.destinationOptions)();
+        expect(options).toHaveLength(9);
+        expect(options.every((o) => !o.custom)).toBe(true);
+    });
+    it("puts each custom category directly after the code it counts within", () => {
+        const codes = (0, destinations_1.destinationOptions)(customs).map((o) => o.code);
+        expect(codes.indexOf("custom_supported_internship")).toEqual(codes.indexOf("EMP") + 1);
+        // Both NEET categories follow NEET, alphabetically.
+        expect(codes.slice(codes.indexOf("NEET"), codes.indexOf("NEET") + 3))
+            .toEqual(["NEET", "custom_in_custody", "custom_in_hospital"]);
+    });
+    it("hides archived categories unless asked for them", () => {
+        expect((0, destinations_1.destinationOptions)(customs).map((o) => o.code)).not.toContain("custom_moved_away");
+        expect((0, destinations_1.destinationOptions)(customs, { includeArchived: true }).map((o) => o.code))
+            .toContain("custom_moved_away");
+    });
+});
+describe("resolveLeaverDestinations", () => {
+    const trust = { leaverDestinations: {
+            custom_in_care: { id: "custom_in_care", label: "In care", nccisCode: "NEET" },
+            custom_in_hospital: { id: "custom_in_hospital", label: "In hospital (trust)", nccisCode: "NEET" },
+        } };
+    it("offers the trust's categories alongside the school's, and names the trust's", () => {
+        const { destinations, trustIds } = (0, destinations_1.resolveLeaverDestinations)({ leaverDestinations: customs }, trust);
+        expect(Object.keys(destinations).sort()).toEqual([
+            "custom_in_care", "custom_in_custody", "custom_in_hospital",
+            "custom_moved_away", "custom_supported_internship",
+        ]);
+        expect(trustIds).toEqual(["custom_in_care"]);
+    });
+    it("leaves the school's own version of a shared id in the school's hands", () => {
+        const { destinations, trustIds } = (0, destinations_1.resolveLeaverDestinations)({ leaverDestinations: customs }, trust);
+        expect(destinations.custom_in_hospital.label).toEqual("In hospital");
+        expect(trustIds).not.toContain("custom_in_hospital");
+    });
+    it("is the school's own map when there is no trust", () => {
+        expect((0, destinations_1.resolveLeaverDestinations)({ leaverDestinations: customs }).trustIds).toEqual([]);
+        expect((0, destinations_1.resolveLeaverDestinations)().destinations).toEqual({});
+    });
+});
+describe("destinationLabel", () => {
+    it("reads standard codes and the school's own categories", () => {
+        expect((0, destinations_1.destinationLabel)("APP")).toEqual("Apprenticeship");
+        expect((0, destinations_1.destinationLabel)("custom_in_hospital", customs)).toEqual("In hospital");
+    });
+    it("recovers words from an id defined by another school", () => {
+        // A student browsing trust-wide alumni meets categories we don't hold.
+        expect((0, destinations_1.destinationLabel)("custom_in_care")).toEqual("In care");
+    });
+});
+describe("destinationNccisCode", () => {
+    it("maps a custom category onto the code it reports as", () => {
+        expect((0, destinations_1.destinationNccisCode)("custom_in_hospital", customs)).toEqual("NEET");
+        expect((0, destinations_1.destinationNccisCode)("custom_supported_internship", customs)).toEqual("EMP");
+    });
+    it("treats an unknown id as not known rather than dropping the leaver", () => {
+        expect((0, destinations_1.destinationNccisCode)("custom_gone", customs)).toEqual("NK");
+    });
+    it("leaves standard codes alone", () => {
+        expect((0, destinations_1.destinationNccisCode)("HE", customs)).toEqual("HE");
+    });
+});
+describe("isNegativeDestination", () => {
+    it("counts a school's NEET-mapped categories as NEET", () => {
+        expect((0, destinations_1.isNegativeDestination)("custom_in_hospital", customs)).toBe(true);
+        expect((0, destinations_1.isNegativeDestination)("custom_supported_internship", customs)).toBe(false);
+        expect((0, destinations_1.isNegativeDestination)("NK")).toBe(true);
+        expect((0, destinations_1.isNegativeDestination)("HE")).toBe(false);
+    });
+});
+describe("rollUpDestinationCounts", () => {
+    it("folds custom categories into their NCCIS code", () => {
+        const rolled = (0, destinations_1.rollUpDestinationCounts)({ HE: 10, NEET: 2, custom_in_hospital: 3, custom_in_custody: 1, custom_supported_internship: 4 }, customs);
+        expect(rolled).toEqual({ HE: 10, NEET: 6, EMP: 4 });
+    });
+});
+describe("customDestinationId", () => {
+    it("derives a field-path-safe id from the label", () => {
+        expect((0, destinations_1.customDestinationId)("In hospital")).toEqual("custom_in_hospital");
+    });
+    it("suffixes rather than overwriting a category that slugs the same", () => {
+        expect((0, destinations_1.customDestinationId)("In-hospital", customs)).toEqual("custom_in_hospital_2");
+    });
+});
+describe("validateLeaverDestinations", () => {
+    it("accepts a well-formed set", () => {
+        expect((0, destinations_1.validateLeaverDestinations)(customs)).toBeUndefined();
+    });
+    it("rejects a category with no name, a bad group, or a duplicate label", () => {
+        expect((0, destinations_1.validateLeaverDestinations)({
+            custom_x: { id: "custom_x", label: "  ", nccisCode: "NEET" },
+        })).toBeDefined();
+        expect((0, destinations_1.validateLeaverDestinations)({
+            custom_x: { id: "custom_x", label: "In hospital", nccisCode: "XX" },
+        })).toBeDefined();
+        expect((0, destinations_1.validateLeaverDestinations)({
+            ...customs,
+            custom_in_hospital_2: { id: "custom_in_hospital_2", label: "in hospital", nccisCode: "NEET" },
+        })).toBeDefined();
+    });
+    it("rejects an id that could collide with a standard code or a field path", () => {
+        expect((0, destinations_1.validateLeaverDestinations)({
+            HE: { id: "HE", label: "Uni", nccisCode: "HE" },
+        })).toBeDefined();
+        expect((0, destinations_1.validateLeaverDestinations)({
+            "custom_a.b": { id: "custom_a.b", label: "Dotted", nccisCode: "NEET" },
+        })).toBeDefined();
+    });
+});
+//# sourceMappingURL=destinations.test.js.map

package/lib/destinations.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"destinations.test.js","sourceRoot":"","sources":["../src/destinations.test.ts"],"names":[],"mappings":"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"}

package/lib/index.d.ts

@@ -21,6 +21,7 @@ export * from "./groups";
 export * from "./emailSections";
 export * from "./exportTransformers";
 export * from "./compassExport";
+export * from "./destinations";
 export * from "./benchmarkEvidenceRules";
 export * from "./portfolioAggregate";
 export * from "./tutorialTips";

package/lib/index.js

@@ -41,6 +41,7 @@ __exportStar(require("./groups"), exports);
 __exportStar(require("./emailSections"), exports);
 __exportStar(require("./exportTransformers"), exports);
 __exportStar(require("./compassExport"), exports);
+__exportStar(require("./destinations"), exports);
 __exportStar(require("./benchmarkEvidenceRules"), exports);
 __exportStar(require("./portfolioAggregate"), exports);
 __exportStar(require("./tutorialTips"), exports);

package/lib/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;AACA,sDAAoC;AACpC,gEAA8C;AAC9C,0DAAwC;AACxC,2DAAyC;AACzC,kDAAgC;AAChC,uDAAqC;AACrC,4DAA0C;AAC1C,2DAAyC;AAEzC,oDAAkC;AAClC,8CAA4B;AAC5B,kDAAgC;AAChC,kDAAgC;AAChC,qDAAmC;AACnC,mDAAiC;AACjC,qDAAmC;AACnC,mDAAiC;AACjC,+CAA6B;AAC7B,wCAAsB;AACtB,oDAAkC;AAClC,2CAAyB;AACzB,kDAAgC;AAChC,uDAAqC;AACrC,kDAAgC;AAChC,2DAAyC;AACzC,uDAAqC;AACrC,iDAA+B;AAC/B,8CAA4B;AAC5B,qDAAmC;AACnC,0CAAwB;AACxB,yCAAuB;AACvB,4DAA0C;AAC1C,kDAAgC;AAChC,iDAA+B;AAC/B,2CAAyB;AACzB,4DAA0C;AAC1C,oEAAiD;AACjD,yEAAuD;AACvD,kEAAgD;AAChD,kEAAgD;AAChD,oEAAkD;AAClD,yGAAuF;AACvF,0GAAwF;AACxF,+FAA6E;AAC7E,4DAA0C;AAC1C,oEAAkD;AAClD,iEAA+C;AAC/C,gEAA8C;AAC9C,2EAAyD;AACzD,6CAA2B;AAC3B,+CAA6B;AAC7B,8CAA4B;AAC5B,6DAAuE;AAA9D,2IAAA,OAAO,OAAuB"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;AACA,sDAAoC;AACpC,gEAA8C;AAC9C,0DAAwC;AACxC,2DAAyC;AACzC,kDAAgC;AAChC,uDAAqC;AACrC,4DAA0C;AAC1C,2DAAyC;AAEzC,oDAAkC;AAClC,8CAA4B;AAC5B,kDAAgC;AAChC,kDAAgC;AAChC,qDAAmC;AACnC,mDAAiC;AACjC,qDAAmC;AACnC,mDAAiC;AACjC,+CAA6B;AAC7B,wCAAsB;AACtB,oDAAkC;AAClC,2CAAyB;AACzB,kDAAgC;AAChC,uDAAqC;AACrC,kDAAgC;AAChC,iDAA+B;AAC/B,2DAAyC;AACzC,uDAAqC;AACrC,iDAA+B;AAC/B,8CAA4B;AAC5B,qDAAmC;AACnC,0CAAwB;AACxB,yCAAuB;AACvB,4DAA0C;AAC1C,kDAAgC;AAChC,iDAA+B;AAC/B,2CAAyB;AACzB,4DAA0C;AAC1C,oEAAiD;AACjD,yEAAuD;AACvD,kEAAgD;AAChD,kEAAgD;AAChD,oEAAkD;AAClD,yGAAuF;AACvF,0GAAwF;AACxF,+FAA6E;AAC7E,4DAA0C;AAC1C,oEAAkD;AAClD,iEAA+C;AAC/C,gEAA8C;AAC9C,2EAAyD;AACzD,6CAA2B;AAC3B,+CAA6B;AAC7B,8CAA4B;AAC5B,6DAAuE;AAA9D,2IAAA,OAAO,OAAuB"}

package/lib/typeDefinitions.d.ts

@@ -1077,6 +1077,14 @@ export type InstituteData = {
         closeAfterDays?: number;
     };
     destinationsConfig?: DestinationsConfig;
+    /** School-defined leaver destination categories, keyed by id, added from the
+     * Destinations Setup tab. They sit alongside the nine NCCIS codes on every
+     * leaver form and each one names the NCCIS code it counts within, so a school
+     * can break "NEET" down into the situations it actually needs to track
+     * (in hospital, in care, in custody) without breaking statutory reporting. */
+    leaverDestinations?: {
+        [id: string]: LeaverDestination;
+    };
     /** Trust-authored policy, one entry per feature a trust can impose on the schools
      * beneath it. Set on the TRUST's own institute doc and read by its schools through
      * their approved trust link — never copied onto the school, so there is one source
@@ -2227,6 +2235,44 @@ export type ExternalEventRequest = {
 };
 /** NCCIS-compatible destination activity codes (MI Requirement 2026–27) */
 export type DestinationCode = "HE" | "FE" | "APP" | "EWBL" | "EMP" | "VOL" | "OTH" | "NEET" | "NK";
+/**
+ * A destination as it is actually stored on a response, an alumni record or a
+ * cycle aggregate: one of the nine NCCIS codes above, or the id of a school-defined
+ * category from `InstituteData.leaverDestinations`.
+ *
+ * Custom categories exist because NCCIS's NEET and NK are a single bucket for very
+ * different situations — a SEND leaver in hospital, in care or in custody is "NEET"
+ * to the local authority and nothing more, which is exactly the granularity schools
+ * lose. Every custom category still carries the NCCIS code it counts within
+ * (`LeaverDestination.nccisCode`), so statutory returns are unaffected: only the
+ * school's own reporting gets finer.
+ *
+ * The `(string & {})` half keeps editor autocomplete for the nine standard codes
+ * while still accepting a custom id.
+ */
+export type DestinationValue = DestinationCode | (string & {});
+/**
+ * A school-defined leaver destination category, stored on
+ * `InstituteData.leaverDestinations` keyed by `id`.
+ *
+ * `id` is what lands in responses and in `aggregates.destinations.<id>`, so it is
+ * restricted to `[A-Za-z0-9_]` (see DESTINATION_ID_PATTERN) — a Firestore field path
+ * segment can't contain a dot or a slash, and these keys become one.
+ */
+export type LeaverDestination = {
+    id: string;
+    label: string;
+    /** Which of the nine NCCIS codes this rolls up into for statutory reporting. */
+    nccisCode: DestinationCode;
+    /** Optional helper text shown under the option on the leaver forms. */
+    description?: string;
+    /** Removed from the forms, but kept here so records and charts that already
+     * carry the id keep their label. Deleting outright would leave past responses
+     * showing a raw id. */
+    archived?: boolean;
+    createdAt?: string;
+    createdBy?: string;
+};
 /** SOC 2020 major group number */
 export type SOCMajorGroup = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9;
 /** Employment detail captured in Form C and stored in CheckInEntry */
@@ -2270,7 +2316,7 @@ export type ApprenticeshipDetails = {
  * Appended on every check-in; source distinguishes self-report from staff/trusted-contact entry.
  */
 export type CheckInEntry = {
-    destinationCode: DestinationCode;
+    destinationCode: DestinationValue;
     type?: "annual" | "midYear" | "leaverTransition" | "resultsDay" | "christmas";
     sector?: string;
     date: string;
@@ -2611,7 +2657,7 @@ export type LeaverTransitionData = {
     mobile?: string;
     linkedinUrl?: string;
     activities?: string[];
-    intendedDestination: DestinationCode;
+    intendedDestination: DestinationValue;
     intendedDestinationDetails?: EducationDetails | EmploymentDetails | ApprenticeshipDetails;
     intendedStartDate?: string;
     trustedContact?: TrustedContact;
@@ -2652,7 +2698,7 @@ export type LeaverConsentCapture = {
  */
 export type LeaverCheckpointResponse = {
     checkpoint: "resultsDay" | "christmas";
-    destination: DestinationCode;
+    destination: DestinationValue;
     destinationDetails?: EducationDetails | EmploymentDetails | ApprenticeshipDetails;
     /** resultsDay only — did results change their plan vs intendedDestination? */
     changedFromIntended?: boolean;
@@ -2713,13 +2759,13 @@ export type Alumni = {
     status: "pending" | "inviteSent" | "leaverReviewed" | "uploaded" | "alumniReviewed" | "declined" | "approved";
     source?: "selfRegistered" | "staffAdded" | "leaverExport";
     /** Intended destination captured via Form B before leaving */
-    intendedDestination?: DestinationCode;
+    intendedDestination?: DestinationValue;
     intendedDestinationDetails?: EducationDetails | EmploymentDetails | ApprenticeshipDetails;
     intendedStartDate?: string;
     /** October confirmed actual destination snapshot */
-    confirmedDestination?: DestinationCode;
+    confirmedDestination?: DestinationValue;
     /** Most recent known destination — updated on each check-in */
-    currentDestination?: DestinationCode;
+    currentDestination?: DestinationValue;
     sector?: string;
     subsector?: string;
     businessSize?: string;

package/package.json

@@ -2,7 +2,7 @@
   "private": false,
   "name": "placementt-core",
   "author": "Placementt",
-  "version": "1.400.1039",
+  "version": "1.400.1041",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
   "scripts": {

package/src/destinations.test.ts

@@ -0,0 +1,149 @@
+import {
+    customDestinationId,
+    resolveLeaverDestinations,
+    destinationLabel,
+    destinationNccisCode,
+    destinationOptions,
+    isNegativeDestination,
+    LeaverDestinationMap,
+    rollUpDestinationCounts,
+    validateLeaverDestinations,
+} from "./destinations";
+
+const customs: LeaverDestinationMap = {
+    custom_in_hospital: {id: "custom_in_hospital", label: "In hospital", nccisCode: "NEET"},
+    custom_in_custody: {id: "custom_in_custody", label: "In custody", nccisCode: "NEET"},
+    custom_supported_internship: {id: "custom_supported_internship", label: "Supported internship", nccisCode: "EMP"},
+    custom_moved_away: {id: "custom_moved_away", label: "Moved away", nccisCode: "NK", archived: true},
+};
+
+describe("destinationOptions", () => {
+    it("lists the nine NCCIS codes when a school has added nothing", () => {
+        const options = destinationOptions();
+        expect(options).toHaveLength(9);
+        expect(options.every((o) => !o.custom)).toBe(true);
+    });
+
+    it("puts each custom category directly after the code it counts within", () => {
+        const codes = destinationOptions(customs).map((o) => o.code);
+        expect(codes.indexOf("custom_supported_internship")).toEqual(codes.indexOf("EMP") + 1);
+        // Both NEET categories follow NEET, alphabetically.
+        expect(codes.slice(codes.indexOf("NEET"), codes.indexOf("NEET") + 3))
+            .toEqual(["NEET", "custom_in_custody", "custom_in_hospital"]);
+    });
+
+    it("hides archived categories unless asked for them", () => {
+        expect(destinationOptions(customs).map((o) => o.code)).not.toContain("custom_moved_away");
+        expect(destinationOptions(customs, {includeArchived: true}).map((o) => o.code))
+            .toContain("custom_moved_away");
+    });
+});
+
+describe("resolveLeaverDestinations", () => {
+    const trust = {leaverDestinations: {
+        custom_in_care: {id: "custom_in_care", label: "In care", nccisCode: "NEET" as const},
+        custom_in_hospital: {id: "custom_in_hospital", label: "In hospital (trust)", nccisCode: "NEET" as const},
+    }};
+
+    it("offers the trust's categories alongside the school's, and names the trust's", () => {
+        const {destinations, trustIds} = resolveLeaverDestinations({leaverDestinations: customs}, trust);
+        expect(Object.keys(destinations).sort()).toEqual([
+            "custom_in_care", "custom_in_custody", "custom_in_hospital",
+            "custom_moved_away", "custom_supported_internship",
+        ]);
+        expect(trustIds).toEqual(["custom_in_care"]);
+    });
+
+    it("leaves the school's own version of a shared id in the school's hands", () => {
+        const {destinations, trustIds} = resolveLeaverDestinations({leaverDestinations: customs}, trust);
+        expect(destinations.custom_in_hospital.label).toEqual("In hospital");
+        expect(trustIds).not.toContain("custom_in_hospital");
+    });
+
+    it("is the school's own map when there is no trust", () => {
+        expect(resolveLeaverDestinations({leaverDestinations: customs}).trustIds).toEqual([]);
+        expect(resolveLeaverDestinations().destinations).toEqual({});
+    });
+});
+
+describe("destinationLabel", () => {
+    it("reads standard codes and the school's own categories", () => {
+        expect(destinationLabel("APP")).toEqual("Apprenticeship");
+        expect(destinationLabel("custom_in_hospital", customs)).toEqual("In hospital");
+    });
+
+    it("recovers words from an id defined by another school", () => {
+        // A student browsing trust-wide alumni meets categories we don't hold.
+        expect(destinationLabel("custom_in_care")).toEqual("In care");
+    });
+});
+
+describe("destinationNccisCode", () => {
+    it("maps a custom category onto the code it reports as", () => {
+        expect(destinationNccisCode("custom_in_hospital", customs)).toEqual("NEET");
+        expect(destinationNccisCode("custom_supported_internship", customs)).toEqual("EMP");
+    });
+
+    it("treats an unknown id as not known rather than dropping the leaver", () => {
+        expect(destinationNccisCode("custom_gone", customs)).toEqual("NK");
+    });
+
+    it("leaves standard codes alone", () => {
+        expect(destinationNccisCode("HE", customs)).toEqual("HE");
+    });
+});
+
+describe("isNegativeDestination", () => {
+    it("counts a school's NEET-mapped categories as NEET", () => {
+        expect(isNegativeDestination("custom_in_hospital", customs)).toBe(true);
+        expect(isNegativeDestination("custom_supported_internship", customs)).toBe(false);
+        expect(isNegativeDestination("NK")).toBe(true);
+        expect(isNegativeDestination("HE")).toBe(false);
+    });
+});
+
+describe("rollUpDestinationCounts", () => {
+    it("folds custom categories into their NCCIS code", () => {
+        const rolled = rollUpDestinationCounts(
+            {HE: 10, NEET: 2, custom_in_hospital: 3, custom_in_custody: 1, custom_supported_internship: 4}, customs);
+        expect(rolled).toEqual({HE: 10, NEET: 6, EMP: 4});
+    });
+});
+
+describe("customDestinationId", () => {
+    it("derives a field-path-safe id from the label", () => {
+        expect(customDestinationId("In hospital")).toEqual("custom_in_hospital");
+    });
+
+    it("suffixes rather than overwriting a category that slugs the same", () => {
+        expect(customDestinationId("In-hospital", customs)).toEqual("custom_in_hospital_2");
+    });
+});
+
+describe("validateLeaverDestinations", () => {
+    it("accepts a well-formed set", () => {
+        expect(validateLeaverDestinations(customs)).toBeUndefined();
+    });
+
+    it("rejects a category with no name, a bad group, or a duplicate label", () => {
+        expect(validateLeaverDestinations({
+            custom_x: {id: "custom_x", label: "  ", nccisCode: "NEET"},
+        })).toBeDefined();
+        expect(validateLeaverDestinations({
+            custom_x: {id: "custom_x", label: "In hospital", nccisCode: "XX" as never},
+        })).toBeDefined();
+        expect(validateLeaverDestinations({
+            ...customs,
+            custom_in_hospital_2: {id: "custom_in_hospital_2", label: "in hospital", nccisCode: "NEET"},
+        })).toBeDefined();
+    });
+
+    it("rejects an id that could collide with a standard code or a field path", () => {
+        expect(validateLeaverDestinations({
+            HE: {id: "HE", label: "Uni", nccisCode: "HE"},
+        })).toBeDefined();
+        expect(validateLeaverDestinations({
+            "custom_a.b": {id: "custom_a.b", label: "Dotted", nccisCode: "NEET"},
+        })).toBeDefined();
+    });
+});

package/src/destinations.ts

@@ -0,0 +1,249 @@
+import {DESTINATION_CODES} from "./constants";
+import {DestinationCode, DestinationValue, InstituteData, LeaverDestination} from "./typeDefinitions";
+
+/**
+ * destinations.ts — the nine NCCIS codes plus whatever a school has added to them.
+ *
+ * NCCIS gives every leaver one of nine activity codes, and two of them — NEET and
+ * NK — cover situations that could hardly be less alike: a leaver in hospital, one
+ * in care, one in custody and one who simply hasn't decided are all the same row of
+ * the return. Schools with SEND cohorts need that row broken up, so a school can
+ * define its own categories (`InstituteData.leaverDestinations`) and every one of
+ * them names the NCCIS code it counts within.
+ *
+ * That mapping is the whole design: a custom category's id is what gets stored and
+ * counted, so the school's own charts get the finer breakdown, while anything
+ * statutory (Compass+, the LA MI return) resolves it back to one of the nine.
+ */
+
+export type LeaverDestinationMap = {[id: string]: LeaverDestination};
+
+/**
+ * One option as the forms and charts see it — standard and custom side by side, so
+ * nothing downstream has to know which it is unless it cares.
+ */
+export type DestinationOption = {
+    /** What gets stored: an NCCIS code, or a custom category's id. */
+    code: DestinationValue,
+    label: string,
+    /** The NCCIS code this counts within — its own code, for the standard nine. */
+    nccisCode: DestinationCode,
+    custom: boolean,
+    description?: string,
+    archived?: boolean,
+};
+
+/** Ids become Firestore field-path segments (`aggregates.destinations.<id>`), so
+ * they may not contain a dot, a slash or anything else a path splits on. */
+export const DESTINATION_ID_PATTERN = /^[A-Za-z0-9_]{1,60}$/;
+
+/** Custom ids carry a prefix so nothing can shadow a standard code, now or when
+ * NCCIS adds one. */
+export const CUSTOM_DESTINATION_PREFIX = "custom_";
+
+/** The NCCIS codes that mean "not in education, employment or training, or we don't
+ * know" — the pair schools break down, and the pair a positive-destination rate
+ * counts against. */
+export const NEGATIVE_DESTINATION_CODES: DestinationCode[] = ["NEET", "NK"];
+
+/**
+ * A stable id for a new custom category, derived from its label.
+ *
+ * @param {string} label the category's display name.
+ * @param {object} [existing] categories already defined, so ids stay unique.
+ * @return {string} a field-path-safe id.
+ */
+export const customDestinationId = (label: string, existing?: LeaverDestinationMap): string => {
+    const slug = (label || "")
+        .trim().toLowerCase()
+        .replace(/[^a-z0-9]+/g, "_")
+        .replace(/^_+|_+$/g, "")
+        .slice(0, 40) || "category";
+    const base = `${CUSTOM_DESTINATION_PREFIX}${slug}`;
+    if (!existing?.[base]) return base;
+    // Two categories can legitimately slug the same ("In care" / "In-care"), so the
+    // second one gets a suffix rather than silently overwriting the first.
+    let n = 2;
+    while (existing[`${base}_${n}`]) n++;
+    return `${base}_${n}`;
+};
+
+/** The nine NCCIS codes as options, in the order the MI return lists them. */
+export const standardDestinationOptions = (): DestinationOption[] =>
+    Object.entries(DESTINATION_CODES).map(([code, label]) => ({
+        code, label, nccisCode: code as DestinationCode, custom: false,
+    }));
+
+/**
+ * Every destination a school offers: the nine standard codes, then its own
+ * categories grouped after the NCCIS code each one belongs to.
+ *
+ * Archived categories are left out unless asked for — they exist so that historical
+ * records keep their label, not so that new leavers can pick them.
+ *
+ * @param {object} [customs] the institute's leaverDestinations map.
+ * @param {object} [opts] `includeArchived` to keep withdrawn categories in the list.
+ * @return {DestinationOption[]} the ordered option list.
+ */
+export const destinationOptions = (
+    customs?: LeaverDestinationMap, opts?: {includeArchived?: boolean},
+): DestinationOption[] => {
+    const custom = Object.entries(customs ?? {})
+        .filter(([, d]) => d && (opts?.includeArchived || !d.archived))
+        .map(([id, d]) => ({
+            code: id,
+            label: d.label,
+            nccisCode: (DESTINATION_CODES[d.nccisCode] ? d.nccisCode : "NEET") as DestinationCode,
+            custom: true,
+            description: d.description,
+            archived: d.archived,
+        }))
+        .sort((a, b) => a.label.localeCompare(b.label));
+
+    // Grouped under their parent so "In hospital" reads as a kind of NEET rather than
+    // as a tenth code of its own.
+    return standardDestinationOptions().flatMap((std) => [
+        std, ...custom.filter((c) => c.nccisCode === std.code),
+    ]);
+};
+
+/**
+ * A school's categories, plus the ones its trust supplies.
+ *
+ * A trust's categories are extra vocabulary, not a mandate: they are added to
+ * whatever the school has of its own, and the school can neither edit nor remove
+ * them. Nothing is copied onto the school — resolution is a read-time merge, so a
+ * school that leaves the trust simply stops seeing them (see ./trustPolicies for why
+ * that is how every trust-supplied setting works here).
+ *
+ * On an id collision the SCHOOL's entry wins. Both keys are the same, so responses
+ * and aggregates land in the same place either way; what differs is that the school
+ * keeps the category it made, and keeps being able to edit it.
+ *
+ * @param {object} [school] the school's own institute doc.
+ * @param {object} [trust] the trust's institute doc, when the school is in one.
+ * @return {object} the merged map, and the ids the trust owns.
+ */
+export const resolveLeaverDestinations = (
+    school?: Pick<InstituteData, "leaverDestinations">,
+    trust?: Pick<InstituteData, "leaverDestinations">,
+): {destinations: LeaverDestinationMap, trustIds: string[]} => {
+    const own = school?.leaverDestinations ?? {};
+    const fromTrust = trust?.leaverDestinations ?? {};
+    const trustIds = Object.keys(fromTrust).filter((id) => !own[id]);
+    return {
+        destinations: {...fromTrust, ...own},
+        trustIds,
+    };
+};
+
+/**
+ * What to show for a stored destination — a standard label, or a school's own.
+ *
+ * A category defined by a DIFFERENT school (a student browsing trust-wide alumni
+ * meets these) isn't in the map we hold, so its id is turned back into words rather
+ * than shown raw: an id is derived from the label it was created with, which makes
+ * "custom_in_hospital" recoverable as "In hospital".
+ *
+ * @param {string} [code] the stored destination.
+ * @param {object} [customs] the institute's leaverDestinations map.
+ * @return {string|undefined} the display label.
+ */
+export const destinationLabel = (
+    code?: DestinationValue, customs?: LeaverDestinationMap,
+): string|undefined => {
+    if (!code) return undefined;
+    if (DESTINATION_CODES[code]) return DESTINATION_CODES[code];
+    const known = customs?.[code]?.label;
+    if (known) return known;
+    if (!code.startsWith(CUSTOM_DESTINATION_PREFIX)) return code;
+    const words = code.slice(CUSTOM_DESTINATION_PREFIX.length).replace(/_/g, " ").trim();
+    return words ? words.charAt(0).toUpperCase() + words.slice(1) : code;
+};
+
+/**
+ * The NCCIS code a stored destination counts within. Statutory exports and the
+ * NEET/NK figures go through this, never through the raw value.
+ *
+ * @param {string} [code] the stored destination.
+ * @param {object} [customs] the institute's leaverDestinations map.
+ * @return {DestinationCode|undefined} the NCCIS code to report it as.
+ */
+export const destinationNccisCode = (
+    code?: DestinationValue, customs?: LeaverDestinationMap,
+): DestinationCode|undefined => {
+    if (!code) return undefined;
+    if (DESTINATION_CODES[code]) return code as DestinationCode;
+    const custom = customs?.[code];
+    // An id we no longer recognise is still somebody's leaver: "not known" is the
+    // honest reading, and it keeps them in the cohort rather than dropping them.
+    if (!custom) return "NK";
+    return DESTINATION_CODES[custom.nccisCode] ? custom.nccisCode : "NEET";
+};
+
+/**
+ * Whether a destination is one of the two the school is trying to shrink. Custom
+ * categories count exactly as the NCCIS code they name does.
+ *
+ * @param {string} [code] the stored destination.
+ * @param {object} [customs] the institute's leaverDestinations map.
+ * @return {boolean} true for NEET / NK and anything mapped to them.
+ */
+export const isNegativeDestination = (
+    code?: DestinationValue, customs?: LeaverDestinationMap,
+): boolean => {
+    const nccis = destinationNccisCode(code, customs);
+    return Boolean(nccis && NEGATIVE_DESTINATION_CODES.includes(nccis));
+};
+
+/**
+ * Re-keys a `{destination: count}` aggregate onto the nine NCCIS codes, folding each
+ * custom category into its parent. For anything that has to report in NCCIS terms
+ * while the raw aggregate stays as granular as the school made it.
+ *
+ * @param {object} [counts] the raw aggregate.
+ * @param {object} [customs] the institute's leaverDestinations map.
+ * @return {object} counts keyed by NCCIS code.
+ */
+export const rollUpDestinationCounts = (
+    counts?: {[code: string]: number}, customs?: LeaverDestinationMap,
+): {[code: string]: number} => {
+    const out: {[code: string]: number} = {};
+    for (const [code, n] of Object.entries(counts ?? {})) {
+        const key = destinationNccisCode(code, customs) ?? "NK";
+        out[key] = (out[key] ?? 0) + (n ?? 0);
+    }
+    return out;
+};
+
+/**
+ * Validates a set of custom categories before it is stored. Shared by the setup card
+ * and the callable so both refuse the same things.
+ *
+ * @param {object} destinations the map to check.
+ * @return {string|undefined} the first problem found, or undefined if it's valid.
+ */
+export const validateLeaverDestinations = (destinations: LeaverDestinationMap): string|undefined => {
+    const entries = Object.entries(destinations ?? {});
+    if (entries.length > 50) return "You can add up to 50 destination categories.";
+    const seen = new Set<string>();
+    for (const [id, d] of entries) {
+        if (!d) return "One of your categories is empty.";
+        if (!DESTINATION_ID_PATTERN.test(id) || id !== d.id) return "A category id is invalid.";
+        if (!id.startsWith(CUSTOM_DESTINATION_PREFIX)) return "A category id is invalid.";
+        if (DESTINATION_CODES[id]) return "A category can't reuse a standard destination code.";
+        const label = (d.label ?? "").trim();
+        if (!label) return "Give every category a name.";
+        if (label.length > 60) return "Category names must be 60 characters or fewer.";
+        if (!DESTINATION_CODES[d.nccisCode]) return `Choose which group "${label}" counts within.`;
+        const key = label.toLowerCase();
+        if (seen.has(key)) return `You already have a category called "${label}".`;
+        // A category that duplicates a standard label would show twice in the picker
+        // with no way to tell them apart.
+        if (Object.values(DESTINATION_CODES).some((l) => l.toLowerCase() === key)) {
+            return `"${label}" is already a standard destination.`;
+        }
+        seen.add(key);
+    }
+    return undefined;
+};

package/src/index.ts

@@ -23,6 +23,7 @@ export * from "./groups";
 export * from "./emailSections";
 export * from "./exportTransformers";
 export * from "./compassExport";
+export * from "./destinations";
 export * from "./benchmarkEvidenceRules";
 export * from "./portfolioAggregate";
 export * from "./tutorialTips";

package/src/typeDefinitions.ts

@@ -1106,6 +1106,12 @@ export type InstituteData = {
     // Written by the setup wizard (aspirations-saveDestinationsConfig); read by
     // destinationsProvisionCron each September to create that year's surveys/groups.
     destinationsConfig?: DestinationsConfig,
+    /** School-defined leaver destination categories, keyed by id, added from the
+     * Destinations Setup tab. They sit alongside the nine NCCIS codes on every
+     * leaver form and each one names the NCCIS code it counts within, so a school
+     * can break "NEET" down into the situations it actually needs to track
+     * (in hospital, in care, in custody) without breaking statutory reporting. */
+    leaverDestinations?: {[id: string]: LeaverDestination},
     /** Trust-authored policy, one entry per feature a trust can impose on the schools
      * beneath it. Set on the TRUST's own institute doc and read by its schools through
      * their approved trust link — never copied onto the school, so there is one source
@@ -2188,6 +2194,47 @@ export type ExternalEventRequest = {
 /** NCCIS-compatible destination activity codes (MI Requirement 2026–27) */
 export type DestinationCode = "HE"|"FE"|"APP"|"EWBL"|"EMP"|"VOL"|"OTH"|"NEET"|"NK";
 
+/**
+ * A destination as it is actually stored on a response, an alumni record or a
+ * cycle aggregate: one of the nine NCCIS codes above, or the id of a school-defined
+ * category from `InstituteData.leaverDestinations`.
+ *
+ * Custom categories exist because NCCIS's NEET and NK are a single bucket for very
+ * different situations — a SEND leaver in hospital, in care or in custody is "NEET"
+ * to the local authority and nothing more, which is exactly the granularity schools
+ * lose. Every custom category still carries the NCCIS code it counts within
+ * (`LeaverDestination.nccisCode`), so statutory returns are unaffected: only the
+ * school's own reporting gets finer.
+ *
+ * The `(string & {})` half keeps editor autocomplete for the nine standard codes
+ * while still accepting a custom id.
+ */
+// eslint-disable-next-line @typescript-eslint/ban-types
+export type DestinationValue = DestinationCode | (string & {});
+
+/**
+ * A school-defined leaver destination category, stored on
+ * `InstituteData.leaverDestinations` keyed by `id`.
+ *
+ * `id` is what lands in responses and in `aggregates.destinations.<id>`, so it is
+ * restricted to `[A-Za-z0-9_]` (see DESTINATION_ID_PATTERN) — a Firestore field path
+ * segment can't contain a dot or a slash, and these keys become one.
+ */
+export type LeaverDestination = {
+    id: string,
+    label: string,
+    /** Which of the nine NCCIS codes this rolls up into for statutory reporting. */
+    nccisCode: DestinationCode,
+    /** Optional helper text shown under the option on the leaver forms. */
+    description?: string,
+    /** Removed from the forms, but kept here so records and charts that already
+     * carry the id keep their label. Deleting outright would leave past responses
+     * showing a raw id. */
+    archived?: boolean,
+    createdAt?: string,
+    createdBy?: string,
+}
+
 /** SOC 2020 major group number */
 export type SOCMajorGroup = 1|2|3|4|5|6|7|8|9;
 
@@ -2235,7 +2282,7 @@ export type ApprenticeshipDetails = {
  * Appended on every check-in; source distinguishes self-report from staff/trusted-contact entry.
  */
 export type CheckInEntry = {
-    destinationCode: DestinationCode,
+    destinationCode: DestinationValue,
     type?: "annual"|"midYear"|"leaverTransition"|"resultsDay"|"christmas",   // Timepoint type; defaults to "annual"
     sector?: string,
     date: string,             // ISO date string
@@ -2559,7 +2606,7 @@ export type LeaverTransitionData = {
     activities?: string[],
 
     // Destination (NCCIS / Gatsby BM3)
-    intendedDestination: DestinationCode,
+    intendedDestination: DestinationValue,
     intendedDestinationDetails?: EducationDetails|EmploymentDetails|ApprenticeshipDetails,
     intendedStartDate?: string,
 
@@ -2606,7 +2653,7 @@ export type LeaverConsentCapture = {
  */
 export type LeaverCheckpointResponse = {
     checkpoint: "resultsDay"|"christmas",
-    destination: DestinationCode,
+    destination: DestinationValue,
     destinationDetails?: EducationDetails|EmploymentDetails|ApprenticeshipDetails,
     /** resultsDay only — did results change their plan vs intendedDestination? */
     changedFromIntended?: boolean,
@@ -2680,13 +2727,13 @@ export type Alumni = {
 
     // Destination tracking
     /** Intended destination captured via Form B before leaving */
-    intendedDestination?: DestinationCode,
+    intendedDestination?: DestinationValue,
     intendedDestinationDetails?: EducationDetails|EmploymentDetails|ApprenticeshipDetails,
     intendedStartDate?: string,
     /** October confirmed actual destination snapshot */
-    confirmedDestination?: DestinationCode,
+    confirmedDestination?: DestinationValue,
     /** Most recent known destination — updated on each check-in */
-    currentDestination?: DestinationCode,
+    currentDestination?: DestinationValue,
 
     // Legacy fields — retained for backwards compatibility; use CheckInEntry going forward
     sector?: string,