@staticbolt/docs 0.0.1-beta.0

package/sources/parts/pagination-links/pagination-links.part.html

@@ -0,0 +1,81 @@
+<div class="pagination-links">
+  <a class="pagination-link-prev" href="#" rel="prev">
+    <span class="link-label">
+      <svg aria-hidden="true" viewBox="0 0 24 24">
+        <path
+          d="M17 11H9.41l3.3-3.29a1.004 1.004 0 1 0-1.42-1.42l-5 5a1 1 0 0 0-.21.33 1 1 0 0 0 0 .76 1 1 0 0 0 .21.33l5 5a1.002 1.002 0 0 0 1.639-.325 1 1 0 0 0-.219-1.095L9.41 13H17a1 1 0 0 0 0-2Z"
+        ></path>
+      </svg>
+      Previous
+    </span>
+    <span class="link-title"></span>
+  </a>
+
+  <a class="pagination-link-next" href="#" rel="next">
+    <span class="link-label">
+      Next
+      <svg aria-hidden="true" viewBox="0 0 24 24">
+        <path
+          d="M17.92 11.62a1.001 1.001 0 0 0-.21-.33l-5-5a1.003 1.003 0 1 0-1.42 1.42l3.3 3.29H7a1 1 0 0 0 0 2h7.59l-3.3 3.29a1.002 1.002 0 0 0 .325 1.639 1 1 0 0 0 1.095-.219l5-5a1 1 0 0 0 .21-.33 1 1 0 0 0 0-.76Z"
+        ></path>
+      </svg>
+    </span>
+    <span class="link-title"></span>
+  </a>
+</div>
+
+<!-- This script will run once at build time for each page -->
+<script type="module" build-time>
+  // ::: Get current link and populate previous/next links :::
+  import { join, dirname, normalize } from "node:path";
+
+  const paginationPrev = document.querySelector(".pagination-link-prev");
+  const paginationPrevTitle = paginationPrev.querySelector(".link-title");
+
+  const paginationNext = document.querySelector(".pagination-link-next");
+  const paginationNextTitle = paginationNext.querySelector(".link-title");
+
+  // You can find `.sidebar` in the documentation layout
+  const navigationLinks = document.querySelectorAll(".sidebar a.sidebar-link");
+  const currentFile = normalize(__filepath);
+
+  let nextLinkFound = false;
+  let previousLinkFound = false;
+
+  for (const [linkIndex, link] of navigationLinks.entries()) {
+    const linkPath = join(dirname(__filepath), link.attributes.href, "index.html");
+    if (linkPath !== currentFile) continue;
+
+    // Previous
+    const previousLink = navigationLinks[linkIndex - 1];
+    if (previousLink) {
+      const prevHref = previousLink.getAttribute("href");
+      paginationPrev.setAttribute("href", prevHref);
+
+      const prevTitle = previousLink.getAttribute("data-title") || previousLink.textContent;
+      paginationPrevTitle.textContent = prevTitle;
+
+      previousLinkFound = true;
+    }
+
+    // Next
+    const nextLink = navigationLinks[linkIndex + 1];
+    if (nextLink) {
+      const nextHref = nextLink.getAttribute("href");
+      paginationNext.setAttribute("href", nextHref);
+
+      const nextTitle = nextLink.getAttribute("data-title") || nextLink.textContent;
+      paginationNextTitle.textContent = nextTitle;
+
+      nextLinkFound = true;
+    }
+  }
+
+  if (!nextLinkFound) {
+    paginationNext.remove();
+  }
+
+  if (!previousLinkFound) {
+    paginationPrev.remove();
+  }
+</script>

package/sources/parts/pagination-links/pagination-links.style.css

