feat(site): simplify the docs header menu and move the V1 notice into the header (#63399)

This commit is contained in:
David Hill
2026-11-11 15:51:02 -06:00
committed by GitHub
Unverified
parent 7392bd4567
commit 1df721deeb
9 changed files with 314 additions and 69 deletions
@@ -16,7 +16,7 @@
"data-menu-align": "edge",
"data-wide-align": null,
"data-nav-numbers": "1",
"data-docs-nav": "split",
"data-docs-nav": "combined",
"data-section-menu": "list",
"data-docs-variants": "typography-4 lists-3 blockquote-2 callout-3 tabs-6 code-6 codeTitle-6 codeLines-6 codeDiff-6 terminal-6 fileTree-6 steps-2 cards-3 tables-5 badges-4 details-2 media-2 api-7 config-6 cli-6 pagination-4 breadcrumbs-3 search-4 switchers-2 editLink-4 feedback-5 inlineCode-6",
"data-status-bars": "4",
@@ -41,7 +41,7 @@
["[data-component=\"hero-install\"][data-mode=\"row\"]", "data-style", "inline"],
["[data-component=\"hero\"][data-design~=\"hero\"]", "data-title-size", "fitted"],
["[data-component=\"page-title\"]", "data-sticky", null],
["[data-component=\"docs-version-notice\"]", "data-variant", "frosted top"],
["[data-component=\"docs-version-notice\"]", "data-variant", "inverted"],
["[data-component=\"products\"]", "data-tone", "color"],
["[data-component=\"badges\"]", "data-style", "sans"],
["[data-component=\"badges\"]", "data-layout", "tabs"],
@@ -56,7 +56,8 @@
position: relative;
display: inline-flex;
align-items: center;
gap: 6px;
/* Label and chevron are one button, so the chevron sits close, as in the product navs. */
gap: 4px;
/* OpenTUI Mono's caps sit 0.325px below its line box's centre; this puts them on the logo's centre. */
padding: 0 6px 0.65px;
@@ -439,22 +440,6 @@
}
}
/* The section word also opens the OpenCode product menu on hover (packages/nav-menus), so hovered, open and pressed it
takes the one name fill every OpenCode nav shares (--nav-name-hover), never a darker one; the chevron keeps its own
states for the sections menu. */
[data-site] [data-component="docs-lockup"] [data-slot="word"][data-nav-product] {
@media (hover: hover) and (pointer: fine) {
&:hover {
background: var(--nav-name-hover);
}
}
&:active,
&[aria-expanded="true"] {
background: var(--nav-name-hover);
}
}
/* The logo before the lockup stays a plain link (no fill); its keyboard ring, drawn around the mark
(site.css), is 2px like the segments'. */
[data-site]
@@ -40,8 +40,8 @@ type Item = {
/**
* Settings › Docs switcher › lockup: the docs section word after the site's logo, like the Data and
* Console headers (public/nav-demo/switcher.js). One button opens a menu of the docs sections, where
* "Docs" has a submenu of versions. On an older version, "/ V1" after the word shows it and switches
* back. The menus are always in the page, hidden while closed, so pages that never hydrate (the docs)
* "Docs" has a submenu of versions. On the V1 docs the word reads "V1 docs" and the same menu marks V1
* under "Docs". The menus are always in the page, hidden while closed, so pages that never hydrate (the docs)
* can open them from a delegated listener (src/docs/client.ts).
*/
export function DocsLockup(props: {
@@ -63,10 +63,18 @@ export function DocsLockup(props: {
}
}) {
const i18n = useI18n()
// On the V1 docs the product name says so: "V1 docs", with the same chevron and menu as the latest docs.
const v1 = () => props.version?.current === "v1"
const name = (label: string) =>
label === "Docs"
? docsSectionName(i18n, label)
: i18n.t("docs.lockup.sectionDocs", { section: docsSectionName(i18n, label) })
v1()
? i18n.t("docs.lockup.sectionDocs", { section: "V1" })
: label === "Docs"
? docsSectionName(i18n, label)
: i18n.t("docs.lockup.sectionDocs", { section: docsSectionName(i18n, label) })
// The sections menu names each section's docs: "CLI docs", "API docs". The main docs are about OpenCode
// itself, so they're "OpenCode docs" rather than "Docs docs".
const menuName = (label: string) =>
i18n.t("docs.lockup.sectionDocs", { section: label === "Docs" ? "OpenCode" : docsSectionName(i18n, label) })
// V1 is a version, not a section: "Docs" has a submenu of versions, V2 (these docs) and V1 (the old
// docs site). The /docs demo can pass its own (?version= switches in place).
const sections = () => docsProducts.filter((product) => product.label !== "V1")
@@ -115,8 +123,8 @@ export function DocsLockup(props: {
triggerLabel={(label) => i18n.t("docs.lockup.switchLabel", { name: name(label) })}
items={sections().map((product) => ({
id: product.label,
label: docsSectionName(i18n, product.label),
ariaLabel: name(product.label),
label: menuName(product.label),
ariaLabel: menuName(product.label),
href: props.href?.(product.label) ?? product.href,
sub:
product.label !== "Docs"
@@ -132,30 +140,8 @@ export function DocsLockup(props: {
}))}
current={props.current}
onSelect={props.onSelect}
split={{ label: i18n.t("docs.lockup.switch"), onSelect: props.onSelect }}
split={{ label: i18n.t("docs.lockup.switch"), onSelect: props.onSelect, href: v1() ? v1DocsUrl() : undefined }}
/>
{/* Only the main docs have versions, and only an older one shows here. */}
<Show when={props.current === "Docs" && props.version?.current !== "latest" && props.version}>
{(version) => (
<>
<span data-slot="separator" aria-hidden="true">
|
</span>
<Dropdown
id={`docs-version-menu${suffix}`}
variant="version"
menuLabel={i18n.t("docs.version.label")}
trigger={(id) => docsVersions.find((item) => item.id === id)!.label}
triggerLabel={(id) =>
i18n.t("docs.version.switch", { version: docsVersions.find((item) => item.id === id)!.label })
}
items={versionItems(version())}
current={version().current}
onSelect={(id) => version().onSelect(id as DocsVersion)}
/>
</>
)}
</Show>
</div>
)
if (props.inline) return lockup()
@@ -186,8 +172,11 @@ function Dropdown(props: {
items: Item[]
current: string
onSelect?: (id: string) => void
/** Settings › Docs nav › split: the word links to the section's home; `label` names the chevron. */
split?: { label: string; onSelect?: (id: string) => void }
/**
* Settings › Docs nav › split: the word links to the section's home (or `href`, the V1 docs' home);
* `label` names the chevron.
*/
split?: { label: string; onSelect?: (id: string) => void; href?: string }
}) {
const i18n = useI18n()
const [open, setOpen] = createSignal(false)
@@ -323,11 +312,7 @@ function Dropdown(props: {
<a
data-slot="word"
data-design="docsNav sectionMenuStyle menuActive menuColor menuAlign docsSubmenu"
href={props.items[currentIndex()].href}
data-nav-product="docs"
data-nav-product-chevron="none"
aria-haspopup="menu"
aria-expanded="false"
href={split().href ?? props.items[currentIndex()].href}
aria-label={i18n.t("docs.lockup.home", { name: props.trigger(props.items[currentIndex()].id) })}
onClick={(event) => {
close()
@@ -1,20 +1,29 @@
import "./docs-version-notice.css"
import { useI18n } from "~/context/i18n"
import { Show } from "solid-js"
import { siteSettings } from "./settings"
/** On the V1 docs: a bar at the top of the content column, with a way back to the latest docs. */
export function DocsVersionNotice(props: { latest: string; onLatest?: () => void }) {
/**
* On the V1 docs: a bar with a way back to the latest docs, at the top of the content column, or in the
* logo row (`placement="header"`, the docs), where the sentence shortens with "…" before the link does.
* On phones the header placement is a bar on the screen's bottom edge saying only "V1 docs" (docs.css).
*/
export function DocsVersionNotice(props: { latest: string; onLatest?: () => void; placement?: "header" }) {
const i18n = useI18n()
return (
<aside
data-component="docs-version-notice"
data-variant={siteSettings.docsVersionNotice}
data-design="docsVersionNotice"
data-placement={props.placement}
aria-label={i18n.t("docs.version.label")}
>
<span data-slot="badge">V1</span>
<Show when={props.placement}>
<span data-slot="short">{i18n.t("docs.version.v1Docs")}</span>
</Show>
<p>
{i18n.t("docs.version.notice")}{" "}
<span data-slot="sentence">{i18n.t("docs.version.notice")}</span>{" "}
<a
href={props.latest}
onClick={(event) => {
@@ -24,8 +33,20 @@ export function DocsVersionNotice(props: { latest: string; onLatest?: () => void
}}
>
{i18n.t("docs.version.switchToLatest")}
<Show when={props.placement}>
<LinkChevron />
</Show>
</a>
</p>
</aside>
)
}
/** The 16px chevron after the logo row's links, toward the reading direction (mirrored in RTL by CSS). */
export function LinkChevron() {
return (
<svg data-slot="link-chevron" width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true">
<path d="M6 4L10 8L6 12" stroke="currentColor" stroke-width="1.5" stroke-linecap="square" />
</svg>
)
}
@@ -352,8 +352,8 @@
"consoleCopyColumns": "2 columns",
"docsSwitcher": "lockup",
"docsSubmenu": "flyout",
"docsNav": "split",
"docsVersionNotice": "frosted top",
"docsNav": "combined",
"docsVersionNotice": "inverted",
"terminalInstall": "button",
"carouselPreset": "four across",
"carousel": {
+2 -2
View File
@@ -1051,8 +1051,8 @@ function createSchema() {
consoleCopyColumns: z.enum(sectionColumns).catch("2 columns"),
docsSwitcher: z.enum(docsSwitchers).catch("lockup"),
docsSubmenu: z.enum(docsSubmenus).catch("flyout"),
docsNav: z.enum(docsNavs).catch("split"),
docsVersionNotice: z.enum(docsVersionNotices).catch("frosted top"),
docsNav: z.enum(docsNavs).catch("combined"),
docsVersionNotice: z.enum(docsVersionNotices).catch("inverted"),
terminalInstall: z.enum(terminalInstalls).catch("button"),
carouselPreset: z.enum(carouselPresetNames).catch("four across"),
carousel: z
+30 -2
View File
@@ -128,6 +128,23 @@ function enter(menu: HTMLElement) {
menu.animate([{ opacity: 0 }, { opacity: 1 }], { duration: 140, easing: "ease-out" })
}
// The versions flyout appears softly beside "Docs": a 140ms fade with a 3px nudge from the row it opens
// from, on the strong ease-out, transform and opacity only. Only its first showing in an open menu
// animates; coming back to "Docs" shows it at once, and it hides at once. Reduced motion shows it at once.
let flown = false
function flyIn(submenu: HTMLElement) {
if (flown || matchMedia("(prefers-reduced-motion: reduce)").matches) return
flown = true
const from = `translateX(${html.dir === "rtl" ? 3 : -3}px)`
submenu.animate(
[
{ opacity: 0, transform: from },
{ opacity: 1, transform: "translateX(0)" },
],
{ duration: 140, easing: "cubic-bezier(0.23, 1, 0.32, 1)" },
)
}
// The docs lockup (component/site/docs-lockup.tsx): the chevron opens the sections menu, where "Docs"
// has its versions in a flyout beside it, or nested under it on phones and touch screens. An older
// version adds a second menu, of the versions, so each dropdown in it opens on its own.
@@ -177,6 +194,7 @@ function openLockup(root: HTMLElement, focus?: "first" | "last" | "current") {
}
function closeLockup(refocus?: boolean) {
flown = false
if (!lockup) return
const root = lockup
lockup = undefined
@@ -185,7 +203,10 @@ function closeLockup(refocus?: boolean) {
$$("[aria-haspopup=menu]:not([role=menuitem], [data-nav-product])", root).forEach((button) =>
button.setAttribute("aria-expanded", "false"),
)
if (refocus) ($("[data-slot=toggle]", root) ?? $("[data-slot=trigger]", root))?.focus()
if (refocus)
$$("[data-slot=toggle], [data-slot=trigger]", root)
.find((button) => button.offsetParent)
?.focus()
}
function toggleSub(root: HTMLElement, open: boolean, focus?: boolean) {
@@ -196,7 +217,7 @@ function toggleSub(root: HTMLElement, open: boolean, focus?: boolean) {
parent.toggleAttribute("data-open", open)
const submenu = $("[data-slot=submenu]", parent)!
submenu.hidden = !open
if (opening && menuOf(root).dataset.submenu === "flyout") enter(submenu)
if (opening && menuOf(root).dataset.submenu === "flyout") flyIn(submenu)
$$("[aria-expanded]", parent).forEach((item) => item.setAttribute("aria-expanded", String(open)))
if (open && focus)
($('[aria-current="page"]', $("[data-slot=submenu]", parent)!) ?? $("[data-slot=submenu] a", parent))?.focus()
@@ -210,6 +231,13 @@ on("click", (event) => {
return lockup === root ? closeLockup() : openLockup(root)
const expand = target.closest("[data-slot=expand]")
if (expand) return toggleSub(root, expand.getAttribute("aria-expanded") !== "true")
// Nested (phones, touch and narrow windows): tapping "Docs" opens and closes its versions in place,
// like its "›", instead of leaving for the docs home, which V2 still links. The flyout keeps the link.
const parent = target.closest("[data-slot=parent] > [role=menuitem]")
if (parent && menuOf(root).dataset.submenu === "nested") {
event.preventDefault()
return toggleSub(root, parent.getAttribute("aria-expanded") !== "true")
}
if (target.closest("a")) closeLockup()
})
@@ -83,7 +83,7 @@ export function DocsLayout(props: {
const contents = props.headings
.filter((heading) => heading.depth === 2 || heading.depth === 3)
.map((heading) => ({ id: heading.slug, title: heading.text, level: heading.depth as 2 | 3 }))
// The lockup's versions: this page in each (the versions menu, and "| V1" on V1 pages).
// The lockup's versions: this page in each (the versions menu under "Docs"; V1 pages read "V1 docs").
const version = () =>
props.versions && {
current: props.set.id,
@@ -187,6 +187,11 @@ export function DocsLayout(props: {
</div>
</div>
</aside>
{/* V1: the notice sits in the logo row, after the sidebar's label so it can start past a long one
(docs.css); phones show it as a bar on the screen's bottom edge. */}
<Show when={props.set.id === "v1" && props.versions}>
{(versions) => <DocsVersionNotice latest={versions().latest} placement="header" />}
</Show>
{/* Mobile layout: the Contents rail folded into a bar stuck under the
section row from load. It names the section being read (client.ts swaps the label as you scroll)
and keeps "Contents" in its accessible name. Hidden beside the rail on wide screens. */}
@@ -213,9 +218,6 @@ export function DocsLayout(props: {
<main data-component="content" id="content" tabindex={-1}>
<div data-slot="page">
<Show when={props.set.id === "v1" && props.versions}>
{(versions) => <DocsVersionNotice latest={versions().latest} />}
</Show>
<article
data-component="docs-article"
data-section="article"
+224
View File
@@ -759,3 +759,227 @@
padding-inline: 0;
}
}
/* ───────────── V1 notice in the logo row ─────────────
The V1 docs' notice is the solid dark bar ("inverted", docs-version-notice.css) in the logo row,
centred on the logo and as wide as the article column. A narrow column shortens the sentence with
"…" and keeps the link at its end. In the dark theme it stays dark: a raised dark bar with a
hairline, so it stands off the page. Behind it the logo row is the page's colour down to the bar's
bottom edge, so the article, the docs nav and the Contents rail pass under it and end there. Phones
have it on the screen's bottom edge instead (below). */
[data-site] [data-component="docs-version-notice"][data-placement="header"] {
/* The link's grey: 6.6:1 on the light theme's bar, 6.1:1 on the dark theme's. */
--notice-muted: hsl(0, 0%, 64%);
--notice-text: light-dark(var(--text-inverted), var(--text-strong));
position: fixed;
z-index: 7;
top: calc(var(--banner-offset, 0px) + var(--top) + var(--logo-height) / 2);
height: var(--v1-notice-height);
/* The article column's edges. A long translated label ("DOKUMENTACJA V1") can end past the
article's start; the notice then starts after its chevron. Browsers without anchor positioning
keep the article's start and end before the GitHub mark. */
inset-inline-start: calc(var(--page-offset) + var(--sidebar-width) + var(--gutter));
inset-inline-end: calc(
var(--page-offset) + var(--github-right) + (var(--github-size) + var(--github-mark, 20px)) / 2 + 24px
);
inset-inline-start: max(
anchor(--docs-article start, calc(var(--page-offset) + var(--sidebar-width) + var(--gutter))),
calc(anchor(--docs-lockup-toggle end, 0px) + 12px)
);
inset-inline-end: anchor(
--docs-article end,
calc(var(--page-offset) + var(--github-right) + (var(--github-size) + var(--github-mark, 20px)) / 2 + 24px)
);
translate: 0 -50%;
margin: 0;
white-space: nowrap;
background: light-dark(var(--bg-strong), hsl(0, 0%, 13%));
box-shadow: inset 0 0 0 1px light-dark(transparent, var(--border-strong));
border-color: transparent;
color: var(--notice-text);
&::before,
&::after {
content: none;
}
p {
flex: 1;
display: flex;
min-width: 0;
gap: 0.5em;
white-space: nowrap;
}
[data-slot="sentence"] {
min-width: 0;
overflow: hidden;
text-overflow: ellipsis;
}
a {
position: relative;
flex: none;
display: flex;
align-items: center;
gap: 4px;
color: var(--notice-muted);
text-decoration: none;
transition: color 100ms ease-out;
/* 44px tall to tap, on the bar's 32px. */
&::after {
content: "";
position: absolute;
inset-inline: 0;
top: 50%;
height: 44px;
translate: 0 -50%;
}
&:focus-visible {
outline: 2px solid var(--link);
outline-offset: 2px;
}
&:is(:hover, :focus-visible) {
color: var(--notice-text);
transition-duration: 0ms;
}
}
[data-slot="badge"] {
background: none;
color: inherit;
border-inline-end-color: light-dark(
color-mix(in srgb, var(--text-inverted) 22%, transparent),
var(--border-strong)
);
}
[data-slot="short"] {
display: none;
}
}
/* The link's chevron, after its text toward the reading direction, nudged 2px on hover. */
[data-site] [data-slot="link-chevron"] {
flex: none;
transition: translate 150ms var(--ease-out);
:is(a:hover, a:focus-visible) > & {
translate: 2px 0;
}
[dir="rtl"] & {
scale: -1 1;
}
[dir="rtl"] :is(a:hover, a:focus-visible) > & {
translate: -2px 0;
}
@media (prefers-reduced-motion: reduce) {
transition: none;
}
}
@media (min-width: 60.0625rem) {
/* A heading reached from Contents or a link lands below the logo row's band. */
[data-site] [data-slot="frame"]:has(> [data-placement="header"]) [data-component="docs-article"] [id] {
scroll-margin-top: calc(var(--v1-notice-bottom) + 1.5rem);
}
[data-site] [data-slot="frame"]:has(> [data-placement="header"]) > [data-component="content"]::before {
content: "";
position: fixed;
/* Under the sidebar (2), whose logo strip covers its own nav, and over the article. */
z-index: 1;
top: 0;
inset-inline: 0;
height: var(--v1-notice-bottom);
background: var(--bg);
pointer-events: none;
}
}
[data-site] [data-component="sidebar"] [data-component="docs-lockup"] :is([data-slot="toggle"], [data-slot="trigger"]) {
anchor-name: --docs-lockup-toggle;
}
[data-site] [data-slot="frame"] {
--v1-notice-height: 2rem;
/* The bar's bottom edge, where the logo row's band ends. */
--v1-notice-bottom: calc(
var(--banner-offset, 0px) + var(--top) + var(--logo-height) / 2 + var(--v1-notice-height) / 2
);
&:has(> [data-placement="header"]) [data-component="docs-article"] {
anchor-name: --docs-article;
}
}
/* Phones: one line on the screen's bottom edge, "V1 docs" and the link, in the same dark, running
under the home indicator to the very edge. iOS Safari tints its bottom toolbar from what touches the
bottom edge, and the page behind the site (html) takes the dark too, so the bottom of the screen is
one dark area; the top still takes the top bar's page colour. The page ends above the bar, so the
footer stays reachable. Open menus and sheets sit over it. */
@media (max-width: 60rem) {
html:has([data-component="docs-version-notice"][data-placement="header"]) {
background: light-dark(hsl(0, 0%, 8%), hsl(0, 0%, 13%));
}
[data-site]:has([data-component="docs-version-notice"][data-placement="header"]) {
padding-bottom: calc(3rem + env(safe-area-inset-bottom, 0px));
}
[data-site][data-page="docs"] [data-component="docs-version-notice"][data-placement="header"] {
position: fixed;
inset: auto 0 0;
margin: 0;
z-index: 5;
height: auto;
translate: none;
align-items: center;
padding: 0 calc(var(--edge) + env(safe-area-inset-right, 0px)) env(safe-area-inset-bottom, 0px)
calc(var(--edge) + env(safe-area-inset-left, 0px));
box-shadow: inset 0 1px 0 light-dark(transparent, var(--border-strong));
font-size: 14px;
[data-slot="badge"],
[data-slot="sentence"] {
display: none;
}
[data-slot="short"] {
display: block;
flex: none;
text-transform: uppercase;
}
p {
justify-content: flex-end;
padding: 0;
}
a {
height: 3rem;
text-decoration: none;
}
a::after {
content: none;
}
}
/* While a phone menu or sheet is open, the bar goes, so nothing sits half under it. */
[data-site]:has(
[data-component="topbar"] [data-slot="menu"]:not([hidden]),
[data-component="section-nav"][data-open],
[data-component="contents-menu"][open],
[data-search-dialog]:not([hidden])
)
[data-component="docs-version-notice"][data-placement="header"] {
visibility: hidden;
}
}