@tideworthy/tidysites-platform 0.10.15 → 0.11.0

package/src/sections/lib.ts

@@ -0,0 +1,157 @@
+/** Helpers every section component shares: reading a stored block, images, lists, and the business record. */
+import { getEmDashCollection, getSiteSettings } from "emdash";
+
+export type Node = Record<string, unknown>;
+
+/** A section component receives the stored block as `value`; a Portable Text renderer passes `node`; accept both or the props themselves. */
+export function nodeOf(props: Record<string, unknown>): Node {
+	return (props.value as Node | undefined) ?? (props.node as Node | undefined) ?? props;
+}
+export const str = (v: unknown, fallback = ""): string => (typeof v === "string" ? v : fallback);
+export const bool = (v: unknown, fallback = false): boolean => (typeof v === "boolean" ? v : typeof v === "number" ? v !== 0 : fallback);
+export const int = (v: unknown, fallback: number): number => (typeof v === "number" && Number.isFinite(v) ? Math.floor(v) : fallback);
+export const num = (v: unknown): number | null => (typeof v === "number" && Number.isFinite(v) ? v : typeof v === "string" && v.trim() && Number.isFinite(Number(v)) ? Number(v) : null);
+export const lines = (v: unknown): string[] => str(v).split("\n").map((s) => s.trim()).filter(Boolean);
+export const list = <T = Record<string, unknown>>(v: unknown): T[] => (Array.isArray(v) ? (v as T[]) : []);
+export const slugify = (s: string): string => s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+
+/** An image field's value: a media value, or a plain URL left from an older site. */
+export type Pic = { image: { id?: string; src?: string; alt?: string; width?: number; height?: number } | null; url: string | null };
+export function pic(v: unknown): Pic {
+	if (typeof v === "string") return { image: null, url: v || null };
+	if (v && typeof v === "object") {
+		const o = v as { id?: string; src?: string; url?: string; alt?: string; width?: number; height?: number; meta?: { storageKey?: string } };
+		if (o.id || o.src) return { image: o, url: null };
+		const url = o.url ?? (o.meta?.storageKey ? `/_emdash/api/media/file/${o.meta.storageKey}` : null);
+		return { image: null, url };
+	}
+	return { image: null, url: null };
+}
+export const hasPic = (v: unknown): boolean => { const p = pic(v); return Boolean(p.image || p.url); };
+
+/** "Label: value" lines into pairs. */
+export function facts(v: unknown): Array<[string, string]> {
+	return lines(v).map((l) => { const i = l.indexOf(":"); return i > 0 ? [l.slice(0, i).trim(), l.slice(i + 1).trim()] : ["", l]; });
+}
+/** "Title|Text" lines into steps. */
+export function steps(v: unknown): Array<{ title: string; text: string }> {
+	return lines(v).map((l) => { const i = l.indexOf("|"); return i > 0 ? { title: l.slice(0, i).trim(), text: l.slice(i + 1).trim() } : { title: l, text: "" }; });
+}
+export function telHref(phone: string): string {
+	const digits = phone.replace(/[^\d+]/g, "");
+	if (!digits) return "";
+	return `tel:${digits.startsWith("+") ? digits : digits.length === 10 ? `+1${digits}` : digits}`;
+}
+
+/** An entry from a collection read, as the sections see it. */
+export interface Entry { id: string; slug?: string | null; data: Record<string, unknown> }
+type Query = { status?: "published" | "draft"; limit?: number; orderBy?: Record<string, "asc" | "desc">; where?: Record<string, string> };
+
+/** Published entries of a collection, sorted by `sort` when the collection has it; empty when the collection is missing on an older site. */
+export async function entries(collection: string, q: Query = {}): Promise<Entry[]> {
+	try {
+		const r = await getEmDashCollection(collection, { status: "published", orderBy: { sort: "asc" }, ...q } as never);
+		return ((r as { entries?: Entry[] }).entries ?? []) as Entry[];
+	} catch {
+		return [];
+	}
+}
+/** Entries that pass a where filter plus an in-memory predicate (EmDash filters take strings only). */
+export async function entriesWhere(collection: string, where: Record<string, string>, q: Query = {}): Promise<Entry[]> {
+	return entries(collection, Object.keys(where).length ? { ...q, where } : q);
+}
+export const field = (e: Entry, k: string): string => str(e.data[k]);
+
+/** The business record, normalized to what sections and layouts read. Field names follow the template; older pest-era names are read too. */
+export interface Business {
+	id: string | null;
+	title: string; tagline: string;
+	phone: string; phoneHref: string; phoneText: string; phoneTextHref: string; fax: string; email: string;
+	address: string; city: string; region: string; postal: string; country: string; hideAddress: boolean; isServiceArea: boolean;
+	hours: string; hoursNote: string;
+	foundedYear: number | null; yearsLine: string; sinceLine: string | null;
+	rating: number | null; reviewCount: number | null; ratingSource: string; reviewsUrl: string;
+	bookingUrl: string; bookingLabel: string; portalUrl: string; formsUrl: string; storeUrl: string; storeLabel: string; ctaLabel: string;
+	languages: string; newPatientsLine: string; neighbourhoods: string; serviceAreaLine: string; sameDayLine: string; emergencyLine: string;
+	insuranceLine: string; governmentPrograms: string; hsaFsaLine: string; licenseLine: string; insuredLine: string; warrantyLine: string; accessibilityLine: string; parkingLine: string; directionsLine: string;
+	social: Array<{ network: string; url: string }>;
+	brandPrimary: string; brandAccent: string; fontDisplay: string; fontBody: string;
+	logo: { src: string; alt?: string; width?: number; height?: number } | null;
+	ga4Id: string; gtmId: string; customCss: string;
+	raw: Record<string, unknown>;
+}
+const NETWORKS = ["facebook", "instagram", "google", "youtube", "linkedin", "tiktok", "yelp"];
+function mediaSrc(v: unknown): Business["logo"] {
+	const p = pic(v);
+	if (p.image?.src) return { src: p.image.src, alt: p.image.alt, width: p.image.width, height: p.image.height };
+	if (p.image && (p.image as { meta?: { storageKey?: string } }).meta?.storageKey) return { src: `/_emdash/api/media/file/${(p.image as { meta: { storageKey: string } }).meta.storageKey}`, alt: p.image.alt };
+	if (p.url) return { src: p.url };
+	return null;
+}
+async function readBusiness(): Promise<Business> {
+	let d: Record<string, unknown> = {}; let id: string | null = null; let siteTitle = "";
+	try { const s = (await getSiteSettings()) as { title?: string } | null; siteTitle = s?.title ?? ""; } catch { /* no settings yet */ }
+	try {
+		const r = await getEmDashCollection("business", { status: "published", limit: 1 } as never);
+		const e = ((r as { entries?: Entry[] }).entries ?? [])[0];
+		if (e) { d = e.data; id = e.id; }
+	} catch { /* collection missing on an older site */ }
+	const s = (k: string, alt?: string) => str(d[k]) || (alt ? str(d[alt]) : "");
+	const phone = s("phone"); const phoneText = s("phone_text");
+	const founded = num(d.founded_year);
+	const city = s("city");
+	const primary = s("brand_primary") || "#1e5a46"; const accent = s("brand_accent") || "#e8b23a";
+	return {
+		id, title: s("title") || siteTitle || "Our business", tagline: s("tagline"),
+		phone, phoneHref: telHref(phone), phoneText, phoneTextHref: phoneText ? `sms:${phoneText.replace(/[^\d+]/g, "")}` : "", fax: s("fax"), email: s("email"),
+		address: s("address"), city, region: s("region"), postal: s("postal"), country: s("country"), hideAddress: bool(d.hide_address), isServiceArea: bool(d.is_service_area_business),
+		hours: s("hours"), hoursNote: s("hours_note"),
+		foundedYear: founded, yearsLine: s("years_line"), sinceLine: city && founded ? `${city} since ${founded}` : city || null,
+		rating: num(d.rating), reviewCount: num(d.review_count), ratingSource: s("rating_source") || "Google", reviewsUrl: s("reviews_url"),
+		bookingUrl: s("booking_url"), bookingLabel: s("booking_label") || "Book online", portalUrl: s("portal_url"), formsUrl: s("forms_url"), storeUrl: s("store_url"), storeLabel: s("store_label") || "Shop", ctaLabel: s("cta_label") || "Get in touch",
+		languages: s("languages"), newPatientsLine: s("new_patients_line"), neighbourhoods: s("neighbourhoods"), serviceAreaLine: s("service_area_line"), sameDayLine: s("same_day_line", "same_day_note"), emergencyLine: s("emergency_line"),
+		insuranceLine: s("insurance_line"), governmentPrograms: s("government_programs"), hsaFsaLine: s("hsa_fsa_line"), licenseLine: s("license_line"), insuredLine: s("insured_line"), warrantyLine: s("warranty_line"), accessibilityLine: s("accessibility_line"), parkingLine: s("parking_line"), directionsLine: s("directions_line"),
+		social: NETWORKS.map((n) => ({ network: n, url: s(n) })).filter((x) => x.url),
+		brandPrimary: primary, brandAccent: accent, fontDisplay: s("font_display") || "Bricolage Grotesque", fontBody: s("font_body") || "Public Sans",
+		logo: mediaSrc(d.logo), ga4Id: s("ga4_id"), gtmId: s("gtm_id"), customCss: s("custom_css"), raw: d,
+	};
+}
+const memo = new WeakMap<Request, Promise<Business>>();
+/** One read per request, however many sections ask. */
+export function getBusiness(request: Request): Promise<Business> {
+	let p = memo.get(request);
+	if (!p) { p = readBusiness(); memo.set(request, p); }
+	return p;
+}
+/** Text contrast for a background colour. */
+export function inkFor(hex: string): string {
+	const m = /^#?([0-9a-f]{6})$/i.exec(hex); if (!m) return "#ffffff";
+	const n = parseInt(m[1]!, 16); const r = (n >> 16) & 255, g = (n >> 8) & 255, b = n & 255;
+	return (0.299 * r + 0.587 * g + 0.114 * b) / 255 > 0.6 ? "#111111" : "#ffffff";
+}
+/** Inline style for <html>: the brand tokens from the business record. */
+export function brandStyle(b: Business): string {
+	const font = (name: string, fallback: string) => `"${name.replace(/"/g, "")}", ${fallback}`;
+	return [`--brand-primary:${b.brandPrimary}`, `--brand-primary-ink:${inkFor(b.brandPrimary)}`, `--brand-accent:${b.brandAccent}`, `--brand-accent-ink:${inkFor(b.brandAccent)}`, `--brand-font-display:${font(b.fontDisplay, "Arial, sans-serif")}`, `--brand-font-body:${font(b.fontBody, '"Helvetica Neue", Arial, sans-serif')}`].join(";");
+}
+/** Google Fonts stylesheet for the two brand families. */
+export function fontsHref(b: Business): string {
+	const fam = (name: string, axes: string) => `family=${encodeURIComponent(name).replace(/%20/g, "+")}:${axes}`;
+	return `https://fonts.googleapis.com/css2?${fam(b.fontDisplay, "wght@600;700;800")}&${fam(b.fontBody, "wght@400;500;600;700")}&display=swap`;
+}
+/** The one line of address a section prints. */
+export function addressLine(b: { address: string; city: string; region: string; postal: string; hideAddress?: boolean }): string {
+	if (b.hideAddress) return [b.city, b.region].filter(Boolean).join(", ");
+	return [b.address, [b.city, b.region].filter(Boolean).join(", "), b.postal].filter(Boolean).join(", ");
+}
+/** Hours rows of a location record (hours_mon..hours_sun), grouped when identical days follow each other. */
+export const DAYS: Array<[string, string]> = [["hours_mon", "Monday"], ["hours_tue", "Tuesday"], ["hours_wed", "Wednesday"], ["hours_thu", "Thursday"], ["hours_fri", "Friday"], ["hours_sat", "Saturday"], ["hours_sun", "Sunday"]];
+export function hoursRows(d: Record<string, unknown>): Array<{ day: string; value: string }> {
+	return DAYS.map(([k, day]) => ({ day, value: str(d[k]) })).filter((r) => r.value);
+}
+export function hoursGrouped(d: Record<string, unknown>): Array<{ days: string; value: string }> {
+	const rows = hoursRows(d); const out: Array<{ days: string[]; value: string }> = [];
+	for (const r of rows) { const last = out[out.length - 1]; if (last && last.value === r.value) last.days.push(r.day); else out.push({ days: [r.day], value: r.value }); }
+	return out.map((g) => ({ days: g.days.length > 2 ? `${g.days[0]} to ${g.days[g.days.length - 1]}` : g.days.join(" and "), value: g.value }));
+}
+export const todayKey = (): string => DAYS[(new Date().getDay() + 6) % 7]![0];

