@highjumpdigitalsoftware/blog-kit 0.6.0

package/astro/blogkit/BlogIndex.astro

@@ -0,0 +1,144 @@
+---
+/* ============================================================
+   <BlogIndex> — the listing route surface for ASTRO.
+   ------------------------------------------------------------
+   The Astro counterpart of package/blog-index.tsx. Self-contained
+   and source-agnostic: a featured hero + category nav + card grid
+   + pagination, all using the kit's `bk-idx-*` classes (shipped in
+   core/css/index-listing.css), so a site gets a working /blog with
+   no bespoke listing chrome. Byte-identical markup to the Next
+   <BlogIndex>.
+
+   Data comes pre-computed from loadIndex() (in the route's
+   frontmatter), so this template just iterates.
+   ============================================================ */
+import type { IndexData, ResolvedConfig } from "@highjumpdigitalsoftware/blog-kit/astro";
+import {
+  articleHref,
+  categoryHref,
+  listingHref,
+  formatDate,
+  readingLabel,
+} from "@highjumpdigitalsoftware/blog-kit/astro";
+
+interface Props {
+  data: IndexData;
+  config: ResolvedConfig;
+}
+
+const { data, config } = Astro.props;
+const { listing } = config;
+const { featured, items, categories, page, totalPages, categorySlug } = data;
+
+const base = (p: number) =>
+  categorySlug
+    ? categoryHref(listing.listingBasePath, categorySlug, p)
+    : listingHref(listing.listingBasePath, p);
+
+const heading = categorySlug
+  ? categories.find((c) => c.slug === categorySlug)?.label ?? "Articles"
+  : "Latest articles";
+---
+
+<div class="blog-root bk-idx">
+  <header class="bk-idx-head">
+    <p class="bk-idx-eyebrow">{config.brand.name}</p>
+    <h1 class="bk-idx-h1">{heading}</h1>
+  </header>
+
+  {listing.showCategoryNav && categories.length > 0 && (
+    <nav class="bk-idx-nav" aria-label="Categories">
+      <a
+        class={`bk-idx-pill${!categorySlug ? " is-active" : ""}`}
+        href={listingHref(listing.listingBasePath, 1)}
+      >
+        All
+      </a>
+      {categories.map((c) => (
+        <a
+          class={`bk-idx-pill${c.slug === categorySlug ? " is-active" : ""}`}
+          href={categoryHref(listing.listingBasePath, c.slug, 1)}
+        >
+          {c.label} <span class="bk-idx-pill-count">{c.count}</span>
+        </a>
+      ))}
+    </nav>
+  )}
+
+  {featured && (
+    <section class="bk-idx-featured">
+      <a
+        class="bk-idx-card bk-idx-card--featured"
+        href={articleHref(listing.articleBasePath, featured.slug)}
+      >
+        <div
+          class={`bk-idx-thumb${featured.featuredImage ? "" : " bk-idx-thumb--ph"}`}
+          aria-hidden={featured.featuredImage ? undefined : true}
+        >
+          {featured.featuredImage && (
+            <img
+              class="bk-idx-img"
+              src={featured.featuredImage}
+              alt={featured.featuredImageAlt ?? featured.title}
+              loading="lazy"
+            />
+          )}
+        </div>
+        <div class="bk-idx-body">
+          {featured.category && <span class="bk-idx-cat">{featured.category}</span>}
+          <h3 class="bk-idx-title">{featured.title}</h3>
+          <p class="bk-idx-desc">{featured.description}</p>
+          <p class="bk-idx-meta">
+            {formatDate(featured.date, listing.dateLocale)}
+            {featured.readingTime ? ` · ${readingLabel(featured.readingTime)}` : ""}
+          </p>
+        </div>
+      </a>
+    </section>
+  )}
+
+  {items.length > 0 ? (
+    <section class="bk-idx-grid">
+      {items.map((post) => (
+        <a class="bk-idx-card" href={articleHref(listing.articleBasePath, post.slug)}>
+          <div
+            class={`bk-idx-thumb${post.featuredImage ? "" : " bk-idx-thumb--ph"}`}
+            aria-hidden={post.featuredImage ? undefined : true}
+          >
+            {post.featuredImage && (
+              <img
+                class="bk-idx-img"
+                src={post.featuredImage}
+                alt={post.featuredImageAlt ?? post.title}
+                loading="lazy"
+              />
+            )}
+          </div>
+          <div class="bk-idx-body">
+            {post.category && <span class="bk-idx-cat">{post.category}</span>}
+            <h3 class="bk-idx-title">{post.title}</h3>
+            <p class="bk-idx-desc">{post.description}</p>
+            <p class="bk-idx-meta">
+              {formatDate(post.date, listing.dateLocale)}
+              {post.readingTime ? ` · ${readingLabel(post.readingTime)}` : ""}
+            </p>
+          </div>
+        </a>
+      ))}
+    </section>
+  ) : featured ? null : (
+    <p class="bk-idx-empty">No articles yet.</p>
+  )}
+
+  {totalPages > 1 && (
+    <nav class="bk-idx-pager" aria-label="Pagination">
+      {page > 1 && (
+        <a class="bk-idx-pagelink" href={base(page - 1)}>← Newer</a>
+      )}
+      <span class="bk-idx-pageinfo">Page {page} of {totalPages}</span>
+      {page < totalPages && (
+        <a class="bk-idx-pagelink" href={base(page + 1)}>Older →</a>
+      )}
+    </nav>
+  )}
+</div>

