Young Americans Are Choosin’ Texas. But Gen Zers Are Moving To San Antonio and Austin, While Millennials Favor Houston

const migration = await d3.csv(
`${base}/${cfg.migrationFile}`,
parseMigration
);

return { migration };
};

App = App || {};
App.metroCoords = {
10420: [-81.519, 41.081],
10580: [-73.756, 42.653],
10740: [-106.65, 35.084],
10900: [-75.49, 40.608],
11100: [-101.831, 35.222],
11260: [-149.9, 61.218],
11460: [-83.743, 42.281],
11700: [-82.552, 35.595],
12060: [-84.388, 33.749],
12220: [-85.481, 32.61],
12260: [-82.011, 33.474],
12420: [-97.743, 30.267],
12540: [-119.019, 35.373],
12580: [-76.612, 39.29],
12700: [-70.3, 41.7],
12940: [-91.187, 30.452],
13140: [-94.127, 30.08],
13380: [-122.479, 48.752],
13820: [-86.81, 33.519],
14010: [-88.994, 40.484],
14260: [-116.202, 43.615],
14460: [-71.059, 42.36],
14740: [-122.633, 47.567],
14860: [-73.195, 41.187],
15380: [-78.878, 42.886],
15940: [-81.378, 40.799],
15980: [-81.95, 26.563],
16580: [-88.243, 40.116],
16700: [-79.931, 32.777],
16740: [-80.843, 35.227],
16860: [-85.31, 35.046],
16980: [-87.63, 41.878],
17020: [-121.838, 39.729],
17140: [-84.512, 39.103],
17300: [-87.36, 36.53],
17460: [-81.694, 41.499],
17780: [-96.334, 30.628],
17820: [-104.821, 38.834],
17860: [-92.334, 38.952],
17900: [-81.035, 34.001],
18140: [-82.999, 39.961],
18580: [-97.396, 27.801],
18880: [-86.57, 30.766],
19100: [-96.797, 32.777],
19660: [-81.264, 28.901],
19740: [-104.99, 39.739],
19780: [-93.625, 41.587],
19820: [-83.046, 42.331],
21340: [-106.485, 31.762],
21500: [-80.085, 42.129],
21660: [-123.087, 44.052],
22180: [-94.172, 36.082],
22220: [-78.878, 35.053],
22380: [-111.651, 35.198],
22660: [-105.084, 40.585],
23060: [-85.139, 41.079],
23420: [-119.787, 36.738],
23540: [-82.325, 29.652],
23580: [-97.133, 33.632],
24340: [-85.668, 42.963],
24660: [-79.792, 36.073],
24780: [-77.366, 35.613],
24860: [-82.394, 34.853],
25060: [-89.093, 30.367],
25260: [-119.646, 36.327],
25420: [-76.887, 40.273],
25540: [-72.685, 41.766],
25940: [-80.753, 32.216],
26420: [-95.37, 29.76],
26900: [-86.158, 39.768],
26980: [-91.53, 41.661],
27060: [-76.502, 42.444],
27140: [-90.185, 32.299],
27260: [-81.656, 30.332],
28020: [-85.587, 42.292],
28140: [-94.579, 39.1],
28940: [-83.921, 35.961],
29180: [-92.02, 30.224],
29200: [-86.875, 40.417],
29420: [-114.322, 34.484],
29460: [-81.95, 28.04],
29540: [-76.306, 40.038],
29620: [-84.556, 42.733],
29740: [-106.764, 32.32],
29820: [-115.14, 36.17],
29940: [-95.235, 38.972],
30700: [-96.703, 40.814],
30780: [-92.29, 34.747],
31080: [-118.244, 34.052],
31140: [-85.759, 38.253],
31180: [-101.855, 33.578],
31340: [-79.142, 37.414],
31460: [-120.061, 36.961],
32580: [-98.23, 26.203],
32820: [-90.049, 35.15],
32900: [-120.483, 37.302],
33100: [-80.192, 25.762],
33260: [-102.078, 31.997],
33340: [-87.907, 43.039],
33460: [-93.265, 44.978],
33660: [-88.04, 30.695],
33700: [-120.997, 37.639],
33860: [-86.279, 32.362],
34820: [-78.887, 33.689],
34900: [-122.287, 38.298],
34940: [-81.795, 26.142],
34980: [-86.782, 36.163],
35300: [-72.928, 41.308],
35380: [-90.072, 29.951],
35620: [-74.006, 40.713],
35840: [-82.236, 27.044],
35980: [-72.076, 41.524],
36100: [-82.14, 29.187],
36260: [-111.974, 41.223],
36420: [-97.516, 35.468],
36500: [-122.901, 47.038],
36540: [-95.935, 41.257],
36740: [-81.379, 28.538],
37100: [-119.177, 34.198],
37340: [-80.589, 28.035],
37460: [-85.66, 30.159],
37860: [-87.217, 30.421],
37980: [-75.165, 39.953],
38060: [-112.074, 33.448],
38300: [-79.996, 40.441],
38860: [-70.257, 43.659],
38900: [-122.675, 45.505],
38940: [-80.35, 27.294],
39300: [-71.413, 41.824],
39340: [-111.659, 40.234],
39460: [-82.045, 26.93],
39580: [-78.638, 35.78],
39740: [-75.927, 40.336],
39900: [-119.814, 39.53],
40060: [-77.436, 37.541],
40140: [-117.376, 33.981],
40220: [-79.941, 37.271],
40380: [-77.609, 43.157],
40420: [-89.094, 42.271],
40900: [-121.494, 38.582],
41060: [-94.163, 45.558],
41180: [-90.199, 38.627],
41420: [-123.035, 44.943],
41500: [-121.656, 36.678],
41540: [-75.599, 38.361],
41620: [-111.891, 40.761],
41660: [-100.437, 31.464],
41700: [-98.494, 29.424],
41740: [-117.161, 32.716],
41860: [-122.419, 37.775],
41940: [-121.886, 37.338],
42020: [-120.66, 35.283],
42100: [-122.031, 36.974],
42200: [-120.436, 34.953],
42220: [-122.714, 38.44],
42540: [-75.662, 41.409],
42660: [-122.332, 47.606],
43900: [-81.932, 34.95],
44060: [-117.426, 47.659],
44140: [-72.59, 42.102],
44180: [-93.292, 37.209],
44700: [-121.291, 37.958],
45300: [-82.457, 27.951],
45780: [-83.555, 41.664],
45940: [-74.743, 40.217],
46060: [-110.975, 32.223],
46140: [-95.993, 36.154],
46220: [-87.569, 33.21],
46520: [-157.858, 21.307],
46700: [-122.257, 38.104],
47260: [-75.978, 36.853],
47300: [-119.292, 36.33],
47380: [-97.147, 31.549],
47900: [-77.037, 38.907],
48620: [-97.33, 37.687],
48660: [-98.493, 33.914],
48900: [-77.945, 34.226],
49340: [-71.802, 42.263],
49620: [-76.728, 39.963],
49660: [-80.65, 41.1],
49740: [-114.628, 32.693]
};

