ferst-core 0.1.0

package/styles/theme.css

@@ -0,0 +1,90 @@
+/* Theme tokens — the single home for every colour, surface, and breakpoint
+   width the rest of the core references via `var(--…)`. Lifted out of
+   `Base.astro` so the chrome components (`SiteHeader`, `SiteFooter`,
+   `CookiePreferences`) and any future "modify page elements" feature can
+   read the same palette without touching the layout file.
+
+   These are the core's NEUTRAL DEFAULTS — a deliberately unbranded slate +
+   indigo set. Every client overrides the ones it cares about via the
+   `themeSettings` collection (Base.astro emits those as a higher-specificity
+   <style> in the document head), so brand colours live in the client's repo,
+   never here. That's why the accent tokens keep their historic names
+   (`--gold`, `--brown`, `--gold-light`) even though the default values are no
+   longer gold: renaming them would churn ~60 call-sites across the chrome for
+   no functional gain, and clients set them by name regardless. Roles:
+     --gold        interactive accent (links hover, buttons, focus, active)
+     --accent      dark readable text accent (nav/footer link text)
+     --brown       secondary muted text
+     --gold-light  soft accent background (callouts, gradients)
+     --dark-bg     dark-mode chrome background (header/footer/nav)
+
+   Breakpoints are em-based (MDN-recommended); duplicated as literals inside
+   @media rules elsewhere because media queries can't reference custom
+   properties. Read them in JS via getComputedStyle if you ever need the
+   numeric value at runtime. */
+
+:root {
+  --bp-tablet: 48em;   /* 768px @ default 16px root */
+  --bp-desktop: 64em;  /* 1024px @ default 16px root */
+
+  --fg: #1F2937;
+  --muted: #4B5563;
+  --accent: #334155;
+  --bg: #F1F5F9;
+  --bg-surface: #FFFFFF;
+  --bg-section: #E2E8F0;
+  --bg-tag: #E2E8F0;
+  --border: #CBD5E1;
+  --max: 72ch;
+  --dark-bg: #0F172A;
+  --gold: #4F46E5;
+  --gold-light: #E0E7FF;
+  --brown: #4B5563;
+  --text-light: #FFFFFF;
+  --text-footer: #4B5563;
+  --text-footer-link: #4F46E5;
+  --text-copyright: #94A3B8;
+  --divider-dark: #94A3B8;
+  --text-subtle: #94A3B8;
+  --overlay-accent-08: rgba(51,65,85,0.08);
+  --overlay-accent-18: rgba(51,65,85,0.18);
+  --overlay-white-07: rgba(255,255,255,0.07);
+  --overlay-white-08: rgba(255,255,255,0.08);
+  --overlay-white-12: rgba(255,255,255,0.12);
+  /* Accent-tinted cards (e.g. the news carousel) — reuse the accent tokens */
+  --news-card-body: #1F2937;
+  --news-card-meta: #4B5563;
+  /* All `h3` / `.t-h3`: ~22px (1.375rem) floor on mobile → max 26px (1.625rem) */
+  --type-h3-size: clamp(1.375rem, 1.2rem + 0.55vw, 1.625rem);
+}
+
+/* ── Dark mode ── */
+[data-theme="dark"] {
+  --fg: #E2E8F0;
+  --muted: #94A3B8;
+  --accent: #CBD5E1;
+  --bg: #0F172A;
+  --bg-surface: #1E293B;
+  --bg-section: #1E293B;
+  --bg-tag: #1E293B;
+  --border: #334155;
+  --dark-bg: #0B1120;
+  --gold: #818CF8;
+  --gold-light: #312E81;
+  --brown: #94A3B8;
+  --text-light: #E2E8F0;
+  --text-footer: #94A3B8;
+  --text-footer-link: #818CF8;
+  --text-copyright: #64748B;
+  --divider-dark: #334155;
+  --text-subtle: #64748B;
+  /* Footer secondary-logo raster: darken toward paragraph copy (--muted) */
+  --secondary-logo-filter: brightness(0.68) contrast(1.12) saturate(0.82);
+  --overlay-accent-08: rgba(255,255,255,0.07);
+  --overlay-accent-18: rgba(255,255,255,0.12);
+  --overlay-white-07: rgba(255,255,255,0.07);
+  --overlay-white-08: rgba(255,255,255,0.08);
+  --overlay-white-12: rgba(255,255,255,0.12);
+  --news-card-body: var(--fg);
+  --news-card-meta: rgba(226, 232, 240, 0.78);
+}

package/utils/excerpt.ts

