ferst-core 0.1.0

package/content/collections.ts

@@ -0,0 +1,40 @@
+// Collection definitions — the content *contract*. Core owns this; each consumer
+// re-exports it from its own `src/content/config.ts` (Astro requires the config
+// to live in the consumer). The content files themselves stay in the consumer.
+import { defineCollection } from 'astro:content';
+import {
+  homepageSchema,
+  postSchema,
+  siteSettingsSchema,
+  logoSettingsSchema,
+  postsSettingsSchema,
+  calendarSettingsSchema,
+  navbarSettingsSchema,
+  footerSettingsSchema,
+  themeSettingsSchema,
+  tagSchema,
+} from './schemas';
+
+const homepage = defineCollection({ type: 'data', schema: homepageSchema });
+const posts = defineCollection({ type: 'content', schema: postSchema });
+const siteSettings = defineCollection({ type: 'data', schema: siteSettingsSchema });
+const logoSettings = defineCollection({ type: 'data', schema: logoSettingsSchema });
+const postsSettings = defineCollection({ type: 'data', schema: postsSettingsSchema });
+const calendarSettings = defineCollection({ type: 'data', schema: calendarSettingsSchema });
+const navbarSettings = defineCollection({ type: 'data', schema: navbarSettingsSchema });
+const footerSettings = defineCollection({ type: 'data', schema: footerSettingsSchema });
+const themeSettings = defineCollection({ type: 'data', schema: themeSettingsSchema });
+const tags = defineCollection({ type: 'content', schema: tagSchema });
+
+export const collections = {
+  posts,
+  homepage,
+  siteSettings,
+  logoSettings,
+  postsSettings,
+  calendarSettings,
+  navbarSettings,
+  footerSettings,
+  themeSettings,
+  tags,
+};

package/content/filters.ts

