@highjumpdigitalsoftware/blog-kit 0.6.0

package/react/CaseStudyHero.tsx

@@ -0,0 +1,71 @@
+/* blog-kit React adapter — CaseStudyHero
+   Thin wrapper: all styling lives in core/css/components.css (.bk-case-study-hero).
+   A dark case-study banner: a white logo plate (client logo image, an
+   HTML/text wordmark, or the auto-broken client name), then a body with
+   uppercase chips, a headline, a sub-line, and a row of brand-coloured
+   result tiles (big number + uppercase label). */
+
+export interface CaseStudyResult {
+  num: string;
+  label: string;
+}
+
+export interface CaseStudyHeroProps {
+  /** Client logo URL — preferred plate content. */
+  logoImage?: string;
+  /** HTML/text wordmark (supports <br/>) — used when no logoImage. */
+  logo?: string;
+  /** Client name — auto-broken at spaces as a last-resort plate. */
+  client?: string;
+  /** Uppercase tag chips shown above the headline. */
+  chips?: string[];
+  title?: string;
+  sub?: string;
+  /** Result tiles — each a big number + uppercase label. */
+  results?: CaseStudyResult[];
+}
+
+export function CaseStudyHero({
+  logoImage,
+  logo,
+  client,
+  chips = [],
+  title,
+  sub,
+  results = [],
+}: CaseStudyHeroProps) {
+  return (
+    <div className="bk-case-study-hero">
+      <div className="bk-case-study-hero__logo">
+        {logoImage ? (
+          <img src={logoImage} alt={client ? `${client} logo` : "Client logo"} />
+        ) : (
+          <strong
+            dangerouslySetInnerHTML={{
+              __html: logo || client?.replace(/ /g, "<br/>") || "",
+            }}
+          />
+        )}
+      </div>
+      <div className="bk-case-study-hero__body">
+        <div className="bk-case-study-hero__chips">
+          {chips.map((c) => (
+            <span key={c} className="bk-case-study-hero__chip">
+              {c}
+            </span>
+          ))}
+        </div>
+        <h2 className="bk-case-study-hero__heading">{title}</h2>
+        <p className="bk-case-study-hero__sub">{sub}</p>
+        <div className="bk-case-study-hero__results">
+          {results.map((r, i) => (
+            <div key={i} className="bk-case-study-hero__result">
+              <div className="bk-case-study-hero__result-num">{r.num}</div>
+              <div className="bk-case-study-hero__result-label">{r.label}</div>
+            </div>
+          ))}
+        </div>
+      </div>
+    </div>
+  );
+}

package/react/ChannelMixBars.tsx

@@ -0,0 +1,50 @@
+/* blog-kit React adapter — ChannelMixBars
+   Thin wrapper: all styling lives in core/css/components.css (.bk-channel-mix).
+   A horizontal bar breakdown of a metric across channels — an uppercase
+   heading + optional total, then one labelled row per channel with a
+   proportional fill (width = value / max) and a right-aligned value.
+   The first row uses the brand fill; subsequent rows step through a
+   neutral colour ramp. Ported from hjd-website's blog ChannelMixBars. */
+
+export interface ChannelMixRow {
+  /** Channel name (rendered uppercase as the row label). */
+  name: string;
+  /** Numeric magnitude used to compute the bar width. */
+  value: number;
+  /** Optional pre-formatted value shown on the right (falls back to value). */
+  display?: string;
+}
+
+export interface ChannelMixBarsProps {
+  /** One entry per channel. Renders nothing meaningful if empty. */
+  rows?: ChannelMixRow[];
+  /** Optional total, shown in the header after "Total · ". */
+  total?: string;
+  /** Optional header label (defaults to "Channel split"). */
+  period?: string;
+}
+
+export function ChannelMixBars({ rows = [], total, period }: ChannelMixBarsProps) {
+  const max = Math.max(...rows.map((r) => Number(r.value) || 0), 1);
+
+  return (
+    <div className="bk-channel-mix">
+      <div className="bk-channel-mix__head">
+        <div className="bk-channel-mix__title">{period || "Channel split"}</div>
+        {total && <div className="bk-channel-mix__total">Total · {total}</div>}
+      </div>
+      {rows.map((r, i) => (
+        <div key={i} className="bk-channel-mix__row">
+          <div className="bk-channel-mix__name">{r.name}</div>
+          <div className="bk-channel-mix__bar">
+            <div
+              className={`bk-channel-mix__fill${i > 0 ? ` bk-channel-mix__fill--${Math.min(i + 1, 5)}` : ""}`}
+              style={{ width: `${(Number(r.value) / max) * 100}%` }}
+            />
+          </div>
+          <div className="bk-channel-mix__val">{r.display || r.value}</div>
+        </div>
+      ))}
+    </div>
+  );
+}

