@hgdc/docs 0.2.0 → 0.4.0

package/src/overrides/Search.astro

@@ -0,0 +1,54 @@
+---
+import data from "virtual:hgdc-docs/config"
+
+import Icon from "./Icon.astro"
+import { assistantEnabled } from "./sections.ts"
+
+/**
+ * Recherche en palette (Ctrl K ou « / ») sur l'index Pagefind que Starlight construit au
+ * build. Le script de Pagefind n'est chargé qu'à la première ouverture. Logique dans
+ * `../widget/search.ts`.
+ */
+const assistant = assistantEnabled(data.config)
+---
+
+<hd-search data-base={data.base} data-assistant={assistant ? "" : undefined}>
+  <button type="button" class="hd-search-trigger" data-open aria-haspopup="dialog" aria-label="Rechercher (Ctrl K)">
+    <Icon name="search" size={16} />
+    <span class="hd-search-trigger__label">Rechercher</span>
+    <kbd class="hd-kbd" data-shortcut>Ctrl K</kbd>
+  </button>
+
+  <dialog class="hd-palette" aria-label="Rechercher dans la documentation">
+    <div class="hd-palette__box">
+      <div class="hd-palette__field">
+        <Icon name="search" />
+        <input
+          type="search"
+          data-input
+          placeholder="Rechercher dans la documentation"
+          autocomplete="off"
+          spellcheck="false"
+          role="combobox"
+          aria-expanded="false"
+          aria-controls="hd-palette-results"
+          aria-autocomplete="list"
+        />
+        <button type="button" class="hd-kbd hd-kbd--button" data-close>Échap</button>
+      </div>
+      <div class="hd-palette__results" id="hd-palette-results" role="listbox" aria-label="Résultats" data-results></div>
+      <p class="hd-palette__status" data-status role="status">Tape un mot pour chercher dans les pages.</p>
+      <footer class="hd-palette__hints" aria-hidden="true">
+        <span><kbd class="hd-kbd">↑</kbd><kbd class="hd-kbd">↓</kbd> Choisir</span>
+        <span><kbd class="hd-kbd">↵</kbd> Ouvrir</span>
+        <span><kbd class="hd-kbd">Échap</kbd> Fermer</span>
+      </footer>
+    </div>
+  </dialog>
+</hd-search>
+
+<script>
+  import { defineSearch } from "../widget/search.ts"
+
+  defineSearch()
+</script>

package/src/overrides/Sidebar.astro

