ferst-core 0.1.0 → 0.2.0

package/lib/posts.ts

@@ -0,0 +1,93 @@
+/**
+ * The posts/blog capability's data side — `astro:content` wrappers around the pure
+ * selectors in content/posts.ts, plus `getStaticPaths` helpers so a client's post
+ * routes stay thin (like lib/pages.ts for pages). A client repo carries the post
+ * markdown + tag data + a couple of two-line routes; the logic lives here, once.
+ *
+ * Route sketch a client (or the showcase) uses:
+ *   // src/pages/posts/[...slug].astro  — an individual post
+ *   import { getPostRoutes } from 'ferst-core/lib/posts';
+ *   export const getStaticPaths = getPostRoutes;
+ *   const { entry } = Astro.props;
+ *   const { Content } = await entry.render();
+ *   // <PostArticle ...><Content /></PostArticle>
+ */
+import { getCollection, getEntry, type CollectionEntry } from 'astro:content';
+import {
+  postsSettingsSchema,
+  tagSchema,
+  sortByDateDesc,
+  dropDrafts,
+  excludeTags,
+  withTag,
+  tagCounts,
+  type PostsSettings,
+} from '../content/posts';
+
+export type PostEntry = CollectionEntry<'posts'>;
+
+/** A tag resolved for display: its slug + label/description + how many posts use it. */
+export interface UsedTag {
+  slug: string;
+  label: string;
+  description: string;
+  count: number;
+}
+
+/** All non-draft posts, newest first. */
+export async function getPublishedPosts(): Promise<PostEntry[]> {
+  return sortByDateDesc(dropDrafts(await getCollection('posts')));
+}
+
+/** Blog-wide settings (defaults applied). */
+export async function getPostsSettings(): Promise<PostsSettings> {
+  const entry = await getEntry('postsSettings', 'index');
+  return postsSettingsSchema.parse(entry?.data ?? {});
+}
+
+/** Posts for the MAIN index — published, minus any `excludeFromIndex` tags. */
+export async function getIndexPosts(): Promise<PostEntry[]> {
+  const [posts, settings] = await Promise.all([getPublishedPosts(), getPostsSettings()]);
+  return excludeTags(posts, settings.excludeFromIndex);
+}
+
+/** Published posts carrying a given tag slug, newest first. */
+export async function getPostsByTag(tag: string): Promise<PostEntry[]> {
+  return withTag(await getPublishedPosts(), tag);
+}
+
+/** Visible tags that actually have published posts, with counts (for tag routes/listings). */
+export async function getUsedTags(): Promise<UsedTag[]> {
+  const [posts, tagEntries] = await Promise.all([getPublishedPosts(), getCollection('tags')]);
+  const counts = tagCounts(posts);
+  return tagEntries
+    .map((t) => {
+      const data = tagSchema.parse(t.data);
+      return { slug: t.id, label: data.label, description: data.description, hidden: data.hidden, count: counts[t.id] ?? 0 };
+    })
+    .filter((t) => !t.hidden && t.count > 0)
+    .map(({ hidden: _hidden, ...t }) => t)
+    .sort((a, b) => a.label.localeCompare(b.label));
+}
+
+/** Resolve tag slugs on a post to `{ slug, label }` for display (unknown slugs fall back to the slug). */
+export async function resolveTagLabels(slugs: string[]): Promise<Array<{ slug: string; label: string }>> {
+  return Promise.all(
+    slugs.map(async (slug) => {
+      const entry = await getEntry('tags', slug);
+      return { slug, label: entry ? tagSchema.parse(entry.data).label : slug };
+    }),
+  );
+}
+
+/** `getStaticPaths` for a post route (`posts/[...slug].astro`). */
+export async function getPostRoutes() {
+  const posts = await getPublishedPosts();
+  return posts.map((entry) => ({ params: { slug: entry.slug }, props: { entry } }));
+}
+
+/** `getStaticPaths` for a tag route (`tags/[...tag].astro`). */
+export async function getTagRoutes() {
+  const tags = await getUsedTags();
+  return tags.map((tag) => ({ params: { tag: tag.slug }, props: { tag } }));
+}