@@ -0,0 +1,107 @@
+// Named predicates for the content collection filters used across the
+// /posts/* page routes.
+//
+// Why this lives here:
+//   - DRY: each rule is defined once instead of duplicated as an inline
+//     arrow at every call site.
+//   - Testable: pure functions over Post data, no Astro runtime needed.
+//   - Self-documenting: at the page, `getCollection('posts', forArchive)`
+//     reads better than the equivalent arrow.
+//
+// Visibility model encoded here:
+//   - `draft` and `scheduled` posts are never visible (no listing, no detail
+//     page). A `scheduled` post is content that has been written ahead of time:
+//     a cron worker flips it to `published` once its `date` has passed, which
+//     is the only thing that makes it appear. Until then it is hidden exactly
+//     like a draft.
+//   - `published`: appear on /posts/ (paginated index); anything beyond
+//     `LATEST_NEWS_MAX` newest also appears on /posts/archive/ alongside
+//     posts explicitly marked `archived`.
+//   - `archived` posts appear on /posts/archive/ (and still get
+//     /posts/<slug>/).
+//   - "Newsletter" is a tag, not a separate content type — a post tagged
+//     `newsletter` is otherwise an ordinary post (same schema, same
+//     `/posts/<slug>/` detail page, same listing/archive rules above) that
+//     just typically has no body, only an attachment. `/posts/tag/newsletter/`
+//     is the generic per-tag archive every tag gets for free, no bespoke
+//     route needed.
+import type { CollectionEntry } from 'astro:content';
+import type { Post } from './schemas';
+
+type PostEntry = { data: Post };
+
+/** How many published news posts headline /posts/ before they roll into /posts/archive/. */
+export const LATEST_NEWS_MAX = 6;
+
+/**
+ * Statuses that are never shown on the public site — no listing, no detail
+ * page. `scheduled` joins `draft` here: it stays invisible until the cron
+ * worker promotes it to `published`.
+ */
+const isHidden = ({ data }: PostEntry): boolean =>
+  data.status === 'draft' || data.status === 'scheduled';
+
+/** Listed on /posts/ (the news index). */
+export function forLatestListing(entry: PostEntry): boolean {
+  return entry.data.status === 'published';
+}
+
+/** Has a generated /posts/<slug>/ detail page. Includes archived posts. */
+export function forLatestDetail(entry: PostEntry): boolean {
+  return !isHidden(entry);
+}
+
+/**
+ * Single-entry archive predicate (tests, CMS docs). The live /posts/archive/
+ * list is built with `buildArchiveListing` (archived + published overflow).
+ */
+export function forArchive(entry: PostEntry): boolean {
+  return entry.data.status === 'archived';
+}
+
+/**
+ * /posts/archive/: all `archived` posts, plus `published` news that are not
+ * among the `LATEST_NEWS_MAX` newest (same date order as /posts/).
+ */
+export function buildArchiveListing(
+  publishedPosts: CollectionEntry<'posts'>[],
+  archivedPosts: CollectionEntry<'posts'>[]
+): CollectionEntry<'posts'>[] {
+  const sorted = [...publishedPosts].sort(
+    (a, b) => b.data.date.valueOf() - a.data.date.valueOf()
+  );
+  const afterLatest = sorted.slice(LATEST_NEWS_MAX);
+  return [...archivedPosts, ...afterLatest].sort(
+    (a, b) => b.data.date.valueOf() - a.data.date.valueOf()
+  );
+}
+
+/** Back link on a news article under /posts/ (archive vs main list; same cut-off as LATEST_NEWS_MAX). */
+export function newsDetailBackLink(
+  post: CollectionEntry<'posts'>,
+  publishedPosts: CollectionEntry<'posts'>[]
+): { href: string; label: string } {
+  if (post.data.status === 'archived') {
+    return { href: '/posts/archive/', label: '← Back to archive' };
+  }
+  const sorted = [...publishedPosts].sort(
+    (a, b) => b.data.date.valueOf() - a.data.date.valueOf()
+  );
+  const topIds = new Set(sorted.slice(0, LATEST_NEWS_MAX).map((p) => p.id));
+  if (topIds.has(post.id)) {
+    return { href: '/posts/', label: '← Back to all news' };
+  }
+  return { href: '/posts/archive/', label: '← Back to archive' };
+}
+
+/**
+ * A body-less post with an attachment (the typical newsletter shape) has
+ * nothing to show on a `/posts/<slug>/` detail page, so its card/row should
+ * open the attachment directly instead of linking internally. An ordinary
+ * post that happens to also carry an attachment still opens its detail page
+ * (where the attachment is offered as a separate link) since there's a body
+ * worth reading first.
+ */
+export function opensAttachmentDirectly(entry: PostEntry & { body?: string }): boolean {
+  return Boolean(entry.data.attachment) && !entry.body?.trim();
+}

package/content/schemas.ts

