app/lib/cv/view.mjs

Functions

Imports

It imports no other module of this repo. Imported by app/enhance/cv.ts, app/kb/admin.mjs, app/kb/registry/compile.mjs, app/lib/carrel/cv-handler.server.ts, app/lib/cv/charts.ts, app/lib/cv/entries.mjs, app/lib/cv/markdown.mjs, app/lib/cv/render-charts.ts, app/lib/cv/validate.mjs, app/lib/phages/catalog.mjs, app/lib/phages/compile.mjs, app/routes/cv.charts[.json].ts, app/routes/cv.tsx.

Source

1/**
2 * What the CV page shows for a filter state: the state's URL form, which entries match, how they are
3 * grouped, the headline counts and the chart inputs. One module for both sides: the route computes the
4 * first render from the query string (so a shared URL and a scripts-off reader get the same page), and
5 * app/enhance/cv.ts recomputes it on every input. It never imports the data, so the enhancement bundle
6 * carries none of it; each side hands in `Facts`.
7 */
8
9/** @typedef {import("./types.ts").CvType} CvType */
10/** @typedef {import("./types.ts").CvArea} CvArea */
11/** @typedef {import("./types.ts").CvRole} CvRole */
12
13/**
14 * @typedef {object} Facts what filtering, grouping and counting read from an entry
15 * @property {string} id
16 * @property {CvType} type
17 * @property {string | null} section
18 * @property {CvArea[]} areas
19 * @property {CvRole | null} role
20 * @property {number | null} year
21 * @property {number | "present" | null} endYear
22 * @property {number | null} students
23 * @property {boolean} cohort
24 * @property {number | null} amount
25 * @property {number} order position in the source, the tiebreak everywhere
26 * @property {string} search folded text
27 */
28
29/**
30 * @typedef {object} CvState
31 * @property {CvType[]} types empty means every type
32 * @property {CvArea[]} areas empty means every area
33 * @property {number | null} from
34 * @property {number | null} to
35 * @property {CvRole | null} role
36 * @property {string} q
37 * @property {"type" | "newest" | "oldest"} sort
38 */
39
40/** Traditional CV order, which is also the "by type" sort. */
41export const TYPES = /** @type {const} */ ([
42  ["appointment", "Appointment", "Appointments"],
43  ["education", "Education", "Education"],
44  ["publication", "Publication", "Publications"],
45  ["grant", "Grant", "Grants"],
46  ["award", "Award", "Fellowships and awards"],
47  ["talk", "Invited talk", "Invited talks"],
48  ["course", "Course", "Courses taught"],
49  ["mentoring", "Mentoring", "Students mentored"],
50  ["service", "Service", "Service"],
51  ["development", "Professional development", "Professional development"],
52]);
53
54export const AREAS = /** @type {const} */ ([
55  ["retroviruses", "Retroviruses"],
56  ["bacteriophages", "Bacteriophages"],
57  ["science-education", "Science education"],
58  ["ai", "AI"],
59]);
60
61export const ROLES = /** @type {const} */ ([
62  ["first-author", "First author"],
63  ["senior-author", "Senior author"],
64  ["co-author", "Co-author"],
65  ["recipient", "Recipient"],
66  ["speaker", "Speaker"],
67  ["instructor", "Instructor"],
68  ["mentor", "Mentor"],
69  ["chair", "Chair"],
70  ["organizer", "Organizer"],
71  ["member", "Member"],
72  ["editor", "Editor"],
73  ["reviewer", "Reviewer"],
74  ["judge", "Judge"],
75  ["advisor", "Advisor"],
76  ["volunteer", "Volunteer"],
77  ["consultant", "Consultant"],
78  ["participant", "Participant"],
79]);
80
81export const SORTS = /** @type {const} */ ([
82  ["type", "Section"],
83  ["newest", "Newest first"],
84  ["oldest", "Oldest first"],
85]);
86
87/** The timeline figure's id, which Enarratio's `enarratio:select` events carry as `chartId`. */
88export const TIMELINE_ID = "cv-timeline";
89
90/** The types the timeline stacks, in stacking order, each with its chart token. */
91export const CHART_SERIES = /** @type {const} */ ([
92  ["publication", "Publications", "var(--chart-purple)"],
93  ["grant", "Grants", "var(--chart-cadet)"],
94  ["talk", "Invited talks", "var(--chart-claret)"],
95  ["award", "Awards", "var(--chart-sage)"],
96]);
97
98const TYPE_IDS = new Set(TYPES.map(([id]) => /** @type {string} */ (id)));
99const AREA_IDS = new Set(AREAS.map(([id]) => /** @type {string} */ (id)));
100const ROLE_IDS = new Set(ROLES.map(([id]) => /** @type {string} */ (id)));
101const SORT_IDS = new Set(SORTS.map(([id]) => /** @type {string} */ (id)));
102
103/** @param {CvType} type */
104export function typeLabel(type, plural = false) {
105  const row = TYPES.find(([id]) => id === type);
106  if (!row) throw new Error(`cv: unknown type ${type}`);
107  return plural ? row[2] : row[1];
108}
109
110/** @param {string} area */
111export function areaLabel(area) {
112  return AREAS.find(([id]) => id === area)?.[1] ?? area;
113}
114
115/** @param {string} role */
116export function roleLabel(role) {
117  return ROLES.find(([id]) => id === role)?.[1] ?? role;
118}
119
120/**
121 * Lowercased with diacritics removed, so "Galvão" matches "galvao".
122 *
123 * @param {string} text
124 */
125export function foldText(text) {
126  return String(text ?? "")
127    .normalize("NFKD")
128    .replace(/[̀-ͯ]/g, "")
129    .toLowerCase()
130    .replace(/\s+/g, " ")
131    .trim();
132}
133
134/**
135 * Whole dollars print without cents; the CV's cents are kept where it has them.
136 *
137 * @param {number} amount
138 */
139export function formatDollars(amount) {
140  const cents = Math.round(amount * 100) % 100 !== 0;
141  return `$${amount.toLocaleString("en-US", { minimumFractionDigits: cents ? 2 : 0, maximumFractionDigits: 2 })}`;
142}
143
144/** @returns {CvState} */
145function defaultState() {
146  return { types: [], areas: [], from: null, to: null, role: null, q: "", sort: "type" };
147}
148
149/**
150 * Both spellings a list arrives in: repeated keys from the scripts-off form, commas from a hand-typed
151 * URL. Unknown values are dropped rather than refused: a stale shared link still opens the CV.
152 *
153 * @param {URLSearchParams} params
154 * @param {string} key
155 * @param {Set<string>} known
156 */
157function listParam(params, key, known) {
158  /** @type {string[]} */
159  const out = [];
160  for (const raw of params.getAll(key)) {
161    for (const value of raw.split(",")) {
162      const v = value.trim();
163      if (known.has(v) && !out.includes(v)) out.push(v);
164    }
165  }
166  return out;
167}
168
169/** @param {string | null} raw */
170function yearParam(raw) {
171  if (!raw || !/^\d{4}$/.test(raw.trim())) return null;
172  return Number(raw.trim());
173}
174
175/**
176 * @param {URLSearchParams} params
177 * @returns {CvState}
178 */
179export function parseState(params) {
180  const state = defaultState();
181  state.types = /** @type {CvType[]} */ (listParam(params, "type", TYPE_IDS));
182  state.areas = /** @type {CvArea[]} */ (listParam(params, "area", AREA_IDS));
183  state.from = yearParam(params.get("from"));
184  state.to = yearParam(params.get("to"));
185  if (state.from !== null && state.to !== null && state.from > state.to) {
186    [state.from, state.to] = [state.to, state.from];
187  }
188  const role = params.get("role") ?? "";
189  state.role = ROLE_IDS.has(role) ? /** @type {CvRole} */ (role) : null;
190  state.q = (params.get("q") ?? "").trim().slice(0, 100);
191  const sort = params.get("sort") ?? "";
192  state.sort = SORT_IDS.has(sort) ? /** @type {CvState["sort"]} */ (sort) : "type";
193  return state;
194}
195
196/**
197 * The canonical query string for a state: only what differs from the default, lists in their
198 * vocabulary's order, so one filter has one URL. Repeated keys, as the scripts-off form submits them.
199 *
200 * @param {CvState} state
201 */
202export function stateToSearch(state) {
203  const params = new URLSearchParams();
204  for (const [id] of TYPES) if (state.types.includes(id)) params.append("type", id);
205  for (const [id] of AREAS) if (state.areas.includes(id)) params.append("area", id);
206  if (state.from !== null) params.set("from", String(state.from));
207  if (state.to !== null) params.set("to", String(state.to));
208  if (state.role) params.set("role", state.role);
209  if (state.q) params.set("q", state.q);
210  if (state.sort !== "type") params.set("sort", state.sort);
211  const out = params.toString();
212  return out ? `?${out}` : "";
213}
214
215/** @param {CvState} state */
216export function isFiltered(state) {
217  return (
218    state.types.length > 0 ||
219    state.areas.length > 0 ||
220    state.from !== null ||
221    state.to !== null ||
222    state.role !== null ||
223    state.q !== ""
224  );
225}
226
227/**
228 * An entry's span: an ongoing one runs forever, and an undated one has no span and matches no range.
229 *
230 * @param {Facts} f
231 * @returns {[number, number] | null}
232 */
233function spanOf(f) {
234  if (f.year === null) return null;
235  const end = f.endYear === "present" ? Number.POSITIVE_INFINITY : (f.endYear ?? f.year);
236  return [f.year, end];
237}
238
239/**
240 * @param {Facts} f
241 * @param {CvState} state
242 * @param {{ ignoreYears?: boolean }} [options] the charts show every year and mark the range instead
243 */
244export function matches(f, state, options = {}) {
245  if (state.types.length > 0 && !state.types.includes(f.type)) return false;
246  if (state.areas.length > 0 && !f.areas.some((a) => state.areas.includes(a))) return false;
247  if (state.role && f.role !== state.role) return false;
248  if (!options.ignoreYears && (state.from !== null || state.to !== null)) {
249    const span = spanOf(f);
250    if (!span) return false;
251    if (state.from !== null && span[1] < state.from) return false;
252    if (state.to !== null && span[0] > state.to) return false;
253  }
254  if (state.q) {
255    for (const word of foldText(state.q).split(" ")) {
256      if (word && !f.search.includes(word)) return false;
257    }
258  }
259  return true;
260}
261
262/**
263 * @typedef {object} Group
264 * @property {string} key
265 * @property {string} heading
266 * @property {{ key: string, heading: string | null, ids: string[] }[]} parts
267 */
268
269/**
270 * How the entries sit on the page. By section: the CV's order, each type's subsections in the order
271 * they first appear, newest first inside each. By date: one group per year, undated last.
272 *
273 * @param {Facts[]} facts every entry, matching or not: a hidden entry keeps its place
274 * @param {CvState["sort"]} sort
275 * @returns {Group[]}
276 */
277export function groupEntries(facts, sort) {
278  const byYearDesc = (/** @type {Facts} */ a, /** @type {Facts} */ b) =>
279    (b.year ?? -Infinity) - (a.year ?? -Infinity) || a.order - b.order;
280
281  if (sort === "type") {
282    /** @type {Group[]} */
283    const groups = [];
284    for (const [type, , plural] of TYPES) {
285      const members = facts.filter((f) => f.type === type);
286      if (members.length === 0) continue;
287      /** @type {Map<string, Facts[]>} */
288      const parts = new Map();
289      for (const f of [...members].sort((a, b) => a.order - b.order)) {
290        const key = f.section ?? "";
291        if (!parts.has(key)) parts.set(key, []);
292        parts.get(key)?.push(f);
293      }
294      groups.push({
295        key: `type-${type}`,
296        heading: plural,
297        parts: [...parts].map(([section, list]) => ({
298          key: `type-${type}-${section ? section.toLowerCase().replace(/[^a-z0-9]+/g, "-") : "all"}`,
299          heading: section || null,
300          ids: [...list].sort(byYearDesc).map((f) => f.id),
301        })),
302      });
303    }
304    return groups;
305  }
306
307  const typeRank = new Map(TYPES.map(([id], i) => [/** @type {string} */ (id), i]));
308  const years = [...new Set(facts.map((f) => f.year))].sort((a, b) => {
309    if (a === null) return 1;
310    if (b === null) return -1;
311    return sort === "newest" ? b - a : a - b;
312  });
313  return years.map((year) => ({
314    key: `year-${year ?? "undated"}`,
315    heading: year === null ? "Undated" : String(year),
316    parts: [
317      {
318        key: `year-${year ?? "undated"}-all`,
319        heading: null,
320        ids: facts
321          .filter((f) => f.year === year)
322          .sort((a, b) => (typeRank.get(a.type) ?? 0) - (typeRank.get(b.type) ?? 0) || a.order - b.order)
323          .map((f) => f.id),
324      },
325    ],
326  }));
327}
328
329/**
330 * The headline counts for the matching entries.
331 *
332 * @param {Facts[]} shown
333 */
334export function headline(shown) {
335  let papers = 0;
336  let grants = 0;
337  let dollars = 0;
338  let students = 0;
339  for (const f of shown) {
340    if (f.type === "publication") papers += 1;
341    if (f.type === "grant") {
342      grants += 1;
343      dollars += f.amount ?? 0;
344    }
345    if (f.type === "mentoring") students += f.students ?? 0;
346  }
347  return { papers, grants, dollars: Math.round(dollars * 100) / 100, students, entries: shown.length };
348}
349
350/**
351 * Inclusive, ascending.
352 *
353 * @param {number} from
354 * @param {number} to
355 */
356function range(from, to) {
357  const out = [];
358  for (let y = from; y <= to; y += 1) out.push(y);
359  return out;
360}
361
362/**
363 * The year axis every chart shares: the first charted year in the whole CV to the last. Fixed across
364 * filters, so bars do not slide sideways when a filter changes.
365 *
366 * @param {Facts[]} all
367 */
368export function chartYears(all) {
369  const charted = new Set(CHART_SERIES.map(([id]) => /** @type {string} */ (id)));
370  const years = all
371    .filter((f) => f.year !== null && (charted.has(f.type) || (f.type === "mentoring" && f.cohort)))
372    .map((f) => /** @type {number} */ (f.year));
373  return range(Math.min(...years), Math.max(...years));
374}
375
376/**
377 * The stacked timeline's input: output per start year by type, for entries matching every filter but
378 * the year range, which the chart marks instead.
379 *
380 * @param {Facts[]} all
381 * @param {CvState} state
382 */
383export function timelineData(all, state) {
384  const years = chartYears(all);
385  const shown = all.filter((f) => matches(f, state, { ignoreYears: true }));
386  const series = CHART_SERIES.map(([key, label, token]) => ({
387    key,
388    label,
389    token,
390    values: years.map((y) => shown.filter((f) => f.type === key && f.year === y).length),
391  }));
392  return { years, series, selected: selectedRange(state, years), entries: shown.length };
393}
394
395/**
396 * What the timeline says in place of a chart when the filters leave it nothing to draw: no entry matches at
397 * all, or some do but none is a charted type (publications, grants, talks, awards), as with courses or
398 * service. Null when there is something to draw. Enarratio refuses to chart no data, so the caller draws this
399 * sentence instead and never calls it.
400 *
401 * @param {ReturnType<typeof timelineData>} data
402 * @returns {string | null}
403 */
404export function timelineEmptyText(data) {
405  if (data.series.some((s) => s.values.some((n) => n > 0))) return null;
406  if (data.entries === 0) return "No entries match these filters, so there is nothing to chart.";
407  const names = data.series.map((s) => s.label.toLowerCase());
408  return `The timeline charts ${names.slice(0, -1).join(", ")} and ${names[names.length - 1]}, and none of the entries these filters select is one of those.`;
409}
410
411/**
412 * @param {CvState} state
413 * @param {number[]} years
414 * @returns {[number, number] | null}
415 */
416function selectedRange(state, years) {
417  if (state.from === null && state.to === null) return null;
418  const first = years[0] ?? 0;
419  const last = years[years.length - 1] ?? 0;
420  return [state.from ?? first, state.to ?? last];
421}
422
423/**
424 * Per-year series for the three headline sparklines. Students count only the one-cohort lines: a
425 * count spread over a decade (19 lab students, 2015 to 2026) has no honest per-year split.
426 *
427 * @param {Facts[]} all
428 * @param {CvState} state
429 */
430export function sparkData(all, state) {
431  const years = chartYears(all);
432  const shown = all.filter((f) => matches(f, state, { ignoreYears: true }));
433  const per = (/** @type {(f: Facts) => number} */ value) =>
434    years.map((y) => shown.filter((f) => f.year === y).reduce((sum, f) => sum + value(f), 0));
435  return {
436    years,
437    selected: selectedRange(state, years),
438    papers: per((f) => (f.type === "publication" ? 1 : 0)),
439    grants: per((f) => (f.type === "grant" ? 1 : 0)),
440    students: per((f) => (f.type === "mentoring" && f.cohort ? (f.students ?? 0) : 0)),
441  };
442}
443
444/**
445 * The query a year's bar links to with script off: that year alone, or every year when it already is.
446 *
447 * @param {CvState} state
448 * @param {number} year
449 */
450export function yearHref(state, year) {
451  const only = state.from === year && state.to === year;
452  return stateToSearch({ ...state, from: only ? null : year, to: only ? null : year });
453}
454
455/**
456 * One sentence for a screen reader and the status line: what is shown out of what.
457 *
458 * @param {number} shown
459 * @param {number} total
460 */
461export function summaryText(shown, total) {
462  if (shown === total) return `Showing all ${total} entries`;
463  if (shown === 0) return `No entries match. ${total} entries in all`;
464  return `Showing ${shown} of ${total} entries`;
465}
466
467/**
468 * How many entries each filter option would show, given every other filter: the number beside a
469 * checkbox is what ticking it adds, the way a faceted search counts.
470 *
471 * @param {Facts[]} all
472 * @param {CvState} state
473 */
474export function facetCounts(all, state) {
475  /** @type {Record<string, number>} */
476  const types = {};
477  /** @type {Record<string, number>} */
478  const areas = {};
479  /** @type {Record<string, number>} */
480  const roles = {};
481  const noTypes = { ...state, types: [] };
482  const noAreas = { ...state, areas: [] };
483  const noRole = { ...state, role: null };
484  for (const f of all) {
485    if (matches(f, noTypes)) types[f.type] = (types[f.type] ?? 0) + 1;
486    if (matches(f, noAreas)) for (const a of f.areas) areas[a] = (areas[a] ?? 0) + 1;
487    if (f.role && matches(f, noRole)) roles[f.role] = (roles[f.role] ?? 0) + 1;
488  }
489  return { types, areas, roles };
490}
491
492/**
493 * Every year an entry starts in, ascending: the year pickers' options.
494 *
495 * @param {Facts[]} all
496 */
497export function yearOptions(all) {
498  const years = all.map((f) => f.year).filter((y) => y !== null);
499  return range(Math.min(...years), Math.max(...years));
500}
501
502/**
503 * The timeline's accessible name: what it plots and its peak, since the bars are not read out.
504 *
505 * @param {ReturnType<typeof timelineData>} data
506 */
507export function timelineLabel(data) {
508  const totals = data.years.map((_, i) => data.series.reduce((sum, s) => sum + (s.values[i] ?? 0), 0));
509  const peak = Math.max(0, ...totals);
510  const first = data.years[0];
511  const last = data.years[data.years.length - 1];
512  const names = data.series.map((s) => s.label.toLowerCase());
513  const what = `${names.slice(0, -1).join(", ")} and ${names[names.length - 1]} per year, ${first} to ${last}`;
514  if (peak === 0) return `${what[0]?.toUpperCase()}${what.slice(1)}: none match the filters.`;
515  const peakYears = data.years.filter((_, i) => totals[i] === peak);
516  return `${what[0]?.toUpperCase()}${what.slice(1)}. Most in ${peakYears.join(" and ")}, with ${peak}. Each year's bar shows that year only.`;
517}
518
519/**
520 * @param {string} what "papers", "grants" or "students in one-year cohorts"
521 * @param {number[]} years
522 * @param {number[]} values
523 */
524export function sparkLabel(what, years, values) {
525  const peak = Math.max(0, ...values);
526  if (peak === 0) return `No ${what} per year match the filters.`;
527  const at = years.filter((_, i) => values[i] === peak);
528  return `${what[0]?.toUpperCase()}${what.slice(1)} per year, ${years[0]} to ${years[years.length - 1]}: most in ${at.join(" and ")}, with ${peak}.`;
529}
530
531/**
532 * How many filters are on, for the collapsed filter panel's label: each ticked type and area, the year
533 * range, the role and the search.
534 *
535 * @param {CvState} state
536 */
537export function activeCount(state) {
538  return (
539    state.types.length +
540    state.areas.length +
541    (state.from !== null || state.to !== null ? 1 : 0) +
542    (state.role ? 1 : 0) +
543    (state.q ? 1 : 0)
544  );
545}