package/core/behaviors/code.js

@@ -0,0 +1,78 @@
+/* ============================================================
+   blog-kit — CodeSnippet behaviour
+   Copy-to-clipboard for code blocks. Each block's copy button
+   reads the exact rendered text from .bk-code__code, writes it to
+   the clipboard, and flips its label to "Copied" for 1.5s. Falls
+   back to a hidden textarea + execCommand where the async Clipboard
+   API is unavailable.
+
+   Framework-neutral ESM: exports initCode() (run it after each
+   client navigation) and also self-runs once on load for plain
+   <script> usage. Idempotent: a block is wired at most once.
+   ============================================================ */
+var RESET_MS = 1500;
+
+function writeClipboard(text) {
+  if (navigator.clipboard && navigator.clipboard.writeText) {
+    return navigator.clipboard.writeText(text);
+  }
+  return new Promise(function (resolve, reject) {
+    try {
+      var ta = document.createElement("textarea");
+      ta.value = text;
+      ta.setAttribute("readonly", "");
+      ta.style.position = "absolute";
+      ta.style.left = "-9999px";
+      document.body.appendChild(ta);
+      ta.select();
+      document.execCommand("copy");
+      document.body.removeChild(ta);
+      resolve();
+    } catch (err) {
+      reject(err);
+    }
+  });
+}
+
+function enhance(root) {
+  if (root.getAttribute("data-bk-code") === "ready") return;
+  root.setAttribute("data-bk-code", "ready");
+
+  var btn = root.querySelector("[data-bk-code-copy]");
+  var code = root.querySelector(".bk-code__code");
+  if (!btn || !code) return;
+
+  var labelEl = btn.querySelector(".bk-code__copy-label");
+  var timer = null;
+
+  btn.addEventListener("click", function () {
+    writeClipboard(code.textContent || "").then(
+      function () {
+        if (labelEl) labelEl.textContent = "Copied";
+        btn.setAttribute("data-copied", "true");
+        if (timer) clearTimeout(timer);
+        timer = setTimeout(function () {
+          if (labelEl) labelEl.textContent = "Copy";
+          btn.removeAttribute("data-copied");
+        }, RESET_MS);
+      },
+      function () {
+        /* clipboard unavailable — silently ignore */
+      }
+    );
+  });
+}
+
+export function initCode() {
+  if (typeof document === "undefined") return;
+  var blocks = document.querySelectorAll("[data-bk-code]");
+  for (var i = 0; i < blocks.length; i++) enhance(blocks[i]);
+}
+
+if (typeof document !== "undefined") {
+  if (document.readyState === "loading") {
+    document.addEventListener("DOMContentLoaded", initCode);
+  } else {
+    initCode();
+  }
+}

package/core/behaviors/comparison.js