@@ -1,60 +1,105 @@
----
-import Default from "@astrojs/starlight/components/Sidebar.astro"
-import data from "virtual:hgdc-docs/config"
-
-import { pagesOf, pageToPath, withBase } from "../core/navigation.ts"
-
-// Onglets et versions de docs.json, en tête de la sidebar : visibles sur ordinateur et dans
-// le menu mobile, sans toucher à la hauteur de l'en-tête de Starlight.
-const sections = data.tree.versions.flatMap((version) => version.tabs.map((tab) => ({ version, tab })))
-const index = Astro.locals.hgdcSection ?? 0
-const current = sections[index] ?? sections[0]!
-const firstPath = (items: Parameters<typeof pagesOf>[0]) => {
-  const first = pagesOf(items)[0]
-  return withBase(data.base, first ? pageToPath(first) : "/")
-}
-const tabs = current.version.tabs.filter((tab) => tab.label)
-const versions = data.tree.versions.filter((version) => version.label)
-const tabPosition = current.version.tabs.indexOf(current.tab)
-const versionHref = (version: (typeof versions)[number]) =>
-  firstPath((version.tabs[tabPosition] ?? version.tabs[0]!).items)
----
-
-{
-  (tabs.length > 1 || versions.length > 1) && (
-    <div class="hgdc-sections">
-      {versions.length > 1 && (
-        <label class="hgdc-version">
-          <span class="sr-only">Version de la documentation</span>
-          <select data-hgdc-version>
-            {versions.map((version) => (
-              <option value={versionHref(version)} selected={version === current.version}>
-                {version.label}
-                {version.isDefault ? " (actuelle)" : ""}
-              </option>
-            ))}
-          </select>
-        </label>
-      )}
-      {tabs.length > 1 && (
-        <nav aria-label="Sections de la documentation">
-          <ul class="hgdc-tabs">
-            {tabs.map((tab) => (
-              <li>
-                <a href={firstPath(tab.items)} aria-current={tab === current.tab ? "page" : undefined}>
-                  {tab.label}
-                </a>
-              </li>
-            ))}
-          </ul>
-        </nav>
-      )}
-    </div>
-  )
-}
-<Default><slot /></Default>
-
-<script>
-  for (const select of document.querySelectorAll<HTMLSelectElement>("[data-hgdc-version]"))
-    select.addEventListener("change", () => window.location.assign(select.value))
-</script>
+---
+import data from "virtual:hgdc-docs/config"
+
+import Icon from "./Icon.astro"
+import { docsSections, sectionHref } from "./sections.ts"
+import SidebarList from "./SidebarList.astro"
+import ThemeToggle from "./ThemeToggle.astro"
+
+/**
+ * Barre latérale : la version (s'il y en a plusieurs), puis les groupes de docs.json. Sur
+ * téléphone, le même panneau sert de menu : il reprend les onglets et les liens de
+ * l'en-tête, et le choix du thème.
+ */
+const { tabs, versions, current } = docsSections(data.tree, Astro.locals.hgdcSection ?? 0)
+const tabPosition = current.version.tabs.indexOf(current.tab)
+const versionHref = (version: (typeof versions)[number]) =>
+  sectionHref(data.base, (version.tabs[tabPosition] ?? version.tabs[0]!).items)
+const links = data.config.navbar?.links ?? []
+const primary = data.config.navbar?.primary
+---
+
+<div class="hd-mobile-only hd-sidebar-head">
+  <a class="hd-brand" href={`${data.base}/`}><span class="hd-brand__name">{data.config.name}</span></a>
+  <button type="button" class="hd-icon-button" popovertarget="starlight__sidebar" popovertargetaction="hide" aria-label="Fermer le menu">
+    <Icon name="x" />
+  </button>
+</div>
+
+{
+  versions.length > 1 && (
+    <label class="hd-version">
+      <span class="sr-only">Version de la documentation</span>
+      <select data-hgdc-version>
+        {versions.map((version) => (
+          <option value={versionHref(version)} selected={version === current.version}>
+            {version.label}
+            {version.isDefault ? " (actuelle)" : ""}
+          </option>
+        ))}
+      </select>
+    </label>
+  )
+}
+{
+  tabs.length > 1 && (
+    <nav class="hd-mobile-only hd-sidebar-tabs" aria-label="Sections de la documentation">
+      {tabs.map((tab) => (
+        <a href={sectionHref(data.base, tab.items)} aria-current={tab === current.tab ? "page" : undefined}>
+          {tab.label}
+        </a>
+      ))}
+    </nav>
+  )
+}
+
+<SidebarList entries={Astro.locals.starlightRoute.sidebar} />
+
+<div class="hd-mobile-only hd-sidebar-footer">
+  {
+    (links.length > 0 || primary) && (
+      <nav class="hd-sidebar-links" aria-label="Liens">
+        {links.map((link) => (
+          <a href={link.href}>{link.label}</a>
+        ))}
+        {primary && (
+          <a class="hd-pill hd-pill--primary" href={primary.href}>
+            {primary.label}
+          </a>
+        )}
+      </nav>
+    )
+  }
+  <ThemeToggle variant="segmented" />
+</div>
+
+<script>
+  for (const select of document.querySelectorAll<HTMLSelectElement>("[data-hgdc-version]"))
+    select.addEventListener("change", () => window.location.assign(select.value))
+
+  // La barre garde sa position de défilement d'une page à l'autre, et l'élément courant
+  // reste visible à l'arrivée.
+  const pane = document.querySelector<HTMLElement>(".sidebar-pane")
+  if (pane) {
+    const KEY = "hd-sidebar-scroll"
+    try {
+      const saved = Number(sessionStorage.getItem(KEY))
+      if (saved) pane.scrollTop = saved
+    } catch {
+      // Stockage refusé : la barre repart du haut.
+    }
+    const current = pane.querySelector<HTMLElement>('[aria-current="page"]')
+    if (current) {
+      const box = pane.getBoundingClientRect()
+      const item = current.getBoundingClientRect()
+      if (item.top < box.top || item.bottom > box.bottom) current.scrollIntoView({ block: "center" })
+    }
+    addEventListener("pagehide", () => {
+      try {
+        sessionStorage.setItem(KEY, String(pane.scrollTop))
+      } catch {
+        // Rien à faire.
+      }
+    })
+  }
+</script>

