@staticbolt/docs 0.0.1-beta.0

package/sources/parts/badge/badge.style.css

@@ -0,0 +1,44 @@
+.badge {
+  padding: 0.1em 0.4em;
+  padding-block-start: 0.2em;
+  margin-block: 0.2em;
+  font-family: var(--sb-font-mono);
+  font-size: var(--sb-text-xs);
+  font-weight: normal;
+  line-height: 1;
+  color: #fff;
+  border: 1px solid #fff;
+  border-radius: 5px;
+
+  &.warning {
+    color: var(--sb-warning-text);
+    background-color: var(--sb-warning-background);
+    border: 1px solid var(--sb-warning-border);
+  }
+
+  &.caution,
+  &.danger {
+    color: var(--sb-caution-text);
+    background-color: var(--sb-caution-background);
+    border: 1px solid var(--sb-caution-border);
+  }
+
+  &.note {
+    color: var(--sb-note-text);
+    background-color: var(--sb-note-background);
+    border: 1px solid var(--sb-note-border);
+  }
+
+  &.important {
+    color: var(--sb-important-text);
+    background-color: var(--sb-important-background);
+    border: 1px solid var(--sb-important-border);
+  }
+
+  &.tip,
+  &.success {
+    color: var(--sb-tip-text);
+    background-color: var(--sb-tip-background);
+    border: 1px solid var(--sb-tip-border);
+  }
+}

package/sources/parts/callouts/callouts.part.html

@@ -0,0 +1,30 @@
+<!-- ::: Collapsible callouts (`> [!note]-`) render as `<details>`; swap them for sv-accordion ::: -->
+<script build-time>
+  for (const callout of document.querySelectorAll("details.callout")) {
+    const accordion = document.createElement("sv-accordion");
+    accordion.setAttribute("data-callout", callout.getAttribute("data-callout"));
+    accordion.setAttribute("class", callout.getAttribute("class"));
+    accordion.setAttribute("heading-level", "none");
+
+    if (callout.hasAttribute("open")) {
+      accordion.setAttribute("opened", "");
+    }
+
+    const summary = callout.querySelector(".callout-title");
+    if (summary) {
+      const span = document.createElement("span");
+      span.setAttribute("slot", "summary");
+      span.classList.add("callout-title");
+      span.innerHTML = summary.innerHTML;
+      accordion.append(span);
+    }
+
+    const content = callout.querySelector(".callout-content");
+    if (content) {
+      accordion.append(content);
+    }
+
+    callout.replaceWith(accordion);
+    accordion.querySelector(".callout-fold-icon")?.remove();
+  }
+</script>

package/sources/parts/color-scheme-switch/color-scheme-switch.part.html

