Adds the hero contract: golden files for the picture and the preload links, mapping and seed

Model B (wide 3:2 and tall 4:5 variants, focus point), agreed with the CMS
session. Pure functions mapHero, heroHtml and heroPreloadHtml, golden files in
web/contract/host-injection/hero with a README, and a seed with a first focus
estimate per photo. No site change yet.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-16 14:44:30 +01:00
co-authored by Claude Sonnet 5.5
parent 2c15cda7c4
commit 13f78c48cd
24 changed files with 793 additions and 0 deletions
+248
View File
@@ -0,0 +1,248 @@
import { readdirSync, readFileSync, writeFileSync } from 'node:fs';
import { join } from 'node:path';
import { describe, expect, it } from 'vitest';
import { mapHero } from './hero';
import { heroHtml, heroPreloadHtml } from './heroHtml';
// The contract with the CMS host: for every hero-*.input.json in
// contract/host-injection/hero there is an *.expected.html (the region between
// <!--CMS:HERO-HTML--> markers) and an *.expected-preload.html (the links
// between <!--CMS:HERO-PRELOAD--> markers). Regenerate after a deliberate change
// with UPDATE_GOLDEN=1 and send the files to the CMS session.
const DIR = join(process.cwd(), 'contract', 'host-injection', 'hero');
const inputs = readdirSync(DIR).filter((name) => name.endsWith('.input.json'));
describe('hero golden files', () => {
it('has inputs', () => {
expect(inputs.length).toBeGreaterThanOrEqual(6);
});
it.each(inputs)('%s gives the expected HTML and preload', (file) => {
const name = file.replace('.input.json', '');
const hero = mapHero(JSON.parse(readFileSync(join(DIR, file), 'utf8')));
const outputs = [
[`${name}.expected.html`, heroHtml(hero)],
[`${name}.expected-preload.html`, heroPreloadHtml(hero)],
];
for (const [expectedName, html] of outputs) {
const path = join(DIR, expectedName);
if (process.env.UPDATE_GOLDEN === '1') {
writeFileSync(path, html + '\n');
}
expect(html + '\n').toBe(readFileSync(path, 'utf8'));
}
});
});
const slide = (image: object, extra: object = {}) => ({
id: 's',
alt: 'Alt',
decorative: false,
image: { width: 10, height: 8, src: '/m/a.webp', ...image },
...extra,
});
const answer = (slides: unknown[], extra: object = {}) => ({
title: 'T',
slides,
...extra,
});
describe('mapHero', () => {
it('rejects what is not a usable hero', () => {
expect(mapHero(null)).toBeNull();
expect(mapHero([])).toBeNull();
expect(mapHero({ title: 'T' })).toBeNull();
expect(mapHero(answer([]))).toBeNull();
expect(mapHero({ slides: [slide({})] })).toBeNull();
expect(mapHero(answer([slide({})], { title: ' ' }))).toBeNull();
});
it('drops slides that cannot be used', () => {
const bad = [
null,
{ id: 's' },
slide({}, { id: '' }),
slide({ src: '' }),
slide({ src: 'https://evil.example/a.webp' }),
slide({ src: '//evil.example/a.webp' }),
slide({ src: '/a\\b.webp' }),
slide({ width: 0 }),
slide({ height: 1.5 }),
slide({}, { alt: ' ' }),
];
expect(mapHero(answer(bad))).toBeNull();
expect(mapHero(answer([...bad, slide({})]))?.slides).toHaveLength(1);
});
it('keeps a decorative slide with an empty alt', () => {
const hero = mapHero(
answer([slide({}, { decorative: true, alt: 'ignored' })]),
);
expect(hero?.slides[0].alt).toBe('');
expect(hero?.slides[0].decorative).toBe(true);
});
it('reads the display, the tagline and at most two safe buttons', () => {
const hero = mapHero(
answer([slide({})], {
display: 'single',
tagline: ' Label ',
buttons: [
null,
{ label: 'x', target: 'javascript:1' },
{ label: '', target: '/a' },
{ label: 'A', target: '#contact' },
{ label: 'B', target: '/b' },
{ label: 'C', target: 'https://a.example/c' },
],
}),
);
expect(hero?.display).toBe('single');
expect(hero?.tagline).toBe('Label');
expect(hero?.buttons.map((b) => b.label)).toEqual(['A', 'B']);
expect(mapHero(answer([slide({})]))?.display).toBe('slideshow');
expect(
mapHero(answer([slide({})], { buttons: 'nope' }))?.buttons,
).toEqual([]);
});
it('keeps only valid variants and a focus point inside the picture', () => {
const hero = mapHero(
answer([
slide({
focus: { x: 0.25, y: 1 },
variants: [
null,
{
ratio: 'wide',
width: 100,
type: 'image/webp',
url: '/a.webp',
},
{
ratio: 'wide',
width: 0,
type: 'image/webp',
url: '/b.webp',
},
{
ratio: 'wide',
width: 100,
type: 'image/webp',
url: 'https://x.example/c.webp',
},
],
}),
slide({ focus: { x: 2, y: 0 } }),
slide({ focus: 'middle', variants: 'none' }),
]),
);
expect(hero?.slides[0].image.variants).toHaveLength(1);
expect(hero?.slides[0].image.focus).toEqual({ x: 0.25, y: 1 });
expect(hero?.slides[1].image.focus).toBeNull();
expect(hero?.slides[2].image.focus).toBeNull();
expect(hero?.slides[2].image.variants).toEqual([]);
});
});
describe('heroHtml and heroPreloadHtml', () => {
it('write nothing for no hero', () => {
expect(heroHtml(null)).toBe('');
expect(heroPreloadHtml(null)).toBe('');
});
it('leave out what is not there', () => {
const hero = mapHero(answer([slide({})]));
const html = heroHtml(hero);
expect(html).not.toContain('<source');
expect(html).not.toContain('srcset');
expect(html).not.toContain('style=');
expect(html).not.toContain('cms-hero-buttons');
expect(html).not.toContain('cms-hero-tagline');
expect(heroPreloadHtml(hero)).toBe(
'<link rel="preload" as="image" href="/m/a.webp" fetchpriority="high">',
);
});
it('uses the same srcset, sizes and media in the picture and the preload', () => {
const hero = mapHero(
answer([
slide({
variants: [
{
ratio: 'wide',
width: 20,
type: 'image/webp',
url: '/w20.webp',
},
{
ratio: 'tall',
width: 8,
type: 'image/webp',
url: '/t8.webp',
},
],
}),
]),
);
const html = heroHtml(hero);
const preload = heroPreloadHtml(hero);
for (const part of [
'srcset="/t8.webp 8w"',
'srcset="/w20.webp 20w"',
'media="(orientation: portrait)"',
]) {
expect(html).toContain(part);
}
expect(preload).toContain('imagesrcset="/t8.webp 8w"');
expect(preload).toContain('imagesrcset="/w20.webp 20w"');
expect(preload).toContain('media="(orientation: portrait)"');
expect(preload).toContain('media="(orientation: landscape)"');
});
it('preloads the plain image for landscape when only a tall variant has a set', () => {
const hero = mapHero(
answer([
slide({
variants: [
{
ratio: 'tall',
width: 8,
type: 'image/webp',
url: '/t8.webp',
},
],
}),
]),
);
expect(heroPreloadHtml(hero)).toContain(
'href="/m/a.webp" media="(orientation: landscape)"',
);
});
it('keeps one preload without media when there is no tall variant', () => {
const hero = mapHero(
answer([
slide({
variants: [
{
ratio: 'wide',
width: 20,
type: 'image/webp',
url: '/w20.webp',
},
],
}),
]),
);
expect(heroPreloadHtml(hero)).toBe(
'<link rel="preload" as="image" imagesrcset="/w20.webp 20w" imagesizes="100vw" fetchpriority="high">',
);
});
it('writes the focus point as object-position', () => {
const hero = mapHero(answer([slide({ focus: { x: 0.333333, y: 0 } })]));
expect(heroHtml(hero)).toContain('style="object-position:33.33% 0%"');
});
});