@highjumpdigitalsoftware/blog-kit 0.6.0

package/core/css/index-listing.css

@@ -0,0 +1,207 @@
+/* ============================================================
+   blog-kit — listing surface (<BlogIndex>) styles.
+   Namespaced bk-idx-*, scoped under .blog-root, driven entirely
+   by --blog-* tokens so the tenant theme recolours it for free.
+   Self-contained so a site gets a working /blog with no bespoke
+   listing chrome.
+   ============================================================ */
+.blog-root.bk-idx {
+  max-width: var(--blog-max-page, 960px);
+  margin: 0 auto;
+  padding: 48px 20px 80px;
+  font-family: var(--blog-font-body);
+  color: var(--blog-text);
+}
+
+.bk-idx-head {
+  margin-bottom: 28px;
+}
+.bk-idx-eyebrow {
+  margin: 0 0 6px;
+  font-size: var(--blog-fs-eyebrow, 0.75rem);
+  letter-spacing: var(--blog-tracking-eyebrow, 0.12em);
+  text-transform: uppercase;
+  font-weight: 700;
+  color: var(--blog-brand-dark, var(--blog-brand));
+}
+.bk-idx-h1 {
+  margin: 0;
+  font-family: var(--blog-font-display);
+  font-size: var(--blog-fs-display-1, 2.5rem);
+  font-weight: var(--blog-heading-weight, 800);
+  text-transform: var(--blog-heading-transform, none);
+  letter-spacing: var(--blog-tracking-tight, -0.01em);
+  color: var(--blog-ink);
+  line-height: 1.05;
+}
+
+/* category nav */
+.bk-idx-nav {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 8px;
+  margin: 0 0 32px;
+}
+.bk-idx-pill {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  padding: 6px 14px;
+  border-radius: var(--blog-radius-pill, 999px);
+  border: 1px solid var(--blog-border);
+  background: var(--blog-paper);
+  color: var(--blog-mute);
+  font-size: 0.85rem;
+  font-weight: 600;
+  text-decoration: none;
+  transition: all 0.15s ease;
+}
+.bk-idx-pill:hover {
+  border-color: var(--blog-brand);
+  color: var(--blog-ink);
+}
+.bk-idx-pill.is-active {
+  background: var(--blog-brand);
+  border-color: var(--blog-brand);
+  color: var(--blog-on-brand, #fff);
+}
+.bk-idx-pill-count {
+  opacity: 0.6;
+  font-variant-numeric: tabular-nums;
+}
+
+/* grid */
+.bk-idx-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(280px, 1fr));
+  gap: 24px;
+}
+.bk-idx-featured {
+  margin-bottom: 32px;
+}
+
+/* cards */
+.bk-idx-card {
+  display: flex;
+  flex-direction: column;
+  border-radius: var(--blog-radius-lg, 16px);
+  overflow: hidden;
+  background: var(--blog-paper);
+  border: 1px solid var(--blog-border);
+  box-shadow: var(--blog-shadow-card, 0 1px 3px rgba(0, 0, 0, 0.06));
+  text-decoration: none;
+  color: inherit;
+  transition: transform 0.18s ease, box-shadow 0.18s ease, border-color 0.18s ease;
+}
+.bk-idx-card:hover {
+  transform: translateY(-3px);
+  box-shadow: var(--blog-shadow-lg, 0 12px 30px rgba(0, 0, 0, 0.12));
+  border-color: var(--blog-brand-soft, var(--blog-brand));
+}
+.bk-idx-card--featured {
+  flex-direction: row;
+  align-items: stretch;
+}
+.bk-idx-card--featured .bk-idx-thumb {
+  flex: 0 0 48%;
+  min-height: 280px;
+}
+.bk-idx-card--featured .bk-idx-title {
+  font-size: var(--blog-fs-h2, 1.6rem);
+}
+
+.bk-idx-thumb {
+  position: relative;
+  aspect-ratio: 16 / 9;
+  overflow: hidden;
+  background: var(--blog-bg-secondary, #f1f3f5);
+}
+.bk-idx-thumb--ph {
+  background: linear-gradient(135deg, var(--blog-brand-tint, #eef) 0%, var(--blog-brand-soft, #dde) 100%);
+}
+.bk-idx-img {
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+  display: block;
+}
+
+.bk-idx-body {
+  padding: 18px 20px 22px;
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+.bk-idx-cat {
+  font-size: 0.72rem;
+  font-weight: 700;
+  letter-spacing: 0.06em;
+  text-transform: uppercase;
+  color: var(--blog-brand-dark, var(--blog-brand));
+}
+.bk-idx-title {
+  margin: 0;
+  font-family: var(--blog-font-display);
+  font-size: var(--blog-fs-h3, 1.25rem);
+  font-weight: 700;
+  line-height: 1.2;
+  color: var(--blog-ink);
+}
+.bk-idx-desc {
+  margin: 0;
+  font-size: 0.95rem;
+  line-height: 1.5;
+  color: var(--blog-mute);
+  display: -webkit-box;
+  -webkit-line-clamp: 3;
+  -webkit-box-orient: vertical;
+  overflow: hidden;
+}
+.bk-idx-meta {
+  margin: 4px 0 0;
+  font-size: 0.8rem;
+  color: var(--blog-faint, var(--blog-mute-2));
+  font-variant-numeric: tabular-nums;
+}
+
+.bk-idx-empty {
+  padding: 60px 0;
+  text-align: center;
+  color: var(--blog-mute);
+}
+
+/* pager */
+.bk-idx-pager {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: 20px;
+  margin-top: 48px;
+}
+.bk-idx-pagelink {
+  padding: 8px 18px;
+  border-radius: var(--blog-radius-pill, 999px);
+  border: 1px solid var(--blog-border);
+  background: var(--blog-paper);
+  color: var(--blog-ink);
+  font-weight: 600;
+  font-size: 0.9rem;
+  text-decoration: none;
+}
+.bk-idx-pagelink:hover {
+  border-color: var(--blog-brand);
+}
+.bk-idx-pageinfo {
+  font-size: 0.85rem;
+  color: var(--blog-mute);
+}
+
+@media (max-width: 640px) {
+  .bk-idx-card--featured {
+    flex-direction: column;
+  }
+  .bk-idx-card--featured .bk-idx-thumb {
+    flex: none;
+    min-height: 0;
+  }
+}

package/core/css/index.css

@@ -0,0 +1,13 @@
+/* ============================================================
+   blog-kit — CSS entrypoint
+   Import this once per site (the /blog route imports it).
+   Order matters: tokens → base → components.
+   A tenant theme is layered AFTER this (it overrides --blog-*
+   tokens on .blog-root) — see the generated theme stylesheet.
+   ============================================================ */
+@import "./tokens.css";
+@import "./base.css";
+@import "./components.css";
+/* Listing surface (<BlogIndex>) — namespaced bk-idx-*, token-driven. Additive:
+   only renders if a site uses the package's <BlogIndex> route. */
+@import "./index-listing.css";

package/core/css/tokens.css

@@ -0,0 +1,127 @@
+/* ============================================================
+   blog-kit — Design Tokens (default theme)
+   ------------------------------------------------------------
+   Every token is declared on the .blog-root wrapper, NOT :root.
+   This is deliberate: it keeps the blog's styling out of the
+   host page entirely, and lets a per-tenant theme re-skin the
+   blog by overriding ONLY these variables on .blog-root.
+
+   A tenant theme (generated from the content repo's theme.json)
+   overrides only the brand + font tokens. Everything structural
+   below stays shared across every site.
+
+   Naming: all tokens are --blog-* to avoid any collision with a
+   host site's own custom properties.
+   ============================================================ */
+
+.blog-root {
+  /* --- Brand (tenant overrides these) --------------------- */
+  --blog-brand: #2563EB;          /* primary accent */
+  --blog-brand-dark: #1D4ED8;     /* hover / pressed */
+  --blog-brand-bright: #3B82F6;   /* lifted accent */
+  --blog-brand-soft: #DBEAFE;     /* soft fill */
+  --blog-brand-tint: #EFF6FF;     /* faint wash / callout bg */
+  --blog-on-brand: #FFFFFF;       /* text on a brand fill */
+
+  /* --- Semantic state colours ----------------------------- */
+  --blog-success: #15803D;
+  --blog-success-bg: #F0FDF4;
+  --blog-warn: #B45309;
+  --blog-warn-bg: #FFFBEB;
+  --blog-danger: #DC2626;
+  --blog-danger-bg: #FEF2F2;
+  --blog-info: #0369A1;
+  --blog-info-bg: #EFF6FF;
+
+  /* --- Text / ink (5-layer ramp) -------------------------- */
+  --blog-ink: #0A0E13;            /* headings / strongest */
+  --blog-text: #1F2937;           /* body */
+  --blog-mute: #4B5563;           /* secondary */
+  --blog-mute-2: #6B7280;         /* captions / labels */
+  --blog-faint: #9CA3AF;          /* faintest meta */
+
+  /* --- Surfaces ------------------------------------------- */
+  --blog-paper: #FFFFFF;          /* main surface */
+  --blog-bg-secondary: #F9FAFB;   /* grouped panels */
+  --blog-bg-tertiary: #F2F5F7;    /* deepest light fill */
+  --blog-dark: #0B0F14;           /* dark panel */
+  --blog-dark-2: #141A21;
+  --blog-dark-3: #1F2730;
+  --blog-on-dark: #F3F4F6;        /* text on a dark panel */
+  --blog-on-dark-mute: rgba(255, 255, 255, 0.62);
+
+  /* --- Borders -------------------------------------------- */
+  --blog-border: #D7DBE0;
+  --blog-border-light: #E4E7EA;
+  --blog-border-subtle: #EEF1F4;
+  --blog-border-dark: rgba(255, 255, 255, 0.12);
+
+  /* --- Shadows (tokenised — never inline a box-shadow) ----- */
+  --blog-shadow-sm: 0 1px 2px rgba(10, 14, 19, 0.06);
+  --blog-shadow-md: 0 4px 12px rgba(10, 14, 19, 0.08);
+  --blog-shadow-lg: 0 12px 32px rgba(10, 14, 19, 0.12);
+  --blog-shadow-card: 0 1px 3px rgba(10, 14, 19, 0.08), 0 1px 2px rgba(10, 14, 19, 0.04);
+  /* resolves the using component's local --_accent (falls back to brand) */
+  --blog-shadow-verdict: 0 5px 30px color-mix(in srgb, var(--_accent, var(--blog-brand)) 15%, transparent);
+  --blog-shadow-ring: 0 0 0 1px var(--blog-brand);          /* 1px brand outline (e.g. timeline dot) */
+  --blog-shadow-focus-ring: 0 0 0 2px color-mix(in srgb, var(--blog-brand) 40%, transparent);
+
+  /* --- Radii ---------------------------------------------- */
+  --blog-radius-xs: 4px;
+  --blog-radius-sm: 8px;
+  --blog-radius-md: 12px;
+  --blog-radius-lg: 16px;
+  --blog-radius-xl: 20px;
+  --blog-radius-2xl: 24px;
+  --blog-radius-pill: 999px;
+
+  /* --- Spacing scale -------------------------------------- */
+  --blog-sp-1: 0.25rem;
+  --blog-sp-2: 0.5rem;
+  --blog-sp-3: 0.75rem;
+  --blog-sp-4: 1rem;
+  --blog-sp-5: 1.25rem;
+  --blog-sp-6: 1.5rem;
+  --blog-sp-7: 1.75rem;
+  --blog-sp-8: 2rem;
+  --blog-sp-10: 2.5rem;
+  --blog-sp-12: 3rem;
+  --blog-sp-16: 4rem;
+
+  /* --- Typography (tenant overrides the families) --------- */
+  --blog-font-display: "Inter", system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
+  --blog-font-body: "Inter", system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
+  --blog-font-mono: ui-monospace, "SF Mono", Menlo, Monaco, "Cascadia Code", monospace;
+  --blog-tracking-tight: -0.01em;
+  --blog-tracking-wide: 0.04em;
+  --blog-tracking-eyebrow: 0.08em;
+  --blog-heading-transform: none;   /* tenants can set uppercase */
+  --blog-heading-weight: 700;
+
+  /* --- Type scale ----------------------------------------------
+     One canonical ramp every component points at, so the same role
+     (eyebrow, body, caption, display number) is the same size kit-
+     wide. Reconciled from the kit's prevailing sizes; all rem on a
+     16px base. Components must not hardcode font-size — use these. */
+  --blog-fs-eyebrow-sm: 0.625rem;   /* 10px — tiny kickers / badges / pill labels */
+  --blog-fs-eyebrow: 0.6875rem;     /* 11px — standard uppercase eyebrow */
+  --blog-fs-xs: 0.75rem;            /* 12px — counters, mono meta, small labels */
+  --blog-fs-sm: 0.8125rem;          /* 13px — captions, secondary body */
+  --blog-fs-base: 0.875rem;         /* 14px — default body */
+  --blog-fs-md: 0.9375rem;          /* 15px — comfortable body */
+  --blog-fs-lg: 1rem;               /* 16px — large body / strong labels */
+  --blog-fs-xl: 1.125rem;           /* 18px — lead / sub-headings */
+  --blog-fs-2xl: 1.375rem;          /* 22px */
+  --blog-fs-3xl: 1.625rem;          /* 26px */
+  --blog-fs-4xl: 1.75rem;           /* 28px */
+  --blog-fs-5xl: 2rem;              /* 32px */
+  --blog-fs-6xl: 2.25rem;           /* 36px */
+  --blog-fs-7xl: 2.75rem;           /* 44px — large metric numbers */
+  --blog-fs-8xl: 3.5rem;            /* 56px — largest stepped metric number */
+  --blog-fs-display: clamp(56px, 14vw, 130px);   /* metric hero value */
+  --blog-fs-display-2: clamp(80px, 11vw, 150px); /* KeyMetric headline number */
+
+  /* --- Layout --------------------------------------------- */
+  --blog-max-content: 720px;        /* article body measure */
+  --blog-max-page: 960px;           /* full breakout width */
+}

package/core/icons.ts

@@ -0,0 +1,20 @@
+/* ============================================================
+   blog-kit — shared inline SVG icons
+   Framework-neutral raw SVG strings. React renders them via
+   dangerouslySetInnerHTML; Astro via set:html. Defining them
+   once here keeps the two adapters byte-identical.
+   1.75px stroke, currentColor, 24px viewbox.
+   ============================================================ */
+
+export const ICONS: Record<string, string> = {
+  info: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="10"/><path d="M12 16v-4"/><path d="M12 8h.01"/></svg>',
+  tip: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round"><path d="M15 14c.2-1 .7-1.7 1.5-2.5 1-.9 1.5-2.2 1.5-3.5A6 6 0 0 0 6 8c0 1.3.5 2.6 1.5 3.5.8.8 1.3 1.5 1.5 2.5"/><path d="M9 18h6"/><path d="M10 22h4"/></svg>',
+  success: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round"><path d="M22 11.08V12a10 10 0 1 1-5.93-9.14"/><path d="m9 11 3 3L22 4"/></svg>',
+  warn: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round"><path d="m21.73 18-8-14a2 2 0 0 0-3.48 0l-8 14A2 2 0 0 0 4 21h16a2 2 0 0 0 1.73-3"/><path d="M12 9v4"/><path d="M12 17h.01"/></svg>',
+  danger: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="10"/><path d="M12 8v4"/><path d="M12 16h.01"/></svg>',
+  external: '<svg viewBox="0 0 12 12" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M4 2h6v6"/><path d="M10 2 3 9"/></svg>',
+  "check-tick": '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="3" stroke-linecap="round" stroke-linejoin="round"><polyline points="6 13 10 17 18 7"/></svg>',
+  copy: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round"><rect x="9" y="9" width="13" height="13" rx="2"/><path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"/></svg>',
+  arrowRight: '<svg viewBox="0 0 18 16" fill="none"><path d="M9.34 15.71L15.15 9.04H0.77V7.62H15.17L9.34 0.95H11.19L17.79 8.32L11.19 15.71H9.34Z" fill="currentColor"/></svg>',
+  "search": '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round"><circle cx="11" cy="11" r="7"/><path d="M21 21l-4.35-4.35"/></svg>',
+};

package/core/lib.ts

@@ -0,0 +1,70 @@
+/* ============================================================
+   blog-kit — shared component logic
+   Framework-neutral helpers reused by both the React and Astro
+   adapters so prop-handling never diverges between frameworks.
+   ============================================================ */
+
+export type CalloutTone = "info" | "tip" | "success" | "warn" | "danger";
+
+const CALLOUT_TONE_ALIASES: Record<string, CalloutTone> = {
+  info: "info",
+  note: "info",
+  default: "info",
+  tip: "tip",
+  idea: "tip",
+  success: "success",
+  ok: "success",
+  positive: "success",
+  warn: "warn",
+  warning: "warn",
+  caution: "warn",
+  danger: "danger",
+  error: "danger",
+  important: "danger",
+  alert: "danger",
+};
+
+/**
+ * Normalise the callout tone from any of the accepted prop names.
+ * hjd authored `type`, capture authored `variant`; canonical is `tone`.
+ * Falls back to "info" for anything unrecognised.
+ */
+export function resolveCalloutTone(input?: string): CalloutTone {
+  if (!input) return "info";
+  return CALLOUT_TONE_ALIASES[input.toLowerCase().trim()] ?? "info";
+}
+
+export const CALLOUT_DEFAULT_TITLE: Record<CalloutTone, string> = {
+  info: "Note",
+  tip: "Tip",
+  success: "Success",
+  warn: "Warning",
+  danger: "Important",
+};
+
+/** Tiny classnames joiner (skips falsy). */
+export function cx(...parts: Array<string | false | null | undefined>): string {
+  return parts.filter(Boolean).join(" ");
+}
+
+// ── AuthorCard helpers ───────────────────────────────────────────────────────
+
+/** A labelled link shown in an AuthorCard (e.g. profile / site). */
+export interface AuthorLink {
+  label: string;
+  href: string;
+}
+
+/**
+ * Derive up-to-two-letter initials from an author name for the avatar
+ * fallback. "Jane Doe" → "JD"; "capture ai" → "CA"; "" → "".
+ */
+export function authorInitials(name: string): string {
+  return (name || "")
+    .trim()
+    .split(/\s+/)
+    .filter(Boolean)
+    .slice(0, 2)
+    .map((w) => w[0]!.toUpperCase())
+    .join("");
+}