package/lib/siteSettings.ts

@@ -1,45 +1,32 @@
 /**
- * Single accessor merging all the site-settings content entries into one
- * combined object.
+ * Single accessor merging the site-settings content entries into one combined
+ * object. Storage is split across small collections (identity+contact, logos,
+ * navbar, footer, theme) so each is its own focused Sveltia CMS pane — see
+ * `content/schemas.ts`. Consumers read one combined shape though, so this loader
+ * re-assembles it (including the `navigation.primary` / `navigation.footer`
+ * grouping) at read time — the only place that needs to know storage is split.
  *
- * Storage is split across several small collections (identity+contact,
- * logos, posts, calendar, navbar, footer) so each is also its own focused
- * Sveltia CMS pane instead of one long mixed-purpose form — see
- * `src/content/schemas.ts`. Every existing consumer (`Base.astro`,
- * `/calendar/`, `/contact/`, `/`) reads a single combined shape though, so
- * this loader re-assembles that shape (including the `navigation.primary`
- * / `navigation.footer` grouping, even though navbar and footer links now
- * live in two separate collections) at read time — the only place that
- * needs to know the storage is split.
- *
- * `getEntry(...)` yields `data` typed per-collection when the entry exists,
- * but the content runtime does not always apply nested Zod defaults the same
- * way a plain `schema.parse()` does. We always re-parse each entry's data
- * through its own schema so nested defaults (`identity`, `contact`,
- * `secondaryLogoLink`) are fully populated, including when a file is missing.
+ * `getEntry(...)` yields `data` typed per-collection when the entry exists, but
+ * the content runtime doesn't always apply nested Zod defaults the way a plain
+ * `schema.parse()` does. We re-parse each entry through its own schema so nested
+ * defaults are fully populated, including when a file is missing.
  */
 import { getEntry } from 'astro:content';
 import {
-  calendarSettingsSchema,
   footerSettingsSchema,
   logoSettingsSchema,
   navbarSettingsSchema,
-  postsSettingsSchema,
   siteSettingsSchema,
   themeSettingsSchema,
-  type CalendarSettings,
   type LogoSettings,
   type NavLink,
   type NavGroup,
-  type PostsSettings,
   type SiteSettings,
   type ThemeSettings,
 } from '../content/schemas';
 
 export type LoadedSiteSettings = SiteSettings &
