ferst-core 0.1.0 → 0.2.1

package/README.md

@@ -1,73 +1,89 @@
-# ferst-core
-
-The shared, brand-agnostic client-site system behind [Ferst](https://ferst.co.uk).
-It ships the Astro components, layouts, content schemas, the layered config
-resolver, and a neutral styling architecture that every client site is built
-on. Update the core → every client benefits; brand and bespoke changes live in
-the client's own repo.
-
-This is the open, source-available **core**. It is deliberately generic — there
-are no verticals baked in (a "parish" or a "school" site is a *preset* of
-generic capabilities and content, never core code). Premium capability modules
-and the hosting platform live elsewhere.
-
-## Install
-
-```sh
-npm install ferst-core astro
-```
-
-`astro` is a peer dependency (Astro 5+). The package ships raw `.astro` / `.ts`
-source and is compiled by your own Astro build.
-
-## Usage
-
-A client site holds only its content, brand, and config. The core owns the
-schemas, the resolver, and the chrome.
-
-**1. Re-export the content collections** (Astro requires the config to live in
-the consumer — this one line is the whole contract):
-
-```ts
-// src/content/config.ts
-export { collections } from 'ferst-core/content/collections';
-```
-
-**2. Render pages through the core layout:**
-
-```astro
----
-import Base from 'ferst-core/layouts/Base.astro';
-import Button from 'ferst-core/components/Button.astro';
----
-<Base title="Home">
-  <h1>Welcome</h1>
-  <Button href="/contact/">Get in touch</Button>
-</Base>
-```
-
-`<Base>` loads the site's settings (identity, navigation, logos, calendar,
-footer) from the consumer's content collections and composes the header,
-footer, and cookie controls automatically.
-
-## Brand colours are yours
-
-The core ships a neutral slate + indigo default palette. Override any design
-token per-site via the `themeSettings` collection — no code change, and the
-colours live in your repo (or, later, the CMS):
-
-```json
-// src/content/themeSettings/index.json
-{
-  "light": { "--gold": "#EA580C", "--gold-light": "#FFEDD5" },
-  "dark":  { "--gold": "#FB923C", "--gold-light": "#431407" }
-}
-```
-
-`light` applies at `:root`, `dark` under `[data-theme="dark"]`; only the tokens
-you set are overridden, the rest fall through to the neutral defaults.
-
-## Licence
-
-[Apache-2.0](./LICENSE). Please retain the [NOTICE](./NOTICE) attribution when
-redistributing. © 2026 MyAI4 Ltd.
+# ferst-core
+
+The shared, brand-agnostic client-site system behind [Ferst](https://ferst.co.uk).
+It ships the Astro components, layouts, content schemas, the layered config
+resolver, and a neutral styling architecture that every client site is built
+on. Update the core → every client benefits; brand and bespoke changes live in
+the client's own repo.
+
+This is the open, source-available **core**. It is deliberately generic — there
+are no verticals baked in (a "parish" or a "school" site is a *preset* of
+generic capabilities and content, never core code). Premium capability modules
+and the hosting platform live elsewhere.
+
+## Install
+
+```sh
+npm install ferst-core astro
+```
+
+`astro` is a peer dependency (Astro 5+). The package ships raw `.astro` / `.ts`
+source and is compiled by your own Astro build.
+
+## Usage
+
+A client site holds only its content, brand, and config. The core owns the
+schemas, the resolver, and the chrome.
+
+**1. Re-export the content collections** (Astro requires the config to live in
+the consumer — this one line is the whole contract):
+
+```ts
+// src/content/config.ts
+export { collections } from 'ferst-core/content/collections';
+```
+
+**2. Render pages through the core layout:**
+
+```astro
+---
+import Base from 'ferst-core/layouts/Base.astro';
+import Button from 'ferst-core/components/Button.astro';
+---
+<Base title="Home">
+  <h1>Welcome</h1>
+  <Button href="/contact/">Get in touch</Button>
+</Base>
+```
+
+`<Base>` loads the site's settings (identity, navigation, logos, calendar,
+footer) from the consumer's content collections and composes the header,
+footer, and cookie controls automatically.
+
+## Brand colours are yours
+
+The core ships a neutral slate + indigo default palette. Design your whole brand
+from **three colours** in the `themeSettings` collection — the core derives the
+~40 working tokens for you (light via `color-mix`, dark via an OKLCH translation).
+No code change; the colours live in your repo, edited by hand or in the CMS:
+
+```json
+// src/content/themeSettings/index.json
+{
+  "brand": "#0E4D4A",
+  "ink": "#10201F",
+  "surface": "#FBFDFC",
+  "fonts": { "heading": "Poppins, sans-serif", "body": "Inter, sans-serif" },
+  "corners": "rounded",
+  "elevation": "raised",
+  "stroke": "on",
+  "fields": "boxed"
+}
+```
+
+`brand` drives buttons/links/accents, `ink` text, `surface` backgrounds (cards,
+sections and borders are tinted from it). The four knobs — `corners` /
+`elevation` / `stroke` / `fields` — are set once and apply to every card, tile
+and input. Set no brand and the neutral defaults stand. For the rare token that
+must differ from what the three colours derive, `advanced.light` / `advanced.dark`
+are raw `{ "--token": "value" }` escape hatches layered last.
+
+## Licence
+
+[Business Source License 1.1](./LICENSE) from v0.2.0 (v0.1.x was Apache-2.0 and stays
+that way). **You may use this in production** to build, operate and maintain individual
+websites -- your own, or ones you build for a client who controls the site, and any
+developer may take that site over. You may not use it to run a multi-tenant or hosted
+website service for third parties. Each version converts automatically to
+[Apache-2.0](./LICENSE-Apache-2.0) four years after publication. Please retain the
+[NOTICE](./NOTICE) attribution when redistributing.

