From 1df721deeb2ea26128403a55da67cda51394c246 Mon Sep 17 00:00:00 2001 From: David Hill <1879069+iamdavidhill@users.noreply.github.com> Date: Wed, 11 Nov 2026 15:51:02 -0600 Subject: [PATCH] feat(site): simplify the docs header menu and move the V1 notice into the header (#63399) --- .../site/src/component/site/css-variants.json | 4 +- .../site/src/component/site/docs-lockup.css | 19 +- .../site/src/component/site/docs-lockup.tsx | 59 ++--- .../component/site/docs-version-notice.tsx | 27 ++- .../src/component/site/settings-defaults.json | 4 +- services/site/src/component/site/settings.ts | 4 +- services/site/src/docs/client.ts | 32 ++- services/site/src/docs/layouts/DocsLayout.tsx | 10 +- services/site/src/docs/styles/docs.css | 224 ++++++++++++++++++ 9 files changed, 314 insertions(+), 69 deletions(-) diff --git a/services/site/src/component/site/css-variants.json b/services/site/src/component/site/css-variants.json index 337c5ebb19d..b13fc092f1c 100644 --- a/services/site/src/component/site/css-variants.json +++ b/services/site/src/component/site/css-variants.json @@ -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"], diff --git a/services/site/src/component/site/docs-lockup.css b/services/site/src/component/site/docs-lockup.css index be17a871631..5e3d7d80720 100644 --- a/services/site/src/component/site/docs-lockup.css +++ b/services/site/src/component/site/docs-lockup.css @@ -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] diff --git a/services/site/src/component/site/docs-lockup.tsx b/services/site/src/component/site/docs-lockup.tsx index 2b94a6c18af..95768238f45 100644 --- a/services/site/src/component/site/docs-lockup.tsx +++ b/services/site/src/component/site/docs-lockup.tsx @@ -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. */} - - {(version) => ( - <> - - 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)} - /> - - )} - ) 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: { ) } + +/** The 16px chevron after the logo row's links, toward the reading direction (mirrored in RTL by CSS). */ +export function LinkChevron() { + return ( + + ) +} diff --git a/services/site/src/component/site/settings-defaults.json b/services/site/src/component/site/settings-defaults.json index 5afc5040ebb..aa1ff8a8230 100644 --- a/services/site/src/component/site/settings-defaults.json +++ b/services/site/src/component/site/settings-defaults.json @@ -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": { diff --git a/services/site/src/component/site/settings.ts b/services/site/src/component/site/settings.ts index 1c36be6b8a5..d93afeae423 100644 --- a/services/site/src/component/site/settings.ts +++ b/services/site/src/component/site/settings.ts @@ -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 diff --git a/services/site/src/docs/client.ts b/services/site/src/docs/client.ts index 0cf0f613b45..c8031fda3b1 100644 --- a/services/site/src/docs/client.ts +++ b/services/site/src/docs/client.ts @@ -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() }) diff --git a/services/site/src/docs/layouts/DocsLayout.tsx b/services/site/src/docs/layouts/DocsLayout.tsx index 6fcdb4c1815..66b2696c2df 100644 --- a/services/site/src/docs/layouts/DocsLayout.tsx +++ b/services/site/src/docs/layouts/DocsLayout.tsx @@ -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: { + {/* 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. */} + + {(versions) => } + {/* 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: {
- - {(versions) => } -
& { + 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; + } +}