-  LogoSettings &
-  PostsSettings &
-  CalendarSettings & {
+  LogoSettings & {
     navigation: { primary: NavLink[]; footer: NavLink[]; dropdown?: NavGroup };
     /** Client-provided design-token overrides (empty objects if none). */
     theme: ThemeSettings;
@@ -50,22 +37,17 @@ let cached: LoadedSiteSettings | null = null;
 export async function loadSiteSettings(): Promise<LoadedSiteSettings> {
   if (cached) return cached;
 
-  const [siteSettingsEntry, logoEntry, postsEntry, calendarEntry, navbarEntry, footerEntry, themeEntry] =
-    await Promise.all([
-      getEntry('siteSettings', 'index'),
-      getEntry('logoSettings', 'index'),
-      getEntry('postsSettings', 'index'),
-      getEntry('calendarSettings', 'index'),
-      getEntry('navbarSettings', 'index'),
-      getEntry('footerSettings', 'index'),
-      getEntry('themeSettings', 'index'),
-    ]);
+  const [siteSettingsEntry, logoEntry, navbarEntry, footerEntry, themeEntry] = await Promise.all([
+    getEntry('siteSettings', 'index'),
+    getEntry('logoSettings', 'index'),
+    getEntry('navbarSettings', 'index'),
+    getEntry('footerSettings', 'index'),
+    getEntry('themeSettings', 'index'),
+  ]);
 
   cached = {
     ...siteSettingsSchema.parse(siteSettingsEntry?.data ?? {}),
     ...logoSettingsSchema.parse(logoEntry?.data ?? {}),
-    ...postsSettingsSchema.parse(postsEntry?.data ?? {}),
-    ...calendarSettingsSchema.parse(calendarEntry?.data ?? {}),
     navigation: {
       primary: navbarSettingsSchema.parse(navbarEntry?.data ?? {}).primary,
       footer: footerSettingsSchema.parse(footerEntry?.data ?? {}).footer,

package/lib/themeTokens.ts

@@ -0,0 +1,163 @@
+/**
+ * The theming engine: turn the structured `themeSettings` (three brand colours +
+ * a font pairing + four surface knobs) into the CSS that drives the whole site.
+ *
+ * The design premise is that a brand needs only THREE source colours — `--brand`
+ * (interactive accent), `--ink` (text) and `--surface` (background). Every other
+ * working token (`--muted`, `--border`, `--bg-surface`, `--gold`, …) is DERIVED:
+ *   • Light  — `color-mix()` tints between ink/brand and the surface.
+ *   • Dark   — a scientific OKLCH translation of the SAME three colours: lightness
+ *              is flipped to dark-surface / light-text targets while HUE is
+ *              preserved and chroma is DAMPED, because a naïve hex inversion
+ *              yields harsh neon tones that vibrate and fail contrast on dark
+ *              grounds. Surfaces are deep, desaturated and faintly brand-tinted;
+ *              text lands at OKLCH L≈0.74–0.94 for comfortable legibility.
+ *              (Refs: Material dark theme; OKLCH accessible-palette guidance.)
+ *
+ * This lives in the CORE (not the showcase) so a real client site, the CMS, and
+ * the showcase's live playground all derive a palette the SAME way. `Base.astro`
+ * emits the result at doubled `:root:root` specificity so it beats the neutral
+ * literal defaults in `styles/theme.css` regardless of stylesheet order; the
+ * showcase playground then overrides `--brand/--ink/--surface` inline on <html>
+ * for per-visitor re-theming, and because the derivations read `var(--brand)`
+ * etc. the whole palette re-resolves live.
+ *
+ * Pure + framework-free so it is unit-testable without a render.
+ */
+import type { ThemeSettings } from '../content/schemas';
+
+/** The neutral source triple — used to fill any colour a client leaves blank so
+ *  the derivation is always self-contained (mirrors `styles/theme.css`). */
+export const NEUTRAL_SOURCE = {
+  brand: '#4F46E5',
+  ink: '#1F2937',
+  surface: '#F1F5F9',
+} as const;
+
+/** Corner-knob vocabulary → the `--radius` value every surface reads. */
+export const CORNERS_PX: Record<ThemeSettings['corners'], string> = {
+  sharp: '0px',
+  rounded: '12px',
+  soft: '22px',
+};
+
+/**
+ * Light-mode derivations — read the three source vars, tint via color-mix.
+ * Secondary-text mixes sit at ~72% ink so body copy (which uses `--muted`) keeps
+ * a comfortable AA contrast on the surface, rather than the trendy-but-faint
+ * light grey that fails it.
+ */
+const LIGHT_DERIVATION = [
+  '--gold:var(--brand)',
+  '--gold-light:color-mix(in srgb, var(--brand) 14%, var(--surface))',
+  '--accent-2:oklch(from var(--brand) 0.58 c calc(h + 26))',
+  '--fg:var(--ink)',
+  '--accent:color-mix(in srgb, var(--ink) 84%, var(--surface))',
+  '--muted:color-mix(in srgb, var(--ink) 72%, var(--surface))',
+  '--brown:color-mix(in srgb, var(--ink) 72%, var(--surface))',
+  '--bg:var(--surface)',
+  '--bg-surface:color-mix(in srgb, #fff 62%, var(--surface))',
+  '--bg-section:color-mix(in srgb, var(--ink) 7%, var(--surface))',
+  '--bg-tag:color-mix(in srgb, var(--ink) 6%, var(--surface))',
+  '--border:color-mix(in srgb, var(--ink) 16%, var(--surface))',
+  '--text-footer:color-mix(in srgb, var(--ink) 72%, var(--surface))',
+  '--text-footer-link:var(--brand)',
+  '--news-card-body:var(--ink)',
+  '--news-card-meta:color-mix(in srgb, var(--ink) 72%, var(--surface))',
+].join(';');
+
+/** Dark-mode derivations — the OKLCH translation of the same three source vars. */
+const DARK_DERIVATION = [
+  '--fg:oklch(from var(--ink) 0.94 calc(c * 0.3) h)',
+  '--muted:oklch(from var(--ink) 0.74 calc(c * 0.3) h)',
+  '--accent:oklch(from var(--ink) 0.86 calc(c * 0.3) h)',
+  '--brown:oklch(from var(--ink) 0.74 calc(c * 0.3) h)',
+  '--bg:oklch(from var(--brand) 0.16 0.015 h)',
+  '--bg-surface:oklch(from var(--brand) 0.21 0.02 h)',
+  '--bg-section:oklch(from var(--brand) 0.19 0.018 h)',
+  '--bg-tag:oklch(from var(--brand) 0.14 0.015 h)',
+  '--dark-bg:oklch(from var(--brand) 0.12 0.015 h)',
+  '--border:oklch(from var(--brand) 0.32 0.02 h)',
+  '--gold:oklch(from var(--brand) 0.78 calc(c * 0.9) h)',
+  '--gold-light:oklch(from var(--brand) 0.30 calc(c * 0.55) h)',
+  '--accent-2:oklch(from var(--brand) 0.70 calc(c * 0.9) calc(h + 26))',
+  '--text-footer:oklch(from var(--ink) 0.74 calc(c * 0.3) h)',
+  '--text-footer-link:oklch(from var(--brand) 0.78 calc(c * 0.9) h)',
+  '--text-copyright:oklch(from var(--ink) 0.55 calc(c * 0.3) h)',
+  '--text-subtle:oklch(from var(--ink) 0.55 calc(c * 0.3) h)',
+  '--divider-dark:oklch(from var(--brand) 0.32 0.02 h)',
+  '--news-card-meta:oklch(from var(--ink) 0.74 calc(c * 0.3) h)',
+].join(';');
+
+/** Drop a value that could break out of a CSS declaration. The source is trusted
+ *  repo JSON, but this keeps a stray value honest (defence in depth). */
+function clean(v: unknown): string {
+  return typeof v === 'string' && v.trim() !== '' && !/[<>{};]/.test(v) ? v.trim() : '';
+}
+
+/** A raw `{ '--token': 'value' }` record → one CSS rule (the advanced escape hatch). */
+function rawBlock(selector: string, tokens: Record<string, string> | undefined): string {
+  const decls = Object.entries(tokens ?? {})
+    .filter(([k, v]) => /^--?[a-zA-Z0-9-]+$/.test(k) && clean(v) !== '')
+    .map(([k, v]) => `${k.startsWith('--') ? k : `--${k}`}:${clean(v)}`)
+    .join(';');
+  return decls ? `${selector}{${decls}}` : '';
+}
+
+export interface ThemeStyle {
+  /** CSS to inline in <head> (may be an empty string when nothing is overridden). */
+  css: string;
+  /** Value for `<html data-field="…">`, or undefined for the `boxed` default. */
+  field: string | undefined;
+}
+
+/**
+ * Build the inline <style> body + the `data-field` attribute for a theme.
+ *
+ * When a client sets any of brand/ink/surface the full derivation is emitted
+ * (source colours — blanks filled from NEUTRAL_SOURCE — plus the light and dark
+ * derivations). When they set none, no colour CSS is emitted at all and the
+ * core's neutral literals in `styles/theme.css` stand. Fonts and knobs are
+ * emitted independently of colour; `advanced.*` raw tokens are layered last.
+ */
+export function buildThemeStyle(theme: ThemeSettings): ThemeStyle {
+  const brand = clean(theme.brand);
+  const ink = clean(theme.ink);
+  const surface = clean(theme.surface);
+  const themed = !!(brand || ink || surface);
+
+  // Block A — source colours + fonts + knobs (both modes). `:root:root` beats the
+  // theme.css `:root` / `[data-theme=dark]` literals; inline <html> beats this.
+  const rootDecls: string[] = [];
+  if (themed) {
+    rootDecls.push(`--brand:${brand || NEUTRAL_SOURCE.brand}`);
+    rootDecls.push(`--ink:${ink || NEUTRAL_SOURCE.ink}`);
+    rootDecls.push(`--surface:${surface || NEUTRAL_SOURCE.surface}`);
+  }
+  const fh = clean(theme.fonts?.heading);
+  const fb = clean(theme.fonts?.body);
+  const fd = clean(theme.fonts?.display);
+  if (fh) rootDecls.push(`--font-heading:${fh}`);
+  if (fb) rootDecls.push(`--font-body:${fb}`);
+  if (fd) rootDecls.push(`--font-display:${fd}`);
+  // Corners always resolves to a radius; only emit when it differs from the
+  // core default (`rounded` = 12px) to keep the payload minimal.
+  if (theme.corners && theme.corners !== 'rounded') {
+    rootDecls.push(`--radius:${CORNERS_PX[theme.corners]}`);
+  }
+  if (theme.elevation === 'flat') rootDecls.push('--shadow-md:none');
+  if (theme.stroke === 'off') rootDecls.push('--card-border:none');
+
+  const css = [
+    rootDecls.length ? `:root:root{${rootDecls.join(';')}}` : '',
+    themed ? `:root:root:not([data-theme="dark"]){${LIGHT_DERIVATION}}` : '',
+    themed ? `:root:root[data-theme="dark"]{${DARK_DERIVATION}}` : '',
+    rawBlock(':root:root', theme.advanced?.light),
+    rawBlock(':root:root[data-theme="dark"]', theme.advanced?.dark),
+  ]
+    .filter(Boolean)
+    .join('');
+
+  const field = theme.fields && theme.fields !== 'boxed' ? theme.fields : undefined;
+  return { css, field };
+}

package/package.json

@@ -1,48 +1,61 @@
-{
-  "name": "ferst-core",
-  "version": "0.1.0",
-  "type": "module",
-  "description": "Ferst Core — the shared, brand-agnostic client-site system: Astro components, layouts, content schemas, the layered config resolver, and a neutral styling architecture that every client overrides.",
-  "license": "Apache-2.0",
-  "author": "MyAI4 Ltd (https://ferst.co.uk)",
-  "homepage": "https://ferst.co.uk",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/MyAI4WebDev/myai4-ferst-core.git",
-    "directory": "packages/core"
-  },
-  "bugs": {
-    "url": "https://github.com/MyAI4WebDev/myai4-ferst-core/issues"
-  },
-  "keywords": [
-    "astro",
-    "astro-component",
-    "cms",
-    "sveltia",
-    "website",
-    "design-tokens",
-    "ferst"
-  ],
-  "sideEffects": [
-    "**/*.css"
-  ],
-  "files": [
-    "components",
-    "layouts",
-    "content",
-    "lib",
-    "utils",
-    "styles",
-    "README.md",
-    "NOTICE"
-  ],
-  "dependencies": {
-    "zod": "^3.25.0"
-  },
-  "peerDependencies": {
-    "astro": "^5.0.0"
-  },
-  "publishConfig": {
-    "access": "public"
-  }
-}
+{
+  "name": "ferst-core",
+  "version": "0.2.0",
+  "type": "module",
+  "description": "Ferst Core — the shared, brand-agnostic client-site system: Astro components, layouts, content schemas, the layered config resolver, and a neutral styling architecture that every client overrides.",
+  "license": "BUSL-1.1",
+  "author": "MyAI4 Ltd (https://ferst.co.uk)",
+  "homepage": "https://ferst.co.uk",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MyAI4WebDev/myai4-ferst-core.git",
+    "directory": "packages/core"
+  },
+  "bugs": {
+    "url": "https://github.com/MyAI4WebDev/myai4-ferst-core/issues"
+  },
+  "keywords": [
+    "astro",
+    "astro-component",
+    "cms",
+    "sveltia",
+    "website",
+    "design-tokens",
+    "ferst"
+  ],
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "files": [
+    "bin",
+    "components",
+    "layouts",
+    "content",
+    "lib",
+    "utils",
+    "styles",
+    "README.md",
+    "NOTICE",
+    "LICENSE",
+    "LICENSE-Apache-2.0"
+  ],
+  "bin": {
+    "ferst-check-thin": "bin/check-thin.mjs"
+  },
+  "dependencies": {
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "vitest": "^3.0.0"
+  },
+  "peerDependencies": {
+    "astro": "^5.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/styles/theme.css

@@ -56,6 +56,42 @@
   --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);
+
+  /* ── Surface treatment — the design "knobs" every card / tile / input reads,
+     so a single change restyles the whole site consistently (a client sets
+     these once in themeSettings; the showcase /theme playground sets them live).
+       --radius       corner radius for cards, tiles, inputs, buttons-as-tiles
+       --card-border  the stroke around a surface (set to `none` for borderless)
+       --shadow-*     elevation ramp (sm/md/lg); set --shadow-md:none for flat. */
+  --radius: 12px;
+  /* Derived from --radius so the one "corners" control also rounds the smaller
+     surfaces (fields, accordion rows) proportionally — sharp brand → sharp
+     fields, soft brand → soft fields. */
+  --radius-sm: calc(var(--radius) * 0.66);
+  --radius-pill: 999px;
+  --card-border: 1px solid var(--border);
+  --shadow-sm: 0 1px 2px rgba(15, 23, 42, 0.06), 0 1px 3px rgba(15, 23, 42, 0.08);
+  --shadow-md: 0 6px 22px rgba(15, 23, 42, 0.06), 0 2px 8px rgba(15, 23, 42, 0.04);
+  --shadow-lg: 0 12px 32px rgba(15, 23, 42, 0.12), 0 4px 12px rgba(15, 23, 42, 0.08);
+
+  /* Derived secondary accent for gradients / two-tone tiles — a tonal shade of
+     the single brand accent, so a one-colour brand still yields depth. Clients
+     (or the showcase's live playground) can override with a distinct hue. */
+  --accent-2: color-mix(in oklch, var(--gold) 82%, #000);
+
+  /* ── Typography roles — the site-wide font config. Every heading / body /
+     accent face reads one of these, so a client sets fonts by name (in
+     themeSettings, same as colours) and it propagates everywhere. A recipe that
+     needs a special face uses the DISPLAY role by design — we don't allow a
+     free-form per-block font (that's the inconsistency the system prevents).
+       --font-heading  h1/h3, nav, buttons, card titles (the workhorse UI face)
+       --font-display  h2/h4 and hero display type (the characterful face)
+       --font-body     paragraphs, lists, form fields, meta
+       --font-mono     code, block-type labels, tabular data */
+  --font-heading: 'Poppins', system-ui, -apple-system, Segoe UI, Roboto, sans-serif;
+  --font-display: 'Playfair Display', Georgia, 'Times New Roman', serif;
+  --font-body: 'Inter', system-ui, -apple-system, Segoe UI, Roboto, sans-serif;
+  --font-mono: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
 }
 
 /* ── Dark mode ── */
@@ -87,4 +123,10 @@
   --overlay-white-12: rgba(255,255,255,0.12);
   --news-card-body: var(--fg);
   --news-card-meta: rgba(226, 232, 240, 0.78);
+  /* On dark, depth comes from the elevated surface + border, not soft shadows —
+     keep shadows deep and quiet so they don't glow. */
+  --shadow-sm: none;
+  --shadow-md: 0 1px 0 rgba(255, 255, 255, 0.03);
+  --shadow-lg: 0 12px 32px rgba(0, 0, 0, 0.45);
+  --accent-2: color-mix(in oklch, var(--gold) 82%, #fff);
 }