@sumaq/site-kit 0.2.0 → 0.4.0

package/README.md

@@ -3,7 +3,7 @@
 Layouts, blocks, helpers and Astro config factory for Sumaq client sites.
 
 ```bash
-pnpm add @sumaq/site-kit@0.2.0
+pnpm add @sumaq/site-kit@0.4.0
 ```
 
 Public on [npmjs.com](https://www.npmjs.com/package/@sumaq/site-kit). Pin an exact version in each `www-*` site — never a range.
@@ -33,7 +33,7 @@ The checks live in `lib/content.ts` (`hasText`, `list`, `hasItems`, `hasImage`,
 | `Actions` | a row of CTAs; honours `external` |
 | `Card` | media, icon, badge, title, text, bullets; becomes an `<a>` when given `href` |
 | `Logo` | brand link, falls back to the brand name when there is no image |
-| `Media` | `<img>` for CMS strings, `astro:assets` `<Image>` for imported assets |
+| `Media` | resolves `/media/…` content paths to optimised assets; passthrough `<img>` for anything else — see [Images](#images) |
 | `Prose` | markdown or HTML into `sq-prose` |
 | `ScrollToTop` | floating back-to-top control |
 
@@ -51,6 +51,44 @@ The checks live in `lib/content.ts` (`hasText`, `list`, `hasItems`, `hasImage`,
 
 Every block accepts `section` (the `data-cms` base key), `variant` (`light` / `muted` / …) and `id`, so the same component can appear twice on a page under different CMS keys.
 
+## Images
+
+A site keeps its images in **`./media/`** at the repo root — a sibling of `schema/` and `content/`, not inside `public/`. The CMS publishes there, and Astro processes what it finds: content hash in the filename, `srcset` at four widths, and a `dist/_astro/…` URL that changes whenever the bytes change.
+
+That makes the string in `content/*.json` a **key, not a URL**:
+
+```jsonc
+"image": { "alt": "Retrato", "src": "/media/portrait-a3f9c1d2.webp" }
+```
+
+Nothing serves `/media/portrait-a3f9c1d2.webp`. `Media` looks the key up in a build-time glob and renders the asset Astro emitted for it. **Interpolating that string into a `src=` yourself gives a silent 404** — use `<Media>`, or `mediaUrl()` where only a string fits (an `og:image`, a `data-` attribute a script reads later).
+
+```astro
+<Media src={data.hero.image} sizes="(max-width: 900px) 100vw, 25rem" />
+```
+
+| `src` | What happens |
+|---|---|
+| `/media/x.webp` present in `./media/` | `<Image>` with `srcset` at 640/960/1280/2000 (clamped to the original) plus the manifest's LQIP as a background |
+| `/media/x.svg` | `<img>` with the emitted URL — imported SVGs become components in Astro 7, and this keeps them images |
+| `https://…` or any `public/` path | plain `<img>`, untouched |
+| an `ImageMetadata` import | `<Image>`, as before |
+| empty | nothing — unless `fallback` is set |
+
+`media/manifest.json`, written by the CMS, carries `{ alt, width, height, lqip }` per key. A site without one simply renders without LQIP.
+
+### Placeholder
+
+`<Media fallback />` shows a placeholder instead of rendering nothing when `src` is empty. It is **opt-in per block** on purpose: a hero with a gap reads better than a grey box, a card grid with a hole does not.
+
+The file ships inside this package (`src/assets/placeholder.webp`), so no site has to remember to add one. A site that wants its own branding drops `media/placeholder.webp` in the repo and that wins.
+
+In `astro dev`, a `/media/…` key that does not resolve also shows the placeholder plus a `console.warn` with the path. In a production build there is no such branch: `validateSiteContent` (from `@sumaq/cms-schema`, wired by `defineSumaqSite`) has already failed the build. A placeholder in production would hide a broken publication behind a grey rectangle nobody reports.
+
+### Non-image attachments
+
+PDFs and the like go to **`public/files/`** and are referenced as `/files/tarifas-a3f9c1d2.pdf`. They are copied verbatim, so their URL stays stable for whoever the client shared it with — which is exactly why they do *not* get a content hash in their served path.
+
 ## Site-local components
 
 The kit is where a site **starts**, not where it is confined — a client paying for something of their own gets it in their own repo. Two seams make that work without forking:
@@ -63,7 +101,7 @@ import Rooms from "../components/Rooms.astro";   // only this client
 <BlockRenderer blocks={blocks} components={{ rooms: Rooms }} />
 ```
 
-`components` merges into the catalogue **and wins over it**, so a site can add a block the kit does not have or replace one it does. An unmatched `type` still falls back to `Generic`, and warns in dev so a custom block never fails silently. Data-side there is nothing to register: `@sumaq/cms-schema` validates each block against the site's own `cms/*.yaml`, never against a central list.
+`components` merges into the catalogue **and wins over it**, so a site can add a block the kit does not have or replace one it does. An unmatched `type` still falls back to `Generic`, and warns in dev so a custom block never fails silently. Data-side there is nothing to register: `@sumaq/cms-schema` validates each block against the site's own `schema/*.yaml`, never against a central list.
 
 **The namespace rule:** `sq-*` belongs to the kit and is inventoried in `class-inventory.json`. Site-local components use their own prefix. That is what keeps the shared markup verifiable without taxing what makes a client's site theirs.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sumaq/site-kit",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Layouts, blocks, helpers and Astro config factory for Sumaq client sites.",
   "license": "UNLICENSED",
   "author": "elingan",
@@ -20,6 +20,7 @@
     "./content": "./src/lib/content.ts",
     "./format": "./src/lib/format.ts",
     "./markdown": "./src/lib/markdown.ts",
+    "./media": "./src/lib/media.ts",
     "./tokens.css": "./src/tokens/index.css",
     "./class-inventory.json": "./src/tokens/class-inventory.json",
     "./profiles/*": "./src/profiles/*.yaml",
@@ -32,7 +33,7 @@
   "dependencies": {
     "@astrojs/sitemap": "3.7.3",
     "marked": "15.0.7",
-    "@sumaq/cms-schema": "0.1.0"
+    "@sumaq/cms-schema": "0.3.0"
   },
   "devDependencies": {
     "astro": "7.1.4",

package/src/blocks/Gallery.astro

@@ -11,6 +11,7 @@
 import Section from "../components/Section.astro";
 import SectionHeader from "../components/SectionHeader.astro";
 import Media from "../components/Media.astro";
+import { mediaUrl } from "../lib/media";
 import { cmsKey, hasText, list } from "../lib/content";
 
 const {
@@ -52,7 +53,7 @@ const images = list<any>(items)
 								type="button"
 								class="sq-gallery__trigger"
 								data-gallery-index={i}
-								data-src={image.src}
+								data-src={mediaUrl(image.src)}
 								data-alt={image.alt || ""}
 								aria-label={image.alt || undefined}
 							>

package/src/blocks/LocationsOverview.astro

@@ -2,6 +2,7 @@
 import Section from "../components/Section.astro";
 import SectionHeader from "../components/SectionHeader.astro";
 import Media from "../components/Media.astro";
+import { mediaUrl } from "../lib/media";
 import { cmsKey, hasAny, hasText, list } from "../lib/content";
 
 const {
@@ -71,7 +72,7 @@ const hasTitle = hasText(sectionTitle) || hasText(sectionTitleAccent);
 													type="button"
 													class:list={["sq-location__thumb", imageIndex === 0 && "is-active"]}
 													data-target={`${location.id}-main-img`}
-													data-src={image.src}
+													data-src={mediaUrl(image.src)}
 													data-alt={image.alt}
 													aria-label={`${image.alt || location.name} ${imageIndex + 1}`}
 												>

package/src/components/Media.astro

@@ -1,20 +1,36 @@
 ---
 /**
- * Image primitive. Renders nothing when there is no `src`.
+ * Image primitive.
  *
- * Accepts both shapes the sites use:
- *  - a string path coming from `content/*.json` → plain `<img>`
+ * Accepts the three shapes the sites use:
+ *  - a `/media/…` key from `content/*.json` → resolved to a build asset and
+ *    optimised by `astro:assets` (srcset + content hash)
+ *  - any other string (external URL, `public/` path) → plain `<img>`,
+ *    untouched
  *  - an `ImageMetadata` import (logos, local assets) → `astro:assets` `<Image>`
+ *
+ * Renders nothing when there is no `src`, unless `fallback` is set — see the
+ * placeholder rules below.
  */
 import { Image } from "astro:assets";
 import type { ImageMetadata } from "astro";
 import { hasImage, hasText } from "../lib/content";
+import {
+	DEFAULT_WIDTHS,
+	isMediaPath,
+	isSvg,
+	mediaMeta,
+	placeholderOverride,
+	resolveMedia,
+} from "../lib/media";
+import kitPlaceholder from "../assets/placeholder.webp";
 
 interface Props {
 	src?: string | ImageMetadata | { src?: string; alt?: string } | null;
 	alt?: string;
 	id?: string;
 	class?: string;
+	style?: string;
 	width?: number;
 	height?: number;
 	sizes?: string;
@@ -22,6 +38,12 @@ interface Props {
 	loading?: "lazy" | "eager";
 	decoding?: "async" | "sync" | "auto";
 	fetchpriority?: "high" | "low" | "auto";
+	/**
+	 * Show the placeholder instead of rendering nothing when `src` is empty.
+	 * Opt-in per block: a gap in a hero looks better than a grey box, a hole in
+	 * a card grid does not.
+	 */
+	fallback?: boolean;
 	/** `data-cms-src` path so the live preview can swap the file. */
 	cms?: string;
 }
@@ -31,6 +53,7 @@ const {
 	alt,
 	id,
 	class: className,
+	style,
 	width,
 	height,
 	sizes,
@@ -38,6 +61,7 @@ const {
 	loading = "lazy",
 	decoding = "async",
 	fetchpriority,
+	fallback = false,
 	cms,
 } = Astro.props;
 
@@ -45,35 +69,94 @@ const {
 const isPlainImageField =
 	src !== null && typeof src === "object" && !("width" in src) && "src" in src;
 const resolved = isPlainImageField ? (src as { src?: string }).src : src;
-const resolvedAlt = alt ?? (isPlainImageField ? ((src as { alt?: string }).alt ?? "") : "");
+const authoredAlt = alt ?? (isPlainImageField ? ((src as { alt?: string }).alt ?? "") : "");
 const isAsset = typeof resolved === "object" && resolved !== null;
+
+/** A `/media/…` key resolves to a build asset; anything else stays a string. */
+const localAsset = isAsset ? null : resolveMedia(resolved);
+const meta = isAsset ? null : mediaMeta(resolved);
+
+const missing = !hasImage(resolved);
+/** A local key that should have resolved and did not — a broken publication. */
+const broken = !isAsset && isMediaPath(resolved) && localAsset === null;
+
+if (broken && import.meta.env.DEV) {
+	console.warn(
+		`[sumaq] Media: "${resolved}" is not in ./media/. ` +
+			"Showing the placeholder — this fails the production build.",
+	);
+}
+
+/**
+ * The placeholder covers two cases: an empty field on a block that opted in,
+ * and — in dev only — a key that does not resolve. In production the build has
+ * already failed via `validateSiteContent`, so there is nothing to hide.
+ */
+const usePlaceholder = (missing && fallback) || (broken && import.meta.env.DEV);
+const placeholder = placeholderOverride ?? kitPlaceholder;
+
+/** The author's alt still describes what *should* be there; keep it. */
+const resolvedAlt = usePlaceholder ? (hasText(authoredAlt) ? authoredAlt : "") : authoredAlt;
+
+const asset: ImageMetadata | null = usePlaceholder
+	? placeholder
+	: (localAsset ?? (isAsset ? (resolved as ImageMetadata) : null));
+
+/** Content images get the full srcset; a hand-passed import keeps its own props. */
+const assetWidths = widths ?? (localAsset || usePlaceholder ? DEFAULT_WIDTHS : undefined);
+
+/** LQIP from the manifest, shown behind the image while it loads. */
+const lqipStyle = meta?.lqip
+	? `background-image:url(${meta.lqip});background-size:cover;background-position:center`
+	: undefined;
+const composedStyle = [style, usePlaceholder ? undefined : lqipStyle]
+	.filter(Boolean)
+	.join(";") || undefined;
+
+/**
+ * An SVG gets its dimensions written out by hand (it skips `<Image>`), so a
+ * caller that gave only one of them would otherwise pair it with the asset's
+ * intrinsic other one and describe a box of the wrong shape.
+ */
+const svgWidth = asset && width === undefined && height !== undefined
+	? Math.round((height * asset.width) / asset.height)
+	: (width ?? asset?.width);
+const svgHeight = asset && height === undefined && width !== undefined
+	? Math.round((width * asset.height) / asset.width)
+	: (height ?? asset?.height);
+
+const passthrough = !asset && !missing;
 ---
 
 {
-	hasImage(resolved) &&
-		(isAsset ? (
-			<Image
-				src={resolved as ImageMetadata}
+	asset &&
+		(isSvg(asset) ? (
+			/* Astro compiles imported SVGs into components; the emitted URL keeps
+			   them rendering as plain images. */
+			<img
+				src={asset.src}
 				alt={resolvedAlt}
 				id={id}
 				class={className}
-				width={width}
-				height={height}
-				widths={widths}
-				sizes={sizes}
+				style={composedStyle}
+				width={svgWidth}
+				height={svgHeight}
 				loading={loading}
 				decoding={decoding}
+				fetchpriority={fetchpriority}
 				data-cms-src={cms}
 			/>
 		) : (
-			<img
-				src={resolved as string}
+			<Image
+				src={asset}
 				alt={resolvedAlt}
 				id={id}
 				class={className}
+				style={composedStyle}
 				width={width}
 				height={height}
-				sizes={hasText(sizes) ? sizes : undefined}
+				widths={assetWidths}
+				sizes={sizes}
 				loading={loading}
 				decoding={decoding}
 				fetchpriority={fetchpriority}
@@ -81,3 +164,21 @@ const isAsset = typeof resolved === "object" && resolved !== null;
 			/>
 		))
 }
+{
+	passthrough && (
+		<img
+			src={resolved as string}
+			alt={resolvedAlt}
+			id={id}
+			class={className}
+			style={composedStyle}
+			width={width}
+			height={height}
+			sizes={hasText(sizes) ? sizes : undefined}
+			loading={loading}
+			decoding={decoding}
+			fetchpriority={fetchpriority}
+			data-cms-src={cms}
+		/>
+	)
+}

package/src/components/Seo.astro

@@ -9,6 +9,7 @@
  * not fill emits no tag at all.
  */
 import { hasText } from "../lib/content";
+import { mediaUrl } from "../lib/media";
 
 interface Props {
 	seo?: Record<string, any>;
@@ -19,7 +20,9 @@ const { seo = {} } = Astro.props;
 const base = Astro.site ?? Astro.url;
 const absolute = (value?: string) => (hasText(value) ? new URL(value!, base).href : undefined);
 
-const image = absolute(seo.ogImage);
+// Through the resolver first: a `/media/…` value is a repo path, and the tag a
+// scraper reads has to be the URL Astro actually emitted for it.
+const image = absolute(mediaUrl(seo.ogImage));
 const canonical = hasText(seo.canonical)
 	? absolute(seo.canonical)
 	: new URL(Astro.url.pathname, base).href;

package/src/config.ts

@@ -21,13 +21,13 @@ export type SumaqSiteOptions = {
 	//   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/`,
+	// dos líneas y hay que decidir a la vez cómo se traducen `schema/` 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.
+ * Validates content/*.json against schema/*.yaml before the build emits pages.
  */
 export function defineSumaqSite(opts: SumaqSiteOptions) {
 	return defineConfig({
@@ -41,10 +41,9 @@ export function defineSumaqSite(opts: SumaqSiteOptions) {
 				hooks: {
 					"astro:build:start": async () => {
 						if (opts.skipContentValidation) return;
-						await validateSiteContent({
-							cmsDir: "./cms",
-							contentDir: "./content",
-						});
+						// No arguments: the directory names are the contract, and
+						// @sumaq/cms-schema is the only place that decides them.
+						await validateSiteContent();
 					},
 				},
 			},

package/src/index.ts

@@ -73,3 +73,14 @@ export {
 export { telHref } from "./lib/format";
 export { md } from "./lib/markdown";
 export { cmsKey, hasAny, hasImage, hasItems, hasText, list } from "./lib/content";
+export {
+	DEFAULT_WIDTHS,
+	MEDIA_PREFIX,
+	isMediaPath,
+	isSvg,
+	mediaKeys,
+	mediaMeta,
+	mediaUrl,
+	resolveMedia,
+} from "./lib/media";
+export type { MediaManifestEntry } from "./lib/media";

package/src/lib/media.ts

@@ -0,0 +1,101 @@
+/**
+ * Resolves the `/media/…` strings that live in `content/*.json` to real build
+ * assets.
+ *
+ * The CMS publishes one master image per upload into the **site's** `./media/`
+ * directory and writes its repo path into the content JSON. That string is a
+ * *logical key*, not a URL: nothing serves `/media/portrait-a3f9c1d2.webp` at
+ * runtime. The glob below turns the key into an `ImageMetadata`, and
+ * `astro:assets` emits a content-hashed, resized `dist/_astro/…` file for it.
+ *
+ * The glob is absolute on purpose. Vite resolves absolute glob patterns against
+ * the **project root**, so this module — living inside the published package —
+ * still scans the consuming site's `./media/`, never the package's own files.
+ *
+ * A key that does not resolve is not an error here: external URLs
+ * (`https://…`) and `public/` paths are legitimate and fall through to a plain
+ * `<img>`. Only a `/media/…` key that fails to resolve is broken, and that is
+ * what `isMediaPath` is for — `validateSiteContent` turns it into a build
+ * failure, and `Media.astro` shows the placeholder in dev.
+ */
+import type { ImageMetadata } from "astro";
+
+/** Widths the CMS master (2000px) is resized to. Astro clamps to the original. */
+export const DEFAULT_WIDTHS = [640, 960, 1280, 2000];
+
+/** The prefix that marks a string as a local key instead of a URL. */
+export const MEDIA_PREFIX = "/media/";
+
+/** What `media/manifest.json` stores per image. Written by the CMS on publish. */
+export interface MediaManifestEntry {
+	alt?: string;
+	width?: number;
+	height?: number;
+	/** Base64 data URI shown while the real image loads. */
+	lqip?: string;
+}
+
+/**
+ * The pattern must be a literal: Vite rewrites `import.meta.glob` at transform
+ * time and silently yields `{}` for a pattern it cannot read statically.
+ * Extensions are the ones `astro:assets` can process.
+ */
+const assets = import.meta.glob<{ default: ImageMetadata }>(
+	"/media/**/*.{webp,avif,png,jpg,jpeg,svg}",
+	{ eager: true },
+);
+
+const manifests = import.meta.glob<Record<string, MediaManifestEntry>>("/media/manifest.json", {
+	eager: true,
+	import: "default",
+});
+
+/** `{}` when the site has no manifest yet — every lookup simply misses. */
+const manifest: Record<string, MediaManifestEntry> = manifests["/media/manifest.json"] ?? {};
+
+/** True for strings the site is expected to resolve locally. */
+export function isMediaPath(value: unknown): value is string {
+	return typeof value === "string" && value.startsWith(MEDIA_PREFIX);
+}
+
+/** The build asset for a `/media/…` key, or `null` when there is none. */
+export function resolveMedia(value: unknown): ImageMetadata | null {
+	if (typeof value !== "string" || value === "") return null;
+	return assets[value]?.default ?? null;
+}
+
+/**
+ * The URL a browser should request for a content ref.
+ *
+ * `resolveMedia` is for rendering with `<Image>`; this is for the places that
+ * can only take a string — an `og:image` meta, a `data-src` a script later
+ * assigns. Those are exactly where a `/media/…` key would 404 silently, because
+ * nothing serves the key itself: it has to become the emitted asset URL.
+ * Anything that does not resolve (external URL, `public/` path) passes through.
+ */
+export function mediaUrl(value: unknown): string | undefined {
+	if (typeof value !== "string" || value === "") return undefined;
+	return resolveMedia(value)?.src ?? value;
+}
+
+/** Manifest metadata (lqip, dimensions, authored alt) for a `/media/…` key. */
+export function mediaMeta(value: unknown): MediaManifestEntry | null {
+	if (typeof value !== "string") return null;
+	return manifest[value] ?? null;
+}
+
+/** Every `/media/…` key the site ships. Used by tooling, not by rendering. */
+export function mediaKeys(): string[] {
+	return Object.keys(assets);
+}
+
+/** SVGs skip `<Image>`: Astro turns imported SVGs into components. */
+export function isSvg(asset: ImageMetadata): boolean {
+	return asset.format === "svg";
+}
+
+/**
+ * A site can override the kit's placeholder with its own branding by dropping
+ * `media/placeholder.webp` into the repo.
+ */
+export const placeholderOverride = resolveMedia("/media/placeholder.webp");

package/src/profiles/clinic.yaml

@@ -2,7 +2,7 @@
 # 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
+# propias en su `schema/page.*.yaml` y pasar sus componentes a `<BlockRenderer
 # components={{ … }} />`. Ver block-contract.md §7.
 
 label: Práctica con sedes y equipo

package/src/profiles/portfolio.yaml

@@ -2,7 +2,7 @@
 # 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
+# propias en su `schema/page.*.yaml` y pasar sus componentes a `<BlockRenderer
 # components={{ … }} />`. Ver block-contract.md §7.
 
 label: Portfolio profesional

package/src/profiles/therapist.yaml

@@ -2,7 +2,7 @@
 # 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
+# propias en su `schema/page.*.yaml` y pasar sus componentes a `<BlockRenderer
 # components={{ … }} />`. Ver block-contract.md §7.
 
 label: Consulta de psicoterapia

package/src/scripts/enhancements.js

@@ -269,15 +269,6 @@ const initEnhancements = () => {
     });
   }
 
-  // 4b. Broken image fallback (team / profile)
-  document.querySelectorAll("img[src^='media/team/']").forEach((img) => {
-    img.addEventListener("error", () => {
-      if (img.dataset.fallbackApplied) return;
-      img.dataset.fallbackApplied = "1";
-      img.src = "media/team/profile_placeholder.CZDfc6EN_1FnOqJ.webp";
-    });
-  });
-
   // 4c. Gallery lightbox (<Gallery lightbox />) — one viewer per gallery,
   // keyboard-navigable, restores focus to the trigger on close.
   document.querySelectorAll("[data-lightbox]").forEach((viewer) => {

package/src/tokens/class-inventory.json

@@ -1,6 +1,6 @@
 {
 	"$comment": "Generated by scripts/build-class-inventory.mjs — do not edit by hand. `sq-*` is the kit's namespace; site-local components must use their own prefix.",
-	"version": "0.2.0",
+	"version": "0.4.0",
 	"classes": [
 		"sq-about",
 		"sq-about__body",