App = App || {};
App.data = App.data || {};

App.data.createModel = function createModel(raw) {
const migrationByKey = new Map();
const migrationByGenerationYear = new Map();

const add = (map, key, row) => {
if (!map.has(key)) map.set(key, []);
map.get(key).push(row);
};

for (const row of raw.migration) {
migrationByKey.set(`${row.met}|${row.year}|${row.gen_cat}`, row);
add(migrationByGenerationYear, `${row.year}|${row.gen_cat}`, row);
}

return {
raw,

migration(met, year, generation) {
return migrationByKey.get(`${met}|${year}|${generation}`) ?? null;
},

migrationForGeneration(year, generation) {
return migrationByGenerationYear.get(`${year}|${generation}`) ?? [];
}
};
};

App = App || {};
App.map = App.map || {};

App.map.loadUsAtlas = async function loadUsAtlas() {
// Development loads the vendored JSON file; build.py inlines it into App.US_ATLAS.
if (App.US_ATLAS) return App.US_ATLAS;
return d3.json(“./vendor/states-10m.json”);
};

App = App || {};
App.map = App.map || {};

// Shared brand palette. Rocket’s own semantic-palette rule: positive is
// green, negative is orange, never red – and a genuine neutral/near-zero
// band gets blue, not a fallback for exact 0. Every pair touching the
// neutral band clears both colorblind and normal-vision separation floors
// by a wide margin, because blue sits far from the orange/green axis that
// colorblind viewers struggle with most. A plain orangegreen split with
// no neutral band would put mild-loss and mild-gain directly adjacent at
// the zero boundary, where they’re hard to tell apart even for colorblind
// viewers – inserting the neutral band separates them so they’re never
// adjacent.
const RATE_STEPS = [-0.03, -0.015, -0.005, 0.005, 0.015, 0.03];
const RATE_COLORS = [
“#df5106”, // = +3% heavy gain
];
const COUNT_COLOR_GAIN = “#187549”; // heavy-gain green
const COUNT_COLOR_LOSS = “#df5106”; // heavy-loss orange

// Fixed editorial highlight list per generation – always these metros, in
// both views, regardless of year. Not derived from the data, so update by
// hand if the story changes.
const HIGHLIGHT_METROS = {
“Gen Z”: [“San Antonio, TX”, “Washington, DC”, “Austin, TX”, “New York, NY”, “Los Angeles, CA”, “Minneapolis, MN”, “San Francisco, CA”, “Orlando, FL”, “Charleston, SC”],
“Millennial”: [“Houston, TX”, “Dallas, TX”, “New York, NY”, “Los Angeles, CA”, “Miami, FL”, “Las Vegas, NV”, “San Francisco, CA”, “Atlanta, GA”]
};

// Below this width, drop these labels from HIGHLIGHT_METROS entirely
// rather than keep tuning collision avoidance for the narrowest supported
// screens – simpler and more predictable than fighting for space in an
// already-crowded corner (both sit close to other highlighted metros:
// Las Vegas near LA/San Francisco, Atlanta near Miami/New York). The
// underlying circle and tooltip are untouched – only the direct text
// label is dropped, so the data itself is never hidden, just its
// editorial label at this size.
const MOBILE_HIDE_BREAKPOINT = 400;
const MOBILE_HIDDEN_METROS = {
“Millennial”: [“Atlanta, GA”, “Las Vegas, NV”]
};

// Metros that get the bespoke callout (a plain title label + a colored
// value line + a leader to the circle) instead of a plain metro-label.
// Same per-generation config shape as HIGHLIGHT_METROS/HEADLINE_TEXT – add
// more here later without new plumbing. A callout metro is excluded from
// the plain-label set so the two don’t fight over the same space.
// `direction` picks where the label sits relative to the circle and is one
// of six values:
// – “left” / “right” – label at the same height as the circle, straight
// leader, no curve.
// – “top-left” / “top-right” / “bottom-left” / “bottom-right” – label
// offset diagonally from the circle (see CALLOUT_DIRECTION_VECTORS), a
// curved leader that lands on that same diagonal edge of the circle
// (not its horizontal center).
// `label` is an optional override of the usual state-stripped label text –
// San Antonio needs its “TX” kept because its neighbor Austin is close
// enough that “San Antonio” alone would read ambiguously next to it.
const CALLOUT_METROS = {
“Gen Z”: [
{ metro: “San Antonio, TX”, direction: “left”, },
{ metro: “New York, NY”, direction: “bottom-right” }
],
“Millennial”: [
{ metro: “Houston, TX”, direction: “right” },
{ metro: “Dallas, TX”, direction: “left” },
{ metro: “Los Angeles, CA”, direction: “bottom-right” },
{ metro: “New York, NY”, direction: “top-left” }
]
};

// Fixed editorial headline + subtitle per generation – supplied copy, not
// computed from the data. Update by hand if the story changes. `subtitle`
// explains the count view’s own metric (net inflow/outflow) and is
// generation-specific; the rate view uses RATE_SUBTITLE instead (see
// renderHeader) – generic across generations, since the rate metric’s
// definition doesn’t change with who’s being counted.
const HEADLINE_TEXT = {
“Gen Z”: {
headline: “Gen Zers Are Heading to San Antonio, and Leaving New York”,
subtitle: “Net inflow = How many more Gen Zers are moving into a metro area than moving out. Net outflow = How many more Gen Zers are leaving a metro area than moving in.”
},
“Millennial”: {
headline: “Millennials Are Flowing Into Big Texas Cities, Leaving New York and Los Angeles”,
subtitle: “Net inflow = How many more millennials are moving into a metro area than moving out. Net outflow = How many more millennials are leaving a metro area than moving in.”
}
};

