diff --git a/website/src/components/MarkdownContent.astro b/website/src/components/MarkdownContent.astro
index b0e31a6d..402cedf4 100644
--- a/website/src/components/MarkdownContent.astro
+++ b/website/src/components/MarkdownContent.astro
@@ -20,3 +20,14 @@ const { searchWeight } = Astro.locals.starlightRoute.entry.data;
+
+
+
diff --git a/website/src/scripts/site.ts b/website/src/scripts/site.ts
index 68a426dc..c503a0ee 100644
--- a/website/src/scripts/site.ts
+++ b/website/src/scripts/site.ts
@@ -1,6 +1,8 @@
// Progressive enhancement of the generated pages: table captions, filters
-// and phone layout, the hash lookup on files/, moved cards, a hash typed in
-// the search, glossary terms on a tap, and the 404 page's hints.
+// and keyboard scrolling, the hash lookup on files/, moved cards, a hash
+// typed in the search, glossary terms on a tap, and the 404 page's hints.
+// Which tables stack on a phone is decided when the page is built
+// (src/plugins/rehype-stack-tables.mjs), so the layout is right on first paint.
const HASH_LENGTHS: Record = { 8: 'CRC32', 32: 'MD5', 40: 'SHA1', 64: 'SHA256' };
const LAYER_LABELS: Record = {
@@ -17,16 +19,39 @@ const isHash = (value: string) => /^[0-9a-f]+$/.test(value) && value.length in H
// Tables
+// The heading a table sits under: the nearest one before it, looking up
+// through the blocks that hold it, else the page title.
const headingText = (element: Element): string => {
- let cursor: Element | null = element;
- while (cursor) {
- cursor = cursor.previousElementSibling;
- if (!cursor) break;
- const heading = /^H[1-6]$/.test(cursor.tagName) ? cursor : cursor.querySelector('h1, h2, h3, h4, h5, h6');
- if (heading && cursor.classList.contains('sl-heading-wrapper')) return heading.textContent!.trim();
- if (/^H[1-6]$/.test(cursor.tagName)) return cursor.textContent!.trim();
+ for (let block: Element | null = element; block && !block.matches('.sl-markdown-content'); block = block.parentElement) {
+ for (let cursor = block.previousElementSibling; cursor; cursor = cursor.previousElementSibling) {
+ const heading = /^H[1-6]$/.test(cursor.tagName)
+ ? cursor
+ : cursor.classList.contains('sl-heading-wrapper')
+ ? cursor.querySelector('h1, h2, h3, h4, h5, h6')
+ : null;
+ if (heading?.textContent?.trim()) return heading.textContent.trim();
+ }
}
- return document.querySelector('h1')?.textContent?.trim() || 'Data table';
+ return document.querySelector('h1')?.textContent?.trim() || document.title;
+};
+
+// Each table's name, once per page: two tables under one heading are told
+// apart by their order, so no two regions share a label (axe landmark-unique).
+const tableNames = new WeakMap();
+const tableName = (table: HTMLTableElement): string => {
+ let name = tableNames.get(table);
+ if (name) return name;
+ const tables = [...document.querySelectorAll('.sl-markdown-content table')];
+ const seen = new Map();
+ for (const each of tables) {
+ const heading = headingText(each);
+ const count = (seen.get(heading) ?? 0) + 1;
+ seen.set(heading, count);
+ tableNames.set(each, count === 1 ? heading : `${heading}, table ${count}`);
+ }
+ name = tableNames.get(table) ?? headingText(table);
+ tableNames.set(table, name);
+ return name;
};
// A table that overflows is a named stop in the tab order, so a keyboard
@@ -39,11 +64,10 @@ const markScrollable = (tables: HTMLTableElement[]) => {
};
const setScrollable = (table: HTMLTableElement, overflows: boolean) => {
- const heading = table.dataset.rbHeading ?? 'Data table';
if (overflows) {
table.tabIndex = 0;
table.setAttribute('role', 'region');
- table.setAttribute('aria-label', `${heading}, scrollable table`);
+ table.setAttribute('aria-label', `${tableName(table)}, scrollable table`);
} else if (table.getAttribute('role') === 'region') {
table.removeAttribute('tabindex');
table.removeAttribute('role');
@@ -51,21 +75,6 @@ const setScrollable = (table: HTMLTableElement, overflows: boolean) => {
}
};
-// A table whose rows end in an action (a button, a pack to download) is laid
-// out one block per row on a phone, each cell under its column name, so the
-// action never sits behind a horizontal scroll.
-const stackActionTable = (table: HTMLTableElement) => {
- if (!table.querySelector('tbody :is(.rb-button, a[href*="/releases/download/"], a[href$="/releases/latest"])')) return;
- const labels = [...table.querySelectorAll('thead th')].map((cell) => cell.textContent!.trim());
- if (!labels.length) return;
- table.dataset.rbStack = 'true';
- for (const row of table.querySelectorAll('tbody tr')) {
- [...row.children].forEach((cell, column) => {
- if (labels[column] && !cell.hasAttribute('data-label')) cell.setAttribute('data-label', labels[column]);
- });
- }
-};
-
const filterTable = (table: HTMLTableElement, index: number, heading: string) => {
const rows = [...table.querySelectorAll('tbody tr')];
if (rows.length < 20) return;
@@ -104,15 +113,13 @@ const enhanceTables = () => {
const tables = [...document.querySelectorAll('.sl-markdown-content table')];
const enhance = (table: HTMLTableElement) => {
for (const cell of table.querySelectorAll('thead th')) if (!cell.hasAttribute('scope')) cell.setAttribute('scope', 'col');
- const heading = headingText(table);
- table.dataset.rbHeading = heading;
+ const heading = tableName(table);
if (!table.querySelector('caption') && !table.closest('.rb-meta-card')) {
const caption = document.createElement('caption');
caption.className = 'rb-visually-hidden';
caption.textContent = heading;
table.prepend(caption);
}
- stackActionTable(table);
filterTable(table, tables.indexOf(table), heading);
};
// A table is set up and measured when it nears the screen. Doing all of
@@ -160,32 +167,164 @@ const lookupShard = (value: string): Promise- =>
.then((response) => (response.ok ? response.json() : { items: [] }))
.then((shard) => shard.items || []);
-const renderMatches = (status: HTMLElement, value: string, items: Item[]) => {
- status.textContent = '';
- const heading = document.createElement('p');
- heading.textContent = `${items.length} ${items.length === 1 ? 'match' : 'matches'} for ${HASH_LENGTHS[value.length]} ${value}:`;
- status.append(heading);
- for (const [layer, label] of Object.entries(LAYER_LABELS)) {
- const found = items.filter((item) => item.layer === layer);
- if (!found.length) continue;
- const title = document.createElement('p');
- const strong = document.createElement('strong');
- strong.textContent = label;
- title.append(strong);
+type Held = { name: string; path: string; sha1: string; size: number };
+type Declared = { name?: string; destination?: string; required?: boolean; [hash: string]: unknown };
+
+const json = (path: string) =>
+ fetch(new URL(path, siteRoot())).then((response) => (response.ok ? response.json() : Promise.reject(response.status)));
+
+const formatSize = (bytes: number) =>
+ bytes >= 1024 ** 3 ? `${(bytes / 1024 ** 3).toFixed(1)} GB`
+ : bytes >= 1024 ** 2 ? `${(bytes / 1024 ** 2).toFixed(1)} MB`
+ : bytes >= 1024 ? `${(bytes / 1024).toFixed(1)} KB`
+ : `${bytes} B`;
+
+const code = (text: string) => {
+ const element = document.createElement('code');
+ element.textContent = text;
+ return element;
+};
+
+const link = (url: string, ...content: (Node | string)[]) => {
+ const element = document.createElement('a');
+ element.href = new URL(url, siteRoot()).href;
+ element.append(...content);
+ return element;
+};
+
+const paragraph = (...content: (Node | string)[]) => {
+ const element = document.createElement('p');
+ element.append(...content);
+ return element;
+};
+
+const strong = (text: string) => {
+ const element = document.createElement('strong');
+ element.textContent = text;
+ return element;
+};
+
+// The card a collection match points at, read from its manufacturer's file
+// of api/v1/systems/: the path in the collection and the size.
+const heldFile = async (item: Item & { sha1?: string }): Promise => {
+ const slug = /^systems\/([^/]+)\//.exec(item.url)?.[1];
+ if (!slug || !item.sha1) return undefined;
+ const data = await json(`api/v1/systems/${slug}.json`);
+ for (const files of Object.values(data.items?.[0]?.consoles ?? {})) {
+ const found = files.find((file) => file.sha1 === item.sha1);
+ if (found) return found;
+ }
+ return undefined;
+};
+
+// A setup's own entry for the value, from its contract in api/v1/platforms/:
+// where the file goes and whether the setup requires it. Recalbox writes
+// several MD5 in one field, separated by commas.
+const declaredEntry = async (item: Item, value: string): Promise => {
+ const system = decodeURIComponent(new URL(item.url, siteRoot()).hash.slice(1));
+ const data = await json(`api/v1/platforms/${item.owner}.json`);
+ const files: Declared[] = data.items?.[0]?.contract?.systems?.[system]?.files ?? [];
+ const holds = (entry: Declared) =>
+ String(entry[item.algorithm] ?? '').toLowerCase().split(',').map((hash) => hash.trim()).includes(value);
+ return files.find((entry) => holds(entry) && entry.name === item.name) ?? files.find(holds);
+};
+
+const setupTable = (rows: { item: Item; entry?: Declared; setup: string }[]) => {
+ const table = document.createElement('table');
+ const head = table.createTHead().insertRow();
+ for (const label of ['Setup', 'Name as declared', 'Destination', 'Hash matched', 'Required']) {
+ const cell = document.createElement('th');
+ cell.scope = 'col';
+ cell.textContent = label;
+ head.append(cell);
+ }
+ const body = table.createTBody();
+ for (const { item, entry, setup } of rows) {
+ const row = body.insertRow();
+ const name = entry?.name ?? item.name ?? '';
+ // EmuDeck lists a hash with no file name: any file that has it passes.
+ const named = name && !name.includes(':');
+ const destination = entry?.destination;
+ const cells: (Node | string)[] = [
+ link(item.url, setup),
+ named ? code(name) : 'Any name',
+ destination ? code(destination) : '-',
+ item.algorithm.toUpperCase(),
+ entry?.required === undefined ? '-' : entry.required ? 'Yes' : 'No',
+ ];
+ cells.forEach((content, column) => {
+ const cell = row.insertCell();
+ cell.dataset.label = head.cells[column].textContent!;
+ cell.append(content);
+ });
+ }
+ table.dataset.rbStack = 'true';
+ return table;
+};
+
+// The answer first: which file this is and where the collection holds it,
+// then the setups that list it (where it goes, whether it is required),
+// then the emulators that read it.
+const renderMatches = async (status: HTMLElement, result: HTMLElement, value: string, items: Item[]) => {
+ const byLayer = (layer: string) => items.filter((item) => item.layer === layer);
+ const held = byLayer('collection');
+ const platforms = byLayer('platform');
+ const [files, entries, names] = await Promise.all([
+ Promise.all(held.map((item) => heldFile(item).catch(() => undefined))),
+ Promise.all(platforms.map((item) => declaredEntry(item, value).catch(() => undefined))),
+ json('data/picker/index.json').catch(() => []) as Promise<{ platform: string; name: string }[]>,
+ ]);
+ const setupName = new Map(names.map((entry) => [entry.platform, entry.name]));
+ status.textContent = `${items.length.toLocaleString('en')} ${items.length === 1 ? 'match' : 'matches'} for ${HASH_LENGTHS[value.length]} ${value}.`;
+ const blocks: Node[] = [];
+ held.forEach((item, index) => {
+ const file = files[index];
+ const name = file?.name ?? item.name ?? value;
+ blocks.push(
+ file
+ ? paragraph('This is ', code(name), ', held in the collection at ', code(file.path), '.')
+ : paragraph('This is ', code(name), ', held in the collection.'),
+ paragraph(
+ ...(file ? ['SHA1 ', code(file.sha1), `, ${formatSize(file.size)}. `] : []),
+ link(item.url, 'Open its card'),
+ '.',
+ ),
+ );
+ });
+ if (!held.length) blocks.push(paragraph('No file in the collection has this hash.'));
+ const shipped = byLayer('data-directory');
+ if (shipped.length) {
const list = document.createElement('ul');
- for (const item of found) {
+ for (const item of shipped) {
const row = document.createElement('li');
- const link = document.createElement('a');
- link.href = new URL(item.url, siteRoot()).href;
- const code = document.createElement('code');
- code.textContent = item.name || item.value;
- link.append(code);
- row.append(link);
- if (item.owner) row.append(` (${item.owner})`);
+ row.append(link(item.url, code(item.name || item.value)));
list.append(row);
}
- status.append(title, list);
+ blocks.push(paragraph(strong(LAYER_LABELS['data-directory'])), list);
}
+ if (platforms.length) {
+ const owners = new Set(platforms.map((item) => item.owner));
+ blocks.push(
+ paragraph(strong(`Setups that list it (${owners.size})`)),
+ setupTable(platforms.map((item, index) => ({
+ item,
+ entry: entries[index],
+ setup: setupName.get(item.owner ?? '') ?? item.owner ?? '',
+ }))),
+ );
+ }
+ const readers = byLayer('emulator');
+ if (readers.length) {
+ const list = document.createElement('ul');
+ for (const item of readers) {
+ const row = document.createElement('li');
+ row.append(link(item.url, item.owner ?? item.name ?? ''));
+ if (item.name && item.name !== held[0]?.name) row.append(' as ', code(item.name));
+ list.append(row);
+ }
+ blocks.push(paragraph(strong(`${LAYER_LABELS.emulator} (${readers.length})`)), list);
+ }
+ result.replaceChildren(...blocks);
};
// files/?sha1= is a file's content address and opens its card
@@ -194,6 +333,9 @@ const renderMatches = (status: HTMLElement, value: string, items: Item[]) => {
const resolveFileAddress = () => {
const status = document.getElementById('rb-file-lookup-status');
if (!status) return;
+ const result = document.createElement('div');
+ result.id = 'rb-file-lookup-result';
+ status.after(result);
const params = new URLSearchParams(location.search);
const permalink = params.has('sha1');
const value = normalizeHash(params.get('sha1') || params.get('hash') || '');
@@ -214,7 +356,7 @@ const resolveFileAddress = () => {
if (permalink && new Set(cards.map((item) => item.url)).size === 1) {
location.replace(new URL(cards[0].url, siteRoot()));
} else if (matches.length) {
- renderMatches(status, prefix ? matches[0].value : value, prefix ? cards : matches);
+ return renderMatches(status, result, prefix ? matches[0].value : value, prefix ? cards : matches);
} else {
status.textContent = 'No file the site knows has this hash.';
}
@@ -240,8 +382,65 @@ const followMovedCard = () => {
if (match && !target) location.replace(new URL(`files/?sha1=${match[1]}`, siteRoot()));
};
-// The site search holds no hashes: Enter on one opens the lookup.
+// The site search holds no hashes. A hash typed in it gets "Look up this
+// hash" as its first result, and Enter opens the lookup.
+const hashLookupRow = (drawer: Element, value: string) => {
+ let row = drawer.querySelector(':scope > .rb-search-hash');
+ if (!isHash(value)) {
+ row?.remove();
+ return;
+ }
+ if (!row) {
+ row = document.createElement('p');
+ row.className = 'rb-search-hash';
+ drawer.prepend(row);
+ }
+ const target = new URL(`files/?hash=${value}`, siteRoot()).href;
+ if (row.querySelector('a')?.href === target) return;
+ const anchor = document.createElement('a');
+ anchor.href = target;
+ anchor.append('Look up this hash');
+ row.replaceChildren(anchor, ` ${HASH_LENGTHS[value.length]} `, code(value));
+};
+
+// Pagefind lists a page's title twice: once for the page and once for the
+// anchor of its h1 (#_top). The second title is hidden, its excerpt kept.
+// The `files` field of a system page weighs its file names in the ranking
+// and is never shown: a result is not a list of 120 names. Pagefind reuses
+// its nodes from one query to the next, so both are worked out again on
+// every change.
+const tidyResults = (root: Element) => {
+ for (const title of root.querySelectorAll('.pagefind-ui__result-nested > .pagefind-ui__result-title')) {
+ title.hidden = !!title.querySelector('a')?.getAttribute('href')?.endsWith('#_top');
+ }
+ for (const tags of root.querySelectorAll('.pagefind-ui__result-tags')) {
+ let shown = 0;
+ for (const tag of tags.querySelectorAll('.pagefind-ui__result-tag')) {
+ tag.hidden = tag.dataset.pagefindUiMeta === 'files';
+ if (!tag.hidden) shown += 1;
+ }
+ tags.hidden = shown === 0;
+ }
+};
+
const hashSearch = () => {
+ const root = document.getElementById('starlight__search');
+ if (root) {
+ const refresh = () => {
+ tidyResults(root);
+ const input = root.querySelector('input');
+ const drawer = root.querySelector('.pagefind-ui__drawer');
+ if (input && drawer) hashLookupRow(drawer, normalizeHash(input.value));
+ };
+ new MutationObserver(refresh).observe(root, {
+ childList: true,
+ subtree: true,
+ characterData: true,
+ attributes: true,
+ attributeFilter: ['href', 'data-pagefind-ui-meta'],
+ });
+ root.addEventListener('input', refresh);
+ }
document.addEventListener(
'keydown',
(event) => {