package/bin/check-thin.mjs

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+// Ferst single-source guard (manifest §2): a client repo DEPENDS on the core —
+// it never contains a COPY. This fails the build if a client's src/ shadows a
+// core-owned module. Shared code (components/layouts/lib/utils/styles + the
+// content schema/collections/filters) comes from `ferst-core`; the client keeps
+// only content DATA, pages, the content config re-export, and a `custom/`
+// override sandbox. Shipped from core (its own single source) and run in each
+// client's CI/build: `ferst-check-thin [srcDir]` (defaults to ./src).
+import { readdirSync, statSync, existsSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+// Directories directly under src/ that belong to the core, not the client.
+const CORE_OWNED_DIRS = ['components', 'layouts', 'lib', 'utils', 'styles'];
+// Files under src/content/ that are the core's contract, not client data.
+// (Directories like content/posts/ and content/pages/ are client DATA — allowed;
+// these are the single-source contract FILES a client must import, never copy.)
+const CORE_OWNED_CONTENT_FILES = ['schemas.ts', 'collections.ts', 'blocks.ts', 'posts.ts', 'calendar.ts'];
+
+const toPosix = (s) => s.replace(/\\/g, '/');
+
+function* walk(dir) {
+  for (const name of readdirSync(dir)) {
+    const p = join(dir, name);
+    if (statSync(p).isDirectory()) yield* walk(p);
+    else yield p;
+  }
+}
+
+/**
+ * Return client `src/` paths (posix-style, relative to srcRoot) that shadow a
+ * core module. Pure + synchronous so it is unit-testable against a fixture dir.
+ */
+export function findShadowViolations(srcRoot) {
+  const violations = [];
+  if (!existsSync(srcRoot)) return violations; // no src/ → trivially thin
+
+  for (const dir of CORE_OWNED_DIRS) {
+    const p = join(srcRoot, dir);
+    if (existsSync(p) && statSync(p).isDirectory()) {
+      for (const f of walk(p)) violations.push(toPosix(relative(srcRoot, f)));
+    }
+  }
+
+  const contentDir = join(srcRoot, 'content');
+  for (const f of CORE_OWNED_CONTENT_FILES) {
+    const p = join(contentDir, f);
+    if (existsSync(p)) violations.push(toPosix(relative(srcRoot, p)));
+  }
+
+  return violations.sort();
+}
+
+function main() {
+  const srcRoot = process.argv[2] ?? 'src';
+  const violations = findShadowViolations(srcRoot);
+  if (violations.length === 0) {
+    console.log(`ferst-check-thin: OK — ${toPosix(srcRoot)}/ contains no copies of core modules.`);
+    process.exit(0);
+  }
+  console.error(
+    `ferst-check-thin: FAILED — ${violations.length} file(s) in ${toPosix(srcRoot)}/ shadow ferst-core.\n` +
+      `A client repo must DEPEND on the core, never copy it (manifest §2). Import these from\n` +
+      `'ferst-core' instead, or move a genuine one-off into src/custom/.\n\n` +
+      violations.map((v) => `  ✗ ${v}`).join('\n') +
+      '\n'
+  );
+  process.exit(1);
+}
+
+// Run only when invoked directly as a bin (not when imported by a test).
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  main();
+}

package/components/BlockRenderer.astro