@@ -0,0 +1,111 @@
+<div class="color-scheme-switch-container">
+  <button type="button" class="color-scheme-switch" aria-label="Switch to dark mode" aria-pressed="false" title="Select theme">
+    <!-- Sun — shown when light mode is active -->
+    <svg
+      class="switch-icon switch-icon-sun"
+      aria-hidden="true"
+      focusable="false"
+      viewBox="0 -960 960 960"
+      xmlns="http://www.w3.org/2000/svg"
+    >
+      <path
+        d="M480-360q50 0 85-35t35-85q0-50-35-85t-85-35q-50 0-85 35t-35 85q0 50 35 85t85 35Zm0 80q-83 0-141.5-58.5T280-480q0-83 58.5-141.5T480-680q83 0 141.5 58.5T680-480q0 83-58.5 141.5T480-280ZM200-440H40v-80h160v80Zm720 0H760v-80h160v80ZM440-760v-160h80v160h-80Zm0 720v-160h80v160h-80ZM256-650l-101-97 57-59 96 100-52 56Zm492 496-97-101 53-55 101 97-57 59Zm-98-550 97-101 59 57-100 96-56-52ZM154-212l101-97 55 53-97 101-59-57Zm326-268Z"
+      />
+    </svg>
+
+    <!-- Moon — shown when dark mode is active -->
+    <svg
+      class="switch-icon switch-icon-moon"
+      aria-hidden="true"
+      focusable="false"
+      viewBox="0 -960 960 960"
+      xmlns="http://www.w3.org/2000/svg"
+    >
+      <path
+        d="M484-87q-81.77 0-154.11-31.27-72.35-31.27-126.35-85.27t-85.27-126.35Q87-402.23 87-484q0-140.38 87.12-248.04 87.11-107.65 224.19-136.65-7.08 97.31 20.34 190.27 27.43 92.96 97.12 162.65 69.69 69.69 162.65 97.12 92.96 27.42 190.27 17.34-28.38 138.08-136.35 226.19Q624.38-87 484-87Z"
+      />
+    </svg>
+  </button>
+</div>
+
+<insert selector="head">
+  <script>
+    // @ts-check
+    (() => {
+      const STORAGE_KEY = "color-scheme";
+      const PREFERS_DARK = window.matchMedia("(prefers-color-scheme: dark)");
+
+      let currentScheme = PREFERS_DARK.matches ? "dark" : "light";
+
+      // Override with stored value
+      const stored = window.localStorage.getItem(STORAGE_KEY);
+      if (stored === "dark" || stored === "light") {
+        currentScheme = stored;
+        document.documentElement.style.colorScheme = stored;
+      }
+
+      /**
+       * @param {"light" | "dark"} scheme
+       * @param {NodeListOf<HTMLButtonElement>} buttons
+       */
+      const applyScheme = (scheme, buttons) => {
+        const isDark = scheme === "dark";
+
+        for (const button of buttons) {
+          document.documentElement.style.colorScheme = scheme;
+          window.localStorage.setItem(STORAGE_KEY, scheme);
+          button.setAttribute("aria-pressed", String(isDark));
+          button.setAttribute("aria-label", isDark ? "Switch to light mode" : "Switch to dark mode");
+        }
+
+        document.dispatchEvent(new CustomEvent("color-scheme-changed", { detail: scheme }));
+      };
+
+      const onReady = () => {
+        /** @type {NodeListOf<HTMLButtonElement>} */
+        const colorSchemeButtons = document.querySelectorAll(".color-scheme-switch");
+
+        const isDark = currentScheme === "dark";
+
+        for (const colorSchemeButton of colorSchemeButtons) {
+          // Set initial state without triggering storage/event side-effects
+          colorSchemeButton.setAttribute("aria-pressed", String(isDark));
+          colorSchemeButton.setAttribute("aria-label", isDark ? "Switch to light mode" : "Switch to dark mode");
+
+          // Add event listener
+          colorSchemeButton.addEventListener("click", () => {
+            const nextScheme = colorSchemeButton.getAttribute("aria-pressed") === "true" ? "light" : "dark";
+            const { left, top, width, height } = colorSchemeButton.getBoundingClientRect();
+            viewTransition(() => applyScheme(nextScheme, colorSchemeButtons), left + width / 2, top + height / 2);
+          });
+        }
+      };
+
+      document.addEventListener("DOMContentLoaded", onReady, { once: true, passive: true });
+
+      /**
+       * @param {() => void} update
+       * @param {number} x
+       * @param {number} y
+       */
+      async function viewTransition(update, x, y) {
+        if (!document.startViewTransition || matchMedia("(prefers-reduced-motion: reduce)").matches) {
+          update();
+          return;
+        }
+
+        const transition = document.startViewTransition({ update, types: ["circular-reveal"] });
+
+        await transition.ready;
+
+        const xPercent = (x / window.innerWidth) * 100;
+        const yPercent = (y / window.innerHeight) * 100;
+
+        document.documentElement.animate(
+          { clipPath: [`circle(0% at ${xPercent}% ${yPercent}%)`, `circle(150vmax at ${xPercent}% ${yPercent}%)`] },
+          { duration: 400, easing: "cubic-bezier(0.64, 0, 0.78, 0)", pseudoElement: "::view-transition-new(root)" }
+        );
+      }
+    })();
+  </script>
+</insert>