@@ -0,0 +1,210 @@
+// Pure Zod schemas, separated from config.ts so they can be unit-tested
+// without pulling in `astro:content` (a virtual module that only exists
+// during Astro's build). config.ts wraps these with defineCollection.
+import { z } from 'zod';
+
+/** One “Get Involved” card on the home page (`GroupCard`). */
+export const homepageGroupSchema = z.object({
+  title: z.string(),
+  description: z.string(),
+  icon: z.enum(['prayer', 'charity', 'ordinariate', 'youth']).optional(),
+  /** Shown when `linkHref` is not set — mailto handled in `GroupCard`. */
+  contact: z.string().optional(),
+  contactLabel: z.string().optional(),
+  linkHref: z.string().optional(),
+  imageSrc: z.string().optional(),
+  imageAlt: z.string().optional(),
+});
+
+export const homepageSchema = z.object({
+  heroImage: z.string().optional(),
+  groups: z.array(homepageGroupSchema).default([]),
+});
+
+/**
+ * Editor-managed tag vocabulary. A post's `tags` array stores these entries'
+ * `name` values directly (not a slug/reference) — see the CMS `relation`
+ * field config in scripts/build-admin-config.mjs — so this collection exists
+ * purely to give editors a searchable, growable, typo-resistant picker
+ * instead of a hardcoded list. The site itself never reads this collection;
+ * only the CMS authoring UI does.
+ */
+export const tagSchema = z.object({
+  name: z.string(),
+});
+
+/* ────────────────────────────────────────────────────────────────────────
+ *  Site settings — split into several small single-purpose collections
+ *  (logo / posts / calendar / navigation / identity+contact) instead of one
+ *  big file, so each one is also its own focused Sveltia CMS pane rather
+ *  than everything mushed onto a single long form. `src/lib/siteSettings.ts`
+ *  merges all of these back into one `SiteSettings`-shaped object at read
+ *  time, so every consumer keeps reading a single combined shape — only the
+ *  underlying storage and CMS authoring surface are split.
+ *
+ *  Every nested object is `.default({})` so the data file only has to
+ *  supply the keys it wants to override; defaults fill in the rest at
+ *  parse time. That keeps schemas additive and JSON edits small.
+ * ──────────────────────────────────────────────────────────────────── */
+
+const navLinkSchema = z.object({
+  label: z.string(),
+  href: z.string(),
+});
+
+/** One item inside a nav dropdown / mega panel (client-configured, generic). */
+const navGroupItemSchema = z.object({
+  title: z.string(),
+  desc: z.string().optional(),
+  href: z.string(),
+});
+
+/** An optional dropdown group in the primary nav (e.g. an "About" mega-menu
+ *  or a "Services" menu). Entirely client-configured — the core ships none. */
+const navGroupSchema = z.object({
+  label: z.string(),
+  href: z.string(),
+  items: z.array(navGroupItemSchema).default([]),
+});
+
+const churchSchema = z.object({
+  name: z.string(),
+  /** One physical-address line per array entry; rendered with <br /> between. */
+  addressLines: z.array(z.string()).default([]),
+  /** Free-form Google Maps query; the page wraps it in maps.google.com/?q=. */
+  mapsQuery: z.string().optional(),
+});
+
+const siteIdentitySchema = z
+  .object({
+    /** Used in <title> as " — {siteTitle}" and in the document description fallback.
+     *  Generic default — every client overrides via their siteSettings content. */
+    siteTitle: z.string().default('Your Site'),
+    /** Short brand label — used in alt text. */
+    shortName: z.string().default('Your Site'),
+    /** Default <meta name="description"> when a page doesn't supply its own. */
+    description: z.string().default('A website built with Ferst.'),
+    /** Optional org/parent line (e.g. a diocese, a group) — blank by default. */
+    diocese: z.string().default(''),
+    /** Town / city — appears under the hero title and elsewhere. */
+    location: z.string().default(''),
+    /** Home-page hero copy. */
+    heroDiocese: z.string().default(''),
+    heroTitle: z.string().default('Welcome'),
+    heroLocation: z.string().default(''),
+  })
+  .default({});
+
+const siteContactSchema = z
+  .object({
+    /** Human-readable phone number. Blank by default — client provides. */
+    phoneDisplay: z.string().default(''),
+    /** Digits-only form used in `tel:` href. */
+    phoneTel: z.string().default(''),
+    email: z.string().default(''),
+    facebookUrl: z.string().default(''),
+    /** One entry per physical location/site. Iterated on /contact/. */
+    churches: z.array(churchSchema).default([]),
+  })
+  .default({});
+
+/** Site identity + contact details. Everything else that used to live
+ * alongside these (logos, posts-per-page, calendar ID, navigation) now has
+ * its own collection — see below. */
+export const siteSettingsSchema = z.object({
+  identity: siteIdentitySchema,
+  contact: siteContactSchema,
+});
+
+export const logoSettingsSchema = z.object({
+  /** Primary/header logo — light theme variant. Optional — Base.astro falls back to a baked-in path. */
+  primaryLogoLight: z.string().optional(),
+  /** Primary/header logo — dark theme variant. Optional — Base.astro falls back to a baked-in path. */
+  primaryLogoDark: z.string().optional(),
+  /** Secondary/footer logo — light theme variant (optional). */
+  secondaryLogoLight: z.string().optional(),
+  /** Secondary/footer logo — dark theme variant (optional). */
+  secondaryLogoDark: z.string().optional(),
+  /** Display name + target URL for the secondary/footer logo's link (optional). */
+  secondaryLogoLink: z
+    .object({
+      name: z.string().default(''),
+      url: z.string().default(''),
+    })
+    .default({}),
+});
+
+export const postsSettingsSchema = z.object({
+  postsPerPage: z.number().int().min(1).max(20).default(5),
+});
+
+export const calendarSettingsSchema = z.object({
+  /** Google Calendar ID (e.g. "abc123@group.calendar.google.com") embedded on /calendar/.
+   *  Blank by default — client provides; the calendar page can hide itself when unset. */
+  calendarId: z.string().default(''),
+});
+
+export const navbarSettingsSchema = z.object({
+  /** Simple top-level links. Empty by default — every client defines its own nav. */
+  primary: z.array(navLinkSchema).default([]),
+  /** Optional dropdown / mega-menu group (e.g. an "About" or "Services" menu).
+   *  Rendered by SiteHeader only when present — the core ships none. */
+  dropdown: navGroupSchema.optional(),
+});
+
+export const footerSettingsSchema = z.object({
+  /** Footer legal/info nav. Empty by default — every client defines its own. */
+  footer: z.array(navLinkSchema).default([]),
+});
+
+/**
+ * Client-overridable design tokens. Each key maps to a CSS custom property
+ * (a leading `--` is added if omitted); the values are emitted into a
+ * `<style>` in the document head that overrides the core's NEUTRAL defaults
+ * in `styles/theme.css`. The core ships none — every client brings its own
+ * palette here, so brand colours live in the client's repo (or, later, the
+ * CMS), never baked into the shared core. `light` applies at `:root`, `dark`
+ * under `[data-theme="dark"]`; only the keys a client sets are overridden,
+ * the rest fall through to the neutral defaults.
+ */
+export const themeSettingsSchema = z.object({
+  light: z.record(z.string()).default({}),
+  dark: z.record(z.string()).default({}),
+});
+
+export const postSchema = z.object({
+  title: z.string(),
+  /** Author byline — shown in the CMS posts list and publicly under the post title.
+   * Expected on every post except newsletters, but Sveltia CMS can't enforce that
+   * conditionally, so it's optional here too (communicated via the CMS field hint). */
+  author: z.string().optional(),
+  date: z.coerce.date(),
+  /** A `newsletter`-tagged post is treated as a newsletter throughout the site
+   * (tag-driven, not a separate content type) — see src/content/filters.ts. */
+  tags: z.array(z.string()).default([]),
+  image: z.string().optional(),
+  /** Optional file (PDF, image, document). Expected for newsletter-tagged
+   * posts, which are otherwise body-less — communicated via the CMS hint,
+   * same conditional-required pattern as `author`. */
+  attachment: z.string().optional(),
+  // Visibility states. 'scheduled' is hidden from the site exactly like
+  // 'draft'; a separate cron worker flips due 'scheduled' posts to
+  // 'published' (commit → rebuild) once their `date` has passed.
+  status: z.enum(['published', 'draft', 'scheduled', 'archived']).default('published'),
+});
+
+export type Post = z.infer<typeof postSchema>;
+export type Tag = z.infer<typeof tagSchema>;
+export type Homepage = z.infer<typeof homepageSchema>;
+export type HomepageGroup = z.infer<typeof homepageGroupSchema>;
+export type SiteSettings = z.infer<typeof siteSettingsSchema>;
+export type LogoSettings = z.infer<typeof logoSettingsSchema>;
+export type PostsSettings = z.infer<typeof postsSettingsSchema>;
+export type CalendarSettings = z.infer<typeof calendarSettingsSchema>;
+export type NavbarSettings = z.infer<typeof navbarSettingsSchema>;
+export type FooterSettings = z.infer<typeof footerSettingsSchema>;
+export type ThemeSettings = z.infer<typeof themeSettingsSchema>;
+export type NavLink = z.infer<typeof navLinkSchema>;
+export type NavGroup = z.infer<typeof navGroupSchema>;
+export type NavGroupItem = z.infer<typeof navGroupItemSchema>;
+export type Church = z.infer<typeof churchSchema>;