@@ -0,0 +1,89 @@
+---
+/**
+ * Renders an ordered list of blocks by mapping each block's `type` to its
+ * component via a registry. Disabled blocks are skipped. The registry is typed
+ * `Record<BlockType, …>`, so adding a block type to the union without a renderer
+ * here is a compile error — no silent `undefined` component at runtime.
+ */
+import type { Block, BlockType } from '../content/blocks';
+import Heading from './blocks/Heading.astro';
+import Prose from './blocks/Prose.astro';
+import ImageBlock from './blocks/ImageBlock.astro';
+import ButtonBlock from './blocks/ButtonBlock.astro';
+import Quote from './blocks/Quote.astro';
+import Divider from './blocks/Divider.astro';
+import Spacer from './blocks/Spacer.astro';
+import Badge from './blocks/Badge.astro';
+import Stat from './blocks/Stat.astro';
+import List from './blocks/List.astro';
+import Section from './blocks/Section.astro';
+import Grid from './blocks/Grid.astro';
+import Stack from './blocks/Stack.astro';
+import Hero from './recipes/Hero.astro';
+import FeatureCards from './recipes/FeatureCards.astro';
+import Cta from './recipes/Cta.astro';
+import Faq from './recipes/Faq.astro';
+import Gallery from './recipes/Gallery.astro';
+import Testimonial from './recipes/Testimonial.astro';
+import ContactForm from './recipes/ContactForm.astro';
+import Accordion from './recipes/Accordion.astro';
+import Tiles from './recipes/Tiles.astro';
+import Banner from './recipes/Banner.astro';
+import Stats from './recipes/Stats.astro';
+import Steps from './recipes/Steps.astro';
+import Pricing from './recipes/Pricing.astro';
+import Logos from './recipes/Logos.astro';
+import Tabs from './recipes/Tabs.astro';
+import Announcement from './recipes/Announcement.astro';
+import Bento from './recipes/Bento.astro';
+import Marquee from './recipes/Marquee.astro';
+
+interface Props {
+  blocks: Block[];
+}
+
+const { blocks } = Astro.props;
+
+const registry: Record<BlockType, any> = {
+  heading: Heading,
+  prose: Prose,
+  image: ImageBlock,
+  button: ButtonBlock,
+  quote: Quote,
+  divider: Divider,
+  spacer: Spacer,
+  badge: Badge,
+  stat: Stat,
+  list: List,
+  section: Section,
+  grid: Grid,
+  stack: Stack,
+  hero: Hero,
+  featureCards: FeatureCards,
+  cta: Cta,
+  faq: Faq,
+  gallery: Gallery,
+  testimonial: Testimonial,
+  contactForm: ContactForm,
+  accordion: Accordion,
+  tiles: Tiles,
+  banner: Banner,
+  stats: Stats,
+  steps: Steps,
+  pricing: Pricing,
+  logos: Logos,
+  tabs: Tabs,
+  announcement: Announcement,
+  bento: Bento,
+  marquee: Marquee,
+};
+---
+
+{
+  blocks
+    .filter((block) => block.enabled !== false)
+    .map((block) => {
+      const Component = registry[block.type];
+      return <Component {...block} />;
+    })
+}

package/components/Button.astro