const RATE_SUBTITLE = “Net migration rate = net movers as a share of the metro population. Positive values mean more people moved in than out; negative values mean more moved out than in.”;

// Count-view circles are much bigger and overlap more than rate-view’s
// fixed 8px dots, so they need to be more transparent for a dense cluster
// to still read as distinct, stacked marks under the multiply blend.
const FILL_OPACITY = { rate: 0.78, count: 0.45 };

// Circle radii – module-level (not derived from data) so the horizontal
// margin calculation can use them before the projection is built.
const CIRCLE_R = 8;
const CIRCLE_R_HOVER = 15;
const MIN_COUNT_R = 4;
const MAX_COUNT_R = 28;

// Direct-label text drops the state abbreviation (“New York, NY” -> “New
// York”) – the tooltip still has the full name. Washington is the one
// exception: “Washington” alone is ambiguous, so it keeps its qualifier.
function labelTextFor(metro) {
if (metro === “Washington, DC”) return “Washington, D.C.”;
return metro.replace(/,\s*[A-Z]{2}$/, “”);
}

App.map.renderExample = async function renderExample(container, options) {
const { data, generation, year, mode = “rate”, setMode } = options;

const width = Math.max(320, container.clientWidth || 800);
const us = await App.map.loadUsAtlas();

// Below MOBILE_BREAKPOINT, shrink every circle radius proportionally to
// how much narrower the container is than that – the desktop sizes
// (CIRCLE_R, CIRCLE_R_HOVER, MIN_COUNT_R, MAX_COUNT_R) are tuned for a
// wide map and read as oversized/crowded at phone widths if used as-is.
// Floored at MOBILE_MIN_SCALE so circles never shrink to the point of
// being unreadable/untappable on the smallest supported width (320px).
const MOBILE_BREAKPOINT = 640;
const MOBILE_MIN_SCALE = 0.6;
const circleScale = width >= MOBILE_BREAKPOINT
? 1
: Math.max(MOBILE_MIN_SCALE, width / MOBILE_BREAKPOINT);
const maxCountR = MAX_COUNT_R * circleScale;
const minCountR = MIN_COUNT_R * circleScale;

// Plain metro-label text needs a gentler floor than the circles – it
// still has to stay legible, not just small – so it shrinks less
// aggressively than circleScale. Mirrors the .metro-label font-size
// knocked down in the matching @media rule in styles.css; keep the two
// in sync, since this is what the label-placement collision math
// actually measures against.
const LABEL_MIN_SCALE = 0.82;
const labelScale = width >= MOBILE_BREAKPOINT
? 1
: Math.max(LABEL_MIN_SCALE, width / MOBILE_BREAKPOINT);

// Fit the projection to the container’s actual width instead of a hand-
// tuned scale/translate guess, which would need re-tuning per width and
// still drift out of alignment. fitWidth guarantees a bounding box
// touches x=0 and x=width exactly – but fit to *every* state
// including Alaska and Hawaii, their bottom-left insets are the ones that
// touch x=0 (Alaska’s, specifically), pushing the mainland’s own left edge
// ~70-100px inward – visually a “gap” between the headline (flush left)
// and the mainland coast. None of this story’s highlighted metros are in
// AK/HI, so fit to the contiguous 48 only; Alaska’s inset still renders
// whatever falls out of that (usually landing slightly left of x=0, i.e.
// very slightly clipped at the edge) – a standard, acceptable tradeoff so
// the mainland – what the story is actually about – aligns with the text.
//
// A coastal metro’s circle is centered ON the coastline, so with no
// margin its edge would cross x=0/x=width and get clipped by the SVG’s
// own boundary – worse in the count view, where a coastal metro can be
// the single biggest circle (radius up to MAX_COUNT_R). H_MARGIN is sized
// to the largest circle *either* mode can draw and used unconditionally –
// fit to CONUS at width-2*H_MARGIN, then the whole projection is shifted
// right by H_MARGIN, so CONUS ends up centered in [H_MARGIN,
// width-H_MARGIN]. Deliberately mode-independent even though the rate
// view’s fixed 8px dots don’t need this much room: using the same margin
// (and therefore the same innerWidth) in both modes makes the map’s own
// fitted height identical between modes too – one less thing that jumps
// when switching the dropdown.
const H_MARGIN = maxCountR + 4;
const innerWidth = Math.max(100, width – 2 * H_MARGIN);
const statesFC = topojson.feature(us, us.objects.states);
const conusFC = {
type: “FeatureCollection”,
features: statesFC.features.filter(f => f.id !== “02” && f.id !== “15”)
};
const projection = d3.geoAlbersUsa().fitWidth(innerWidth, conusFC);
const [t0, t1] = projection.translate();
projection.translate([t0 + H_MARGIN, t1]);
const path = d3.geoPath(projection);
const [[, boundsY0], [, boundsY1]] = path.bounds(conusFC);
const height = Math.max(360, Math.ceil(boundsY1 – boundsY0));

const circleR = CIRCLE_R * circleScale;
const circleRLarge = CIRCLE_R_HOVER * circleScale;

// Selection: the 15 largest net gains + 15 largest net losses (by migrant
// count) per generation. Shared by both views, so switching views doesn’t
// change which 30 metros are on the map – only how they’re drawn. Keep
// this in one place so the count is easy to change later.
const SELECTION_COUNT = 20;
const withCoords = data
.map(d => {
const coord = App.metroCoords?.[d.met];
return coord ? { …d, lon: coord[0], lat: coord[1] } : null;
})
.filter(Boolean);

const gains = withCoords
.filter(d => d.net > 0)
.sort((a, b) => b.net – a.net)
.slice(0, SELECTION_COUNT);
const losses = withCoords
.filter(d => d.net a.net – b.net)
.slice(0, SELECTION_COUNT);
const displayData = […gains, …losses];

// Direct labels are reserved for a fixed editorial list of metros (same
// list in both views – see HIGHLIGHT_METROS). Everything else (all 30
// points, in both views) is still fully available in the tooltip. A
// highlighted metro that didn’t make this year’s top-15/15 selection is
// simply not on the map, so it’s silently skipped here. Below
// MOBILE_HIDE_BREAKPOINT, a couple of editorial labels are dropped
// outright too (see MOBILE_HIDDEN_METROS) – their circle stays, only
// the direct text label goes.
const hiddenOnMobile = width !hiddenOnMobile || !hiddenOnMobile.has(m))
);
const labeledMets = new Set(
displayData.filter(d => highlightNames.has(d.metro)).map(d => d.met)
);

