Repository navigation
feat(apidocs): suite switcher, audit fixes and a stylesheet that follows good-css - #30
Conversation
…move to the navigator
The top bar now holds only what belongs to the whole site: the navigator toggle, the
brand, the version (or the Astro version menu), a switcher between sibling
documentation sites, search and the theme switch. Between 1101 and 1180px it
overflowed by 31 to 78px, and below 1100px the sibling links were hidden, so a phone
could not reach the other suites at all.
- The theme's header links are the sibling sites. ThemeLink gains `current`; without
it, the entry whose URL is the site's own root (or its baseUrl) is current. The
switcher is a row of the sites with the current one marked, or, where the bar has
no room, one <details> menu button that names the current site (closed by Escape
and an outside click with the script). Where the navigator is a drawer, the drawer
lists the sites first and the bar shows the row only when it fits.
- No width is written down. Hidden copies of the labels form a wrapping row whose
height (one line or more) places the visible row or the menu, so the layout alone
decides, with or without JavaScript. A small script at the end of the bar, run
before first paint and on resize, sizes the switcher to what it shows, so a menu
leaves no dead space, and hides the other form from the keyboard and assistive
technology. The order in which the bar gives way is in apidocs.css: the search
field narrows (19rem to 10rem, then 5rem in a drawer layout), the switcher gives
way, the product name ends in an ellipsis.
- Overview, Packages, All types, Index and Deprecated are at the top of the
navigator, under the filter: as many as the site has, one line when at most two,
else rows under "Reference" (any three need 223 to 238px against a 223px line at
the narrowest navigator, measured in Chromium at both presets).
- Footer theme links are resolved from the site root, as header links are; a path
from the server root ("/x/") is written as given in both.
- The navigator's filter is there on guides-only sites and narrows guides; it never
filters the sites, the indexes or the packages.
- Fixes found on the way: the drawer took its content's height and sat behind the
top bar, unscrollable (align-self: start on a fixed box); links in the deprecated
index's summaries were not underlined (axe link-in-text-block).
- Astro: the persisted top bar and navigator still update per page. The navigator's
blocks keep their order around the kept filter field, the kept filter text is
applied to the new rows before the scroll position is put back, and a top bar from
another site is sized before it paints. The sample app's sites switch between
each other.
- The dev bar can show none, one, three or five sibling sites.
Tests: test/topbar.test.ts sweeps 320 to 1600px in steps of 20 in the static and the
Astro markup, with 0, 1, 3 and 5 sites, with and without a version menu, and with a
long product name (nothing wraps, overflows or is cut off); the menu with and without
JavaScript; no layout shift at 1440, 1000 and 360px. axe now covers every page kind
in light and dark. The Astro app's suite sweeps its own pages and checks the current
index link and site across navigations. bun test: 306 pass, 4 skip; the Astro app:
32 pass.
Signed-off-by: Sam Gammon <sam@elide.dev>
…, lastmod, llms.txt guidance
Works down the local agent-readiness audit (Ora's checks, as Is Agentic scores them).
- Link previews: a theme's socialImage ({ asset or url, width, height, alt }) gives
og:image, its size and alt text, and a large Twitter card; nothing without one.
Both presets have a 1200x630 image, generated by scripts/gen-social.ts into
artwork/ with sharp (Elide's dark lockup on its dark surface; the neutral preset's
mark, which is also its new favicon, so a browser's /favicon.ico request no longer
logs a 404 on neutral sites). socialImage: null leaves it out. Astro bundles the
images and og:image names the bundled file.
- JSON-LD: every page's item has a url (absolute with a baseUrl, else relative, as
the breadcrumbs are); the overview lists its guides and packages as hasPart.
- 404.html and 404.md: the page shell with links to the overview, the indexes and
llms.txt, noindex, no canonical; with a baseUrl they link from it (<base href>), so
a host can serve them at any depth. Not in llms.txt or the sitemap. The Astro route
renders the same page (status 404) for a missing path, or its Markdown, with links
under the base (notFoundText); notFound()'s wording matches.
- sitemap.xml lastmod from the theme's lastModified (a W3C date), set by the runner's
and the guides command's --last-modified; never from the clock, absent otherwise.
- llms.txt has a "When to use this" section: the theme's whenToUse, or one sentence
from the module's name, version and description.
- Markdown twins open with YAML frontmatter (title, description, kind, id, module,
version, canonical when known), values quoted with <, > and & escaped.
llms-full.txt joins the twins without it; copy as Markdown copies the page without
it; Astro twins name the Astro URL as canonical.
- Page token budget: a member row's summary sentence is drawn from a data attribute
(::before), since the entry inside carries the same sentence as text; the members
filter still matches it. The largest Java sample page goes from 102,861 to 89,287
characters of text. The audit had counted the markup inside <pre> as text (175,174
for that page); it now parses <pre> like any element.
- Audit: Lighthouse also runs on a guide page; the type picks no longer include
guides and the root index pages; built sites get the run's date as lastModified;
the Markdown-fallback check reads the heading after the frontmatter.
Agent readiness, measured: 93/94 before on every sample site; now 97 with the static
host profile (agent-friendly-404 is 1/2 there: answering Accept: text/markdown with
404.md is content negotiation, which a static host does not do) and 100 with
--host agent. bun test: 322 pass, 4 skip; the Astro app: 37 pass.
Signed-off-by: Sam Gammon <sam@elide.dev>
isThrowable looked only for java.lang.Throwable among a type's ancestors, so in a Kotlin model, whose ids are Dokka DRIs, exceptions were grouped with ordinary classes and drew the class glyph. It now accepts java.lang.Throwable, kotlin/Throwable///PointingToDeclaration/ and the Java class as a Kotlin model reaches it, java.lang/Throwable///PointingToDeclaration/, by exact id: a class that merely has "Throwable" in its name is not an exception. The Kotlin sample gains ShapeParseException (ancestors kotlin/Exception, kotlin/Throwable, kotlin/Any as DRIs), now grouped under Exceptions with the exception glyph. Unit tests cover a Java model, a Kotlin model (both DRI forms), a name that contains "Throwable", and the sample's page; the Astro app runs axe on it. Signed-off-by: Sam Gammon <sam@elide.dev>
…s, OKLCH, fluid spacing, guarded hover
Converts src/styles/apidocs.css, the Astro stylesheet and the Elide preset's tokens to
the nine mechanical good-css rules; the local CSS audit goes from 0 to 100 on both
presets.
- Logical properties throughout (inset-*, margin-/padding-block and -inline,
border-inline-start, logical corner radii, text-align: start/end). Left to right
nothing moves; with dir="rtl" the page mirrors (navigator on the right, rail on
the left), code stays left to right there, and a closed member row's chevron
points to the start of the line.
- Colors as oklch(): the neutral defaults converted exactly from their hex values;
the Elide preset's converted from @elide/tokens when it loads (src/color.ts:
lightness to 0.001%, chroma to 0.00001, hue to 0.001 degree; within 0.08 of an
8-bit step on a random sample; a gray's hue is none). test/color.test.ts checks
every token against its former hex value and that text contrast is unchanged.
- Fluid spacing: custom properties with clamp() (narrow value up to 480px, wide from
1000px) for the content's gutter and padding, the top bar's padding and gaps and
the declaration specimen's padding, in place of the 860px steps. The type scale
stays exact: the neutral preset's title and specimen sizes are fluid between two
scale steps, and the Elide preset keeps exact JetBrains Mono sizes, stepped at
860px as a token switch (noted exception).
- :hover only inside (hover: hover) and (pointer: fine), with an :active state for
every hover target; :focus-visible for the skip link; motion (the member fade, the
reading bar, view transitions) only inside prefers-reduced-motion: no-preference;
overflow: clip in place of hidden, except where an ellipsis or a line clamp needs
hidden; text-rendering: optimizeLegibility removed.
- Noted exceptions, each with its reason beside the code and in AUDITS.md, which the
audit now reads ("good-css exception (rule-id): reason" before a declaration or
its rule): the load bar's 6s and 420ms animations (progress, not a transition);
overflow: hidden for five ellipses and one line clamp; and layout changes where
the navigator becomes a drawer, which are arrangements, not stepped sizes.
Pixel comparison against the previous commit, 112 screenshots per run (both presets,
the guides suite; seven pages; light and dark; 1440, 1180, 1101, 1024 and 360px):
largest per-channel difference 6/255 (neutral dark, alpha-blended tints), at most 2
elsewhere, no shift. At 860 and 600px the page changes where intended: spacing is
fluid there now. bun test: 330 pass, 4 skip.
Signed-off-by: Sam Gammon <sam@elide.dev>
…SON-LD has a name Lighthouse flagged target-size (accessibility 97) on the Java sample's LegacyShape page at desktop size, before and after the top bar work: the navigator had scrolled to put the current row a third of the way down, leaving a row half under the sticky filter field, a target partly covered by another. axe counts the field's input as the covering target. - The client scrolls the navigator only when the current row is out of view, as the head script already did; a fresh visit to a page whose row is in view leaves the navigator at its top. - When it must scroll, apidocsNavTop (defined in the head script, used by the client and the Astro client) picks the position nearest the third at which the field sits over a gap between rows (a heading, the space between sections), with the current row in view, and clamps it to the navigator's scroll range first. - A guide's JSON-LD (TechArticle) names it, so a guides-only overview passes the json-ld check's name test (3.2 of 4 before). axe target-size over every page of the Java (both presets), Kotlin and guides sites, at Lighthouse's desktop and mobile viewports: no findings (3 pages each on two sites before the second change). bun test: 330 pass, 4 skip; the Astro app: 37 pass. Signed-off-by: Sam Gammon <sam@elide.dev>
At phone width a member row had no room for the signature and the summary sentence side by side: the signature broke inside identifiers and the sentence was clipped against the row's badge. Below 640px the sentence goes under the signature, which takes the full line and breaks between words. Verified: bun test passes (330 pass, 4 skip); the Shapes sample page was checked by eye at 360px.
|
React Doctor found 38 new issues in 8 files · 38 warnings · score 44 / 100 (Critical) · 1 fixed · vs 38 warnings
Reviewed by React Doctor for commit |
| servers.push(server); | ||
| const theme = { ...extraTheme, extends: extraTheme.extends ?? input.preset, ...(args.includes("--no-base-url") ? {} : { baseUrl: server.url }) }; | ||
| // The build's date, as the doclet passes it (--last-modified): the audit may read the clock; the renderer never does. | ||
| const theme = { lastModified: new Date().toISOString().slice(0, 10), ...extraTheme, extends: extraTheme.extends ?? input.preset, ...(args.includes("--no-base-url") ? {} : { baseUrl: server.url }) }; |
There was a problem hiding this comment.
React Doctor · react-doctor/js-set-map-lookups (warning)
This scales poorly because array.includes() inside a loop scans the whole list every time. Use a Set for constant-time lookups.
Fix → Use a Set or Map when you check for the same items over and over. Array.includes/find scans the whole list each time
|
|
||
| const require = createRequire(import.meta.url); | ||
| const lockup = readFileSync(require.resolve("@elide/brand/assets/svg/elide-full-blend-dark.svg"), "utf8"); | ||
| const [, , w, h] = /viewBox="([\d.\s]+)"/.exec(lockup)![1]!.trim().split(/\s+/).map(Number) as [number, number, number, number]; |
There was a problem hiding this comment.
React Doctor · react-doctor/no-array-index-deref-without-bounds-or-empty-guard (warning)
This dereferences an array index result that can be undefined at runtime (empty list, no regex match, or a short split), which throws Cannot read properties of undefined. Guard with a length/emptiness check or optional chaining before the access.
Fix → An array index read is typed T but is T | undefined at runtime, so dereferencing it on an empty list, a non-matching regex, or a short split throws. Add a length/emptiness check or optional chaining before the access.
| const label = currentSuiteLabel(list); | ||
| return ( | ||
| <div class="suites"> | ||
| <div class="suites-fit"> |
There was a problem hiding this comment.
React Doctor · react-doctor/no-unknown-property (warning)
React ignores this prop because it doesn't recognize the name.
Fix → Use the prop name React expects, like className, htmlFor, or tabIndex, so the attribute is applied correctly.
| <div class="suites"> | ||
| <div class="suites-fit"> | ||
| {/* Empty and zero-wide, so that even a first label wider than the switcher moves to a second line. */} | ||
| <span class="suites-probe" aria-hidden="true" /> |
There was a problem hiding this comment.
React Doctor · react-doctor/no-unknown-property (warning)
React ignores this prop because it doesn't recognize the name.
Fix → Use the prop name React expects, like className, htmlFor, or tabIndex, so the attribute is applied correctly.
| <div class="suites-fit"> | ||
| {/* Empty and zero-wide, so that even a first label wider than the switcher moves to a second line. */} | ||
| <span class="suites-probe" aria-hidden="true" /> | ||
| {list.map((entry, i) => <span key={i} class="suites-ghost" data-current={entry.current ? "" : undefined} aria-hidden="true">{entry.label}</span>)} |
There was a problem hiding this comment.
React Doctor · react-doctor/no-unknown-property (warning)
React ignores this prop because it doesn't recognize the name.
Fix → Use the prop name React expects, like className, htmlFor, or tabIndex, so the attribute is applied correctly.
| ) | ||
| : ( | ||
| <section class="nav-section nav-reference"> | ||
| <h2 class="nav-heading"><span>Reference</span></h2> |
There was a problem hiding this comment.
React Doctor · react-doctor/no-unknown-property (warning)
React ignores this prop because it doesn't recognize the name.
Fix → Use the prop name React expects, like className, htmlFor, or tabIndex, so the attribute is applied correctly.
| : ( | ||
| <section class="nav-section nav-reference"> | ||
| <h2 class="nav-heading"><span>Reference</span></h2> | ||
| <ul class="nav-list"> |
There was a problem hiding this comment.
React Doctor · react-doctor/no-unknown-property (warning)
React ignores this prop because it doesn't recognize the name.
Fix → Use the prop name React expects, like className, htmlFor, or tabIndex, so the attribute is applied correctly.
| <h2 class="nav-heading"><span>Reference</span></h2> | ||
| <ul class="nav-list"> | ||
| {indexes.map(entry => ( | ||
| <li key={entry.page}><a class="nav-row" href={entry.href} aria-current={entry.current ? "page" : undefined}><span class="nav-label">{entry.label}</span></a></li> |
There was a problem hiding this comment.
React Doctor · react-doctor/no-unknown-property (warning)
React ignores this prop because it doesn't recognize the name.
Fix → Use the prop name React expects, like className, htmlFor, or tabIndex, so the attribute is applied correctly.
| return ( | ||
| <Shell title={`Not found (${moduleTitle()})`} description={description} crumbs={[]} toc={[]} jsonLd={{ "@context": "https://schema.org", "@type": "WebPage", name: "Not found", description }} | ||
| meta={{ kind: "notfound" }}> | ||
| <header class="page-head"> |
There was a problem hiding this comment.
React Doctor · react-doctor/no-unknown-property (warning)
React ignores this prop because it doesn't recognize the name.
Fix → Use the prop name React expects, like className, htmlFor, or tabIndex, so the attribute is applied correctly.
| <header class="page-head"> | ||
| <h1>Not found</h1> | ||
| </header> | ||
| <div class="prose"> |
There was a problem hiding this comment.
React Doctor · react-doctor/no-unknown-property (warning)
React ignores this prop because it doesn't recognize the name.
Fix → Use the prop name React expects, like className, htmlFor, or tabIndex, so the attribute is applied correctly.
Bundle ReportBundle size has no change ✅ |
There was a problem hiding this comment.
Devin Review found 6 potential issues.
2 flags not posted on this PR by your GitHub settings — view them in Devin Review. (Configure)
| if (resolved.kind === "missing" && prefersMarkdown(accept)) { | ||
| return new Response(notFoundText(site.model, site.base, theme), { status: 404, headers: { "content-type": "text/markdown; charset=utf-8", vary: "Accept", "cache-control": "public, max-age=60" } }); | ||
| } | ||
| if (resolved.kind === "missing") { | ||
| Astro.response.status = 404; | ||
| Astro.response.headers.set("cache-control", "public, max-age=60"); | ||
| } | ||
| const page = resolved.kind === "missing" ? "404" : resolved.page; |
There was a problem hiding this comment.
🟡 Broken Markdown controls on Astro 404s
On an Astro error page, Route.astro serves HTML again when readers follow the 404.md link. The copy button also follows that link on a 404 instead of copying Markdown.
Learn more
The error page uses the regular page shell, which builds Markdown actions and links from the page name in PageActions. resolvePage recognizes a Markdown file only when its name is in the model's ordinary page map. The separate not-found page is not in that map, so a browser requesting the file reaches the HTML error branch. The copy control also rejects any non-2xx response before reading the body.
Example: Open /java/2.0/com/example/geo/Nope and choose “This page as Markdown.” /java/2.0/404.md returns the same HTML shell with status 404.
Recommended fix: Serve the explicit 404.md resource as Markdown with status 200, while retaining status 404 and Vary: Accept for negotiated responses at genuinely missing URLs.
Was this helpful? React with 👍 or 👎 to provide feedback.
| .suites-row { position: absolute; inset-inline-start: 0; inset-block-start: calc((32px - 100%) * 1000); display: flex; align-items: center; height: 32px; max-width: 100%; overflow: clip; column-gap: 2px; } | ||
| .suites-row a { padding-block: 5px; padding-inline: 9px; border-radius: var(--apidocs-radius); color: var(--apidocs-muted); white-space: nowrap; } | ||
| @media (hover: hover) and (pointer: fine) { .suites-row a:hover { color: var(--apidocs-fg); background: var(--apidocs-subtle); text-decoration: none; } } | ||
| .suites-row a:active { color: var(--apidocs-fg); background: var(--apidocs-subtle); text-decoration: none; } | ||
| .suites-row a[aria-current="true"] { color: var(--apidocs-accent); background: var(--apidocs-accent-soft); font-weight: 600; } | ||
| .suite-menu { position: absolute; inset-inline-start: 0; inset-inline-end: 0; inset-block-start: min(0px, calc((100% - 64px) * 1000)); height: 32px; } |
There was a problem hiding this comment.
🟡 Invisible keyboard stops in suite switcher
With JavaScript off, .suites-fit moves the unused switcher controls offscreen but leaves them focusable. Keyboard users tab to controls they cannot see.
Learn more
The two versions of the switcher are real interactive controls in SuiteSwitcher. Positioning one above the page does not remove it from sequential focus or the accessibility tree. The visibility rules depend on a data-fit value set by the boot script, so they do not apply without JavaScript.
Example: Open a wide documentation page with JavaScript disabled and tab through the site links. After the visible links, focus moves to the offscreen menu button.
Recommended fix: Make the inactive variant non-interactive in CSS without depending on the boot script. If layout cannot switch visibility reliably without JavaScript, show just one accessible disclosure by default and enable the dynamic row when JavaScript runs. Test the actual tab order with JavaScript disabled.
Was this helpful? React with 👍 or 👎 to provide feedback.
| html(NOT_FOUND, site.language, <NotFoundPage />); | ||
| out[`${NOT_FOUND}.md`] = frontmatter(site, { title: "Not found", kind: "notfound" }) + notFoundMarkdown(site, theme.baseUrl ?? "", indexPages(site)); | ||
|
|
||
| out["llms.txt"] = llms(site, pages, guides, symbols, indexes, theme.whenToUse); |
There was a problem hiding this comment.
🟡 Usage guidance leaks across documentation sites
With shared models and different guidance, llms supplies content that wholeSite caches by model and symbol mode. The first site requested determines the guidance both sites serve.
Learn more
The Astro integration imports the configured model modules and stores a separate theme per site. Sites pointing at the same module share its exported model object; the sample Java versions already do this. renderText serves the cached llms.txt, whose content now depends on the theme's whenToUse. The key in wholeSite accounts for symbols but not the new input.
Example: Configure the Java release to say “Use this for production” and Java main to say “Use this for development.” Request the release's llms.txt first. Java main then serves the production guidance as well.
Recommended fix: Include the normalized whenToUse value in the cache key for llms.txt, or generate that file separately. Test two requests using the same model object, the same symbol mode, and different guidance.
Was this helpful? React with 👍 or 👎 to provide feedback.
| {/* The not-found page is served at whatever URL was missing, so its skip link names no file. */} | ||
| <a class="skip" href={meta?.kind === "notfound" ? "#content" : `${name}.html#content`}>Skip to content</a> |
There was a problem hiding this comment.
🟡 Static 404 skip link leaves page
On a static 404 with baseUrl configured, Shell sends the skip link to the site root. The <base> element resolves #content against that root, not the missing URL.
Learn more
The static error shell sets a <base> element so that assets and recovery links resolve correctly at any URL depth. That element also controls how browsers resolve fragment-only links. A skip link must target the same document to move focus to its main content.
Example: A static host serves the error page at https://docs.example.com/api/old/Type with a base of https://docs.example.com/api/. Activating the skip link navigates to https://docs.example.com/api/#content instead of staying on old/Type.
Recommended fix: Avoid <base> on the static error page by emitting its resource URLs and recovery links relative to the configured site root explicitly. Keep the skip link fragment-only and test it with the error document served at a nested missing URL.
Was this helpful? React with 👍 or 👎 to provide feedback.
| const marked = links.some(link => link.current); | ||
| const isOwnRoot = (url: string) => { | ||
| if (["", "./", ".", "index.html", "./index.html"].includes(url.trim())) return true; | ||
| if (!theme.baseUrl) return false; |
There was a problem hiding this comment.
🟡 Missing current site for empty URL
When a header link uses url: "", suites never receives that entry. safeTheme drops the empty string before the switcher can mark it current.
Learn more
The header-link contract allows an empty URL to identify the current site. safeUrl distinguishes an allowed empty string from a rejected URL by returning undefined only for rejection. safeTheme treats both results as a rejection before static or Astro rendering reaches the switcher.
Example: Configure User guide with its external URL and API reference with an empty URL. The switcher renders only User guide, with no current site marked.
Recommended fix: Preserve empty URLs for header entries by checking safeUrl against undefined. Add an end-to-end render test for an empty current-site URL rather than testing only the switcher helper.
Was this helpful? React with 👍 or 👎 to provide feedback.
| // For an agent deciding whether this is the reference it needs: the theme's words, or one sentence from the module's. | ||
| const what = guidesOnly ? "documentation" : "API reference"; | ||
| const summary = overviewSummary(site); | ||
| lines.push("## When to use this", "", whenToUse?.trim() || `Use this ${what} when you write, read or review code that uses ${md(m.name)}${m.version ? ` ${md(m.version)}` : ""}.${summary ? ` ${md(summary)}` : ""}`, ""); |
There was a problem hiding this comment.
🟡 Guidance links abort hosted documentation audits
When custom usage guidance links to sibling Markdown, llms exposes that link to mirrorSite. The mirror mistakes it for a local page and aborts when its extensionless URL fails.
Learn more
A publisher can supply arbitrary Markdown in the new ‘When to use this’ section. The remote audit command uses mirrorSite to discover generated pages before running checks. mirrorSite treats every relative .md destination as a generated page, requests an extensionless HTML URL, and throws unless that request returns 200.
Example: Add Read [the integration notes](https://github.com/elide-dev/components/blob/e0b47b499aa556e5d1b33f879cd0ad716a735967/../integration.md "../integration.md") first to the theme's usage guidance. The Markdown link works, but audit --url requests ../integration as a documentation page and stops when that route does not exist.
Recommended fix: Discover generated pages from the renderer's inventory sections or API model, not arbitrary prose links. Keep custom Markdown in the guidance and add a remote audit test that includes a sibling Markdown link.
Was this helpful? React with 👍 or 👎 to provide feedback.
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
|
React Doctor reports 38 warnings and no errors (Preact |
Finishes the page chrome and brings the three local audits to full score, with the exceptions listed below.
What changed
404.htmland404.md,lastmodin the sitemap from a build-date input, guidance inllms.txt, and YAML frontmatter on the Markdown twins. A member row's summary sentence is drawn from an attribute, so the page text says it once.:focus-visible, and motion only when the reader has not asked for less. Pages mirror correctly underdir="rtl".Verified
bun testinpackages/apidocs: 330 pass, 4 skip. The Astro sample app's suite: 37 pass.Exceptions, recorded beside the code and in AUDITS.md
overflow: hiddenstays on six elements that need it for ellipsis or line clamping.Not verified
:dir(),oklch()and logical properties are untested in Safari and Firefox.