ferst-core 0.9.6 → 0.9.8

package/bin/cms-config.mjs

@@ -60,53 +60,10 @@ export function repoSlug() {
   return '';
 }
 
-export const PROD_GIT_BASE = 'https://signin.ferst.co.uk';
-export const DEV_GIT_BASE = 'https://signin-dev.ferst.co.uk';
-
-/**
- * The platform git-proxy origin (CMS `base_url` / `api_root`) for THIS build:
- *   1. `FERST_GIT_BASE` env — explicit override, always wins.
- *   2. committed `ferst-site.json` `gitBase` — an explicit per-site pin (e.g. a
- *      custom proxy); a BYO/seeded site can hard-bind its origin this way.
- *   3. otherwise DERIVE from the deploy environment: the production branch talks to
- *      the prod git-proxy, every other (preview/dev) branch talks to the dev
- *      git-proxy. So a templated repo self-configures per environment on deploy — a
- *      dev-branch build points its CMS at the dev worker and main at prod — with NO
- *      per-client config. (The production branch defaults to `main`; override via
- *      `FERST_PROD_BRANCH` env or `ferst-site.json` `productionBranch`.)
- * This restores the "site respects the environment it's deployed in" binding the old
- * per-branch site config gave, without a per-client file to maintain.
- */
-export function resolveGitBase(cwd = process.cwd(), branch = deploymentBranch()) {
-  const fromEnv = env('FERST_GIT_BASE');
-  if (fromEnv) return fromEnv;
-  let prodBranch = env('FERST_PROD_BRANCH') || 'main';
-  try {
-    const site = JSON.parse(readFileSync(resolve(cwd, 'ferst-site.json'), 'utf8'));
-    if (site && typeof site.gitBase === 'string' && site.gitBase.trim()) return site.gitBase.trim();
-    if (!env('FERST_PROD_BRANCH') && site && typeof site.productionBranch === 'string' && site.productionBranch.trim()) {
-      prodBranch = site.productionBranch.trim();
-    }
-  } catch {
-    /* no ferst-site.json (e.g. the template repo itself) — derive from the branch */
-  }
-  return branch === prodBranch ? PROD_GIT_BASE : DEV_GIT_BASE;
-}
-
-/** The deployment branch: CF Pages env → current git branch → main. */
-export function deploymentBranch() {
-  const cf = env('CF_PAGES_BRANCH');
-  if (cf) return cf;
-  try {
-    const git = execSync('git rev-parse --abbrev-ref HEAD', {
-      stdio: ['ignore', 'pipe', 'ignore'],
-    }).toString().trim();
-    if (git && git !== 'HEAD') return git;
-  } catch {
-    /* not a git checkout — fall through */
-  }
-  return 'main';
-}
+// The git-proxy origin lives in lib/git-base.mjs, which components can import: this file is a
+// build-time script whose module scope needs a real filesystem (TEMPLATE_PATH).
+export { PROD_GIT_BASE, DEV_GIT_BASE, resolveGitBase, deploymentBranch } from '../lib/git-base.mjs';
+import { resolveGitBase, deploymentBranch } from '../lib/git-base.mjs';
 
 /** Ferst's managed GitHub org: its sites are on the Basic plan. */
 const MANAGED_OWNER = 'myai4webdev';

package/bin/ferst-modules.mjs

@@ -12,7 +12,7 @@
 import { readFileSync, realpathSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
-import { resolveGitBase } from './cms-config.mjs';
+import { resolveGitBase } from '../lib/git-base.mjs';
 
 /**
  * True when THIS file is run as a CLI (not imported). Each bin needs its own copy:

package/components/recipes/FeatureCards.astro

@@ -5,6 +5,7 @@
  * link. Composes the Card, Icon, Heading and Button primitives.
  */
 import Heading from '../blocks/Heading.astro';
+import { gridColumns } from '../../lib/gridColumns';
 import Card from '../Card.astro';
 import Icon from '../Icon.astro';
 import Button from '../Button.astro';
@@ -24,7 +25,7 @@ const { align: blockAlign, headingAlign } = Astro.props as { align?: 'start' | '
 const headAlign = headingAlign ?? blockAlign ?? 'center';
 // Never reserve more columns than there are cards (a lone card in a 3-col grid
 // would strand two empty cells); `data-single` centres a solitary card.
-const cols = Math.min(columns, Math.max(cards.length, 1)) as 1 | 2 | 3 | 4;
+const { tablet, desktop: cols } = gridColumns(cards.length, columns); // never a short last row
 ---
 
 <section class="b-feature-cards">
@@ -34,7 +35,7 @@ const cols = Math.min(columns, Math.max(cards.length, 1)) as 1 | 2 | 3 | 4;
       {intro && <p class="b-feature-cards__intro" set:html={inlineMarkdown(intro)} />}
     </div>
   )}