// Scales are computed before anything is drawn, so the key row (which
// renders above the map) and the map itself always agree.
const rateColor = d3.scaleThreshold().domain(RATE_STEPS).range(RATE_COLORS);

// Area-proportional size scale for the count view (radius ~ sqrt(count),
// not count itself, so the reader compares areas honestly). A small floor
// keeps the smallest metros visible and clickable.
const maxAbsNet = d3.max(displayData, d => Math.abs(d.net)) || 1;
const sizeScale = d3.scaleSqrt().domain([0, maxAbsNet]).range([0, maxCountR]);
const countRadius = d => Math.max(minCountR, sizeScale(Math.abs(d.net)));

function radiusOf(d) {
return mode === “count” ? countRadius(d) : circleR;
}
function fillOf(d) {
if (mode === “count”) return d.net >= 0 ? COUNT_COLOR_GAIN : COUNT_COLOR_LOSS;
return rateColor(d.net_rate);
}

container.innerHTML = “”;

const shell = d3.select(container)
.append(“div”)
.attr(“class”, “map-panel”);

renderHeader(shell, generation, mode);
renderKeyRow(shell, mode, sizeScale, setMode);

// The rate view’s stepped color bar is a footer below the map; the count
// view has no equivalent content there. renderRateLegend still appends
// the same `.rate-legend` wrapper either way (just leaves it empty in
// count mode) – `.rate-legend`’s CSS min-height reserves the same space
// regardless, so switching modes doesn’t change the page’s height.
renderRateLegend(shell, mode, rateColor);

const svg = shell.append(“svg”)
.attr(“viewBox”, `0 0 ${width} ${height}`)
.attr(“role”, “img”)
.attr(
“aria-label”,
mode === “count”
? `${generation} migration map for ${year}. Circle size represents net migration count; color represents gain or loss.`
: `${generation} migration map for ${year}. Circle color represents net migration rate.`
);

// Small light-gray affordance sitting in the blank vertical space the
// fitted map often leaves above the states themselves (height is floored
// at 360px, but the actual projected CONUS is frequently shorter than
// that at typical widths – see the `height` calculation above) – tells
// the reader the circles are interactive. Native SVG text, not an HTML
// block above the map, so it sits inside that space instead of pushing
// the map down the page.
// On phones the map itself sits closer to the top of its own container
// (less unrelated chrome above it), so this hint reads better nudged up
// a bit further rather than keeping the same fixed offset used at
// desktop widths – and “hover” isn’t a real touchscreen gesture, so the
// copy swaps to “tap” there too (font-size itself is handled in CSS via
// a matching @media rule, not here).
const isMobile = width a !== b))
.attr(“class”, “state-border”)
.attr(“d”, path);

const plotted = displayData
.map(d => {
const point = projection([d.lon, d.lat]);
return point ? { …d, x: point[0], y: point[1] } : null;
})
.filter(Boolean);

const tooltip = App.ui.createTooltip(container);

const calloutConfig = new Map(
(CALLOUT_METROS[generation] || []).map(c => [c.metro, c])
);
const labeled = plotted.filter(d => labeledMets.has(d.met) && !calloutConfig.has(d.metro));
const calloutPoints = plotted.filter(d => calloutConfig.has(d.metro));
const allCircles = plotted.map(d => ({ cx: d.x, cy: d.y, r: radiusOf(d) }));

const metroLayer = svg.append(“g”).attr(“class”, “metro-layer”);