package/react/Checklist.tsx

@@ -0,0 +1,31 @@
+export interface ChecklistEntry {
+  title: string;
+  sub?: string;
+  done?: boolean;
+}
+
+export interface ChecklistProps {
+  items: ChecklistEntry[];
+}
+
+export function Checklist({ items }: ChecklistProps) {
+  if (!items || items.length === 0) return null;
+  return (
+    <ul className="bk-checklist">
+      {items.map((it, i) => (
+        <li
+          key={i}
+          className={`bk-checklist__item${it.done ? " bk-checklist__item--done" : ""}`}
+        >
+          <span className="bk-checklist__box" aria-hidden="true">
+            {it.done ? "✓" : ""}
+          </span>
+          <span className="bk-checklist__text">
+            <span className="bk-checklist__title">{it.title}</span>
+            {it.sub && <span className="bk-checklist__sub">{it.sub}</span>}
+          </span>
+        </li>
+      ))}
+    </ul>
+  );
+}

package/react/ChecklistItem.tsx

@@ -0,0 +1,19 @@
+export interface ChecklistItemProps {
+  checked: boolean;
+  label: string;
+  description?: string;
+}
+
+export function ChecklistItem({ checked, label, description }: ChecklistItemProps) {
+  return (
+    <div className={`bk-checklist-item${checked ? " bk-checklist-item--checked" : ""}`}>
+      <span className="bk-checklist-item__box" aria-hidden={!checked}>
+        {checked ? "✓" : ""}
+      </span>
+      <span className="bk-checklist-item__text">
+        <span className="bk-checklist-item__label">{label}</span>
+        {description && <span className="bk-checklist-item__desc">{description}</span>}
+      </span>
+    </div>
+  );
+}

package/react/CodeSnippet.tsx

@@ -0,0 +1,36 @@
+import { ICONS } from "../core/icons";
+
+export interface CodeSnippetProps {
+  /** The raw code to display and copy. */
+  code: string;
+  /** Language hint, used for the label and the `language-*` class. */
+  language?: string;
+  /** Optional filename shown in the header instead of the language. */
+  filename?: string;
+}
+
+/**
+ * A dark, framework-agnostic code block with a header bar and a
+ * copy-to-clipboard button. The copy interaction is handled by the
+ * shared vanilla-JS behaviour, which attaches via the [data-bk-code]
+ * hook on load — no framework state. The raw source is carried in a
+ * hidden <template> so the script can copy the exact text.
+ */
+export function CodeSnippet({ code, language = "text", filename }: CodeSnippetProps) {
+  const label = filename || (language !== "text" ? language : "code");
+
+  return (
+    <div className="bk-code" data-bk-code>
+      <div className="bk-code__bar">
+        <span className="bk-code__label">{label}</span>
+        <button type="button" className="bk-code__copy" data-bk-code-copy>
+          <span className="bk-code__copy-icon" dangerouslySetInnerHTML={{ __html: ICONS.copy }} />
+          <span className="bk-code__copy-label">Copy</span>
+        </button>
+      </div>
+      <pre className="bk-code__pre">
+        <code className={`bk-code__code language-${language}`}>{code}</code>
+      </pre>
+    </div>
+  );
+}

package/react/ComparisonTable.tsx

