@sumaq/site-kit 0.2.0

package/src/components/SiteFooter.astro

@@ -0,0 +1,90 @@
+---
+/**
+ * Site chrome: brand, navigation columns, legal column, copyright, to-top.
+ *
+ * Each column disappears when its link list is empty, and the bottom bar
+ * disappears when there is neither a copyright nor a to-top label. The old
+ * version crashed on `footer.navLinks.map` when either list was absent.
+ */
+import type { ImageMetadata } from "astro";
+import Logo from "./Logo.astro";
+import { cmsKey, hasAny, hasItems, hasText, list } from "../lib/content";
+
+interface Props {
+	footer?: Record<string, any>;
+	header?: Record<string, any>;
+	logo?: ImageMetadata;
+}
+
+const { footer = {}, header = {}, logo } = Astro.props;
+
+const usable = (links: unknown) =>
+	list<any>(links).filter((link) => hasText(link?.label) && hasText(link?.href));
+
+const columns = [
+	{ key: "navLinks", title: footer.navTitle || "Navigation", links: usable(footer.navLinks) },
+	{ key: "legalLinks", title: footer.legalTitle || "Rechtliches", links: usable(footer.legalLinks) },
+	{ key: "socialLinks", title: footer.socialTitle, links: usable(footer.socialLinks) },
+].filter((column) => hasItems(column.links));
+
+const copyright = [footer.copyrightPrefix, footer.copyrightSuffix].filter(hasText).join(" ");
+const hasBrand = hasAny(logo, footer.tagline, header.brandName);
+---
+
+<footer class="sq-footer">
+	{
+		(hasBrand || columns.length > 0) && (
+			<div class="sq-container sq-footer__inner">
+				{hasBrand && (
+					<div class="sq-footer__brand">
+						<Logo
+							image={logo}
+							name={header.brandName}
+							href={header.homeHref || "/"}
+							label={header.homeLabel || header.brandName}
+							variant="footer"
+						/>
+						{hasText(footer.tagline) && (
+							<p class="sq-footer__tagline" data-cms="footer.tagline">
+								{footer.tagline}
+							</p>
+						)}
+					</div>
+				)}
+
+				{columns.map((column) => (
+					<nav class="sq-footer__nav" aria-label={column.title}>
+						{hasText(column.title) && <p class="sq-footer__nav-title">{column.title}</p>}
+						<ul>
+							{column.links.map((link: any, i: number) => (
+								<li>
+									<a
+										href={link.href}
+										target={link.external ? "_blank" : undefined}
+										rel={link.external ? "noopener" : undefined}
+										data-cms={cmsKey("footer", column.key, i, "label")}
+									>
+										{link.label}
+									</a>
+								</li>
+							))}
+						</ul>
+					</nav>
+				))}
+			</div>
+		)
+	}
+
+	{
+		hasAny(copyright, footer.toTopLabel) && (
+			<div class="sq-container sq-footer__bottom">
+				{hasText(copyright) && <p data-cms="footer.copyrightPrefix">{copyright}</p>}
+				{hasText(footer.toTopLabel) && (
+					<a class="sq-to-top" href="#top" data-cms="footer.toTopLabel">
+						{footer.toTopLabel}
+					</a>
+				)}
+			</div>
+		)
+	}
+</footer>

package/src/components/SiteHeader.astro

