ferst-core 0.9.8 → 0.10.0

package/bin/ferst-modules.mjs

@@ -7,7 +7,7 @@
 //   npx --no-install ferst-modules --json          # the raw answer
 //
 // Forms and calendars live in the portal, never in the repo: place a form with a
-// `{ "type": "form", "form": "<id>" }` block, and show the calendar by setting
+// `{ "type": "form", "form": "<its name on this site>" }` block, and show the calendar by setting
 // calendarSettings.embedUrl to the address printed here.
 import { readFileSync, realpathSync } from 'node:fs';
 import { resolve } from 'node:path';
@@ -46,7 +46,7 @@ export function formatModules(data) {
   else if (data.forms.length === 0) out.push('  No forms yet. They are created in the portal (Forms).');
   for (const f of data.forms) {
     out.push(`  ${f.name}`);
-    out.push(`    place it with: { "type": "form", "form": "${f.id}" }`);
+    out.push(`    place it with: { "type": "form", "form": "${f.slot ?? f.id}" }`);
     out.push(`    fields: ${f.fields.map((x) => `${x.label}${x.required ? ' *' : ''}`).join(', ') || '(none)'}`);
     out.push(`    button: ${f.submitLabel}`);
   }

package/components/recipes/Form.astro

@@ -1,13 +1,14 @@
 ---
 /**
- * Form — one of the organisation's forms from the Ferst portal, placed by id. Reads the
- * form's fields, button and submit address from the platform at build time (lib/forms)
- * and renders it with the ContactForm recipe, so it looks like every other form and a
- * change made in the portal reaches the site on its next build.
+ * Form — one of the organisation's forms from the Ferst portal, placed by its name on this site
+ * (its slot; older pages give its id). Reads the form's fields, button and submit address from the
+ * platform at build time, through the site (lib/forms), and renders it with the ContactForm recipe,
+ * so it looks like every other form and a change made in the portal reaches the site on its next
+ * build.
  */
 import ContactForm from './ContactForm.astro';
 import { loadFormDefinition } from '../../lib/forms';
-import { resolveGitBase } from '../../lib/git-base.mjs';
+import { resolveGitBase, resolveSiteId } from '../../lib/git-base.mjs';
 
 interface Props {
   form: string;
@@ -16,7 +17,7 @@ interface Props {
   note?: string;
 }
 const { form, title, intro, note } = Astro.props;
-const def = await loadFormDefinition(form, { base: resolveGitBase() });
+const def = await loadFormDefinition(form, { base: resolveGitBase(), siteId: resolveSiteId() });
 ---
 
 <ContactForm

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/forms.ts

@@ -1,8 +1,15 @@
 /**
- * A form placed by id (the `form` block) is read from the Ferst platform at build time, so
+ * A form placed on a page (the `form` block) is read from the Ferst platform at build time, so
  * a change made to it in the portal reaches the site on its next build — no pasted copy of
  * its fields to keep in step. A missing form or an unreachable platform fails the build:
  * better the last good deploy stays live than a form that can't be sent goes out.
+ *
+ * The block names the form by its name on this site — its slot — and the site says who it is
+ * (`siteId` in ferst-site.json): the platform answers with whichever of the organisation's forms
+ * fills that slot, and the form posts to the site's own address for it. So the organisation can
+ * swap, copy or move forms without anyone editing the site. Pages from before slots name a form
+ * by its id, which still answers; a platform that doesn't know the site (a site id from another
+ * environment) falls back to the form's id.
  */
 export interface FormField {
   name: string;
@@ -24,17 +31,35 @@ type FetchFn = (input: string, init?: RequestInit) => Promise<Response>;
 
 const cache = new Map<string, Promise<FormDefinition>>();
 
-export function loadFormDefinition(id: string, opts: { base: string; fetch?: FetchFn }): Promise<FormDefinition> {
-  const key = `${opts.base}|${id}`;
+export function loadFormDefinition(ref: string, opts: { base: string; siteId?: string | null; fetch?: FetchFn }): Promise<FormDefinition> {
+  const key = `${opts.base}|${opts.siteId ?? ''}|${ref}`;
   let hit = cache.get(key);
   if (!hit) {
-    hit = fetchDefinition(id, opts.base, opts.fetch ?? fetch);
+    hit = opts.siteId ? fetchThroughSite(ref, opts.siteId, opts.base, opts.fetch ?? fetch) : fetchDefinition(ref, opts.base, opts.fetch ?? fetch);
     cache.set(key, hit);
     hit.catch(() => cache.delete(key)); // a failure is retried by the next caller
   }
   return hit;
 }
 
+async function fetchThroughSite(slot: string, siteId: string, base: string, fetchFn: FetchFn): Promise<FormDefinition> {
+  const url = `${base}/sites/${encodeURIComponent(siteId)}/forms/${encodeURIComponent(slot)}`;
+  let res: Response;
+  try {
+    res = await fetchFn(url, { headers: { Accept: 'application/json' } });
+  } catch (e) {
+    throw new Error(`Form block: couldn’t reach the Ferst platform for form "${slot}" (${url}): ${e instanceof Error ? e.message : String(e)}`);
+  }
+  if (res.status === 404) {
+    const body = (await res.json().catch(() => ({}))) as { error?: string };
+    if (body.error === 'site_not_found') return fetchDefinition(slot, base, fetchFn);
+    throw new Error(`Form block: form "${slot}" isn’t on this site. Check its name on the site in the portal (Forms → Place on a site), or run \`npx ferst-modules\` to list this site's forms.`);
+  }
+  if (!res.ok) throw new Error(`Form block: the Ferst platform answered ${res.status} for form "${slot}" (${url}).`);
+  const def = (await res.json()) as { name: string; submit_label?: string; fields?: FormField[]; action: string };
+  return { name: def.name, submitLabel: def.submit_label || 'Send', fields: def.fields ?? [], action: def.action };
+}
+
 async function fetchDefinition(id: string, base: string, fetchFn: FetchFn): Promise<FormDefinition> {
   const url = `${base}/forms/${encodeURIComponent(id)}`;
   let res: Response;

package/lib/git-base.mjs

@@ -46,6 +46,21 @@ export function resolveGitBase(cwd = process.cwd(), branch = deploymentBranch())
   return branch === prodBranch ? PROD_GIT_BASE : DEV_GIT_BASE;
 }
 
+/**
+ * Who this site is on the Ferst platform: `FERST_SITE_ID` env, else ferst-site.json's `siteId`
+ * (written when the site was set up), else null. The Form block asks for its forms through it.
+ */
+export function resolveSiteId(cwd = process.cwd()) {
+  const fromEnv = env('FERST_SITE_ID');
+  if (fromEnv) return fromEnv;
+  try {
+    const site = JSON.parse(readFileSync(resolve(cwd, 'ferst-site.json'), 'utf8'));
+    return site && typeof site.siteId === 'string' && site.siteId.trim() ? site.siteId.trim() : null;
+  } catch {
+    return null;
+  }
+}
+
 /** The deployment branch: CF Pages env → current git branch → main. */
 export function deploymentBranch() {
   const cf = env('CF_PAGES_BRANCH');

package/package.json

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