package/sources/parts/color-scheme-switch/color-scheme-switch.style.css

@@ -0,0 +1,77 @@
+:root:active-view-transition-type(circular-reveal) {
+  &::view-transition-image-pair(root) {
+    isolation: auto;
+  }
+
+  &::view-transition-old(root),
+  &::view-transition-new(root) {
+    display: block;
+    mix-blend-mode: normal;
+    animation: none;
+  }
+}
+
+.color-scheme-switch-container {
+  display: flex;
+  align-items: center;
+  padding: 0.6em 1em;
+}
+
+.color-scheme-switch {
+  position: relative;
+  inline-size: var(--header-icon-size);
+  block-size: var(--header-icon-size);
+  padding: 0;
+  line-height: 0;
+  color: inherit;
+  appearance: none;
+  cursor: pointer;
+  outline-offset: 4px;
+  background: none;
+  border: none;
+  border-radius: 50%;
+
+  &:focus-visible {
+    outline: 2px solid var(--sb-color-accent, currentColor);
+  }
+}
+
+.switch-icon {
+  position: absolute;
+  inset: 0;
+  inline-size: 1.4em;
+  block-size: 1.4em;
+  fill: currentcolor;
+  transition:
+    opacity 250ms ease,
+    rotate 350ms cubic-bezier(0.34, 1.56, 0.64, 1),
+    scale 350ms cubic-bezier(0.34, 1.56, 0.64, 1);
+}
+
+.color-scheme-switch[aria-pressed="false"] {
+  .switch-icon-sun {
+    opacity: 1;
+    rotate: 0deg;
+    scale: 1;
+  }
+
+  .switch-icon-moon {
+    opacity: 0;
+    rotate: -180deg;
+    scale: 0.5;
+  }
+}
+
+.color-scheme-switch[aria-pressed="true"] {
+  .switch-icon-sun {
+    opacity: 0;
+    rotate: 180deg;
+    scale: 0.5;
+  }
+
+  .switch-icon-moon {
+    opacity: 1;
+    rotate: 0deg;
+    scale: 1;
+  }
+}

package/sources/parts/document/document.part.html

@@ -0,0 +1,66 @@
+<!--
+  @part The whole docs page inside <body>: header, sidebar, content, table of contents, pagination.
+  @attr title - Site name shown in the header.
+  @attr minHeading - Lowest heading level in the table of contents. Default 2.
+  @attr maxHeading - Highest heading level in the table of contents. Default 3.
+  @slot - The page content.
+  @slot logo - Rendered before the title in the header link.
+  @slot icons - Links rendered in the header and the sidebar footer.
+-->
+
+<!-- ::: sv-accordion: sidebar, mobile table of contents, collapsible callouts ::: -->
+<script src="@staticview/ui/accordion"></script>
+
+<a class="skip-content-link" href="">Skip to content</a>
+
+<part src="@staticbolt/docs/parts/header/header.part.html" title="{{ $data.title }}">
+  <slot name="logo" slot="logo"></slot>
+  <slot name="icons" slot="icons"></slot>
+</part>
+
+<div class="markdown-layout">
+  <part src="@staticbolt/docs/parts/sidebar/sidebar.part.html">
+    <slot name="icons" slot="icons"></slot>
+  </part>
+
+  <div class="markdown-wrapper">
+    <part src="@staticbolt/docs/parts/table-of-content/table-of-content-mobile.part.html"></part>
+
+    <div class="markdown-body">
+      <main data-pagefind-body>
+        <slot />
+      </main>
+
+      <footer>
+        <part src="@staticbolt/docs/parts/pagination-links/pagination-links.part.html"></part>
+      </footer>
+    </div>
+  </div>
+
+  <part
+    maxHeading="{{ $data.maxHeading ?? 3 }}"
+    minHeading="{{ $data.minHeading ?? 2 }}"
+    src="@staticbolt/docs/parts/table-of-content/table-of-content-desktop.part.html"
+  ></part>
+</div>
+
+<part src="@staticbolt/docs/parts/callouts/callouts.part.html"></part>
+<part src="@staticbolt/docs/parts/mermaid/mermaid.part.html"></part>
+
+<!-- ::: Page title and skip link ::: -->
+<script build-time>
+  const heading = document.querySelector("h1[id]");
+  const title = document.querySelector("title");
+  const ogTitle = document.querySelector('meta[property="og:title"]');
+  const skipContent = document.querySelector("a.skip-content-link");
+
+  if (heading && title && heading.textContent !== title.textContent) {
+    const fullTitle = `${heading.textContent} | ${title.textContent}`;
+    title.textContent = fullTitle;
+    ogTitle?.setAttribute("content", fullTitle);
+  }
+
+  if (heading && skipContent) {
+    skipContent.setAttribute("href", `#${heading.id}`);
+  }
+</script>