metroLayer.selectAll(“circle.metro-dot”)
.data(plotted, d => d.met)
.join(“circle”)
.attr(“class”, “metro-dot”)
.attr(“cx”, d => d.x)
.attr(“cy”, d => d.y)
.attr(“r”, radiusOf)
.attr(“fill”, fillOf)
.style(“fill-opacity”, FILL_OPACITY[mode])
.attr(“stroke”, “#ffffff”)
.attr(“stroke-width”, 1.2)
.attr(“tabindex”, 0)
.attr(“aria-label”, d => `${d.metro}: ${formatSignedNumber(d.net)} net migrants, ${formatSignedRate(d.net_rate)} net migration rate`)
.on(“pointerenter focus”, function (event, d) {
showTooltip(event, d);
const hoverR = radiusOf(d) + (mode === “count” ? 3 : circleRLarge – circleR);
d3.select(this).attr(“r”, hoverR).attr(“stroke-width”, 1.8);
// Called-out metros also have a highlight ring drawn on top (see
// below) – grow it with the dot, or its outline stays a fixed size
// while the fill underneath expands. A no-op for every other metro,
// which has no matching ring to select.
metroLayer.selectAll(“circle.metro-dot-callout-ring”)
.filter(rd => rd.met === d.met)
.attr(“r”, hoverR);
})
.on(“pointermove”, moveTooltip)
.on(“pointerleave blur”, function (event, d) {
tooltip.hidden = true;
d3.select(this).attr(“r”, radiusOf(d)).attr(“stroke-width”, 1.2);
metroLayer.selectAll(“circle.metro-dot-callout-ring”)
.filter(rd => rd.met === d.met)
.attr(“r”, radiusOf(d));
});

// Highlight ring for called-out metros only (see CALLOUT_METROS): a
// stroke in the dot’s own fill color, at the default full stroke
// opacity – reads as a darker edge against the dot’s own fill (which
// sits at FILL_OPACITY[mode], well under 1) without touching the white
// halo every base dot already has.
metroLayer.selectAll(“circle.metro-dot-callout-ring”)
.data(calloutPoints, d => d.met)
.join(“circle”)
.attr(“class”, “metro-dot-callout-ring”)
.attr(“cx”, d => d.x)
.attr(“cy”, d => d.y)
.attr(“r”, radiusOf)
.attr(“stroke”, fillOf)
.attr(“stroke-width”, 2 * circleScale);

// Place each label (metro name only – no value, so it can sit close to
// its circle) in whichever of 8 directions around its circle first clears
// every circle on the map, every label already placed, AND the canvas
// edge itself (see placeLabels) – so a coastal metro like New York
// automatically falls back to “left”/”upper-left” instead of overflowing
// past x=width. Labels for the biggest circles are placed first (hardest
// to fit), so they get first pick of the clear space.
const labelPlacements = placeLabels(
labeled.map(d => ({ met: d.met, cx: d.x, cy: d.y, r: radiusOf(d), text: labelTextFor(d.metro) })),
allCircles,
{ x0: 0, y0: 0, x1: width, y1: height },
labelScale
);

svg.append(“g”)
.attr(“class”, “metro-label-layer”)
.selectAll(“text.metro-label”)
.data(labelPlacements, d => d.met)
.join(“text”)
.attr(“class”, “metro-label”)
.attr(“x”, d => d.x)
.attr(“y”, d => d.y)
.attr(“text-anchor”, d => d.anchor)
.text(d => d.text);

if (calloutPoints.length) {
calloutPoints.forEach(d => {
const isGain = d.net_rate >= 0;
const config = calloutConfig.get(d.metro);
renderCallout(svg, {
cx: d.x,
cy: d.y,
r: radiusOf(d),
title: config.label || labelTextFor(d.metro),
value: mode === “count” ? formatSignedNumber(d.net) : formatSignedRate(d.net_rate),
sign: isGain ? “gain” : “loss”,
direction: config.direction,
showLeader: mode !== “count”,
canvasWidth: width,
circleScale
});
});
}

function showTooltip(event, d) {
// Only the metric the current view actually encodes – not both. The
// other metric is still there, one tab away, not hidden entirely.
const label = mode === “count” ? “Net migration count” : “Net migration rate”;
const value = mode === “count” ? formatSignedNumber(d.net) : formatSignedRate(d.net_rate);

tooltip.replaceChildren();

const title = document.createElement(“div”);
title.className = “tooltip-title”;
title.textContent = d.metro;

const valueEl = document.createElement(“div”);
valueEl.className = “tooltip-value”;
valueEl.textContent = value;

tooltip.append(title, valueEl);
tooltip.hidden = false;
moveTooltip(event);
}

function moveTooltip(event) {
if (!event || event.clientX == null) return;
const rect = container.getBoundingClientRect();
const x = event.clientX – rect.left;
const y = event.clientY – rect.top;
const GAP = 12;

// Flip to the left of the cursor when there isn’t room on the right
// (coastal-east metros, e.g. New York) – otherwise the tooltip’s own
// width would push it past the container edge and get clipped/hidden.
// tooltip.offsetWidth is real here: showTooltip already set innerHTML
// and hidden=false before calling this.
const tw = tooltip.offsetWidth;
const fitsRight = x + GAP + tw <= rect.width;
tooltip.style.left = fitsRight ? `${x + GAP}px` : `${Math.max(0, x – GAP – tw)}px`;
tooltip.style.top = `${Math.max(0, y – 18)}px`;
}
};

// Editorial headline + subtitle, replacing the old plain centered title.
// Fixed copy from HEADLINE_TEXT – see that constant to change the story.
// Subtitle depends on `mode` too – see RATE_SUBTITLE.
function renderHeader(shell, generation, mode) {
const copy = HEADLINE_TEXT[generation] || HEADLINE_TEXT["Gen Z"];
const subtitle = mode === "rate" ? RATE_SUBTITLE : copy.subtitle;

const header = shell.append("div").attr("class", "map-header");
const textCol = header.append("div").attr("class", "map-header-text");
textCol.append("h2").attr("class", "map-headline").text(copy.headline);
textCol.append("p").attr("class", "map-subtitle").text(subtitle);

}

// A custom button + popup listbox, not a native , so the open
// panel can actually be styled (checkmark, rounded shadowed panel,
// divider – see styles.css) instead of whatever the browser’s own
// unstylable dropdown list happens to look like.
const MODE_OPTIONS = [
{ key: “count”, label: “Net migration count” },
{ key: “rate”, label: “Net migration rate” }

];

function renderModeSelect(container, mode, setMode) {
const wrap = container.append(“div”).attr(“class”, “mode-select-wrap”);
const current = MODE_OPTIONS.find(o => o.key === mode) || MODE_OPTIONS[0];

const button = wrap.append(“button”)
.attr(“type”, “button”)
.attr(“class”, “mode-select-button”)
.attr(“aria-haspopup”, “listbox”)
.attr(“aria-expanded”, “false”)
.attr(“aria-label”, “Map view”);
button.append(“span”).attr(“class”, “mode-select-label”).text(current.label);
button.append(“span”).attr(“class”, “mode-select-caret”).attr(“aria-hidden”, “true”);

const list = wrap.append(“ul”)
.attr(“class”, “mode-select-list”)
.attr(“role”, “listbox”)
.attr(“hidden”, true);

// Document-level listeners only exist while the panel is open, and are
// torn down the moment it closes (by selection, Escape, or an outside
// click) – the whole graphic re-renders from scratch on most triggers
// that would otherwise matter here (mode change, resize), so this is
// the one path that needs explicit cleanup to avoid leaking a listener
// that closes over now-detached nodes.
let onDocClick = null;
let onKeydown = null;

function closeList() {
list.attr(“hidden”, true);
button.attr(“aria-expanded”, “false”);
if (onDocClick) { document.removeEventListener(“click”, onDocClick, true); onDocClick = null; }
if (onKeydown) { document.removeEventListener(“keydown”, onKeydown); onKeydown = null; }
}

function openList() {
list.attr(“hidden”, null);
button.attr(“aria-expanded”, “true”);
onDocClick = event => {
// Self-cleans if a re-render elsewhere detached this dropdown while
// it was open, instead of leaking the listener forever.
if (!document.body.contains(wrap.node()) || !wrap.node().contains(event.target)) closeList();
};
onKeydown = event => {
if (event.key === “Escape”) { closeList(); button.node().focus(); }
};
document.addEventListener(“click”, onDocClick, true);
document.addEventListener(“keydown”, onKeydown);
}

button.on(“click”, event => {
event.stopPropagation();
button.attr(“aria-expanded”) === “true” ? closeList() : openList();
});

list.selectAll(“li”)
.data(MODE_OPTIONS)
.join(“li”)
.attr(“class”, d => `mode-select-option${d.key === mode ? ” is-selected” : “”}`)
.attr(“role”, “option”)
.attr(“aria-selected”, d => d.key === mode ? “true” : “false”)
.on(“click”, (event, d) => {
event.stopPropagation();
closeList();
if (d.key !== mode && typeof setMode === “function”) setMode(d.key);
})
.each(function (d) {
const li = d3.select(this);
li.append(“span”).text(d.label);
if (d.key === mode) {
li.append(“span”).attr(“class”, “mode-select-check”).attr(“aria-hidden”, “true”).text(“✓”);
}
});
}

