ferst-core 0.9.7 → 0.9.9

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/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/content/recipe-questions.ts

@@ -0,0 +1,78 @@
+/**
+ * Setup questions, kept with the recipes. When a client sets up a page from a design, each
+ * section of the design asks one free-flowing question; the answer is a paragraph in the client's
+ * own words, from which the section is filled. Deliberately not a field-by-field form: the
+ * recipe decides how the words are laid out, so the client only has to say what they mean.
+ *
+ * - `ask`: the question, a hint, and a plain name for the section.
+ * - `note`: the section fills itself (from the platform or the site), so nothing is asked.
+ * - `null`: spacing and layout pieces, which have no content of their own (containers are
+ *   walked into by the caller).
+ *
+ * Generic wording only. How questions are ordered and combined into a request lives with the
+ * platform.
+ */
+export type RecipeQuestion =
+  | { kind: 'ask'; label: string; question: string; hint: string }
+  | { kind: 'note'; label: string; note: string };
+
+const ask = (label: string, question: string, hint: string): RecipeQuestion => ({ kind: 'ask', label, question, hint });
+const note = (label: string, text: string): RecipeQuestion => ({ kind: 'note', label, note: text });
+
+const QUESTIONS: Record<string, RecipeQuestion | null> = {
+  // Recipes
+  hero: ask('Opening banner', 'What should the first thing visitors see say?', 'Your main message in your own words, a supporting line, and where the main button should take people.'),
+  featureCards: ask('Highlights', 'What are the main things you want to highlight here?', 'Describe each one in a sentence or two, and say where each should lead if people want more.'),
+  cta: ask('Call to action', 'What do you most want visitors to do next?', 'For example: book, call, visit, sign up. Say it the way you would to a customer.'),
+  faq: ask('Questions and answers', 'What do people often ask you, and how do you answer?', 'Write each question with your usual answer. As many as you like.'),
+  gallery: ask('Photo gallery', 'What should these photos show?', 'Describe the pictures you have or want: your work, your place, your people. You can upload them in the content editor.'),
+  testimonial: ask('What people say', 'What have customers said about you?', 'Paste a kind word or review, with the person’s name or initials if they’re happy to be named.'),
+  contactForm: ask('Contact form', 'What should people be able to ask you through this form?', 'Who answers, what you need to know from them, and how soon they can expect a reply.'),
+  form: note('Form', 'This shows one of your organisation’s forms. Choose or create it in the portal under Forms.'),
+  accordion: ask('Expandable sections', 'What information should people be able to open up and read here?', 'Give each topic a short heading and the detail that goes under it.'),
+  tiles: ask('Quick links', 'Where do visitors most often want to go from here?', 'List the places or tasks, a few words each, for example: opening times, book now, prices.'),
+  banner: ask('Banner', 'What message deserves a bold band across the page?', 'A short statement or invitation, and where it should lead if anywhere.'),
+  stats: ask('Key numbers', 'Which numbers say something good about you?', 'Years running, people helped, places served: the number and what it means.'),
+  steps: ask('How it works', 'What are the steps someone goes through with you?', 'From first contact to finished, in your own words, in order.'),
+  pricing: ask('Prices', 'What do you charge, and what does each option include?', 'List each option with its price and what someone gets. Say if prices start “from”.'),
+  logos: ask('Logos', 'Whose logos should appear here?', 'Partners, accreditations or clients you are proud to show. You can upload the images in the content editor.'),
+  tabs: ask('Tabbed information', 'What information would people like to switch between here?', 'Name each topic and what it should say.'),
+  announcement: ask('Announcement', 'Is there a short announcement visitors should see?', 'One or two sentences: news, a change to times, an offer. Leave it blank if not.'),
+  bento: ask('Feature panels', 'What would you show off in a set of feature panels?', 'Your strongest points, products or moments, a sentence or two each.'),
+  marquee: ask('Scrolling line', 'What short words or phrases should scroll across here?', 'Things you offer, places you serve, or values, a few words each.'),
+  latestPosts: note('Latest posts', 'This shows your newest posts automatically. Write posts in the content editor.'),
+  mapEmbed: ask('Map', 'Where should the map show?', 'The address or place name, and anything about finding you or parking.'),
+  table: ask('Table', 'What information belongs in a table here?', 'Describe the rows and columns, or paste the details as you have them.'),
+  notice: ask('Notice', 'What notice should stand out on this page?', 'An important point people must not miss, in a sentence or two.'),
+  mediaCards: ask('Picture cards', 'What should each picture card show and say?', 'For each one: what the picture is, a short title and a line of text.'),
+  contactCard: ask('Contact details', 'How would you like people to reach you?', 'Phone, email, address and opening hours, as you want them shown.'),
+  locations: ask('Locations', 'Which places should be listed?', 'Each place with its address and anything visitors should know.'),
+  video: ask('Video', 'Which video should play here, and what is it about?', 'A link to the video (for example YouTube) and a line about it.'),
+  documents: ask('Documents', 'Which documents should people be able to open or download?', 'List each with a short description. You can upload the files in the content editor.'),
+  linkRow: ask('Links', 'Which links should sit together here?', 'Each link’s words and where it goes.'),
+  document: ask('Document', 'Which document should be shown here?', 'What it is and who it is for. You can upload the file in the content editor.'),
+  timetable: ask('Timetable', 'What happens when?', 'The days and times, and what is on at each. Say if it changes through the year.'),
+  contacts: ask('People to contact', 'Who should people contact, and about what?', 'Each person or role, what they help with, and how to reach them.'),
+  mediaText: ask('Picture with text', 'What should this picture and its words tell people?', 'Describe the picture and write the words that go beside it.'),
+  // Leaves and primitives
+  heading: ask('Heading', 'What should this heading say?', 'A few words that introduce what comes next.'),
+  prose: ask('Text', 'What should this text say?', 'Write it as you would explain it to a visitor. The more you give, the better the result.'),
+  image: ask('Picture', 'What should this picture show?', 'Describe it, or say which of your photos to use. You can upload it in the content editor.'),
+  button: ask('Button', 'What should this button say, and where should it take people?', 'A few words for the button and the page or address it opens.'),
+  quote: ask('Quote', 'What quote belongs here, and who said it?', 'The words and the person, if they are happy to be named.'),
+  list: ask('List', 'What should this list contain?', 'One item per line, in the order you want them.'),
+  stat: ask('Number', 'Which number should stand out here, and what does it mean?', 'The figure and a few words about it.'),
+  badge: ask('Label', 'What short label belongs here?', 'One to three words, for example: New, Open now, Since 1998.'),
+  divider: null,
+  spacer: null,
+  section: null,
+  grid: null,
+  stack: null,
+};
+
+const GENERAL = ask('Section', 'What should this section say?', 'Describe what it is for and the words you want in it.');
+
+/** The setup question for a block type; `null` for spacing and layout pieces. */
+export function recipeQuestion(type: string): RecipeQuestion | null {
+  return type in QUESTIONS ? QUESTIONS[type] : GENERAL;
+}

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.7",
+  "version": "0.9.9",
   "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",