@@ -2,7 +2,7 @@
 interface Props {
   href?: string;
   type?: 'button' | 'submit' | 'reset';
-  variant?: 'primary' | 'secondary' | 'cta' | 'compact';
+  variant?: 'primary' | 'secondary' | 'cta' | 'compact' | 'ghost';
   size?: 'sm' | 'md';
   disabled?: boolean;
   [x: string]: any;
@@ -45,8 +45,9 @@ const {
     justify-content: center;
     background: transparent;
     border: 2px solid var(--fg);
+    border-radius: var(--radius-sm);
     color: var(--fg);
-    font-family: 'Poppins', sans-serif;
+    font-family: var(--font-heading);
     font-size: 0.75rem;
     font-weight: 600;
     text-transform: uppercase;
@@ -88,6 +89,24 @@ const {
     cursor: not-allowed;
   }
 
+  /* Role distinction: primary = filled (high emphasis), secondary = the base
+     outline (medium). Filled beats the base outline-hover, so override it. */
+  .btn--primary {
+    background: var(--gold);
+    border-color: var(--gold);
+    color: var(--text-light);
+  }
+  .btn--primary:hover,
+  .btn--primary:focus-visible {
+    background: color-mix(in srgb, var(--gold) 85%, #000);
+    border-color: color-mix(in srgb, var(--gold) 85%, #000);
+    color: var(--text-light);
+  }
+  .btn--primary:focus-visible {
+    outline: 2px solid var(--gold);
+    outline-offset: 2px;
+  }
+
   .btn--sm {
     height: auto;
     min-height: 40px;
@@ -98,13 +117,15 @@ const {
     .btn--sm { height: 40px; padding: 0 0.85rem; }
   }
 
-  /* CTA variant - matches the header's Contact button style */
+  /* CTA / compact variants — a filled button in the brand accent. Token-driven
+     (was a hardcoded CTK green) so it recolours with the site palette; hover
+     darkens the accent via color-mix, which works for any brand colour. */
   .btn--cta {
-    background: #2A3A2A;
-    color: #C8D4C2;
+    background: var(--gold);
+    color: var(--text-light);
     border: none;
     border-radius: 8px;
-    font-family: 'Inter', 'Lato', sans-serif;
+    font-family: var(--font-body);
     font-size: 0.75rem;
     font-weight: 600;
     letter-spacing: 0.1em;
@@ -123,12 +144,12 @@ const {
   }
 
   .btn--cta:hover {
-    background: #1A2A1A;
-    color: #C8D4C2;
+    background: color-mix(in srgb, var(--gold) 85%, #000);
+    color: var(--text-light);
   }
   .btn--cta:focus-visible {
-    background: #1A2A1A;
-    color: #C8D4C2;
+    background: color-mix(in srgb, var(--gold) 85%, #000);
+    color: var(--text-light);
     outline: 2px solid var(--gold);
     outline-offset: 2px;
   }
@@ -139,11 +160,11 @@ const {
     justify-content: center;
     margin-top: auto;
     align-self: flex-start;
-    background: #2A3A2A;
-    color: #C8D4C2;
+    background: var(--gold);
+    color: var(--text-light);
     border: none;
     border-radius: 8px;
-    font-family: 'Inter', 'Lato', sans-serif;
+    font-family: var(--font-body);
     font-size: 0.75rem;
     font-weight: 600;
     letter-spacing: 0.1em;
@@ -162,12 +183,33 @@ const {
   }
 
   .btn--compact:hover {
-    background: #1A2A1A;
-    color: #C8D4C2;
+    background: color-mix(in srgb, var(--gold) 85%, #000);
+    color: var(--text-light);
   }
   .btn--compact:focus-visible {
-    background: #1A2A1A;
-    color: #C8D4C2;
+    background: color-mix(in srgb, var(--gold) 85%, #000);
+    color: var(--text-light);
+    outline: 2px solid var(--gold);
+    outline-offset: 2px;
+  }
+
+  /* Ghost — a quiet, borderless text button for tertiary actions. */
+  .btn--ghost {
+    background: transparent;
+    border: 2px solid transparent;
+    color: var(--gold);
+    min-width: auto;
+    padding: 0 0.6rem;
+  }
+  .btn--ghost:hover {
+    color: var(--gold);
+    border-color: transparent;
+    background: var(--gold-light);
+  }
+  .btn--ghost:focus-visible {
+    color: var(--gold);
+    border-color: transparent;
+    background: var(--gold-light);
     outline: 2px solid var(--gold);
     outline-offset: 2px;
   }
@@ -178,31 +220,41 @@ const {
     color: var(--text-light);
   }
 
+  :global([data-theme="dark"]) .btn--ghost {
+    border-color: transparent;
+    color: var(--gold);
+  }
+  :global([data-theme="dark"]) .btn--ghost:hover,
+  :global([data-theme="dark"]) .btn--ghost:focus-visible {
+    border-color: transparent;
+    color: var(--gold);
+    background: var(--gold-light);
+  }
+
   :global([data-theme="dark"]) .btn:hover,
   :global([data-theme="dark"]) .btn:focus-visible {
     border-color: var(--gold);
     color: var(--gold);
   }
 
-  :global([data-theme="dark"]) .btn--cta {
-    background: #C8973A;
-    color: #3D2B1A;
+  /* In dark mode --gold is a light accent, so dark text reads best on it, and
+     hover lightens (mix toward white) rather than darkens. */
+  :global([data-theme="dark"]) .btn--cta,
+  :global([data-theme="dark"]) .btn--compact,
+  :global([data-theme="dark"]) .btn--primary {
+    background: var(--gold);
+    border-color: var(--gold);
+    color: var(--dark-bg);
   }
 
   :global([data-theme="dark"]) .btn--cta:hover,
-  :global([data-theme="dark"]) .btn--cta:focus-visible {
-    background: #B8872A;
-    color: #3D2B1A;
-  }
-
-  :global([data-theme="dark"]) .btn--compact {
-    background: #C8973A;
-    color: #3D2B1A;
-  }
-
+  :global([data-theme="dark"]) .btn--cta:focus-visible,
   :global([data-theme="dark"]) .btn--compact:hover,
-  :global([data-theme="dark"]) .btn--compact:focus-visible {
-    background: #B8872A;
-    color: #3D2B1A;
+  :global([data-theme="dark"]) .btn--compact:focus-visible,
+  :global([data-theme="dark"]) .btn--primary:hover,
+  :global([data-theme="dark"]) .btn--primary:focus-visible {
+    background: color-mix(in srgb, var(--gold) 85%, #fff);
+    border-color: color-mix(in srgb, var(--gold) 85%, #fff);
+    color: var(--dark-bg);
   }
 </style>