package/sources/parts/header/header.part.html

@@ -0,0 +1,62 @@
+<header class="header">
+  <div class="header-content">
+    <div class="side-menu-trigger-container">
+      <button class="side-menu-trigger-button" aria-expanded="false" aria-label="Menu">
+        <svg class="menu-open-icon" aria-hidden="true" viewBox="0 -960 960 960" xmlns="http://www.w3.org/2000/svg">
+          <path d="M120-240v-80h720v80H120Zm0-200v-80h720v80H120Zm0-200v-80h720v80H120Z" />
+        </svg>
+
+        <svg class="menu-close-icon" aria-hidden="true" viewBox="0 -960 960 960" xmlns="http://www.w3.org/2000/svg">
+          <path d="m256-200-56-56 224-224-224-224 56-56 224 224 224-224 56 56-224 224 224 224-56 56-224-224-224 224Z" />
+        </svg>
+      </button>
+    </div>
+
+    <div class="header-title">
+      <div class="title-wrapper">
+        <a href="~/" translate="no">
+          <slot name="logo"></slot>
+          {{ $data.title }}
+        </a>
+      </div>
+    </div>
+
+    <div class="header-center">
+      <part src="../pagefind/pagefind.part.html"></part>
+    </div>
+
+    <div class="header-icons">
+      <slot name="icons"></slot>
+
+      <div class="header-color-scheme-switch">
+        <part src="../color-scheme-switch/color-scheme-switch.part.html"></part>
+      </div>
+    </div>
+  </div>
+</header>
+
+<!-- ::: Toggle the sidebar ::: -->
+<script type="module">
+  // @ts-check
+
+  (() => {
+    /** @type {HTMLButtonElement | null} */
+    const menuTrigger = document.querySelector(".side-menu-trigger-button");
+    if (!menuTrigger) {
+      return;
+    }
+
+    /** @type {HTMLDivElement | null} */
+    const sidebar = document.querySelector(".sidebar");
+    if (!sidebar) {
+      menuTrigger.remove();
+      return;
+    }
+
+    menuTrigger.addEventListener("click", () => {
+      const isOpen = menuTrigger.getAttribute("aria-expanded") === "true";
+      menuTrigger.setAttribute("aria-expanded", String(!isOpen));
+      sidebar.classList.toggle("open", !isOpen);
+    });
+  })();
+</script>

package/sources/parts/header/header.style.css