-  <div class="b-feature-cards__grid" data-cols={cols} data-single={cards.length === 1 ? 'true' : undefined}>
+  <div class="b-feature-cards__grid" data-cols={cols} data-tablet={tablet} data-single={cards.length === 1 ? 'true' : undefined}>
     {cards.map((card) => (
       <Card>
         {card.icon && isIconKey(card.icon) && (
@@ -79,17 +80,19 @@ const cols = Math.min(columns, Math.max(cards.length, 1)) as 1 | 2 | 3 | 4;
     grid-template-columns: 1fr; /* mobile-first */
     gap: 1.5rem;
   }
-  @media (min-width: 48em) {
-    .b-feature-cards__grid[data-cols='2'] { grid-template-columns: repeat(2, 1fr); }
-    .b-feature-cards__grid[data-cols='3'] { grid-template-columns: repeat(3, 1fr); }
-    .b-feature-cards__grid[data-cols='4'] { grid-template-columns: repeat(2, 1fr); }
+  /* Never a short last row (lib/gridColumns): twos on tablet for an even count; on desktop
+     everything in one row, or even rows. Phones stay one column. */
+  @media (min-width: 40em) {
+    .b-feature-cards__grid[data-tablet='2'] { grid-template-columns: repeat(2, minmax(0, 1fr)); }
+  }
+  @media (min-width: 60em) {
+    .b-feature-cards__grid[data-cols='2'] { grid-template-columns: repeat(2, minmax(0, 1fr)); }
+    .b-feature-cards__grid[data-cols='3'] { grid-template-columns: repeat(3, minmax(0, 1fr)); }
+    .b-feature-cards__grid[data-cols='4'] { grid-template-columns: repeat(4, minmax(0, 1fr)); }
   }
   /* A solitary card is a centred feature, not a full-width slab. */
   .b-feature-cards__grid[data-single] { max-width: 26rem; margin-inline: auto;
   }
-  @media (min-width: 64em) {
-    .b-feature-cards__grid[data-cols='4'] { grid-template-columns: repeat(4, 1fr); }
-  }
   .b-feature-cards__icon {
     color: var(--gold);
     margin-bottom: 0.5rem;

package/components/recipes/Form.astro

@@ -7,7 +7,7 @@
  */
 import ContactForm from './ContactForm.astro';
 import { loadFormDefinition } from '../../lib/forms';
-import { resolveGitBase } from '../../bin/cms-config.mjs';
+import { resolveGitBase } from '../../lib/git-base.mjs';
 
 interface Props {
   form: string;

package/components/recipes/MediaCards.astro

@@ -9,6 +9,7 @@
  * when `href` is set. Token-driven, equal-height.
  */
 import Icon from '../Icon.astro';
+import { gridColumns } from '../../lib/gridColumns';
 import { isIconKey } from '../../lib/icons';
 import Heading from '../blocks/Heading.astro';
 
@@ -31,7 +32,7 @@ interface Props {
 }
 const { title, intro, columns = 3, ratio = '16/9', cards = [] } = Astro.props;
 // Never reserve more columns than there are cards; `data-single` centres a lone one.
-const cols = Math.min(columns, Math.max(cards.length, 1)) as 1 | 2 | 3;
+const { tablet, desktop: cols } = gridColumns(cards.length, columns); // never a short last row
 ---
 
 <section class="b-media-cards">
@@ -41,7 +42,7 @@ const cols = Math.min(columns, Math.max(cards.length, 1)) as 1 | 2 | 3;
       {intro && <p class="b-media-cards__intro" set:html={inlineMarkdown(intro)} />}
     </div>
   )}
-  <div class="b-media-cards__grid" data-cols={cols} data-single={cards.length === 1 ? 'true' : undefined}>
+  <div class="b-media-cards__grid" data-cols={cols} data-tablet={tablet} data-single={cards.length === 1 ? 'true' : undefined}>
     {cards.map((card) => {
       // Surface a mailto:/tel: as visible, copyable text — a plain mailto does
       // nothing on a device with no mail app, so the address must be readable too.
@@ -104,12 +105,15 @@ const cols = Math.min(columns, Math.max(cards.length, 1)) as 1 | 2 | 3;
   }
   /* A solitary card is a centred feature, not a full-width slab. */
   .b-media-cards__grid[data-single] { max-width: 28rem; margin-inline: auto; }
+  /* Never a short last row (lib/gridColumns): twos on tablet for an even count; on desktop
+     everything in one row, or even rows. Phones stay one column. */
   @media (min-width: 40em) {
-    .b-media-cards__grid[data-cols='2'] { grid-template-columns: repeat(2, 1fr); }
-    .b-media-cards__grid[data-cols='3'] { grid-template-columns: repeat(2, 1fr); }
+    .b-media-cards__grid[data-tablet='2'] { grid-template-columns: repeat(2, minmax(0, 1fr)); }
   }
   @media (min-width: 60em) {
-    .b-media-cards__grid[data-cols='3'] { grid-template-columns: repeat(3, 1fr); }
+    .b-media-cards__grid[data-cols='2'] { grid-template-columns: repeat(2, minmax(0, 1fr)); }
+    .b-media-cards__grid[data-cols='3'] { grid-template-columns: repeat(3, minmax(0, 1fr)); }
+    .b-media-cards__grid[data-cols='4'] { grid-template-columns: repeat(4, minmax(0, 1fr)); }
   }
   .b-media-cards__card {
     position: relative;

package/components/recipes/Stats.astro

@@ -9,6 +9,7 @@
  *  at any count and in either theme. Labels are width-capped so a long caption
  *  wraps to a tidy block rather than a full-width line. */
 import Heading from '../blocks/Heading.astro';
+import { gridColumns } from '../../lib/gridColumns';
 
 interface Item { value: string; label: string; description?: string }
 interface Props {
@@ -25,7 +26,7 @@ const { align: blockAlign, headingAlign } = Astro.props as { align?: 'start' | '
 const headAlign = headingAlign ?? blockAlign ?? 'center';
 // Cap the column count at the item count — one stat should never sit in a
 // two-column grid (half empty). Falls back to 1 for an empty list.
-const cols = Math.min(columns, Math.max(items.length, 1)) as 1 | 2 | 3 | 4;
+const { tablet, desktop: cols } = gridColumns(items.length, columns); // never a short last row
 ---
 
 <section class="b-stats" data-bg={background}>
@@ -36,7 +37,7 @@ const cols = Math.min(columns, Math.max(items.length, 1)) as 1 | 2 | 3 | 4;
         {intro && <p class="b-stats__intro">{intro}</p>}
       </div>
     )}
-    <div class="b-stats__grid" data-cols={cols}>
+    <div class="b-stats__grid" data-cols={cols} data-tablet={tablet}>
       {items.map((item) => (
         <div class="b-stats__item ferst-tile">
           <span class="b-stats__value">{item.value}</span>
@@ -75,12 +76,13 @@ const cols = Math.min(columns, Math.max(items.length, 1)) as 1 | 2 | 3 | 4;
     width: 100%;
     margin-inline: auto;
   }
+  /* Never a short last row (lib/gridColumns): twos on tablet for an even count; on desktop
+     everything in one row, or even rows. Phones stay one column. */
   @media (min-width: 40em) {
-    .b-stats__grid[data-cols='2'] { grid-template-columns: repeat(2, minmax(0, 1fr)); }
-    .b-stats__grid[data-cols='3'] { grid-template-columns: repeat(2, minmax(0, 1fr)); }
-    .b-stats__grid[data-cols='4'] { grid-template-columns: repeat(2, minmax(0, 1fr)); }
+    .b-stats__grid[data-tablet='2'] { grid-template-columns: repeat(2, minmax(0, 1fr)); }
   }
   @media (min-width: 60em) {
+    .b-stats__grid[data-cols='2'] { grid-template-columns: repeat(2, minmax(0, 1fr)); }
     .b-stats__grid[data-cols='3'] { grid-template-columns: repeat(3, minmax(0, 1fr)); }
     .b-stats__grid[data-cols='4'] { grid-template-columns: repeat(4, minmax(0, 1fr)); }
   }

package/components/recipes/Tiles.astro

@@ -14,6 +14,7 @@
  * Composes the Icon primitive.
  */
 import Heading from '../blocks/Heading.astro';
+import { gridColumns } from '../../lib/gridColumns';
 import Icon from '../Icon.astro';
 import { isIconKey } from '../../lib/icons';
 
@@ -43,7 +44,7 @@ const ItemHeading = title ? 'h3' : 'h2';
 const { align: blockAlign, headingAlign } = Astro.props as { align?: 'start' | 'center' | 'end'; headingAlign?: 'start' | 'center' | 'end' };
 const headAlign = headingAlign ?? blockAlign ?? 'center';
 // Never reserve more columns than there are tiles; `data-single` centres a lone one.
-const cols = Math.min(columns, Math.max(tiles.length, 1)) as 1 | 2 | 3 | 4;
+const { tablet, desktop: cols } = gridColumns(tiles.length, columns); // never a short last row
 ---
 
 <section class="b-tiles">
@@ -53,7 +54,7 @@ const cols = Math.min(columns, Math.max(tiles.length, 1)) as 1 | 2 | 3 | 4;
       {intro && <p class="b-tiles__intro" set:html={inlineMarkdown(intro)} />}
     </div>
   )}
-  <div class="b-tiles__grid" data-cols={cols} data-single={tiles.length === 1 ? 'true' : undefined} data-variant={variant} data-spotlight={spotlight ? 'true' : 'false'}>
+  <div class="b-tiles__grid" data-cols={cols} data-tablet={tablet} data-single={tiles.length === 1 ? 'true' : undefined} data-variant={variant} data-spotlight={spotlight ? 'true' : 'false'}>
     {tiles.map((tile) => {
       const Tag = tile.href ? 'a' : 'div';
       // A picture tile: an image with no words, shown WHOLE as a real <img> (posters,
@@ -114,13 +115,15 @@ const cols = Math.min(columns, Math.max(tiles.length, 1)) as 1 | 2 | 3 | 4;
   }
   /* A solitary tile is a centred feature, not a full-width slab. */
   .b-tiles__grid[data-single] { max-width: 26rem; margin-inline: auto; }
-  @media (min-width: 48em) {
-    .b-tiles__grid[data-cols='2'] { grid-template-columns: repeat(2, 1fr); }
-    .b-tiles__grid[data-cols='3'] { grid-template-columns: repeat(3, 1fr); }
-    .b-tiles__grid[data-cols='4'] { grid-template-columns: repeat(2, 1fr); }
-  }
-  @media (min-width: 64em) {
-    .b-tiles__grid[data-cols='4'] { grid-template-columns: repeat(4, 1fr); }
+  /* Never a short last row (lib/gridColumns): twos on tablet for an even count; on desktop
+     everything in one row, or even rows. Phones stay one column. */
+  @media (min-width: 40em) {
+    .b-tiles__grid[data-tablet='2'] { grid-template-columns: repeat(2, minmax(0, 1fr)); }
+  }
+  @media (min-width: 60em) {
+    .b-tiles__grid[data-cols='2'] { grid-template-columns: repeat(2, minmax(0, 1fr)); }
+    .b-tiles__grid[data-cols='3'] { grid-template-columns: repeat(3, minmax(0, 1fr)); }
+    .b-tiles__grid[data-cols='4'] { grid-template-columns: repeat(4, minmax(0, 1fr)); }
   }
 
   /* Base tile — radius/stroke/shadow all from the global surface tokens. */

package/lib/git-base.mjs

@@ -0,0 +1,62 @@
+/**
+ * The platform git-proxy origin for this build (the CMS `base_url`, and where the Form block
+ * reads a form's fields). Kept apart from bin/cms-config.mjs so components can import it: that
+ * file is a build-time script whose module scope needs a real filesystem, which an on-request
+ * renderer (Cloudflare Workers) doesn't have. Nothing here runs at import time.
+ */
+import { readFileSync } from 'node:fs';
+import { execSync } from 'node:child_process';
+import { resolve } from 'node:path';
+
+function env(name) {
+  const v = typeof process !== 'undefined' ? process.env?.[name] : undefined;
+  return v && v.trim() ? v.trim() : '';
+}
+
+export const PROD_GIT_BASE = 'https://signin.ferst.co.uk';
+export const DEV_GIT_BASE = 'https://signin-dev.ferst.co.uk';
+
+/**
+ * The platform git-proxy origin (CMS `base_url` / `api_root`) for THIS build:
+ *   1. `FERST_GIT_BASE` env — explicit override, always wins.
+ *   2. committed `ferst-site.json` `gitBase` — an explicit per-site pin (e.g. a
+ *      custom proxy); a BYO/seeded site can hard-bind its origin this way.
+ *   3. otherwise DERIVE from the deploy environment: the production branch talks to
+ *      the prod git-proxy, every other (preview/dev) branch talks to the dev
+ *      git-proxy. So a templated repo self-configures per environment on deploy — a
+ *      dev-branch build points its CMS at the dev worker and main at prod — with NO
+ *      per-client config. (The production branch defaults to `main`; override via
+ *      `FERST_PROD_BRANCH` env or `ferst-site.json` `productionBranch`.)
+ * This restores the "site respects the environment it's deployed in" binding the old
+ * per-branch site config gave, without a per-client file to maintain.
+ */
+export function resolveGitBase(cwd = process.cwd(), branch = deploymentBranch()) {
+  const fromEnv = env('FERST_GIT_BASE');
+  if (fromEnv) return fromEnv;
+  let prodBranch = env('FERST_PROD_BRANCH') || 'main';
+  try {
+    const site = JSON.parse(readFileSync(resolve(cwd, 'ferst-site.json'), 'utf8'));
+    if (site && typeof site.gitBase === 'string' && site.gitBase.trim()) return site.gitBase.trim();
+    if (!env('FERST_PROD_BRANCH') && site && typeof site.productionBranch === 'string' && site.productionBranch.trim()) {
+      prodBranch = site.productionBranch.trim();
+    }
+  } catch {
+    /* no ferst-site.json (e.g. the template repo itself) — derive from the branch */
+  }
+  return branch === prodBranch ? PROD_GIT_BASE : DEV_GIT_BASE;
+}
+
+/** The deployment branch: CF Pages env → current git branch → main. */
+export function deploymentBranch() {
+  const cf = env('CF_PAGES_BRANCH');
+  if (cf) return cf;
+  try {
+    const git = execSync('git rev-parse --abbrev-ref HEAD', {
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).toString().trim();
+    if (git && git !== 'HEAD') return git;
+  } catch {
+    /* not a git checkout — fall through */
+  }
+  return 'main';
+}

package/lib/gridColumns.ts

@@ -0,0 +1,22 @@
+/**
+ * How many columns a grid of cards or numbers uses, so the last row is never short.
+ * - **Desktop:** everything in one row when it fits within `max`; otherwise the widest column
+ *   count up to `max` that divides the items evenly; failing that, `max`.
+ * - **Tablet:** twos for an even count, one column for an odd one (an odd count sits in one row
+ *   on desktop and one column below it, never 2 + 1).
+ * - **Phones:** always one column (the recipes' base style).
+ */
+export interface GridColumns { tablet: 1 | 2; desktop: number }
+
+export function gridColumns(count: number, max: number): GridColumns {
+  if (count <= 1) return { tablet: 1, desktop: 1 };
+  let desktop = max;
+  if (count <= max) desktop = count;
+  else {
+    for (let c = max; c >= 2; c--) {
+      if (count % c === 0) { desktop = c; break; }
+    }
+  }
+  const tablet = desktop > 1 && count % 2 === 0 ? 2 : 1;
+  return { tablet, desktop };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ferst-core",
-  "version": "0.9.6",
+  "version": "0.9.8",
   "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",