package/src/template/index.ts

@@ -0,0 +1,75 @@
+/**
+ * The Tidysites template: the one data shape every theme renders. The JSON
+ * at /template/structure.json is the source; this module gives it types and
+ * the merge a theme's seed goes through so a theme never carries a schema of
+ * its own (see template/README.md).
+ */
+import structure from "../../template/structure.json";
+
+export interface TemplateField {
+	slug: string;
+	label: string;
+	type: string;
+	required?: boolean;
+	validation?: Record<string, unknown>;
+	defaultValue?: unknown;
+	[k: string]: unknown;
+}
+export interface TemplateCollection {
+	slug: string;
+	label: string;
+	labelSingular: string;
+	supports?: string[];
+	fields: TemplateField[];
+	[k: string]: unknown;
+}
+export interface SectionType {
+	slug: string;
+	label: string;
+	description?: string;
+	category?: string;
+	currentVersion: number;
+	versions: Array<{ version: number; fields: TemplateField[] }>;
+}
+export interface TemplateMenu {
+	name: string;
+	label: string;
+	items: Array<Record<string, unknown>>;
+}
+export interface TemplateStructure {
+	$schema?: string;
+	version: string;
+	meta?: Record<string, unknown>;
+	blockTypes: SectionType[];
+	collections: TemplateCollection[];
+	menus?: TemplateMenu[];
+	relations?: unknown;
+}
+
+export const template = structure as unknown as TemplateStructure;
+/** Every section type a page may hold, in the template's order. */
+export const sectionTypes: SectionType[] = template.blockTypes;
+export const collections: TemplateCollection[] = template.collections;
+/** The section type slugs, for a theme that wants to check coverage. */
+export const SECTION_TYPES: string[] = sectionTypes.map((b) => b.slug);
+
+export function collection(slug: string): TemplateCollection | undefined {
+	return collections.find((c) => c.slug === slug);
+}
+export function sectionType(slug: string): SectionType | undefined {
+	return sectionTypes.find((b) => b.slug === slug);
+}
+
+/**
+ * A theme's seed with the template's structure in place of its own: the
+ * collections, block types and relations come from the template; the menus,
+ * settings, meta and content stay the theme's. A theme seed is content and
+ * menus; everything structural is this package's.
+ */
+export function mergeStructure<T extends Record<string, unknown>>(seed: T): T & Pick<TemplateStructure, "version" | "blockTypes" | "collections"> {
+	const { blockTypes: _b, collections: _c, relations: _r, ...rest } = seed as Record<string, unknown>;
+	const out: Record<string, unknown> = { ...rest, version: template.version, blockTypes: template.blockTypes, collections: template.collections };
+	if (template.relations !== undefined) out.relations = template.relations;
+	if (!out.menus && template.menus) out.menus = template.menus;
+	return out as T & Pick<TemplateStructure, "version" | "blockTypes" | "collections">;
+}