@@ -0,0 +1,58 @@
+.pagination-links {
+  display: flex;
+  flex-flow: row wrap;
+  gap: 0.5em;
+  justify-content: space-between;
+  padding-block-start: 1.5em;
+  margin-block-start: 3em;
+  border-block-start: solid 1px var(--sb-color-gray-5);
+
+  @media print {
+    display: none;
+  }
+
+  .pagination-link-prev,
+  .pagination-link-next {
+    display: flex;
+    flex: 1;
+    flex-direction: column;
+    min-inline-size: 200px;
+    text-decoration: none;
+
+    &[rel="next"] {
+      align-items: flex-end;
+    }
+
+    &[rel="prev"] {
+      align-items: flex-start;
+    }
+
+    .link-label {
+      display: flex;
+      gap: 0.15rem;
+      align-items: center;
+      font-size: var(--sb-text-sm);
+      color: var(--sb-color-gray-3);
+
+      svg {
+        inline-size: 1em;
+        block-size: 1em;
+        fill: currentcolor;
+
+        [dir="rtl"] & {
+          transform: rotate(180deg);
+        }
+      }
+    }
+
+    .link-title {
+      margin-inline: 0.25rem;
+      font-weight: 600;
+      color: var(--sb-color-gray-2);
+    }
+  }
+}
+
+[data-pagefind-announcer] {
+  margin: -1px;
+}

package/sources/parts/sidebar/directory.part.html

@@ -0,0 +1,13 @@
+<sv-accordion class="sidebar-accordion" add-attr-opened="{{ !$data.collapsed }}" heading-level="none" marker="start">
+  <span slot="summary">
+    {{ $data.iconSrc ? `
+    <icon src="${ $data.iconSrc }"></icon>
+    ` : ""}}
+
+    <!-- Title -->
+    {{ $data.title }}
+  </span>
+
+  <!-- Items -->
+  <slot></slot>
+</sv-accordion>

package/sources/parts/sidebar/item.part.html

@@ -0,0 +1,9 @@
+<a class="sidebar-link" data-title="{{ $data.fullTitle }}" href="{{ $data.href }}">
+  {{ $data.iconSrc ? `
+  <icon src="${ $data.iconSrc }"></icon>
+  ` : ""}}
+  <!-- Title -->
+  {{ $data.title }} {{ ($data.badgeVariant && $data.badgeText) ? `
+  <part src="../badge/badge.part.html" text="${$data.badgeText}" variant="${$data.badgeVariant}"></part>
+  ` : "" }}
+</a>

package/sources/parts/sidebar/sidebar.part.html

@@ -0,0 +1,106 @@
+<div class="sidebar">
+  <nav aria-label="Sidebar navigation">
+    <slot name="sidebar"></slot>
+  </nav>
+
+  <div class="sidebar-footer">
+    <div class="sidebar-social-icons">
+      <slot name="icons"></slot>
+    </div>
+
+    <div class="sidebar-color-scheme-switcher">
+      <part src="../color-scheme-switch/color-scheme-switch.part.html"></part>
+    </div>
+  </div>
+</div>
+
+<script type="module" build-time>
+  import { join, dirname, normalize } from "node:path";
+
+  // ::: Mark current page links as active and expand matching accordions. :::
+
+  const navigationLinks = document.querySelectorAll(".sidebar a");
+  const currentFile = normalize(__filepath);
+
+  for (const [linkIndex, link] of navigationLinks.entries()) {
+    const linkPath = join(dirname(__filepath), link.attributes.href, "index.html");
+    if (linkPath !== currentFile) continue;
+
+    link.classList.add("active");
+    link.setAttribute("aria-current", "page");
+
+    // Open all parent accordions
+    let parent = link.parentNode;
+    while (parent) {
+      if (parent.classList?.contains("sidebar-accordion")) {
+        parent.setAttribute("opened", "");
+      }
+
+      parent = parent.parentNode;
+    }
+  }
+</script>
+
+<!-- ::: Persist sidebar navigation state across page loads. ::: -->
+<script>
+  (() => {
+    /** @type {NodeListOf<HTMLDivElement>} */
+    const accordions = document.querySelectorAll(".sidebar-accordion");
+
+    // ::: Restore the accordion's previous open state. :::
+    try {
+      const state = JSON.parse(sessionStorage.getItem("sidebar-state") ?? {});
+
+      for (const [accordionIndex, opened] of Object.entries(state)) {
+        const accordion = /** @type {HTMLDivElement} */ (accordions[accordionIndex]);
+        if (!accordion) continue;
+
+        // Keep accordions containing the active link expanded by default
+        // to preserve navigation context and visibility of the current page.
+        if (accordion.matches(":has(a.active)")) continue;
+
+        // Toggle the accordion instantly without animation.
+        accordion[opened ? "open" : "close"](true);
+      }
+    } catch {
+      // ignore
+    }
+
+    // ::: Save accordion open state when toggled. :::
+    const accordionToggleHandler = () => {
+      const state = {};
+
+      for (const [accordionIndex, accordion] of accordions.entries()) {
+        state[accordionIndex] = accordion.opened;
+      }
+
+      sessionStorage.setItem("sidebar-state", JSON.stringify(state));
+    };
+
+    for (const accordion of accordions) {
+      accordion.addEventListener("toggled", accordionToggleHandler);
+    }
+
+    // ::: Restore sidebar scroll position. :::
+    const sidebar = document.querySelector(".sidebar");
+
+    const onReady = () => {
+      // First rAF: end of current task, second rAF: after first paint
+      requestAnimationFrame(() => {
+        requestAnimationFrame(() => {
+          const saved = sessionStorage.getItem("sidebar-scroll");
+          if (saved) sidebar.scrollTop = +saved;
+        });
+      });
+    };
+
+    document.addEventListener("DOMContentLoaded", onReady, { once: true });
+
+    // ::: Save sidebar scroll position. :::
+    const sidebarScrollHandler = () => {
+      sessionStorage.setItem("sidebar-scroll", sidebar.scrollTop);
+    };
+
+    sidebar.addEventListener("scroll", sidebarScrollHandler, { passive: true });
+  })();
+</script>