// The row above the map: dropdown always centered; count view adds the
// Gain/Loss color key on the left and the nested size key on the right.
// Rate view leaves both side slots empty so the dropdown still centers.
function renderKeyRow(shell, mode, sizeScale, setMode) {
const row = shell.append(“div”).attr(“class”, “key-row”);
const left = row.append(“div”).attr(“class”, “key-row-left”);
const center = row.append(“div”).attr(“class”, “key-row-center”);
const right = row.append(“div”).attr(“class”, “key-row-right”);

if (mode === “count”) {
const colorKey = left.append(“div”).attr(“class”, “count-color-key”);
colorKey.append(“span”).attr(“class”, “count-swatch count-swatch-gain”);
colorKey.append(“span”).attr(“class”, “count-key-label”).text(“Inflow”);
colorKey.append(“span”).attr(“class”, “count-swatch count-swatch-loss”);
colorKey.append(“span”).attr(“class”, “count-key-label”).text(“Outflow”);
}

renderModeSelect(center, mode, setMode);

if (mode === “count”) {
renderSizeKey(right, sizeScale);
}
}

// Nested, bottom-tangent size key: the largest reference circle drawn
// first, smaller ones nested inside it, all sharing the same bottom edge,
// each pointed to by a leader line. Neutral gray – size applies to both
// gain and loss alike.
function renderSizeKey(container, sizeScale) {
const [maxDomain] = sizeScale.domain().slice(-1);
const refValues = d3.ticks(0, maxDomain, 3).filter(v => v > 0).sort((a, b) => b – a);
const radii = refValues.map(v => Math.max(sizeScale(v), 4));
const maxR = Math.max(…radii);

const LEADER = 14; // horizontal leader-line length
const LABEL_W = 64; // reserved width for each label
const svgWidth = maxR * 2 + LEADER + LABEL_W + 8;
const svgHeight = maxR * 2 + 8;
const baseline = svgHeight – 4; // bottom tangent line every circle shares
const cx = maxR + 4;

const sizeSvg = container.append(“svg”)
.attr(“class”, “count-size-key”)
.attr(“aria-hidden”, “true”)
// Override the page’s global `svg { width: 100% }` rule – this legend
// graphic is sized to its content, not the container.
.style(“width”, `${svgWidth}px`)
.style(“height”, `${svgHeight}px`)
.attr(“width”, svgWidth)
.attr(“height”, svgHeight);

// Largest circle first (drawn in back), so smaller reference circles nest
// visibly inside it, all sharing the same bottom edge.
radii.forEach((r, i) => {
sizeSvg.append(“circle”)
.attr(“cx”, cx)
.attr(“cy”, baseline – r)
.attr(“r”, r)
.attr(“class”, “count-size-ref”);

const topY = baseline – 2 * r;
sizeSvg.append(“line”)
.attr(“class”, “count-size-leader”)
.attr(“x1”, cx)
.attr(“y1”, topY)
.attr(“x2”, cx + maxR + LEADER)
.attr(“y2”, topY);

sizeSvg.append(“text”)
.attr(“class”, “count-size-label”)
.attr(“x”, cx + maxR + LEADER + 4)
.attr(“y”, topY + 5)
.text(`${formatCompactNumber(refValues[i])}`);
});
}

function renderRateLegend(shell, mode, color) {
const legend = shell.append(“div”).attr(“class”, “rate-legend”);
if (mode !== “rate”) return; // still reserves its height (see CSS), just empty

legend.append(“div”)
.attr(“class”, “legend-title”)
// .text(“Net migration rate”);

const bar = legend.append(“div”).attr(“class”, “legend-row”);
bar.append(“span”).attr(“class”, “legend-label”).text(“≤ −3%”);

// Contiguous rounded blocks, not a smooth gradient – the reader compares
// seven named bands (orange severity, a blue neutral band, green
// severity – Rocket’s semantic palette). Labels stay sparse: the two
// ends plus “Neutral” under the middle block, which is always the
// neutral band by construction (3 loss steps + neutral + 3 gain steps).
const colors = color.range();
const stepsBlock = bar.append(“div”).attr(“class”, “legend-steps”);
colors.forEach(hex => {
stepsBlock.append(“span”)
.attr(“class”, “legend-step”)
.style(“background”, hex);
});

const neutralPct = ((Math.floor(colors.length / 2) + 0.5) / colors.length) * 100;
stepsBlock.append(“span”)
.attr(“class”, “legend-neutral-label”)
.style(“left”, `${neutralPct}%`)
.text(“Neutral”);

bar.append(“span”).attr(“class”, “legend-label”).text(“≥+3%”);
}

// Bespoke callout (title + a colored value beneath it, connected to the
// circle by a plain straight line) – see CALLOUT_METROS. Both lines are
// plain text – no badge/background on the value, just colored ink (green
// for a gain, orange for a loss, reusing the same tokens the rest of the
// map already uses) – so the whole thing reads as one clean two-line
// label. Not the systematic placeLabels path – this is a hand-placed
// annotation, positioned by a fixed offset tuned by eye against a real
// render, rather than run through general collision avoidance.
// Matches the ascent used for plain metro-labels at the same 13px size.
const CALLOUT_TITLE_ASCENT = 15;
const CALLOUT_VALUE_DY = 19; // value’s baseline below the title’s own baseline