@@ -0,0 +1,97 @@
+---
+/**
+ * Site chrome: brand + primary navigation + mobile toggle.
+ *
+ * A site with no nav links renders no `<nav>` and no burger button — the
+ * toggle would otherwise open an empty drawer.
+ */
+import type { ImageMetadata } from "astro";
+import Logo from "./Logo.astro";
+import { hasItems, hasText, list } from "../lib/content";
+
+interface Props {
+	header?: Record<string, any>;
+	logo?: ImageMetadata;
+	currentPath?: string;
+	navLinks?: any[];
+}
+
+const { header = {}, logo, currentPath = "/", navLinks } = Astro.props;
+const links = list<any>(navLinks ?? header.navLinks).filter(
+	(link) => hasText(link?.label) && hasText(link?.href),
+);
+const pathOnly = (href: string) => href.split("#")[0] || "/";
+
+const bestMatchPath = links.reduce((best: string | null, link: any) => {
+	if (link.href.includes("#")) return best;
+	const path = pathOnly(link.href);
+	const matches =
+		path === "/" ? currentPath === "/" : currentPath === path || currentPath.startsWith(`${path}/`);
+	if (!matches) return best;
+	return !best || path.length > best.length ? path : best;
+}, null as string | null);
+
+const isCurrent = (href: string) => !href.includes("#") && pathOnly(href) === bestMatchPath;
+
+/**
+ * `emergency: true` in the nav link is the supported way to flag the crisis
+ * link. The label test is the pre-0.2 behaviour kept so sites that have not
+ * added the field yet keep their styling; drop it once content is migrated.
+ */
+const isEmergency = (link: any) => link.emergency === true || /notfall/i.test(link.label);
+
+const hasNav = hasItems(links);
+---
+
+<header class="sq-header">
+	<div class="sq-container sq-header__inner">
+		<div class="sq-header__bar">
+			<Logo
+				image={logo}
+				name={header.brandName}
+				href={header.homeHref || "/"}
+				label={header.homeLabel || header.brandName}
+				eager
+			/>
+			{
+				hasNav && (
+					<div class="sq-header__actions">
+						<button
+							class="sq-nav__toggle"
+							type="button"
+							aria-expanded="false"
+							aria-controls="site-nav"
+							aria-label={header.menuOpenLabel || "Menü öffnen"}
+						>
+							<span class="sq-nav__toggle-bar" aria-hidden="true" />
+							<span class="sq-nav__toggle-bar" aria-hidden="true" />
+							<span class="sq-nav__toggle-bar" aria-hidden="true" />
+						</button>
+					</div>
+				)
+			}
+		</div>
+		{
+			hasNav && (
+				<nav class="sq-nav" id="site-nav" aria-label={header.navLabel || "Hauptnavigation"}>
+					<ul class="sq-nav__list">
+						{links.map((link: any, i: number) => (
+							<li>
+								<a
+									class={isEmergency(link) ? "sq-nav__emergency" : undefined}
+									href={link.href}
+									target={link.external ? "_blank" : undefined}
+									rel={link.external ? "noopener" : undefined}
+									aria-current={isCurrent(link.href) ? "page" : undefined}
+									data-cms={`header.navLinks[${i}].label`}
+								>
+									{link.label}
+								</a>
+							</li>
+						))}
+					</ul>
+				</nav>
+			)
+		}
+	</div>
+</header>

package/src/config.ts

@@ -0,0 +1,59 @@
+import { defineConfig } from "astro/config";
+import type { AstroUserConfig } from "astro";
+import sitemap from "@astrojs/sitemap";
+import { validateSiteContent } from "@sumaq/cms-schema/build";
+
+export type SumaqSiteOptions = {
+	site: string;
+	integrations?: unknown[];
+	image?: {
+		domains?: string[];
+		responsiveStyles?: boolean;
+	};
+	/** Passed through to Astro (e.g. Google fonts via `fontProviders`). */
+	fonts?: AstroUserConfig["fonts"];
+	/** Passed through to Astro. Dev-only plugins (QR, devtools) live here. */
+	vite?: AstroUserConfig["vite"];
+	/** Skip content↔schema validation (escape hatch for experiments). */
+	skipContentValidation?: boolean;
+
+	// Sitios multiidioma: cuando un cliente lo pida, aquí entra
+	//   i18n?: AstroUserConfig["i18n"];
+	// y se reenvía a `defineConfig` igual que `fonts` y `vite`. Hoy ningún sitio
+	// lo usa, así que no se añade en vacío: el día que haga falta, el cambio son
+	// dos líneas y hay que decidir a la vez cómo se traducen `cms/` y `content/`,
+	// que es la parte cara.
+};
+
+/**
+ * Shared Astro config for Sumaq client sites.
+ * Validates content/*.json against cms/*.yaml before the build emits pages.
+ */
+export function defineSumaqSite(opts: SumaqSiteOptions) {
+	return defineConfig({
+		site: opts.site,
+		fonts: opts.fonts,
+		vite: opts.vite,
+		integrations: [
+			sitemap(),
+			{
+				name: "@sumaq/validate-content",
+				hooks: {
+					"astro:build:start": async () => {
+						if (opts.skipContentValidation) return;
+						await validateSiteContent({
+							cmsDir: "./cms",
+							contentDir: "./content",
+						});
+					},
+				},
+			},
+			...((opts.integrations as never[]) ?? []),
+		],
+		image: {
+			responsiveStyles: true,
+			domains: opts.image?.domains ?? [],
+			...opts.image,
+		},
+	});
+}