package/src/overrides/SidebarList.astro

@@ -0,0 +1,52 @@
+---
+import type { StarlightRouteData } from "@astrojs/starlight/route-data"
+
+import Icon from "./Icon.astro"
+
+/**
+ * Arbre de la barre latérale. Premier niveau : titres de groupe et pages. Plus bas : un
+ * groupe se replie derrière un chevron, ouvert d'office s'il contient la page affichée.
+ */
+type Entry = StarlightRouteData["sidebar"][number]
+interface Props {
+  entries: Array<Entry>
+  depth?: number
+}
+const { entries, depth = 0 } = Astro.props
+const containsCurrent = (entry: Entry): boolean =>
+  entry.type === "link" ? entry.isCurrent : entry.entries.some(containsCurrent)
+---
+
+<ul class:list={["hd-nav", `hd-nav--depth-${depth}`]}>
+  {
+    entries.map((entry) =>
+      entry.type === "link" ? (
+        <li>
+          <a href={entry.href} class="hd-nav__link" aria-current={entry.isCurrent ? "page" : undefined} {...entry.attrs}>
+            <span>{entry.label}</span>
+            {entry.badge && (
+              <span class="hd-badge" data-variant={entry.badge.variant}>
+                {entry.badge.text}
+              </span>
+            )}
+          </a>
+        </li>
+      ) : depth === 0 ? (
+        <li class="hd-nav__group">
+          <p class="hd-nav__heading">{entry.label}</p>
+          <Astro.self entries={entry.entries} depth={depth + 1} />
+        </li>
+      ) : (
+        <li>
+          <details class="hd-nav__fold" open={!entry.collapsed || containsCurrent(entry)}>
+            <summary class="hd-nav__link">
+              <span>{entry.label}</span>
+              <Icon name="chevron-right" size={14} class="hd-nav__chevron" />
+            </summary>
+            <Astro.self entries={entry.entries} depth={depth + 1} />
+          </details>
+        </li>
+      ),
+    )
+  }
+</ul>

package/src/overrides/SiteFooter.astro

@@ -0,0 +1,51 @@
+---
+import { Icon as StarlightIcon } from "@astrojs/starlight/components"
+import data from "virtual:hgdc-docs/config"
+
+import { socialNetwork } from "../core/config.ts"
+import ThemeToggle from "./ThemeToggle.astro"
+
+/**
+ * Pied de page du site, à droite de la barre latérale : le produit, ses réseaux
+ * (`footer.socials`) et le choix du thème.
+ */
+const logo = typeof data.config.logo === "string" ? { light: data.config.logo } : data.config.logo
+const src = (path: string) => `${data.base}${path.startsWith("/") ? path : `/${path}`}`
+const socials = Object.entries(data.config.footer?.socials ?? {}).flatMap(([key, href]) => {
+  const network = socialNetwork(key)
+  return network ? [{ ...network, href }] : []
+})
+---
+
+<footer class="hd-site-footer" data-pagefind-ignore>
+  <div class="hd-site-footer__row">
+    <a class="hd-brand hd-brand--footer" href={`${data.base}/`}>
+      {
+        logo && (
+          <span class="hd-brand__mark">
+            <img class="hd-brand__light" src={src(logo.light)} alt="" width="20" height="20" loading="lazy" />
+            <img class="hd-brand__dark" src={src(logo.dark ?? logo.light)} alt="" width="20" height="20" loading="lazy" />
+          </span>
+        )
+      }
+      <span class="hd-brand__name">{data.config.name}</span>
+    </a>
+    {
+      socials.length > 0 && (
+        <ul class="hd-socials" aria-label="Réseaux">
+          {socials.map((social) => (
+            <li>
+              <a class="hd-icon-button" href={social.href} rel="me noopener" aria-label={social.label} title={social.label}>
+                <StarlightIcon name={social.icon as "github"} size="1.1rem" />
+              </a>
+            </li>
+          ))}
+        </ul>
+      )
+    }
+  </div>
+  <div class="hd-site-footer__row hd-site-footer__row--meta">
+    {data.config.description && <p>{data.config.description}</p>}
+    <ThemeToggle variant="segmented" />
+  </div>
+</footer>