@@ -0,0 +1,56 @@
+/**
+ * Cheap markdown → plaintext for listing cards and meta descriptions.
+ * Not a full parser; tuned for news-style Markdown (headings, links, emphasis).
+ */
+export function markdownToPlainText(markdown: string, maxInputChars = 8000): string {
+  let s = markdown.length > maxInputChars ? markdown.slice(0, maxInputChars) : markdown;
+  s = s.replace(/\r\n/g, '\n');
+  // Drop fenced code (and inline code ticks)
+  s = s.replace(/```[\s\S]*?```/g, ' ');
+  s = s.replace(/`[^`]*`/g, ' ');
+  // Images ![alt](url) → alt text
+  s = s.replace(/!\[([^\]]*)\]\([^)]*\)/g, '$1 ');
+  // Links [text](url) → text
+  s = s.replace(/\[([^\]]*)\]\([^)]*\)/g, '$1 ');
+  s = s.replace(/\[([^\]]+)\]\[[^\]]*]/g, '$1 ');
+  // ATX headings
+  s = s.replace(/^#{1,6}\s+(.+)$/gm, '$1 ');
+  // Setext-style underline headings (rare)
+  s = s.replace(/^\s*[-=]{2,}\s*$/gm, ' ');
+  // Blockquotes, lists
+  s = s.replace(/^>\s?/gm, '');
+  s = s.replace(/^[\t ]*[-*+]\s+/gm, '');
+  s = s.replace(/^\d+\.\s+/gm, '');
+  // HR
+  s = s.replace(/^[\t ]*[-*_]{3,}[\t ]*$/gm, ' ');
+  // Bold / italic (nested patterns handled loosely)
+  s = s.replace(/\*\*([^*]+)\*\*/g, '$1');
+  s = s.replace(/\*([^*]+)\*/g, '$1');
+  s = s.replace(/__([^_]+)__/g, '$1');
+  s = s.replace(/_([^_]+)_/g, '$1');
+  // Strip simple HTML / MDX-looking tags
+  s = s.replace(/<[^>]+>/g, ' ');
+  s = s.replace(/\n+/g, ' ');
+  s = s.replace(/\s+/g, ' ').trim();
+  return s;
+}
+
+/**
+ * Plaintext suitable for cards (word-boundary trim + ellipsis).
+ */
+export function plainTextExcerpt(markdown: string, maxChars = 220): string {
+  const plain = markdownToPlainText(markdown);
+  if (!plain) return '';
+  if (plain.length <= maxChars) return plain;
+  const slice = plain.slice(0, maxChars);
+  const lastSpace = slice.lastIndexOf(' ');
+  const cut = lastSpace > maxChars * 0.55 ? slice.slice(0, lastSpace) : slice;
+  return `${cut.replace(/[.,;:!?…\s]+$/u, '').trim()}…`;
+}
+
+/**
+ * Shorter blurb for `<meta name="description">` and Open Graph.
+ */
+export function metaDescriptionFromBody(markdown: string, maxChars = 155): string {
+  return plainTextExcerpt(markdown, maxChars);
+}

package/utils/formatDate.ts

@@ -0,0 +1,22 @@
+/**
+ * Single source for the "30 April 2026" date label used across post cards,
+ * the post detail page, and the newsletter listing. Pulling it out of four
+ * inline `toLocaleDateString(...)` calls means a future change to the
+ * format (e.g. add weekday, switch to a relative label) is one edit.
+ */
+
+const DEFAULT_OPTIONS: Intl.DateTimeFormatOptions = {
+  day: 'numeric',
+  month: 'long',
+  year: 'numeric',
+};
+
+const DEFAULT_LOCALE = 'en-GB';
+
+export function formatDate(
+  date: Date,
+  options: Intl.DateTimeFormatOptions = DEFAULT_OPTIONS,
+  locale: string = DEFAULT_LOCALE,
+): string {
+  return date.toLocaleDateString(locale, options);
+}

package/utils/freshness.ts

@@ -0,0 +1,5 @@
+export const FRESH_WINDOW_MS = 3 * 24 * 60 * 60 * 1000;
+
+export function isFreshPost(date: Date, now: number = Date.now()): boolean {
+  return now - date.valueOf() < FRESH_WINDOW_MS;
+}

package/utils/scrollReveal.ts

@@ -0,0 +1,40 @@
+/**
+ * Progressive-enhancement reveal-on-scroll. Elements already on screen at
+ * arm-time are left alone (no hide, no fade, no JS involvement at all) —
+ * only elements below the fold get hidden and then faded/slid up once, the
+ * first time each individually scrolls into view. Pairs with the
+ * `.js-reveal` / `.is-visible` CSS in Base.astro.
+ *
+ * Skipping already-visible elements isn't just an optimisation: it avoids a
+ * flash where on-screen content would otherwise blink to invisible and back
+ * right as this runs — most noticeable right after an Astro View
+ * Transitions swap, where the new tiles are already painted by the time
+ * this executes.
+ *
+ * Callers should re-run this after any content swap — armed elements aren't
+ * tracked globally, so freshly rendered ones need to be passed in again to
+ * get the effect.
+ */
+export function armReveal(elements: HTMLElement[]): void {
+  const reducedMotionMq = window.matchMedia('(prefers-reduced-motion: reduce)');
+  if (!elements.length || reducedMotionMq.matches || !('IntersectionObserver' in window)) return;
+
+  const offscreen = elements.filter((el) => {
+    const rect = el.getBoundingClientRect();
+    return rect.bottom <= 0 || rect.top >= window.innerHeight;
+  });
+  if (!offscreen.length) return;
+
+  offscreen.forEach((el) => el.classList.add('js-reveal'));
+  requestAnimationFrame(() => {
+    const io = new IntersectionObserver((entries) => {
+      entries.forEach((entry) => {
+        if (entry.isIntersecting) {
+          entry.target.classList.add('is-visible');
+          io.unobserve(entry.target);
+        }
+      });
+    }, { threshold: 0.12 });
+    offscreen.forEach((el) => io.observe(el));
+  });
+}