package/src/index.ts

@@ -0,0 +1,75 @@
+// Layouts
+export { default as Base } from "./layouts/Base.astro";
+
+// Chrome
+export { default as Seo } from "./components/Seo.astro";
+export { default as SiteHeader } from "./components/SiteHeader.astro";
+export { default as SiteFooter } from "./components/SiteFooter.astro";
+
+// Primitives — the pieces every block is assembled from (block-contract §3, layer A)
+export { default as Section } from "./components/Section.astro";
+export { default as SectionHeader } from "./components/SectionHeader.astro";
+export { default as SectionHeading } from "./components/SectionHeading.astro";
+export { default as Actions } from "./components/Actions.astro";
+export { default as Card } from "./components/Card.astro";
+export { default as Logo } from "./components/Logo.astro";
+export { default as Media } from "./components/Media.astro";
+export { default as Prose } from "./components/Prose.astro";
+export { default as ScrollToTop } from "./components/ScrollToTop.astro";
+
+// Blocks — page openers
+export { default as Hero } from "./blocks/Hero.astro";
+export { default as PageBanner } from "./blocks/PageBanner.astro";
+
+// Blocks — content
+export { default as About } from "./blocks/About.astro";
+export { default as Audience } from "./blocks/Audience.astro";
+export { default as Faq } from "./blocks/Faq.astro";
+export { default as FeatureList } from "./blocks/FeatureList.astro";
+export { default as Gallery } from "./blocks/Gallery.astro";
+export { default as Generic } from "./blocks/Generic.astro";
+export { default as Notice } from "./blocks/Notice.astro";
+export { default as Pricing } from "./blocks/Pricing.astro";
+export { default as Projects } from "./blocks/Projects.astro";
+export { default as Quote } from "./blocks/Quote.astro";
+export { default as Services } from "./blocks/Services.astro";
+export { default as Skills } from "./blocks/Skills.astro";
+export { default as Stats } from "./blocks/Stats.astro";
+export { default as Steps } from "./blocks/Steps.astro";
+export { default as Testimonials } from "./blocks/Testimonials.astro";
+export { default as Timeline } from "./blocks/Timeline.astro";
+
+// Blocks — conversion
+export { default as Contact } from "./blocks/Contact.astro";
+export { default as ContactDetails } from "./blocks/ContactDetails.astro";
+export { default as CtaBand } from "./blocks/CtaBand.astro";
+export { default as IntroCta } from "./blocks/IntroCta.astro";
+
+// Blocks — collections
+export { default as LocationsOverview } from "./blocks/LocationsOverview.astro";
+export { default as ProfileDetail } from "./blocks/ProfileDetail.astro";
+export { default as TeamDirectory } from "./blocks/TeamDirectory.astro";
+export { default as TeamTeaser } from "./blocks/TeamTeaser.astro";
+
+// Blocks — standalone pages
+export { default as LegalDocument } from "./blocks/LegalDocument.astro";
+export { default as NotFound } from "./blocks/NotFound.astro";
+
+// Blocks — emergency (profile: therapist)
+export { default as EmergencyGrid } from "./blocks/EmergencyGrid.astro";
+export { default as EmergencyHelplines } from "./blocks/EmergencyHelplines.astro";
+export { default as EmergencyPrimary } from "./blocks/EmergencyPrimary.astro";
+
+export { default as BlockRenderer } from "./blocks/BlockRenderer.astro";
+
+// Lib re-exports for convenience
+export {
+	loadEntries,
+	applyOrder,
+	getTeamMembers,
+	getLocationCards,
+	getCollectionCards,
+} from "./lib/collections";
+export { telHref } from "./lib/format";
+export { md } from "./lib/markdown";
+export { cmsKey, hasAny, hasImage, hasItems, hasText, list } from "./lib/content";