const CALLOUT_GAP = 3; // required clearance from the target circle’s own edge

// Curved leader, in place of a plain straight tick – a quadratic Bezier
// whose control point sits at the midpoint of the line from `a` to `b`,
// translated PERPENDICULAR to that line by `offset` * the distance
// between them. 0.35 is the curviness that reads well at this leader’s
// length. Returns an SVG path `d` string directly – no point sampling
// needed, since SVG’s own “Q” command already draws exactly this
// quadratic curve.
function swoopQuadPath(a, b, offset) {
const dx = b[0] – a[0], dy = b[1] – a[1];
const len = Math.hypot(dx, dy);
const perpAngle = Math.atan2(dy, dx) + Math.PI / 2;
const mx = (a[0] + b[0]) / 2, my = (a[1] + b[1]) / 2;
const cx = mx + Math.cos(perpAngle) * len * offset;
const cy = my + Math.sin(perpAngle) * len * offset;
return `M${a[0]},${a[1]} Q${cx},${cy} ${b[0]},${b[1]}`;
}

const CALLOUT_SWOOP_OFFSET = 0.35;

// Which of the two perpendicular sides to bulge toward, per corner – top
// corners curve downward (back toward the circle), bottom corners curve
// upward, mirrored left vs. right so each pair reads as a true reflection
// of the other across the circle’s own vertical centerline.
function diagonalSwoopSign(direction) {
const isTop = direction.startsWith(“top”);
const isLeftSide = direction.endsWith(“left”);
return isTop === isLeftSide ? -CALLOUT_SWOOP_OFFSET : CALLOUT_SWOOP_OFFSET;
}

// Unit vector from the circle’s own center toward the LABEL, for each
// `direction` value (see CALLOUT_METROS) – where the label’s near edge
// sits, at CALLOUT_LABEL_GAP past the circle’s edge. Diagonal for the four
// corner directions (1/√2 matches the plain-label diagonal candidates’ own
// convention – see the `diag` constant in labelCandidates below), straight
// left/right for the other two.
const CALLOUT_DIRECTION_VECTORS = {
left: { x: -1, y: 0 },
right: { x: 1, y: 0 },
“top-left”: { x: -Math.SQRT1_2, y: -Math.SQRT1_2 },
“top-right”: { x: Math.SQRT1_2, y: -Math.SQRT1_2 },
“bottom-left”: { x: -Math.SQRT1_2, y: Math.SQRT1_2 },
“bottom-right”: { x: Math.SQRT1_2, y: Math.SQRT1_2 }
};

// Unit vector for where the leader actually meets the CIRCLE – a cardinal
// point, not a diagonal one: “top-left”/”top-right” both land dead center
// on the circle’s own top edge, “bottom-left”/”bottom-right” both on its
// bottom edge, matching CALLOUT_DIRECTION_VECTORS only for plain
// “left”/”right” (where the label sits at the same height as the circle
// anyway, so its near edge already is the left/right center point).
const CALLOUT_CIRCLE_EXIT_VECTORS = {
left: { x: -1, y: 0 },
right: { x: 1, y: 0 },
“top-left”: { x: 0, y: -1 },
“top-right”: { x: 0, y: -1 },
“bottom-left”: { x: 0, y: 1 },
“bottom-right”: { x: 0, y: 1 }
};