@@ -0,0 +1,52 @@
+/* ============================================================
+   blog-kit — ComparisonTable behaviour
+   The desktop comparison table can overflow its container on
+   narrow viewports. Native overflow-x scrolls fine but gives no
+   visual cue that more columns exist (the hidden-horizontal-
+   scroll trap). This script toggles edge-fade hint classes on the
+   wrap depending on whether the inner scroller can scroll left or
+   right, updating on scroll and resize.
+
+   Framework-neutral ESM: exports initComparison() (run it after
+   each client navigation) and also self-runs once on load for
+   plain <script> usage. Idempotent: a block is wired at most once.
+   ============================================================ */
+function update(wrap, scroller) {
+  var max = scroller.scrollWidth - scroller.clientWidth;
+  var x = scroller.scrollLeft;
+  var canScroll = max > 1;
+  wrap.classList.toggle("bk-comparison__table-wrap--hint-right", canScroll && x < max - 1);
+  wrap.classList.toggle("bk-comparison__table-wrap--hint-left", canScroll && x > 1);
+}
+
+function enhance(wrap) {
+  if (wrap.getAttribute("data-bk-comparison") === "ready") return;
+  wrap.setAttribute("data-bk-comparison", "ready");
+  var scroller = wrap.querySelector(".bk-comparison__scroll");
+  if (!scroller) return;
+  var sync = function () {
+    update(wrap, scroller);
+  };
+  scroller.addEventListener("scroll", sync, { passive: true });
+  if (typeof window.ResizeObserver === "function") {
+    var ro = new ResizeObserver(sync);
+    ro.observe(scroller);
+  } else {
+    window.addEventListener("resize", sync);
+  }
+  sync();
+}
+
+export function initComparison() {
+  if (typeof document === "undefined") return;
+  var blocks = document.querySelectorAll("[data-bk-comparison]");
+  for (var i = 0; i < blocks.length; i++) enhance(blocks[i]);
+}
+
+if (typeof document !== "undefined") {
+  if (document.readyState === "loading") {
+    document.addEventListener("DOMContentLoaded", initComparison);
+  } else {
+    initComparison();
+  }
+}

package/core/behaviors/delivery-comparison.js

@@ -0,0 +1,52 @@
+/* ============================================================
+   blog-kit — DeliveryComparison behaviour
+   The N-column comparison matrix can overflow its container on
+   narrow viewports. Native overflow-x scrolls fine but gives no
+   visual cue that more columns exist (the hidden-horizontal-scroll
+   trap). This script toggles edge-fade hint classes on the wrap
+   depending on whether the inner scroller can scroll left or right,
+   updating on scroll and resize.
+
+   Framework-neutral ESM: exports initDeliveryComparison() (run it
+   after each client navigation) and also self-runs once on load for
+   plain <script> usage. Idempotent: a block is wired at most once.
+   ============================================================ */
+function update(wrap, scroller) {
+  var max = scroller.scrollWidth - scroller.clientWidth;
+  var x = scroller.scrollLeft;
+  var canScroll = max > 1;
+  wrap.classList.toggle("bk-delivery-comparison--hint-right", canScroll && x < max - 1);
+  wrap.classList.toggle("bk-delivery-comparison--hint-left", canScroll && x > 1);
+}
+
+function enhance(wrap) {
+  if (wrap.getAttribute("data-bk-delivery-comparison") === "ready") return;
+  wrap.setAttribute("data-bk-delivery-comparison", "ready");
+  var scroller = wrap.querySelector(".bk-delivery-comparison__scroll");
+  if (!scroller) return;
+  var sync = function () {
+    update(wrap, scroller);
+  };
+  scroller.addEventListener("scroll", sync, { passive: true });
+  if (typeof window.ResizeObserver === "function") {
+    var ro = new ResizeObserver(sync);
+    ro.observe(scroller);
+  } else {
+    window.addEventListener("resize", sync);
+  }
+  sync();
+}
+
+export function initDeliveryComparison() {
+  if (typeof document === "undefined") return;
+  var blocks = document.querySelectorAll("[data-bk-delivery-comparison]");
+  for (var i = 0; i < blocks.length; i++) enhance(blocks[i]);
+}
+
+if (typeof document !== "undefined") {
+  if (document.readyState === "loading") {
+    document.addEventListener("DOMContentLoaded", initDeliveryComparison);
+  } else {
+    initDeliveryComparison();
+  }
+}

package/core/behaviors/faq.js