package/sources/parts/sidebar/sidebar.style.css

@@ -0,0 +1,202 @@
+.sidebar {
+  position: sticky;
+  inset-block-start: var(--sb-header-height);
+  display: flex;
+  flex-direction: column;
+  align-items: flex-end;
+  justify-content: space-between;
+  min-inline-size: 18rem;
+  block-size: 100%;
+  max-block-size: calc(100svh - var(--sb-header-height));
+  padding-inline: 0.8em 0.1em;
+  overflow-y: auto;
+  scrollbar-gutter: stable;
+  overscroll-behavior: contain;
+  scrollbar-color: var(--sb-color-gray-5) transparent;
+  scrollbar-width: thin;
+  background-color: var(--sb-color-black);
+  border-inline-end: solid 1px var(--sb-color-gray-5);
+
+  & > nav {
+    flex: 1;
+  }
+
+  .sidebar-item-icon {
+    display: block;
+    inline-size: 1em;
+    block-size: 1em;
+
+    &:not(.no-fill) {
+      fill: var(--sb-color-gray-4);
+    }
+  }
+
+  .sidebar-list {
+    padding: 0;
+    margin: 0;
+    list-style: none;
+  }
+
+  .sidebar-accordion {
+    --sv-toggle-dur: 200ms;
+    --sv-gray-6: transparent;
+    --sv-gray-5: transparent;
+
+    &::part(trigger) {
+      padding-block: 0.35em;
+      font-family: var(--sb-md-font);
+      font-size: var(--sb-text-base);
+      font-weight: 600;
+      color: var(--sb-color-gray-0);
+    }
+
+    &::part(marker) {
+      color: var(--sb-color-gray-2);
+    }
+
+    &::part(content) {
+      padding-inline: 0;
+      margin-inline-start: calc(1lh - 2px);
+      border-inline-start: solid 1px var(--sb-color-gray-5);
+    }
+
+    &:has(.sidebar-link.active) {
+      & > span[slot="summary"] {
+        &::before {
+          position: absolute;
+          inset-inline-start: 0;
+          inline-size: 4px;
+          block-size: 4px;
+          content: "";
+          background-color: var(--sb-color-accent);
+          border-radius: 50%;
+        }
+
+        .sidebar-item-icon:not(.no-fill) {
+          fill: var(--sb-color-accent-high);
+        }
+      }
+    }
+
+    span[slot="summary"] {
+      position: relative;
+      display: flex;
+      flex-direction: row;
+      gap: 0.5em;
+      align-items: center;
+    }
+
+    @media (pointer: fine) {
+      &::part(trigger):hover {
+        color: var(--sb-color-accent-high);
+      }
+
+      &:hover:not(:has(&:hover))::part(content) {
+        border-inline-start: solid 1px var(--sb-color-accent-high);
+      }
+    }
+  }
+
+  .sidebar-link {
+    display: flex;
+    flex-direction: row;
+    gap: 0.5em;
+    align-items: center;
+    padding: 0.3em 1.4em;
+    margin-inline-start: -0.5px;
+    font-family: var(--sb-md-font);
+    font-size: var(--sb-text-sm);
+    line-height: 1.4;
+    color: var(--sb-color-gray-2);
+    text-decoration: none;
+    border-inline-start: solid 1px transparent;
+    border-start-end-radius: 5px;
+    border-end-end-radius: 5px;
+
+    @media (pointer: fine) {
+      &:hover {
+        color: var(--sb-color-accent-high);
+      }
+    }
+
+    &.active {
+      color: var(--sb-color-accent-high);
+      background-color: var(--sb-color-gray-6);
+      border-inline-start: solid 1px var(--sb-color-accent-high);
+    }
+  }
+
+  .sidebar-list:first-child {
+    align-self: flex-start;
+    padding-block: 1em;
+
+    /** First level .sidebar-list-item */
+    > .sidebar-list-item:not(:first-child) {
+      margin-block-start: 1rem;
+    }
+
+    /** First level .sidebar-link */
+    > .sidebar-list-item > .sidebar-link {
+      padding-inline-start: 2em;
+      font-family: var(--sb-md-font);
+      font-size: var(--sb-text-base);
+      font-weight: 600;
+      color: var(--sb-color-gray-0);
+    }
+  }
+
+  .sidebar-footer {
+    display: none;
+    flex-direction: row;
+    align-items: center;
+    justify-content: space-between;
+    min-inline-size: 18rem;
+    padding: 1em 0.5em;
+    border-block-start: solid 1px var(--sb-color-gray-5);
+  }
+
+  @media print {
+    display: none;
+  }
+}
+
+@media (max-width: 900px) {
+  .sidebar {
+    position: fixed;
+    inset-block: var(--sb-header-height) 0;
+    inset-inline: 0;
+    z-index: 200;
+    visibility: hidden;
+    align-items: unset;
+    justify-content: stretch;
+    opacity: 0;
+    translate: -100% 0;
+    transition:
+      translate 200ms cubic-bezier(0.7, 0, 0.84, 0),
+      opacity 200ms linear,
+      visibility 200ms linear;
+    transition-behavior: allow-discrete;
+
+    [dir="rtl"] & {
+      translate: 100% 0;
+    }
+
+    &.open {
+      visibility: visible;
+      opacity: 1;
+      translate: 0 0;
+      transition:
+        translate 200ms cubic-bezier(0.16, 1, 0.3, 1),
+        opacity 200ms linear,
+        visibility 200ms linear;
+    }
+
+    @media (prefers-reduced-motion: reduce) {
+      transition: none;
+    }
+
+    .sidebar-footer {
+      display: flex;
+    }
+  }
+}