package/src/layouts/Base.astro

@@ -0,0 +1,57 @@
+---
+import { ClientRouter } from "astro:transitions";
+import type { ImageMetadata } from "astro";
+import Seo from "../components/Seo.astro";
+import SiteHeader from "../components/SiteHeader.astro";
+import SiteFooter from "../components/SiteFooter.astro";
+import ScrollToTop from "../components/ScrollToTop.astro";
+
+interface Props {
+	seo?: Record<string, any>;
+	header?: Record<string, any>;
+	footer?: Record<string, any>;
+	/** Site logo (lives in the client repo, not the kit). */
+	logo?: ImageMetadata;
+	/** Label of the skip link; the site's language decides the wording. */
+	skipLabel?: string;
+	/** Floating back-to-top control. Off by default: the footer link covers it. */
+	scrollToTop?: boolean | { label?: string; threshold?: number };
+}
+
+const {
+	seo = {},
+	header,
+	footer,
+	logo,
+	skipLabel = "Zum Inhalt springen",
+	scrollToTop = false,
+} = Astro.props;
+const lang = seo.lang || "de";
+const scrollOptions = typeof scrollToTop === "object" ? scrollToTop : {};
+---
+
+<!doctype html>
+<html lang={lang}>
+	<head>
+		<meta charset="UTF-8" />
+		<link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+		<link rel="sitemap" href="/sitemap-index.xml" />
+		<meta name="viewport" content="width=device-width, initial-scale=1" />
+		<meta name="generator" content={Astro.generator} />
+		<Seo seo={seo} />
+		<ClientRouter />
+		<slot name="head" />
+	</head>
+	<body id="top">
+		{skipLabel && <a class="sq-skip-link" href="#main">{skipLabel}</a>}
+		{header && <SiteHeader header={header} logo={logo} currentPath={Astro.url.pathname} />}
+		<main id="main"><slot /></main>
+		{footer && <SiteFooter footer={footer} header={header ?? {}} logo={logo} />}
+		{
+			scrollToTop && (
+				<ScrollToTop label={scrollOptions.label} threshold={scrollOptions.threshold} />
+			)
+		}
+		<script src="../scripts/enhancements.js"></script>
+	</body>
+</html>

package/src/lib/collections.ts

