From f1db614bfc6122fdadac7e752fc1d131d755d5ce Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Julien=20D=C3=A9ramond?= Date: Tue, 20 Oct 2026 20:50:04 +0200 Subject: [PATCH 1/4] Docs: prototype a sidebar with universes and a filter Co-Authored-By: Claude Opus 5.5 --- site/data/sidebar.yml | 2 +- site/src/assets/application.js | 2 + site/src/assets/partials/sidebar-universes.js | 131 +++++++ site/src/components/DocsSidebar.astro | 321 +++++++++++------- site/src/scss/_sidebar.scss | 86 ++++- 5 files changed, 421 insertions(+), 121 deletions(-) create mode 100644 site/src/assets/partials/sidebar-universes.js diff --git a/site/data/sidebar.yml b/site/data/sidebar.yml index 73dee44b39..f378f87315 100644 --- a/site/data/sidebar.yml +++ b/site/data/sidebar.yml @@ -2,7 +2,7 @@ # Each group has a `section` field that determines which sub-navbar tab it belongs to. - title: Getting started - section: Getting Started + section: Getting started icon: book-half icon_color: indigo pages: diff --git a/site/src/assets/application.js b/site/src/assets/application.js index cef1debbdc..103955a642 100644 --- a/site/src/assets/application.js +++ b/site/src/assets/application.js @@ -8,6 +8,7 @@ */ import sidebarScroll from './partials/sidebar.js' +import sidebarUniverses from './partials/sidebar-universes.js' import snippets from './partials/snippets.js' import stickyNav from './partials/sticky.js' import tocDrawer from './partials/toc.js' @@ -15,6 +16,7 @@ import tocHeight from './partials/toc-height.js' import tocScroll from './partials/toc-scroll.js' export default () => { + sidebarUniverses() sidebarScroll() snippets() stickyNav() diff --git a/site/src/assets/partials/sidebar-universes.js b/site/src/assets/partials/sidebar-universes.js new file mode 100644 index 0000000000..12f6022383 --- /dev/null +++ b/site/src/assets/partials/sidebar-universes.js @@ -0,0 +1,131 @@ +// NOTICE: Internal docs helpers — not shipped in Bootstrap; not for reuse. + +/* + * JavaScript for Bootstrap's docs (https://getbootstrap.com/) + * Copyright 2011-2026 The Bootstrap Authors + * Licensed under the Creative Commons Attribution 3.0 Unported License. + * For details, see https://creativecommons.org/licenses/by/3.0/. + */ + +const normalize = text => text.normalize('NFD').replace(/[̀-ͯ]/g, '').toLowerCase().trim() + +// The text of a link or heading, without its "New" badge +const ownText = element => [...element.childNodes] + .filter(node => node.nodeType === Node.TEXT_NODE) + .map(node => node.textContent) + .join(' ') + +const filterPanel = (panel, query) => { + const term = normalize(query) + let panelMatches = 0 + + for (const group of panel.querySelectorAll('[data-bd-filter-group]')) { + const heading = group.querySelector('.bd-links-heading') + const groupMatches = term !== '' && heading !== null && normalize(ownText(heading)).includes(term) + let groupCount = 0 + + for (const subgroup of group.querySelectorAll('[data-bd-filter-subgroup]')) { + const subgroupMatches = groupMatches || normalize(ownText(subgroup.querySelector('.bd-links-subgroup'))).includes(term) + let subgroupCount = 0 + + for (const item of subgroup.querySelectorAll('[data-bd-filter-item]')) { + const visible = subgroupMatches || normalize(ownText(item.querySelector('a'))).includes(term) + item.hidden = !visible + subgroupCount += visible ? 1 : 0 + } + + subgroup.hidden = subgroupCount === 0 + groupCount += subgroupCount + } + + for (const item of group.querySelectorAll('[data-bd-filter-item]')) { + if (item.closest('[data-bd-filter-subgroup]')) { + continue + } + + const visible = groupMatches || normalize(ownText(item.querySelector('a'))).includes(term) + item.hidden = !visible + groupCount += visible ? 1 : 0 + } + + group.hidden = groupCount === 0 + panelMatches += groupCount + } + + const empty = panel.querySelector('.bd-links-empty') + empty.hidden = panelMatches > 0 + empty.querySelector('[data-bd-filter-query]').textContent = query.trim() +} + +export default () => { + const nav = document.querySelector('#bd-docs-nav') + + if (!nav) { + return + } + + const tabs = [...nav.querySelectorAll('[data-bd-universe]')] + const panels = [...nav.querySelectorAll('[data-bd-universe-panel]')] + const input = nav.querySelector('#bd-links-filter-input') + const activePanel = () => panels.find(panel => !panel.hidden) + + const selectUniverse = (tab, { focus = false } = {}) => { + for (const other of tabs) { + const selected = other === tab + other.classList.toggle('active', selected) + other.setAttribute('aria-selected', selected ? 'true' : 'false') + other.tabIndex = selected ? 0 : -1 + } + + for (const panel of panels) { + panel.hidden = panel.dataset.bdUniversePanel !== tab.dataset.bdUniverse + } + + // Each universe starts unfiltered + input.value = '' + filterPanel(activePanel(), '') + + if (focus) { + tab.focus() + } + } + + for (const tab of tabs) { + tab.addEventListener('click', () => selectUniverse(tab)) + + // Vertical tablist: arrow keys, Home and End move between universes + tab.addEventListener('keydown', event => { + const index = tabs.indexOf(tab) + const next = { + ArrowDown: tabs[(index + 1) % tabs.length], + ArrowUp: tabs[(index - 1 + tabs.length) % tabs.length], + Home: tabs[0], + End: tabs.at(-1) + }[event.key] + + if (next) { + event.preventDefault() + selectUniverse(next, { focus: true }) + } + }) + } + + input.addEventListener('input', () => filterPanel(activePanel(), input.value)) + + input.addEventListener('keydown', event => { + const firstLink = activePanel().querySelector('[data-bd-filter-item]:not([hidden]) a') + + if (event.key === 'Enter' && firstLink && input.value.trim() !== '') { + event.preventDefault() + firstLink.click() + } else if (event.key === 'ArrowDown' && firstLink) { + event.preventDefault() + firstLink.focus() + } else if (event.key === 'Escape' && input.value !== '') { + event.preventDefault() + event.stopPropagation() + input.value = '' + filterPanel(activePanel(), '') + } + }) +} diff --git a/site/src/components/DocsSidebar.astro b/site/src/components/DocsSidebar.astro index 9c2c7581b7..905882a460 100644 --- a/site/src/components/DocsSidebar.astro +++ b/site/src/components/DocsSidebar.astro @@ -1,132 +1,219 @@ --- -import { getData, type SidebarItem, type SidebarSubItem } from '@libs/data' +import { getData, type SidebarGroup, type SidebarItem, type SidebarSubItem } from '@libs/data' import { getConfig } from '@libs/config' import { docsPages, getDocsPageSlug } from '@libs/content' import { getSlug } from '@libs/utils' import NewBadge from '@components/NewBadge.astro' +interface Universe { + title: string + slug: string + icon?: string + iconColor?: string + groups: SidebarGroup[] +} + const sidebar = getData('sidebar') +const defaultUniverse = 'Getting started' + +// Gather the sidebar groups into "universes" using their `section` field, in the order of `sidebar.yml`. +const universes: Universe[] = [] + +for (const group of sidebar) { + const title = group.section ?? group.title + let universe = universes.find((u) => u.title === title) + + if (!universe) { + universe = { title, slug: getSlug(title), icon: group.icon, iconColor: group.icon_color, groups: [] } + universes.push(universe) + } + + universe.groups.push(group) +} + +function getPageLink(groupTitle: string, pageTitle: string) { + const unversionedPageSlug = `${getSlug(groupTitle)}/${getSlug(pageTitle)}` + const url = `/docs/${getConfig().docs_version}/${unversionedPageSlug}` + + // This test should not be necessary, see comments for `getSlug()` in `src/libs/utils.ts`. + if (!docsPages.some((page) => getDocsPageSlug(page.id) === unversionedPageSlug)) { + throw new Error(`The page '${pageTitle}' referenced in 'site/data/sidebar.yml' does not exist at '${url}'.`) + } + + return { url, active: Astro.params.slug === unversionedPageSlug } +} + +function hasActivePage(universe: Universe) { + return universe.groups.some((group) => { + if (!group.pages) { + return Astro.params.slug === getSlug(group.title) + } + + return group.pages.some((item) => { + const titles = item.group && item.pages ? item.pages.map((page) => page.title) : item.title ? [item.title] : [] + return titles.some((title) => Astro.params.slug === `${getSlug(group.title)}/${getSlug(title)}`) + }) + }) +} + +// The universe of the current page is open, "Getting started" otherwise. +const activeUniverse = + universes.find((universe) => hasActivePage(universe)) ?? + universes.find((universe) => universe.title === defaultUniverse) ?? + universes[0] + +const iconStyle = (color?: string) => color && `color: light-dark(var(--bs-${color}-500), var(--bs-${color}-400));` --- -