components/catalog/catalog-core.ts

Functions

Imports

It imports no other module of this repo. Imported by components/catalog/catalog.react.tsx, components/catalog/catalog.ts, components/catalog/examples.tsx, components/catalog/fixture.ts.

Source

1// The catalog's core: one declaration of a collection's fields, and the pure functions that turn the
2// address's query string and the items into the page's state. No DOM and no framework, so a server
3// renders the same result a browser would, the filter works with no script, and every site that uses
4// the catalog gets the same counts, chips and addresses.
5//
6// A collection declares each field once (is it searched, is it a facet, is it a column, can it sort).
7// `parseCatalogParams` reads the address; `queryCatalog` applies it and returns what the page shows.
8// The result never depends on how it is drawn.
9
10export type CatalogValue = string | number | boolean | null | undefined;
11
12export interface CatalogFacet {
13  // "many": values of the field combine with "or" (checkboxes). "one": a single value (radios, with "Any").
14  kind?: "one" | "many";
15  // General facets are listed first and start open; the rest start folded.
16  general?: boolean;
17  // The options' order: most items first (default), alphabetical, or a fixed list.
18  order?: "count" | "alpha" | readonly string[];
19  // How a value reads as an option and as a chip, when the value is not already words.
20  label?: (value: string) => string;
21  // How many options show before "Show more". Default 8.
22  limit?: number;
23}
24
25export interface CatalogColumn {
26  header?: string;
27  align?: "end";
28  // Opt in to dropping the column on a narrow region (the table's `data-drop`).
29  drop?: 1 | 2;
30  // A small note under the header ("last 24 hours").
31  note?: string;
32  // The column is left out while the rows are grouped, because the group heading already says it (a Year column
33  // under year headings). It shows again in every flat view.
34  hideWhenGrouped?: boolean;
35}
36
37// Rows under headings, in the default order only. The group field must be the one the default sort orders by, so
38// each heading's rows are together; a search or another sort shows the same rows flat.
39export interface CatalogGroup<T> {
40  // The sortable field the default sort orders by (its key, not "-key").
41  field: string;
42  // What puts an item in a group, when the field's own value is finer than a heading (a month, not a day).
43  value?: (item: T) => string;
44  // How a group's value reads as its heading. Default: the value.
45  label?: (value: string) => string;
46}
47
48export interface CatalogSort<T> {
49  // How the two directions read in the sort menu. Defaults follow the field's `type`.
50  labels?: { asc: string; desc: string };
51  // Replaces comparing the field's value: for a field whose order is not alphabetical or numeric.
52  compare?: (a: T, b: T) => number;
53}
54
55export interface CatalogField<T> {
56  // The field's name, and its URL parameter when it is a facet. Not q, sort or page.
57  key: string;
58  label: string;
59  // What the field says about one item: a value, a list of values, or nothing.
60  value: (item: T) => CatalogValue | readonly CatalogValue[];
61  // The field is typed by the search box. A number is its weight in the ranking (true is 1).
62  search?: boolean | number;
63  facet?: CatalogFacet;
64  column?: CatalogColumn;
65  sort?: boolean | CatalogSort<T>;
66  // Reading and ordering: text (A to Z), number (low to high) or date (oldest first, ISO strings).
67  type?: "text" | "number" | "date";
68}
69
70export interface CatalogDefinition<T> {
71  // Names the live regions and the form: unique on a page.
72  id: string;
73  // The items' name, singular and plural, for the count ("3 of 14 protocols").
74  noun: readonly [string, string];
75  // The page's address, with no query: the canonical, and where every filtered address is built from.
76  basePath: string;
77  fields: readonly CatalogField<T>[];
78  itemKey: (item: T) => string;
79  // The order with nothing typed: a field key, "-" first for descending ("-updated").
80  defaultSort?: string;
81  // Rows per page; leave out for one page.
82  pageSize?: number;
83  // Headings over the rows in the default order (see CatalogGroup).
84  group?: CatalogGroup<T>;
85}
86
87export interface CatalogState {
88  q: string;
89  filters: Record<string, string[]>;
90  // "" is the default order (best match while a search is typed).
91  sort: string;
92  page: number;
93}
94
95export interface CatalogOption {
96  value: string;
97  label: string;
98  // Items that would match with this option chosen, the other filters held.
99  count: number;
100  selected: boolean;
101}
102
103export interface CatalogFacetResult {
104  key: string;
105  label: string;
106  kind: "one" | "many";
107  general: boolean;
108  limit: number;
109  options: CatalogOption[];
110  selected: number;
111}
112
113export interface CatalogChip {
114  id: string;
115  field: string;
116  value: string;
117  // "Method: PCR", or the search typed in quotes.
118  label: string;
119  // The address with this one filter removed: a link that works with no script.
120  href: string;
121}
122
123export interface CatalogSortOption {
124  value: string;
125  label: string;
126  selected: boolean;
127}
128
129export interface CatalogRowGroup<T> {
130  value: string;
131  label: string;
132  rows: T[];
133}
134
135export interface CatalogResult<T> {
136  state: CatalogState;
137  total: number;
138  count: number;
139  rows: T[];
140  // The shown rows under their headings, or null when the view is flat (a search, another sort, or no group declared).
141  groups: CatalogRowGroup<T>[] | null;
142  page: number;
143  pageCount: number;
144  // The 1-based position of the first and last row shown, of `count`.
145  from: number;
146  to: number;
147  facets: CatalogFacetResult[];
148  chips: CatalogChip[];
149  clearHref: string | null;
150  sorts: CatalogSortOption[];
151  // The address for this state with changes; with none, the current address.
152  href: (change?: Partial<CatalogState>) => string;
153}
154
155export const RESERVED_PARAMS = ["q", "sort", "page"] as const;
156
157// Folds case and accents, so "Mycobacterium" matches "mycobacterium" and "Genève" matches "geneve".
158export function fold(text: string): string {
159  return text.normalize("NFD").replace(/\p{M}+/gu, "").toLowerCase();
160}
161
162const asList = (v: CatalogValue | readonly CatalogValue[]): string[] =>
163  (Array.isArray(v) ? v : [v]).filter((x): x is string | number | boolean => x !== null && x !== undefined && x !== "").map(String);
164
165// Checks a declaration once, at definition time, so a mistake is a thrown error where it is made and not a
166// filter that quietly does nothing.
167export function defineCatalog<T>(def: CatalogDefinition<T>): CatalogDefinition<T> {
168  const keys = new Set<string>();
169  for (const field of def.fields) {
170    if (!/^[a-z][a-z0-9_-]*$/.test(field.key)) throw new Error(`catalog ${def.id}: field key "${field.key}" must be lower case letters, digits, - or _`);
171    if ((RESERVED_PARAMS as readonly string[]).includes(field.key)) throw new Error(`catalog ${def.id}: "${field.key}" is a reserved parameter`);
172    if (keys.has(field.key)) throw new Error(`catalog ${def.id}: two fields are named "${field.key}"`);
173    keys.add(field.key);
174  }
175  if (def.defaultSort !== undefined) {
176    const key = def.defaultSort.replace(/^-/, "");
177    const field = def.fields.find((f) => f.key === key);
178    if (!field?.sort) throw new Error(`catalog ${def.id}: defaultSort "${def.defaultSort}" is not a sortable field`);
179  }
180  if (def.group) {
181    const field = def.fields.find((f) => f.key === def.group?.field);
182    if (!field?.sort) throw new Error(`catalog ${def.id}: group field "${def.group.field}" is not a sortable field`);
183    if (def.defaultSort?.replace(/^-/, "") !== def.group.field) {
184      throw new Error(`catalog ${def.id}: group field "${def.group.field}" must be the field the default sort orders by`);
185    }
186  }
187  if (!def.basePath.startsWith("/") || def.basePath.includes("?")) throw new Error(`catalog ${def.id}: basePath is a path with no query`);
188  return def;
189}
190
191export function parseCatalogParams<T>(def: CatalogDefinition<T>, input: URLSearchParams | string): CatalogState {
192  const params = typeof input === "string" ? new URLSearchParams(input) : input;
193  const filters: Record<string, string[]> = {};
194  for (const field of def.fields) {
195    if (!field.facet) continue;
196    const values = params.getAll(field.key).map((v) => v.trim()).filter(Boolean);
197    const unique = [...new Set(values)];
198    if (unique.length > 0) filters[field.key] = field.facet.kind === "one" ? unique.slice(0, 1) : unique;
199  }
200  const rawSort = params.get("sort") ?? "";
201  const sortKey = rawSort.replace(/^-/, "");
202  const sortable = def.fields.some((f) => f.key === sortKey && f.sort);
203  const page = Number.parseInt(params.get("page") ?? "1", 10);
204  return {
205    q: (params.get("q") ?? "").trim().replace(/\s+/g, " ").slice(0, 200),
206    filters,
207    sort: sortable ? rawSort : "",
208    page: Number.isFinite(page) && page > 1 ? page : 1,
209  };
210}
211
212// The address for a state: only what differs from the default, in a fixed order, so one state has one
213// address (which is also what keeps the base page the canonical).
214export function catalogHref<T>(def: CatalogDefinition<T>, state: CatalogState): string {
215  const params = new URLSearchParams();
216  if (state.q) params.set("q", state.q);
217  for (const field of def.fields) {
218    for (const value of state.filters[field.key] ?? []) params.append(field.key, value);
219  }
220  if (state.sort && state.sort !== def.defaultSort) params.set("sort", state.sort);
221  if (state.page > 1) params.set("page", String(state.page));
222  const query = params.toString();
223  return query ? `${def.basePath}?${query}` : def.basePath;
224}
225
226// The address a request should have, or null when it already has it. A browser submitting the form with no script
227// sends every control, including the ones at their defaults (`?q=phage&sort=-updated&kind=`); a server answers
228// that with a redirect to the one address the state has, so what is shared and cached is the clean one.
229export function catalogRedirect<T>(def: CatalogDefinition<T>, url: URL): string | null {
230  const wanted = catalogHref(def, parseCatalogParams(def, url.searchParams));
231  return `${url.pathname}${url.search}` === wanted ? null : wanted;
232}
233
234const DIRECTION_WORDS = {
235  text: { asc: "A to Z", desc: "Z to A" },
236  number: { asc: "low to high", desc: "high to low" },
237  date: { asc: "oldest first", desc: "newest first" },
238} as const;
239
240function compareValues(a: string | undefined, b: string | undefined, type: "text" | "number" | "date"): number {
241  // An item with no value sorts last in either direction: the caller handles that.
242  if (type === "number") return Number(a) - Number(b);
243  if (type === "date") return (a ?? "") < (b ?? "") ? -1 : (a ?? "") > (b ?? "") ? 1 : 0;
244  return fold(a ?? "").localeCompare(fold(b ?? ""), "en", { numeric: true });
245}
246
247// How well the typed words match an item: every word must appear, and a word that starts a word of a field
248// counts double. null is no match.
249function searchScore<T>(def: CatalogDefinition<T>, item: T, tokens: string[]): number | null {
250  const fields = def.fields.filter((f) => f.search);
251  const folded = fields.map((f) => ({ weight: f.search === true ? 1 : Number(f.search), text: asList(f.value(item)).map(fold).join(" ") }));
252  let total = 0;
253  for (const token of tokens) {
254    let best = 0;
255    for (const { weight, text } of folded) {
256      if (!text.includes(token)) continue;
257      const starts = text.startsWith(token) || text.includes(` ${token}`);
258      best = Math.max(best, weight * (starts ? 2 : 1));
259    }
260    if (best === 0) return null;
261    total += best;
262  }
263  return total;
264}
265
266function matchesFilters<T>(def: CatalogDefinition<T>, item: T, filters: Record<string, string[]>, except?: string): boolean {
267  for (const field of def.fields) {
268    if (field.key === except) continue;
269    const chosen = filters[field.key];
270    if (!chosen || chosen.length === 0) continue;
271    const has = asList(field.value(item));
272    if (!chosen.some((value) => has.includes(value))) return false;
273  }
274  return true;
275}
276
277export function queryCatalog<T>(def: CatalogDefinition<T>, items: readonly T[], state: CatalogState): CatalogResult<T> {
278  const tokens = fold(state.q).split(" ").filter(Boolean);
279  const searching = tokens.length > 0;
280  const scores = new Map<string, number>();
281  const matchesSearch = (item: T): boolean => {
282    if (!searching) return true;
283    const key = def.itemKey(item);
284    if (!scores.has(key)) {
285      const s = searchScore(def, item, tokens);
286      scores.set(key, s ?? -1);
287    }
288    return (scores.get(key) ?? -1) >= 0;
289  };
290  const searched = items.filter(matchesSearch);
291
292  const matched = searched.filter((item) => matchesFilters(def, item, state.filters));
293
294  // The order. An explicit sort wins; with a search typed and no sort, best match first; else the default.
295  const sortValue = state.sort || (searching ? "" : def.defaultSort ?? "");
296  const rank = (item: T) => scores.get(def.itemKey(item)) ?? 0;
297  const byField = (value: string) => {
298    const key = value.replace(/^-/, "");
299    const dir = value.startsWith("-") ? -1 : 1;
300    const field = def.fields.find((f) => f.key === key);
301    const type = field?.type ?? "text";
302    const custom = typeof field?.sort === "object" ? field.sort.compare : undefined;
303    return (a: T, b: T) => {
304      if (custom) return dir * custom(a, b);
305      const av = asList(field?.value(a) ?? null)[0];
306      const bv = asList(field?.value(b) ?? null)[0];
307      if (av === undefined && bv === undefined) return 0;
308      if (av === undefined) return 1;
309      if (bv === undefined) return -1;
310      return dir * compareValues(av, bv, type);
311    };
312  };
313  const fallback = def.defaultSort ? byField(def.defaultSort) : () => 0;
314  const primary = sortValue ? byField(sortValue) : (a: T, b: T) => rank(b) - rank(a);
315  const rows = [...matched].sort((a, b) => primary(a, b) || (searching && !state.sort ? rank(b) - rank(a) : 0) || fallback(a, b) || def.itemKey(a).localeCompare(def.itemKey(b)));
316
317  const pageSize = def.pageSize ?? 0;
318  const pageCount = pageSize > 0 ? Math.max(1, Math.ceil(rows.length / pageSize)) : 1;
319  const page = Math.min(state.page, pageCount);
320  const slice = pageSize > 0 ? rows.slice((page - 1) * pageSize, page * pageSize) : rows;
321  const from = slice.length === 0 ? 0 : (page - 1) * (pageSize || rows.length) + 1;
322
323  // Headings only in the default order with nothing typed: any other order would scatter a group's rows.
324  const grouped = def.group !== undefined && !searching && sortValue === def.defaultSort;
325  const groups = grouped ? groupRows(def, slice) : null;
326
327  // Facet counts hold every other filter and the search, and not the facet's own, so the options of a field
328  // show what choosing each would give.
329  const facets: CatalogFacetResult[] = def.fields
330    .filter((f) => f.facet)
331    .map((field) => {
332      const facet = field.facet as CatalogFacet;
333      const base = searched.filter((item) => matchesFilters(def, item, state.filters, field.key));
334      const counts = new Map<string, number>();
335      for (const item of items) for (const value of asList(field.value(item))) if (!counts.has(value)) counts.set(value, 0);
336      for (const item of base) for (const value of new Set(asList(field.value(item)))) counts.set(value, (counts.get(value) ?? 0) + 1);
337      const chosen = state.filters[field.key] ?? [];
338      for (const value of chosen) if (!counts.has(value)) counts.set(value, 0);
339      const label = facet.label ?? ((v: string) => v);
340      let values = [...counts.keys()];
341      if (Array.isArray(facet.order)) {
342        const fixed = facet.order as readonly string[];
343        values.sort((a, b) => (fixed.indexOf(a) === -1 ? 1e6 : fixed.indexOf(a)) - (fixed.indexOf(b) === -1 ? 1e6 : fixed.indexOf(b)) || a.localeCompare(b));
344      } else if (facet.order === "alpha") {
345        values.sort((a, b) => fold(label(a)).localeCompare(fold(label(b)), "en", { numeric: true }));
346      } else {
347        values.sort((a, b) => (counts.get(b) ?? 0) - (counts.get(a) ?? 0) || fold(label(a)).localeCompare(fold(label(b)), "en", { numeric: true }));
348      }
349      values = values.filter((v) => (counts.get(v) ?? 0) > 0 || chosen.includes(v));
350      return {
351        key: field.key,
352        label: field.label,
353        kind: facet.kind ?? "many",
354        general: facet.general === true,
355        limit: facet.limit ?? 8,
356        options: values.map((value) => ({ value, label: label(value), count: counts.get(value) ?? 0, selected: chosen.includes(value) })),
357        selected: chosen.length,
358      };
359    })
360    // General facets first, the rest in the order they were declared.
361    .sort((a, b) => Number(b.general) - Number(a.general));
362
363  const href = (change: Partial<CatalogState> = {}): string => catalogHref(def, { ...state, ...change });
364
365  const chips: CatalogChip[] = [];
366  if (state.q) chips.push({ id: "q", field: "q", value: state.q, label: `"${state.q}"`, href: href({ q: "", page: 1 }) });
367  for (const facet of facets) {
368    for (const option of facet.options.filter((o) => o.selected)) {
369      const remaining = (state.filters[facet.key] ?? []).filter((v) => v !== option.value);
370      chips.push({
371        id: `${facet.key}:${option.value}`,
372        field: facet.key,
373        value: option.value,
374        label: `${facet.label}: ${option.label}`,
375        href: href({ filters: { ...state.filters, [facet.key]: remaining }, page: 1 }),
376      });
377    }
378  }
379
380  const sorts: CatalogSortOption[] = [];
381  if (searching) sorts.push({ value: "", label: "Best match", selected: !state.sort });
382  for (const field of def.fields) {
383    if (!field.sort) continue;
384    const words = (typeof field.sort === "object" ? field.sort.labels : undefined) ?? DIRECTION_WORDS[field.type ?? "text"];
385    for (const dir of ["asc", "desc"] as const) {
386      const value = dir === "asc" ? field.key : `-${field.key}`;
387      sorts.push({ value, label: `${field.label}, ${words[dir]}`, selected: sortValue === value });
388    }
389  }
390
391  return {
392    state: { ...state, page },
393    total: items.length,
394    count: rows.length,
395    rows: slice,
396    groups,
397    page,
398    pageCount,
399    from,
400    to: from === 0 ? 0 : from + slice.length - 1,
401    facets,
402    chips,
403    clearHref: chips.length > 0 ? catalogHref(def, { q: "", filters: {}, sort: state.sort, page: 1 }) : null,
404    sorts,
405    href,
406  };
407}
408
409// The rows in order, cut into runs of one group value. An item with no value goes under "Other".
410function groupRows<T>(def: CatalogDefinition<T>, rows: readonly T[]): CatalogRowGroup<T>[] {
411  const group = def.group as CatalogGroup<T>;
412  const field = def.fields.find((f) => f.key === group.field) as CatalogField<T>;
413  const groups: CatalogRowGroup<T>[] = [];
414  for (const row of rows) {
415    const value = group.value ? group.value(row) : (asList(field.value(row))[0] ?? "");
416    const last = groups[groups.length - 1];
417    if (last && last.value === value) last.rows.push(row);
418    else groups.push({ value, label: value === "" ? "Other" : (group.label?.(value) ?? value), rows: [row] });
419  }
420  return groups;
421}
422
423// "3 of 14 protocols", "14 protocols", "1 protocol": the live count in words with its total.
424export function countText<T>(def: CatalogDefinition<T>, result: Pick<CatalogResult<T>, "count" | "total">): string {
425  const noun = (n: number) => (n === 1 ? def.noun[0] : def.noun[1]);
426  return result.count === result.total ? `${result.total} ${noun(result.total)}` : `${result.count} of ${result.total} ${noun(result.total)}`;
427}
428
429// The state as a downloadable table: the matching items' columns, so a CSV or JSON export is the same
430// rows the page shows (not a second query).
431export function catalogRecords<T>(def: CatalogDefinition<T>, items: readonly T[], state: CatalogState): Array<Record<string, string>> {
432  const everything = queryCatalog({ ...def, pageSize: undefined }, items, { ...state, page: 1 });
433  return everything.rows.map((item) => {
434    const record: Record<string, string> = {};
435    for (const field of def.fields) {
436      if (!field.column) continue;
437      record[field.column.header ?? field.label] = asList(field.value(item)).join("; ");
438    }
439    return record;
440  });
441}