@@ -0,0 +1,101 @@
+/**
+ * Collection access helpers.
+ *
+ * Globs must live in the consuming site (Vite resolves import.meta.glob relative
+ * to the importing module). Pass the eager-glob result into loadEntries().
+ *
+ * The entry slug is the JSON file name — the same rule the Sumaq CMS uses.
+ * Never read a `slug` field from the JSON.
+ */
+
+type Entry = Record<string, any>;
+
+function slugOf(path: string): string {
+	return path.split("/").pop()!.replace(/\.json$/, "");
+}
+
+/** Turn an eager import.meta.glob result into entries with slug from filename. */
+export function loadEntries(modules: Record<string, unknown>): Entry[] {
+	return Object.entries(modules)
+		.map(([path, entry]) => ({ slug: slugOf(path), ...(entry as Entry) }))
+		.sort((a, b) => a.slug.localeCompare(b.slug));
+}
+
+/** Applies the display order declared on the index page; unlisted entries go last. */
+export function applyOrder(entries: Entry[], order: string[] = []): Entry[] {
+	if (!order.length) return entries;
+	const rank = new Map(order.map((slug, index) => [slug, index]));
+	return [...entries].sort(
+		(a, b) => (rank.get(a.slug) ?? order.length) - (rank.get(b.slug) ?? order.length),
+	);
+}
+
+/** Slugs always shown first, in this exact order, ahead of the completeness-based sort. */
+const TEAM_PRIORITY_SLUGS = ["stefan-just", "barbara-bischoff"];
+
+function teamDataCompleteness(profile: Entry): number {
+	return [profile.titleSuffix, profile.role, profile.card?.description].filter(Boolean).length;
+}
+
+function sortTeamEntries(entries: Entry[]): Entry[] {
+	const bySlug = new Map(entries.map((entry) => [entry.slug, entry]));
+	const pinned = TEAM_PRIORITY_SLUGS.map((slug) => bySlug.get(slug)).filter(Boolean) as Entry[];
+	const rest = entries
+		.filter((entry) => !TEAM_PRIORITY_SLUGS.includes(entry.slug))
+		.sort(
+			(a, b) =>
+				teamDataCompleteness(b) - teamDataCompleteness(a) || a.name.localeCompare(b.name, "de"),
+		);
+	return [...pinned, ...rest];
+}
+
+/** Team members as consumed by the `teamDirectory` block. */
+export function getTeamMembers(entries: Entry[], order?: string[]) {
+	const ordered = order?.length ? applyOrder(entries, order) : sortTeamEntries(entries);
+	return ordered.map((profile) => ({
+		slug: profile.slug,
+		name: profile.name,
+		titleSuffix: profile.titleSuffix,
+		role: profile.role,
+		description:
+			profile.card?.description ||
+			profile.activityAreas?.[0]?.text ||
+			profile.diagnoses?.split(",")[0] ||
+			profile.role ||
+			"",
+		photo: profile.photo,
+		searchKeywords: profile.searchKeywords || "",
+		categories: profile.categories || "",
+		href: `/team/${profile.slug}`,
+	}));
+}
+
+/** Locations as consumed by the `locationsOverview` block. */
+export function getLocationCards(entries: Entry[], order?: string[]) {
+	return applyOrder(entries, order).map((entry, index) => {
+		const card = entry.card ?? {};
+		return {
+			id: entry.slug,
+			name: [entry.name, entry.nameAccent].filter(Boolean).join(" "),
+			address: card.address ?? "",
+			description: card.description ?? "",
+			priceLabel: card.priceLabel ?? "",
+			priceValue: card.priceValue ?? "",
+			priceSuffix: card.priceSuffix ?? "",
+			href: card.href || (entry.hasDetailPage ? `/standorte/${entry.slug}` : `#${entry.slug}`),
+			reverse: index % 2 === 1,
+			images: card.images ?? [],
+			features: card.features ?? [],
+		};
+	});
+}
+
+/** Alias matching the migration docs: cards for a named collection. */
+export function getCollectionCards(
+	name: "locations" | "team",
+	entries: Entry[],
+	order?: string[],
+) {
+	if (name === "team") return getTeamMembers(entries, order);
+	return getLocationCards(entries, order);
+}

package/src/lib/content.ts

@@ -0,0 +1,51 @@
+/**
+ * Content presence helpers.
+ *
+ * The kit's rendering rule is: **if there is content, the element renders;
+ * if there is not, nothing is emitted.** No empty `<p>`, no empty `<ul>`, no
+ * `<header>` with three blank lines inside. These helpers keep that decision
+ * identical in every block instead of each component inventing its own truthy
+ * check — `""`, `"   "`, `[]` and `{ src: "" }` all mean "no content".
+ */
+
+/** A non-blank string, or a finite number (prices, counters, badges). */
+export function hasText(value: unknown): boolean {
+	if (typeof value === "number") return Number.isFinite(value);
+	return typeof value === "string" && value.trim() !== "";
+}
+
+/** Always an array, with null/undefined entries dropped. Never throws on `undefined`. */
+export function list<T = any>(value: unknown): T[] {
+	if (!Array.isArray(value)) return [];
+	return value.filter((item) => item !== null && item !== undefined) as T[];
+}
+
+/** True when the array holds at least one usable entry. */
+export function hasItems(value: unknown): boolean {
+	return list(value).length > 0;
+}
+
+/** An image is present when it carries a `src` — either as a string or as `{ src }`. */
+export function hasImage(value: unknown): boolean {
+	if (!value) return false;
+	if (typeof value === "string") return value.trim() !== "";
+	if (typeof value !== "object") return false;
+	return hasText((value as { src?: unknown }).src);
+}
+
+/** True when at least one of the values would render something. */
+export function hasAny(...values: unknown[]): boolean {
+	return values.some((value) =>
+		Array.isArray(value) ? hasItems(value) : hasText(value) || hasImage(value),
+	);
+}
+
+/**
+ * Builds a `data-cms` path, or `undefined` when there is no base key.
+ * Astro drops attributes whose value is `undefined`, so an unkeyed block
+ * simply emits no `data-cms` instead of `data-cms="undefined.title"`.
+ */
+export function cmsKey(base: string | undefined, ...parts: (string | number)[]): string | undefined {
+	if (!hasText(base)) return undefined;
+	return [base, ...parts].join(".").replace(/\.(\d+)/g, "[$1]");
+}