@@ -0,0 +1,123 @@
+:root {
+  --header-icon-size: 1.5em;
+  --sb-header-height: 4rem;
+
+  @media (max-width: 900px) {
+    --sb-header-height: 3rem;
+  }
+}
+
+.header {
+  position: sticky;
+  inset-block-start: 0;
+  z-index: 100;
+  display: grid;
+  align-items: center;
+  block-size: var(--sb-header-height);
+  padding-inline: 1.5em 1em;
+  background-color: rgb(from var(--sb-color-black) r g b / 80%);
+  border-block-end: 1px solid var(--sb-color-gray-5);
+  backdrop-filter: blur(7px);
+
+  @media (max-width: 900px) {
+    padding-inline: 0.8em 0.5em;
+  }
+
+  @media print {
+    display: none;
+  }
+
+  .header-content {
+    display: grid;
+    grid-template-columns: 1fr 2fr 1fr;
+    align-content: center;
+    inline-size: 100%;
+    max-inline-size: 100rem;
+    margin: auto;
+  }
+
+  .side-menu-trigger-container {
+    display: none;
+    align-items: center;
+
+    .side-menu-trigger-button {
+      position: relative;
+      inline-size: var(--header-icon-size);
+      block-size: var(--header-icon-size);
+      color: inherit;
+      cursor: pointer;
+      background-color: transparent;
+      border: none;
+
+      svg {
+        position: absolute;
+        inset: 0;
+        inline-size: var(--header-icon-size);
+        block-size: var(--header-icon-size);
+        opacity: 0;
+        fill: currentcolor;
+        rotate: 0deg;
+        scale: 0;
+        transition:
+          opacity 0.25s ease,
+          scale 0.35s cubic-bezier(0.34, 1.56, 0.64, 1);
+      }
+
+      &[aria-expanded="true"] .menu-close-icon,
+      &[aria-expanded="false"] .menu-open-icon {
+        opacity: 1;
+        scale: 1;
+      }
+    }
+  }
+
+  .header-title {
+    display: grid;
+    align-items: center;
+
+    .title-wrapper {
+      a {
+        font-family: var(--sb-md-font);
+        font-size: var(--sb-text-h3);
+        font-weight: 600;
+        color: var(--sb-color-accent-high);
+        text-decoration: none;
+      }
+    }
+  }
+
+  .header-center {
+    display: grid;
+    place-items: center;
+  }
+
+  .header-icons {
+    display: flex;
+    align-items: center;
+    justify-content: flex-end;
+
+    .header-color-scheme-switch {
+      border-inline-start: solid 1px var(--sb-color-gray-5);
+    }
+  }
+}
+
+@media (max-width: 900px) {
+  .header {
+    .side-menu-trigger-container {
+      display: flex;
+    }
+
+    .header-title {
+      text-align: center;
+    }
+
+    .header-center {
+      justify-items: end;
+    }
+
+    .header-icons {
+      display: none;
+    }
+  }
+}

package/sources/parts/mermaid/mermaid.part.html