@@ -0,0 +1,61 @@
+/* ============================================================
+   blog-kit — FAQList behaviour
+   Native <details> handles open/close on its own. This script's
+   only job is SEO: lift every rendered Q&A pair into FAQPage
+   JSON-LD so search engines can surface it.
+
+   Framework-neutral ESM: exports initFaq() (run it after each
+   client navigation) and also self-runs once on load for plain
+   <script> usage. Idempotent: a block is processed at most once.
+   ============================================================ */
+function clean(s) {
+  return String(s || "").replace(/\s+/g, " ").trim();
+}
+
+function buildSchema(root) {
+  var items = root.querySelectorAll(".bk-faq__item");
+  var entities = [];
+  for (var i = 0; i < items.length; i++) {
+    var q = items[i].querySelector(".bk-faq__question");
+    var a = items[i].querySelector(".bk-faq__answer");
+    var name = clean(q && q.textContent);
+    var text = clean(a && a.textContent);
+    if (!name) continue;
+    entities.push({
+      "@type": "Question",
+      name: name,
+      acceptedAnswer: { "@type": "Answer", text: text },
+    });
+  }
+  if (!entities.length) return null;
+  return {
+    "@context": "https://schema.org",
+    "@type": "FAQPage",
+    mainEntity: entities,
+  };
+}
+
+function enhance(root) {
+  if (root.getAttribute("data-bk-faq") === "ready") return;
+  root.setAttribute("data-bk-faq", "ready");
+  var schema = buildSchema(root);
+  if (!schema) return;
+  var tag = document.createElement("script");
+  tag.type = "application/ld+json";
+  tag.textContent = JSON.stringify(schema);
+  root.appendChild(tag);
+}
+
+export function initFaq() {
+  if (typeof document === "undefined") return;
+  var blocks = document.querySelectorAll("[data-bk-faq]");
+  for (var i = 0; i < blocks.length; i++) enhance(blocks[i]);
+}
+
+if (typeof document !== "undefined") {
+  if (document.readyState === "loading") {
+    document.addEventListener("DOMContentLoaded", initFaq);
+  } else {
+    initFaq();
+  }
+}

package/core/behaviors/index.d.ts

@@ -0,0 +1,3 @@
+/** Ambient types for the vanilla-JS behaviours module (copied verbatim to
+ *  dist by copy-assets.mjs; not compiled by tsc). */
+export function initBlogBehaviors(): void;

package/core/behaviors/index.js

@@ -0,0 +1,35 @@
+/* ============================================================
+   blog-kit — behaviours barrel
+   One entry point that wires every interactive component. Importing
+   this module also self-runs each behaviour once on load (see each
+   file's guarded auto-run), so a plain `<script type="module">` that
+   imports it is enough for a static (Astro) site. For SPA frameworks
+   call initBlogBehaviors() after each client-side navigation so newly
+   mounted markup gets enhanced — each enhance step is idempotent, so
+   re-running is safe and only touches not-yet-wired elements.
+   ============================================================ */
+import { initToc } from "./toc.js";
+import { initFaq } from "./faq.js";
+import { initComparison } from "./comparison.js";
+import { initCode } from "./code.js";
+import { initKeywordTable } from "./keyword-table.js";
+import { initDeliveryComparison } from "./delivery-comparison.js";
+
+export {
+  initToc,
+  initFaq,
+  initComparison,
+  initCode,
+  initKeywordTable,
+  initDeliveryComparison,
+};
+
+/** Run every blog-kit behaviour. Idempotent; safe to call on each navigation. */
+export function initBlogBehaviors() {
+  initToc();
+  initFaq();
+  initComparison();
+  initCode();
+  initKeywordTable();
+  initDeliveryComparison();
+}

package/core/behaviors/keyword-table.js

@@ -0,0 +1,52 @@
+/* ============================================================
+   blog-kit — KeywordTable behaviour
+   A six-column SEO keyword-ranking table overflows its container
+   on narrow viewports. Native overflow-x scrolls fine but gives no
+   visual cue that more columns exist (the hidden-horizontal-scroll
+   trap). This script toggles edge-fade hint classes on the wrap
+   depending on whether the inner scroller can scroll left or right,
+   updating on scroll and resize.
+
+   Framework-neutral ESM: exports initKeywordTable() (run it after
+   each client navigation) and also self-runs once on load for
+   plain <script> usage. Idempotent: a block is wired at most once.
+   ============================================================ */
+function update(wrap, scroller) {
+  var max = scroller.scrollWidth - scroller.clientWidth;
+  var x = scroller.scrollLeft;
+  var canScroll = max > 1;
+  wrap.classList.toggle("bk-keyword-table--hint-right", canScroll && x < max - 1);
+  wrap.classList.toggle("bk-keyword-table--hint-left", canScroll && x > 1);
+}
+
+function enhance(wrap) {
+  if (wrap.getAttribute("data-bk-keyword-table") === "ready") return;
+  wrap.setAttribute("data-bk-keyword-table", "ready");
+  var scroller = wrap.querySelector(".bk-keyword-table__scroll");
+  if (!scroller) return;
+  var sync = function () {
+    update(wrap, scroller);
+  };
+  scroller.addEventListener("scroll", sync, { passive: true });
+  if (typeof window.ResizeObserver === "function") {
+    var ro = new ResizeObserver(sync);
+    ro.observe(scroller);
+  } else {
+    window.addEventListener("resize", sync);
+  }
+  sync();
+}
+
+export function initKeywordTable() {
+  if (typeof document === "undefined") return;
+  var blocks = document.querySelectorAll("[data-bk-keyword-table]");
+  for (var i = 0; i < blocks.length; i++) enhance(blocks[i]);
+}
+
+if (typeof document !== "undefined") {
+  if (document.readyState === "loading") {
+    document.addEventListener("DOMContentLoaded", initKeywordTable);
+  } else {
+    initKeywordTable();
+  }
+}