function renderCallout(svg, { cx, cy, r, title, value, sign, direction = “left”, showLeader = true, canvasWidth, circleScale = 1 }) {
const g = svg.append(“g”).attr(“class”, “callout”);
const u = CALLOUT_DIRECTION_VECTORS[direction] || CALLOUT_DIRECTION_VECTORS.left;
const isDiagonal = direction.includes(“-“);
const isLeftSide = direction.endsWith(“left”);

// Count view has no leader line, so the label can (and should) sit right
// up against the circle instead of leaving room for one – a smaller
// flat gap than the rate view’s. Same flat number for every direction,
// diagonal and plain alike, so the circle-to-label padding reads as
// identical across every callout on the map. Scaled by `circleScale`
// (the same mobile factor already used for circle radii) so the callout
// tightens further on narrow screens instead of just the circles
// shrinking underneath a leader that stays just as long.
const BASE_CALLOUT_LABEL_GAP = 12;
const BASE_COUNT_LABEL_GAP = 2;
const CALLOUT_LABEL_GAP = (!showLeader ? BASE_COUNT_LABEL_GAP : BASE_CALLOUT_LABEL_GAP) * circleScale;

// The near edge – the one facing the circle, right edge of the text for
// a “left” side, left edge for “right” – sits exactly CALLOUT_LABEL_GAP
// past the circle’s own edge, along `direction`’s own ray from the
// center. Both the title and the value sit on that same edge via
// text-anchor – so real rendered width (never estimated) decides how far
// each line’s far end reaches, and a long title like “San Antonio, TX”
// can’t push its near edge further from the circle than a short one
// like “New York”.
const nearEdgeX = cx + u.x * (r + CALLOUT_LABEL_GAP);
const nearEdgeY = cy + u.y * (r + CALLOUT_LABEL_GAP);
const textAnchor = isLeftSide ? “end” : “start”;

let titleBaselineY, valueBaselineY;
if (direction.startsWith(“top”)) {
// Block sits above the circle – its bottom line (the value) is the
// one nearest, so anchor from there and stack the title above it.
// The leader always targets the TITLE’s own middle (see anchorY
// below), which this puts CALLOUT_VALUE_DY + half its ascent beyond
// the near edge – title is the far line here.
valueBaselineY = nearEdgeY;
titleBaselineY = valueBaselineY – CALLOUT_VALUE_DY;
} else if (direction.startsWith(“bottom”)) {
// Block sits below the circle – title is structurally the NEAR line
// here (it’s above value, and the circle sits above the whole
// block) – the opposite of “top”, where the far line (title) is what
// the leader targets. Without compensation, the leader’s actual
// target (title’s middle, again see anchorY) would sit closer to the
// circle than “top” ever gets, close enough that the title text’s own
// box can overlap the circle outright. Adding back the same
// CALLOUT_VALUE_DY + CALLOUT_TITLE_ASCENT that “top”‘s title
// effectively sits beyond its own near line equalizes the two
// exactly – both directions’ leader end up the identical length. That
// compensation only matters when a leader is actually being drawn
// (the rate view): in the count view there’s no leader to match
// lengths with, so skipping it there keeps the label sitting tight
// against the circle instead of needlessly far from it.
titleBaselineY = nearEdgeY + (showLeader ? CALLOUT_VALUE_DY + CALLOUT_TITLE_ASCENT : 0);
valueBaselineY = titleBaselineY + CALLOUT_VALUE_DY;
} else {
// Plain left/right: title vertically centered ON the circle’s own
// center (titleBaselineY – half its ascent == cy exactly) so the
// leader – which lands on (cx ± r, cy), dead level with the circle’s
// center – comes out perfectly horizontal instead of tilting by
// whatever gap this baseline happens to sit at.
const CALLOUT_DY = showLeader ? CALLOUT_TITLE_ASCENT / 2 : -8;
titleBaselineY = cy + CALLOUT_DY;
valueBaselineY = titleBaselineY + CALLOUT_VALUE_DY;
}

// Title: a plain label, styled exactly like every other metro-label.
const titleX = isLeftSide ? nearEdgeX – 2 : nearEdgeX + 2;
const titleText = g.append(“text”)
.attr(“class”, “metro-label callout-title”)
.attr(“x”, titleX)
.attr(“y”, titleBaselineY – 3)
.attr(“text-anchor”, textAnchor)
.text(title);

// Value: colored text, no badge – green for a gain, orange for a loss.
const valueText = g.append(“text”)
.attr(“class”, `callout-value callout-value-${sign}`)
.attr(“x”, titleX)
.attr(“y”, valueBaselineY – 3)
.attr(“text-anchor”, textAnchor)
.text(value);

// Clamp the whole callout so it can’t run off the SVG’s own left/right
// edge and get cropped – unlike the systematic placeLabels path, this is
// a hand-placed annotation with no other edge-awareness, so a coastal
// “right”-placed metro (New York) sits closer to that edge as the
// container narrows and can otherwise push its text straight past it.
// Measured off the actual rendered text (getBBox), not an estimate,
// since that’s already live in the DOM at this point.
let edgeShift = 0;
if (canvasWidth != null) {
const EDGE_MARGIN = 6;
const titleBox = titleText.node().getBBox();
const valueBox = valueText.node().getBBox();
if (isLeftSide) {
const farX = Math.min(titleBox.x, valueBox.x);
if (farX canvasWidth – EDGE_MARGIN) edgeShift = (canvasWidth – EDGE_MARGIN) – farX;
}
if (edgeShift !== 0) {
titleText.attr(“x”, titleX + edgeShift);
valueText.attr(“x”, titleX + edgeShift);
}
}

if (!showLeader) return;

const anchorX = nearEdgeX + edgeShift; // the label’s own near edge, shifted to match any edge clamp above
// Point at the metro name itself, not the gap between the name and the
// value – the vertical center of just the title’s own glyphs, roughly
// its baseline minus half its ascent.
const anchorY = titleBaselineY – CALLOUT_TITLE_ASCENT / 2;

// Leader: a plain straight line for “left”/”right”, a curved one for a
// diagonal direction. Lands on the circle’s own edge at a cardinal
// point – due east/west at the vertical
// center for “left”/”right”, dead center on the top or bottom edge for
// the four corner directions (see CALLOUT_CIRCLE_EXIT_VECTORS) – never
// the diagonal corner itself, and never bent off that point to dodge a
// neighbor.
const uExit = CALLOUT_CIRCLE_EXIT_VECTORS[direction] || CALLOUT_CIRCLE_EXIT_VECTORS.left;
const scaledCalloutGap = CALLOUT_GAP * circleScale;
const endX = cx + uExit.x * (r + scaledCalloutGap);
const endY = cy + uExit.y * (r + scaledCalloutGap);

if (isDiagonal) {
g.append(“path”)
.attr(“class”, “callout-leader”)
.attr(“d”, swoopQuadPath([anchorX, anchorY], [endX, endY], diagonalSwoopSign(direction)));
} else {
g.append(“line”)
.attr(“class”, “callout-leader”)
.attr(“x1”, anchorX)
.attr(“y1”, anchorY)
.attr(“x2”, endX)
.attr(“y2”, endY);
}
}

// Label collision avoidance ————————————————
// Estimates each label’s box from its text content (no DOM measurement
// needed – width from character count, height from a single line), then
// tries 8 candidate positions around its circle in priority order (above,
// below, right, left, then the four diagonals), picking the first that
// overlaps neither another circle, an already-placed label, NOR the canvas
// edge. That third check is the systematic fix for edge-of-map cropping
// (e.g. “New York”): the canvas boundary is treated exactly like a circle
// or another label – just another rect a candidate must clear – so a
// coastal metro automatically falls through “right”/”upper-right” (which
// would overflow past x=width) to “left”/”upper-left” (which doesn’t),
// with no per-metro special-casing. Falls back to “above” if every
// candidate collides – a best effort, not a guarantee, but comfortable
// with a handful of labels among 30 circles.
const LABEL_CHAR_W = 7.05; // approx px/char at the label’s 13px regular weight
const LABEL_LINE_H = 15; // single line height
const LABEL_GAP = 3; // clearance from the circle edge – kept tight so
// it’s obvious which label belongs to which dot
const LABEL_PAD = 2; // extra breathing room in collision checks
const LABEL_ASCENT = 11; // distance from a candidate box’s top edge to its baseline, at scale 1

// `scale` mirrors the shrunk .metro-label font-size on mobile (see the
// @media rule in styles.css) – without it, the collision math would still
// assume the desktop-sized 13px box even though the real rendered text is
// smaller there, silently under-packing labels into a crowded, narrow map
// instead of actually taking advantage of the smaller font to fit more of
// them cleanly.
function estimateLabelBox(text, scale = 1) {
return { width: text.length * LABEL_CHAR_W * scale, height: LABEL_LINE_H * scale };
}

function padRect(rect, pad) {
return { x0: rect.x0 – pad, x1: rect.x1 + pad, y0: rect.y0 – pad, y1: rect.y1 + pad };
}

function rectsOverlap(a, b) {
return !(a.x1 b.x1 || a.y1 b.y1);
}