package/sources/parts/table-of-content/table-of-content-desktop.part.html

@@ -0,0 +1,122 @@
+<aside class="toc desktop">
+  <div class="toc-nav-container">
+    <nav class="toc-nav toc-content" aria-labelledby="toc-title">
+      <h2 id="toc-title" class="toc-title" data-ignore-toc>On this page</h2>
+    </nav>
+  </div>
+</aside>
+
+<script build-time>
+  const tocContents = document.querySelectorAll(".toc-content");
+  const headings = document
+    .querySelectorAll("h1[id], h2[id], h3[id], h4[id], h5[id], h6[id]")
+    .filter(el => !el.closest(".not-content"));
+
+  const maxHeading = +"{{ $data.maxHeading }}";
+  const minHeading = +"{{ $data.minHeading }}";
+
+  const ul = document.createElement("ul");
+  ul.classList.add("toc-list");
+
+  const title = document.querySelector("h1[id]");
+
+  // Overview
+  const overviewItem = document.createElement("li");
+  overviewItem.style.setProperty("--depth", "0");
+
+  const overviewLink = document.createElement("a");
+  overviewLink.classList.add("toc-link");
+  overviewLink.setAttribute("href", `#${title?.id || ""}`);
+  overviewLink.textContent = "Overview";
+
+  overviewItem.appendChild(overviewLink);
+  ul.appendChild(overviewItem);
+
+  for (const heading of headings) {
+    const level = +heading.tagName.slice(1);
+
+    if (heading.hasAttribute("data-ignore-toc")) {
+      heading.removeAttribute("data-ignore-toc");
+      continue;
+    }
+
+    if (level < minHeading || level > maxHeading) {
+      continue;
+    }
+
+    const id = heading.getAttribute("id");
+    const content = heading.textContent;
+    const depth = Math.max(level - minHeading, 0);
+
+    const listItem = document.createElement("li");
+    listItem.style.setProperty("--depth", String(depth));
+
+    const link = document.createElement("a");
+    link.classList.add("toc-link");
+    link.setAttribute("href", `#${id}`);
+    link.textContent = content;
+
+    listItem.appendChild(link);
+    ul.appendChild(listItem);
+  }
+
+  for (const tocContent of tocContents) {
+    tocContent.appendChild(ul.cloneNode(true));
+  }
+</script>
+
+<script>
+  (() => {
+    // All links in the mobile and desktop TOC
+    const links = document.querySelectorAll(".toc-list a");
+
+    // Mobile TOC current title
+    const currentTitle = document.querySelector(".toc-current-title");
+
+    const headings = Array.from(links)
+      .map(a => document.getElementById(a.getAttribute("href").slice(1)))
+      .filter(Boolean);
+
+    function setActive(id) {
+      for (const link of links) {
+        const active = link.getAttribute("href") === "#" + id;
+        link.classList.toggle("active", active);
+        if (active) {
+          currentTitle.textContent = link.textContent;
+        }
+      }
+    }
+
+    function update() {
+      if (!headings.length) return;
+
+      let scrollPaddingTop = getComputedStyle(document.documentElement).getPropertyValue("scroll-padding-top");
+      scrollPaddingTop = parseFloat(scrollPaddingTop.replace("px", "").trim());
+      scrollPaddingTop = !isFinite(scrollPaddingTop) ? 50 : scrollPaddingTop + 2;
+
+      let active = headings[0];
+
+      for (const heading of headings) {
+        if (heading.getBoundingClientRect().top <= scrollPaddingTop) {
+          active = heading;
+        }
+
+        // headings are in document order, so we can stop early
+        else {
+          break;
+        }
+      }
+
+      const nearBottom = window.innerHeight + window.scrollY >= document.documentElement.scrollHeight - 100;
+      if (nearBottom) {
+        active = headings[headings.length - 1];
+      }
+
+      setActive(active.id);
+    }
+
+    window.addEventListener("scroll", update, { passive: true });
+
+    update(); // set correct state on page load / hash navigation
+  })();
+</script>

package/sources/parts/table-of-content/table-of-content-mobile.part.html

@@ -0,0 +1,24 @@
+<div class="toc mobile">
+  <nav class="toc-nav-mobile">
+    <sv-accordion class="toc-accordion" heading-level="none" marker="start">
+      <span slot="summary">
+        <span class="toc-accordion-summary">On this page</span>
+        <span class="toc-current-title"></span>
+      </span>
+
+      <div class="toc-content"></div>
+    </sv-accordion>
+  </nav>
+</div>
+
+<!-- ::: Close the accordion when a link is clicked ::: -->
+<script type="module">
+  const tocAccordion = document.querySelector(".toc-accordion");
+  const tocLinks = document.querySelectorAll(".toc-accordion a");
+
+  for (const link of tocLinks) {
+    link.addEventListener("click", () => {
+      tocAccordion.opened = false;
+    });
+  }
+</script>