@@ -0,0 +1,15 @@
+<!-- ::: Renders ```mermaid fences, themed from the page's CSS variables ::: -->
+<script type="module" data-mermaid-script src="@staticbolt/docs/scripts/mermaid.ts"></script>
+
+<!-- ::: Drop the script from pages without a diagram ::: -->
+<script build-time>
+  const mermaidScript = document.querySelector("[data-mermaid-script]");
+
+  if (mermaidScript) {
+    mermaidScript.removeAttribute("data-mermaid-script");
+
+    if (!document.querySelector(".mermaid")) {
+      mermaidScript.remove();
+    }
+  }
+</script>

package/sources/parts/pagefind/pagefind.part.html

@@ -0,0 +1,75 @@
+<pagefind-modal-trigger></pagefind-modal-trigger>
+
+<button class="pagefind-modal-trigger-button" style="display: none" aria-keyshortcuts="Control+k" aria-label="Search">
+  <svg aria-hidden="true" viewBox="0 0 24 24">
+    <path
+      d="M21.71 20.29 18 16.61A9 9 0 1 0 16.61 18l3.68 3.68a.999.999 0 0 0 1.42 0 1 1 0 0 0 0-1.39ZM11 18a7 7 0 1 1 0-14 7 7 0 0 1 0 14Z"
+    ></path>
+  </svg>
+</button>
+
+<pagefind-modal></pagefind-modal>
+
+<!-- ::: Path from this page to the Pagefind bundle, so the site works on any subpath ::: -->
+<script type="module" build-time>
+  import { dirname, relative } from "node:path";
+
+  const modal = document.querySelector("pagefind-modal");
+  modal.setAttribute("data-bundle-path", relative(dirname(__filepath), "pagefind") + "/");
+</script>
+
+<insert selector="body">
+  <link class="pagefind-stylesheet" as="style" bundle href="./pagefind.style.css" rel="preload" />
+
+  <script type="module">
+    // @ts-check
+
+    (async () => {
+      // ::: Lazy-load the Pagefind UI. :::
+
+      /** @type {HTMLLinkElement | null} */
+      const pagefindStyleSheet = document.querySelector(".pagefind-stylesheet");
+      if (!pagefindStyleSheet) {
+        console.error("Could not find pagefind stylesheet element");
+        return;
+      }
+
+      const onLoad = async () => {
+        pagefindStyleSheet.rel = "stylesheet";
+
+        const { getInstanceManager } = await import("@pagefind/component-ui");
+
+        const relativeBundlePath = document.querySelector("pagefind-modal")?.getAttribute("data-bundle-path") ?? "pagefind/";
+        const bundlePath = new URL(relativeBundlePath, import.meta.url).pathname;
+        getInstanceManager().instances.get("default").options.bundlePath = bundlePath;
+      };
+
+      const isDownloaded = performance.getEntriesByName(pagefindStyleSheet.href).length > 0;
+      if (isDownloaded) {
+        await onLoad();
+      } else {
+        pagefindStyleSheet.addEventListener("load", onLoad, { once: true });
+      }
+
+      // ::: Open the Pagefind modal when the search button is clicked. :::
+
+      /** @type {(HTMLElement & { openModal(): void }) | null} */
+      const pagefindModalTrigger = document.querySelector("pagefind-modal-trigger");
+      if (!pagefindModalTrigger) {
+        console.error("Could not find pagefind modal trigger element");
+        return;
+      }
+
+      /** @type {HTMLButtonElement | null} */
+      const triggerModalIconButton = document.querySelector(".pagefind-modal-trigger-button");
+      if (!triggerModalIconButton) {
+        console.error("Could not find pagefind modal trigger button element");
+        return;
+      }
+
+      triggerModalIconButton.addEventListener("click", () => {
+        pagefindModalTrigger.openModal();
+      });
+    })();
+  </script>
+</insert>

package/sources/parts/pagefind/pagefind.style.css

@@ -0,0 +1,57 @@
+@import url("@pagefind/component-ui/css");
+
+:root {
+  --pf-text: var(--sb-color-gray-0);
+  --pf-text-secondary: var(--sb-color-gray-0);
+  --pf-text-muted: var(--sb-color-gray-3);
+  --pf-background: var(--sb-color-gray-7);
+  --pf-border: var(--sb-color-gray-5);
+  --pf-border-focus: var(--sb-color-gray-4);
+  --pf-skeleton: var(--sb-color-gray-5);
+  --pf-skeleton-shine: var(--sb-color-gray-6);
+  --pf-hover: var(--sb-color-gray-5);
+  --pf-mark: var(--sb-color-accent-high);
+  --pf-error-text: var(--sb-caution-text);
+  --pf-error-bg: var(--sb-caution-background);
+  --pf-error-border: var(--sb-caution-border);
+}
+
+:is(pagefind-modal-trigger, pagefind-modal, pagefind-modal-header, pagefind-summary, pagefind-results, pagefind-input) {
+  color-scheme: inherit !important;
+
+  &:not(:defined) {
+    display: none;
+  }
+}
+
+pagefind-modal-trigger {
+  inline-size: 100%;
+  max-inline-size: 20em;
+  padding-inline: 0.5em;
+
+  @media (max-width: 900px) {
+    display: none;
+  }
+}
+
+pagefind-modal {
+  display: contents;
+}
+
+.pagefind-modal-trigger-button {
+  display: none;
+  color: inherit;
+  cursor: pointer;
+  background-color: transparent;
+  border: none;
+
+  @media (max-width: 900px) {
+    display: block !important;
+  }
+
+  svg {
+    inline-size: var(--header-icon-size);
+    block-size: var(--header-icon-size);
+    fill: currentcolor;
+  }
+}