Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 15 additions & 5 deletions apps/apidocs-astro/astro.config.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,17 @@ import { apidocs } from "@elide/apidocs/astro/integration";
import { defineConfig } from "astro/config";
import { guidesPlugin } from "./scripts/guides.mjs";

const theme = { extends: "elide" };
// Each site's top bar switches between the sample's documentation sites, with its own marked as current.
const theme = current => ({
extends: "elide",
links: {
header: [
{ label: "User guide", url: "/guides/", current: current === "guides" },
{ label: "Java API", url: "/java/2.0/", current: current === "java" },
{ label: "Kotlin API", url: "/kotlin/", current: current === "kotlin" },
],
},
});

export default defineConfig({
adapter: cloudflare(),
Expand All @@ -15,10 +25,10 @@ export default defineConfig({
integrations: [
apidocs({
sites: [
{ base: "/java/2.0/", model: "./src/models/java.ts", theme, version: "2.0" },
{ base: "/java/main/", model: "./src/models/java.ts", theme, version: "main" },
{ base: "/kotlin/", model: "./src/models/kotlin.ts", theme },
{ base: "/guides/", model: "./src/generated/guides.json", theme },
{ base: "/java/2.0/", model: "./src/models/java.ts", theme: theme("java"), version: "2.0" },
{ base: "/java/main/", model: "./src/models/java.ts", theme: theme("java"), version: "main" },
{ base: "/kotlin/", model: "./src/models/kotlin.ts", theme: theme("kotlin") },
{ base: "/guides/", model: "./src/generated/guides.json", theme: theme("guides") },
],
versions: "./src/versions.ts",
}),
Expand Down
120 changes: 111 additions & 9 deletions apps/apidocs-astro/test/browser.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,8 @@
* top bar and navigator, the page behaviors across navigations, server islands, JavaScript off, reduced motion,
* layout stability, axe, and head metadata against the static renderer.
*
* Builds the app and starts wrangler dev on port 5191 unless APIDOCS_ASTRO_URL names a running server. Needs a
* Playwright 1.65 Chromium (PLAYWRIGHT_BROWSERS_PATH).
* Builds the app and starts wrangler dev on port 5191 (APIDOCS_ASTRO_PORT picks another) unless APIDOCS_ASTRO_URL
* names a running server. Needs a Playwright 1.65 Chromium (PLAYWRIGHT_BROWSERS_PATH).
*/
import { afterAll, beforeAll, describe, expect, test } from "bun:test";
import { type ChildProcess, spawn, spawnSync } from "node:child_process";
Expand All @@ -17,7 +17,7 @@ import { type Browser, type BrowserContextOptions, chromium, type Page } from "p

const app = fileURLToPath(new URL("..", import.meta.url));
const require = createRequire(import.meta.url);
const PORT = 5191;
const PORT = Number(process.env.APIDOCS_ASTRO_PORT ?? 5191);
let origin = process.env.APIDOCS_ASTRO_URL?.replace(/\/$/, "") ?? `http://127.0.0.1:${PORT}`;
let server: ChildProcess | undefined;
let browser: Browser;
Expand Down Expand Up @@ -155,10 +155,50 @@ describe("the persisted top bar and navigator", () => {
await page.context().close();
});

test("the index links follow the page", async () => {
test("the navigator's index links follow the page", async () => {
const { page } = await open(TYPE);
await follow(page, '.topbar-nav a[href="/java/2.0/packages"]');
expect(await page.locator('.topbar-nav [aria-current="page"]').getAttribute("href")).toBe("/java/2.0/packages");
expect(await page.locator('.nav-reference [aria-current="page"]').count()).toBe(0);
await follow(page, '.nav-reference a[href="/java/2.0/packages"]');
expect(await page.locator('.nav-reference [aria-current="page"]').getAttribute("href")).toBe("/java/2.0/packages");
await follow(page, '.nav-reference a[href="/java/2.0/index-all"]');
expect(await page.locator('.nav-reference [aria-current="page"]').getAttribute("href")).toBe("/java/2.0/index-all");
expect(await page.locator('.sidebar [aria-current="page"]').count()).toBe(1);
await page.context().close();
});

test("the suite switcher marks the current site, within a site and after moving to another", async () => {
const { page, documents } = await open(TYPE);
const current = () => page.locator('.suites-row a[aria-current="true"]').textContent();
expect(await current()).toBe("Java API");
expect(await page.locator('.suites-row a[aria-current="true"]').getAttribute("href")).toBe("/java/2.0/");
await follow(page, `.sidebar a[href="${OTHER}"]`);
expect(await current()).toBe("Java API");
expect(await page.locator(".suites").getAttribute("data-fit")).toBe("row");
await follow(page, '.suites-row a[href="/kotlin/"]');
expect(new URL(page.url()).pathname).toBe("/kotlin/");
expect(await current()).toBe("Kotlin API");
expect(await page.locator('.suites-row a[aria-current="true"]').getAttribute("href")).toBe("/kotlin/");
expect(await page.locator(".suites").getAttribute("data-fit")).toBe("row");
await follow(page, '.suites-row a[href="/guides/"]');
expect(await current()).toBe("User guide");
// The guides-only site has its overview as a guide, so the navigator lists no index links.
expect(await page.locator(".nav-reference, .nav-index").count()).toBe(0);
expect(documents).toEqual([]);
await page.context().close();
});

test("on a phone the switcher leaves the bar, and the drawer lists the sites first", async () => {
const { page } = await open(TYPE, { viewport: { width: 360, height: 700 } });
expect(await page.locator(".suites").getAttribute("data-fit")).toBe("none");
expect(await page.locator(".suites-row").isVisible()).toBe(false);
await page.locator(".nav-button").click();
const first = page.locator(".sidebar > :first-child");
expect(await first.evaluate(e => e.classList.contains("nav-suites"))).toBe(true);
expect(await first.locator("a").allTextContents()).toEqual(["User guide", "Java API", "Kotlin API"]);
// After a navigation the drawer's blocks keep their order around the kept filter field.
await follow(page, `.sidebar a[href="${OTHER}"]`);
expect(await page.locator(".sidebar > :first-child").evaluate(e => e.classList.contains("nav-suites"))).toBe(true);
expect(await page.locator(".sidebar > :nth-child(2)").evaluate(e => e.classList.contains("nav-filter"))).toBe(true);
await page.context().close();
});

Expand Down Expand Up @@ -331,6 +371,48 @@ describe("layout stability", () => {
});
});

describe("the top bar", () => {
/** packages/apidocs/test/topbar.test.ts topBarProblems, for the app's own pages: what wraps, overflows or is cut off. */
const problems = (page: Page) => page.evaluate(() => {
const bar = document.querySelector<HTMLElement>(".topbar")!;
const box = bar.getBoundingClientRect();
const found: string[] = [];
if (bar.scrollWidth > bar.clientWidth) found.push(`the bar scrolls: ${bar.scrollWidth} > ${bar.clientWidth}`);
const shown = (e: Element) => {
for (let n: Element | null = e; n && n !== bar.parentElement; n = n.parentElement) {
const s = getComputedStyle(n);
if (s.display === "none" || s.visibility === "hidden" || n.classList.contains("visually-hidden")) return false;
}
return true;
};
for (const e of bar.querySelectorAll<HTMLElement>("*")) {
if (e.matches(".suites-fit, .suites-probe") || e.closest(".search-results, .suite-list, .version-list, script") || !shown(e)) continue;
const r = e.getBoundingClientRect();
if ((r.width === 0 && r.height === 0) || r.bottom < 0) continue;
const s = getComputedStyle(e);
const name = `${e.tagName.toLowerCase()}.${typeof e.className === "string" ? e.className.split(" ")[0] : ""}`;
if (r.left < box.left - 0.5 || r.right > box.right + 0.5 || r.top < box.top - 0.5 || r.bottom > box.bottom + 0.5) found.push(`${name} lies outside the bar`);
if (s.overflowX !== "visible" && e.scrollWidth > e.clientWidth + 1 && s.textOverflow !== "ellipsis" && !(e instanceof HTMLInputElement)) found.push(`${name} is cut off`);
}
return found;
});

for (const path of [TYPE, "/kotlin/org/example/kgeo/Geometry", "/guides/guides/getting-started"]) {
test(`${path}: nothing wraps, overflows or is cut off from 320 to 1600px`, async () => {
const { page } = await open(path, { viewport: { width: 1600, height: 600 } });
await page.waitForSelector(".topbar");
const found: string[] = [];
for (let width = 320; width <= 1600; width += 20) {
await page.setViewportSize({ width, height: 600 });
await page.evaluate(() => new Promise(r => requestAnimationFrame(() => requestAnimationFrame(r))));
for (const problem of await problems(page)) found.push(`${width}px: ${problem}`);
}
expect(found).toEqual([]);
await page.context().close();
}, 120_000);
}
});

describe("server islands", () => {
test("the version menu lists the versions and opens the same page in another one", async () => {
const { page, documents } = await open("/java/main/com/example/geo/Circle");
Expand Down Expand Up @@ -395,7 +477,7 @@ describe("reduced motion", () => {

describe("accessibility", () => {
for (const colorScheme of ["light", "dark"] as const) {
for (const path of [TYPE, "/java/2.0/guides/concepts", "/java/2.0/index-all", "/java/main/com/example/geo/", "/guides/"]) {
for (const path of [TYPE, "/java/2.0/guides/concepts", "/java/2.0/index-all", "/java/main/com/example/geo/", "/guides/", "/kotlin/org/example/kgeo/ShapeParseException", "/java/2.0/nope"]) {
test(`${path} in ${colorScheme} has no axe violations`, async () => {
const { page } = await open(path, { colorScheme });
await page.waitForLoadState("networkidle");
Expand Down Expand Up @@ -423,9 +505,10 @@ describe("metadata", () => {
const head = html.split("<head>")[1]!.split("</head>")[0]!;
return {
title: /<title>(.*?)<\/title>/.exec(head)?.[1],
meta: [...head.matchAll(/<meta (?:name|property)="(description|keywords|generator|apidocs:[a-z]+|og:[a-z_]+|twitter:card)" content="([^"]*)"\/?>/g)].map(m => [m[1], m[1] === "og:url" ? map(m[2]!) : m[2]]),
meta: [...head.matchAll(/<meta (?:name|property)="(description|keywords|generator|apidocs:[a-z]+|og:[a-z_]+|twitter:card)" content="([^"]*)"\/?>/g)].map(m => [m[1], m[1] === "og:url" ? map(m[2]!) : m[1] === "og:image" ? "(the social image)" : m[2]]),
links: [...head.matchAll(/<link rel="(canonical|alternate|index)"[^>]*? href="([^"]*)"/g)].map(m => [m[1], map(m[2]!)]),
jsonLd: JSON.parse(/<script type="application\/ld\+json">(.*?)<\/script>/.exec(head)![1]!, (key, value) => (["url", "item", "contentUrl"].includes(key) ? map(value) : value)),
// The social image is the app's bundled file, not the static site's assets/social/.
jsonLd: JSON.parse(/<script type="application\/ld\+json">(.*?)<\/script>/.exec(head)![1]!, (key, value) => (key === "url" && /\.png$/.test(value) ? "(the social image)" : ["url", "item", "contentUrl"].includes(key) ? map(value) : value)),
};
};
expect(metadata(served, u => u)).toEqual(metadata(staticHtml, u => mapUrl(u, ctx)));
Expand All @@ -440,4 +523,23 @@ describe("metadata", () => {
expect(redirect.headers.get("location")).toBe("/java/2.0/com/example/geo/Circle");
expect((await at("/java/2.0/com/example/geo/Nope")).status).toBe(404);
});

test("the social image is served, and a missing page is the site's not-found page, as HTML or Markdown", async () => {
const html = await (await fetch(`${origin}/java/2.0/`)).text();
const image = /<meta property="og:image" content="([^"]*)"/.exec(html)![1]!;
expect(image).toMatch(new RegExp(`^${origin}/_astro/`));
const png = await fetch(image);
expect(png.status).toBe(200);
expect(png.headers.get("content-type")).toBe("image/png");
const missing = await fetch(`${origin}/java/2.0/com/example/geo/Nope`);
expect(missing.status).toBe(404);
const page = await missing.text();
expect(page).toContain("<h1>Not found</h1>");
expect(page).toContain('<a href="/java/2.0/packages">Packages</a>');
expect(page).toContain('<meta name="robots" content="noindex"/>');
const md = await fetch(`${origin}/java/2.0/com/example/geo/Nope`, { headers: { accept: "text/markdown" } });
expect(md.status).toBe(404);
expect(md.headers.get("content-type")).toContain("text/markdown");
expect(await md.text()).toContain("Start at the [overview](/java/2.0/index.md)");
});
});
1 change: 1 addition & 0 deletions bun.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

31 changes: 29 additions & 2 deletions packages/apidocs/AUDITS.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,8 +43,9 @@ the score below; the CSS row is the share of the nine mechanical good-css rules

Lighthouse 13.6.0 (pinned) runs programmatically in the Chromium that Playwright installs, through chrome-launcher, once
per page and form factor (mobile is Lighthouse's default config; desktop uses `desktop-config.js`). It audits the module
overview, the package page with the most types, the smallest type page with real content, and the largest type page
(`ShapeCatalog.html` in the Java sample; `dev/elide/kotlin/api/Ir.html` in the Komodo model). Each run's JSON and HTML
overview, the package page with the most types, the smallest type page with real content, the largest type page
(`ShapeCatalog.html` in the Java sample; `dev/elide/kotlin/api/Ir.html` in the Komodo model), and a guide page
(`guides/getting-started.html` when there is one). Each run's JSON and HTML
report, and a summary of the failing weighted audits with their values, are in `lighthouse/`.

The pages are served the way a static host would serve them: brotli or gzip, `Cache-Control: public, max-age=31536000`
Expand Down Expand Up @@ -83,6 +84,16 @@ Ora's partial-credit thresholds are not all published, and the values used are i
Agentic's own display groups checks as Essential (80 points), Recommended (20) and Bonus (5); that grouping per site
type is not published, so the audit reports Ora's score.

The text the token budget and the content checks measure is what a reader gets: `<pre>` is parsed like any other
element, so a highlighted signature counts as its text, not its markup. (Earlier versions of the audit counted the
markup inside `<pre>`, which made the largest Java sample page read as 175,174 characters; parsed, it was 102,861,
and with each member's summary sentence drawn once it is 89,287.) Built sites get the run's date as the theme's
`lastModified`, as the doclet passes its build date.

The static host profile cannot pass `agent-friendly-404` in full: a missing page gets the site's `404.html` with a
404 status (1 of 2), but answering `Accept: text/markdown` with `404.md` is content negotiation, which a static
host does not do. `--host agent` does it, as the Astro integration's route does.

Each finding names an owner: `page` (markup, CSS, client script), `output` (files the renderer writes: llms.txt,
sitemap.xml, robots.txt, 404 pages, JSON-LD content) or `host` (status codes, headers, negotiation). `--host agent`
serves each page's `.md` twin for `Accept: text/markdown` with `Vary: Accept` and adds Link headers, to show the score
Expand All @@ -106,3 +117,19 @@ everything pressable (approximated: every `:hover` selector has a matching `:act
`prefers-reduced-motion: no-preference`, named transition properties without `all` or `ease-in` and at most 300 ms,
`overflow: clip` over `hidden`, and the declarations the skill leaves out on purpose. The 47 entries need judgment
about where they apply, so each gets a `review` row in the report with what the stylesheet shows; a person settles it.

A declaration may be a noted exception to one rule: a `/* good-css exception (rule-id): reason */` comment before it
in its rule, or before its rule, takes it out of that rule's count, and the report lists it. Each one is a choice
the pages need, kept on purpose:

| Rule | Where | Why |
| --- | --- | --- |
| `motion-properties` | the load bar's two animations | It shows progress, not a change of state: a 6s ease-out so a slow page still shows movement, and 420ms for the arriving page to finish it. Both stay inside `prefers-reduced-motion: no-preference`. |
| `overflow-clip` | `.product`, `.suite-label`, `.result-context`, `.nav-label`, `.toc a` | `overflow: hidden` so `text-overflow: ellipsis` shows in every target browser (Safari before 16 has no `clip`). |
| `overflow-clip` | `.member-brief` | WebKit clamps lines with `-webkit-line-clamp` only under `overflow: hidden`. |
| `fluid-clamp` | where the navigator becomes a drawer (860px): the drawer's padding, the switcher's margin, the search field without its key hint, the drawer's sites block, one-column facts, the summary table as blocks; and the content's padding when the navigator is hidden | Layout changes, not a size stepped at a breakpoint: each value belongs to a different arrangement of the page. |
| `fluid-clamp` | the Elide preset's title and declaration-specimen sizes | The preset sets its type in exact pixels so JetBrains Mono's characters are a whole number of pixels wide: 30px and 15px, 25px and 13.3333px where the navigator is a drawer. A fluid size between them would put the characters off the pixel grid. It is written as a token switch in the preset's CSS. |

Fluid sizes are custom properties at the top of `apidocs.css` (`--apidocs-gutter`, `--apidocs-content-top`, and so
on): the narrow value at 480px wide and below, the wide one from 1000px, a straight line between. They cover spacing,
and the title and specimen sizes of the neutral (fallback) type scale; the scale tokens themselves stay exact.
Loading
Loading