package/src/lib/format.ts

@@ -0,0 +1,17 @@
+/**
+ * Display helpers shared by the collection detail pages.
+ */
+
+/**
+ * Builds a dialable `tel:` href. Numbers are entered in Austrian national
+ * notation ("0660 / 721 7711") or already in E.164 ("+43 677 616519"), so a
+ * leading national 0 is replaced by the Austrian country code.
+ */
+export function telHref(phone: string): string {
+  const digits = String(phone ?? "").replace(/[^\d+]/g, "");
+  if (!digits) return "";
+  if (digits.startsWith("+")) return `tel:${digits}`;
+  if (digits.startsWith("00")) return `tel:+${digits.slice(2)}`;
+  if (digits.startsWith("0")) return `tel:+43${digits.slice(1)}`;
+  return `tel:${digits}`;
+}

package/src/lib/markdown.ts

@@ -0,0 +1,5 @@
+import { marked } from "marked";
+
+export function md(src?: string) {
+  return marked.parse(src || "", { async: false }) as string;
+}

package/src/profiles/clinic.yaml

@@ -0,0 +1,35 @@
+# Perfil: práctica con varias sedes y equipo, respaldada por collections.
+# Extraído de www-therapieraum-graz-at.
+#
+# `blocks` es el punto de partida, no el límite: un sitio puede declarar shapes
+# propias en su `cms/page.*.yaml` y pasar sus componentes a `<BlockRenderer
+# components={{ … }} />`. Ver block-contract.md §7.
+
+label: Práctica con sedes y equipo
+
+blocks:
+  - hero
+  - pageBanner
+  - introCta
+  - teamTeaser
+  - teamDirectory
+  - profileDetail
+  - locationsOverview
+  - services
+  - audience
+  - pricing
+  - contact
+  - cta
+  - emergencyPrimary
+  - emergencyGrid
+  - emergencyHelplines
+  - generic
+
+collections: [team, locations]
+
+pages:
+  required: [index, impressum, datenschutz, 404]
+  optional: [team, standorte, notfall, agb]
+
+composition:
+  index: [hero, teamTeaser, introCta, locationsOverview, services, audience, pricing, cta, contact]

package/src/profiles/portfolio.yaml

@@ -0,0 +1,27 @@
+# Perfil: portfolio profesional / freelance.
+# Extraído de www-elingan-dev.
+#
+# `blocks` es el punto de partida, no el límite: un sitio puede declarar shapes
+# propias en su `cms/page.*.yaml` y pasar sus componentes a `<BlockRenderer
+# components={{ … }} />`. Ver block-contract.md §7.
+
+label: Portfolio profesional
+
+blocks:
+  - hero
+  - projects
+  - skills
+  - about
+  - timeline
+  - testimonials
+  - stats
+  - contactDetails
+  - cta
+  - generic
+
+pages:
+  required: [index, 404]
+  optional: [privacy, terms]
+
+composition:
+  index: [hero, projects, skills, about, cta]

package/src/profiles/therapist.yaml

@@ -0,0 +1,31 @@
+# Perfil: consulta individual de psicoterapia.
+# Extraído de www-utehofer-at, www-bettinageidl-at y www-juliaschaffer-at.
+#
+# `blocks` es el punto de partida, no el límite: un sitio puede declarar shapes
+# propias en su `cms/page.*.yaml` y pasar sus componentes a `<BlockRenderer
+# components={{ … }} />`. Ver block-contract.md §7.
+
+label: Consulta de psicoterapia
+
+blocks:
+  - hero
+  - about
+  - services
+  - featureList
+  - steps
+  - quote
+  - gallery
+  - timeline
+  - pricing
+  - faq
+  - notice
+  - contactDetails
+  - cta
+  - generic
+
+pages:
+  required: [index, impressum, datenschutz, 404]
+  optional: [agb, notfall]
+
+composition:
+  index: [hero, about, services, featureList, steps, quote, pricing, contactDetails, cta]