package/core/behaviors/toc.js

@@ -0,0 +1,130 @@
+/* ============================================================
+   blog-kit — TableOfContents behaviour
+   The TOC is built from the live document, not authored markup:
+   it scans the article for <h2> headings (sub-headings inside MDX
+   components are not document structure and are skipped), renders
+   one numbered entry per heading, smooth-scrolls on click, and
+   runs a scrollspy (IntersectionObserver) that flags the heading
+   currently in view with the --active modifier. If the scope has
+   no <h2>s the container hides itself.
+
+   Scope resolution (centralised so no site has to wrap its body in
+   a particular tag): an explicit data-bk-toc-scope selector wins if
+   it matches; otherwise the TOC scans the prose region that
+   contains it (.bk-prose, then .blog-root), falling back to body.
+
+   Framework-neutral ESM: exports initToc() (run it after each
+   client navigation) and also self-runs once on load for plain
+   <script> usage. Idempotent: a block is wired at most once.
+   ============================================================ */
+function pad2(n) {
+  return n < 10 ? "0" + n : String(n);
+}
+
+function resolveScope(root) {
+  var sel = root.getAttribute("data-bk-toc-scope");
+  if (sel) {
+    var bySel = document.querySelector(sel);
+    if (bySel) return bySel;
+  }
+  return (
+    root.closest(".bk-prose") ||
+    root.closest(".blog-root") ||
+    document.body
+  );
+}
+
+function build(root) {
+  var scope = resolveScope(root);
+  if (!scope) {
+    root.hidden = true;
+    return;
+  }
+
+  // h2 only — sub-headings inside MDX components (h3/h4 from cards,
+  // CTAs, etc.) are not document structure and shouldn't be entries.
+  var headings = scope.querySelectorAll("h2");
+  if (!headings.length) {
+    root.hidden = true;
+    return;
+  }
+  root.hidden = false;
+
+  var list = root.querySelector(".bk-toc__list");
+  if (!list) return;
+  list.textContent = "";
+
+  var links = [];
+  var byId = {};
+
+  Array.prototype.forEach.call(headings, function (el, i) {
+    var id = el.id;
+    var text = el.textContent || "";
+
+    var li = document.createElement("li");
+    li.className = "bk-toc__item";
+
+    var num = document.createElement("span");
+    num.className = "bk-toc__num";
+    num.textContent = pad2(i + 1);
+
+    var a = document.createElement("a");
+    a.className = "bk-toc__link";
+    a.href = id ? "#" + id : "#";
+    a.textContent = text;
+    a.addEventListener("click", function (e) {
+      e.preventDefault();
+      var target = id ? document.getElementById(id) : null;
+      if (target) target.scrollIntoView({ behavior: "smooth" });
+    });
+
+    li.appendChild(num);
+    li.appendChild(a);
+    list.appendChild(li);
+
+    links.push(a);
+    if (id) byId[id] = a;
+  });
+
+  function setActive(id) {
+    for (var i = 0; i < links.length; i++) {
+      links[i].classList.remove("bk-toc__link--active");
+    }
+    var hit = byId[id];
+    if (hit) hit.classList.add("bk-toc__link--active");
+  }
+
+  if (typeof window.IntersectionObserver === "function") {
+    var observer = new IntersectionObserver(
+      function (entries) {
+        for (var i = 0; i < entries.length; i++) {
+          if (entries[i].isIntersecting) setActive(entries[i].target.id);
+        }
+      },
+      { rootMargin: "-80px 0px -60% 0px" }
+    );
+    Array.prototype.forEach.call(headings, function (el) {
+      observer.observe(el);
+    });
+  }
+}
+
+function enhance(root) {
+  if (root.getAttribute("data-bk-toc") === "ready") return;
+  root.setAttribute("data-bk-toc", "ready");
+  build(root);
+}
+
+export function initToc() {
+  if (typeof document === "undefined") return;
+  var blocks = document.querySelectorAll("[data-bk-toc]");
+  for (var i = 0; i < blocks.length; i++) enhance(blocks[i]);
+}
+
+if (typeof document !== "undefined") {
+  if (document.readyState === "loading") {
+    document.addEventListener("DOMContentLoaded", initToc);
+  } else {
+    initToc();
+  }
+}