package/src/version.ts

@@ -1,3 +1,3 @@
 /** Kept in step with package.json by the release checklist in MAINTAINING.md. */
-export const VERSION = "0.10.15";
+export const VERSION = "0.11.0";
 export const PLUGIN_ID = "tidy-platform";

package/template/README.md

@@ -0,0 +1,33 @@
+# The Tidysites template
+
+One data shape, rendered by every theme. `structure.json` is the structure half of an EmDash seed: 24 collections, 35 section types, the two menus. No content, no design. It validates with EmDash's `validateSeed` (emdash 1.0.1).
+
+## The model
+
+- **There is one template.** Every site has every collection and every section type available. A dentist, a roofer, a bike shop with a repair bench and a marketing agency run the same schema; what differs is which records they fill and which sections their pages use.
+- **Everything is optional.** A record needs its name (a review needs its quote, a FAQ its answer, a policy its text). Every other field is optional, because that is what real sites showed: a date on one review in eleven, a price on no service page, bios on cards for some and on profile pages for others.
+- **The theme is the only choice.** A person picks a look and launches it. The theme decides which sections its pages use and how each renders. There are no profiles, presets or industry variants of the schema.
+- **A theme renders; it never adds.** A theme may render any field or section type here and may ignore any. It adds no fields and no section types of its own. When a theme needs something this template lacks, the template grows, additively, and every theme may render the new piece or ignore it. That rule is what lets a site switch themes without touching its content, and what lets a site owner's assistant add products, service areas or case studies to a site whose theme never showed them: the data has a home already.
+- **The plugin owes a default rendering of every section type** so that a section a theme never shipped still renders when an owner adds it, and the theme's own component takes over when it has one. Not built yet; it is the next piece.
+- **Live sites take template changes through the schema apply** (`POST /_tidy/schema`, run after every staging deploy). Definitions are updated or created, nothing is deleted. Retiring a field is a separate, deliberate step once no live site holds data in it.
+
+## What is in it
+
+Business and place: `business` (the one record every page reads: name, phones with purposes, address and whether to show it, hours in one line, booking, portal, forms and store links, languages, rating and count, insurance and programs lines, licence, insured and warranty lines, accessibility, parking, directions, emergency line, service-area line, social, brand tokens, analytics ids), `locations` (per-day hours, parking, directions, transit, map, booking per location; exists even for one location so growth is never a migration), `service_areas` (places served, with neighbourhoods, coordinates, distance, home base).
+
+What they do: `service_categories`, `services` (with a call-to-action kind, price from, duration, free consultation, in-season flag, providers through reviews and cases), `conditions` (what customers search for, pointing at the service that treats it), `technologies`, `products` (name, category, brand, price, images, variants, stock, buy or enquire link), `brands`.
+
+Who they are: `people` (role, group, credentials, licence, two bio lengths, education, memberships, awards, languages, pronouns, video, start year, status note, owner flag, own-page flag), `badges` (associations, certifications, awards and seals with issuer and year), `clients` (logo wall), `case_studies` (situation, approach, outcome, three result numbers, quote).
+
+Proof: `reviews` (quote, display name, rating, source, date, photo, service, service area, provider, video, featured), `cases` (before and after with problem and treatment).
+
+Money and admin: `plans` (memberships, packages, tiers, banked credit), `insurers` (network status, note, which services), `financing_providers`, `offers` (with how to claim and an end date), `downloads` (intake, consent, pre-op, post-op), `policies`.
+
+Pages and words: `pages`, `posts`, `faqs`, and a `sections` field on pages, services, service categories, service areas and case studies that holds any of the 35 section types.
+
+Section types: hero (five layouts incl. a picker), intro, services (five layouts), feature or why choose us (with bullets, steps, photo side), steps, team (four layouts), reviews (four), cases (three), faq, stats, badges, insurance (three), financing, plans, contact or request form (three, each question a switch), location (per-day or grouped hours), locations, cta (three), gallery (three), video, technologies, brands, offer, conditions, downloads, policies, posts, areas (four), products (three), case_studies (three), clients (three), signs, options, related, custom (HTML, CSS and script in an isolated frame).
+
+## Where the shape came from
+
+Read by hand, with every claim tied to the URL it was seen on: six sites in a pilot (three roofers, three dentists), then eleven local service sites (seven dental, plus chiropractic, med spa, optometry and physiotherapy), plus the pest-control template's own collections for the service-area side. The evidence tables below are from the local service read; the counts are out of eleven unless said. Service-area, shop and agency evidence is thinner (the pilot's roofers and the pest template) and those parts of the schema will be revised as those kinds are read.
+