package/src/overrides/ThemeProvider.astro

@@ -0,0 +1,23 @@
+---
+/**
+ * Thème avant la première peinture, sans éclair : clair par défaut, même si le système est
+ * en sombre ; « Sombre » et « Système » se choisissent et restent mémorisés (`starlight-theme`
+ * vaut `dark` ou `auto`). `data-hd-theme` n'est posé que par ce script : sans JavaScript,
+ * la page reste claire (theme.css).
+ */
+---
+
+<script is:inline>
+  ;(() => {
+    let stored = null
+    try {
+      stored = localStorage.getItem("starlight-theme")
+    } catch {}
+    const dark =
+      stored === "dark" || (stored === "auto" && matchMedia("(prefers-color-scheme: dark)").matches)
+    const theme = dark ? "dark" : "light"
+    document.documentElement.dataset.theme = theme
+    document.documentElement.dataset.hdTheme = theme
+    window.StarlightThemeProvider = { updatePickers() {} }
+  })()
+</script>

package/src/overrides/ThemeToggle.astro

@@ -0,0 +1,90 @@
+---
+import Icon from "./Icon.astro"
+
+/**
+ * Thème : un bouton clair / sombre dans l'en-tête, et le choix à trois (système, clair,
+ * sombre) au pied de page et dans le menu. Clair par défaut. Clé `starlight-theme`, lue avant
+ * la première peinture par `ThemeProvider.astro` : aucun éclair au chargement.
+ */
+interface Props {
+  variant: "button" | "segmented"
+}
+const { variant } = Astro.props
+const choices = [
+  { value: "auto", label: "Système", icon: "monitor" },
+  { value: "light", label: "Clair", icon: "sun" },
+  { value: "dark", label: "Sombre", icon: "moon" },
+] as const
+---
+
+{
+  variant === "button" ? (
+    <button type="button" class="hd-icon-button hd-theme-button" data-hd-theme-toggle aria-label="Passer au thème sombre">
+      <Icon name="moon" class="hd-theme-button__moon" />
+      <Icon name="sun" class="hd-theme-button__sun" />
+    </button>
+  ) : (
+    <div class="hd-theme-choice" role="radiogroup" aria-label="Thème">
+      {choices.map((choice) => (
+        <button type="button" role="radio" aria-checked="false" data-hd-theme={choice.value} aria-label={choice.label} title={choice.label}>
+          <Icon name={choice.icon} size={16} />
+        </button>
+      ))}
+    </div>
+  )
+}
+
+<script>
+  const KEY = "starlight-theme"
+  const stored = (): string => {
+    try {
+      return localStorage.getItem(KEY) || "light"
+    } catch {
+      return "light"
+    }
+  }
+  const system = () => (matchMedia("(prefers-color-scheme: light)").matches ? "light" : "dark")
+  const apply = (choice: string) => {
+    try {
+      localStorage.setItem(KEY, choice)
+    } catch {
+      // Stockage refusé : le thème vaut pour la page affichée.
+    }
+    const theme = choice === "auto" ? system() : choice
+    document.documentElement.dataset.theme = theme
+    document.documentElement.dataset.hdTheme = theme
+    sync()
+  }
+  const sync = () => {
+    const choice = stored()
+    const dark = document.documentElement.dataset.theme === "dark"
+    for (const button of document.querySelectorAll<HTMLButtonElement>("[data-hd-theme-toggle]"))
+      button.setAttribute("aria-label", dark ? "Passer au thème clair" : "Passer au thème sombre")
+    for (const radio of document.querySelectorAll<HTMLButtonElement>("[data-hd-theme]")) {
+      const checked = radio.dataset.hdTheme === choice
+      radio.setAttribute("aria-checked", String(checked))
+      radio.tabIndex = checked ? 0 : -1
+    }
+  }
+
+  for (const button of document.querySelectorAll<HTMLButtonElement>("[data-hd-theme-toggle]"))
+    button.addEventListener("click", () => apply(document.documentElement.dataset.theme === "dark" ? "light" : "dark"))
+  for (const group of document.querySelectorAll<HTMLElement>(".hd-theme-choice")) {
+    const radios = [...group.querySelectorAll<HTMLButtonElement>("[data-hd-theme]")]
+    for (const radio of radios) radio.addEventListener("click", () => apply(radio.dataset.hdTheme!))
+    // Groupe de boutons radio : les flèches déplacent le choix, Tab sort du groupe.
+    group.addEventListener("keydown", (event) => {
+      const step = event.key === "ArrowRight" || event.key === "ArrowDown" ? 1 : event.key === "ArrowLeft" || event.key === "ArrowUp" ? -1 : 0
+      if (!step) return
+      event.preventDefault()
+      const index = radios.findIndex((radio) => radio.getAttribute("aria-checked") === "true")
+      const next = radios[(index + step + radios.length) % radios.length]!
+      apply(next.dataset.hdTheme!)
+      next.focus()
+    })
+  }
+  matchMedia("(prefers-color-scheme: light)").addEventListener("change", () => {
+    if (stored() === "auto") apply("auto")
+  })
+  sync()
+</script>