@@ -0,0 +1,114 @@
+export interface ComparisonItem {
+  feature: string;
+  optionA: string;
+  optionB: string;
+  /** Which column wins this row, if any. */
+  winner?: "a" | "b" | "tie";
+}
+
+export interface ComparisonTableProps {
+  /** Optional heading rendered above the table. */
+  title?: string;
+  optionALabel: string;
+  optionBLabel: string;
+  items?: ComparisonItem[];
+}
+
+const TICK = "✓";
+const CROSS = "✕";
+
+type Cell = { kind: "yes" | "no" | "text"; text: string };
+
+/** Normalise a cell value: tick/"yes" and cross/"no" become glyph marks. */
+function resolveCell(text: string): Cell {
+  const v = String(text ?? "").trim();
+  const lower = v.toLowerCase();
+  if (v === TICK || lower === "yes") return { kind: "yes", text: TICK };
+  if (v === CROSS || lower === "no") return { kind: "no", text: CROSS };
+  return { kind: "text", text: v };
+}
+
+/**
+ * Side-by-side comparison of two options across a set of features.
+ * Renders twice: stacked cards on mobile (avoids the hidden-horizontal-
+ * scroll trap) and a table on tablet/desktop. The behaviour script adds a
+ * scroll-edge hint to the table when it overflows its container.
+ */
+export function ComparisonTable({
+  title,
+  optionALabel,
+  optionBLabel,
+  items = [],
+}: ComparisonTableProps) {
+  if (!items || items.length === 0) return null;
+
+  return (
+    <div className="bk-comparison">
+      {title && <h3 className="bk-comparison__title">{title}</h3>}
+
+      <div className="bk-comparison__cards">
+        {items.map((item, i) => (
+          <div className="bk-comparison__card" key={i}>
+            <div className="bk-comparison__card-feature">{item.feature}</div>
+            <div
+              className={`bk-comparison__card-row${item.winner === "a" ? " bk-comparison__card-row--best" : ""}`}
+            >
+              <span className="bk-comparison__card-label">{optionALabel}</span>
+              <ComparisonValue text={item.optionA} best={item.winner === "a"} />
+            </div>
+            <div
+              className={`bk-comparison__card-row${item.winner === "b" ? " bk-comparison__card-row--best" : ""}`}
+            >
+              <span className="bk-comparison__card-label">{optionBLabel}</span>
+              <ComparisonValue text={item.optionB} best={item.winner === "b"} />
+            </div>
+          </div>
+        ))}
+      </div>
+
+      <div className="bk-comparison__table-wrap" data-bk-comparison>
+        <div className="bk-comparison__scroll">
+          <table className="bk-comparison__table">
+            <thead>
+              <tr>
+                <th className="bk-comparison__th">Feature</th>
+                <th className="bk-comparison__th">{optionALabel}</th>
+                <th className="bk-comparison__th">{optionBLabel}</th>
+              </tr>
+            </thead>
+            <tbody>
+              {items.map((item, i) => (
+                <tr className="bk-comparison__tr" key={i}>
+                  <td className="bk-comparison__td bk-comparison__td--feature">
+                    {item.feature}
+                  </td>
+                  <td
+                    className={`bk-comparison__td${item.winner === "a" ? " bk-comparison__td--best" : ""}`}
+                  >
+                    <ComparisonValue text={item.optionA} best={item.winner === "a"} />
+                  </td>
+                  <td
+                    className={`bk-comparison__td${item.winner === "b" ? " bk-comparison__td--best" : ""}`}
+                  >
+                    <ComparisonValue text={item.optionB} best={item.winner === "b"} />
+                  </td>
+                </tr>
+              ))}
+            </tbody>
+          </table>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+function ComparisonValue({ text, best }: { text: string; best?: boolean }) {
+  const cell = resolveCell(text);
+  if (cell.kind === "yes") {
+    return <span className="bk-comparison__mark bk-comparison__mark--yes">{cell.text}</span>;
+  }
+  if (cell.kind === "no") {
+    return <span className="bk-comparison__mark bk-comparison__mark--no">{cell.text}</span>;
+  }
+  return <span className={best ? "bk-comparison__value--best" : undefined}>{cell.text}</span>;
+}

package/react/Definition.tsx

@@ -0,0 +1,36 @@
+import type { ReactNode } from "react";
+
+export interface DefinitionProps {
+  term: string;
+  name?: string;
+  pronunciation?: string;
+  children?: ReactNode;
+}
+
+export function Definition({ term, name, pronunciation, children }: DefinitionProps) {
+  // `term` is meant to be a 2-3 char monogram. If an author passes a full
+  // phrase, derive initials so the tile doesn't overflow.
+  const rawTerm = String(term ?? "").trim();
+  const looksLikePhrase = rawTerm.length > 4 || /\s|-/.test(rawTerm);
+  const monogram = looksLikePhrase
+    ? rawTerm
+        .split(/[\s-]+/)
+        .map((w) => w[0])
+        .filter(Boolean)
+        .join("")
+        .slice(0, 3)
+        .toUpperCase()
+    : rawTerm.toUpperCase();
+  const resolvedName = name ?? (looksLikePhrase ? rawTerm : undefined);
+
+  return (
+    <div className="bk-definition">
+      <div className="bk-definition__monogram" aria-hidden="true">{monogram}</div>
+      <div className="bk-definition__content">
+        {resolvedName && <p className="bk-definition__name">{resolvedName}</p>}
+        {pronunciation && <p className="bk-definition__pronunciation">{pronunciation}</p>}
+        <p className="bk-definition__body">{children}</p>
+      </div>
+    </div>
+  );
+}

package/react/DeliveryComparison.tsx

@@ -0,0 +1,62 @@
+/* blog-kit React adapter — DeliveryComparison
+   Thin wrapper: all styling lives in core/css/components.css (.bk-delivery-comparison).
+   A flexible N-column comparison matrix — a header row of column labels (the
+   first header cell is intentionally blank, sitting above the row-label column),
+   then one row per criterion: a bold row label with optional sub-text, followed
+   by one cell per column. Overflows horizontally on narrow viewports; the
+   [data-bk-delivery-comparison] behaviour adds scroll-edge hints. Ported from
+   hjd-website's blog DeliveryComparison. */
+
+export interface DeliveryComparisonRow {
+  /** Bold row label (the left-hand criterion name). */
+  label: string;
+  /** Optional secondary line shown under the label. */
+  sub?: string;
+  /** One value per column, in the same order as `columns`. */
+  values: string[];
+}
+
+export interface DeliveryComparisonProps {
+  /** Column headers. The matrix renders a blank header above the label column. */
+  columns?: string[];
+  /** One entry per criterion row. Renders nothing if empty. */
+  rows?: DeliveryComparisonRow[];
+}
+
+export function DeliveryComparison({ columns = [], rows = [] }: DeliveryComparisonProps) {
+  if (!rows || rows.length === 0) return null;
+
+  return (
+    <div className="bk-delivery-comparison" data-bk-delivery-comparison>
+      <div className="bk-delivery-comparison__scroll">
+        <table className="bk-delivery-comparison__table">
+          <thead>
+            <tr>
+              <th className="bk-delivery-comparison__th" />
+              {columns.map((c, i) => (
+                <th className="bk-delivery-comparison__th" key={i}>
+                  {c}
+                </th>
+              ))}
+            </tr>
+          </thead>
+          <tbody>
+            {rows.map((r, i) => (
+              <tr className="bk-delivery-comparison__tr" key={i}>
+                <td className="bk-delivery-comparison__td bk-delivery-comparison__td--label">
+                  <strong className="bk-delivery-comparison__label">{r.label}</strong>
+                  {r.sub}
+                </td>
+                {r.values.map((v, j) => (
+                  <td className="bk-delivery-comparison__td" key={j}>
+                    {v}
+                  </td>
+                ))}
+              </tr>
+            ))}
+          </tbody>
+        </table>
+      </div>
+    </div>
+  );
+}

package/react/FAQList.tsx

@@ -0,0 +1,61 @@
+import type { ReactNode } from "react";
+
+export interface FAQItem {
+  q: string;
+  /** Body text. Split into paragraphs on blank lines. Inline HTML is rendered. */
+  a: string;
+}
+
+export interface FAQListProps {
+  /** Q&A pairs. Optional — children may carry the body instead (MDX). */
+  items?: FAQItem[];
+  /** Optional heading rendered above the list. */
+  heading?: string;
+  children?: ReactNode;
+}
+
+/** Split an answer body into paragraphs on blank lines. */
+function toParagraphs(a: string): string[] {
+  return String(a ?? "")
+    .split(/\n{2,}/)
+    .filter(Boolean);
+}
+
+/**
+ * Expandable Q&A list built on native <details> for accessibility and SEO.
+ * The first item is open by default to signal interaction. The behaviour
+ * script lifts every rendered Q&A pair into FAQPage JSON-LD on load.
+ */
+export function FAQList({ items, heading, children }: FAQListProps) {
+  const list = items ?? [];
+
+  return (
+    <div className="bk-faq" data-bk-faq>
+      {heading && <p className="bk-faq__heading">{heading}</p>}
+      <div className="bk-faq__list">
+        {list.length > 0
+          ? list.map((it, i) => (
+              <details className="bk-faq__item" key={i} open={i === 0}>
+                <summary className="bk-faq__summary">
+                  <span className="bk-faq__question">{it.q}</span>
+                  <span className="bk-faq__toggle" aria-hidden="true">
+                    <span className="bk-faq__bar bk-faq__bar--h" />
+                    <span className="bk-faq__bar bk-faq__bar--v" />
+                  </span>
+                </summary>
+                <div className="bk-faq__answer">
+                  {toParagraphs(it.a).map((p, j) => (
+                    <p
+                      className="bk-faq__para"
+                      key={j}
+                      dangerouslySetInnerHTML={{ __html: p }}
+                    />
+                  ))}
+                </div>
+              </details>
+            ))
+          : children}
+      </div>
+    </div>
+  );
+}

package/react/FurtherReading.tsx

@@ -0,0 +1,46 @@
+export interface FurtherReadingSource {
+  /** Display title of the linked resource. */
+  title: string;
+  /** Short source/publisher label shown on the right. */
+  source: string;
+  /** Destination URL (opens in a new tab, rel=nofollow). */
+  url: string;
+}
+
+export interface FurtherReadingProps {
+  /** List of external resources. Renders nothing when empty. */
+  sources?: FurtherReadingSource[];
+  /** Optional heading override (default "Further reading"). */
+  heading?: string;
+}
+
+/**
+ * Card listing external resources for further reading. Each row is a
+ * title linking out (new tab, nofollow) with a source label on the right.
+ * Rows are dashed-separated; the last row has no separator.
+ */
+export function FurtherReading({ sources, heading }: FurtherReadingProps) {
+  const list = sources ?? [];
+  if (list.length === 0) return null;
+
+  return (
+    <div className="bk-further-reading">
+      <p className="bk-further-reading__title">{heading ?? "Further reading"}</p>
+      <ul className="bk-further-reading__list">
+        {list.map((s, i) => (
+          <li className="bk-further-reading__item" key={i}>
+            <a
+              className="bk-further-reading__link"
+              href={s.url}
+              target="_blank"
+              rel="nofollow noopener noreferrer"
+            >
+              {s.title}
+            </a>
+            <span className="bk-further-reading__source">{s.source}</span>
+          </li>
+        ))}
+      </ul>
+    </div>
+  );
+}

package/react/ImageFeature.tsx

@@ -0,0 +1,26 @@
+/* blog-kit React adapter — ImageFeature
+   Thin wrapper: all styling lives in core/css/components.css (.bk-image-feature).
+   Framework-neutral <img> (no next/image) so React + Astro emit identical markup. */
+export interface ImageFeatureProps {
+  src: string;
+  alt: string;
+  caption?: string;
+  credit?: string;
+  position?: "left" | "right" | "full";
+}
+export function ImageFeature({ src, alt, caption, credit, position = "full" }: ImageFeatureProps) {
+  const pos = position === "left" || position === "right" ? position : "full";
+  return (
+    <figure className={`bk-image-feature bk-image-feature--${pos}`}>
+      <div className="bk-image-feature__frame">
+        <img className="bk-image-feature__img" src={src} alt={alt} loading="lazy" decoding="async" />
+      </div>
+      {(caption || credit) && (
+        <figcaption className="bk-image-feature__caption">
+          {caption && <span className="bk-image-feature__text">{caption}</span>}
+          {credit && <span className="bk-image-feature__credit">{credit}</span>}
+        </figcaption>
+      )}
+    </figure>
+  );
+}

package/react/Infographic.tsx

@@ -0,0 +1,18 @@
+/* blog-kit React adapter — Infographic
+   AI-generated, brand-locked infographic image. Frameless and borderless on
+   purpose: the image is the whole point and every pixel carries information.
+   Renders at the image's natural aspect ratio (full width, auto height) so
+   nothing gets cropped. Framework-neutral <img> (no next/image) so React +
+   Astro emit identical markup. All styling lives in .bk-infographic. */
+export interface InfographicProps {
+  src: string;
+  alt: string;
+}
+export function Infographic({ src, alt }: InfographicProps) {
+  if (!src) return null;
+  return (
+    <figure className="bk-infographic">
+      <img className="bk-infographic__img" src={src} alt={alt} loading="lazy" decoding="async" />
+    </figure>
+  );
+}

package/react/KeyMetric.tsx

@@ -0,0 +1,61 @@
+/* blog-kit React adapter — KeyMetric
+   Thin wrapper: all styling lives in core/css/components.css (.bk-key-metric).
+   A dark, full-width hero metric panel: one oversized brand-coloured number on
+   the left, and a copy column on the right (optional uppercase label, an
+   optional rich-text title that accepts inline HTML, an optional sub-line, and
+   an optional dashed-divider "SOURCE" attribution row that links out when a URL
+   is given). Ported from hjd's blog KeyMetric (+ inlined _StatSourceRow);
+   cyan/dark mapped to neutral tokens. */
+import { ICONS } from "../core/icons";
+
+export interface KeyMetricProps {
+  /** The oversized headline figure, e.g. "3.2×" or "87%". */
+  number: string;
+  /** Short uppercase caption above the title. */
+  label?: string;
+  /** Rich-text headline; accepts inline HTML (rendered as markup). */
+  title?: string;
+  /** Supporting line under the title. */
+  sub?: string;
+  /** Optional source attribution, shown below in a dashed-divider row. */
+  source?: string;
+  /** Optional URL — when set alongside `source`, the row becomes a link. */
+  sourceUrl?: string;
+}
+
+export function KeyMetric({ number, label, title, sub, source, sourceUrl }: KeyMetricProps) {
+  return (
+    <div className="bk-key-metric">
+      <div className="bk-key-metric__num">{number}</div>
+      <div className="bk-key-metric__copy">
+        {label && <div className="bk-key-metric__label">{label}</div>}
+        {title && (
+          <p className="bk-key-metric__title" dangerouslySetInnerHTML={{ __html: title }} />
+        )}
+        {sub && <p className="bk-key-metric__sub">{sub}</p>}
+        {source &&
+          (sourceUrl ? (
+            <a
+              className="bk-key-metric__source bk-key-metric__source--link"
+              href={sourceUrl}
+              target="_blank"
+              rel="nofollow noopener noreferrer"
+            >
+              <span className="bk-key-metric__source-kicker">Source</span>
+              {source}
+              <span
+                className="bk-key-metric__source-icon"
+                aria-hidden="true"
+                dangerouslySetInnerHTML={{ __html: ICONS["external"] }}
+              />
+            </a>
+          ) : (
+            <div className="bk-key-metric__source">
+              <span className="bk-key-metric__source-kicker">Source</span>
+              {source}
+            </div>
+          ))}
+      </div>
+    </div>
+  );
+}