package/src/overrides/TwoColumnContent.astro

@@ -0,0 +1,45 @@
+---
+import data from "virtual:hgdc-docs/config"
+
+import Icon from "./Icon.astro"
+import { assistantEnabled } from "./sections.ts"
+
+/**
+ * Contenu et table des matières côte à côte. La colonne du contenu garde une largeur de
+ * lecture ; la table colle sous l'en-tête. Elle laisse la place à l'assistant quand il est ouvert.
+ */
+const { toc } = Astro.locals.starlightRoute
+const assistant = assistantEnabled(data.config)
+---
+
+<div class:list={["hd-columns", { "hd-columns--toc": toc }]}>
+  <div class="hd-columns__main main-pane">
+    <slot />
+    {
+      assistant && (
+        <form class="hd-askbar" data-askbar data-pagefind-ignore>
+          <label class="sr-only" for="hd-askbar-input">Pose une question à l'assistant</label>
+          <input
+            id="hd-askbar-input"
+            data-askbar-input
+            type="text"
+            maxlength="1000"
+            placeholder="Pose une question…"
+            autocomplete="off"
+          />
+          <kbd class="hd-kbd" data-shortcut aria-hidden="true">Ctrl I</kbd>
+          <button type="submit" class="hd-send" aria-label="Envoyer la question"><Icon name="arrow-up" size={16} /></button>
+        </form>
+      )
+    }
+  </div>
+  {
+    toc && (
+      <aside class="hd-columns__toc" aria-label="Sur cette page">
+        <div class="hd-toc-scroll">
+          <slot name="right-sidebar" />
+        </div>
+      </aside>
+    )
+  }
+</div>

package/src/overrides/sections.ts

@@ -0,0 +1,29 @@
+import type { DocsConfig } from "../core/config.ts"
+import {
+  pagesOf,
+  pageToPath,
+  withBase,
+  type NavItem,
+  type NavTab,
+  type NavTree,
+  type NavVersion,
+} from "../core/navigation.ts"
+
+/** Section affichée (version, onglet) et onglets de sa version, pour l'en-tête et le menu. */
+export function docsSections(tree: NavTree, index: number) {
+  const sections = tree.versions.flatMap((version) => version.tabs.map((tab) => ({ version, tab })))
+  const current = sections[index] ?? sections[0]!
+  const tabs: Array<NavTab> = current.version.tabs.filter((tab) => tab.label)
+  const versions: Array<NavVersion> = tree.versions.filter((version) => version.label)
+  return { current, tabs, versions }
+}
+
+/** Première page d'une liste : la cible d'un onglet ou d'une version. */
+export function sectionHref(base: string, items: Array<NavItem>): string {
+  const first = pagesOf(items)[0]
+  return withBase(base, first ? pageToPath(first) : "/")
+}
+
+export function assistantEnabled(config: DocsConfig): boolean {
+  return Boolean(config.project) && config.assistant?.enabled !== false
+}